@llui/agent 0.0.32 → 0.0.35

package/dist/client/effect-handler.js

@@ -1,132 +1,173 @@
+/**
+ * Top-level dispatcher. The switch is intentionally thin — each
+ * `case` delegates to a per-effect function below. Splitting was
+ * motivated by the previous 150-line monolith mixing HTTP, WS, and
+ * browser-only side effects in one switch; per-effect handlers are
+ * directly unit-testable and the dispatcher reads as a flat catalogue
+ * of supported effect types.
+ */
 export function createEffectHandler(host) {
     const doFetch = host.fetch ?? fetch.bind(globalThis);
     return async function handle(effect) {
         switch (effect.type) {
-            case 'AgentMintRequest': {
-                try {
-                    const res = await doFetch(effect.mintUrl, { method: 'POST', credentials: 'include' });
-                    if (!res.ok) {
-                        const detail = await safeText(res);
-                        host.send(host.wrapAgentConnect({
-                            type: 'MintFailed',
-                            error: { code: `http-${res.status}`, detail },
-                        }));
-                        return;
-                    }
-                    const body = (await res.json());
-                    host.send(host.wrapAgentConnect({
-                        type: 'MintSucceeded',
-                        token: body.token,
-                        tid: body.tid,
-                        lapUrl: body.lapUrl,
-                        wsUrl: body.wsUrl,
-                        expiresAt: body.expiresAt,
-                    }));
-                }
-                catch (e) {
-                    host.send(host.wrapAgentConnect({
-                        type: 'MintFailed',
-                        error: { code: 'network', detail: String(e) },
-                    }));
-                }
-                return;
-            }
-            case 'AgentOpenWS': {
-                host.openWs(effect.token, effect.wsUrl);
-                return;
-            }
-            case 'AgentCloseWS': {
-                host.closeWs();
-                return;
-            }
-            case 'AgentResumeCheck': {
-                // For v1 we call /agent/resume/list via the mint URL's origin; the mintUrl is a POST
-                // endpoint at `/agent/mint`, so we derive the origin and hit `/agent/resume/list`.
-                const origin = deriveOrigin(host);
-                if (!origin)
-                    return;
-                try {
-                    const res = await doFetch(`${origin}/agent/resume/list`, {
-                        method: 'POST',
-                        credentials: 'include',
-                        headers: { 'content-type': 'application/json' },
-                        body: JSON.stringify({ tids: effect.tids }),
-                    });
-                    if (!res.ok)
-                        return;
-                    const body = (await res.json());
-                    host.send(host.wrapAgentConnect({ type: 'ResumeListLoaded', sessions: body.sessions }));
-                }
-                catch {
-                    /* quiet failure; user can retry */
-                }
-                return;
-            }
-            case 'AgentResumeClaim': {
-                const origin = deriveOrigin(host);
-                if (!origin)
-                    return;
-                try {
-                    const res = await doFetch(`${origin}/agent/resume/claim`, {
-                        method: 'POST',
-                        credentials: 'include',
-                        headers: { 'content-type': 'application/json' },
-                        body: JSON.stringify({ tid: effect.tid }),
-                    });
-                    if (!res.ok)
-                        return;
-                    const body = (await res.json());
-                    host.openWs(body.token, body.wsUrl);
-                    host.send(host.wrapAgentConnect({ type: 'WsOpened' }));
-                }
-                catch {
-                    /* quiet */
-                }
-                return;
-            }
-            case 'AgentRevoke': {
-                const origin = deriveOrigin(host);
-                if (!origin)
-                    return;
-                try {
-                    await doFetch(`${origin}/agent/revoke`, {
-                        method: 'POST',
-                        credentials: 'include',
-                        headers: { 'content-type': 'application/json' },
-                        body: JSON.stringify({ tid: effect.tid }),
-                    });
-                }
-                catch {
-                    /* quiet */
-                }
-                return;
-            }
-            case 'AgentSessionsList': {
-                const origin = deriveOrigin(host);
-                if (!origin)
-                    return;
-                try {
-                    const res = await doFetch(`${origin}/agent/sessions`, {
-                        method: 'GET',
-                        credentials: 'include',
-                    });
-                    if (!res.ok)
-                        return;
-                    const body = (await res.json());
-                    host.send(host.wrapAgentConnect({ type: 'SessionsLoaded', sessions: body.sessions }));
-                }
-                catch {
-                    /* quiet */
-                }
-                return;
-            }
-            case 'AgentForwardMsg': {
-                host.forward(effect.payload);
-                return;
-            }
+            case 'AgentMintRequest':
+                return handleMintRequest(host, effect, doFetch);
+            case 'AgentOpenWS':
+                return handleOpenWs(host, effect);
+            case 'AgentCloseWS':
+                return handleCloseWs(host);
+            case 'AgentResumeCheck':
+                return handleResumeCheck(host, effect, doFetch);
+            case 'AgentResumeClaim':
+                return handleResumeClaim(host, effect, doFetch);
+            case 'AgentRevoke':
+                return handleRevoke(host, effect, doFetch);
+            case 'AgentSessionsList':
+                return handleSessionsList(host, doFetch);
+            case 'AgentForwardMsg':
+                return handleForwardMsg(host, effect);
+            case 'AgentClipboardWrite':
+                return handleClipboardWrite(effect);
         }
     };
 }
+// ── HTTP-bound handlers ─────────────────────────────────────────────
+async function handleMintRequest(host, effect, doFetch) {
+    // Derive a default `mintUrl` from `agentBasePath` so consumers can
+    // change the base path in one place (the effect handler) without
+    // also having to keep the `agentConnect` opts in sync. `agentBase`
+    // accepts both absolute paths and full URLs.
+    const base = agentBase(host);
+    if (!base)
+        return;
+    const mintUrl = effect.mintUrl ?? `${base}/mint`;
+    try {
+        const res = await doFetch(mintUrl, { method: 'POST', credentials: 'include' });
+        if (!res.ok) {
+            const detail = await safeText(res);
+            host.send(host.wrapAgentConnect({
+                type: 'MintFailed',
+                error: { code: `http-${res.status}`, detail },
+            }));
+            return;
+        }
+        const body = (await res.json());
+        host.send(host.wrapAgentConnect({
+            type: 'MintSucceeded',
+            token: body.token,
+            tid: body.tid,
+            lapUrl: body.lapUrl,
+            wsUrl: body.wsUrl,
+            expiresAt: body.expiresAt,
+        }));
+    }
+    catch (e) {
+        host.send(host.wrapAgentConnect({
+            type: 'MintFailed',
+            error: { code: 'network', detail: String(e) },
+        }));
+    }
+}
+async function handleResumeCheck(host, effect, doFetch) {
+    const base = agentBase(host);
+    if (!base)
+        return;
+    try {
+        const res = await doFetch(`${base}/resume/list`, {
+            method: 'POST',
+            credentials: 'include',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ tids: effect.tids }),
+        });
+        if (!res.ok)
+            return;
+        const body = (await res.json());
+        host.send(host.wrapAgentConnect({ type: 'ResumeListLoaded', sessions: body.sessions }));
+    }
+    catch {
+        /* quiet failure; user can retry */
+    }
+}
+async function handleResumeClaim(host, effect, doFetch) {
+    const base = agentBase(host);
+    if (!base)
+        return;
+    try {
+        const res = await doFetch(`${base}/resume/claim`, {
+            method: 'POST',
+            credentials: 'include',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ tid: effect.tid }),
+        });
+        if (!res.ok)
+            return;
+        const body = (await res.json());
+        host.openWs(body.token, body.wsUrl);
+        host.send(host.wrapAgentConnect({ type: 'WsOpened' }));
+    }
+    catch {
+        /* quiet */
+    }
+}
+async function handleRevoke(host, effect, doFetch) {
+    const base = agentBase(host);
+    if (!base)
+        return;
+    try {
+        await doFetch(`${base}/revoke`, {
+            method: 'POST',
+            credentials: 'include',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ tid: effect.tid }),
+        });
+    }
+    catch {
+        /* quiet */
+    }
+}
+async function handleSessionsList(host, doFetch) {
+    const base = agentBase(host);
+    if (!base)
+        return;
+    try {
+        const res = await doFetch(`${base}/sessions`, {
+            method: 'GET',
+            credentials: 'include',
+        });
+        if (!res.ok)
+            return;
+        const body = (await res.json());
+        host.send(host.wrapAgentConnect({ type: 'SessionsLoaded', sessions: body.sessions }));
+    }
+    catch {
+        /* quiet */
+    }
+}
+// ── WS-bound handlers ───────────────────────────────────────────────
+function handleOpenWs(host, effect) {
+    host.openWs(effect.token, effect.wsUrl);
+}
+function handleCloseWs(host) {
+    host.closeWs();
+}
+// ── Local handlers (no network) ─────────────────────────────────────
+function handleForwardMsg(host, effect) {
+    host.forward(effect.payload);
+}
+async function handleClipboardWrite(effect) {
+    // Browser-only — `navigator.clipboard` is undefined in Node/jsdom
+    // test environments. Silently no-op rather than throw, matching the
+    // rest of the agent effect handlers' failure-quiet pattern.
+    if (typeof navigator === 'undefined' || !('clipboard' in navigator))
+        return;
+    try {
+        await navigator.clipboard.writeText(effect.text);
+    }
+    catch {
+        /* quiet — clipboard permission denied or document not focused */
+    }
+}
+// ── Helpers ─────────────────────────────────────────────────────────
 async function safeText(res) {
     try {
         return await res.text();
@@ -135,12 +176,30 @@ async function safeText(res) {
         return '';
     }
 }
-function deriveOrigin(_host) {
-    // When running in the browser, `location.origin` is correct (the agent endpoints
-    // are same-origin with the app per spec §6.2). When not in a browser (tests),
-    // the test-side host can override by monkeypatching in its own effect handler.
+function deriveOrigin() {
+    // When running in the browser, `location.origin` is correct for
+    // same-origin agent endpoints. Tests override `host.fetch` and
+    // short-circuit before this is reached.
     if (typeof location !== 'undefined')
         return location.origin;
     return null;
 }
+const ABSOLUTE_URL_RE = /^https?:\/\//i;
+/**
+ * Resolve the absolute base URL for agent HTTP endpoints. Accepts both
+ * absolute paths (`/agent`) and full URLs (`https://api.example/agent`)
+ * — the absolute URL form lets consumers point at a cross-origin agent
+ * server without pre-composing every endpoint URL. Trailing slashes
+ * are normalized so callers can always concatenate `${base}/mint`.
+ */
+function agentBase(host) {
+    const raw = host.agentBasePath ?? '/agent';
+    const trimmed = raw.endsWith('/') ? raw.slice(0, -1) : raw;
+    if (ABSOLUTE_URL_RE.test(trimmed))
+        return trimmed;
+    const origin = deriveOrigin();
+    if (!origin)
+        return null;
+    return `${origin}${trimmed}`;
+}
 //# sourceMappingURL=effect-handler.js.map

package/dist/client/effect-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"effect-handler.js","sourceRoot":"","sources":["../../src/client/effect-handler.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AgentEffect } from './effects.js'\nimport type {\n  MintResponse,\n  ResumeListResponse,\n  ResumeClaimResponse,\n  SessionsResponse,\n} from '../protocol.js'\n\nexport type EffectHandlerHost = {\n  send(msg: unknown): void // root app send; wraps agent sub-msgs into the app Msg envelope\n  /** Wraps an agentConnect msg into an app-Msg. */\n  wrapAgentConnect(m: unknown): unknown\n  /** Called for AgentForwardMsg — the payload is re-dispatched via send. */\n  forward(payload: unknown): void\n  /** fetch for HTTP effects; override in tests. */\n  fetch?: typeof fetch\n  /** Called before opening WS / on WS lifecycle events. */\n  openWs(token: string, wsUrl: string): void\n  closeWs(): void\n}\n\nexport function createEffectHandler(host: EffectHandlerHost) {\n  const doFetch = host.fetch ?? fetch.bind(globalThis)\n\n  return async function handle(effect: AgentEffect): Promise<void> {\n    switch (effect.type) {\n      case 'AgentMintRequest': {\n        try {\n          const res = await doFetch(effect.mintUrl, { method: 'POST', credentials: 'include' })\n          if (!res.ok) {\n            const detail = await safeText(res)\n            host.send(\n              host.wrapAgentConnect({\n                type: 'MintFailed',\n                error: { code: `http-${res.status}`, detail },\n              }),\n            )\n            return\n          }\n          const body = (await res.json()) as MintResponse\n          host.send(\n            host.wrapAgentConnect({\n              type: 'MintSucceeded',\n              token: body.token,\n              tid: body.tid,\n              lapUrl: body.lapUrl,\n              wsUrl: body.wsUrl,\n              expiresAt: body.expiresAt,\n            }),\n          )\n        } catch (e) {\n          host.send(\n            host.wrapAgentConnect({\n              type: 'MintFailed',\n              error: { code: 'network', detail: String(e) },\n            }),\n          )\n        }\n        return\n      }\n      case 'AgentOpenWS': {\n        host.openWs(effect.token, effect.wsUrl)\n        return\n      }\n      case 'AgentCloseWS': {\n        host.closeWs()\n        return\n      }\n      case 'AgentResumeCheck': {\n        // For v1 we call /agent/resume/list via the mint URL's origin; the mintUrl is a POST\n        // endpoint at `/agent/mint`, so we derive the origin and hit `/agent/resume/list`.\n        const origin = deriveOrigin(host)\n        if (!origin) return\n        try {\n          const res = await doFetch(`${origin}/agent/resume/list`, {\n            method: 'POST',\n            credentials: 'include',\n            headers: { 'content-type': 'application/json' },\n            body: JSON.stringify({ tids: effect.tids }),\n          })\n          if (!res.ok) return\n          const body = (await res.json()) as ResumeListResponse\n          host.send(host.wrapAgentConnect({ type: 'ResumeListLoaded', sessions: body.sessions }))\n        } catch {\n          /* quiet failure; user can retry */\n        }\n        return\n      }\n      case 'AgentResumeClaim': {\n        const origin = deriveOrigin(host)\n        if (!origin) return\n        try {\n          const res = await doFetch(`${origin}/agent/resume/claim`, {\n            method: 'POST',\n            credentials: 'include',\n            headers: { 'content-type': 'application/json' },\n            body: JSON.stringify({ tid: effect.tid }),\n          })\n          if (!res.ok) return\n          const body = (await res.json()) as ResumeClaimResponse\n          host.openWs(body.token, body.wsUrl)\n          host.send(host.wrapAgentConnect({ type: 'WsOpened' }))\n        } catch {\n          /* quiet */\n        }\n        return\n      }\n      case 'AgentRevoke': {\n        const origin = deriveOrigin(host)\n        if (!origin) return\n        try {\n          await doFetch(`${origin}/agent/revoke`, {\n            method: 'POST',\n            credentials: 'include',\n            headers: { 'content-type': 'application/json' },\n            body: JSON.stringify({ tid: effect.tid }),\n          })\n        } catch {\n          /* quiet */\n        }\n        return\n      }\n      case 'AgentSessionsList': {\n        const origin = deriveOrigin(host)\n        if (!origin) return\n        try {\n          const res = await doFetch(`${origin}/agent/sessions`, {\n            method: 'GET',\n            credentials: 'include',\n          })\n          if (!res.ok) return\n          const body = (await res.json()) as SessionsResponse\n          host.send(host.wrapAgentConnect({ type: 'SessionsLoaded', sessions: body.sessions }))\n        } catch {\n          /* quiet */\n        }\n        return\n      }\n      case 'AgentForwardMsg': {\n        host.forward(effect.payload)\n        return\n      }\n    }\n  }\n}\n\nasync function safeText(res: Response): Promise<string> {\n  try {\n    return await res.text()\n  } catch {\n    return ''\n  }\n}\n\nfunction deriveOrigin(_host: EffectHandlerHost): string | null {\n  // When running in the browser, `location.origin` is correct (the agent endpoints\n  // are same-origin with the app per spec §6.2). When not in a browser (tests),\n  // the test-side host can override by monkeypatching in its own effect handler.\n  if (typeof location !== 'undefined') return location.origin\n  return null\n}\n"]}
+{"version":3,"file":"effect-handler.js","sourceRoot":"","sources":["../../src/client/effect-handler.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AgentEffect } from './effects.js'\nimport type {\n  MintResponse,\n  ResumeListResponse,\n  ResumeClaimResponse,\n  SessionsResponse,\n} from '../protocol.js'\n\nexport type EffectHandlerHost = {\n  send(msg: unknown): void // root app send; wraps agent sub-msgs into the app Msg envelope\n  /** Wraps an agentConnect msg into an app-Msg. */\n  wrapAgentConnect(m: unknown): unknown\n  /** Called for AgentForwardMsg — the payload is re-dispatched via send. */\n  forward(payload: unknown): void\n  /** fetch for HTTP effects; override in tests. */\n  fetch?: typeof fetch\n  /** Called before opening WS / on WS lifecycle events. */\n  openWs(token: string, wsUrl: string): void\n  closeWs(): void\n  /**\n   * Base path for agent HTTP endpoints. Default: `'/agent'` (matches\n   * the canonical paths in `@llui/vite-plugin`'s dev middleware and\n   * `@llui/agent/server/http/router.ts`).\n   *\n   * Override when the consumer ships `@cloudflare/vite-plugin` in\n   * dev — that plugin routes every non-`/cdn-cgi/*` path to the\n   * worker, shadowing canonical `/agent/*` URLs. The vite-plugin\n   * registers a parallel handler at `/cdn-cgi/agent/*`; pass\n   * `agentBasePath: '/cdn-cgi/agent'` here so the client hits that.\n   *\n   * Production deployments without cloudflare-vite leave this\n   * unset; the agent server's router serves the canonical paths.\n   */\n  agentBasePath?: string\n}\n\ntype Fetch = typeof fetch\n\n/**\n * Top-level dispatcher. The switch is intentionally thin — each\n * `case` delegates to a per-effect function below. Splitting was\n * motivated by the previous 150-line monolith mixing HTTP, WS, and\n * browser-only side effects in one switch; per-effect handlers are\n * directly unit-testable and the dispatcher reads as a flat catalogue\n * of supported effect types.\n */\nexport function createEffectHandler(host: EffectHandlerHost) {\n  const doFetch = host.fetch ?? fetch.bind(globalThis)\n\n  return async function handle(effect: AgentEffect): Promise<void> {\n    switch (effect.type) {\n      case 'AgentMintRequest':\n        return handleMintRequest(host, effect, doFetch)\n      case 'AgentOpenWS':\n        return handleOpenWs(host, effect)\n      case 'AgentCloseWS':\n        return handleCloseWs(host)\n      case 'AgentResumeCheck':\n        return handleResumeCheck(host, effect, doFetch)\n      case 'AgentResumeClaim':\n        return handleResumeClaim(host, effect, doFetch)\n      case 'AgentRevoke':\n        return handleRevoke(host, effect, doFetch)\n      case 'AgentSessionsList':\n        return handleSessionsList(host, doFetch)\n      case 'AgentForwardMsg':\n        return handleForwardMsg(host, effect)\n      case 'AgentClipboardWrite':\n        return handleClipboardWrite(effect)\n    }\n  }\n}\n\n// ── HTTP-bound handlers ─────────────────────────────────────────────\n\nasync function handleMintRequest(\n  host: EffectHandlerHost,\n  effect: Extract<AgentEffect, { type: 'AgentMintRequest' }>,\n  doFetch: Fetch,\n): Promise<void> {\n  // Derive a default `mintUrl` from `agentBasePath` so consumers can\n  // change the base path in one place (the effect handler) without\n  // also having to keep the `agentConnect` opts in sync. `agentBase`\n  // accepts both absolute paths and full URLs.\n  const base = agentBase(host)\n  if (!base) return\n  const mintUrl = effect.mintUrl ?? `${base}/mint`\n  try {\n    const res = await doFetch(mintUrl, { method: 'POST', credentials: 'include' })\n    if (!res.ok) {\n      const detail = await safeText(res)\n      host.send(\n        host.wrapAgentConnect({\n          type: 'MintFailed',\n          error: { code: `http-${res.status}`, detail },\n        }),\n      )\n      return\n    }\n    const body = (await res.json()) as MintResponse\n    host.send(\n      host.wrapAgentConnect({\n        type: 'MintSucceeded',\n        token: body.token,\n        tid: body.tid,\n        lapUrl: body.lapUrl,\n        wsUrl: body.wsUrl,\n        expiresAt: body.expiresAt,\n      }),\n    )\n  } catch (e) {\n    host.send(\n      host.wrapAgentConnect({\n        type: 'MintFailed',\n        error: { code: 'network', detail: String(e) },\n      }),\n    )\n  }\n}\n\nasync function handleResumeCheck(\n  host: EffectHandlerHost,\n  effect: Extract<AgentEffect, { type: 'AgentResumeCheck' }>,\n  doFetch: Fetch,\n): Promise<void> {\n  const base = agentBase(host)\n  if (!base) return\n  try {\n    const res = await doFetch(`${base}/resume/list`, {\n      method: 'POST',\n      credentials: 'include',\n      headers: { 'content-type': 'application/json' },\n      body: JSON.stringify({ tids: effect.tids }),\n    })\n    if (!res.ok) return\n    const body = (await res.json()) as ResumeListResponse\n    host.send(host.wrapAgentConnect({ type: 'ResumeListLoaded', sessions: body.sessions }))\n  } catch {\n    /* quiet failure; user can retry */\n  }\n}\n\nasync function handleResumeClaim(\n  host: EffectHandlerHost,\n  effect: Extract<AgentEffect, { type: 'AgentResumeClaim' }>,\n  doFetch: Fetch,\n): Promise<void> {\n  const base = agentBase(host)\n  if (!base) return\n  try {\n    const res = await doFetch(`${base}/resume/claim`, {\n      method: 'POST',\n      credentials: 'include',\n      headers: { 'content-type': 'application/json' },\n      body: JSON.stringify({ tid: effect.tid }),\n    })\n    if (!res.ok) return\n    const body = (await res.json()) as ResumeClaimResponse\n    host.openWs(body.token, body.wsUrl)\n    host.send(host.wrapAgentConnect({ type: 'WsOpened' }))\n  } catch {\n    /* quiet */\n  }\n}\n\nasync function handleRevoke(\n  host: EffectHandlerHost,\n  effect: Extract<AgentEffect, { type: 'AgentRevoke' }>,\n  doFetch: Fetch,\n): Promise<void> {\n  const base = agentBase(host)\n  if (!base) return\n  try {\n    await doFetch(`${base}/revoke`, {\n      method: 'POST',\n      credentials: 'include',\n      headers: { 'content-type': 'application/json' },\n      body: JSON.stringify({ tid: effect.tid }),\n    })\n  } catch {\n    /* quiet */\n  }\n}\n\nasync function handleSessionsList(host: EffectHandlerHost, doFetch: Fetch): Promise<void> {\n  const base = agentBase(host)\n  if (!base) return\n  try {\n    const res = await doFetch(`${base}/sessions`, {\n      method: 'GET',\n      credentials: 'include',\n    })\n    if (!res.ok) return\n    const body = (await res.json()) as SessionsResponse\n    host.send(host.wrapAgentConnect({ type: 'SessionsLoaded', sessions: body.sessions }))\n  } catch {\n    /* quiet */\n  }\n}\n\n// ── WS-bound handlers ───────────────────────────────────────────────\n\nfunction handleOpenWs(\n  host: EffectHandlerHost,\n  effect: Extract<AgentEffect, { type: 'AgentOpenWS' }>,\n): void {\n  host.openWs(effect.token, effect.wsUrl)\n}\n\nfunction handleCloseWs(host: EffectHandlerHost): void {\n  host.closeWs()\n}\n\n// ── Local handlers (no network) ─────────────────────────────────────\n\nfunction handleForwardMsg(\n  host: EffectHandlerHost,\n  effect: Extract<AgentEffect, { type: 'AgentForwardMsg' }>,\n): void {\n  host.forward(effect.payload)\n}\n\nasync function handleClipboardWrite(\n  effect: Extract<AgentEffect, { type: 'AgentClipboardWrite' }>,\n): Promise<void> {\n  // Browser-only — `navigator.clipboard` is undefined in Node/jsdom\n  // test environments. Silently no-op rather than throw, matching the\n  // rest of the agent effect handlers' failure-quiet pattern.\n  if (typeof navigator === 'undefined' || !('clipboard' in navigator)) return\n  try {\n    await navigator.clipboard.writeText(effect.text)\n  } catch {\n    /* quiet — clipboard permission denied or document not focused */\n  }\n}\n\n// ── Helpers ─────────────────────────────────────────────────────────\n\nasync function safeText(res: Response): Promise<string> {\n  try {\n    return await res.text()\n  } catch {\n    return ''\n  }\n}\n\nfunction deriveOrigin(): string | null {\n  // When running in the browser, `location.origin` is correct for\n  // same-origin agent endpoints. Tests override `host.fetch` and\n  // short-circuit before this is reached.\n  if (typeof location !== 'undefined') return location.origin\n  return null\n}\n\nconst ABSOLUTE_URL_RE = /^https?:\\/\\//i\n\n/**\n * Resolve the absolute base URL for agent HTTP endpoints. Accepts both\n * absolute paths (`/agent`) and full URLs (`https://api.example/agent`)\n * — the absolute URL form lets consumers point at a cross-origin agent\n * server without pre-composing every endpoint URL. Trailing slashes\n * are normalized so callers can always concatenate `${base}/mint`.\n */\nfunction agentBase(host: EffectHandlerHost): string | null {\n  const raw = host.agentBasePath ?? '/agent'\n  const trimmed = raw.endsWith('/') ? raw.slice(0, -1) : raw\n  if (ABSOLUTE_URL_RE.test(trimmed)) return trimmed\n  const origin = deriveOrigin()\n  if (!origin) return null\n  return `${origin}${trimmed}`\n}\n"]}

package/dist/client/effects.d.ts

@@ -1,7 +1,15 @@
 import type { AgentToken } from '../protocol.js';
-export type AgentEffect = {
+export type AgentEffect = 
+/**
+ * Mint a fresh agent token. `mintUrl` is optional — when omitted the
+ * effect handler derives it from `EffectHandlerHost.agentBasePath`
+ * (default `/agent`), producing `<agentBasePath>/mint`. Pass an
+ * explicit value when the mint endpoint lives outside the configured
+ * base path.
+ */
+{
     type: 'AgentMintRequest';
-    mintUrl: string;
+    mintUrl?: string;
 } | {
     type: 'AgentOpenWS';
     token: AgentToken;
@@ -22,6 +30,9 @@ export type AgentEffect = {
 } | {
     type: 'AgentForwardMsg';
     payload: unknown;
+} | {
+    type: 'AgentClipboardWrite';
+    text: string;
 };
 export type AgentEffectHandler = (effect: AgentEffect) => Promise<void>;
 //# sourceMappingURL=effects.d.ts.map

package/dist/client/effects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"effects.d.ts","sourceRoot":"","sources":["../../src/client/effects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAEhD,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAA;AAGjD,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA"}
+{"version":3,"file":"effects.d.ts","sourceRoot":"","sources":["../../src/client/effects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAEhD,MAAM,MAAM,WAAW;AACrB;;;;;;GAMG;AACD;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAK7C;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAGjD,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA"}

package/dist/client/effects.js.map

@@ -1 +1 @@
-{"version":3,"file":"effects.js","sourceRoot":"","sources":["../../src/client/effects.ts"],"names":[],"mappings":"","sourcesContent":["import type { AgentToken } from '../protocol.js'\n\nexport type AgentEffect =\n  | { type: 'AgentMintRequest'; mintUrl: string }\n  | { type: 'AgentOpenWS'; token: AgentToken; wsUrl: string }\n  | { type: 'AgentCloseWS' }\n  | { type: 'AgentResumeCheck'; tids: string[] }\n  | { type: 'AgentResumeClaim'; tid: string }\n  | { type: 'AgentRevoke'; tid: string }\n  | { type: 'AgentSessionsList' }\n  | { type: 'AgentForwardMsg'; payload: unknown }\n\n// Handler implementation lands in Plan 7 alongside the WS client.\nexport type AgentEffectHandler = (effect: AgentEffect) => Promise<void>\n"]}
+{"version":3,"file":"effects.js","sourceRoot":"","sources":["../../src/client/effects.ts"],"names":[],"mappings":"","sourcesContent":["import type { AgentToken } from '../protocol.js'\n\nexport type AgentEffect =\n  /**\n   * Mint a fresh agent token. `mintUrl` is optional — when omitted the\n   * effect handler derives it from `EffectHandlerHost.agentBasePath`\n   * (default `/agent`), producing `<agentBasePath>/mint`. Pass an\n   * explicit value when the mint endpoint lives outside the configured\n   * base path.\n   */\n  | { type: 'AgentMintRequest'; mintUrl?: string }\n  | { type: 'AgentOpenWS'; token: AgentToken; wsUrl: string }\n  | { type: 'AgentCloseWS' }\n  | { type: 'AgentResumeCheck'; tids: string[] }\n  | { type: 'AgentResumeClaim'; tid: string }\n  | { type: 'AgentRevoke'; tid: string }\n  | { type: 'AgentSessionsList' }\n  | { type: 'AgentForwardMsg'; payload: unknown }\n  // Handler reads `text` (no state lookup needed at handler time —\n  // update() resolved it from the current state.pendingToken). Lets\n  // the static-bag `connect()` shape avoid leaking state-reads into\n  // event handlers.\n  | { type: 'AgentClipboardWrite'; text: string }\n\n// Handler implementation lands in Plan 7 alongside the WS client.\nexport type AgentEffectHandler = (effect: AgentEffect) => Promise<void>\n"]}

package/dist/client/factory.d.ts

@@ -2,13 +2,44 @@ import type { AppHandle } from '@llui/dom';
 import type { AgentEffect } from './effects.js';
 import type { AgentConfirmState } from './agentConfirm.js';
 import type { AgentDocs, AgentContext, MessageAnnotations } from '../protocol.js';
+import { type CodecRegistry } from '../codecs.js';
+/**
+ * The shape the compiler emits as `__msgSchema`. Mirrors `MsgField`
+ * from `@llui/vite-plugin/src/msg-schema.ts`. Three coexisting forms:
+ *
+ *   1. Bare primitive: `'string' | 'number' | 'boolean' | 'unknown'`
+ *      and bare enum: `{enum: [...]}`. Compact form for unannotated
+ *      required fields.
+ *   2. Bare nested types: `{kind: 'object', shape}` for inline /
+ *      followed-via-typeIndex shapes; `{kind: 'array', element}` for
+ *      `T[]` / `readonly T[]` / `Array<T>`. The synthesizer recurses
+ *      to build copy-paste-ready nested examples.
+ *   3. Rich descriptor: wraps any of the above with `{optional?,
+ *      priority?, hint?}` carrying TS optionality and `@should` hints.
+ */
+export type MsgSchemaBareType = string | {
+    enum: string[];
+} | {
+    kind: 'object';
+    shape: Record<string, MsgSchemaField>;
+} | {
+    kind: 'array';
+    element: MsgSchemaBareType;
+};
+export type MsgSchemaField = MsgSchemaBareType | {
+    type: MsgSchemaBareType;
+    optional?: boolean;
+    priority?: 'should';
+    hint?: string;
+};
+export type MsgSchemaShape = {
+    discriminant: string;
+    variants: Record<string, Record<string, MsgSchemaField>>;
+};
 type ComponentMetadata = {
     __msgSchema?: unknown;
     __stateSchema?: unknown;
     __msgAnnotations?: Record<string, MessageAnnotations>;
-    __bindingDescriptors?: Array<{
-        variant: string;
-    }>;
     __schemaHash?: string;
     name: string;
     agentAffordances?: (state: unknown) => Array<{
@@ -36,6 +67,27 @@ export type CreateAgentClientOpts<State, Msg> = {
          */
         wrapLogMsg?: (m: unknown) => Msg;
     };
+    /**
+     * Codec registry for non-JSON-safe values (Date, Blob, Map, …)
+     * crossing the LAP boundary. Defaults to `makeDefaultCodecs()`
+     * which ships `iso-date` and `epoch-millis`. Provide a custom
+     * registry to register additional codecs (e.g. `base64-blob` for
+     * file uploads). See `@llui/agent/codecs` for the convention.
+     */
+    codecs?: CodecRegistry;
+    /**
+     * Base path for agent HTTP endpoints. Default: `'/agent'` (matches
+     * the canonical paths in `@llui/vite-plugin`'s dev middleware and
+     * `@llui/agent/server`). The mint URL, resume URLs, and revoke URL
+     * derive from this so consumers don't have to keep them in sync.
+     *
+     * Override when:
+     *   - **Cross-origin agent server**: pass the full base, e.g.
+     *     `'https://api.example.com/agent'` or `'http://localhost:8787/agent'`.
+     *   - **`@cloudflare/vite-plugin` in dev**: pass `'/cdn-cgi/agent'`
+     *     because cloudflare-vite shadows non-`/cdn-cgi/*` routes.
+     */
+    agentBasePath?: string;
 };
 export type AgentClient = {
     effectHandler: (effect: AgentEffect) => Promise<void>;

package/dist/client/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/client/factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EAEZ,kBAAkB,EAEnB,MAAM,gBAAgB,CAAA;AAIvB,KAAK,iBAAiB,GAAG;IACvB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;IACrD,oBAAoB,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACjD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAA;IACpF,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,YAAY,CAAA;CAChD,CAAA;AAED,MAAM,MAAM,qBAAqB,CAAC,KAAK,EAAE,GAAG,IAAI;IAC9C,MAAM,EAAE,SAAS,CAAA;IACjB,GAAG,EAAE,iBAAiB,CAAA;IACtB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,OAAO,GAAG,IAAI,CAAA;IAC3B,MAAM,EAAE;QACN,UAAU,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,OAAO,CAAA;QACjC,UAAU,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,iBAAiB,CAAA;QAC3C,cAAc,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,GAAG,CAAA;QACnC,cAAc,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,GAAG,CAAA;QACnC;;;;;WAKG;QACH,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,GAAG,CAAA;KACjC,CAAA;CACF,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,aAAa,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACrD,KAAK,IAAI,IAAI,CAAA;IACb,IAAI,IAAI,IAAI,CAAA;CACb,CAAA;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,GAAG,EAC1C,IAAI,EAAE,qBAAqB,CAAC,KAAK,EAAE,GAAG,CAAC,GACtC,WAAW,CAoJb"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/client/factory.ts"],"names":[],"mappings":"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"}

package/dist/client/factory.js

@@ -1,5 +1,6 @@
 import { attachWsClient } from './ws-client.js';
 import { createEffectHandler } from './effect-handler.js';
+import { makeDefaultCodecs, encodeForWire, decodeFromWire } from '../codecs.js';
 export function createAgentClient(opts) {
     let ws = null;
     let wsClient = null;
@@ -52,14 +53,34 @@ export function createAgentClient(opts) {
         onRejectionEvt = null;
         errorListenersInstalled = false;
     }
+    // Codec registry handles non-JSON-safe values (Date, etc.) crossing
+    // the LAP boundary. `getState` encodes outgoing snapshots; `send`
+    // decodes incoming agent messages before they hit the reducer. The
+    // tagged-value convention is documented in `@llui/agent/codecs`.
+    const codecs = opts.codecs ?? makeDefaultCodecs();
     const rpcHost = {
-        getState: () => opts.handle.getState(),
-        send: (m) => opts.handle.send(m),
+        getState: () => encodeForWire(opts.handle.getState(), codecs),
+        send: (m) => opts.handle.send(decodeFromWire(m, codecs)),
         flush: () => opts.handle.flush(),
         subscribe: (listener) => opts.handle.subscribe(() => listener()),
         getAndClearDrainErrors: () => drainErrors.splice(0, drainErrors.length),
         getMsgAnnotations: () => opts.def.__msgAnnotations ?? null,
-        getBindingDescriptors: () => opts.def.__bindingDescriptors ?? null,
+        // The compiler-injected message schema. Used by `list_actions` to
+        // synthesize payload examples for `@agentOnly` variants that have
+        // no live UI binding — the agent should still see them as
+        // affordances even though no human can click them.
+        getMsgSchema: () => opts.def.__msgSchema ?? null,
+        // Run the reducer in isolation for `would_dispatch`. Wraps the
+        // AppHandle's same-named method so the host doesn't need a direct
+        // reference to the live ComponentInstance.
+        runReducer: (msg) => opts.handle.runReducer(msg),
+        // Live binding descriptors: read from the runtime registry that
+        // tracks which Msg variants are dispatchable from currently-mounted
+        // event handlers. Empty array when the app wasn't compiled with
+        // agent metadata (no tagger pass) or has no view bindings yet —
+        // both produce the same "no live affordances" signal at the agent
+        // layer.
+        getBindingDescriptors: () => opts.handle.getBindingDescriptors(),
         getAgentAffordances: () => opts.def.agentAffordances ?? null,
         getAgentContext: () => opts.def.agentContext ?? null,
         getRootElement: () => opts.rootElement,
@@ -83,6 +104,7 @@ export function createAgentClient(opts) {
         send: (m) => opts.handle.send(m),
         wrapAgentConnect: (m) => opts.slices.wrapConnectMsg(m),
         forward: (payload) => opts.handle.send(payload),
+        agentBasePath: opts.agentBasePath,
         openWs: (token, wsUrl) => {
             if (ws)
                 ws.close();
@@ -120,7 +142,7 @@ export function createAgentClient(opts) {
                 continue;
             resolvedConfirms.add(entry.id);
             if (entry.status === 'approved') {
-                wsClient?.resolveConfirm(entry.id, 'confirmed', opts.handle.getState());
+                wsClient?.resolveConfirm(entry.id, 'confirmed', encodeForWire(opts.handle.getState(), codecs));
             }
             else if (entry.status === 'rejected') {
                 wsClient?.resolveConfirm(entry.id, 'user-cancelled');
@@ -134,7 +156,10 @@ export function createAgentClient(opts) {
                 confirmPollTimer = setInterval(pollConfirms, 200);
             if (!stateSubscription) {
                 stateSubscription = opts.handle.subscribe((state) => {
-                    wsClient?.emitStateUpdate('/', state);
+                    // Same codec convention as `getState`: outgoing snapshots
+                    // pass through the encoder so non-JSON-safe values (Date,
+                    // etc.) become tagged-wire form.
+                    wsClient?.emitStateUpdate('/', encodeForWire(state, codecs));
                 });
             }
             installErrorListeners();