--- url: >- https://adk.nht.io/api/@nhtio/adk/spooled_artifact/classes/SpooledMarkdownArtifact.md description: >- A {@link @nhtio/adk!SpooledArtifact} specialisation that adds markdown-aware structural queries. --- # Class: SpooledMarkdownArtifact Defined in: [lib/classes/spooled\_markdown\_artifact.ts:129](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_markdown_artifact.ts#L129) A [@nhtio/adk!SpooledArtifact](SpooledArtifact.md) specialisation that adds markdown-aware structural queries. ## Remarks Designed for large markdown documents where loading the full content into memory is impractical. The structural index (heading positions, code block positions) is built by a single line-by-line scan of the [@nhtio/adk!SpoolReader](../interfaces/SpoolReader.md) without retaining any content. Only the tiny metadata index and the parsed frontmatter object are cached. Content retrieval is always bounded — use `cat(start, end)` or the `startLine`/`endLine` parameters on inline methods to fetch only the lines you need. Inline methods (`md_links`, `md_images`, `md_text`, `md_ast`) accept optional line-range arguments. Without a range they read the full document — documented trade-off, caller responsibility to bound the range for large documents. The processor always applies `remark-gfm` (tables, task lists, strikethrough, autolinks) in addition to standard CommonMark and YAML frontmatter. ## Extends * [`SpooledArtifact`](SpooledArtifact.md) ## Constructors ### Constructor ```ts new SpooledMarkdownArtifact(reader: SpoolReader): SpooledMarkdownArtifact; ``` Defined in: [lib/classes/spooled\_markdown\_artifact.ts:136](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_markdown_artifact.ts#L136) #### Parameters | Parameter | Type | Description | | --------- | --------------------------------------------- | ------------------------------- | | `reader` | [`SpoolReader`](../interfaces/SpoolReader.md) | The backing store to read from. | #### Returns `SpooledMarkdownArtifact` #### Overrides [`SpooledArtifact`](SpooledArtifact.md).[`constructor`](SpooledArtifact.md#constructor) ## Properties | Property | Modifier | Type | Description | Overrides | Defined in | | ----------------------------------------------- | -------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `toolMethods` | `static` | readonly [`ToolMethodDescriptor`](../../common/interfaces/ToolMethodDescriptor.md)\[] | The markdown-specific artifact-query descriptors this class adds on top of the base set. **Remarks** Lists `artifact_md_frontmatter`, `artifact_md_headings`, `artifact_md_code_blocks`, `artifact_md_sections`, `artifact_md_links`, `artifact_md_images`, `artifact_md_text`, `artifact_md_ast`. The base seven descriptors (`artifact_head`, etc.) are NOT included here — they are forged separately by [SpooledMarkdownArtifact.forgeTools](#forgetools), which calls `SpooledArtifact.forgeTools(ctx)` to produce the base-narrowed tools and then registers its own markdown 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`](SpooledArtifact.md).[`toolMethods`](SpooledArtifact.md#property-toolmethods) | [lib/classes/spooled\_markdown\_artifact.ts:166](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_markdown_artifact.ts#L166) | ## Methods ### asString() ```ts asString(): Promise; ``` Defined in: [lib/classes/spooled\_artifact.ts:421](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L421) 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](../interfaces/SpoolReader.md) was constructed over — preserves trailing newlines and non-`\n` line terminators that [SpooledArtifact.cat](SpooledArtifact.md#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`](SpooledArtifact.md).[`asString`](SpooledArtifact.md#asstring) *** ### byteLength() ```ts byteLength(): Promise; ``` Defined in: [lib/classes/spooled\_artifact.ts:374](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L374) Returns the total byte length of the underlying data. #### Returns `Promise`<`number`> The byte length as reported by the [@nhtio/adk!SpoolReader](../interfaces/SpoolReader.md). #### Inherited from [`SpooledArtifact`](SpooledArtifact.md).[`byteLength`](SpooledArtifact.md#bytelength) *** ### cat() ```ts cat(start?: number, end?: number): Promise; ``` Defined in: [lib/classes/spooled\_artifact.ts:355](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L355) Returns lines from the artifact, optionally bounded to a range. #### Parameters | Parameter | Type | Description | | --------- | -------- | -------------------------------------------------------------- | | `start?` | `number` | 0-based start line index (inclusive). Defaults to `0`. | | `end?` | `number` | 0-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.md#head) / [SpooledArtifact.tail](SpooledArtifact.md#tail). #### Inherited from [`SpooledArtifact`](SpooledArtifact.md).[`cat`](SpooledArtifact.md#cat) *** ### estimateTokens() ```ts estimateTokens(encoding: | "gpt2" | "r50k_base" | "p50k_base" | "p50k_edit" | "cl100k_base" | "o200k_base" | "gemini" | "llama2" | "claude"): Promise; ``` Defined in: [lib/classes/spooled\_artifact.ts:400](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L400) Estimates the total token count of the artifact under `encoding`. #### Parameters | Parameter | Type | Description | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | `encoding` | | `"gpt2"` | `"r50k_base"` | `"p50k_base"` | `"p50k_edit"` | `"cl100k_base"` | `"o200k_base"` | `"gemini"` | `"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](SpooledArtifact.md#asstring) (which delegates to [@nhtio/adk!SpoolReader.readAll](../interfaces/SpoolReader.md#readall)) and delegates to [@nhtio/adk!Tokenizable.estimateTokens](../../common/classes/Tokenizable.md#estimatetokens). The estimate therefore reflects the actual source bytes — including trailing newlines and non-`\n` line terminators that the line-based [SpooledArtifact.cat](SpooledArtifact.md#cat) view would otherwise discard or misrepresent. #### Inherited from [`SpooledArtifact`](SpooledArtifact.md).[`estimateTokens`](SpooledArtifact.md#estimatetokens) *** ### grep() ```ts grep(pattern: RegExp): Promise; ``` Defined in: [lib/classes/spooled\_artifact.ts:327](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L327) Returns all lines that match `pattern`. #### Parameters | Parameter | Type | Description | | --------- | -------- | ------------------------------------------------- | | `pattern` | `RegExp` | The 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`](SpooledArtifact.md).[`grep`](SpooledArtifact.md#grep) *** ### head() ```ts head(n?: number): Promise; ``` Defined in: [lib/classes/spooled\_artifact.ts:274](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L274) Returns the first `n` lines of the artifact. #### Parameters | Parameter | Type | Default value | Description | | --------- | -------- | ------------- | ------------------------------------------ | | `n` | `number` | `10` | Number 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`](SpooledArtifact.md).[`head`](SpooledArtifact.md#head) *** ### lineCount() ```ts lineCount(): Promise; ``` Defined in: [lib/classes/spooled\_artifact.ts:383](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L383) Returns the total number of lines in the artifact. #### Returns `Promise`<`number`> The line count as reported by the [@nhtio/adk!SpoolReader](../interfaces/SpoolReader.md). #### Inherited from [`SpooledArtifact`](SpooledArtifact.md).[`lineCount`](SpooledArtifact.md#linecount) *** ### md\_ast() ```ts md_ast(startLine?: number, endLine?: number): Promise; ``` Defined in: [lib/classes/spooled\_markdown\_artifact.ts:573](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_markdown_artifact.ts#L573) Returns the full MDAST Root for the specified line range. #### Parameters | Parameter | Type | Description | | ------------ | -------- | -------------------------------------------------------- | | `startLine?` | `number` | 0-based start line (inclusive). Defaults to `0`. | | `endLine?` | `number` | 0-based end line (exclusive). Defaults to `lineCount()`. | #### Returns `Promise`<`Root`> #### Remarks Without a range, reads the full document — for large documents, use [SpooledMarkdownArtifact.md\_sections](#md_sections) to locate sections and pass bounded line ranges here. *** ### md\_code\_blocks() ```ts md_code_blocks(lang?: string): Promise; ``` Defined in: [lib/classes/spooled\_markdown\_artifact.ts:528](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_markdown_artifact.ts#L528) Returns all fenced code block entries, optionally filtered by language identifier. #### Parameters | Parameter | Type | Description | | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `lang?` | `string` | When provided, only blocks with this exact lang identifier are returned. Pass an empty string to match blocks with no lang identifier. | #### Returns `Promise`<[`MarkdownCodeEntry`](../interfaces/MarkdownCodeEntry.md)\[]> #### Remarks Returns line-range metadata only — no content is fetched. Use `cat(entry.startLine + 1, entry.endLine)` to retrieve the code body (excluding fence lines). *** ### md\_frontmatter() ```ts md_frontmatter(): Promise< | Record | undefined>; ``` Defined in: [lib/classes/spooled\_markdown\_artifact.ts:472](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_markdown_artifact.ts#L472) Returns the parsed YAML frontmatter, or `undefined` when no frontmatter block is present. #### Returns `Promise`< | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, `unknown`> | `undefined`> #### Remarks Short-circuits after reading the frontmatter block — never reads the document body. Caches the result so subsequent calls are free. The result is `undefined` (not an empty object) when no frontmatter is found, distinguishing "no frontmatter" from "empty frontmatter". *** ### md\_headings() ```ts md_headings(depth?: 1 | 2 | 3 | 4 | 5 | 6): Promise; ``` Defined in: [lib/classes/spooled\_markdown\_artifact.ts:512](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_markdown_artifact.ts#L512) Returns all headings in document order, optionally filtered by depth. #### Parameters | Parameter | Type | Description | | --------- | -------------------------------------- | ------------------------------------------------------------------ | | `depth?` | `1` | `2` | `3` | `4` | `5` | `6` | When provided, only headings at this ATX depth (1–6) are returned. | #### Returns `Promise`<[`MarkdownHeadingEntry`](../interfaces/MarkdownHeadingEntry.md)\[]> #### Remarks Uses the cached structural index — no content is fetched from the [@nhtio/adk!SpoolReader](../interfaces/SpoolReader.md). *** ### md\_images() ```ts md_images(startLine?: number, endLine?: number): Promise<{ alt: string; title?: string; url: string; }[]>; ``` Defined in: [lib/classes/spooled\_markdown\_artifact.ts:607](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_markdown_artifact.ts#L607) Returns all images in the specified line range. #### Parameters | Parameter | Type | Description | | ------------ | -------- | -------------------------------------------------------- | | `startLine?` | `number` | 0-based start line (inclusive). Defaults to `0`. | | `endLine?` | `number` | 0-based end line (exclusive). Defaults to `lineCount()`. | #### Returns `Promise`<{ `alt`: `string`; `title?`: `string`; `url`: `string`; }\[]> *** ### md\_links() ```ts md_links(startLine?: number, endLine?: number): Promise<{ text: string; title?: string; url: string; }[]>; ``` Defined in: [lib/classes/spooled\_markdown\_artifact.ts:584](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_markdown_artifact.ts#L584) Returns all inline and reference links in the specified line range. #### Parameters | Parameter | Type | Description | | ------------ | -------- | -------------------------------------------------------- | | `startLine?` | `number` | 0-based start line (inclusive). Defaults to `0`. | | `endLine?` | `number` | 0-based end line (exclusive). Defaults to `lineCount()`. | #### Returns `Promise`<{ `text`: `string`; `title?`: `string`; `url`: `string`; }\[]> *** ### md\_sections() ```ts md_sections(depth?: 1 | 2 | 3 | 4 | 5 | 6): Promise; ``` Defined in: [lib/classes/spooled\_markdown\_artifact.ts:547](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_markdown_artifact.ts#L547) Returns document sections derived from the structural index. #### Parameters | Parameter | Type | Description | | --------- | -------------------------------------- | ------------------------------------------------------------------ | | `depth?` | `1` | `2` | `3` | `4` | `5` | `6` | When provided, only sections at this ATX depth (1–6) are returned. | #### Returns `Promise`<[`MarkdownSection`](../interfaces/MarkdownSection.md)\[]> #### Remarks Returns only line-range metadata — body content is never fetched. To retrieve the body of a section, call `cat(section.bodyStartLine, section.bodyEndLine + 1)`. When `depth` is provided, only sections introduced by a heading at that depth are returned; deeper headings become part of the body. *** ### md\_text() ```ts md_text(startLine?: number, endLine?: number): Promise; ``` Defined in: [lib/classes/spooled\_markdown\_artifact.ts:634](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_markdown_artifact.ts#L634) Returns all document text with markup stripped, for the specified line range. #### Parameters | Parameter | Type | Description | | ------------ | -------- | -------------------------------------------------------- | | `startLine?` | `number` | 0-based start line (inclusive). Defaults to `0`. | | `endLine?` | `number` | 0-based end line (exclusive). Defaults to `lineCount()`. | #### Returns `Promise`<`string`> #### Remarks Uses `mdast-util-to-string` to extract plain text from the AST — code, link text, and alt text are included; markdown syntax is removed. *** ### tail() ```ts tail(n?: number): Promise; ``` Defined in: [lib/classes/spooled\_artifact.ts:297](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L297) Returns the last `n` lines of the artifact. #### Parameters | Parameter | Type | Default value | Description | | --------- | -------- | ------------- | ------------------------------------------ | | `n` | `number` | `10` | Number 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`](SpooledArtifact.md).[`tail`](SpooledArtifact.md#tail) *** ### forgeTools() ```ts static forgeTools(ctx: DispatchContext): ToolRegistry; ``` Defined in: [lib/classes/spooled\_markdown\_artifact.ts:309](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_markdown_artifact.ts#L309) Forges base-class tools plus markdown-specific tools narrowed to SpooledMarkdownArtifact. #### Parameters | Parameter | Type | | --------- | -------------------------------------------------------------- | | `ctx` | [`DispatchContext`](../../types/interfaces/DispatchContext.md) | #### Returns [`ToolRegistry`](../../forge/classes/ToolRegistry.md) #### 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 markdown-specific descriptor narrowed to markdown artifacts. Downstream consumers building their own subclasses should follow the same shape. #### Overrides [`SpooledArtifact`](SpooledArtifact.md).[`forgeTools`](SpooledArtifact.md#forgetools) *** ### isSpooledArtifact() ```ts static isSpooledArtifact(value: unknown): value is SpooledArtifact; ``` Defined in: [lib/classes/spooled\_artifact.ts:234](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L234) Returns `true` if `value` is a [SpooledArtifact](SpooledArtifact.md) instance (including any subclass). #### Parameters | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to test. | #### Returns `value is SpooledArtifact` `true` when `value` is a [SpooledArtifact](SpooledArtifact.md) instance. #### Remarks Uses the cross-realm-safe [@nhtio/adk!isInstanceOf](../../guards/functions/isInstanceOf.md) guard: `instanceof` first, then `Symbol.hasInstance`, then a `constructor.name` fallback. Subclass instances (e.g. [@nhtio/adk!SpooledJsonArtifact](SpooledJsonArtifact.md)) 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`](SpooledArtifact.md).[`isSpooledArtifact`](SpooledArtifact.md#isspooledartifact) *** ### isSpooledArtifactConstructor() ```ts static isSpooledArtifactConstructor(value: unknown): value is SpooledArtifactConstructor; ``` Defined in: [lib/classes/spooled\_artifact.ts:251](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_artifact.ts#L251) Returns `true` if `value` is a constructor function whose prototype chain includes [SpooledArtifact](SpooledArtifact.md) (including `SpooledArtifact` itself). #### Parameters | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to test. | #### Returns `value is SpooledArtifactConstructor` `true` when `value` is a constructor for `SpooledArtifact` or a subclass. #### Remarks Used by [@nhtio/adk!Tool](../../forge/classes/Tool.md) 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`](SpooledArtifact.md).[`isSpooledArtifactConstructor`](SpooledArtifact.md#isspooledartifactconstructor) *** ### isSpooledMarkdownArtifact() ```ts static isSpooledMarkdownArtifact(value: unknown): value is SpooledMarkdownArtifact; ``` Defined in: [lib/classes/spooled\_markdown\_artifact.ts:149](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/spooled_markdown_artifact.ts#L149) Returns `true` if `value` is a SpooledMarkdownArtifact instance. #### Parameters | Parameter | Type | | --------- | --------- | | `value` | `unknown` | #### Returns `value is SpooledMarkdownArtifact` #### Remarks Uses the cross-realm-safe [@nhtio/adk!isInstanceOf](../../guards/functions/isInstanceOf.md) 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 `SpooledMarkdownArtifact` classes coexist in the same realm.