@immediately-run/sdk 0.2.4 → 0.2.6

package/dist/index.cjs

@@ -28,6 +28,9 @@ __reExport(index_exports, require("./formFactor"), module.exports);
 __reExport(index_exports, require("./mounts"), module.exports);
 __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("./tasks"), module.exports);
+__reExport(index_exports, require("./runtime"), module.exports);
 __reExport(index_exports, require("./protocolStream"), module.exports);
 __reExport(index_exports, require("./sandboxTypes"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
@@ -45,6 +48,9 @@ __reExport(index_exports, require("./sandboxTypes"), module.exports);
   ...require("./mounts"),
   ...require("./contribute"),
   ...require("./catalog"),
+  ...require("./ipc"),
+  ...require("./tasks"),
+  ...require("./runtime"),
   ...require("./protocolStream"),
   ...require("./sandboxTypes")
 });

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 './formFactor';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\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,yBATd;AAUA,0BAAc,qBAVd;AAWA,0BAAc,yBAXd;AAYA,0BAAc,sBAZd;AAaA,0BAAc,6BAbd;AAcA,0BAAc,2BAdd;","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 './formFactor';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\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,yBATd;AAUA,0BAAc,qBAVd;AAWA,0BAAc,yBAXd;AAYA,0BAAc,sBAZd;AAaA,0BAAc,kBAbd;AAcA,0BAAc,oBAdd;AAeA,0BAAc,sBAfd;AAgBA,0BAAc,6BAhBd;AAiBA,0BAAc,2BAjBd;","names":[]}

package/dist/index.d.cts

@@ -11,6 +11,9 @@ export { FormFactor, FormFactorClass, Orientation, getFormFactor, onFormFactorCh
 export { GrantRecord, Member, MountQuery, ResolvedUser, Role, SandboxMount, SpaceError, SpaceInfo, createSpace, findMount, getMounts, getSpaceMembers, listAllSpaces, listGrants, listSpaces, lookupUser, mount, mountSpace, onMountsChange, openAppSpace, requestMount, requestSpace, revokeGrant, setSpaceRole, shareSpace, unmountSpace, unshareSpace, useMounts, waitForMount } from './mounts.cjs';
 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 { FileCap, TaskInput, cancelTask, capFile, completeTask, getTaskInput, invokeTask, useTaskInput } from './tasks.cjs';
+export { ImmediatelyRunGlobal, SDK_PROTOCOL_VERSION, SDK_VERSION, SdkHandshake, announceHandshake, getHostRuntime, sdkHandshake } from './runtime.cjs';
 export { StreamError, StreamFrame, StreamTransport, consumeStream, protocolStream } from './protocolStream.cjs';
 export { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryFunction, MetadataQueryResult, ModuleExports } from './sandboxTypes.cjs';
 import 'react';

package/dist/index.d.ts

@@ -11,6 +11,9 @@ export { FormFactor, FormFactorClass, Orientation, getFormFactor, onFormFactorCh
 export { GrantRecord, Member, MountQuery, ResolvedUser, Role, SandboxMount, SpaceError, SpaceInfo, createSpace, findMount, getMounts, getSpaceMembers, listAllSpaces, listGrants, listSpaces, lookupUser, mount, mountSpace, onMountsChange, openAppSpace, requestMount, requestSpace, revokeGrant, setSpaceRole, shareSpace, unmountSpace, unshareSpace, useMounts, waitForMount } from './mounts.js';
 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 { FileCap, TaskInput, cancelTask, capFile, completeTask, getTaskInput, invokeTask, useTaskInput } from './tasks.js';
+export { ImmediatelyRunGlobal, SDK_PROTOCOL_VERSION, SDK_VERSION, SdkHandshake, announceHandshake, getHostRuntime, sdkHandshake } from './runtime.js';
 export { StreamError, StreamFrame, StreamTransport, consumeStream, protocolStream } from './protocolStream.js';
 export { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryFunction, MetadataQueryResult, ModuleExports } from './sandboxTypes.js';
 import 'react';

package/dist/index.js

@@ -11,6 +11,9 @@ export * from "./formFactor";
 export * from "./mounts";
 export * from "./contribute";
 export * from "./catalog";
+export * from "./ipc";
+export * from "./tasks";
+export * from "./runtime";
 export * from "./protocolStream";
 export * from "./sandboxTypes";
 //# sourceMappingURL=index.js.map

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 './formFactor';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\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;","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 './formFactor';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\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;","names":[]}

package/dist/ipc.cjs

@@ -0,0 +1,51 @@
+"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 ipc_exports = {};
+__export(ipc_exports, {
+  onRegionMessage: () => onRegionMessage,
+  postToRegion: () => postToRegion,
+  useRegionMessage: () => useRegionMessage
+});
+module.exports = __toCommonJS(ipc_exports);
+var import_react = require("react");
+var import_sandboxUtils = require("./sandboxUtils");
+const postToRegion = async (region, data) => {
+  const res = await (0, import_sandboxUtils.protocolRequest)("ipc", "post", [{ to: region, msg: data }]);
+  if (!res || res.ok !== true) {
+    const err = new Error(res?.message ?? "ipc post failed");
+    err.code = res?.code ?? "unknown";
+    throw err;
+  }
+};
+const onRegionMessage = (listener) => (0, import_sandboxUtils.addListener)(
+  "region-message",
+  (m) => listener({ from: m.from, data: m.data })
+);
+const useRegionMessage = () => {
+  const [msg, setMsg] = (0, import_react.useState)(null);
+  (0, import_react.useEffect)(() => onRegionMessage(setMsg), []);
+  return msg;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  onRegionMessage,
+  postToRegion,
+  useRegionMessage
+});
+//# sourceMappingURL=ipc.cjs.map

package/dist/ipc.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ipc.ts"],"sourcesContent":["// Inter-app messaging (UI_AS_APPS_SPEC §5.6) — L2: chrome panels/regions talk to\n// each other across an edge BOTH sides declared in their bindings (sender `ipc.to`\n// + the `ipc` capability; receiver `ipc.accepts`). The host enforces both halves\n// and attaches an unspoofable `from`; you still treat the payload as untrusted.\nimport { useEffect, useState } from 'react';\nimport { protocolRequest, addListener } from './sandboxUtils';\n\n/** A message delivered to this region. `from` is the SENDER's region, attached by\n *  the host (unspoofable, T19); `data` is the sender-provided payload. */\nexport interface RegionMessage {\n  from: string;\n  data: unknown;\n}\n\n/**\n * Send a message to another region. Resolves when delivered; rejects (`forbidden`)\n * if the edge isn't two-sided-consented, the target isn't mounted, or this app\n * lacks the `ipc` capability.\n */\nexport const postToRegion = async (region: string, data: unknown): Promise<void> => {\n  const res = (await protocolRequest('ipc', 'post', [{ to: region, msg: data }])) as\n    | { ok: true }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'ipc post failed') as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n};\n\n/** Subscribe to inbound region messages. Returns an unsubscribe fn. */\nexport const onRegionMessage = (listener: (msg: RegionMessage) => void): (() => void) =>\n  addListener('region-message', (m: { from: string; data: unknown }) =>\n    listener({ from: m.from, data: m.data }),\n  );\n\n/** React hook: the most recent inbound region message (or `null`). */\nexport const useRegionMessage = (): RegionMessage | null => {\n  const [msg, setMsg] = useState<RegionMessage | null>(null);\n  useEffect(() => onRegionMessage(setMsg), []);\n  return msg;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAIA,mBAAoC;AACpC,0BAA6C;AActC,MAAM,eAAe,OAAO,QAAgB,SAAiC;AAClF,QAAM,MAAO,UAAM,qCAAgB,OAAO,QAAQ,CAAC,EAAE,IAAI,QAAQ,KAAK,KAAK,CAAC,CAAC;AAI7E,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,iBAAiB;AACvD,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACF;AAGO,MAAM,kBAAkB,CAAC,iBAC9B;AAAA,EAAY;AAAA,EAAkB,CAAC,MAC7B,SAAS,EAAE,MAAM,EAAE,MAAM,MAAM,EAAE,KAAK,CAAC;AACzC;AAGK,MAAM,mBAAmB,MAA4B;AAC1D,QAAM,CAAC,KAAK,MAAM,QAAI,uBAA+B,IAAI;AACzD,8BAAU,MAAM,gBAAgB,MAAM,GAAG,CAAC,CAAC;AAC3C,SAAO;AACT;","names":[]}

package/dist/ipc.d.cts

@@ -0,0 +1,18 @@
+/** A message delivered to this region. `from` is the SENDER's region, attached by
+ *  the host (unspoofable, T19); `data` is the sender-provided payload. */
+interface RegionMessage {
+    from: string;
+    data: unknown;
+}
+/**
+ * Send a message to another region. Resolves when delivered; rejects (`forbidden`)
+ * if the edge isn't two-sided-consented, the target isn't mounted, or this app
+ * lacks the `ipc` capability.
+ */
+declare const postToRegion: (region: string, data: unknown) => Promise<void>;
+/** Subscribe to inbound region messages. Returns an unsubscribe fn. */
+declare const onRegionMessage: (listener: (msg: RegionMessage) => void) => (() => void);
+/** React hook: the most recent inbound region message (or `null`). */
+declare const useRegionMessage: () => RegionMessage | null;
+
+export { type RegionMessage, onRegionMessage, postToRegion, useRegionMessage };

package/dist/ipc.d.ts

@@ -0,0 +1,18 @@
+/** A message delivered to this region. `from` is the SENDER's region, attached by
+ *  the host (unspoofable, T19); `data` is the sender-provided payload. */
+interface RegionMessage {
+    from: string;
+    data: unknown;
+}
+/**
+ * Send a message to another region. Resolves when delivered; rejects (`forbidden`)
+ * if the edge isn't two-sided-consented, the target isn't mounted, or this app
+ * lacks the `ipc` capability.
+ */
+declare const postToRegion: (region: string, data: unknown) => Promise<void>;
+/** Subscribe to inbound region messages. Returns an unsubscribe fn. */
+declare const onRegionMessage: (listener: (msg: RegionMessage) => void) => (() => void);
+/** React hook: the most recent inbound region message (or `null`). */
+declare const useRegionMessage: () => RegionMessage | null;
+
+export { type RegionMessage, onRegionMessage, postToRegion, useRegionMessage };

package/dist/ipc.js

@@ -0,0 +1,25 @@
+import { useEffect, useState } from "react";
+import { protocolRequest, addListener } from "./sandboxUtils";
+const postToRegion = async (region, data) => {
+  const res = await protocolRequest("ipc", "post", [{ to: region, msg: data }]);
+  if (!res || res.ok !== true) {
+    const err = new Error(res?.message ?? "ipc post failed");
+    err.code = res?.code ?? "unknown";
+    throw err;
+  }
+};
+const onRegionMessage = (listener) => addListener(
+  "region-message",
+  (m) => listener({ from: m.from, data: m.data })
+);
+const useRegionMessage = () => {
+  const [msg, setMsg] = useState(null);
+  useEffect(() => onRegionMessage(setMsg), []);
+  return msg;
+};
+export {
+  onRegionMessage,
+  postToRegion,
+  useRegionMessage
+};
+//# sourceMappingURL=ipc.js.map

package/dist/ipc.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ipc.ts"],"sourcesContent":["// Inter-app messaging (UI_AS_APPS_SPEC §5.6) — L2: chrome panels/regions talk to\n// each other across an edge BOTH sides declared in their bindings (sender `ipc.to`\n// + the `ipc` capability; receiver `ipc.accepts`). The host enforces both halves\n// and attaches an unspoofable `from`; you still treat the payload as untrusted.\nimport { useEffect, useState } from 'react';\nimport { protocolRequest, addListener } from './sandboxUtils';\n\n/** A message delivered to this region. `from` is the SENDER's region, attached by\n *  the host (unspoofable, T19); `data` is the sender-provided payload. */\nexport interface RegionMessage {\n  from: string;\n  data: unknown;\n}\n\n/**\n * Send a message to another region. Resolves when delivered; rejects (`forbidden`)\n * if the edge isn't two-sided-consented, the target isn't mounted, or this app\n * lacks the `ipc` capability.\n */\nexport const postToRegion = async (region: string, data: unknown): Promise<void> => {\n  const res = (await protocolRequest('ipc', 'post', [{ to: region, msg: data }])) as\n    | { ok: true }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'ipc post failed') as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n};\n\n/** Subscribe to inbound region messages. Returns an unsubscribe fn. */\nexport const onRegionMessage = (listener: (msg: RegionMessage) => void): (() => void) =>\n  addListener('region-message', (m: { from: string; data: unknown }) =>\n    listener({ from: m.from, data: m.data }),\n  );\n\n/** React hook: the most recent inbound region message (or `null`). */\nexport const useRegionMessage = (): RegionMessage | null => {\n  const [msg, setMsg] = useState<RegionMessage | null>(null);\n  useEffect(() => onRegionMessage(setMsg), []);\n  return msg;\n};\n"],"mappings":"AAIA,SAAS,WAAW,gBAAgB;AACpC,SAAS,iBAAiB,mBAAmB;AActC,MAAM,eAAe,OAAO,QAAgB,SAAiC;AAClF,QAAM,MAAO,MAAM,gBAAgB,OAAO,QAAQ,CAAC,EAAE,IAAI,QAAQ,KAAK,KAAK,CAAC,CAAC;AAI7E,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,iBAAiB;AACvD,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACF;AAGO,MAAM,kBAAkB,CAAC,aAC9B;AAAA,EAAY;AAAA,EAAkB,CAAC,MAC7B,SAAS,EAAE,MAAM,EAAE,MAAM,MAAM,EAAE,KAAK,CAAC;AACzC;AAGK,MAAM,mBAAmB,MAA4B;AAC1D,QAAM,CAAC,KAAK,MAAM,IAAI,SAA+B,IAAI;AACzD,YAAU,MAAM,gBAAgB,MAAM,GAAG,CAAC,CAAC;AAC3C,SAAO;AACT;","names":[]}

package/dist/runtime.cjs

@@ -0,0 +1,60 @@
+"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 runtime_exports = {};
+__export(runtime_exports, {
+  SDK_PROTOCOL_VERSION: () => SDK_PROTOCOL_VERSION,
+  SDK_VERSION: () => SDK_VERSION,
+  announceHandshake: () => announceHandshake,
+  getHostRuntime: () => getHostRuntime,
+  sdkHandshake: () => sdkHandshake
+});
+module.exports = __toCommonJS(runtime_exports);
+var import_sandboxUtils = require("./sandboxUtils");
+const SDK_PROTOCOL_VERSION = "1.0.0";
+const SDK_VERSION = "0.2.6";
+function getHostRuntime() {
+  try {
+    return globalThis.__immediatelyRun__ ?? null;
+  } catch {
+    return null;
+  }
+}
+const sdkHandshake = () => ({
+  sdkVersion: SDK_VERSION,
+  protocolVersion: SDK_PROTOCOL_VERSION
+});
+function announceHandshake() {
+  const send = () => {
+    try {
+      (0, import_sandboxUtils.sendMessage)("sdk-handshake", sdkHandshake());
+    } catch {
+    }
+  };
+  send();
+  return (0, import_sandboxUtils.addListener)("request-handshake", send);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SDK_PROTOCOL_VERSION,
+  SDK_VERSION,
+  announceHandshake,
+  getHostRuntime,
+  sdkHandshake
+});
+//# sourceMappingURL=runtime.cjs.map

package/dist/runtime.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/runtime.ts"],"sourcesContent":["// Runtime discovery + version handshake (SDK_PACKAGING_SPEC §4/§6).\n//\n// Today the SDK reaches the host through the INJECTED sandbox services\n// (`module.evaluation.module.bundler.*`, see sandboxUtils). The packaging migration\n// makes the SDK an app-pinnable npm dependency that finds the runtime through a\n// stable, versioned global the sandbox publishes BEFORE evaluating app code:\n//\n//   globalThis.__immediatelyRun__ = { runtimeVersion, protocolVersion, transport }\n//\n// Phase 1 (behind a flag, injection still active): the SDK can READ that global\n// when present (else fall back to injection), and ANNOUNCE its own version +\n// protocol so the host can record + version-check it (§6/T45). The transport itself\n// is unchanged here — this only wires the discovery + handshake fields so the check\n// exists when app-pinned versions become real.\nimport { sendMessage, addListener } from './sandboxUtils';\n\n/** The wire protocol (postMessage envelope / channels / methods) THIS SDK speaks.\n *  Additive-only (§9); bump only for a backwards-compatible extension. */\nexport const SDK_PROTOCOL_VERSION = '1.0.0';\n\n/** This SDK's package version. Kept in step with package.json (a build step can\n *  inject it later; a constant is fine while versions are still effectively fixed). */\nexport const SDK_VERSION = '0.2.6';\n\n/** The sandbox runtime's pre-evaluation discovery global (§4). */\nexport interface ImmediatelyRunGlobal {\n  /** Sandbox-runtime protocol version (semver). */\n  runtimeVersion?: string;\n  /** postMessage envelope/protocol version. */\n  protocolVersion?: string;\n  /** The host channel the SDK talks over (MessagePort | message bus). */\n  transport?: unknown;\n  /** Resolves when ports arrive, if they arrive async after register-frame. */\n  ready?: Promise<void>;\n}\n\n/**\n * Read the sandbox runtime's discovery global (§4), or null when absent — in which\n * case the SDK uses the current INJECTED path (`module.evaluation.*`). Lets the SDK\n * detect a host too old/new and fail closed (§6) once the global ships.\n */\nexport function getHostRuntime(): ImmediatelyRunGlobal | null {\n  try {\n    return (globalThis as { __immediatelyRun__?: ImmediatelyRunGlobal }).__immediatelyRun__ ?? null;\n  } catch {\n    return null;\n  }\n}\n\n/** This SDK's handshake payload — the version + protocol the host records + checks\n *  against `HOST_PROTOCOL_VERSION` (§6/T45). */\nexport interface SdkHandshake {\n  sdkVersion: string;\n  protocolVersion: string;\n}\nexport const sdkHandshake = (): SdkHandshake => ({\n  sdkVersion: SDK_VERSION,\n  protocolVersion: SDK_PROTOCOL_VERSION,\n});\n\n/**\n * Announce this SDK's version to the host (§6). Sends `sdk-handshake` eagerly\n * (best-effort — the host may already be listening) AND replies to a host\n * `request-handshake` (the robust path, mirroring the other `request-*` pulls).\n * Idempotent; safe to call more than once. Returns an unsubscribe fn.\n */\nexport function announceHandshake(): () => void {\n  const send = () => {\n    try {\n      sendMessage('sdk-handshake', sdkHandshake() as unknown as Record<string, unknown>);\n    } catch {\n      /* transport not ready yet — the request-handshake reply covers it */\n    }\n  };\n  send();\n  return addListener('request-handshake', send);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAcA,0BAAyC;AAIlC,MAAM,uBAAuB;AAI7B,MAAM,cAAc;AAmBpB,SAAS,iBAA8C;AAC5D,MAAI;AACF,WAAQ,WAA6D,sBAAsB;AAAA,EAC7F,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAQO,MAAM,eAAe,OAAqB;AAAA,EAC/C,YAAY;AAAA,EACZ,iBAAiB;AACnB;AAQO,SAAS,oBAAgC;AAC9C,QAAM,OAAO,MAAM;AACjB,QAAI;AACF,2CAAY,iBAAiB,aAAa,CAAuC;AAAA,IACnF,QAAQ;AAAA,IAER;AAAA,EACF;AACA,OAAK;AACL,aAAO,iCAAY,qBAAqB,IAAI;AAC9C;","names":[]}

package/dist/runtime.d.cts

@@ -0,0 +1,39 @@
+/** The wire protocol (postMessage envelope / channels / methods) THIS SDK speaks.
+ *  Additive-only (§9); bump only for a backwards-compatible extension. */
+declare const SDK_PROTOCOL_VERSION = "1.0.0";
+/** This SDK's package version. Kept in step with package.json (a build step can
+ *  inject it later; a constant is fine while versions are still effectively fixed). */
+declare const SDK_VERSION = "0.2.6";
+/** The sandbox runtime's pre-evaluation discovery global (§4). */
+interface ImmediatelyRunGlobal {
+    /** Sandbox-runtime protocol version (semver). */
+    runtimeVersion?: string;
+    /** postMessage envelope/protocol version. */
+    protocolVersion?: string;
+    /** The host channel the SDK talks over (MessagePort | message bus). */
+    transport?: unknown;
+    /** Resolves when ports arrive, if they arrive async after register-frame. */
+    ready?: Promise<void>;
+}
+/**
+ * Read the sandbox runtime's discovery global (§4), or null when absent — in which
+ * case the SDK uses the current INJECTED path (`module.evaluation.*`). Lets the SDK
+ * detect a host too old/new and fail closed (§6) once the global ships.
+ */
+declare function getHostRuntime(): ImmediatelyRunGlobal | null;
+/** This SDK's handshake payload — the version + protocol the host records + checks
+ *  against `HOST_PROTOCOL_VERSION` (§6/T45). */
+interface SdkHandshake {
+    sdkVersion: string;
+    protocolVersion: string;
+}
+declare const sdkHandshake: () => SdkHandshake;
+/**
+ * Announce this SDK's version to the host (§6). Sends `sdk-handshake` eagerly
+ * (best-effort — the host may already be listening) AND replies to a host
+ * `request-handshake` (the robust path, mirroring the other `request-*` pulls).
+ * Idempotent; safe to call more than once. Returns an unsubscribe fn.
+ */
+declare function announceHandshake(): () => void;
+
+export { type ImmediatelyRunGlobal, SDK_PROTOCOL_VERSION, SDK_VERSION, type SdkHandshake, announceHandshake, getHostRuntime, sdkHandshake };

package/dist/runtime.d.ts

@@ -0,0 +1,39 @@
+/** The wire protocol (postMessage envelope / channels / methods) THIS SDK speaks.
+ *  Additive-only (§9); bump only for a backwards-compatible extension. */
+declare const SDK_PROTOCOL_VERSION = "1.0.0";
+/** This SDK's package version. Kept in step with package.json (a build step can
+ *  inject it later; a constant is fine while versions are still effectively fixed). */
+declare const SDK_VERSION = "0.2.6";
+/** The sandbox runtime's pre-evaluation discovery global (§4). */
+interface ImmediatelyRunGlobal {
+    /** Sandbox-runtime protocol version (semver). */
+    runtimeVersion?: string;
+    /** postMessage envelope/protocol version. */
+    protocolVersion?: string;
+    /** The host channel the SDK talks over (MessagePort | message bus). */
+    transport?: unknown;
+    /** Resolves when ports arrive, if they arrive async after register-frame. */
+    ready?: Promise<void>;
+}
+/**
+ * Read the sandbox runtime's discovery global (§4), or null when absent — in which
+ * case the SDK uses the current INJECTED path (`module.evaluation.*`). Lets the SDK
+ * detect a host too old/new and fail closed (§6) once the global ships.
+ */
+declare function getHostRuntime(): ImmediatelyRunGlobal | null;
+/** This SDK's handshake payload — the version + protocol the host records + checks
+ *  against `HOST_PROTOCOL_VERSION` (§6/T45). */
+interface SdkHandshake {
+    sdkVersion: string;
+    protocolVersion: string;
+}
+declare const sdkHandshake: () => SdkHandshake;
+/**
+ * Announce this SDK's version to the host (§6). Sends `sdk-handshake` eagerly
+ * (best-effort — the host may already be listening) AND replies to a host
+ * `request-handshake` (the robust path, mirroring the other `request-*` pulls).
+ * Idempotent; safe to call more than once. Returns an unsubscribe fn.
+ */
+declare function announceHandshake(): () => void;
+
+export { type ImmediatelyRunGlobal, SDK_PROTOCOL_VERSION, SDK_VERSION, type SdkHandshake, announceHandshake, getHostRuntime, sdkHandshake };

package/dist/runtime.js

@@ -0,0 +1,32 @@
+import { sendMessage, addListener } from "./sandboxUtils";
+const SDK_PROTOCOL_VERSION = "1.0.0";
+const SDK_VERSION = "0.2.6";
+function getHostRuntime() {
+  try {
+    return globalThis.__immediatelyRun__ ?? null;
+  } catch {
+    return null;
+  }
+}
+const sdkHandshake = () => ({
+  sdkVersion: SDK_VERSION,
+  protocolVersion: SDK_PROTOCOL_VERSION
+});
+function announceHandshake() {
+  const send = () => {
+    try {
+      sendMessage("sdk-handshake", sdkHandshake());
+    } catch {
+    }
+  };
+  send();
+  return addListener("request-handshake", send);
+}
+export {
+  SDK_PROTOCOL_VERSION,
+  SDK_VERSION,
+  announceHandshake,
+  getHostRuntime,
+  sdkHandshake
+};
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/runtime.ts"],"sourcesContent":["// Runtime discovery + version handshake (SDK_PACKAGING_SPEC §4/§6).\n//\n// Today the SDK reaches the host through the INJECTED sandbox services\n// (`module.evaluation.module.bundler.*`, see sandboxUtils). The packaging migration\n// makes the SDK an app-pinnable npm dependency that finds the runtime through a\n// stable, versioned global the sandbox publishes BEFORE evaluating app code:\n//\n//   globalThis.__immediatelyRun__ = { runtimeVersion, protocolVersion, transport }\n//\n// Phase 1 (behind a flag, injection still active): the SDK can READ that global\n// when present (else fall back to injection), and ANNOUNCE its own version +\n// protocol so the host can record + version-check it (§6/T45). The transport itself\n// is unchanged here — this only wires the discovery + handshake fields so the check\n// exists when app-pinned versions become real.\nimport { sendMessage, addListener } from './sandboxUtils';\n\n/** The wire protocol (postMessage envelope / channels / methods) THIS SDK speaks.\n *  Additive-only (§9); bump only for a backwards-compatible extension. */\nexport const SDK_PROTOCOL_VERSION = '1.0.0';\n\n/** This SDK's package version. Kept in step with package.json (a build step can\n *  inject it later; a constant is fine while versions are still effectively fixed). */\nexport const SDK_VERSION = '0.2.6';\n\n/** The sandbox runtime's pre-evaluation discovery global (§4). */\nexport interface ImmediatelyRunGlobal {\n  /** Sandbox-runtime protocol version (semver). */\n  runtimeVersion?: string;\n  /** postMessage envelope/protocol version. */\n  protocolVersion?: string;\n  /** The host channel the SDK talks over (MessagePort | message bus). */\n  transport?: unknown;\n  /** Resolves when ports arrive, if they arrive async after register-frame. */\n  ready?: Promise<void>;\n}\n\n/**\n * Read the sandbox runtime's discovery global (§4), or null when absent — in which\n * case the SDK uses the current INJECTED path (`module.evaluation.*`). Lets the SDK\n * detect a host too old/new and fail closed (§6) once the global ships.\n */\nexport function getHostRuntime(): ImmediatelyRunGlobal | null {\n  try {\n    return (globalThis as { __immediatelyRun__?: ImmediatelyRunGlobal }).__immediatelyRun__ ?? null;\n  } catch {\n    return null;\n  }\n}\n\n/** This SDK's handshake payload — the version + protocol the host records + checks\n *  against `HOST_PROTOCOL_VERSION` (§6/T45). */\nexport interface SdkHandshake {\n  sdkVersion: string;\n  protocolVersion: string;\n}\nexport const sdkHandshake = (): SdkHandshake => ({\n  sdkVersion: SDK_VERSION,\n  protocolVersion: SDK_PROTOCOL_VERSION,\n});\n\n/**\n * Announce this SDK's version to the host (§6). Sends `sdk-handshake` eagerly\n * (best-effort — the host may already be listening) AND replies to a host\n * `request-handshake` (the robust path, mirroring the other `request-*` pulls).\n * Idempotent; safe to call more than once. Returns an unsubscribe fn.\n */\nexport function announceHandshake(): () => void {\n  const send = () => {\n    try {\n      sendMessage('sdk-handshake', sdkHandshake() as unknown as Record<string, unknown>);\n    } catch {\n      /* transport not ready yet — the request-handshake reply covers it */\n    }\n  };\n  send();\n  return addListener('request-handshake', send);\n}\n"],"mappings":"AAcA,SAAS,aAAa,mBAAmB;AAIlC,MAAM,uBAAuB;AAI7B,MAAM,cAAc;AAmBpB,SAAS,iBAA8C;AAC5D,MAAI;AACF,WAAQ,WAA6D,sBAAsB;AAAA,EAC7F,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAQO,MAAM,eAAe,OAAqB;AAAA,EAC/C,YAAY;AAAA,EACZ,iBAAiB;AACnB;AAQO,SAAS,oBAAgC;AAC9C,QAAM,OAAO,MAAM;AACjB,QAAI;AACF,kBAAY,iBAAiB,aAAa,CAAuC;AAAA,IACnF,QAAQ;AAAA,IAER;AAAA,EACF;AACA,OAAK;AACL,SAAO,YAAY,qBAAqB,IAAI;AAC9C;","names":[]}

package/dist/tasks.cjs

@@ -0,0 +1,71 @@
+"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 tasks_exports = {};
+__export(tasks_exports, {
+  cancelTask: () => cancelTask,
+  capFile: () => capFile,
+  completeTask: () => completeTask,
+  getTaskInput: () => getTaskInput,
+  invokeTask: () => invokeTask,
+  useTaskInput: () => useTaskInput
+});
+module.exports = __toCommonJS(tasks_exports);
+var import_react = require("react");
+var import_sandboxUtils = require("./sandboxUtils");
+const capFile = (ref, opts) => ({ $cap: "file", mountId: ref.mountId, relPath: ref.relPath, mode: opts.mode });
+const invokeTask = async (task, params = {}) => {
+  const res = await (0, import_sandboxUtils.protocolRequest)("task", "invoke", [{ task, params }]);
+  if (!res || res.ok !== true) {
+    const err = new Error(res?.message ?? `task '${task}' failed`);
+    err.code = res?.code ?? "unknown";
+    throw err;
+  }
+  return res.data;
+};
+let latestInput = null;
+const inputListeners = /* @__PURE__ */ new Set();
+(0, import_sandboxUtils.addListener)("task-input", (m) => {
+  latestInput = { task: m.task, params: m.params ?? {} };
+  inputListeners.forEach((l) => l(latestInput));
+});
+const getTaskInput = () => latestInput;
+const completeTask = (result) => (0, import_sandboxUtils.sendMessage)("task-complete", { result });
+const cancelTask = () => (0, import_sandboxUtils.sendMessage)("task-cancel", {});
+const useTaskInput = () => {
+  const [input, setInput] = (0, import_react.useState)(getTaskInput);
+  (0, import_react.useEffect)(() => {
+    const l = (i) => setInput(i);
+    inputListeners.add(l);
+    if (latestInput) setInput(latestInput);
+    return () => {
+      inputListeners.delete(l);
+    };
+  }, []);
+  return input;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cancelTask,
+  capFile,
+  completeTask,
+  getTaskInput,
+  invokeTask,
+  useTaskInput
+});
+//# sourceMappingURL=tasks.cjs.map

package/dist/tasks.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tasks.ts"],"sourcesContent":["// Task invocation — apps invoking apps (UI_AS_APPS_SPEC §5.7). The\n// `startActivityForResult` pattern: one app invokes another by TASK CONTRACT\n// (never by app name — the user's override picks the bound app), passes typed\n// params, and awaits a typed result. The callee runs in a host-owned overlay\n// under ITS OWN grants — data crosses, your authority does not (§5.7).\n//\n// Two roles:\n//  - CALLER: `invokeTask(task, params)` (Recipe B — a deferred reply the host\n//    holds open until the callee finishes). Delegate a file with `capFile(...)`:\n//    the host resolves it against YOUR grants and mints an attenuated chroot.\n//  - CALLEE: read `useTaskInput()`, then `completeTask(result)` / `cancelTask()`.\nimport { useEffect, useState } from 'react';\nimport { protocolRequest, sendMessage, addListener } from './sandboxUtils';\n\n// ── caller side ─────────────────────────────────────────────────────────────\n\n/** A delegated FILE capability marker for a task param (§5.7). */\nexport interface FileCap {\n  $cap: 'file';\n  mountId: string;\n  relPath: string;\n  mode: 'ro' | 'rw';\n}\n\n/**\n * Build a delegated file reference for a task param. The host resolves it against\n * YOUR OWN grants and mints an attenuated, task-scoped chroot for the callee — you\n * can only delegate a path you already hold (attenuation only, never escalation).\n *\n *   file: capFile({ mountId: 'space:abc', relPath: 'photos/cat.jpg' }, { mode: 'rw' })\n */\nexport const capFile = (\n  ref: { mountId: string; relPath: string },\n  opts: { mode: 'ro' | 'rw' },\n): FileCap => ({ $cap: 'file', mountId: ref.mountId, relPath: ref.relPath, mode: opts.mode });\n\n/**\n * Invoke another app via a task contract and await its typed result (Recipe B).\n * Rejects with a machine `.code` on refusal: `cancelled` (user dismissed the\n * overlay), `timeout` (§5.7.1 liveness), `forbidden` (undeclared task or a file\n * delegation you don't hold), `no-such-task`, `task-cycle`/`task-depth-exceeded`/\n * `task-version-mismatch`, or `invalid-params` (result failed the contract schema).\n */\nexport const invokeTask = async <R = unknown>(\n  task: string,\n  params: Record<string, unknown> = {},\n): Promise<R> => {\n  const res = (await protocolRequest('task', 'invoke', [{ task, params }])) as\n    | { ok: true; data: R }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `task '${task}' failed`) as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n  return res.data;\n};\n\n// ── callee side ─────────────────────────────────────────────────────────────\n\n/** The params this app was invoked with as a task callee. */\nexport interface TaskInput {\n  task: string;\n  params: Record<string, unknown>;\n}\n\nlet latestInput: TaskInput | null = null;\nconst inputListeners = new Set<(i: TaskInput) => void>();\n\n// The host delivers a `task-input` message to the callee's iframe right after it\n// mounts the overlay (the §5.7 \"params via the region's mount event\").\naddListener('task-input', (m: { task: string; params?: Record<string, unknown> }) => {\n  latestInput = { task: m.task, params: m.params ?? {} };\n  inputListeners.forEach((l) => l(latestInput!));\n});\n\n/** The task params this app was invoked with, or null if it isn't a task callee. */\nexport const getTaskInput = (): TaskInput | null => latestInput;\n\n/**\n * Finish the task, returning a result to the caller. The host validates it against\n * the contract's result schema before resolving the caller (`invalid-params` on\n * violation), then tears down this overlay.\n */\nexport const completeTask = (result: unknown): void => sendMessage('task-complete', { result });\n\n/** Abort the task; the caller's `invokeTask` rejects with `cancelled`. */\nexport const cancelTask = (): void => sendMessage('task-cancel', {});\n\n/** React hook: the task input for this callee, re-rendering when it arrives. */\nexport const useTaskInput = (): TaskInput | null => {\n  const [input, setInput] = useState<TaskInput | null>(getTaskInput);\n  useEffect(() => {\n    const l = (i: TaskInput) => setInput(i);\n    inputListeners.add(l);\n    if (latestInput) setInput(latestInput);\n    return () => {\n      inputListeners.delete(l);\n    };\n  }, []);\n  return input;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,mBAAoC;AACpC,0BAA0D;AAmBnD,MAAM,UAAU,CACrB,KACA,UACa,EAAE,MAAM,QAAQ,SAAS,IAAI,SAAS,SAAS,IAAI,SAAS,MAAM,KAAK,KAAK;AASpF,MAAM,aAAa,OACxB,MACA,SAAkC,CAAC,MACpB;AACf,QAAM,MAAO,UAAM,qCAAgB,QAAQ,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC;AAIvE,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,SAAS,IAAI,UAAU;AAC7D,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AAUA,IAAI,cAAgC;AACpC,MAAM,iBAAiB,oBAAI,IAA4B;AAAA,IAIvD,iCAAY,cAAc,CAAC,MAA0D;AACnF,gBAAc,EAAE,MAAM,EAAE,MAAM,QAAQ,EAAE,UAAU,CAAC,EAAE;AACrD,iBAAe,QAAQ,CAAC,MAAM,EAAE,WAAY,CAAC;AAC/C,CAAC;AAGM,MAAM,eAAe,MAAwB;AAO7C,MAAM,eAAe,CAAC,eAA0B,iCAAY,iBAAiB,EAAE,OAAO,CAAC;AAGvF,MAAM,aAAa,UAAY,iCAAY,eAAe,CAAC,CAAC;AAG5D,MAAM,eAAe,MAAwB;AAClD,QAAM,CAAC,OAAO,QAAQ,QAAI,uBAA2B,YAAY;AACjE,8BAAU,MAAM;AACd,UAAM,IAAI,CAAC,MAAiB,SAAS,CAAC;AACtC,mBAAe,IAAI,CAAC;AACpB,QAAI,YAAa,UAAS,WAAW;AACrC,WAAO,MAAM;AACX,qBAAe,OAAO,CAAC;AAAA,IACzB;AAAA,EACF,GAAG,CAAC,CAAC;AACL,SAAO;AACT;","names":[]}

package/dist/tasks.d.cts

@@ -0,0 +1,47 @@
+/** A delegated FILE capability marker for a task param (§5.7). */
+interface FileCap {
+    $cap: 'file';
+    mountId: string;
+    relPath: string;
+    mode: 'ro' | 'rw';
+}
+/**
+ * Build a delegated file reference for a task param. The host resolves it against
+ * YOUR OWN grants and mints an attenuated, task-scoped chroot for the callee — you
+ * can only delegate a path you already hold (attenuation only, never escalation).
+ *
+ *   file: capFile({ mountId: 'space:abc', relPath: 'photos/cat.jpg' }, { mode: 'rw' })
+ */
+declare const capFile: (ref: {
+    mountId: string;
+    relPath: string;
+}, opts: {
+    mode: "ro" | "rw";
+}) => FileCap;
+/**
+ * Invoke another app via a task contract and await its typed result (Recipe B).
+ * Rejects with a machine `.code` on refusal: `cancelled` (user dismissed the
+ * overlay), `timeout` (§5.7.1 liveness), `forbidden` (undeclared task or a file
+ * delegation you don't hold), `no-such-task`, `task-cycle`/`task-depth-exceeded`/
+ * `task-version-mismatch`, or `invalid-params` (result failed the contract schema).
+ */
+declare const invokeTask: <R = unknown>(task: string, params?: Record<string, unknown>) => Promise<R>;
+/** The params this app was invoked with as a task callee. */
+interface TaskInput {
+    task: string;
+    params: Record<string, unknown>;
+}
+/** The task params this app was invoked with, or null if it isn't a task callee. */
+declare const getTaskInput: () => TaskInput | null;
+/**
+ * Finish the task, returning a result to the caller. The host validates it against
+ * the contract's result schema before resolving the caller (`invalid-params` on
+ * violation), then tears down this overlay.
+ */
+declare const completeTask: (result: unknown) => void;
+/** Abort the task; the caller's `invokeTask` rejects with `cancelled`. */
+declare const cancelTask: () => void;
+/** React hook: the task input for this callee, re-rendering when it arrives. */
+declare const useTaskInput: () => TaskInput | null;
+
+export { type FileCap, type TaskInput, cancelTask, capFile, completeTask, getTaskInput, invokeTask, useTaskInput };

package/dist/tasks.d.ts

@@ -0,0 +1,47 @@
+/** A delegated FILE capability marker for a task param (§5.7). */
+interface FileCap {
+    $cap: 'file';
+    mountId: string;
+    relPath: string;
+    mode: 'ro' | 'rw';
+}
+/**
+ * Build a delegated file reference for a task param. The host resolves it against
+ * YOUR OWN grants and mints an attenuated, task-scoped chroot for the callee — you
+ * can only delegate a path you already hold (attenuation only, never escalation).
+ *
+ *   file: capFile({ mountId: 'space:abc', relPath: 'photos/cat.jpg' }, { mode: 'rw' })
+ */
+declare const capFile: (ref: {
+    mountId: string;
+    relPath: string;
+}, opts: {
+    mode: "ro" | "rw";
+}) => FileCap;
+/**
+ * Invoke another app via a task contract and await its typed result (Recipe B).
+ * Rejects with a machine `.code` on refusal: `cancelled` (user dismissed the
+ * overlay), `timeout` (§5.7.1 liveness), `forbidden` (undeclared task or a file
+ * delegation you don't hold), `no-such-task`, `task-cycle`/`task-depth-exceeded`/
+ * `task-version-mismatch`, or `invalid-params` (result failed the contract schema).
+ */
+declare const invokeTask: <R = unknown>(task: string, params?: Record<string, unknown>) => Promise<R>;
+/** The params this app was invoked with as a task callee. */
+interface TaskInput {
+    task: string;
+    params: Record<string, unknown>;
+}
+/** The task params this app was invoked with, or null if it isn't a task callee. */
+declare const getTaskInput: () => TaskInput | null;
+/**
+ * Finish the task, returning a result to the caller. The host validates it against
+ * the contract's result schema before resolving the caller (`invalid-params` on
+ * violation), then tears down this overlay.
+ */
+declare const completeTask: (result: unknown) => void;
+/** Abort the task; the caller's `invokeTask` rejects with `cancelled`. */
+declare const cancelTask: () => void;
+/** React hook: the task input for this callee, re-rendering when it arrives. */
+declare const useTaskInput: () => TaskInput | null;
+
+export { type FileCap, type TaskInput, cancelTask, capFile, completeTask, getTaskInput, invokeTask, useTaskInput };

package/dist/tasks.js

@@ -0,0 +1,42 @@
+import { useEffect, useState } from "react";
+import { protocolRequest, sendMessage, addListener } from "./sandboxUtils";
+const capFile = (ref, opts) => ({ $cap: "file", mountId: ref.mountId, relPath: ref.relPath, mode: opts.mode });
+const invokeTask = async (task, params = {}) => {
+  const res = await protocolRequest("task", "invoke", [{ task, params }]);
+  if (!res || res.ok !== true) {
+    const err = new Error(res?.message ?? `task '${task}' failed`);
+    err.code = res?.code ?? "unknown";
+    throw err;
+  }
+  return res.data;
+};
+let latestInput = null;
+const inputListeners = /* @__PURE__ */ new Set();
+addListener("task-input", (m) => {
+  latestInput = { task: m.task, params: m.params ?? {} };
+  inputListeners.forEach((l) => l(latestInput));
+});
+const getTaskInput = () => latestInput;
+const completeTask = (result) => sendMessage("task-complete", { result });
+const cancelTask = () => sendMessage("task-cancel", {});
+const useTaskInput = () => {
+  const [input, setInput] = useState(getTaskInput);
+  useEffect(() => {
+    const l = (i) => setInput(i);
+    inputListeners.add(l);
+    if (latestInput) setInput(latestInput);
+    return () => {
+      inputListeners.delete(l);
+    };
+  }, []);
+  return input;
+};
+export {
+  cancelTask,
+  capFile,
+  completeTask,
+  getTaskInput,
+  invokeTask,
+  useTaskInput
+};
+//# sourceMappingURL=tasks.js.map

package/dist/tasks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tasks.ts"],"sourcesContent":["// Task invocation — apps invoking apps (UI_AS_APPS_SPEC §5.7). The\n// `startActivityForResult` pattern: one app invokes another by TASK CONTRACT\n// (never by app name — the user's override picks the bound app), passes typed\n// params, and awaits a typed result. The callee runs in a host-owned overlay\n// under ITS OWN grants — data crosses, your authority does not (§5.7).\n//\n// Two roles:\n//  - CALLER: `invokeTask(task, params)` (Recipe B — a deferred reply the host\n//    holds open until the callee finishes). Delegate a file with `capFile(...)`:\n//    the host resolves it against YOUR grants and mints an attenuated chroot.\n//  - CALLEE: read `useTaskInput()`, then `completeTask(result)` / `cancelTask()`.\nimport { useEffect, useState } from 'react';\nimport { protocolRequest, sendMessage, addListener } from './sandboxUtils';\n\n// ── caller side ─────────────────────────────────────────────────────────────\n\n/** A delegated FILE capability marker for a task param (§5.7). */\nexport interface FileCap {\n  $cap: 'file';\n  mountId: string;\n  relPath: string;\n  mode: 'ro' | 'rw';\n}\n\n/**\n * Build a delegated file reference for a task param. The host resolves it against\n * YOUR OWN grants and mints an attenuated, task-scoped chroot for the callee — you\n * can only delegate a path you already hold (attenuation only, never escalation).\n *\n *   file: capFile({ mountId: 'space:abc', relPath: 'photos/cat.jpg' }, { mode: 'rw' })\n */\nexport const capFile = (\n  ref: { mountId: string; relPath: string },\n  opts: { mode: 'ro' | 'rw' },\n): FileCap => ({ $cap: 'file', mountId: ref.mountId, relPath: ref.relPath, mode: opts.mode });\n\n/**\n * Invoke another app via a task contract and await its typed result (Recipe B).\n * Rejects with a machine `.code` on refusal: `cancelled` (user dismissed the\n * overlay), `timeout` (§5.7.1 liveness), `forbidden` (undeclared task or a file\n * delegation you don't hold), `no-such-task`, `task-cycle`/`task-depth-exceeded`/\n * `task-version-mismatch`, or `invalid-params` (result failed the contract schema).\n */\nexport const invokeTask = async <R = unknown>(\n  task: string,\n  params: Record<string, unknown> = {},\n): Promise<R> => {\n  const res = (await protocolRequest('task', 'invoke', [{ task, params }])) as\n    | { ok: true; data: R }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `task '${task}' failed`) as Error & { code?: string };\n    err.code = res?.code ?? 'unknown';\n    throw err;\n  }\n  return res.data;\n};\n\n// ── callee side ─────────────────────────────────────────────────────────────\n\n/** The params this app was invoked with as a task callee. */\nexport interface TaskInput {\n  task: string;\n  params: Record<string, unknown>;\n}\n\nlet latestInput: TaskInput | null = null;\nconst inputListeners = new Set<(i: TaskInput) => void>();\n\n// The host delivers a `task-input` message to the callee's iframe right after it\n// mounts the overlay (the §5.7 \"params via the region's mount event\").\naddListener('task-input', (m: { task: string; params?: Record<string, unknown> }) => {\n  latestInput = { task: m.task, params: m.params ?? {} };\n  inputListeners.forEach((l) => l(latestInput!));\n});\n\n/** The task params this app was invoked with, or null if it isn't a task callee. */\nexport const getTaskInput = (): TaskInput | null => latestInput;\n\n/**\n * Finish the task, returning a result to the caller. The host validates it against\n * the contract's result schema before resolving the caller (`invalid-params` on\n * violation), then tears down this overlay.\n */\nexport const completeTask = (result: unknown): void => sendMessage('task-complete', { result });\n\n/** Abort the task; the caller's `invokeTask` rejects with `cancelled`. */\nexport const cancelTask = (): void => sendMessage('task-cancel', {});\n\n/** React hook: the task input for this callee, re-rendering when it arrives. */\nexport const useTaskInput = (): TaskInput | null => {\n  const [input, setInput] = useState<TaskInput | null>(getTaskInput);\n  useEffect(() => {\n    const l = (i: TaskInput) => setInput(i);\n    inputListeners.add(l);\n    if (latestInput) setInput(latestInput);\n    return () => {\n      inputListeners.delete(l);\n    };\n  }, []);\n  return input;\n};\n"],"mappings":"AAWA,SAAS,WAAW,gBAAgB;AACpC,SAAS,iBAAiB,aAAa,mBAAmB;AAmBnD,MAAM,UAAU,CACrB,KACA,UACa,EAAE,MAAM,QAAQ,SAAS,IAAI,SAAS,SAAS,IAAI,SAAS,MAAM,KAAK,KAAK;AASpF,MAAM,aAAa,OACxB,MACA,SAAkC,CAAC,MACpB;AACf,QAAM,MAAO,MAAM,gBAAgB,QAAQ,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC;AAIvE,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,SAAS,IAAI,UAAU;AAC7D,QAAI,OAAO,KAAK,QAAQ;AACxB,UAAM;AAAA,EACR;AACA,SAAO,IAAI;AACb;AAUA,IAAI,cAAgC;AACpC,MAAM,iBAAiB,oBAAI,IAA4B;AAIvD,YAAY,cAAc,CAAC,MAA0D;AACnF,gBAAc,EAAE,MAAM,EAAE,MAAM,QAAQ,EAAE,UAAU,CAAC,EAAE;AACrD,iBAAe,QAAQ,CAAC,MAAM,EAAE,WAAY,CAAC;AAC/C,CAAC;AAGM,MAAM,eAAe,MAAwB;AAO7C,MAAM,eAAe,CAAC,WAA0B,YAAY,iBAAiB,EAAE,OAAO,CAAC;AAGvF,MAAM,aAAa,MAAY,YAAY,eAAe,CAAC,CAAC;AAG5D,MAAM,eAAe,MAAwB;AAClD,QAAM,CAAC,OAAO,QAAQ,IAAI,SAA2B,YAAY;AACjE,YAAU,MAAM;AACd,UAAM,IAAI,CAAC,MAAiB,SAAS,CAAC;AACtC,mBAAe,IAAI,CAAC;AACpB,QAAI,YAAa,UAAS,WAAW;AACrC,WAAO,MAAM;AACX,qBAAe,OAAO,CAAC;AAAA,IACzB;AAAA,EACF,GAAG,CAAC,CAAC;AACL,SAAO;AACT;","names":[]}

package/package.json

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