{
  "name": "@forge-sdk/agent",
  "language": "typescript",
  "version": "0.1.0",
  "description": "Agent abstractions, tool loops, workflows, sub-agent delegation, and messaging for the Forge SDK",
  "manifest": "forge-ts/packages/forge-agent/package.json",
  "manifestSha256": "007384f14cd43f4c6f5ef9244bec5fb5c15d1906608e2b08f3e259e2ff67fbff",
  "status": "source-reference",
  "registryPublicationVerified": false,
  "route": "/libraries/typescript/agent",
  "features": {},
  "files": [
    {
      "path": "forge-ts/packages/forge-agent/src/agent.ts",
      "sha256": "5160b08ae8f13cf08105c05b2fc067c5a7e62f1f126f988164e264a3bf38378c",
      "artifactSha256": "466bc2fa700fa800de105f4c342f8b9f55763d19e91cf986942713fb3b314911",
      "url": "/reference/source/forge-ts/packages/forge-agent/src/agent.ts.txt",
      "declarations": [
        {
          "name": "AgentConfig",
          "line": 43,
          "signature": "export interface AgentConfig {\n  /** A human-readable name for this agent. */\n  readonly name: string;\n  /** The language model to use for inference. */\n  readonly model: LanguageModel;\n  /** Optional system prompt. */\n  readonly systemPrompt?: string;\n  /** Maximum tool loop iterations. Defaults to 10. */\n  readonly maxIterations?: number;\n  /** Generation options for model calls. */\n  readonly generateOptions?: GenerateOptions;\n  /** The approval handler for tool execution. Defaults to AutoApprove. */\n  readonly approvalHandler?: ApprovalHandler;\n  /** Custom stop conditions for the tool loop. */\n  readonly stopConditions?: readonly AgentStopCondition[];\n  /** Optional agent DID for audit trail integration. */\n  readonly agentDid?: string;\n}",
          "documentation": "Configuration for creating a ToolLoopAgent.\n\nANVIL Spec section 7.1."
        },
        {
          "name": "ToolLoopAgent",
          "line": 94,
          "signature": "export class ToolLoopAgent {\n  readonly name: string;\n  readonly agentDid: string | undefined;\n  readonly registry: ToolRegistry;\n  readonly healthProfile: HealthProfile;\n  readonly lifecycle: LifecycleManager;\n  constructor(config: AgentConfig);\n  async initialize(): Promise<void>;\n  async run(userMessage: string): Promise<ToolLoopOutput>;\n  async pause(): Promise<void>;\n  async resume(): Promise<void>;\n  async terminate(): Promise<void>;\n  get isRunning(): boolean;\n  get isTerminated(): boolean;\n}",
          "documentation": "A tool-loop agent that manages its own lifecycle, tool registry, and health profile.\n\nThe ToolLoopAgent is the primary agent abstraction in Forge. It:\n- Manages the ANVIL lifecycle state machine (Initializing -> Ready -> Running -> ...).\n- Maintains a tool registry for available tools.\n- Tracks health metrics (inference calls, tool invocations, errors).\n- Executes the tool loop when `run()` is called.\n\nANVIL Spec section 7.1: Agent Execution.\nANVIL Spec section 13.2: Lifecycle State Machine."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-agent/src/error.ts",
      "sha256": "b9f015e7e6f75d48dfd49027470d71711ecd33fdc7e8ae512fa755a349e0d2fc",
      "artifactSha256": "7f71c698d1279de36b5cfb8c018bd16aafa14f028eb1baf14ea11c12cec2d314",
      "url": "/reference/source/forge-ts/packages/forge-agent/src/error.ts.txt",
      "declarations": [
        {
          "name": "export const ForgeAgentErrorCode = {",
          "line": 17,
          "signature": "export const ForgeAgentErrorCode /* type inferred in source */;",
          "documentation": "Error types for the `@forge-sdk/agent` package.\n\nAll errors are actionable with full context: agent DIDs, tool names,\nworkflow IDs, and specific reasons for failure. This enables operators\nand developers to diagnose agent execution failures without guessing.\n\nANVIL Spec section 7.1 -- Agent Execution.\nANVIL Spec section 11.2 -- Sub-Agent Delegation.\nError code enumeration for `@forge-sdk/agent`."
        },
        {
          "name": "ForgeAgentErrorCodeType",
          "line": 39,
          "signature": "export type ForgeAgentErrorCodeType =\n  (typeof ForgeAgentErrorCode)[keyof typeof ForgeAgentErrorCode];",
          "documentation": "Error code type."
        },
        {
          "name": "ForgeAgentError",
          "line": 59,
          "signature": "export class ForgeAgentError extends Error {\n  public readonly code: ForgeAgentErrorCodeType;\n  static maxIterationsExceeded(\n    maxIterations: number,\n    lastToolNames: readonly string[]\n  ): ForgeAgentError;\n  static toolNotFound(toolName: string, available: readonly string[]): ForgeAgentError;\n  static toolExecutionFailed(toolName: string, reason: string): ForgeAgentError;\n  static modelError(reason: string): ForgeAgentError;\n  static workflowFailed(\n    workflowId: string,\n    stepIndex: number,\n    reason: string\n  ): ForgeAgentError;\n  static delegationFailed(parentDid: string, reason: string): ForgeAgentError;\n  static invalidState(\n    currentState: string,\n    requiredState: string,\n    operation: string\n  ): ForgeAgentError;\n  static channelError(reason: string): ForgeAgentError;\n  static core(cause: string): ForgeAgentError;\n  isMaxIterationsExceeded(): boolean;\n  isToolNotFound(): boolean;\n  isWorkflowFailed(): boolean;\n  isDelegationFailed(): boolean;\n}",
          "documentation": "Error class for Forge agent operations.\n\nEach variant carries enough context for operators to diagnose the issue\nwithout access to internal state."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-agent/src/index.ts",
      "sha256": "5b2ad1ec8450d18ef3a2d7fc3c8e5b2dd5b941ffbf9c817f136af89e275a8f90",
      "artifactSha256": "f463da14f96f4b7a1d5bd9a3450d2bd7bd314fa724a1186675a6211feeb3d6ce",
      "url": "/reference/source/forge-ts/packages/forge-agent/src/index.ts.txt",
      "declarations": [
        {
          "name": "export { ForgeAgentError, ForgeAgentErrorCode, type ForgeAgentErrorCodeType } from './error.js';",
          "line": 45,
          "signature": "export { ForgeAgentError, ForgeAgentErrorCode, type ForgeAgentErrorCodeType } from './error.js';",
          "documentation": ""
        },
        {
          "name": "export {",
          "line": 48,
          "signature": "export {\n  AgentStopReason,\n  type AgentStopCondition,\n  type LoopContext,\n  maxIterations,\n  maxTotalTokens,\n  modelStopsNaturally,\n  customStop,\n  evaluateStopConditions,\n} from './loop-control.js';",
          "documentation": ""
        },
        {
          "name": "export {",
          "line": 60,
          "signature": "export {\n  type ToolLoopConfig,\n  type ToolLoopIteration,\n  type ToolLoopOutput,\n  runToolLoop,\n} from './tool-loop.js';",
          "documentation": ""
        },
        {
          "name": "export {",
          "line": 68,
          "signature": "export {\n  type AgentConfig,\n  ToolLoopAgent,\n} from './agent.js';",
          "documentation": ""
        },
        {
          "name": "export {",
          "line": 74,
          "signature": "export {\n  type WorkflowStep,\n  type WorkflowResult,\n  type RouterFn,\n  SequentialWorkflow,\n  ParallelWorkflow,\n  RouterWorkflow,\n} from './workflow.js';",
          "documentation": ""
        },
        {
          "name": "export {",
          "line": 84,
          "signature": "export {\n  type SubAgentConfig,\n  createSubAgent,\n  runSubAgentTask,\n} from './subagent.js';",
          "documentation": ""
        },
        {
          "name": "export {",
          "line": 91,
          "signature": "export {\n  type AgentMessage,\n  MessageType,\n  type TypedMessage,\n  AgentChannel,\n  createAgentMessage,\n  createTypedMessage,\n} from './messaging.js';",
          "documentation": ""
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-agent/src/loop-control.ts",
      "sha256": "0c956a76d40aa30e8ff6a533c84527ce3e0d5e88a03667444c14f20d69cc7d95",
      "artifactSha256": "2aabbd72da869a2a13fca20952859001a3477c349a58d355569a1550b924c185",
      "url": "/reference/source/forge-ts/packages/forge-agent/src/loop-control.ts.txt",
      "declarations": [
        {
          "name": "export const AgentStopReason = {",
          "line": 20,
          "signature": "export const AgentStopReason /* type inferred in source */;",
          "documentation": "Stop condition types for the tool loop.\n\nANVIL Spec section 7.1."
        },
        {
          "name": "AgentStopReason",
          "line": 32,
          "signature": "export type AgentStopReason = (typeof AgentStopReason)[keyof typeof AgentStopReason];",
          "documentation": "Agent stop reason type."
        },
        {
          "name": "AgentStopCondition",
          "line": 48,
          "signature": "export interface AgentStopCondition {\n  /** A human-readable name for this stop condition. */\n  readonly name: string;\n\n  /**\n   * Evaluates the stop condition against the current loop context.\n   *\n   * @param context - The current loop iteration context.\n   * @returns `true` if the loop should stop.\n   */\n  check(context: LoopContext): boolean;\n}",
          "documentation": "A stop condition that evaluates after each tool loop iteration.\n\nANVIL Spec section 7.1: The tool loop MUST terminate when a stop\ncondition is met. Stop conditions are checked after every iteration."
        },
        {
          "name": "LoopContext",
          "line": 64,
          "signature": "export interface LoopContext {\n  /** The current iteration number (0-indexed). */\n  readonly iteration: number;\n  /** The cumulative token usage across all iterations. */\n  readonly totalUsage: Usage;\n  /** The finish reason from the last model call. */\n  readonly lastFinishReason: FinishReason;\n  /** The number of tool calls in the last iteration. */\n  readonly lastToolCallCount: number;\n}",
          "documentation": "Context passed to stop conditions after each tool loop iteration."
        },
        {
          "name": "maxIterations",
          "line": 86,
          "signature": "export function maxIterations(max: number): AgentStopCondition;",
          "documentation": "Creates a stop condition that triggers after N iterations."
        },
        {
          "name": "maxTotalTokens",
          "line": 104,
          "signature": "export function maxTotalTokens(max: number): AgentStopCondition;",
          "documentation": "Creates a stop condition that triggers when total tokens exceed a limit."
        },
        {
          "name": "modelStopsNaturally",
          "line": 124,
          "signature": "export function modelStopsNaturally(): AgentStopCondition;",
          "documentation": "Creates a stop condition that triggers when the model produces no tool calls.\n\nThis is the most common stop condition -- the loop ends when the model\nprovides a natural text response without requesting any tool invocations."
        },
        {
          "name": "customStop",
          "line": 143,
          "signature": "export function customStop(\n  name: string,\n  predicate: (context: LoopContext) => boolean\n): AgentStopCondition;",
          "documentation": "Creates a custom stop condition from a predicate function."
        },
        {
          "name": "evaluateStopConditions",
          "line": 160,
          "signature": "export function evaluateStopConditions(\n  context: LoopContext,\n  conditions: readonly AgentStopCondition[]\n): { reason: AgentStopReason; conditionName: string } | undefined;",
          "documentation": "Determines the agent stop reason from the loop context.\n\nChecks stop conditions in priority order and returns the reason for\nthe first condition that triggers."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-agent/src/messaging.ts",
      "sha256": "f8f29bcc0045c4ccd0bbfa8f2c4d855d955b398354270db1bd60a7fdaff20ad0",
      "artifactSha256": "2010dfb42ed76e184a07a0b4a9a5cf44277692f8740ac3430e370fadc1a3e99a",
      "url": "/reference/source/forge-ts/packages/forge-agent/src/messaging.ts.txt",
      "declarations": [
        {
          "name": "AgentMessage",
          "line": 34,
          "signature": "export interface AgentMessage {\n  /** Unique message identifier. */\n  readonly id: string;\n  /** The OAS DID of the sending agent. */\n  readonly senderDid: string;\n  /** The OAS DID of the recipient agent. */\n  readonly recipientDid: string;\n  /** The message payload (arbitrary JSON-serializable data). */\n  readonly payload: unknown;\n  /** The UTC timestamp when the message was created. */\n  readonly timestamp: Timestamp;\n}",
          "documentation": "A message exchanged between agents.\n\nEvery message carries sender and recipient DIDs for audit trail\nintegration and accountability.\n\nANVIL Spec section 12.1."
        },
        {
          "name": "export const MessageType = {",
          "line": 52,
          "signature": "export const MessageType /* type inferred in source */;",
          "documentation": "Message types for structured inter-agent communication.\n\nANVIL Spec section 12.1."
        },
        {
          "name": "MessageType",
          "line": 64,
          "signature": "export type MessageType = (typeof MessageType)[keyof typeof MessageType];",
          "documentation": "Message type value."
        },
        {
          "name": "TypedMessage",
          "line": 78,
          "signature": "export interface TypedMessage extends AgentMessage {\n  /** The message type discriminator. */\n  readonly messageType: MessageType;\n  /** Optional correlation ID for request-response pairing. */\n  readonly correlationId?: string;\n}",
          "documentation": "A typed message with a message type discriminator."
        },
        {
          "name": "AgentChannel",
          "line": 107,
          "signature": "export class AgentChannel {\n  constructor(capacity: number = 1000);\n  send(message: AgentMessage): void;\n  receive(): AgentMessage | undefined;\n  drain(): AgentMessage[];\n  get size(): number;\n  get isEmpty(): boolean;\n  get capacity(): number;\n}",
          "documentation": "A simple in-memory message channel between two agents.\n\nMessages are queued in FIFO order and can be consumed one at a time\nor drained in batch. The channel has a configurable capacity limit\nto prevent unbounded memory growth.\n\nANVIL Spec section 12.1: Inter-agent communication channels."
        },
        {
          "name": "createAgentMessage",
          "line": 207,
          "signature": "export function createAgentMessage(\n  senderDid: string,\n  recipientDid: string,\n  payload: unknown\n): AgentMessage;",
          "documentation": "Creates an AgentMessage with auto-generated ID and timestamp."
        },
        {
          "name": "createTypedMessage",
          "line": 231,
          "signature": "export function createTypedMessage(\n  senderDid: string,\n  recipientDid: string,\n  payload: unknown,\n  messageType: MessageType,\n  correlationId?: string\n): TypedMessage;",
          "documentation": "Creates a TypedMessage with auto-generated ID and timestamp."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-agent/src/subagent.ts",
      "sha256": "30c60fd0938dc0eb99383880558d8a791b3eb371ecd3ef1dd2a2bc74c0dad444",
      "artifactSha256": "e2ea6ccee3609100bb81f530f9b7d577a854e5e8bf95d1614cbfcb3bfb79c448",
      "url": "/reference/source/forge-ts/packages/forge-agent/src/subagent.ts.txt",
      "declarations": [
        {
          "name": "SubAgentConfig",
          "line": 35,
          "signature": "export interface SubAgentConfig {\n  /** A human-readable name for the sub-agent. */\n  readonly name: string;\n  /** The language model for the sub-agent (may differ from parent). */\n  readonly model: LanguageModel;\n  /** Optional system prompt for the sub-agent. */\n  readonly systemPrompt?: string;\n  /** Maximum tool loop iterations. Defaults to 10. */\n  readonly maxIterations?: number;\n  /** Generation options for the sub-agent's model calls. */\n  readonly generateOptions?: GenerateOptions;\n  /** Approval handler for the sub-agent. Defaults to parent's handler. */\n  readonly approvalHandler?: ApprovalHandler;\n  /** Custom stop conditions for the sub-agent. */\n  readonly stopConditions?: readonly AgentStopCondition[];\n  /**\n   * Tool names to grant to the sub-agent. Must be a subset of the\n   * parent's registered tools.\n   *\n   * ANVIL Spec section 11.3: child_capabilities subset_of parent_capabilities.\n   */\n  readonly allowedTools?: readonly string[];\n  /** Optional sub-agent DID. */\n  readonly agentDid?: string;\n}",
          "documentation": "Configuration for creating a sub-agent from a parent agent.\n\nANVIL Spec section 11.2."
        },
        {
          "name": "createSubAgent",
          "line": 91,
          "signature": "export function createSubAgent(\n  parent: ToolLoopAgent,\n  config: SubAgentConfig\n): ToolLoopAgent;",
          "documentation": "Creates a sub-agent from a parent agent with a narrowed set of tools.\n\nThe sub-agent receives only the tools specified in `config.allowedTools`.\nIf `allowedTools` is not specified, the sub-agent receives all of the\nparent's tools.\n\nANVIL Spec section 11.2: Sub-Agent Delegation.\nANVIL Spec section 11.3: The sub-agent's capabilities MUST be a subset\nof the parent's capabilities. Escalation is always denied."
        },
        {
          "name": "runSubAgentTask",
          "line": 179,
          "signature": "export async function runSubAgentTask(\n  parent: ToolLoopAgent,\n  config: SubAgentConfig,\n  message: string\n): Promise<import('./tool-loop.js').ToolLoopOutput>;",
          "documentation": "Runs a sub-agent task: creates a sub-agent, initializes it, runs the\nmessage, and terminates it, all in one call.\n\nThis is a convenience function for fire-and-forget delegation patterns."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-agent/src/tool-loop.ts",
      "sha256": "8cc5f367a14480d640e77a45ffc1aa3e657531eb1018a5b0557d27833e1ca5ed",
      "artifactSha256": "e50b26583583d8fe32591511e4461d74f528937077daafb4bf01b44d9b0f55fb",
      "url": "/reference/source/forge-ts/packages/forge-agent/src/tool-loop.ts.txt",
      "declarations": [
        {
          "name": "ToolLoopConfig",
          "line": 55,
          "signature": "export interface ToolLoopConfig {\n  /** The language model to use for inference. */\n  readonly model: LanguageModel;\n  /** The tool registry containing available tools and their executors. */\n  readonly registry: ToolRegistry;\n  /** Optional system prompt prepended to every conversation. */\n  readonly systemPrompt?: string;\n  /** Maximum number of tool loop iterations. Defaults to 10. */\n  readonly maxIterations?: number;\n  /** Generation options for model calls. */\n  readonly generateOptions?: GenerateOptions;\n  /** The approval handler for tool execution. Defaults to AutoApprove. */\n  readonly approvalHandler?: ApprovalHandler;\n  /** Custom stop conditions evaluated after each iteration. */\n  readonly stopConditions?: readonly AgentStopCondition[];\n  /** The health profile to update with tool invocations and inference calls. */\n  readonly healthProfile?: HealthProfile;\n}",
          "documentation": "Configuration for a tool loop execution.\n\nANVIL Spec section 7.1."
        },
        {
          "name": "ToolLoopIteration",
          "line": 79,
          "signature": "export interface ToolLoopIteration {\n  /** The iteration index (0-based). */\n  readonly index: number;\n  /** The model's response message for this iteration. */\n  readonly assistantMessage: ModelMessage;\n  /** The tool calls requested by the model (empty if none). */\n  readonly toolCalls: readonly ToolCall[];\n  /** The tool results from executing the tool calls (empty if no calls). */\n  readonly toolResults: readonly ToolResult[];\n  /** Token usage for this iteration. */\n  readonly usage: Usage;\n}",
          "documentation": "The output of a single tool loop iteration.\n\nANVIL Spec section 7.1."
        },
        {
          "name": "ToolLoopOutput",
          "line": 104,
          "signature": "export interface ToolLoopOutput {\n  /** The final text response from the model. */\n  readonly finalText: string;\n  /** All iterations executed during the loop. */\n  readonly iterations: readonly ToolLoopIteration[];\n  /** The total token usage across all iterations. */\n  readonly totalUsage: Usage;\n  /** The reason the loop stopped. */\n  readonly stopReason: string;\n  /** The complete conversation history including all messages. */\n  readonly messages: readonly ModelMessage[];\n}",
          "documentation": "The output of a complete tool loop execution.\n\nANVIL Spec section 7.1."
        },
        {
          "name": "runToolLoop",
          "line": 148,
          "signature": "export async function runToolLoop(\n  config: ToolLoopConfig,\n  userMessage: string\n): Promise<ToolLoopOutput>;",
          "documentation": "Runs the tool loop: the core ANVIL agent execution pattern.\n\nThe loop repeatedly calls the model, executes any requested tools,\nand appends results to the conversation until a stop condition triggers.\n\nANVIL Spec section 7.1: The agent execution loop MUST:\n- Call the model with the full conversation context and available tools.\n- Execute tool calls through the approval pipeline.\n- Append tool results to the conversation.\n- Repeat until the model stops calling tools or a limit is reached."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-agent/src/workflow.ts",
      "sha256": "fca44a1ad9c288097814295e175f0b0afeb9d65c6cb671778b9f0a7673d839c1",
      "artifactSha256": "ca5aa95f48a65433cb62c0d7e0a7354eff501a0aa19d14439c2ebfa53fdcf2ee",
      "url": "/reference/source/forge-ts/packages/forge-agent/src/workflow.ts.txt",
      "declarations": [
        {
          "name": "WorkflowStep",
          "line": 28,
          "signature": "export interface WorkflowStep {\n  /** The name of the agent that executed this step. */\n  readonly agentName: string;\n  /** The output from the agent's tool loop. */\n  readonly output: ToolLoopOutput;\n  /** The wall-clock duration of this step in milliseconds. */\n  readonly durationMs: number;\n}",
          "documentation": "The result of a single workflow step."
        },
        {
          "name": "WorkflowResult",
          "line": 49,
          "signature": "export interface WorkflowResult {\n  /** The workflow identifier. */\n  readonly workflowId: string;\n  /** All steps executed in the workflow. */\n  readonly steps: readonly WorkflowStep[];\n  /** The total wall-clock duration of the workflow in milliseconds. */\n  readonly totalDurationMs: number;\n}",
          "documentation": "The result of a complete workflow execution."
        },
        {
          "name": "SequentialWorkflow",
          "line": 74,
          "signature": "export class SequentialWorkflow {\n  readonly workflowId: string;\n  constructor(workflowId: string, agents: readonly ToolLoopAgent[]);\n  async run(initialMessage: string): Promise<WorkflowResult>;\n}",
          "documentation": "A sequential workflow that runs agents one after another.\n\nEach agent receives the output text of the previous agent as its input.\nThis enables pipeline-style processing where each stage transforms\nor refines the result.\n\nANVIL Spec section 7.2: Sequential Orchestration."
        },
        {
          "name": "ParallelWorkflow",
          "line": 166,
          "signature": "export class ParallelWorkflow {\n  readonly workflowId: string;\n  constructor(workflowId: string, agents: readonly ToolLoopAgent[]);\n  async run(message: string): Promise<WorkflowResult>;\n}",
          "documentation": "A parallel workflow that runs agents concurrently.\n\nAll agents receive the same input message and execute simultaneously.\nTheir outputs are collected and returned together when all agents complete.\n\nANVIL Spec section 7.2: Parallel Orchestration."
        },
        {
          "name": "RouterFn",
          "line": 256,
          "signature": "export type RouterFn = (\n  message: string,\n  agents: readonly ToolLoopAgent[]\n) => number | Promise<number>;",
          "documentation": "A routing function that selects which agent should handle a message."
        },
        {
          "name": "RouterWorkflow",
          "line": 281,
          "signature": "export class RouterWorkflow {\n  readonly workflowId: string;\n  constructor(\n    workflowId: string,\n    agents: readonly ToolLoopAgent[],\n    router: RouterFn\n  );\n  async run(message: string): Promise<WorkflowResult>;\n}",
          "documentation": "A router workflow that dynamically selects an agent based on the input.\n\nThe router function determines which agent handles each request. This\nenables pattern-matching, intent classification, or model-based routing.\n\nANVIL Spec section 7.2: Router Orchestration."
        }
      ]
    }
  ]
}