Graphorin API reference v0.12.1
Graphorin API reference / @graphorin/tools / / ExecutorOptions
Interface: ExecutorOptions
Defined in: packages/tools/src/executor/types.ts:55
Options accepted by createToolExecutor(...).
Properties
| Property | Modifier | Type | Description | Defined in |
|---|---|---|---|---|
approvalGate? | readonly | ApprovalGate | Approval gate - invoked when a tool's needsApproval resolves to true. | packages/tools/src/executor/types.ts:62 |
argumentPolicy? | readonly | ToolArgumentPolicyGuard | Declarative tool-argument policy guard (D4 / Progent). Consulted AFTER schema validation + approval, BEFORE the data-flow sink gate, on every tool call. A forbid/deny verdict blocks the call with a capability_blocked outcome; ask/defer verdicts (E1, via the optional decide) fail closed here unless the batch is pre-approved - only the agent pre-screen can suspend. The pure decision engine lives in @graphorin/security/policy (evaluatePermissionDecision); the agent runtime injects this adapter. Absent ⇒ no policy (legacy). | packages/tools/src/executor/types.ts:74 |
cancellationGraceMs? | readonly | number | Hard-kill grace window (ms) for tools that ignore ctx.signal. Default 50. | packages/tools/src/executor/types.ts:96 |
dataFlowGuard? | readonly | DataFlowGuard | Optional provenance / data-flow guard (P1-3). When present, the executor consults it as a sink gate before running any side-effecting / external-stateful tool (so untrusted content cannot reach an exfiltration/mutation sink ungated) and records the provenance of every successful output for downstream sink checks. The agent runtime supplies the implementation (@graphorin/security's taint engine threaded through a per-run ledger); when absent, both steps are skipped (zero overhead, feature off). Because every in-script code-mode tool call also flows through executeOne, the same guard composes with code-mode automatically (P1-2). | packages/tools/src/executor/types.ts:170 |
emitAudit? | readonly | (event) => void | Audit emitter override. Defaults to the global registry. | packages/tools/src/executor/types.ts:60 |
handleProducerTaintCap? | readonly | number | W-114: cap on the in-memory handle-producer-taint map (TL-6). The map previously grew for the executor's whole lifetime; at the cap the OLDEST entry is evicted FIFO - safe, because the on-disk taint sidecar restores producer taint for evicted handles (the tools-03 fallback). Default 1024. | packages/tools/src/executor/types.ts:104 |
imperativeBudgetMs? | readonly | number | Override for the imperative-pattern scan budget (ms). The scanner returns null (= timed out, strip-pass skipped) when it exceeds this budget. Defaults to 250 ms (TOOLS-EX-02): 5 ms was the long-term target but is empirically too tight on cold-start / loaded CI runners, where a skipped strip pass silently lets injection through. 250 ms stays below any user-perceptible (one-shot, registration-time) latency. Hot-path callers that want a stricter budget can lower this explicitly. | packages/tools/src/executor/types.ts:116 |
imperativePatterns? | readonly | readonly ImperativePattern[] | Pluggable imperative patterns override. | packages/tools/src/executor/types.ts:106 |
inlineToolTimeoutMs? | readonly | number | Wall-clock limit applied to INLINE tool execution (TL-4). When set, this executor-level value takes precedence; otherwise the resolved per-tool sandbox-tier timeoutMs applies when > 0, else DEFAULT_INLINE_TOOL_TIMEOUT_MS (60s). Expiry fails the call with ToolError({ kind: 'timeout' }); the run continues. | packages/tools/src/executor/types.ts:178 |
maxParallelTools? | readonly | number | Cap on parallel tool calls per batch. Defaults to 8. | packages/tools/src/executor/types.ts:58 |
memoryGuardFactory? | readonly | (tier) => | MemoryModificationGuard | null | Optional memory-modification guard factory. Returns a MemoryModificationGuard per the tool's memoryGuardTier. The agent runtime supplies the implementation (createGuard(...) from @graphorin/security/guard); when absent, the guard step is skipped (audit-only baseline). | packages/tools/src/executor/types.ts:147 |
memoryRegionReader? | readonly | MemoryRegionReader | Optional memory-region reader the guard uses to hash the pre/post snapshots. The agent runtime supplies one automatically when memory is wired (a scope-aware reader over the working tier, SDF-1); without a reader the snapshot/verify cycle is skipped. | packages/tools/src/executor/types.ts:157 |
permissionHook? | readonly | PermissionHook | E1 pre-tool permission hook. Runs as its own phase AFTER schema validation (+ repair), BEFORE the approval phase - see PermissionHook for the decision semantics and the updatedInput rewrite contract. Absent ⇒ phase skipped. | packages/tools/src/executor/types.ts:81 |
registry | readonly | ToolRegistry | - | packages/tools/src/executor/types.ts:56 |
repair? | readonly | ToolRepairHook | Tool repair hook (single-round). | packages/tools/src/executor/types.ts:83 |
retry? | readonly | { backoffMs?: number; kinds?: readonly ToolErrorKind[]; maxAttempts?: number; } | C3: transparent bounded retry for transient tool failures. A failed attempt whose error kind is in kinds is silently re-executed with exponential backoff (a ToolRateLimitError's retryAfterMs wins over the computed backoff) up to maxAttempts TOTAL attempts - but only for pure / read-only tools or tools declaring an idempotencyKey, so a retry can never double a side effect. Defaults: maxAttempts: 3, backoffMs: 250, kinds: ['rate_limited'] ('timeout' is deliberately not retried by default - stacked wall-clock timeouts multiply run latency; opt in via kinds when you want it). | packages/tools/src/executor/types.ts:191 |
retry.backoffMs? | readonly | number | - | packages/tools/src/executor/types.ts:193 |
retry.kinds? | readonly | readonly ToolErrorKind[] | - | packages/tools/src/executor/types.ts:194 |
retry.maxAttempts? | readonly | number | - | packages/tools/src/executor/types.ts:192 |
sandboxResolver? | readonly | (policy) => Sandbox | null | Optional sandbox-dispatch resolver. Returns the Sandbox implementation to use for a given resolved policy, OR null to run the tool inline (the default for kind: 'none' policies). Skill loaders / agent runtimes inject this when sandbox-bundled code (skills, MCP-derived tools) needs out-of-process execution. | packages/tools/src/executor/types.ts:139 |
secretResolver? | readonly | SecretResolverHook | Secrets resolver injected from the agent runtime. | packages/tools/src/executor/types.ts:91 |
spill? | readonly | SpillWriter | Optional spill writer for the 'spill-to-file' truncation strategy. | packages/tools/src/executor/types.ts:89 |
streamingEventQueueDepth? | readonly | number | Default streaming queue depth. Default 256. | packages/tools/src/executor/types.ts:124 |
streamingMaxBufferBytes? | readonly | number | W-117: byte cap on each call's streaming aggregation buffer (the buffer-becomes-output chunks). Past the cap, chunks keep DELIVERING to the sink but stop accumulating; the aggregator flags bufferTruncated and dropped bytes are counted. Default 8 MiB. | packages/tools/src/executor/types.ts:131 |
streamingSink? | readonly | (event) => void | Sink for tool execution events; the agent runtime forwards these into agent.stream(...). Receives every tool.execute.* variant emitted by the executor (start, progress, partial, end, error). | packages/tools/src/executor/types.ts:122 |
summarizer? | readonly | ResultSummarizer | Optional summarizer for the 'summarize' truncation strategy. | packages/tools/src/executor/types.ts:87 |
tokenCounter? | readonly | TokenCounter | Per-provider token counter used by the truncation pipeline. | packages/tools/src/executor/types.ts:85 |