@sayknow-cli/coding-agent 0.4.2 → 0.4.3

package/dist/types/session/session-storage.d.ts

@@ -0,0 +1,297 @@
+import * as native from "@sayknow-cli/natives";
+import { type ManagedDirectoryRoot } from "./internal/managed-session-storage";
+export interface SessionStorageStat {
+    dev: bigint;
+    ino: bigint;
+    size: number;
+    mtimeMs: number;
+    mtimeNs: bigint;
+    mtime: Date;
+    isFile: boolean;
+}
+/** Exact bytes and identity captured from one opened regular-file descriptor. */
+export interface SessionStorageSnapshot {
+    bytes: Uint8Array;
+    stat: SessionStorageStat;
+}
+/**
+ * Four-state writer close lifecycle. Only a successful underlying close confirms
+ * `closed`. A failure certified to have happened BEFORE the OS close was dispatched
+ * is `close_failed_retryable` (ownership of the numeric fd is still proven, so a
+ * later retry/finalizer close is safe). Any exception from an actually dispatched
+ * close call is terminal `close_unknown`: the numeric fd cannot be safely retried
+ * or finalizer-closed, and the writer blocks strict deletion.
+ */
+export type SessionStorageWriterCloseState = "open" | "close_failed_retryable" | "close_unknown" | "closed";
+/**
+ * Thrown by a {@link SessionStorageWriterCloseAdapter} to certify that a close
+ * failure occurred BEFORE the real OS close (`fs.closeSync`-equivalent) was ever
+ * dispatched. Because no OS close ran, the numeric fd is still owned and a retry
+ * is safe. Any other thrown value is treated as a dispatched close failure
+ * (`close_unknown`) and forbids retry/finalizer close of that fd.
+ */
+export declare class SessionStorageWriterRetryableCloseError extends Error {
+    readonly name = "SessionStorageWriterRetryableCloseError";
+    constructor(message?: string, options?: ErrorOptions);
+}
+/**
+ * Injectable dispatcher for the numeric-fd OS close. The default implementation
+ * calls `fs.closeSync(fd)`. Tests inject adapters that throw
+ * {@link SessionStorageWriterRetryableCloseError} to certify a pre-dispatch
+ * failure, or that call the real close and throw to simulate a dispatched
+ * failure (`close_unknown`).
+ */
+export interface SessionStorageWriterCloseAdapter {
+    close(fd: number): void;
+}
+/** Options for opening a {@link SessionStorageWriter}. */
+export interface SessionStorageWriterOpenOptions {
+    flags?: "a" | "w";
+    onError?: (err: Error) => void;
+    /** Injectable OS-close dispatcher; defaults to `fs.closeSync`. */
+    closeAdapter?: SessionStorageWriterCloseAdapter;
+    /** Opaque authority for default-computed managed destinations only. */
+    securityContext?: SessionStorageSecurityContext;
+}
+/**
+ * Immutable authority attached only to a computed managed session destination.
+ * A caller-supplied pathname never receives this capability, even when it
+ * happens to equal the current default session directory.
+ */
+export interface ManagedSessionSecurityContext {
+    readonly kind: "managed";
+    readonly agentDir: string;
+    readonly sessionsRoot: string;
+    readonly sessionDir: string;
+    readonly rootAuthority: ManagedDirectoryRoot;
+    readonly retainedAuthority?: native.RecoveryFsRoot;
+}
+/** @internal Create the only accepted managed writer authority object. */
+export declare function createManagedSessionSecurityContext(input: {
+    agentDir: string;
+    sessionsRoot: string;
+    sessionDir: string;
+    rootAuthority: ManagedDirectoryRoot;
+    retainedAuthority?: native.RecoveryFsRoot;
+}): ManagedSessionSecurityContext;
+export type SessionStorageSecurityContext = ManagedSessionSecurityContext | undefined;
+export interface SessionStorageWriter {
+    writeLine(line: string): Promise<void>;
+    /**
+     * Synchronously append a single line. Returns once the bytes are handed to the kernel
+     * (page cache), so the data survives a non-graceful process death (OOM, SIGKILL, etc.)
+     * even though it has not yet been fsynced to the underlying disk.
+     *
+     * `line` MUST already include the trailing newline. Throws synchronously on I/O error.
+     */
+    writeLineSync(line: string): void;
+    flush(): Promise<void>;
+    fsync(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Synchronously close the underlying descriptor. The certainty-aware close
+     * state is updated synchronously and any close failure throws before this
+     * returns, so sync callers (atomic rewrite) can observe a close failure
+     * before proceeding to rename. Mirrors {@link close} semantics exactly.
+     */
+    closeSync(): void;
+    getError(): Error | undefined;
+    /** Current certainty-aware close lifecycle state. */
+    getCloseState(): SessionStorageWriterCloseState;
+    /** Stored error for non-success close states (`close_failed_retryable`/`close_unknown`). */
+    getCloseError(): Error | undefined;
+}
+export interface SessionStorage {
+    ensureDirSync(dir: string): void;
+    existsSync(path: string): boolean;
+    writeTextSync(path: string, content: string): void;
+    readTextSync(path: string): string;
+    /** Exact on-disk bytes for strict read-only session inspection. */
+    readBytesSync?(path: string): Uint8Array;
+    /** Exact bytes and descriptor-bound identity captured from one opened regular file. */
+    readSnapshotSync?(path: string): SessionStorageSnapshot;
+    statSync(path: string): SessionStorageStat;
+    listFilesSync(dir: string, pattern: string): string[];
+    /**
+     * Strict directory scan that never suppresses scan/root errors. Used by strict
+     * authorization inventory; the forgiving {@link listFilesSync} stays display-only.
+     */
+    listFilesStrictSync?(dir: string, pattern: string): string[];
+    exists(path: string): Promise<boolean>;
+    readText(path: string): Promise<string>;
+    readTextPrefix(path: string, maxBytes: number): Promise<string>;
+    writeText(path: string, content: string): Promise<void>;
+    rename(path: string, nextPath: string): Promise<void>;
+    renameSync(path: string, nextPath: string): void;
+    unlink(path: string): Promise<void>;
+    unlinkSync(path: string): void;
+    deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
+    /**
+     * Verified hard delete bound to exact identity evidence. Removes the verified
+     * artifact directory first, revalidates, and unlinks the transcript last. Returns
+     * typed partial-cleanup evidence for exact-identity retry; never returns success
+     * for a partial deletion.
+     */
+    deleteSessionVerified?(target: VerifiedSessionDeleteTarget): Promise<VerifiedSessionDeleteResult>;
+    openWriter(path: string, options?: SessionStorageWriterOpenOptions): SessionStorageWriter;
+}
+/** Exact authorization evidence for a transcript or artifact path. */
+export interface SessionStorageFileIdentity {
+    dev: bigint;
+    ino: bigint;
+    size: number;
+    mtimeNs: bigint;
+    sha256: string;
+}
+/** Kind of verification failure surfaced by {@link deleteSessionVerified}. */
+export type VerifiedDeleteFailureKind = "containment" | "symlink" | "stat" | "identity" | "header" | "cwd" | "artifacts";
+/**
+ * Thrown by {@link deleteSessionVerified} when canonical containment, transcript
+ * non-symlink/identity, header id/cwd, parent identity, or artifact identity
+ * verification fails. These are visible, sanitized failures: they never mutate
+ * the transcript or artifacts and grant zero authority.
+ */
+export declare class SessionDeleteVerificationError extends Error {
+    readonly kind: VerifiedDeleteFailureKind;
+    constructor(kind: VerifiedDeleteFailureKind, message: string, options?: ErrorOptions);
+}
+/**
+ * Exact identity evidence a verified hard delete binds to. All fields are captured
+ * at authorization time; delete revalidates each one before any mutation. Retry
+ * after a partial cleanup supplies the recorded artifact identity via
+ * {@link expectedArtifactsIdentity}.
+ */
+export interface VerifiedSessionDeleteTarget {
+    /** Canonical sessions root; the transcript must be contained within it. */
+    sessionsRoot: string;
+    /** Canonical transcript path (absolute `*.jsonl`). */
+    transcriptPath: string;
+    /** Expected session id parsed from the header. */
+    sessionId: string;
+    /** Expected canonical cwd parsed from the header. */
+    cwd: string;
+    /** Expected transcript file `(dev, ino)` captured at authorization. */
+    transcriptIdentity: SessionStorageFileIdentity;
+    /**
+     * For retry after an `artifacts` `cleanup_pending`: the recorded artifact
+     * directory identity to re-accept. A replacement/different artifact directory
+     * fails closed. Omit on first attempt or to accept recorded absence.
+     */
+    expectedArtifactsIdentity?: SessionStorageFileIdentity;
+    /** Stable native recursive-tree evidence captured before artifact detachment. */
+    expectedArtifactsTree?: NativeDirectoryTreeSnapshot;
+    /** Identity-bound quarantine path retained when recursive artifact cleanup failed. */
+    detachedArtifactsPath?: string;
+    /** Identity-bound quarantine path retained when transcript unlink deferred cleanup. */
+    detachedTranscriptPath?: string;
+    /** Caller-published, no-replace quarantine pathname for the next artifact detach. */
+    plannedArtifactsPath?: string;
+    /** Caller-published, no-replace quarantine pathname for the next transcript detach. */
+    plannedTranscriptPath?: string;
+    /** Set only after a durable caller receipt records successful artifact removal. */
+    artifactsRemoved?: true;
+}
+/**
+ * Outcome of a verified hard delete. Artifact removal happens first; only after
+ * revalidation is the transcript unlinked last. A partial deletion returns
+ * `cleanup_pending` with exact evidence for same-connection retry — never
+ * `deleted` and never `{}`.
+ */
+export type VerifiedSessionDeleteResult = {
+    kind: "artifacts_removed";
+    phase: "artifacts";
+    transcriptIdentity: SessionStorageFileIdentity;
+} | {
+    kind: "deleted";
+} | {
+    kind: "cleanup_pending";
+    phase: "artifacts";
+    error: Error;
+    /** Artifact directory identity at failure time; undefined when absent. */
+    artifactsIdentity: SessionStorageFileIdentity | undefined;
+    /** Identity-bound quarantine path retained when recursive cleanup failed. */
+    detachedArtifactsPath: string;
+    /** Native snapshot required for an identity-bound recursive retry. */
+    artifactsTree: NativeDirectoryTreeSnapshot;
+    /** Transcript identity (unchanged) for retry binding. */
+    transcriptIdentity: SessionStorageFileIdentity;
+} | {
+    kind: "cleanup_pending";
+    phase: "transcript";
+    error: Error;
+    /** Transcript identity at failure time for retry binding. */
+    transcriptIdentity: SessionStorageFileIdentity;
+    /** Optional identity-bound transcript quarantine path for restart cleanup. */
+    detachedTranscriptPath?: string;
+};
+type NativeDirectoryTreeEntry = {
+    relativePath: string;
+    kind: string;
+    dev: string;
+    ino: string;
+    size: string;
+    mtimeNs: string;
+    ctimeNs: string;
+    sha256?: string;
+};
+export type NativeDirectoryTreeSnapshot = {
+    rootDev: string;
+    rootIno: string;
+    entries: NativeDirectoryTreeEntry[];
+};
+export declare class FileSessionStorage implements SessionStorage {
+    #private;
+    ensureDirSync(dir: string): void;
+    existsSync(path: string): boolean;
+    writeTextSync(fpath: string, content: string): void;
+    readTextSync(fpath: string): string;
+    readBytesSync(fpath: string): Uint8Array;
+    readSnapshotSync(fpath: string): SessionStorageSnapshot;
+    statSync(path: string): SessionStorageStat;
+    listFilesSync(dir: string, pattern: string): string[];
+    listFilesStrictSync(dir: string, pattern: string): string[];
+    exists(path: string): Promise<boolean>;
+    readText(path: string): Promise<string>;
+    readTextPrefix(path: string, maxBytes: number): Promise<string>;
+    writeText(path: string, content: string): Promise<void>;
+    rename(path: string, nextPath: string): Promise<void>;
+    renameSync(path: string, nextPath: string): void;
+    unlink(path: string): Promise<void>;
+    unlinkSync(path: string): void;
+    openWriter(path: string, options?: SessionStorageWriterOpenOptions): SessionStorageWriter;
+    /**
+     * Delete a session and sibling artifacts in an operator-selected explicit directory.
+     * Default managed roots use deleteSessionVerified and never call this path.
+     */
+    deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
+    /**
+     * Verified hard delete bound to exact identity evidence. Artifact directory first,
+     * revalidate, transcript last. Partial deletion returns typed cleanup_pending
+     * evidence; identity/symlink/containment/header/cwd mismatch throws.
+     */
+    deleteSessionVerified(target: VerifiedSessionDeleteTarget): Promise<VerifiedSessionDeleteResult>;
+}
+export declare class MemorySessionStorage implements SessionStorage {
+    #private;
+    ensureDirSync(_dir: string): void;
+    existsSync(path: string): boolean;
+    writeTextSync(path: string, content: string): void;
+    readTextSync(path: string): string;
+    readBytesSync(path: string): Uint8Array;
+    readSnapshotSync(path: string): SessionStorageSnapshot;
+    statSync(path: string): SessionStorageStat;
+    listFilesSync(dir: string, pattern: string): string[];
+    listFilesStrictSync(dir: string, pattern: string): string[];
+    exists(path: string): Promise<boolean>;
+    readText(path: string): Promise<string>;
+    readTextPrefix(path: string, maxBytes: number): Promise<string>;
+    writeText(path: string, content: string): Promise<void>;
+    rename(path: string, nextPath: string): Promise<void>;
+    renameSync(path: string, nextPath: string): void;
+    unlink(path: string): Promise<void>;
+    unlinkSync(path: string): void;
+    deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
+    deleteSessionVerified(target: VerifiedSessionDeleteTarget): Promise<VerifiedSessionDeleteResult>;
+    openWriter(path: string, options?: SessionStorageWriterOpenOptions): SessionStorageWriter;
+}
+export {};

package/dist/types/session/streaming-output.d.ts

@@ -0,0 +1,213 @@
+import type { AgentToolUpdateCallback } from "@sayknow-cli/agent-core";
+export declare const DEFAULT_MAX_LINES = 3000;
+export declare const DEFAULT_MAX_BYTES: number;
+export declare const DEFAULT_MAX_COLUMN = 1024;
+export declare const DEFAULT_ARTIFACT_MAX_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;
+    /** Artifact ID for internal URL access (artifact://<id>) when truncated */
+    artifactId?: string;
+    /** Bytes omitted from artifact storage after the artifact hard cap was reached. */
+    artifactTruncatedBytes?: number;
+}
+export interface OutputSinkOptions {
+    /**
+     * Deprecated managed artifact pathname. Bare paths are deliberately ignored:
+     * streaming output must be terminally published through ArtifactManager.
+     */
+    artifactPath?: string;
+    artifactId?: string;
+    /** Tail buffer budget (bytes). Default DEFAULT_MAX_BYTES. */
+    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). 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;
+    /** Hard cap for artifact writes/pending replay. Default DEFAULT_ARTIFACT_MAX_BYTES. */
+    artifactMaxBytes?: number;
+    onChunk?: (chunk: string) => void;
+    /** Minimum ms between onChunk calls. 0 = every chunk (default). */
+    chunkThrottleMs?: number;
+    /**
+     * Unthrottled per-chunk callback fired *after* sanitization but *before*
+     * any throttle gating, column capping, or head/tail bookkeeping. Used by
+     * background-job substrate to record the complete process stream for the
+     * Monitor tool while keeping `onChunk` cheap for UI/progress.
+     *
+     * Receives the sanitized chunk verbatim; never receives the column-capped
+     * or minimized text. Implementations must be fast and side-effect-free
+     * relative to the sink (the sink does not catch errors from this callback).
+     */
+    onRawChunk?: (chunk: string) => void;
+    /**
+     * Opt-in (F21): when true, sanitization + live callback delivery + retention are coalesced over
+     * batched raw chunks instead of run per chunk, bounding sync CPU for many-small-chunk output. The
+     * raw artifact mirror stays byte-correct. Defaults to the PI_OUTPUT_SANITIZE_COALESCE env flag
+     * (default OFF — the per-chunk path is byte-identical to historical behavior).
+     */
+    coalesceSanitize?: boolean;
+}
+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;
+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. Raw bytes are mirrored to artifacts, while the
+     * visible retention windows are selected from the sanitized/column-capped
+     * stream so production-default display matches the historical processed view.
+     */
+    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>;
+}
+/**
+ * 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;

package/dist/types/session/tool-choice-queue.d.ts

@@ -0,0 +1,84 @@
+import type { ToolChoice } from "@sayknow-cli/ai";
+export interface ResolveInfo {
+    /** The ToolChoice that was served to the LLM. */
+    choice: ToolChoice;
+}
+export interface RejectInfo {
+    /** The ToolChoice that was yielded but never (or unsuccessfully) served. */
+    choice: ToolChoice;
+    reason: "aborted" | "error" | "cleared" | "removed";
+}
+/** "requeue" replays the lost yield next turn; "drop" (or void/undefined) discards it. */
+export type RejectOutcome = "requeue" | "drop";
+export interface DirectiveCallbacks {
+    /** Fires when the yield was served (LLM call completed). The directive is consumed. */
+    onResolved?: (info: ResolveInfo) => void;
+    /**
+     * Fires when the yield is being discarded. Return "requeue" to replay the
+     * same value at the head of the queue for the next turn. Default: "drop".
+     */
+    onRejected?: (info: RejectInfo) => RejectOutcome | undefined;
+    /**
+     * Handler invoked when the model actually calls the forced tool. The queue
+     * directive carries the real execution logic; the tool's own execute() is
+     * bypassed. Returns the tool result directly.
+     */
+    onInvoked?: (input: unknown) => Promise<unknown> | unknown;
+}
+export interface ToolChoiceDirective {
+    generator: Iterator<ToolChoice>;
+    /** Stable label for targeted removal and debugging (e.g. "user-force"). */
+    label: string;
+    callbacks: DirectiveCallbacks;
+}
+export interface PushOptions {
+    /** Prepend to head instead of appending to tail. Default: false. */
+    now?: boolean;
+    label?: string;
+    /** Lifecycle callbacks for this directive. */
+    onResolved?: DirectiveCallbacks["onResolved"];
+    onRejected?: DirectiveCallbacks["onRejected"];
+    onInvoked?: DirectiveCallbacks["onInvoked"];
+}
+export declare function onceGen(choice: ToolChoice): Generator<ToolChoice, void, unknown>;
+export declare class ToolChoiceQueue {
+    #private;
+    pushOnce(choice: ToolChoice, options?: PushOptions): void;
+    pushSequence(choices: ToolChoice[], options?: PushOptions): void;
+    push(generator: Iterable<ToolChoice>, options?: PushOptions): void;
+    /**
+     * Advance the head directive and return its next yield. Records the value
+     * as in-flight until resolve() or reject() is called.
+     */
+    nextToolChoice(): ToolChoice | undefined;
+    /**
+     * The in-flight yield was served — the LLM call completed normally.
+     * Fires onResolved, then clears in-flight state. The directive's generator
+     * remains in the queue if it has more values to yield.
+     */
+    resolve(): void;
+    /**
+     * The in-flight yield was not served, or the turn aborted/errored.
+     * Fires onRejected to let the caller decide: "requeue" replays the exact
+     * lost value at the head of the queue; anything else drops it.
+     */
+    reject(reason: RejectInfo["reason"]): void;
+    /**
+     * Drop an in-flight yield after runtime tool_choice degradation. This bypasses
+     * onRejected so forced directives cannot requeue themselves after the model
+     * proved incapable of honoring the forced choice.
+     */
+    degradeInFlight(reason?: string): string | undefined;
+    /** True if there is an in-flight yield that hasn't been resolved or rejected. */
+    get hasInFlight(): boolean;
+    /** Peek the in-flight directive's onInvoked handler, if any. */
+    peekInFlightInvoker(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
+    /** Remove all directives with the given label. Rejects in-flight if it matches. */
+    removeByLabel(label: string): void;
+    /** Empty the queue and reject any in-flight yield. */
+    clear(): void;
+    /** Return the label of the most recently resolved directive, then clear it. */
+    consumeLastServedLabel(): string | undefined;
+    /** For tests/debug: labels of currently queued directives in order. */
+    inspect(): readonly string[];
+}

package/dist/types/session/volatile-context-pruning.d.ts

@@ -0,0 +1,15 @@
+import type { CustomMessageEntry, SessionEntry } from "./session-manager";
+/**
+ * Volatile context is refreshed for every prompt. Only its newest copy is useful;
+ * replacing older copies at a maintenance boundary preserves the audit trail
+ * without repeatedly charging the model for stale workspace snapshots.
+ */
+export declare function pruneSupersededVolatileProjectContext(entries: readonly SessionEntry[]): {
+    changed: CustomMessageEntry[];
+    bytesSaved: number;
+};
+/** Retire superseded known singleton maintenance reminders without touching ordinary user context. */
+export declare function pruneSupersededMaintenanceReminders(entries: readonly SessionEntry[]): {
+    changed: CustomMessageEntry[];
+    bytesSaved: number;
+};

package/dist/types/session/yield-queue.d.ts

@@ -0,0 +1,32 @@
+import type { AgentMessage } from "@sayknow-cli/agent-core";
+export interface YieldDispatcher<P> {
+    /** Drop entries already delivered through another path. Called per-entry at flush time. */
+    isStale?(entry: P): boolean;
+    /** Produce one batched AgentMessage from non-stale entries. Return null to skip. */
+    build(survivors: P[]): AgentMessage | null;
+}
+export interface YieldQueueOptions {
+    isStreaming: () => boolean;
+    injectStreaming(msg: AgentMessage): void;
+    injectIdle(messages: AgentMessage[]): Promise<void>;
+    scheduleIdleFlush(run: () => Promise<void>): void;
+}
+type YieldFlushMode = "streaming" | "idle";
+export declare class YieldQueue {
+    #private;
+    constructor(options: YieldQueueOptions);
+    register<P>(kind: string, dispatcher: YieldDispatcher<P>): () => void;
+    enqueue<P>(kind: string, entry: P): void;
+    has(kind?: string): boolean;
+    flush(mode: YieldFlushMode): Promise<void>;
+    clear(): void;
+    /** Drop only the queued entries of a single kind, leaving other kinds intact. */
+    clearKind(kind: string): void;
+    /**
+     * Re-schedule an idle flush if work remains and the session is idle. Used after
+     * a transition (e.g. handoff) releases a delivery fence so entries queued while
+     * fenced are not stranded until an unrelated enqueue or agent yield.
+     */
+    rearmIdle(): void;
+}
+export {};