@llui/agent 0.0.31 → 0.0.34

package/dist/client/factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/client/factory.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AppHandle } from '@llui/dom'\nimport type { AgentEffect } from './effects.js'\nimport type { AgentConfirmState } from './agentConfirm.js'\nimport type {\n  AgentDocs,\n  AgentContext,\n  LapDrainMeta,\n  MessageAnnotations,\n  MessageSchemaEntry,\n} from '../protocol.js'\nimport { attachWsClient, type WsLike, type RpcHosts } from './ws-client.js'\nimport { createEffectHandler } from './effect-handler.js'\n\ntype ComponentMetadata = {\n  __msgSchema?: unknown\n  __stateSchema?: unknown\n  __msgAnnotations?: Record<string, MessageAnnotations>\n  __bindingDescriptors?: Array<{ variant: string }>\n  __schemaHash?: string\n  name: string\n  agentAffordances?: (state: unknown) => Array<{ type: string; [k: string]: unknown }>\n  agentDocs?: AgentDocs\n  agentContext?: (state: unknown) => AgentContext\n}\n\nexport type CreateAgentClientOpts<State, Msg> = {\n  handle: AppHandle\n  def: ComponentMetadata\n  appVersion?: string\n  rootElement: Element | null\n  slices: {\n    getConnect: (s: State) => unknown\n    getConfirm: (s: State) => AgentConfirmState\n    wrapConnectMsg: (m: unknown) => Msg\n    wrapConfirmMsg: (m: unknown) => Msg\n    /**\n     * Optional: wrap an agentLog msg so the client-side activity feed\n     * mirrors what Claude is doing. If omitted, outbound log-append\n     * frames still go to the server, but the local agent.log slice\n     * stays empty (the UI won't show activity).\n     */\n    wrapLogMsg?: (m: unknown) => Msg\n  }\n}\n\nexport type AgentClient = {\n  effectHandler: (effect: AgentEffect) => Promise<void>\n  start(): void\n  stop(): void\n}\n\nexport function createAgentClient<State, Msg>(\n  opts: CreateAgentClientOpts<State, Msg>,\n): AgentClient {\n  let ws: WebSocket | null = null\n  let wsClient: ReturnType<typeof attachWsClient> | null = null\n  let confirmPollTimer: ReturnType<typeof setInterval> | null = null\n  let stateSubscription: (() => void) | null = null\n  const resolvedConfirms = new Set<string>()\n\n  // Drain-error buffer: populated by persistent `window.error` and\n  // `window.unhandledrejection` listeners installed on `start()`. The\n  // send-message drain loop consumes and clears it per call so the\n  // envelope surfaces only errors that fired during that window.\n  const drainErrors: LapDrainMeta['errors'] = []\n  let errorListenersInstalled = false\n  let onErrorEvt: ((e: ErrorEvent) => void) | null = null\n  let onRejectionEvt: ((e: PromiseRejectionEvent) => void) | null = null\n\n  function installErrorListeners(): void {\n    if (errorListenersInstalled) return\n    if (typeof window === 'undefined') return\n    onErrorEvt = (e: ErrorEvent) => {\n      drainErrors.push({\n        kind: 'error',\n        message: e.message ?? String(e.error ?? 'unknown error'),\n        stack: e.error instanceof Error ? e.error.stack : undefined,\n      })\n    }\n    onRejectionEvt = (e: PromiseRejectionEvent) => {\n      const r = e.reason\n      const message = r instanceof Error ? r.message : typeof r === 'string' ? r : safeStringify(r)\n      drainErrors.push({\n        kind: 'unhandledrejection',\n        message,\n        stack: r instanceof Error ? r.stack : undefined,\n      })\n    }\n    window.addEventListener('error', onErrorEvt)\n    window.addEventListener('unhandledrejection', onRejectionEvt)\n    errorListenersInstalled = true\n  }\n\n  function removeErrorListeners(): void {\n    if (!errorListenersInstalled) return\n    if (typeof window === 'undefined') return\n    if (onErrorEvt) window.removeEventListener('error', onErrorEvt)\n    if (onRejectionEvt) window.removeEventListener('unhandledrejection', onRejectionEvt)\n    onErrorEvt = null\n    onRejectionEvt = null\n    errorListenersInstalled = false\n  }\n\n  const rpcHost: RpcHosts = {\n    getState: () => opts.handle.getState(),\n    send: (m) => opts.handle.send(m),\n    flush: () => opts.handle.flush(),\n    subscribe: (listener) => opts.handle.subscribe(() => listener()),\n    getAndClearDrainErrors: () => drainErrors.splice(0, drainErrors.length),\n    getMsgAnnotations: () => opts.def.__msgAnnotations ?? null,\n    getBindingDescriptors: () => opts.def.__bindingDescriptors ?? null,\n    getAgentAffordances: () => opts.def.agentAffordances ?? null,\n    getAgentContext: () => opts.def.agentContext ?? null,\n    getRootElement: () => opts.rootElement,\n    proposeConfirm: (entry) => {\n      opts.handle.send(opts.slices.wrapConfirmMsg({ type: 'Propose', entry }))\n    },\n  }\n\n  const helloBuilder = () => ({\n    t: 'hello' as const,\n    appName: opts.def.name,\n    appVersion: opts.appVersion ?? '0.0.0',\n    msgSchema: (opts.def.__msgSchema ?? {}) as Record<string, MessageSchemaEntry>,\n    stateSchema: (opts.def.__stateSchema ?? {}) as object,\n    affordancesSample: opts.def.agentAffordances\n      ? opts.def.agentAffordances(opts.handle.getState())\n      : [],\n    docs: opts.def.agentDocs ?? null,\n    schemaHash: opts.def.__schemaHash ?? '',\n  })\n\n  const effectHandler = createEffectHandler({\n    send: (m) => opts.handle.send(m),\n    wrapAgentConnect: (m) => opts.slices.wrapConnectMsg(m),\n    forward: (payload) => opts.handle.send(payload),\n    openWs: (token, wsUrl) => {\n      if (ws) ws.close()\n      ws = new WebSocket(`${wsUrl}?token=${encodeURIComponent(token)}`)\n      wsClient = attachWsClient(ws as unknown as WsLike, rpcHost, helloBuilder, {\n        onActivated: () => {\n          opts.handle.send(opts.slices.wrapConnectMsg({ type: 'ActivatedByClaude' }))\n        },\n        onLogEntry: opts.slices.wrapLogMsg\n          ? (entry) => {\n              opts.handle.send(opts.slices.wrapLogMsg!({ type: 'Append', entry }))\n            }\n          : undefined,\n      })\n      ws.addEventListener('open', () => {\n        opts.handle.send(opts.slices.wrapConnectMsg({ type: 'WsOpened' }))\n      })\n      ws.addEventListener('close', () => {\n        opts.handle.send(opts.slices.wrapConnectMsg({ type: 'WsClosed' }))\n      })\n    },\n    closeWs: () => {\n      wsClient?.close()\n      ws = null\n      wsClient = null\n    },\n  })\n\n  const pollConfirms = () => {\n    const state = opts.handle.getState() as State\n    const confirm = opts.slices.getConfirm(state)\n    for (const entry of confirm.pending) {\n      if (entry.status === 'pending') continue\n      if (resolvedConfirms.has(entry.id)) continue\n      resolvedConfirms.add(entry.id)\n      if (entry.status === 'approved') {\n        wsClient?.resolveConfirm(entry.id, 'confirmed', opts.handle.getState())\n      } else if (entry.status === 'rejected') {\n        wsClient?.resolveConfirm(entry.id, 'user-cancelled')\n      }\n    }\n  }\n\n  return {\n    effectHandler,\n    start() {\n      if (!confirmPollTimer) confirmPollTimer = setInterval(pollConfirms, 200)\n      if (!stateSubscription) {\n        stateSubscription = opts.handle.subscribe((state) => {\n          wsClient?.emitStateUpdate('/', state)\n        })\n      }\n      installErrorListeners()\n    },\n    stop() {\n      if (confirmPollTimer) clearInterval(confirmPollTimer)\n      confirmPollTimer = null\n      if (stateSubscription) {\n        stateSubscription()\n        stateSubscription = null\n      }\n      removeErrorListeners()\n      drainErrors.length = 0\n      wsClient?.close()\n    },\n  }\n}\n\nfunction safeStringify(v: unknown): string {\n  try {\n    return JSON.stringify(v)\n  } catch {\n    return String(v)\n  }\n}\n"]}
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/client/factory.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AppHandle } from '@llui/dom'\nimport type { AgentEffect } from './effects.js'\nimport type { AgentConfirmState } from './agentConfirm.js'\nimport type {\n  AgentDocs,\n  AgentContext,\n  LapDrainMeta,\n  MessageAnnotations,\n  MessageSchemaEntry,\n} from '../protocol.js'\nimport { attachWsClient, type WsLike, type RpcHosts } from './ws-client.js'\nimport { createEffectHandler } from './effect-handler.js'\nimport { makeDefaultCodecs, encodeForWire, decodeFromWire, type CodecRegistry } from '../codecs.js'\n\n/**\n * The shape the compiler emits as `__msgSchema`. Mirrors `MsgField`\n * from `@llui/vite-plugin/src/msg-schema.ts`. Three coexisting forms:\n *\n *   1. Bare primitive: `'string' | 'number' | 'boolean' | 'unknown'`\n *      and bare enum: `{enum: [...]}`. Compact form for unannotated\n *      required fields.\n *   2. Bare nested types: `{kind: 'object', shape}` for inline /\n *      followed-via-typeIndex shapes; `{kind: 'array', element}` for\n *      `T[]` / `readonly T[]` / `Array<T>`. The synthesizer recurses\n *      to build copy-paste-ready nested examples.\n *   3. Rich descriptor: wraps any of the above with `{optional?,\n *      priority?, hint?}` carrying TS optionality and `@should` hints.\n */\nexport type MsgSchemaBareType =\n  | string\n  | { enum: string[] }\n  | { kind: 'object'; shape: Record<string, MsgSchemaField> }\n  | { kind: 'array'; element: MsgSchemaBareType }\n\nexport type MsgSchemaField =\n  | MsgSchemaBareType\n  | {\n      type: MsgSchemaBareType\n      optional?: boolean\n      priority?: 'should'\n      hint?: string\n    }\n\nexport type MsgSchemaShape = {\n  discriminant: string\n  variants: Record<string, Record<string, MsgSchemaField>>\n}\n\ntype ComponentMetadata = {\n  __msgSchema?: unknown\n  __stateSchema?: unknown\n  __msgAnnotations?: Record<string, MessageAnnotations>\n  __schemaHash?: string\n  name: string\n  agentAffordances?: (state: unknown) => Array<{ type: string; [k: string]: unknown }>\n  agentDocs?: AgentDocs\n  agentContext?: (state: unknown) => AgentContext\n}\n\nexport type CreateAgentClientOpts<State, Msg> = {\n  handle: AppHandle\n  def: ComponentMetadata\n  appVersion?: string\n  rootElement: Element | null\n  slices: {\n    getConnect: (s: State) => unknown\n    getConfirm: (s: State) => AgentConfirmState\n    wrapConnectMsg: (m: unknown) => Msg\n    wrapConfirmMsg: (m: unknown) => Msg\n    /**\n     * Optional: wrap an agentLog msg so the client-side activity feed\n     * mirrors what Claude is doing. If omitted, outbound log-append\n     * frames still go to the server, but the local agent.log slice\n     * stays empty (the UI won't show activity).\n     */\n    wrapLogMsg?: (m: unknown) => Msg\n  }\n  /**\n   * Codec registry for non-JSON-safe values (Date, Blob, Map, …)\n   * crossing the LAP boundary. Defaults to `makeDefaultCodecs()`\n   * which ships `iso-date` and `epoch-millis`. Provide a custom\n   * registry to register additional codecs (e.g. `base64-blob` for\n   * file uploads). See `@llui/agent/codecs` for the convention.\n   */\n  codecs?: CodecRegistry\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`). The mint URL, resume URLs, and revoke URL\n   * derive from this so consumers don't have to keep them in sync.\n   *\n   * Override when:\n   *   - **Cross-origin agent server**: pass the full base, e.g.\n   *     `'https://api.example.com/agent'` or `'http://localhost:8787/agent'`.\n   *   - **`@cloudflare/vite-plugin` in dev**: pass `'/cdn-cgi/agent'`\n   *     because cloudflare-vite shadows non-`/cdn-cgi/*` routes.\n   */\n  agentBasePath?: string\n}\n\nexport type AgentClient = {\n  effectHandler: (effect: AgentEffect) => Promise<void>\n  start(): void\n  stop(): void\n}\n\nexport function createAgentClient<State, Msg>(\n  opts: CreateAgentClientOpts<State, Msg>,\n): AgentClient {\n  let ws: WebSocket | null = null\n  let wsClient: ReturnType<typeof attachWsClient> | null = null\n  let confirmPollTimer: ReturnType<typeof setInterval> | null = null\n  let stateSubscription: (() => void) | null = null\n  const resolvedConfirms = new Set<string>()\n\n  // Drain-error buffer: populated by persistent `window.error` and\n  // `window.unhandledrejection` listeners installed on `start()`. The\n  // send-message drain loop consumes and clears it per call so the\n  // envelope surfaces only errors that fired during that window.\n  const drainErrors: LapDrainMeta['errors'] = []\n  let errorListenersInstalled = false\n  let onErrorEvt: ((e: ErrorEvent) => void) | null = null\n  let onRejectionEvt: ((e: PromiseRejectionEvent) => void) | null = null\n\n  function installErrorListeners(): void {\n    if (errorListenersInstalled) return\n    if (typeof window === 'undefined') return\n    onErrorEvt = (e: ErrorEvent) => {\n      drainErrors.push({\n        kind: 'error',\n        message: e.message ?? String(e.error ?? 'unknown error'),\n        stack: e.error instanceof Error ? e.error.stack : undefined,\n      })\n    }\n    onRejectionEvt = (e: PromiseRejectionEvent) => {\n      const r = e.reason\n      const message = r instanceof Error ? r.message : typeof r === 'string' ? r : safeStringify(r)\n      drainErrors.push({\n        kind: 'unhandledrejection',\n        message,\n        stack: r instanceof Error ? r.stack : undefined,\n      })\n    }\n    window.addEventListener('error', onErrorEvt)\n    window.addEventListener('unhandledrejection', onRejectionEvt)\n    errorListenersInstalled = true\n  }\n\n  function removeErrorListeners(): void {\n    if (!errorListenersInstalled) return\n    if (typeof window === 'undefined') return\n    if (onErrorEvt) window.removeEventListener('error', onErrorEvt)\n    if (onRejectionEvt) window.removeEventListener('unhandledrejection', onRejectionEvt)\n    onErrorEvt = null\n    onRejectionEvt = null\n    errorListenersInstalled = false\n  }\n\n  // Codec registry handles non-JSON-safe values (Date, etc.) crossing\n  // the LAP boundary. `getState` encodes outgoing snapshots; `send`\n  // decodes incoming agent messages before they hit the reducer. The\n  // tagged-value convention is documented in `@llui/agent/codecs`.\n  const codecs = opts.codecs ?? makeDefaultCodecs()\n\n  const rpcHost: RpcHosts = {\n    getState: () => encodeForWire(opts.handle.getState(), codecs),\n    send: (m) => opts.handle.send(decodeFromWire(m, codecs)),\n    flush: () => opts.handle.flush(),\n    subscribe: (listener) => opts.handle.subscribe(() => listener()),\n    getAndClearDrainErrors: () => drainErrors.splice(0, drainErrors.length),\n    getMsgAnnotations: () => opts.def.__msgAnnotations ?? null,\n    // The compiler-injected message schema. Used by `list_actions` to\n    // synthesize payload examples for `@agentOnly` variants that have\n    // no live UI binding — the agent should still see them as\n    // affordances even though no human can click them.\n    getMsgSchema: () => (opts.def.__msgSchema as MsgSchemaShape | undefined) ?? null,\n    // Run the reducer in isolation for `would_dispatch`. Wraps the\n    // AppHandle's same-named method so the host doesn't need a direct\n    // reference to the live ComponentInstance.\n    runReducer: (msg) => opts.handle.runReducer(msg),\n    // Live binding descriptors: read from the runtime registry that\n    // tracks which Msg variants are dispatchable from currently-mounted\n    // event handlers. Empty array when the app wasn't compiled with\n    // agent metadata (no tagger pass) or has no view bindings yet —\n    // both produce the same \"no live affordances\" signal at the agent\n    // layer.\n    getBindingDescriptors: () => opts.handle.getBindingDescriptors(),\n    getAgentAffordances: () => opts.def.agentAffordances ?? null,\n    getAgentContext: () => opts.def.agentContext ?? null,\n    getRootElement: () => opts.rootElement,\n    proposeConfirm: (entry) => {\n      opts.handle.send(opts.slices.wrapConfirmMsg({ type: 'Propose', entry }))\n    },\n  }\n\n  const helloBuilder = () => ({\n    t: 'hello' as const,\n    appName: opts.def.name,\n    appVersion: opts.appVersion ?? '0.0.0',\n    msgSchema: (opts.def.__msgSchema ?? {}) as Record<string, MessageSchemaEntry>,\n    stateSchema: (opts.def.__stateSchema ?? {}) as object,\n    affordancesSample: opts.def.agentAffordances\n      ? opts.def.agentAffordances(opts.handle.getState())\n      : [],\n    docs: opts.def.agentDocs ?? null,\n    schemaHash: opts.def.__schemaHash ?? '',\n  })\n\n  const effectHandler = createEffectHandler({\n    send: (m) => opts.handle.send(m),\n    wrapAgentConnect: (m) => opts.slices.wrapConnectMsg(m),\n    forward: (payload) => opts.handle.send(payload),\n    agentBasePath: opts.agentBasePath,\n    openWs: (token, wsUrl) => {\n      if (ws) ws.close()\n      ws = new WebSocket(`${wsUrl}?token=${encodeURIComponent(token)}`)\n      wsClient = attachWsClient(ws as unknown as WsLike, rpcHost, helloBuilder, {\n        onActivated: () => {\n          opts.handle.send(opts.slices.wrapConnectMsg({ type: 'ActivatedByClaude' }))\n        },\n        onLogEntry: opts.slices.wrapLogMsg\n          ? (entry) => {\n              opts.handle.send(opts.slices.wrapLogMsg!({ type: 'Append', entry }))\n            }\n          : undefined,\n      })\n      ws.addEventListener('open', () => {\n        opts.handle.send(opts.slices.wrapConnectMsg({ type: 'WsOpened' }))\n      })\n      ws.addEventListener('close', () => {\n        opts.handle.send(opts.slices.wrapConnectMsg({ type: 'WsClosed' }))\n      })\n    },\n    closeWs: () => {\n      wsClient?.close()\n      ws = null\n      wsClient = null\n    },\n  })\n\n  const pollConfirms = () => {\n    const state = opts.handle.getState() as State\n    const confirm = opts.slices.getConfirm(state)\n    for (const entry of confirm.pending) {\n      if (entry.status === 'pending') continue\n      if (resolvedConfirms.has(entry.id)) continue\n      resolvedConfirms.add(entry.id)\n      if (entry.status === 'approved') {\n        wsClient?.resolveConfirm(\n          entry.id,\n          'confirmed',\n          encodeForWire(opts.handle.getState(), codecs),\n        )\n      } else if (entry.status === 'rejected') {\n        wsClient?.resolveConfirm(entry.id, 'user-cancelled')\n      }\n    }\n  }\n\n  return {\n    effectHandler,\n    start() {\n      if (!confirmPollTimer) confirmPollTimer = setInterval(pollConfirms, 200)\n      if (!stateSubscription) {\n        stateSubscription = opts.handle.subscribe((state) => {\n          // Same codec convention as `getState`: outgoing snapshots\n          // pass through the encoder so non-JSON-safe values (Date,\n          // etc.) become tagged-wire form.\n          wsClient?.emitStateUpdate('/', encodeForWire(state, codecs))\n        })\n      }\n      installErrorListeners()\n    },\n    stop() {\n      if (confirmPollTimer) clearInterval(confirmPollTimer)\n      confirmPollTimer = null\n      if (stateSubscription) {\n        stateSubscription()\n        stateSubscription = null\n      }\n      removeErrorListeners()\n      drainErrors.length = 0\n      wsClient?.close()\n    },\n  }\n}\n\nfunction safeStringify(v: unknown): string {\n  try {\n    return JSON.stringify(v)\n  } catch {\n    return String(v)\n  }\n}\n"]}

package/dist/client/rpc/describe-visible-content.d.ts

@@ -1,22 +1,35 @@
-import type { OutlineNode } from '../../protocol.js';
+import type { MessageAnnotations, OutlineNode } from '../../protocol.js';
 export type DescribeVisibleArgs = Record<string, never>;
 export type DescribeVisibleResult = {
     outline: OutlineNode[];
+    /**
+     * `'data-agent'` when the outline was scoped to author-tagged zones.
+     * `'fallback'` when the app has no `data-agent` attributes and the
+     * walker fell back to a generic semantic-element pass over the root.
+     * `'truncated'` when the fallback outline hit the node-count cap and
+     * stopped early; the caller can ask follow-up questions through
+     * `query_dom` or by inspecting state directly.
+     */
+    source: 'data-agent' | 'fallback' | 'truncated';
 };
 export type DescribeVisibleHost = {
     getRootElement(): Element | null;
     getBindingDescriptors(): Array<{
         variant: string;
     }> | null;
-    getMsgAnnotations(): Record<string, {
-        intent: string | null;
-        humanOnly: boolean;
-    }> | null;
+    getMsgAnnotations(): Record<string, MessageAnnotations> | null;
 };
 /**
  * Walk data-agent-tagged subtrees and produce a structured outline.
  * Buttons cross-reference __bindingDescriptors so Claude can tie
  * visible text to variant names.
+ *
+ * If the app has no `data-agent` tags, fall back to a depth-limited
+ * walk of the entire root element. This makes the tool useful for apps
+ * that haven't (yet) tagged their views — typical first-pass dogfood
+ * targets — instead of returning an empty outline that conveys
+ * nothing. The fallback path sets `source: 'fallback'` so the caller
+ * can tell the outline is best-effort.
  */
 export declare function handleDescribeVisibleContent(host: DescribeVisibleHost): DescribeVisibleResult;
 //# sourceMappingURL=describe-visible-content.d.ts.map

package/dist/client/rpc/describe-visible-content.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe-visible-content.d.ts","sourceRoot":"","sources":["../../../src/client/rpc/describe-visible-content.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;AACvD,MAAM,MAAM,qBAAqB,GAAG;IAAE,OAAO,EAAE,WAAW,EAAE,CAAA;CAAE,CAAA;AAE9D,MAAM,MAAM,mBAAmB,GAAG;IAChC,cAAc,IAAI,OAAO,GAAG,IAAI,CAAA;IAChC,qBAAqB,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI,CAAA;IAC1D,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC,GAAG,IAAI,CAAA;CAC1F,CAAA;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,mBAAmB,GAAG,qBAAqB,CAa7F"}
+{"version":3,"file":"describe-visible-content.d.ts","sourceRoot":"","sources":["../../../src/client/rpc/describe-visible-content.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAExE,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;AACvD,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,WAAW,EAAE,CAAA;IACtB;;;;;;;OAOG;IACH,MAAM,EAAE,YAAY,GAAG,UAAU,GAAG,WAAW,CAAA;CAChD,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,cAAc,IAAI,OAAO,GAAG,IAAI,CAAA;IAChC,qBAAqB,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI,CAAA;IAC1D,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,IAAI,CAAA;CAC/D,CAAA;AAcD;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,mBAAmB,GAAG,qBAAqB,CAqB7F"}

package/dist/client/rpc/describe-visible-content.js

@@ -1,20 +1,46 @@
+/**
+ * Hard caps for the fallback walk. The author-tagged path doesn't need
+ * caps — by definition the author chose what to expose. The fallback is
+ * walking arbitrary DOM, so it has to bound the work.
+ *
+ * 200 nodes covers ~3–5 visible screens of typical app UI; depth 8 is
+ * deep enough for nested content trees but stops us from descending
+ * into giant virtualised lists or syntax-highlighted code blocks.
+ */
+const FALLBACK_MAX_NODES = 200;
+const FALLBACK_MAX_DEPTH = 8;
 /**
  * Walk data-agent-tagged subtrees and produce a structured outline.
  * Buttons cross-reference __bindingDescriptors so Claude can tie
  * visible text to variant names.
+ *
+ * If the app has no `data-agent` tags, fall back to a depth-limited
+ * walk of the entire root element. This makes the tool useful for apps
+ * that haven't (yet) tagged their views — typical first-pass dogfood
+ * targets — instead of returning an empty outline that conveys
+ * nothing. The fallback path sets `source: 'fallback'` so the caller
+ * can tell the outline is best-effort.
  */
 export function handleDescribeVisibleContent(host) {
     const root = host.getRootElement();
     if (!root)
-        return { outline: [] };
-    const out = [];
+        return { outline: [], source: 'data-agent' };
     const allZones = Array.from(root.querySelectorAll('[data-agent]'));
-    // Only walk top-level zones; skip zones that are descendants of other zones
-    const topLevel = allZones.filter((zone) => !allZones.some((other) => other !== zone && other.contains(zone)));
-    for (const zone of topLevel) {
-        walk(zone, out);
+    if (allZones.length > 0) {
+        const out = [];
+        // Only walk top-level zones; skip zones that are descendants of other zones
+        const topLevel = allZones.filter((zone) => !allZones.some((other) => other !== zone && other.contains(zone)));
+        for (const zone of topLevel) {
+            walk(zone, out);
+        }
+        return { outline: out, source: 'data-agent' };
     }
-    return { outline: out };
+    // Fallback: walk the entire root with caps. Useful for apps without
+    // any data-agent annotations — at minimum the agent gets headings,
+    // buttons, links, lists, and visible text it can use to orient.
+    const out = [];
+    const truncated = walkFallback(root, out, 0);
+    return { outline: out, source: truncated ? 'truncated' : 'fallback' };
 }
 function walk(el, out) {
     const tag = el.tagName.toLowerCase();
@@ -63,4 +89,83 @@ function walk(el, out) {
         walk(child, out);
     }
 }
+/**
+ * Depth- and count-limited walk for the fallback path. Returns true
+ * iff the cap was hit (at least one element was skipped). Same node
+ * vocabulary as `walk` but prunes more aggressively:
+ *
+ *  - `<a>` without `href`, `<button>` without text — skipped (often
+ *    icon-only chrome that adds noise without helping the agent).
+ *  - Nested wrapper divs without semantic content — descended into
+ *    but not emitted.
+ *  - Standalone text nodes — only emitted when the parent has no
+ *    semantic children (preserves the existing `walk` heuristic).
+ */
+function walkFallback(el, out, depth) {
+    if (out.length >= FALLBACK_MAX_NODES)
+        return true;
+    if (depth > FALLBACK_MAX_DEPTH)
+        return false;
+    const tag = el.tagName.toLowerCase();
+    // Skip script/style/noscript subtrees — never user-facing content.
+    if (tag === 'script' || tag === 'style' || tag === 'noscript' || tag === 'template')
+        return false;
+    const text = (el.textContent ?? '').trim();
+    if (/^h[1-6]$/.test(tag)) {
+        out.push({ kind: 'heading', level: Number(tag[1]), text });
+        return false;
+    }
+    if (tag === 'button') {
+        if (text.length > 0 || el.getAttribute('aria-label')) {
+            out.push({
+                kind: 'button',
+                text: text || el.getAttribute('aria-label') || '',
+                disabled: el.disabled,
+                actionVariant: el.getAttribute('data-agent') ?? null,
+            });
+        }
+        return out.length >= FALLBACK_MAX_NODES;
+    }
+    if (tag === 'a' && el.getAttribute('href')) {
+        out.push({ kind: 'link', text, href: el.getAttribute('href') ?? '' });
+        return out.length >= FALLBACK_MAX_NODES;
+    }
+    if (tag === 'input') {
+        const inputType = el.type ?? 'text';
+        // `hidden` inputs are almost always form-state plumbing; skip them.
+        if (inputType !== 'hidden') {
+            out.push({
+                kind: 'input',
+                label: el.getAttribute('aria-label') ?? el.getAttribute('name') ?? null,
+                value: el.value ?? null,
+                type: inputType,
+            });
+        }
+        return out.length >= FALLBACK_MAX_NODES;
+    }
+    if (tag === 'ul' || tag === 'ol') {
+        const items = [];
+        for (const child of Array.from(el.children)) {
+            if (child.tagName.toLowerCase() === 'li') {
+                const itemText = (child.textContent ?? '').trim();
+                if (itemText.length > 0)
+                    items.push({ kind: 'item', text: itemText });
+            }
+        }
+        if (items.length > 0)
+            out.push({ kind: 'list', items });
+        return out.length >= FALLBACK_MAX_NODES;
+    }
+    // Bare text leaf: only emit if the element has a non-empty text and
+    // no element children. Same rule as the tagged walker.
+    if (text.length > 0 && el.children.length === 0) {
+        out.push({ kind: 'text', text });
+        return out.length >= FALLBACK_MAX_NODES;
+    }
+    for (const child of Array.from(el.children)) {
+        if (walkFallback(child, out, depth + 1))
+            return true;
+    }
+    return false;
+}
 //# sourceMappingURL=describe-visible-content.js.map

package/dist/client/rpc/describe-visible-content.js.map

@@ -1 +1 @@
-{"version":3,"file":"describe-visible-content.js","sourceRoot":"","sources":["../../../src/client/rpc/describe-visible-content.ts"],"names":[],"mappings":"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","sourcesContent":["import type { OutlineNode } from '../../protocol.js'\n\nexport type DescribeVisibleArgs = Record<string, never>\nexport type DescribeVisibleResult = { outline: OutlineNode[] }\n\nexport type DescribeVisibleHost = {\n  getRootElement(): Element | null\n  getBindingDescriptors(): Array<{ variant: string }> | null\n  getMsgAnnotations(): Record<string, { intent: string | null; humanOnly: boolean }> | null\n}\n\n/**\n * Walk data-agent-tagged subtrees and produce a structured outline.\n * Buttons cross-reference __bindingDescriptors so Claude can tie\n * visible text to variant names.\n */\nexport function handleDescribeVisibleContent(host: DescribeVisibleHost): DescribeVisibleResult {\n  const root = host.getRootElement()\n  if (!root) return { outline: [] }\n  const out: OutlineNode[] = []\n  const allZones = Array.from(root.querySelectorAll('[data-agent]'))\n  // Only walk top-level zones; skip zones that are descendants of other zones\n  const topLevel = allZones.filter(\n    (zone) => !allZones.some((other) => other !== zone && other.contains(zone)),\n  )\n  for (const zone of topLevel) {\n    walk(zone, out)\n  }\n  return { outline: out }\n}\n\nfunction walk(el: Element, out: OutlineNode[]): void {\n  const tag = el.tagName.toLowerCase()\n  const text = (el.textContent ?? '').trim()\n  if (/^h[1-6]$/.test(tag)) {\n    out.push({ kind: 'heading', level: Number(tag[1]), text })\n    return\n  }\n  if (tag === 'button') {\n    out.push({\n      kind: 'button',\n      text,\n      disabled: (el as HTMLButtonElement).disabled,\n      actionVariant: el.getAttribute('data-agent') ?? null,\n    })\n    return\n  }\n  if (tag === 'a' && el.getAttribute('href')) {\n    out.push({ kind: 'link', text, href: el.getAttribute('href') ?? '' })\n    return\n  }\n  if (tag === 'input') {\n    out.push({\n      kind: 'input',\n      label: el.getAttribute('aria-label') ?? el.getAttribute('name') ?? null,\n      value: (el as HTMLInputElement).value ?? null,\n      type: (el as HTMLInputElement).type ?? 'text',\n    })\n    return\n  }\n  if (tag === 'ul' || tag === 'ol') {\n    const items: OutlineNode[] = []\n    for (const child of Array.from(el.children)) {\n      if (child.tagName.toLowerCase() === 'li') {\n        items.push({ kind: 'item', text: (child.textContent ?? '').trim() })\n      }\n    }\n    out.push({ kind: 'list', items })\n    return\n  }\n  if (text.length > 0 && el.children.length === 0) {\n    out.push({ kind: 'text', text })\n    return\n  }\n  for (const child of Array.from(el.children)) {\n    walk(child, out)\n  }\n}\n"]}
+{"version":3,"file":"describe-visible-content.js","sourceRoot":"","sources":["../../../src/client/rpc/describe-visible-content.ts"],"names":[],"mappings":"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","sourcesContent":["import type { MessageAnnotations, OutlineNode } from '../../protocol.js'\n\nexport type DescribeVisibleArgs = Record<string, never>\nexport type DescribeVisibleResult = {\n  outline: OutlineNode[]\n  /**\n   * `'data-agent'` when the outline was scoped to author-tagged zones.\n   * `'fallback'` when the app has no `data-agent` attributes and the\n   * walker fell back to a generic semantic-element pass over the root.\n   * `'truncated'` when the fallback outline hit the node-count cap and\n   * stopped early; the caller can ask follow-up questions through\n   * `query_dom` or by inspecting state directly.\n   */\n  source: 'data-agent' | 'fallback' | 'truncated'\n}\n\nexport type DescribeVisibleHost = {\n  getRootElement(): Element | null\n  getBindingDescriptors(): Array<{ variant: string }> | null\n  getMsgAnnotations(): Record<string, MessageAnnotations> | null\n}\n\n/**\n * Hard caps for the fallback walk. The author-tagged path doesn't need\n * caps — by definition the author chose what to expose. The fallback is\n * walking arbitrary DOM, so it has to bound the work.\n *\n * 200 nodes covers ~3–5 visible screens of typical app UI; depth 8 is\n * deep enough for nested content trees but stops us from descending\n * into giant virtualised lists or syntax-highlighted code blocks.\n */\nconst FALLBACK_MAX_NODES = 200\nconst FALLBACK_MAX_DEPTH = 8\n\n/**\n * Walk data-agent-tagged subtrees and produce a structured outline.\n * Buttons cross-reference __bindingDescriptors so Claude can tie\n * visible text to variant names.\n *\n * If the app has no `data-agent` tags, fall back to a depth-limited\n * walk of the entire root element. This makes the tool useful for apps\n * that haven't (yet) tagged their views — typical first-pass dogfood\n * targets — instead of returning an empty outline that conveys\n * nothing. The fallback path sets `source: 'fallback'` so the caller\n * can tell the outline is best-effort.\n */\nexport function handleDescribeVisibleContent(host: DescribeVisibleHost): DescribeVisibleResult {\n  const root = host.getRootElement()\n  if (!root) return { outline: [], source: 'data-agent' }\n  const allZones = Array.from(root.querySelectorAll('[data-agent]'))\n  if (allZones.length > 0) {\n    const out: OutlineNode[] = []\n    // Only walk top-level zones; skip zones that are descendants of other zones\n    const topLevel = allZones.filter(\n      (zone) => !allZones.some((other) => other !== zone && other.contains(zone)),\n    )\n    for (const zone of topLevel) {\n      walk(zone, out)\n    }\n    return { outline: out, source: 'data-agent' }\n  }\n  // Fallback: walk the entire root with caps. Useful for apps without\n  // any data-agent annotations — at minimum the agent gets headings,\n  // buttons, links, lists, and visible text it can use to orient.\n  const out: OutlineNode[] = []\n  const truncated = walkFallback(root, out, 0)\n  return { outline: out, source: truncated ? 'truncated' : 'fallback' }\n}\n\nfunction walk(el: Element, out: OutlineNode[]): void {\n  const tag = el.tagName.toLowerCase()\n  const text = (el.textContent ?? '').trim()\n  if (/^h[1-6]$/.test(tag)) {\n    out.push({ kind: 'heading', level: Number(tag[1]), text })\n    return\n  }\n  if (tag === 'button') {\n    out.push({\n      kind: 'button',\n      text,\n      disabled: (el as HTMLButtonElement).disabled,\n      actionVariant: el.getAttribute('data-agent') ?? null,\n    })\n    return\n  }\n  if (tag === 'a' && el.getAttribute('href')) {\n    out.push({ kind: 'link', text, href: el.getAttribute('href') ?? '' })\n    return\n  }\n  if (tag === 'input') {\n    out.push({\n      kind: 'input',\n      label: el.getAttribute('aria-label') ?? el.getAttribute('name') ?? null,\n      value: (el as HTMLInputElement).value ?? null,\n      type: (el as HTMLInputElement).type ?? 'text',\n    })\n    return\n  }\n  if (tag === 'ul' || tag === 'ol') {\n    const items: OutlineNode[] = []\n    for (const child of Array.from(el.children)) {\n      if (child.tagName.toLowerCase() === 'li') {\n        items.push({ kind: 'item', text: (child.textContent ?? '').trim() })\n      }\n    }\n    out.push({ kind: 'list', items })\n    return\n  }\n  if (text.length > 0 && el.children.length === 0) {\n    out.push({ kind: 'text', text })\n    return\n  }\n  for (const child of Array.from(el.children)) {\n    walk(child, out)\n  }\n}\n\n/**\n * Depth- and count-limited walk for the fallback path. Returns true\n * iff the cap was hit (at least one element was skipped). Same node\n * vocabulary as `walk` but prunes more aggressively:\n *\n *  - `<a>` without `href`, `<button>` without text — skipped (often\n *    icon-only chrome that adds noise without helping the agent).\n *  - Nested wrapper divs without semantic content — descended into\n *    but not emitted.\n *  - Standalone text nodes — only emitted when the parent has no\n *    semantic children (preserves the existing `walk` heuristic).\n */\nfunction walkFallback(el: Element, out: OutlineNode[], depth: number): boolean {\n  if (out.length >= FALLBACK_MAX_NODES) return true\n  if (depth > FALLBACK_MAX_DEPTH) return false\n  const tag = el.tagName.toLowerCase()\n  // Skip script/style/noscript subtrees — never user-facing content.\n  if (tag === 'script' || tag === 'style' || tag === 'noscript' || tag === 'template') return false\n  const text = (el.textContent ?? '').trim()\n  if (/^h[1-6]$/.test(tag)) {\n    out.push({ kind: 'heading', level: Number(tag[1]), text })\n    return false\n  }\n  if (tag === 'button') {\n    if (text.length > 0 || el.getAttribute('aria-label')) {\n      out.push({\n        kind: 'button',\n        text: text || el.getAttribute('aria-label') || '',\n        disabled: (el as HTMLButtonElement).disabled,\n        actionVariant: el.getAttribute('data-agent') ?? null,\n      })\n    }\n    return out.length >= FALLBACK_MAX_NODES\n  }\n  if (tag === 'a' && el.getAttribute('href')) {\n    out.push({ kind: 'link', text, href: el.getAttribute('href') ?? '' })\n    return out.length >= FALLBACK_MAX_NODES\n  }\n  if (tag === 'input') {\n    const inputType = (el as HTMLInputElement).type ?? 'text'\n    // `hidden` inputs are almost always form-state plumbing; skip them.\n    if (inputType !== 'hidden') {\n      out.push({\n        kind: 'input',\n        label: el.getAttribute('aria-label') ?? el.getAttribute('name') ?? null,\n        value: (el as HTMLInputElement).value ?? null,\n        type: inputType,\n      })\n    }\n    return out.length >= FALLBACK_MAX_NODES\n  }\n  if (tag === 'ul' || tag === 'ol') {\n    const items: OutlineNode[] = []\n    for (const child of Array.from(el.children)) {\n      if (child.tagName.toLowerCase() === 'li') {\n        const itemText = (child.textContent ?? '').trim()\n        if (itemText.length > 0) items.push({ kind: 'item', text: itemText })\n      }\n    }\n    if (items.length > 0) out.push({ kind: 'list', items })\n    return out.length >= FALLBACK_MAX_NODES\n  }\n  // Bare text leaf: only emit if the element has a non-empty text and\n  // no element children. Same rule as the tagged walker.\n  if (text.length > 0 && el.children.length === 0) {\n    out.push({ kind: 'text', text })\n    return out.length >= FALLBACK_MAX_NODES\n  }\n  for (const child of Array.from(el.children)) {\n    if (walkFallback(child, out, depth + 1)) return true\n  }\n  return false\n}\n"]}

package/dist/client/rpc/list-actions.d.ts

@@ -1,4 +1,5 @@
 import type { MessageAnnotations } from '../../protocol.js';
+import type { MsgSchemaShape } from '../factory.js';
 type Binding = {
     variant: string;
 };
@@ -7,19 +8,68 @@ export type ListActionsHost = {
     getState(): unknown;
     getBindingDescriptors(): Binding[] | null;
     getMsgAnnotations(): Annotations | null;
+    getMsgSchema(): MsgSchemaShape | null;
     getAgentAffordances(): ((state: unknown) => Array<{
         type: string;
         [k: string]: unknown;
     }>) | null;
 };
+/**
+ * `dispatchMode` on each action is `'shared'` (human can also click via
+ * a UI affordance) or `'agent-only'` (no UI binding — agent is the only
+ * dispatcher). `'human-only'` variants are filtered out before this
+ * point — they never reach the LLM.
+ *
+ * `source` distinguishes WHERE the affordance came from:
+ *   - `'binding'`     — a tagged event handler is currently mounted.
+ *   - `'always-affordable'` — the app's `agentAffordances(state)` hook
+ *     listed it as available right now.
+ *   - `'schema'`      — neither of the above; the variant is in the
+ *     Msg union, annotated `@agentOnly`, and the payload is example-
+ *     only (no live UI binding maps to it). Bulk-edit operations
+ *     typically land here.
+ */
 export type ListActionsResult = {
     actions: Array<{
         variant: string;
-        intent: string;
+        /**
+         * Human-readable phrase from `@intent("…")`, or `null` when the
+         * variant is unannotated. Mirror of LapActionsResponse.intent —
+         * callers should treat `null` as a documentation gap and not as
+         * "missing label, fall back to variant name".
+         */
+        intent: string | null;
         requiresConfirm: boolean;
-        source: 'binding' | 'always-affordable';
+        dispatchMode: 'shared' | 'agent-only';
+        source: 'binding' | 'always-affordable' | 'schema';
         selectorHint: string | null;
         payloadHint: object | null;
+        /** Cautionary text from `@warning` JSDoc, or null. */
+        warning: string | null;
+        /** Concrete examples from `@example` JSDoc, in source order. */
+        examples: string[];
+        /**
+         * Effect kinds this variant emits, from `@emits("k1", "k2")`.
+         * Empty when not annotated. Lets the agent know what side
+         * effects fire — useful for batching ("100 dispatches × cloud-
+         * save = bad") and for confirming destructive flows.
+         */
+        emits: string[];
+        /**
+         * Per-field guidance lifted from `@should("…")` JSDoc on payload
+         * fields. Path is dot/bracket notation rooted at the payload
+         * (e.g. `"cells"` for a top-level field, `"cells[].meta"` for an
+         * array element's nested field). Useful when the field is typed
+         * as `unknown` or as a polymorphic shape — the hint says "type
+         * matches the criterion's kind: number for quantity, …" so the
+         * agent doesn't have to guess from the bare schema.
+         *
+         * Empty when no field on this variant carries an `@should` hint.
+         */
+        fieldHints: Array<{
+            path: string;
+            hint: string;
+        }>;
     }>;
 };
 export declare function handleListActions(host: ListActionsHost): ListActionsResult;

package/dist/client/rpc/list-actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-actions.d.ts","sourceRoot":"","sources":["../../../src/client/rpc/list-actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAE3D,KAAK,OAAO,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAClC,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;AAErD,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,IAAI,OAAO,CAAA;IACnB,qBAAqB,IAAI,OAAO,EAAE,GAAG,IAAI,CAAA;IACzC,iBAAiB,IAAI,WAAW,GAAG,IAAI,CAAA;IACvC,mBAAmB,IAAI,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC,GAAG,IAAI,CAAA;CAClG,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,KAAK,CAAC;QACb,OAAO,EAAE,MAAM,CAAA;QACf,MAAM,EAAE,MAAM,CAAA;QACd,eAAe,EAAE,OAAO,CAAA;QACxB,MAAM,EAAE,SAAS,GAAG,mBAAmB,CAAA;QACvC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;QAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;KAC3B,CAAC,CAAA;CACH,CAAA;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAsC1E"}
+{"version":3,"file":"list-actions.d.ts","sourceRoot":"","sources":["../../../src/client/rpc/list-actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,eAAe,CAAA;AAEnE,KAAK,OAAO,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAClC,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;AAErD,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,IAAI,OAAO,CAAA;IACnB,qBAAqB,IAAI,OAAO,EAAE,GAAG,IAAI,CAAA;IACzC,iBAAiB,IAAI,WAAW,GAAG,IAAI,CAAA;IACvC,YAAY,IAAI,cAAc,GAAG,IAAI,CAAA;IACrC,mBAAmB,IAAI,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC,GAAG,IAAI,CAAA;CAClG,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,KAAK,CAAC;QACb,OAAO,EAAE,MAAM,CAAA;QACf;;;;;WAKG;QACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;QACrB,eAAe,EAAE,OAAO,CAAA;QACxB,YAAY,EAAE,QAAQ,GAAG,YAAY,CAAA;QACrC,MAAM,EAAE,SAAS,GAAG,mBAAmB,GAAG,QAAQ,CAAA;QAClD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;QAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;QAC1B,sDAAsD;QACtD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;QACtB,gEAAgE;QAChE,QAAQ,EAAE,MAAM,EAAE,CAAA;QAClB;;;;;WAKG;QACH,KAAK,EAAE,MAAM,EAAE,CAAA;QACf;;;;;;;;;;WAUG;QACH,UAAU,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAClD,CAAC,CAAA;CACH,CAAA;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAoG1E"}

package/dist/client/rpc/list-actions.js

@@ -3,36 +3,218 @@ export function handleListActions(host) {
     const state = host.getState();
     const descriptors = host.getBindingDescriptors() ?? [];
     const affordances = host.getAgentAffordances()?.(state) ?? [];
+    const schema = host.getMsgSchema();
     const out = [];
-    // From bindings
+    const seen = new Set();
+    // From bindings — these have UI affordances by definition, so they're
+    // either 'shared' (default) or, in the malformed case where someone
+    // bound an `@agentOnly` Msg in a view, 'agent-only'. Either way the
+    // agent can dispatch them.
     for (const d of descriptors) {
         const ann = annotations[d.variant];
-        if (ann?.humanOnly)
+        if (ann?.dispatchMode === 'human-only')
             continue;
+        seen.add(d.variant);
+        const variantSchema = schema?.variants[d.variant];
         out.push({
             variant: d.variant,
-            intent: ann?.intent ?? d.variant,
+            intent: ann?.intent ?? null,
             requiresConfirm: ann?.requiresConfirm ?? false,
+            dispatchMode: ann?.dispatchMode === 'agent-only' ? 'agent-only' : 'shared',
             source: 'binding',
             selectorHint: null,
             payloadHint: null,
+            warning: ann?.warning ?? null,
+            examples: ann?.examples ?? [],
+            emits: ann?.emits ?? [],
+            fieldHints: variantSchema ? collectFieldHints(variantSchema) : [],
         });
     }
     // From always-affordable
     for (const msg of affordances) {
         const ann = annotations[msg.type];
-        if (ann?.humanOnly)
+        if (ann?.dispatchMode === 'human-only')
             continue;
+        seen.add(msg.type);
         const { type, ...rest } = msg;
+        const variantSchema = schema?.variants[type];
         out.push({
             variant: type,
-            intent: ann?.intent ?? type,
+            intent: ann?.intent ?? null,
             requiresConfirm: ann?.requiresConfirm ?? false,
+            dispatchMode: ann?.dispatchMode === 'agent-only' ? 'agent-only' : 'shared',
             source: 'always-affordable',
             selectorHint: null,
             payloadHint: Object.keys(rest).length > 0 ? rest : null,
+            warning: ann?.warning ?? null,
+            examples: ann?.examples ?? [],
+            emits: ann?.emits ?? [],
+            fieldHints: variantSchema ? collectFieldHints(variantSchema) : [],
         });
     }
+    // From schema — variants that aren't already surfaced as bindings
+    // or always-affordable, and that the author intentionally documented
+    // for agent use. Two cases land here:
+    //
+    //   1. `@agentOnly` variants — the canonical "no UI button maps to
+    //      this; the agent is the only dispatcher." Bulk edits, imports,
+    //      admin operations.
+    //   2. `'shared'` variants with `@intent` but no live binding — the
+    //      author wrote a description for the variant, signalling it's
+    //      a real agent-callable dispatch even when the corresponding UI
+    //      affordance is closed (e.g. `Matrix/SetQuantityValue` lives
+    //      inside the cell editor; without this case, an agent that
+    //      wants to set one cell is forced to use the bulk
+    //      `Matrix/SetManyCells` with a 1-element array).
+    //
+    // `'shared'` variants WITHOUT `@intent` stay hidden — undocumented
+    // shared variants are usually internal (effect-result messages,
+    // router-internal acks) that aren't intended as agent affordances.
+    // `'human-only'` is always filtered.
+    if (schema) {
+        for (const [variant, fields] of Object.entries(schema.variants)) {
+            if (seen.has(variant))
+                continue;
+            const ann = annotations[variant];
+            if (ann?.dispatchMode === 'human-only')
+                continue;
+            const isAgentOnly = ann?.dispatchMode === 'agent-only';
+            const isDocumentedShared = ann?.dispatchMode !== 'agent-only' && Boolean(ann?.intent);
+            if (!isAgentOnly && !isDocumentedShared)
+                continue;
+            out.push({
+                variant,
+                intent: ann?.intent ?? null,
+                requiresConfirm: ann?.requiresConfirm ?? false,
+                dispatchMode: isAgentOnly ? 'agent-only' : 'shared',
+                source: 'schema',
+                selectorHint: null,
+                payloadHint: synthesizePayload(variant, fields),
+                warning: ann?.warning ?? null,
+                examples: ann?.examples ?? [],
+                emits: ann?.emits ?? [],
+                fieldHints: collectFieldHints(fields),
+            });
+        }
+    }
     return { actions: out };
 }
+/**
+ * Build an example payload object the LLM can fill in. Required
+ * fields always appear; optional fields appear only when annotated
+ * `@should` (LLM is encouraged to fill them in). Fields without a
+ * concrete primitive type (`'unknown'`) emit `null` placeholders the
+ * LLM is expected to replace.
+ *
+ * The first key is `type` so the payload reads as a complete Msg
+ * shape — copy-paste-ready into `send_message`.
+ */
+function synthesizePayload(variant, fields) {
+    const out = { type: variant };
+    for (const [name, descriptor] of Object.entries(fields)) {
+        const optional = isOptional(descriptor);
+        const priority = isShould(descriptor);
+        // Skip optional fields unless they're @should-flagged. Required
+        // fields always appear.
+        if (optional && priority !== 'should')
+            continue;
+        out[name] = exampleValue(descriptor);
+    }
+    return out;
+}
+/**
+ * Walk a variant's field tree and collect every `@should` hint into a
+ * flat list keyed by field path. Path conventions:
+ *   - top-level field: `"cells"`
+ *   - nested object property: `"cells.value"`
+ *   - array element: `"cells[]"` for the element itself; descendants
+ *     use `"cells[].meta"` and so on.
+ *
+ * Surfaces the same hints that show up nested inside
+ * `description.messages.variants[X].field.hint` so callers don't have
+ * to dig through the schema tree to find them.
+ */
+function collectFieldHints(fields) {
+    const out = [];
+    for (const [name, descriptor] of Object.entries(fields)) {
+        walkHint(name, descriptor, out);
+    }
+    return out;
+}
+function walkHint(path, d, out) {
+    // Rich descriptor with a hint at this position.
+    if (typeof d === 'object' && d !== null && 'type' in d) {
+        if (typeof d.hint === 'string' && d.hint.length > 0) {
+            out.push({ path, hint: d.hint });
+        }
+        walkHintBare(path, d.type, out);
+        return;
+    }
+    walkHintBare(path, d, out);
+}
+function walkHintBare(path, t, out) {
+    if (t === null || typeof t !== 'object')
+        return;
+    const obj = t;
+    if (obj.kind === 'object' && obj.shape !== null && typeof obj.shape === 'object') {
+        for (const [name, descriptor] of Object.entries(obj.shape)) {
+            walkHint(`${path}.${name}`, descriptor, out);
+        }
+        return;
+    }
+    if (obj.kind === 'array') {
+        walkHint(`${path}[]`, obj.element, out);
+    }
+}
+function isOptional(d) {
+    return typeof d === 'object' && 'type' in d && d.optional === true;
+}
+function isShould(d) {
+    return typeof d === 'object' && 'type' in d ? d.priority : undefined;
+}
+function exampleValue(d) {
+    // Unwrap rich descriptor to get the bare type for synthesis.
+    const t = typeof d === 'object' && 'type' in d
+        ? d.type
+        : d;
+    return synthesizeBare(t);
+}
+function synthesizeBare(t) {
+    if (typeof t === 'string') {
+        if (t === 'string')
+            return '';
+        if (t === 'number')
+            return 0;
+        if (t === 'boolean')
+            return false;
+        return null; // 'unknown' or unrecognized keyword → placeholder
+    }
+    if (t === null || typeof t !== 'object')
+        return null;
+    const obj = t;
+    if ('enum' in obj && Array.isArray(obj.enum)) {
+        // First option doubles as the canonical example.
+        return obj.enum[0] ?? null;
+    }
+    if (obj.kind === 'object' && obj.shape !== null && typeof obj.shape === 'object') {
+        // Recurse into the nested shape. Same optional-skip rule as the
+        // top-level synthesizer: required fields appear, optional ones
+        // appear only when @should-flagged.
+        const out = {};
+        for (const [name, descriptor] of Object.entries(obj.shape)) {
+            const isOpt = isOptional(descriptor);
+            const pri = isShould(descriptor);
+            if (isOpt && pri !== 'should')
+                continue;
+            out[name] = exampleValue(descriptor);
+        }
+        return out;
+    }
+    if (obj.kind === 'array') {
+        // Wrap the synthesized element in a one-item array. Lets the LLM
+        // see the per-entry shape without us guessing at array length.
+        return [synthesizeBare(obj.element)];
+    }
+    return null;
+}
 //# sourceMappingURL=list-actions.js.map