@xiaoso/dsh-tool-plus 0.1.7-beta.0 → 0.1.7

package/lib/types/tools/omp/markit/converters/epub.d.ts

@@ -0,0 +1,15 @@
+import type { ConversionResult, Converter, StreamInfo } from "../types";
+/** A metadata value: a bare string, or a node carrying `#text` and/or array children. */
+type MetaValue = string | MetaNode;
+interface MetaNode {
+    "#text"?: string;
+    [index: number]: MetaValue;
+}
+export declare class EpubConverter implements Converter {
+    name: string;
+    accepts(streamInfo: StreamInfo): boolean;
+    convert(input: Buffer, _streamInfo: StreamInfo): Promise<ConversionResult>;
+    getText(node: MetaValue | undefined): string | undefined;
+    getTextArray(node: MetaValue | undefined): (string | undefined)[];
+}
+export {};

package/lib/types/tools/omp/markit/converters/pdf/index.d.ts

@@ -0,0 +1,7 @@
+import type { ConversionResult, Converter, StreamInfo } from "../../types";
+/** Converts PDF buffers to Markdown through the native `pdf-inspector` bridge. */
+export declare class PdfConverter implements Converter {
+    name: string;
+    accepts(streamInfo: StreamInfo): boolean;
+    convert(input: Buffer, _streamInfo: StreamInfo): Promise<ConversionResult>;
+}

package/lib/types/tools/omp/markit/converters/pptx.d.ts

@@ -0,0 +1,57 @@
+import type { ConversionResult, Converter, StreamInfo } from "../types";
+/** A text value: bare string/number, or a `{ "#text" }` node when the element carries attributes. */
+type XmlText = string | number | {
+    "#text"?: string;
+};
+interface TextRun {
+    "a:t"?: XmlText;
+}
+interface Paragraph {
+    "a:r"?: TextRun | TextRun[];
+}
+interface TextBody {
+    "a:p"?: Paragraph | Paragraph[];
+}
+interface CNvPr {
+    "@_name": string;
+}
+interface Placeholder {
+    "@_type": string;
+}
+interface NvPr {
+    "p:ph"?: Placeholder;
+}
+interface NvSpPr {
+    "p:cNvPr"?: CNvPr;
+    "p:nvPr"?: NvPr;
+}
+interface Shape {
+    "p:txBody"?: TextBody;
+    "p:nvSpPr"?: NvSpPr;
+}
+interface TableCell {
+    "a:txBody"?: TextBody;
+}
+interface TableRow {
+    "a:tc"?: TableCell | TableCell[];
+}
+interface Table {
+    "a:tr"?: TableRow | TableRow[];
+}
+interface GraphicData {
+    "a:tbl"?: Table;
+}
+interface Graphic {
+    "a:graphicData"?: GraphicData;
+}
+interface GraphicFrame {
+    "a:graphic"?: Graphic;
+}
+export declare class PptxConverter implements Converter {
+    name: string;
+    accepts(streamInfo: StreamInfo): boolean;
+    convert(input: Buffer, streamInfo: StreamInfo): Promise<ConversionResult>;
+    extractText(shape: Shape): string;
+    extractTable(gf: GraphicFrame): string | null;
+}
+export {};

package/lib/types/tools/omp/markit/converters/xlsx.d.ts

@@ -0,0 +1,25 @@
+import type { ConversionResult, Converter, StreamInfo } from "../types";
+/** A text value: bare string/number, or a `{ "#text" }` node when the element carries attributes. */
+type XmlText = string | number | {
+    "#text"?: string;
+};
+interface RichTextRun {
+    t?: XmlText;
+}
+interface StringItem {
+    t?: XmlText;
+    r?: RichTextRun | RichTextRun[];
+}
+interface Cell {
+    "@_t"?: string;
+    v?: string | number;
+    is?: StringItem;
+}
+export declare class XlsxConverter implements Converter {
+    name: string;
+    accepts(streamInfo: StreamInfo): boolean;
+    convert(input: Buffer, _streamInfo: StreamInfo): Promise<ConversionResult>;
+    getCellValue(cell: Cell, shared: StringItem[]): string;
+    getSharedString(shared: StringItem[], idx: number): string;
+}
+export {};

package/lib/types/tools/omp/markit/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./registry";
+export * from "./types";

package/lib/types/tools/omp/markit/registry.d.ts

@@ -0,0 +1,16 @@
+import type { ConversionResult, MarkitOptions, StreamInfo } from "./types";
+/**
+ * In-house document → markdown engine (replaces the `markit-ai` package).
+ *
+ * Only the document converters omp routes are registered (pdf, docx, pptx,
+ * xlsx, epub). The first converter whose `accepts()` returns true and whose
+ * `convert()` succeeds wins.
+ */
+export declare class Markit {
+    #private;
+    constructor(options?: MarkitOptions);
+    convertFile(filePath: string, extra?: {
+        imageDir?: string;
+    }): Promise<ConversionResult>;
+    convert(input: Buffer, streamInfo: StreamInfo): Promise<ConversionResult>;
+}

package/lib/types/tools/omp/markit/types.d.ts

@@ -0,0 +1,30 @@
+export interface StreamInfo {
+    mimetype?: string;
+    extension?: string;
+    charset?: string;
+    filename?: string;
+    localPath?: string;
+    url?: string;
+    /** Directory to write extracted images/diagrams. */
+    imageDir?: string;
+}
+export interface ConversionResult {
+    markdown: string;
+    title?: string;
+}
+export interface MarkitOptions {
+    /** Describe an image, return markdown. Receives raw bytes and mimetype. */
+    describe?: (image: Buffer, mimetype: string) => Promise<string>;
+    /** Transcribe audio, return text. Receives raw bytes and mimetype. */
+    transcribe?: (audio: Buffer, mimetype: string) => Promise<string>;
+    /** Extra instructions appended to the image description prompt. */
+    prompt?: string;
+}
+export interface Converter {
+    /** Human-readable name for error messages. */
+    name: string;
+    /** Quick check: can this converter handle the given stream? */
+    accepts(streamInfo: StreamInfo): boolean;
+    /** Convert the source to markdown. */
+    convert(input: Buffer, streamInfo: StreamInfo, options?: MarkitOptions): Promise<ConversionResult>;
+}

package/lib/types/tools/omp/sdk.d.ts

@@ -0,0 +1,103 @@
+/**
+ * DSH adapter for OMP `sdk.ts` — the `ToolSession` interface consumed by the
+ * tool-plus engines (read/write/grep/glob/edit).
+ *
+ * Shared superset: read/write/grep/glob adapter copies declared the members
+ * their engine touches; this shared copy keeps the union (read's
+ * conflict-history, grep/glob's `getSessionSpawns`, the native edit store).
+ * DSH provides a session adapter implementing this interface.
+ */
+import type { Settings } from './config/settings.ts';
+import type { Skill } from './extensibility/skills.ts';
+import type { ConflictHistory } from './tools/conflict-detect.ts';
+import type { Model } from '@oh-my-pi/pi-ai';
+declare module '@oh-my-pi/pi-agent-core' {
+    interface AgentToolContext {
+        hasUI?: boolean;
+        toolNames?: string[];
+        /** Session settings (cross-module nominal Settings — typed loosely). */
+        settings?: any;
+        /** Session manager (DSH: none). */
+        sessionManager?: {
+            saveArtifact: (text: string, toolName: string) => Promise<string | undefined>;
+        };
+    }
+}
+/**
+ * Minimal ToolSession surface used by the OMP engines (verbatim member
+ * shapes, shared superset). DSH provides a session adapter implementing
+ * this interface.
+ */
+export interface ToolSession {
+    /** Current working directory */
+    cwd: string;
+    /** Whether an edit-capable tool is available (controls hashline output) */
+    hasEditTool?: boolean;
+    /** Session settings (read.* keys; DSH maps them onto tool-plus config). */
+    settings: Settings;
+    /** Active model string for mode resolution (optional in DSH). */
+    getActiveModelString?: () => string | undefined;
+    /** Active model object (image-capability checks; optional in DSH). */
+    getActiveModel?: () => Model | undefined;
+    /**
+     * DSH image bridge (拍板#22): attachment store + route vision-capability
+     * probe handed to the read/fetch image paths. Optional — engines degrade to
+     * a model-facing metadata text when absent.
+     */
+    imageBridge?: () => import('../shared/image-bridge.ts').ImageBridge | undefined;
+    /**
+     * Native edit store (created lazily by the engine): the hashline snapshot
+     * ring, the `CUT`/`PUT` clipboard registers and the no-op loop guard. Shared
+     * by read / search / write / edit through `file-snapshot-store.ts`, and
+     * round-tripped across tool calls by `shared/session-state.ts`.
+     */
+    editStore?: import('../hashline/native/index.ts').EditStore;
+    /** Plan-mode state (DSH plan is a hint layer — never enabled). */
+    getPlanModeState?: () => {
+        enabled: boolean;
+        planFilePath: string;
+    } | undefined;
+    /** Plan reference path (DSH: none). */
+    getPlanReferencePath?: () => string | null;
+    /** Local protocol options (DSH has no local:// sandbox — optional). */
+    localProtocolOptions?: import('./internal-urls/index.ts').LocalProtocolOptions;
+    getArtifactsDir?: () => string | null;
+    /** Allocate a new artifact path (DSH: none). */
+    allocateOutputArtifact?: (toolType: string) => Promise<{
+        id?: string;
+        path?: string;
+    }>;
+    getSessionId?: () => string | null;
+    /** Session spawn policy (DSH: none — engines fall back to `"*"`). */
+    getSessionSpawns?: () => string | boolean | null | undefined;
+    /** Fetch implementation for URL reads (DSH: global fetch). */
+    fetch?: typeof globalThis.fetch;
+    /** Tool-choice queue (resolution devices; DSH: none). */
+    getToolChoiceQueue?: () => ToolChoiceQueueLike | undefined;
+    /** Plan-proposal handler (resolution devices; DSH: none). */
+    peekPlanProposalHandler?: () => PlanProposalHandler | undefined;
+    /** Queued/pending invocation peek (resolution devices; DSH: none). */
+    peekQueueInvoker?: () => ResolveInvoker | undefined;
+    peekPendingInvoker?: () => ResolveInvoker | undefined;
+    /** Clear pending invokers (resolution devices; DSH: none). */
+    clearPendingInvokers?: () => void;
+    /** Whether a built-in tool is active in this turn's tool set. */
+    isToolActive?: (name: string) => boolean;
+    /** Pre-loaded skills (DSH: none). */
+    skills?: readonly Skill[];
+    /** Auth storage for search providers (DSH: none). */
+    authStorage?: import('@oh-my-pi/pi-ai').AuthStorage;
+    /** Conflict history for conflict:// write-back (DSH: absent). */
+    conflictHistory?: ConflictHistory;
+}
+/** Tool-choice queue for staged resolution previews (DSH: never present). */
+export interface ToolChoiceQueueLike {
+    registerPendingInvoker: (id: string, toolName: string, invoker: ResolveInvoker) => void;
+    removePendingInvoker: (id: string) => void;
+}
+/** Plan-proposal approval handler (DSH: never present). */
+export type PlanProposalHandler = (title: string) => Promise<import('@oh-my-pi/pi-agent-core').AgentToolResult<unknown>>;
+/** Staged resolution invocation runner (DSH: never present). */
+export type ResolveInvoker = (invocation: unknown) => Promise<import('@oh-my-pi/pi-agent-core').AgentToolResult<unknown>>;
+/** DSH: no auth storage discovery — search providers have no credentials. */
+export declare function discoverAuthStorage(_agentDir?: string): Promise<import('@oh-my-pi/pi-ai').AuthStorage>;

package/lib/types/tools/omp/session/agent-storage.d.ts

@@ -0,0 +1,154 @@
+import { type AuthCredential, type AuthCredentialStore, type StoredAuthCredential } from "@oh-my-pi/pi-ai";
+import type { RawSettings as Settings } from "../config/settings";
+/** One completed request's timing, folded into the per-model aggregates. */
+export interface ModelPerfSample {
+    /** Output tokens the provider reported for the turn. */
+    outputTokens: number;
+    /** Total request duration in milliseconds. */
+    durationMs: number;
+    /** Time to first token in milliseconds; omit when the provider did not report one. */
+    ttftMs?: number;
+}
+/** Recency-weighted per-model performance averages. */
+export interface ModelPerfStats {
+    /** Decayed sample count backing the averages. */
+    samples: number;
+    /** Average output tokens/sec over the total request duration. */
+    tps: number;
+    /** Average time-to-first-token in milliseconds; null when no sample reported one. */
+    ttftMs: number | null;
+}
+/** Current agent.db schema version; bump when schema changes require migration. */
+export declare const SCHEMA_VERSION = 6;
+/**
+ * Unified SQLite storage for agent settings, model usage, and auth credentials.
+ * Delegates auth credential operations to AuthCredentialStore from @oh-my-pi/pi-ai.
+ * Uses singleton pattern per database path; access via AgentStorage.open().
+ */
+export declare class AgentStorage {
+    #private;
+    private constructor();
+    /**
+     * Returns singleton instance for the given database path, creating if needed.
+     * Retries on the `SQLITE_BUSY` family (including `SQLITE_BUSY_RECOVERY`) with
+     * exponential backoff. See issue #2421.
+     * @param dbPath - Path to the SQLite database file (defaults to config path)
+     * @returns AgentStorage instance for the given path
+     */
+    static open(dbPath?: string): Promise<AgentStorage>;
+    /** @internal Reset all singletons and close their databases — test-only. */
+    static resetInstance(): void;
+    /**
+     * Reads legacy settings persisted in the agent.db `settings` table.
+     * The canonical settings store is `config.yml`; this accessor only
+     * exists so the config loader can migrate values from older installs.
+     * @returns Settings object, or null if no settings are stored
+     */
+    getSettings(): Settings | null;
+    /**
+     * Records model usage, updating the last-used timestamp.
+     * @param modelKey - Model key in "provider/modelId" format
+     */
+    recordModelUsage(modelKey: string): void;
+    /**
+     * Gets model keys ordered by most recently used.
+     * Results are cached until recordModelUsage is called.
+     * @returns Array of model keys ("provider/modelId") in MRU order
+     */
+    getModelUsageOrder(): string[];
+    /**
+     * Folds one completed request's timing into the model's perf aggregates.
+     * TPS is measured over the total request duration — not the post-TTFT
+     * decode window, which undercounts generation time (and so inflates the
+     * rate) when reasoning tokens are generated before the first visible
+     * token. Invalid samples (no tokens, no duration) are dropped.
+     *
+     * Deferred like prompt history: samples are batched and written in one
+     * transaction after {@link MODEL_PERF_FLUSH_DELAY_MS}, keeping SQLite off
+     * the turn-completion hot path. Fire-and-forget safe — flush failures are
+     * logged, never thrown; await the returned promise only to observe the flush.
+     * @param modelKey - Model key in "provider/modelId" format
+     */
+    recordModelPerf(modelKey: string, sample: ModelPerfSample): Promise<void>;
+    /**
+     * Returns recency-weighted TPS/TTFT averages for every model with recorded
+     * requests, keyed by "provider/modelId". Read by the /models browser.
+     * Also kicks the one-time background stats.db import; until it completes,
+     * models without live samples are simply absent.
+     */
+    getModelPerf(): Map<string, ModelPerfStats>;
+    /**
+     * Imports recent measurable request rows from an `omp stats` database
+     * (`messages` table) into the model_perf aggregates. Walks newest-first
+     * over the timestamp index in {@link MODEL_PERF_BACKFILL_CHUNK}-row chunks,
+     * yielding to the event loop between chunks, and keeps at most
+     * {@link MODEL_PERF_DECAY_AT} rows per model within the
+     * {@link MODEL_PERF_BACKFILL_MAX_AGE_MS} window — beyond either bound the
+     * live decay would erase the contribution anyway. Errored turns are
+     * excluded; aborted turns with reported usage count, matching live capture.
+     * Sums land in one additive transaction at the end, so concurrent live
+     * samples merge correctly regardless of order.
+     * @param statsDbPath - Path to a stats.db file; opened read-only
+     * @returns Number of rows folded in
+     * @throws When the stats db cannot be opened or queried
+     */
+    backfillModelPerfFromStats(statsDbPath: string): Promise<number>;
+    /**
+     * Checks if any auth credentials exist in storage.
+     * @returns True if at least one credential is stored
+     */
+    hasAuthCredentials(): boolean;
+    /**
+     * Returns the underlying {@link AuthCredentialStore} so callers that need
+     * the lower-level pi-ai abstraction (e.g. `findAnthropicAuth(store)`) can
+     * reuse this storage's open database connection instead of opening their
+     * own.
+     */
+    get authStore(): AuthCredentialStore;
+    /**
+     * Lists auth credentials, optionally filtered by provider.
+     * Only returns active (non-disabled) credentials by default.
+     * @param provider - Optional provider name to filter by
+     * @param includeDisabled - If true, includes disabled credentials
+     * @returns Array of stored credentials with their database IDs
+     */
+    listAuthCredentials(provider?: string, includeDisabled?: boolean): StoredAuthCredential[];
+    /**
+     * Atomically replaces all credentials for a provider.
+     * Useful for OAuth token refresh where old tokens should be discarded.
+     * @param provider - Provider name (e.g., "anthropic", "openai")
+     * @param credentials - New credentials to store
+     * @returns Array of newly stored credentials with their database IDs
+     */
+    replaceAuthCredentialsForProvider(provider: string, credentials: AuthCredential[]): StoredAuthCredential[];
+    /**
+     * Updates an existing auth credential by ID.
+     * @param id - Database row ID of the credential to update
+     * @param credential - New credential data
+     */
+    updateAuthCredential(id: number, credential: AuthCredential): void;
+    /**
+     * Disables an auth credential by ID with a persisted cause.
+     * @param id - Database row ID of the credential to disable
+     * @param disabledCause - Human-readable cause stored with the disabled row
+     */
+    deleteAuthCredential(id: number, disabledCause: string): void;
+    /**
+     * Disables all auth credentials for a provider with a persisted cause.
+     * @param provider - Provider name whose credentials should be disabled
+     * @param disabledCause - Human-readable cause stored with the disabled rows
+     */
+    deleteAuthCredentialsForProvider(provider: string, disabledCause: string): void;
+    /**
+     * Gets a cached value by key. Returns null if not found or expired.
+     */
+    getCache(key: string): string | null;
+    /**
+     * Sets a cached value with expiry time (unix seconds).
+     */
+    setCache(key: string, value: string, expiresAtSec: number): void;
+    /**
+     * Deletes expired cache entries. Call periodically for cleanup.
+     */
+    cleanExpiredCache(): void;
+}

package/lib/types/tools/omp/session/streaming-output.d.ts

@@ -0,0 +1,244 @@
+import type { AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+export declare const DEFAULT_MAX_LINES = 3000;
+export declare const DEFAULT_MAX_BYTES: number;
+export declare const DEFAULT_MAX_COLUMN = 512;
+/**
+ * Default artifact-on-disk cap for {@link OutputSink}.
+ *
+ * `0` means unbounded: by default, `artifact://<id>` references preserve the
+ * complete raw stream instead of a capped head/tail sample.
+ */
+export declare const ARTIFACT_DEFAULT_MAX_BYTES = 0;
+/** Default head budget; the remainder becomes the rolling tail window. */
+export declare const ARTIFACT_DEFAULT_HEAD_BYTES: number;
+export interface OutputSummary {
+    output: string;
+    truncated: boolean;
+    totalLines: number;
+    totalBytes: number;
+    outputLines: number;
+    outputBytes: number;
+    /** Bytes elided from the middle when head-retain mode is active. */
+    elidedBytes?: number;
+    /** Lines elided from the middle when head-retain mode is active. */
+    elidedLines?: number;
+    /** Bytes dropped by the per-line column cap (sum across all lines). */
+    columnDroppedBytes?: number;
+    /** Number of distinct lines that hit the per-line column cap. */
+    columnTruncatedLines?: number;
+    /** Configured per-line column cap in effect (chars), when > 0. */
+    columnMax?: number;
+    /** Artifact ID for internal URL access (artifact://<id>) when truncated */
+    artifactId?: string;
+}
+export interface OutputSinkOptions {
+    artifactPath?: string;
+    artifactId?: string;
+    /**
+     * Total inline body budget (bytes). Default DEFAULT_MAX_BYTES. The head
+     * window and rolling tail window share this budget, so a composed
+     * `dump()` body never exceeds it (plus the elision marker).
+     */
+    spillThreshold?: number;
+    /**
+     * When > 0, the sink keeps the first `headBytes` of output in addition to
+     * the rolling tail window. Output between the two windows is elided
+     * (middle elision). Clamped to `spillThreshold / 2` so the tail keeps at
+     * least half the inline budget. Default 0 = tail-only behavior.
+     */
+    headBytes?: number;
+    /**
+     * Per-line byte cap. When > 0, lines wider than `maxColumns` bytes are
+     * truncated with an ellipsis at write time; remaining bytes up to the next
+     * `\n` are dropped. Cap state persists across chunks so split-mid-line
+     * writes still respect the budget. Default 0 = no per-line cap.
+     */
+    maxColumns?: number;
+    onChunk?: (chunk: string) => void;
+    /** Minimum ms between onChunk calls. 0 = every chunk (default). */
+    chunkThrottleMs?: number;
+    /**
+     * Optional cap on bytes written to the artifact-on-disk file. When the cap
+     * is hit, the head window is preserved verbatim and subsequent output feeds
+     * a rolling tail window; on close, the sink writes a single
+     * `[ARTIFACT TRUNCATED: …]` notice between them. Default
+     * {@link ARTIFACT_DEFAULT_MAX_BYTES} (unbounded).
+     */
+    artifactMaxBytes?: number;
+    /**
+     * Bytes reserved for the head window of the capped artifact file. The
+     * tail window receives `artifactMaxBytes - artifactHeadBytes`. Default
+     * {@link ARTIFACT_DEFAULT_HEAD_BYTES}; clamped to `[0, artifactMaxBytes]`.
+     */
+    artifactHeadBytes?: number;
+}
+export interface TruncationResult {
+    content: string;
+    truncated?: boolean;
+    truncatedBy?: "lines" | "bytes" | "middle";
+    totalLines: number;
+    totalBytes: number;
+    outputLines?: number;
+    outputBytes?: number;
+    /** Bytes elided from the middle (truncateMiddle only). */
+    elidedBytes?: number;
+    /** Lines elided from the middle (truncateMiddle only). */
+    elidedLines?: number;
+    lastLinePartial?: boolean;
+    firstLineExceedsLimit?: boolean;
+}
+export interface TruncationOptions {
+    /** Maximum number of lines (default: 3000) */
+    maxLines?: number;
+    /** Maximum number of bytes (default: 50KB) */
+    maxBytes?: number;
+    /**
+     * For `truncateMiddle`: bytes reserved for the head window. The tail
+     * window receives `maxBytes - maxHeadBytes`. Default `floor(maxBytes/2)`.
+     */
+    maxHeadBytes?: number;
+    /**
+     * For `truncateMiddle`: lines reserved for the head window. The tail
+     * window receives `maxLines - maxHeadLines`. Default `floor(maxLines/2)`.
+     */
+    maxHeadLines?: number;
+}
+/** Result from byte-level truncation helpers. */
+export interface ByteTruncationResult {
+    text: string;
+    bytes: number;
+}
+export interface TailTruncationNoticeOptions {
+    fullOutputPath?: string;
+    originalContent?: string;
+    suffix?: string;
+}
+export interface HeadTruncationNoticeOptions {
+    startLine?: number;
+    totalFileLines?: number;
+}
+/**
+ * Truncate a string/buffer to fit within a byte limit, keeping the tail.
+ * Handles multi-byte UTF-8 boundaries correctly.
+ */
+export declare function truncateTailBytes(data: string | Uint8Array, maxBytes: number): ByteTruncationResult;
+/**
+ * Truncate a string/buffer to fit within a byte limit, keeping the head.
+ * Handles multi-byte UTF-8 boundaries correctly.
+ */
+export declare function truncateHeadBytes(data: string | Uint8Array, maxBytes: number): ByteTruncationResult;
+/**
+ * Truncate a single line to max characters, appending '…' if truncated.
+ */
+export declare function truncateLine(line: string, maxChars?: number): {
+    text: string;
+    wasTruncated: boolean;
+};
+/** Shared helper to build a no-truncation result. */
+export declare function noTruncResult(content: string, totalLines?: number, totalBytes?: number): TruncationResult;
+/**
+ * Truncate content from the head (keep first N lines/bytes).
+ * Never returns partial lines. If the first line exceeds the byte limit,
+ * returns empty content with firstLineExceedsLimit=true.
+ *
+ * This implementation avoids Buffer.from(content) for the whole input.
+ * It only computes UTF-8 byteLength for candidate lines that can still fit.
+ */
+export declare function truncateHead(content: string, options?: TruncationOptions): TruncationResult;
+/**
+ * Truncate content from the tail (keep last N lines/bytes).
+ * May return a partial first line if the last line exceeds the byte limit.
+ *
+ * Also avoids Buffer.from(content) for the whole input.
+ */
+export declare function truncateTail(content: string, options?: TruncationOptions): TruncationResult;
+/**
+ * Format the inline marker substituted for the elided middle region.
+ * Returned without surrounding newlines so callers can position it freely.
+ */
+export declare function formatMiddleElisionMarker(elidedLines: number, elidedBytes: number): string;
+/**
+ * Truncate content keeping a head window and a tail window, eliding the middle.
+ *
+ * The combined output is `<head>\n<marker>\n<tail>` when truncation is needed.
+ * `maxHeadBytes` defaults to `floor(maxBytes / 2)`; the tail receives the
+ * remainder. Falls back to `truncateTail` / `truncateHead` if either side's
+ * budget is empty or the content already fits.
+ */
+export declare function truncateMiddle(content: string, options?: TruncationOptions): TruncationResult;
+/** Options for {@link enforceInlineByteCap}. */
+export interface InlineByteCapOptions {
+    /** Inline byte budget. Defaults to {@link DEFAULT_MAX_BYTES}. */
+    maxBytes?: number;
+    /**
+     * Persist the full text as a session artifact. When an artifact id is
+     * returned, a `[raw output: artifact://<id>]` footer is appended so the
+     * elided bytes stay recoverable.
+     */
+    saveArtifact?: (full: string) => string | undefined | Promise<string | undefined>;
+}
+/**
+ * Final-defense inline size guard for tool results.
+ *
+ * No-op when `text` fits within `maxBytes` (the common path). Otherwise keeps
+ * ~60% of the budget from the head and ~25% from the tail — cut on line
+ * boundaries, never splitting a multi-byte UTF-8 sequence — with an elision
+ * marker between. The remaining ~15% is slack for the marker and the optional
+ * `[raw output: artifact://<id>]` footer, so the result stays under `maxBytes`.
+ */
+export declare function enforceInlineByteCap(text: string, options: InlineByteCapOptions): Promise<string>;
+export declare class TailBuffer {
+    #private;
+    readonly maxBytes: number;
+    constructor(maxBytes: number);
+    append(text: string): void;
+    text(): string;
+    bytes(): number;
+}
+export declare class OutputSink {
+    #private;
+    constructor(options?: OutputSinkOptions);
+    /**
+     * Push a chunk of output. The buffer management and onChunk callback run
+     * synchronously. File sink writes are deferred and serialized internally.
+     */
+    push(chunk: string): void;
+    createInput(): WritableStream<Uint8Array | string>;
+    /**
+     * Replace the in-memory buffer with the given text. Used when an upstream
+     * minimizer rewrites the captured output after the raw bytes have already
+     * been streamed.
+     *
+     * After this call the buffer is authoritative: streaming counters realign
+     * to the replacement, the retained head window is cleared, and head
+     * retention is disabled so subsequent `push()` calls append directly to the
+     * tail buffer instead of repopulating the (now meaningless) head window
+     * — which would otherwise reorder content and trip the middle-elision
+     * branch in `dump()` against stale totals.
+     */
+    replace(text: string): void;
+    dump(notice?: string): Promise<OutputSummary>;
+    /**
+     * Release the artifact spill descriptor on an exit path that skips
+     * {@link dump} — a thrown error or abort. Idempotent and safe in a
+     * `finally`: if {@link dump} already ran this is a no-op, otherwise it
+     * flushes the capped tail and closes the sink so the descriptor is not
+     * leaked until a later unrelated read hits `EMFILE` (issue #6463).
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Format a truncation notice for tail-truncated output (bash, python, ssh).
+ * Returns empty string if not truncated.
+ */
+export declare function formatTailTruncationNotice(truncation: TruncationResult, options?: TailTruncationNoticeOptions): string;
+/**
+ * Format a truncation notice for head-truncated output (read tool).
+ * Returns empty string if not truncated.
+ */
+export declare function formatHeadTruncationNotice(truncation: TruncationResult, options?: HeadTruncationNoticeOptions): string;
+/**
+ * Build an onChunk handler that appends to a TailBuffer and emits a streaming
+ * update (when `onUpdate` is defined) with the buffer's current text.
+ */
+export declare function streamTailUpdates<TDetails, TInput = unknown>(tailBuffer: TailBuffer, onUpdate: AgentToolUpdateCallback<TDetails, TInput> | undefined): (chunk: string) => void;