@getfamiliar/shared 0.1.4 → 0.1.7

package/build/EventBus.d.ts

@@ -108,7 +108,7 @@ export declare class EventBus {
     listSince(since: Date): Promise<EventRow[]>;
     /**
      * Fetch the most recently created N event rows, newest first. Used by
-     * `./cli.sh events list` to surface recent bus activity for operators
+     * `familiar events list` to surface recent bus activity for operators
      * looking for an event id to inspect with `events report <id>`.
      *
      * @param limit Maximum number of rows to return. Must be a positive integer.
@@ -118,7 +118,7 @@ export declare class EventBus {
     /**
      * Fetch the most recently created N event rows whose topic, start_handler,
      * prompt, or payload (cast to text) case-insensitively contains `needle`.
-     * Used by `./cli.sh events list <search>` so the operator can grep the
+     * Used by `familiar events list <search>` so the operator can grep the
      * recent bus without piping through `grep`.
      *
      * Substring match via `ILIKE '%needle%'`; the needle is escaped for the

package/build/EventBus.js

@@ -229,7 +229,7 @@ export class EventBus {
     }
     /**
      * Fetch the most recently created N event rows, newest first. Used by
-     * `./cli.sh events list` to surface recent bus activity for operators
+     * `familiar events list` to surface recent bus activity for operators
      * looking for an event id to inspect with `events report <id>`.
      *
      * @param limit Maximum number of rows to return. Must be a positive integer.
@@ -244,7 +244,7 @@ export class EventBus {
     /**
      * Fetch the most recently created N event rows whose topic, start_handler,
      * prompt, or payload (cast to text) case-insensitively contains `needle`.
-     * Used by `./cli.sh events list <search>` so the operator can grep the
+     * Used by `familiar events list <search>` so the operator can grep the
      * recent bus without piping through `grep`.
      *
      * Substring match via `ILIKE '%needle%'`; the needle is escaped for the

package/build/Mail.d.ts

@@ -20,6 +20,8 @@
  * (e.g. ms365 → `inbox`, `archive`, `deleteditems`; gmail eventually →
  * `INBOX`, `[Gmail]/All Mail`, `[Gmail]/Trash`).
  */
+import type { NewEvent } from "./Event.js";
+import type { EmitHandle } from "./Plugin.js";
 export type MailFolder = "inbox" | "archive" | "trash" | "sent";
 /**
  * One downloaded attachment. The core tool stages these into the
@@ -211,8 +213,8 @@ export interface MailProvider {
 /**
  * Capabilities the host exposes to plugins for mail data. Reached via
  * `ctx.mail` on a plugin's `HostContext`. Tiny by design: there is no
- * mail cache in core, so the only thing plugins do here is register
- * their provider during `start()`.
+ * mail cache in core, so plugins only register their provider during
+ * `start()` and hand new-mail events to the host for emission.
  */
 export interface MailApi {
     /**
@@ -221,6 +223,20 @@ export interface MailApi {
      * wiring bug, not a feature.
      */
     registerProvider(provider: MailProvider): void;
+    /**
+     * Emit a new-mail bus event. Mail pollers must use this instead of
+     * `ctx.events.emit` so the host can apply cross-provider policy:
+     * on dev instances the event is dropped unless
+     * `mail.emitEventsInDev` is set, so a fresh dev database doesn't
+     * replay the whole inbox. Otherwise behaves exactly like
+     * `ctx.events.emit` (idempotency, `files` staging).
+     *
+     * @param event - Event to emit; `topic` must be `mail` or start with `mail:`.
+     * @returns The emit handle, or `null` when the host suppressed the event.
+     * @throws If `topic` is not a mail topic, or whatever `ctx.events.emit`
+     *   throws (e.g. `DuplicateIdempotencyKeyError`).
+     */
+    emitMailEvent(event: NewEvent): Promise<EmitHandle | null>;
 }
 /**
  * Build a self-routing mail id from the three segments. Format:

package/build/Plugin.d.ts

@@ -11,6 +11,7 @@ import type { MailApi } from "./Mail.js";
 import type { MailStyleTemplate } from "./MailStyleTemplate.js";
 import type { ModelMetaData, ModelProviderDescriptor } from "./ModelMetaData.js";
 import type { StepResultRow } from "./StepResult.js";
+import type { StorageApi } from "./Storage.js";
 import type { ToolLevel } from "./ToolLevel.js";
 import type { ToolRunContext } from "./ToolRunner.js";
 import type { WorkspaceWatcherApi } from "./WorkspaceFile.js";
@@ -266,7 +267,7 @@ export interface HostContext {
      */
     readonly tmpDir: string;
     /**
-     * Cheap synchronous probe for whether the host daemon (`./cli.sh
+     * Cheap synchronous probe for whether the host daemon (`familiar
      * start`) is currently running on this machine. Inspects the
      * daemon's pidfile under `<tmpDir>/.daemon.pid` and confirms the
      * recorded pid is still alive — no network calls, no MCP traffic.
@@ -349,10 +350,21 @@ export interface HostContext {
      *
      * Unlike `calendar`, there is no read-side surface here — the
      * core does not cache mail bodies or metadata. Pollers emit
-     * `mail:<plugin>` events with a prefixed `mail_id` in the payload;
-     * the agent reaches the body via `mail_fetch_body` on demand.
+     * `mail:<plugin>` events with a prefixed `mail_id` in the payload
+     * through `ctx.mail.emitMailEvent` (not `ctx.events.emit`, so the
+     * dev-instance gate applies); the agent reaches the body via
+     * `mail_fetch_body` on demand.
      */
     readonly mail: MailApi;
+    /**
+     * Shared cloud-storage layer. Plugins that act as storage providers
+     * register a {@link StorageProvider} during **`prepare()`** (not
+     * `start()`) via `ctx.storage.registerProvider(provider)`, so the
+     * `familiar storage` CLI can reach them without the daemon. The core
+     * `storage_*` agent tools route through the host `StorageService`,
+     * which maps the user's configured mounts onto providers.
+     */
+    readonly storage: StorageApi;
     /**
      * Read the per-mailbox style template the user (or the
      * extract-style handler) wrote at `data/mail/templates/<mailbox>/<name>.json`.
@@ -376,7 +388,7 @@ export interface HostContext {
      * {@link WorkspaceWatcherApi} for the full contract.
      *
      * Only available inside the daemon: one-shot CLI invocations
-     * (`./cli.sh <plugin> …`) do not spin up the watcher, so calling
+     * (`familiar <plugin> …`) do not spin up the watcher, so calling
      * either method from a CLI command throws synchronously. Daemon
      * plugins are the intended consumer.
      */
@@ -403,11 +415,11 @@ export interface HostContext {
     };
     /**
      * Aborts when the host daemon is no longer running — i.e. when the
-     * `./cli.sh start` process backing this context has stopped or
+     * `familiar start` process backing this context has stopped or
      * crashed. Always present; consumers don't need to null-check.
      *
-     * Intended use: one-shot CLI commands (`./cli.sh <plugin> ...`,
-     * `./cli.sh cli-chat`, etc.) race long waits (`emit().settled`,
+     * Intended use: one-shot CLI commands (`familiar <plugin> ...`,
+     * `familiar cli-chat`, etc.) race long waits (`emit().settled`,
      * polling loops, interactive prompts) against this signal and exit
      * cleanly when it fires instead of hanging on a postgres connection
      * the dying daemon took with it.
@@ -644,20 +656,20 @@ export interface PluginHostManifest {
     getModelProviders?(ctx: HostContext): readonly ModelProviderDescriptor[];
     /**
      * Default command for the plugin's CLI root. When set, invoking
-     * the plugin id with no subcommand (e.g. `cli.sh cli-chat`) runs
+     * the plugin id with no subcommand (e.g. `familiar cli-chat`) runs
      * this command's `run`. Its `args` are also lifted onto the root.
      * Useful for plugins whose primary mode is interactive (REPL-like)
      * — the user shouldn't have to remember a subcommand name.
      *
      * Subcommands declared in {@link commands} are still available
-     * under the same root, so `cli.sh cli-chat send "hi"` keeps
+     * under the same root, so `familiar cli-chat send "hi"` keeps
      * working alongside the bare-root invocation.
      */
     main?(ctx: HostContext): AnyCommandDef;
     /**
      * Citty commands contributed by this plugin. They are mounted
      * under `subCommands[<plugin.id>]` in the root CLI by default
-     * (e.g. `cli.sh cli-chat send "hi"`).
+     * (e.g. `familiar cli-chat send "hi"`).
      */
     commands?(ctx: HostContext): readonly AnyCommandDef[];
 }
@@ -673,7 +685,7 @@ export interface PluginHostManifest {
 export interface PluginManifest {
     /**
      * Plugin id, matching `[a-z0-9-]+`. Used to namespace the
-     * plugin's CLI commands (`cli.sh <id> <subcommand>`). A plugin
+     * plugin's CLI commands (`familiar <id> <subcommand>`). A plugin
      * that contributes {@link PluginHostManifest.tools | tools} must
      * additionally satisfy {@link IDENT_PATTERN} so the id is usable
      * as a tool group name; the tools registry enforces that at

package/build/Storage.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Cloud-storage provider SPI. Lives in `shared/` because the host (which
+ * owns the `StorageService`, the `storage_*` agent tools and the
+ * `familiar storage` CLI) and the provider plugins (ms365, later gdrive,
+ * dropbox, …) trade in the same shapes.
+ *
+ * Division of labour:
+ *
+ * - **Providers** speak their API: they address items by their native
+ *   id (`realId`), stream bytes between the provider and a host-side
+ *   file, and map API failures onto {@link StorageError} codes. They
+ *   never see mounts, refs, policy, quotas or the agent.
+ * - **The host `StorageService`** owns everything that must behave the
+ *   same for every provider: mount aliases, ref parsing, path
+ *   resolution for id-addressed providers, write policy, search
+ *   fan-out, cross-mount copies and the per-run byte quota.
+ *
+ * Credentials never leave the provider: the agent only ever sees mount
+ * aliases, refs, metadata and files placed in its scratch directory.
+ * Hard delete is deliberately absent from the SPI.
+ */
+/** Kind of a storage item. `native` = provider document without bytes (Google Docs, …). */
+export type StorageItemKind = "file" | "folder" | "native";
+/** Hash algorithms a provider may report for file content. */
+export type StorageHashAlgo = "sha1" | "sha256" | "md5" | "quickXor" | "dropbox";
+/** Provider-reported content hash. */
+export interface StorageContentHash {
+    readonly algo: StorageHashAlgo;
+    readonly value: string;
+}
+/**
+ * Normalized item metadata. `realId` / `parentRealId` are provider-native
+ * and only ever reach the agent wrapped inside an id ref (`mount#<id>`).
+ */
+export interface StorageItem {
+    readonly realId: string;
+    /** `null` for the drive root and for parentless items (gdrive "shared with me"). */
+    readonly parentRealId: string | null;
+    readonly name: string;
+    /**
+     * Absolute path within the drive (`/folder/file.ext`, root = `/`),
+     * or `null` when the provider cannot tell cheaply. The service fills
+     * it in where it can.
+     */
+    readonly path: string | null;
+    readonly kind: StorageItemKind;
+    readonly mimeType: string | null;
+    /** Bytes; `null` for folders and native docs. */
+    readonly size: number | null;
+    /** UTC ISO-8601. */
+    readonly createdUtc: string | null;
+    /** UTC ISO-8601. */
+    readonly modifiedUtc: string | null;
+    readonly modifiedBy: string | null;
+    /** Opaque concurrency token (OneDrive eTag, Dropbox rev, gdrive version). */
+    readonly revision: string | null;
+    readonly contentHash: StorageContentHash | null;
+    readonly webUrl: string | null;
+    readonly isShared: boolean;
+}
+/** Feature flags the service adapts to. Reported to the agent in summary form. */
+export interface StorageCapabilities {
+    /** `path` = the provider resolves `/a/b` natively; `id` = the service walks the tree. */
+    readonly addressing: "path" | "id";
+    /** `false` when siblings may share a name (Google Drive). */
+    readonly uniqueNames: boolean;
+    /** Full-text search over file contents. */
+    readonly contentSearch: boolean;
+    /** Search hits can carry a snippet. */
+    readonly searchSnippets: boolean;
+    /** Soft delete into a recoverable trash / recycle bin. */
+    readonly trash: boolean;
+    /** Byte-less provider documents exist and are exported on download. */
+    readonly nativeDocs: boolean;
+    /** Same-drive copies happen server-side. */
+    readonly serverSideCopy: boolean;
+}
+/** Kind of a drive as offered to the user in `familiar storage list`. */
+export type StorageDriveKind = "personal" | "shared" | "team";
+/**
+ * One drive of one account: a OneDrive, a SharePoint document library,
+ * a Google shared drive, … Opaque to the service beyond these fields.
+ */
+export interface StorageDrive {
+    /** Account key the drive belongs to (UPN, e-mail, dbid, …). */
+    readonly account: string;
+    /**
+     * Value to put into a mount's `drive:` field. `null` = the account's
+     * primary drive (the default when `drive:` is omitted).
+     */
+    readonly selector: string | null;
+    /** Provider-native drive id. Never shown to the agent. */
+    readonly id: string;
+    /** Human-readable name, e.g. "OneDrive" or "Verwaltung / Dokumente". */
+    readonly name: string;
+    readonly kind: StorageDriveKind;
+}
+/** Search criteria. The service post-filters kind / mime / modified / subtree, so providers may ignore them. */
+export interface StorageSearchQuery {
+    /** Plain keywords; providers must escape their own query syntax. */
+    readonly text: string;
+    /** Folder to scope the search to (provider-native id). */
+    readonly underRealId?: string;
+    /** Absolute path of that folder, when known. */
+    readonly underPath?: string;
+    readonly kind?: StorageItemKind;
+    readonly mimePrefix?: string;
+    /** Inclusive lower bound, UTC ISO. */
+    readonly modifiedFromUtc?: string;
+    /** Exclusive upper bound, UTC ISO. */
+    readonly modifiedToUtc?: string;
+}
+/** Where a search matched. */
+export type StorageMatchedIn = "name" | "content" | "unknown";
+/** One search hit. */
+export interface StorageSearchHit {
+    readonly item: StorageItem;
+    readonly matchedIn: StorageMatchedIn;
+    readonly snippet?: string;
+}
+/** One page of results with an opaque continuation cursor (`null` on the last page). */
+export interface StoragePage<T> {
+    readonly entries: readonly T[];
+    readonly nextCursor: string | null;
+}
+/** Paging options. */
+export interface StoragePageOptions {
+    readonly cursor?: string;
+    readonly limit: number;
+    readonly signal?: AbortSignal;
+}
+/** Order for folder listings. Providers that cannot sort leave it to the service. */
+export type StorageListOrder = "name" | "modified_desc";
+/** Conflict behaviour on create. */
+export type StorageConflict = "fail" | "rename" | "replace";
+/** Host-side file to upload. */
+export interface StorageUploadSource {
+    /** Absolute host path of a regular file. */
+    readonly path: string;
+    readonly size: number;
+    readonly mimeType?: string;
+}
+/** Result of a download. */
+export interface StorageDownloadResult {
+    readonly bytes: number;
+    readonly mimeType: string | null;
+    /** File name to store under; for native docs it carries the export extension. */
+    readonly fileName: string;
+}
+/**
+ * The provider contract. One instance per plugin, covering every
+ * account the plugin is logged into. Implementations must be **lazy**:
+ * providers register during `prepare()` (so the CLI can use them
+ * without the daemon), which forbids network access, so the first
+ * network call happens inside a method.
+ *
+ * Every method may throw {@link StorageError}; anything else is treated
+ * as `ProviderUnavailable` by the service.
+ */
+export interface StorageProvider {
+    readonly pluginId: string;
+    /** Capabilities for one drive (content search may depend on the tenant / plan). */
+    capabilities(drive: StorageDrive): StorageCapabilities;
+    /** Accounts this plugin is logged into (lower-cased keys). */
+    listAccounts(): Promise<readonly string[]>;
+    /** CLI hint telling the user how to (re-)login `account`. */
+    loginCommand(account: string): string;
+    /** Drives the account can reach: personal, shared and team drives / libraries. */
+    listDrives(account: string, options: {
+        readonly limit: number;
+        readonly search?: string;
+    }): Promise<readonly StorageDrive[]>;
+    /**
+     * Open one drive by its config selector (`null` = primary drive).
+     *
+     * @throws StorageError `NotFound` when the selector matches nothing.
+     */
+    openDrive(account: string, selector: string | null): Promise<StorageDrive>;
+    /** Provider id of the drive's root folder. */
+    rootRealId(drive: StorageDrive): Promise<string>;
+    /** Metadata of one item, or `null` if it does not exist. */
+    stat(drive: StorageDrive, realId: string): Promise<StorageItem | null>;
+    /**
+     * Resolve an absolute path natively. Only required when
+     * `capabilities.addressing === "path"`. Returns `[]` when not found,
+     * several items when names are ambiguous.
+     */
+    resolvePath?(drive: StorageDrive, path: string): Promise<readonly StorageItem[]>;
+    /** One page of the direct children of a folder. */
+    list(drive: StorageDrive, folderRealId: string, options: StoragePageOptions & {
+        readonly order?: StorageListOrder;
+    }): Promise<StoragePage<StorageItem>>;
+    /** One page of search hits. */
+    search(drive: StorageDrive, query: StorageSearchQuery, options: StoragePageOptions): Promise<StoragePage<StorageSearchHit>>;
+    /**
+     * Stream the item's bytes into `destPath` (created / truncated). Native
+     * docs are exported server-side in a provider-chosen format; a native
+     * type without an export mapping throws `Unsupported`.
+     */
+    download(drive: StorageDrive, realId: string, destPath: string, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<StorageDownloadResult>;
+    /**
+     * Upload a host-side file as `name` into `parentRealId`. The provider
+     * picks simple vs. resumable upload.
+     *
+     * - `conflict: "fail"` — throw `NameConflict` if the name is taken
+     *   (only meaningful with `uniqueNames`).
+     * - `conflict: "rename"` — let the provider pick a free name.
+     * - `conflict: "replace"` — overwrite the content of the item
+     *   `replaceRealId` (required; replacing by name is ambiguous on
+     *   id-addressed providers). With `ifRevision`, the replace must be
+     *   guarded by that revision (atomically where the API allows) and
+     *   throw `RevisionMismatch` otherwise.
+     */
+    upload(drive: StorageDrive, parentRealId: string, name: string, source: StorageUploadSource, options: {
+        readonly conflict: StorageConflict;
+        readonly replaceRealId?: string;
+        readonly ifRevision?: string;
+        readonly signal?: AbortSignal;
+    }): Promise<StorageItem>;
+    /** Create a folder. `reuse` returns an existing folder of that name. */
+    createFolder(drive: StorageDrive, parentRealId: string, name: string, options: {
+        readonly conflict: "fail" | "rename" | "reuse";
+    }): Promise<StorageItem>;
+    /** Move and / or rename within one drive. */
+    move(drive: StorageDrive, realId: string, target: {
+        readonly parentRealId?: string;
+        readonly name?: string;
+    }, options: {
+        readonly ifRevision?: string;
+    }): Promise<StorageItem>;
+    /** Server-side copy within one drive; resolves once the copy is complete. */
+    copy(drive: StorageDrive, realId: string, target: {
+        readonly parentRealId: string;
+        readonly name?: string;
+    }, options: {
+        readonly conflict: "fail" | "rename";
+    }): Promise<StorageItem>;
+    /** Soft delete into the provider's trash. Folders go with their contents. */
+    trash(drive: StorageDrive, realId: string, options: {
+        readonly ifRevision?: string;
+    }): Promise<void>;
+}
+/** Normalized provider failure codes. */
+export type StorageErrorCode = "NotFound" | "NameConflict" | "RevisionMismatch" | "Unsupported" | "AuthExpired" | "RateLimited" | "QuotaExceeded" | "ProviderUnavailable";
+/**
+ * Error a provider throws with a normalized code. The service maps it
+ * onto an agent-readable `ToolError`.
+ */
+export declare class StorageError extends Error {
+    readonly code: StorageErrorCode;
+    constructor(code: StorageErrorCode, message: string);
+}
+/** Plugin-facing registration surface (`ctx.storage`). */
+export interface StorageApi {
+    /**
+     * Register the plugin's storage provider. Call from `prepare()` so
+     * CLI commands reach it too. Throws if the same `pluginId`
+     * registers twice.
+     */
+    registerProvider(provider: StorageProvider): void;
+}

package/build/Storage.js

@@ -0,0 +1,33 @@
+/**
+ * Cloud-storage provider SPI. Lives in `shared/` because the host (which
+ * owns the `StorageService`, the `storage_*` agent tools and the
+ * `familiar storage` CLI) and the provider plugins (ms365, later gdrive,
+ * dropbox, …) trade in the same shapes.
+ *
+ * Division of labour:
+ *
+ * - **Providers** speak their API: they address items by their native
+ *   id (`realId`), stream bytes between the provider and a host-side
+ *   file, and map API failures onto {@link StorageError} codes. They
+ *   never see mounts, refs, policy, quotas or the agent.
+ * - **The host `StorageService`** owns everything that must behave the
+ *   same for every provider: mount aliases, ref parsing, path
+ *   resolution for id-addressed providers, write policy, search
+ *   fan-out, cross-mount copies and the per-run byte quota.
+ *
+ * Credentials never leave the provider: the agent only ever sees mount
+ * aliases, refs, metadata and files placed in its scratch directory.
+ * Hard delete is deliberately absent from the SPI.
+ */
+/**
+ * Error a provider throws with a normalized code. The service maps it
+ * onto an agent-readable `ToolError`.
+ */
+export class StorageError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "StorageError";
+    }
+}

package/build/ToolRunner.d.ts

@@ -84,6 +84,17 @@ export interface OffloadedJson {
  * the runner does not catch.
  */
 export declare function runJsonTool(body: () => Promise<object>, ctx: ToolRunContext): Promise<object>;
+/**
+ * Optional presentation settings for {@link runJsonLinesTool} and
+ * {@link runTextTool}.
+ *
+ *   - `header`: one line prepended to the result (provenance,
+ *     pagination, …). It is always kept inline, also when the body gets
+ *     truncated, and is included at the top of the spilled file.
+ */
+export interface ToolRunOptions {
+    readonly header?: string;
+}
 /**
  * Run a tool whose result is a stream of JSON objects, serialized as
  * newline-delimited JSON. If the total fits within the limit, returns
@@ -97,7 +108,7 @@ export declare function runJsonTool(body: () => Promise<object>, ctx: ToolRunCon
  * 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>;
+export declare function runJsonLinesTool(body: () => Promise<Iterable<object> | AsyncIterable<object>>, ctx: ToolRunContext, options?: ToolRunOptions | (() => ToolRunOptions)): 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
@@ -109,7 +120,7 @@ export declare function runJsonLinesTool(body: () => Promise<Iterable<object> |
  * 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>;
+export declare function runTextTool(body: () => Promise<string>, ctx: ToolRunContext, options?: ToolRunOptions | (() => ToolRunOptions)): 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

package/build/ToolRunner.js

@@ -89,15 +89,17 @@ export async function runJsonTool(body, ctx) {
  * limit, only the marker is returned (`omittedLines` then equals the
  * total line count).
  */
-export async function runJsonLinesTool(body, ctx) {
+export async function runJsonLinesTool(body, ctx, options) {
     const source = await body();
     const serialized = [];
     for await (const item of asAsyncIterable(source)) {
         serialized.push(JSON.stringify(item));
     }
-    const inline = serialized.join("\n");
+    const header = resolveOptions(options).header;
+    const headerPrefix = header !== undefined ? `${header}\n` : "";
+    const inline = headerPrefix + serialized.join("\n");
     if (estimateTokens(inline) <= ctx.limit) {
-        return inline;
+        return header !== undefined && serialized.length === 0 ? header : inline;
     }
     const fullText = inline;
     const fullResultAt = await ctx.spill("result.jsonl", Buffer.from(fullText, "utf8"));
@@ -111,7 +113,7 @@ export async function runJsonLinesTool(body, ctx) {
     });
     const markerBudget = estimateTokens(upperBoundMarker);
     const kept = [];
-    let usedTokens = 0;
+    let usedTokens = estimateTokens(headerPrefix);
     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
@@ -125,9 +127,9 @@ export async function runJsonLinesTool(body, ctx) {
     const omittedLines = serialized.length - kept.length;
     const marker = JSON.stringify({ truncated: true, fullResultAt, omittedLines });
     if (kept.length === 0) {
-        return marker;
+        return `${headerPrefix}${marker}`;
     }
-    return `${kept.join("\n")}\n${marker}`;
+    return `${headerPrefix}${kept.join("\n")}\n${marker}`;
 }
 /**
  * Run a tool whose result is free text. If the text fits the limit,
@@ -140,22 +142,25 @@ export async function runJsonLinesTool(body, ctx) {
  * 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();
+export async function runTextTool(body, ctx, options) {
+    const bodyText = await body();
+    const header = resolveOptions(options).header;
+    const headerPrefix = header !== undefined ? `${header}\n` : "";
+    const text = headerPrefix + bodyText;
     if (estimateTokens(text) <= ctx.limit) {
-        return text;
+        return header !== undefined && bodyText.length === 0 ? header : 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);
+    const footerTokens = estimateTokens(footer) + estimateTokens(headerPrefix);
     // 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}`;
+    const prefix = truncateUtf8(bodyText, prefixCharBudget);
+    return `${headerPrefix}${prefix}${footer}`;
 }
 /**
  * Truncate `str` to at most `maxBytes` UTF-8 bytes without splitting a
@@ -182,6 +187,17 @@ export function truncateUtf8(str, maxBytes) {
     }
     return str.slice(0, charIdx);
 }
+/**
+ * Normalize the options argument. A function form lets a tool compute
+ * its header *after* the body ran (e.g. from pagination state the body
+ * produced).
+ */
+function resolveOptions(options) {
+    if (options === undefined) {
+        return {};
+    }
+    return typeof options === "function" ? options() : options;
+}
 /** Lift a sync iterable into an async one so we can `for await` over both. */
 async function* asAsyncIterable(source) {
     if (Symbol.asyncIterator in source) {

package/build/index.d.ts

@@ -18,6 +18,7 @@ export { buildMailId, type ForwardInput, type MailAddress, type MailApi, type Ma
 export { MAIL_STYLE_TEMPLATE_DEFAULTS, type MailStyleTemplate, mailStyleTemplatePath, signatureToPlainText, } from "./MailStyleTemplate.js";
 export { type ModelMetaData, ModelNotSupported, type ModelProviderDescriptor, } from "./ModelMetaData.js";
 export { renderMarkdownToHtml } from "./markdownHtml.js";
+export { escapeTableCell, markdownTable, writeMarkdown } from "./markdownOutput.js";
 export { renderMarkdown } from "./markdownTerminal.js";
 export { matchesAnyGlob, matchesGlob } from "./PathGlob.js";
 export type { AnyCommandDef, EmitHandle, EmitOptions, EventContextProvider, HostContext, McpClient, McpInfo, PluginHostManifest, PluginManifest, PluginTool, PluginToolCallContext, } from "./Plugin.js";
@@ -28,10 +29,11 @@ export { ScheduledSubagentBus, type ScheduledSubagentNotification, type Schedule
 export { AGENTRUNS_CHANNEL, CHATMESSAGES_NEW_CHANNEL, EVENT_TERMINAL_UPDATE_SQL, EVENTS_NEW_CHANNEL, EVENTS_STATE_CHANNEL, SCHEDULED_SUBAGENTS_CHANNEL, SCHEMA_SQL, STEPRESULTS_NEW_CHANNEL, TOPIC_PATTERN, } from "./Schema.js";
 export type { NewStepResult, StepResultRow } from "./StepResult.js";
 export { StepResultBus, type StepResultUnsubscribe } from "./StepResultBus.js";
+export { type StorageApi, type StorageCapabilities, type StorageConflict, type StorageContentHash, type StorageDownloadResult, type StorageDrive, type StorageDriveKind, StorageError, type StorageErrorCode, type StorageHashAlgo, type StorageItem, type StorageItemKind, type StorageListOrder, type StorageMatchedIn, type StoragePage, type StoragePageOptions, type StorageProvider, type StorageSearchHit, type StorageSearchQuery, type StorageUploadSource, } from "./Storage.js";
 export { dayBoundsInZone, type ParseInZoneResult, parseInZone, renderInZone, } from "./Timezone.js";
 export type { NewToolCall, ToolCallRow, ToolUsageCount } from "./ToolCall.js";
 export { ToolCallBus } from "./ToolCallBus.js";
 export { DEFAULT_TOOL_LEVEL, type ToolLevel } from "./ToolLevel.js";
-export { DEFAULT_TOOL_CALL_OFFLOADING_LIMIT, type OffloadedJson, runJsonLinesTool, runJsonTool, runTextTool, ToolError, type ToolRunContext, truncateUtf8, } from "./ToolRunner.js";
+export { DEFAULT_TOOL_CALL_OFFLOADING_LIMIT, type OffloadedJson, runJsonLinesTool, runJsonTool, runTextTool, ToolError, type ToolRunContext, type ToolRunOptions, truncateUtf8, } from "./ToolRunner.js";
 export { ALL_GROUP_NAME, CORE_PLUGIN_ID, IDENT_PATTERN, MCP_GROUP_NAME, matchesAnyToolPattern, NONE_GROUP_NAME, RESERVED_GROUP_NAMES, toolPatternMatches, validateGroupName, } from "./ToolsExpressionUtils.js";
 export type { WorkspaceFile, WorkspaceFileFilter, WorkspaceWatcherApi, } from "./WorkspaceFile.js";

package/build/index.js

@@ -12,6 +12,7 @@ export { buildMailId, parseMailId, } from "./Mail.js";
 export { MAIL_STYLE_TEMPLATE_DEFAULTS, mailStyleTemplatePath, signatureToPlainText, } from "./MailStyleTemplate.js";
 export { ModelNotSupported, } from "./ModelMetaData.js";
 export { renderMarkdownToHtml } from "./markdownHtml.js";
+export { escapeTableCell, markdownTable, writeMarkdown } from "./markdownOutput.js";
 export { renderMarkdown } from "./markdownTerminal.js";
 export { matchesAnyGlob, matchesGlob } from "./PathGlob.js";
 export { DaemonStoppedError, definePlugin } from "./Plugin.js";
@@ -19,6 +20,7 @@ export { POSTGRES_DB, POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, PostgresConne
 export { ScheduledSubagentBus, } from "./ScheduledSubagentBus.js";
 export { AGENTRUNS_CHANNEL, CHATMESSAGES_NEW_CHANNEL, EVENT_TERMINAL_UPDATE_SQL, EVENTS_NEW_CHANNEL, EVENTS_STATE_CHANNEL, SCHEDULED_SUBAGENTS_CHANNEL, SCHEMA_SQL, STEPRESULTS_NEW_CHANNEL, TOPIC_PATTERN, } from "./Schema.js";
 export { StepResultBus } from "./StepResultBus.js";
+export { StorageError, } from "./Storage.js";
 export { dayBoundsInZone, parseInZone, renderInZone, } from "./Timezone.js";
 export { ToolCallBus } from "./ToolCallBus.js";
 export { DEFAULT_TOOL_LEVEL } from "./ToolLevel.js";