@nhtio/adk

Appearance

12 min read · 2,464 words

Class: SpooledToonArtifact ​

Defined in: src/batteries/artifacts/toon/index.ts:90

A @nhtio/adk!SpooledArtifact specialisation that adds TOON-aware read operations.

Remarks ​

Construct with an optional options object to control decoding. When omitted, the TOON is decoded with strict: true (default). Once decoded (on first access), the parsed value is cached for the lifetime of the instance.

All TOON methods are async, consistent with @nhtio/adk!SpooledArtifact.

Path-based methods (toon_get, toon_filter, toon_pluck) use JSONPath-Plus expressions. Full JSONPath syntax is supported, including recursive descent (..), filter expressions ([?(@.age > 18)]), and union selectors.

Extends ​

Constructors ​

Constructor ​

ts
new SpooledToonArtifact(reader: SpoolReader, options?: ToonDecodeOptions): SpooledToonArtifact;

Defined in: src/batteries/artifacts/toon/index.ts:99

Parameters ​

ParameterTypeDescription
readerSpoolReaderThe backing store to read from.
options?ToonDecodeOptionsOptional TOON decode options.

Returns ​

SpooledToonArtifact

Overrides ​

SpooledArtifact.constructor

Properties ​

PropertyModifierTypeDescriptionOverridesDefined in
toolMethodsstaticreadonly ToolMethodDescriptor[]The TOON-specific artifact-query descriptors this class adds on top of the base set. Remarks Lists artifact_toon_type, artifact_toon_keys, artifact_toon_length, artifact_toon_get, artifact_toon_filter, artifact_toon_slice, artifact_toon_pluck. The base seven descriptors (artifact_head, etc.) are NOT included here — they are forged separately by SpooledToonArtifact.forgeTools, which calls SpooledArtifact.forgeTools(ctx) to produce the base-narrowed tools and then registers its own TOON tools on the result. Downstream consumers building custom subclasses should follow the same pattern: own only your own descriptors; override forgeTools to compose with the base output.SpooledArtifact.toolMethodssrc/batteries/artifacts/toon/index.ts:133

Methods ​

[ENCODE_METHOD]() ​

ts
ENCODE_METHOD: unknown;

Defined in: src/batteries/artifacts/toon/index.ts:457

Serialise this SpooledToonArtifact into an @nhtio/encoder snapshot — the reader handle plus the decode options.

Returns ​

unknown

A snapshot consumed by SpooledToonArtifact.[DECODE_METHOD].

Remarks ​

Overrides SpooledArtifact.[ENCODE_METHOD] to carry the constructor's options (the parsed-value cache is derived and not encoded). Round-trips via SpooledToonArtifact.[DECODE_METHOD].

Inherited from ​

SpooledArtifact.[ENCODE_METHOD]

[ENCODE_METHOD]() ​

ts
ENCODE_METHOD: unknown;

Defined in: src/lib/classes/spooled_artifact.ts:314

Serialise this SpooledArtifact into an @nhtio/encoder snapshot — the reader handle, not the bytes.

Returns ​

unknown

A snapshot consumed by SpooledArtifact.[DECODE_METHOD].

Remarks ​

Emits the backing reader's ReaderDescriptor; decode re-binds the reader through the registered resolver. Throws @nhtio/adk!E_READER_NOT_DESCRIBABLE when the reader cannot describe itself. Subclasses override this to include their own discriminators (e.g. @nhtio/adk!SpooledJsonArtifact adds format).

Inherited from ​

ts
SpooledArtifact.[ENCODE_METHOD]

asString() ​

ts
asString(): Promise<string>;

Defined in: src/lib/classes/spooled_artifact.ts:630

Returns the full artifact body as a single byte-faithful string.

Returns ​

Promise<string>

The full content as a single string.

Remarks ​

Round-trip faithful to whatever bytes the @nhtio/adk!SpoolReader was constructed over — preserves trailing newlines and non-\n line terminators that SpooledArtifact.cat discards via its line-based view. This is the canonical primitive for "inline the artifact content directly into a message" use cases.

asString() and the static forgeTools(ctx) factory on each subclass are independent alternatives — a consumer chooses per turn whether to inline the body in a message (await tc.results.asString()) or hand the model query tools (SpooledArtifact.forgeTools(ctx)). Neither calls the other; either works with neither.

Inherited from ​

SpooledArtifact.asString

byteLength() ​

ts
byteLength(): Promise<number>;

Defined in: src/lib/classes/spooled_artifact.ts:501

Returns the total byte length of the underlying data.

Returns ​

Promise<number>

The byte length as reported by the @nhtio/adk!SpoolReader.

Inherited from ​

SpooledArtifact.byteLength

cat() ​

ts
cat(start?: number, end?: number): Promise<string[]>;

Defined in: src/lib/classes/spooled_artifact.ts:482

Returns lines from the artifact, optionally bounded to a range.

Parameters ​

ParameterTypeDescription
start?number0-based start line index (inclusive). Defaults to 0.
end?number0-based end line index (exclusive). Defaults to lineCount().

Returns ​

Promise<string[]>

Array of line strings in the requested range.

Remarks ​

Without arguments, returns all lines — equivalent to POSIX cat. With start and/or end, behaves like Array.prototype.slice: start defaults to 0, end defaults to the total line count, and only lines in [start, end) are fetched from the backing store. For large artifacts, prefer a bounded range or SpooledArtifact.head / SpooledArtifact.tail.

Inherited from ​

SpooledArtifact.cat

estimateHandleTokens() ​

ts
estimateHandleTokens(
   callId: string,
   encoding:
  | "gpt2"
  | "r50k_base"
  | "p50k_base"
  | "p50k_edit"
  | "cl100k_base"
  | "o200k_base"
  | "gemini"
  | "gemma"
  | "llama2"
  | "claude",
   renderer?: (input: {
  artifact: unknown;
  byteLength: number;
  callId: string;
  encoding?: string;
  estimatedTokens?: number;
  lineCount: number;
}) => string): number;

Defined in: src/lib/classes/spooled_artifact.ts:547

Estimates tokens for the exact handle-body metadata rendered for this artifact.

The fallback renderer is an interim core-safe implementation. Its output is deliberately specified here for fan-in parity: the lines are the fixed prose and metadata strings below, with one \n separator, and method entries formatted as - name — description (or - name). The canonical renderer in chat_common should eventually delegate to this builder rather than maintain a second copy.

Parameters ​

ParameterTypeDescription
callIdstringThe turn-local artifact identifier.
encoding| "gpt2" | "r50k_base" | "p50k_base" | "p50k_edit" | "cl100k_base" | "o200k_base" | "gemini" | "gemma" | "llama2" | "claude"The token encoding used for estimation.
renderer?(input: { artifact: unknown; byteLength: number; callId: string; encoding?: string; estimatedTokens?: number; lineCount: number; }) => stringOptional renderer overriding the interim default.

Returns ​

number

A synchronous token estimate.

Inherited from ​

SpooledArtifact.estimateHandleTokens

estimateTokens() ​

ts
estimateTokens(encoding:
  | "gpt2"
  | "r50k_base"
  | "p50k_base"
  | "p50k_edit"
  | "cl100k_base"
  | "o200k_base"
  | "gemini"
  | "gemma"
  | "llama2"
| "claude"): Promise<number>;

Defined in: src/lib/classes/spooled_artifact.ts:609

Estimates the total token count of the artifact under encoding.

Parameters ​

ParameterTypeDescription
encoding| "gpt2" | "r50k_base" | "p50k_base" | "p50k_edit" | "cl100k_base" | "o200k_base" | "gemini" | "gemma" | "llama2" | "claude"The encoding identifier to use for counting.

Returns ​

Promise<number>

The estimated number of tokens.

Remarks ​

Reads the full byte-faithful content via SpooledArtifact.asString (which delegates to @nhtio/adk!SpoolReader.readAll) and delegates to @nhtio/adk!Tokenizable.estimateTokens. The estimate therefore reflects the actual source bytes — including trailing newlines and non-\n line terminators that the line-based SpooledArtifact.cat view would otherwise discard or misrepresent.

Inherited from ​

SpooledArtifact.estimateTokens

grep() ​

ts
grep(pattern: RegExp): Promise<string[]>;

Defined in: src/lib/classes/spooled_artifact.ts:454

Returns all lines that match pattern.

Parameters ​

ParameterTypeDescription
patternRegExpThe regular expression to test each line against.

Returns ​

Promise<string[]>

Array of matching line strings, in order.

Remarks ​

Behaves like POSIX grep: each line is tested against the pattern and included in the result when it matches. The pattern is applied as a JavaScript RegExp; flags (e.g. case- insensitivity) should be encoded in the expression itself.

Stateful flags (g, y) on the supplied RegExp would normally cause pattern.test() to advance lastIndex across calls, producing skipped matches and order-dependent results. To keep the per-line semantics stateless, grep resets pattern.lastIndex to 0 before each line test. The forged artifact_grep tool also rejects g and y flags up-front at schema validation time.

Inherited from ​

SpooledArtifact.grep

hasSizeHints() ​

ts
hasSizeHints(): boolean;

Defined in: src/lib/classes/spooled_artifact.ts:520

Returns whether producer-computed size metadata is available.

Returns ​

boolean

true when SpooledArtifact._setSizeHints has populated the cache.

Inherited from ​

SpooledArtifact.hasSizeHints

ts
head(n?: number): Promise<string[]>;

Defined in: src/lib/classes/spooled_artifact.ts:401

Returns the first n lines of the artifact.

Parameters ​

ParameterTypeDefault valueDescription
nnumber10Number of lines to return. Defaults to 10.

Returns ​

Promise<string[]>

Array of line strings, without trailing newlines.

Remarks ​

If the artifact contains fewer than n lines, all available lines are returned. Matches the behaviour of POSIX head -n.

Inherited from ​

SpooledArtifact.head

lineCount() ​

ts
lineCount(): Promise<number>;

Defined in: src/lib/classes/spooled_artifact.ts:529

Returns the total number of lines in the artifact.

Returns ​

Promise<number>

The line count as reported by the @nhtio/adk!SpoolReader.

Inherited from ​

SpooledArtifact.lineCount

tail() ​

ts
tail(n?: number): Promise<string[]>;

Defined in: src/lib/classes/spooled_artifact.ts:424

Returns the last n lines of the artifact.

Parameters ​

ParameterTypeDefault valueDescription
nnumber10Number of lines to return. Defaults to 10.

Returns ​

Promise<string[]>

Array of line strings, without trailing newlines.

Remarks ​

If the artifact contains fewer than n lines, all available lines are returned. Matches the behaviour of POSIX tail -n.

Inherited from ​

SpooledArtifact.tail

toon_filter() ​

ts
toon_filter(path: string): Promise<unknown[]>;

Defined in: src/batteries/artifacts/toon/index.ts:406

Returns elements matched by a JSONPath filter expression.

Parameters ​

ParameterTypeDescription
pathstringA JSONPath expression (e.g. '$[?(@.status === "active")]').

Returns ​

Promise<unknown[]>

Array of matching elements (at most one element, the root if matched).

Remarks ​

Evaluates path against the root value and returns it in an array if matched.

toon_get() ​

ts
toon_get(path: string): Promise<unknown[]>;

Defined in: src/batteries/artifacts/toon/index.ts:392

Evaluates a JSONPath expression against the parsed TOON content.

Parameters ​

ParameterTypeDescription
pathstringA JSONPath expression (e.g. '$.user.address.city', '$..name').

Returns ​

Promise<unknown[]>

Array of matched values. Empty array when no matches are found.

Remarks ​

Uses JSONPath-Plus. Full JSONPath syntax is supported: recursive descent ($..*), filter expressions ($[?(@.age > 18)]), union selectors, and more.

toon_keys() ​

ts
toon_keys(): Promise<string[] | undefined>;

Defined in: src/batteries/artifacts/toon/index.ts:356

Returns the top-level keys of the parsed TOON content.

Returns ​

Promise<string[] | undefined>

Array of key strings, or undefined when the root is not an object.

Remarks ​

  • If the root is an object, returns its keys.
  • If the root is not a plain object (e.g. an array or scalar), returns undefined.

toon_length() ​

ts
toon_length(): Promise<number>;

Defined in: src/batteries/artifacts/toon/index.ts:373

Returns the element count of the parsed TOON content.

Returns ​

Promise<number>

The element count.

Remarks ​

  • If the root is an array, returns the array length.
  • Otherwise, returns 1 (the root is a single element).

toon_pluck() ​

ts
toon_pluck(path: string): Promise<unknown[]>;

Defined in: src/batteries/artifacts/toon/index.ts:442

Returns all values matched by a JSONPath expression.

Parameters ​

ParameterTypeDescription
pathstringA JSONPath expression (e.g. '$..name').

Returns ​

Promise<unknown[]>

Array of matched values.

Remarks ​

Convenience over SpooledToonArtifact.toon_get with an identical signature — use whichever name better communicates intent at the call site. toon_pluck reads well for extracting a single field; toon_get reads well for structured queries.

toon_slice() ​

ts
toon_slice(start?: number, end?: number): Promise<unknown[]>;

Defined in: src/batteries/artifacts/toon/index.ts:423

Returns a slice of the parsed content by index range.

Parameters ​

ParameterTypeDescription
start?numberStart index (inclusive). Defaults to 0.
end?numberEnd index (exclusive). Defaults to the element count.

Returns ​

Promise<unknown[]>

Array of sliced elements.

Remarks ​

  • If the root is an array, behaves like Array.prototype.slice.
  • If the root is not an array, returns the entire root in an array.

toon_type() ​

ts
toon_type(): Promise<{
  format: string;
}>;

Defined in: src/batteries/artifacts/toon/index.ts:342

Returns the format of a TOON artifact.

Returns ​

Promise<{ format: string; }>

An object with format: 'toon'.

Remarks ​

Reports only the format name. The delimiter is deliberately not reported: the TOON decoder exposes no delimiter information, and every method of inferring one from the source proved unreliable for some class of strict-valid document. Four distinct approaches were attempted, each defeated by its own edge case:

  • Lexical scanning for the delimiter character failed on unquoted pipes inside values
  • Anchored header regex requiring a word key failed on quoted keys and keyless root arrays
  • Widened regex accepting quoted keys failed on escaped quotes within the key (e.g., "a"b")
  • Byte-exact round-trip re-encoding failed on non-canonical formatting (indentation, line endings, trailing newlines)

Delimiter inference is no longer attempted: nothing in the model's workflow needs it, and the TOON decoder is the source of truth for all document metadata.

This result is cached after the first parse and returned identically on every call.

[DECODE_METHOD]() ​

ts
static DECODE_METHOD: SpooledToonArtifact;

Defined in: src/batteries/artifacts/toon/index.ts:468

Reconstruct a SpooledToonArtifact from a SpooledToonArtifact.[ENCODE_METHOD] snapshot.

Parameters ​

ParameterTypeDescription
dataunknownThe snapshot produced by SpooledToonArtifact.[ENCODE_METHOD].

Returns ​

SpooledToonArtifact

A fresh SpooledToonArtifact} backed by a freshly-resolved reader.

Inherited from ​

SpooledArtifact.[DECODE_METHOD]

[DECODE_METHOD]() ​

ts
static DECODE_METHOD: SpooledArtifact;

Defined in: src/lib/classes/spooled_artifact.ts:328

Reconstruct a SpooledArtifact from an SpooledArtifact.[ENCODE_METHOD] snapshot.

Parameters ​

ParameterTypeDescription
dataunknownThe snapshot produced by SpooledArtifact.[ENCODE_METHOD].

Returns ​

SpooledArtifact

A fresh SpooledArtifact backed by a freshly-resolved reader.

Remarks ​

Re-binds the reader via @nhtio/adk!resolveSpoolReader; throws @nhtio/adk!E_NO_READER_RESOLVER when no resolver is registered for the descriptor's tag.

Inherited from ​

ts
SpooledArtifact.[DECODE_METHOD]

forgeTools() ​

ts
static forgeTools(ctx: DispatchContext): ToolRegistry;

Defined in: src/batteries/artifacts/toon/index.ts:209

Forges base-class tools plus TOON-specific tools narrowed to SpooledToonArtifact.

Parameters ​

ParameterType
ctxDispatchContext

Returns ​

ToolRegistry

Remarks ​

Standard subclass extension pattern: call SpooledArtifact.forgeTools(ctx) to produce the base seven artifact_* tools narrowed to any SpooledArtifact in the turn, then register one ArtifactTool per TOON-specific descriptor narrowed to TOON artifacts. Downstream consumers building their own subclasses should follow the same shape.

Overrides ​

SpooledArtifact.forgeTools

isSpooledArtifact() ​

ts
static isSpooledArtifact(value: unknown): value is SpooledArtifact;

Defined in: src/lib/classes/spooled_artifact.ts:361

Returns true if value is a SpooledArtifact instance (including any subclass).

Parameters ​

ParameterTypeDescription
valueunknownThe value to test.

Returns ​

value is SpooledArtifact

true when value is a SpooledArtifact instance.

Remarks ​

Uses the cross-realm-safe @nhtio/adk!isInstanceOf guard: instanceof first, then Symbol.hasInstance, then a constructor.name fallback. Subclass instances (e.g. @nhtio/adk!SpooledJsonArtifact) satisfy this guard because instanceof walks the prototype chain. The fallbacks handle the dual-module-copy case where two distinct SpooledArtifact classes coexist in the same realm (e.g. one bundled into a downstream library, one in the consumer's node_modules).

Inherited from ​

SpooledArtifact.isSpooledArtifact

isSpooledArtifactConstructor() ​

ts
static isSpooledArtifactConstructor(value: unknown): value is SpooledArtifactConstructor<SpooledArtifact>;

Defined in: src/lib/classes/spooled_artifact.ts:378

Returns true if value is a constructor function whose prototype chain includes SpooledArtifact (including SpooledArtifact itself).

Parameters ​

ParameterTypeDescription
valueunknownThe value to test.

Returns ​

value is SpooledArtifactConstructor<SpooledArtifact>

true when value is a constructor for SpooledArtifact or a subclass.

Remarks ​

Used by @nhtio/adk!Tool to validate the optional artifactConstructor field. Performs an instanceof-based check on the prototype chain; falls back to a duck-type test that looks for the canonical SpooledArtifact instance methods on value.prototype for cross-realm safety (constructors passed from a different module copy or VM context).

Inherited from ​

SpooledArtifact.isSpooledArtifactConstructor

isSpooledToonArtifact() ​

ts
static isSpooledToonArtifact(value: unknown): value is SpooledToonArtifact;

Defined in: src/batteries/artifacts/toon/index.ts:116

Returns true if value is a SpooledToonArtifact instance.

Parameters ​

ParameterTypeDescription
valueunknownThe value to test.

Returns ​

value is SpooledToonArtifact

true when value is a SpooledToonArtifact instance.

Remarks ​

Uses the cross-realm-safe @nhtio/adk!isInstanceOf guard: instanceof first, then Symbol.hasInstance, then a constructor.name fallback. Matches the pattern used by every other class guard in the ADK; safe against the dual-module-copy case where two distinct SpooledToonArtifact classes coexist in the same realm.

Copyright © 2025-present New Horizon Technology LTD