| // Shared tool context type. Lives at the bottom of the dependency graph | |
| // alongside json-schema.ts. Both shell and im import it; neither owns it. | |
| // | |
| // v0.10.2: only state_query reads ctx.stateLine. v0.9 tools ignore ctx. | |
| // v0.10.3 will add more fields (e.g. memoryLayer signal). | |
| // v0.10.3.2 (P2): agentId + databus added so mailbox tools read identity | |
| // from the running loop instead of a workingAgentId closure. | |
| import type { ApprovalStore } from '../im/tools/security/approval-store.js' | |
| import type { SubAgentToolPolicy } from '../im/sub-agent/policy.js' | |
| import type { DirectRecallLedger, TokenRange } from '../im/tools/databus-recall.js' | |
| import type { LargeRecallReport } from '../im/system-agents/large-recall.js' | |
| import type { TokenCounter } from './token-counter.js' | |
| export type ToolContext = { | |
| stateLine?: unknown | |
| agentId?: string // identity of the agent whose loop runs the tool | |
| databus?: unknown // the databus visible to this loop's tools. | |
| // For the working agent: its own private bus. | |
| // For sub-agents: opts.ctxDatabus ?? opts.databus — | |
| // the shared/contextual bus set by IMLoopOptions. | |
| // Tools read one bus; the loop decides which one. | |
| subAgentDepth?: number // v0.11.1 P2.3: recursion guard for run_subagent. | |
| // 0 = working agent (top level). Each nested | |
| // run_subagent increments by 1. Checked against | |
| // the effective maxSubAgentDepth (from ShellConfig | |
| // or SubAgentConfig.config override) in run-subagent.ts. | |
| // v0.12.3 stage 2b: Node-side M3 join metadata, injected by drive-coordinator | |
| // via metadata and merged into record_m3_summary (LLM must not fabricate it). | |
| // sourceStamps = the _stamps of the M1/M2 blocks being archived into M3; | |
| // rawArchiveIds = the archiveIds of their raw-archive records. When set, | |
| // record_m3_summary overrides the LLM's summary with these exact arrays so | |
| // the M3 join chain is authoritative from Node, not from LLM transcription. | |
| archiveSourceStamps?: string[] | |
| archiveRawArchiveIds?: string[] | |
| // v0.13.1: wiki-mcp 上下文注入守卫标记。仅 wiki system agent 的 loop | |
| // 会将其设为 true（IMLoopOptions.isWikiAgent → ctx.isWikiAgent）。 | |
| // 注册在 registry 上的 security hook 据此标记拦截 wiki__ 前缀工具的非授权 | |
| // 调用（hook 在 executeGuarded 内运行）。默认 undefined（falsy）——所有 | |
| // 非 wiki agent 调用 wiki__ 工具都会被 hook 拦截。 | |
| isWikiAgent?: boolean | |
| sessionId?: string // v0.16: security router session identifier | |
| /** The session's approval store. Set by ToolRegistry.execute() after the security check. */ | |
| approvalStore?: ApprovalStore | |
| // v0.27: 本 loop 的取消信号（IMLoopOptions.signal 透传）。阻塞型工具路径 | |
| // （write-approval 审批门、request_user_input）据此与自身 await 竞速—— | |
| // 否则 turn.cancel 的 abort 无法打断"卡在门内等用户"的回合（loop 的 | |
| // abort 检查只在 await 边界生效，工具不返回就永远到不了边界）。 | |
| signal?: AbortSignal | |
| // v0.16.2: agent→user reverse-RPC handler. Tools like request_user_input | |
| // call await ctx.requestHandler('request_user_input', payload) to pause | |
| // the turn and surface a question to the user. The handler returns the | |
| // user's response (or an empty/declined object if cancelled). When | |
| // undefined, tools that depend on it throw a clean error. | |
| requestHandler?: (kind: string, payload: unknown) => Promise<unknown> | |
| // v0.17: per-loop control-flow hooks. Propagated so run_subagent can pass | |
| // the working agent's hooks to child loops (matching the v0.16 sessionId | |
| // propagation pattern). Typed as unknown to avoid a reverse dependency from | |
| // shared → im/loop-hooks — tools that need it cast at the call site. | |
| hooks?: unknown | |
| // v0.18: sub-agent tool policy for load_tools runtime filtering. | |
| // When set, load_tools checks each requested tool against this policy | |
| // before injecting its schema. The main agent's loop does NOT set this | |
| // (no filtering); sub-agents' system-agent.ts sets it from their policy. | |
| toolPolicy?: SubAgentToolPolicy | |
| // Effective execution boundary for the current loop. This is the declared | |
| // toolRefs set after the sub-agent policy has been applied. | |
| allowedToolRefs?: readonly string[] | |
| /** Per-loop ledger used to prevent repeated small Databus reads bypassing the direct recall budget. */ | |
| directRecallLedger?: DirectRecallLedger | |
| /** Main agents use the 200K direct budget; delegated recall agents may read pages beyond it. */ | |
| directRecallLimitTokens?: number | |
| /** Temporary read-only delegated recall path for ranges over the direct budget. */ | |
| largeRecall?: (input: { | |
| question: string | |
| stamp?: string | |
| requestedRange: TokenRange | |
| sourceDatabus: unknown | |
| signal?: AbortSignal | |
| }) => Promise<LargeRecallReport> | |
| /** Counter selected by the host for this loop's provider/model. */ | |
| tokenCounter?: TokenCounter | |
| } | |