@a1hvdy/cc-openclaw 0.24.0 → 0.25.0

package/dist/src/channels/telegram-mirror/sessions-keyboard.d.ts

@@ -0,0 +1,84 @@
+/**
+ * src/channels/telegram-mirror/sessions-keyboard.ts — v0.25.0 M3.
+ *
+ * Builds the inline keyboard for /sessions. Pure function — takes a row
+ * list + page index + a CallbackMap, returns Telegram's inline_keyboard
+ * shape. Caller is responsible for sending/editing the surrounding
+ * Telegram message via the dispatch layer.
+ *
+ * Decision refs:
+ *   • ADR-003 — slug ↔ sessionName comes from session-registry; the row
+ *     list here is a denormalised SessionRow because the keyboard also
+ *     needs live state + lastUsedAt, which the registry doesn't track
+ *     (state lives in session-manager, time-since lives in the registry's
+ *     lastUsedAt). The handler in M4 stitches them together.
+ *   • ADR-004 — every callback_data slot is a CallbackMap id, not a raw
+ *     JSON payload. Keeps every button under the 64-byte cap by design.
+ *   • ADR-005 — page size is 8; 9th row is "▶ More" when more pages exist.
+ */
+import type { CallbackMap } from './callback-mapping.js';
+export declare const SESSIONS_PAGE_SIZE = 8;
+export type SessionState = 'running' | 'stopped' | 'idle';
+export interface SessionRow {
+    slug: string;
+    sessionName: string;
+    state: SessionState;
+    /** ISO timestamp — the registry's lastUsedAt. */
+    lastUsedAt: string;
+}
+export interface InlineButton {
+    text: string;
+    callback_data: string;
+}
+export interface SessionsKeyboardResult {
+    inline_keyboard: InlineButton[][];
+    /** Zero-indexed page rendered. */
+    page: number;
+    /** Total page count (≥ 1 even when rows is empty). */
+    pageCount: number;
+    /** True when there is at least one page after the rendered one. */
+    hasMore: boolean;
+}
+/**
+ * Compact relative-time string for a row's lastUsedAt.
+ *   < 60s   →  "<1m"
+ *   < 1h    →  "Nm"
+ *   < 1d    →  "Nh"
+ *   else    →  "Nd"
+ * Designed to fit in 4 chars so the row stays narrow on phone Telegram.
+ */
+export declare function formatLastActivity(lastUsedAt: string, now?: number): string;
+/**
+ * Format a row label.  "cc-openclaw · 🟢 · 2m"
+ */
+export declare function formatSessionRowLabel(row: SessionRow, now?: number): string;
+export interface SessionsKeyboardOpts {
+    rows: SessionRow[];
+    /** Zero-indexed page; clamped into [0, pageCount-1]. */
+    page?: number;
+    callbackMap: CallbackMap;
+    /** Override clock for tests. */
+    now?: number;
+}
+/**
+ * Build the full /sessions inline keyboard. Layout:
+ *
+ *   Row 1..N    session rows (one button each)        (N ≤ 8)
+ *   Row N+1     "▶ More" — only when hasMore===true
+ *   Row last    "➕ New" "🗑 Stop" "✖ Close"          (always)
+ *
+ * Every button's callback_data is a CallbackMap id pointing at a payload:
+ *   session row →  { action: 'switch', slug }
+ *   ▶ More       →  { action: 'page', page: N+1 }
+ *   ➕ New       →  { action: 'new' }
+ *   🗑 Stop      →  { action: 'stop' }
+ *   ✖ Close      →  { action: 'close' }
+ */
+export declare function buildSessionsKeyboard(opts: SessionsKeyboardOpts): SessionsKeyboardResult;
+/**
+ * Helper: every button's callback_data must fit in 64 UTF-8 bytes per
+ * Telegram's API. We enforce this at build time as a defense-in-depth
+ * check — even an 8-char id is well under, but a future refactor that
+ * stuffs raw JSON would silently break Telegram without this assertion.
+ */
+export declare function assertCallbackDataBudget(keyboard: SessionsKeyboardResult): void;

package/dist/src/channels/telegram-mirror/sessions-keyboard.js

@@ -0,0 +1,113 @@
+/**
+ * src/channels/telegram-mirror/sessions-keyboard.ts — v0.25.0 M3.
+ *
+ * Builds the inline keyboard for /sessions. Pure function — takes a row
+ * list + page index + a CallbackMap, returns Telegram's inline_keyboard
+ * shape. Caller is responsible for sending/editing the surrounding
+ * Telegram message via the dispatch layer.
+ *
+ * Decision refs:
+ *   • ADR-003 — slug ↔ sessionName comes from session-registry; the row
+ *     list here is a denormalised SessionRow because the keyboard also
+ *     needs live state + lastUsedAt, which the registry doesn't track
+ *     (state lives in session-manager, time-since lives in the registry's
+ *     lastUsedAt). The handler in M4 stitches them together.
+ *   • ADR-004 — every callback_data slot is a CallbackMap id, not a raw
+ *     JSON payload. Keeps every button under the 64-byte cap by design.
+ *   • ADR-005 — page size is 8; 9th row is "▶ More" when more pages exist.
+ */
+export const SESSIONS_PAGE_SIZE = 8;
+const STATE_EMOJI = {
+    running: '🟢',
+    stopped: '⚫',
+    idle: '🟡',
+};
+/**
+ * Compact relative-time string for a row's lastUsedAt.
+ *   < 60s   →  "<1m"
+ *   < 1h    →  "Nm"
+ *   < 1d    →  "Nh"
+ *   else    →  "Nd"
+ * Designed to fit in 4 chars so the row stays narrow on phone Telegram.
+ */
+export function formatLastActivity(lastUsedAt, now = Date.now()) {
+    const t = new Date(lastUsedAt).getTime();
+    if (!Number.isFinite(t))
+        return '?';
+    const ms = Math.max(0, now - t);
+    if (ms < 60_000)
+        return '<1m';
+    if (ms < 3_600_000)
+        return `${Math.floor(ms / 60_000)}m`;
+    if (ms < 86_400_000)
+        return `${Math.floor(ms / 3_600_000)}h`;
+    return `${Math.floor(ms / 86_400_000)}d`;
+}
+/**
+ * Format a row label.  "cc-openclaw · 🟢 · 2m"
+ */
+export function formatSessionRowLabel(row, now = Date.now()) {
+    return `${row.slug} · ${STATE_EMOJI[row.state]} · ${formatLastActivity(row.lastUsedAt, now)}`;
+}
+/**
+ * Build the full /sessions inline keyboard. Layout:
+ *
+ *   Row 1..N    session rows (one button each)        (N ≤ 8)
+ *   Row N+1     "▶ More" — only when hasMore===true
+ *   Row last    "➕ New" "🗑 Stop" "✖ Close"          (always)
+ *
+ * Every button's callback_data is a CallbackMap id pointing at a payload:
+ *   session row →  { action: 'switch', slug }
+ *   ▶ More       →  { action: 'page', page: N+1 }
+ *   ➕ New       →  { action: 'new' }
+ *   🗑 Stop      →  { action: 'stop' }
+ *   ✖ Close      →  { action: 'close' }
+ */
+export function buildSessionsKeyboard(opts) {
+    const { rows, callbackMap, now = Date.now() } = opts;
+    const pageCount = Math.max(1, Math.ceil(rows.length / SESSIONS_PAGE_SIZE));
+    const page = Math.min(Math.max(0, opts.page ?? 0), pageCount - 1);
+    const start = page * SESSIONS_PAGE_SIZE;
+    const slice = rows.slice(start, start + SESSIONS_PAGE_SIZE);
+    const hasMore = page < pageCount - 1;
+    const inline_keyboard = [];
+    for (const row of slice) {
+        inline_keyboard.push([
+            {
+                text: formatSessionRowLabel(row, now),
+                callback_data: callbackMap.create({ action: 'switch', slug: row.slug }),
+            },
+        ]);
+    }
+    if (hasMore) {
+        inline_keyboard.push([
+            {
+                text: '▶ More',
+                callback_data: callbackMap.create({ action: 'page', page: page + 1 }),
+            },
+        ]);
+    }
+    inline_keyboard.push([
+        { text: '➕ New', callback_data: callbackMap.create({ action: 'new' }) },
+        { text: '🗑 Stop', callback_data: callbackMap.create({ action: 'stop' }) },
+        { text: '✖ Close', callback_data: callbackMap.create({ action: 'close' }) },
+    ]);
+    return { inline_keyboard, page, pageCount, hasMore };
+}
+/**
+ * Helper: every button's callback_data must fit in 64 UTF-8 bytes per
+ * Telegram's API. We enforce this at build time as a defense-in-depth
+ * check — even an 8-char id is well under, but a future refactor that
+ * stuffs raw JSON would silently break Telegram without this assertion.
+ */
+export function assertCallbackDataBudget(keyboard) {
+    for (const row of keyboard.inline_keyboard) {
+        for (const btn of row) {
+            const bytes = Buffer.byteLength(btn.callback_data, 'utf8');
+            if (bytes > 64) {
+                throw new Error(`[cc-openclaw/telegram-mirror/sessions-keyboard] callback_data exceeds 64-byte cap (${bytes}b) on button "${btn.text}"`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=sessions-keyboard.js.map

package/dist/src/channels/telegram-mirror/sessions-keyboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions-keyboard.js","sourceRoot":"","sources":["../../../../src/channels/telegram-mirror/sessions-keyboard.ts"],"names":[],"mappings":"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"}

package/dist/src/channels/telegram-mirror/soak-log.d.ts

@@ -0,0 +1,98 @@
+/**
+ * src/channels/telegram-mirror/soak-log.ts — v0.25.0 M14.
+ *
+ * Daily JSONL incident + activity log for the 2-week soak (M14 → M15
+ * cutover gate). Writes append-only rows to
+ *   workspace/memory/mirror-soak-<YYYY-MM-DD>.jsonl
+ * per PRP §5 M14. The file rolls at UTC midnight (date-stamped path).
+ *
+ * Three row types per spec:
+ *   • laptop-check       — A1 self-reports opened-laptop-today via /soak-check.
+ *   • failure-incident   — fires once per M12 handler invocation in soak.
+ *   • slash-invocation   — one row per slash command dispatch.
+ *
+ * Idempotency: a single laptop-check per UTC day. recordLaptopCheck()
+ * returns false on the second call within a day so the /soak-check
+ * handler can surface "already recorded today" UX rather than logging
+ * duplicates.
+ *
+ * Decision-link: this file is the only filesystem-touching mirror module
+ * outside session-registry (M1). Both share the atomic-write-via-rename
+ * idiom; soak-log appends so it doesn't need the tmpfile dance, but the
+ * path resolution is the same shape.
+ */
+export type SoakRow = SoakLaptopCheckRow | SoakFailureRow | SoakSlashRow;
+export interface SoakLaptopCheckRow {
+    ts: string;
+    type: 'laptop-check';
+    openedLaptop: boolean;
+}
+export interface SoakFailureRow {
+    ts: string;
+    type: 'failure-incident';
+    mode: string;
+    chatId: string | number;
+    info?: unknown;
+}
+export interface SoakSlashRow {
+    ts: string;
+    type: 'slash-invocation';
+    cmd: string;
+    chatId: string | number;
+}
+export interface SoakLoggerOptions {
+    /** Override base dir for tests (defaults to ~/.openclaw/workspace/memory). */
+    dir?: string;
+    /** Override clock for tests. */
+    now?: () => Date;
+}
+export declare class SoakLogger {
+    private readonly dir;
+    private readonly now;
+    constructor(opts?: SoakLoggerOptions);
+    /**
+     * Absolute path of today's JSONL file. Honors the configured clock.
+     */
+    pathForToday(): string;
+    /**
+     * Append a row to today's file. Creates the parent directory if missing.
+     * Each row is `JSON.stringify(row) + '\n'`.
+     */
+    append(row: SoakRow): void;
+    /**
+     * Read all rows for today (parsing each line). Returns [] when the
+     * file is missing OR when every line is malformed.
+     */
+    readToday(): SoakRow[];
+    /**
+     * Returns true iff a laptop-check row has already been written today.
+     * Used by /soak-check's once-per-day gate.
+     */
+    hasLaptopCheckToday(): boolean;
+    /**
+     * Idempotent laptop-check writer. Returns true when the row was
+     * persisted, false when a check was already recorded today.
+     */
+    recordLaptopCheck(openedLaptop: boolean): boolean;
+    /**
+     * Failure-incident logger — called by the dispatcher when a M12
+     * handler fires. The info payload is opaque JSON; the schema is
+     * per-mode and lives in the handler's documentation.
+     */
+    recordFailure(mode: string, chatId: string | number, info?: unknown): void;
+    /**
+     * Slash-invocation logger — called once per dispatchCommand call by
+     * the dispatcher (M5+). Cheap to record and lets the soak surface
+     * which commands A1 actually uses on phone.
+     */
+    recordSlash(cmd: string, chatId: string | number): void;
+    /**
+     * Count rows by type for the day — used by M15's "5/7 no-laptop days"
+     * gate without having to ship a separate aggregator.
+     */
+    countByType(): {
+        'laptop-check': number;
+        'failure-incident': number;
+        'slash-invocation': number;
+    };
+}

package/dist/src/channels/telegram-mirror/soak-log.js

@@ -0,0 +1,136 @@
+/**
+ * src/channels/telegram-mirror/soak-log.ts — v0.25.0 M14.
+ *
+ * Daily JSONL incident + activity log for the 2-week soak (M14 → M15
+ * cutover gate). Writes append-only rows to
+ *   workspace/memory/mirror-soak-<YYYY-MM-DD>.jsonl
+ * per PRP §5 M14. The file rolls at UTC midnight (date-stamped path).
+ *
+ * Three row types per spec:
+ *   • laptop-check       — A1 self-reports opened-laptop-today via /soak-check.
+ *   • failure-incident   — fires once per M12 handler invocation in soak.
+ *   • slash-invocation   — one row per slash command dispatch.
+ *
+ * Idempotency: a single laptop-check per UTC day. recordLaptopCheck()
+ * returns false on the second call within a day so the /soak-check
+ * handler can surface "already recorded today" UX rather than logging
+ * duplicates.
+ *
+ * Decision-link: this file is the only filesystem-touching mirror module
+ * outside session-registry (M1). Both share the atomic-write-via-rename
+ * idiom; soak-log appends so it doesn't need the tmpfile dance, but the
+ * path resolution is the same shape.
+ */
+import { appendFileSync, readFileSync, existsSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+function defaultDir() {
+    return join(homedir(), '.openclaw', 'workspace', 'memory');
+}
+function ymd(d) {
+    return d.toISOString().slice(0, 10); // YYYY-MM-DD (UTC)
+}
+export class SoakLogger {
+    dir;
+    now;
+    constructor(opts = {}) {
+        this.dir = opts.dir ?? defaultDir();
+        this.now = opts.now ?? (() => new Date());
+    }
+    /**
+     * Absolute path of today's JSONL file. Honors the configured clock.
+     */
+    pathForToday() {
+        return join(this.dir, `mirror-soak-${ymd(this.now())}.jsonl`);
+    }
+    /**
+     * Append a row to today's file. Creates the parent directory if missing.
+     * Each row is `JSON.stringify(row) + '\n'`.
+     */
+    append(row) {
+        const path = this.pathForToday();
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, JSON.stringify(row) + '\n');
+    }
+    /**
+     * Read all rows for today (parsing each line). Returns [] when the
+     * file is missing OR when every line is malformed.
+     */
+    readToday() {
+        const path = this.pathForToday();
+        if (!existsSync(path))
+            return [];
+        const raw = readFileSync(path, 'utf8');
+        const out = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                /* skip malformed line — defensive */
+            }
+        }
+        return out;
+    }
+    /**
+     * Returns true iff a laptop-check row has already been written today.
+     * Used by /soak-check's once-per-day gate.
+     */
+    hasLaptopCheckToday() {
+        return this.readToday().some((r) => r.type === 'laptop-check');
+    }
+    /**
+     * Idempotent laptop-check writer. Returns true when the row was
+     * persisted, false when a check was already recorded today.
+     */
+    recordLaptopCheck(openedLaptop) {
+        if (this.hasLaptopCheckToday())
+            return false;
+        this.append({
+            ts: this.now().toISOString(),
+            type: 'laptop-check',
+            openedLaptop,
+        });
+        return true;
+    }
+    /**
+     * Failure-incident logger — called by the dispatcher when a M12
+     * handler fires. The info payload is opaque JSON; the schema is
+     * per-mode and lives in the handler's documentation.
+     */
+    recordFailure(mode, chatId, info) {
+        this.append({
+            ts: this.now().toISOString(),
+            type: 'failure-incident',
+            mode,
+            chatId,
+            info,
+        });
+    }
+    /**
+     * Slash-invocation logger — called once per dispatchCommand call by
+     * the dispatcher (M5+). Cheap to record and lets the soak surface
+     * which commands A1 actually uses on phone.
+     */
+    recordSlash(cmd, chatId) {
+        this.append({
+            ts: this.now().toISOString(),
+            type: 'slash-invocation',
+            cmd,
+            chatId,
+        });
+    }
+    /**
+     * Count rows by type for the day — used by M15's "5/7 no-laptop days"
+     * gate without having to ship a separate aggregator.
+     */
+    countByType() {
+        const out = { 'laptop-check': 0, 'failure-incident': 0, 'slash-invocation': 0 };
+        for (const r of this.readToday())
+            out[r.type] += 1;
+        return out;
+    }
+}
+//# sourceMappingURL=soak-log.js.map

package/dist/src/channels/telegram-mirror/soak-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"soak-log.js","sourceRoot":"","sources":["../../../../src/channels/telegram-mirror/soak-log.ts"],"names":[],"mappings":"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"}

package/dist/src/channels/telegram-mirror/state-machine.d.ts

@@ -0,0 +1,102 @@
+/**
+ * src/channels/telegram-mirror/state-machine.ts — v0.25.0 M2.
+ *
+ * Per-chat turn-lifecycle state machine for the Telegram Terminal Mirror.
+ * Consumes Claude stream events (tool_use / tool_result / text / turn_done)
+ * and produces a Turn object the card-renderer (sibling module) can format
+ * into Telegram message bodies.
+ *
+ * Naming note: this is NOT a 1:1 port of the legacy state-machine.ts —
+ * legacy is a message_sending cross-path-dedup hook. Per ADR-001 (mimic
+ * the terminal flow) the mirror's state-machine models what a user sees
+ * during a turn (running tools → completion), which is closer to a UI
+ * controller than legacy's API-dispatch hook. The name is reused for
+ * cross-reference clarity; the shape diverges intentionally.
+ *
+ * Pure module — no I/O, no Telegram-API calls. Wiring into register() and
+ * the actual gateway event bus lands in M3/M4 once /sessions provides a
+ * user-facing entry point. M2's scope: the abstraction + tests.
+ */
+/**
+ * Stream event shape (mirrors the subset of legacy card-renderer.ts
+ * StreamEvent that the mirror actually consumes). Re-exported here so
+ * dependents don't need to import from the legacy directory.
+ */
+export interface StreamEvent {
+    type: string;
+    id?: string;
+    tool_use_id?: string;
+    tool?: {
+        name?: string;
+        input?: Record<string, unknown>;
+    };
+    tool_name?: string;
+    input?: Record<string, unknown>;
+    content?: unknown;
+    output?: unknown;
+    is_error?: boolean;
+    error?: unknown;
+    result?: string;
+}
+export type TurnState = 'working' | 'done';
+export interface ToolCallRecord {
+    /** Tool name (e.g. "Bash", "Read", "Edit"). */
+    name: string;
+    /** Tool input arguments (snapshot at tool_use time). */
+    input: Record<string, unknown>;
+    /** Telegram-readable tool-use id, used to match tool_result events. */
+    toolUseId: string;
+    /** Set when the matching tool_result event arrives. */
+    result?: unknown;
+    /** True if the tool_result event flagged is_error/error. */
+    isError?: boolean;
+}
+export interface Turn {
+    /** Telegram chat id this turn is rendering into. */
+    chatId: string;
+    /** Lifecycle state. */
+    state: TurnState;
+    /** Monotonic timestamp (Date.now()) when the turn started. */
+    startedAt: number;
+    /** Set when the turn transitions to 'done'. */
+    endedAt?: number;
+    /** Tool calls observed during the turn, in arrival order. */
+    toolCalls: ToolCallRecord[];
+    /** Accumulated assistant text (concatenation of text events). */
+    assistantText: string;
+    /** Accumulated extended-thinking text (M6). Rendered above assistant text. */
+    thinkingText: string;
+}
+export declare class TurnStateMachine {
+    private readonly turns;
+    /**
+     * Start (or restart) a turn for the given chat. If a turn already exists,
+     * its 'done' state is preserved as the prior turn until a new start
+     * overwrites it — the mirror does not keep history at this layer.
+     */
+    start(chatId: string, now?: number): Turn;
+    /**
+     * Apply a stream event. Returns the updated turn, or undefined if no
+     * turn is active for the chat. The state machine accepts:
+     *   - tool_use     → push a ToolCallRecord
+     *   - tool_result  → resolve the matching ToolCallRecord
+     *   - text         → append to assistantText
+     * Other event types are ignored at this layer; downstream milestones add
+     * thinking/insight handling (M6) and plan-mode handling (M9).
+     */
+    applyEvent(chatId: string, event: StreamEvent): Turn | undefined;
+    /**
+     * End the active turn for chatId. Transitions state to 'done' and stamps
+     * endedAt. Returns the finalized turn, or undefined if no turn was active.
+     */
+    end(chatId: string, now?: number): Turn | undefined;
+    /**
+     * Returns the active or most-recently-ended turn for chatId.
+     */
+    getTurn(chatId: string): Turn | undefined;
+    /**
+     * Drop the cached turn. Test-only convenience; production code starts a
+     * new turn instead.
+     */
+    clear(chatId: string): void;
+}

package/dist/src/channels/telegram-mirror/state-machine.js

@@ -0,0 +1,117 @@
+/**
+ * src/channels/telegram-mirror/state-machine.ts — v0.25.0 M2.
+ *
+ * Per-chat turn-lifecycle state machine for the Telegram Terminal Mirror.
+ * Consumes Claude stream events (tool_use / tool_result / text / turn_done)
+ * and produces a Turn object the card-renderer (sibling module) can format
+ * into Telegram message bodies.
+ *
+ * Naming note: this is NOT a 1:1 port of the legacy state-machine.ts —
+ * legacy is a message_sending cross-path-dedup hook. Per ADR-001 (mimic
+ * the terminal flow) the mirror's state-machine models what a user sees
+ * during a turn (running tools → completion), which is closer to a UI
+ * controller than legacy's API-dispatch hook. The name is reused for
+ * cross-reference clarity; the shape diverges intentionally.
+ *
+ * Pure module — no I/O, no Telegram-API calls. Wiring into register() and
+ * the actual gateway event bus lands in M3/M4 once /sessions provides a
+ * user-facing entry point. M2's scope: the abstraction + tests.
+ */
+export class TurnStateMachine {
+    turns = new Map();
+    /**
+     * Start (or restart) a turn for the given chat. If a turn already exists,
+     * its 'done' state is preserved as the prior turn until a new start
+     * overwrites it — the mirror does not keep history at this layer.
+     */
+    start(chatId, now = Date.now()) {
+        const turn = {
+            chatId,
+            state: 'working',
+            startedAt: now,
+            toolCalls: [],
+            assistantText: '',
+            thinkingText: '',
+        };
+        this.turns.set(chatId, turn);
+        return turn;
+    }
+    /**
+     * Apply a stream event. Returns the updated turn, or undefined if no
+     * turn is active for the chat. The state machine accepts:
+     *   - tool_use     → push a ToolCallRecord
+     *   - tool_result  → resolve the matching ToolCallRecord
+     *   - text         → append to assistantText
+     * Other event types are ignored at this layer; downstream milestones add
+     * thinking/insight handling (M6) and plan-mode handling (M9).
+     */
+    applyEvent(chatId, event) {
+        const turn = this.turns.get(chatId);
+        if (!turn)
+            return undefined;
+        if (turn.state !== 'working')
+            return turn;
+        if (event.type === 'tool_use') {
+            turn.toolCalls.push({
+                name: event.tool?.name ?? 'Unknown',
+                input: event.tool?.input ?? {},
+                toolUseId: event.id ?? event.tool_use_id ?? '',
+            });
+            return turn;
+        }
+        if (event.type === 'tool_result') {
+            const useId = event.tool_use_id ?? event.id ?? '';
+            const match = turn.toolCalls.find((tc) => tc.toolUseId === useId);
+            if (match) {
+                match.result = event.content ?? event.output ?? '';
+                match.isError = Boolean(event.is_error || event.error);
+            }
+            return turn;
+        }
+        if (event.type === 'text') {
+            turn.assistantText += event.result ?? '';
+            return turn;
+        }
+        if (event.type === 'thinking') {
+            // M6: extended-thinking deltas land here. Claude's API emits these
+            // separately from 'text' events; the mirror accumulates them so the
+            // renderer can surface them above the assistant text per ADR-001
+            // (mimic the terminal flow — terminal users see thinking before
+            // the response renders).
+            const piece = typeof event.result === 'string'
+                ? event.result
+                : typeof event.content === 'string'
+                    ? event.content
+                    : '';
+            turn.thinkingText += piece;
+            return turn;
+        }
+        return turn;
+    }
+    /**
+     * End the active turn for chatId. Transitions state to 'done' and stamps
+     * endedAt. Returns the finalized turn, or undefined if no turn was active.
+     */
+    end(chatId, now = Date.now()) {
+        const turn = this.turns.get(chatId);
+        if (!turn)
+            return undefined;
+        turn.state = 'done';
+        turn.endedAt = now;
+        return turn;
+    }
+    /**
+     * Returns the active or most-recently-ended turn for chatId.
+     */
+    getTurn(chatId) {
+        return this.turns.get(chatId);
+    }
+    /**
+     * Drop the cached turn. Test-only convenience; production code starts a
+     * new turn instead.
+     */
+    clear(chatId) {
+        this.turns.delete(chatId);
+    }
+}
+//# sourceMappingURL=state-machine.js.map

package/dist/src/channels/telegram-mirror/state-machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.js","sourceRoot":"","sources":["../../../../src/channels/telegram-mirror/state-machine.ts"],"names":[],"mappings":"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"}