@nordbyte/nordrelay 0.5.2 → 0.7.0

package/dist/peer-server.js

@@ -0,0 +1,220 @@
+import { createServer as createHttpServer } from "node:http";
+import { createServer as createHttpsServer } from "node:https";
+import { URL } from "node:url";
+import { friendlyErrorText } from "./error-messages.js";
+import { createPairingSignaturePayload, createSharedSecret, ensurePeerTlsFiles, fingerprintForPublicKey, loadOrCreatePeerIdentity, verifyPeerPayload, } from "./peer-identity.js";
+import { header, PeerNonceCache, verifyPeerRequest } from "./peer-auth.js";
+import { peerRuntimeContextKey } from "./peer-context.js";
+import { PeerStore } from "./peer-store.js";
+import { PeerRuntimeService, peerError } from "./peer-runtime-service.js";
+import { PEER_PROTOCOL_VERSION, } from "./peer-types.js";
+import { RelayRuntime } from "./relay-runtime.js";
+export async function startPeerServer(options) {
+    const { config, runtime } = options;
+    if (!config.peerEnabled) {
+        return null;
+    }
+    const home = options.home ?? process.env.NORDRELAY_HOME;
+    const identity = loadOrCreatePeerIdentity(home, config.peerName);
+    const store = new PeerStore(home);
+    const nonces = new PeerNonceCache();
+    const contextRuntimes = new Map();
+    const service = new PeerRuntimeService(config, runtime, {
+        runtimeForContext: (peer, sourceContextKey) => {
+            const contextKey = peerRuntimeContextKey(peer, sourceContextKey);
+            let scoped = contextRuntimes.get(contextKey);
+            if (!scoped) {
+                scoped = new RelayRuntime(config, {
+                    contextKey,
+                    registryFileName: "peer-contexts.json",
+                    registrySqliteKey: "peer-contexts",
+                });
+                contextRuntimes.set(contextKey, scoped);
+            }
+            return scoped;
+        },
+    });
+    const useTls = config.peerTlsEnabled;
+    const tls = useTls ? ensurePeerTlsFiles(home, identity.public) : null;
+    if (!useTls && config.peerRequireTls && !isLoopbackHost(config.peerHost)) {
+        throw new Error("Peer server refuses plaintext on non-loopback hosts. Set NORDRELAY_PEER_TLS_ENABLED=true or bind to 127.0.0.1.");
+    }
+    const server = useTls
+        ? createHttpsServer({ cert: tls.cert, key: tls.key }, handleRequest)
+        : createHttpServer(handleRequest);
+    await new Promise((resolve) => server.listen(config.peerPort, config.peerHost, resolve));
+    const scheme = useTls ? "https" : "http";
+    const host = config.peerHost === "0.0.0.0" || config.peerHost === "::" ? "127.0.0.1" : config.peerHost;
+    const displayHost = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+    const address = server.address();
+    const actualPort = typeof address === "object" && address ? address.port : config.peerPort;
+    const url = config.peerPublicUrl || `${scheme}://${displayHost}:${actualPort}`;
+    console.log(`Peer server: ${url} (${useTls ? `TLS ${tls.fingerprint}` : "plaintext loopback"})`);
+    return {
+        url,
+        tlsFingerprint: tls?.fingerprint,
+        close: async () => {
+            await closeServer(server);
+            for (const scoped of contextRuntimes.values()) {
+                scoped.dispose();
+            }
+        },
+    };
+    async function handleRequest(req, res) {
+        try {
+            const url = new URL(req.url ?? "/", "http://localhost");
+            if (req.method === "GET" && url.pathname === "/peer/healthz") {
+                sendJson(res, 200, { ok: true, protocolVersion: PEER_PROTOCOL_VERSION });
+                return;
+            }
+            if (req.method === "GET" && url.pathname === "/peer/identity") {
+                sendJson(res, 200, {
+                    protocolVersion: PEER_PROTOCOL_VERSION,
+                    identity: identity.public,
+                    tlsFingerprint: tls?.fingerprint,
+                });
+                return;
+            }
+            if (req.method === "POST" && url.pathname === "/peer/pair") {
+                const bodyText = await readBody(req, 128 * 1024);
+                const body = parseJson(bodyText);
+                const response = handlePair(body);
+                sendJson(res, 201, response);
+                return;
+            }
+            if (req.method === "POST" && url.pathname === "/peer/rpc") {
+                const bodyText = await readBody(req, 64 * 1024 * 1024);
+                const peer = authenticate(req, "POST", "/peer/rpc", bodyText);
+                const body = parseJson(bodyText);
+                const data = await service.handle(peer, body);
+                const result = { ok: true, data };
+                sendJson(res, 200, result);
+                return;
+            }
+            if (req.method === "GET" && url.pathname === "/peer/events") {
+                const peer = authenticate(req, "GET", `${url.pathname}${url.search}`, "");
+                res.writeHead(200, {
+                    "content-type": "text/event-stream; charset=utf-8",
+                    "cache-control": "no-cache, no-transform",
+                    connection: "keep-alive",
+                });
+                const sourceContextKey = url.searchParams.get("contextKey") || undefined;
+                const unsubscribe = service.subscribe(peer, sourceContextKey, (event) => {
+                    if (res.destroyed || res.writableEnded)
+                        return;
+                    res.write(`event: ${event.type}\n`);
+                    res.write(`data: ${JSON.stringify(event)}\n\n`);
+                });
+                const heartbeat = setInterval(() => {
+                    if (!res.destroyed && !res.writableEnded)
+                        res.write(": heartbeat\n\n");
+                }, 25_000);
+                heartbeat.unref?.();
+                req.on("close", () => {
+                    clearInterval(heartbeat);
+                    unsubscribe();
+                });
+                return;
+            }
+            sendJson(res, 404, { error: "not found" });
+        }
+        catch (error) {
+            const status = isAuthError(error) ? 403 : 500;
+            sendJson(res, status, { error: friendlyErrorText(error) });
+        }
+    }
+    function handlePair(body) {
+        if (!body?.identity?.nodeId || !body.identity.publicKey || !body.code || !body.signature || !body.timestamp) {
+            throw new Error("Invalid peer pairing request.");
+        }
+        if (fingerprintForPublicKey(body.identity.publicKey) !== body.identity.fingerprint) {
+            throw new Error("Pairing identity fingerprint mismatch.");
+        }
+        if (body.identity.nodeId === identity.public.nodeId) {
+            throw new Error("Refusing to pair this NordRelay instance with itself.");
+        }
+        if (Math.abs(Date.now() - Date.parse(body.timestamp)) > 5 * 60 * 1000) {
+            throw new Error("Pairing request timestamp is outside the allowed clock skew.");
+        }
+        const signaturePayload = createPairingSignaturePayload(body.identity.nodeId, body.timestamp, body.code);
+        if (!verifyPeerPayload(body.identity.publicKey, signaturePayload, body.signature)) {
+            throw new Error("Invalid peer pairing signature.");
+        }
+        const invitation = store.consumeInvitation(body.code, body.identity.nodeId);
+        const secret = createSharedSecret();
+        const peer = store.upsertPeer({
+            name: body.name?.trim() || body.identity.name || invitation.name,
+            url: body.publicUrl,
+            nodeId: body.identity.nodeId,
+            publicKey: body.identity.publicKey,
+            fingerprint: body.identity.fingerprint,
+            secret,
+            enabled: true,
+            direction: body.publicUrl ? "bidirectional" : "inbound",
+            scopes: invitation.scopes,
+            allowedAgents: invitation.allowedAgents,
+            allowedWorkspaceRoots: invitation.allowedWorkspaceRoots,
+            workspaceAliases: invitation.workspaceAliases,
+        });
+        return {
+            protocolVersion: PEER_PROTOCOL_VERSION,
+            identity: identity.public,
+            peerId: peer.id,
+            secret,
+            scopes: peer.scopes,
+            allowedAgents: peer.allowedAgents,
+            allowedWorkspaceRoots: peer.allowedWorkspaceRoots,
+            workspaceAliases: peer.workspaceAliases,
+        };
+    }
+    function authenticate(req, method, pathname, body) {
+        const peerId = header(req, "x-nordrelay-peer-id");
+        const peer = peerId ? store.get(peerId) : null;
+        if (!peer) {
+            throw new Error("Unknown peer.");
+        }
+        if (!peer.enabled) {
+            throw new Error("Peer is disabled.");
+        }
+        verifyPeerRequest({ req, peer, method, pathname, body, nonces });
+        store.markSeen(peer.id);
+        return peer;
+    }
+}
+async function readBody(req, maxBytes) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > maxBytes) {
+            throw new Error("Peer request body is too large.");
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text || "{}");
+    }
+    catch {
+        throw new Error("Invalid JSON body.");
+    }
+}
+function sendJson(res, status, value) {
+    res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+    res.end(`${JSON.stringify(value)}\n`);
+}
+function isLoopbackHost(host) {
+    return host === "127.0.0.1" || host === "::1" || host === "localhost";
+}
+function isAuthError(error) {
+    const message = peerError(error).toLowerCase();
+    return /peer|signature|timestamp|replay|permission|denied|auth|disabled/.test(message);
+}
+function closeServer(server) {
+    return new Promise((resolve, reject) => {
+        server.close((error) => error ? reject(error) : resolve());
+    });
+}

package/dist/peer-store.js

@@ -0,0 +1,294 @@
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ALL_PERMISSIONS } from "./access-control.js";
+import { AGENT_IDS, isAgentId } from "./agent.js";
+import { readJsonFileWithBackup, writeJsonFileAtomic } from "./persistence.js";
+import { DEFAULT_PEER_SCOPES, publicInvitation, publicPeer, } from "./peer-types.js";
+const DEFAULT_HOME = path.join(os.homedir(), ".nordrelay");
+const INVITE_CODE_BYTES = 18;
+const MAX_INVITATION_TTL_MS = 24 * 60 * 60 * 1000;
+export class PeerStore {
+    filePath;
+    constructor(home = process.env.NORDRELAY_HOME || DEFAULT_HOME) {
+        this.filePath = path.join(home, "peers.json");
+    }
+    snapshot(identity, options) {
+        const payload = this.readPayload();
+        return {
+            identity,
+            enabled: options.enabled,
+            listenUrl: options.listenUrl,
+            requireTls: options.requireTls,
+            peers: payload.peers.map(publicPeer),
+            invitations: payload.invitations.map(publicInvitation),
+        };
+    }
+    list() {
+        return this.readPayload().peers;
+    }
+    listPublic() {
+        return this.list().map(publicPeer);
+    }
+    get(id) {
+        return this.readPayload().peers.find((peer) => peer.id === id || peer.nodeId === id) ?? null;
+    }
+    createInvitation(options = {}) {
+        const code = randomBytes(INVITE_CODE_BYTES).toString("base64url");
+        const now = new Date();
+        const requestedTtl = options.expiresInMs ?? 10 * 60 * 1000;
+        const ttl = Math.max(1_000, Math.min(requestedTtl, MAX_INVITATION_TTL_MS));
+        const expiresAt = new Date(now.getTime() + ttl);
+        const invitation = {
+            id: randomUUID().replace(/-/g, "").slice(0, 12),
+            name: options.name?.trim() || "NordRelay peer",
+            codeHash: hashSecret(code),
+            createdAt: now.toISOString(),
+            expiresAt: expiresAt.toISOString(),
+            scopes: normalizeScopes(options.scopes ?? DEFAULT_PEER_SCOPES),
+            allowedAgents: normalizeAgents(options.allowedAgents ?? [...AGENT_IDS]),
+            allowedWorkspaceRoots: normalizeWorkspaceRoots(options.allowedWorkspaceRoots ?? []),
+            workspaceAliases: normalizeWorkspaceAliases(options.workspaceAliases ?? {}),
+        };
+        this.mutatePayload((payload) => {
+            payload.invitations = payload.invitations.filter((item) => !item.usedAt && Date.parse(item.expiresAt) > Date.now());
+            payload.invitations.push(invitation);
+        });
+        return { invitation: publicInvitation(invitation), code };
+    }
+    consumeInvitation(code, usedByNodeId) {
+        const trimmed = code.trim();
+        if (!trimmed) {
+            throw new Error("Pairing code is required.");
+        }
+        let consumed = null;
+        this.mutatePayload((payload) => {
+            const invitation = payload.invitations.find((item) => !item.usedAt && verifySecret(trimmed, item.codeHash));
+            if (!invitation) {
+                throw new Error("Invalid or already used pairing code.");
+            }
+            if (Date.parse(invitation.expiresAt) <= Date.now()) {
+                throw new Error("Pairing code has expired.");
+            }
+            invitation.usedAt = new Date().toISOString();
+            invitation.usedByNodeId = usedByNodeId;
+            consumed = { ...invitation, scopes: [...invitation.scopes], allowedAgents: [...invitation.allowedAgents], allowedWorkspaceRoots: [...invitation.allowedWorkspaceRoots] };
+        });
+        if (!consumed) {
+            throw new Error("Pairing code could not be consumed.");
+        }
+        return consumed;
+    }
+    upsertPeer(input) {
+        const now = new Date().toISOString();
+        let next = null;
+        this.mutatePayload((payload) => {
+            const existing = payload.peers.find((peer) => peer.nodeId === input.nodeId || (input.id && peer.id === input.id));
+            if (existing) {
+                existing.name = input.name.trim() || existing.name;
+                existing.url = input.url ?? existing.url;
+                existing.publicKey = input.publicKey;
+                existing.fingerprint = input.fingerprint;
+                existing.tlsFingerprint = input.tlsFingerprint ?? existing.tlsFingerprint;
+                existing.secret = input.secret;
+                existing.enabled = input.enabled ?? existing.enabled;
+                existing.direction = mergeDirection(existing.direction, input.direction ?? existing.direction);
+                existing.scopes = normalizeScopes(input.scopes ?? existing.scopes);
+                existing.allowedAgents = normalizeAgents(input.allowedAgents ?? existing.allowedAgents);
+                existing.allowedWorkspaceRoots = normalizeWorkspaceRoots(input.allowedWorkspaceRoots ?? existing.allowedWorkspaceRoots);
+                existing.workspaceAliases = normalizeWorkspaceAliases(input.workspaceAliases ?? existing.workspaceAliases ?? {});
+                existing.updatedAt = now;
+                delete existing.lastError;
+                next = clonePeer(existing);
+                return;
+            }
+            const record = {
+                id: input.id ?? randomUUID().replace(/-/g, "").slice(0, 12),
+                name: input.name.trim() || "NordRelay peer",
+                url: input.url,
+                nodeId: input.nodeId,
+                publicKey: input.publicKey,
+                fingerprint: input.fingerprint,
+                tlsFingerprint: input.tlsFingerprint,
+                secret: input.secret,
+                enabled: input.enabled ?? true,
+                direction: input.direction ?? "outbound",
+                scopes: normalizeScopes(input.scopes ?? DEFAULT_PEER_SCOPES),
+                allowedAgents: normalizeAgents(input.allowedAgents ?? [...AGENT_IDS]),
+                allowedWorkspaceRoots: normalizeWorkspaceRoots(input.allowedWorkspaceRoots ?? []),
+                workspaceAliases: normalizeWorkspaceAliases(input.workspaceAliases ?? {}),
+                createdAt: now,
+                updatedAt: now,
+            };
+            payload.peers.push(record);
+            next = clonePeer(record);
+        });
+        if (!next) {
+            throw new Error("Peer could not be saved.");
+        }
+        return next;
+    }
+    updatePeer(id, patch) {
+        let next = null;
+        this.mutatePayload((payload) => {
+            const peer = payload.peers.find((candidate) => candidate.id === id || candidate.nodeId === id);
+            if (!peer) {
+                throw new Error("Peer not found.");
+            }
+            if (patch.name !== undefined)
+                peer.name = patch.name.trim() || peer.name;
+            if (patch.url !== undefined)
+                peer.url = patch.url.trim() || undefined;
+            if (patch.enabled !== undefined)
+                peer.enabled = patch.enabled;
+            if (patch.scopes !== undefined)
+                peer.scopes = normalizeScopes(patch.scopes);
+            if (patch.allowedAgents !== undefined)
+                peer.allowedAgents = normalizeAgents(patch.allowedAgents);
+            if (patch.allowedWorkspaceRoots !== undefined)
+                peer.allowedWorkspaceRoots = normalizeWorkspaceRoots(patch.allowedWorkspaceRoots);
+            if (patch.workspaceAliases !== undefined)
+                peer.workspaceAliases = normalizeWorkspaceAliases(patch.workspaceAliases);
+            peer.updatedAt = new Date().toISOString();
+            next = clonePeer(peer);
+        });
+        if (!next) {
+            throw new Error("Peer not found.");
+        }
+        return next;
+    }
+    markSeen(id, patch = {}) {
+        this.patchPeer(id, {
+            lastSeenAt: new Date().toISOString(),
+            lastCheckedAt: new Date().toISOString(),
+            lastLatencyMs: patch.latencyMs,
+            remoteVersion: patch.remoteVersion,
+            remoteStatus: patch.remoteStatus ?? "online",
+            lastError: undefined,
+        });
+    }
+    markError(id, error) {
+        this.patchPeer(id, { lastError: error, remoteStatus: "offline", lastCheckedAt: new Date().toISOString(), updatedAt: new Date().toISOString() });
+    }
+    revokePeer(id) {
+        let removed = false;
+        this.mutatePayload((payload) => {
+            const before = payload.peers.length;
+            payload.peers = payload.peers.filter((peer) => peer.id !== id && peer.nodeId !== id);
+            removed = payload.peers.length !== before;
+        });
+        return removed;
+    }
+    patchPeer(id, patch) {
+        this.mutatePayload((payload) => {
+            const peer = payload.peers.find((candidate) => candidate.id === id || candidate.nodeId === id);
+            if (!peer)
+                return;
+            Object.assign(peer, patch);
+        });
+    }
+    mutatePayload(mutator) {
+        const payload = this.readPayload();
+        const result = mutator(payload);
+        mkdirSync(path.dirname(this.filePath), { recursive: true });
+        writeJsonFileAtomic(this.filePath, payload);
+        return result;
+    }
+    readPayload() {
+        const payload = readJsonFileWithBackup(this.filePath).value;
+        if (!payload || payload.version !== 1 || !Array.isArray(payload.peers) || !Array.isArray(payload.invitations)) {
+            return { version: 1, peers: [], invitations: [] };
+        }
+        return {
+            version: 1,
+            peers: payload.peers.filter(isPeerRecord).map((peer) => ({
+                ...peer,
+                scopes: normalizeScopes(peer.scopes),
+                allowedAgents: normalizeAgents(peer.allowedAgents),
+                allowedWorkspaceRoots: normalizeWorkspaceRoots(peer.allowedWorkspaceRoots),
+                workspaceAliases: normalizeWorkspaceAliases(peer.workspaceAliases ?? {}),
+            })),
+            invitations: payload.invitations.filter(isInvitationRecord).map((invitation) => ({
+                ...invitation,
+                scopes: normalizeScopes(invitation.scopes),
+                allowedAgents: normalizeAgents(invitation.allowedAgents),
+                allowedWorkspaceRoots: normalizeWorkspaceRoots(invitation.allowedWorkspaceRoots),
+                workspaceAliases: normalizeWorkspaceAliases(invitation.workspaceAliases ?? {}),
+            })),
+        };
+    }
+}
+export function hashSecret(value) {
+    const salt = randomBytes(16).toString("hex");
+    const digest = createHash("sha256").update(`${salt}:${value}`).digest("hex");
+    return `${salt}:${digest}`;
+}
+export function verifySecret(value, stored) {
+    const [salt, digest] = stored.split(":");
+    if (!salt || !digest) {
+        return false;
+    }
+    const next = createHash("sha256").update(`${salt}:${value}`).digest();
+    const previous = Buffer.from(digest, "hex");
+    return previous.length === next.length && timingSafeEqual(previous, next);
+}
+function normalizeScopes(values) {
+    const allowed = new Set(ALL_PERMISSIONS);
+    return [...new Set(values.filter((value) => allowed.has(value)))];
+}
+function normalizeAgents(values) {
+    return [...new Set(values.filter(isAgentId))];
+}
+function normalizeWorkspaceRoots(values) {
+    return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
+function normalizeWorkspaceAliases(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    const aliases = {};
+    for (const [rawAlias, rawWorkspace] of Object.entries(value ?? {})) {
+        const alias = rawAlias.trim();
+        const workspace = String(rawWorkspace ?? "").trim();
+        if (!alias || !workspace || /[,\s]/.test(alias))
+            continue;
+        aliases[alias] = workspace;
+    }
+    return aliases;
+}
+function clonePeer(peer) {
+    return {
+        ...peer,
+        scopes: [...peer.scopes],
+        allowedAgents: [...peer.allowedAgents],
+        allowedWorkspaceRoots: [...peer.allowedWorkspaceRoots],
+        workspaceAliases: { ...peer.workspaceAliases },
+    };
+}
+function mergeDirection(left, right) {
+    if (left === right)
+        return left;
+    return "bidirectional";
+}
+function isPeerRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return typeof record.id === "string" &&
+        typeof record.name === "string" &&
+        typeof record.nodeId === "string" &&
+        typeof record.publicKey === "string" &&
+        typeof record.fingerprint === "string" &&
+        typeof record.secret === "string" &&
+        typeof record.enabled === "boolean";
+}
+function isInvitationRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return typeof record.id === "string" &&
+        typeof record.name === "string" &&
+        typeof record.codeHash === "string" &&
+        typeof record.expiresAt === "string";
+}

package/dist/peer-types.js

@@ -0,0 +1,52 @@
+export const PEER_PROTOCOL_VERSION = 1;
+export const DEFAULT_PEER_SCOPES = [
+    "inspect",
+    "sessions.read",
+    "sessions.write",
+    "prompt.send",
+    "prompt.abort",
+    "queue.read",
+    "queue.write",
+    "files.read",
+    "files.write",
+    "diagnostics.read",
+    "logs.read",
+];
+export function publicPeer(record) {
+    return {
+        id: record.id,
+        name: record.name,
+        url: record.url,
+        nodeId: record.nodeId,
+        fingerprint: record.fingerprint,
+        tlsFingerprint: record.tlsFingerprint,
+        enabled: record.enabled,
+        direction: record.direction,
+        scopes: [...record.scopes],
+        allowedAgents: [...record.allowedAgents],
+        allowedWorkspaceRoots: [...record.allowedWorkspaceRoots],
+        workspaceAliases: { ...record.workspaceAliases },
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        lastSeenAt: record.lastSeenAt,
+        lastCheckedAt: record.lastCheckedAt,
+        lastLatencyMs: record.lastLatencyMs,
+        remoteVersion: record.remoteVersion,
+        remoteStatus: record.remoteStatus,
+        lastError: record.lastError,
+    };
+}
+export function publicInvitation(record) {
+    return {
+        id: record.id,
+        name: record.name,
+        expiresAt: record.expiresAt,
+        createdAt: record.createdAt,
+        scopes: [...record.scopes],
+        allowedAgents: [...record.allowedAgents],
+        allowedWorkspaceRoots: [...record.allowedWorkspaceRoots],
+        workspaceAliases: { ...record.workspaceAliases },
+        usedAt: record.usedAt,
+        usedByNodeId: record.usedByNodeId,
+    };
+}

package/dist/relay-external-activity-monitor.js

@@ -2,6 +2,10 @@ import {} from "./agent.js";
 import { getExternalSnapshotForSession } from "./agent-activity.js";
 import { friendlyErrorText } from "./error-messages.js";
 import {} from "./web-state.js";
+const CLI_ACTIVITY_ACTOR = {
+    channel: "cli",
+    label: "CLI",
+};
 export class RelayExternalActivityMonitor {
     options;
     mirror = null;
@@ -16,7 +20,9 @@ export class RelayExternalActivityMonitor {
         if (!this.mirror) {
             return null;
         }
-        const startedAt = this.mirror.startedAt ?? new Date().toISOString();
+        const startedAt = this.mirror.startedAt instanceof Date
+            ? this.mirror.startedAt.toISOString()
+            : this.mirror.startedAt ?? new Date().toISOString();
         const startedMs = new Date(startedAt).getTime();
         return {
             id: this.mirror.turnId ?? "cli",
@@ -75,7 +81,7 @@ export class RelayExternalActivityMonitor {
                 startedAt: snapshot.activity.startedAt?.toISOString() ?? null,
             };
             if (snapshot.activity.active) {
-                this.startExternalTurn(snapshot);
+                this.startExternalTurn(snapshot, info);
             }
             return;
         }
@@ -85,9 +91,9 @@ export class RelayExternalActivityMonitor {
                 mirror.turnId = snapshot.activity.turnId;
                 mirror.startedAt = snapshot.activity.startedAt?.toISOString() ?? null;
                 mirror.latestAgentLine = undefined;
-                this.startExternalTurn(snapshot);
+                this.startExternalTurn(snapshot, info);
             }
-            this.broadcastExternalEvents(snapshot, snapshot.events.filter((event) => event.lineNumber > mirror.lastLine));
+            this.broadcastExternalEvents(snapshot, snapshot.events.filter((event) => event.lineNumber > mirror.lastLine), info);
             mirror.lastLine = Math.max(mirror.lastLine, snapshot.lineCount);
             mirror.latestStatus = externalStatusLine(snapshot, this.options.queueLength());
             this.options.broadcastStatus(mirror.latestStatus, "info");
@@ -122,6 +128,7 @@ export class RelayExternalActivityMonitor {
                 threadId: snapshot.threadId,
                 workspace: info.workspace,
                 agentId: info.agentId,
+                actor: CLI_ACTIVITY_ACTOR,
                 prompt: snapshot.latestUserMessage ?? undefined,
                 detail: `${snapshot.agentLabel} CLI task ${terminalEvent.status ?? "finished"}.`,
                 durationMs: durationFromDates(externalStartedAt, terminalEvent.timestamp),
@@ -136,7 +143,7 @@ export class RelayExternalActivityMonitor {
         }
         mirror.lastLine = Math.max(mirror.lastLine, snapshot.lineCount);
     }
-    startExternalTurn(snapshot) {
+    startExternalTurn(snapshot, info) {
         const prompt = snapshot.latestUserMessage ?? `${snapshot.agentLabel} CLI task`;
         this.options.chatStore.append({
             threadId: snapshot.threadId,
@@ -158,11 +165,14 @@ export class RelayExternalActivityMonitor {
             status: "running",
             type: "cli_turn_started",
             threadId: snapshot.threadId,
+            workspace: info.workspace,
+            agentId: info.agentId,
+            actor: CLI_ACTIVITY_ACTOR,
             prompt,
             detail: `${snapshot.sourceLabel}: ${snapshot.sourcePath}`,
         });
     }
-    broadcastExternalEvents(snapshot, events) {
+    broadcastExternalEvents(snapshot, events, info) {
         for (const event of events) {
             if (event.kind === "tool" && event.status === "started") {
                 this.options.broadcast({
@@ -176,6 +186,9 @@ export class RelayExternalActivityMonitor {
                     status: "running",
                     type: "cli_tool_started",
                     threadId: snapshot.threadId,
+                    workspace: info.workspace,
+                    agentId: info.agentId,
+                    actor: CLI_ACTIVITY_ACTOR,
                     detail: event.toolName ?? "tool",
                 });
             }
@@ -186,6 +199,34 @@ export class RelayExternalActivityMonitor {
                     toolCallId: `cli-${event.lineNumber}`,
                     isError: false,
                 });
+                this.options.appendActivity({
+                    source: "cli",
+                    status: "completed",
+                    type: "cli_tool_completed",
+                    threadId: snapshot.threadId,
+                    workspace: info.workspace,
+                    agentId: info.agentId,
+                    actor: CLI_ACTIVITY_ACTOR,
+                    detail: event.toolName ?? "tool",
+                });
+            }
+            if (event.kind === "tool" && event.status === "failed") {
+                this.options.broadcast({
+                    type: "tool_end",
+                    id: snapshot.activity.turnId ?? "cli",
+                    toolCallId: `cli-${event.lineNumber}`,
+                    isError: true,
+                });
+                this.options.appendActivity({
+                    source: "cli",
+                    status: "failed",
+                    type: "cli_tool_failed",
+                    threadId: snapshot.threadId,
+                    workspace: info.workspace,
+                    agentId: info.agentId,
+                    actor: CLI_ACTIVITY_ACTOR,
+                    detail: event.toolName ?? "tool",
+                });
             }
         }
     }