@immediately-run/sdk 0.60.0 → 0.64.0

package/dist/index.d.ts

@@ -20,7 +20,7 @@ export { FormFactor, FormFactorClass, Orientation, getFormFactor, onFormFactorCh
 export { ChromeState, getChromeState, onChromeStateChange, useChromeState } from './chromeState.js';
 export { Workspace, getWorkspace, onWorkspaceChange, useWorkspace } from './workspace.js';
 export { HostAttention, HostAttentionKind, NO_HOST_ATTENTION, getHostAttention, onHostAttentionChange, useHostAttention } from './hostAttention.js';
-export { getRegion, useRegion } from './region.js';
+export { getRegion, isRegionHidden, onRegionVisibilityChange, useRegion, useRegionHidden } from './region.js';
 export { Invite, MountQuery, MountRemoveReason, MountRule, RemovedMount, SandboxMount, SessionMount, SpaceError, acceptInvite, awaitMatchingMount, createSpace, declineInvite, findMount, getAppMountPath, getInvites, getMounts, getSessionMounts, importSettingsFromParent, listMyInvites, listPendingInvites, listSettingsApps, makeContentRef, mount, mountSpace, onInvitesChange, onMountsChange, onSessionMountsChange, openSettings, openSettingsOf, requestMount, requestSpace, resolveContentRef, resolveContentRefs, revokeInvite, unmountSpace, useInvites, useMounts, useSessionMounts, waitForMount } from './mounts.js';
 export { AnalyticsAck, AnalyticsPropValue, emitAnalyticsEvent, recordRoute, track, trackRoute } from './analytics.js';
 export { ContributeMode, ContributeOptions, ContributionEvent, ContributionResult, contribute } from './contribute.js';
@@ -31,7 +31,8 @@ export { HostFetchInit, HostFetchResponse, HostFetchStreamEvent, HostFetchStream
 export { FeedFetchResponse, FeedParams, feedFetch } from './feed.js';
 export { SecretError, SecretGrant, SecretHints, SecretQuery, SecretType, SecretView, getSecrets, onSecretsChange, requestAddSecret, requestSecret, revokeSecret, useSecrets } from './secrets.js';
 export { RecentProject, clearRecentProjects, listRecentProjects } from './recents.js';
-export { ChatDelta, ChatFeatures, ChatMessage, ChatProviderInfo, ChatProviderState, ChatRequest, ChatResult, ChatRole, ChatStopReason, ContentPart, ToolDef, chat, describeChat, describeChatState, normalizeProviderInfo, onChatProviderChange, onChatProviderStateChange, useChatProvider, useChatProviderState } from './llm.js';
+export { OpenRepositoryError, OpenRepositoryErrorCode, RepositoryCoordinates, openRepository } from './openRepository.js';
+export { ChatDelta, ChatExecutor, ChatFeatures, ChatMessage, ChatProviderInfo, ChatProviderState, ChatRequest, ChatResult, ChatRole, ChatStopReason, ChatTierModels, ContentPart, ToolDef, chat, describeChat, describeChatState, normalizeProviderInfo, onChatProviderChange, onChatProviderStateChange, useChatProvider, useChatProviderState } from './llm.js';
 export { BuildError, ConsoleEntry, ConsoleLevel, Diagnostics, DiagnosticsProvenance, getDiagnostics, onDiagnosticsChange, useDiagnostics } from './diagnostics.js';
 export { VcsActionError, VcsBranch, VcsChange, VcsPR, VcsState, getVcsState, onVcsStateChange, refreshDiff, refreshPRs, resetWorkingTree, useVcsState } from './vcs.js';
 export { FsChange, MountChange, getFsChange, onFsChange, useFsChange } from './onFsChange.js';
@@ -49,6 +50,7 @@ export { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQu
 export * from '@immediately-run/safe-content';
 export { AgentEvents, AgentMessage, AgentRole, AgentTool, COMPACTION_MARKER, ContentBlock, ImageBlock, ModelClient, ModelResponse, NUDGE_TEXT, ReasoningBlock, RunAgentOptions, StallReason, TextBlock, TokenUsage, ToolExecutor, ToolOutcome, ToolResultBlock, ToolUseBlock, compactTranscript, detectStall, estimateTokens, isContextOverflow, runAgent, shouldCompact } from './agentLoop.js';
 export { INTERRUPTED_TURN_TEXT, STEER_INTERRUPT_MARKER, STEER_MARKER, SteerController, SteerMessage, SteerMode, SteerSource, anySignal, parseSteer, steerWireText } from './agentSteering.js';
+export { PauseController, PauseSource } from './agentPause.js';
 export { createChatModelClient } from './agentChatClient.js';
 export { HeadingSummary, METADATA_HEADINGS_KEY, METADATA_QUERY_TOOL_DESCRIPTOR, METADATA_QUERY_TOOL_NAME, MetadataQueryError, MetadataQueryInput, MetadataQueryRow, createMetadataQueryTool, executeMetadataQuery, globToRegExp, runMetadataQuery } from './metadataQueryTool.js';
 export { collectHeadings } from './collectHeadings.js';

package/dist/index.js

@@ -33,6 +33,7 @@ export * from "./netFetch";
 export * from "./feed";
 export * from "./secrets";
 export * from "./recents";
+export * from "./openRepository";
 export * from "./llm";
 export * from "./diagnostics";
 export * from "./vcs";
@@ -51,6 +52,7 @@ export * from "./sandboxTypes";
 export * from "./safeContent";
 export * from "./agentLoop";
 export * from "./agentSteering";
+export * from "./agentPause";
 export * from "./agentChatClient";
 export * from "./metadataQueryTool";
 export * from "./collectHeadings";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './MDXProvider';\nexport * from './routing';\nexport * from './boot';\nexport * from './components/Include';\n// Only the component is public. `stripFrontmatter`/`appMountRelative` are module-level\n// exports so they can be unit-tested directly, NOT public API — the SDK's surface is\n// backwards-compatible forever, so an internal helper exported for a test's convenience is a\n// permanent commitment made for the wrong reason.\nexport { SafeInclude } from './components/SafeInclude';\nexport * from './sourceCache';\nexport * from './components/MDXComponents';\nexport * from './linkSpace';\nexport * from './bundle';\n// Deprecated `Corpus*` spellings of the above (R3-482); see `src/corpus.ts`.\nexport * from './corpus';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks';\n// R3-276: the supported way for a viewer app to provide its own metadata store,\n// replacing a wholesale re-provision of `TinkerableContext` in app code.\nexport * from './metadataSource';\n// The deprecated injected-bundler adapters, re-exported so their deprecation notices\n// are visible in the published docs (R3-278; the window only narrows).\nexport { getInjectedMetadataEmitter, getInjectedMetadataSnapshot } from './injectedBundler';\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './chromeState';\nexport * from './workspace';\nexport * from './hostAttention';\nexport * from './region';\nexport * from './mounts';\nexport * from './analytics';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './feed';\nexport * from './secrets';\nexport * from './recents'; // R3-485: the gated recent-projects read (page.home)\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './launch';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './protocolDeadline';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n// R3-489 (GROVE_AGENT_SPEC): the embedded-agent seam every app shares — the tool-use\n// loop ported from agent-demo (`runAgent` over the host chat slot), the MDX metadata\n// query tool, the headings index collector, the deixis context block, and the fence\n// for corpus-derived bytes entering a loop.\nexport * from './agentLoop';\nexport * from './agentSteering';\nexport * from './agentChatClient';\nexport * from './metadataQueryTool';\nexport * from './collectHeadings';\nexport * from './agentContext';\nexport * from './fence';\nexport * from './platformLink';\n"],"mappings":";AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAKd,SAAS,mBAAmB;AAC5B,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAEd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AAGd,SAAS,4BAA4B,mCAAmC;AACxE,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAKd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from './MDXProvider';\nexport * from './routing';\nexport * from './boot';\nexport * from './components/Include';\n// Only the component is public. `stripFrontmatter`/`appMountRelative` are module-level\n// exports so they can be unit-tested directly, NOT public API — the SDK's surface is\n// backwards-compatible forever, so an internal helper exported for a test's convenience is a\n// permanent commitment made for the wrong reason.\nexport { SafeInclude } from './components/SafeInclude';\nexport * from './sourceCache';\nexport * from './components/MDXComponents';\nexport * from './linkSpace';\nexport * from './bundle';\n// Deprecated `Corpus*` spellings of the above (R3-482); see `src/corpus.ts`.\nexport * from './corpus';\nexport * from './components/MountImage';\nexport * from './components/Routes';\nexport * from './hooks';\n// R3-276: the supported way for a viewer app to provide its own metadata store,\n// replacing a wholesale re-provision of `TinkerableContext` in app code.\nexport * from './metadataSource';\n// The deprecated injected-bundler adapters, re-exported so their deprecation notices\n// are visible in the published docs (R3-278; the window only narrows).\nexport { getInjectedMetadataEmitter, getInjectedMetadataSnapshot } from './injectedBundler';\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './chromeState';\nexport * from './workspace';\nexport * from './hostAttention';\nexport * from './region';\nexport * from './mounts';\nexport * from './analytics';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './feed';\nexport * from './secrets';\nexport * from './recents'; // R3-485: the gated recent-projects read (page.home)\nexport * from './openRepository'; // R3-476: host-mediated open-in-a-new-tab (route:read)\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './vcs';\nexport * from './onFsChange';\nexport * from './fs';\nexport * from './debug';\nexport * from './tasks';\nexport * from './launch';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\nexport * from './protocolStream';\nexport * from './protocolDeadline';\nexport * from './sandboxTypes';\nexport * from './safeContent';\n// R3-489 (GROVE_AGENT_SPEC): the embedded-agent seam every app shares — the tool-use\n// loop ported from agent-demo (`runAgent` over the host chat slot), the MDX metadata\n// query tool, the headings index collector, the deixis context block, and the fence\n// for corpus-derived bytes entering a loop.\nexport * from './agentLoop';\nexport * from './agentSteering';\nexport * from './agentPause';\nexport * from './agentChatClient';\nexport * from './metadataQueryTool';\nexport * from './collectHeadings';\nexport * from './agentContext';\nexport * from './fence';\nexport * from './platformLink';\n"],"mappings":";AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAKd,SAAS,mBAAmB;AAC5B,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAEd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AAGd,SAAS,4BAA4B,mCAAmC;AACxE,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAKd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}

package/dist/llm.cjs

@@ -35,10 +35,26 @@ function chat(req) {
   const { signal, ...params } = req;
   return (0, import_catalog.invokeStream)("llm:chat", params, signal);
 }
+const EXECUTORS = ["browser-direct", "backend-proxied"];
+const usableModels = (raw) => {
+  if (!raw || typeof raw !== "object") return void 0;
+  const { fast, smart } = raw;
+  return typeof fast === "string" && fast && typeof smart === "string" && smart ? { fast, smart } : void 0;
+};
 function normalizeProviderInfo(provider) {
   if (!provider) return null;
+  const { displayName: rawName, executor: rawExecutor, models: rawModels, ...rest } = provider;
   const wire = provider.features;
-  return { ...provider, features: { ...wire, reasoning: wire.reasoning === true } };
+  const executor = EXECUTORS.includes(rawExecutor) ? rawExecutor : void 0;
+  const displayName = typeof rawName === "string" && rawName ? rawName : void 0;
+  const models = usableModels(rawModels);
+  return {
+    ...rest,
+    features: { ...wire, reasoning: wire.reasoning === true },
+    ...displayName ? { displayName } : {},
+    ...executor ? { executor } : {},
+    ...models ? { models } : {}
+  };
 }
 let answered = false;
 const channel = (0, import_pushChannel.createPushChannel)({

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  // 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  // Token accounting for the turn. `cacheReadTokens`/`cacheWriteTokens` are present\n  // only on providers that report prompt caching (R3-336) — they are what makes a\n  // caching claim verifiable rather than believed, and their ABSENCE is meaningful:\n  // it says this provider reports nothing, not that nothing was cached.\n  | {\n      type: 'usage';\n      inputTokens: number;\n      outputTokens: number;\n      cacheReadTokens?: number;\n      cacheWriteTokens?: number;\n    };\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 first\n * draws the SP-7 connect-me gate itself (R3-456: the app never draws a\n * credential prompt — that is host chrome, SECRETS_SPEC S3):\n * - the user connects a key → the call retries once and streams normally;\n * - the user declines → the generator throws `code: 'cancelled'` (the same code\n *   a declined powerbox produces — a working degraded state: catch it and\n *   degrade, e.g. skip the AI feature);\n * - an older host without the gate throws `code: 'provider-not-configured'`.\n * A signed-out user throws `code: 'auth-required'`; an un-granted call throws\n * `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 *\n * **`unknown` is TRANSIENT — the host answers every frame** (R3-419;\n * `LLM_AND_AGENTS_SPEC §4.1` R-LLM-1..3). An app that does not hold `llm:chat` is not\n * met with silence: it is answered `not-configured`, the same terminal state as a user\n * with no key, because from the app's side those are the same fact — do not render a\n * provider, do offer the connect path. So it is correct to treat a `unknown` that\n * persists as a host bug rather than as a state to design around, and WRONG to render a\n * spinner with no timeout on it. (Before R3-419 the host withheld the channel entirely\n * from an ungranted frame, and `unknown` stood forever — that is the failure this note\n * exists to keep from being re-created on the app side.)\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;AAqH5C,SAAS,KAAK,KAA+D;AAGlF,QAAM,EAAE,QAAQ,GAAG,OAAO,IAAI;AAC9B,aAAO,6BAAoC,YAAY,QAA8C,MAAM;AAC7G;AAmFO,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":[]}
+{"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  // Token accounting for the turn. `cacheReadTokens`/`cacheWriteTokens` are present\n  // only on providers that report prompt caching (R3-336) — they are what makes a\n  // caching claim verifiable rather than believed, and their ABSENCE is meaningful:\n  // it says this provider reports nothing, not that nothing was cached.\n  | {\n      type: 'usage';\n      inputTokens: number;\n      outputTokens: number;\n      cacheReadTokens?: number;\n      cacheWriteTokens?: number;\n    };\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 first\n * draws the SP-7 connect-me gate itself (R3-456: the app never draws a\n * credential prompt — that is host chrome, SECRETS_SPEC S3):\n * - the user connects a key → the call retries once and streams normally;\n * - the user declines → the generator throws `code: 'cancelled'` (the same code\n *   a declined powerbox produces — a working degraded state: catch it and\n *   degrade, e.g. skip the AI feature);\n * - an older host without the gate throws `code: 'provider-not-configured'`.\n * A signed-out user throws `code: 'auth-required'`; an un-granted call throws\n * `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/** How the resolved provider's requests physically leave the browser. Read it to\n *  DESCRIBE routing where that matters to the person (\"runs in your browser\" vs\n *  \"routed through immediately.run\") — never to draw host chrome or a consent prompt,\n *  which remain the host's (UI_AS_APPS §8 T15). */\nexport type ChatExecutor = 'browser-direct' | 'backend-proxied';\n\n/** The concrete model each abstract tier resolves to right now. */\nexport interface ChatTierModels {\n  fast: string;\n  smart: string;\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  /** The provider's human name, e.g. `OpenRouter` — what to put in front of a person.\n   *  Absent on a host that predates the field: fall back to your own copy rather than\n   *  rendering the id, which is a platform identifier and not a name. */\n  displayName?: string;\n  /** How this provider's requests leave the browser. Absent on a host that predates the\n   *  field, which is NOT the same as `browser-direct` — say nothing about routing rather\n   *  than guess at it. */\n  executor?: ChatExecutor;\n  /**\n   * The concrete model each {@link ChatRequest.modelHint} tier resolves to — what a\n   * `smart` request would actually run, after the user's own preference.\n   *\n   * Read-only, and it does not weaken `LLM_AND_AGENTS_SPEC §0`: an app still names no\n   * model, and {@link ChatRequest} still carries only the abstract hint. It is here so an\n   * app can be HONEST about what answered — a transcript that says which model wrote a\n   * reply, a warning that names the model about to be spent on — instead of showing a\n   * blank where the platform knows the answer. The user picks the model in host settings;\n   * the app reports it.\n   *\n   * Absent on a host that predates the field. It changes when the user changes their\n   * preference, so read it through {@link onChatProviderChange} rather than caching it.\n   */\n  models?: ChatTierModels;\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 *\n * **`unknown` is TRANSIENT — the host answers every frame** (R3-419;\n * `LLM_AND_AGENTS_SPEC §4.1` R-LLM-1..3). An app that does not hold `llm:chat` is not\n * met with silence: it is answered `not-configured`, the same terminal state as a user\n * with no key, because from the app's side those are the same fact — do not render a\n * provider, do offer the connect path. So it is correct to treat a `unknown` that\n * persists as a host bug rather than as a state to design around, and WRONG to render a\n * spinner with no timeout on it. (Before R3-419 the host withheld the channel entirely\n * from an ungranted frame, and `unknown` stood forever — that is the failure this note\n * exists to keep from being re-created on the app side.)\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 * Reconcile what the host actually sent with what this SDK declares.\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 * `displayName`, `executor` and `models` arrived later still, and for them absence is a\n * REAL answer an app is told to handle (\"this host does not say\"), so they are left\n * absent rather than filled in. What is dropped is a value that is present but not\n * usable — an `executor` outside the union, a `models` missing a tier — because a\n * half-answer rendered as fact is worse than the honest blank the app already handles.\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 */\nconst EXECUTORS: readonly ChatExecutor[] = ['browser-direct', 'backend-proxied'];\n\nconst usableModels = (raw: unknown): ChatTierModels | undefined => {\n  if (!raw || typeof raw !== 'object') return undefined;\n  const { fast, smart } = raw as Partial<ChatTierModels>;\n  return typeof fast === 'string' && fast && typeof smart === 'string' && smart ? { fast, smart } : undefined;\n};\n\nexport function normalizeProviderInfo(provider: ChatProviderInfo | null): ChatProviderInfo | null {\n  if (!provider) return null;\n  // The three later fields are taken OFF the value and put back only if usable — spreading\n  // and then overwriting would leave an unusable key present, and `key in provider` is\n  // exactly how an app is told to ask whether the host said anything.\n  const { displayName: rawName, executor: rawExecutor, models: rawModels, ...rest } = provider;\n  // The wire value is whatever the host sent, which may predate any of these fields — so\n  // read it as partial rather than trusting the declared type, and decide each explicitly.\n  const wire = provider.features as Partial<ChatFeatures>;\n  const executor = EXECUTORS.includes(rawExecutor as ChatExecutor) ? (rawExecutor as ChatExecutor) : undefined;\n  const displayName = typeof rawName === 'string' && rawName ? rawName : undefined;\n  const models = usableModels(rawModels);\n  return {\n    ...rest,\n    features: { ...wire, reasoning: wire.reasoning === true } as ChatFeatures,\n    ...(displayName ? { displayName } : {}),\n    ...(executor ? { executor } : {}),\n    ...(models ? { models } : {}),\n  };\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;AAqH5C,SAAS,KAAK,KAA+D;AAGlF,QAAM,EAAE,QAAQ,GAAG,OAAO,IAAI;AAC9B,aAAO,6BAAoC,YAAY,QAA8C,MAAM;AAC7G;AAoHA,MAAM,YAAqC,CAAC,kBAAkB,iBAAiB;AAE/E,MAAM,eAAe,CAAC,QAA6C;AACjE,MAAI,CAAC,OAAO,OAAO,QAAQ,SAAU,QAAO;AAC5C,QAAM,EAAE,MAAM,MAAM,IAAI;AACxB,SAAO,OAAO,SAAS,YAAY,QAAQ,OAAO,UAAU,YAAY,QAAQ,EAAE,MAAM,MAAM,IAAI;AACpG;AAEO,SAAS,sBAAsB,UAA4D;AAChG,MAAI,CAAC,SAAU,QAAO;AAItB,QAAM,EAAE,aAAa,SAAS,UAAU,aAAa,QAAQ,WAAW,GAAG,KAAK,IAAI;AAGpF,QAAM,OAAO,SAAS;AACtB,QAAM,WAAW,UAAU,SAAS,WAA2B,IAAK,cAA+B;AACnG,QAAM,cAAc,OAAO,YAAY,YAAY,UAAU,UAAU;AACvE,QAAM,SAAS,aAAa,SAAS;AACrC,SAAO;AAAA,IACL,GAAG;AAAA,IACH,UAAU,EAAE,GAAG,MAAM,WAAW,KAAK,cAAc,KAAK;AAAA,IACxD,GAAI,cAAc,EAAE,YAAY,IAAI,CAAC;AAAA,IACrC,GAAI,WAAW,EAAE,SAAS,IAAI,CAAC;AAAA,IAC/B,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC;AAAA,EAC7B;AACF;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

@@ -126,6 +126,16 @@ interface ChatFeatures {
     reasoning: boolean;
     maxContextTokens: number;
 }
+/** How the resolved provider's requests physically leave the browser. Read it to
+ *  DESCRIBE routing where that matters to the person ("runs in your browser" vs
+ *  "routed through immediately.run") — never to draw host chrome or a consent prompt,
+ *  which remain the host's (UI_AS_APPS §8 T15). */
+type ChatExecutor = 'browser-direct' | 'backend-proxied';
+/** The concrete model each abstract tier resolves to right now. */
+interface ChatTierModels {
+    fast: string;
+    smart: string;
+}
 /** Info about the provider the host resolved for this app. `null` when no provider
  *  is bound (SP-7: prompt the user to add a key before calling {@link chat}). */
 interface ChatProviderInfo {
@@ -135,6 +145,29 @@ interface ChatProviderInfo {
      *  whose `features` are an untrusted claim. */
     hostVouched: boolean;
     features: ChatFeatures;
+    /** The provider's human name, e.g. `OpenRouter` — what to put in front of a person.
+     *  Absent on a host that predates the field: fall back to your own copy rather than
+     *  rendering the id, which is a platform identifier and not a name. */
+    displayName?: string;
+    /** How this provider's requests leave the browser. Absent on a host that predates the
+     *  field, which is NOT the same as `browser-direct` — say nothing about routing rather
+     *  than guess at it. */
+    executor?: ChatExecutor;
+    /**
+     * The concrete model each {@link ChatRequest.modelHint} tier resolves to — what a
+     * `smart` request would actually run, after the user's own preference.
+     *
+     * Read-only, and it does not weaken `LLM_AND_AGENTS_SPEC §0`: an app still names no
+     * model, and {@link ChatRequest} still carries only the abstract hint. It is here so an
+     * app can be HONEST about what answered — a transcript that says which model wrote a
+     * reply, a warning that names the model about to be spent on — instead of showing a
+     * blank where the platform knows the answer. The user picks the model in host settings;
+     * the app reports it.
+     *
+     * Absent on a host that predates the field. It changes when the user changes their
+     * preference, so read it through {@link onChatProviderChange} rather than caching it.
+     */
+    models?: ChatTierModels;
 }
 /**
  * Whether the host has told us about a provider yet, and if so whether one is bound.
@@ -163,20 +196,6 @@ type ChatProviderState = {
     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`.
@@ -206,4 +225,4 @@ declare const useChatProvider: () => ChatProviderInfo | null;
  */
 declare const useChatProviderState: () => ChatProviderState;
 
-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 };
+export { type ChatDelta, type ChatExecutor, type ChatFeatures, type ChatMessage, type ChatProviderInfo, type ChatProviderState, type ChatRequest, type ChatResult, type ChatRole, type ChatStopReason, type ChatTierModels, type ContentPart, type ToolDef, chat, describeChat, describeChatState, normalizeProviderInfo, onChatProviderChange, onChatProviderStateChange, useChatProvider, useChatProviderState };

package/dist/llm.d.ts

@@ -126,6 +126,16 @@ interface ChatFeatures {
     reasoning: boolean;
     maxContextTokens: number;
 }
+/** How the resolved provider's requests physically leave the browser. Read it to
+ *  DESCRIBE routing where that matters to the person ("runs in your browser" vs
+ *  "routed through immediately.run") — never to draw host chrome or a consent prompt,
+ *  which remain the host's (UI_AS_APPS §8 T15). */
+type ChatExecutor = 'browser-direct' | 'backend-proxied';
+/** The concrete model each abstract tier resolves to right now. */
+interface ChatTierModels {
+    fast: string;
+    smart: string;
+}
 /** Info about the provider the host resolved for this app. `null` when no provider
  *  is bound (SP-7: prompt the user to add a key before calling {@link chat}). */
 interface ChatProviderInfo {
@@ -135,6 +145,29 @@ interface ChatProviderInfo {
      *  whose `features` are an untrusted claim. */
     hostVouched: boolean;
     features: ChatFeatures;
+    /** The provider's human name, e.g. `OpenRouter` — what to put in front of a person.
+     *  Absent on a host that predates the field: fall back to your own copy rather than
+     *  rendering the id, which is a platform identifier and not a name. */
+    displayName?: string;
+    /** How this provider's requests leave the browser. Absent on a host that predates the
+     *  field, which is NOT the same as `browser-direct` — say nothing about routing rather
+     *  than guess at it. */
+    executor?: ChatExecutor;
+    /**
+     * The concrete model each {@link ChatRequest.modelHint} tier resolves to — what a
+     * `smart` request would actually run, after the user's own preference.
+     *
+     * Read-only, and it does not weaken `LLM_AND_AGENTS_SPEC §0`: an app still names no
+     * model, and {@link ChatRequest} still carries only the abstract hint. It is here so an
+     * app can be HONEST about what answered — a transcript that says which model wrote a
+     * reply, a warning that names the model about to be spent on — instead of showing a
+     * blank where the platform knows the answer. The user picks the model in host settings;
+     * the app reports it.
+     *
+     * Absent on a host that predates the field. It changes when the user changes their
+     * preference, so read it through {@link onChatProviderChange} rather than caching it.
+     */
+    models?: ChatTierModels;
 }
 /**
  * Whether the host has told us about a provider yet, and if so whether one is bound.
@@ -163,20 +196,6 @@ type ChatProviderState = {
     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`.
@@ -206,4 +225,4 @@ declare const useChatProvider: () => ChatProviderInfo | null;
  */
 declare const useChatProviderState: () => ChatProviderState;
 
-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 };
+export { type ChatDelta, type ChatExecutor, type ChatFeatures, type ChatMessage, type ChatProviderInfo, type ChatProviderState, type ChatRequest, type ChatResult, type ChatRole, type ChatStopReason, type ChatTierModels, type ContentPart, type ToolDef, chat, describeChat, describeChatState, normalizeProviderInfo, onChatProviderChange, onChatProviderStateChange, useChatProvider, useChatProviderState };

package/dist/llm.js

@@ -6,10 +6,26 @@ function chat(req) {
   const { signal, ...params } = req;
   return invokeStream("llm:chat", params, signal);
 }
+const EXECUTORS = ["browser-direct", "backend-proxied"];
+const usableModels = (raw) => {
+  if (!raw || typeof raw !== "object") return void 0;
+  const { fast, smart } = raw;
+  return typeof fast === "string" && fast && typeof smart === "string" && smart ? { fast, smart } : void 0;
+};
 function normalizeProviderInfo(provider) {
   if (!provider) return null;
+  const { displayName: rawName, executor: rawExecutor, models: rawModels, ...rest } = provider;
   const wire = provider.features;
-  return { ...provider, features: { ...wire, reasoning: wire.reasoning === true } };
+  const executor = EXECUTORS.includes(rawExecutor) ? rawExecutor : void 0;
+  const displayName = typeof rawName === "string" && rawName ? rawName : void 0;
+  const models = usableModels(rawModels);
+  return {
+    ...rest,
+    features: { ...wire, reasoning: wire.reasoning === true },
+    ...displayName ? { displayName } : {},
+    ...executor ? { executor } : {},
+    ...models ? { models } : {}
+  };
 }
 let answered = false;
 const channel = createPushChannel({

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  // 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  // Token accounting for the turn. `cacheReadTokens`/`cacheWriteTokens` are present\n  // only on providers that report prompt caching (R3-336) — they are what makes a\n  // caching claim verifiable rather than believed, and their ABSENCE is meaningful:\n  // it says this provider reports nothing, not that nothing was cached.\n  | {\n      type: 'usage';\n      inputTokens: number;\n      outputTokens: number;\n      cacheReadTokens?: number;\n      cacheWriteTokens?: number;\n    };\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 first\n * draws the SP-7 connect-me gate itself (R3-456: the app never draws a\n * credential prompt — that is host chrome, SECRETS_SPEC S3):\n * - the user connects a key → the call retries once and streams normally;\n * - the user declines → the generator throws `code: 'cancelled'` (the same code\n *   a declined powerbox produces — a working degraded state: catch it and\n *   degrade, e.g. skip the AI feature);\n * - an older host without the gate throws `code: 'provider-not-configured'`.\n * A signed-out user throws `code: 'auth-required'`; an un-granted call throws\n * `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 *\n * **`unknown` is TRANSIENT — the host answers every frame** (R3-419;\n * `LLM_AND_AGENTS_SPEC §4.1` R-LLM-1..3). An app that does not hold `llm:chat` is not\n * met with silence: it is answered `not-configured`, the same terminal state as a user\n * with no key, because from the app's side those are the same fact — do not render a\n * provider, do offer the connect path. So it is correct to treat a `unknown` that\n * persists as a host bug rather than as a state to design around, and WRONG to render a\n * spinner with no timeout on it. (Before R3-419 the host withheld the channel entirely\n * from an ungranted frame, and `unknown` stood forever — that is the failure this note\n * exists to keep from being re-created on the app side.)\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;AAqH5C,SAAS,KAAK,KAA+D;AAGlF,QAAM,EAAE,QAAQ,GAAG,OAAO,IAAI;AAC9B,SAAO,aAAoC,YAAY,QAA8C,MAAM;AAC7G;AAmFO,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":[]}
+{"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  // Token accounting for the turn. `cacheReadTokens`/`cacheWriteTokens` are present\n  // only on providers that report prompt caching (R3-336) — they are what makes a\n  // caching claim verifiable rather than believed, and their ABSENCE is meaningful:\n  // it says this provider reports nothing, not that nothing was cached.\n  | {\n      type: 'usage';\n      inputTokens: number;\n      outputTokens: number;\n      cacheReadTokens?: number;\n      cacheWriteTokens?: number;\n    };\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 first\n * draws the SP-7 connect-me gate itself (R3-456: the app never draws a\n * credential prompt — that is host chrome, SECRETS_SPEC S3):\n * - the user connects a key → the call retries once and streams normally;\n * - the user declines → the generator throws `code: 'cancelled'` (the same code\n *   a declined powerbox produces — a working degraded state: catch it and\n *   degrade, e.g. skip the AI feature);\n * - an older host without the gate throws `code: 'provider-not-configured'`.\n * A signed-out user throws `code: 'auth-required'`; an un-granted call throws\n * `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/** How the resolved provider's requests physically leave the browser. Read it to\n *  DESCRIBE routing where that matters to the person (\"runs in your browser\" vs\n *  \"routed through immediately.run\") — never to draw host chrome or a consent prompt,\n *  which remain the host's (UI_AS_APPS §8 T15). */\nexport type ChatExecutor = 'browser-direct' | 'backend-proxied';\n\n/** The concrete model each abstract tier resolves to right now. */\nexport interface ChatTierModels {\n  fast: string;\n  smart: string;\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  /** The provider's human name, e.g. `OpenRouter` — what to put in front of a person.\n   *  Absent on a host that predates the field: fall back to your own copy rather than\n   *  rendering the id, which is a platform identifier and not a name. */\n  displayName?: string;\n  /** How this provider's requests leave the browser. Absent on a host that predates the\n   *  field, which is NOT the same as `browser-direct` — say nothing about routing rather\n   *  than guess at it. */\n  executor?: ChatExecutor;\n  /**\n   * The concrete model each {@link ChatRequest.modelHint} tier resolves to — what a\n   * `smart` request would actually run, after the user's own preference.\n   *\n   * Read-only, and it does not weaken `LLM_AND_AGENTS_SPEC §0`: an app still names no\n   * model, and {@link ChatRequest} still carries only the abstract hint. It is here so an\n   * app can be HONEST about what answered — a transcript that says which model wrote a\n   * reply, a warning that names the model about to be spent on — instead of showing a\n   * blank where the platform knows the answer. The user picks the model in host settings;\n   * the app reports it.\n   *\n   * Absent on a host that predates the field. It changes when the user changes their\n   * preference, so read it through {@link onChatProviderChange} rather than caching it.\n   */\n  models?: ChatTierModels;\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 *\n * **`unknown` is TRANSIENT — the host answers every frame** (R3-419;\n * `LLM_AND_AGENTS_SPEC §4.1` R-LLM-1..3). An app that does not hold `llm:chat` is not\n * met with silence: it is answered `not-configured`, the same terminal state as a user\n * with no key, because from the app's side those are the same fact — do not render a\n * provider, do offer the connect path. So it is correct to treat a `unknown` that\n * persists as a host bug rather than as a state to design around, and WRONG to render a\n * spinner with no timeout on it. (Before R3-419 the host withheld the channel entirely\n * from an ungranted frame, and `unknown` stood forever — that is the failure this note\n * exists to keep from being re-created on the app side.)\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 * Reconcile what the host actually sent with what this SDK declares.\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 * `displayName`, `executor` and `models` arrived later still, and for them absence is a\n * REAL answer an app is told to handle (\"this host does not say\"), so they are left\n * absent rather than filled in. What is dropped is a value that is present but not\n * usable — an `executor` outside the union, a `models` missing a tier — because a\n * half-answer rendered as fact is worse than the honest blank the app already handles.\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 */\nconst EXECUTORS: readonly ChatExecutor[] = ['browser-direct', 'backend-proxied'];\n\nconst usableModels = (raw: unknown): ChatTierModels | undefined => {\n  if (!raw || typeof raw !== 'object') return undefined;\n  const { fast, smart } = raw as Partial<ChatTierModels>;\n  return typeof fast === 'string' && fast && typeof smart === 'string' && smart ? { fast, smart } : undefined;\n};\n\nexport function normalizeProviderInfo(provider: ChatProviderInfo | null): ChatProviderInfo | null {\n  if (!provider) return null;\n  // The three later fields are taken OFF the value and put back only if usable — spreading\n  // and then overwriting would leave an unusable key present, and `key in provider` is\n  // exactly how an app is told to ask whether the host said anything.\n  const { displayName: rawName, executor: rawExecutor, models: rawModels, ...rest } = provider;\n  // The wire value is whatever the host sent, which may predate any of these fields — so\n  // read it as partial rather than trusting the declared type, and decide each explicitly.\n  const wire = provider.features as Partial<ChatFeatures>;\n  const executor = EXECUTORS.includes(rawExecutor as ChatExecutor) ? (rawExecutor as ChatExecutor) : undefined;\n  const displayName = typeof rawName === 'string' && rawName ? rawName : undefined;\n  const models = usableModels(rawModels);\n  return {\n    ...rest,\n    features: { ...wire, reasoning: wire.reasoning === true } as ChatFeatures,\n    ...(displayName ? { displayName } : {}),\n    ...(executor ? { executor } : {}),\n    ...(models ? { models } : {}),\n  };\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;AAqH5C,SAAS,KAAK,KAA+D;AAGlF,QAAM,EAAE,QAAQ,GAAG,OAAO,IAAI;AAC9B,SAAO,aAAoC,YAAY,QAA8C,MAAM;AAC7G;AAoHA,MAAM,YAAqC,CAAC,kBAAkB,iBAAiB;AAE/E,MAAM,eAAe,CAAC,QAA6C;AACjE,MAAI,CAAC,OAAO,OAAO,QAAQ,SAAU,QAAO;AAC5C,QAAM,EAAE,MAAM,MAAM,IAAI;AACxB,SAAO,OAAO,SAAS,YAAY,QAAQ,OAAO,UAAU,YAAY,QAAQ,EAAE,MAAM,MAAM,IAAI;AACpG;AAEO,SAAS,sBAAsB,UAA4D;AAChG,MAAI,CAAC,SAAU,QAAO;AAItB,QAAM,EAAE,aAAa,SAAS,UAAU,aAAa,QAAQ,WAAW,GAAG,KAAK,IAAI;AAGpF,QAAM,OAAO,SAAS;AACtB,QAAM,WAAW,UAAU,SAAS,WAA2B,IAAK,cAA+B;AACnG,QAAM,cAAc,OAAO,YAAY,YAAY,UAAU,UAAU;AACvE,QAAM,SAAS,aAAa,SAAS;AACrC,SAAO;AAAA,IACL,GAAG;AAAA,IACH,UAAU,EAAE,GAAG,MAAM,WAAW,KAAK,cAAc,KAAK;AAAA,IACxD,GAAI,cAAc,EAAE,YAAY,IAAI,CAAC;AAAA,IACrC,GAAI,WAAW,EAAE,SAAS,IAAI,CAAC;AAAA,IAC/B,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC;AAAA,EAC7B;AACF;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":[]}

package/dist/openRepository.cjs

@@ -0,0 +1,44 @@
+"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 openRepository_exports = {};
+__export(openRepository_exports, {
+  openRepository: () => openRepository
+});
+module.exports = __toCommonJS(openRepository_exports);
+var import_sandboxUtils = require("./sandboxUtils");
+var import_protocol = require("./generated/protocol");
+var import_protocolSchemes = require("./protocolSchemes");
+async function openRepository(coordinates) {
+  const { provider, namespace, repository } = coordinates;
+  const res = await (0, import_sandboxUtils.protocolRequest)(import_protocolSchemes.SCHEMES[import_protocol.PROTOCOL_OPENREPO], "open", [
+    { provider, namespace, repository }
+  ]);
+  if (!res || res.ok !== true) {
+    const err = new Error(
+      (res && "message" in res ? res.message : void 0) ?? "repository open refused"
+    );
+    err.code = (res && "code" in res ? res.code : void 0) ?? "unknown";
+    throw err;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  openRepository
+});
+//# sourceMappingURL=openRepository.cjs.map

package/dist/openRepository.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/openRepository.ts"],"sourcesContent":["// Host-mediated \"open this repository in a new tab\" (R3-476).\n//\n// An app frame cannot open a first-party tab itself. A `window.open` from inside the\n// sandboxed frame inherits the sandbox — the opened tab runs at the same opaque origin and\n// cannot load the host — and `target=\"_top\"` would replace the app's own frame rather than\n// open a tab. So the app asks the host, and the host performs the open from its own context.\n//\n// The app names COORDINATES and nothing else. It cannot pass a URL, a route prefix or a\n// path: the host builds the destination from its own route grammar, so this call can only\n// ever reach one of the platform's own repository routes. That is the point of the shape —\n// an app that could spell the destination could open anything.\n//\n// Two more conditions hold on the host side, and neither is something this call can assert\n// for itself: the open needs the HOST document's live transient user activation (a real\n// click, which the host samples rather than believes), and one gesture opens exactly one\n// tab. Both surface here as ordinary coded refusals.\nimport { protocolRequest } from './sandboxUtils';\nimport { PROTOCOL_OPENREPO } from './generated/protocol';\nimport { SCHEMES } from './protocolSchemes';\n\n/** Where a repository lives. The same three fields a `RecentProject` carries — this is a\n *  location the user may already have navigated to under their own authority. */\nexport interface RepositoryCoordinates {\n  provider: string;\n  namespace: string;\n  repository: string;\n}\n\n/** Why the host refused to open a tab.\n *\n *  - `invalid` — the coordinates are not three clean path segments.\n *  - `no-activation` — no live user gesture on the host document. Call this from a click\n *    handler; a timer or a boot path will always get this. A SECOND call inside one gesture\n *    also lands here: `window.open` consumes the host's transient activation, so one click\n *    buys exactly one tab and the next needs a real second click.\n *  - `forbidden` — the app does not hold the baseline `route:read` capability.\n *  - `unsupported` — this host has no repository-open surface wired.\n *  - `unknown` — the host refused without naming a code. */\nexport type OpenRepositoryErrorCode = 'invalid' | 'no-activation' | 'forbidden' | 'unsupported' | 'unknown';\n\nexport interface OpenRepositoryError extends Error {\n  code: OpenRepositoryErrorCode;\n}\n\n/** The host's reply: the envelope resolves INSIDE the promise, so a refusal is a resolved\n *  `{ ok: false }` rather than a rejection at the transport layer. */\ntype OpenRepositoryReply = { ok: true; url?: string } | { ok: false; code?: string; message?: string };\n\n/**\n * Ask the host to open a repository in a new browser tab.\n *\n * Resolves once the host has performed the open; it does not wait for — and cannot observe —\n * the opened tab loading. Rejects with a typed {@link OpenRepositoryError} carrying `code`\n * when the host refuses.\n *\n * Call it directly from a user gesture. The host samples its own transient activation when\n * the request arrives, so anything that defers the call past the gesture (an `await` before\n * it, a `setTimeout`, a retry) will be refused `no-activation`. None of the refusals are\n * worth retrying: each names a condition a retry cannot change.\n */\nexport async function openRepository(coordinates: RepositoryCoordinates): Promise<void> {\n  const { provider, namespace, repository } = coordinates;\n  const res = (await protocolRequest(SCHEMES[PROTOCOL_OPENREPO], 'open', [\n    { provider, namespace, repository },\n  ])) as OpenRepositoryReply;\n  // The refusal resolves inside the reply, so `res.ok !== true` is the only failure test\n  // there is — a bare-promise shape here would swallow every coded refusal as a success.\n  if (!res || res.ok !== true) {\n    const err = new Error(\n      (res && 'message' in res ? res.message : undefined) ?? 'repository open refused',\n    ) as OpenRepositoryError;\n    err.code = ((res && 'code' in res ? res.code : undefined) as OpenRepositoryErrorCode) ?? 'unknown';\n    throw err;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBA,0BAAgC;AAChC,sBAAkC;AAClC,6BAAwB;AA0CxB,eAAsB,eAAe,aAAmD;AACtF,QAAM,EAAE,UAAU,WAAW,WAAW,IAAI;AAC5C,QAAM,MAAO,UAAM,qCAAgB,+BAAQ,iCAAiB,GAAG,QAAQ;AAAA,IACrE,EAAE,UAAU,WAAW,WAAW;AAAA,EACpC,CAAC;AAGD,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI;AAAA,OACb,OAAO,aAAa,MAAM,IAAI,UAAU,WAAc;AAAA,IACzD;AACA,QAAI,QAAS,OAAO,UAAU,MAAM,IAAI,OAAO,WAA0C;AACzF,UAAM;AAAA,EACR;AACF;","names":[]}

package/dist/openRepository.d.cts

@@ -0,0 +1,36 @@
+/** Where a repository lives. The same three fields a `RecentProject` carries — this is a
+ *  location the user may already have navigated to under their own authority. */
+interface RepositoryCoordinates {
+    provider: string;
+    namespace: string;
+    repository: string;
+}
+/** Why the host refused to open a tab.
+ *
+ *  - `invalid` — the coordinates are not three clean path segments.
+ *  - `no-activation` — no live user gesture on the host document. Call this from a click
+ *    handler; a timer or a boot path will always get this. A SECOND call inside one gesture
+ *    also lands here: `window.open` consumes the host's transient activation, so one click
+ *    buys exactly one tab and the next needs a real second click.
+ *  - `forbidden` — the app does not hold the baseline `route:read` capability.
+ *  - `unsupported` — this host has no repository-open surface wired.
+ *  - `unknown` — the host refused without naming a code. */
+type OpenRepositoryErrorCode = 'invalid' | 'no-activation' | 'forbidden' | 'unsupported' | 'unknown';
+interface OpenRepositoryError extends Error {
+    code: OpenRepositoryErrorCode;
+}
+/**
+ * Ask the host to open a repository in a new browser tab.
+ *
+ * Resolves once the host has performed the open; it does not wait for — and cannot observe —
+ * the opened tab loading. Rejects with a typed {@link OpenRepositoryError} carrying `code`
+ * when the host refuses.
+ *
+ * Call it directly from a user gesture. The host samples its own transient activation when
+ * the request arrives, so anything that defers the call past the gesture (an `await` before
+ * it, a `setTimeout`, a retry) will be refused `no-activation`. None of the refusals are
+ * worth retrying: each names a condition a retry cannot change.
+ */
+declare function openRepository(coordinates: RepositoryCoordinates): Promise<void>;
+
+export { type OpenRepositoryError, type OpenRepositoryErrorCode, type RepositoryCoordinates, openRepository };

package/dist/openRepository.d.ts

@@ -0,0 +1,36 @@
+/** Where a repository lives. The same three fields a `RecentProject` carries — this is a
+ *  location the user may already have navigated to under their own authority. */
+interface RepositoryCoordinates {
+    provider: string;
+    namespace: string;
+    repository: string;
+}
+/** Why the host refused to open a tab.
+ *
+ *  - `invalid` — the coordinates are not three clean path segments.
+ *  - `no-activation` — no live user gesture on the host document. Call this from a click
+ *    handler; a timer or a boot path will always get this. A SECOND call inside one gesture
+ *    also lands here: `window.open` consumes the host's transient activation, so one click
+ *    buys exactly one tab and the next needs a real second click.
+ *  - `forbidden` — the app does not hold the baseline `route:read` capability.
+ *  - `unsupported` — this host has no repository-open surface wired.
+ *  - `unknown` — the host refused without naming a code. */
+type OpenRepositoryErrorCode = 'invalid' | 'no-activation' | 'forbidden' | 'unsupported' | 'unknown';
+interface OpenRepositoryError extends Error {
+    code: OpenRepositoryErrorCode;
+}
+/**
+ * Ask the host to open a repository in a new browser tab.
+ *
+ * Resolves once the host has performed the open; it does not wait for — and cannot observe —
+ * the opened tab loading. Rejects with a typed {@link OpenRepositoryError} carrying `code`
+ * when the host refuses.
+ *
+ * Call it directly from a user gesture. The host samples its own transient activation when
+ * the request arrives, so anything that defers the call past the gesture (an `await` before
+ * it, a `setTimeout`, a retry) will be refused `no-activation`. None of the refusals are
+ * worth retrying: each names a condition a retry cannot change.
+ */
+declare function openRepository(coordinates: RepositoryCoordinates): Promise<void>;
+
+export { type OpenRepositoryError, type OpenRepositoryErrorCode, type RepositoryCoordinates, openRepository };

package/dist/openRepository.js

@@ -0,0 +1,21 @@
+import "./chunk-VHAA22YE.js";
+import { protocolRequest } from "./sandboxUtils";
+import { PROTOCOL_OPENREPO } from "./generated/protocol";
+import { SCHEMES } from "./protocolSchemes";
+async function openRepository(coordinates) {
+  const { provider, namespace, repository } = coordinates;
+  const res = await protocolRequest(SCHEMES[PROTOCOL_OPENREPO], "open", [
+    { provider, namespace, repository }
+  ]);
+  if (!res || res.ok !== true) {
+    const err = new Error(
+      (res && "message" in res ? res.message : void 0) ?? "repository open refused"
+    );
+    err.code = (res && "code" in res ? res.code : void 0) ?? "unknown";
+    throw err;
+  }
+}
+export {
+  openRepository
+};
+//# sourceMappingURL=openRepository.js.map