@theoremjs/studio 0.3.4-next.693.g4ab1526 → 0.3.4-next.715.geef22fd

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/agreement.js +35 -5
  2. package/compile.d.ts +3 -3
  3. package/compile.js +43 -20
  4. package/cookbooks/catalog.js +8 -10
  5. package/draft.d.ts +12 -9
  6. package/draft.js +4 -4
  7. package/mod.d.ts +1 -2
  8. package/mod.js +1 -2
  9. package/package.json +4 -4
  10. package/page/assets/Banner-CrhjYjDy.js +3 -0
  11. package/page/assets/{ConsoleFrame-BvgFGqp2.js → ConsoleFrame-dOTqIkpb.js} +1 -1
  12. package/page/assets/{MenuBottomSheet-BZecY8fw.js → MenuBottomSheet-DeuZCVb-.js} +1 -1
  13. package/page/assets/{SchemaFields-BNNkvyyO.js → SchemaFields-DeuNDrvj.js} +1 -1
  14. package/page/assets/{ToolResultCharts-C3CPsfXl.js → ToolResultCharts-B-pokquL.js} +1 -1
  15. package/page/assets/{TraceInspector-36e6ozKD.js → TraceInspector-CvJ0wx9n.js} +1 -1
  16. package/page/assets/{TraceOverview-CSdJ_cYY.js → TraceOverview-cIjJwpvK.js} +1 -1
  17. package/page/assets/{_virtual_studio-type-sources-DSpwr3WK.js → _virtual_studio-type-sources-BxnDf9BC.js} +225 -85
  18. package/page/assets/browser-connection-CuWeoI9s.js +3 -0
  19. package/page/assets/browser-engine-C3SeJyrA.js +13 -0
  20. package/page/assets/{browser-transport-GzhRiBdm.js → browser-transport-DKhZ4zo1.js} +3 -3
  21. package/page/assets/{crypto-B8dqEoWf.js → crypto-BnoW7FFO.js} +1 -1
  22. package/page/assets/{encode-files-CHeRLBO8.js → encode-files-DoLGXgup.js} +1 -1
  23. package/page/assets/{export-agent-botXSyoH.js → export-agent-CO4lAMum.js} +1 -1
  24. package/page/assets/{guardrail-tester-DYR7EPIy.js → guardrail-tester-Slctc2oI.js} +1 -1
  25. package/page/assets/{index-B7sK7d-l.js → index-CAK9cdCh.js} +72 -76
  26. package/page/assets/{labels-provider-t4c-5JMk.js → labels-provider-uONlWExD.js} +1 -1
  27. package/page/assets/{live-messages-DN_q2nBN.js → live-messages-M0vS3YB0.js} +1 -1
  28. package/page/assets/people-CIsR0-5R.js +1 -0
  29. package/page/assets/reader-747-Cvu8.js +5 -0
  30. package/page/assets/{shaped-data-CJQ3W_RE.js → shaped-data-7q5Be8sp.js} +3 -3
  31. package/page/assets/{stub-U6wDGe3P.js → stub--LOYiyQO.js} +1 -1
  32. package/page/assets/studio-code-pane-CuccT4Ur.js +10 -0
  33. package/page/assets/{studio-console-B7zL133d.js → studio-console-DwxLzV9_.js} +1 -1
  34. package/page/assets/{studio-decision-CbRjfbvG.js → studio-decision-w6OjVUM3.js} +1 -1
  35. package/page/assets/{studio-embedding-DQ0QrEsu.js → studio-embedding-CxFoTvOd.js} +1 -1
  36. package/page/assets/studio-host-console-BhQSkUhA.js +2 -0
  37. package/page/assets/{studio-labels-jYWBoEyP.js → studio-labels-q6eBFSru.js} +1 -1
  38. package/page/assets/{studio-live-D0YRu2zQ.js → studio-live-D5NjMEky.js} +1 -1
  39. package/page/assets/{studio-map-C4Ra1QqL.js → studio-map-DlkGoGam.js} +1 -1
  40. package/page/assets/studio-session-ClF2iNCX.js +1 -0
  41. package/page/assets/{studio-trace-replay-D-f2p7k9.js → studio-trace-replay-Ccv4ToIz.js} +1 -1
  42. package/page/assets/{studio-type-checker-CVNPnko-.js → studio-type-checker-Dm2eit0p.js} +1 -1
  43. package/page/assets/{tool-schema-BDG2_rlP.js → tool-schema-6RWBAqGO.js} +2 -2
  44. package/page/assets/{trace-record-DoXjxrmJ.js → trace-record-Dm2jEhUR.js} +1 -1
  45. package/page/assets/tree-DcCW259J.js +3 -0
  46. package/page/assets/turn-client-OLK12Fyi.js +2 -0
  47. package/page/assets/{use-one-call-B3t-kfc5.js → use-one-call-CLndFp2X.js} +1 -1
  48. package/page/assets/use-second-ticker-D6JSf9B3.js +1 -0
  49. package/page/assets/{workspace-DUfaxr-g.js → workspace-DSAX72vF.js} +1 -1
  50. package/page/index.html +18 -17
  51. package/read-source.js +41 -8
  52. package/registrations.d.ts +9 -1
  53. package/runtime.js +1 -0
  54. package/section-notes.d.ts +1 -0
  55. package/section-notes.js +1 -0
  56. package/serve-page.mjs +8 -4
  57. package/server/handler.d.ts +0 -3
  58. package/server/handler.js +4 -26
  59. package/server/live.d.ts +1 -2
  60. package/server/live.js +3 -4
  61. package/server/save-plan.js +2 -1
  62. package/system-markup.d.ts +9 -7
  63. package/system-markup.js +38 -19
  64. package/tools.js +1 -0
  65. package/types.d.ts +3 -0
  66. package/ui/inspector-context.d.ts +1 -8
  67. package/ui/inspector-context.js +0 -7
  68. package/ui/inspector.d.ts +43 -1
  69. package/ui/inspector.js +50 -9
  70. package/ui/lib/entries.d.ts +13 -0
  71. package/ui/lib/entries.js +43 -0
  72. package/ui/lib/project-traces.js +2 -10
  73. package/ui/lib/studio-prefs.d.ts +0 -4
  74. package/ui/lib/studio-prefs.js +0 -7
  75. package/ui/lib/studio-project.d.ts +2 -5
  76. package/ui/lib/studio-project.js +1 -4
  77. package/ui/profile-editor.js +37 -49
  78. package/ui/studio-screen.d.ts +0 -1
  79. package/ui/studio-screen.js +8 -18
  80. package/ui/studio-settings.js +1 -12
  81. package/asks.d.ts +0 -61
  82. package/asks.js +0 -78
  83. package/page/assets/Banner-DrRNC3MG.js +0 -4
  84. package/page/assets/browser-connection-dads1eyK.js +0 -3
  85. package/page/assets/browser-engine-CugH58NS.js +0 -13
  86. package/page/assets/reader-DHN96tSr.js +0 -5
  87. package/page/assets/studio-code-pane-Boy63AK2.js +0 -8
  88. package/page/assets/studio-host-console-DDA2Um2-.js +0 -2
  89. package/page/assets/studio-session-CPnJaHc-.js +0 -1
  90. package/page/assets/tree-CcEbNvms.js +0 -3
  91. package/page/assets/turn-client-BmOSpCgw.js +0 -2
  92. package/page/assets/use-second-ticker-CWjCHLG6.js +0 -1
  93. package/ui/confirm-write.d.ts +0 -12
  94. package/ui/confirm-write.js +0 -45
@@ -4760,14 +4760,15 @@ export { applyStageResult, STAGE_AFFORDANCE_MATRIX, STAGE_AFFORDANCES, stageAllo
4760
4760
  export type { MediaTurnBehaviourSpec, ProfileTurnBehaviourSpec, ProfileTurnResumptionSpec, TurnContinueFrom, TurnStop, } from './src/kernel/stop.js';
4761
4761
  export { AUTO_CONTINUE_DELAY_MS, DEFAULT_ALLOW_CONTINUE, DEFAULT_AUTO_CONTINUE, GenerationStopError, isContinueStopKind, isGenerationStopError, isResumeableStop, isUserCancelledStop, profileAllowsInject, profileAllowsSteering, profileTurnResumption, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenAiFinishReason, } from './src/kernel/stop.js';
4762
4762
  export { systemLinesProblem } from './src/kernel/system-lines.js';
4763
+ export type { ToolBackground, ToolBackgroundCall, ToolBackgroundHandle, ToolBackgroundService, } from './src/kernel/tools/background.js';
4763
4764
  export { authorizeToolReplay } from './src/kernel/tools/execute.js';
4764
4765
  export { GATE_DECISIONS, type GateDecision } from './src/kernel/tools/gate-answer.js';
4765
4766
  export type { MemoryToolExecutionOptions } from './src/kernel/tools/memory-execution.js';
4766
4767
  export { createMemoryToolExecution } from './src/kernel/tools/memory-execution.js';
4767
4768
  export type { CredentialQuery, McpProtocolVersion, McpRpcResponse, ToolRegistry, } from './src/kernel/tools/mod.js';
4768
4769
  export { askUserTool, buildHttpToolTarget, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, formatToolResult, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, prepareTurnToolSnapshot, registerHarnessTools, resolveToolAuth, UncheckedOutput, uncheckedOutput, withCredentialQuery, } from './src/kernel/tools/mod.js';
4769
- export type { BeginToolOperationResult, PageToolDispatch, PageToolExecution, SavedToolInvocation, TerminalToolEvent, ToolExecutionCoordinator, ToolOperationClaim, ToolOperationIdentity, ToolOperationOutcome, ToolOperationUncertainty, } from './src/kernel/tools/operation.js';
4770
- export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, } from './src/kernel/tools/operation.js';
4770
+ export type { BackgroundToolEvent, BeginToolOperationResult, PageToolDispatch, PageToolExecution, SavedToolInvocation, TerminalToolEvent, ToolExecutionCoordinator, ToolOperationClaim, ToolOperationIdentity, ToolOperationOutcome, ToolOperationReply, ToolOperationUncertainty, } from './src/kernel/tools/operation.js';
4771
+ export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, toolOperationReplySchema, } from './src/kernel/tools/operation.js';
4771
4772
  export type { SettledToolCall, ToolCallResult, ToolStepCallResult, } from './src/kernel/tools/run.js';
4772
4773
  export type { ModelToolResult, PageAnswer, ToolContext } from './src/kernel/tools/types.js';
4773
4774
  export { awaitingUserInputSchema, type GateReference, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './src/kernel/turn-events.js';
@@ -5217,6 +5218,7 @@ export declare const providerLimitsSchema: z.ZodType<ProviderLimits>;
5217
5218
  import type { JsonObject } from './json.js';
5218
5219
  import type { CacheMode, CacheTtl, CompactionMeter, CompactionOutcome, CompactionTiming, ContextSender, ContinueStopKind, FieldMeta, KeySlot, KeyVault, LiveActivityHandling, LiveEndSensitivity, LiveStartSensitivity, MediaInputKind, ProfileType, SpeechAudioFormat, StreamMode, SummaryMode, ThinkingLevel, ToolLoadTier, TurnStage, TurnStopKind } from './schema.js';
5219
5220
  import type { StageHandler } from './stages.js';
5221
+ import type { ToolBackgroundService } from './tools/background.js';
5220
5222
  import type { GateDecision } from './tools/gate-answer.js';
5221
5223
  import type { PageToolExecution, ToolExecutionCoordinator } from './tools/operation.js';
5222
5224
  import type { AgentCall, AgentCallHook, AgentCallRequest, AgentToolDef, AgentToolInput, AgentToolOutput, HostProfileToolsSpec, InvokeToolRequest, InvokeToolResume, InvokeToolStepCall, InvokeToolStepRequest, LiveProfileToolsSpec, ModelToolResult, PageAnswer, ProfileToolsSpec, RegisteredTool, ToolCallEvent, ToolFailure, ToolGate, ToolLoadContext, ToolPolicy, TurnToolSnapshot, WireFunctionTool } from './tools/types.js';
@@ -5974,6 +5976,7 @@ export interface TurnTraceLink {
5974
5976
  /** A request to \`runTurn\`: the profile, the input, and the host's hooks and keys. */
5975
5977
  export interface TurnRequest {
5976
5978
  execution?: ToolExecutionCoordinator;
5979
+ background?: ToolBackgroundService;
5977
5980
  pageExecution?: PageToolExecution;
5978
5981
  providerState?: ProviderCheckpoint;
5979
5982
  profile: ProfileId;
@@ -6035,6 +6038,17 @@ export interface TurnRequest {
6035
6038
  * Compared to \`profile.turnBehaviour.resumption.maxContinues\` when that cap is set.
6036
6039
  */
6037
6040
  continuation?: number;
6041
+ /**
6042
+ * Tools this reply already had when an earlier run of it paused. The turn opens with them on its
6043
+ * list, so an answered call does not take back what the model loaded. An id \`tools.allow\` or the
6044
+ * path does not grant is left out, as for \`tools.t1Policy\`.
6045
+ */
6046
+ promoted?: ToolId[];
6047
+ /**
6048
+ * Steps this reply already took when an earlier run of it paused. They count against \`maxSteps\`,
6049
+ * so an answered call does not give the reply its steps back. Read \`done.steps\`.
6050
+ */
6051
+ stepsTaken?: number;
6038
6052
  input?: TurnInput;
6039
6053
  /** Credentials for authenticated HTTP / MCP tools, read by auth slot when a tool needs one. */
6040
6054
  credentials?: ToolCredentialSource;
@@ -6796,6 +6810,8 @@ export interface TurnToolSnapshot {
6796
6810
  path?: string;
6797
6811
  sessionPermissions?: string[];
6798
6812
  wire: WireFunctionTool[];
6813
+ /** The request has a background service, so \`ask\` tools offer the \`background\` argument. */
6814
+ modelBackground?: boolean;
6799
6815
  }
6800
6816
  /** The schema a tool snapshot parses against. */
6801
6817
  export declare const turnToolSnapshotSchema: z.ZodType<TurnToolSnapshot>;
@@ -6901,12 +6917,17 @@ export type ToolPhaseEvent = ToolPhaseBase & ({
6901
6917
  readBack?: string;
6902
6918
  parts?: InteractionPart[];
6903
6919
  activityPast?: string;
6904
- /** An agent tool's call: the called agent's own usage, which the caller's \`done.tokens\` includes. */
6920
+ /** An agent tool's call: the called agent's own usage. The caller's \`done.tokens\` includes it, unless the call settled after \`done\`. */
6905
6921
  tokens?: TurnTokens;
6906
6922
  } | {
6907
6923
  phase: 'gate';
6908
6924
  gate: ToolGate;
6909
6925
  readBack?: string;
6926
+ }
6927
+ /** The model reads \`readBack\` now and the call goes on; its real end reaches the host alone. */
6928
+ | {
6929
+ phase: 'background';
6930
+ readBack: string;
6910
6931
  } | {
6911
6932
  phase: 'error';
6912
6933
  failure: ToolFailure;
@@ -6990,6 +7011,8 @@ export interface DoneBase {
6990
7011
  tokens?: TurnTokens;
6991
7012
  /** The turn's root span as a W3C \`traceparent\`, for a later request's \`links\`. */
6992
7013
  traceparent?: string;
7014
+ /** The model calls that count against \`maxSteps\` so far, those of \`stepsTaken\` included. */
7015
+ steps?: number;
6993
7016
  compaction?: CompactionSignal;
6994
7017
  /** A user utterance interrupted an in-flight live response (barge-in). */
6995
7018
  interrupted?: boolean;
@@ -7993,7 +8016,7 @@ export { applySpans, blobAt, mergeSpans, OMIT_CANARY, OMIT_INJECTION, OMIT_PROMP
7993
8016
  `,"file:///node_modules/@theoremjs/agents/src/guardrails/labels.d.ts":`/** Values that fill a label template's \`{param}\` placeholders. */
7994
8017
  export type LabelParams = Record<string, string | number>;
7995
8018
  /** Keys are stable API. */
7996
- export declare const LABEL_KEYS: readonly ["provider.decision_failed", "provider.decision_unavailable", "provider.decision_model_missing", "provider.decision_ended", "provider.decision_images_off", "provider.decision_box_model", "provider.budget_exhausted", "provider.adapter_version", "provider.adapter_methods", "provider.adapter_schemas", "provider.fallback_slot", "provider.model_fallback_slot", "provider.host_model", "provider.turn_profile", "provider.model_binding_missing", "provider.session_closed", "provider.settled_call", "provider.session_unavailable", "provider.live_input", "provider.tool_cancel_missing", "provider.kernel_gate", "provider.event_invalid", "provider.response_identity", "provider.credential_resolution", "provider.credential_shape", "provider.stored_continuation", "provider.continuation_mismatch", "provider.continuation_contract", "provider.stateless_history", "provider.events_after_completion", "provider.duplicate_call", "provider.tool_cancel_live", "provider.complete_unavailable", "provider.parallel_tools", "provider.binding_identity", "provider.profile_type", "provider.event_type", "provider.feature", "provider.input_kind", "provider.output_kind", "provider.builtin", "provider.credential_missing", "provider.profile_configuration", "continue.instruction", "canary.bind_note", "user_data.note", "context.note", "taint.blocked", "taint.reason_steered", "taint.reason_tainted", "taint.destination_blocked", "taint.destination_confirm", "advisory.notice_elevated", "advisory.notice_high", "advisory.guidance", "attachments.too_many_files", "attachments.too_many_of_kind", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "attachments.limits_unconfigured", "quota.exhausted", "quota.busy", "error.config", "error.request", "error.conflict", "error.not_found", "error.input", "error.action", "error.auth", "error.rate_limit", "error.busy", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "repair.default_guidance", "repair.items_guidance", "repair.prompt_header", "repair.prompt_intro", "repair.prompt_instructions", "repair.history_heading", "repair.section_previous_output", "repair.section_validator_rejection", "repair.section_repair_guidance", "repair.section_instructions", "structured.answer_tool", "structured.answer_missing", "structured.cut_off", "structured.not_json", "compaction.request", "compaction.tool_call", "compaction.tool_result", "compaction.tool_files", "decision.box_image", "detect.blocked", "detect.call_blocked", "detect.output_blocked", "detect.shown_blocked", "detect.hint.ids", "detect.hint.financial", "detect.hint.network", "detect.hint.credentials", "detect.hint.injection", "detect.hint.tool_instructions", "detect.hint.canary_leak", "detect.hint.prompt_leak", "detect.hint.marker_leak", "detect.hint.ungiven_images", "detect.hint.ungiven_links", "detect.hint.tool_leak", "detect.hint.own", "egress.default_repair_guidance", "egress.refusal", "egress.refusal_cut", "egress.rejection", "egress.rejection_found", "egress.hint_unscannable", "egress.hint_provider_tool_leak", "thought.omitted_image", "thought.omitted_link", "thought.omitted_instructions", "session.abandon_gated", "session.tool_denied", "session.tool_aborted", "session.sign_in", "sign_in.link", "sign_in.pending", "sign_in.done", "sign_in.declined", "sign_in.expired", "sign_in.out_of_scope", "session.gate_expired", "session.provider_state_unowned", "session.conversation_unknown", "session.full", "session.busy", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty", "stop.cancelled", "stop.interrupted", "stop.length", "stop.filtered", "stop.provider_error", "stop.stream_incomplete", "stop.step_limit", "composer.model", "composer.effort", "tool.awaiting_user", "tool.completed_hidden", "tool.t2_loader_needs_snapshot", "tool.t2_loader_shape", "tool.t2_loader_output_invalid", "tool.execution_uncertain", "tool.input_invalid", "tool.input_invalid_after_mutate", "tool.output_invalid_after_mutate", "tool.handler_no_output", "tool.did_not_run", "tool.page_no_answer", "tool.page_timed_out", "tool.output_invalid", "tool.not_loaded_t2", "tool.wait_unknown", "tool.wait_cycle", "tool.after_field", "tool.not_visible", "tool.builtin_not_enabled", "tool.provider_native", "tool.not_registered", "tool.builtin_needs_snapshot", "tool.not_allowed", "tool.not_eligible", "tool.unsupported_type", "tool.agent_call_limit", "tool.agent_failed", "tool.activity_failed", "protocol.not_served", "protocol.profile_type", "protocol.options", "protocol.option_clash", "protocol.base_options", "protocol.id_clash", "protocol.ws_headers", "protocol.builtin_unwritten", "protocol.provider_missing", "protocol.connection", "protocol.part_schema", "protocol.part_invalid", "protocol.key_invalid", "protocol.no_key", "protocol.reply_shape", "protocol.endpoint_url", "protocol.endpoint_host", "protocol.http", "protocol.no_operation", "protocol.definition", "protocol.provider_id_clash", "protocol.history_needed"];
8019
+ export declare const LABEL_KEYS: readonly ["provider.decision_failed", "provider.decision_unavailable", "provider.decision_model_missing", "provider.decision_ended", "provider.decision_images_off", "provider.decision_box_model", "provider.budget_exhausted", "provider.adapter_version", "provider.adapter_methods", "provider.adapter_schemas", "provider.fallback_slot", "provider.model_fallback_slot", "provider.host_model", "provider.turn_profile", "provider.model_binding_missing", "provider.session_closed", "provider.settled_call", "provider.session_unavailable", "provider.live_input", "provider.tool_cancel_missing", "provider.kernel_gate", "provider.event_invalid", "provider.response_identity", "provider.credential_resolution", "provider.credential_shape", "provider.stored_continuation", "provider.continuation_mismatch", "provider.continuation_contract", "provider.stateless_history", "provider.events_after_completion", "provider.duplicate_call", "provider.tool_cancel_live", "provider.complete_unavailable", "provider.parallel_tools", "provider.binding_identity", "provider.profile_type", "provider.event_type", "provider.feature", "provider.input_kind", "provider.output_kind", "provider.builtin", "provider.credential_missing", "provider.profile_configuration", "continue.instruction", "canary.bind_note", "user_data.note", "context.note", "taint.blocked", "taint.reason_steered", "taint.reason_tainted", "taint.destination_blocked", "taint.destination_confirm", "advisory.notice_elevated", "advisory.notice_high", "advisory.guidance", "attachments.too_many_files", "attachments.too_many_of_kind", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "attachments.limits_unconfigured", "quota.exhausted", "quota.busy", "error.config", "error.request", "error.conflict", "error.not_found", "error.input", "error.action", "error.auth", "error.rate_limit", "error.busy", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "repair.default_guidance", "repair.items_guidance", "repair.prompt_header", "repair.prompt_intro", "repair.prompt_instructions", "repair.history_heading", "repair.section_previous_output", "repair.section_validator_rejection", "repair.section_repair_guidance", "repair.section_instructions", "structured.answer_tool", "structured.answer_missing", "structured.cut_off", "structured.not_json", "compaction.request", "compaction.tool_call", "compaction.tool_result", "compaction.tool_files", "decision.box_image", "detect.blocked", "detect.call_blocked", "detect.output_blocked", "detect.shown_blocked", "detect.hint.ids", "detect.hint.financial", "detect.hint.network", "detect.hint.credentials", "detect.hint.injection", "detect.hint.tool_instructions", "detect.hint.canary_leak", "detect.hint.prompt_leak", "detect.hint.marker_leak", "detect.hint.ungiven_images", "detect.hint.ungiven_links", "detect.hint.tool_leak", "detect.hint.own", "egress.default_repair_guidance", "egress.refusal", "egress.refusal_cut", "egress.rejection", "egress.rejection_found", "egress.hint_unscannable", "egress.hint_provider_tool_leak", "thought.omitted_image", "thought.omitted_link", "thought.omitted_instructions", "session.abandon_gated", "session.tool_denied", "session.tool_aborted", "session.sign_in", "sign_in.link", "sign_in.pending", "sign_in.done", "sign_in.declined", "sign_in.expired", "sign_in.out_of_scope", "session.gate_expired", "session.provider_state_unowned", "session.conversation_unknown", "session.full", "session.busy", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty", "stop.cancelled", "stop.interrupted", "stop.length", "stop.filtered", "stop.provider_error", "stop.stream_incomplete", "stop.step_limit", "composer.model", "composer.effort", "tool.awaiting_user", "tool.completed_hidden", "tool.t2_loader_needs_snapshot", "tool.t2_loader_shape", "tool.t2_loader_output_invalid", "tool.execution_uncertain", "tool.input_invalid", "tool.input_invalid_after_mutate", "tool.output_invalid_after_mutate", "tool.handler_no_output", "tool.did_not_run", "tool.page_no_answer", "tool.page_timed_out", "tool.output_invalid", "tool.not_loaded_t2", "tool.wait_unknown", "tool.wait_cycle", "tool.after_field", "tool.background_field", "tool.background_started", "tool.not_visible", "tool.builtin_not_enabled", "tool.provider_native", "tool.not_registered", "tool.builtin_needs_snapshot", "tool.not_allowed", "tool.not_eligible", "tool.unsupported_type", "tool.agent_call_limit", "tool.agent_failed", "tool.activity_failed", "protocol.not_served", "protocol.profile_type", "protocol.options", "protocol.option_clash", "protocol.base_options", "protocol.id_clash", "protocol.ws_headers", "protocol.builtin_unwritten", "protocol.provider_missing", "protocol.connection", "protocol.part_schema", "protocol.part_invalid", "protocol.key_invalid", "protocol.no_key", "protocol.reply_shape", "protocol.endpoint_url", "protocol.endpoint_host", "protocol.http", "protocol.no_operation", "protocol.definition", "protocol.provider_id_clash", "protocol.history_needed"];
7997
8020
  /** One of {@linkcode LABEL_KEYS}. */
7998
8021
  export type LabelKey = (typeof LABEL_KEYS)[number];
7999
8022
  /**
@@ -9000,6 +9023,7 @@ import type { AuthUnauthenticatedPolicy, HttpMethod, ToolAccess, ToolAuthType, T
9000
9023
  import type { RemovedItem, Source, ToolCallEdit, ToolCallEvent, ToolCallRequest, ToolFailure, ToolGate, ToolPhaseEvent, ToolTraceStep, ToolWarning, TurnToolSnapshot, WireFunctionTool } from '../turn-events.js';
9001
9024
  import type { InteractionPart, ModelId, Profile, ProfileId, ToolId, TurnInput, TurnRequest, TurnSpeech, TurnTraceLink } from '../types.js';
9002
9025
  import type { LabelTemplate } from './activity-label.js';
9026
+ import type { ToolBackground, ToolBackgroundService } from './background.js';
9003
9027
  import type { PageToolExecution, ToolExecutionCoordinator } from './operation.js';
9004
9028
  import type { UncheckedOutput } from './unchecked-output.js';
9005
9029
  export type { AuthUnauthenticatedPolicy, HttpMethod, ToolAccess, ToolAuthType, ToolCallEdit, ToolCallEvent, ToolCallRequest, ToolFailure, ToolGate, ToolPermission, ToolPhaseEvent, ToolTraceStep, ToolWarning, TurnToolSnapshot, WireFunctionTool, };
@@ -9149,6 +9173,10 @@ export interface ToolHostHooks<TIn = unknown> {
9149
9173
  exposeToModel?: boolean;
9150
9174
  /** The model gets an \`after\` field: the tools in the same step that must settle before this call starts. */
9151
9175
  after?: boolean;
9176
+ /** When the model gets its reply. Unset is \`never\`: when the body ends. A turn without a background service runs inline. */
9177
+ background?: ToolBackground;
9178
+ /** \`inputSchema\` with the \`background\` argument. The registry sets it on an \`ask\` tool. */
9179
+ askInputSchema?: Record<string, unknown>;
9152
9180
  }
9153
9181
  export interface ToolOutputHooks<TOut = unknown> {
9154
9182
  /** A source that fails \`sourceSchema\`, or a throw, is a \`sources_invalid\` warning and is not cited. */
@@ -9311,6 +9339,7 @@ export interface AgentToolDef extends ToolBase {
9311
9339
  hostOnly?: AgentToolChannel[];
9312
9340
  preTool?: ToolHostHooks<AgentToolInput>['preTool'];
9313
9341
  after?: ToolHostHooks<AgentToolInput>['after'];
9342
+ background?: ToolHostHooks<AgentToolInput>['background'];
9314
9343
  exposeToModel?: boolean;
9315
9344
  }
9316
9345
  export interface RegisteredAgentTool extends AgentToolDef, ToolHostHooks<AgentToolInput>, ToolOutputHooks<AgentToolOutput> {
@@ -9392,6 +9421,7 @@ export type ToolPolicy = (ctx: ToolLoadContext) => ToolId[] | Promise<ToolId[]>;
9392
9421
  /** A request to run a held tool call outside a turn. */
9393
9422
  export interface InvokeToolRequest {
9394
9423
  execution?: ToolExecutionCoordinator;
9424
+ background?: ToolBackgroundService;
9395
9425
  /** invariant: Only the trusted host restores the kernel-issued identity from saved authority. */
9396
9426
  operationId?: string;
9397
9427
  profile: string;
@@ -9767,6 +9797,18 @@ export interface PageToolDispatch {
9767
9797
  export interface PageToolExecution {
9768
9798
  dispatch(claim: ToolOperationClaim, signal?: AbortSignal): Promise<PageToolDispatch>;
9769
9799
  }
9800
+ export type BackgroundToolEvent = TurnEventOf<'tool'> & {
9801
+ tool: Extract<TurnEventOf<'tool'>['tool'], {
9802
+ phase: 'background';
9803
+ }>;
9804
+ };
9805
+ /** What the model reads when a call goes on after its turn. */
9806
+ export interface ToolOperationReply {
9807
+ event: BackgroundToolEvent;
9808
+ replay: {
9809
+ modelResult: ModelToolResult;
9810
+ };
9811
+ }
9770
9812
  export interface ToolOperationOutcome {
9771
9813
  event: TerminalToolEvent;
9772
9814
  effects: 'not_started' | 'completed' | 'unknown';
@@ -9790,6 +9832,9 @@ export type BeginToolOperationResult = {
9790
9832
  } | {
9791
9833
  kind: 'settled';
9792
9834
  outcome: ToolOperationOutcome;
9835
+ } | {
9836
+ kind: 'background';
9837
+ reply: ToolOperationReply;
9793
9838
  } | {
9794
9839
  kind: 'running';
9795
9840
  } | {
@@ -9806,6 +9851,11 @@ export interface ToolExecutionCoordinator {
9806
9851
  kind: 'acquired';
9807
9852
  }> | undefined>;
9808
9853
  begin(operation: ToolOperationIdentity): Promise<BeginToolOperationResult>;
9854
+ /**
9855
+ * Keeps the reply the model reads for a call that goes on after its turn. The claim stays held
9856
+ * for \`settle\` or \`markUncertain\`. A coordinator without it cannot take a background service.
9857
+ */
9858
+ detach?(claim: ToolOperationClaim, reply: ToolOperationReply): Promise<void>;
9809
9859
  settle(claim: ToolOperationClaim, outcome: ToolOperationOutcome): Promise<void>;
9810
9860
  settleNotStarted(operation: ToolOperationIdentity, outcome: ToolOperationOutcome): Promise<void>;
9811
9861
  markUncertain(claim: ToolOperationClaim, reason: ToolOperationUncertainty): Promise<void>;
@@ -9817,9 +9867,167 @@ export declare function unresolvedOperation(kind: ErrorKind, reason: string, cau
9817
9867
  /** The host asked to run an operation that is still running or uncertain, so the host settles it first. */
9818
9868
  export declare function heldOperation(state: 'running' | 'uncertain'): TheoremError;
9819
9869
  export declare function toolInvocationHash(value: unknown): Promise<string>;
9870
+ export declare const toolOperationReplySchema: z.ZodType<ToolOperationReply>;
9820
9871
  export declare const toolOperationOutcomeSchema: z.ZodType<ToolOperationOutcome>;
9821
9872
  export declare function operationWireValue(value: unknown): JsonValue;
9822
- `,"file:///node_modules/@theoremjs/agents/src/guardrails/error.d.ts":"import type { TurnEventOf } from '../kernel/turn-events.js';\nimport type { TurnEvent } from '../kernel/types.js';\nimport { type LabelOverrides } from './labels.js';\nimport { type ErrorCopies, type ErrorKind, TheoremError } from './theorem-error.js';\n/** True when the value is an error named `AbortError`. */\ndeclare function isAbortError(err: unknown): boolean;\n/** `AbortSignal.timeout` rejects with a `TimeoutError`, not an `AbortError`. */\ndeclare function isTimeoutError(err: unknown): boolean;\n/** Throws when the signal has aborted: its framework, abort or timeout reason, else an `AbortError`. */\ndeclare function throwIfAborted(signal?: AbortSignal): void;\n/** Anything that is not a `TheoremError` or an abort escaped every boundary that names kinds: a THEOREM bug. */\ndeclare function errorKind(err: unknown): ErrorKind;\n/** The error kind for an HTTP status: 401, 402 and 403 are `auth`; 408, 504 and 524 `timeout`; 409 `conflict`; 429 `rate_limit`; 503 and 529 (overloaded) `busy`; 500 and above `unavailable`; the rest `unsupported`. */\ndeclare function kindOfHttpStatus(status: number): ErrorKind;\n/** The named reasons an error carries, one line each, in the profile's wording. */\ndeclare function errorCopyText(copy: ErrorCopies, labels?: LabelOverrides): string;\n/** Pass the profile's `labels`, or the profile's wording is skipped. */\ndeclare function publicError(err: unknown, labels?: LabelOverrides): string;\n/** Raw diagnostic for hosts, traces, and logs; never shown to end users. Each cause that says something new follows on its own line. */\ndeclare function describeError(err: unknown): string;\n/** fetch rejects only when no response came back, so any non-abort, non-timeout rejection is `network`. */\ndeclare function networkError(err: unknown): unknown;\n/** `send`, with a failed send or body read named as `networkError` names it. */\ndeclare function sendOrNetworkError(send: typeof fetch, ...args: Parameters<typeof fetch>): Promise<Response>;\ntype ProducedError = TurnEventOf<'error'> & {\n errorInternal: string;\n};\n/** No user wording yet: `withPublicLabels` adds it where the event reaches the host, the one place that knows the profile. */\ndeclare function toErrorEvent(err: unknown): ProducedError;\n/** Wording already set (host copy) is kept. */\ndeclare function withPublicLabels(event: TurnEvent, labels?: LabelOverrides): TurnEvent;\nexport type { ErrorCopies, ErrorCopy, ErrorKind, TheoremErrorOptions } from './theorem-error.js';\nexport { ERROR_KINDS } from './theorem-error.js';\nexport type { ProducedError };\nexport { describeError, errorCopyText, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, networkError, publicError, sendOrNetworkError, TheoremError, throwIfAborted, toErrorEvent, withPublicLabels, };\n","file:///node_modules/@theoremjs/agents/src/kernel/tools/activity-label.d.ts":`/** One line of wording, or a list of lines read top to bottom: the first that fits is shown. */
9873
+ `,"file:///node_modules/@theoremjs/agents/src/guardrails/error.d.ts":"import type { TurnEventOf } from '../kernel/turn-events.js';\nimport type { TurnEvent } from '../kernel/types.js';\nimport { type LabelOverrides } from './labels.js';\nimport { type ErrorCopies, type ErrorKind, TheoremError } from './theorem-error.js';\n/** True when the value is an error named `AbortError`. */\ndeclare function isAbortError(err: unknown): boolean;\n/** `AbortSignal.timeout` rejects with a `TimeoutError`, not an `AbortError`. */\ndeclare function isTimeoutError(err: unknown): boolean;\n/** Throws when the signal has aborted: its framework, abort or timeout reason, else an `AbortError`. */\ndeclare function throwIfAborted(signal?: AbortSignal): void;\n/** Anything that is not a `TheoremError` or an abort escaped every boundary that names kinds: a THEOREM bug. */\ndeclare function errorKind(err: unknown): ErrorKind;\n/** The error kind for an HTTP status: 401, 402 and 403 are `auth`; 408, 504 and 524 `timeout`; 409 `conflict`; 429 `rate_limit`; 503 and 529 (overloaded) `busy`; 500 and above `unavailable`; the rest `unsupported`. */\ndeclare function kindOfHttpStatus(status: number): ErrorKind;\n/** The named reasons an error carries, one line each, in the profile's wording. */\ndeclare function errorCopyText(copy: ErrorCopies, labels?: LabelOverrides): string;\n/** Pass the profile's `labels`, or the profile's wording is skipped. */\ndeclare function publicError(err: unknown, labels?: LabelOverrides): string;\n/** Raw diagnostic for hosts, traces, and logs; never shown to end users. Each cause that says something new follows on its own line. */\ndeclare function describeError(err: unknown): string;\n/** fetch rejects only when no response came back, so any non-abort, non-timeout rejection is `network`. */\ndeclare function networkError(err: unknown): unknown;\n/** `send`, with a failed send or body read named as `networkError` names it. */\ndeclare function sendOrNetworkError(send: typeof fetch, ...args: Parameters<typeof fetch>): Promise<Response>;\ntype ProducedError = TurnEventOf<'error'> & {\n errorInternal: string;\n};\n/** No user wording yet: `withPublicLabels` adds it where the event reaches the host, the one place that knows the profile. */\ndeclare function toErrorEvent(err: unknown): ProducedError;\n/** Wording already set (host copy) is kept. */\ndeclare function withPublicLabels(event: TurnEvent, labels?: LabelOverrides): TurnEvent;\nexport type { ErrorCopies, ErrorCopy, ErrorKind, TheoremErrorOptions } from './theorem-error.js';\nexport { ERROR_KINDS } from './theorem-error.js';\nexport type { ProducedError };\nexport { describeError, errorCopyText, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, networkError, publicError, sendOrNetworkError, TheoremError, throwIfAborted, toErrorEvent, withPublicLabels, };\n","file:///node_modules/@theoremjs/agents/src/kernel/tools/background.d.ts":`import { z } from 'zod';
9874
+ import { labelText } from '../../guardrails/labels.js';
9875
+ import type { SpanHandle, TraceAttributes } from '../../observability/trace-span.js';
9876
+ import type { TurnEvent } from '../types.js';
9877
+ import { type ToolCallBase } from './events.js';
9878
+ import { type ToolExecutionCoordinator, type ToolOperationReply } from './operation.js';
9879
+ /** When the model gets its reply: at the hand-off, past a time, if it asks, or when the body ends. */
9880
+ export type ToolBackground = 'always' | {
9881
+ afterMs: number;
9882
+ } | 'ask' | 'never';
9883
+ /** The call a detached event belongs to. */
9884
+ export interface ToolBackgroundCall {
9885
+ operationId: string;
9886
+ callId: string;
9887
+ toolId: string;
9888
+ }
9889
+ /** The host's hold on one detached call. */
9890
+ export interface ToolBackgroundHandle extends ToolBackgroundCall {
9891
+ /**
9892
+ * Stops the call. It settles as a \`cancelled\` failure with \`reason\` as its code, whatever the
9893
+ * body does. With no reason this is a shutdown: the call ends \`execution_interrupted\`. With
9894
+ * \`graceMs\`, a body that ignores its signal past that time settles anyway.
9895
+ */
9896
+ stop(reason?: string, options?: {
9897
+ graceMs?: number;
9898
+ }): void;
9899
+ /** Resolves when the call has settled or been marked. */
9900
+ done: Promise<void>;
9901
+ }
9902
+ /** The host's service for detached calls. Without it every tool runs inline. */
9903
+ export interface ToolBackgroundService {
9904
+ detached(call: ToolBackgroundHandle): void;
9905
+ event(event: TurnEvent, call: ToolBackgroundCall): void | Promise<void>;
9906
+ }
9907
+ /** A detached call's own trace record, joined to its turn through \`traceparent\`. */
9908
+ export interface DetachedToolTrace {
9909
+ open: (name: string, attributes: TraceAttributes) => SpanHandle;
9910
+ end: () => void | Promise<void>;
9911
+ }
9912
+ /** The service with what a request adds: its event projection and where a detached trace goes. */
9913
+ export interface ToolBackgroundSupport {
9914
+ service: ToolBackgroundService;
9915
+ project: (event: TurnEvent) => TurnEvent;
9916
+ openTrace: (callId: string) => DetachedToolTrace;
9917
+ }
9918
+ export interface ToolDetach {
9919
+ at: 'claim' | {
9920
+ afterMs: number;
9921
+ };
9922
+ support: ToolBackgroundSupport;
9923
+ trace: DetachedToolTrace;
9924
+ reply: () => ToolOperationReply;
9925
+ }
9926
+ /** The \`ask\` argument, as the model reads it. */
9927
+ export declare function backgroundField(): z.ZodOptional<z.ZodBoolean>;
9928
+ /** The call's input without \`background\`, and whether the model asked for it. */
9929
+ export declare function splitBackground(tool: {
9930
+ background?: ToolBackground;
9931
+ } | undefined, input: unknown): {
9932
+ input: unknown;
9933
+ asked: boolean;
9934
+ };
9935
+ /** How this call detaches, or \`undefined\` when it runs inline. */
9936
+ export declare function planDetach(args: {
9937
+ tool: {
9938
+ background?: ToolBackground;
9939
+ name: string;
9940
+ } | undefined;
9941
+ input: unknown;
9942
+ support: ToolBackgroundSupport | undefined;
9943
+ base: ToolCallBase;
9944
+ labels: Parameters<typeof labelText>[2];
9945
+ }): ToolDetach | undefined;
9946
+ /** A late result needs a coordinator to keep it. */
9947
+ export declare function assertBackgroundCoordinator(service: ToolBackgroundService | undefined, execution: ToolExecutionCoordinator | undefined): void;
9948
+ /** A tool that must answer in an open turn cannot detach; only an object input takes \`background\`. */
9949
+ export declare function assertBackgroundSetting(tool: {
9950
+ name: string;
9951
+ background?: ToolBackground;
9952
+ answeredBy?: string;
9953
+ }): void;
9954
+ `,"file:///node_modules/@theoremjs/agents/src/kernel/tools/events.d.ts":`import type { z } from 'zod';
9955
+ import { type LabelOverrides } from '../../guardrails/labels.js';
9956
+ import type { GuardrailEvent, NetworkGuardrailSpec } from '../../guardrails/types.js';
9957
+ import type { SpanHandle } from '../../observability/trace-span.js';
9958
+ import { type Source } from '../turn-events.js';
9959
+ import type { TurnEvent, TurnEventOf } from '../types.js';
9960
+ import type { ToolOperationClaim } from './operation.js';
9961
+ import type { ToolCallRequest, ToolContext, ToolFailure, ToolLabels, ToolPhaseEvent } from './types.js';
9962
+ export type ToolCallBase = Pick<ToolPhaseEvent, 'name' | 'callId'> & {
9963
+ operationId?: string;
9964
+ /** The call's failed label, from {@linkcode failedActivity}; absent, a failure names the tool. */
9965
+ activityFailed?: string;
9966
+ };
9967
+ export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
9968
+ export type ToolPhasePatch = DistributiveOmit<ToolPhaseEvent, keyof ToolCallBase | 'at'>;
9969
+ export declare function toolEvent(base: ToolCallBase, patch: ToolPhasePatch): TurnEventOf<'tool'>;
9970
+ /**
9971
+ * The label a failed call shows: the tool's own, filled from the input the model sent, else the
9972
+ * labels' line naming the tool in words.
9973
+ */
9974
+ export declare function failedActivity(name: string, profileLabels?: LabelOverrides, labels?: ToolLabels, input?: unknown): string;
9975
+ /** The failed label of the call \`base\` names. */
9976
+ export declare function failedActivityOf(base: ToolCallBase): string;
9977
+ /** \`readBack\` is passed when the call's result guard already wrote the model's text. */
9978
+ export declare function failureEvent(base: ToolCallBase, failure: ToolFailure, readBack?: string): TurnEventOf<'tool'>;
9979
+ /** The first event of every call. */
9980
+ export declare function toolCallRequestEvent(base: ToolCallBase, args: Record<string, unknown>, { reasoning, stepId, stepCallCount, }?: Pick<ToolCallRequest, 'reasoning' | 'stepId' | 'stepCallCount'>): TurnEventOf<'tool'>;
9981
+ /** Unique: readers join a call's events by it. */
9982
+ export declare function newCallId(name: string): string;
9983
+ export declare function toolCallArguments(safeInput: unknown): Record<string, unknown>;
9984
+ export declare function messageOf(err: unknown): string;
9985
+ export declare function sourceEvents(base: ToolCallBase, sources: (output: unknown) => Source[], output: unknown): Generator<TurnEvent>;
9986
+ /** A call's claim, taken once at the hand-off: right before the destination is asked. */
9987
+ export declare class HandOff {
9988
+ private begin?;
9989
+ private taken?;
9990
+ private failed?;
9991
+ constructor(begin?: (() => Promise<ToolOperationClaim | undefined>) | undefined);
9992
+ claim(): Promise<ToolOperationClaim | undefined>;
9993
+ /** The claim's own failure is the coordinator's, so no tool catch may turn it into a tool failure. */
9994
+ rethrowClaimFailure(): void;
9995
+ }
9996
+ export declare function dispatchToolBody(tool: {
9997
+ labels?: ToolLabels;
9998
+ }, input: unknown, ctx: ToolContext, base: ToolCallBase, beginBody?: (preparedInput: unknown) => Promise<ToolOperationClaim | undefined>): AsyncGenerator<TurnEvent, HandOff>;
9999
+ export declare function startToolExecution<T>(tool: {
10000
+ input: z.ZodType<T>;
10001
+ }, rawInput: unknown, ctx: ToolContext): {
10002
+ ok: true;
10003
+ data: T;
10004
+ } | {
10005
+ ok: false;
10006
+ failure: ToolFailure;
10007
+ };
10008
+ export declare function networkBlockedEvent(): GuardrailEvent;
10009
+ export declare function networkBlocked(err: unknown, guardrail?: GuardrailEvent): Generator<TurnEvent, ToolFailure>;
10010
+ /**
10011
+ * Shared by HTTP and MCP so they cannot diverge on what SSRF enforcement means.
10012
+ * The check's time goes on the tool's span, when the call is traced.
10013
+ */
10014
+ export declare function guardToolTarget(url: string, ctx: ToolContext, span?: SpanHandle): Generator<TurnEvent, {
10015
+ ok: true;
10016
+ url: URL;
10017
+ } | {
10018
+ ok: false;
10019
+ failure: ToolFailure;
10020
+ }>;
10021
+ /** The checks a guarded request runs on its way, timed together: each hop's address, and its lookup. */
10022
+ export interface RequestChecks {
10023
+ /** Pass as \`fetchGuarded\`'s \`onCheck\`. */
10024
+ onCheck: (ms: number) => void;
10025
+ /** Records the checks once, when any ran, with the block they raised. */
10026
+ record: (blocked?: GuardrailEvent) => void;
10027
+ }
10028
+ export declare function requestChecks(span: SpanHandle | undefined): RequestChecks;
10029
+ export declare function toolNetworkPolicy(ctx: ToolContext): NetworkGuardrailSpec | undefined;
10030
+ `,"file:///node_modules/@theoremjs/agents/src/kernel/tools/activity-label.d.ts":`/** One line of wording, or a list of lines read top to bottom: the first that fits is shown. */
9823
10031
  export type LabelTemplate = string | readonly string[];
9824
10032
  /** \`expected: null\` is the check "is null". */
9825
10033
  export type Check = {
@@ -10412,9 +10620,9 @@ export { clearTraceDestinations, getTraceDestination, isTraceSink, listTraceDest
10412
10620
  */
10413
10621
  import type { ToolPhaseEvent, TurnEvent } from '../turn-events.js';
10414
10622
  import type { StartedInvoke, StartedStep } from './invoke.js';
10415
- /** The phase a call ends on: it completed, a gate held it, or it failed. */
10623
+ /** The phase a call ends on: it completed, a gate held it, it failed, or it went on in the background. */
10416
10624
  export type SettledToolCall = Extract<ToolPhaseEvent, {
10417
- phase: 'complete' | 'gate' | 'error';
10625
+ phase: 'complete' | 'gate' | 'error' | 'background';
10418
10626
  }> & {
10419
10627
  /** Kernel-issued identity; a gate's resume carries it. */
10420
10628
  operationId?: string;
@@ -10694,8 +10902,8 @@ export declare function profileToolsSpec(profile: Profile): ProfileToolsSpec | u
10694
10902
  export declare function profileToolsParallel(profile: Profile): boolean | undefined;
10695
10903
  export declare function resolveAllowedCustomToolIds(tools: ToolRegistry, profile: Profile, req: TurnRequest): ToolId[];
10696
10904
  export declare function resolveModelBuiltinIds(tools: ToolRegistry, profile: ModelProfile, req: TurnRequest, modelId: ModelId): ToolId[];
10697
- export declare function wireForTool(tools: ToolRegistry, name: string): WireFunctionTool | undefined;
10698
- export declare function buildWire(tools: ToolRegistry, visible: ToolId[]): WireFunctionTool[];
10905
+ export declare function wireForTool(tools: ToolRegistry, name: string, modelBackground?: boolean): WireFunctionTool | undefined;
10906
+ export declare function buildWire(tools: ToolRegistry, visible: ToolId[], modelBackground?: boolean): WireFunctionTool[];
10699
10907
  export declare function promoteTool(tools: ToolRegistry, state: TurnToolSnapshot, id: ToolId): void;
10700
10908
  export declare function promoteBuiltin(tools: ToolRegistry, state: TurnToolSnapshot, id: ToolId): void;
10701
10909
  /** Live declarations are fixed at session setup, so every allowed tool there is effectively T0. */
@@ -10707,6 +10915,8 @@ export declare function prepareTurnToolSnapshot(tools: ToolRegistry, profile: Pr
10707
10915
  /** So concurrent host invokes do not share mutable state. */
10708
10916
  export declare function cloneTurnToolSnapshot(state: TurnToolSnapshot): TurnToolSnapshot;
10709
10917
  export declare function expandT1Policy(tools: ToolRegistry, state: TurnToolSnapshot, profile: Profile, req: TurnRequest): Promise<void>;
10918
+ /** Puts the T2 tools among \`ids\` that the turn may call on its list; any other id is left out. */
10919
+ export declare function promoteTurnTools(tools: ToolRegistry, state: TurnToolSnapshot, ids?: readonly ToolId[]): void;
10710
10920
  export declare function extractLoadedIds(output: unknown): string[] | undefined;
10711
10921
  export declare function promoteLoadedTools(tools: ToolRegistry, state: TurnToolSnapshot, loaded: string[], profile: Profile): PromoteLoadedResult;
10712
10922
  export declare function promotionTarget(tools: ToolRegistry, id: string, profile: Profile): {
@@ -10897,6 +11107,8 @@ export interface ToolStageSupport {
10897
11107
  wait?: StepWait;
10898
11108
  /** The host sees a handler's drafts: \`outputs.streaming.mode\` \`sse\`. Unset outside a turn's step. */
10899
11109
  drafts?: boolean;
11110
+ /** Told when the body has ended, before \`post_tool\` reads it. */
11111
+ bodyEnded?: () => void;
10900
11112
  }
10901
11113
  export type PreBodyOutcome = {
10902
11114
  ok: true;
@@ -10977,82 +11189,6 @@ export declare function emitGateSettlement(args: {
10977
11189
  toolName: string;
10978
11190
  labels: LabelOverrides | undefined;
10979
11191
  }): AsyncGenerator<TurnEvent, string | undefined>;
10980
- `,"file:///node_modules/@theoremjs/agents/src/kernel/tools/events.d.ts":`import type { z } from 'zod';
10981
- import { type LabelOverrides } from '../../guardrails/labels.js';
10982
- import type { GuardrailEvent, NetworkGuardrailSpec } from '../../guardrails/types.js';
10983
- import type { SpanHandle } from '../../observability/trace-span.js';
10984
- import { type Source } from '../turn-events.js';
10985
- import type { TurnEvent, TurnEventOf } from '../types.js';
10986
- import type { ToolOperationClaim } from './operation.js';
10987
- import type { ToolCallRequest, ToolContext, ToolFailure, ToolLabels, ToolPhaseEvent } from './types.js';
10988
- export type ToolCallBase = Pick<ToolPhaseEvent, 'name' | 'callId'> & {
10989
- operationId?: string;
10990
- /** The call's failed label, from {@linkcode failedActivity}; absent, a failure names the tool. */
10991
- activityFailed?: string;
10992
- };
10993
- export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
10994
- export type ToolPhasePatch = DistributiveOmit<ToolPhaseEvent, keyof ToolCallBase | 'at'>;
10995
- export declare function toolEvent(base: ToolCallBase, patch: ToolPhasePatch): TurnEventOf<'tool'>;
10996
- /**
10997
- * The label a failed call shows: the tool's own, filled from the input the model sent, else the
10998
- * labels' line naming the tool in words.
10999
- */
11000
- export declare function failedActivity(name: string, profileLabels?: LabelOverrides, labels?: ToolLabels, input?: unknown): string;
11001
- /** The failed label of the call \`base\` names. */
11002
- export declare function failedActivityOf(base: ToolCallBase): string;
11003
- /** \`readBack\` is passed when the call's result guard already wrote the model's text. */
11004
- export declare function failureEvent(base: ToolCallBase, failure: ToolFailure, readBack?: string): TurnEventOf<'tool'>;
11005
- /** The first event of every call. */
11006
- export declare function toolCallRequestEvent(base: ToolCallBase, args: Record<string, unknown>, { reasoning, stepId, stepCallCount, }?: Pick<ToolCallRequest, 'reasoning' | 'stepId' | 'stepCallCount'>): TurnEventOf<'tool'>;
11007
- /** Unique: readers join a call's events by it. */
11008
- export declare function newCallId(name: string): string;
11009
- export declare function toolCallArguments(safeInput: unknown): Record<string, unknown>;
11010
- export declare function messageOf(err: unknown): string;
11011
- export declare function sourceEvents(base: ToolCallBase, sources: (output: unknown) => Source[], output: unknown): Generator<TurnEvent>;
11012
- /** A call's claim, taken once at the hand-off: right before the destination is asked. */
11013
- export declare class HandOff {
11014
- private begin?;
11015
- private taken?;
11016
- private failed?;
11017
- constructor(begin?: (() => Promise<ToolOperationClaim | undefined>) | undefined);
11018
- claim(): Promise<ToolOperationClaim | undefined>;
11019
- /** The claim's own failure is the coordinator's, so no tool catch may turn it into a tool failure. */
11020
- rethrowClaimFailure(): void;
11021
- }
11022
- export declare function dispatchToolBody(tool: {
11023
- labels?: ToolLabels;
11024
- }, input: unknown, ctx: ToolContext, base: ToolCallBase, beginBody?: (preparedInput: unknown) => Promise<ToolOperationClaim | undefined>): AsyncGenerator<TurnEvent, HandOff>;
11025
- export declare function startToolExecution<T>(tool: {
11026
- input: z.ZodType<T>;
11027
- }, rawInput: unknown, ctx: ToolContext): {
11028
- ok: true;
11029
- data: T;
11030
- } | {
11031
- ok: false;
11032
- failure: ToolFailure;
11033
- };
11034
- export declare function networkBlockedEvent(): GuardrailEvent;
11035
- export declare function networkBlocked(err: unknown, guardrail?: GuardrailEvent): Generator<TurnEvent, ToolFailure>;
11036
- /**
11037
- * Shared by HTTP and MCP so they cannot diverge on what SSRF enforcement means.
11038
- * The check's time goes on the tool's span, when the call is traced.
11039
- */
11040
- export declare function guardToolTarget(url: string, ctx: ToolContext, span?: SpanHandle): Generator<TurnEvent, {
11041
- ok: true;
11042
- url: URL;
11043
- } | {
11044
- ok: false;
11045
- failure: ToolFailure;
11046
- }>;
11047
- /** The checks a guarded request runs on its way, timed together: each hop's address, and its lookup. */
11048
- export interface RequestChecks {
11049
- /** Pass as \`fetchGuarded\`'s \`onCheck\`. */
11050
- onCheck: (ms: number) => void;
11051
- /** Records the checks once, when any ran, with the block they raised. */
11052
- record: (blocked?: GuardrailEvent) => void;
11053
- }
11054
- export declare function requestChecks(span: SpanHandle | undefined): RequestChecks;
11055
- export declare function toolNetworkPolicy(ctx: ToolContext): NetworkGuardrailSpec | undefined;
11056
11192
  `,"file:///node_modules/@theoremjs/agents/src/kernel/tools/handler-events.d.ts":`import type { ToolBoundary } from '../../guardrails/boundaries.js';
11057
11193
  import type { Provenance, ResolvedGuardrailPolicy } from '../../guardrails/types.js';
11058
11194
  import type { TurnEvent } from '../types.js';
@@ -11139,6 +11275,7 @@ import { type ToolCallEnd } from '../engine/tool-trace.js';
11139
11275
  import type { InjectUnit } from '../stages.js';
11140
11276
  import type { InteractionPart, Profile, TurnEvent } from '../types.js';
11141
11277
  import { type AgentCaller } from './agent.js';
11278
+ import { type ToolBackgroundSupport } from './background.js';
11142
11279
  import { startToolExecution, type ToolCallBase } from './events.js';
11143
11280
  import type { ToolExecutionCoordinator, ToolOperationClaim, ToolOperationOutcome } from './operation.js';
11144
11281
  import type { ToolRegistry } from './registry.js';
@@ -11194,6 +11331,7 @@ export declare function authorizeToolReplay(args: {
11194
11331
  }): void;
11195
11332
  interface RegisteredToolCall {
11196
11333
  execution?: ToolExecutionCoordinator;
11334
+ background?: ToolBackgroundSupport;
11197
11335
  invocation?: unknown;
11198
11336
  onDispatch?: () => void;
11199
11337
  beginBody?: (preparedInput: unknown) => Promise<ToolOperationClaim | undefined>;
@@ -11798,12 +11936,14 @@ export { isModelProfile, pickModel, projectProfileInRegistry, projectProfileObje
11798
11936
  `,"file:///node_modules/@theoremjs/agents/src/kernel/engine/session/mod.d.ts":`import type { TraceSink } from '../../../observability/trace-sink.js';
11799
11937
  import type { ProviderHostOptions } from '../../protocols/runtime.js';
11800
11938
  import type { KernelRegistry } from '../../registry/kernel-registry.js';
11939
+ import { type ToolBackgroundService } from '../../tools/background.js';
11801
11940
  import { type PageToolExecution, type ToolExecutionCoordinator } from '../../tools/operation.js';
11802
11941
  import type { KeyVault, LiveSession, SessionRequest } from '../../types.js';
11803
11942
  export type { LiveSession, SessionRequest };
11804
11943
  /** Options for opening a live session: the key vault, a provider's own settings, a WebSocket opener, how long a gated call waits for its decision, and the sign-in gate policy. */
11805
11944
  export interface RunSessionOptions extends ProviderHostOptions {
11806
11945
  execution?: ToolExecutionCoordinator;
11946
+ background?: ToolBackgroundService;
11807
11947
  pageExecution?: PageToolExecution;
11808
11948
  /** The host's keys by slot; the session uses the slots its profile names. */
11809
11949
  vault?: KeyVault;