@qduc/term2 0.11.1 → 0.13.0

package/dist/services/shell/background-shell-output-store.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Session-owned retention of per-job background shell output.
+ *
+ * One ring buffer per job holds tagged, complete-line records in arrival order
+ * — chronological, unlike the settled result, which keeps stdout and stderr
+ * separate. The buffer is capped by both bytes and lines; eviction always drops
+ * from the head (the oldest output) and is surfaced through
+ * `droppedBytes`/`droppedLines` on every read, so a consumer is never shown a
+ * silently incomplete tail.
+ *
+ * Line assembly is this module's job, not the consumer's: chunks arrive on
+ * arbitrary byte boundaries, so each stream's pending partial line is held out
+ * of the buffer until it terminates (or until {@link BackgroundShellOutputStore.close}
+ * flushes it at EOF). Matching sees only complete lines, so a pattern can never
+ * span a chunk split or match half a line.
+ *
+ * Pure unit module: no processes, no timers, no shell-tool coupling. The shell
+ * tool opens a job's stream when the job launches, pushes chunks as they
+ * arrive, and closes it in the registry's `onSettled` callback.
+ */
+export type BackgroundShellOutputStream = 'stdout' | 'stderr';
+export interface BackgroundShellOutputLine {
+    stream: BackgroundShellOutputStream;
+    /** A complete line of output, without its trailing newline. '\r' is preserved. */
+    text: string;
+}
+export interface BackgroundShellOutputRead {
+    /** Complete lines in arrival order. The pending partial line is excluded until close. */
+    lines: readonly BackgroundShellOutputLine[];
+    /** Bytes dropped from the head of the retained stream since this job opened. */
+    droppedBytes: number;
+    /** Complete lines dropped from the head since this job opened. */
+    droppedLines: number;
+    /** True once `close` flushed the stream; no more lines can ever arrive. */
+    closed: boolean;
+}
+export interface BackgroundShellOutputTailRead {
+    /**
+     * Newest retained bytes in arrival order: complete lines joined by '\n',
+     * with each stream's pending partial line in its chronological position. An
+     * EOF-flushed final line is not given a newline it never had.
+     */
+    text: string;
+    /** Store evictions since this job opened, not bytes cut by the read window. */
+    droppedBytes: number;
+    droppedLines: number;
+    closed: boolean;
+}
+export interface BackgroundShellOutputStoreOptions {
+    /**
+     * Max retained bytes per job, including pending partial-line text. Line
+     * terminators are not counted. Default 256 KB.
+     */
+    maxBytes?: number;
+    /** Max retained complete lines per job. Default 2000. */
+    maxLines?: number;
+    /** Max settled jobs whose buffers survive for post-hoc reads. Default 20. */
+    maxRetainedJobs?: number;
+}
+export declare class BackgroundShellOutputStoreError extends Error {
+    constructor(message: string);
+}
+export declare class BackgroundShellOutputStore {
+    #private;
+    constructor(options?: BackgroundShellOutputStoreOptions);
+    /** Begins a job's output stream. Throws if the job id already has one. */
+    open(jobId: string): void;
+    /**
+     * Appends one chunk of a job's output. Chunks may arrive on arbitrary byte
+     * boundaries; complete lines enter the buffer, the partial remainder is held
+     * per stream. Throws if the job is unknown or already closed.
+     */
+    push(jobId: string, stream: BackgroundShellOutputStream, text: string): void;
+    /**
+     * Ends a job's output stream: flushes each pending partial line as a final
+     * record and marks the job settled, subject to retention eviction. Returns
+     * true if this call settled the stream; a second close is a no-op returning
+     * false. Throws if the job was never opened.
+     */
+    close(jobId: string): boolean;
+    /** Reads the retained complete lines of a job. Returns undefined for unknown jobs. */
+    readLines(jobId: string): BackgroundShellOutputRead | undefined;
+    /**
+     * Reads the newest retained bytes of a job as text, in arrival order, cut to
+     * the requested window (default: the store's byte cap). Includes each
+     * stream's pending partial line. Returns undefined for unknown jobs.
+     */
+    readTail(jobId: string, maxBytes?: number): BackgroundShellOutputTailRead | undefined;
+}
+//# sourceMappingURL=background-shell-output-store.d.ts.map

package/dist/services/shell/background-shell-output-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-shell-output-store.d.ts","sourceRoot":"","sources":["../../../source/services/shell/background-shell-output-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,2BAA2B,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9D,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,2BAA2B,CAAC;IACpC,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,yBAAyB;IACxC,yFAAyF;IACzF,KAAK,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC5C,gFAAgF;IAChF,YAAY,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,iCAAiC;IAChD;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAsBD,qBAAa,0BAA0B;;IAQrC,YAAY,OAAO,GAAE,iCAAsC,EAa1D;IAED,0EAA0E;IAC1E,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAcxB;IAED;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,2BAA2B,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CA6B3E;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAyB5B;IAED,sFAAsF;IACtF,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,yBAAyB,GAAG,SAAS,CAS9D;IAED;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAuB,GAAG,6BAA6B,GAAG,SAAS,CAuBpG;CAgDF"}

package/dist/services/shell/background-shell-output-store.js

@@ -0,0 +1,207 @@
+export class BackgroundShellOutputStoreError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BackgroundShellOutputStoreError';
+    }
+}
+export class BackgroundShellOutputStore {
+    #jobs = new Map();
+    /** Settled job ids in close order; retention evicts from the front. */
+    #settled = [];
+    #maxBytes;
+    #maxLines;
+    #maxRetainedJobs;
+    constructor(options = {}) {
+        this.#maxBytes = options.maxBytes ?? 256 * 1024;
+        this.#maxLines = options.maxLines ?? 2000;
+        this.#maxRetainedJobs = options.maxRetainedJobs ?? 20;
+        if (!Number.isInteger(this.#maxBytes) || this.#maxBytes < 0) {
+            throw new RangeError('maxBytes must be a non-negative integer.');
+        }
+        if (!Number.isInteger(this.#maxLines) || this.#maxLines < 0) {
+            throw new RangeError('maxLines must be a non-negative integer.');
+        }
+        if (!Number.isInteger(this.#maxRetainedJobs) || this.#maxRetainedJobs < 0) {
+            throw new RangeError('maxRetainedJobs must be a non-negative integer.');
+        }
+    }
+    /** Begins a job's output stream. Throws if the job id already has one. */
+    open(jobId) {
+        if (this.#jobs.has(jobId)) {
+            throw new BackgroundShellOutputStoreError(`Output stream already open for job ${jobId}.`);
+        }
+        this.#jobs.set(jobId, {
+            records: [],
+            remainder: {},
+            remainderSeq: {},
+            remainderOrder: [],
+            droppedBytes: 0,
+            droppedLines: 0,
+            closed: false,
+            nextSeq: 0,
+        });
+    }
+    /**
+     * Appends one chunk of a job's output. Chunks may arrive on arbitrary byte
+     * boundaries; complete lines enter the buffer, the partial remainder is held
+     * per stream. Throws if the job is unknown or already closed.
+     */
+    push(jobId, stream, text) {
+        const job = this.#jobs.get(jobId);
+        if (!job)
+            throw new BackgroundShellOutputStoreError(`No output stream open for job ${jobId}.`);
+        if (job.closed)
+            throw new BackgroundShellOutputStoreError(`Output stream for job ${jobId} is already closed.`);
+        if (text.length === 0)
+            return;
+        let pending = (job.remainder[stream] ?? '') + text;
+        let newline = pending.indexOf('\n');
+        while (newline !== -1) {
+            job.records.push({
+                stream,
+                text: pending.slice(0, newline),
+                seq: job.nextSeq++,
+                terminated: true,
+            });
+            pending = pending.slice(newline + 1);
+            newline = pending.indexOf('\n');
+        }
+        job.remainder[stream] = pending;
+        if (pending.length > 0) {
+            job.remainderSeq[stream] = job.nextSeq++;
+            if (!job.remainderOrder.includes(stream))
+                job.remainderOrder.push(stream);
+        }
+        else {
+            delete job.remainder[stream];
+            delete job.remainderSeq[stream];
+            const index = job.remainderOrder.indexOf(stream);
+            if (index !== -1)
+                job.remainderOrder.splice(index, 1);
+        }
+        this.#evictToFit(job);
+    }
+    /**
+     * Ends a job's output stream: flushes each pending partial line as a final
+     * record and marks the job settled, subject to retention eviction. Returns
+     * true if this call settled the stream; a second close is a no-op returning
+     * false. Throws if the job was never opened.
+     */
+    close(jobId) {
+        const job = this.#jobs.get(jobId);
+        if (!job)
+            throw new BackgroundShellOutputStoreError(`No output stream open for job ${jobId}.`);
+        if (job.closed)
+            return false;
+        for (const stream of job.remainderOrder) {
+            const text = job.remainder[stream];
+            if (text !== undefined && text.length > 0) {
+                // Keep the remainder's own arrival position: the flushed line completes
+                // at EOF but its bytes arrived when the remainder was last extended.
+                job.records.push({ stream, text, seq: job.remainderSeq[stream] ?? 0, terminated: false });
+            }
+        }
+        job.remainder = {};
+        job.remainderSeq = {};
+        job.remainderOrder = [];
+        job.closed = true;
+        this.#evictToFit(job);
+        this.#settled.push(jobId);
+        while (this.#settled.length > this.#maxRetainedJobs) {
+            const evicted = this.#settled.shift();
+            if (evicted)
+                this.#jobs.delete(evicted);
+        }
+        return true;
+    }
+    /** Reads the retained complete lines of a job. Returns undefined for unknown jobs. */
+    readLines(jobId) {
+        const job = this.#jobs.get(jobId);
+        if (!job)
+            return undefined;
+        return {
+            lines: job.records.map(({ stream, text }) => ({ stream, text })),
+            droppedBytes: job.droppedBytes,
+            droppedLines: job.droppedLines,
+            closed: job.closed,
+        };
+    }
+    /**
+     * Reads the newest retained bytes of a job as text, in arrival order, cut to
+     * the requested window (default: the store's byte cap). Includes each
+     * stream's pending partial line. Returns undefined for unknown jobs.
+     */
+    readTail(jobId, maxBytes = this.#maxBytes) {
+        if (!Number.isInteger(maxBytes) || maxBytes < 0) {
+            throw new RangeError('maxBytes must be a non-negative integer.');
+        }
+        const job = this.#jobs.get(jobId);
+        if (!job)
+            return undefined;
+        const segments = [];
+        for (const record of job.records) {
+            segments.push({ seq: record.seq, text: record.text, newline: record.terminated });
+        }
+        for (const stream of job.remainderOrder) {
+            const text = job.remainder[stream];
+            if (text !== undefined && text.length > 0) {
+                segments.push({ seq: job.remainderSeq[stream] ?? 0, text, newline: false });
+            }
+        }
+        segments.sort((a, b) => a.seq - b.seq);
+        let text = '';
+        for (const segment of segments)
+            text += segment.newline ? `${segment.text}\n` : segment.text;
+        if (text.length > maxBytes)
+            text = text.slice(text.length - maxBytes);
+        return { text, droppedBytes: job.droppedBytes, droppedLines: job.droppedLines, closed: job.closed };
+    }
+    /** Retained bytes per job, including pending partial-line text. */
+    #retainedBytes(job) {
+        let bytes = 0;
+        for (const record of job.records)
+            bytes += record.text.length;
+        for (const stream of job.remainderOrder)
+            bytes += job.remainder[stream]?.length ?? 0;
+        return bytes;
+    }
+    /**
+     * Drops from the head of the retained stream until both caps hold. Whole
+     * lines go first (they are the oldest content); a byte overflow that whole
+     * lines cannot fix is a single pending partial line longer than the cap, in
+     * which case its oldest bytes are dropped and its newest tail is kept. Every
+     * drop is accounted for in `droppedBytes`/`droppedLines`.
+     */
+    #evictToFit(job) {
+        while (job.records.length > 0 &&
+            (this.#retainedBytes(job) > this.#maxBytes || job.records.length > this.#maxLines)) {
+            const head = job.records.shift();
+            if (head) {
+                job.droppedBytes += head.text.length;
+                job.droppedLines += 1;
+            }
+        }
+        let overflow = this.#retainedBytes(job) - this.#maxBytes;
+        for (const stream of [...job.remainderOrder]) {
+            if (overflow <= 0)
+                break;
+            const text = job.remainder[stream];
+            if (text === undefined || text.length === 0)
+                continue;
+            const drop = Math.min(text.length, overflow);
+            job.remainder[stream] = text.slice(drop);
+            job.droppedBytes += drop;
+            overflow -= drop;
+        }
+        for (const stream of [...job.remainderOrder]) {
+            if ((job.remainder[stream]?.length ?? 0) === 0) {
+                delete job.remainder[stream];
+                delete job.remainderSeq[stream];
+                const index = job.remainderOrder.indexOf(stream);
+                if (index !== -1)
+                    job.remainderOrder.splice(index, 1);
+            }
+        }
+    }
+}
+//# sourceMappingURL=background-shell-output-store.js.map

package/dist/services/shell/background-shell-output-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-shell-output-store.js","sourceRoot":"","sources":["../../../source/services/shell/background-shell-output-store.ts"],"names":[],"mappings":"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"}

package/dist/services/shell/background-shell-registry.d.ts

@@ -0,0 +1,128 @@
+export type BackgroundShellJobStatus = 'running' | 'cancelling' | 'completed' | 'failed' | 'timed_out' | 'cancelled';
+export type BackgroundShellTerminalStatus = Extract<BackgroundShellJobStatus, 'completed' | 'failed' | 'timed_out' | 'cancelled'>;
+export interface BackgroundShellJob<TResult> {
+    id: string;
+    command: string;
+    status: BackgroundShellJobStatus;
+    startedAt: number;
+    completedAt?: number;
+    result?: TResult;
+    error?: string;
+    /** Last registry-observed start or output-chunk timestamp. */
+    lastActivityAt?: number;
+}
+export interface BackgroundShellLaunch<TResult> extends BackgroundShellJob<TResult> {
+    /** Resolves after the command and its per-job cleanup have both settled. */
+    settled: Promise<BackgroundShellJob<TResult>>;
+}
+export interface BackgroundShellLaunchOptions<TResult> {
+    command: string;
+    /** The registry creates this signal so cancellation has one owner. */
+    run: (signal: AbortSignal) => Promise<TResult>;
+    /** Called after registration and before the runner starts. */
+    onStarted?: (jobId: string) => void;
+    /** Releases resources that must remain live until the process settles. */
+    onSettled?: () => Promise<void> | void;
+    /** Lets the launcher preserve a successful process result that timed out. */
+    resultToStatus?: (result: TResult) => Exclude<BackgroundShellTerminalStatus, 'cancelled'>;
+}
+/** A running root-shell invocation that can be transferred to this registry. */
+export interface ForegroundShellLease<TResult> {
+    /** The original root tool call which may request the transfer. */
+    callId: string;
+    /** The preallocated background-job ID, stable across adoption. */
+    jobId: string;
+    command: string;
+    startedAt: number;
+    status: 'running';
+    /** Resolves to the normal tool result, or the adopted job handle after transfer. */
+    foregroundResult: Promise<TResult | ForegroundShellTransferResult>;
+    /** Resolves only after the one process and its cleanup have settled. */
+    settled: Promise<BackgroundShellJob<TResult>>;
+}
+export interface ForegroundShellLeaseOptions<TResult> extends BackgroundShellLaunchOptions<TResult> {
+    callId: string;
+    /** The foreground turn owns this signal until the lease is adopted. */
+    parentSignal?: AbortSignal;
+    /** Observational transfer hand-off, invoked before the foreground result resolves. */
+    onAdopted?: () => void;
+}
+export interface ForegroundShellTransferResult {
+    jobId: string;
+    status: 'running';
+}
+export interface ForegroundShellLeaseDetails {
+    callId: string;
+    jobId: string;
+    command: string;
+    status: 'running';
+    startedAt: number;
+}
+export interface BackgroundShellRegistryOptions<TResult = unknown> {
+    maxConcurrentJobs?: number;
+    maxRetainedJobs?: number;
+    createId?: () => string;
+    now?: () => number;
+    onEvent?: BackgroundShellEventSink<TResult>;
+}
+export type BackgroundShellEvent<TResult> = {
+    type: 'background_shell_started';
+    jobId: string;
+    command: string;
+} | {
+    type: 'background_shell_completed';
+    jobId: string;
+    command: string;
+    status: BackgroundShellTerminalStatus;
+    output?: TResult;
+    error?: string;
+} | {
+    /** One watch firing for a job that may still be running. */
+    type: 'background_shell_output';
+    jobId: string;
+    command: string;
+    watchId: string;
+    /** Per-watch monotonic firing ordinal; the notification messageId dedupe key. */
+    seq: number;
+    /** Bounded, complete-line match text carried by the firing. */
+    matchedLines: string;
+    /** Present when the job's retained buffer evicted bytes before this firing. */
+    droppedBytes?: number;
+};
+/** Observational only: failures must not interfere with job lifecycle. */
+export type BackgroundShellEventSink<TResult> = (event: BackgroundShellEvent<TResult>) => void;
+export declare class BackgroundShellRegistryCapacityError extends Error {
+    constructor(maxConcurrentJobs: number);
+}
+export declare class BackgroundShellRegistryDisposedError extends Error {
+    constructor();
+}
+/**
+ * Session-owned lifecycle for shell processes whose tool invocation has
+ * already returned. The registry deliberately owns cancellation and retention
+ * so callers cannot accidentally leave an orphaned process behind.
+ */
+export declare class BackgroundShellRegistry<TResult> {
+    #private;
+    constructor(options?: BackgroundShellRegistryOptions<TResult>);
+    launch(options: BackgroundShellLaunchOptions<TResult>): BackgroundShellLaunch<TResult>;
+    /**
+     * Starts a root shell process under a detachable foreground lease. The lease
+     * is intentionally invisible to `list()` until `adoptForeground` succeeds.
+     */
+    startForeground(options: ForegroundShellLeaseOptions<TResult>): ForegroundShellLease<TResult>;
+    getForeground(callId: string): ForegroundShellLeaseDetails | undefined;
+    listForeground(): ForegroundShellLeaseDetails[];
+    /** Atomically publishes a running foreground lease as a background job. */
+    adoptForeground(callId: string): ForegroundShellTransferResult;
+    get(id: string): BackgroundShellJob<TResult> | undefined;
+    whenSettled(id: string): Promise<BackgroundShellJob<TResult>> | undefined;
+    setEventSink(eventSink: BackgroundShellEventSink<TResult> | undefined): void;
+    list(): BackgroundShellJob<TResult>[];
+    cancel(id: string): boolean;
+    /** Records that a running process produced output without retaining the chunk. */
+    recordOutputChunk(id: string): boolean;
+    /** Cancels every running process and permanently rejects new launches. */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=background-shell-registry.d.ts.map

package/dist/services/shell/background-shell-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-shell-registry.d.ts","sourceRoot":"","sources":["../../../source/services/shell/background-shell-registry.ts"],"names":[],"mappings":"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"}