@agentdeck/bridge 1.0.24 → 1.2.0

package/dist/openclaw-transcript-timeline.js

@@ -0,0 +1,328 @@
+/**
+ * Timeline rows read from OpenClaw's OWN on-disk session store.
+ *
+ * WHY THIS EXISTS. OpenClaw reaches this daemon through the Gateway WebSocket
+ * event stream and nothing else — the adapter's whole RPC surface is `connect`
+ * / `sessions.list` / `chat.send` / `chat.abort` / `exec.approval.*`. That
+ * stream carries the prompt, the final response, and the approvals it has to
+ * block on. It does NOT carry the individual tool calls, so the timeline showed
+ * "OpenClaw said something" with no account of what it actually did, and the
+ * only tools that ever appeared were the ones that happened to need approval —
+ * a biased sample, not a log.
+ *
+ * OpenClaw writes a full transcript per session (measured 2026-08-23 against
+ * OpenClaw 2026.7.1-2). This reads it, exactly the way `kiro-transcript-timeline`
+ * reads Kiro's — an agent that pushes nothing still has a producer.
+ *
+ * **Scope is deliberately the complement of the Gateway stream, not a
+ * duplicate of it.** Only `tool_exec` rows are emitted here. Prompts, responses
+ * and approval rows already arrive live over the Gateway and re-deriving them
+ * would double every turn in the strip.
+ *
+ * The record shapes below were copied off a real store, never invented — this
+ * repo has a specific history of parsers written against imagined fixtures that
+ * passed their tests and matched nothing real, so the test file pins the
+ * measured shape verbatim:
+ *
+ *   {"type":"session","version":3,"id":"fef73899-…","timestamp":"2026-08-22T23:52:16.443Z",
+ *    "cwd":"/Users/x/.openclaw/workspace"}
+ *   {"type":"message","id":"577c04b8","parentId":"40296bc1",
+ *    "timestamp":"2026-08-22T23:52:23.315Z",
+ *    "message":{"role":"assistant","content":[
+ *      {"type":"thinking","thinking":"…"},
+ *      {"type":"toolCall","id":"38e16c61-…","name":"exec",
+ *       "arguments":{"command":"ls ~/github/OpenClaw && …"}}],
+ *     "provider":"openrouter","model":"stealth/ox-alpha","usage":{…}}}
+ *   {"type":"message","id":"53079fbe","timestamp":"2026-08-22T23:52:23.376Z",
+ *    "message":{"role":"toolResult","toolCallId":"38e16c61-…","toolName":"exec",
+ *     "content":[{"type":"text","text":"CAPTURE_GUIDE.md\n…"}],
+ *     "details":{"status":"completed","exitCode":0,"durationMs":13},"isError":false}}
+ *
+ * Three properties of that shape drive the code:
+ *  - A line carries an ISO `timestamp` AND `message.timestamp` in epoch-ms.
+ *    They agree; the ISO one is used, with the epoch one as the fallback,
+ *    because a row with no time cannot be ordered against the live stream.
+ *  - A tool call and its result are SEPARATE lines linked by `toolCallId`. The
+ *    call names what was attempted and only the result knows whether it worked,
+ *    so a row is emitted once, at the call, and completed from the result.
+ *  - `isError` and `details.exitCode` disagree in the interesting direction: a
+ *    command can exit 0 while the tool reports an error (and vice versa), so
+ *    both are consulted rather than picking one.
+ */
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { debug } from './logger.js';
+/** Cap on transcript bytes read, matching the Claude/Kiro readers' posture. */
+const MAX_TRANSCRIPT_BYTES = 4 * 1024 * 1024;
+/** Agent directories scanned under `~/.openclaw/agents`. */
+const MAX_AGENT_DIRS = 32;
+/** Row text budgets — these land on 144×144 keys and 120-byte firmware buffers. */
+const RAW_MAX = 160;
+const DETAIL_MAX = 400;
+export function openClawStateDir(opts = {}) {
+    return opts.stateDir ?? join(homedir(), '.openclaw');
+}
+/**
+ * Sessions across every agent, newest-first.
+ *
+ * Reads each agent's `sessions.json`, whose keys ARE the session keys — the one
+ * fact that says whether a given piece of OpenClaw activity is the chat the
+ * user is looking at (`agent:main:main`), a scheduled job
+ * (`agent:main:cron:<id>`) or a model-eval run (`agent:main:eval-…__r2`). All
+ * three arrive at AgentDeck as the single literal "OpenClaw", which is why an
+ * approval raised by an eval harness looked like it came from a conversation
+ * the user could not find.
+ */
+export function listOpenClawSessions(opts = {}) {
+    const agentsRoot = join(openClawStateDir(opts), 'agents');
+    let agents;
+    try {
+        agents = readdirSync(agentsRoot, { withFileTypes: true, encoding: 'utf-8' })
+            .filter((e) => e.isDirectory() && !e.isSymbolicLink())
+            .slice(0, MAX_AGENT_DIRS)
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const agent of agents) {
+        const indexPath = join(agentsRoot, agent, 'sessions', 'sessions.json');
+        let parsed;
+        try {
+            const st = statSync(indexPath);
+            if (!st.isFile() || st.size > MAX_TRANSCRIPT_BYTES)
+                continue;
+            parsed = JSON.parse(readFileSync(indexPath, 'utf-8'));
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            continue;
+        for (const [sessionKey, value] of Object.entries(parsed)) {
+            if (!value || typeof value !== 'object')
+                continue;
+            const rec = value;
+            if (typeof rec.sessionId !== 'string' || !rec.sessionId)
+                continue;
+            out.push({
+                sessionKey,
+                sessionId: rec.sessionId,
+                agent,
+                updatedAt: typeof rec.updatedAt === 'number' ? rec.updatedAt : 0,
+            });
+        }
+    }
+    return out.sort((a, b) => b.updatedAt - a.updatedAt);
+}
+function clip(s, max) {
+    const flat = s.replace(/\s+/g, ' ').trim();
+    return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
+/**
+ * Join detail parts into LINES, flattening each one but keeping the breaks.
+ *
+ * `detail` is ordered most-decisive-first precisely so a narrow surface can
+ * take its head line, and every consumer does exactly that (`split('\n')[0]`).
+ * Running the whole block through `clip` collapses those breaks and there is no
+ * head line left to take — the ordering becomes decorative and the surface
+ * shows the first 22 characters of a run-on string instead.
+ */
+function clipLines(parts, max) {
+    const lines = [];
+    let budget = max;
+    for (const part of parts) {
+        if (!part)
+            continue;
+        for (const raw of part.split('\n')) {
+            if (budget <= 1)
+                return lines.join('\n');
+            const line = clip(raw, budget);
+            if (!line)
+                continue;
+            lines.push(line);
+            budget -= line.length + 1;
+        }
+    }
+    return lines.join('\n');
+}
+/** Epoch-ms for a store line. */
+function lineTs(line) {
+    if (typeof line.timestamp === 'string') {
+        const parsed = Date.parse(line.timestamp);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    const inner = line.message?.timestamp;
+    if (typeof inner === 'number' && Number.isFinite(inner))
+        return inner;
+    return null;
+}
+/**
+ * The one line that says what a tool call is going to do.
+ *
+ * `exec` is the overwhelming majority and its `command` is the whole story.
+ * Anything else falls back to the first string-valued argument, then to the
+ * argument names — a tool this build has never seen must degrade to something
+ * true ("browser · url, selector") rather than render as nothing.
+ */
+export function summarizeToolArguments(args) {
+    if (typeof args === 'string')
+        return args;
+    if (!args || typeof args !== 'object' || Array.isArray(args))
+        return '';
+    const rec = args;
+    for (const key of ['command', 'cmd', 'script', 'query', 'path', 'file', 'url', 'prompt']) {
+        const v = rec[key];
+        if (typeof v === 'string' && v.trim())
+            return v.trim();
+    }
+    for (const v of Object.values(rec)) {
+        if (typeof v === 'string' && v.trim())
+            return v.trim();
+    }
+    const names = Object.keys(rec);
+    return names.length > 0 ? names.join(', ') : '';
+}
+/**
+ * `tool_exec` rows for one session's transcript, oldest-first.
+ *
+ * Emitted at the CALL, then completed in place from the matching result: the
+ * call is when the work started and is what orders correctly against the live
+ * Gateway rows, while only the result knows the outcome. Building the row at
+ * the result instead would stamp every tool with the time it finished and lose
+ * any call still running when the read happened.
+ */
+export function openClawTimelineForSession(sessionId, opts = {}) {
+    const path = join(openClawStateDir(opts), 'agents');
+    let transcript = null;
+    let agents = [];
+    try {
+        agents = readdirSync(path, { withFileTypes: true, encoding: 'utf-8' })
+            .filter((e) => e.isDirectory() && !e.isSymbolicLink())
+            .slice(0, MAX_AGENT_DIRS)
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+    for (const agent of agents) {
+        const candidate = join(path, agent, 'sessions', `${sessionId}.jsonl`);
+        try {
+            const st = statSync(candidate);
+            if (st.isFile() && st.size <= MAX_TRANSCRIPT_BYTES) {
+                transcript = candidate;
+                break;
+            }
+        }
+        catch {
+            // not this agent's session
+        }
+    }
+    if (!transcript)
+        return [];
+    let text;
+    try {
+        text = readFileSync(transcript, 'utf-8');
+    }
+    catch (err) {
+        debug('daemon', `openclaw transcript read failed for ${sessionId}: ${String(err)}`);
+        return [];
+    }
+    const rows = [];
+    const pending = new Map();
+    let model;
+    let provider;
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (rec.type !== 'message')
+            continue;
+        const msg = rec.message;
+        if (!msg || typeof msg !== 'object')
+            continue;
+        const ts = lineTs(rec);
+        if (ts === null)
+            continue;
+        if (msg.role === 'assistant') {
+            // Carried onto the rows this turn produces: which weights actually ran is
+            // the fact an eval session exists to vary, and the Gateway stream reports
+            // one model for the whole hub.
+            if (typeof msg.model === 'string' && msg.model)
+                model = msg.model;
+            if (typeof msg.provider === 'string' && msg.provider)
+                provider = msg.provider;
+            const content = Array.isArray(msg.content) ? msg.content : [];
+            for (const part of content) {
+                if (!part || typeof part !== 'object')
+                    continue;
+                const p = part;
+                if (p.type !== 'toolCall')
+                    continue;
+                const toolName = typeof p.name === 'string' && p.name ? p.name : 'tool';
+                const summary = summarizeToolArguments(p.arguments);
+                const detailParts = [
+                    model ? `model: ${provider ? `${provider}/${model}` : model}` : '',
+                ].filter(Boolean);
+                rows.push({
+                    ts,
+                    type: 'tool_exec',
+                    raw: clip(summary ? `${toolName} · ${summary}` : toolName, RAW_MAX),
+                    ...(detailParts.length > 0 ? { detail: clipLines(detailParts, DETAIL_MAX) } : {}),
+                    agentType: 'openclaw',
+                });
+                if (typeof p.id === 'string' && p.id) {
+                    pending.set(p.id, { index: rows.length - 1, toolName });
+                }
+            }
+            continue;
+        }
+        if (msg.role === 'toolResult') {
+            const callId = typeof msg.toolCallId === 'string' ? msg.toolCallId : '';
+            const target = callId ? pending.get(callId) : undefined;
+            if (!target)
+                continue;
+            pending.delete(callId);
+            const details = (msg.details ?? {});
+            const exitCode = typeof details.exitCode === 'number' ? details.exitCode : undefined;
+            const durationMs = typeof details.durationMs === 'number' ? details.durationMs : undefined;
+            // `isError` and a non-zero exit are independent signals — a tool can fail
+            // to run at all (isError, no exit code) and a command can fail while the
+            // tool call itself succeeded. Either one means this did not go well.
+            const failed = msg.isError === true || (exitCode !== undefined && exitCode !== 0);
+            const first = Array.isArray(msg.content)
+                ? msg.content.find((c) => c && typeof c === 'object' && c.type === 'text')
+                : undefined;
+            const output = typeof first?.text === 'string' ? first.text : '';
+            const outcome = [
+                failed ? 'failed' : 'ok',
+                exitCode !== undefined ? `exit ${exitCode}` : '',
+                durationMs !== undefined ? `${durationMs}ms` : '',
+            ].filter(Boolean).join(' · ');
+            const existing = rows[target.index];
+            // Outcome, then the model, then the output. The first two are short and
+            // decisive; the output is unbounded, so putting it ahead of the model
+            // pushed "which weights ran" past the clip on any tool that printed more
+            // than a line — the one fact an eval session exists to vary.
+            rows[target.index] = {
+                ...existing,
+                detail: clipLines([outcome, existing.detail, output], DETAIL_MAX),
+                ...(failed ? { status: 'denied' } : {}),
+            };
+        }
+    }
+    const since = opts.since;
+    const filtered = typeof since === 'number' ? rows.filter((r) => r.ts > since) : rows;
+    const limit = opts.limit;
+    return typeof limit === 'number' && limit >= 0 ? filtered.slice(-limit) : filtered;
+}
+//# sourceMappingURL=openclaw-transcript-timeline.js.map

package/dist/openclaw-transcript-timeline.js.map

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

package/dist/pairing-knocks.d.ts

@@ -0,0 +1,80 @@
+/**
+ * A knock is worth showing for this long after its last attempt. Long enough
+ * that the operator can walk to the machine; short enough that a device carried
+ * out of the building stops being offered.
+ */
+export declare const KNOCK_TTL_MS: number;
+/** Cap on simultaneously-tracked peers. */
+export declare const MAX_KNOCKS = 12;
+export interface PairingKnock {
+    /**
+     * What an approval will be recorded against. `device:<id>` when the client
+     * identified itself, `ip:<addr>` otherwise — never the bare string, so the
+     * two can never collide or be confused downstream.
+     */
+    key: string;
+    ip: string;
+    deviceId: string | null;
+    attempts: number;
+    firstSeen: number;
+    lastSeen: number;
+    /**
+     * True when the peer presented a token we do not accept, rather than no token
+     * at all. Reads very differently to an operator: usually a provisioned device
+     * whose credential went stale, not a new device.
+     */
+    staleToken: boolean;
+    /** Display only — `key` already encodes which kind this is. */
+    deviceScoped: boolean;
+}
+export interface PairingApproval {
+    key: string;
+    /**
+     * Where it last connected from. Display only — an approval keyed on a device
+     * id must not start depending on the address, or it would silently reacquire
+     * the NAT and DHCP problems it exists to escape.
+     */
+    lastIP: string;
+    approvedAt: number;
+    deviceId: string | null;
+}
+/**
+ * The one place a key is spelled, so the gate, the store and the UI cannot
+ * disagree about what "this peer" means.
+ */
+export declare function peerKey(ip: string, deviceId: unknown): string;
+/**
+ * Called from the refusal path. Cheap on purpose — it runs for every rejected
+ * handshake, and a looping device produces one every few seconds.
+ */
+export declare function recordKnock(ip: string, deviceId: unknown, staleToken: boolean, now?: number): void;
+/** Live knocks, newest first. Expiry is applied here — see the header. */
+export declare function pairingKnocks(now?: number): PairingKnock[];
+/**
+ * Drop a knock without approving it. Not a block: the peer may knock again,
+ * which is deliberate — a permanent denylist keyed on an address a stranger can
+ * change is security theatre, and it would silently strand a real device that
+ * later inherits that address.
+ */
+export declare function dismissKnock(key: string): boolean;
+/**
+ * Approving is what a pairing code would have done, minus the typing: from here
+ * on this peer authenticates by its key. Persisted immediately.
+ */
+export declare function approvePeer(key: string, now?: number): boolean;
+export declare function revokePeer(key: string): boolean;
+/**
+ * The question the WebSocket gate asks.
+ *
+ * A device id wins when the client sent one; the address is consulted only as
+ * the legacy path, so a client that adopts the header stops depending on its
+ * address the moment it does. Both are checked rather than one, because a
+ * device approved by address before it learned to send an id must not be locked
+ * out by the upgrade that taught it.
+ */
+export declare function isApprovedPeer(ip: string, deviceId: unknown): boolean;
+export declare function pairingApprovals(): PairingApproval[];
+/** Read the device id a client offered on the handshake, if any. */
+export declare function deviceIdFromHeaders(headers: Record<string, string | string[] | undefined> | undefined, headerName: string): string | null;
+export declare function resetPairingKnocksForTests(): void;
+//# sourceMappingURL=pairing-knocks.d.ts.map

package/dist/pairing-knocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing-knocks.d.ts","sourceRoot":"","sources":["../src/pairing-knocks.ts"],"names":[],"mappings":"AAgEA;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAc,CAAC;AAExC,2CAA2C;AAC3C,eAAO,MAAM,UAAU,KAAK,CAAC;AAE7B,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,+DAA+D;IAC/D,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CAI7D;AA8ID;;;GAGG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,OAAO,EACnB,GAAG,SAAa,GACf,IAAI,CAwBN;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,GAAG,SAAa,GAAG,YAAY,EAAE,CAK9D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,OAAO,CAQlE;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAK/C;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAMrE;AAED,wBAAgB,gBAAgB,IAAI,eAAe,EAAE,CAEpD;AAED,oEAAoE;AACpE,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,SAAS,EAClE,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAGf;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAGjD"}