@r0hitsharma/mcp-relay 0.12.0-rohit-fork-ci.1

package/README.md

@@ -0,0 +1,55 @@
+# @r0hitsharma/mcp-relay
+
+Host-agnostic core for the WebMCP relay protocol.
+
+## What it is
+
+A pure TypeScript library that implements the WebMCP relay wire protocol
+types, HS256 JWT helpers (mint + verify), and a `RelaySession` sans-I/O
+state machine. It contains zero transport code: no sockets, no timers,
+no fetch, no Cloudflare or Node APIs.
+
+Use it as the shared core inside any relay host adapter:
+- Cloudflare Durable Objects (see `packages/uikit-preview/demo-relay/`)
+- Node.js / Bun servers
+- Future WASM targets
+
+## Core vs Host boundary
+
+The host (e.g. a Durable Object) owns:
+
+- Holding the live WebSocket and sending/receiving frames.
+- **The async invoke round-trip**: generating a `call_id`, sending the
+  `InvokeMessage` over the WS, storing a `{resolve, reject, timer}` entry
+  keyed by `call_id`, resolving it when the browser's `result` frame arrives,
+  and timing out after `INVOKE_TIMEOUT_MS`.
+- Scheduling the liveness TTL sweep (e.g. via a DO alarm or setInterval).
+
+The core (`RelaySession`) owns:
+
+- Protocol framing (building `invoke`, `tool_activity`, `harness_status` frames).
+- State tracking (tools catalogue, `harnessAttached`, `lastSeenMs`).
+- `onHello` -> accepted/rejected logic.
+- `onInitialize` -> flips `harnessAttached`, returns `harness_status` frame.
+- `sweep` -> reverts `harnessAttached` on TTL expiry, returns frame or null.
+- `toSnapshot` / `RelaySession.fromSnapshot` -> persist and rehydrate the
+  durable state, so a host survives eviction/hibernation.
+
+## Exports
+
+```ts
+// Wire types (MVP subset: connect + tool-activity)
+export type { ToolDefinition, HelloMessage, InvokeMessage, ... }
+
+// Token helpers (JWT mint/verify via Web Crypto, plus pairing codes)
+export { mintConnectionToken, sessionIdFromToken, decodeConnectionToken, parseBearer, newPairingToken, ... }
+
+// State machine
+export { RelaySession, HARNESS_LIVENESS_TTL_MS, INVOKE_TIMEOUT_MS }
+```
+
+## Build
+
+```bash
+npm run build --workspace packages/mcp-relay
+```

package/dist/src/__tests__/session.test.d.ts

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

package/dist/src/__tests__/session.test.js

@@ -0,0 +1,199 @@
+import { describe, expect, it } from 'vitest';
+import { HARNESS_LIVENESS_TTL_MS, RelaySession } from '../session.js';
+const SESSION_ID = 'test-session-001';
+function makeSession() {
+    return new RelaySession(SESSION_ID);
+}
+describe('RelaySession', () => {
+    describe('onHello', () => {
+        it('returns hello/accepted when tokenValid=true', () => {
+            const s = makeSession();
+            const reply = s.onHello({
+                type: 'hello',
+                tab_id: 'tab-1',
+                origin: 'http://localhost',
+                url: 'http://localhost',
+            }, true);
+            expect(reply.type).toBe('hello/accepted');
+            if (reply.type === 'hello/accepted') {
+                expect(reply.session_id).toBe(SESSION_ID);
+            }
+        });
+        it('returns hello/rejected when tokenValid=false', () => {
+            const s = makeSession();
+            const reply = s.onHello({
+                type: 'hello',
+                tab_id: 'tab-1',
+                origin: 'http://localhost',
+                url: 'http://localhost',
+            }, false);
+            expect(reply.type).toBe('hello/rejected');
+        });
+        it('transitions state to connected on acceptance', () => {
+            const s = makeSession();
+            s.onHello({
+                type: 'hello',
+                tab_id: 'tab-1',
+                origin: 'http://localhost',
+                url: 'http://localhost',
+            }, true);
+            expect(s.state).toBe('connected');
+        });
+    });
+    describe('onInitialize', () => {
+        it('flips harnessAttached to true', () => {
+            const s = makeSession();
+            expect(s.harnessAttached).toBe(false);
+            s.onInitialize(Date.now());
+            expect(s.harnessAttached).toBe(true);
+        });
+        it('returns a harness_status frame with attached=true', () => {
+            const s = makeSession();
+            const now = Date.now();
+            const { harnessStatus } = s.onInitialize(now);
+            expect(harnessStatus.type).toBe('harness_status');
+            expect(harnessStatus.attached).toBe(true);
+            expect(harnessStatus.last_activity_ms).toBe(now);
+        });
+    });
+    describe('sweep', () => {
+        it('returns null when harness is not attached', () => {
+            const s = makeSession();
+            const frame = s.sweep(Date.now());
+            expect(frame).toBeNull();
+        });
+        it('returns null when TTL has not elapsed', () => {
+            const s = makeSession();
+            const now = Date.now();
+            s.onInitialize(now);
+            const frame = s.sweep(now + 1000, HARNESS_LIVENESS_TTL_MS);
+            expect(frame).toBeNull();
+        });
+        it('returns harness_status{attached:false} when TTL has elapsed', () => {
+            const s = makeSession();
+            const now = Date.now();
+            s.onInitialize(now);
+            // Simulate TTL + 1 ms elapsed.
+            const frame = s.sweep(now + HARNESS_LIVENESS_TTL_MS + 1);
+            expect(frame).not.toBeNull();
+            expect(frame?.type).toBe('harness_status');
+            expect(frame?.attached).toBe(false);
+        });
+        it('reverts harnessAttached to false after sweep', () => {
+            const s = makeSession();
+            const now = Date.now();
+            s.onInitialize(now);
+            s.sweep(now + HARNESS_LIVENESS_TTL_MS + 1);
+            expect(s.harnessAttached).toBe(false);
+        });
+        it('does not revert a second time once already false', () => {
+            const s = makeSession();
+            const now = Date.now();
+            s.onInitialize(now);
+            s.sweep(now + HARNESS_LIVENESS_TTL_MS + 1);
+            const secondSweep = s.sweep(now + HARNESS_LIVENESS_TTL_MS + 2);
+            expect(secondSweep).toBeNull();
+        });
+    });
+    describe('setTools / listToolsResult', () => {
+        it('stores and lists tools', () => {
+            const s = makeSession();
+            s.setTools([
+                {
+                    name: 'click_button',
+                    description: 'Clicks a button',
+                    input_schema: {
+                        type: 'object',
+                        properties: { selector: { type: 'string' } },
+                        required: ['selector'],
+                    },
+                },
+            ]);
+            const result = s.listToolsResult(42);
+            expect(result.result.tools).toHaveLength(1);
+            expect(result.result.tools[0]?.name).toBe('click_button');
+        });
+    });
+    describe('buildInvoke', () => {
+        it('returns an invoke frame with the correct shape', () => {
+            const s = makeSession();
+            const frame = s.buildInvoke('call-001', 'click_button', {
+                selector: '#btn',
+            });
+            expect(frame.type).toBe('invoke');
+            expect(frame.call_id).toBe('call-001');
+            expect(frame.tool_name).toBe('click_button');
+            expect(frame.args).toEqual({ selector: '#btn' });
+        });
+    });
+    describe('buildToolActivity', () => {
+        it('returns a tool_activity frame with status=started', () => {
+            const s = makeSession();
+            const frame = s.buildToolActivity('act-001', 'click_button', 'started', {
+                args: { selector: '#btn' },
+            });
+            expect(frame.type).toBe('tool_activity');
+            expect(frame.status).toBe('started');
+            expect(frame.tool_name).toBe('click_button');
+            expect(frame.args).toEqual({ selector: '#btn' });
+        });
+        it('returns a tool_activity frame with status=ok and result_preview', () => {
+            const s = makeSession();
+            const frame = s.buildToolActivity('act-001', 'click_button', 'ok', {
+                resultPreview: 'clicked',
+            });
+            expect(frame.status).toBe('ok');
+            expect(frame.result_preview).toBe('clicked');
+        });
+        it('defaults kind to "ui" but honours an explicit kind', () => {
+            const s = makeSession();
+            expect(s.buildToolActivity('a', 't', 'started').kind).toBe('ui');
+            expect(s.buildToolActivity('a', 't', 'started', { kind: 'mutation' }).kind).toBe('mutation');
+        });
+    });
+    describe('toSnapshot / fromSnapshot (DO hibernation durability)', () => {
+        it('round-trips the full durable state losslessly', () => {
+            const s = makeSession();
+            s.setTools([
+                {
+                    name: 'click_button',
+                    description: 'Clicks a button',
+                    input_schema: { type: 'object', properties: {}, required: [] },
+                },
+            ]);
+            s.onHello({
+                type: 'hello',
+                tab_id: 't',
+                origin: 'http://localhost',
+                url: 'http://localhost',
+            }, true);
+            s.onInitialize(1700001234567);
+            const restored = RelaySession.fromSnapshot(s.toSnapshot());
+            expect(restored.toSnapshot()).toEqual(s.toSnapshot());
+            expect(restored.state).toBe('connected');
+            expect(restored.harnessAttached).toBe(true);
+            expect(restored.lastSeenMs).toBe(1700001234567);
+            expect(restored.tools).toHaveLength(1);
+        });
+        it('defaults unknown/legacy snapshot fields instead of trusting them', () => {
+            // Simulates a snapshot written by an older code version (bad state, no
+            // attached/lastSeen, non-array tools). fromSnapshot must coerce rather
+            // than emit undefined values over the wire afterwards.
+            const restored = RelaySession.fromSnapshot({
+                sessionId: SESSION_ID,
+                // @ts-expect-error deliberately invalid persisted state
+                sessionState: 'bogus',
+                // @ts-expect-error deliberately invalid persisted tools
+                tools: undefined,
+                // @ts-expect-error deliberately missing persisted attached
+                attached: undefined,
+                // @ts-expect-error deliberately missing persisted lastSeen
+                lastSeen: undefined,
+            });
+            expect(restored.state).toBe('pending');
+            expect(restored.tools).toEqual([]);
+            expect(restored.harnessAttached).toBe(false);
+            expect(restored.lastSeenMs).toBeNull();
+        });
+    });
+});

package/dist/src/__tests__/tokens.test.d.ts

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

package/dist/src/__tests__/tokens.test.js

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest';
+import { CONNECTION_TOKEN_TTL_SECONDS, decodeConnectionToken, mintConnectionToken, parseBearer, sessionIdFromToken, } from '../tokens.js';
+const SECRET = 'test-secret-1234567890abcdef';
+const SESSION_ID = 'session-abc-123';
+const TAB_ID = 'tab-xyz-456';
+describe('tokens', () => {
+    describe('mintConnectionToken / sessionIdFromToken round-trip', () => {
+        it('returns the session_id from a freshly minted token', async () => {
+            const token = await mintConnectionToken(SESSION_ID, TAB_ID, SECRET);
+            const result = await sessionIdFromToken(token, SECRET);
+            expect(result).toBe(SESSION_ID);
+        });
+        it('returns null for a token signed with a different secret', async () => {
+            const token = await mintConnectionToken(SESSION_ID, TAB_ID, SECRET);
+            const result = await sessionIdFromToken(token, 'wrong-secret');
+            expect(result).toBeNull();
+        });
+        it('returns null for a tampered payload', async () => {
+            const token = await mintConnectionToken(SESSION_ID, TAB_ID, SECRET);
+            const parts = token.split('.');
+            // Flip a byte in the payload.
+            const payloadBytes = atob(parts[1].replace(/-/g, '+').replace(/_/g, '/'));
+            const tampered = payloadBytes.slice(0, -2) + 'XX';
+            const tamperedB64 = btoa(tampered)
+                .replace(/\+/g, '-')
+                .replace(/\//g, '_')
+                .replace(/=/g, '');
+            const tamperedToken = `${parts[0]}.${tamperedB64}.${parts[2]}`;
+            const result = await sessionIdFromToken(tamperedToken, SECRET);
+            expect(result).toBeNull();
+        });
+        it('returns null for an expired token', async () => {
+            const token = await mintConnectionToken(SESSION_ID, TAB_ID, SECRET, -1);
+            const result = await sessionIdFromToken(token, SECRET);
+            expect(result).toBeNull();
+        });
+        it('carries channel_id equal to session_id', async () => {
+            const token = await mintConnectionToken(SESSION_ID, TAB_ID, SECRET);
+            const claims = await decodeConnectionToken(token, SECRET);
+            expect(claims?.channel_id).toBe(SESSION_ID);
+            expect(claims?.tab_id).toBe(TAB_ID);
+        });
+        it('sets iss and aud correctly', async () => {
+            const token = await mintConnectionToken(SESSION_ID, TAB_ID, SECRET);
+            const claims = await decodeConnectionToken(token, SECRET);
+            expect(claims?.iss).toBe('urn:webmcp-relay');
+            expect(claims?.aud).toBe('webmcp-relay');
+        });
+        it('respects a custom TTL', async () => {
+            const before = Math.floor(Date.now() / 1000);
+            const ttl = 3600;
+            const token = await mintConnectionToken(SESSION_ID, TAB_ID, SECRET, ttl);
+            const claims = await decodeConnectionToken(token, SECRET);
+            expect(claims?.exp).toBeGreaterThanOrEqual(before + ttl - 1);
+            expect(claims?.exp).toBeLessThanOrEqual(before + ttl + 2);
+        });
+        it('uses CONNECTION_TOKEN_TTL_SECONDS by default (12 h)', () => {
+            expect(CONNECTION_TOKEN_TTL_SECONDS).toBe(12 * 3600);
+        });
+    });
+    describe('parseBearer', () => {
+        it('extracts a bearer token', () => {
+            expect(parseBearer('Bearer my-token-123')).toBe('my-token-123');
+        });
+        it('is case-insensitive for the scheme', () => {
+            expect(parseBearer('bearer abc')).toBe('abc');
+        });
+        it('returns null for missing auth', () => {
+            expect(parseBearer(null)).toBeNull();
+            expect(parseBearer(undefined)).toBeNull();
+            expect(parseBearer('')).toBeNull();
+        });
+        it('returns null for non-bearer scheme', () => {
+            expect(parseBearer('Basic dXNlcjpwYXNz')).toBeNull();
+        });
+    });
+});

package/dist/src/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @r0hitsharma/mcp-relay
+ *
+ * Host-agnostic core for the WebMCP relay protocol.
+ * Zero I/O, zero transport: pure state machine + JWT helpers.
+ * Works in Cloudflare Workers, Node >= 19, and browser environments.
+ */
+export * from './protocol.js';
+export * from './tokens.js';
+export * from './session.js';

package/dist/src/index.js

@@ -0,0 +1,10 @@
+/**
+ * @r0hitsharma/mcp-relay
+ *
+ * Host-agnostic core for the WebMCP relay protocol.
+ * Zero I/O, zero transport: pure state machine + JWT helpers.
+ * Works in Cloudflare Workers, Node >= 19, and browser environments.
+ */
+export * from './protocol.js';
+export * from './tokens.js';
+export * from './session.js';

package/dist/src/protocol.d.ts

@@ -0,0 +1,120 @@
+/**
+ * MVP wire-protocol types for the WebMCP relay.
+ *
+ * Re-declared here (not imported from @r0hitsharma/webmcp) so this
+ * package stays browser-free and usable in Cloudflare Workers without any
+ * DOM or React dependency.
+ *
+ * Field names match the Python protocol.py verbatim (snake_case throughout).
+ * Message `type` strings match the @mcp-b/webmcp-local-relay wire protocol
+ * so the existing browser client interoperates with no changes.
+ *
+ * MVP subset: connect + tool-activity only (NO mutation-confirmation).
+ */
+export interface ToolInputSchema {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+    [key: string]: unknown;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    /** Snake-case per MCP spec and the Python ToolDefinition model. */
+    input_schema: ToolInputSchema;
+    mutation?: boolean;
+    confirmation_summary_template?: string;
+}
+export interface HelloMessage {
+    type: 'hello';
+    tab_id: string;
+    origin: string;
+    url: string;
+    title?: string;
+    /** Durable HS256 JWT; the relay verifies it for stateless auth. */
+    connection_token?: string;
+}
+export interface ToolsListMessage {
+    type: 'tools/list';
+    tools: ToolDefinition[];
+}
+export interface ToolsChangedMessage {
+    type: 'tools/changed';
+    tools: ToolDefinition[];
+}
+export interface ResultMessage {
+    type: 'result';
+    call_id: string;
+    result: unknown;
+    error?: string;
+}
+export interface PongMessage {
+    type: 'pong';
+}
+export interface HelloAcceptedMessage {
+    type: 'hello/accepted';
+    session_id: string;
+}
+export interface HelloRejectedMessage {
+    type: 'hello/rejected';
+    reason: string;
+}
+export interface InvokeMessage {
+    type: 'invoke';
+    call_id: string;
+    tool_name: string;
+    args: Record<string, unknown>;
+}
+export interface PingMessage {
+    type: 'ping';
+}
+/**
+ * Best-effort feed of every tools/call the relay handles for this session.
+ * Pushed over the browser WS for the chat "Harness activity" panel.
+ */
+export interface ToolActivityMessage {
+    type: 'tool_activity';
+    activity_id: string;
+    tool_name: string;
+    kind: 'data' | 'ui' | 'mutation';
+    status: 'started' | 'ok' | 'error' | 'denied';
+    args?: Record<string, unknown>;
+    result_preview?: string | null;
+    error?: string | null;
+}
+/**
+ * Pushed when harness attachment state changes.
+ * CONTRACT: { type: "harness_status", attached: bool, last_activity_ms: int | null }
+ * The frontend codes against this exact shape.
+ */
+export interface HarnessStatusMessage {
+    type: 'harness_status';
+    attached: boolean;
+    /** Wall-clock ms timestamp of the last harness /mcp call, or null. */
+    last_activity_ms: number | null;
+}
+/** Frames a browser back-channel sends to the relay. */
+export type BrowserToServerMessage = HelloMessage | ToolsListMessage | ToolsChangedMessage | ResultMessage | PongMessage;
+/** Frames the relay pushes to a browser back-channel. */
+export type ServerToBrowserMessage = HelloAcceptedMessage | HelloRejectedMessage | InvokeMessage | PingMessage | ToolActivityMessage | HarnessStatusMessage;
+export interface CreateSessionResponse {
+    session_id: string;
+    pairing_token: string;
+    /** Durable HS256 JWT the user pastes into their harness config. */
+    connection_token: string;
+    /** ISO-8601 deadline for connection_token. */
+    connection_token_expires_at: string;
+    ws_url: string;
+    expires_at: string;
+}
+export interface ConnectionTokenClaims {
+    iss: string;
+    sub: string;
+    aud: string;
+    jti: string;
+    iat: number;
+    exp: number;
+    channel_id: string;
+    scope: string;
+    tab_id: string;
+}

package/dist/src/protocol.js

@@ -0,0 +1,14 @@
+/**
+ * MVP wire-protocol types for the WebMCP relay.
+ *
+ * Re-declared here (not imported from @r0hitsharma/webmcp) so this
+ * package stays browser-free and usable in Cloudflare Workers without any
+ * DOM or React dependency.
+ *
+ * Field names match the Python protocol.py verbatim (snake_case throughout).
+ * Message `type` strings match the @mcp-b/webmcp-local-relay wire protocol
+ * so the existing browser client interoperates with no changes.
+ *
+ * MVP subset: connect + tool-activity only (NO mutation-confirmation).
+ */
+export {};

package/dist/src/session.d.ts

@@ -0,0 +1,114 @@
+/**
+ * RelaySession: sans-I/O state machine for ONE relay session.
+ *
+ * CORE vs HOST BOUNDARY
+ * ---------------------
+ * This class owns protocol framing and state tracking ONLY.
+ * It never touches a socket, timer, or Promise.
+ *
+ * The HOST (e.g. the Cloudflare Durable Object in session-do.ts) is
+ * responsible for:
+ *   - Holding the live WebSocket and sending/receiving frames.
+ *   - The async invoke round-trip: generating a call_id, sending the
+ *     InvokeMessage over the WS, storing a {resolve, reject, timer} entry
+ *     keyed by call_id, resolving it when the browser's `result` frame
+ *     arrives, and timing out after INVOKE_TIMEOUT_MS.
+ *   - Scheduling the liveness TTL sweep (e.g. via a DO alarm).
+ *
+ * The core's role in a tools/call flow:
+ *   1. Host calls core.buildInvoke(callId, name, args) to get the wire frame.
+ *   2. Host sends the frame and registers the pending call.
+ *   3. Browser sends a `result` frame; host calls core.buildToolActivity(...)
+ *      to get the terminal activity frame, then resolves the pending call.
+ *   4. Host pushes the tool_activity frames and returns the JSON-RPC response.
+ */
+import type { HelloAcceptedMessage, HelloMessage, HelloRejectedMessage, HarnessStatusMessage, InvokeMessage, ToolActivityMessage, ToolDefinition } from './protocol.js';
+/** State machine states, mirroring the Python SessionRecord. */
+export type SessionState = 'pending' | 'connected' | 'disconnected';
+/** Liveness TTL: 90 s matches the Python HARNESS_LIVENESS_TTL_SECONDS. */
+export declare const HARNESS_LIVENESS_TTL_MS = 90000;
+/** Invoke timeout: 30 s matches the Python INVOKE_TIMEOUT_SECONDS. */
+export declare const INVOKE_TIMEOUT_MS = 30000;
+/**
+ * Serializable snapshot of a session's durable state. A host (e.g. a Cloudflare
+ * Durable Object) persists this so the session survives eviction/hibernation,
+ * then rehydrates with RelaySession.fromSnapshot.
+ */
+export interface RelaySessionSnapshot {
+    sessionId: string;
+    sessionState: SessionState;
+    tools: ToolDefinition[];
+    attached: boolean;
+    lastSeen: number | null;
+}
+export declare class RelaySession {
+    readonly sessionId: string;
+    private sessionState;
+    private toolsCatalogue;
+    private attached;
+    /** Wall-clock ms of the last harness /mcp call (null = never). */
+    private lastSeen;
+    constructor(sessionId: string);
+    get state(): SessionState;
+    get tools(): readonly ToolDefinition[];
+    get harnessAttached(): boolean;
+    get lastSeenMs(): number | null;
+    /** Snapshot the durable state so a host can persist it (e.g. to DO storage). */
+    toSnapshot(): RelaySessionSnapshot;
+    /**
+     * Reconstruct a session from a persisted snapshot (after eviction/wake).
+     *
+     * This is the durability seam: the snapshot may have been written by an older
+     * code version, so every field is validated and defaulted rather than trusted.
+     * An unknown/corrupt state falls back to `pending`, and `attached`/`lastSeen`
+     * are coerced so the wire frames built afterwards never carry undefined values.
+     */
+    static fromSnapshot(snap: RelaySessionSnapshot): RelaySession;
+    /**
+     * Validate a browser `hello` and return the appropriate response.
+     * The caller (host) is responsible for verifying the connection_token JWT
+     * before calling this; pass `tokenValid = false` to reject immediately.
+     */
+    onHello(_hello: HelloMessage, tokenValid: boolean): HelloAcceptedMessage | HelloRejectedMessage;
+    /** Mark the session disconnected (browser WS closed). */
+    onDisconnect(): void;
+    /** Store the full catalogue pushed by `tools/list` or `tools/changed`. */
+    setTools(tools: ToolDefinition[]): void;
+    /**
+     * Called by the host on every /mcp request to record the harness timestamp.
+     * Returns a `harness_status` frame to push over the WS.
+     */
+    touch(nowMs: number): HarnessStatusMessage;
+    /**
+     * Mark harness attached on `initialize`. Returns the `harness_status` frame
+     * to push over the WS (best-effort, host sends it).
+     */
+    onInitialize(nowMs: number): {
+        harnessStatus: HarnessStatusMessage;
+    };
+    /**
+     * TTL sweep: revert harness-attached to false if the TTL has elapsed.
+     * Returns a `harness_status` frame if the state flipped (host must push it),
+     * or null if nothing changed.
+     */
+    sweep(nowMs: number, ttlMs?: number): HarnessStatusMessage | null;
+    /** Build the JSON-RPC `tools/list` result payload. */
+    listToolsResult(jsonRpcId: unknown): object;
+    /**
+     * Build an `invoke` wire frame for a browser tool call.
+     * The HOST generates callId (crypto.randomUUID()) and stores the pending
+     * promise before sending this frame.
+     */
+    buildInvoke(callId: string, toolName: string, args: Record<string, unknown>): InvokeMessage;
+    /**
+     * Build a `tool_activity` frame.
+     * Called by the host at start (status="started") and on completion (status="ok"|"error").
+     */
+    buildToolActivity(activityId: string, toolName: string, status: ToolActivityMessage['status'], options?: {
+        kind?: ToolActivityMessage['kind'];
+        args?: Record<string, unknown>;
+        resultPreview?: string;
+        error?: string;
+    }): ToolActivityMessage;
+    private harnessStatusFrame;
+}