@llui/agent 0.0.29

package/dist/server/token.js

@@ -0,0 +1,77 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+const PREFIX = 'llui-agent_';
+function toKeyBuffer(key) {
+    const buf = typeof key === 'string' ? Buffer.from(key, 'utf8') : Buffer.from(key);
+    if (buf.length < 32)
+        throw new Error('signingKey must be at least 32 bytes');
+    return buf;
+}
+function b64url(buf) {
+    return buf.toString('base64url');
+}
+function b64urlDecode(s) {
+    try {
+        return Buffer.from(s, 'base64url');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Serialize a payload to `llui-agent_<base64url(json)>.<base64url(hmac)>`.
+ * See spec §6.1.
+ */
+export function signToken(payload, key) {
+    const keyBuf = toKeyBuffer(key);
+    const jsonBuf = Buffer.from(JSON.stringify(payload), 'utf8');
+    const payloadPart = b64url(jsonBuf);
+    const mac = createHmac('sha256', keyBuf).update(payloadPart).digest();
+    const sigPart = b64url(mac);
+    return (PREFIX + payloadPart + '.' + sigPart);
+}
+/**
+ * Verify the signature, parse the payload, and check expiry.
+ */
+export function verifyToken(token, key, nowSec = Math.floor(Date.now() / 1000)) {
+    if (!token.startsWith(PREFIX))
+        return { kind: 'invalid', reason: 'malformed' };
+    const body = token.slice(PREFIX.length);
+    const dot = body.indexOf('.');
+    if (dot < 0)
+        return { kind: 'invalid', reason: 'malformed' };
+    const payloadPart = body.slice(0, dot);
+    const sigPart = body.slice(dot + 1);
+    const sigBuf = b64urlDecode(sigPart);
+    if (!sigBuf)
+        return { kind: 'invalid', reason: 'malformed' };
+    const keyBuf = toKeyBuffer(key);
+    const expected = createHmac('sha256', keyBuf).update(payloadPart).digest();
+    if (expected.length !== sigBuf.length || !timingSafeEqual(expected, sigBuf)) {
+        return { kind: 'invalid', reason: 'bad-signature' };
+    }
+    const jsonBuf = b64urlDecode(payloadPart);
+    if (!jsonBuf)
+        return { kind: 'invalid', reason: 'malformed' };
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonBuf.toString('utf8'));
+    }
+    catch {
+        return { kind: 'invalid', reason: 'malformed' };
+    }
+    if (!isTokenPayload(parsed))
+        return { kind: 'invalid', reason: 'malformed' };
+    if (parsed.exp <= nowSec)
+        return { kind: 'invalid', reason: 'expired' };
+    return { kind: 'ok', payload: parsed };
+}
+function isTokenPayload(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const o = x;
+    return (typeof o.tid === 'string' &&
+        typeof o.iat === 'number' &&
+        typeof o.exp === 'number' &&
+        o.scope === 'agent');
+}
+//# sourceMappingURL=token.js.map

package/dist/server/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../src/server/token.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHmac, timingSafeEqual } from 'node:crypto'\nimport type { AgentToken } from '../protocol.js'\n\nexport type TokenPayload = {\n  tid: string\n  iat: number\n  exp: number\n  scope: 'agent'\n}\n\nexport type VerifyResult =\n  | { kind: 'ok'; payload: TokenPayload }\n  | { kind: 'invalid'; reason: 'malformed' | 'bad-signature' | 'expired' }\n\nconst PREFIX = 'llui-agent_'\n\nfunction toKeyBuffer(key: string | Uint8Array): Buffer {\n  const buf = typeof key === 'string' ? Buffer.from(key, 'utf8') : Buffer.from(key)\n  if (buf.length < 32) throw new Error('signingKey must be at least 32 bytes')\n  return buf\n}\n\nfunction b64url(buf: Buffer): string {\n  return buf.toString('base64url')\n}\n\nfunction b64urlDecode(s: string): Buffer | null {\n  try {\n    return Buffer.from(s, 'base64url')\n  } catch {\n    return null\n  }\n}\n\n/**\n * Serialize a payload to `llui-agent_<base64url(json)>.<base64url(hmac)>`.\n * See spec §6.1.\n */\nexport function signToken(payload: TokenPayload, key: string | Uint8Array): AgentToken {\n  const keyBuf = toKeyBuffer(key)\n  const jsonBuf = Buffer.from(JSON.stringify(payload), 'utf8')\n  const payloadPart = b64url(jsonBuf)\n  const mac = createHmac('sha256', keyBuf).update(payloadPart).digest()\n  const sigPart = b64url(mac)\n  return (PREFIX + payloadPart + '.' + sigPart) as AgentToken\n}\n\n/**\n * Verify the signature, parse the payload, and check expiry.\n */\nexport function verifyToken(\n  token: string,\n  key: string | Uint8Array,\n  nowSec: number = Math.floor(Date.now() / 1000),\n): VerifyResult {\n  if (!token.startsWith(PREFIX)) return { kind: 'invalid', reason: 'malformed' }\n  const body = token.slice(PREFIX.length)\n  const dot = body.indexOf('.')\n  if (dot < 0) return { kind: 'invalid', reason: 'malformed' }\n\n  const payloadPart = body.slice(0, dot)\n  const sigPart = body.slice(dot + 1)\n  const sigBuf = b64urlDecode(sigPart)\n  if (!sigBuf) return { kind: 'invalid', reason: 'malformed' }\n\n  const keyBuf = toKeyBuffer(key)\n  const expected = createHmac('sha256', keyBuf).update(payloadPart).digest()\n  if (expected.length !== sigBuf.length || !timingSafeEqual(expected, sigBuf)) {\n    return { kind: 'invalid', reason: 'bad-signature' }\n  }\n\n  const jsonBuf = b64urlDecode(payloadPart)\n  if (!jsonBuf) return { kind: 'invalid', reason: 'malformed' }\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(jsonBuf.toString('utf8'))\n  } catch {\n    return { kind: 'invalid', reason: 'malformed' }\n  }\n\n  if (!isTokenPayload(parsed)) return { kind: 'invalid', reason: 'malformed' }\n  if (parsed.exp <= nowSec) return { kind: 'invalid', reason: 'expired' }\n  return { kind: 'ok', payload: parsed }\n}\n\nfunction isTokenPayload(x: unknown): x is TokenPayload {\n  if (!x || typeof x !== 'object') return false\n  const o = x as Record<string, unknown>\n  return (\n    typeof o.tid === 'string' &&\n    typeof o.iat === 'number' &&\n    typeof o.exp === 'number' &&\n    o.scope === 'agent'\n  )\n}\n"]}

package/dist/server/ws/pairing-registry.d.ts

@@ -0,0 +1,53 @@
+import type { ClientFrame, ServerFrame, HelloFrame, LogEntry } from '../../protocol.js';
+/**
+ * Thin abstraction over a WebSocket so the registry is testable with
+ * a fake EventEmitter-style mock.
+ */
+export interface PairingConnection {
+    send(frame: ServerFrame): void;
+    onFrame(handler: (f: ClientFrame) => void): void;
+    onClose(handler: () => void): void;
+    close(): void;
+}
+export type RpcError = {
+    code: 'paused' | 'invalid' | 'timeout' | 'schema-error' | 'internal' | string;
+    detail?: string;
+};
+export type RpcOptions = {
+    timeoutMs?: number;
+};
+/**
+ * Tracks live browser pairings and correlates rpc requests with replies.
+ * One instance per server; shared by all LAP handlers + the upgrade
+ * handler. Spec §10.4–§10.5.
+ */
+export declare class WsPairingRegistry {
+    private pairings;
+    private now;
+    private onLogAppend;
+    constructor(opts?: {
+        now?: () => number;
+        onLogAppend?: (tid: string, entry: LogEntry) => void;
+    });
+    register(tid: string, conn: PairingConnection): void;
+    unregister(tid: string): void;
+    isPaired(tid: string): boolean;
+    /**
+     * Send a ServerFrame to the paired browser connection, if one is live.
+     * No-op when unpaired or closed.
+     */
+    notify(tid: string, frame: ServerFrame): void;
+    getHello(tid: string): HelloFrame | null;
+    rpc(tid: string, tool: string, args: unknown, opts?: RpcOptions): Promise<unknown>;
+    waitForConfirm(tid: string, confirmId: string, timeoutMs: number): Promise<{
+        outcome: 'confirmed' | 'user-cancelled';
+        stateAfter?: unknown;
+    }>;
+    waitForChange(tid: string, path: string | undefined, timeoutMs: number): Promise<{
+        status: 'changed' | 'timeout';
+        stateAfter: unknown;
+    }>;
+    private handleClientFrame;
+    private handleClose;
+}
+//# sourceMappingURL=pairing-registry.d.ts.map

package/dist/server/ws/pairing-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing-registry.d.ts","sourceRoot":"","sources":["../../../src/server/ws/pairing-registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAEvF;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAA;IAC9B,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI,CAAA;IAChD,OAAO,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;IAClC,KAAK,IAAI,IAAI,CAAA;CACd;AA4BD,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,cAAc,GAAG,UAAU,GAAG,MAAM,CAAA;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAE/C;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,GAAG,CAAc;IACzB,OAAO,CAAC,WAAW,CAAiD;gBAGlE,IAAI,GAAE;QACJ,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;QAClB,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAA;KAChD;IAMR,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,IAAI;IAcpD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAM7B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAK9B;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI;IAU7C,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAIlC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IA6BtF,cAAc,CAClB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;QAAE,OAAO,EAAE,WAAW,GAAG,gBAAgB,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAiBvE,aAAa,CACjB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;QAAE,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC;IAiBlE,OAAO,CAAC,iBAAiB;IAmDzB,OAAO,CAAC,WAAW;CAqBpB"}

package/dist/server/ws/pairing-registry.js

@@ -0,0 +1,205 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * Tracks live browser pairings and correlates rpc requests with replies.
+ * One instance per server; shared by all LAP handlers + the upgrade
+ * handler. Spec §10.4–§10.5.
+ */
+export class WsPairingRegistry {
+    pairings = new Map();
+    now;
+    onLogAppend;
+    constructor(opts = {}) {
+        this.now = opts.now ?? (() => Date.now());
+        this.onLogAppend = opts.onLogAppend ?? null;
+    }
+    register(tid, conn) {
+        const p = {
+            conn,
+            hello: null,
+            pendingRpc: new Map(),
+            pendingConfirm: new Map(),
+            pendingWait: [],
+            closed: false,
+        };
+        this.pairings.set(tid, p);
+        conn.onFrame((frame) => this.handleClientFrame(tid, frame));
+        conn.onClose(() => this.handleClose(tid));
+    }
+    unregister(tid) {
+        const p = this.pairings.get(tid);
+        if (!p)
+            return;
+        this.handleClose(tid);
+    }
+    isPaired(tid) {
+        const p = this.pairings.get(tid);
+        return !!p && !p.closed;
+    }
+    /**
+     * Send a ServerFrame to the paired browser connection, if one is live.
+     * No-op when unpaired or closed.
+     */
+    notify(tid, frame) {
+        const p = this.pairings.get(tid);
+        if (!p || p.closed)
+            return;
+        try {
+            p.conn.send(frame);
+        }
+        catch {
+            // connection may have dropped between isPaired and notify; ignore
+        }
+    }
+    getHello(tid) {
+        return this.pairings.get(tid)?.hello ?? null;
+    }
+    async rpc(tid, tool, args, opts = {}) {
+        const p = this.pairings.get(tid);
+        if (!p || p.closed) {
+            const err = { code: 'paused' };
+            throw err;
+        }
+        const id = randomUUID();
+        const timeoutMs = opts.timeoutMs ?? 15_000;
+        return new Promise((resolve, reject) => {
+            const entry = {
+                resolve,
+                reject,
+                timer: setTimeout(() => {
+                    p.pendingRpc.delete(id);
+                    reject({ code: 'timeout' });
+                }, timeoutMs),
+            };
+            p.pendingRpc.set(id, entry);
+            const frame = { t: 'rpc', id, tool, args };
+            try {
+                p.conn.send(frame);
+            }
+            catch (e) {
+                p.pendingRpc.delete(id);
+                if (entry.timer)
+                    clearTimeout(entry.timer);
+                reject({ code: 'internal', detail: String(e) });
+            }
+        });
+    }
+    async waitForConfirm(tid, confirmId, timeoutMs) {
+        const p = this.pairings.get(tid);
+        if (!p || p.closed) {
+            return { outcome: 'user-cancelled' };
+        }
+        return new Promise((resolve) => {
+            const entry = {
+                resolve,
+                timer: setTimeout(() => {
+                    p.pendingConfirm.delete(confirmId);
+                    resolve({ outcome: 'user-cancelled' });
+                }, timeoutMs),
+            };
+            p.pendingConfirm.set(confirmId, entry);
+        });
+    }
+    async waitForChange(tid, path, timeoutMs) {
+        const p = this.pairings.get(tid);
+        if (!p || p.closed)
+            return { status: 'timeout', stateAfter: null };
+        return new Promise((resolve) => {
+            const entry = {
+                path,
+                resolve,
+                timer: setTimeout(() => {
+                    const idx = p.pendingWait.indexOf(entry);
+                    if (idx >= 0)
+                        p.pendingWait.splice(idx, 1);
+                    resolve({ status: 'timeout', stateAfter: null });
+                }, timeoutMs),
+            };
+            p.pendingWait.push(entry);
+        });
+    }
+    handleClientFrame(tid, frame) {
+        const p = this.pairings.get(tid);
+        if (!p || p.closed)
+            return;
+        switch (frame.t) {
+            case 'hello': {
+                p.hello = frame;
+                break;
+            }
+            case 'rpc-reply': {
+                const e = p.pendingRpc.get(frame.id);
+                if (!e)
+                    break;
+                p.pendingRpc.delete(frame.id);
+                if (e.timer)
+                    clearTimeout(e.timer);
+                e.resolve(frame.result);
+                break;
+            }
+            case 'rpc-error': {
+                const e = p.pendingRpc.get(frame.id);
+                if (!e)
+                    break;
+                p.pendingRpc.delete(frame.id);
+                if (e.timer)
+                    clearTimeout(e.timer);
+                e.reject({ code: frame.code, detail: frame.detail });
+                break;
+            }
+            case 'confirm-resolved': {
+                const e = p.pendingConfirm.get(frame.confirmId);
+                if (!e)
+                    break;
+                p.pendingConfirm.delete(frame.confirmId);
+                if (e.timer)
+                    clearTimeout(e.timer);
+                e.resolve({ outcome: frame.outcome, stateAfter: frame.stateAfter });
+                break;
+            }
+            case 'state-update': {
+                for (let i = p.pendingWait.length - 1; i >= 0; i--) {
+                    const w = p.pendingWait[i];
+                    if (w === undefined)
+                        continue;
+                    if (w.path === undefined || w.path === frame.path || frame.path.startsWith(w.path)) {
+                        p.pendingWait.splice(i, 1);
+                        if (w.timer)
+                            clearTimeout(w.timer);
+                        w.resolve({ status: 'changed', stateAfter: frame.stateAfter });
+                    }
+                }
+                break;
+            }
+            case 'log-append': {
+                this.onLogAppend?.(tid, frame.entry);
+                break;
+            }
+        }
+    }
+    handleClose(tid) {
+        const p = this.pairings.get(tid);
+        if (!p)
+            return;
+        p.closed = true;
+        for (const [, e] of p.pendingRpc) {
+            if (e.timer)
+                clearTimeout(e.timer);
+            e.reject({ code: 'paused' });
+        }
+        p.pendingRpc.clear();
+        for (const [, e] of p.pendingConfirm) {
+            if (e.timer)
+                clearTimeout(e.timer);
+            e.resolve({ outcome: 'user-cancelled' });
+        }
+        p.pendingConfirm.clear();
+        for (const w of p.pendingWait) {
+            if (w.timer)
+                clearTimeout(w.timer);
+            w.resolve({ status: 'timeout', stateAfter: null });
+        }
+        p.pendingWait.length = 0;
+        this.pairings.delete(tid);
+    }
+}
+//# sourceMappingURL=pairing-registry.js.map

package/dist/server/ws/pairing-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing-registry.js","sourceRoot":"","sources":["../../../src/server/ws/pairing-registry.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from 'node:crypto'\nimport type { ClientFrame, ServerFrame, HelloFrame, LogEntry } from '../../protocol.js'\n\n/**\n * Thin abstraction over a WebSocket so the registry is testable with\n * a fake EventEmitter-style mock.\n */\nexport interface PairingConnection {\n  send(frame: ServerFrame): void\n  onFrame(handler: (f: ClientFrame) => void): void\n  onClose(handler: () => void): void\n  close(): void\n}\n\ntype RpcEntry = {\n  resolve: (result: unknown) => void\n  reject: (err: RpcError) => void\n  timer: ReturnType<typeof setTimeout> | null\n}\n\ntype ConfirmEntry = {\n  resolve: (r: { outcome: 'confirmed' | 'user-cancelled'; stateAfter?: unknown }) => void\n  timer: ReturnType<typeof setTimeout> | null\n}\n\ntype WaitEntry = {\n  path: string | undefined\n  resolve: (r: { status: 'changed' | 'timeout'; stateAfter: unknown }) => void\n  timer: ReturnType<typeof setTimeout> | null\n}\n\ntype Pairing = {\n  conn: PairingConnection\n  hello: HelloFrame | null\n  pendingRpc: Map<string, RpcEntry>\n  pendingConfirm: Map<string, ConfirmEntry>\n  pendingWait: WaitEntry[]\n  closed: boolean\n}\n\nexport type RpcError = {\n  code: 'paused' | 'invalid' | 'timeout' | 'schema-error' | 'internal' | string\n  detail?: string\n}\n\nexport type RpcOptions = { timeoutMs?: number }\n\n/**\n * Tracks live browser pairings and correlates rpc requests with replies.\n * One instance per server; shared by all LAP handlers + the upgrade\n * handler. Spec §10.4–§10.5.\n */\nexport class WsPairingRegistry {\n  private pairings = new Map<string, Pairing>()\n  private now: () => number\n  private onLogAppend: ((tid: string, entry: LogEntry) => void) | null\n\n  constructor(\n    opts: {\n      now?: () => number\n      onLogAppend?: (tid: string, entry: LogEntry) => void\n    } = {},\n  ) {\n    this.now = opts.now ?? (() => Date.now())\n    this.onLogAppend = opts.onLogAppend ?? null\n  }\n\n  register(tid: string, conn: PairingConnection): void {\n    const p: Pairing = {\n      conn,\n      hello: null,\n      pendingRpc: new Map(),\n      pendingConfirm: new Map(),\n      pendingWait: [],\n      closed: false,\n    }\n    this.pairings.set(tid, p)\n    conn.onFrame((frame) => this.handleClientFrame(tid, frame))\n    conn.onClose(() => this.handleClose(tid))\n  }\n\n  unregister(tid: string): void {\n    const p = this.pairings.get(tid)\n    if (!p) return\n    this.handleClose(tid)\n  }\n\n  isPaired(tid: string): boolean {\n    const p = this.pairings.get(tid)\n    return !!p && !p.closed\n  }\n\n  /**\n   * Send a ServerFrame to the paired browser connection, if one is live.\n   * No-op when unpaired or closed.\n   */\n  notify(tid: string, frame: ServerFrame): void {\n    const p = this.pairings.get(tid)\n    if (!p || p.closed) return\n    try {\n      p.conn.send(frame)\n    } catch {\n      // connection may have dropped between isPaired and notify; ignore\n    }\n  }\n\n  getHello(tid: string): HelloFrame | null {\n    return this.pairings.get(tid)?.hello ?? null\n  }\n\n  async rpc(tid: string, tool: string, args: unknown, opts: RpcOptions = {}): Promise<unknown> {\n    const p = this.pairings.get(tid)\n    if (!p || p.closed) {\n      const err: RpcError = { code: 'paused' }\n      throw err\n    }\n    const id = randomUUID()\n    const timeoutMs = opts.timeoutMs ?? 15_000\n    return new Promise((resolve, reject) => {\n      const entry: RpcEntry = {\n        resolve,\n        reject,\n        timer: setTimeout(() => {\n          p.pendingRpc.delete(id)\n          reject({ code: 'timeout' } as RpcError)\n        }, timeoutMs),\n      }\n      p.pendingRpc.set(id, entry)\n      const frame: ServerFrame = { t: 'rpc', id, tool, args }\n      try {\n        p.conn.send(frame)\n      } catch (e) {\n        p.pendingRpc.delete(id)\n        if (entry.timer) clearTimeout(entry.timer)\n        reject({ code: 'internal', detail: String(e) } as RpcError)\n      }\n    })\n  }\n\n  async waitForConfirm(\n    tid: string,\n    confirmId: string,\n    timeoutMs: number,\n  ): Promise<{ outcome: 'confirmed' | 'user-cancelled'; stateAfter?: unknown }> {\n    const p = this.pairings.get(tid)\n    if (!p || p.closed) {\n      return { outcome: 'user-cancelled' }\n    }\n    return new Promise((resolve) => {\n      const entry: ConfirmEntry = {\n        resolve,\n        timer: setTimeout(() => {\n          p.pendingConfirm.delete(confirmId)\n          resolve({ outcome: 'user-cancelled' })\n        }, timeoutMs),\n      }\n      p.pendingConfirm.set(confirmId, entry)\n    })\n  }\n\n  async waitForChange(\n    tid: string,\n    path: string | undefined,\n    timeoutMs: number,\n  ): Promise<{ status: 'changed' | 'timeout'; stateAfter: unknown }> {\n    const p = this.pairings.get(tid)\n    if (!p || p.closed) return { status: 'timeout', stateAfter: null }\n    return new Promise((resolve) => {\n      const entry: WaitEntry = {\n        path,\n        resolve,\n        timer: setTimeout(() => {\n          const idx = p.pendingWait.indexOf(entry)\n          if (idx >= 0) p.pendingWait.splice(idx, 1)\n          resolve({ status: 'timeout', stateAfter: null })\n        }, timeoutMs),\n      }\n      p.pendingWait.push(entry)\n    })\n  }\n\n  private handleClientFrame(tid: string, frame: ClientFrame): void {\n    const p = this.pairings.get(tid)\n    if (!p || p.closed) return\n    switch (frame.t) {\n      case 'hello': {\n        p.hello = frame\n        break\n      }\n      case 'rpc-reply': {\n        const e = p.pendingRpc.get(frame.id)\n        if (!e) break\n        p.pendingRpc.delete(frame.id)\n        if (e.timer) clearTimeout(e.timer)\n        e.resolve(frame.result)\n        break\n      }\n      case 'rpc-error': {\n        const e = p.pendingRpc.get(frame.id)\n        if (!e) break\n        p.pendingRpc.delete(frame.id)\n        if (e.timer) clearTimeout(e.timer)\n        e.reject({ code: frame.code, detail: frame.detail } as RpcError)\n        break\n      }\n      case 'confirm-resolved': {\n        const e = p.pendingConfirm.get(frame.confirmId)\n        if (!e) break\n        p.pendingConfirm.delete(frame.confirmId)\n        if (e.timer) clearTimeout(e.timer)\n        e.resolve({ outcome: frame.outcome, stateAfter: frame.stateAfter })\n        break\n      }\n      case 'state-update': {\n        for (let i = p.pendingWait.length - 1; i >= 0; i--) {\n          const w = p.pendingWait[i]\n          if (w === undefined) continue\n          if (w.path === undefined || w.path === frame.path || frame.path.startsWith(w.path)) {\n            p.pendingWait.splice(i, 1)\n            if (w.timer) clearTimeout(w.timer)\n            w.resolve({ status: 'changed', stateAfter: frame.stateAfter })\n          }\n        }\n        break\n      }\n      case 'log-append': {\n        this.onLogAppend?.(tid, frame.entry)\n        break\n      }\n    }\n  }\n\n  private handleClose(tid: string): void {\n    const p = this.pairings.get(tid)\n    if (!p) return\n    p.closed = true\n    for (const [, e] of p.pendingRpc) {\n      if (e.timer) clearTimeout(e.timer)\n      e.reject({ code: 'paused' } as RpcError)\n    }\n    p.pendingRpc.clear()\n    for (const [, e] of p.pendingConfirm) {\n      if (e.timer) clearTimeout(e.timer)\n      e.resolve({ outcome: 'user-cancelled' })\n    }\n    p.pendingConfirm.clear()\n    for (const w of p.pendingWait) {\n      if (w.timer) clearTimeout(w.timer)\n      w.resolve({ status: 'timeout', stateAfter: null })\n    }\n    p.pendingWait.length = 0\n    this.pairings.delete(tid)\n  }\n}\n"]}

package/dist/server/ws/upgrade.d.ts

@@ -0,0 +1,23 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { WsPairingRegistry } from './pairing-registry.js';
+import type { TokenStore } from '../token-store.js';
+import type { AuditSink } from '../audit.js';
+export type UpgradeDeps = {
+    signingKey: string | Uint8Array;
+    tokenStore: TokenStore;
+    registry: WsPairingRegistry;
+    auditSink: AuditSink;
+    now?: () => number;
+};
+/**
+ * Returns a handler for `server.on('upgrade', ...)`. Validates the token
+ * from the query string, attaches to the registry, wires frame/close
+ * routing. Unauthorized paths/tokens get a bare HTTP error response on
+ * the raw socket (per RFC 6455 the response must be sent before the
+ * socket is torn down).
+ *
+ * Spec §10.2, §10.4.
+ */
+export declare function createWsUpgradeHandler(deps: UpgradeDeps): (req: IncomingMessage, socket: Duplex, head: Buffer) => void;
+//# sourceMappingURL=upgrade.d.ts.map

package/dist/server/ws/upgrade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../../src/server/ws/upgrade.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,iBAAiB,EAAqB,MAAM,uBAAuB,CAAA;AACjF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAI5C,MAAM,MAAM,WAAW,GAAG;IACxB,UAAU,EAAE,MAAM,GAAG,UAAU,CAAA;IAC/B,UAAU,EAAE,UAAU,CAAA;IACtB,QAAQ,EAAE,iBAAiB,CAAA;IAC3B,SAAS,EAAE,SAAS,CAAA;IACpB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,WAAW,IAI9C,KAAK,eAAe,EAAE,QAAQ,MAAM,EAAE,MAAM,MAAM,KAAG,IAAI,CAoElE"}

package/dist/server/ws/upgrade.js

@@ -0,0 +1,81 @@
+import { WebSocketServer } from 'ws';
+import { verifyToken } from '../token.js';
+/**
+ * Returns a handler for `server.on('upgrade', ...)`. Validates the token
+ * from the query string, attaches to the registry, wires frame/close
+ * routing. Unauthorized paths/tokens get a bare HTTP error response on
+ * the raw socket (per RFC 6455 the response must be sent before the
+ * socket is torn down).
+ *
+ * Spec §10.2, §10.4.
+ */
+export function createWsUpgradeHandler(deps) {
+    const wss = new WebSocketServer({ noServer: true });
+    const now = deps.now ?? (() => Date.now());
+    return (req, socket, head) => {
+        // Path check
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        if (url.pathname !== '/agent/ws') {
+            socket.write('HTTP/1.1 404 Not Found\r\n\r\n');
+            socket.destroy();
+            return;
+        }
+        // Token — try query string first, then Authorization header
+        let token = url.searchParams.get('token');
+        if (!token) {
+            const auth = req.headers['authorization'];
+            if (typeof auth === 'string' && auth.startsWith('Bearer ')) {
+                token = auth.slice('Bearer '.length);
+            }
+        }
+        if (!token) {
+            socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+            socket.destroy();
+            return;
+        }
+        const verified = verifyToken(token, deps.signingKey);
+        if (verified.kind !== 'ok') {
+            socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+            socket.destroy();
+            return;
+        }
+        const { tid } = verified.payload;
+        // Perform upgrade, wire to registry
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            const conn = {
+                send(frame) {
+                    ws.send(JSON.stringify(frame));
+                },
+                onFrame(handler) {
+                    ws.on('message', (data) => {
+                        const raw = typeof data === 'string' ? data : data.toString('utf8');
+                        try {
+                            const parsed = JSON.parse(raw);
+                            handler(parsed);
+                        }
+                        catch {
+                            // Ignore malformed frames.
+                        }
+                    });
+                },
+                onClose(handler) {
+                    ws.on('close', handler);
+                },
+                close() {
+                    ws.close();
+                },
+            };
+            deps.registry.register(tid, conn);
+            // Transition status: browser WS is now live, waiting for Claude's first call.
+            void deps.tokenStore.markAwaitingClaude(tid, now());
+            void deps.auditSink.write({
+                at: now(),
+                tid,
+                uid: null,
+                event: 'claim',
+                detail: { transport: 'ws' },
+            });
+        });
+    };
+}
+//# sourceMappingURL=upgrade.js.map

package/dist/server/ws/upgrade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.js","sourceRoot":"","sources":["../../../src/server/ws/upgrade.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,IAAI,CAAA;AAOpC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAWzC;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAiB;IACtD,MAAM,GAAG,GAAG,IAAI,eAAe,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;IACnD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;IAE1C,OAAO,CAAC,GAAoB,EAAE,MAAc,EAAE,IAAY,EAAQ,EAAE;QAClE,aAAa;QACb,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,EAAE,kBAAkB,CAAC,CAAA;QACvD,IAAI,GAAG,CAAC,QAAQ,KAAK,WAAW,EAAE,CAAC;YACjC,MAAM,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAA;YAC9C,MAAM,CAAC,OAAO,EAAE,CAAA;YAChB,OAAM;QACR,CAAC;QAED,4DAA4D;QAC5D,IAAI,KAAK,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QACzC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAA;YACzC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC3D,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;YACtC,CAAC;QACH,CAAC;QACD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAA;YACjD,MAAM,CAAC,OAAO,EAAE,CAAA;YAChB,OAAM;QACR,CAAC;QAED,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,CAAA;QACpD,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YAC3B,MAAM,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAA;YACjD,MAAM,CAAC,OAAO,EAAE,CAAA;YAChB,OAAM;QACR,CAAC;QACD,MAAM,EAAE,GAAG,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAA;QAEhC,oCAAoC;QACpC,GAAG,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAa,EAAE,EAAE;YACrD,MAAM,IAAI,GAAsB;gBAC9B,IAAI,CAAC,KAAkB;oBACrB,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAA;gBAChC,CAAC;gBACD,OAAO,CAAC,OAAO;oBACb,EAAE,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,IAAqB,EAAE,EAAE;wBACzC,MAAM,GAAG,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;wBACnE,IAAI,CAAC;4BACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAgB,CAAA;4BAC7C,OAAO,CAAC,MAAM,CAAC,CAAA;wBACjB,CAAC;wBAAC,MAAM,CAAC;4BACP,2BAA2B;wBAC7B,CAAC;oBACH,CAAC,CAAC,CAAA;gBACJ,CAAC;gBACD,OAAO,CAAC,OAAO;oBACb,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;gBACzB,CAAC;gBACD,KAAK;oBACH,EAAE,CAAC,KAAK,EAAE,CAAA;gBACZ,CAAC;aACF,CAAA;YACD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;YAEjC,8EAA8E;YAC9E,KAAK,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAA;YACnD,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;gBACxB,EAAE,EAAE,GAAG,EAAE;gBACT,GAAG;gBACH,GAAG,EAAE,IAAI;gBACT,KAAK,EAAE,OAAO;gBACd,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE;aAC5B,CAAC,CAAA;QACJ,CAAC,CAAC,CAAA;IACJ,CAAC,CAAA;AACH,CAAC","sourcesContent":["import { WebSocketServer } from 'ws'\nimport type { WebSocket } from 'ws'\nimport type { IncomingMessage } from 'node:http'\nimport type { Duplex } from 'node:stream'\nimport type { WsPairingRegistry, PairingConnection } from './pairing-registry.js'\nimport type { TokenStore } from '../token-store.js'\nimport type { AuditSink } from '../audit.js'\nimport { verifyToken } from '../token.js'\nimport type { ClientFrame, ServerFrame } from '../../protocol.js'\n\nexport type UpgradeDeps = {\n  signingKey: string | Uint8Array\n  tokenStore: TokenStore\n  registry: WsPairingRegistry\n  auditSink: AuditSink\n  now?: () => number\n}\n\n/**\n * Returns a handler for `server.on('upgrade', ...)`. Validates the token\n * from the query string, attaches to the registry, wires frame/close\n * routing. Unauthorized paths/tokens get a bare HTTP error response on\n * the raw socket (per RFC 6455 the response must be sent before the\n * socket is torn down).\n *\n * Spec §10.2, §10.4.\n */\nexport function createWsUpgradeHandler(deps: UpgradeDeps) {\n  const wss = new WebSocketServer({ noServer: true })\n  const now = deps.now ?? (() => Date.now())\n\n  return (req: IncomingMessage, socket: Duplex, head: Buffer): void => {\n    // Path check\n    const url = new URL(req.url ?? '/', 'http://localhost')\n    if (url.pathname !== '/agent/ws') {\n      socket.write('HTTP/1.1 404 Not Found\\r\\n\\r\\n')\n      socket.destroy()\n      return\n    }\n\n    // Token — try query string first, then Authorization header\n    let token = url.searchParams.get('token')\n    if (!token) {\n      const auth = req.headers['authorization']\n      if (typeof auth === 'string' && auth.startsWith('Bearer ')) {\n        token = auth.slice('Bearer '.length)\n      }\n    }\n    if (!token) {\n      socket.write('HTTP/1.1 401 Unauthorized\\r\\n\\r\\n')\n      socket.destroy()\n      return\n    }\n\n    const verified = verifyToken(token, deps.signingKey)\n    if (verified.kind !== 'ok') {\n      socket.write('HTTP/1.1 401 Unauthorized\\r\\n\\r\\n')\n      socket.destroy()\n      return\n    }\n    const { tid } = verified.payload\n\n    // Perform upgrade, wire to registry\n    wss.handleUpgrade(req, socket, head, (ws: WebSocket) => {\n      const conn: PairingConnection = {\n        send(frame: ServerFrame) {\n          ws.send(JSON.stringify(frame))\n        },\n        onFrame(handler) {\n          ws.on('message', (data: Buffer | string) => {\n            const raw = typeof data === 'string' ? data : data.toString('utf8')\n            try {\n              const parsed = JSON.parse(raw) as ClientFrame\n              handler(parsed)\n            } catch {\n              // Ignore malformed frames.\n            }\n          })\n        },\n        onClose(handler) {\n          ws.on('close', handler)\n        },\n        close() {\n          ws.close()\n        },\n      }\n      deps.registry.register(tid, conn)\n\n      // Transition status: browser WS is now live, waiting for Claude's first call.\n      void deps.tokenStore.markAwaitingClaude(tid, now())\n      void deps.auditSink.write({\n        at: now(),\n        tid,\n        uid: null,\n        event: 'claim',\n        detail: { transport: 'ws' },\n      })\n    })\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@llui/agent",
+  "version": "0.0.29",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "ws": "^8.18.0",
+    "@llui/dom": "0.0.29",
+    "@llui/effects": "0.0.9"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.13"
+  },
+  "description": "LLui Agent — LAP server + browser client runtime for driving LLui apps from LLM clients",
+  "keywords": [
+    "llui",
+    "agent",
+    "llm",
+    "mcp",
+    "lap"
+  ],
+  "author": "Franco Ponticelli <franco.ponticelli@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fponticelli/llui.git",
+    "directory": "packages/agent"
+  },
+  "bugs": {
+    "url": "https://github.com/fponticelli/llui/issues"
+  },
+  "homepage": "https://github.com/fponticelli/llui/tree/main/packages/agent#readme",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
+}