echo-cli-agent 0.1.8 → 0.1.10

package/dist/src/session/terminal-line-sanitizer.js

@@ -0,0 +1,21 @@
+/**
+ * Terminal row sanitization. The escape, control-byte and credential patterns
+ * live here so there is a single place to audit what can leave the device when
+ * terminal text is read on demand.
+ */
+// CSI (`ESC [ … final`), terminated OSC (`ESC ] … BEL/ST`) and two-character escapes.
+const TERMINAL_ESCAPE = /\u001b(?:\][^\u0007]*?(?:\u0007|\u001b\\)|\[[0-?]*[ -/]*[@-~]|[@-Z\\-_])/g;
+// Everything unprintable except tab.
+const CONTROL_CHARACTER = /[\u0000-\u0008\u000b-\u001f\u007f]/g;
+// A labeled key redacts to end of line: `Authorization: Bearer <token>` would
+// otherwise stop at the scheme and leave the token itself in the output.
+const SENSITIVE_VALUE = /\b(?:sk|rk|pk|ghp|github_pat)_[A-Za-z0-9._-]+|\bBearer\s+\S+|\b(?:api[_-]?key|token|authorization|x-mcp-token)\s*[:=]\s*\S[^\r\n]*/gi;
+/** Strip escapes and control bytes, redact credential-shaped values, drop cell padding. */
+export function sanitizeTerminalLine(line) {
+    return line
+        .replace(TERMINAL_ESCAPE, '')
+        .replace(CONTROL_CHARACTER, '')
+        .replace(SENSITIVE_VALUE, '[redacted]')
+        .replace(/\s+$/, '');
+}
+//# sourceMappingURL=terminal-line-sanitizer.js.map

package/dist/src/session/terminal-line-sanitizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-line-sanitizer.js","sourceRoot":"","sources":["../../../src/session/terminal-line-sanitizer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,sFAAsF;AACtF,MAAM,eAAe,GAAG,2EAA2E,CAAA;AACnG,qCAAqC;AACrC,MAAM,iBAAiB,GAAG,qCAAqC,CAAA;AAC/D,8EAA8E;AAC9E,yEAAyE;AACzE,MAAM,eAAe,GACnB,sIAAsI,CAAA;AAExI,2FAA2F;AAC3F,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAO,IAAI;SACR,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC;SAC5B,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC;SAC9B,OAAO,CAAC,eAAe,EAAE,YAAY,CAAC;SACtC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;AACxB,CAAC"}

package/dist/src/session/terminal-tail-buffer.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Bounded terminal tail with absolute line cursors, so a client can read the
+ * newest rows and then page backwards without re-reading what it already has.
+ *
+ * Mirrors Orca's split between a line-oriented tail and the still-unterminated
+ * partial line. Two properties matter for cost:
+ *
+ * - Appends are O(chunk). The naive `output = (output + chunk).slice(-N)` form
+ *   re-materializes the whole retained tail on every PTY chunk, which is O(N)
+ *   per write; a busy CLI turns that into a per-keystroke copy of 128 KiB.
+ * - Reads are O(requested lines). Escape stripping and redaction run on the
+ *   returned rows only, never on the whole buffer.
+ *
+ * Retained rows are raw. Sanitizing on read keeps escape sequences that straddle
+ * a chunk boundary intact until the full sequence has arrived.
+ */
+/** Retained completed rows. Matches Orca's `MAX_TAIL_LINES`. */
+export declare const MAX_TAIL_LINES = 2000;
+/** Retained characters across completed rows. Matches Orca's `MAX_TAIL_CHARS`. */
+export declare const MAX_TAIL_CHARS: number;
+/** A CLI that redraws a spinner without ever emitting a newline cannot grow past this. */
+export declare const MAX_TAIL_PARTIAL_CHARS = 4000;
+/** Rows returned when the caller does not ask for a specific count. */
+export declare const DEFAULT_TAIL_READ_LIMIT = 120;
+export declare const MAX_TAIL_READ_LIMIT = 2000;
+/** Character budget applied after the row limit, so wide rows cannot blow up a response. */
+export declare const MAX_TAIL_READ_CHARS: number;
+export type TerminalTailReadOptions = {
+    /** Rows to return, clamped to `MAX_TAIL_READ_LIMIT`. */
+    limit?: number;
+    /** Absolute cursor to read backwards from. Omit for the newest rows. */
+    beforeCursor?: number;
+};
+export type TerminalTailRead = {
+    lines: string[];
+    /** Absolute index of `lines[0]`. Pass it back as `beforeCursor` to page further up. */
+    startCursor: number;
+    /** Absolute index just past the last completed row returned. */
+    nextCursor: number;
+    /** Oldest absolute index still retained. `startCursor` cannot go below it. */
+    oldestCursor: number;
+    /** Absolute count of rows completed so far. */
+    latestCursor: number;
+    /** More retained rows exist above `startCursor`. */
+    hasMore: boolean;
+    /** Rows older than `oldestCursor` were dropped to stay within the caps. */
+    truncated: boolean;
+    /** The character budget clipped the response. */
+    limited: boolean;
+    /** Milliseconds since the CLI last wrote anything, or undefined if it never did. */
+    idleMs: number | undefined;
+};
+export declare class TerminalTailBuffer {
+    /** Completed rows, raw. Dropped head slots are blanked, then compacted in batches. */
+    private lines;
+    private head;
+    private chars;
+    /** Absolute count of completed rows, including dropped ones. Defines cursor space. */
+    private completedCount;
+    private partial;
+    private droppedRows;
+    private lastOutputAt;
+    get lastWriteAt(): number | undefined;
+    append(chunk: string, at?: number): void;
+    read(options?: TerminalTailReadOptions, now?: number): TerminalTailRead;
+    private appendPartial;
+    private commitPartial;
+    private trim;
+    private dropHead;
+}

package/dist/src/session/terminal-tail-buffer.js

@@ -0,0 +1,149 @@
+import { sanitizeTerminalLine } from './terminal-line-sanitizer.js';
+/**
+ * Bounded terminal tail with absolute line cursors, so a client can read the
+ * newest rows and then page backwards without re-reading what it already has.
+ *
+ * Mirrors Orca's split between a line-oriented tail and the still-unterminated
+ * partial line. Two properties matter for cost:
+ *
+ * - Appends are O(chunk). The naive `output = (output + chunk).slice(-N)` form
+ *   re-materializes the whole retained tail on every PTY chunk, which is O(N)
+ *   per write; a busy CLI turns that into a per-keystroke copy of 128 KiB.
+ * - Reads are O(requested lines). Escape stripping and redaction run on the
+ *   returned rows only, never on the whole buffer.
+ *
+ * Retained rows are raw. Sanitizing on read keeps escape sequences that straddle
+ * a chunk boundary intact until the full sequence has arrived.
+ */
+/** Retained completed rows. Matches Orca's `MAX_TAIL_LINES`. */
+export const MAX_TAIL_LINES = 2_000;
+/** Retained characters across completed rows. Matches Orca's `MAX_TAIL_CHARS`. */
+export const MAX_TAIL_CHARS = 256 * 1024;
+/** A CLI that redraws a spinner without ever emitting a newline cannot grow past this. */
+export const MAX_TAIL_PARTIAL_CHARS = 4_000;
+/** Rows returned when the caller does not ask for a specific count. */
+export const DEFAULT_TAIL_READ_LIMIT = 120;
+export const MAX_TAIL_READ_LIMIT = MAX_TAIL_LINES;
+/** Character budget applied after the row limit, so wide rows cannot blow up a response. */
+export const MAX_TAIL_READ_CHARS = 32 * 1024;
+/** Empty head slots tolerated before the backing array is compacted. */
+const HEAD_COMPACT_THRESHOLD = 1_024;
+export class TerminalTailBuffer {
+    /** Completed rows, raw. Dropped head slots are blanked, then compacted in batches. */
+    lines = [];
+    head = 0;
+    chars = 0;
+    /** Absolute count of completed rows, including dropped ones. Defines cursor space. */
+    completedCount = 0;
+    partial = '';
+    droppedRows = false;
+    lastOutputAt;
+    get lastWriteAt() {
+        return this.lastOutputAt;
+    }
+    append(chunk, at = Date.now()) {
+        if (!chunk)
+            return;
+        this.lastOutputAt = at;
+        let index = 0;
+        for (;;) {
+            const newline = chunk.indexOf('\n', index);
+            if (newline === -1) {
+                this.appendPartial(chunk.slice(index));
+                return;
+            }
+            // Trim the CR of a CRLF pair so it does not survive as a row rewrite.
+            const end = newline > index && chunk.charCodeAt(newline - 1) === 13 ? newline - 1 : newline;
+            this.appendPartial(chunk.slice(index, end));
+            this.commitPartial();
+            index = newline + 1;
+        }
+    }
+    read(options = {}, now = Date.now()) {
+        const limit = clampLimit(options.limit);
+        const retained = this.lines.length - this.head;
+        const oldestCursor = this.completedCount - retained;
+        const latestCursor = this.completedCount;
+        // A preview read shows what the screen shows, including the row being written.
+        const includePartial = options.beforeCursor === undefined && this.partial.length > 0;
+        const endCursor = options.beforeCursor === undefined
+            ? latestCursor
+            : Math.min(Math.max(options.beforeCursor, oldestCursor), latestCursor);
+        const rowBudget = Math.max(0, limit - (includePartial ? 1 : 0));
+        const startCursor = Math.max(oldestCursor, endCursor - rowBudget);
+        const rows = [];
+        for (let cursor = startCursor; cursor < endCursor; cursor += 1) {
+            rows.push(sanitizeTerminalLine(this.lines[this.head + (cursor - oldestCursor)] ?? ''));
+        }
+        if (includePartial)
+            rows.push(sanitizeTerminalLine(this.partial));
+        const clipped = clipToCharacterBudget(rows, MAX_TAIL_READ_CHARS);
+        return {
+            lines: clipped.lines,
+            startCursor,
+            nextCursor: endCursor,
+            oldestCursor,
+            latestCursor,
+            hasMore: startCursor > oldestCursor,
+            truncated: this.droppedRows,
+            limited: clipped.limited,
+            idleMs: this.lastOutputAt === undefined ? undefined : Math.max(0, now - this.lastOutputAt)
+        };
+    }
+    appendPartial(text) {
+        if (!text)
+            return;
+        const carriage = text.lastIndexOf('\r');
+        // A bare CR rewrites the current row on a real terminal; keep only what would stay visible.
+        const next = carriage === -1 ? `${this.partial}${text}` : text.slice(carriage + 1);
+        this.partial =
+            next.length > MAX_TAIL_PARTIAL_CHARS ? next.slice(-MAX_TAIL_PARTIAL_CHARS) : next;
+    }
+    commitPartial() {
+        const line = this.partial;
+        this.partial = '';
+        this.lines.push(line);
+        this.chars += line.length;
+        this.completedCount += 1;
+        this.trim();
+    }
+    trim() {
+        while (this.lines.length - this.head > MAX_TAIL_LINES)
+            this.dropHead();
+        while (this.head < this.lines.length && this.chars > MAX_TAIL_CHARS)
+            this.dropHead();
+        if (this.head >= HEAD_COMPACT_THRESHOLD) {
+            this.lines = this.lines.slice(this.head);
+            this.head = 0;
+        }
+    }
+    dropHead() {
+        const line = this.lines[this.head];
+        if (line === undefined)
+            return;
+        this.chars -= line.length;
+        // Release the row before compaction so a large tail is not pinned by an empty slot.
+        this.lines[this.head] = '';
+        this.head += 1;
+        this.droppedRows = true;
+    }
+}
+function clampLimit(limit) {
+    if (limit === undefined || !Number.isFinite(limit))
+        return DEFAULT_TAIL_READ_LIMIT;
+    return Math.max(1, Math.min(Math.floor(limit), MAX_TAIL_READ_LIMIT));
+}
+/**
+ * Apply the character budget from the newest row backwards, so the rows closest
+ * to what the CLI is doing now are the ones that survive.
+ */
+function clipToCharacterBudget(rows, budget) {
+    let total = 0;
+    for (let index = rows.length - 1; index >= 0; index -= 1) {
+        total += rows[index].length + 1;
+        if (total > budget)
+            return { lines: rows.slice(index + 1), limited: true };
+    }
+    return { lines: rows, limited: false };
+}
+//# sourceMappingURL=terminal-tail-buffer.js.map

package/dist/src/session/terminal-tail-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-tail-buffer.js","sourceRoot":"","sources":["../../../src/session/terminal-tail-buffer.ts"],"names":[],"mappings":"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"}

package/dist/src/transport/taskmcp-client.d.ts

@@ -1,11 +1,17 @@
 import { EventEmitter } from 'node:events';
 import type { AgentConfig } from '../config.js';
 import type { DiagnosticLogger } from '../logging/diagnostic-log.js';
-import type { AgentCliAck, AgentCliControlAck, AgentCliEvent, ExecScriptAck, LocalCliDetectAck, WorkspaceAck } from '../types/protocol.js';
+import type { AgentCliAck, AgentCliControlAck, AgentCliEvent, AgentCliOutputTailAck, ExecScriptAck, LocalCliDetectAck, WorkspaceAck } from '../types/protocol.js';
 type ClientEvents = {
     message: [unknown];
     connection: [boolean];
 };
+export type ConnectionFailure = {
+    /** HTTP status of a rejected upgrade, absent for transport-level failures. */
+    status?: number;
+    reason: string;
+    at: string;
+};
 export declare class TaskMcpClient extends EventEmitter<ClientEvents> {
     private readonly config;
     private readonly deviceId;
@@ -15,8 +21,11 @@ export declare class TaskMcpClient extends EventEmitter<ClientEvents> {
     private retryAttempt;
     private reconnectTimer;
     private heartbeat;
+    private failure;
     constructor(config: AgentConfig, deviceId: string, logger: DiagnosticLogger);
     get connected(): boolean;
+    /** Last reason the connection failed, cleared once a handshake succeeds. */
+    get lastFailure(): ConnectionFailure | undefined;
     start(): void;
     stop(): void;
     sendEvent(event: AgentCliEvent): Promise<void>;
@@ -25,6 +34,7 @@ export declare class TaskMcpClient extends EventEmitter<ClientEvents> {
     sendExecScriptAck(ack: ExecScriptAck): Promise<void>;
     sendWorkspaceAck(ack: WorkspaceAck): Promise<void>;
     sendLocalCliDetectAck(ack: LocalCliDetectAck): Promise<void>;
+    sendOutputTailAck(ack: AgentCliOutputTailAck): Promise<void>;
     private send;
     private connect;
     private scheduleReconnect;

package/dist/src/transport/taskmcp-client.js

@@ -1,5 +1,22 @@
 import { EventEmitter } from 'node:events';
 import WebSocket from 'ws';
+/**
+ * Why the handshake was refused, in terms the operator can act on. A rejected
+ * upgrade retries forever otherwise, and `connected: false` alone does not say
+ * whether the credential, the URL, or the network is at fault.
+ */
+function handshakeReason(status) {
+    if (status === 401 || status === 403) {
+        return `服务端拒绝了设备凭据（${status}）。凭据可能已被轮换或吊销，请在客户端重新配对该设备。`;
+    }
+    if (status === 429)
+        return '认证失败次数过多，已被限流（429）。请稍后重试。';
+    if (status === 404)
+        return 'WebSocket 地址不存在（404）。请检查 wsUrl 是否正确。';
+    if (status >= 500)
+        return `服务端暂时不可用（${status}）。`;
+    return `服务端拒绝了 WebSocket 握手（${status}）。`;
+}
 export class TaskMcpClient extends EventEmitter {
     config;
     deviceId;
@@ -9,6 +26,7 @@ export class TaskMcpClient extends EventEmitter {
     retryAttempt = 0;
     reconnectTimer;
     heartbeat;
+    failure;
     constructor(config, deviceId, logger) {
         super();
         this.config = config;
@@ -18,6 +36,10 @@ export class TaskMcpClient extends EventEmitter {
     get connected() {
         return this.socket?.readyState === WebSocket.OPEN;
     }
+    /** Last reason the connection failed, cleared once a handshake succeeds. */
+    get lastFailure() {
+        return this.failure;
+    }
     start() {
         this.stopped = false;
         this.connect();
@@ -47,6 +69,9 @@ export class TaskMcpClient extends EventEmitter {
         return this.send(ack);
     }
     sendLocalCliDetectAck(ack) { return this.send(ack); }
+    sendOutputTailAck(ack) {
+        return this.send(ack);
+    }
     send(message) {
         return new Promise((resolveSend, rejectSend) => {
             if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
@@ -76,8 +101,23 @@ export class TaskMcpClient extends EventEmitter {
         const headers = this.config.authMode === 'mcp' ? { 'X-MCP-Token': this.config.authToken } : undefined;
         const socket = new WebSocket(url, { ...(headers ? { headers } : {}) });
         this.socket = socket;
+        // ws suppresses its default error for a rejected upgrade once this is
+        // observed, so the reconnect has to be scheduled here.
+        socket.on('unexpected-response', (request, response) => {
+            const status = response.statusCode ?? 0;
+            const reason = handshakeReason(status);
+            this.failure = { status, reason, at: new Date().toISOString() };
+            this.logger.error('taskmcp-handshake-rejected', { status, reason });
+            response.resume();
+            request.destroy();
+            if (this.socket === socket)
+                this.socket = undefined;
+            this.emit('connection', false);
+            this.scheduleReconnect();
+        });
         socket.on('open', () => {
             this.retryAttempt = 0;
+            this.failure = undefined;
             this.logger.info('taskmcp-connected', { deviceId: this.deviceId });
             this.emit('connection', true);
             this.heartbeat = setInterval(() => {
@@ -95,6 +135,7 @@ export class TaskMcpClient extends EventEmitter {
             }
         });
         socket.on('error', (error) => {
+            this.failure = { reason: error.message, at: new Date().toISOString() };
             this.logger.warn('taskmcp-socket-error', { error: error.message });
         });
         socket.on('close', (code) => {

package/dist/src/transport/taskmcp-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"taskmcp-client.js","sourceRoot":"","sources":["../../../src/transport/taskmcp-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,SAAS,MAAM,IAAI,CAAA;AAU1B,MAAM,OAAO,aAAc,SAAQ,YAA0B;IAQxC;IACA;IACA;IATX,MAAM,CAAuB;IAC7B,OAAO,GAAG,KAAK,CAAA;IACf,YAAY,GAAG,CAAC,CAAA;IAChB,cAAc,CAA4B;IAC1C,SAAS,CAA4B;IAE7C,YACmB,MAAmB,EACnB,QAAgB,EAChB,MAAwB;QAEzC,KAAK,EAAE,CAAA;QAJU,WAAM,GAAN,MAAM,CAAa;QACnB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,WAAM,GAAN,MAAM,CAAkB;IAG3C,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,MAAM,EAAE,UAAU,KAAK,SAAS,CAAC,IAAI,CAAA;IACnD,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,KAAK,CAAA;QACpB,IAAI,CAAC,OAAO,EAAE,CAAA;IAChB,CAAC;IAED,IAAI;QACF,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;QACnB,IAAI,IAAI,CAAC,cAAc;YAAE,YAAY,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;QAC1D,IAAI,IAAI,CAAC,SAAS;YAAE,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;QACjD,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAA;QAC1C,IAAI,CAAC,MAAM,GAAG,SAAS,CAAA;IACzB,CAAC;IAED,SAAS,CAAC,KAAoB;QAC5B,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACzB,CAAC;IAED,OAAO,CAAC,GAAgB;QACtB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACvB,CAAC;IAED,cAAc,CAAC,GAAuB;QACpC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACvB,CAAC;IAED,iBAAiB,CAAC,GAAkB;QAClC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACvB,CAAC;IAED,gBAAgB,CAAC,GAAiB;QAChC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACvB,CAAC;IAED,qBAAqB,CAAC,GAAsB,IAAmB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA,CAAC,CAAC;IAE9E,IAAI,CAAC,OAA4G;QACvH,OAAO,IAAI,OAAO,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,EAAE;YAC7C,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;gBAC9D,UAAU,CAAC,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC,CAAA;gBAC3D,OAAM;YACR,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE;gBAClD,IAAI,KAAK;oBAAE,UAAU,CAAC,KAAK,CAAC,CAAA;;oBACvB,WAAW,EAAE,CAAA;YACpB,CAAC,CAAC,CAAA;QACJ,CAAC,CAAC,CAAA;IACJ,CAAC;IAEO,OAAO;QACb,IAAI,IAAI,CAAC,OAAO;YAAE,OAAM;QACxB,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACtC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAA;QAC/C,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;QAC5C,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QACtD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;QACpD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QACtD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;QACxE,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,QAAQ;YAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;QAE3F,MAAM,OAAO,GACX,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;QACvF,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;QACtE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QAEpB,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;YACrB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAA;YACrB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAA;YAClE,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,CAAA;YAC7B,IAAI,CAAC,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;gBAChC,oEAAoE;gBACpE,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI;oBAAE,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAA;YAC1E,CAAC,EAAE,MAAM,CAAC,CAAA;QACZ,CAAC,CAAC,CAAA;QAEF,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE;YAC5B,IAAI,CAAC;gBACH,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAA;YACnD,CAAC;YAAC,MAAM,CAAC;gBACP,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAA;YAC1C,CAAC;QACH,CAAC,CAAC,CAAA;QAEF,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC3B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,sBAAsB,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAA;QACpE,CAAC,CAAC,CAAA;QAEF,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YAC1B,IAAI,IAAI,CAAC,SAAS;gBAAE,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;YACjD,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;YAC1B,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM;gBAAE,IAAI,CAAC,MAAM,GAAG,SAAS,CAAA;YACnD,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,CAAA;YAC9B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,sBAAsB,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;YAClD,IAAI,CAAC,iBAAiB,EAAE,CAAA;QAC1B,CAAC,CAAC,CAAA;IACJ,CAAC;IAEO,iBAAiB;QACvB,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,cAAc;YAAE,OAAM;QAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC,CAAA;QAC/D,MAAM,KAAK,GAAG,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAA;QACpD,IAAI,CAAC,cAAc,GAAG,UAAU,CAAC,GAAG,EAAE;YACpC,IAAI,CAAC,cAAc,GAAG,SAAS,CAAA;YAC/B,IAAI,CAAC,OAAO,EAAE,CAAA;QAChB,CAAC,EAAE,KAAK,CAAC,CAAA;IACX,CAAC;CACF"}
+{"version":3,"file":"taskmcp-client.js","sourceRoot":"","sources":["../../../src/transport/taskmcp-client.ts"],"names":[],"mappings":"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"}

package/dist/src/types/protocol.d.ts

@@ -47,6 +47,45 @@ export type LocalCliDetectAck = {
     snapshot?: Record<string, unknown>;
     error?: string;
 };
+/**
+ * On-demand read of a live CLI session's newest terminal rows. Modelled on
+ * Orca's `terminal.read`: no cursor returns a preview of the newest rows, a
+ * cursor pages backwards through rows the reader has not seen yet.
+ *
+ * Either `run_id` or `task_id` must identify the session. Sessions are reused
+ * across runs, so `task_id` still resolves after a later prompt took over.
+ */
+export declare const AgentCliOutputTailRequestSchema: z.ZodObject<{
+    type: z.ZodLiteral<"agent_cli.output_tail">;
+    request_id: z.ZodString;
+    run_id: z.ZodOptional<z.ZodString>;
+    task_id: z.ZodOptional<z.ZodString>;
+    agent_type: z.ZodOptional<z.ZodString>;
+    lines: z.ZodOptional<z.ZodNumber>;
+    before_cursor: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type AgentCliOutputTailRequest = z.infer<typeof AgentCliOutputTailRequestSchema>;
+export type AgentCliOutputTailAck = {
+    type: 'agent_cli.output_tail.ack';
+    request_id: string;
+    status: 'done' | 'idle' | 'failed';
+    run_id?: string;
+    session_id?: string;
+    agent_type?: string;
+    lines?: string[];
+    /** Absolute index of the first returned row; pass back as `before_cursor` to page up. */
+    start_cursor?: number;
+    next_cursor?: number;
+    oldest_cursor?: number;
+    latest_cursor?: number;
+    has_more?: boolean;
+    truncated?: boolean;
+    limited?: boolean;
+    /** Milliseconds since the CLI last wrote. The strongest "is it alive" signal. */
+    idle_ms?: number | null;
+    markers?: string[];
+    error?: string;
+};
 export declare const ExecScriptRequestSchema: z.ZodObject<{
     type: z.ZodLiteral<"exec_script">;
     log_id: z.ZodString;

package/dist/src/types/protocol.js

@@ -40,6 +40,33 @@ export const LocalCliDetectRequestSchema = z.object({
     request_id: z.string().min(1).max(128),
     refresh: z.boolean().optional().default(false)
 });
+/**
+ * On-demand read of a live CLI session's newest terminal rows. Modelled on
+ * Orca's `terminal.read`: no cursor returns a preview of the newest rows, a
+ * cursor pages backwards through rows the reader has not seen yet.
+ *
+ * Either `run_id` or `task_id` must identify the session. Sessions are reused
+ * across runs, so `task_id` still resolves after a later prompt took over.
+ */
+export const AgentCliOutputTailRequestSchema = z
+    .object({
+    type: z.literal('agent_cli.output_tail'),
+    request_id: z.string().min(1).max(128),
+    run_id: z.string().min(1).max(128).optional(),
+    task_id: z.string().min(1).max(128).optional(),
+    agent_type: z.string().min(1).max(40).optional(),
+    lines: z.number().int().positive().max(2_000).optional(),
+    before_cursor: z.number().int().min(0).optional()
+})
+    .superRefine((request, context) => {
+    if (!request.run_id?.trim() && !request.task_id?.trim()) {
+        context.addIssue({
+            code: 'custom',
+            path: ['run_id'],
+            message: 'output tail requests must provide run_id or task_id'
+        });
+    }
+});
 export const ExecScriptRequestSchema = z.object({
     type: z.literal('exec_script'),
     log_id: z.string().min(1).max(128),

package/dist/src/types/protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../src/types/protocol.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../src/types/protocol.ts"],"names":[],"mappings":"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"}

package/dist/tests/terminal-tail-buffer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/terminal-tail-buffer.test.js

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import { MAX_TAIL_LINES, TerminalTailBuffer } from '../src/session/terminal-tail-buffer.js';
+describe('TerminalTailBuffer', () => {
+    it('returns the newest rows and pages backwards without gaps or repeats', () => {
+        const buffer = new TerminalTailBuffer();
+        for (let index = 1; index <= 10; index += 1)
+            buffer.append(`row ${index}\n`);
+        const latest = buffer.read({ limit: 4 });
+        expect(latest.lines).toEqual(['row 7', 'row 8', 'row 9', 'row 10']);
+        expect(latest.startCursor).toBe(6);
+        expect(latest.latestCursor).toBe(10);
+        expect(latest.hasMore).toBe(true);
+        const older = buffer.read({ limit: 4, beforeCursor: latest.startCursor });
+        expect(older.lines).toEqual(['row 3', 'row 4', 'row 5', 'row 6']);
+        expect(older.nextCursor).toBe(latest.startCursor);
+        const oldest = buffer.read({ limit: 4, beforeCursor: older.startCursor });
+        expect(oldest.lines).toEqual(['row 1', 'row 2']);
+        expect(oldest.hasMore).toBe(false);
+    });
+    it('shows the row still being written, and excludes it from cursor reads', () => {
+        const buffer = new TerminalTailBuffer();
+        buffer.append('done\nin progre');
+        const latest = buffer.read();
+        expect(latest.lines).toEqual(['done', 'in progre']);
+        expect(latest.latestCursor).toBe(1);
+        buffer.append('ss\n');
+        expect(buffer.read().lines).toEqual(['done', 'in progress']);
+    });
+    it('keeps only the visible text of a carriage-return redraw', () => {
+        const buffer = new TerminalTailBuffer();
+        buffer.append('Thinking 10%\rThinking 55%\rThinking 100%\n');
+        expect(buffer.read().lines).toEqual(['Thinking 100%']);
+    });
+    it('splits CRLF without leaving a stray carriage return', () => {
+        const buffer = new TerminalTailBuffer();
+        buffer.append('first\r\nsecond\r\n');
+        expect(buffer.read().lines).toEqual(['first', 'second']);
+    });
+    it('strips escape sequences and redacts credential-shaped values', () => {
+        const buffer = new TerminalTailBuffer();
+        buffer.append('\u001b[32mok\u001b[0m   \nAuthorization: Bearer abc.def\n');
+        buffer.append('loaded sk_live_abcdefgh into env\n');
+        expect(buffer.read().lines).toEqual([
+            'ok',
+            '[redacted]',
+            'loaded [redacted] into env'
+        ]);
+    });
+    it('drops the oldest rows past the retention cap and reports truncation', () => {
+        const buffer = new TerminalTailBuffer();
+        for (let index = 0; index < MAX_TAIL_LINES + 50; index += 1) {
+            buffer.append(`row ${index}\n`);
+        }
+        const read = buffer.read({ limit: 1 });
+        expect(read.truncated).toBe(true);
+        expect(read.oldestCursor).toBe(50);
+        expect(read.latestCursor).toBe(MAX_TAIL_LINES + 50);
+        // A cursor below the retained range clamps instead of returning stale rows.
+        expect(buffer.read({ limit: 5, beforeCursor: 10 }).lines).toEqual([]);
+    });
+    it('reports how long the CLI has been silent', () => {
+        const buffer = new TerminalTailBuffer();
+        expect(buffer.read().idleMs).toBeUndefined();
+        buffer.append('working\n', 1_000);
+        expect(buffer.read({}, 4_500).idleMs).toBe(3_500);
+    });
+});
+//# sourceMappingURL=terminal-tail-buffer.test.js.map

package/dist/tests/terminal-tail-buffer.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-tail-buffer.test.js","sourceRoot":"","sources":["../../tests/terminal-tail-buffer.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echo-cli-agent",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Local CLI bridge agent",
   "type": "module",
   "bin": {