@immediately-run/sdk 0.45.2 → 0.46.0

package/dist/linkSpace.d.ts

@@ -5,6 +5,26 @@ interface LinkSpace {
     /** Absolute filesystem path of the enclosing corpus's root (e.g. `/app/content`),
      *  or `null` when the document is not corpus-hosted (default). */
     corpusRoot: string | null;
+    /**
+     * True when the filesystem this document resolves against is **chroot'd to the
+     * bundle** — i.e. the port the app holds was scoped to the bundle's subtree, so
+     * the mount root and the bundle root are the same directory
+     * (`BUNDLE_LAYERS_SPEC §9`; the `T2`/`T4` wrapper, R3-319 / BL-2).
+     *
+     * Under that grant `$fs:` **collapses to the scoped root**: `$fs:/p` and `/p`
+     * name the same byte, because there is no longer any "mount-absolute" space
+     * outside the bundle for `$fs:` to reach into. Without this flag the resolver
+     * would hand back a mount-absolute path that the chroot then re-roots anyway —
+     * a link that renders as valid and resolves somewhere the author did not mean.
+     *
+     * **This is an invariant to CREATE, not one to inherit** (`BUNDLE_LAYERS_SPEC
+     * §11`): the shipped resolver reads `{currentFile, corpusRoot}` and nothing
+     * else, so `$fs:` is bundle-anchored only if something says so. It lives here,
+     * in the resolver, rather than as a rule each caller applies by passing
+     * `corpusRoot: '/'` — an invariant the arithmetic carries cannot be forgotten
+     * at one call site out of five.
+     */
+    bundleChrooted?: boolean;
 }
 /** Ambient link space. A corpus-rendering app wraps its document tree in
  *  `<LinkSpaceContext value={{ corpusRoot }}>`; nesting a second provider inside a
@@ -39,6 +59,9 @@ type ResolvedLinkTarget =
 declare function resolveLinkTarget(raw: string, opts?: {
     currentFile?: string;
     corpusRoot?: string | null;
+    /** See `LinkSpace.bundleChrooted`. Under a bundle-chroot'd grant `$fs:`
+     *  resolves in the corpus space, because they are the same space. */
+    bundleChrooted?: boolean;
 }): ResolvedLinkTarget;
 
 export { FS_PREFIX, type LinkSpace, LinkSpaceContext, type ResolvedLinkTarget, normalizeAbsolute, resolveLinkTarget };

package/dist/linkSpace.js

@@ -1,7 +1,10 @@
 import "./chunk-VHAA22YE.js";
 import { createContext } from "react";
 const FS_PREFIX = "$fs:";
-const LinkSpaceContext = createContext({ corpusRoot: null });
+const LinkSpaceContext = createContext({
+  corpusRoot: null,
+  bundleChrooted: false
+});
 const normalizeAbsolute = (path) => {
   const out = [];
   for (const seg of path.split("/")) {
@@ -11,16 +14,22 @@ const normalizeAbsolute = (path) => {
   }
   return "/" + out.join("/");
 };
+function resolveCorpusAbsolute(path, corpusRoot) {
+  const inner = normalizeAbsolute(path);
+  if (corpusRoot === null || corpusRoot === "/") return { state: "resolved", path: inner };
+  return { state: "resolved", path: normalizeAbsolute(corpusRoot + inner) };
+}
 function resolveLinkTarget(raw, opts = {}) {
   if (raw.startsWith(FS_PREFIX)) {
     const rest = raw.slice(FS_PREFIX.length);
     if (!rest.startsWith("/")) return { state: "invalid" };
+    if (opts.bundleChrooted) return resolveCorpusAbsolute(rest, opts.corpusRoot ?? null);
     return { state: "resolved", path: normalizeAbsolute(rest) };
   }
   if (raw.startsWith("/")) {
     const corpusRoot = opts.corpusRoot ?? null;
     if (corpusRoot !== null) {
-      return { state: "resolved", path: normalizeAbsolute(corpusRoot + normalizeAbsolute(raw)) };
+      return resolveCorpusAbsolute(raw, corpusRoot);
     }
     return { state: "resolved", path: normalizeAbsolute(raw) };
   }

package/dist/linkSpace.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/linkSpace.ts"],"sourcesContent":["// Link path spaces (R3-273; REPO_CONTENT_DISPATCH_SPEC §9 decision, 2026-08-17).\n//\n// A document link's target resolves in one of two spaces:\n//\n// - DEFAULT — the enclosing corpus's virtual filesystem. RELATIVE targets resolve\n//   against the authoring file (identical in both spaces); ABSOLUTE targets\n//   (`/x/y.mdx`) resolve from the corpus root when an enclosing `LinkSpaceContext`\n//   declares one, else from the filesystem root. A non-corpus app declares nothing\n//   and keeps today's behavior bit-for-bit (its fs root IS its only root).\n//\n// - `$fs:` — the explicit filesystem space: `$fs:/content/x.mdx` resolves from the\n//   root of the filesystem the app reads, escaping corpus-relative addressing.\n//\n// `$fs:` changes ADDRESSING, never REACH: resolution is pure path arithmetic and\n// existence is checked against the same in-mount metadata the default space uses —\n// nothing is fetched, and a link can never name what the app cannot already read.\n// A malformed `$fs:` target (anything not mount-absolute — which also catches\n// scheme smuggling like `$fs:javascript:…`) is INVALID and must render as a broken\n// link, never an anchor.\n//\n// Corpus nesting: `LinkSpaceContext` providers nest, and the NEAREST one wins —\n// which is exactly the innermost-enclosing-corpus rule (bundle encapsulation): a\n// document rendered inside a nested corpus resolves against the nested corpus.\n\nimport { createContext } from 'react';\n\nexport const FS_PREFIX = '$fs:';\n\nexport interface LinkSpace {\n  /** Absolute filesystem path of the enclosing corpus's root (e.g. `/app/content`),\n   *  or `null` when the document is not corpus-hosted (default). */\n  corpusRoot: string | null;\n}\n\n/** Ambient link space. A corpus-rendering app wraps its document tree in\n *  `<LinkSpaceContext value={{ corpusRoot }}>`; nesting a second provider inside a\n *  rendered sub-corpus makes the innermost root win. */\nexport const LinkSpaceContext = createContext<LinkSpace>({ corpusRoot: null });\n\n/** Collapse `.`/`..`/empty segments into a clean absolute path. `..` can never\n *  climb above the root — a (virtual) root's parent is itself, which is what keeps\n *  both the mount space and the corpus space closed under traversal. */\nexport const normalizeAbsolute = (path: string): string => {\n  const out: string[] = [];\n  for (const seg of path.split('/')) {\n    if (seg === '' || seg === '.') continue;\n    if (seg === '..') out.pop();\n    else out.push(seg);\n  }\n  return '/' + out.join('/');\n};\n\nexport type ResolvedLinkTarget =\n  /** Resolved to an absolute filesystem path (existence NOT checked here). */\n  | { state: 'resolved'; path: string }\n  /** A relative target with no known authoring file — the caller may route\n   *  optimistically (it cannot check existence or self-ness generically). */\n  | { state: 'unresolvable' }\n  /** A malformed `$fs:` target (not mount-absolute; includes scheme smuggling).\n   *  Callers MUST render this broken/inert — never as an anchor. */\n  | { state: 'invalid' };\n\n/**\n * Resolve a raw link target (a wikilink target or an in-app href's path half —\n * fragment already split off) to an absolute filesystem path. THE shared resolver:\n * the default `WikiLink`, the markdown `a` override, and safe-content consumers\n * all route through this one function so the two render pipelines cannot drift.\n */\nexport function resolveLinkTarget(\n  raw: string,\n  opts: { currentFile?: string; corpusRoot?: string | null } = {},\n): ResolvedLinkTarget {\n  if (raw.startsWith(FS_PREFIX)) {\n    const rest = raw.slice(FS_PREFIX.length);\n    // Must be mount-absolute. This single rule also fails `$fs:javascript:…`,\n    // `$fs:https://…`, and every other smuggled scheme closed.\n    if (!rest.startsWith('/')) return { state: 'invalid' };\n    return { state: 'resolved', path: normalizeAbsolute(rest) };\n  }\n  if (raw.startsWith('/')) {\n    const corpusRoot = opts.corpusRoot ?? null;\n    if (corpusRoot !== null) {\n      // Clamp the corpus-relative half FIRST (the virtual FS is closed — `/../x`\n      // stays inside the corpus), THEN anchor it at the corpus root.\n      return { state: 'resolved', path: normalizeAbsolute(corpusRoot + normalizeAbsolute(raw)) };\n    }\n    return { state: 'resolved', path: normalizeAbsolute(raw) };\n  }\n  // Relative: against the authoring file's directory — the same in both spaces.\n  if (!opts.currentFile) return { state: 'unresolvable' };\n  const dir = opts.currentFile.slice(0, opts.currentFile.lastIndexOf('/'));\n  return { state: 'resolved', path: normalizeAbsolute(`${dir}/${raw}`) };\n}\n"],"mappings":";AAwBA,SAAS,qBAAqB;AAEvB,MAAM,YAAY;AAWlB,MAAM,mBAAmB,cAAyB,EAAE,YAAY,KAAK,CAAC;AAKtE,MAAM,oBAAoB,CAAC,SAAyB;AACzD,QAAM,MAAgB,CAAC;AACvB,aAAW,OAAO,KAAK,MAAM,GAAG,GAAG;AACjC,QAAI,QAAQ,MAAM,QAAQ,IAAK;AAC/B,QAAI,QAAQ,KAAM,KAAI,IAAI;AAAA,QACrB,KAAI,KAAK,GAAG;AAAA,EACnB;AACA,SAAO,MAAM,IAAI,KAAK,GAAG;AAC3B;AAkBO,SAAS,kBACd,KACA,OAA6D,CAAC,GAC1C;AACpB,MAAI,IAAI,WAAW,SAAS,GAAG;AAC7B,UAAM,OAAO,IAAI,MAAM,UAAU,MAAM;AAGvC,QAAI,CAAC,KAAK,WAAW,GAAG,EAAG,QAAO,EAAE,OAAO,UAAU;AACrD,WAAO,EAAE,OAAO,YAAY,MAAM,kBAAkB,IAAI,EAAE;AAAA,EAC5D;AACA,MAAI,IAAI,WAAW,GAAG,GAAG;AACvB,UAAM,aAAa,KAAK,cAAc;AACtC,QAAI,eAAe,MAAM;AAGvB,aAAO,EAAE,OAAO,YAAY,MAAM,kBAAkB,aAAa,kBAAkB,GAAG,CAAC,EAAE;AAAA,IAC3F;AACA,WAAO,EAAE,OAAO,YAAY,MAAM,kBAAkB,GAAG,EAAE;AAAA,EAC3D;AAEA,MAAI,CAAC,KAAK,YAAa,QAAO,EAAE,OAAO,eAAe;AACtD,QAAM,MAAM,KAAK,YAAY,MAAM,GAAG,KAAK,YAAY,YAAY,GAAG,CAAC;AACvE,SAAO,EAAE,OAAO,YAAY,MAAM,kBAAkB,GAAG,GAAG,IAAI,GAAG,EAAE,EAAE;AACvE;","names":[]}
+{"version":3,"sources":["../src/linkSpace.ts"],"sourcesContent":["// Link path spaces (R3-273; REPO_CONTENT_DISPATCH_SPEC §9 decision, 2026-08-17).\n//\n// A document link's target resolves in one of two spaces:\n//\n// - DEFAULT — the enclosing corpus's virtual filesystem. RELATIVE targets resolve\n//   against the authoring file (identical in both spaces); ABSOLUTE targets\n//   (`/x/y.mdx`) resolve from the corpus root when an enclosing `LinkSpaceContext`\n//   declares one, else from the filesystem root. A non-corpus app declares nothing\n//   and keeps today's behavior bit-for-bit (its fs root IS its only root).\n//\n// - `$fs:` — the explicit filesystem space: `$fs:/content/x.mdx` resolves from the\n//   root of the filesystem the app reads, escaping corpus-relative addressing.\n//\n// `$fs:` changes ADDRESSING, never REACH: resolution is pure path arithmetic and\n// existence is checked against the same in-mount metadata the default space uses —\n// nothing is fetched, and a link can never name what the app cannot already read.\n// A malformed `$fs:` target (anything not mount-absolute — which also catches\n// scheme smuggling like `$fs:javascript:…`) is INVALID and must render as a broken\n// link, never an anchor.\n//\n// Corpus nesting: `LinkSpaceContext` providers nest, and the NEAREST one wins —\n// which is exactly the innermost-enclosing-corpus rule (bundle encapsulation): a\n// document rendered inside a nested corpus resolves against the nested corpus.\n\nimport { createContext } from 'react';\n\nexport const FS_PREFIX = '$fs:';\n\nexport interface LinkSpace {\n  /** Absolute filesystem path of the enclosing corpus's root (e.g. `/app/content`),\n   *  or `null` when the document is not corpus-hosted (default). */\n  corpusRoot: string | null;\n  /**\n   * True when the filesystem this document resolves against is **chroot'd to the\n   * bundle** — i.e. the port the app holds was scoped to the bundle's subtree, so\n   * the mount root and the bundle root are the same directory\n   * (`BUNDLE_LAYERS_SPEC §9`; the `T2`/`T4` wrapper, R3-319 / BL-2).\n   *\n   * Under that grant `$fs:` **collapses to the scoped root**: `$fs:/p` and `/p`\n   * name the same byte, because there is no longer any \"mount-absolute\" space\n   * outside the bundle for `$fs:` to reach into. Without this flag the resolver\n   * would hand back a mount-absolute path that the chroot then re-roots anyway —\n   * a link that renders as valid and resolves somewhere the author did not mean.\n   *\n   * **This is an invariant to CREATE, not one to inherit** (`BUNDLE_LAYERS_SPEC\n   * §11`): the shipped resolver reads `{currentFile, corpusRoot}` and nothing\n   * else, so `$fs:` is bundle-anchored only if something says so. It lives here,\n   * in the resolver, rather than as a rule each caller applies by passing\n   * `corpusRoot: '/'` — an invariant the arithmetic carries cannot be forgotten\n   * at one call site out of five.\n   */\n  bundleChrooted?: boolean;\n}\n\n/** Ambient link space. A corpus-rendering app wraps its document tree in\n *  `<LinkSpaceContext value={{ corpusRoot }}>`; nesting a second provider inside a\n *  rendered sub-corpus makes the innermost root win. */\nexport const LinkSpaceContext = createContext<LinkSpace>({\n  corpusRoot: null,\n  bundleChrooted: false,\n});\n\n/** Collapse `.`/`..`/empty segments into a clean absolute path. `..` can never\n *  climb above the root — a (virtual) root's parent is itself, which is what keeps\n *  both the mount space and the corpus space closed under traversal. */\nexport const normalizeAbsolute = (path: string): string => {\n  const out: string[] = [];\n  for (const seg of path.split('/')) {\n    if (seg === '' || seg === '.') continue;\n    if (seg === '..') out.pop();\n    else out.push(seg);\n  }\n  return '/' + out.join('/');\n};\n\nexport type ResolvedLinkTarget =\n  /** Resolved to an absolute filesystem path (existence NOT checked here). */\n  | { state: 'resolved'; path: string }\n  /** A relative target with no known authoring file — the caller may route\n   *  optimistically (it cannot check existence or self-ness generically). */\n  | { state: 'unresolvable' }\n  /** A malformed `$fs:` target (not mount-absolute; includes scheme smuggling).\n   *  Callers MUST render this broken/inert — never as an anchor. */\n  | { state: 'invalid' };\n\n/** Anchor a corpus-absolute path at `corpusRoot`, clamping the corpus-relative\n *  half FIRST so the virtual corpus space stays closed under traversal. Shared by\n *  the `/p` branch and — under a bundle chroot — the `$fs:/p` branch, so the two\n *  spellings cannot drift into resolving differently. */\nfunction resolveCorpusAbsolute(path: string, corpusRoot: string | null): ResolvedLinkTarget {\n  const inner = normalizeAbsolute(path);\n  if (corpusRoot === null || corpusRoot === '/') return { state: 'resolved', path: inner };\n  return { state: 'resolved', path: normalizeAbsolute(corpusRoot + inner) };\n}\n\n/**\n * Resolve a raw link target (a wikilink target or an in-app href's path half —\n * fragment already split off) to an absolute filesystem path. THE shared resolver:\n * the default `WikiLink`, the markdown `a` override, and safe-content consumers\n * all route through this one function so the two render pipelines cannot drift.\n */\nexport function resolveLinkTarget(\n  raw: string,\n  opts: {\n    currentFile?: string;\n    corpusRoot?: string | null;\n    /** See `LinkSpace.bundleChrooted`. Under a bundle-chroot'd grant `$fs:`\n     *  resolves in the corpus space, because they are the same space. */\n    bundleChrooted?: boolean;\n  } = {},\n): ResolvedLinkTarget {\n  if (raw.startsWith(FS_PREFIX)) {\n    const rest = raw.slice(FS_PREFIX.length);\n    // Must be mount-absolute. This single rule also fails `$fs:javascript:…`,\n    // `$fs:https://…`, and every other smuggled scheme closed.\n    if (!rest.startsWith('/')) return { state: 'invalid' };\n    // Under a bundle chroot the mount root IS the bundle root, so `$fs:` has\n    // nowhere outside to name: it takes the corpus-absolute branch below and the\n    // two spellings collapse. `normalizeAbsolute` clamps `..` at the root either\n    // way, so neither spelling can climb out — the collapse changes WHERE a\n    // `$fs:` link points, never whether it can escape.\n    if (opts.bundleChrooted) return resolveCorpusAbsolute(rest, opts.corpusRoot ?? null);\n    return { state: 'resolved', path: normalizeAbsolute(rest) };\n  }\n  if (raw.startsWith('/')) {\n    const corpusRoot = opts.corpusRoot ?? null;\n    if (corpusRoot !== null) {\n      // Clamp the corpus-relative half FIRST (the virtual FS is closed — `/../x`\n      // stays inside the corpus), THEN anchor it at the corpus root.\n      return resolveCorpusAbsolute(raw, corpusRoot);\n    }\n    return { state: 'resolved', path: normalizeAbsolute(raw) };\n  }\n  // Relative: against the authoring file's directory — the same in both spaces.\n  if (!opts.currentFile) return { state: 'unresolvable' };\n  const dir = opts.currentFile.slice(0, opts.currentFile.lastIndexOf('/'));\n  return { state: 'resolved', path: normalizeAbsolute(`${dir}/${raw}`) };\n}\n"],"mappings":";AAwBA,SAAS,qBAAqB;AAEvB,MAAM,YAAY;AA+BlB,MAAM,mBAAmB,cAAyB;AAAA,EACvD,YAAY;AAAA,EACZ,gBAAgB;AAClB,CAAC;AAKM,MAAM,oBAAoB,CAAC,SAAyB;AACzD,QAAM,MAAgB,CAAC;AACvB,aAAW,OAAO,KAAK,MAAM,GAAG,GAAG;AACjC,QAAI,QAAQ,MAAM,QAAQ,IAAK;AAC/B,QAAI,QAAQ,KAAM,KAAI,IAAI;AAAA,QACrB,KAAI,KAAK,GAAG;AAAA,EACnB;AACA,SAAO,MAAM,IAAI,KAAK,GAAG;AAC3B;AAgBA,SAAS,sBAAsB,MAAc,YAA+C;AAC1F,QAAM,QAAQ,kBAAkB,IAAI;AACpC,MAAI,eAAe,QAAQ,eAAe,IAAK,QAAO,EAAE,OAAO,YAAY,MAAM,MAAM;AACvF,SAAO,EAAE,OAAO,YAAY,MAAM,kBAAkB,aAAa,KAAK,EAAE;AAC1E;AAQO,SAAS,kBACd,KACA,OAMI,CAAC,GACe;AACpB,MAAI,IAAI,WAAW,SAAS,GAAG;AAC7B,UAAM,OAAO,IAAI,MAAM,UAAU,MAAM;AAGvC,QAAI,CAAC,KAAK,WAAW,GAAG,EAAG,QAAO,EAAE,OAAO,UAAU;AAMrD,QAAI,KAAK,eAAgB,QAAO,sBAAsB,MAAM,KAAK,cAAc,IAAI;AACnF,WAAO,EAAE,OAAO,YAAY,MAAM,kBAAkB,IAAI,EAAE;AAAA,EAC5D;AACA,MAAI,IAAI,WAAW,GAAG,GAAG;AACvB,UAAM,aAAa,KAAK,cAAc;AACtC,QAAI,eAAe,MAAM;AAGvB,aAAO,sBAAsB,KAAK,UAAU;AAAA,IAC9C;AACA,WAAO,EAAE,OAAO,YAAY,MAAM,kBAAkB,GAAG,EAAE;AAAA,EAC3D;AAEA,MAAI,CAAC,KAAK,YAAa,QAAO,EAAE,OAAO,eAAe;AACtD,QAAM,MAAM,KAAK,YAAY,MAAM,GAAG,KAAK,YAAY,YAAY,GAAG,CAAC;AACvE,SAAO,EAAE,OAAO,YAAY,MAAM,kBAAkB,GAAG,GAAG,IAAI,GAAG,EAAE,EAAE;AACvE;","names":[]}

package/dist/llm.cjs

@@ -20,8 +20,11 @@ var llm_exports = {};
 __export(llm_exports, {
   chat: () => chat,
   describeChat: () => describeChat,
+  describeChatState: () => describeChatState,
   onChatProviderChange: () => onChatProviderChange,
-  useChatProvider: () => useChatProvider
+  onChatProviderStateChange: () => onChatProviderStateChange,
+  useChatProvider: () => useChatProvider,
+  useChatProviderState: () => useChatProviderState
 });
 module.exports = __toCommonJS(llm_exports);
 var import_catalog = require("./catalog");
@@ -35,20 +38,32 @@ function chat(req) {
     signal
   );
 }
+let answered = false;
 const channel = (0, import_pushChannel.createPushChannel)({
   pushType: import_protocol.LLM_PROVIDER,
   requestType: import_protocol.REQUEST_LLM_PROVIDER,
   initial: null,
-  parse: (msg) => "provider" in msg ? msg.provider : void 0
+  parse: (msg) => {
+    if (!("provider" in msg)) return void 0;
+    answered = true;
+    return msg.provider ?? null;
+  }
 });
+const stateOf = (provider) => !answered ? { status: "unknown" } : provider ? { status: "configured", provider } : { status: "not-configured" };
 const describeChat = () => channel.get();
+const describeChatState = () => stateOf(channel.get());
 const onChatProviderChange = (listener) => channel.onChange(listener);
+const onChatProviderStateChange = (listener) => channel.onChange((p) => listener(stateOf(p)));
 const useChatProvider = () => channel.use();
+const useChatProviderState = () => stateOf(channel.use());
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   chat,
   describeChat,
+  describeChatState,
   onChatProviderChange,
-  useChatProvider
+  onChatProviderStateChange,
+  useChatProvider,
+  useChatProviderState
 });
 //# sourceMappingURL=llm.cjs.map

package/dist/llm.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/llm.ts"],"sourcesContent":["// Provider-agnostic LLM chat — the `llm.chat@1` slot (SERVICE_PROVIDERS_SPEC;\n// LLM_AND_AGENTS_SPEC §8 D5).\n//\n// An app calls ONE chat slot and never worries about which provider the user has a\n// key for: the HOST resolves which vendor answers from the key the user holds\n// (`SecretView.boundOrigin`) plus their `preferredImplementation` choice, normalizes\n// the wire format, injects the key host-side at the §6 net:fetch point (the\n// look-at-nothing proxy), and streams normalized deltas back. The app never names a\n// vendor, never sees the key, and needs NO `net:fetch`/`secrets` grant of its own —\n// only the `llm:chat` capability (elevated, app-scoped: a fork earns it by consent).\n//\n// Inert until the host implements `protocol-llm` (the `chat` stream) + the\n// `llm-provider` describe channel; the contract ships here so apps (the file-explorer\n// summarize fork) can be written against it — exactly how `secrets.ts` shipped ahead\n// of `protocol-secrets`.\nimport { invokeStream } from './catalog';\nimport { createPushChannel } from './pushChannel';\nimport { LLM_PROVIDER, REQUEST_LLM_PROVIDER } from './generated/protocol';\n\n/** Who authored a {@link ChatMessage}. */\nexport type ChatRole = 'system' | 'user' | 'assistant' | 'tool';\n\n/** A part of a message. `image` is only honored when the resolved provider\n *  advertises `features.vision` (§2.5); `tool-use`/`tool-result` only when it\n *  advertises `features.tools` — branch on {@link describeChat} first. */\nexport type ContentPart =\n  | { type: 'text'; text: string }\n  | { type: 'image'; mimeType: string; data: string } // data: base64, no data: URL prefix\n  // A tool call the model emitted on a prior `assistant` turn — replay it in the\n  // conversation so a follow-up request carries the agentic history. Pairs with the\n  // streamed `tool-call` {@link ChatDelta} that first surfaced it.\n  | { type: 'tool-use'; id: string; name: string; input: Record<string, unknown> }\n  // The result of executing a `tool-use`, fed back so the model can continue. Carried\n  // on a `user`/`tool`-role message; `toolCallId` matches the `tool-use` `id`.\n  | { type: 'tool-result'; toolCallId: string; content: string; isError?: boolean };\n\n/** One message in a {@link ChatRequest}: a role plus its content parts. */\nexport interface ChatMessage {\n  role: ChatRole;\n  content: ContentPart[];\n}\n\n/** A tool the model may call — honored only when `features.tools`. */\nexport interface ToolDef {\n  name: string;\n  description?: string;\n  /** JSON-Schema for the tool's arguments. */\n  inputSchema: Record<string, unknown>;\n}\n\n/** A host-brokered chat completion request: the messages plus optional tools,\n *  response format, and model hint (each honored per the provider's features). */\nexport interface ChatRequest {\n  messages: ChatMessage[];\n  /** Honored only when the resolved provider advertises `features.tools`. */\n  tools?: ToolDef[];\n  /** `'json'` honored only when `features.jsonMode`. Defaults to `'text'`. */\n  responseFormat?: 'text' | 'json';\n  maxTokens?: number;\n  /** An ABSTRACT tier hint, never a vendor model id — the host maps it to a concrete\n   *  model on the resolved provider. Omit to take the provider's default. */\n  modelHint?: 'fast' | 'smart';\n  /** Abort the completion mid-stream. When it fires, the SDK sends the host a cancel\n   *  frame so the host aborts the upstream provider request and STOPS BILLING the\n   *  user's key — not merely stops the app-side iterator (LLM_AND_AGENTS_SPEC §3.3\n   *  \"abort the in-flight LLM request\", R3-224). Not sent over the wire (an\n   *  `AbortSignal` isn't serializable); handled SDK-side. */\n  signal?: AbortSignal;\n}\n\n/** One streamed chunk. Consumers typically accumulate `text-delta`s. */\nexport type ChatDelta =\n  | { type: 'text-delta'; text: string }\n  | { type: 'tool-call'; id: string; name: string; input: unknown }\n  | { type: 'usage'; inputTokens: number; outputTokens: number };\n\n/** Why generation stopped: natural `end`, `length` cap, a `tool` call, or content `filtered`. */\nexport type ChatStopReason = 'end' | 'length' | 'tool' | 'filtered';\n\n/** The terminal value of the {@link chat} stream. */\nexport interface ChatResult {\n  stopReason: ChatStopReason;\n}\n\n/**\n * Stream a chat completion from whichever provider the user has configured.\n *\n * ```ts\n * let summary = '';\n * for await (const d of chat({ messages: [{ role: 'user', content: [{ type: 'text', text }] }] })) {\n *   if (d.type === 'text-delta') summary += d.text;\n * }\n * ```\n *\n * Requires the `llm:chat` capability. If no provider is bound the host fails the\n * stream into the SP-7 connect-me prompt (the user adds a key) — the generator\n * throws with `code: 'auth-required'`; an un-granted call throws `forbidden`.\n */\nexport function chat(req: ChatRequest): AsyncGenerator<ChatDelta, ChatResult, void> {\n  // Peel `signal` out of the request before it becomes wire params — an AbortSignal\n  // can't cross the postMessage boundary as data; it drives the SDK-side cancel frame.\n  const { signal, ...params } = req;\n  return invokeStream<ChatDelta, ChatResult>(\n    'llm:chat',\n    params as unknown as Record<string, unknown>,\n    signal,\n  );\n}\n\n/** The resolved provider's advertised abilities (SERVICE_PROVIDERS_SPEC §2.5) — read\n *  to branch/degrade (offer image upload only when `vision`). */\nexport interface ChatFeatures {\n  vision: boolean;\n  tools: boolean;\n  jsonMode: boolean;\n  maxContextTokens: number;\n}\n\n/** Info about the provider the host resolved for this app. `null` when no provider\n *  is bound (SP-7: prompt the user to add a key before calling {@link chat}). */\nexport interface ChatProviderInfo {\n  /** Opaque provider id, e.g. `llm.chat.anthropic` — never a vendor secret or model id. */\n  providerId: string;\n  /** True for Host-proxied providers (host-vouched, SP-9); false for app-level ones,\n   *  whose `features` are an untrusted claim. */\n  hostVouched: boolean;\n  features: ChatFeatures;\n}\n\n// The `llm-provider` describe channel (Recipe A): the host pushes the resolved\n// provider info on change and replays it on register-frame, gated by `llm:chat`.\n// A message with no `provider` key is ignored; an explicit `null` means \"no provider\n// bound\" (distinct from \"not yet answered\", which keeps the `initial` null).\nconst channel = createPushChannel<ChatProviderInfo | null>({\n  pushType: LLM_PROVIDER,\n  requestType: REQUEST_LLM_PROVIDER,\n  initial: null,\n  parse: (msg) =>\n    'provider' in msg ? (msg.provider as ChatProviderInfo | null) : undefined,\n});\n\n/** The provider the host resolved for this app (or `null` if none bound). Poll for a\n *  one-off read; use {@link onChatProviderChange}/{@link useChatProvider} to react. */\nexport const describeChat = (): ChatProviderInfo | null => channel.get();\n\n/** Subscribe to provider changes (key added/revoked, preference changed). Invoked\n *  immediately with the current value, then on every change. Returns unsubscribe. */\nexport const onChatProviderChange = (\n  listener: (provider: ChatProviderInfo | null) => void,\n): (() => void) => channel.onChange(listener);\n\n/** React hook returning the resolved chat provider (or `null`), re-rendering on\n *  change — gate the summarize affordance on `provider !== null`. */\nexport const useChatProvider = (): ChatProviderInfo | null => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAeA,qBAA6B;AAC7B,yBAAkC;AAClC,sBAAmD;AAiF5C,SAAS,KAAK,KAA+D;AAGlF,QAAM,EAAE,QAAQ,GAAG,OAAO,IAAI;AAC9B,aAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AA0BA,MAAM,cAAU,sCAA2C;AAAA,EACzD,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QACN,cAAc,MAAO,IAAI,WAAuC;AACpE,CAAC;AAIM,MAAM,eAAe,MAA+B,QAAQ,IAAI;AAIhE,MAAM,uBAAuB,CAClC,aACiB,QAAQ,SAAS,QAAQ;AAIrC,MAAM,kBAAkB,MAA+B,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/llm.ts"],"sourcesContent":["// Provider-agnostic LLM chat — the `llm.chat@1` slot (SERVICE_PROVIDERS_SPEC;\n// LLM_AND_AGENTS_SPEC §8 D5).\n//\n// An app calls ONE chat slot and never worries about which provider the user has a\n// key for: the HOST resolves which vendor answers from the key the user holds\n// (`SecretView.boundOrigin`) plus their `preferredImplementation` choice, normalizes\n// the wire format, injects the key host-side at the §6 net:fetch point (the\n// look-at-nothing proxy), and streams normalized deltas back. The app never names a\n// vendor, never sees the key, and needs NO `net:fetch`/`secrets` grant of its own —\n// only the `llm:chat` capability (elevated, app-scoped: a fork earns it by consent).\n//\n// Inert until the host implements `protocol-llm` (the `chat` stream) + the\n// `llm-provider` describe channel; the contract ships here so apps (the file-explorer\n// summarize fork) can be written against it — exactly how `secrets.ts` shipped ahead\n// of `protocol-secrets`.\nimport { invokeStream } from './catalog';\nimport { createPushChannel } from './pushChannel';\nimport { LLM_PROVIDER, REQUEST_LLM_PROVIDER } from './generated/protocol';\n\n/** Who authored a {@link ChatMessage}. */\nexport type ChatRole = 'system' | 'user' | 'assistant' | 'tool';\n\n/** A part of a message. `image` is only honored when the resolved provider\n *  advertises `features.vision` (§2.5); `tool-use`/`tool-result` only when it\n *  advertises `features.tools` — branch on {@link describeChat} first. */\nexport type ContentPart =\n  | { type: 'text'; text: string }\n  | { type: 'image'; mimeType: string; data: string } // data: base64, no data: URL prefix\n  // A tool call the model emitted on a prior `assistant` turn — replay it in the\n  // conversation so a follow-up request carries the agentic history. Pairs with the\n  // streamed `tool-call` {@link ChatDelta} that first surfaced it.\n  | { type: 'tool-use'; id: string; name: string; input: Record<string, unknown> }\n  // The result of executing a `tool-use`, fed back so the model can continue. Carried\n  // on a `user`/`tool`-role message; `toolCallId` matches the `tool-use` `id`.\n  | { type: 'tool-result'; toolCallId: string; content: string; isError?: boolean };\n\n/** One message in a {@link ChatRequest}: a role plus its content parts. */\nexport interface ChatMessage {\n  role: ChatRole;\n  content: ContentPart[];\n}\n\n/** A tool the model may call — honored only when `features.tools`. */\nexport interface ToolDef {\n  name: string;\n  description?: string;\n  /** JSON-Schema for the tool's arguments. */\n  inputSchema: Record<string, unknown>;\n}\n\n/** A host-brokered chat completion request: the messages plus optional tools,\n *  response format, and model hint (each honored per the provider's features). */\nexport interface ChatRequest {\n  messages: ChatMessage[];\n  /** Honored only when the resolved provider advertises `features.tools`. */\n  tools?: ToolDef[];\n  /** `'json'` honored only when `features.jsonMode`. Defaults to `'text'`. */\n  responseFormat?: 'text' | 'json';\n  maxTokens?: number;\n  /** An ABSTRACT tier hint, never a vendor model id — the host maps it to a concrete\n   *  model on the resolved provider. Omit to take the provider's default. */\n  modelHint?: 'fast' | 'smart';\n  /** Abort the completion mid-stream. When it fires, the SDK sends the host a cancel\n   *  frame so the host aborts the upstream provider request and STOPS BILLING the\n   *  user's key — not merely stops the app-side iterator (LLM_AND_AGENTS_SPEC §3.3\n   *  \"abort the in-flight LLM request\", R3-224). Not sent over the wire (an\n   *  `AbortSignal` isn't serializable); handled SDK-side. */\n  signal?: AbortSignal;\n}\n\n/** One streamed chunk. Consumers typically accumulate `text-delta`s. */\nexport type ChatDelta =\n  | { type: 'text-delta'; text: string }\n  | { type: 'tool-call'; id: string; name: string; input: unknown }\n  | { type: 'usage'; inputTokens: number; outputTokens: number };\n\n/** Why generation stopped: natural `end`, `length` cap, a `tool` call, or content `filtered`. */\nexport type ChatStopReason = 'end' | 'length' | 'tool' | 'filtered';\n\n/** The terminal value of the {@link chat} stream. */\nexport interface ChatResult {\n  stopReason: ChatStopReason;\n}\n\n/**\n * Stream a chat completion from whichever provider the user has configured.\n *\n * ```ts\n * let summary = '';\n * for await (const d of chat({ messages: [{ role: 'user', content: [{ type: 'text', text }] }] })) {\n *   if (d.type === 'text-delta') summary += d.text;\n * }\n * ```\n *\n * Requires the `llm:chat` capability. If no provider is bound the host fails the\n * stream into the SP-7 connect-me prompt (the user adds a key) — the generator\n * throws with `code: 'auth-required'`; an un-granted call throws `forbidden`.\n */\nexport function chat(req: ChatRequest): AsyncGenerator<ChatDelta, ChatResult, void> {\n  // Peel `signal` out of the request before it becomes wire params — an AbortSignal\n  // can't cross the postMessage boundary as data; it drives the SDK-side cancel frame.\n  const { signal, ...params } = req;\n  return invokeStream<ChatDelta, ChatResult>(\n    'llm:chat',\n    params as unknown as Record<string, unknown>,\n    signal,\n  );\n}\n\n/** The resolved provider's advertised abilities (SERVICE_PROVIDERS_SPEC §2.5) — read\n *  to branch/degrade (offer image upload only when `vision`). */\nexport interface ChatFeatures {\n  vision: boolean;\n  tools: boolean;\n  jsonMode: boolean;\n  maxContextTokens: number;\n}\n\n/** Info about the provider the host resolved for this app. `null` when no provider\n *  is bound (SP-7: prompt the user to add a key before calling {@link chat}). */\nexport interface ChatProviderInfo {\n  /** Opaque provider id, e.g. `llm.chat.anthropic` — never a vendor secret or model id. */\n  providerId: string;\n  /** True for Host-proxied providers (host-vouched, SP-9); false for app-level ones,\n   *  whose `features` are an untrusted claim. */\n  hostVouched: boolean;\n  features: ChatFeatures;\n  // NOTE (R3-300): `displayName`, `executor` and the resolved per-tier `models` belong\n  // here — an app rendering provider state wants all three. They are NOT added yet,\n  // deliberately: this interface IS the `llm-provider` channel's declared value, so\n  // adding a field is a WIRE change, and the wire is owned by\n  // `@immediately-run/sandbox-protocol` (descriptor edit → publish → pin bump on both\n  // sides). The protocol snapshot gate enforces exactly that, and it is right to. The\n  // enrichment rides R3-307's publish, which already has to touch those descriptors —\n  // one publish for two additions rather than two.\n}\n\n/**\n * Whether the host has told us about a provider yet, and if so whether one is bound.\n *\n * THREE states, because two is the bug (R3-300). `describeChat()` returns `null` both\n * when no provider is configured AND when the channel has not answered — so an app\n * cannot tell \"you need a key\" from \"ask again in a moment\", and consuming apps\n * rendered a misleading \"connect a key\" banner at users who had one. `unknown` is the\n * state before the host answers; it is not an error and not a prompt to act.\n */\nexport type ChatProviderState =\n  | { status: 'unknown' }\n  | { status: 'not-configured' }\n  | { status: 'configured'; provider: ChatProviderInfo };\n\n// The `llm-provider` describe channel (Recipe A): the host pushes the resolved\n// provider info on change and replays it on register-frame, gated by `llm:chat`.\n// A message with no `provider` key is ignored; an explicit `null` means \"no provider\n// bound\", which is now REPRESENTABLE as distinct from \"not yet answered\".\n// The channel's VALUE stays exactly what the wire carries — `ChatProviderInfo | null` —\n// because the wire did not change here and the protocol snapshot gate reads this type as\n// the channel's shape. The three-state lives BESIDE it: `answered` records whether the host\n// has ever spoken on this channel, which is the one bit `null` cannot carry. Deriving the\n// state rather than widening the channel keeps the wire contract byte-identical, which it\n// is (SDK_PACKAGING_SPEC §9: the wire is additive-only, and this is not a wire change).\nlet answered = false;\nconst channel = createPushChannel<ChatProviderInfo | null>({\n  pushType: LLM_PROVIDER,\n  requestType: REQUEST_LLM_PROVIDER,\n  initial: null,\n  parse: (msg) => {\n    if (!('provider' in msg)) return undefined;\n    answered = true;\n    return (msg.provider as ChatProviderInfo | null) ?? null;\n  },\n});\n\n/** Derive the three-state from the wire value plus whether the host has answered. */\nconst stateOf = (provider: ChatProviderInfo | null): ChatProviderState =>\n  !answered ? { status: 'unknown' } : provider ? { status: 'configured', provider } : { status: 'not-configured' };\n\n/**\n * The provider the host resolved for this app, or `null`.\n *\n * Kept for compatibility (`ways_of_working §6`, additive-only): it collapses `unknown`\n * and `not-configured` to `null`. Prefer {@link describeChatState} when the difference\n * matters — which is any time you would render \"connect a key\", because doing that in\n * the `unknown` state is exactly the false banner R3-300 fixes.\n */\nexport const describeChat = (): ChatProviderInfo | null => channel.get();\n\n/** The three-state read: `unknown` before the host answers, then configured or not. */\nexport const describeChatState = (): ChatProviderState => stateOf(channel.get());\n\n/** Subscribe to provider changes (key added/revoked, preference changed). Invoked\n *  immediately with the current value, then on every change. Returns unsubscribe. */\nexport const onChatProviderChange = (\n  listener: (provider: ChatProviderInfo | null) => void,\n): (() => void) => channel.onChange(listener);\n\n/** Subscribe to the three-state provider description. */\nexport const onChatProviderStateChange = (\n  listener: (state: ChatProviderState) => void,\n): (() => void) => channel.onChange((p) => listener(stateOf(p)));\n\n/** React hook returning the resolved chat provider (or `null`), re-rendering on\n *  change — gate the summarize affordance on `provider !== null`. */\nexport const useChatProvider = (): ChatProviderInfo | null => channel.use();\n\n/**\n * React hook returning the three-state description.\n *\n * Use this to render provider state honestly: show nothing (or a neutral placeholder)\n * while `unknown`, the connect affordance only on `not-configured`, and the provider's\n * name on `configured`.\n */\nexport const useChatProviderState = (): ChatProviderState => stateOf(channel.use());\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAeA,qBAA6B;AAC7B,yBAAkC;AAClC,sBAAmD;AAiF5C,SAAS,KAAK,KAA+D;AAGlF,QAAM,EAAE,QAAQ,GAAG,OAAO,IAAI;AAC9B,aAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAsDA,IAAI,WAAW;AACf,MAAM,cAAU,sCAA2C;AAAA,EACzD,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ;AACd,QAAI,EAAE,cAAc,KAAM,QAAO;AACjC,eAAW;AACX,WAAQ,IAAI,YAAwC;AAAA,EACtD;AACF,CAAC;AAGD,MAAM,UAAU,CAAC,aACf,CAAC,WAAW,EAAE,QAAQ,UAAU,IAAI,WAAW,EAAE,QAAQ,cAAc,SAAS,IAAI,EAAE,QAAQ,iBAAiB;AAU1G,MAAM,eAAe,MAA+B,QAAQ,IAAI;AAGhE,MAAM,oBAAoB,MAAyB,QAAQ,QAAQ,IAAI,CAAC;AAIxE,MAAM,uBAAuB,CAClC,aACiB,QAAQ,SAAS,QAAQ;AAGrC,MAAM,4BAA4B,CACvC,aACiB,QAAQ,SAAS,CAAC,MAAM,SAAS,QAAQ,CAAC,CAAC,CAAC;AAIxD,MAAM,kBAAkB,MAA+B,QAAQ,IAAI;AASnE,MAAM,uBAAuB,MAAyB,QAAQ,QAAQ,IAAI,CAAC;","names":[]}

package/dist/llm.d.cts

@@ -105,14 +105,49 @@ interface ChatProviderInfo {
     hostVouched: boolean;
     features: ChatFeatures;
 }
-/** The provider the host resolved for this app (or `null` if none bound). Poll for a
- *  one-off read; use {@link onChatProviderChange}/{@link useChatProvider} to react. */
+/**
+ * Whether the host has told us about a provider yet, and if so whether one is bound.
+ *
+ * THREE states, because two is the bug (R3-300). `describeChat()` returns `null` both
+ * when no provider is configured AND when the channel has not answered — so an app
+ * cannot tell "you need a key" from "ask again in a moment", and consuming apps
+ * rendered a misleading "connect a key" banner at users who had one. `unknown` is the
+ * state before the host answers; it is not an error and not a prompt to act.
+ */
+type ChatProviderState = {
+    status: 'unknown';
+} | {
+    status: 'not-configured';
+} | {
+    status: 'configured';
+    provider: ChatProviderInfo;
+};
+/**
+ * The provider the host resolved for this app, or `null`.
+ *
+ * Kept for compatibility (`ways_of_working §6`, additive-only): it collapses `unknown`
+ * and `not-configured` to `null`. Prefer {@link describeChatState} when the difference
+ * matters — which is any time you would render "connect a key", because doing that in
+ * the `unknown` state is exactly the false banner R3-300 fixes.
+ */
 declare const describeChat: () => ChatProviderInfo | null;
+/** The three-state read: `unknown` before the host answers, then configured or not. */
+declare const describeChatState: () => ChatProviderState;
 /** Subscribe to provider changes (key added/revoked, preference changed). Invoked
  *  immediately with the current value, then on every change. Returns unsubscribe. */
 declare const onChatProviderChange: (listener: (provider: ChatProviderInfo | null) => void) => (() => void);
+/** Subscribe to the three-state provider description. */
+declare const onChatProviderStateChange: (listener: (state: ChatProviderState) => void) => (() => void);
 /** React hook returning the resolved chat provider (or `null`), re-rendering on
  *  change — gate the summarize affordance on `provider !== null`. */
 declare const useChatProvider: () => ChatProviderInfo | null;
+/**
+ * React hook returning the three-state description.
+ *
+ * Use this to render provider state honestly: show nothing (or a neutral placeholder)
+ * while `unknown`, the connect affordance only on `not-configured`, and the provider's
+ * name on `configured`.
+ */
+declare const useChatProviderState: () => ChatProviderState;
 
-export { type ChatDelta, type ChatFeatures, type ChatMessage, type ChatProviderInfo, type ChatRequest, type ChatResult, type ChatRole, type ChatStopReason, type ContentPart, type ToolDef, chat, describeChat, onChatProviderChange, useChatProvider };
+export { type ChatDelta, type ChatFeatures, type ChatMessage, type ChatProviderInfo, type ChatProviderState, type ChatRequest, type ChatResult, type ChatRole, type ChatStopReason, type ContentPart, type ToolDef, chat, describeChat, describeChatState, onChatProviderChange, onChatProviderStateChange, useChatProvider, useChatProviderState };

package/dist/llm.d.ts

@@ -105,14 +105,49 @@ interface ChatProviderInfo {
     hostVouched: boolean;
     features: ChatFeatures;
 }
-/** The provider the host resolved for this app (or `null` if none bound). Poll for a
- *  one-off read; use {@link onChatProviderChange}/{@link useChatProvider} to react. */
+/**
+ * Whether the host has told us about a provider yet, and if so whether one is bound.
+ *
+ * THREE states, because two is the bug (R3-300). `describeChat()` returns `null` both
+ * when no provider is configured AND when the channel has not answered — so an app
+ * cannot tell "you need a key" from "ask again in a moment", and consuming apps
+ * rendered a misleading "connect a key" banner at users who had one. `unknown` is the
+ * state before the host answers; it is not an error and not a prompt to act.
+ */
+type ChatProviderState = {
+    status: 'unknown';
+} | {
+    status: 'not-configured';
+} | {
+    status: 'configured';
+    provider: ChatProviderInfo;
+};
+/**
+ * The provider the host resolved for this app, or `null`.
+ *
+ * Kept for compatibility (`ways_of_working §6`, additive-only): it collapses `unknown`
+ * and `not-configured` to `null`. Prefer {@link describeChatState} when the difference
+ * matters — which is any time you would render "connect a key", because doing that in
+ * the `unknown` state is exactly the false banner R3-300 fixes.
+ */
 declare const describeChat: () => ChatProviderInfo | null;
+/** The three-state read: `unknown` before the host answers, then configured or not. */
+declare const describeChatState: () => ChatProviderState;
 /** Subscribe to provider changes (key added/revoked, preference changed). Invoked
  *  immediately with the current value, then on every change. Returns unsubscribe. */
 declare const onChatProviderChange: (listener: (provider: ChatProviderInfo | null) => void) => (() => void);
+/** Subscribe to the three-state provider description. */
+declare const onChatProviderStateChange: (listener: (state: ChatProviderState) => void) => (() => void);
 /** React hook returning the resolved chat provider (or `null`), re-rendering on
  *  change — gate the summarize affordance on `provider !== null`. */
 declare const useChatProvider: () => ChatProviderInfo | null;
+/**
+ * React hook returning the three-state description.
+ *
+ * Use this to render provider state honestly: show nothing (or a neutral placeholder)
+ * while `unknown`, the connect affordance only on `not-configured`, and the provider's
+ * name on `configured`.
+ */
+declare const useChatProviderState: () => ChatProviderState;
 
-export { type ChatDelta, type ChatFeatures, type ChatMessage, type ChatProviderInfo, type ChatRequest, type ChatResult, type ChatRole, type ChatStopReason, type ContentPart, type ToolDef, chat, describeChat, onChatProviderChange, useChatProvider };
+export { type ChatDelta, type ChatFeatures, type ChatMessage, type ChatProviderInfo, type ChatProviderState, type ChatRequest, type ChatResult, type ChatRole, type ChatStopReason, type ContentPart, type ToolDef, chat, describeChat, describeChatState, onChatProviderChange, onChatProviderStateChange, useChatProvider, useChatProviderState };

package/dist/llm.js

@@ -10,19 +10,31 @@ function chat(req) {
     signal
   );
 }
+let answered = false;
 const channel = createPushChannel({
   pushType: LLM_PROVIDER,
   requestType: REQUEST_LLM_PROVIDER,
   initial: null,
-  parse: (msg) => "provider" in msg ? msg.provider : void 0
+  parse: (msg) => {
+    if (!("provider" in msg)) return void 0;
+    answered = true;
+    return msg.provider ?? null;
+  }
 });
+const stateOf = (provider) => !answered ? { status: "unknown" } : provider ? { status: "configured", provider } : { status: "not-configured" };
 const describeChat = () => channel.get();
+const describeChatState = () => stateOf(channel.get());
 const onChatProviderChange = (listener) => channel.onChange(listener);
+const onChatProviderStateChange = (listener) => channel.onChange((p) => listener(stateOf(p)));
 const useChatProvider = () => channel.use();
+const useChatProviderState = () => stateOf(channel.use());
 export {
   chat,
   describeChat,
+  describeChatState,
   onChatProviderChange,
-  useChatProvider
+  onChatProviderStateChange,
+  useChatProvider,
+  useChatProviderState
 };
 //# sourceMappingURL=llm.js.map

package/dist/llm.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/llm.ts"],"sourcesContent":["// Provider-agnostic LLM chat — the `llm.chat@1` slot (SERVICE_PROVIDERS_SPEC;\n// LLM_AND_AGENTS_SPEC §8 D5).\n//\n// An app calls ONE chat slot and never worries about which provider the user has a\n// key for: the HOST resolves which vendor answers from the key the user holds\n// (`SecretView.boundOrigin`) plus their `preferredImplementation` choice, normalizes\n// the wire format, injects the key host-side at the §6 net:fetch point (the\n// look-at-nothing proxy), and streams normalized deltas back. The app never names a\n// vendor, never sees the key, and needs NO `net:fetch`/`secrets` grant of its own —\n// only the `llm:chat` capability (elevated, app-scoped: a fork earns it by consent).\n//\n// Inert until the host implements `protocol-llm` (the `chat` stream) + the\n// `llm-provider` describe channel; the contract ships here so apps (the file-explorer\n// summarize fork) can be written against it — exactly how `secrets.ts` shipped ahead\n// of `protocol-secrets`.\nimport { invokeStream } from './catalog';\nimport { createPushChannel } from './pushChannel';\nimport { LLM_PROVIDER, REQUEST_LLM_PROVIDER } from './generated/protocol';\n\n/** Who authored a {@link ChatMessage}. */\nexport type ChatRole = 'system' | 'user' | 'assistant' | 'tool';\n\n/** A part of a message. `image` is only honored when the resolved provider\n *  advertises `features.vision` (§2.5); `tool-use`/`tool-result` only when it\n *  advertises `features.tools` — branch on {@link describeChat} first. */\nexport type ContentPart =\n  | { type: 'text'; text: string }\n  | { type: 'image'; mimeType: string; data: string } // data: base64, no data: URL prefix\n  // A tool call the model emitted on a prior `assistant` turn — replay it in the\n  // conversation so a follow-up request carries the agentic history. Pairs with the\n  // streamed `tool-call` {@link ChatDelta} that first surfaced it.\n  | { type: 'tool-use'; id: string; name: string; input: Record<string, unknown> }\n  // The result of executing a `tool-use`, fed back so the model can continue. Carried\n  // on a `user`/`tool`-role message; `toolCallId` matches the `tool-use` `id`.\n  | { type: 'tool-result'; toolCallId: string; content: string; isError?: boolean };\n\n/** One message in a {@link ChatRequest}: a role plus its content parts. */\nexport interface ChatMessage {\n  role: ChatRole;\n  content: ContentPart[];\n}\n\n/** A tool the model may call — honored only when `features.tools`. */\nexport interface ToolDef {\n  name: string;\n  description?: string;\n  /** JSON-Schema for the tool's arguments. */\n  inputSchema: Record<string, unknown>;\n}\n\n/** A host-brokered chat completion request: the messages plus optional tools,\n *  response format, and model hint (each honored per the provider's features). */\nexport interface ChatRequest {\n  messages: ChatMessage[];\n  /** Honored only when the resolved provider advertises `features.tools`. */\n  tools?: ToolDef[];\n  /** `'json'` honored only when `features.jsonMode`. Defaults to `'text'`. */\n  responseFormat?: 'text' | 'json';\n  maxTokens?: number;\n  /** An ABSTRACT tier hint, never a vendor model id — the host maps it to a concrete\n   *  model on the resolved provider. Omit to take the provider's default. */\n  modelHint?: 'fast' | 'smart';\n  /** Abort the completion mid-stream. When it fires, the SDK sends the host a cancel\n   *  frame so the host aborts the upstream provider request and STOPS BILLING the\n   *  user's key — not merely stops the app-side iterator (LLM_AND_AGENTS_SPEC §3.3\n   *  \"abort the in-flight LLM request\", R3-224). Not sent over the wire (an\n   *  `AbortSignal` isn't serializable); handled SDK-side. */\n  signal?: AbortSignal;\n}\n\n/** One streamed chunk. Consumers typically accumulate `text-delta`s. */\nexport type ChatDelta =\n  | { type: 'text-delta'; text: string }\n  | { type: 'tool-call'; id: string; name: string; input: unknown }\n  | { type: 'usage'; inputTokens: number; outputTokens: number };\n\n/** Why generation stopped: natural `end`, `length` cap, a `tool` call, or content `filtered`. */\nexport type ChatStopReason = 'end' | 'length' | 'tool' | 'filtered';\n\n/** The terminal value of the {@link chat} stream. */\nexport interface ChatResult {\n  stopReason: ChatStopReason;\n}\n\n/**\n * Stream a chat completion from whichever provider the user has configured.\n *\n * ```ts\n * let summary = '';\n * for await (const d of chat({ messages: [{ role: 'user', content: [{ type: 'text', text }] }] })) {\n *   if (d.type === 'text-delta') summary += d.text;\n * }\n * ```\n *\n * Requires the `llm:chat` capability. If no provider is bound the host fails the\n * stream into the SP-7 connect-me prompt (the user adds a key) — the generator\n * throws with `code: 'auth-required'`; an un-granted call throws `forbidden`.\n */\nexport function chat(req: ChatRequest): AsyncGenerator<ChatDelta, ChatResult, void> {\n  // Peel `signal` out of the request before it becomes wire params — an AbortSignal\n  // can't cross the postMessage boundary as data; it drives the SDK-side cancel frame.\n  const { signal, ...params } = req;\n  return invokeStream<ChatDelta, ChatResult>(\n    'llm:chat',\n    params as unknown as Record<string, unknown>,\n    signal,\n  );\n}\n\n/** The resolved provider's advertised abilities (SERVICE_PROVIDERS_SPEC §2.5) — read\n *  to branch/degrade (offer image upload only when `vision`). */\nexport interface ChatFeatures {\n  vision: boolean;\n  tools: boolean;\n  jsonMode: boolean;\n  maxContextTokens: number;\n}\n\n/** Info about the provider the host resolved for this app. `null` when no provider\n *  is bound (SP-7: prompt the user to add a key before calling {@link chat}). */\nexport interface ChatProviderInfo {\n  /** Opaque provider id, e.g. `llm.chat.anthropic` — never a vendor secret or model id. */\n  providerId: string;\n  /** True for Host-proxied providers (host-vouched, SP-9); false for app-level ones,\n   *  whose `features` are an untrusted claim. */\n  hostVouched: boolean;\n  features: ChatFeatures;\n}\n\n// The `llm-provider` describe channel (Recipe A): the host pushes the resolved\n// provider info on change and replays it on register-frame, gated by `llm:chat`.\n// A message with no `provider` key is ignored; an explicit `null` means \"no provider\n// bound\" (distinct from \"not yet answered\", which keeps the `initial` null).\nconst channel = createPushChannel<ChatProviderInfo | null>({\n  pushType: LLM_PROVIDER,\n  requestType: REQUEST_LLM_PROVIDER,\n  initial: null,\n  parse: (msg) =>\n    'provider' in msg ? (msg.provider as ChatProviderInfo | null) : undefined,\n});\n\n/** The provider the host resolved for this app (or `null` if none bound). Poll for a\n *  one-off read; use {@link onChatProviderChange}/{@link useChatProvider} to react. */\nexport const describeChat = (): ChatProviderInfo | null => channel.get();\n\n/** Subscribe to provider changes (key added/revoked, preference changed). Invoked\n *  immediately with the current value, then on every change. Returns unsubscribe. */\nexport const onChatProviderChange = (\n  listener: (provider: ChatProviderInfo | null) => void,\n): (() => void) => channel.onChange(listener);\n\n/** React hook returning the resolved chat provider (or `null`), re-rendering on\n *  change — gate the summarize affordance on `provider !== null`. */\nexport const useChatProvider = (): ChatProviderInfo | null => channel.use();\n"],"mappings":";AAeA,SAAS,oBAAoB;AAC7B,SAAS,yBAAyB;AAClC,SAAS,cAAc,4BAA4B;AAiF5C,SAAS,KAAK,KAA+D;AAGlF,QAAM,EAAE,QAAQ,GAAG,OAAO,IAAI;AAC9B,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AA0BA,MAAM,UAAU,kBAA2C;AAAA,EACzD,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QACN,cAAc,MAAO,IAAI,WAAuC;AACpE,CAAC;AAIM,MAAM,eAAe,MAA+B,QAAQ,IAAI;AAIhE,MAAM,uBAAuB,CAClC,aACiB,QAAQ,SAAS,QAAQ;AAIrC,MAAM,kBAAkB,MAA+B,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/llm.ts"],"sourcesContent":["// Provider-agnostic LLM chat — the `llm.chat@1` slot (SERVICE_PROVIDERS_SPEC;\n// LLM_AND_AGENTS_SPEC §8 D5).\n//\n// An app calls ONE chat slot and never worries about which provider the user has a\n// key for: the HOST resolves which vendor answers from the key the user holds\n// (`SecretView.boundOrigin`) plus their `preferredImplementation` choice, normalizes\n// the wire format, injects the key host-side at the §6 net:fetch point (the\n// look-at-nothing proxy), and streams normalized deltas back. The app never names a\n// vendor, never sees the key, and needs NO `net:fetch`/`secrets` grant of its own —\n// only the `llm:chat` capability (elevated, app-scoped: a fork earns it by consent).\n//\n// Inert until the host implements `protocol-llm` (the `chat` stream) + the\n// `llm-provider` describe channel; the contract ships here so apps (the file-explorer\n// summarize fork) can be written against it — exactly how `secrets.ts` shipped ahead\n// of `protocol-secrets`.\nimport { invokeStream } from './catalog';\nimport { createPushChannel } from './pushChannel';\nimport { LLM_PROVIDER, REQUEST_LLM_PROVIDER } from './generated/protocol';\n\n/** Who authored a {@link ChatMessage}. */\nexport type ChatRole = 'system' | 'user' | 'assistant' | 'tool';\n\n/** A part of a message. `image` is only honored when the resolved provider\n *  advertises `features.vision` (§2.5); `tool-use`/`tool-result` only when it\n *  advertises `features.tools` — branch on {@link describeChat} first. */\nexport type ContentPart =\n  | { type: 'text'; text: string }\n  | { type: 'image'; mimeType: string; data: string } // data: base64, no data: URL prefix\n  // A tool call the model emitted on a prior `assistant` turn — replay it in the\n  // conversation so a follow-up request carries the agentic history. Pairs with the\n  // streamed `tool-call` {@link ChatDelta} that first surfaced it.\n  | { type: 'tool-use'; id: string; name: string; input: Record<string, unknown> }\n  // The result of executing a `tool-use`, fed back so the model can continue. Carried\n  // on a `user`/`tool`-role message; `toolCallId` matches the `tool-use` `id`.\n  | { type: 'tool-result'; toolCallId: string; content: string; isError?: boolean };\n\n/** One message in a {@link ChatRequest}: a role plus its content parts. */\nexport interface ChatMessage {\n  role: ChatRole;\n  content: ContentPart[];\n}\n\n/** A tool the model may call — honored only when `features.tools`. */\nexport interface ToolDef {\n  name: string;\n  description?: string;\n  /** JSON-Schema for the tool's arguments. */\n  inputSchema: Record<string, unknown>;\n}\n\n/** A host-brokered chat completion request: the messages plus optional tools,\n *  response format, and model hint (each honored per the provider's features). */\nexport interface ChatRequest {\n  messages: ChatMessage[];\n  /** Honored only when the resolved provider advertises `features.tools`. */\n  tools?: ToolDef[];\n  /** `'json'` honored only when `features.jsonMode`. Defaults to `'text'`. */\n  responseFormat?: 'text' | 'json';\n  maxTokens?: number;\n  /** An ABSTRACT tier hint, never a vendor model id — the host maps it to a concrete\n   *  model on the resolved provider. Omit to take the provider's default. */\n  modelHint?: 'fast' | 'smart';\n  /** Abort the completion mid-stream. When it fires, the SDK sends the host a cancel\n   *  frame so the host aborts the upstream provider request and STOPS BILLING the\n   *  user's key — not merely stops the app-side iterator (LLM_AND_AGENTS_SPEC §3.3\n   *  \"abort the in-flight LLM request\", R3-224). Not sent over the wire (an\n   *  `AbortSignal` isn't serializable); handled SDK-side. */\n  signal?: AbortSignal;\n}\n\n/** One streamed chunk. Consumers typically accumulate `text-delta`s. */\nexport type ChatDelta =\n  | { type: 'text-delta'; text: string }\n  | { type: 'tool-call'; id: string; name: string; input: unknown }\n  | { type: 'usage'; inputTokens: number; outputTokens: number };\n\n/** Why generation stopped: natural `end`, `length` cap, a `tool` call, or content `filtered`. */\nexport type ChatStopReason = 'end' | 'length' | 'tool' | 'filtered';\n\n/** The terminal value of the {@link chat} stream. */\nexport interface ChatResult {\n  stopReason: ChatStopReason;\n}\n\n/**\n * Stream a chat completion from whichever provider the user has configured.\n *\n * ```ts\n * let summary = '';\n * for await (const d of chat({ messages: [{ role: 'user', content: [{ type: 'text', text }] }] })) {\n *   if (d.type === 'text-delta') summary += d.text;\n * }\n * ```\n *\n * Requires the `llm:chat` capability. If no provider is bound the host fails the\n * stream into the SP-7 connect-me prompt (the user adds a key) — the generator\n * throws with `code: 'auth-required'`; an un-granted call throws `forbidden`.\n */\nexport function chat(req: ChatRequest): AsyncGenerator<ChatDelta, ChatResult, void> {\n  // Peel `signal` out of the request before it becomes wire params — an AbortSignal\n  // can't cross the postMessage boundary as data; it drives the SDK-side cancel frame.\n  const { signal, ...params } = req;\n  return invokeStream<ChatDelta, ChatResult>(\n    'llm:chat',\n    params as unknown as Record<string, unknown>,\n    signal,\n  );\n}\n\n/** The resolved provider's advertised abilities (SERVICE_PROVIDERS_SPEC §2.5) — read\n *  to branch/degrade (offer image upload only when `vision`). */\nexport interface ChatFeatures {\n  vision: boolean;\n  tools: boolean;\n  jsonMode: boolean;\n  maxContextTokens: number;\n}\n\n/** Info about the provider the host resolved for this app. `null` when no provider\n *  is bound (SP-7: prompt the user to add a key before calling {@link chat}). */\nexport interface ChatProviderInfo {\n  /** Opaque provider id, e.g. `llm.chat.anthropic` — never a vendor secret or model id. */\n  providerId: string;\n  /** True for Host-proxied providers (host-vouched, SP-9); false for app-level ones,\n   *  whose `features` are an untrusted claim. */\n  hostVouched: boolean;\n  features: ChatFeatures;\n  // NOTE (R3-300): `displayName`, `executor` and the resolved per-tier `models` belong\n  // here — an app rendering provider state wants all three. They are NOT added yet,\n  // deliberately: this interface IS the `llm-provider` channel's declared value, so\n  // adding a field is a WIRE change, and the wire is owned by\n  // `@immediately-run/sandbox-protocol` (descriptor edit → publish → pin bump on both\n  // sides). The protocol snapshot gate enforces exactly that, and it is right to. The\n  // enrichment rides R3-307's publish, which already has to touch those descriptors —\n  // one publish for two additions rather than two.\n}\n\n/**\n * Whether the host has told us about a provider yet, and if so whether one is bound.\n *\n * THREE states, because two is the bug (R3-300). `describeChat()` returns `null` both\n * when no provider is configured AND when the channel has not answered — so an app\n * cannot tell \"you need a key\" from \"ask again in a moment\", and consuming apps\n * rendered a misleading \"connect a key\" banner at users who had one. `unknown` is the\n * state before the host answers; it is not an error and not a prompt to act.\n */\nexport type ChatProviderState =\n  | { status: 'unknown' }\n  | { status: 'not-configured' }\n  | { status: 'configured'; provider: ChatProviderInfo };\n\n// The `llm-provider` describe channel (Recipe A): the host pushes the resolved\n// provider info on change and replays it on register-frame, gated by `llm:chat`.\n// A message with no `provider` key is ignored; an explicit `null` means \"no provider\n// bound\", which is now REPRESENTABLE as distinct from \"not yet answered\".\n// The channel's VALUE stays exactly what the wire carries — `ChatProviderInfo | null` —\n// because the wire did not change here and the protocol snapshot gate reads this type as\n// the channel's shape. The three-state lives BESIDE it: `answered` records whether the host\n// has ever spoken on this channel, which is the one bit `null` cannot carry. Deriving the\n// state rather than widening the channel keeps the wire contract byte-identical, which it\n// is (SDK_PACKAGING_SPEC §9: the wire is additive-only, and this is not a wire change).\nlet answered = false;\nconst channel = createPushChannel<ChatProviderInfo | null>({\n  pushType: LLM_PROVIDER,\n  requestType: REQUEST_LLM_PROVIDER,\n  initial: null,\n  parse: (msg) => {\n    if (!('provider' in msg)) return undefined;\n    answered = true;\n    return (msg.provider as ChatProviderInfo | null) ?? null;\n  },\n});\n\n/** Derive the three-state from the wire value plus whether the host has answered. */\nconst stateOf = (provider: ChatProviderInfo | null): ChatProviderState =>\n  !answered ? { status: 'unknown' } : provider ? { status: 'configured', provider } : { status: 'not-configured' };\n\n/**\n * The provider the host resolved for this app, or `null`.\n *\n * Kept for compatibility (`ways_of_working §6`, additive-only): it collapses `unknown`\n * and `not-configured` to `null`. Prefer {@link describeChatState} when the difference\n * matters — which is any time you would render \"connect a key\", because doing that in\n * the `unknown` state is exactly the false banner R3-300 fixes.\n */\nexport const describeChat = (): ChatProviderInfo | null => channel.get();\n\n/** The three-state read: `unknown` before the host answers, then configured or not. */\nexport const describeChatState = (): ChatProviderState => stateOf(channel.get());\n\n/** Subscribe to provider changes (key added/revoked, preference changed). Invoked\n *  immediately with the current value, then on every change. Returns unsubscribe. */\nexport const onChatProviderChange = (\n  listener: (provider: ChatProviderInfo | null) => void,\n): (() => void) => channel.onChange(listener);\n\n/** Subscribe to the three-state provider description. */\nexport const onChatProviderStateChange = (\n  listener: (state: ChatProviderState) => void,\n): (() => void) => channel.onChange((p) => listener(stateOf(p)));\n\n/** React hook returning the resolved chat provider (or `null`), re-rendering on\n *  change — gate the summarize affordance on `provider !== null`. */\nexport const useChatProvider = (): ChatProviderInfo | null => channel.use();\n\n/**\n * React hook returning the three-state description.\n *\n * Use this to render provider state honestly: show nothing (or a neutral placeholder)\n * while `unknown`, the connect affordance only on `not-configured`, and the provider's\n * name on `configured`.\n */\nexport const useChatProviderState = (): ChatProviderState => stateOf(channel.use());\n"],"mappings":";AAeA,SAAS,oBAAoB;AAC7B,SAAS,yBAAyB;AAClC,SAAS,cAAc,4BAA4B;AAiF5C,SAAS,KAAK,KAA+D;AAGlF,QAAM,EAAE,QAAQ,GAAG,OAAO,IAAI;AAC9B,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAsDA,IAAI,WAAW;AACf,MAAM,UAAU,kBAA2C;AAAA,EACzD,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ;AACd,QAAI,EAAE,cAAc,KAAM,QAAO;AACjC,eAAW;AACX,WAAQ,IAAI,YAAwC;AAAA,EACtD;AACF,CAAC;AAGD,MAAM,UAAU,CAAC,aACf,CAAC,WAAW,EAAE,QAAQ,UAAU,IAAI,WAAW,EAAE,QAAQ,cAAc,SAAS,IAAI,EAAE,QAAQ,iBAAiB;AAU1G,MAAM,eAAe,MAA+B,QAAQ,IAAI;AAGhE,MAAM,oBAAoB,MAAyB,QAAQ,QAAQ,IAAI,CAAC;AAIxE,MAAM,uBAAuB,CAClC,aACiB,QAAQ,SAAS,QAAQ;AAGrC,MAAM,4BAA4B,CACvC,aACiB,QAAQ,SAAS,CAAC,MAAM,SAAS,QAAQ,CAAC,CAAC,CAAC;AAIxD,MAAM,kBAAkB,MAA+B,QAAQ,IAAI;AASnE,MAAM,uBAAuB,MAAyB,QAAQ,QAAQ,IAAI,CAAC;","names":[]}

package/dist/protocolDeadline.cjs

@@ -0,0 +1,205 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var protocolDeadline_exports = {};
+__export(protocolDeadline_exports, {
+  ATTENDED_FIRST_FRAME_MS: () => ATTENDED_FIRST_FRAME_MS,
+  ATTENDED_TIMEOUT_MS: () => ATTENDED_TIMEOUT_MS,
+  NETWORK_TIMEOUT_MS: () => NETWORK_TIMEOUT_MS,
+  PENDING_NOTICE_MS: () => PENDING_NOTICE_MS,
+  ProtocolCancelledError: () => ProtocolCancelledError,
+  ProtocolTimeoutError: () => ProtocolTimeoutError,
+  STREAM_IDLE_TIMEOUT_MS: () => STREAM_IDLE_TIMEOUT_MS,
+  UNATTENDED_TIMEOUT_MS: () => UNATTENDED_TIMEOUT_MS,
+  attendanceOf: () => attendanceOf,
+  attendanceReason: () => attendanceReason,
+  boundsFor: () => boundsFor,
+  createSuspendableDeadline: () => createSuspendableDeadline,
+  firstFrameBoundsFor: () => firstFrameBoundsFor,
+  firstFrameTimeoutFor: () => firstFrameTimeoutFor,
+  timeoutFor: () => timeoutFor
+});
+module.exports = __toCommonJS(protocolDeadline_exports);
+const UNATTENDED_TIMEOUT_MS = 3e4;
+const NETWORK_TIMEOUT_MS = 12e4;
+const ATTENDED_TIMEOUT_MS = 6e5;
+const ATTENDED_FIRST_FRAME_MS = 3e5;
+const STREAM_IDLE_TIMEOUT_MS = 12e4;
+const PENDING_NOTICE_MS = 3e3;
+const ATTENDED = {
+  // The powerbox and the add-secret modal are host-drawn and wait for the user to type or
+  // pick; the first use of any stored secret additionally raises a WebAuthn assertion
+  // (SECRETS_SPEC §3 — one unlock per session, from a live gesture). All three are wrapped
+  // presenters, so the signal covers this scheme completely.
+  secrets: {
+    reason: "host-drawn key entry / picker, and the per-session passkey unlock",
+    idleMs: UNATTENDED_TIMEOUT_MS
+  },
+  // Consent is raised INSIDE the request: presentMountConsent, presentGrantPicker,
+  // presentCreateConsent, presentShareDisclosure, presentReferenceConsent — every one of
+  // them a wrapped presenter. Unattended once the grant is held, attended on first use, and
+  // since R3-307 the host says which of those is happening.
+  spaces: {
+    reason: "first-use mount/share/create consent is drawn inside the request",
+    idleMs: UNATTENDED_TIMEOUT_MS
+  },
+  settings: {
+    reason: "settings verbs reach the same consent and picker surfaces as spaces",
+    idleMs: UNATTENDED_TIMEOUT_MS
+  },
+  // The contribute flow shows the full diff for approval before anything is written
+  // (TRUST_AND_SAFETY TS-19b: the approval MUST show the real diff, so a human reads it).
+  // NOT a wrapped presenter — no `idleMs`.
+  contribute: { reason: "the diff-approval step is a human read of the whole change" },
+  // A task is an app bound to a transient slot that the user interacts with; it returns
+  // when they finish, which is human-paced by construction. That is an APP's interaction,
+  // not a host prompt, so the attention channel never fires for it — no `idleMs`.
+  task: { reason: "a task app runs an interaction and returns when the user finishes" },
+  // Launching a target can raise consent for a not-yet-granted app — through the launch
+  // flow's own surface, not one of the wrapped presenters. No `idleMs`.
+  launch: { reason: "may raise first-use consent for the launched target" },
+  // A drag is a gesture in progress — its duration is the user's hand, and no host prompt
+  // is up while it happens. No `idleMs`.
+  dnd: { reason: "a drag is a human gesture in flight" },
+  // The chat stream's FIRST frame sits behind the session's first passkey unseal — the
+  // exact hang the dogfood run found — and that unseal IS a wrapped presenter. But the idle
+  // bound here is the NETWORK one, not the channel one: with no prompt up, this call is
+  // waiting on an arbitrary upstream model, and thirty seconds is a normal generation.
+  llm: {
+    reason: "the first frame can sit behind the session passkey unseal",
+    idleMs: NETWORK_TIMEOUT_MS
+  }
+};
+function attendedEntry(scheme, method) {
+  return ATTENDED[`${scheme}:${method}`] ?? ATTENDED[scheme];
+}
+function attendedReason(scheme, method) {
+  return attendedEntry(scheme, method)?.reason;
+}
+function attendanceOf(scheme, method) {
+  return attendedReason(scheme, method) ? "attended" : "unattended";
+}
+function attendanceReason(scheme, method) {
+  return attendedReason(scheme, method);
+}
+function timeoutFor(scheme, method) {
+  if (attendanceOf(scheme, method) === "attended") return ATTENDED_TIMEOUT_MS;
+  if (scheme === "fetch") return NETWORK_TIMEOUT_MS;
+  return UNATTENDED_TIMEOUT_MS;
+}
+function firstFrameTimeoutFor(scheme, method) {
+  return attendanceOf(scheme, method) === "attended" ? ATTENDED_FIRST_FRAME_MS : NETWORK_TIMEOUT_MS;
+}
+function boundsFor(scheme, method) {
+  const ceilingMs = timeoutFor(scheme, method);
+  const idleMs = attendedEntry(scheme, method)?.idleMs;
+  return { idleMs: idleMs === void 0 ? ceilingMs : Math.min(idleMs, ceilingMs), ceilingMs };
+}
+function firstFrameBoundsFor(scheme, method) {
+  const ceilingMs = firstFrameTimeoutFor(scheme, method);
+  const idleMs = attendedEntry(scheme, method)?.idleMs;
+  return { idleMs: idleMs === void 0 ? ceilingMs : Math.min(idleMs, ceilingMs), ceilingMs };
+}
+function createSuspendableDeadline(opts) {
+  const setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = opts.clearTimer ?? ((h) => clearTimeout(h));
+  const { idleMs, ceilingMs } = opts.bounds;
+  const hasIdleLeg = Number.isFinite(idleMs) && idleMs < ceilingMs;
+  let done = false;
+  let idle;
+  let ceiling;
+  const expire = (bound, boundMs) => {
+    if (done) return;
+    done = true;
+    opts.onExpire(bound, boundMs);
+  };
+  const armIdle = () => {
+    if (done || !hasIdleLeg || idle !== void 0) return;
+    idle = setTimer(() => {
+      idle = void 0;
+      expire("idle", idleMs);
+    }, idleMs);
+  };
+  const disarmIdle = () => {
+    if (idle !== void 0) {
+      clearTimer(idle);
+      idle = void 0;
+    }
+  };
+  if (Number.isFinite(ceilingMs)) {
+    ceiling = setTimer(() => {
+      ceiling = void 0;
+      expire("ceiling", ceilingMs);
+    }, ceilingMs);
+  }
+  armIdle();
+  return {
+    setAwaiting(awaiting) {
+      if (done) return;
+      if (awaiting) disarmIdle();
+      else armIdle();
+    },
+    dispose() {
+      done = true;
+      disarmIdle();
+      if (ceiling !== void 0) {
+        clearTimer(ceiling);
+        ceiling = void 0;
+      }
+    }
+  };
+}
+class ProtocolTimeoutError extends Error {
+  constructor(call, timeoutMs, attendance, bound = attendance === "attended" ? "ceiling" : "idle") {
+    super(
+      attendance === "attended" && bound === "ceiling" ? `immediately.run: ${call} was abandoned after ${Math.round(timeoutMs / 1e3)}s waiting for you` : `immediately.run: ${call} did not respond within ${Math.round(timeoutMs / 1e3)}s`
+    );
+    this.code = "timeout";
+    this.name = "ProtocolTimeoutError";
+    this.call = call;
+    this.timeoutMs = timeoutMs;
+    this.attendance = attendance;
+    this.bound = bound;
+  }
+}
+class ProtocolCancelledError extends Error {
+  constructor(call) {
+    super(`immediately.run: ${call} was cancelled`);
+    this.code = "cancelled";
+    this.name = "ProtocolCancelledError";
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ATTENDED_FIRST_FRAME_MS,
+  ATTENDED_TIMEOUT_MS,
+  NETWORK_TIMEOUT_MS,
+  PENDING_NOTICE_MS,
+  ProtocolCancelledError,
+  ProtocolTimeoutError,
+  STREAM_IDLE_TIMEOUT_MS,
+  UNATTENDED_TIMEOUT_MS,
+  attendanceOf,
+  attendanceReason,
+  boundsFor,
+  createSuspendableDeadline,
+  firstFrameBoundsFor,
+  firstFrameTimeoutFor,
+  timeoutFor
+});
+//# sourceMappingURL=protocolDeadline.cjs.map