Class: ArtifactTool

Defined in: src/lib/classes/artifact_tool.ts:137

A @nhtio/adk!Tool subclass whose handler return value is wrapped directly in a @nhtio/adk!Tokenizable (not a @nhtio/adk!SpooledArtifact) when it lands on ToolCall.results.

Remarks

ArtifactTool is the canonical producer for forged artifact-query tools — the tools SpooledArtifact.forgeTools(ctx) emits so the model can head, tail, grep, json_get, md_headings (etc.) an artifact that is already in ctx.turnToolCalls.

The difference from @nhtio/adk!Tool is structural, not stylistic:

A normal Tool's handler returns bytes the ADK wraps in a fresh SpooledArtifact. The artifact lands in ToolCall.results, joins ctx.turnToolCalls, and is itself a first-class queryable artifact in the turn.
An ArtifactTool's handler returns a string that is already the model-visible answer to a query against an existing artifact. The ADK wraps it in a Tokenizable rather than a SpooledArtifact; nothing new is queryable on its own. Subsequent forgeTools(ctx) calls exclude ToolCalls produced by an ArtifactTool from the callId enum (via the ToolCall.fromArtifactTool marker) — this is the structural fix that breaks the otherwise-recursive grep-on-the-grep-result loop.

Consumers who want to build their own artifact-query tools (e.g. for a domain-specific spooled subclass not shipped by the ADK) should extend or instantiate this class.

Extends

Tool

Constructors

Constructor

new ArtifactTool(raw: RawArtifactTool): ArtifactTool;

Defined in: src/lib/classes/artifact_tool.ts:171

Parameters

Parameter	Type	Description
`raw`	`RawArtifactTool`	Raw tool input validated against ArtifactTool.schema.

Returns

ArtifactTool

Throws

@nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE when raw does not satisfy ArtifactTool.schema (most commonly, when artifactConstructor is supplied — it is explicitly forbidden on this class) or when the base @nhtio/adk!Tool constructor rejects the input for any reason.

Overrides

Tool.constructor

Properties

Property	Modifier	Type	Description	Overrides	Inherited from	Defined in
`artifactConstructor`	`readonly`	\| `ArtifactConstructorResolver`<`SpooledArtifact`> \| `undefined`	Resolver for the artifact constructor used to wrap the handler's output, if any.	-	`Tool`.`artifactConstructor`	src/lib/classes/tool.ts:232
`description`	`readonly`	`string`	Human/model-facing description of what the tool does.	-	`Tool`.`description`	src/lib/classes/tool.ts:228
`ephemeral`	`readonly`	`boolean`	When `true`, the tool's results are not persisted to history (transient/one-shot).	-	`Tool`.`ephemeral`	src/lib/classes/tool.ts:236
`inputSchema`	`readonly`	`Schema`	Validation schema for the tool's arguments; also drives the generated parameter definition.	-	`Tool`.`inputSchema`	src/lib/classes/tool.ts:230
`meta`	`readonly`	`Registry`	Arbitrary per-tool metadata registry, passed through to the handler.	-	`Tool`.`meta`	src/lib/classes/tool.ts:234
`name`	`readonly`	`string`	The tool's unique name, as exposed to the model in the tool definition.	-	`Tool`.`name`	src/lib/classes/tool.ts:226
`onCollision`	`readonly`	`"keep"` \| `"throw"` \| `"replace"`	How registration resolves a name clash in a ToolRegistry: throw, replace, or keep the existing.	-	`Tool`.`onCollision`	src/lib/classes/tool.ts:240
`trusted`	`readonly`	`boolean`	When `true`, the tool's output is treated as trusted content by the LLM battery's envelopes.	-	`Tool`.`trusted`	src/lib/classes/tool.ts:238
`schema`	`static`	`ObjectSchema`<`RawTool`<`SpooledArtifact`>>	Validator schema that accepts a RawArtifactTool object. Remarks Differs from @nhtio/adk!Tool.schema by forbidding `artifactConstructor` — wrapping is exactly the thing this class opts out of. Typed identically to @nhtio/adk!Tool.schema so the subclass relationship `class ArtifactTool extends Tool` remains structurally sound; the runtime validation rules still differ as declared by `rawArtifactToolSchema`.	`Tool`.`schema`	-	src/lib/classes/artifact_tool.ts:147

Methods

[ENCODE_METHOD]()

ENCODE_METHOD: unknown;

Defined in: src/lib/classes/artifact_tool.ts:196

Serialise this ArtifactTool into an @nhtio/encoder snapshot.

Returns

unknown

A RawArtifactTool-shaped snapshot (with inputSchema as an encoded string).

Remarks

Reuses the base Tool.[ENCODE_METHOD] (function-serialised handler, validation-encoded inputSchema, plain config) and strips artifactConstructor — which ArtifactTool.schema forbids. The handler's closure caveat from Tool.[ENCODE_METHOD] applies here too.

Overrides

Tool.[ENCODE_METHOD]

describe()

describe(): {
  description: string;
  inputSchema: Description;
  name: string;
};

Defined in: src/lib/classes/tool.ts:434

Returns a fully serialisable snapshot of this tool's definition.

Returns

{
  description: string;
  inputSchema: Description;
  name: string;
}

{ name, description, inputSchema } where inputSchema is the schema description.

Name	Type	Defined in
`description`	`string`	src/lib/classes/tool.ts:434
`inputSchema`	`Description`	src/lib/classes/tool.ts:434
`name`	`string`	src/lib/classes/tool.ts:434

Remarks

The inputSchema property is the result of calling .describe() on the raw schema — a plain object carrying all the annotation metadata (descriptions, notes, examples, types) without any validator functions. Use this to build provider-specific LLM tool definitions.

Inherited from

Tool.describe

executor()

executor(ctx: DispatchContext): (args: unknown) => Promise<
  | string
  | SpooledArtifact
  | Uint8Array<ArrayBufferLike>
  | Media
| Media[]>;

Defined in: src/lib/classes/tool.ts:377

Returns a bound executor function for this tool against the given turn context.

Parameters

Parameter	Type	Description
`ctx`	`DispatchContext`	The active turn context. Provides emit functions and turn ID.

Returns

An async function (args) => Promise<string | Uint8Array | SpooledArtifact | Media | Media[]>. A SpooledArtifact is a result the HANDLER built (streamed to storage and wrapped itself); a wrap-site passes it through unwrapped rather than re-spooling it. string/Uint8Array are the opposite case — bytes the consumer must still store and wrap.

Remarks

The executor: (1) computes a stable callId as sha256(canonicalStringify({tool, args})) over the raw, pre-validation args, (2) validates args via Tool.validate, (3) emits toolExecutionStart on the context (with the computed callId), (4) calls the handler, (5) emits toolExecutionEnd (with the same callId), (6) wraps any handler error in @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR before re-throwing.

The handler usually returns serialised bytes (string | Uint8Array) — persistence is then the consumer's concern, and Tool.artifactConstructor is the class a wrap-site uses when wrapping those bytes into a ToolCall.results field. A handler may instead return a @nhtio/adk!SpooledArtifact it built itself (streaming into storage and wrapping the reader), in which case wrap-sites pass it through untouched and artifactConstructor does not apply — the returned instance's own class is what artifact-tool forging reads.

Pattern mirrors Middleware.runner() — call once per turn, reuse the returned function.

Inherited from

Tool.executor

validate()

validate(args: unknown): Promise<unknown>;

Defined in: src/lib/classes/tool.ts:341

Validates args against the tool's input schema asynchronously.

Parameters

Parameter	Type	Description
`args`	`unknown`	The arguments to validate.

Returns

Promise<unknown>

The validated (and coerced) arguments.

Remarks

Async to support schemas with external validators (e.g. database lookups, API calls). A validation failure throws @nhtio/adk!E_INVALID_TOOL_ARGS — this indicates a programming error in the tool call loop, not a downstream failure.

Throws

@nhtio/adk!E_INVALID_TOOL_ARGS when args does not satisfy the input schema.

Inherited from

Tool.validate

[DECODE_METHOD]()

static DECODE_METHOD: ArtifactTool;

Defined in: src/lib/classes/artifact_tool.ts:208

Reconstruct an ArtifactTool from an ArtifactTool.[ENCODE_METHOD] snapshot.

Parameters

Parameter	Type	Description
`data`	`unknown`	The snapshot produced by ArtifactTool.[ENCODE_METHOD].

Returns

ArtifactTool

A fully-validated ArtifactTool.

Overrides

Tool.[DECODE_METHOD]

isArtifactTool()

static isArtifactTool(value: unknown): value is ArtifactTool;

Defined in: src/lib/classes/artifact_tool.ts:159

Returns true if value is an ArtifactTool instance.

Parameters

Parameter	Type	Description
`value`	`unknown`	The value to test.

Returns

value is ArtifactTool

true when value is an ArtifactTool instance.

Remarks

Uses @nhtio/adk!isInstanceOf for cross-realm safety — instanceof would fail for instances created in a different module copy or VM context.

isTool()

static isTool(value: unknown): value is Tool<SpooledArtifact>;

Defined in: src/lib/classes/tool.ts:221

Returns true if value is a Tool instance.

Parameters

Parameter	Type	Description
`value`	`unknown`	The value to test.

Returns

value is Tool<SpooledArtifact>

true when value is a Tool instance.

Inherited from

Tool.isTool

What each pipeline owns

Envelopes

Persistence

Identity and Reasoning

Media

Class: ArtifactTool ​

Remarks ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Throws ​

Overrides ​

Properties ​

Methods ​

[ENCODE_METHOD]() ​

Returns ​

Remarks ​

Overrides ​

describe() ​

Returns ​

Remarks ​

Inherited from ​

executor() ​

Parameters ​

Returns ​

Remarks ​

Inherited from ​

validate() ​

Parameters ​

Returns ​

Remarks ​

Throws ​

Inherited from ​

[DECODE_METHOD]() ​

Parameters ​

Returns ​

Overrides ​

isArtifactTool() ​

Parameters ​

Returns ​

Remarks ​

isTool() ​

Parameters ​

Returns ​

Inherited from ​

Class: ArtifactTool

Remarks

Extends

Constructors

Constructor

Parameters

Returns

Throws

Overrides

Properties

Methods

[ENCODE_METHOD]()

Returns

Remarks

Overrides

describe()

Returns

Remarks

Inherited from

executor()

Parameters

Returns

Remarks

Inherited from

validate()

Parameters

Returns

Remarks

Throws

Inherited from

[DECODE_METHOD]()

Parameters

Returns

Overrides

isArtifactTool()

Parameters

Returns

Remarks

isTool()

Parameters

Returns

Inherited from