@immediately-run/sdk 0.45.3 → 0.47.0

package/dist/linkSpace.d.cts

@@ -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.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,12 @@ var llm_exports = {};
 __export(llm_exports, {
   chat: () => chat,
   describeChat: () => describeChat,
+  describeChatState: () => describeChatState,
+  normalizeProviderInfo: () => normalizeProviderInfo,
   onChatProviderChange: () => onChatProviderChange,
-  useChatProvider: () => useChatProvider
+  onChatProviderStateChange: () => onChatProviderStateChange,
+  useChatProvider: () => useChatProvider,
+  useChatProviderState: () => useChatProviderState
 });
 module.exports = __toCommonJS(llm_exports);
 var import_catalog = require("./catalog");
@@ -29,26 +33,40 @@ var import_pushChannel = require("./pushChannel");
 var import_protocol = require("./generated/protocol");
 function chat(req) {
   const { signal, ...params } = req;
-  return (0, import_catalog.invokeStream)(
-    "llm:chat",
-    params,
-    signal
-  );
+  return (0, import_catalog.invokeStream)("llm:chat", params, signal);
 }
+function normalizeProviderInfo(provider) {
+  if (!provider) return null;
+  const wire = provider.features;
+  return { ...provider, features: { ...wire, reasoning: wire.reasoning === true } };
+}
+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 normalizeProviderInfo(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,
+  normalizeProviderInfo,
   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  // A block of the model's own REASONING from a prior `assistant` turn (R3-335).\n  // Honored only when the resolved provider advertises `features.reasoning`.\n  //\n  // Echo these back. On some providers a reasoning block must be replayed — with its\n  // `signature` intact and BEFORE the turn's text/tool-use — for the following turn to\n  // be accepted at all; a loop that drops them is quietly lossy across turns in a way\n  // that shows up as degraded output rather than an error. Pairs with the streamed\n  // `reasoning` {@link ChatDelta}.\n  | { type: 'reasoning'; text: string; signature?: string }\n  // Reasoning the provider REDACTED: opaque bytes with no readable text, which still\n  // have to be echoed back in place to keep the chain valid. Never render it.\n  | { type: 'reasoning-redacted'; data: string }\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  // R3-335 — the model's reasoning as it streams. `reasoning-delta` carries the text\n  // incrementally (render it live); the terminal `reasoning` carries the WHOLE block\n  // plus the `signature` the provider may require on the echo, and is what a caller\n  // should put back into the conversation. A provider without reasoning emits neither.\n  | { type: 'reasoning-delta'; text: string }\n  | { type: 'reasoning'; text: string; signature?: string }\n  | { type: 'reasoning-redacted'; data: string }\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>('llm:chat', params as unknown as Record<string, unknown>, signal);\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  /** R3-335: the provider emits reasoning blocks. Read it to decide whether to render\n   *  a thinking surface at all — an empty affordance on a provider that never thinks\n   *  is worse than none. Normalized to `false` by the channel when a host predating\n   *  R3-335 omits it, so this is never `undefined` in practice. */\n  reasoning: 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).\n/**\n * Fill in feature flags a host older than the field does not send (R3-335).\n *\n * `features.reasoning` arrived after `ChatFeatures` shipped, so a host predating it\n * omits the key. `undefined` reads as falsy everywhere EXCEPT a `'reasoning' in\n * features` check, which is exactly the kind of difference that produces one wrong\n * branch a year later — so it is normalized here, once, rather than left to every\n * caller. Absent means \"does not reason\": the fail-closed reading.\n *\n * Exported for its own test; not part of the public surface (`index.ts` re-exports\n * this module wholesale, so it is reachable — it is documented as internal rather\n * than hidden behind a lie).\n * @internal\n */\nexport function normalizeProviderInfo(provider: ChatProviderInfo | null): ChatProviderInfo | null {\n  if (!provider) return null;\n  // The wire value is whatever the host sent, which may predate `reasoning` — so read\n  // it as partial rather than trusting the declared type, and decide the flag explicitly.\n  const wire = provider.features as Partial<ChatFeatures>;\n  return { ...provider, features: { ...wire, reasoning: wire.reasoning === true } as ChatFeatures };\n}\n\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 normalizeProviderInfo((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 = (listener: (provider: ChatProviderInfo | null) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** Subscribe to the three-state provider description. */\nexport const onChatProviderStateChange = (listener: (state: ChatProviderState) => void): (() => void) =>\n  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;AAAA;AAeA,qBAA6B;AAC7B,yBAAkC;AAClC,sBAAmD;AAoG5C,SAAS,KAAK,KAA+D;AAGlF,QAAM,EAAE,QAAQ,GAAG,OAAO,IAAI;AAC9B,aAAO,6BAAoC,YAAY,QAA8C,MAAM;AAC7G;AAyEO,SAAS,sBAAsB,UAA4D;AAChG,MAAI,CAAC,SAAU,QAAO;AAGtB,QAAM,OAAO,SAAS;AACtB,SAAO,EAAE,GAAG,UAAU,UAAU,EAAE,GAAG,MAAM,WAAW,KAAK,cAAc,KAAK,EAAkB;AAClG;AAEA,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,WAAO,sBAAuB,IAAI,YAAwC,IAAI;AAAA,EAChF;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,CAAC,aACnC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,4BAA4B,CAAC,aACxC,QAAQ,SAAS,CAAC,MAAM,SAAS,QAAQ,CAAC,CAAC,CAAC;AAIvC,MAAM,kBAAkB,MAA+B,QAAQ,IAAI;AASnE,MAAM,uBAAuB,MAAyB,QAAQ,QAAQ,IAAI,CAAC;","names":[]}

package/dist/llm.d.cts

@@ -15,6 +15,13 @@ type ContentPart = {
     id: string;
     name: string;
     input: Record<string, unknown>;
+} | {
+    type: 'reasoning';
+    text: string;
+    signature?: string;
+} | {
+    type: 'reasoning-redacted';
+    data: string;
 } | {
     type: 'tool-result';
     toolCallId: string;
@@ -61,6 +68,16 @@ type ChatDelta = {
     id: string;
     name: string;
     input: unknown;
+} | {
+    type: 'reasoning-delta';
+    text: string;
+} | {
+    type: 'reasoning';
+    text: string;
+    signature?: string;
+} | {
+    type: 'reasoning-redacted';
+    data: string;
 } | {
     type: 'usage';
     inputTokens: number;
@@ -93,6 +110,11 @@ interface ChatFeatures {
     vision: boolean;
     tools: boolean;
     jsonMode: boolean;
+    /** R3-335: the provider emits reasoning blocks. Read it to decide whether to render
+     *  a thinking surface at all — an empty affordance on a provider that never thinks
+     *  is worse than none. Normalized to `false` by the channel when a host predating
+     *  R3-335 omits it, so this is never `undefined` in practice. */
+    reasoning: boolean;
     maxContextTokens: number;
 }
 /** Info about the provider the host resolved for this app. `null` when no provider
@@ -105,14 +127,64 @@ 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;
+};
+/**
+ * Fill in feature flags a host older than the field does not send (R3-335).
+ *
+ * `features.reasoning` arrived after `ChatFeatures` shipped, so a host predating it
+ * omits the key. `undefined` reads as falsy everywhere EXCEPT a `'reasoning' in
+ * features` check, which is exactly the kind of difference that produces one wrong
+ * branch a year later — so it is normalized here, once, rather than left to every
+ * caller. Absent means "does not reason": the fail-closed reading.
+ *
+ * Exported for its own test; not part of the public surface (`index.ts` re-exports
+ * this module wholesale, so it is reachable — it is documented as internal rather
+ * than hidden behind a lie).
+ * @internal
+ */
+declare function normalizeProviderInfo(provider: ChatProviderInfo | null): ChatProviderInfo | null;
+/**
+ * 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, normalizeProviderInfo, onChatProviderChange, onChatProviderStateChange, useChatProvider, useChatProviderState };

package/dist/llm.d.ts

@@ -15,6 +15,13 @@ type ContentPart = {
     id: string;
     name: string;
     input: Record<string, unknown>;
+} | {
+    type: 'reasoning';
+    text: string;
+    signature?: string;
+} | {
+    type: 'reasoning-redacted';
+    data: string;
 } | {
     type: 'tool-result';
     toolCallId: string;
@@ -61,6 +68,16 @@ type ChatDelta = {
     id: string;
     name: string;
     input: unknown;
+} | {
+    type: 'reasoning-delta';
+    text: string;
+} | {
+    type: 'reasoning';
+    text: string;
+    signature?: string;
+} | {
+    type: 'reasoning-redacted';
+    data: string;
 } | {
     type: 'usage';
     inputTokens: number;
@@ -93,6 +110,11 @@ interface ChatFeatures {
     vision: boolean;
     tools: boolean;
     jsonMode: boolean;
+    /** R3-335: the provider emits reasoning blocks. Read it to decide whether to render
+     *  a thinking surface at all — an empty affordance on a provider that never thinks
+     *  is worse than none. Normalized to `false` by the channel when a host predating
+     *  R3-335 omits it, so this is never `undefined` in practice. */
+    reasoning: boolean;
     maxContextTokens: number;
 }
 /** Info about the provider the host resolved for this app. `null` when no provider
@@ -105,14 +127,64 @@ 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;
+};
+/**
+ * Fill in feature flags a host older than the field does not send (R3-335).
+ *
+ * `features.reasoning` arrived after `ChatFeatures` shipped, so a host predating it
+ * omits the key. `undefined` reads as falsy everywhere EXCEPT a `'reasoning' in
+ * features` check, which is exactly the kind of difference that produces one wrong
+ * branch a year later — so it is normalized here, once, rather than left to every
+ * caller. Absent means "does not reason": the fail-closed reading.
+ *
+ * Exported for its own test; not part of the public surface (`index.ts` re-exports
+ * this module wholesale, so it is reachable — it is documented as internal rather
+ * than hidden behind a lie).
+ * @internal
+ */
+declare function normalizeProviderInfo(provider: ChatProviderInfo | null): ChatProviderInfo | null;
+/**
+ * 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, normalizeProviderInfo, onChatProviderChange, onChatProviderStateChange, useChatProvider, useChatProviderState };

package/dist/llm.js

@@ -4,25 +4,39 @@ import { createPushChannel } from "./pushChannel";
 import { LLM_PROVIDER, REQUEST_LLM_PROVIDER } from "./generated/protocol";
 function chat(req) {
   const { signal, ...params } = req;
-  return invokeStream(
-    "llm:chat",
-    params,
-    signal
-  );
+  return invokeStream("llm:chat", params, signal);
 }
+function normalizeProviderInfo(provider) {
+  if (!provider) return null;
+  const wire = provider.features;
+  return { ...provider, features: { ...wire, reasoning: wire.reasoning === true } };
+}
+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 normalizeProviderInfo(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,
+  normalizeProviderInfo,
   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  // A block of the model's own REASONING from a prior `assistant` turn (R3-335).\n  // Honored only when the resolved provider advertises `features.reasoning`.\n  //\n  // Echo these back. On some providers a reasoning block must be replayed — with its\n  // `signature` intact and BEFORE the turn's text/tool-use — for the following turn to\n  // be accepted at all; a loop that drops them is quietly lossy across turns in a way\n  // that shows up as degraded output rather than an error. Pairs with the streamed\n  // `reasoning` {@link ChatDelta}.\n  | { type: 'reasoning'; text: string; signature?: string }\n  // Reasoning the provider REDACTED: opaque bytes with no readable text, which still\n  // have to be echoed back in place to keep the chain valid. Never render it.\n  | { type: 'reasoning-redacted'; data: string }\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  // R3-335 — the model's reasoning as it streams. `reasoning-delta` carries the text\n  // incrementally (render it live); the terminal `reasoning` carries the WHOLE block\n  // plus the `signature` the provider may require on the echo, and is what a caller\n  // should put back into the conversation. A provider without reasoning emits neither.\n  | { type: 'reasoning-delta'; text: string }\n  | { type: 'reasoning'; text: string; signature?: string }\n  | { type: 'reasoning-redacted'; data: string }\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>('llm:chat', params as unknown as Record<string, unknown>, signal);\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  /** R3-335: the provider emits reasoning blocks. Read it to decide whether to render\n   *  a thinking surface at all — an empty affordance on a provider that never thinks\n   *  is worse than none. Normalized to `false` by the channel when a host predating\n   *  R3-335 omits it, so this is never `undefined` in practice. */\n  reasoning: 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).\n/**\n * Fill in feature flags a host older than the field does not send (R3-335).\n *\n * `features.reasoning` arrived after `ChatFeatures` shipped, so a host predating it\n * omits the key. `undefined` reads as falsy everywhere EXCEPT a `'reasoning' in\n * features` check, which is exactly the kind of difference that produces one wrong\n * branch a year later — so it is normalized here, once, rather than left to every\n * caller. Absent means \"does not reason\": the fail-closed reading.\n *\n * Exported for its own test; not part of the public surface (`index.ts` re-exports\n * this module wholesale, so it is reachable — it is documented as internal rather\n * than hidden behind a lie).\n * @internal\n */\nexport function normalizeProviderInfo(provider: ChatProviderInfo | null): ChatProviderInfo | null {\n  if (!provider) return null;\n  // The wire value is whatever the host sent, which may predate `reasoning` — so read\n  // it as partial rather than trusting the declared type, and decide the flag explicitly.\n  const wire = provider.features as Partial<ChatFeatures>;\n  return { ...provider, features: { ...wire, reasoning: wire.reasoning === true } as ChatFeatures };\n}\n\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 normalizeProviderInfo((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 = (listener: (provider: ChatProviderInfo | null) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** Subscribe to the three-state provider description. */\nexport const onChatProviderStateChange = (listener: (state: ChatProviderState) => void): (() => void) =>\n  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;AAoG5C,SAAS,KAAK,KAA+D;AAGlF,QAAM,EAAE,QAAQ,GAAG,OAAO,IAAI;AAC9B,SAAO,aAAoC,YAAY,QAA8C,MAAM;AAC7G;AAyEO,SAAS,sBAAsB,UAA4D;AAChG,MAAI,CAAC,SAAU,QAAO;AAGtB,QAAM,OAAO,SAAS;AACtB,SAAO,EAAE,GAAG,UAAU,UAAU,EAAE,GAAG,MAAM,WAAW,KAAK,cAAc,KAAK,EAAkB;AAClG;AAEA,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,WAAO,sBAAuB,IAAI,YAAwC,IAAI;AAAA,EAChF;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,CAAC,aACnC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,4BAA4B,CAAC,aACxC,QAAQ,SAAS,CAAC,MAAM,SAAS,QAAQ,CAAC,CAAC,CAAC;AAIvC,MAAM,kBAAkB,MAA+B,QAAQ,IAAI;AASnE,MAAM,uBAAuB,MAAyB,QAAQ,QAAQ,IAAI,CAAC;","names":[]}