@immediately-run/sdk 0.7.0 → 0.8.0

package/dist/index.cjs

@@ -31,6 +31,7 @@ __reExport(index_exports, require("./contribute"), module.exports);
 __reExport(index_exports, require("./catalog"), module.exports);
 __reExport(index_exports, require("./ipc"), module.exports);
 __reExport(index_exports, require("./netFetch"), module.exports);
+__reExport(index_exports, require("./secrets"), module.exports);
 __reExport(index_exports, require("./tasks"), module.exports);
 __reExport(index_exports, require("./runtime"), module.exports);
 __reExport(index_exports, require("./protocolStream"), module.exports);
@@ -53,6 +54,7 @@ __reExport(index_exports, require("./sandboxTypes"), module.exports);
   ...require("./catalog"),
   ...require("./ipc"),
   ...require("./netFetch"),
+  ...require("./secrets"),
   ...require("./tasks"),
   ...require("./runtime"),
   ...require("./protocolStream"),

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './netFetch';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":";;;;;;;;;;;;;;;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAIA,0BAAc,uCAJd;AAKA,0BAAc,oBALd;AAMA,0BAAc,mBANd;AAOA,0BAAc,oBAPd;AAQA,0BAAc,4BARd;AASA,0BAAc,qBATd;AAUA,0BAAc,yBAVd;AAWA,0BAAc,qBAXd;AAYA,0BAAc,yBAZd;AAaA,0BAAc,sBAbd;AAcA,0BAAc,kBAdd;AAeA,0BAAc,uBAfd;AAgBA,0BAAc,oBAhBd;AAiBA,0BAAc,sBAjBd;AAkBA,0BAAc,6BAlBd;AAmBA,0BAAc,2BAnBd;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":";;;;;;;;;;;;;;;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAIA,0BAAc,uCAJd;AAKA,0BAAc,oBALd;AAMA,0BAAc,mBANd;AAOA,0BAAc,oBAPd;AAQA,0BAAc,4BARd;AASA,0BAAc,qBATd;AAUA,0BAAc,yBAVd;AAWA,0BAAc,qBAXd;AAYA,0BAAc,yBAZd;AAaA,0BAAc,sBAbd;AAcA,0BAAc,kBAdd;AAeA,0BAAc,uBAfd;AAgBA,0BAAc,sBAhBd;AAiBA,0BAAc,oBAjBd;AAkBA,0BAAc,sBAlBd;AAmBA,0BAAc,6BAnBd;AAoBA,0BAAc,2BApBd;","names":[]}

package/dist/index.d.cts

@@ -13,7 +13,8 @@ export { GrantRecord, Member, MountQuery, ResolvedUser, Role, SandboxMount, Spac
 export { ContributeMode, ContributeOptions, ContributionEvent, ContributionResult, contribute } from './contribute.cjs';
 export { ApiMethod, getCatalog, invoke, invokeStream, onCatalogChange, useCatalog } from './catalog.cjs';
 export { RegionMessage, onRegionMessage, postToRegion, useRegionMessage } from './ipc.cjs';
-export { HostFetchInit, HostFetchResponse, hostFetch } from './netFetch.cjs';
+export { HostFetchInit, HostFetchResponse, HostFetchStreamEvent, HostFetchStreamResult, hostFetch, hostFetchStream } from './netFetch.cjs';
+export { SecretError, SecretGrant, SecretHints, SecretQuery, SecretType, SecretView, getSecrets, onSecretsChange, requestAddSecret, requestSecret, revokeSecret, useSecrets } from './secrets.cjs';
 export { FileCap, TaskInput, cancelTask, capFile, completeTask, getTaskInput, invokeTask, useTaskInput } from './tasks.cjs';
 export { SDK_PROTOCOL_VERSION, SDK_VERSION, SdkHandshake, announceHandshake, sdkHandshake } from './runtime.cjs';
 export { StreamError, StreamFrame, StreamTransport, consumeStream, protocolStream } from './protocolStream.cjs';

package/dist/index.d.ts

@@ -13,7 +13,8 @@ export { GrantRecord, Member, MountQuery, ResolvedUser, Role, SandboxMount, Spac
 export { ContributeMode, ContributeOptions, ContributionEvent, ContributionResult, contribute } from './contribute.js';
 export { ApiMethod, getCatalog, invoke, invokeStream, onCatalogChange, useCatalog } from './catalog.js';
 export { RegionMessage, onRegionMessage, postToRegion, useRegionMessage } from './ipc.js';
-export { HostFetchInit, HostFetchResponse, hostFetch } from './netFetch.js';
+export { HostFetchInit, HostFetchResponse, HostFetchStreamEvent, HostFetchStreamResult, hostFetch, hostFetchStream } from './netFetch.js';
+export { SecretError, SecretGrant, SecretHints, SecretQuery, SecretType, SecretView, getSecrets, onSecretsChange, requestAddSecret, requestSecret, revokeSecret, useSecrets } from './secrets.js';
 export { FileCap, TaskInput, cancelTask, capFile, completeTask, getTaskInput, invokeTask, useTaskInput } from './tasks.js';
 export { SDK_PROTOCOL_VERSION, SDK_VERSION, SdkHandshake, announceHandshake, sdkHandshake } from './runtime.js';
 export { StreamError, StreamFrame, StreamTransport, consumeStream, protocolStream } from './protocolStream.js';

package/dist/index.js

@@ -14,6 +14,7 @@ export * from "./contribute";
 export * from "./catalog";
 export * from "./ipc";
 export * from "./netFetch";
+export * from "./secrets";
 export * from "./tasks";
 export * from "./runtime";
 export * from "./protocolStream";

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';\nexport * from './components/MDXComponents';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './netFetch';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":"AAAA,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;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":"AAAA,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;","names":[]}

package/dist/netFetch.cjs

@@ -18,10 +18,12 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var netFetch_exports = {};
 __export(netFetch_exports, {
-  hostFetch: () => hostFetch
+  hostFetch: () => hostFetch,
+  hostFetchStream: () => hostFetchStream
 });
 module.exports = __toCommonJS(netFetch_exports);
 var import_sandboxUtils = require("./sandboxUtils");
+var import_protocolStream = require("./protocolStream");
 const hostFetch = async (url, init = {}) => {
   const res = await (0, import_sandboxUtils.protocolRequest)("fetch", "fetch", [
     { url, method: init.method, headers: init.headers, body: init.body }
@@ -33,8 +35,16 @@ const hostFetch = async (url, init = {}) => {
   }
   return res.data;
 };
+function hostFetchStream(url, init = {}) {
+  return (0, import_protocolStream.protocolStream)(
+    "protocol-fetch",
+    "fetchStream",
+    [{ url, method: init.method, headers: init.headers, body: init.body }]
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  hostFetch
+  hostFetch,
+  hostFetchStream
 });
 //# sourceMappingURL=netFetch.cjs.map

package/dist/netFetch.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/netFetch.ts"],"sourcesContent":["// hostFetch — the app-facing side of the §5.11 parent-fetch proxy. The app calls\n// `hostFetch(url, init)`; the HOST performs the fetch with its real origin, but\n// only after validating `url` against your manifest's\n// `requests.\"net:fetch\".hosts` ∩ the user's consented hosts, blocking SSRF\n// targets, omitting immediately.run credentials, refusing redirects, and bounding\n// the response size. No raw network handle ever crosses the boundary (§8.10) —\n// only the serialized response.\n\nimport { protocolRequest } from './sandboxUtils';\n\nexport interface HostFetchInit {\n  method?: string;\n  headers?: Record<string, string>;\n  /** Request body for non-GET/HEAD methods (string). */\n  body?: string;\n}\n\nexport interface HostFetchResponse {\n  status: number;\n  statusText: string;\n  headers: Record<string, string>;\n  body: string;\n  /** True if the body hit the host's size cap and was truncated. */\n  truncated: boolean;\n}\n\n/**\n * Fetch through the host's parent-fetch proxy (§5.11). Requires the `net:fetch`\n * capability with `url`'s origin in your effective allowlist (manifest ∩ the\n * user's consent) — both are arranged at load via the consent screen.\n *\n * A reachable server's reply (including a non-2xx status) RESOLVES — inspect\n * `.status`. A gate/SSRF/transport failure REJECTS with an {@link Error} carrying\n * a machine `.code`: `forbidden` (outside the allowlist), `blocked` (SSRF target),\n * `invalid` (bad url/scheme), `redirect` (the host refuses to follow redirects),\n * `too-large`, or `network`.\n */\nexport const hostFetch = async (\n  url: string,\n  init: HostFetchInit = {},\n): Promise<HostFetchResponse> => {\n  const res = (await protocolRequest('fetch', 'fetch', [\n    { url, method: init.method, headers: init.headers, body: init.body },\n  ])) as\n    | { ok: true; data: HostFetchResponse }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'hostFetch failed') as Error & { code?: string };\n    err.code = (res && 'code' in res ? res.code : undefined) ?? 'unknown';\n    throw err;\n  }\n  return res.data;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAQA,0BAAgC;AA6BzB,MAAM,YAAY,OACvB,KACA,OAAsB,CAAC,MACQ;AAC/B,QAAM,MAAO,UAAM,qCAAgB,SAAS,SAAS;AAAA,IACnD,EAAE,KAAK,QAAQ,KAAK,QAAQ,SAAS,KAAK,SAAS,MAAM,KAAK,KAAK;AAAA,EACrE,CAAC;AAID,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,kBAAkB;AACxD,QAAI,QAAQ,OAAO,UAAU,MAAM,IAAI,OAAO,WAAc;AAC5D,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;","names":[]}
+{"version":3,"sources":["../src/netFetch.ts"],"sourcesContent":["// hostFetch — the app-facing side of the §5.11 parent-fetch proxy. The app calls\n// `hostFetch(url, init)`; the HOST performs the fetch with its real origin, but\n// only after validating `url` against your manifest's\n// `requests.\"net:fetch\".hosts` ∩ the user's consented hosts, blocking SSRF\n// targets, omitting immediately.run credentials, refusing redirects, and bounding\n// the response size. No raw network handle ever crosses the boundary (§8.10) —\n// only the serialized response.\n\nimport { protocolRequest } from './sandboxUtils';\nimport { protocolStream } from './protocolStream';\n\nexport interface HostFetchInit {\n  method?: string;\n  headers?: Record<string, string>;\n  /** Request body for non-GET/HEAD methods (string). */\n  body?: string;\n}\n\nexport interface HostFetchResponse {\n  status: number;\n  statusText: string;\n  headers: Record<string, string>;\n  body: string;\n  /** True if the body hit the host's size cap and was truncated. */\n  truncated: boolean;\n}\n\n/**\n * Fetch through the host's parent-fetch proxy (§5.11). Requires the `net:fetch`\n * capability with `url`'s origin in your effective allowlist (manifest ∩ the\n * user's consent) — both are arranged at load via the consent screen.\n *\n * A reachable server's reply (including a non-2xx status) RESOLVES — inspect\n * `.status`. A gate/SSRF/transport failure REJECTS with an {@link Error} carrying\n * a machine `.code`: `forbidden` (outside the allowlist), `blocked` (SSRF target),\n * `invalid` (bad url/scheme), `redirect` (the host refuses to follow redirects),\n * `too-large`, or `network`.\n */\nexport const hostFetch = async (\n  url: string,\n  init: HostFetchInit = {},\n): Promise<HostFetchResponse> => {\n  const res = (await protocolRequest('fetch', 'fetch', [\n    { url, method: init.method, headers: init.headers, body: init.body },\n  ])) as\n    | { ok: true; data: HostFetchResponse }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'hostFetch failed') as Error & { code?: string };\n    err.code = (res && 'code' in res ? res.code : undefined) ?? 'unknown';\n    throw err;\n  }\n  return res.data;\n};\n\n/** One streamed slice of the response body (a chunk as it arrives from the\n *  host). Concatenate `.chunk` across the stream to rebuild the body. */\nexport interface HostFetchStreamEvent {\n  chunk: string;\n}\n\n/** The terminal value of a {@link hostFetchStream} run — the response metadata,\n *  delivered once after the last body chunk. There is no `body` field: the body\n *  arrived as the stream of {@link HostFetchStreamEvent}s. */\nexport interface HostFetchStreamResult {\n  status: number;\n  statusText: string;\n  headers: Record<string, string>;\n  /** True if the stream hit the host's cumulative byte cap and was truncated. */\n  truncated: boolean;\n  /** Total decoded body bytes delivered. */\n  bytes: number;\n}\n\n/**\n * Stream a response through the host's parent-fetch proxy (§5.11 streaming;\n * `LLM_AND_AGENTS_SPEC §2.2`) — the streaming counterpart of {@link hostFetch},\n * for SSE / LLM token streaming. Same `net:fetch` gate (manifest ∩ consent),\n * same credential-less rule and per-hop SSRF re-check; the response body is\n * pumped as a sequence of {@link HostFetchStreamEvent} chunks instead of a single\n * buffered reply.\n *\n * ```ts\n * let body = '';\n * for await (const { chunk } of hostFetchStream(url, { method: 'POST', body })) {\n *   body += chunk;            // e.g. parse SSE / token deltas as they arrive\n * }\n * ```\n *\n * The generator **returns** a {@link HostFetchStreamResult} (status + headers +\n * `truncated`/`bytes`) when the body completes. A gate/SSRF/transport failure —\n * or one of the host's stream bounds — **throws** a `StreamError` (from\n * `./protocolStream`) carrying a\n * machine `.code`: `forbidden` (outside the allowlist), `blocked` (SSRF target),\n * `invalid` (bad url/scheme), `redirect` (the host refuses to follow redirects),\n * `idle-timeout` / `total-timeout` (the host's stream bounds), `byte-cap`, or\n * `network`. The stream is bounded by the host's idle/total timeouts and a\n * cumulative byte cap, so it cannot be used as an unbounded transfer channel.\n *\n * Requires the host to implement the `protocol-fetch` streaming emitter; until\n * that lands a streaming request fails with `not-streamable` and callers should\n * fall back to {@link hostFetch} (`LLM_AND_AGENTS_SPEC §2.2`, roadmap P3-71).\n */\nexport function hostFetchStream(\n  url: string,\n  init: HostFetchInit = {},\n): AsyncGenerator<HostFetchStreamEvent, HostFetchStreamResult, void> {\n  return protocolStream<HostFetchStreamEvent, HostFetchStreamResult>(\n    'protocol-fetch',\n    'fetchStream',\n    [{ url, method: init.method, headers: init.headers, body: init.body }],\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAQA,0BAAgC;AAChC,4BAA+B;AA6BxB,MAAM,YAAY,OACvB,KACA,OAAsB,CAAC,MACQ;AAC/B,QAAM,MAAO,UAAM,qCAAgB,SAAS,SAAS;AAAA,IACnD,EAAE,KAAK,QAAQ,KAAK,QAAQ,SAAS,KAAK,SAAS,MAAM,KAAK,KAAK;AAAA,EACrE,CAAC;AAID,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,kBAAkB;AACxD,QAAI,QAAQ,OAAO,UAAU,MAAM,IAAI,OAAO,WAAc;AAC5D,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AAkDO,SAAS,gBACd,KACA,OAAsB,CAAC,GAC4C;AACnE,aAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,CAAC,EAAE,KAAK,QAAQ,KAAK,QAAQ,SAAS,KAAK,SAAS,MAAM,KAAK,KAAK,CAAC;AAAA,EACvE;AACF;","names":[]}

package/dist/netFetch.d.cts

@@ -24,5 +24,52 @@ interface HostFetchResponse {
  * `too-large`, or `network`.
  */
 declare const hostFetch: (url: string, init?: HostFetchInit) => Promise<HostFetchResponse>;
+/** One streamed slice of the response body (a chunk as it arrives from the
+ *  host). Concatenate `.chunk` across the stream to rebuild the body. */
+interface HostFetchStreamEvent {
+    chunk: string;
+}
+/** The terminal value of a {@link hostFetchStream} run — the response metadata,
+ *  delivered once after the last body chunk. There is no `body` field: the body
+ *  arrived as the stream of {@link HostFetchStreamEvent}s. */
+interface HostFetchStreamResult {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    /** True if the stream hit the host's cumulative byte cap and was truncated. */
+    truncated: boolean;
+    /** Total decoded body bytes delivered. */
+    bytes: number;
+}
+/**
+ * Stream a response through the host's parent-fetch proxy (§5.11 streaming;
+ * `LLM_AND_AGENTS_SPEC §2.2`) — the streaming counterpart of {@link hostFetch},
+ * for SSE / LLM token streaming. Same `net:fetch` gate (manifest ∩ consent),
+ * same credential-less rule and per-hop SSRF re-check; the response body is
+ * pumped as a sequence of {@link HostFetchStreamEvent} chunks instead of a single
+ * buffered reply.
+ *
+ * ```ts
+ * let body = '';
+ * for await (const { chunk } of hostFetchStream(url, { method: 'POST', body })) {
+ *   body += chunk;            // e.g. parse SSE / token deltas as they arrive
+ * }
+ * ```
+ *
+ * The generator **returns** a {@link HostFetchStreamResult} (status + headers +
+ * `truncated`/`bytes`) when the body completes. A gate/SSRF/transport failure —
+ * or one of the host's stream bounds — **throws** a `StreamError` (from
+ * `./protocolStream`) carrying a
+ * machine `.code`: `forbidden` (outside the allowlist), `blocked` (SSRF target),
+ * `invalid` (bad url/scheme), `redirect` (the host refuses to follow redirects),
+ * `idle-timeout` / `total-timeout` (the host's stream bounds), `byte-cap`, or
+ * `network`. The stream is bounded by the host's idle/total timeouts and a
+ * cumulative byte cap, so it cannot be used as an unbounded transfer channel.
+ *
+ * Requires the host to implement the `protocol-fetch` streaming emitter; until
+ * that lands a streaming request fails with `not-streamable` and callers should
+ * fall back to {@link hostFetch} (`LLM_AND_AGENTS_SPEC §2.2`, roadmap P3-71).
+ */
+declare function hostFetchStream(url: string, init?: HostFetchInit): AsyncGenerator<HostFetchStreamEvent, HostFetchStreamResult, void>;
 
-export { type HostFetchInit, type HostFetchResponse, hostFetch };
+export { type HostFetchInit, type HostFetchResponse, type HostFetchStreamEvent, type HostFetchStreamResult, hostFetch, hostFetchStream };

package/dist/netFetch.d.ts

@@ -24,5 +24,52 @@ interface HostFetchResponse {
  * `too-large`, or `network`.
  */
 declare const hostFetch: (url: string, init?: HostFetchInit) => Promise<HostFetchResponse>;
+/** One streamed slice of the response body (a chunk as it arrives from the
+ *  host). Concatenate `.chunk` across the stream to rebuild the body. */
+interface HostFetchStreamEvent {
+    chunk: string;
+}
+/** The terminal value of a {@link hostFetchStream} run — the response metadata,
+ *  delivered once after the last body chunk. There is no `body` field: the body
+ *  arrived as the stream of {@link HostFetchStreamEvent}s. */
+interface HostFetchStreamResult {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    /** True if the stream hit the host's cumulative byte cap and was truncated. */
+    truncated: boolean;
+    /** Total decoded body bytes delivered. */
+    bytes: number;
+}
+/**
+ * Stream a response through the host's parent-fetch proxy (§5.11 streaming;
+ * `LLM_AND_AGENTS_SPEC §2.2`) — the streaming counterpart of {@link hostFetch},
+ * for SSE / LLM token streaming. Same `net:fetch` gate (manifest ∩ consent),
+ * same credential-less rule and per-hop SSRF re-check; the response body is
+ * pumped as a sequence of {@link HostFetchStreamEvent} chunks instead of a single
+ * buffered reply.
+ *
+ * ```ts
+ * let body = '';
+ * for await (const { chunk } of hostFetchStream(url, { method: 'POST', body })) {
+ *   body += chunk;            // e.g. parse SSE / token deltas as they arrive
+ * }
+ * ```
+ *
+ * The generator **returns** a {@link HostFetchStreamResult} (status + headers +
+ * `truncated`/`bytes`) when the body completes. A gate/SSRF/transport failure —
+ * or one of the host's stream bounds — **throws** a `StreamError` (from
+ * `./protocolStream`) carrying a
+ * machine `.code`: `forbidden` (outside the allowlist), `blocked` (SSRF target),
+ * `invalid` (bad url/scheme), `redirect` (the host refuses to follow redirects),
+ * `idle-timeout` / `total-timeout` (the host's stream bounds), `byte-cap`, or
+ * `network`. The stream is bounded by the host's idle/total timeouts and a
+ * cumulative byte cap, so it cannot be used as an unbounded transfer channel.
+ *
+ * Requires the host to implement the `protocol-fetch` streaming emitter; until
+ * that lands a streaming request fails with `not-streamable` and callers should
+ * fall back to {@link hostFetch} (`LLM_AND_AGENTS_SPEC §2.2`, roadmap P3-71).
+ */
+declare function hostFetchStream(url: string, init?: HostFetchInit): AsyncGenerator<HostFetchStreamEvent, HostFetchStreamResult, void>;
 
-export { type HostFetchInit, type HostFetchResponse, hostFetch };
+export { type HostFetchInit, type HostFetchResponse, type HostFetchStreamEvent, type HostFetchStreamResult, hostFetch, hostFetchStream };

package/dist/netFetch.js

@@ -1,4 +1,5 @@
 import { protocolRequest } from "./sandboxUtils";
+import { protocolStream } from "./protocolStream";
 const hostFetch = async (url, init = {}) => {
   const res = await protocolRequest("fetch", "fetch", [
     { url, method: init.method, headers: init.headers, body: init.body }
@@ -10,7 +11,15 @@ const hostFetch = async (url, init = {}) => {
   }
   return res.data;
 };
+function hostFetchStream(url, init = {}) {
+  return protocolStream(
+    "protocol-fetch",
+    "fetchStream",
+    [{ url, method: init.method, headers: init.headers, body: init.body }]
+  );
+}
 export {
-  hostFetch
+  hostFetch,
+  hostFetchStream
 };
 //# sourceMappingURL=netFetch.js.map

package/dist/netFetch.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/netFetch.ts"],"sourcesContent":["// hostFetch — the app-facing side of the §5.11 parent-fetch proxy. The app calls\n// `hostFetch(url, init)`; the HOST performs the fetch with its real origin, but\n// only after validating `url` against your manifest's\n// `requests.\"net:fetch\".hosts` ∩ the user's consented hosts, blocking SSRF\n// targets, omitting immediately.run credentials, refusing redirects, and bounding\n// the response size. No raw network handle ever crosses the boundary (§8.10) —\n// only the serialized response.\n\nimport { protocolRequest } from './sandboxUtils';\n\nexport interface HostFetchInit {\n  method?: string;\n  headers?: Record<string, string>;\n  /** Request body for non-GET/HEAD methods (string). */\n  body?: string;\n}\n\nexport interface HostFetchResponse {\n  status: number;\n  statusText: string;\n  headers: Record<string, string>;\n  body: string;\n  /** True if the body hit the host's size cap and was truncated. */\n  truncated: boolean;\n}\n\n/**\n * Fetch through the host's parent-fetch proxy (§5.11). Requires the `net:fetch`\n * capability with `url`'s origin in your effective allowlist (manifest ∩ the\n * user's consent) — both are arranged at load via the consent screen.\n *\n * A reachable server's reply (including a non-2xx status) RESOLVES — inspect\n * `.status`. A gate/SSRF/transport failure REJECTS with an {@link Error} carrying\n * a machine `.code`: `forbidden` (outside the allowlist), `blocked` (SSRF target),\n * `invalid` (bad url/scheme), `redirect` (the host refuses to follow redirects),\n * `too-large`, or `network`.\n */\nexport const hostFetch = async (\n  url: string,\n  init: HostFetchInit = {},\n): Promise<HostFetchResponse> => {\n  const res = (await protocolRequest('fetch', 'fetch', [\n    { url, method: init.method, headers: init.headers, body: init.body },\n  ])) as\n    | { ok: true; data: HostFetchResponse }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'hostFetch failed') as Error & { code?: string };\n    err.code = (res && 'code' in res ? res.code : undefined) ?? 'unknown';\n    throw err;\n  }\n  return res.data;\n};\n"],"mappings":"AAQA,SAAS,uBAAuB;AA6BzB,MAAM,YAAY,OACvB,KACA,OAAsB,CAAC,MACQ;AAC/B,QAAM,MAAO,MAAM,gBAAgB,SAAS,SAAS;AAAA,IACnD,EAAE,KAAK,QAAQ,KAAK,QAAQ,SAAS,KAAK,SAAS,MAAM,KAAK,KAAK;AAAA,EACrE,CAAC;AAID,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,kBAAkB;AACxD,QAAI,QAAQ,OAAO,UAAU,MAAM,IAAI,OAAO,WAAc;AAC5D,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;","names":[]}
+{"version":3,"sources":["../src/netFetch.ts"],"sourcesContent":["// hostFetch — the app-facing side of the §5.11 parent-fetch proxy. The app calls\n// `hostFetch(url, init)`; the HOST performs the fetch with its real origin, but\n// only after validating `url` against your manifest's\n// `requests.\"net:fetch\".hosts` ∩ the user's consented hosts, blocking SSRF\n// targets, omitting immediately.run credentials, refusing redirects, and bounding\n// the response size. No raw network handle ever crosses the boundary (§8.10) —\n// only the serialized response.\n\nimport { protocolRequest } from './sandboxUtils';\nimport { protocolStream } from './protocolStream';\n\nexport interface HostFetchInit {\n  method?: string;\n  headers?: Record<string, string>;\n  /** Request body for non-GET/HEAD methods (string). */\n  body?: string;\n}\n\nexport interface HostFetchResponse {\n  status: number;\n  statusText: string;\n  headers: Record<string, string>;\n  body: string;\n  /** True if the body hit the host's size cap and was truncated. */\n  truncated: boolean;\n}\n\n/**\n * Fetch through the host's parent-fetch proxy (§5.11). Requires the `net:fetch`\n * capability with `url`'s origin in your effective allowlist (manifest ∩ the\n * user's consent) — both are arranged at load via the consent screen.\n *\n * A reachable server's reply (including a non-2xx status) RESOLVES — inspect\n * `.status`. A gate/SSRF/transport failure REJECTS with an {@link Error} carrying\n * a machine `.code`: `forbidden` (outside the allowlist), `blocked` (SSRF target),\n * `invalid` (bad url/scheme), `redirect` (the host refuses to follow redirects),\n * `too-large`, or `network`.\n */\nexport const hostFetch = async (\n  url: string,\n  init: HostFetchInit = {},\n): Promise<HostFetchResponse> => {\n  const res = (await protocolRequest('fetch', 'fetch', [\n    { url, method: init.method, headers: init.headers, body: init.body },\n  ])) as\n    | { ok: true; data: HostFetchResponse }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'hostFetch failed') as Error & { code?: string };\n    err.code = (res && 'code' in res ? res.code : undefined) ?? 'unknown';\n    throw err;\n  }\n  return res.data;\n};\n\n/** One streamed slice of the response body (a chunk as it arrives from the\n *  host). Concatenate `.chunk` across the stream to rebuild the body. */\nexport interface HostFetchStreamEvent {\n  chunk: string;\n}\n\n/** The terminal value of a {@link hostFetchStream} run — the response metadata,\n *  delivered once after the last body chunk. There is no `body` field: the body\n *  arrived as the stream of {@link HostFetchStreamEvent}s. */\nexport interface HostFetchStreamResult {\n  status: number;\n  statusText: string;\n  headers: Record<string, string>;\n  /** True if the stream hit the host's cumulative byte cap and was truncated. */\n  truncated: boolean;\n  /** Total decoded body bytes delivered. */\n  bytes: number;\n}\n\n/**\n * Stream a response through the host's parent-fetch proxy (§5.11 streaming;\n * `LLM_AND_AGENTS_SPEC §2.2`) — the streaming counterpart of {@link hostFetch},\n * for SSE / LLM token streaming. Same `net:fetch` gate (manifest ∩ consent),\n * same credential-less rule and per-hop SSRF re-check; the response body is\n * pumped as a sequence of {@link HostFetchStreamEvent} chunks instead of a single\n * buffered reply.\n *\n * ```ts\n * let body = '';\n * for await (const { chunk } of hostFetchStream(url, { method: 'POST', body })) {\n *   body += chunk;            // e.g. parse SSE / token deltas as they arrive\n * }\n * ```\n *\n * The generator **returns** a {@link HostFetchStreamResult} (status + headers +\n * `truncated`/`bytes`) when the body completes. A gate/SSRF/transport failure —\n * or one of the host's stream bounds — **throws** a `StreamError` (from\n * `./protocolStream`) carrying a\n * machine `.code`: `forbidden` (outside the allowlist), `blocked` (SSRF target),\n * `invalid` (bad url/scheme), `redirect` (the host refuses to follow redirects),\n * `idle-timeout` / `total-timeout` (the host's stream bounds), `byte-cap`, or\n * `network`. The stream is bounded by the host's idle/total timeouts and a\n * cumulative byte cap, so it cannot be used as an unbounded transfer channel.\n *\n * Requires the host to implement the `protocol-fetch` streaming emitter; until\n * that lands a streaming request fails with `not-streamable` and callers should\n * fall back to {@link hostFetch} (`LLM_AND_AGENTS_SPEC §2.2`, roadmap P3-71).\n */\nexport function hostFetchStream(\n  url: string,\n  init: HostFetchInit = {},\n): AsyncGenerator<HostFetchStreamEvent, HostFetchStreamResult, void> {\n  return protocolStream<HostFetchStreamEvent, HostFetchStreamResult>(\n    'protocol-fetch',\n    'fetchStream',\n    [{ url, method: init.method, headers: init.headers, body: init.body }],\n  );\n}\n"],"mappings":"AAQA,SAAS,uBAAuB;AAChC,SAAS,sBAAsB;AA6BxB,MAAM,YAAY,OACvB,KACA,OAAsB,CAAC,MACQ;AAC/B,QAAM,MAAO,MAAM,gBAAgB,SAAS,SAAS;AAAA,IACnD,EAAE,KAAK,QAAQ,KAAK,QAAQ,SAAS,KAAK,SAAS,MAAM,KAAK,KAAK;AAAA,EACrE,CAAC;AAID,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,kBAAkB;AACxD,QAAI,QAAQ,OAAO,UAAU,MAAM,IAAI,OAAO,WAAc;AAC5D,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AAkDO,SAAS,gBACd,KACA,OAAsB,CAAC,GAC4C;AACnE,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,CAAC,EAAE,KAAK,QAAQ,KAAK,QAAQ,SAAS,KAAK,SAAS,MAAM,KAAK,KAAK,CAAC;AAAA,EACvE;AACF;","names":[]}

package/dist/secrets.cjs

@@ -0,0 +1,63 @@
+"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 secrets_exports = {};
+__export(secrets_exports, {
+  getSecrets: () => getSecrets,
+  onSecretsChange: () => onSecretsChange,
+  requestAddSecret: () => requestAddSecret,
+  requestSecret: () => requestSecret,
+  revokeSecret: () => revokeSecret,
+  useSecrets: () => useSecrets
+});
+module.exports = __toCommonJS(secrets_exports);
+var import_sandboxUtils = require("./sandboxUtils");
+var import_pushChannel = require("./pushChannel");
+const request = async (method, query = {}) => {
+  const res = await (0, import_sandboxUtils.protocolRequest)("secrets", method, [query]);
+  if (!res || res.ok !== true) {
+    const err = new Error(res?.message ?? "secret request failed");
+    err.code = res?.code ?? "unknown";
+    throw err;
+  }
+  return res.data;
+};
+const requestAddSecret = (hints = {}) => request("add", hints);
+const requestSecret = (query = {}) => request("request", query);
+const revokeSecret = async (id) => {
+  await request("revoke", { id });
+};
+const channel = (0, import_pushChannel.createPushChannel)({
+  pushType: "secrets-metadata",
+  requestType: "request-secrets-metadata",
+  initial: [],
+  parse: (msg) => Array.isArray(msg.secrets) ? msg.secrets : void 0
+});
+const getSecrets = () => channel.get();
+const onSecretsChange = (listener) => channel.onChange(listener);
+const useSecrets = () => channel.use();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getSecrets,
+  onSecretsChange,
+  requestAddSecret,
+  requestSecret,
+  revokeSecret,
+  useSecrets
+});
+//# sourceMappingURL=secrets.cjs.map

package/dist/secrets.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/secrets.ts"],"sourcesContent":["// The host-owned secret store — app-facing surface (SECRETS_SPEC §4/§5).\n//\n// An app can ASK the user to store a secret (`requestAddSecret`), be GRANTED the\n// right to USE a specific secret (`requestSecret`, the powerbox flow), LIST\n// secret METADATA (`getSecrets`/`useSecrets`, never values), and REVOKE one\n// (`revokeSecret`). The secret VALUE never crosses this boundary: it is read\n// host-side, once, at the `net:fetch` injection point (SECRETS_SPEC §6). These\n// functions move only hints, metadata, and grant handles.\n//\n// Resolves LLM_AND_AGENTS_SPEC D2 — the host-mediated BYOK key store. Inert until\n// the host implements `protocol-secrets` + the `secrets-metadata` channel\n// (SECRETS_SPEC §3/§6 host work, roadmap P1.E); the contract is shipped here so\n// apps (e.g. the in-browser coding agent, P3-73) can be written against it.\nimport { protocolRequest } from './sandboxUtils';\nimport { createPushChannel } from './pushChannel';\n\n/** The closed secret-type vocabulary (SECRETS_SPEC §2). `api-key` is always\n *  origin-bound; `oauth-refresh` is reserved (no substitution in v1). */\nexport type SecretType = 'api-key' | 'bearer-token' | 'oauth-refresh';\n\n/**\n * The metadata-only projection of a stored secret (SECRETS_SPEC §2/§4) — exactly\n * what `secrets:list` and the powerbox return. **There is no `value` field by\n * design**: the plaintext is never part of any record an app receives.\n */\nexport interface SecretView {\n  id: string;\n  type: SecretType;\n  family?: string;\n  description: string;\n  /** Required for `type:'api-key'` — the one https origin it may be sent to. */\n  boundOrigin?: string;\n  /** ISO-8601, or null if never used (drives the §8.15 90-day expiry). */\n  lastUsedAt: string | null;\n}\n\n/** Hints for the host's \"add secret\" modal (SECRETS_SPEC §4 `secrets:add`). The\n *  app supplies only hints; the user types the value into host chrome. */\nexport interface SecretHints {\n  type?: SecretType;\n  family?: string;\n  /** Pre-fill the bound origin (e.g. `https://api.anthropic.com`). */\n  suggestedOrigin?: string;\n  description?: string;\n}\n\n/** What `requestSecret()` matches against in the powerbox picker (SECRETS_SPEC §5). */\nexport interface SecretQuery {\n  type?: SecretType;\n  family?: string;\n}\n\n/**\n * The result of a granted `requestSecret()` — a durable `(appKey, secretId)` use\n * grant plus the secret's metadata. **Never the value.** Hold onto nothing but\n * this; the host substitutes the value into matching `net:fetch` requests.\n */\nexport interface SecretGrant {\n  /** Opaque handle for the minted `(appKey, secretId)` grant. */\n  grantId: string;\n  /** Metadata of the bound secret (no value). */\n  secret: SecretView;\n}\n\n/** An error from a secret operation, carrying a machine-readable `code`. */\nexport interface SecretError extends Error {\n  code: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'invalid-params' | 'unknown';\n}\n\ntype SecretResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\n// Issue a `protocol-secrets` request, unwrapping the host's {ok,data} envelope\n// and throwing a typed SecretError on failure (mirrors mounts.ts `request`).\nconst request = async <T = unknown>(\n  method: string,\n  query: object = {},\n): Promise<T> => {\n  const res = (await protocolRequest('secrets', method, [query])) as SecretResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'secret request failed') as SecretError;\n    err.code = (res?.code as SecretError['code']) ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n/**\n * Ask the user to store a new secret (SECRETS_SPEC §4 `secrets:add`). Opens a\n * **host-drawn** modal (the value is typed into host chrome, never via the app);\n * resolves with the new secret's {@link SecretView} metadata, or rejects with a\n * {@link SecretError} (`cancelled` if the user dismisses the modal). Requires the\n * `secrets:add` capability.\n */\nexport const requestAddSecret = (hints: SecretHints = {}): Promise<SecretView> =>\n  request<SecretView>('add', hints);\n\n/**\n * Ask the user to bind one of their stored secrets to this app (SECRETS_SPEC §5,\n * the powerbox flow — modeled on `requestSpace()`). The host draws a picker of\n * **only the user's matching secrets**; the user picks, declines, or creates one.\n * On success the host records a durable `(appKey, secretId)` grant and resolves\n * with a {@link SecretGrant} (handle + metadata, **never the value**).\n *\n * **No existence oracle (T20/T27):** a decline, an ungranted secret, and a\n * nonexistent secret are indistinguishable — all reject with a {@link SecretError}\n * `cancelled`; the app never sees the list it chose from.\n */\nexport const requestSecret = (query: SecretQuery = {}): Promise<SecretGrant> =>\n  request<SecretGrant>('request', query);\n\n/**\n * Delete a stored secret and tombstone every dependent per-app use grant\n * (SECRETS_SPEC §4 `secrets:revoke`, §8.15 cascade). Requires `secrets:revoke`.\n */\nexport const revokeSecret = async (id: string): Promise<void> => {\n  await request('revoke', { id });\n};\n\n// The metadata-only `secrets-metadata` channel (Recipe A): the host pushes the\n// current secret metadata on change and replays it on register-frame; gated by\n// `secrets:list`. NEVER carries a value (SECRETS_SPEC §4).\nconst channel = createPushChannel<SecretView[]>({\n  pushType: 'secrets-metadata',\n  requestType: 'request-secrets-metadata',\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.secrets) ? (msg.secrets as SecretView[]) : undefined),\n});\n\n/** The metadata of the user's stored secrets (never values), `secrets:list`. Poll\n *  for a one-off read; use {@link onSecretsChange}/{@link useSecrets} to react. */\nexport const getSecrets = (): SecretView[] => channel.get();\n\n/** Subscribe to secret-metadata changes (added/revoked). Invoked immediately with\n *  the current list, then on every change. Returns an unsubscribe fn. */\nexport const onSecretsChange = (listener: (secrets: SecretView[]) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning the user's secret metadata (never values), re-rendering\n *  on change. For the Settings app (SECRETS_SPEC §7). */\nexport const useSecrets = (): SecretView[] => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAaA,0BAAgC;AAChC,yBAAkC;AA6DlC,MAAM,UAAU,OACd,QACA,QAAgB,CAAC,MACF;AACf,QAAM,MAAO,UAAM,qCAAgB,WAAW,QAAQ,CAAC,KAAK,CAAC;AAC7D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,uBAAuB;AAC7D,QAAI,OAAQ,KAAK,QAAgC;AACjD,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AASO,MAAM,mBAAmB,CAAC,QAAqB,CAAC,MACrD,QAAoB,OAAO,KAAK;AAa3B,MAAM,gBAAgB,CAAC,QAAqB,CAAC,MAClD,QAAqB,WAAW,KAAK;AAMhC,MAAM,eAAe,OAAO,OAA8B;AAC/D,QAAM,QAAQ,UAAU,EAAE,GAAG,CAAC;AAChC;AAKA,MAAM,cAAU,sCAAgC;AAAA,EAC9C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,CAAC;AAAA,EACV,OAAO,CAAC,QAAS,MAAM,QAAQ,IAAI,OAAO,IAAK,IAAI,UAA2B;AAChF,CAAC;AAIM,MAAM,aAAa,MAAoB,QAAQ,IAAI;AAInD,MAAM,kBAAkB,CAAC,aAC9B,QAAQ,SAAS,QAAQ;AAIpB,MAAM,aAAa,MAAoB,QAAQ,IAAI;","names":[]}

package/dist/secrets.d.cts

@@ -0,0 +1,83 @@
+/** The closed secret-type vocabulary (SECRETS_SPEC §2). `api-key` is always
+ *  origin-bound; `oauth-refresh` is reserved (no substitution in v1). */
+type SecretType = 'api-key' | 'bearer-token' | 'oauth-refresh';
+/**
+ * The metadata-only projection of a stored secret (SECRETS_SPEC §2/§4) — exactly
+ * what `secrets:list` and the powerbox return. **There is no `value` field by
+ * design**: the plaintext is never part of any record an app receives.
+ */
+interface SecretView {
+    id: string;
+    type: SecretType;
+    family?: string;
+    description: string;
+    /** Required for `type:'api-key'` — the one https origin it may be sent to. */
+    boundOrigin?: string;
+    /** ISO-8601, or null if never used (drives the §8.15 90-day expiry). */
+    lastUsedAt: string | null;
+}
+/** Hints for the host's "add secret" modal (SECRETS_SPEC §4 `secrets:add`). The
+ *  app supplies only hints; the user types the value into host chrome. */
+interface SecretHints {
+    type?: SecretType;
+    family?: string;
+    /** Pre-fill the bound origin (e.g. `https://api.anthropic.com`). */
+    suggestedOrigin?: string;
+    description?: string;
+}
+/** What `requestSecret()` matches against in the powerbox picker (SECRETS_SPEC §5). */
+interface SecretQuery {
+    type?: SecretType;
+    family?: string;
+}
+/**
+ * The result of a granted `requestSecret()` — a durable `(appKey, secretId)` use
+ * grant plus the secret's metadata. **Never the value.** Hold onto nothing but
+ * this; the host substitutes the value into matching `net:fetch` requests.
+ */
+interface SecretGrant {
+    /** Opaque handle for the minted `(appKey, secretId)` grant. */
+    grantId: string;
+    /** Metadata of the bound secret (no value). */
+    secret: SecretView;
+}
+/** An error from a secret operation, carrying a machine-readable `code`. */
+interface SecretError extends Error {
+    code: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'invalid-params' | 'unknown';
+}
+/**
+ * Ask the user to store a new secret (SECRETS_SPEC §4 `secrets:add`). Opens a
+ * **host-drawn** modal (the value is typed into host chrome, never via the app);
+ * resolves with the new secret's {@link SecretView} metadata, or rejects with a
+ * {@link SecretError} (`cancelled` if the user dismisses the modal). Requires the
+ * `secrets:add` capability.
+ */
+declare const requestAddSecret: (hints?: SecretHints) => Promise<SecretView>;
+/**
+ * Ask the user to bind one of their stored secrets to this app (SECRETS_SPEC §5,
+ * the powerbox flow — modeled on `requestSpace()`). The host draws a picker of
+ * **only the user's matching secrets**; the user picks, declines, or creates one.
+ * On success the host records a durable `(appKey, secretId)` grant and resolves
+ * with a {@link SecretGrant} (handle + metadata, **never the value**).
+ *
+ * **No existence oracle (T20/T27):** a decline, an ungranted secret, and a
+ * nonexistent secret are indistinguishable — all reject with a {@link SecretError}
+ * `cancelled`; the app never sees the list it chose from.
+ */
+declare const requestSecret: (query?: SecretQuery) => Promise<SecretGrant>;
+/**
+ * Delete a stored secret and tombstone every dependent per-app use grant
+ * (SECRETS_SPEC §4 `secrets:revoke`, §8.15 cascade). Requires `secrets:revoke`.
+ */
+declare const revokeSecret: (id: string) => Promise<void>;
+/** The metadata of the user's stored secrets (never values), `secrets:list`. Poll
+ *  for a one-off read; use {@link onSecretsChange}/{@link useSecrets} to react. */
+declare const getSecrets: () => SecretView[];
+/** Subscribe to secret-metadata changes (added/revoked). Invoked immediately with
+ *  the current list, then on every change. Returns an unsubscribe fn. */
+declare const onSecretsChange: (listener: (secrets: SecretView[]) => void) => (() => void);
+/** React hook returning the user's secret metadata (never values), re-rendering
+ *  on change. For the Settings app (SECRETS_SPEC §7). */
+declare const useSecrets: () => SecretView[];
+
+export { type SecretError, type SecretGrant, type SecretHints, type SecretQuery, type SecretType, type SecretView, getSecrets, onSecretsChange, requestAddSecret, requestSecret, revokeSecret, useSecrets };

package/dist/secrets.d.ts

@@ -0,0 +1,83 @@
+/** The closed secret-type vocabulary (SECRETS_SPEC §2). `api-key` is always
+ *  origin-bound; `oauth-refresh` is reserved (no substitution in v1). */
+type SecretType = 'api-key' | 'bearer-token' | 'oauth-refresh';
+/**
+ * The metadata-only projection of a stored secret (SECRETS_SPEC §2/§4) — exactly
+ * what `secrets:list` and the powerbox return. **There is no `value` field by
+ * design**: the plaintext is never part of any record an app receives.
+ */
+interface SecretView {
+    id: string;
+    type: SecretType;
+    family?: string;
+    description: string;
+    /** Required for `type:'api-key'` — the one https origin it may be sent to. */
+    boundOrigin?: string;
+    /** ISO-8601, or null if never used (drives the §8.15 90-day expiry). */
+    lastUsedAt: string | null;
+}
+/** Hints for the host's "add secret" modal (SECRETS_SPEC §4 `secrets:add`). The
+ *  app supplies only hints; the user types the value into host chrome. */
+interface SecretHints {
+    type?: SecretType;
+    family?: string;
+    /** Pre-fill the bound origin (e.g. `https://api.anthropic.com`). */
+    suggestedOrigin?: string;
+    description?: string;
+}
+/** What `requestSecret()` matches against in the powerbox picker (SECRETS_SPEC §5). */
+interface SecretQuery {
+    type?: SecretType;
+    family?: string;
+}
+/**
+ * The result of a granted `requestSecret()` — a durable `(appKey, secretId)` use
+ * grant plus the secret's metadata. **Never the value.** Hold onto nothing but
+ * this; the host substitutes the value into matching `net:fetch` requests.
+ */
+interface SecretGrant {
+    /** Opaque handle for the minted `(appKey, secretId)` grant. */
+    grantId: string;
+    /** Metadata of the bound secret (no value). */
+    secret: SecretView;
+}
+/** An error from a secret operation, carrying a machine-readable `code`. */
+interface SecretError extends Error {
+    code: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'invalid-params' | 'unknown';
+}
+/**
+ * Ask the user to store a new secret (SECRETS_SPEC §4 `secrets:add`). Opens a
+ * **host-drawn** modal (the value is typed into host chrome, never via the app);
+ * resolves with the new secret's {@link SecretView} metadata, or rejects with a
+ * {@link SecretError} (`cancelled` if the user dismisses the modal). Requires the
+ * `secrets:add` capability.
+ */
+declare const requestAddSecret: (hints?: SecretHints) => Promise<SecretView>;
+/**
+ * Ask the user to bind one of their stored secrets to this app (SECRETS_SPEC §5,
+ * the powerbox flow — modeled on `requestSpace()`). The host draws a picker of
+ * **only the user's matching secrets**; the user picks, declines, or creates one.
+ * On success the host records a durable `(appKey, secretId)` grant and resolves
+ * with a {@link SecretGrant} (handle + metadata, **never the value**).
+ *
+ * **No existence oracle (T20/T27):** a decline, an ungranted secret, and a
+ * nonexistent secret are indistinguishable — all reject with a {@link SecretError}
+ * `cancelled`; the app never sees the list it chose from.
+ */
+declare const requestSecret: (query?: SecretQuery) => Promise<SecretGrant>;
+/**
+ * Delete a stored secret and tombstone every dependent per-app use grant
+ * (SECRETS_SPEC §4 `secrets:revoke`, §8.15 cascade). Requires `secrets:revoke`.
+ */
+declare const revokeSecret: (id: string) => Promise<void>;
+/** The metadata of the user's stored secrets (never values), `secrets:list`. Poll
+ *  for a one-off read; use {@link onSecretsChange}/{@link useSecrets} to react. */
+declare const getSecrets: () => SecretView[];
+/** Subscribe to secret-metadata changes (added/revoked). Invoked immediately with
+ *  the current list, then on every change. Returns an unsubscribe fn. */
+declare const onSecretsChange: (listener: (secrets: SecretView[]) => void) => (() => void);
+/** React hook returning the user's secret metadata (never values), re-rendering
+ *  on change. For the Settings app (SECRETS_SPEC §7). */
+declare const useSecrets: () => SecretView[];
+
+export { type SecretError, type SecretGrant, type SecretHints, type SecretQuery, type SecretType, type SecretView, getSecrets, onSecretsChange, requestAddSecret, requestSecret, revokeSecret, useSecrets };

package/dist/secrets.js

@@ -0,0 +1,34 @@
+import { protocolRequest } from "./sandboxUtils";
+import { createPushChannel } from "./pushChannel";
+const request = async (method, query = {}) => {
+  const res = await protocolRequest("secrets", method, [query]);
+  if (!res || res.ok !== true) {
+    const err = new Error(res?.message ?? "secret request failed");
+    err.code = res?.code ?? "unknown";
+    throw err;
+  }
+  return res.data;
+};
+const requestAddSecret = (hints = {}) => request("add", hints);
+const requestSecret = (query = {}) => request("request", query);
+const revokeSecret = async (id) => {
+  await request("revoke", { id });
+};
+const channel = createPushChannel({
+  pushType: "secrets-metadata",
+  requestType: "request-secrets-metadata",
+  initial: [],
+  parse: (msg) => Array.isArray(msg.secrets) ? msg.secrets : void 0
+});
+const getSecrets = () => channel.get();
+const onSecretsChange = (listener) => channel.onChange(listener);
+const useSecrets = () => channel.use();
+export {
+  getSecrets,
+  onSecretsChange,
+  requestAddSecret,
+  requestSecret,
+  revokeSecret,
+  useSecrets
+};
+//# sourceMappingURL=secrets.js.map

package/dist/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/secrets.ts"],"sourcesContent":["// The host-owned secret store — app-facing surface (SECRETS_SPEC §4/§5).\n//\n// An app can ASK the user to store a secret (`requestAddSecret`), be GRANTED the\n// right to USE a specific secret (`requestSecret`, the powerbox flow), LIST\n// secret METADATA (`getSecrets`/`useSecrets`, never values), and REVOKE one\n// (`revokeSecret`). The secret VALUE never crosses this boundary: it is read\n// host-side, once, at the `net:fetch` injection point (SECRETS_SPEC §6). These\n// functions move only hints, metadata, and grant handles.\n//\n// Resolves LLM_AND_AGENTS_SPEC D2 — the host-mediated BYOK key store. Inert until\n// the host implements `protocol-secrets` + the `secrets-metadata` channel\n// (SECRETS_SPEC §3/§6 host work, roadmap P1.E); the contract is shipped here so\n// apps (e.g. the in-browser coding agent, P3-73) can be written against it.\nimport { protocolRequest } from './sandboxUtils';\nimport { createPushChannel } from './pushChannel';\n\n/** The closed secret-type vocabulary (SECRETS_SPEC §2). `api-key` is always\n *  origin-bound; `oauth-refresh` is reserved (no substitution in v1). */\nexport type SecretType = 'api-key' | 'bearer-token' | 'oauth-refresh';\n\n/**\n * The metadata-only projection of a stored secret (SECRETS_SPEC §2/§4) — exactly\n * what `secrets:list` and the powerbox return. **There is no `value` field by\n * design**: the plaintext is never part of any record an app receives.\n */\nexport interface SecretView {\n  id: string;\n  type: SecretType;\n  family?: string;\n  description: string;\n  /** Required for `type:'api-key'` — the one https origin it may be sent to. */\n  boundOrigin?: string;\n  /** ISO-8601, or null if never used (drives the §8.15 90-day expiry). */\n  lastUsedAt: string | null;\n}\n\n/** Hints for the host's \"add secret\" modal (SECRETS_SPEC §4 `secrets:add`). The\n *  app supplies only hints; the user types the value into host chrome. */\nexport interface SecretHints {\n  type?: SecretType;\n  family?: string;\n  /** Pre-fill the bound origin (e.g. `https://api.anthropic.com`). */\n  suggestedOrigin?: string;\n  description?: string;\n}\n\n/** What `requestSecret()` matches against in the powerbox picker (SECRETS_SPEC §5). */\nexport interface SecretQuery {\n  type?: SecretType;\n  family?: string;\n}\n\n/**\n * The result of a granted `requestSecret()` — a durable `(appKey, secretId)` use\n * grant plus the secret's metadata. **Never the value.** Hold onto nothing but\n * this; the host substitutes the value into matching `net:fetch` requests.\n */\nexport interface SecretGrant {\n  /** Opaque handle for the minted `(appKey, secretId)` grant. */\n  grantId: string;\n  /** Metadata of the bound secret (no value). */\n  secret: SecretView;\n}\n\n/** An error from a secret operation, carrying a machine-readable `code`. */\nexport interface SecretError extends Error {\n  code: 'auth-required' | 'cancelled' | 'forbidden' | 'not-found' | 'invalid-params' | 'unknown';\n}\n\ntype SecretResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\n// Issue a `protocol-secrets` request, unwrapping the host's {ok,data} envelope\n// and throwing a typed SecretError on failure (mirrors mounts.ts `request`).\nconst request = async <T = unknown>(\n  method: string,\n  query: object = {},\n): Promise<T> => {\n  const res = (await protocolRequest('secrets', method, [query])) as SecretResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'secret request failed') as SecretError;\n    err.code = (res?.code as SecretError['code']) ?? 'unknown';\n    throw err;\n  }\n  return res.data as T;\n};\n\n/**\n * Ask the user to store a new secret (SECRETS_SPEC §4 `secrets:add`). Opens a\n * **host-drawn** modal (the value is typed into host chrome, never via the app);\n * resolves with the new secret's {@link SecretView} metadata, or rejects with a\n * {@link SecretError} (`cancelled` if the user dismisses the modal). Requires the\n * `secrets:add` capability.\n */\nexport const requestAddSecret = (hints: SecretHints = {}): Promise<SecretView> =>\n  request<SecretView>('add', hints);\n\n/**\n * Ask the user to bind one of their stored secrets to this app (SECRETS_SPEC §5,\n * the powerbox flow — modeled on `requestSpace()`). The host draws a picker of\n * **only the user's matching secrets**; the user picks, declines, or creates one.\n * On success the host records a durable `(appKey, secretId)` grant and resolves\n * with a {@link SecretGrant} (handle + metadata, **never the value**).\n *\n * **No existence oracle (T20/T27):** a decline, an ungranted secret, and a\n * nonexistent secret are indistinguishable — all reject with a {@link SecretError}\n * `cancelled`; the app never sees the list it chose from.\n */\nexport const requestSecret = (query: SecretQuery = {}): Promise<SecretGrant> =>\n  request<SecretGrant>('request', query);\n\n/**\n * Delete a stored secret and tombstone every dependent per-app use grant\n * (SECRETS_SPEC §4 `secrets:revoke`, §8.15 cascade). Requires `secrets:revoke`.\n */\nexport const revokeSecret = async (id: string): Promise<void> => {\n  await request('revoke', { id });\n};\n\n// The metadata-only `secrets-metadata` channel (Recipe A): the host pushes the\n// current secret metadata on change and replays it on register-frame; gated by\n// `secrets:list`. NEVER carries a value (SECRETS_SPEC §4).\nconst channel = createPushChannel<SecretView[]>({\n  pushType: 'secrets-metadata',\n  requestType: 'request-secrets-metadata',\n  initial: [],\n  parse: (msg) => (Array.isArray(msg.secrets) ? (msg.secrets as SecretView[]) : undefined),\n});\n\n/** The metadata of the user's stored secrets (never values), `secrets:list`. Poll\n *  for a one-off read; use {@link onSecretsChange}/{@link useSecrets} to react. */\nexport const getSecrets = (): SecretView[] => channel.get();\n\n/** Subscribe to secret-metadata changes (added/revoked). Invoked immediately with\n *  the current list, then on every change. Returns an unsubscribe fn. */\nexport const onSecretsChange = (listener: (secrets: SecretView[]) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning the user's secret metadata (never values), re-rendering\n *  on change. For the Settings app (SECRETS_SPEC §7). */\nexport const useSecrets = (): SecretView[] => channel.use();\n"],"mappings":"AAaA,SAAS,uBAAuB;AAChC,SAAS,yBAAyB;AA6DlC,MAAM,UAAU,OACd,QACA,QAAgB,CAAC,MACF;AACf,QAAM,MAAO,MAAM,gBAAgB,WAAW,QAAQ,CAAC,KAAK,CAAC;AAC7D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,uBAAuB;AAC7D,QAAI,OAAQ,KAAK,QAAgC;AACjD,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AASO,MAAM,mBAAmB,CAAC,QAAqB,CAAC,MACrD,QAAoB,OAAO,KAAK;AAa3B,MAAM,gBAAgB,CAAC,QAAqB,CAAC,MAClD,QAAqB,WAAW,KAAK;AAMhC,MAAM,eAAe,OAAO,OAA8B;AAC/D,QAAM,QAAQ,UAAU,EAAE,GAAG,CAAC;AAChC;AAKA,MAAM,UAAU,kBAAgC;AAAA,EAC9C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,CAAC;AAAA,EACV,OAAO,CAAC,QAAS,MAAM,QAAQ,IAAI,OAAO,IAAK,IAAI,UAA2B;AAChF,CAAC;AAIM,MAAM,aAAa,MAAoB,QAAQ,IAAI;AAInD,MAAM,kBAAkB,CAAC,aAC9B,QAAQ,SAAS,QAAQ;AAIpB,MAAM,aAAa,MAAoB,QAAQ,IAAI;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Runtime SDK for code executing inside an immediately.run sandbox.",
   "license": "MIT",
   "repository": "github:immediately-run/immediately-run-sdk",