gsd-pi 2.80.0-dev.c5f2443b3 → 2.80.0-dev.d4fc28e6b

package/packages/pi-agent-core/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n\tAssistantMessage,\n\tAssistantMessageEvent,\n\tImageContent,\n\tMessage,\n\tModel,\n\tSimpleStreamOptions,\n\tstreamSimple,\n\tTextContent,\n\tTool,\n\tToolResultMessage,\n} from \"@gsd/pi-ai\";\nimport type { Static, TSchema } from \"@sinclair/typebox\";\n\n/** Stream function - can return sync or Promise for async config lookup */\nexport type StreamFn = (\n\t...args: Parameters<typeof streamSimple>\n) => ReturnType<typeof streamSimple> | Promise<ReturnType<typeof streamSimple>>;\n\n/**\n * Configuration for how tool calls from a single assistant message are executed.\n *\n * - \"sequential\": each tool call is prepared, executed, and finalized before the next one starts.\n * - \"parallel\": tool calls are prepared sequentially, then allowed tools execute concurrently.\n *   Final tool results are still emitted in assistant source order.\n */\nexport type ToolExecutionMode = \"sequential\" | \"parallel\";\n\n/** A single tool call content block emitted by an assistant message. */\nexport type AgentToolCall = Extract<AssistantMessage[\"content\"][number], { type: \"toolCall\" }>;\n\n/**\n * Result returned from `beforeToolCall`.\n *\n * Returning `{ block: true }` prevents the tool from executing. The loop emits an error tool result instead.\n * `reason` becomes the text shown in that error result. If omitted, a default blocked message is used.\n */\nexport interface BeforeToolCallResult {\n\tblock?: boolean;\n\treason?: string;\n}\n\n/**\n * Partial override returned from `afterToolCall`.\n *\n * Merge semantics are field-by-field:\n * - `content`: if provided, replaces the tool result content array in full\n * - `details`: if provided, replaces the tool result details value in full\n * - `isError`: if provided, replaces the tool result error flag\n *\n * Omitted fields keep the original executed tool result values.\n */\nexport interface AfterToolCallResult {\n\tcontent?: (TextContent | ImageContent)[];\n\tdetails?: unknown;\n\tisError?: boolean;\n}\n\n/** Context passed to `beforeToolCall`. */\nexport interface BeforeToolCallContext {\n\t/** The assistant message that requested the tool call. */\n\tassistantMessage: AssistantMessage;\n\t/** The raw tool call block from `assistantMessage.content`. */\n\ttoolCall: AgentToolCall;\n\t/** Validated tool arguments for the target tool schema. */\n\targs: unknown;\n\t/** Current agent context at the time the tool call is prepared. */\n\tcontext: AgentContext;\n}\n\n/** Context passed to `afterToolCall`. */\nexport interface AfterToolCallContext {\n\t/** The assistant message that requested the tool call. */\n\tassistantMessage: AssistantMessage;\n\t/** The raw tool call block from `assistantMessage.content`. */\n\ttoolCall: AgentToolCall;\n\t/** Validated tool arguments for the target tool schema. */\n\targs: unknown;\n\t/** The executed tool result before any `afterToolCall` overrides are applied. */\n\tresult: AgentToolResult<any>;\n\t/** Whether the executed tool result is currently treated as an error. */\n\tisError: boolean;\n\t/** Current agent context at the time the tool call is finalized. */\n\tcontext: AgentContext;\n}\n\n/**\n * Configuration for the agent loop.\n */\nexport interface AgentLoopConfig extends SimpleStreamOptions {\n\tmodel: Model<any>;\n\n\t/**\n\t * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.\n\t *\n\t * Each AgentMessage must be converted to a UserMessage, AssistantMessage, or ToolResultMessage\n\t * that the LLM can understand. AgentMessages that cannot be converted (e.g., UI-only notifications,\n\t * status messages) should be filtered out.\n\t *\n\t * @example\n\t * ```typescript\n\t * convertToLlm: (messages) => messages.flatMap(m => {\n\t *   if (m.role === \"custom\") {\n\t *     // Convert custom message to user message\n\t *     return [{ role: \"user\", content: m.content, timestamp: m.timestamp }];\n\t *   }\n\t *   if (m.role === \"notification\") {\n\t *     // Filter out UI-only messages\n\t *     return [];\n\t *   }\n\t *   // Pass through standard LLM messages\n\t *   return [m];\n\t * })\n\t * ```\n\t */\n\tconvertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;\n\n\t/**\n\t * Optional transform applied to the context before `convertToLlm`.\n\t *\n\t * Use this for operations that work at the AgentMessage level:\n\t * - Context window management (pruning old messages)\n\t * - Injecting context from external sources\n\t *\n\t * @example\n\t * ```typescript\n\t * transformContext: async (messages) => {\n\t *   if (estimateTokens(messages) > MAX_TOKENS) {\n\t *     return pruneOldMessages(messages);\n\t *   }\n\t *   return messages;\n\t * }\n\t * ```\n\t */\n\ttransformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;\n\n\t/**\n\t * Resolves an API key dynamically for each LLM call.\n\t *\n\t * Useful for short-lived OAuth tokens (e.g., GitHub Copilot) that may expire\n\t * during long-running tool execution phases.\n\t */\n\tgetApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;\n\n\t/**\n\t * Returns steering messages to inject into the conversation mid-run.\n\t *\n\t * Called after each tool execution to check for user interruptions.\n\t * If messages are returned, remaining tool calls are skipped and\n\t * these messages are added to the context before the next LLM call.\n\t *\n\t * Use this for \"steering\" the agent while it's working.\n\t */\n\tgetSteeringMessages?: () => Promise<AgentMessage[]>;\n\n\t/**\n\t * Returns follow-up messages to process after the agent would otherwise stop.\n\t *\n\t * Called when the agent has no more tool calls and no steering messages.\n\t * If messages are returned, they're added to the context and the agent\n\t * continues with another turn.\n\t *\n\t * Use this for follow-up messages that should wait until the agent finishes.\n\t */\n\tgetFollowUpMessages?: () => Promise<AgentMessage[]>;\n\n\t/**\n\t * Tool execution mode.\n\t * - \"sequential\": execute tool calls one by one\n\t * - \"parallel\": preflight tool calls sequentially, then execute allowed tools concurrently\n\t *\n\t * Default: \"parallel\"\n\t */\n\ttoolExecution?: ToolExecutionMode;\n\n\t/**\n\t * Called before a tool is executed, after arguments have been validated.\n\t *\n\t * Return `{ block: true }` to prevent execution. The loop emits an error tool result instead.\n\t * The hook receives the agent abort signal and is responsible for honoring it.\n\t */\n\tbeforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;\n\n\t/**\n\t * Called after a tool finishes executing, before final tool events are emitted.\n\t *\n\t * Return an `AfterToolCallResult` to override parts of the executed tool result:\n\t * - `content` replaces the full content array\n\t * - `details` replaces the full details payload\n\t * - `isError` replaces the error flag\n\t *\n\t * Any omitted fields keep their original values. No deep merge is performed.\n\t * The hook receives the agent abort signal and is responsible for honoring it.\n\t */\n\tafterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;\n\n\t/**\n\t * When true, tool calls in assistant messages are rendered in the TUI\n\t * but NOT executed locally. Used for providers that handle tool execution\n\t * internally (e.g., Claude Code CLI via Agent SDK).\n\t *\n\t * The agent loop emits tool_execution_start/end events for TUI rendering\n\t * but skips tool.execute() and does not add tool results to context.\n\t */\n\texternalToolExecution?: boolean;\n\n\t/**\n\t * Called when the agent is about to retry after a recoverable provider error.\n\t *\n\t * Fires after each transient failure (rate limit, connection reset, etc.)\n\t * before the retry backoff sleep. Useful for surfacing retry telemetry to\n\t * the host app without instrumenting the provider layer directly.\n\t */\n\tonRetry?: (context: RetryContext, signal?: AbortSignal) => Promise<void> | void;\n\n\t/**\n\t * Called when the LLM stream fails mid-response.\n\t *\n\t * Fires once per failed stream — `onRetry` may still fire separately if the\n\t * loop elects to retry. Use this for logging or flushing partial state.\n\t */\n\tonStreamError?: (context: StreamErrorContext, signal?: AbortSignal) => Promise<void> | void;\n}\n\n/** Context passed to `onRetry`. */\nexport interface RetryContext {\n\tattempt: number;\n\tmaxRetries: number;\n\tdelayMs: number;\n\terror: Error;\n}\n\n/** Context passed to `onStreamError`. */\nexport interface StreamErrorContext {\n\terror: Error;\n\t/** The text already emitted by the stream before it failed (may be empty). */\n\tpartialText: string;\n\t/** Whether the loop will attempt to retry after this failure. */\n\twillRetry: boolean;\n}\n\n/**\n * Thinking/reasoning level for models that support it.\n * Note: \"xhigh\" is only supported by OpenAI gpt-5.1-codex-max, gpt-5.2, gpt-5.2-codex, gpt-5.3, and gpt-5.3-codex models.\n */\nexport type ThinkingLevel = \"off\" | \"minimal\" | \"low\" | \"medium\" | \"high\" | \"xhigh\";\n\n/**\n * Extensible interface for custom app messages.\n * Apps can extend via declaration merging:\n *\n * @example\n * ```typescript\n * declare module \"@mariozechner/agent\" {\n *   interface CustomAgentMessages {\n *     artifact: ArtifactMessage;\n *     notification: NotificationMessage;\n *   }\n * }\n * ```\n */\nexport interface CustomAgentMessages {\n\t// Empty by default - apps extend via declaration merging\n}\n\n/**\n * AgentMessage: Union of LLM messages + custom messages.\n * This abstraction allows apps to add custom message types while maintaining\n * type safety and compatibility with the base LLM messages.\n */\nexport type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];\n\n/**\n * Agent state containing all configuration and conversation data.\n */\nexport interface AgentState {\n\tsystemPrompt: string;\n\tmodel: Model<any>;\n\tthinkingLevel: ThinkingLevel;\n\ttools: AgentTool<any>[];\n\tmessages: AgentMessage[]; // Can include attachments + custom message types\n\tisStreaming: boolean;\n\tstreamMessage: AgentMessage | null;\n\tpendingToolCalls: Set<string>;\n\terror?: string;\n\t/**\n\t * The model currently being used for inference. Set at _runLoop() start,\n\t * cleared when the loop ends. When present, UI should display this instead\n\t * of `model` to avoid showing a stale value after a mid-turn model switch.\n\t */\n\tactiveInferenceModel?: Model<any>;\n}\n\nexport interface AgentToolResult<T> {\n\t// Content blocks supporting text and images\n\tcontent: (TextContent | ImageContent)[];\n\t// Details to be displayed in a UI or logged\n\tdetails: T;\n}\n\n// Callback for streaming tool execution updates\nexport type AgentToolUpdateCallback<T = any> = (partialResult: AgentToolResult<T>) => void;\n\n// AgentTool extends Tool but adds the execute function\nexport interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any> extends Tool<TParameters> {\n\t// A human-readable label for the tool to be displayed in UI\n\tlabel: string;\n\texecute: (\n\t\ttoolCallId: string,\n\t\tparams: Static<TParameters>,\n\t\tsignal?: AbortSignal,\n\t\tonUpdate?: AgentToolUpdateCallback<TDetails>,\n\t) => Promise<AgentToolResult<TDetails>>;\n}\n\n// AgentContext is like Context but uses AgentTool\nexport interface AgentContext {\n\tsystemPrompt: string;\n\tmessages: AgentMessage[];\n\ttools?: AgentTool<any>[];\n}\n\n/**\n * Events emitted by the Agent for UI updates.\n * These events provide fine-grained lifecycle information for messages, turns, and tool executions.\n */\nexport type AgentEvent =\n\t// Agent lifecycle\n\t| { type: \"agent_start\" }\n\t| { type: \"agent_end\"; messages: AgentMessage[] }\n\t// Turn lifecycle - a turn is one assistant response + any tool calls/results\n\t| { type: \"turn_start\" }\n\t| { type: \"turn_end\"; message: AgentMessage; toolResults: ToolResultMessage[] }\n\t// Message lifecycle - emitted for user, assistant, and toolResult messages\n\t| { type: \"message_start\"; message: AgentMessage }\n\t// Only emitted for assistant messages during streaming\n\t| { type: \"message_update\"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }\n\t| { type: \"message_end\"; message: AgentMessage }\n\t// Tool execution lifecycle\n\t| { type: \"tool_execution_start\"; toolCallId: string; toolName: string; args: any }\n\t| { type: \"tool_execution_update\"; toolCallId: string; toolName: string; args: any; partialResult: any }\n\t| { type: \"tool_execution_end\"; toolCallId: string; toolName: string; result: any; isError: boolean };\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n\tAssistantMessage,\n\tAssistantMessageEvent,\n\tImageContent,\n\tMessage,\n\tModel,\n\tSimpleStreamOptions,\n\tstreamSimple,\n\tTextContent,\n\tTool,\n\tToolResultMessage,\n} from \"@gsd/pi-ai\";\nimport type { Static, TSchema } from \"@sinclair/typebox\";\n\n/** Stream function - can return sync or Promise for async config lookup */\nexport type StreamFn = (\n\t...args: Parameters<typeof streamSimple>\n) => ReturnType<typeof streamSimple> | Promise<ReturnType<typeof streamSimple>>;\n\n/**\n * Configuration for how tool calls from a single assistant message are executed.\n *\n * - \"sequential\": each tool call is prepared, executed, and finalized before the next one starts.\n * - \"parallel\": tool calls are prepared sequentially, then allowed tools execute concurrently.\n *   Final tool results are still emitted in assistant source order.\n */\nexport type ToolExecutionMode = \"sequential\" | \"parallel\";\n\n/** A single tool call content block emitted by an assistant message. */\nexport type AgentToolCall = Extract<AssistantMessage[\"content\"][number], { type: \"toolCall\" }>;\n\n/**\n * Result returned from `beforeToolCall`.\n *\n * Returning `{ block: true }` prevents the tool from executing. The loop emits an error tool result instead.\n * `reason` becomes the text shown in that error result. If omitted, a default blocked message is used.\n */\nexport interface BeforeToolCallResult {\n\tblock?: boolean;\n\treason?: string;\n}\n\n/**\n * Partial override returned from `afterToolCall`.\n *\n * Merge semantics are field-by-field:\n * - `content`: if provided, replaces the tool result content array in full\n * - `details`: if provided, replaces the tool result details value in full\n * - `isError`: if provided, replaces the tool result error flag\n *\n * Omitted fields keep the original executed tool result values.\n */\nexport interface AfterToolCallResult {\n\tcontent?: (TextContent | ImageContent)[];\n\tdetails?: unknown;\n\tisError?: boolean;\n}\n\n/** Context passed to `beforeToolCall`. */\nexport interface BeforeToolCallContext {\n\t/** The assistant message that requested the tool call. */\n\tassistantMessage: AssistantMessage;\n\t/** The raw tool call block from `assistantMessage.content`. */\n\ttoolCall: AgentToolCall;\n\t/** Validated tool arguments for the target tool schema. */\n\targs: unknown;\n\t/** Current agent context at the time the tool call is prepared. */\n\tcontext: AgentContext;\n}\n\n/** Context passed to `afterToolCall`. */\nexport interface AfterToolCallContext {\n\t/** The assistant message that requested the tool call. */\n\tassistantMessage: AssistantMessage;\n\t/** The raw tool call block from `assistantMessage.content`. */\n\ttoolCall: AgentToolCall;\n\t/** Validated tool arguments for the target tool schema. */\n\targs: unknown;\n\t/** The executed tool result before any `afterToolCall` overrides are applied. */\n\tresult: AgentToolResult<any>;\n\t/** Whether the executed tool result is currently treated as an error. */\n\tisError: boolean;\n\t/** Current agent context at the time the tool call is finalized. */\n\tcontext: AgentContext;\n}\n\n/**\n * Configuration for the agent loop.\n */\nexport interface AgentLoopConfig extends SimpleStreamOptions {\n\tmodel: Model<any>;\n\n\t/**\n\t * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.\n\t *\n\t * Each AgentMessage must be converted to a UserMessage, AssistantMessage, or ToolResultMessage\n\t * that the LLM can understand. AgentMessages that cannot be converted (e.g., UI-only notifications,\n\t * status messages) should be filtered out.\n\t *\n\t * @example\n\t * ```typescript\n\t * convertToLlm: (messages) => messages.flatMap(m => {\n\t *   if (m.role === \"custom\") {\n\t *     // Convert custom message to user message\n\t *     return [{ role: \"user\", content: m.content, timestamp: m.timestamp }];\n\t *   }\n\t *   if (m.role === \"notification\") {\n\t *     // Filter out UI-only messages\n\t *     return [];\n\t *   }\n\t *   // Pass through standard LLM messages\n\t *   return [m];\n\t * })\n\t * ```\n\t */\n\tconvertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;\n\n\t/**\n\t * Optional transform applied to the context before `convertToLlm`.\n\t *\n\t * Use this for operations that work at the AgentMessage level:\n\t * - Context window management (pruning old messages)\n\t * - Injecting context from external sources\n\t *\n\t * @example\n\t * ```typescript\n\t * transformContext: async (messages) => {\n\t *   if (estimateTokens(messages) > MAX_TOKENS) {\n\t *     return pruneOldMessages(messages);\n\t *   }\n\t *   return messages;\n\t * }\n\t * ```\n\t */\n\ttransformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;\n\n\t/**\n\t * Optional final tool filter applied immediately before each provider call.\n\t *\n\t * Use this for runtime policy that depends on the fully active tool set.\n\t * The returned list is what token audit and the provider request both see.\n\t * Receives the post-transform AgentMessage context so policy can scope\n\t * request-local custom messages without inspecting provider payload text.\n\t */\n\tfilterTools?: (\n\t\ttools: AgentTool<any>[],\n\t\tsignal?: AbortSignal,\n\t\tmessages?: AgentMessage[],\n\t) => AgentTool<any>[] | Promise<AgentTool<any>[]>;\n\n\t/**\n\t * Resolves an API key dynamically for each LLM call.\n\t *\n\t * Useful for short-lived OAuth tokens (e.g., GitHub Copilot) that may expire\n\t * during long-running tool execution phases.\n\t */\n\tgetApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;\n\n\t/**\n\t * Returns steering messages to inject into the conversation mid-run.\n\t *\n\t * Called after each tool execution to check for user interruptions.\n\t * If messages are returned, remaining tool calls are skipped and\n\t * these messages are added to the context before the next LLM call.\n\t *\n\t * Use this for \"steering\" the agent while it's working.\n\t */\n\tgetSteeringMessages?: () => Promise<AgentMessage[]>;\n\n\t/**\n\t * Returns follow-up messages to process after the agent would otherwise stop.\n\t *\n\t * Called when the agent has no more tool calls and no steering messages.\n\t * If messages are returned, they're added to the context and the agent\n\t * continues with another turn.\n\t *\n\t * Use this for follow-up messages that should wait until the agent finishes.\n\t */\n\tgetFollowUpMessages?: () => Promise<AgentMessage[]>;\n\n\t/**\n\t * Tool execution mode.\n\t * - \"sequential\": execute tool calls one by one\n\t * - \"parallel\": preflight tool calls sequentially, then execute allowed tools concurrently\n\t *\n\t * Default: \"parallel\"\n\t */\n\ttoolExecution?: ToolExecutionMode;\n\n\t/**\n\t * Called before a tool is executed, after arguments have been validated.\n\t *\n\t * Return `{ block: true }` to prevent execution. The loop emits an error tool result instead.\n\t * The hook receives the agent abort signal and is responsible for honoring it.\n\t */\n\tbeforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;\n\n\t/**\n\t * Called after a tool finishes executing, before final tool events are emitted.\n\t *\n\t * Return an `AfterToolCallResult` to override parts of the executed tool result:\n\t * - `content` replaces the full content array\n\t * - `details` replaces the full details payload\n\t * - `isError` replaces the error flag\n\t *\n\t * Any omitted fields keep their original values. No deep merge is performed.\n\t * The hook receives the agent abort signal and is responsible for honoring it.\n\t */\n\tafterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;\n\n\t/**\n\t * When true, tool calls in assistant messages are rendered in the TUI\n\t * but NOT executed locally. Used for providers that handle tool execution\n\t * internally (e.g., Claude Code CLI via Agent SDK).\n\t *\n\t * The agent loop emits tool_execution_start/end events for TUI rendering\n\t * but skips tool.execute() and does not add tool results to context.\n\t */\n\texternalToolExecution?: boolean;\n\n\t/**\n\t * Called when the agent is about to retry after a recoverable provider error.\n\t *\n\t * Fires after each transient failure (rate limit, connection reset, etc.)\n\t * before the retry backoff sleep. Useful for surfacing retry telemetry to\n\t * the host app without instrumenting the provider layer directly.\n\t */\n\tonRetry?: (context: RetryContext, signal?: AbortSignal) => Promise<void> | void;\n\n\t/**\n\t * Called when the LLM stream fails mid-response.\n\t *\n\t * Fires once per failed stream — `onRetry` may still fire separately if the\n\t * loop elects to retry. Use this for logging or flushing partial state.\n\t */\n\tonStreamError?: (context: StreamErrorContext, signal?: AbortSignal) => Promise<void> | void;\n}\n\n/** Context passed to `onRetry`. */\nexport interface RetryContext {\n\tattempt: number;\n\tmaxRetries: number;\n\tdelayMs: number;\n\terror: Error;\n}\n\n/** Context passed to `onStreamError`. */\nexport interface StreamErrorContext {\n\terror: Error;\n\t/** The text already emitted by the stream before it failed (may be empty). */\n\tpartialText: string;\n\t/** Whether the loop will attempt to retry after this failure. */\n\twillRetry: boolean;\n}\n\n/**\n * Thinking/reasoning level for models that support it.\n * Note: \"xhigh\" is only supported by OpenAI gpt-5.1-codex-max, gpt-5.2, gpt-5.2-codex, gpt-5.3, and gpt-5.3-codex models.\n */\nexport type ThinkingLevel = \"off\" | \"minimal\" | \"low\" | \"medium\" | \"high\" | \"xhigh\";\n\n/**\n * Extensible interface for custom app messages.\n * Apps can extend via declaration merging:\n *\n * @example\n * ```typescript\n * declare module \"@mariozechner/agent\" {\n *   interface CustomAgentMessages {\n *     artifact: ArtifactMessage;\n *     notification: NotificationMessage;\n *   }\n * }\n * ```\n */\nexport interface CustomAgentMessages {\n\t// Empty by default - apps extend via declaration merging\n}\n\n/**\n * AgentMessage: Union of LLM messages + custom messages.\n * This abstraction allows apps to add custom message types while maintaining\n * type safety and compatibility with the base LLM messages.\n */\nexport type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];\n\n/**\n * Agent state containing all configuration and conversation data.\n */\nexport interface AgentState {\n\tsystemPrompt: string;\n\tmodel: Model<any>;\n\tthinkingLevel: ThinkingLevel;\n\ttools: AgentTool<any>[];\n\tmessages: AgentMessage[]; // Can include attachments + custom message types\n\tisStreaming: boolean;\n\tstreamMessage: AgentMessage | null;\n\tpendingToolCalls: Set<string>;\n\terror?: string;\n\t/**\n\t * The model currently being used for inference. Set at _runLoop() start,\n\t * cleared when the loop ends. When present, UI should display this instead\n\t * of `model` to avoid showing a stale value after a mid-turn model switch.\n\t */\n\tactiveInferenceModel?: Model<any>;\n}\n\nexport interface AgentToolResult<T> {\n\t// Content blocks supporting text and images\n\tcontent: (TextContent | ImageContent)[];\n\t// Details to be displayed in a UI or logged\n\tdetails: T;\n}\n\n// Callback for streaming tool execution updates\nexport type AgentToolUpdateCallback<T = any> = (partialResult: AgentToolResult<T>) => void;\n\n// AgentTool extends Tool but adds the execute function\nexport interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any> extends Tool<TParameters> {\n\t// A human-readable label for the tool to be displayed in UI\n\tlabel: string;\n\texecute: (\n\t\ttoolCallId: string,\n\t\tparams: Static<TParameters>,\n\t\tsignal?: AbortSignal,\n\t\tonUpdate?: AgentToolUpdateCallback<TDetails>,\n\t) => Promise<AgentToolResult<TDetails>>;\n}\n\n// AgentContext is like Context but uses AgentTool\nexport interface AgentContext {\n\tsystemPrompt: string;\n\tmessages: AgentMessage[];\n\ttools?: AgentTool<any>[];\n}\n\n/**\n * Events emitted by the Agent for UI updates.\n * These events provide fine-grained lifecycle information for messages, turns, and tool executions.\n */\nexport type AgentEvent =\n\t// Agent lifecycle\n\t| { type: \"agent_start\" }\n\t| { type: \"agent_end\"; messages: AgentMessage[] }\n\t// Turn lifecycle - a turn is one assistant response + any tool calls/results\n\t| { type: \"turn_start\" }\n\t| { type: \"turn_end\"; message: AgentMessage; toolResults: ToolResultMessage[] }\n\t// Message lifecycle - emitted for user, assistant, and toolResult messages\n\t| { type: \"message_start\"; message: AgentMessage }\n\t// Only emitted for assistant messages during streaming\n\t| { type: \"message_update\"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }\n\t| { type: \"message_end\"; message: AgentMessage }\n\t// Tool execution lifecycle\n\t| { type: \"tool_execution_start\"; toolCallId: string; toolName: string; args: any }\n\t| { type: \"tool_execution_update\"; toolCallId: string; toolName: string; args: any; partialResult: any }\n\t| { type: \"tool_execution_end\"; toolCallId: string; toolName: string; result: any; isError: boolean };\n"]}

package/packages/pi-agent-core/src/agent-loop.test.ts

@@ -10,6 +10,134 @@ import { AssistantMessageEventStream, EventStream } from "@gsd/pi-ai";
 import type { AssistantMessage, AssistantMessageEvent, Model } from "@gsd/pi-ai";
 
 describe("agent-loop — pauseTurn handling (#2869)", () => {
+	it("emits token audit after context transforms when opted in", async () => {
+		const finalStop = makeAssistantMessage({
+			content: [{ type: "text", text: "Done." }],
+			stopReason: "stop",
+		});
+		const original = process.env.PI_TOKEN_AUDIT;
+		const originalWrite = process.stderr.write;
+		let written = "";
+		process.env.PI_TOKEN_AUDIT = "1";
+		process.stderr.write = ((chunk: string | Uint8Array) => {
+			written += chunk.toString();
+			return true;
+		}) as typeof process.stderr.write;
+
+		try {
+			let filteredMessages: AgentMessage[] | undefined;
+			const streamFn = (_model: Model<any>, llmContext: any): AssistantMessageEventStream => {
+				assert.equal(llmContext.messages.length, 1, "audit boundary must use transformed context");
+				assert.equal(llmContext.messages[0].content[0].text, "transformed");
+				const stream = new AssistantMessageEventStream();
+				queueMicrotask(() => {
+					stream.push({ type: "start", partial: finalStop });
+					stream.push({ type: "done", message: finalStop });
+					stream.end(finalStop);
+				});
+				return stream;
+			};
+			const context: AgentContext = {
+				systemPrompt: "sensitive system",
+				messages: [{ role: "user", content: [{ type: "text", text: "original" }], timestamp: Date.now() }],
+				tools: [],
+			};
+			const config: AgentLoopConfig = {
+				model: TEST_MODEL,
+				transformContext: async () => [
+					{ role: "user", content: [{ type: "text", text: "transformed" }], timestamp: Date.now() },
+				],
+				convertToLlm: (msgs) => msgs.filter((m): m is any => m.role !== "custom"),
+				filterTools: (tools, _signal, messages) => {
+					filteredMessages = messages;
+					return tools;
+				},
+				toolExecution: "sequential",
+			};
+
+			const stream = agentLoop(
+				[{ role: "user", content: [{ type: "text", text: "new prompt" }], timestamp: Date.now() }],
+				context,
+				config,
+				undefined,
+				streamFn as any,
+			);
+			await collectEvents(stream);
+
+			assert.match(written, /"type":"token_audit"/);
+			assert.match(written, /"messageCount":1/);
+			assert.equal((filteredMessages?.[0] as any)?.content?.[0]?.text, "transformed");
+			assert.doesNotMatch(written, /transformed|original|new prompt|sensitive system/);
+		} finally {
+			process.stderr.write = originalWrite;
+			if (original === undefined) delete process.env.PI_TOKEN_AUDIT;
+			else process.env.PI_TOKEN_AUDIT = original;
+		}
+	});
+
+	it("applies final tool filtering before token audit and provider streaming", async () => {
+		const finalStop = makeAssistantMessage({
+			content: [{ type: "text", text: "Done." }],
+			stopReason: "stop",
+		});
+		const original = process.env.PI_TOKEN_AUDIT;
+		const originalWrite = process.stderr.write;
+		let written = "";
+		process.env.PI_TOKEN_AUDIT = "1";
+		process.stderr.write = ((chunk: string | Uint8Array) => {
+			written += chunk.toString();
+			return true;
+		}) as typeof process.stderr.write;
+
+		try {
+			const streamFn = (_model: Model<any>, llmContext: any): AssistantMessageEventStream => {
+				assert.deepEqual(llmContext.tools?.map((tool: AgentTool) => tool.name), ["write_file"]);
+				const stream = new AssistantMessageEventStream();
+				queueMicrotask(() => {
+					stream.push({ type: "start", partial: finalStop });
+					stream.push({ type: "done", message: finalStop });
+					stream.end(finalStop);
+				});
+				return stream;
+			};
+			const context: AgentContext = {
+				systemPrompt: "You are a test agent.",
+				messages: [{ role: "user", content: [{ type: "text", text: "Use a tool" }], timestamp: Date.now() }],
+				tools: [
+					makeToolWithSchema(),
+					{
+						...makeToolWithSchema(),
+						name: "drop_tool",
+						label: "Drop Tool",
+					},
+				],
+			};
+			const config: AgentLoopConfig = {
+				model: TEST_MODEL,
+				convertToLlm: (msgs) => msgs.filter((m): m is any => m.role !== "custom"),
+				filterTools: async (tools) => tools.filter((tool) => tool.name === "write_file"),
+				toolExecution: "sequential",
+			};
+
+			const stream = agentLoop(
+				[{ role: "user", content: [{ type: "text", text: "Use a tool" }], timestamp: Date.now() }],
+				context,
+				config,
+				undefined,
+				streamFn as any,
+			);
+			await collectEvents(stream);
+
+			assert.match(written, /"toolCount":1/);
+			assert.match(written, /"name":"write_file"/);
+			assert.doesNotMatch(written, /drop_tool/);
+		} finally {
+			process.stderr.write = originalWrite;
+			if (original === undefined) delete process.env.PI_TOKEN_AUDIT;
+			else process.env.PI_TOKEN_AUDIT = original;
+		}
+	});
+
 	it("continues to a second assistant turn when stopReason is pauseTurn", async () => {
 		const pauseTurn = makeAssistantMessage({
 			content: [{ type: "text", text: "Still working..." }],

package/packages/pi-agent-core/src/agent-loop.ts

@@ -21,6 +21,7 @@ import type {
 	AgentToolResult,
 	StreamFn,
 } from "./types.js";
+import { maybeLogTokenAudit } from "./token-audit.js";
 
 /**
  * Maximum number of consecutive turns where ALL tool calls in the turn fail
@@ -416,13 +417,15 @@ async function streamAssistantResponse(
 
 	// Convert to LLM-compatible messages (AgentMessage[] → Message[])
 	const llmMessages = await config.convertToLlm(messages);
+	const tools = config.filterTools ? await config.filterTools(context.tools ?? [], signal, messages) : context.tools;
 
 	// Build LLM context
 	const llmContext: Context = {
 		systemPrompt: context.systemPrompt,
 		messages: llmMessages,
-		tools: context.tools,
+		tools,
 	};
+	maybeLogTokenAudit(llmContext, messages);
 
 	const streamFunction = streamFn || streamSimple;
 

package/packages/pi-agent-core/src/agent.ts

@@ -52,6 +52,11 @@ export interface AgentOptions {
 	 */
 	transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
 
+	/**
+	 * Optional final tool filter applied immediately before each provider call.
+	 */
+	filterTools?: AgentLoopConfig["filterTools"];
+
 	/**
 	 * Steering mode: "all" = send all steering messages at once, "one-at-a-time" = one per turn
 	 */
@@ -144,6 +149,7 @@ export class Agent {
 	private abortController?: AbortController;
 	private convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
 	private transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+	private filterTools?: AgentLoopConfig["filterTools"];
 	private steeringQueue: QueueEntry[] = [];
 	private followUpQueue: QueueEntry[] = [];
 	private steeringMode: "all" | "one-at-a-time";
@@ -166,6 +172,7 @@ export class Agent {
 		this._state = { ...this._state, ...opts.initialState };
 		this.convertToLlm = opts.convertToLlm || defaultConvertToLlm;
 		this.transformContext = opts.transformContext;
+		this.filterTools = opts.filterTools;
 		this.steeringMode = opts.steeringMode || "one-at-a-time";
 		this.followUpMode = opts.followUpMode || "one-at-a-time";
 		this.streamFn = opts.streamFn || streamSimple;
@@ -509,6 +516,7 @@ export class Agent {
 			maxRetryDelayMs: this._maxRetryDelayMs,
 			convertToLlm: this.convertToLlm,
 			transformContext: this.transformContext,
+			filterTools: this.filterTools,
 			getApiKey: this.getApiKey,
 			getSteeringMessages: async () => {
 				if (skipInitialSteeringPoll) {

package/packages/pi-agent-core/src/index.ts

@@ -4,5 +4,7 @@ export * from "./agent.js";
 export * from "./agent-loop.js";
 // Proxy utilities
 export * from "./proxy.js";
+// Token audit utilities
+export * from "./token-audit.js";
 // Types
 export * from "./types.js";

package/packages/pi-agent-core/src/token-audit.test.ts

@@ -0,0 +1,189 @@
+// Project/App: GSD-2
+// File Purpose: Tests for provider-boundary token payload audit helpers.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Type } from "@sinclair/typebox";
+import type { Context } from "@gsd/pi-ai";
+import type { AgentMessage } from "./types.js";
+import {
+	buildProviderPayloadAuditSummary,
+	buildTokenAuditSummary,
+	maybeLogProviderPayloadAudit,
+	maybeLogTokenAudit,
+} from "./token-audit.js";
+
+test("buildTokenAuditSummary reports payload section sizes without content fields", () => {
+	const context: Context = {
+		systemPrompt: "system prompt",
+		tools: [
+			{
+				name: "read",
+				description: "Read a file",
+				parameters: Type.Object({ path: Type.String() }),
+			},
+			{
+				name: "large_tool",
+				description: "Large schema".repeat(20),
+				parameters: Type.Object({ value: Type.String() }),
+			},
+		],
+		messages: [
+			{ role: "user", content: [{ type: "text", text: "hello" }], timestamp: 1 },
+			{
+				role: "toolResult",
+				toolCallId: "call-1",
+				toolName: "read",
+				content: [{ type: "text", text: "tool output" }],
+				isError: false,
+				timestamp: 2,
+			},
+			{ role: "user", content: [{ type: "image", data: "abc123", mimeType: "image/png" }], timestamp: 3 },
+		],
+	};
+	const sourceMessages = [
+		...context.messages,
+		{
+			role: "custom",
+			customType: "gsd-memory",
+			content: "memory block",
+			display: false,
+			timestamp: 4,
+		} as AgentMessage,
+	];
+
+	const summary = buildTokenAuditSummary(context, sourceMessages);
+
+	assert.equal(summary.systemChars, "system prompt".length);
+	assert.equal(summary.toolCount, 2);
+	assert.equal(summary.messageCount, 3);
+	assert.equal(summary.toolResultChars, "tool output".length);
+	assert.equal(summary.imageCount, 1);
+	assert.ok(summary.toolSchemaChars > 0);
+	assert.ok(summary.customMessageChars > 0);
+	assert.ok(summary.estimatedInputTokens > 0);
+	assert.deepEqual(
+		summary.largestMessages.map((message) => Object.keys(message).sort()),
+		summary.largestMessages.map(() => ["chars", "index", "role", "type"]),
+	);
+	assert.equal(summary.largestTools[0].name, "large_tool");
+	assert.deepEqual(
+		summary.largestTools.map((tool) => Object.keys(tool).sort()),
+		summary.largestTools.map(() => ["chars", "name"]),
+	);
+	assert.deepEqual(summary.largestCustomMessages, [
+		{ index: 3, role: "custom", customType: "gsd-memory", chars: summary.largestCustomMessages[0].chars },
+	]);
+	assert.ok(!JSON.stringify(summary).includes("tool output"));
+	assert.ok(!JSON.stringify(summary).includes("memory block"));
+});
+
+test("maybeLogTokenAudit is opt-in and emits metadata only", () => {
+	const original = process.env.PI_TOKEN_AUDIT;
+	const originalWrite = process.stderr.write;
+	let written = "";
+	process.stderr.write = ((chunk: string | Uint8Array) => {
+		written += chunk.toString();
+		return true;
+	}) as typeof process.stderr.write;
+
+	try {
+		delete process.env.PI_TOKEN_AUDIT;
+		maybeLogTokenAudit({ messages: [{ role: "user", content: "secret prompt", timestamp: 1 }] }, []);
+		assert.equal(written, "");
+
+		process.env.PI_TOKEN_AUDIT = "1";
+		maybeLogTokenAudit({ systemPrompt: "hidden system", messages: [{ role: "user", content: "secret prompt", timestamp: 1 }] }, []);
+		assert.match(written, /"type":"token_audit"/);
+		assert.doesNotMatch(written, /secret prompt/);
+		assert.doesNotMatch(written, /hidden system/);
+	} finally {
+		process.stderr.write = originalWrite;
+		if (original === undefined) delete process.env.PI_TOKEN_AUDIT;
+		else process.env.PI_TOKEN_AUDIT = original;
+	}
+});
+
+test("provider payload audit summarizes post-hook payload without raw content", () => {
+	const payload = {
+		system: "secret system content",
+		tools: [{
+			type: "function",
+			function: {
+				name: "read",
+				description: "secret tool description",
+				parameters: { type: "object" },
+			},
+		}],
+		messages: [
+			{ role: "user", content: "secret user content" },
+			{ role: "assistant", content: [{ type: "text", text: "secret assistant content" }] },
+		],
+	};
+
+	const summary = buildProviderPayloadAuditSummary(payload);
+
+	assert.equal(summary.messageCount, 2);
+	assert.equal(summary.toolCount, 1);
+	assert.ok(summary.payloadChars > 0);
+	assert.ok(summary.toolSchemaChars > 0);
+	assert.deepEqual(summary.largestTools.map((tool) => tool.name), ["read"]);
+	assert.equal(JSON.stringify(summary).includes("secret"), false);
+});
+
+test("provider payload audit recognizes Gemini and Bedrock payload shapes", () => {
+	const gemini = buildProviderPayloadAuditSummary({
+		contents: [{ role: "user", parts: [{ text: "hidden gemini prompt" }] }],
+		config: {
+			tools: [{
+				functionDeclarations: [
+					{ name: "gsd_exec", description: "hidden declaration", parameters: { type: "object" } },
+				],
+			}],
+		},
+	});
+	const bedrock = buildProviderPayloadAuditSummary({
+		messages: [{ role: "user", content: [{ text: "hidden bedrock prompt" }] }],
+		toolConfig: {
+			tools: [
+				{ toolSpec: { name: "gsd_resume", description: "hidden tool", inputSchema: { json: {} } } },
+			],
+		},
+	});
+
+	assert.equal(gemini.messageCount, 1);
+	assert.equal(gemini.toolCount, 1);
+	assert.deepEqual(gemini.largestTools.map((tool) => tool.name), ["gsd_exec"]);
+	assert.equal(JSON.stringify(gemini).includes("hidden"), false);
+
+	assert.equal(bedrock.messageCount, 1);
+	assert.equal(bedrock.toolCount, 1);
+	assert.deepEqual(bedrock.largestTools.map((tool) => tool.name), ["gsd_resume"]);
+	assert.equal(JSON.stringify(bedrock).includes("hidden"), false);
+});
+
+test("provider payload audit logging is metadata-only", () => {
+	const original = process.env.PI_TOKEN_AUDIT;
+	const originalWrite = process.stderr.write;
+	let written = "";
+	process.env.PI_TOKEN_AUDIT = "1";
+	process.stderr.write = ((chunk: string | Uint8Array) => {
+		written += chunk.toString();
+		return true;
+	}) as typeof process.stderr.write;
+
+	try {
+		maybeLogProviderPayloadAudit({
+			messages: [{ role: "user", content: "raw prompt text must not log" }],
+			tools: [{ name: "bash", description: "raw tool description must not log" }],
+		}, "after");
+		assert.match(written, /"type":"token_audit_provider_payload"/);
+		assert.match(written, /"phase":"after"/);
+		assert.doesNotMatch(written, /raw prompt text/);
+		assert.doesNotMatch(written, /raw tool description/);
+	} finally {
+		process.stderr.write = originalWrite;
+		if (original === undefined) delete process.env.PI_TOKEN_AUDIT;
+		else process.env.PI_TOKEN_AUDIT = original;
+	}
+});