{ "name": "forge-collab", "language": "rust", "version": "0.2.0", "description": "ANVIL Collaboration Contract: roles, sessions, task delegation, shared context, and interrupts for the Forge SDK", "manifest": "forge-rs/crates/forge-collab/Cargo.toml", "manifestSha256": "3b1528e6b976f326d66bd6e964a8de33da673983ba7813cbe9f9103900b18f40", "status": "source-reference", "registryPublicationVerified": false, "route": "/libraries/rust/forge-collab", "features": {}, "files": [ { "path": "forge-rs/crates/forge-collab/src/capability.rs", "sha256": "881a760efca13e792b460d367b6998094b14144f7a45416ee888b57b2653aba1", "artifactSha256": "19b28863af4b912fb7df74a699b1f9a1f2e6dead3b75bd40e5380acbf20de1e4", "url": "/reference/source/forge-rs/crates/forge-collab/src/capability.rs.txt", "declarations": [ { "name": "::CapabilityAdvertiser", "line": 58, "signature": "pub trait CapabilityAdvertiser: Send + Sync {\n /// Returns the agent's full capability profile.\n ///\n /// The profile includes the agent's supported roles, task types,\n /// available tools, current load, and maximum concurrency.\n ///\n /// # Returns\n ///\n /// An [`AgentCapabilityProfile`] describing the agent's capabilities.\n fn advertise_capabilities(&self) -> AgentCapabilityProfile;\n\n /// Returns `true` if this agent can handle the given task type.\n ///\n /// This is a convenience check that avoids constructing the full\n /// capability profile for simple task type matching.\n ///\n /// # Arguments\n ///\n /// * `task_type` - The task type to check (e.g., \"code-review\").\n ///\n /// # Returns\n ///\n /// `true` if the agent supports this task type.\n fn can_handle(&self, task_type: &str) -> bool;\n\n /// Returns the agent's current availability as a factor between 0.0\n /// (fully loaded) and 1.0 (completely idle).\n ///\n /// This is the inverse of `current_load` in the capability profile:\n /// `availability = 1.0 - current_load`.\n ///\n /// # Returns\n ///\n /// A value between 0.0 and 1.0 representing available capacity.\n fn current_availability(&self) -> f64;\n}", "documentation": "Capability advertiser contract.\n\nAgents implement this trait to advertise their capabilities to the\ncollaboration framework. The coordinator uses these advertisements\nto match tasks to suitable agents.\n\nSee ANVIL Spec section 11.6 -- Agent Capability Profile.\n\n# Examples\n\n```\nuse forge_collab::capability::CapabilityAdvertiser;\nuse forge_collab::types::{AgentCapabilityProfile, CollaborationRole};\n\nstruct MyAgent;\n\nimpl CapabilityAdvertiser for MyAgent {\n fn advertise_capabilities(&self) -> AgentCapabilityProfile {\n AgentCapabilityProfile {\n agent_did: \"did:oas:agent:my-agent\".to_string(),\n supported_roles: vec![CollaborationRole::Worker],\n supported_task_types: vec![\"summarize\".to_string(), \"translate\".to_string()],\n available_tools: vec![\"read_file\".to_string()],\n current_load: 0.2,\n max_concurrent_tasks: 5,\n }\n }\n\n fn can_handle(&self, task_type: &str) -> bool {\n matches!(task_type, \"summarize\" | \"translate\")\n }\n\n fn current_availability(&self) -> f64 {\n 0.8\n }\n}\n\nlet agent = MyAgent;\nlet profile = agent.advertise_capabilities();\nassert_eq!(profile.supported_task_types.len(), 2);\nassert!(agent.can_handle(\"summarize\"));\nassert!(!agent.can_handle(\"code-review\"));\n```" }, { "name": "::match_task_to_agents", "line": 163, "signature": "pub fn match_task_to_agents(\n task: &DelegatedTask,\n agents: &[AgentCapabilityProfile],\n) -> Vec;", "documentation": "Matches a task to available agents based on capability profiles.\n\nThe matching algorithm:\n1. Filters agents that support the task's `task_type`.\n2. Filters agents that have all required tools (from `constraints.allowed_tools`,\n if non-empty -- agents must have at least those tools available).\n3. Filters agents with availability > 0.0 (i.e., not fully loaded).\n4. Sorts by availability descending (most available first).\n\nReturns the DIDs of matching agents in order of suitability.\n\nSee ANVIL Spec section 11.6 -- Task-to-Agent Matching.\n\n# Arguments\n\n* `task` - The task to match.\n* `agents` - The available agent capability profiles.\n\n# Returns\n\nA `Vec` of agent DIDs sorted by suitability (most suitable first).\nReturns an empty `Vec` if no agents match.\n\n# Examples\n\n```\nuse forge_collab::capability::match_task_to_agents;\nuse forge_collab::types::{\n DelegatedTask, TaskConstraints, TaskPriority, AgentCapabilityProfile, CollaborationRole,\n};\n\nlet task = DelegatedTask {\n task_id: \"task-001\".to_string(),\n task_type: \"summarize\".to_string(),\n description: \"Summarize document\".to_string(),\n input: serde_json::json!({}),\n output_schema: None,\n constraints: TaskConstraints::default(),\n delegator: \"did:oas:agent:coord\".to_string(),\n priority: TaskPriority::Normal,\n deadline: None,\n context_keys: vec![],\n};\n\nlet agents = vec![\n AgentCapabilityProfile {\n agent_did: \"did:oas:agent:worker-1\".to_string(),\n supported_roles: vec![CollaborationRole::Worker],\n supported_task_types: vec![\"summarize\".to_string()],\n available_tools: vec![],\n current_load: 0.3,\n max_concurrent_tasks: 5,\n },\n AgentCapabilityProfile {\n agent_did: \"did:oas:agent:worker-2\".to_string(),\n supported_roles: vec![CollaborationRole::Worker],\n supported_task_types: vec![\"translate\".to_string()],\n available_tools: vec![],\n current_load: 0.1,\n max_concurrent_tasks: 5,\n },\n];\n\nlet matches = match_task_to_agents(&task, &agents);\nassert_eq!(matches.len(), 1);\nassert_eq!(matches[0], \"did:oas:agent:worker-1\");\n```" } ] }, { "path": "forge-rs/crates/forge-collab/src/context.rs", "sha256": "c415243c7aacfc161a79a3fa7e5460d3ed332dd0f29078f67464f4eb23f05229", "artifactSha256": "08f0c32606b1837ae44c2fc76be8fb8ae2c7654e1da92b7aa390b7dc74c41b07", "url": "/reference/source/forge-rs/crates/forge-collab/src/context.rs.txt", "declarations": [ { "name": "::SharedContextContract", "line": 62, "signature": "#[async_trait::async_trait]\npub trait SharedContextContract: Send + Sync {\n /// Reads a context entry by key from the specified session.\n ///\n /// # Arguments\n ///\n /// * `session_id` - The session whose context to read from.\n /// * `key` - The key of the entry to read.\n ///\n /// # Returns\n ///\n /// The [`ContextEntry`] for the given key.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError::ContextKeyNotFound`] if the key does not\n /// exist in the session's context.\n ///\n /// Returns [`CollabError::SessionNotFound`] if the session does not\n /// exist.\n // ANVIL Spec section 11.4 -- Shared Context: context_read\n async fn context_read(&self, session_id: &str, key: &str) -> Result;\n\n /// Writes a context entry to the specified session.\n ///\n /// If the key already exists, the entry is updated with the new value\n /// and its version is incremented.\n ///\n /// # Arguments\n ///\n /// * `session_id` - The session whose context to write to.\n /// * `entry` - The context entry to write.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError::SessionNotFound`] if the session does not\n /// exist.\n // ANVIL Spec section 11.4 -- Shared Context: context_write\n async fn context_write(&self, session_id: &str, entry: ContextEntry)\n -> Result<(), CollabError>;\n\n /// Lists all keys in the specified session's context.\n ///\n /// # Arguments\n ///\n /// * `session_id` - The session whose context keys to list.\n ///\n /// # Returns\n ///\n /// A `Vec` of key strings.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError::SessionNotFound`] if the session does not\n /// exist.\n // ANVIL Spec section 11.4 -- Shared Context: context_keys\n async fn context_keys(&self, session_id: &str) -> Result, CollabError>;\n}", "documentation": "Shared context contract for collaboration sessions.\n\nImplementations provide read/write access to a session-scoped key-value\nstore. Each entry carries versioning, authorship, and visibility metadata.\n\nSee ANVIL Spec section 11.4 -- Shared Context.\n\n# Examples\n\n```no_run\nuse forge_collab::context::SharedContextContract;\nuse forge_collab::types::ContextEntry;\nuse forge_collab::error::CollabError;\n\nstruct MyContext;\n\n#[async_trait::async_trait]\nimpl SharedContextContract for MyContext {\n async fn context_read(\n &self,\n _session_id: &str,\n _key: &str,\n ) -> Result {\n Err(CollabError::ContextKeyNotFound {\n key: \"not-found\".to_string(),\n })\n }\n\n async fn context_write(\n &self,\n _session_id: &str,\n _entry: ContextEntry,\n ) -> Result<(), CollabError> {\n Ok(())\n }\n\n async fn context_keys(\n &self,\n _session_id: &str,\n ) -> Result, CollabError> {\n Ok(vec![])\n }\n}\n```" }, { "name": "::InMemorySharedContext", "line": 153, "signature": "#[derive(Debug, Clone)]\npub struct InMemorySharedContext {\n\n}", "documentation": "In-memory implementation of the shared context store.\n\nStores context entries in a nested `HashMap` keyed by session ID and\nthen by entry key. Suitable for testing and single-process deployments.\n\n# Examples\n\n```\nuse forge_collab::context::InMemorySharedContext;\nuse forge_collab::types::{ContextEntry, ContextVisibility};\n\nlet mut ctx = InMemorySharedContext::new();\nctx.create_session(\"sess-001\");\n\nlet entry = ContextEntry {\n key: \"result\".to_string(),\n value: serde_json::json!(42),\n value_type: \"number\".to_string(),\n author: \"did:oas:agent:writer\".to_string(),\n version: 1,\n timestamp: \"2026-02-19T10:00:00Z\".to_string(),\n visibility: ContextVisibility::Session,\n};\n\nctx.write_entry(\"sess-001\", entry).unwrap();\n\nlet read = ctx.read_entry(\"sess-001\", \"result\").unwrap();\nassert_eq!(read.key, \"result\");\n\nlet keys = ctx.list_keys(\"sess-001\").unwrap();\nassert_eq!(keys, vec![\"result\"]);\n```" }, { "name": "::InMemorySharedContext::new", "line": 167, "signature": "pub fn new() -> Self;", "documentation": "Creates a new empty in-memory shared context store.\n\nNo sessions are pre-created. Use [`create_session`](Self::create_session)\nto register sessions before reading or writing context.\n\n# Returns\n\nA new `InMemorySharedContext` with no sessions." }, { "name": "::InMemorySharedContext::create_session", "line": 181, "signature": "pub fn create_session(&mut self, session_id: &str);", "documentation": "Registers a session in the context store.\n\nThis must be called before reading or writing context for a session.\nCalling it for an already-registered session is a no-op.\n\n# Arguments\n\n* `session_id` - The ID of the session to register." }, { "name": "::InMemorySharedContext::session_count", "line": 186, "signature": "pub fn session_count(&self) -> usize;", "documentation": "Returns the number of sessions in the context store." }, { "name": "::InMemorySharedContext::write_entry", "line": 269, "signature": "pub fn write_entry(\n &mut self,\n session_id: &str,\n entry: ContextEntry,\n ) -> Result<(), CollabError>;", "documentation": "Writes a context entry directly (requires `&mut self`).\n\nThis is the concrete mutation method. Use this when you have direct\nownership or a mutable reference to the context store.\n\n# Arguments\n\n* `session_id` - The session to write to.\n* `entry` - The context entry to write.\n\n# Errors\n\nReturns [`CollabError::SessionNotFound`] if the session does not exist." }, { "name": "::InMemorySharedContext::read_entry", "line": 296, "signature": "pub fn read_entry(&self, session_id: &str, key: &str) -> Result;", "documentation": "Reads a context entry directly (convenience for non-async contexts).\n\n# Arguments\n\n* `session_id` - The session to read from.\n* `key` - The key to read.\n\n# Errors\n\nReturns [`CollabError::SessionNotFound`] or [`CollabError::ContextKeyNotFound`]." }, { "name": "::InMemorySharedContext::list_keys", "line": 321, "signature": "pub fn list_keys(&self, session_id: &str) -> Result, CollabError>;", "documentation": "Lists all keys for a session directly (convenience for non-async contexts).\n\n# Arguments\n\n* `session_id` - The session to list keys for.\n\n# Errors\n\nReturns [`CollabError::SessionNotFound`] if the session does not exist." } ] }, { "path": "forge-rs/crates/forge-collab/src/delegation.rs", "sha256": "6002f36da9ca332487a312d0077c8348444d00aae86bd12937616226d8ff05b7", "artifactSha256": "ad07563f36f68bd073628dd771bb5b911f779ab5e971e7f8ee9f4012b5ab5435", "url": "/reference/source/forge-rs/crates/forge-collab/src/delegation.rs.txt", "declarations": [ { "name": "::create_delegated_task", "line": 57, "signature": "pub fn create_delegated_task(\n delegator_did: &str,\n task_type: &str,\n description: &str,\n input: serde_json::Value,\n priority: TaskPriority,\n constraints: TaskConstraints,\n) -> DelegatedTask;", "documentation": "Creates a delegated task with a unique ID and timestamp.\n\nThe task ID is generated as a UUID v4 prefixed with `\"task-\"`. The\ntask carries the delegator's DID, priority, constraints, and an empty\nset of context keys (which can be populated after creation).\n\nSee ANVIL Spec section 11.3 -- Delegated Task.\n\n# Arguments\n\n* `delegator_did` - The OAS DID of the agent delegating the task.\n* `task_type` - The type of task (e.g., \"code-review\", \"summarize\").\n* `description` - A human-readable description of the task.\n* `input` - The input data for the task.\n* `priority` - The task priority level.\n* `constraints` - Execution constraints for the task.\n\n# Returns\n\nA new [`DelegatedTask`] with a unique ID and current timestamp.\n\n# Examples\n\n```\nuse forge_collab::delegation::create_delegated_task;\nuse forge_collab::types::{TaskConstraints, TaskPriority};\n\nlet task = create_delegated_task(\n \"did:oas:agent:coordinator-1\",\n \"summarize\",\n \"Summarize the quarterly report\",\n serde_json::json!({\"document_id\": \"doc-123\"}),\n TaskPriority::Normal,\n TaskConstraints::default(),\n);\n\nassert!(task.task_id.starts_with(\"task-\"));\nassert_eq!(task.task_type, \"summarize\");\nassert_eq!(task.delegator, \"did:oas:agent:coordinator-1\");\nassert_eq!(task.priority, TaskPriority::Normal);\n```" }, { "name": "::validate_task_constraints", "line": 124, "signature": "pub fn validate_task_constraints(constraints: &TaskConstraints) -> Result<(), CollabError>;", "documentation": "Validates that a task's constraints are within acceptable bounds.\n\nChecks:\n- `max_steps`, if set, must be greater than 0.\n- `max_tokens`, if set, must be greater than 0.\n- `max_duration_seconds`, if set, must be greater than 0.\n- `required_confidence`, if set, must be between 0.0 and 1.0 inclusive.\n\nSee ANVIL Spec section 11.3 -- Task Constraints.\n\n# Arguments\n\n* `constraints` - The task constraints to validate.\n\n# Returns\n\n`Ok(())` if all constraints are valid.\n\n# Errors\n\nReturns [`CollabError::DelegationFailed`] with a descriptive reason\nif any constraint is invalid.\n\n# Examples\n\n```\nuse forge_collab::delegation::validate_task_constraints;\nuse forge_collab::types::TaskConstraints;\n\n// Default constraints are valid\nlet result = validate_task_constraints(&TaskConstraints::default());\nassert!(result.is_ok());\n\n// Zero max_steps is invalid\nlet bad = TaskConstraints {\n max_steps: Some(0),\n ..TaskConstraints::default()\n};\nlet result = validate_task_constraints(&bad);\nassert!(result.is_err());\n```" } ] }, { "path": "forge-rs/crates/forge-collab/src/error.rs", "sha256": "7f866e40eff44ce1155559a9308dcf036219e70d2f6359af9a38445d230c495b", "artifactSha256": "b82ed936a1a2b1f44de7bcf7d6b9c6033718cf7ea7f9e0b544384dade0e1a5fa", "url": "/reference/source/forge-rs/crates/forge-collab/src/error.rs.txt", "declarations": [ { "name": "::CollabError", "line": 29, "signature": "#[derive(Debug, Error)]\npub enum CollabError {\n /// The specified collaboration session does not exist.\n ///\n /// This is returned when an operation references a session ID that has\n /// not been created or has already been garbage-collected after reaching\n /// a terminal state.\n ///\n /// See ANVIL Spec section 11.2 -- Collaboration Session.\n #[error(\"collaboration session '{session_id}' not found (see ANVIL Spec section 11.2)\")]\n SessionNotFound {\n /// The session ID that was not found.\n session_id: String,\n },\n\n /// A session with the given ID is already in the Active state.\n ///\n /// Duplicate session activation is not permitted. Sessions must be\n /// dissolved before a new session with the same logical purpose is created.\n ///\n /// See ANVIL Spec section 11.2 -- Collaboration Session.\n #[error(\n \"collaboration session '{session_id}' is already active (see ANVIL Spec section 11.2)\"\n )]\n SessionAlreadyActive {\n /// The session ID that is already active.\n session_id: String,\n },\n\n /// The session exceeded its configured timeout duration.\n ///\n /// Sessions with a `timeout_seconds` value will automatically transition\n /// to the `TimedOut` terminal state when the deadline passes.\n ///\n /// See ANVIL Spec section 11.2 -- Collaboration Session.\n #[error(\"collaboration session '{session_id}' timed out (see ANVIL Spec section 11.2)\")]\n SessionTimedOut {\n /// The session ID that timed out.\n session_id: String,\n },\n\n /// An invalid session state transition was attempted.\n ///\n /// The collaboration session state machine defines exactly which transitions\n /// are valid from each state. This error is returned when a transition\n /// violates the state machine rules.\n ///\n /// See ANVIL Spec section 11.2 -- Session State Machine.\n #[error(\"invalid session transition from '{from}' to '{to}' (see ANVIL Spec section 11.2)\")]\n InvalidSessionTransition {\n /// The current session state.\n from: String,\n /// The target state that was attempted.\n to: String,\n },\n\n /// The agent is not a participant in the specified session.\n ///\n /// Only agents that have joined a session can perform operations within\n /// that session (read/write context, receive tasks, send interrupts).\n ///\n /// See ANVIL Spec section 11.2 -- Session Participation.\n #[error(\"agent '{agent_did}' is not a participant in session '{session_id}' (see ANVIL Spec section 11.2)\")]\n NotAParticipant {\n /// The agent DID that is not a participant.\n agent_did: String,\n /// The session ID the agent attempted to interact with.\n session_id: String,\n },\n\n /// The specified delegated task does not exist.\n ///\n /// This is returned when an operation references a task ID that has\n /// not been created or has been completed and removed.\n ///\n /// See ANVIL Spec section 11.3 -- Delegated Task.\n #[error(\"delegated task '{task_id}' not found (see ANVIL Spec section 11.3)\")]\n TaskNotFound {\n /// The task ID that was not found.\n task_id: String,\n },\n\n /// The task is already assigned to another agent.\n ///\n /// A delegated task can only be assigned to one worker at a time.\n /// The existing assignment must be cancelled before re-assignment.\n ///\n /// See ANVIL Spec section 11.3 -- Delegated Task.\n #[error(\"delegated task '{task_id}' is already assigned to '{assignee}' (see ANVIL Spec section 11.3)\")]\n TaskAlreadyAssigned {\n /// The task ID that is already assigned.\n task_id: String,\n /// The DID of the agent currently assigned to the task.\n assignee: String,\n },\n\n /// The agent's capabilities do not match the task requirements.\n ///\n /// Task assignment validates that the target agent supports the required\n /// task type, tools, and has sufficient capacity.\n ///\n /// See ANVIL Spec section 11.6 -- Agent Capability Profile.\n #[error(\"capability mismatch for task type '{task_type}' and agent '{agent_did}': {reason} (see ANVIL Spec section 11.6)\")]\n CapabilityMismatch {\n /// The task type that was not supported.\n task_type: String,\n /// The agent DID that lacks the capability.\n agent_did: String,\n /// A human-readable explanation of the mismatch.\n reason: String,\n },\n\n /// The specified key was not found in the shared context.\n ///\n /// Context reads return this when the key has not been written to\n /// the session's shared context store.\n ///\n /// See ANVIL Spec section 11.4 -- Shared Context.\n #[error(\"context key '{key}' not found (see ANVIL Spec section 11.4)\")]\n ContextKeyNotFound {\n /// The key that was not found.\n key: String,\n },\n\n /// The agent does not have permission to access the specified context key.\n ///\n /// Context entries can have visibility restrictions based on session scope,\n /// role, or specific agent DID.\n ///\n /// See ANVIL Spec section 11.4 -- Shared Context.\n #[error(\"agent '{agent_did}' does not have permission to access context key '{key}' (see ANVIL Spec section 11.4)\")]\n ContextPermissionDenied {\n /// The context key the agent attempted to access.\n key: String,\n /// The agent DID that was denied access.\n agent_did: String,\n },\n\n /// The interrupt was rejected by the target agent.\n ///\n /// Agents may reject interrupts if they are in a state that does not\n /// permit interruption (e.g., in a critical section) or if the interrupt\n /// type is not supported.\n ///\n /// See ANVIL Spec section 11.5 -- Interrupts.\n #[error(\"interrupt '{interrupt_id}' rejected: {reason} (see ANVIL Spec section 11.5)\")]\n InterruptRejected {\n /// The interrupt ID that was rejected.\n interrupt_id: String,\n /// A human-readable explanation of the rejection.\n reason: String,\n },\n\n /// A task delegation operation failed.\n ///\n /// This is a general delegation failure covering scenarios such as\n /// no eligible workers, constraint violations, or internal errors\n /// during the delegation flow.\n ///\n /// See ANVIL Spec section 11.3 -- Delegated Task.\n #[error(\"delegation failed: {reason} (see ANVIL Spec section 11.3)\")]\n DelegationFailed {\n /// A human-readable explanation of the failure.\n reason: String,\n },\n\n /// The agent attempted an action that violates its assigned role.\n ///\n /// For example, a Worker attempting to decompose tasks (a Coordinator\n /// action) or a Peer attempting to assign tasks.\n ///\n /// See ANVIL Spec section 11.1 -- Collaboration Roles.\n #[error(\"role violation: agent '{agent_did}' with role '{role}' cannot perform action '{action}' (see ANVIL Spec section 11.1)\")]\n RoleViolation {\n /// The agent DID that violated its role.\n agent_did: String,\n /// The role the agent holds.\n role: String,\n /// The action the agent attempted.\n action: String,\n },\n}", "documentation": "Error type for collaboration sessions, delegation, context, and interrupts.\n\nEvery variant includes actionable context: what failed, why, and what the\ndeveloper should check. No generic \"something went wrong\" messages.\n\n# Examples\n\n```\nuse forge_collab::error::CollabError;\n\nlet err = CollabError::SessionNotFound {\n session_id: \"sess-001\".to_string(),\n};\nassert!(err.to_string().contains(\"sess-001\"));\n```" }, { "name": "::CollabResult", "line": 212, "signature": "pub type CollabResult = Result;", "documentation": "A specialized `Result` type for `forge-collab` operations." } ] }, { "path": "forge-rs/crates/forge-collab/src/interrupt.rs", "sha256": "8782604eec0d935ab46089000c61664c2c01959fb99703d964a73cc3fb0f767a", "artifactSha256": "4f5b63fa98767e8cb409dfc7d6cf387c57b023b635614709ad1a550b1e17893a", "url": "/reference/source/forge-rs/crates/forge-collab/src/interrupt.rs.txt", "declarations": [ { "name": "::InterruptHandler", "line": 59, "signature": "#[async_trait::async_trait]\npub trait InterruptHandler: Send + Sync {\n /// Handles an incoming interrupt.\n ///\n /// The handler inspects the interrupt type and priority, then decides\n /// whether to acknowledge it. The response includes the agent's current\n /// state if applicable (e.g., for suspendable tasks).\n ///\n /// # Arguments\n ///\n /// * `interrupt` - The interrupt to handle.\n ///\n /// # Returns\n ///\n /// An [`InterruptResponse`] indicating acknowledgment and optional state.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError::InterruptRejected`] if the interrupt cannot\n /// be handled (e.g., the agent is in a critical section).\n // ANVIL Spec section 11.5 -- Interrupt Handler: on_interrupt\n async fn on_interrupt(&self, interrupt: &Interrupt) -> Result;\n\n /// Called when the agent must be preempted by a higher-priority task.\n ///\n /// The agent should save its current state and prepare for the current\n /// task to be suspended or aborted.\n ///\n /// # Arguments\n ///\n /// * `interrupt` - The preemption interrupt.\n ///\n /// # Returns\n ///\n /// An [`InterruptedState`] snapshot of the agent's state at the moment\n /// of preemption.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError::InterruptRejected`] if preemption is not\n /// possible.\n // ANVIL Spec section 11.5 -- Interrupt Handler: on_preempt\n async fn on_preempt(&self, interrupt: &Interrupt) -> Result;\n}", "documentation": "Interrupt handler contract.\n\nAgents implement this trait to handle incoming interrupts. The handler\ndecides whether to acknowledge the interrupt and optionally reports\nits interrupted state for potential resumption.\n\nSee ANVIL Spec section 11.5 -- Interrupts.\n\n# Examples\n\n```no_run\nuse forge_collab::interrupt::InterruptHandler;\nuse forge_collab::types::{Interrupt, InterruptResponse, InterruptedState};\nuse forge_collab::error::CollabError;\n\nstruct MyInterruptHandler;\n\n#[async_trait::async_trait]\nimpl InterruptHandler for MyInterruptHandler {\n async fn on_interrupt(\n &self,\n interrupt: &Interrupt,\n ) -> Result {\n Ok(InterruptResponse {\n interrupt_id: interrupt.interrupt_id.clone(),\n acknowledged: true,\n current_state: None,\n })\n }\n\n async fn on_preempt(\n &self,\n _interrupt: &Interrupt,\n ) -> Result {\n Ok(InterruptedState {\n task_id: None,\n step_count: 0,\n progress_percentage: 0.0,\n can_resume: false,\n })\n }\n}\n```" }, { "name": "::create_interrupt", "line": 139, "signature": "pub fn create_interrupt(\n interrupt_type: InterruptType,\n source_did: &str,\n priority: TaskPriority,\n payload: serde_json::Value,\n) -> Interrupt;", "documentation": "Creates an interrupt with a unique ID and current timestamp.\n\nThe interrupt ID is generated as a UUID v4 prefixed with `\"int-\"`.\n\nSee ANVIL Spec section 11.5 -- Interrupts.\n\n# Arguments\n\n* `interrupt_type` - The type of interrupt.\n* `source_did` - The OAS DID of the agent sending the interrupt.\n* `priority` - The priority of the interrupt.\n* `payload` - Arbitrary payload data for the interrupt.\n\n# Returns\n\nA new [`Interrupt`] with a unique ID and current timestamp.\n\n# Examples\n\n```\nuse forge_collab::interrupt::create_interrupt;\nuse forge_collab::types::{InterruptType, TaskPriority};\n\nlet interrupt = create_interrupt(\n InterruptType::Suspend,\n \"did:oas:agent:coordinator-1\",\n TaskPriority::High,\n serde_json::json!({\"reason\": \"higher priority work\"}),\n);\n\nassert!(interrupt.interrupt_id.starts_with(\"int-\"));\nassert_eq!(interrupt.interrupt_type, InterruptType::Suspend);\nassert_eq!(interrupt.source, \"did:oas:agent:coordinator-1\");\nassert_eq!(interrupt.priority, TaskPriority::High);\n```" } ] }, { "path": "forge-rs/crates/forge-collab/src/lib.rs", "sha256": "c765309b840a52635cf93c81ea15270eb96a82aba0f77ed94076fd4925090ee9", "artifactSha256": "dda93fb227a021af4b3c2d1f056d8cce9c85f29ff3f06232efacf4e8c50c5dd3", "url": "/reference/source/forge-rs/crates/forge-collab/src/lib.rs.txt", "declarations": [ { "name": "capability", "line": 84, "signature": "pub mod capability;", "documentation": "# forge-collab\n\nANVIL Collaboration Contract: roles, sessions, task delegation, shared\ncontext, and interrupts for the Forge SDK.\n\nThis crate provides the multi-agent collaboration infrastructure for\nANVIL-compliant agents. It implements the Collaboration Contract defined\nin ANVIL Spec section 11, enabling agents to coordinate work through\nstructured sessions, delegated tasks, shared context, and interrupts.\n\n# Components\n\n- **Roles** -- Three collaboration roles (Coordinator, Worker, Peer) with\n trait contracts defining each role's operations (ANVIL Spec section 11.1).\n- **Sessions** -- Collaboration session lifecycle with a 6-state immutable\n state machine (Proposed, Active, Completing, Completed, TimedOut,\n Dissolved) per ANVIL Spec section 11.2.\n- **Delegation** -- Task creation, constraint validation, and assignment\n helpers per ANVIL Spec section 11.3.\n- **Shared Context** -- Session-scoped key-value store with visibility\n controls and versioning per ANVIL Spec section 11.4.\n- **Interrupts** -- Preemption, suspension, resumption, and abort\n mechanisms per ANVIL Spec section 11.5.\n- **Capability** -- Agent capability advertisement and task-to-agent\n matching per ANVIL Spec section 11.6.\n\n# ANVIL Spec References\n\n- ANVIL Spec section 11 -- Collaboration Contract\n- ANVIL Spec section 11.1 -- Collaboration Roles\n- ANVIL Spec section 11.2 -- Collaboration Session\n- ANVIL Spec section 11.3 -- Delegated Task\n- ANVIL Spec section 11.4 -- Shared Context\n- ANVIL Spec section 11.5 -- Interrupts\n- ANVIL Spec section 11.6 -- Agent Capability Profile\n\n# Architecture\n\n`forge-collab` depends on `forge-core` for shared types and `forge-comm`\nfor message transport. It does NOT depend on `forge-agent` -- the\ncollaboration contract is a peer-level concern, not an agent-level concern.\nAgents integrate collaboration by implementing the role traits and session\ncontract.\n\n# Examples\n\n```\nuse forge_collab::session::SessionManager;\nuse forge_collab::types::{SessionState, TaskConstraints, TaskPriority};\nuse forge_collab::delegation::{create_delegated_task, validate_task_constraints};\n\n// Create and advance a session\nlet mut session = SessionManager::new();\nassert_eq!(session.state(), SessionState::Proposed);\n\nsession.transition(SessionState::Active).unwrap();\nassert_eq!(session.state(), SessionState::Active);\n\n// Create a delegated task\nlet task = create_delegated_task(\n \"did:oas:agent:coordinator-1\",\n \"code-review\",\n \"Review the authentication module\",\n serde_json::json!({\"file\": \"auth.rs\"}),\n TaskPriority::High,\n TaskConstraints {\n max_steps: Some(20),\n max_tokens: Some(5000),\n ..TaskConstraints::default()\n },\n);\n\n// Validate constraints\nvalidate_task_constraints(&task.constraints).unwrap();\n\n// Complete the session\nsession.transition(SessionState::Completing).unwrap();\nsession.transition(SessionState::Completed).unwrap();\nassert!(session.state().is_terminal());\n```" }, { "name": "context", "line": 85, "signature": "pub mod context;", "documentation": "" }, { "name": "delegation", "line": 86, "signature": "pub mod delegation;", "documentation": "" }, { "name": "error", "line": 87, "signature": "pub mod error;", "documentation": "" }, { "name": "interrupt", "line": 88, "signature": "pub mod interrupt;", "documentation": "" }, { "name": "roles", "line": 89, "signature": "pub mod roles;", "documentation": "" }, { "name": "session", "line": 90, "signature": "pub mod session;", "documentation": "" }, { "name": "types", "line": 91, "signature": "pub mod types;", "documentation": "" }, { "name": "prelude", "line": 94, "signature": "pub mod prelude;", "documentation": "Re-exports of the most commonly used types." }, { "name": "pub use crate::capability::{match_task_to_agents, CapabilityAdvertiser};", "line": 95, "signature": "pub use crate::capability::{match_task_to_agents, CapabilityAdvertiser};", "documentation": "" }, { "name": "pub use crate::context::{InMemorySharedContext, SharedContextContract};", "line": 96, "signature": "pub use crate::context::{InMemorySharedContext, SharedContextContract};", "documentation": "" }, { "name": "pub use crate::delegation::{create_delegated_task, validate_task_constraints};", "line": 97, "signature": "pub use crate::delegation::{create_delegated_task, validate_task_constraints};", "documentation": "" }, { "name": "pub use crate::error::{CollabError, CollabResult};", "line": 98, "signature": "pub use crate::error::{CollabError, CollabResult};", "documentation": "" }, { "name": "pub use crate::interrupt::{create_interrupt, InterruptHandler};", "line": 99, "signature": "pub use crate::interrupt::{create_interrupt, InterruptHandler};", "documentation": "" }, { "name": "pub use crate::roles::{CoordinatorContract, PeerContract, WorkerContract};", "line": 100, "signature": "pub use crate::roles::{CoordinatorContract, PeerContract, WorkerContract};", "documentation": "" }, { "name": "pub use crate::session::{SessionContract, SessionManager};", "line": 101, "signature": "pub use crate::session::{SessionContract, SessionManager};", "documentation": "" }, { "name": "pub use crate::types::{\n AgentCapabilityProfile, CollaborationRole, CollaborationSession, ContextEntry,\n ContextVisibility, DelegatedTask, Interrupt, InterruptResponse, InterruptType,\n InterruptedState, SessionParticipant, SessionState, SessionTransition, TaskAcknowledgment,\n TaskConstraints, TaskPriority, TaskProgress, TaskResult, TaskStatus,\n };", "line": 102, "signature": "pub use crate::types::{\n AgentCapabilityProfile, CollaborationRole, CollaborationSession, ContextEntry,\n ContextVisibility, DelegatedTask, Interrupt, InterruptResponse, InterruptType,\n InterruptedState, SessionParticipant, SessionState, SessionTransition, TaskAcknowledgment,\n TaskConstraints, TaskPriority, TaskProgress, TaskResult, TaskStatus,\n };", "documentation": "" } ] }, { "path": "forge-rs/crates/forge-collab/src/roles.rs", "sha256": "c85da017b2e37e98b9d006156484e17462fc6c06c127092dbdedb4ea1446a232", "artifactSha256": "6e20fc224a7d98ba0c11f039408d3ce77b33ea0db8ab75a98c697d9aeddc1370", "url": "/reference/source/forge-rs/crates/forge-collab/src/roles.rs.txt", "declarations": [ { "name": "::CoordinatorContract", "line": 69, "signature": "#[async_trait::async_trait]\npub trait CoordinatorContract: Send + Sync {\n /// Decomposes a high-level task into smaller sub-tasks.\n ///\n /// The coordinator analyzes the input task and produces a list of\n /// sub-tasks that can be individually assigned to workers. The sub-tasks\n /// should collectively cover the scope of the original task.\n ///\n /// # Arguments\n ///\n /// * `task` - The task to decompose.\n ///\n /// # Returns\n ///\n /// A `Vec` of sub-tasks derived from the original task.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError::DelegationFailed`] if the task cannot be\n /// decomposed (e.g., it is already atomic or invalid).\n // ANVIL Spec section 11.1 -- Coordinator: decompose_task\n async fn decompose_task(&self, task: &DelegatedTask)\n -> Result, CollabError>;\n\n /// Assigns a task to a specific worker agent.\n ///\n /// The coordinator sends the task to the identified worker and receives\n /// an acknowledgment indicating acceptance or rejection.\n ///\n /// # Arguments\n ///\n /// * `task` - The task to assign.\n /// * `worker_did` - The OAS DID of the target worker.\n ///\n /// # Returns\n ///\n /// A [`TaskAcknowledgment`] from the worker.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError::CapabilityMismatch`] if the worker cannot\n /// handle the task type, or [`CollabError::DelegationFailed`] if the\n /// assignment fails for other reasons.\n // ANVIL Spec section 11.1 -- Coordinator: assign_task\n async fn assign_task(\n &self,\n task: &DelegatedTask,\n worker_did: &str,\n ) -> Result;\n\n /// Aggregates results from multiple worker tasks into a single result.\n ///\n /// After all sub-tasks have completed, the coordinator merges their\n /// results into a unified response for the original task.\n ///\n /// # Arguments\n ///\n /// * `results` - The results from all completed sub-tasks.\n ///\n /// # Returns\n ///\n /// A single aggregated [`TaskResult`].\n ///\n /// # Errors\n ///\n /// Returns [`CollabError::DelegationFailed`] if the results cannot be\n /// meaningfully aggregated (e.g., no results, conflicting outputs).\n // ANVIL Spec section 11.1 -- Coordinator: aggregate_results\n async fn aggregate_results(&self, results: &[TaskResult]) -> Result;\n\n /// Handles a failure reported by a worker.\n ///\n /// When a worker fails to complete a task, the coordinator decides how\n /// to recover: reassign the task, mark it as failed, or abort the\n /// session.\n ///\n /// # Arguments\n ///\n /// * `task_id` - The ID of the failed task.\n /// * `worker_did` - The DID of the worker that failed.\n /// * `error` - A description of the failure.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError::DelegationFailed`] if recovery is not possible.\n // ANVIL Spec section 11.1 -- Coordinator: handle_worker_failure\n async fn handle_worker_failure(\n &self,\n task_id: &str,\n worker_did: &str,\n error: &str,\n ) -> Result<(), CollabError>;\n}", "documentation": "Coordinator role contract -- decomposes and assigns tasks, aggregates results.\n\nThe coordinator is responsible for breaking down high-level objectives into\nindividual tasks, assigning them to suitable workers, collecting results,\nand handling worker failures. There is at most one coordinator per\ncollaboration session.\n\nSee ANVIL Spec section 11.1 -- Coordinator Role.\n\n# Examples\n\n```no_run\nuse forge_collab::roles::CoordinatorContract;\nuse forge_collab::types::{DelegatedTask, TaskResult, TaskAcknowledgment};\nuse forge_collab::error::CollabError;\n\nstruct MyCoordinator;\n\n#[async_trait::async_trait]\nimpl CoordinatorContract for MyCoordinator {\n async fn decompose_task(&self, task: &DelegatedTask) -> Result, CollabError> {\n // Split the task into sub-tasks\n Ok(vec![task.clone()])\n }\n\n async fn assign_task(&self, _task: &DelegatedTask, _worker_did: &str) -> Result {\n Ok(TaskAcknowledgment {\n task_id: \"task-001\".to_string(),\n accepted: true,\n rejection_reason: None,\n estimated_completion_seconds: Some(60),\n })\n }\n\n async fn aggregate_results(&self, results: &[TaskResult]) -> Result {\n if results.is_empty() {\n return Err(CollabError::DelegationFailed {\n reason: \"no results to aggregate\".to_string(),\n });\n }\n Ok(results[0].clone())\n }\n\n async fn handle_worker_failure(&self, _task_id: &str, _worker_did: &str, _error: &str) -> Result<(), CollabError> {\n Ok(())\n }\n}\n```" }, { "name": "::WorkerContract", "line": 204, "signature": "#[async_trait::async_trait]\npub trait WorkerContract: Send + Sync {\n /// Called when a task is delegated to this worker.\n ///\n /// The worker inspects the task and decides whether to accept or reject\n /// it based on its capabilities and current load.\n ///\n /// # Arguments\n ///\n /// * `task` - The delegated task to evaluate.\n ///\n /// # Returns\n ///\n /// A [`TaskAcknowledgment`] indicating acceptance or rejection.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError`] if the acknowledgment cannot be produced.\n // ANVIL Spec section 11.1 -- Worker: on_task_delegated\n async fn on_task_delegated(\n &self,\n task: &DelegatedTask,\n ) -> Result;\n\n /// Reports progress on an in-flight task.\n ///\n /// Workers should report progress periodically so the coordinator can\n /// monitor execution and detect stalls.\n ///\n /// # Arguments\n ///\n /// * `progress` - The progress report.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError::TaskNotFound`] if the task ID in the progress\n /// report does not match an active task.\n // ANVIL Spec section 11.1 -- Worker: report_progress\n async fn report_progress(&self, progress: &TaskProgress) -> Result<(), CollabError>;\n\n /// Submits the result of a completed task.\n ///\n /// Called when the worker has finished executing the task. The result\n /// includes the output data, status, and optional confidence score.\n ///\n /// # Arguments\n ///\n /// * `result` - The task result to submit.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError::TaskNotFound`] if the task ID in the result\n /// does not match an active task.\n // ANVIL Spec section 11.1 -- Worker: submit_result\n async fn submit_result(&self, result: &TaskResult) -> Result<(), CollabError>;\n\n /// Called when a task is cancelled by the coordinator.\n ///\n /// The worker should clean up any in-progress work for the specified\n /// task and release resources.\n ///\n /// # Arguments\n ///\n /// * `task_id` - The ID of the cancelled task.\n /// * `reason` - A human-readable cancellation reason.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError::TaskNotFound`] if the task is not known.\n // ANVIL Spec section 11.1 -- Worker: on_task_cancelled\n async fn on_task_cancelled(&self, task_id: &str, reason: &str) -> Result<(), CollabError>;\n}", "documentation": "Worker role contract -- executes delegated tasks, reports progress.\n\nWorkers receive tasks from coordinators, execute them within the given\nconstraints, report progress periodically, and submit results upon\ncompletion. Workers can also handle task cancellation gracefully.\n\nSee ANVIL Spec section 11.1 -- Worker Role.\n\n# Examples\n\n```no_run\nuse forge_collab::roles::WorkerContract;\nuse forge_collab::types::{DelegatedTask, TaskAcknowledgment, TaskProgress, TaskResult};\nuse forge_collab::error::CollabError;\n\nstruct MyWorker;\n\n#[async_trait::async_trait]\nimpl WorkerContract for MyWorker {\n async fn on_task_delegated(&self, task: &DelegatedTask) -> Result {\n Ok(TaskAcknowledgment {\n task_id: task.task_id.clone(),\n accepted: true,\n rejection_reason: None,\n estimated_completion_seconds: Some(30),\n })\n }\n\n async fn report_progress(&self, _progress: &TaskProgress) -> Result<(), CollabError> {\n Ok(())\n }\n\n async fn submit_result(&self, _result: &TaskResult) -> Result<(), CollabError> {\n Ok(())\n }\n\n async fn on_task_cancelled(&self, _task_id: &str, _reason: &str) -> Result<(), CollabError> {\n Ok(())\n }\n}\n```" }, { "name": "::PeerContract", "line": 308, "signature": "#[async_trait::async_trait]\npub trait PeerContract: Send + Sync {\n /// Submits a proposal for peer consensus.\n ///\n /// # Arguments\n ///\n /// * `proposal` - The proposal data to submit for voting.\n ///\n /// # Returns\n ///\n /// A unique proposal ID string.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError::DelegationFailed`] if the proposal cannot be\n /// submitted (e.g., session is not in an active state).\n // ANVIL Spec section 11.1 -- Peer: propose\n async fn propose(&self, proposal: &serde_json::Value) -> Result;\n\n /// Votes on an existing proposal.\n ///\n /// # Arguments\n ///\n /// * `proposal_id` - The ID of the proposal to vote on.\n /// * `approve` - `true` to approve, `false` to reject.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError::DelegationFailed`] if the proposal is not\n /// found or voting has closed.\n // ANVIL Spec section 11.1 -- Peer: vote\n async fn vote(&self, proposal_id: &str, approve: bool) -> Result<(), CollabError>;\n\n /// Called when consensus is reached on a proposal.\n ///\n /// # Arguments\n ///\n /// * `proposal_id` - The ID of the proposal that reached consensus.\n /// * `result` - The consensus result data.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError`] if the agent cannot act on the consensus.\n // ANVIL Spec section 11.1 -- Peer: on_consensus\n async fn on_consensus(\n &self,\n proposal_id: &str,\n result: &serde_json::Value,\n ) -> Result<(), CollabError>;\n}", "documentation": "Peer role contract -- participates in consensus-based collaboration.\n\nIn peer-mode collaboration, all agents have equal standing. Peers propose\nactions, vote on proposals, and act on consensus decisions. There is no\ncoordinator; decisions are made collectively.\n\nSee ANVIL Spec section 11.1 -- Peer Role.\n\n# Examples\n\n```no_run\nuse forge_collab::roles::PeerContract;\nuse forge_collab::error::CollabError;\n\nstruct MyPeer;\n\n#[async_trait::async_trait]\nimpl PeerContract for MyPeer {\n async fn propose(&self, proposal: &serde_json::Value) -> Result {\n Ok(\"proposal-001\".to_string())\n }\n\n async fn vote(&self, _proposal_id: &str, _approve: bool) -> Result<(), CollabError> {\n Ok(())\n }\n\n async fn on_consensus(&self, _proposal_id: &str, _result: &serde_json::Value) -> Result<(), CollabError> {\n Ok(())\n }\n}\n```" } ] }, { "path": "forge-rs/crates/forge-collab/src/session.rs", "sha256": "f65e767a07d3a1a4a3e28c21daefefbdc4ca89b162c4419627de1cf550a13253", "artifactSha256": "51e5ec01f98145d2415f258416006405263295ce7ba46d1a3c7829b01988c78c", "url": "/reference/source/forge-rs/crates/forge-collab/src/session.rs.txt", "declarations": [ { "name": "::SessionContract", "line": 85, "signature": "#[async_trait::async_trait]\npub trait SessionContract: Send + Sync {\n /// Called when the agent joins a collaboration session.\n ///\n /// # Arguments\n ///\n /// * `session` - The session being joined.\n /// * `role` - The role assigned to this agent in the session.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError`] if the agent cannot join the session.\n // ANVIL Spec section 11.2 -- Session Lifecycle: on_session_join\n async fn on_session_join(\n &self,\n session: &CollaborationSession,\n role: CollaborationRole,\n ) -> Result<(), CollabError>;\n\n /// Called when the session transitions between states.\n ///\n /// # Arguments\n ///\n /// * `session_id` - The ID of the session.\n /// * `from` - The previous state.\n /// * `to` - The new state.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError`] if the agent cannot handle the transition.\n // ANVIL Spec section 11.2 -- Session Lifecycle: on_session_transition\n async fn on_session_transition(\n &self,\n session_id: &str,\n from: SessionState,\n to: SessionState,\n ) -> Result<(), CollabError>;\n\n /// Called when the agent leaves a collaboration session.\n ///\n /// # Arguments\n ///\n /// * `session_id` - The ID of the session being left.\n /// * `reason` - A human-readable reason for leaving.\n ///\n /// # Errors\n ///\n /// Returns [`CollabError`] if cleanup fails.\n // ANVIL Spec section 11.2 -- Session Lifecycle: on_session_leave\n async fn on_session_leave(&self, session_id: &str, reason: &str) -> Result<(), CollabError>;\n}", "documentation": "Session lifecycle contract.\n\nAgents implement this trait to receive notifications about session\nlifecycle events: joining, state transitions, and leaving.\n\nSee ANVIL Spec section 11.2 -- Session Lifecycle.\n\n# Examples\n\n```no_run\nuse forge_collab::session::SessionContract;\nuse forge_collab::types::{CollaborationRole, CollaborationSession, SessionState};\nuse forge_collab::error::CollabError;\n\nstruct MySessionHandler;\n\n#[async_trait::async_trait]\nimpl SessionContract for MySessionHandler {\n async fn on_session_join(\n &self,\n _session: &CollaborationSession,\n _role: CollaborationRole,\n ) -> Result<(), CollabError> {\n Ok(())\n }\n\n async fn on_session_transition(\n &self,\n _session_id: &str,\n _from: SessionState,\n _to: SessionState,\n ) -> Result<(), CollabError> {\n Ok(())\n }\n\n async fn on_session_leave(\n &self,\n _session_id: &str,\n _reason: &str,\n ) -> Result<(), CollabError> {\n Ok(())\n }\n}\n```" }, { "name": "::SessionManager", "line": 179, "signature": "#[derive(Debug, Clone)]\npub struct SessionManager {\n\n}", "documentation": "Manages the session state machine per ANVIL Spec section 11.2.\n\nThe `SessionManager` enforces the immutable transition table for\ncollaboration sessions. It tracks the current state, validates all\ntransitions, and maintains a complete transition history.\n\nSessions start in the `Proposed` state and progress through `Active`\nand `Completing` to terminal states (`Completed`, `TimedOut`, `Dissolved`).\n\n# Thread Safety\n\n`SessionManager` is not `Sync`. For concurrent access, wrap it in a\n`Mutex` or `RwLock`.\n\n# Examples\n\n```\nuse forge_collab::session::SessionManager;\nuse forge_collab::types::SessionState;\n\nlet mut mgr = SessionManager::new();\nassert_eq!(mgr.state(), SessionState::Proposed);\n\n// Happy path: Proposed -> Active -> Completing -> Completed\nmgr.transition(SessionState::Active).unwrap();\nmgr.transition(SessionState::Completing).unwrap();\nmgr.transition(SessionState::Completed).unwrap();\nassert!(mgr.state().is_terminal());\nassert_eq!(mgr.history().len(), 3);\n```\n\nDissolution at any non-terminal state:\n\n```\nuse forge_collab::session::SessionManager;\nuse forge_collab::types::SessionState;\n\nlet mut mgr = SessionManager::new();\nmgr.transition(SessionState::Active).unwrap();\nmgr.transition(SessionState::Dissolved).unwrap();\nassert!(mgr.state().is_terminal());\n```" }, { "name": "::SessionManager::new", "line": 206, "signature": "pub fn new() -> Self;", "documentation": "Creates a new `SessionManager` in the `Proposed` state.\n\nEvery session starts in the `Proposed` state per ANVIL Spec\nsection 11.2.\n\n# Returns\n\nA new `SessionManager` with an empty transition history.\n\n# Examples\n\n```\nuse forge_collab::session::SessionManager;\nuse forge_collab::types::SessionState;\n\nlet mgr = SessionManager::new();\nassert_eq!(mgr.state(), SessionState::Proposed);\nassert!(mgr.history().is_empty());\n```" }, { "name": "::SessionManager::state", "line": 228, "signature": "pub fn state(&self) -> SessionState;", "documentation": "Returns the current session state.\n\n# Returns\n\nThe current [`SessionState`].\n\n# Examples\n\n```\nuse forge_collab::session::SessionManager;\nuse forge_collab::types::SessionState;\n\nlet mgr = SessionManager::new();\nassert_eq!(mgr.state(), SessionState::Proposed);\n```" }, { "name": "::SessionManager::transition", "line": 272, "signature": "pub fn transition(&mut self, target: SessionState) -> Result;", "documentation": "Attempts to transition to the given target state.\n\nValidates the transition against the ANVIL Spec section 11.2\ntransition table. If valid, the state is updated, a\n[`SessionTransition`] is recorded in the history, and a copy is\nreturned. If invalid, an error is returned and the state is unchanged.\n\n# Arguments\n\n* `target` - The desired target [`SessionState`].\n\n# Returns\n\nA [`SessionTransition`] record on success.\n\n# Errors\n\nReturns [`CollabError::InvalidSessionTransition`] if the transition\nfrom the current state to `target` is not in the ANVIL transition\ntable, or if `target` equals the current state (self-transitions\nare not permitted).\n\n# Examples\n\n```\nuse forge_collab::session::SessionManager;\nuse forge_collab::types::SessionState;\n\nlet mut mgr = SessionManager::new();\n\n// Valid transition\nlet t = mgr.transition(SessionState::Active).unwrap();\nassert_eq!(t.from, SessionState::Proposed);\nassert_eq!(t.to, SessionState::Active);\n\n// Invalid transition returns error\nlet err = mgr.transition(SessionState::Proposed);\nassert!(err.is_err());\n```" }, { "name": "::SessionManager::can_transition_to", "line": 322, "signature": "pub fn can_transition_to(&self, target: SessionState) -> bool;", "documentation": "Returns `true` if the transition from the current state to `target`\nis valid.\n\n# Arguments\n\n* `target` - The candidate target [`SessionState`].\n\n# Returns\n\n`true` if the transition is permitted by the ANVIL transition table.\n\n# Examples\n\n```\nuse forge_collab::session::SessionManager;\nuse forge_collab::types::SessionState;\n\nlet mgr = SessionManager::new();\nassert!(mgr.can_transition_to(SessionState::Active));\nassert!(mgr.can_transition_to(SessionState::Dissolved));\nassert!(!mgr.can_transition_to(SessionState::Completing));\n```" }, { "name": "::SessionManager::valid_transitions", "line": 344, "signature": "pub fn valid_transitions(&self) -> Vec;", "documentation": "Returns the set of valid target states from the current state.\n\n# Returns\n\nA `Vec` of valid target states. Empty if the current state is\nterminal.\n\n# Examples\n\n```\nuse forge_collab::session::SessionManager;\nuse forge_collab::types::SessionState;\n\nlet mgr = SessionManager::new();\nlet valid = mgr.valid_transitions();\nassert!(valid.contains(&SessionState::Active));\nassert!(valid.contains(&SessionState::Dissolved));\n```" }, { "name": "::SessionManager::history", "line": 370, "signature": "pub fn history(&self) -> &[SessionTransition];", "documentation": "Returns the complete transition history.\n\nThe history is ordered chronologically -- the first entry is the\nfirst transition that occurred.\n\n# Returns\n\nA slice of all [`SessionTransition`] records.\n\n# Examples\n\n```\nuse forge_collab::session::SessionManager;\nuse forge_collab::types::SessionState;\n\nlet mut mgr = SessionManager::new();\nassert!(mgr.history().is_empty());\n\nmgr.transition(SessionState::Active).unwrap();\nassert_eq!(mgr.history().len(), 1);\nassert_eq!(mgr.history()[0].from, SessionState::Proposed);\n```" } ] }, { "path": "forge-rs/crates/forge-collab/src/types.rs", "sha256": "66f63a869b8090ec18d64be190e816ea5c1161b7914e5eceb94dc148cfdb33ab", "artifactSha256": "cd92bcb3e74ed179cf73ef542aabc258378be723432e407b4520a7ad7f10a504", "url": "/reference/source/forge-rs/crates/forge-collab/src/types.rs.txt", "declarations": [ { "name": "::CollaborationRole", "line": 45, "signature": "#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum CollaborationRole {\n /// Coordinator: decomposes tasks, assigns them to workers, and aggregates\n /// results. There is at most one coordinator per session.\n Coordinator,\n /// Worker: executes delegated tasks, reports progress, and submits results\n /// back to the coordinator.\n Worker,\n /// Peer: participates in consensus-based collaboration where all agents\n /// have equal standing.\n Peer,\n}", "documentation": "Role an agent plays in a collaboration session.\n\nRoles define the set of actions available to an agent within a session.\nA Coordinator decomposes and assigns tasks; a Worker executes delegated\ntasks; a Peer participates in consensus-based decision-making.\n\nSee ANVIL Spec section 11.1 -- Collaboration Roles.\n\n# Examples\n\n```\nuse forge_collab::types::CollaborationRole;\n\nlet role = CollaborationRole::Coordinator;\nlet json = serde_json::to_string(&role).unwrap();\nassert_eq!(json, \"\\\"coordinator\\\"\");\n```" }, { "name": "::CollaborationSession", "line": 103, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct CollaborationSession {\n/// Unique identifier for this session.\n\npub session_id: String,\n/// The type of collaboration (e.g., \"code-review\", \"data-analysis\").\n\npub session_type: String,\n/// The agents participating in this session.\n\npub participants: Vec,\n/// The DID of the coordinator agent, if any.\n\npub coordinator: Option,\n/// The ID of the shared context store for this session.\n\npub shared_context_id: Option,\n/// ISO 8601 timestamp when the session was created.\n\npub created_at: String,\n/// Optional session timeout in seconds. When elapsed, the session\n\n/// automatically transitions to the `TimedOut` terminal state.\n\npub timeout_seconds: Option,\n/// Arbitrary metadata for application-specific session properties.\n\npub metadata: serde_json::Value\n}", "documentation": "A collaboration session grouping agents for coordinated work.\n\nSessions have a typed purpose (`session_type`), a set of participants with\nassigned roles, an optional coordinator, and an optional shared context\nstore. Sessions follow a state machine that governs their lifecycle from\nproposal through completion or dissolution.\n\nSee ANVIL Spec section 11.2 -- Collaboration Session.\n\n# Examples\n\n```\nuse forge_collab::types::{CollaborationSession, SessionParticipant, CollaborationRole};\n\nlet session = CollaborationSession {\n session_id: \"sess-001\".to_string(),\n session_type: \"code-review\".to_string(),\n participants: vec![SessionParticipant {\n agent_did: \"did:oas:agent:coordinator-1\".to_string(),\n role: CollaborationRole::Coordinator,\n joined_at: \"2026-02-19T10:00:00Z\".to_string(),\n status: \"active\".to_string(),\n }],\n coordinator: Some(\"did:oas:agent:coordinator-1\".to_string()),\n shared_context_id: Some(\"ctx-001\".to_string()),\n created_at: \"2026-02-19T10:00:00Z\".to_string(),\n timeout_seconds: Some(3600),\n metadata: serde_json::Value::Object(serde_json::Map::new()),\n};\nassert_eq!(session.session_id, \"sess-001\");\n```" }, { "name": "::SessionState", "line": 155, "signature": "#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum SessionState {\n /// The session has been proposed but not yet accepted by all participants.\n Proposed,\n /// The session is active and participants can collaborate.\n Active,\n /// The session is in the process of completing (aggregating results).\n Completing,\n /// The session has completed successfully. Terminal state.\n Completed,\n /// The session exceeded its timeout. Terminal state.\n TimedOut,\n /// The session was dissolved before completion. Terminal state.\n Dissolved,\n}", "documentation": "State of a collaboration session.\n\nThe session state machine controls which operations are valid. Sessions\nstart in the `Proposed` state and progress through `Active` and\n`Completing` states to terminal states.\n\nSee ANVIL Spec section 11.2 -- Session State Machine.\n\n# Transition Table (IMMUTABLE -- ANVIL Spec section 11.2)\n\n| Current State | Valid Next States |\n|---------------|-------------------|\n| Proposed | Active, Dissolved |\n| Active | Completing, Dissolved, TimedOut |\n| Completing | Completed, Dissolved |\n| Completed | *(terminal)* |\n| TimedOut | *(terminal)* |\n| Dissolved | *(terminal)* |\n\n# Examples\n\n```\nuse forge_collab::types::SessionState;\n\nlet state = SessionState::Active;\nassert!(!state.is_terminal());\n\nlet state = SessionState::Completed;\nassert!(state.is_terminal());\n```" }, { "name": "::SessionState::valid_transitions", "line": 192, "signature": "pub fn valid_transitions(&self) -> &'static [SessionState];", "documentation": "Returns the set of valid target states from this state.\n\nThe transition table is defined by ANVIL Spec section 11.2\nand is immutable.\n\n# Returns\n\nA slice of `SessionState` values that are valid targets from the\ncurrent state. Returns an empty slice for terminal states.\n\n# Examples\n\n```\nuse forge_collab::types::SessionState;\n\nlet targets = SessionState::Active.valid_transitions();\nassert!(targets.contains(&SessionState::Completing));\nassert!(targets.contains(&SessionState::Dissolved));\nassert!(targets.contains(&SessionState::TimedOut));\n```" }, { "name": "::SessionState::is_terminal", "line": 223, "signature": "pub fn is_terminal(&self) -> bool;", "documentation": "Returns `true` if this is a terminal state (no outgoing transitions).\n\nTerminal states are `Completed`, `TimedOut`, and `Dissolved`.\n\n# Examples\n\n```\nuse forge_collab::types::SessionState;\n\nassert!(!SessionState::Proposed.is_terminal());\nassert!(!SessionState::Active.is_terminal());\nassert!(!SessionState::Completing.is_terminal());\nassert!(SessionState::Completed.is_terminal());\nassert!(SessionState::TimedOut.is_terminal());\nassert!(SessionState::Dissolved.is_terminal());\n```" }, { "name": "::SessionParticipant", "line": 266, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct SessionParticipant {\n/// The OAS DID of the participating agent.\n\npub agent_did: String,\n/// The role this agent plays in the session.\n\npub role: CollaborationRole,\n/// ISO 8601 timestamp when the agent joined the session.\n\npub joined_at: String,\n/// Current participation status (e.g., \"active\", \"left\", \"disconnected\").\n\npub status: String\n}", "documentation": "A participant in a collaboration session.\n\nEach participant has an assigned role and a status indicating whether\nthey are actively participating. Participants join at a recorded\ntimestamp and may leave before the session completes.\n\nSee ANVIL Spec section 11.2 -- Collaboration Session.\n\n# Examples\n\n```\nuse forge_collab::types::{SessionParticipant, CollaborationRole};\n\nlet participant = SessionParticipant {\n agent_did: \"did:oas:agent:worker-1\".to_string(),\n role: CollaborationRole::Worker,\n joined_at: \"2026-02-19T10:00:00Z\".to_string(),\n status: \"active\".to_string(),\n};\nassert_eq!(participant.role, CollaborationRole::Worker);\n```" }, { "name": "::DelegatedTask", "line": 309, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct DelegatedTask {\n/// Unique identifier for this task.\n\npub task_id: String,\n/// The type of task (e.g., \"code-review\", \"summarize\", \"translate\").\n\npub task_type: String,\n/// Human-readable description of the task.\n\npub description: String,\n/// Input data for the task.\n\npub input: serde_json::Value,\n/// Optional JSON Schema describing the expected output format.\n\npub output_schema: Option,\n/// Constraints bounding the task execution.\n\npub constraints: TaskConstraints,\n/// The OAS DID of the agent that delegated this task.\n\npub delegator: String,\n/// Priority level for task scheduling.\n\npub priority: TaskPriority,\n/// Optional ISO 8601 deadline for task completion.\n\npub deadline: Option,\n/// Keys in the shared context that this task may read.\n\npub context_keys: Vec\n}", "documentation": "A task delegated from a coordinator to a worker agent.\n\nDelegated tasks carry input data, constraint bounds, output expectations,\nand context key references that the worker may read from the shared\ncontext store.\n\nSee ANVIL Spec section 11.3 -- Delegated Task.\n\n# Examples\n\n```\nuse forge_collab::types::{DelegatedTask, TaskConstraints, TaskPriority};\n\nlet task = DelegatedTask {\n task_id: \"task-001\".to_string(),\n task_type: \"code-review\".to_string(),\n description: \"Review the authentication module changes\".to_string(),\n input: serde_json::json!({\"file\": \"auth.rs\"}),\n output_schema: None,\n constraints: TaskConstraints::default(),\n delegator: \"did:oas:agent:coordinator-1\".to_string(),\n priority: TaskPriority::Normal,\n deadline: None,\n context_keys: vec![\"shared.pr.diff\".to_string()],\n};\nassert_eq!(task.task_type, \"code-review\");\n```" }, { "name": "::TaskConstraints", "line": 349, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct TaskConstraints {\n/// Maximum number of reasoning steps the worker may take.\n\npub max_steps: Option,\n/// Maximum number of tokens the worker may consume.\n\npub max_tokens: Option,\n/// Maximum duration in seconds for task execution.\n\npub max_duration_seconds: Option,\n/// Allowed tool names. If empty, no tool restrictions apply.\n\npub allowed_tools: Vec,\n/// Minimum required confidence score (0.0 to 1.0) for the result.\n\npub required_confidence: Option\n}", "documentation": "Constraints bounding a delegated task's execution.\n\nConstraints prevent runaway tasks by limiting steps, tokens, duration,\nand tool access. The worker must respect these bounds during execution.\n\nSee ANVIL Spec section 11.3 -- Task Constraints.\n\n# Examples\n\n```\nuse forge_collab::types::TaskConstraints;\n\nlet constraints = TaskConstraints::default();\nassert!(constraints.max_steps.is_none());\nassert!(constraints.required_confidence.is_none());\n```" }, { "name": "::TaskResult", "line": 411, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct TaskResult {\n/// The ID of the task this result corresponds to.\n\npub task_id: String,\n/// The completion status of the task.\n\npub status: TaskStatus,\n/// The output data produced by the worker.\n\npub output: serde_json::Value,\n/// Optional confidence score (0.0 to 1.0) for the result.\n\npub confidence: Option,\n/// Arbitrary metadata about the task execution.\n\npub metadata: serde_json::Value,\n/// Optional Ed25519 signature over the result for verification.\n\npub signature: Option\n}", "documentation": "The result of a completed delegated task.\n\nWorkers submit results with a status, output data, optional confidence\nscore, metadata, and an optional cryptographic signature.\n\nSee ANVIL Spec section 11.3 -- Task Result.\n\n# Examples\n\n```\nuse forge_collab::types::{TaskResult, TaskStatus};\n\nlet result = TaskResult {\n task_id: \"task-001\".to_string(),\n status: TaskStatus::Completed,\n output: serde_json::json!({\"summary\": \"LGTM\"}),\n confidence: Some(0.95),\n metadata: serde_json::Value::Object(serde_json::Map::new()),\n signature: None,\n};\nassert_eq!(result.status, TaskStatus::Completed);\n```" }, { "name": "::TaskStatus", "line": 431, "signature": "#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum TaskStatus {\n /// The task completed successfully with full output.\n Completed,\n /// The task failed and could not produce output.\n Failed,\n /// The task produced partial output but could not fully complete.\n Partial,\n}", "documentation": "Status of a completed delegated task.\n\nSee ANVIL Spec section 11.3 -- Task Status." }, { "name": "::TaskAcknowledgment", "line": 471, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct TaskAcknowledgment {\n/// The ID of the task being acknowledged.\n\npub task_id: String,\n/// Whether the worker accepts the task.\n\npub accepted: bool,\n/// Reason for rejection, if `accepted` is `false`.\n\npub rejection_reason: Option,\n/// Estimated time to completion in seconds, if accepted.\n\npub estimated_completion_seconds: Option\n}", "documentation": "A worker's acknowledgment of a delegated task.\n\nWhen a task is delegated, the worker responds with an acknowledgment\nindicating whether it accepts or rejects the task.\n\nSee ANVIL Spec section 11.3 -- Task Acknowledgment.\n\n# Examples\n\n```\nuse forge_collab::types::TaskAcknowledgment;\n\nlet ack = TaskAcknowledgment {\n task_id: \"task-001\".to_string(),\n accepted: true,\n rejection_reason: None,\n estimated_completion_seconds: Some(120),\n};\nassert!(ack.accepted);\n```" }, { "name": "::TaskProgress", "line": 502, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct TaskProgress {\n/// The ID of the task this progress report corresponds to.\n\npub task_id: String,\n/// Completion percentage (0.0 to 100.0).\n\npub percentage: f64,\n/// Human-readable status message.\n\npub message: String\n}", "documentation": "Progress report for an in-flight delegated task.\n\nWorkers periodically report progress to the coordinator. Progress\nincludes a percentage estimate and a human-readable status message.\n\nSee ANVIL Spec section 11.3 -- Task Progress.\n\n# Examples\n\n```\nuse forge_collab::types::TaskProgress;\n\nlet progress = TaskProgress {\n task_id: \"task-001\".to_string(),\n percentage: 50.0,\n message: \"Halfway through code review\".to_string(),\n};\nassert!((progress.percentage - 50.0).abs() < f64::EPSILON);\n```" }, { "name": "::TaskPriority", "line": 530, "signature": "#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum TaskPriority {\n /// Highest priority -- task must be handled immediately.\n Critical,\n /// High priority -- task should be handled soon.\n High,\n /// Normal priority -- default scheduling.\n Normal,\n /// Low priority -- task can wait.\n Low,\n}", "documentation": "Priority level for task scheduling.\n\nHigher priority tasks are scheduled before lower priority tasks.\nThe default priority is `Normal`.\n\nSee ANVIL Spec section 11.3 -- Task Priority.\n\n# Examples\n\n```\nuse forge_collab::types::TaskPriority;\n\nassert_eq!(TaskPriority::default(), TaskPriority::Normal);\n\nlet json = serde_json::to_string(&TaskPriority::Critical).unwrap();\nassert_eq!(json, \"\\\"critical\\\"\");\n```" }, { "name": "::Interrupt", "line": 587, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct Interrupt {\n/// Unique identifier for this interrupt.\n\npub interrupt_id: String,\n/// The type of interrupt.\n\npub interrupt_type: InterruptType,\n/// The OAS DID of the agent that sent the interrupt.\n\npub source: String,\n/// Priority of the interrupt.\n\npub priority: TaskPriority,\n/// Arbitrary payload data for the interrupt.\n\npub payload: serde_json::Value,\n/// ISO 8601 timestamp when the interrupt was created.\n\npub timestamp: String\n}", "documentation": "An interrupt sent to an agent during task execution.\n\nInterrupts allow coordinators (or the platform) to preempt, suspend,\nresume, abort, or redirect an agent's current work. Interrupts carry\na priority to determine how urgently they should be handled.\n\nSee ANVIL Spec section 11.5 -- Interrupts.\n\n# Examples\n\n```\nuse forge_collab::types::{Interrupt, InterruptType, TaskPriority};\n\nlet interrupt = Interrupt {\n interrupt_id: \"int-001\".to_string(),\n interrupt_type: InterruptType::Suspend,\n source: \"did:oas:agent:coordinator-1\".to_string(),\n priority: TaskPriority::High,\n payload: serde_json::json!({\"reason\": \"higher priority task incoming\"}),\n timestamp: \"2026-02-19T10:30:00Z\".to_string(),\n};\nassert_eq!(interrupt.interrupt_type, InterruptType::Suspend);\n```" }, { "name": "::InterruptType", "line": 616, "signature": "#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum InterruptType {\n /// Override the current task with a higher-priority task.\n PriorityOverride,\n /// Suspend the current task (can be resumed later).\n Suspend,\n /// Resume a previously suspended task.\n Resume,\n /// Abort the current task entirely.\n Abort,\n /// Redirect the agent to a different task or session.\n Redirect,\n /// A human operator is interjecting into the agent's workflow.\n HumanInterjection,\n}", "documentation": "Type of interrupt that can be sent to an agent.\n\nSee ANVIL Spec section 11.5 -- Interrupt Types.\n\n# Examples\n\n```\nuse forge_collab::types::InterruptType;\n\nlet json = serde_json::to_string(&InterruptType::HumanInterjection).unwrap();\nassert_eq!(json, \"\\\"human_interjection\\\"\");\n```" }, { "name": "::InterruptResponse", "line": 664, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct InterruptResponse {\n/// The ID of the interrupt being responded to.\n\npub interrupt_id: String,\n/// Whether the agent acknowledged and handled the interrupt.\n\npub acknowledged: bool,\n/// The agent's state at the time of interruption, if applicable.\n\npub current_state: Option\n}", "documentation": "An agent's response to an interrupt.\n\nAfter receiving an interrupt, the agent acknowledges it and optionally\nreports its interrupted state for potential resumption.\n\nSee ANVIL Spec section 11.5 -- Interrupt Response.\n\n# Examples\n\n```\nuse forge_collab::types::InterruptResponse;\n\nlet response = InterruptResponse {\n interrupt_id: \"int-001\".to_string(),\n acknowledged: true,\n current_state: None,\n};\nassert!(response.acknowledged);\n```" }, { "name": "::InterruptedState", "line": 694, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct InterruptedState {\n/// The ID of the task that was interrupted, if any.\n\npub task_id: Option,\n/// The number of steps completed before interruption.\n\npub step_count: u32,\n/// Progress percentage at the time of interruption (0.0 to 100.0).\n\npub progress_percentage: f64,\n/// Whether the task can be resumed from this state.\n\npub can_resume: bool\n}", "documentation": "Snapshot of an agent's state at the moment of interruption.\n\nThis captures enough information to resume the task later if the\ninterrupt type supports resumption.\n\nSee ANVIL Spec section 11.5 -- Interrupted State.\n\n# Examples\n\n```\nuse forge_collab::types::InterruptedState;\n\nlet state = InterruptedState {\n task_id: Some(\"task-001\".to_string()),\n step_count: 5,\n progress_percentage: 42.0,\n can_resume: true,\n};\nassert!(state.can_resume);\n```" }, { "name": "::ContextEntry", "line": 734, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ContextEntry {\n/// The key identifying this context entry.\n\npub key: String,\n/// The value stored in this entry.\n\npub value: serde_json::Value,\n/// The type of the value (e.g., \"json\", \"text\", \"binary\").\n\npub value_type: String,\n/// The OAS DID of the agent that wrote this entry.\n\npub author: String,\n/// Monotonically increasing version number for this key.\n\npub version: u64,\n/// ISO 8601 timestamp when this version was written.\n\npub timestamp: String,\n/// Visibility control for this entry.\n\npub visibility: ContextVisibility\n}", "documentation": "An entry in a session's shared context store.\n\nContext entries are key-value pairs with versioning, authorship tracking,\nand visibility controls. Participants read and write context entries to\nshare information during collaboration.\n\nSee ANVIL Spec section 11.4 -- Shared Context.\n\n# Examples\n\n```\nuse forge_collab::types::{ContextEntry, ContextVisibility};\n\nlet entry = ContextEntry {\n key: \"analysis.result\".to_string(),\n value: serde_json::json!({\"score\": 0.95}),\n value_type: \"json\".to_string(),\n author: \"did:oas:agent:worker-1\".to_string(),\n version: 1,\n timestamp: \"2026-02-19T10:15:00Z\".to_string(),\n visibility: ContextVisibility::Session,\n};\nassert_eq!(entry.version, 1);\n```" }, { "name": "::ContextVisibility", "line": 774, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum ContextVisibility {\n /// Visible to all participants in the session.\n Session,\n /// Visible only to agents with the specified role.\n Role(CollaborationRole),\n /// Visible only to the specific agent identified by DID.\n Agent(String),\n}", "documentation": "Visibility scope for a shared context entry.\n\nControls which agents can read a context entry. Entries may be visible\nto the entire session, to agents with a specific role, or to a single\nnamed agent.\n\nSee ANVIL Spec section 11.4 -- Context Visibility.\n\n# Examples\n\n```\nuse forge_collab::types::{ContextVisibility, CollaborationRole};\n\nlet vis = ContextVisibility::Session;\nlet json = serde_json::to_string(&vis).unwrap();\nassert_eq!(json, \"\\\"session\\\"\");\n\nlet role_vis = ContextVisibility::Role(CollaborationRole::Worker);\nlet json2 = serde_json::to_string(&role_vis).unwrap();\nassert!(json2.contains(\"role\"));\n```" }, { "name": "::AgentCapabilityProfile", "line": 812, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct AgentCapabilityProfile {\n/// The OAS DID of the agent.\n\npub agent_did: String,\n/// Collaboration roles this agent supports.\n\npub supported_roles: Vec,\n/// Task types this agent can handle (e.g., \"code-review\", \"translate\").\n\npub supported_task_types: Vec,\n/// Tool names available to this agent.\n\npub available_tools: Vec,\n/// Current load factor (0.0 = idle, 1.0 = fully loaded).\n\npub current_load: f64,\n/// Maximum number of tasks this agent can execute concurrently.\n\npub max_concurrent_tasks: u32\n}", "documentation": "An agent's advertised capability profile for task matching.\n\nCapability profiles describe what an agent can do (supported roles,\ntask types, available tools), its current load, and its maximum\nconcurrency. The collaboration coordinator uses these profiles to\nmatch tasks to suitable workers.\n\nSee ANVIL Spec section 11.6 -- Agent Capability Profile.\n\n# Examples\n\n```\nuse forge_collab::types::{AgentCapabilityProfile, CollaborationRole};\n\nlet profile = AgentCapabilityProfile {\n agent_did: \"did:oas:agent:analyzer-1\".to_string(),\n supported_roles: vec![CollaborationRole::Worker],\n supported_task_types: vec![\"code-review\".to_string(), \"summarize\".to_string()],\n available_tools: vec![\"read_file\".to_string(), \"search\".to_string()],\n current_load: 0.3,\n max_concurrent_tasks: 5,\n};\nassert_eq!(profile.max_concurrent_tasks, 5);\n```" }, { "name": "::SessionTransition", "line": 850, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct SessionTransition {\n/// The state before the transition.\n\npub from: SessionState,\n/// The state after the transition.\n\npub to: SessionState,\n/// ISO 8601 timestamp when the transition occurred.\n\npub timestamp: String\n}", "documentation": "A record of a single session state transition.\n\nEvery session transition is timestamped and can be stored in the session's\ntransition history for audit trail purposes.\n\n# Examples\n\n```\nuse forge_collab::types::{SessionTransition, SessionState};\n\nlet transition = SessionTransition {\n from: SessionState::Proposed,\n to: SessionState::Active,\n timestamp: \"2026-02-19T10:00:00Z\".to_string(),\n};\nassert_eq!(transition.from, SessionState::Proposed);\nassert_eq!(transition.to, SessionState::Active);\n```" } ] } ] }