Graphorin API reference v0.1.0
Graphorin API reference / @graphorin/core / / ResolvedTool
Interface: ResolvedTool<TInput, TOutput, TDeps>
Defined in: packages/core/src/contracts/tool.ts:184
Resolved record returned by the ToolRegistry getter. Carries every non-public registration-time field downstream layers consume (sanitization, audit, retrieval, side-effect classification, collision resolution, …) so consumers do not have to recompute it.
Stable
Extends
Tool<TInput,TOutput,TDeps>
Type Parameters
| Type Parameter | Default type |
|---|---|
TInput | unknown |
TOutput | unknown |
TDeps | unknown |
Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
|---|---|---|---|---|---|
__effectiveDeferLoading | readonly | boolean | - | - | packages/core/src/contracts/tool.ts:188 |
__exampleCount | readonly | number | - | - | packages/core/src/contracts/tool.ts:192 |
__hasIdempotencyKey | readonly | boolean | - | - | packages/core/src/contracts/tool.ts:190 |
__preferredModel? | readonly | | ModelHint | ModelSpec | - | - | packages/core/src/contracts/tool.ts:193 |
__sideEffectClass | readonly | SideEffectClass | - | - | packages/core/src/contracts/tool.ts:189 |
__source | readonly | ToolSource | - | - | packages/core/src/contracts/tool.ts:187 |
__streamingHint | readonly | boolean | - | - | packages/core/src/contracts/tool.ts:191 |
__trustClass | readonly | ToolTrustClass | - | - | packages/core/src/contracts/tool.ts:186 |
defer_loading? | readonly | boolean | Defer the tool from the per-step catalogue until the model invokes the built-in tool_search to look it up. Tools with deferred loading are not advertised to the model on every step, which keeps the input-token cost bounded for installations with dozens of MCP-derived tools. Default false | Tool.defer_loading | packages/core/src/contracts/tool.ts:93 |
description | readonly | string | - | Tool.description | packages/core/src/contracts/tool.ts:37 |
examples? | readonly | readonly ToolExample<TInput, TOutput>[] | Worked examples shown to the model alongside the tool's description. Bounded [1, 5] — overflow emits a one-time WARN at registration. Each example's input and output is validated against the tool's inputSchema / outputSchema. | Tool.examples | packages/core/src/contracts/tool.ts:111 |
examplesEagerlyRendered? | readonly | boolean | Render examples eagerly (every step) regardless of defer_loading. When undefined the runtime applies the auto-rule: defer_loading: true ⇒ false; defer_loading: false ⇒ true; neither ⇒ undefined (the agent runtime decides at assembly time). | Tool.examplesEagerlyRendered | packages/core/src/contracts/tool.ts:118 |
executionMode? | readonly | "parallel" | "sequential" | Sequential execution mode hints. Tools tagged 'sequential' are never executed in parallel with each other; the executor serializes them inside the per-step batch. Default 'parallel' | Tool.executionMode | packages/core/src/contracts/tool.ts:59 |
failClosed? | readonly | boolean | When true, an inbound-sanitization hit returns ToolError({ kind: 'inbound_sanitization_blocked' }) instead of forwarding the (sanitized) result. Intended for regulated deployments. Default false | Tool.failClosed | packages/core/src/contracts/tool.ts:83 |
idempotencyKey? | readonly | (input, ctx) => string | Promise<string> | Optional callback returning a deterministic dedup key per (input, ctx) tuple. REQUIRED-by-WARN for 'side-effecting' / 'external-stateful' tools. The framework does not validate determinism — that is the operator's contract. | Tool.idempotencyKey | packages/core/src/contracts/tool.ts:132 |
inboundSanitization? | readonly | InboundSanitizationPolicy | Inbound prompt-injection sanitization policy. | Tool.inboundSanitization | packages/core/src/contracts/tool.ts:75 |
inputSchema | readonly | ZodLikeSchema<TInput> | - | Tool.inputSchema | packages/core/src/contracts/tool.ts:38 |
maxResultTokens? | readonly | number | Maximum number of tokens the assembled tool result may carry into the conversation history. 0 disables the cap (logs a one-time WARN at registration). Counted against text-shaped output and text-shaped contentParts entries; non-text parts pass through. Default 16384 | Tool.maxResultTokens | packages/core/src/contracts/tool.ts:102 |
memoryGuardTier? | readonly | MemoryGuardTier | Memory-modification guard tier (DEC-153). | Tool.memoryGuardTier | packages/core/src/contracts/tool.ts:73 |
name | readonly | string | - | Tool.name | packages/core/src/contracts/tool.ts:36 |
needsApproval? | readonly | boolean | ((input, ctx) => boolean | Promise<boolean>) | Either a static boolean or a predicate consulted at runtime against the realized input. true means the runtime suspends the run with a tool.approval.requested event before the tool executes. | Tool.needsApproval | packages/core/src/contracts/tool.ts:45 |
outputSchema? | readonly | ZodLikeSchema<TOutput, unknown> | - | Tool.outputSchema | packages/core/src/contracts/tool.ts:39 |
preferredModel? | readonly | | ModelHint | ModelSpec | Per-tool author-time model hint. Either a cost-tier vocabulary literal (`'fast' | 'balanced' | 'smart') OR an explicit ModelSpec` that always wins over the agent-side tier mapping. |
sandboxPolicy? | readonly | SandboxPolicy | Sandbox isolation level. Defaults are picked by @graphorin/security. | Tool.sandboxPolicy | packages/core/src/contracts/tool.ts:49 |
secretsAllowed? | readonly | readonly string[] | Per-tool secrets ACL. Tool execution is wrapped in a scope where ctx.secrets.require(...) only resolves keys present here. Empty / undefined means the tool may not request any secret. | Tool.secretsAllowed | packages/core/src/contracts/tool.ts:65 |
sensitivity? | readonly | Sensitivity | Sensitivity ceiling of the tool's input + output payload. Used by the redaction validator to decide whether the result may flow to a given sink (provider / exporter). | Tool.sensitivity | packages/core/src/contracts/tool.ts:71 |
sideEffectClass? | readonly | SideEffectClass | REQUIRED side-effect classification. v0.1 transition mode emits a one-time WARN per tool name on missing classification and applies the conservative deferred default 'side-effecting'; v0.2 may promote the WARN to a registration error. | Tool.sideEffectClass | packages/core/src/contracts/tool.ts:125 |
streamingHint? | readonly | true | Opt-in flag for streaming-tool execution. The ?: true typing rejects streamingHint: false on purpose — absence is the canonical "non-streaming" signal preserving v0.1 behaviour. When true, Tool.execute(...) may call ctx.streamContent(...) / ctx.reportProgress(...) and may return Promise<void>. | Tool.streamingHint | packages/core/src/contracts/tool.ts:143 |
tags? | readonly | readonly string[] | Free-form labels surfaced to operators and to the model. | Tool.tags | packages/core/src/contracts/tool.ts:51 |
truncationStrategy? | readonly | TruncationStrategy | Truncation strategy applied when maxResultTokens is exceeded. | Tool.truncationStrategy | packages/core/src/contracts/tool.ts:104 |
Methods
execute()
ts
execute(input, ctx): Promise<
| void
| TOutput
| ToolReturn<TOutput>>;Defined in: packages/core/src/contracts/tool.ts:157
Execute the tool. Concrete implementations may return either a raw TOutput or a ToolReturn<TOutput> envelope when extra content parts (images, files, …) need to be appended to the conversation. Streaming-hint tools may also return void once the per-chunk buffer has been populated.
Parameters
| Parameter | Type |
|---|---|
input | TInput |
ctx | ToolExecutionContext<TDeps> |
Returns
Promise< | void | TOutput | ToolReturn<TOutput>>