@getfamiliar/shared 0.1.2

package/build/ToolRunner.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Tool-call runner: the shared machinery every agent-facing tool uses
+ * to package its result. Three flavors — JSON object, JSON Lines, free
+ * text — picked by the tool's `execute` based on what shape it wants
+ * the agent to see.
+ *
+ * Two responsibilities only:
+ *
+ *   - **Truncation / offloading.** When the serialized result's
+ *     estimated token count (see {@link estimateTokens}) exceeds
+ *     {@link ToolRunContext.limit}, the runner spills the *full*
+ *     result to a scratch file via {@link ToolRunContext.spill} and
+ *     returns either a sentinel ({@link OffloadedJson} for the JSON
+ *     runner) or a partial-with-marker (JSONL / text runners). The
+ *     spilled file always carries the complete content so the agent
+ *     can `fs_read` it for the missing portion.
+ *   - **Letting throws propagate.** Failure is signalled by throwing.
+ *     The Vercel AI SDK turns any throw into a `tool-error` block;
+ *     tools that want a clean message catch and re-throw a
+ *     {@link ToolError} inside their own body. The runners do not
+ *     transform errors.
+ *
+ * Note: success bodies are *not* wrapped in `{ok:true,...}`. The agent
+ * receives the bare value (object, JSONL string, or text string).
+ */
+import { Buffer } from "node:buffer";
+/**
+ * Default token cap when no config override and no frontmatter override
+ * is set. Also doubles as the upper bound in the model-relative offload
+ * threshold `min(0.25 * contextLimit, cap)` computed in the agent runner,
+ * and as the host gateway's fallback when a caller sends no limit.
+ */
+export declare const DEFAULT_TOOL_CALL_OFFLOADING_LIMIT = 16000;
+/**
+ * Convenience throwable for tool bodies that want to attach a stable
+ * machine-readable `code` (e.g. `"ErrorItemNotFound"`) and optional
+ * HTTP-flavored `status` alongside the human message. The Vercel SDK
+ * doesn't surface these fields in `tool-error` blocks, but the gateway
+ * transports them across HTTP so transcripts and tests can match on
+ * `code` instead of fuzzy-matching on `message`.
+ *
+ * Plain `Error` throws work too — they propagate verbatim with
+ * `code = "ToolError"` synthesized at the wire boundary.
+ */
+export declare class ToolError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    constructor(code: string, message: string, status?: number | undefined);
+}
+/**
+ * Per-call context handed to every runner. Constructed by whichever
+ * side (host gateway / container tool wrapper) owns the agentrun.
+ *
+ *   - `limit`: token budget for the inline response (compared against
+ *     {@link estimateTokens} of the serialized result). Resolved per-call
+ *     from handler frontmatter → env var / config → default.
+ *   - `spill`: writes the full result under `/scratch/<event-id>/` and
+ *     returns the absolute path the agent can later `fs_read`.
+ *     Implementations dedupe basenames so concurrent calls don't
+ *     clobber each other.
+ */
+export interface ToolRunContext {
+    readonly limit: number;
+    spill(suggestedName: string, contents: Buffer): Promise<string>;
+}
+/**
+ * Sentinel returned by {@link runJsonTool} when the serialized result
+ * exceeds the byte budget. The agent should `fs_read` the path for
+ * the actual content.
+ */
+export interface OffloadedJson {
+    readonly truncated: true;
+    readonly fullResultAt: string;
+    readonly reason: string;
+}
+/**
+ * Run a tool whose result is a single JSON object. If the
+ * `JSON.stringify`'d result's estimated token count is at or below the
+ * limit, returns the object verbatim. Otherwise spills the full JSON to
+ * scratch and returns {@link OffloadedJson}.
+ *
+ * No partial JSON is exposed — an oversized result is either fully
+ * inline or fully offloaded. The body is expected to throw on failure;
+ * the runner does not catch.
+ */
+export declare function runJsonTool(body: () => Promise<object>, ctx: ToolRunContext): Promise<object>;
+/**
+ * Run a tool whose result is a stream of JSON objects, serialized as
+ * newline-delimited JSON. If the total fits within the limit, returns
+ * all lines joined with `\n`. Otherwise spills the full JSONL to
+ * scratch and returns the leading whole lines that fit, followed by a
+ * marker line:
+ *
+ *   `{"truncated":true,"fullResultAt":"<path>","omittedLines":<N>}`
+ *
+ * Edge case: when even the first line plus the marker exceeds the
+ * limit, only the marker is returned (`omittedLines` then equals the
+ * total line count).
+ */
+export declare function runJsonLinesTool(body: () => Promise<Iterable<object> | AsyncIterable<object>>, ctx: ToolRunContext): Promise<string>;
+/**
+ * Run a tool whose result is free text. If the text fits the limit,
+ * returns it verbatim. Otherwise spills the full text to scratch and
+ * returns a truncated prefix followed by a footer pointing at the
+ * scratch path:
+ *
+ *   `<truncated text>\n\n[truncated; full result at <path>]`
+ *
+ * The truncation respects UTF-8 code-point boundaries so multi-byte
+ * characters never get split.
+ */
+export declare function runTextTool(body: () => Promise<string>, ctx: ToolRunContext): Promise<string>;
+/**
+ * Truncate `str` to at most `maxBytes` UTF-8 bytes without splitting a
+ * code point. Surrogate pairs (code points beyond the BMP) are kept
+ * together.
+ */
+export declare function truncateUtf8(str: string, maxBytes: number): string;

package/build/ToolRunner.js

@@ -0,0 +1,192 @@
+/**
+ * Tool-call runner: the shared machinery every agent-facing tool uses
+ * to package its result. Three flavors — JSON object, JSON Lines, free
+ * text — picked by the tool's `execute` based on what shape it wants
+ * the agent to see.
+ *
+ * Two responsibilities only:
+ *
+ *   - **Truncation / offloading.** When the serialized result's
+ *     estimated token count (see {@link estimateTokens}) exceeds
+ *     {@link ToolRunContext.limit}, the runner spills the *full*
+ *     result to a scratch file via {@link ToolRunContext.spill} and
+ *     returns either a sentinel ({@link OffloadedJson} for the JSON
+ *     runner) or a partial-with-marker (JSONL / text runners). The
+ *     spilled file always carries the complete content so the agent
+ *     can `fs_read` it for the missing portion.
+ *   - **Letting throws propagate.** Failure is signalled by throwing.
+ *     The Vercel AI SDK turns any throw into a `tool-error` block;
+ *     tools that want a clean message catch and re-throw a
+ *     {@link ToolError} inside their own body. The runners do not
+ *     transform errors.
+ *
+ * Note: success bodies are *not* wrapped in `{ok:true,...}`. The agent
+ * receives the bare value (object, JSONL string, or text string).
+ */
+import { Buffer } from "node:buffer";
+import { estimateTokens } from "./estimateTokens.js";
+/**
+ * Default token cap when no config override and no frontmatter override
+ * is set. Also doubles as the upper bound in the model-relative offload
+ * threshold `min(0.25 * contextLimit, cap)` computed in the agent runner,
+ * and as the host gateway's fallback when a caller sends no limit.
+ */
+export const DEFAULT_TOOL_CALL_OFFLOADING_LIMIT = 16000;
+/**
+ * Convenience throwable for tool bodies that want to attach a stable
+ * machine-readable `code` (e.g. `"ErrorItemNotFound"`) and optional
+ * HTTP-flavored `status` alongside the human message. The Vercel SDK
+ * doesn't surface these fields in `tool-error` blocks, but the gateway
+ * transports them across HTTP so transcripts and tests can match on
+ * `code` instead of fuzzy-matching on `message`.
+ *
+ * Plain `Error` throws work too — they propagate verbatim with
+ * `code = "ToolError"` synthesized at the wire boundary.
+ */
+export class ToolError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "ToolError";
+    }
+}
+/**
+ * Run a tool whose result is a single JSON object. If the
+ * `JSON.stringify`'d result's estimated token count is at or below the
+ * limit, returns the object verbatim. Otherwise spills the full JSON to
+ * scratch and returns {@link OffloadedJson}.
+ *
+ * No partial JSON is exposed — an oversized result is either fully
+ * inline or fully offloaded. The body is expected to throw on failure;
+ * the runner does not catch.
+ */
+export async function runJsonTool(body, ctx) {
+    const result = await body();
+    const serialized = JSON.stringify(result);
+    if (estimateTokens(serialized) <= ctx.limit) {
+        return result;
+    }
+    const fullResultAt = await ctx.spill("result.json", Buffer.from(serialized, "utf8"));
+    return {
+        truncated: true,
+        fullResultAt,
+        reason: `result exceeded ${ctx.limit} tokens — fs_read the path (it's paginated)`,
+    };
+}
+/**
+ * Run a tool whose result is a stream of JSON objects, serialized as
+ * newline-delimited JSON. If the total fits within the limit, returns
+ * all lines joined with `\n`. Otherwise spills the full JSONL to
+ * scratch and returns the leading whole lines that fit, followed by a
+ * marker line:
+ *
+ *   `{"truncated":true,"fullResultAt":"<path>","omittedLines":<N>}`
+ *
+ * Edge case: when even the first line plus the marker exceeds the
+ * limit, only the marker is returned (`omittedLines` then equals the
+ * total line count).
+ */
+export async function runJsonLinesTool(body, ctx) {
+    const source = await body();
+    const serialized = [];
+    for await (const item of asAsyncIterable(source)) {
+        serialized.push(JSON.stringify(item));
+    }
+    const inline = serialized.join("\n");
+    if (estimateTokens(inline) <= ctx.limit) {
+        return inline;
+    }
+    const fullText = inline;
+    const fullResultAt = await ctx.spill("result.jsonl", Buffer.from(fullText, "utf8"));
+    // Budget the marker assuming worst-case omittedLines (the total
+    // line count). Marker can only get shorter as `omittedLines`
+    // shrinks, so this is a safe upper bound.
+    const upperBoundMarker = JSON.stringify({
+        truncated: true,
+        fullResultAt,
+        omittedLines: serialized.length,
+    });
+    const markerBudget = estimateTokens(upperBoundMarker);
+    const kept = [];
+    let usedTokens = 0;
+    for (const line of serialized) {
+        const separator = kept.length > 0 ? 1 : 0; // newline before this line (~1 token)
+        const newlineBeforeMarker = 1; // newline between last kept line and marker
+        const addTokens = separator + estimateTokens(line);
+        if (usedTokens + addTokens + newlineBeforeMarker + markerBudget > ctx.limit) {
+            break;
+        }
+        kept.push(line);
+        usedTokens += addTokens;
+    }
+    const omittedLines = serialized.length - kept.length;
+    const marker = JSON.stringify({ truncated: true, fullResultAt, omittedLines });
+    if (kept.length === 0) {
+        return marker;
+    }
+    return `${kept.join("\n")}\n${marker}`;
+}
+/**
+ * Run a tool whose result is free text. If the text fits the limit,
+ * returns it verbatim. Otherwise spills the full text to scratch and
+ * returns a truncated prefix followed by a footer pointing at the
+ * scratch path:
+ *
+ *   `<truncated text>\n\n[truncated; full result at <path>]`
+ *
+ * The truncation respects UTF-8 code-point boundaries so multi-byte
+ * characters never get split.
+ */
+export async function runTextTool(body, ctx) {
+    const text = await body();
+    if (estimateTokens(text) <= ctx.limit) {
+        return text;
+    }
+    const fullResultAt = await ctx.spill("result.txt", Buffer.from(text, "utf8"));
+    const footer = `\n\n[truncated; full result at ${fullResultAt}]`;
+    const footerTokens = estimateTokens(footer);
+    // The budget is in tokens; `truncateUtf8` bounds by character count.
+    // estimateTokens(s) = ceil(len/4), so the char budget for the prefix
+    // is the remaining token budget × 4. Bounding `truncateUtf8` by that
+    // char count is slightly conservative for multi-byte text — fine for
+    // a placeholder estimator backing a truncation marker.
+    const prefixCharBudget = Math.max(0, (ctx.limit - footerTokens) * 4);
+    const prefix = truncateUtf8(text, prefixCharBudget);
+    return `${prefix}${footer}`;
+}
+/**
+ * Truncate `str` to at most `maxBytes` UTF-8 bytes without splitting a
+ * code point. Surrogate pairs (code points beyond the BMP) are kept
+ * together.
+ */
+export function truncateUtf8(str, maxBytes) {
+    if (maxBytes <= 0) {
+        return "";
+    }
+    let bytes = 0;
+    let charIdx = 0;
+    while (charIdx < str.length) {
+        const cp = str.codePointAt(charIdx);
+        if (cp === undefined) {
+            break;
+        }
+        const cpBytes = cp < 0x80 ? 1 : cp < 0x800 ? 2 : cp < 0x10000 ? 3 : 4;
+        if (bytes + cpBytes > maxBytes) {
+            break;
+        }
+        bytes += cpBytes;
+        charIdx += cp >= 0x10000 ? 2 : 1;
+    }
+    return str.slice(0, charIdx);
+}
+/** Lift a sync iterable into an async one so we can `for await` over both. */
+async function* asAsyncIterable(source) {
+    if (Symbol.asyncIterator in source) {
+        yield* source;
+        return;
+    }
+    yield* source;
+}

package/build/ToolsExpressionUtils.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Cross-cutting constants for tool-group naming. A handler's `tools:`
+ * frontmatter lists explicit tool names, `*`-globs, or group names;
+ * the resolver lives in the container
+ * (`container/src/tools/ToolsExpressionParser.ts`). The pieces
+ * re-exported here are the ones the host-side `mcp.yml` linter and the
+ * plugin tool registry also need to enforce — namely the reserved
+ * group names and the shape every declarable name must match.
+ *
+ * Group names are otherwise *open*: any identifier matching
+ * {@link IDENT_PATTERN} is a valid group, and a tool joins it by
+ * listing the name in `PluginTool.groups`. The "predefined" groups
+ * (`core`, `fs`, `reflection`, …) are not hardcoded sets — they
+ * emerge from the union of every tool that declares them.
+ */
+/** Built-in group: every key in the available pool (system ∪ MCP). Reserved. */
+export declare const ALL_GROUP_NAME = "all";
+/** Built-in group: every MCP-tool key. Reserved. */
+export declare const MCP_GROUP_NAME = "mcp";
+/** Built-in group: empty set — used to override a parent's `tools:`. Reserved. */
+export declare const NONE_GROUP_NAME = "none";
+/**
+ * Reserved plugin id for host-owned tools registered without a
+ * plugin-id prefix (the "bare-key" path — `cal_get_events` rather
+ * than `core_cal_get_events`). It is a **registration sentinel, not
+ * an addressable tool group**: it deliberately collides in spelling
+ * with the curated `core` group, so it must never be turned into a
+ * plugin-id auto-group (doing so would shadow the curated `core`
+ * group — the union of container built-ins and tools declaring
+ * `groups: ["core"]` — with the full set of host-owned tools). Host
+ * built-in tools join curated groups through their own `groups`
+ * field (`["cal"]`, `["mail"]`, `["reflection"]`, …) instead.
+ */
+export declare const CORE_PLUGIN_ID = "core";
+/**
+ * Names the resolver handles directly and that therefore cannot
+ * appear as a declarable group, an MCP id, or a plugin id. Using one
+ * as an MCP id in `mcp.yml` is rejected by the loader; declaring it in
+ * `PluginTool.groups` is rejected by the plugin tool registry.
+ */
+export declare const RESERVED_GROUP_NAMES: ReadonlySet<string>;
+/**
+ * Pattern any group name — declarable, MCP-id-derived, or
+ * plugin-id-derived — must match.
+ *
+ * Lowercase alphanumeric only, leading letter, no underscores and
+ * no hyphens. The exclusion of `_` is load-bearing: tool keys are
+ * always shaped `${id}_${name}` (plugin tools) or a bare alnum-only
+ * stem (built-ins) and contain at least one underscore in the
+ * namespaced form, so an underscore-free bareword can never collide
+ * with a tool key — the tool-group vs tool-pattern classifier in
+ * `resolveTools` uses that to tell them apart structurally.
+ */
+export declare const IDENT_PATTERN: RegExp;
+/**
+ * Validate a declared group name (used by the host plugin tool
+ * registry and the container's built-in tool registration). Throws
+ * with a self-contained message if the name is reserved or fails
+ * {@link IDENT_PATTERN}.
+ */
+export declare function validateGroupName(name: string): void;
+/**
+ * Match one tool-name glob pattern against a single tool name. A
+ * pattern without `*` is an exact match; `*` is a wildcard for any
+ * character sequence (including `_`, since tool names contain `_`).
+ * Fully anchored (`^…$`) — `comment_*` matches `comment_reply` but not
+ * `commentary`. This is the shared semantics used by the container's
+ * `tools:` frontmatter resolver and by the `mcp.yml` allow/deny/level
+ * globs.
+ *
+ * @param pattern The glob pattern (bareword or `*`-containing).
+ * @param name The tool name to test.
+ * @returns `true` when the name matches the pattern.
+ */
+export declare function toolPatternMatches(pattern: string, name: string): boolean;
+/**
+ * `true` when `name` matches any of the glob `patterns`. Empty list ⇒
+ * `false`. See {@link toolPatternMatches} for the per-pattern semantics.
+ */
+export declare function matchesAnyToolPattern(patterns: readonly string[], name: string): boolean;

package/build/ToolsExpressionUtils.js

@@ -0,0 +1,102 @@
+/**
+ * Cross-cutting constants for tool-group naming. A handler's `tools:`
+ * frontmatter lists explicit tool names, `*`-globs, or group names;
+ * the resolver lives in the container
+ * (`container/src/tools/ToolsExpressionParser.ts`). The pieces
+ * re-exported here are the ones the host-side `mcp.yml` linter and the
+ * plugin tool registry also need to enforce — namely the reserved
+ * group names and the shape every declarable name must match.
+ *
+ * Group names are otherwise *open*: any identifier matching
+ * {@link IDENT_PATTERN} is a valid group, and a tool joins it by
+ * listing the name in `PluginTool.groups`. The "predefined" groups
+ * (`core`, `fs`, `reflection`, …) are not hardcoded sets — they
+ * emerge from the union of every tool that declares them.
+ */
+/** Built-in group: every key in the available pool (system ∪ MCP). Reserved. */
+export const ALL_GROUP_NAME = "all";
+/** Built-in group: every MCP-tool key. Reserved. */
+export const MCP_GROUP_NAME = "mcp";
+/** Built-in group: empty set — used to override a parent's `tools:`. Reserved. */
+export const NONE_GROUP_NAME = "none";
+/**
+ * Reserved plugin id for host-owned tools registered without a
+ * plugin-id prefix (the "bare-key" path — `cal_get_events` rather
+ * than `core_cal_get_events`). It is a **registration sentinel, not
+ * an addressable tool group**: it deliberately collides in spelling
+ * with the curated `core` group, so it must never be turned into a
+ * plugin-id auto-group (doing so would shadow the curated `core`
+ * group — the union of container built-ins and tools declaring
+ * `groups: ["core"]` — with the full set of host-owned tools). Host
+ * built-in tools join curated groups through their own `groups`
+ * field (`["cal"]`, `["mail"]`, `["reflection"]`, …) instead.
+ */
+export const CORE_PLUGIN_ID = "core";
+/**
+ * Names the resolver handles directly and that therefore cannot
+ * appear as a declarable group, an MCP id, or a plugin id. Using one
+ * as an MCP id in `mcp.yml` is rejected by the loader; declaring it in
+ * `PluginTool.groups` is rejected by the plugin tool registry.
+ */
+export const RESERVED_GROUP_NAMES = new Set([
+    ALL_GROUP_NAME,
+    MCP_GROUP_NAME,
+    NONE_GROUP_NAME,
+]);
+/**
+ * Pattern any group name — declarable, MCP-id-derived, or
+ * plugin-id-derived — must match.
+ *
+ * Lowercase alphanumeric only, leading letter, no underscores and
+ * no hyphens. The exclusion of `_` is load-bearing: tool keys are
+ * always shaped `${id}_${name}` (plugin tools) or a bare alnum-only
+ * stem (built-ins) and contain at least one underscore in the
+ * namespaced form, so an underscore-free bareword can never collide
+ * with a tool key — the tool-group vs tool-pattern classifier in
+ * `resolveTools` uses that to tell them apart structurally.
+ */
+export const IDENT_PATTERN = /^[a-z][a-z0-9]*$/;
+/**
+ * Validate a declared group name (used by the host plugin tool
+ * registry and the container's built-in tool registration). Throws
+ * with a self-contained message if the name is reserved or fails
+ * {@link IDENT_PATTERN}.
+ */
+export function validateGroupName(name) {
+    if (!IDENT_PATTERN.test(name)) {
+        throw new Error(`tool group name "${name}" is not a valid tool group name (must match ${IDENT_PATTERN})`);
+    }
+    if (RESERVED_GROUP_NAMES.has(name)) {
+        throw new Error(`tool group name "${name}" is a reserved tool group name (${[...RESERVED_GROUP_NAMES].join(", ")})`);
+    }
+}
+/**
+ * Match one tool-name glob pattern against a single tool name. A
+ * pattern without `*` is an exact match; `*` is a wildcard for any
+ * character sequence (including `_`, since tool names contain `_`).
+ * Fully anchored (`^…$`) — `comment_*` matches `comment_reply` but not
+ * `commentary`. This is the shared semantics used by the container's
+ * `tools:` frontmatter resolver and by the `mcp.yml` allow/deny/level
+ * globs.
+ *
+ * @param pattern The glob pattern (bareword or `*`-containing).
+ * @param name The tool name to test.
+ * @returns `true` when the name matches the pattern.
+ */
+export function toolPatternMatches(pattern, name) {
+    if (!pattern.includes("*")) {
+        return pattern === name;
+    }
+    const regex = new RegExp(`^${pattern
+        .split("*")
+        .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+        .join(".*")}$`);
+    return regex.test(name);
+}
+/**
+ * `true` when `name` matches any of the glob `patterns`. Empty list ⇒
+ * `false`. See {@link toolPatternMatches} for the per-pattern semantics.
+ */
+export function matchesAnyToolPattern(patterns, name) {
+    return patterns.some((pattern) => toolPatternMatches(pattern, name));
+}

package/build/WorkspaceFile.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Public types describing the workspace-file surface plugins observe via
+ * `ctx.workspace.*`. The concrete watcher lives in the host
+ * (`host/src/workspace/WorkspaceWatcher.ts`); host and plugins share the
+ * same `WorkspaceFile` shape — no projection layer.
+ */
+/**
+ * Filter describing which workspace files a subscriber cares about.
+ *
+ * All fields are optional and combined with AND semantics. An empty
+ * filter matches every file in scope (the watcher's scope is markdown
+ * only — see {@link WorkspaceWatcherApi}).
+ */
+export interface WorkspaceFileFilter {
+    /**
+     * Frontmatter key → search expression. The file matches iff every
+     * key listed here is present in the file's YAML frontmatter AND
+     * the stringified value matches the expression.
+     *
+     * The expression is a substring matcher with `*` as the any-chars
+     * wildcard. `"*"` alone means "key present with any value". `"foo"`
+     * means "value contains the substring `foo`". `"foo*bar"` means
+     * "value contains `foo` somewhere, then `bar` later".
+     */
+    readonly frontmatter?: Readonly<Record<string, string>>;
+    /**
+     * Optional substring-with-`*` glob applied to the workspace-relative
+     * path. Same wildcard grammar as the frontmatter values.
+     */
+    readonly pathGlob?: string;
+}
+/**
+ * A workspace file observed by the watcher.
+ *
+ * Returned by {@link WorkspaceWatcherApi.listMarkdownFiles} (with `kind`
+ * omitted) and dispatched to {@link WorkspaceWatcherApi.onMarkdownFileUpdate}
+ * callbacks (with `kind` set to the transition that triggered the
+ * notification).
+ *
+ * `removed` may be synthetic: a file whose frontmatter changed such
+ * that it no longer matches a subscription's filter is reported as
+ * `removed` even though the file still exists on disk. The file is
+ * gone *from the subscriber's point of view*, which is the only thing
+ * the consumer can act on.
+ */
+export interface WorkspaceFile {
+    /** Path relative to the workspace root, POSIX separators. */
+    readonly relativePath: string;
+    /** Absolute path on disk. */
+    readonly absolutePath: string;
+    /**
+     * Transition kind. Always set on `onMarkdownFileUpdate` callbacks
+     * (`"added"` on first match — creation or a frontmatter edit that
+     * brings the file into scope; `"changed"` for content edits while
+     * still in scope; `"removed"` on the reverse transition). Always
+     * omitted on `listMarkdownFiles` results.
+     */
+    readonly kind?: "added" | "changed" | "removed";
+}
+/**
+ * The `ctx.workspace` surface plugins use to observe workspace files.
+ *
+ * **Scope: markdown only.** Only `.md` files under the workspace root
+ * are tracked. Both methods below ignore every other extension; an
+ * empty filter still only matches `.md` files. (The method names
+ * spell this out — `listMarkdownFiles`, `onMarkdownFileUpdate` — so
+ * the scope is impossible to miss at the call site.)
+ *
+ * The intended pattern is snapshot-then-diff: call
+ * {@link listMarkdownFiles} once for the baseline, then
+ * {@link onMarkdownFileUpdate} for live transitions. Both calls take
+ * the same {@link WorkspaceFileFilter}; together they give a plugin a
+ * complete view (baseline + live transitions) without the watcher
+ * having to re-announce pre-existing files on subscription.
+ *
+ * Example:
+ *
+ *     const snapshot = await ctx.workspace.listMarkdownFiles(filter);
+ *     for (const file of snapshot) { ...seed... }
+ *     const unsub = ctx.workspace.onMarkdownFileUpdate(filter, handleDelta);
+ *
+ * Only available inside the daemon — CLI subcommands run without a
+ * live watcher, so both methods throw with an explicit message in
+ * that mode.
+ */
+export interface WorkspaceWatcherApi {
+    /**
+     * Snapshot of every workspace `.md` file currently matching the
+     * filter. Reads from the watcher's in-memory cache (no fresh disk
+     * scan); chokidar keeps that cache continuously in sync with disk.
+     * Returned entries have `kind` omitted. Pair with
+     * {@link onMarkdownFileUpdate} — see the interface-level doc.
+     */
+    listMarkdownFiles(filter: WorkspaceFileFilter): Promise<readonly WorkspaceFile[]>;
+    /**
+     * Subscribe to `.md` file transitions matching the filter. The
+     * callback fires per transition with `kind` always set. Pre-existing
+     * matches at subscription time are **not** replayed — call
+     * {@link listMarkdownFiles} for the baseline.
+     *
+     * Returns the unsubscribe handle.
+     */
+    onMarkdownFileUpdate(filter: WorkspaceFileFilter, callback: (file: WorkspaceFile) => void): () => void;
+}

package/build/WorkspaceFile.js

@@ -0,0 +1,7 @@
+/**
+ * Public types describing the workspace-file surface plugins observe via
+ * `ctx.workspace.*`. The concrete watcher lives in the host
+ * (`host/src/workspace/WorkspaceWatcher.ts`); host and plugins share the
+ * same `WorkspaceFile` shape — no projection layer.
+ */
+export {};

package/build/estimateTokens.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Estimate the number of tokens a string occupies in a model's context
+ * window. Used to bound tool-result offloading (see {@link import("./ToolRunner.js")})
+ * and active context-window management in the container's agent loop.
+ *
+ * The current heuristic is a coarse `~4 characters per token` — fast,
+ * dependency-free, and good enough for the budgeting decisions it backs
+ * (offload-or-not, drop-or-not). It deliberately over- nor under-counts
+ * by much for typical English/JSON payloads. A real tokenizer
+ * (e.g. tiktoken) can be slotted in here later without touching callers.
+ *
+ * @param text The string to estimate.
+ * @returns The estimated token count (always a non-negative integer;
+ *   `0` for the empty string).
+ */
+export declare function estimateTokens(text: string): number;

package/build/estimateTokens.js

@@ -0,0 +1,18 @@
+/**
+ * Estimate the number of tokens a string occupies in a model's context
+ * window. Used to bound tool-result offloading (see {@link import("./ToolRunner.js")})
+ * and active context-window management in the container's agent loop.
+ *
+ * The current heuristic is a coarse `~4 characters per token` — fast,
+ * dependency-free, and good enough for the budgeting decisions it backs
+ * (offload-or-not, drop-or-not). It deliberately over- nor under-counts
+ * by much for typical English/JSON payloads. A real tokenizer
+ * (e.g. tiktoken) can be slotted in here later without touching callers.
+ *
+ * @param text The string to estimate.
+ * @returns The estimated token count (always a non-negative integer;
+ *   `0` for the empty string).
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}