@cef-ai/widget-runtime 1.1.1 → 2.1.0

package/README.md

@@ -91,7 +91,7 @@ something the widget never sent.
 | Message | Direction | Fields |
 | --- | --- | --- |
 | `cef-widget:identity-request` | widget → host | `requestId: string`, `v: number` |
-| `cef-widget:identity-response` | host → widget | `requestId: string`, `v?: number`, `pubkey?: string`, `sigType?: 'ed25519' \| 'sr25519'` (default `ed25519`), `error?: string`, `errorCode?: 'unsupported-version'` |
+| `cef-widget:identity-response` | host → widget | `requestId: string`, `v?: number`, `pubkey?: string`, `sigType?: 'ed25519' \| 'sr25519'` (default `ed25519`), `token?: string` (a bearer delegation the widget uses instead of asking you to sign), `context?: { runId?, recordId?, vaultId? }`, `error?: string`, `errorCode?: 'unsupported-version'` |
 | `cef-widget:sign-request` | widget → host | `requestId: string`, `v: number`, `bytes: number[]` |
 | `cef-widget:sign-response` | host → widget | `requestId: string`, `v?: number`, `signature: number[] \| null` (`null` = user declined), `error?: string`, `errorCode?: 'unsupported-version'` |
 
@@ -105,6 +105,15 @@ Rules:
   answers with `errorCode: 'unsupported-version'` — its own reply is still a v1
   message, so `v` itself cannot carry the rejection, and without the code the
   receiver would just see an opaque error string and keep retrying.
+- **Which vault (`context.vaultId`).** By default a widget opens the
+  **caller's own** vault (`vault.ensure()`), and a `token` does not change that
+  — a delegation says *who*, not *which vault*. A workflow, meanwhile, runs in
+  the vault of the org that owns its agent service, so a host showing somebody
+  else's run must name that vault or the widget reads a different database and
+  reports it as empty. Optional: a host that sends none gets exactly today's
+  behaviour. A host that **does** send one and the widget cannot open it gets
+  `WidgetVaultUnreachableError` — the runtime refuses rather than falling back,
+  because a fallback is indistinguishable from a run that produced nothing.
 - **Sign verbatim.** The host must sign the exact bytes it receives with
   **`ed25519_signRaw`**. Do **not** use the high-level `signMessage` /
   `wallet_signMessage`, which wrap the payload in Substrate's

package/dist/bridge-wallet.js

@@ -14,6 +14,9 @@
 // All hex values in the client-sdk shape are WITHOUT a 0x prefix, matching
 // the proven embed-wallet behaviour (see embed-adapter.ts history).
 import { hexToU8a } from '@polkadot/util';
+import { encodeAddress } from '@polkadot/util-crypto';
+/** Cere's registered SS58 prefix. */
+const CERE_SS58_PREFIX = 54;
 // ── Internal helpers ──────────────────────────────────────────────────────────
 /** Encode bytes as lowercase hex WITHOUT a `0x` prefix. */
 function bytesToHexNo0x(bytes) {
@@ -36,10 +39,22 @@ function bytesToHexNo0x(bytes) {
 export function toVaultSdkSigner(pubkey, sigType, signFn) {
     return {
         type: sigType,
-        // `address` is set to the hex pubkey (NOT an SS58 address). vault-sdk's
-        // WalletAuthProvider reads `publicKey`/`type`, not `address`, to build the
-        // auth headers — matching the toClientSdkWallet note below.
-        address: pubkey,
+        /*
+         * A REAL SS58 ADDRESS, not the hex pubkey.
+         *
+         * It was the hex, justified by "vault-sdk's WalletAuthProvider reads
+         * `publicKey`/`type`, not `address`". True of that provider, and a trap: it
+         * made the field's correctness depend on which auth provider happened to be
+         * in use. The moment a widget carries a host delegation it uses
+         * `DelegationAuthProvider` instead, something downstream decodes `address`,
+         * and a hex string fails SS58's checksum — surfacing in the widget as
+         * "Something went wrong: Invalid checksum", which names neither the field
+         * nor the value.
+         *
+         * Encoding it costs one call and removes the dependency entirely: the
+         * address is right whoever reads it.
+         */
+        address: encodeAddress(hexToU8a(pubkey), CERE_SS58_PREFIX),
         publicKey: hexToU8a(pubkey),
         isReady: async () => true,
         sign: (bytes) => signFn(bytes),

package/dist/entry.js

@@ -5,6 +5,7 @@ import { toVaultSdkSigner } from './bridge-wallet.js';
 import { connectStandaloneWallet } from './standalone-wallet.js';
 import { createIdentityResolver } from './resolve-identity.js';
 import { createVaultClient } from './vault-client.js';
+import { toVaultSdkConfig } from './vault-sdk-config.js';
 import { createWidgetRuntime } from './runtime.js';
 import { captureAndUploadAudio, createVaultObjectUploader } from './audio/capture-upload.js';
 import { decodeToMono16k } from './audio/segment.js';
@@ -38,13 +39,35 @@ function boot() {
         bridge,
         connectWallet: () => connectStandaloneWallet(manifest.wallet),
     });
+    /** The host's delegation, captured when identity resolved. See resolveIdentity. */
+    let hostDelegation;
     const deps = {
         resolveIdentity: async () => {
             const id = await resolveSigningIdentity();
-            return { source: id.source, publicKey: id.publicKey, sigType: id.sigType };
+            // Remembered for buildVaultClient, which is synchronous and runs after
+            // this. The resolver is memoised, so this is the same identity.
+            hostDelegation = id.token;
+            /*
+             * THE CONTEXT TRAVELS THE LAST STEP TOO.
+             *
+             * It was dropped here: the resolver put the host's `context` on the
+             * resolved identity, `createWidgetRuntime` reads `id.context` and hands
+             * it to `identity()` — and this literal, the only production
+             * implementation of `resolveIdentity`, rebuilt the object without it. So
+             * the handshake carried the run all the way to the runtime's front door
+             * and no widget could ever read it. Spread rather than re-listed, so the
+             * next key on the bag does not have to remember to come through here.
+             */
+            return {
+                source: id.source,
+                publicKey: id.publicKey,
+                sigType: id.sigType,
+                ...(id.context ? { context: id.context } : {}),
+            };
         },
         buildVaultClient: (m, id) => {
             const sigType = id.sigType ?? 'ed25519';
+            const hostToken = hostDelegation;
             // Defer to the memoized identity for signing — resolveIdentity() has
             // already run by the time buildVaultClient is called, so this resolves
             // to the same (host or wallet) signer without a second handshake/popup.
@@ -52,14 +75,22 @@ function boot() {
             const vaultSdkSigner = toVaultSdkSigner(id.publicKey, sigType, signFn);
             // vault-sdk SDK instance: used for vault.ensure(), cubby reads, publish,
             // connectAgent, agentStatus — the single SDK for the whole runtime.
-            const makeSdk = () => new VaultSDK({
-                endpoint: m.endpoints.vault,
-                garEndpoint: m.endpoints.gar,
-                marketplaceEndpoint: m.endpoints.marketplace,
-                s3GatewayAuthInfoUrl: m.endpoints.s3GatewayAuthInfo,
-                signer: vaultSdkSigner,
-            });
-            return createVaultClient(m, makeSdk);
+            // `toVaultSdkConfig` carries `endpoints.rpc` as `chainUrl`: ensure()'s
+            // wallet path grants vault-api an on-chain NonTransfer proxy before the
+            // tokenless claim and cannot run without a chain URL.
+            // THE HOST'S DELEGATION, WHEN IT GAVE ONE. `auth` overrides `signer`, so
+            // this handle structurally cannot sign — and on the passkey wallet that is
+            // the difference between one ceremony and one per request: a keyless
+            // session steps up on every signature, so a widget that polls a query
+            // asked for a passkey forever. `sign` stays wired for hosts that supply
+            // no token.
+            const makeSdk = () => new VaultSDK(toVaultSdkConfig(m.endpoints, vaultSdkSigner, hostToken));
+            // WHICH VAULT, when the host named one. It rides `context` rather than
+            // a field of its own because it is the same kind of fact as the run id —
+            // why this widget was opened — and because an optional key on an
+            // already-optional bag is the only shape that leaves a host which sends
+            // nothing behaving exactly as it does today.
+            return createVaultClient(m, makeSdk, hostToken, id.context?.vaultId);
         },
     };
     // Build the mount deps (audio uploader) for config-driven audio kinds.
@@ -85,13 +116,12 @@ function boot() {
             uploaderP = (async () => {
                 const id = await resolveSigningIdentity();
                 const vaultSdkSigner = toVaultSdkSigner(id.publicKey, id.sigType, id.sign);
-                const sdk = new VaultSDK({
-                    endpoint: manifest.endpoints.vault,
-                    garEndpoint: manifest.endpoints.gar,
-                    marketplaceEndpoint: manifest.endpoints.marketplace,
-                    s3GatewayAuthInfoUrl: manifest.endpoints.s3GatewayAuthInfo,
-                    signer: vaultSdkSigner,
-                });
+                // Same delegation preference as the vault client: an upload that signs
+                // per chunk on a keyless session is a ceremony per chunk.
+                // Same config builder as the main vault client above — in particular
+                // the same `chainUrl`, since this `ensure({ onboard: false })` runs
+                // the vault-delegate grant step too.
+                const sdk = new VaultSDK(toVaultSdkConfig(manifest.endpoints, vaultSdkSigner, id.token));
                 const ensuredVault = await sdk.vault.ensure({ onboard: false });
                 return createVaultObjectUploader({ objects: ensuredVault.scope(manifest.scope).objects });
             })().catch((err) => { uploaderP = null; throw err; });
@@ -127,9 +157,19 @@ function boot() {
         // script and are unaffected.)
         onDomReady(() => {
             const app = document.getElementById('app');
-            if (app) {
-                void import('./mount.js').then(({ mountKind }) => mountKind(app, manifest.config, window.WidgetRuntime, mountDeps));
+            if (!app) {
+                // SAY SO. This used to be a bare `if (app)`, so a widget whose entry
+                // HTML had no mount point loaded its runtime, resolved its identity,
+                // ran nothing, and rendered whatever static markup the file happened to
+                // contain. From the outside that is indistinguishable from a query
+                // returning no rows — the page is simply there, and wrong, with an
+                // empty console. Cost us a devnet round trip to find.
+                console.error(`[widget-runtime] widget "${manifest.widgetId}" declares kind "${manifest.kind}" ` +
+                    'but its entry HTML has no <div id="app"></div>, so there is nowhere to render. ' +
+                    'Add the element, or declare kind "custom" and mount it yourself.');
+                return;
             }
+            void import('./mount.js').then(({ mountKind }) => mountKind(app, manifest.config, window.WidgetRuntime, mountDeps));
         });
     }
 }

package/dist/host-bridge.d.ts

@@ -21,6 +21,44 @@ export declare const UNSUPPORTED_VERSION_CODE = "unsupported-version";
 /** Largest `bytes` payload a host will sign, and largest signature accepted. */
 export declare const MAX_SIGN_BYTES: number;
 export type SigType = VaultSigType;
+/**
+ * What the host can tell a widget about WHY it was opened.
+ *
+ * Every field optional, and a widget may ignore any of them — see
+ * `IdentityResponse.context`. Additive only: a new key must never change what a
+ * widget that does not read it does.
+ */
+export interface WidgetHostContext {
+    /** The workflow execution being viewed, when the widget was opened from one. */
+    runId?: string;
+    /** One record, when the widget was opened from a row rather than a run. */
+    recordId?: string;
+    /**
+     * WHICH VAULT THE RUN HAPPENED IN — and therefore which one to read.
+     *
+     * A widget authenticates as the viewer and then opened the VIEWER'S OWN
+     * vault, because `vault.ensure()` claims the caller's vault and a delegation
+     * says WHO, not WHICH. A workflow, meanwhile, runs in the vault of the org
+     * that owns its agent SERVICE. Those are the same database only when the
+     * viewer happens to own that org — so for a member of somebody else's
+     * service the widget read a different database, found nothing, and said so:
+     * "No candidate has been reviewed yet" about a run whose own INSERT had
+     * reported `rowsAffected: 1`. An empty answer and a wrong-database answer
+     * were indistinguishable.
+     *
+     * OPTIONAL, and that is the compatibility story — the same one `token` and
+     * `context` itself have. A host that sends none gets exactly today's
+     * `ensure()`, the viewer's own vault, so every already-deployed widget and
+     * every host that has not been taught this key is untouched.
+     *
+     * CONTEXT, NOT A COMMAND still holds, in the only sense it can here: a widget
+     * that reads nothing from `context` never notices this key. But the runtime
+     * acts on it before any widget code runs, and when it cannot open the named
+     * vault it REFUSES — see `WidgetVaultUnreachableError`. Falling back to the
+     * viewer's own vault is what produced the confident lie above.
+     */
+    vaultId?: string;
+}
 export interface IdentityRequest {
     type: typeof IDENTITY_REQUEST_TYPE;
     requestId: string;
@@ -34,6 +72,42 @@ export interface IdentityResponse {
     pubkey?: string;
     /** Defaults to 'ed25519' when omitted. */
     sigType?: SigType;
+    /**
+     * A bearer delegation the widget may use INSTEAD of asking the host to sign.
+     *
+     * WHY IT EXISTS. Without one, every vault request a widget makes is signed —
+     * and on the passkey wallet a signature from a keyless session raises a
+     * step-up. A widget that polls a query therefore raised a passkey prompt per
+     * poll, forever. The host already holds a session and can mint a delegation
+     * with no ceremony at all, so handing one over turns N ceremonies into none.
+     *
+     * OPTIONAL, AND THAT IS THE COMPATIBILITY STORY. A host that does not send
+     * one gets exactly the old behaviour: the widget falls back to
+     * `cef-widget:sign-request` per operation. Nothing already deployed changes.
+     */
+    token?: string;
+    /**
+     * WHICH RUN THE HOST IS SHOWING — so a widget opened from an execution can
+     * show THAT execution rather than the latest.
+     *
+     * Asked for by name, and left undesigned until now: "we should be able to
+     * pass a parameter, so that the widget opens the right records … a simple
+     * 'id' parameter would suffice and then anyone who decides to build a widget
+     * can decide to support that parameter or not."
+     *
+     * That last clause is the design. This is CONTEXT, not a command: a widget
+     * that ignores it behaves exactly as it does today, and a host that sends
+     * none is the existing case. Neither side has to change for the other's to
+     * work, which is why it is a field on the handshake rather than a new
+     * message or a required query parameter.
+     *
+     * A BAG, not a bare string, and the reason is the thing it will grow into: an
+     * execution id is what an execution view has, but the same slot is where a
+     * record id belongs when a widget is opened from a row — and those are
+     * different keys, which nobody has yet decided are the same. Naming the field
+     * now costs nothing; conflating them would cost a migration.
+     */
+    context?: WidgetHostContext;
     error?: string;
     /** Machine-readable reason; see UNSUPPORTED_VERSION_CODE. */
     errorCode?: typeof UNSUPPORTED_VERSION_CODE;
@@ -73,12 +147,18 @@ export declare function isUnsupportedVersion(v: unknown): boolean;
  */
 export declare function isByteArray(value: unknown): value is number[];
 export interface HostBridge {
-    requestIdentity: () => Promise<{
-        pubkey: string;
-        sigType: SigType;
-    } | null>;
+    requestIdentity: () => Promise<HostIdentity | null>;
     sign: (bytes: Uint8Array) => Promise<Uint8Array>;
 }
+/** What the host answered the handshake with. */
+export interface HostIdentity {
+    pubkey: string;
+    sigType: SigType;
+    /** A bearer delegation, when the host supplied one. See IdentityResponse.token. */
+    token?: string;
+    /** Why the host opened this widget. See IdentityResponse.context. */
+    context?: WidgetHostContext;
+}
 /**
  * Returns the host bridge client. The bridge is stateless across calls
  * (identity is cached internally after the first successful handshake).

package/dist/host-bridge.js

@@ -175,7 +175,12 @@ async function requestIdentity() {
                         scheduleRetryOrTimeout();
                         return;
                     }
-                    const result = { pubkey: d.pubkey, sigType: d.sigType ?? 'ed25519' };
+                    const result = {
+                        pubkey: d.pubkey,
+                        sigType: d.sigType ?? 'ed25519',
+                        ...(d.token ? { token: d.token } : {}),
+                        ...(d.context ? { context: d.context } : {}),
+                    };
                     finish();
                     cachedIdentity = result;
                     outerResolve(result);

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { renderSubmit } from './kinds/submit.js';
 export { renderConversation } from './kinds/conversation.js';
 export { renderComposite, registerCompositePanel, getCompositePanel, type CompositePanelRenderer } from './kinds/composite.js';
 export * from './render-helpers.js';
+export { WidgetVaultUnreachableError } from './vault-client.js';
 export type { WidgetKind, WidgetConfig, RecordConfig, ListConfig, DashboardConfig, SubmitConfig, ConversationConfig, CustomPanelConfig, CompositePanel, CompositeConfig } from './types.js';
 export { captureAndUploadAudio, createVaultObjectUploader, createVaultObjectStore } from './audio/capture-upload.js';
 export type { CaptureUploadInput, CaptureUploadDeps, VaultObjectUploaderConfig, VaultObjectsLike, VaultStoreConfig, VaultObjectStore } from './audio/capture-upload.js';
@@ -21,6 +22,7 @@ export { encodeWav } from './audio/wav.js';
 export { segmentPcm, decodeToMono16k } from './audio/segment.js';
 export { requestMicStream } from './audio/mic.js';
 export { createHostBridge, type HostBridge } from './host-bridge.js';
+export type { WidgetHostContext } from './host-bridge.js';
 export { IDENTITY_REQUEST_TYPE, IDENTITY_RESPONSE_TYPE, SIGN_REQUEST_TYPE, SIGN_RESPONSE_TYPE, PROTOCOL_VERSION, UNSUPPORTED_VERSION_CODE, MAX_SIGN_BYTES, isByteArray, WidgetProtocolVersionError, WidgetMalformedMessageError, } from './host-bridge.js';
 export type { SigType, IdentityRequest, IdentityResponse, SignRequest, SignResponse, } from './host-bridge.js';
 export { createWidgetHost, type WidgetHostOptions, type WidgetHostIdentity } from './widget-host.js';

package/dist/index.js

@@ -11,6 +11,7 @@ export { renderSubmit } from './kinds/submit.js';
 export { renderConversation } from './kinds/conversation.js';
 export { renderComposite, registerCompositePanel, getCompositePanel } from './kinds/composite.js';
 export * from './render-helpers.js';
+export { WidgetVaultUnreachableError } from './vault-client.js';
 export { captureAndUploadAudio, createVaultObjectUploader, createVaultObjectStore } from './audio/capture-upload.js';
 export { mintDelegationToken, Operation } from './audio/ddc-delegation.js';
 export { encodeWav } from './audio/wav.js';

package/dist/manifest.d.ts

@@ -20,7 +20,10 @@ export interface BuildManifestInput {
     queries?: Array<{
         id: string;
         label?: string;
-        sql: string;
+        sql?: string;
+        cubby?: string;
+        tool?: 'search' | 'get' | 'neighbours' | 'countByType';
+        limit?: number;
         timeoutMs?: number;
     }>;
     events?: WidgetManifest['events'];

package/dist/manifest.js

@@ -5,11 +5,23 @@ export function buildWidgetManifest(input) {
     // Build queries[]: explicit array takes priority; otherwise fall back to single query shorthand.
     let resolvedQueries;
     if (input.queries && input.queries.length > 0) {
+        // FIELD BY FIELD, and every new field has to be added here.
+        //
+        // This is the only copy of the manifest the runtime ever sees — it is baked
+        // into the widget's entry HTML as `window.WidgetSandbox.manifest` — so a
+        // field dropped here fails in the most expensive way available: the widget
+        // loads, the query runs, and it reads the wrong thing. Losing `tool` turns
+        // a memory read into a cubby read with no SQL; losing `cubby` sends a query
+        // to the widget's default alias and shows an empty table that looks like
+        // "nothing happened yet".
         resolvedQueries = input.queries.map((q) => ({
             id: q.id,
             label: q.label ?? q.id,
             sql: q.sql,
             timeoutMs: q.timeoutMs ?? 60000,
+            ...(q.cubby ? { cubby: q.cubby } : {}),
+            ...(q.tool ? { tool: q.tool } : {}),
+            ...(q.limit !== undefined ? { limit: q.limit } : {}),
         }));
     }
     else if (input.query) {

package/dist/mount.js

@@ -27,6 +27,32 @@ export async function mountKind(root, config, runtime, deps) {
             await renderer(root, config, runtime, deps);
         }
         catch (err) {
+            /*
+             * THE RUN IS SOMEWHERE THIS WIDGET CANNOT LOOK — said here, once, rather
+             * than in each widget.
+             *
+             * This case used to arrive as zero rows, so every widget answered it with
+             * its own `empty` copy: "No candidate has been reviewed yet", about a run
+             * whose own INSERT had reported `rowsAffected: 1`. No widget can tell an
+             * empty result from a wrong-database result, so no widget should have to
+             * — the runtime is what knows which vault it could not open, and it is
+             * the only layer that can name it.
+             *
+             * Matched on `name`, like AgentNotConnectedError below, so an error that
+             * crossed a bundle boundary still lands here — widget-runtime ships both
+             * as this package and as a vendored IIFE.
+             */
+            if (err && err.name === 'WidgetVaultUnreachableError') {
+                const vaultId = err.vaultId;
+                root.innerHTML =
+                    '<p class="error">This run executed in a vault this widget cannot read'
+                        + (vaultId ? ` (<code>${esc(vaultId)}</code>)` : '')
+                        + '.</p>'
+                        + '<p class="muted">Nothing is shown, on purpose: your own vault is a different '
+                        + 'database, and reading that one here would look exactly like a run that produced '
+                        + 'nothing. Ask an admin of that organization for access.</p>';
+                return;
+            }
             if (err && err.name === 'AgentNotConnectedError') {
                 root.innerHTML = `<p class="muted">Connect your account to view this.</p><button id="cta">Connect</button>`;
                 root.querySelector('#cta').addEventListener('click', async () => {

package/dist/resolve-identity.d.ts

@@ -1,4 +1,4 @@
-import type { HostBridge } from './host-bridge.js';
+import type { HostBridge, WidgetHostContext } from './host-bridge.js';
 import type { StandaloneWallet } from './standalone-wallet.js';
 /**
  * A resolved signing identity plus its raw-bytes signer. Shared by both the
@@ -9,6 +9,26 @@ export interface ResolvedSigningIdentity {
     publicKey: string;
     sigType: 'ed25519' | 'sr25519';
     sign: (bytes: Uint8Array) => Promise<Uint8Array>;
+    /**
+     * A bearer delegation the host supplied, when it did.
+     *
+     * PREFER IT OVER `sign` FOR EVERY VAULT REQUEST. On the passkey wallet a
+     * signature from a keyless session raises a step-up, so a widget that signs
+     * each request raises a ceremony each request — a polling query asks forever.
+     * A delegation is minted once by the host, with no ceremony at all, and
+     * authenticates exactly the same reads and writes.
+     *
+     * `sign` stays for hosts that supply no token, and for anything a delegation
+     * genuinely cannot carry.
+     */
+    token?: string;
+    /**
+     * Why the host opened this widget — the run being viewed, or the record.
+     *
+     * CONTEXT, NOT A COMMAND. A widget that ignores it behaves exactly as it does
+     * today, which is the compatibility story for every widget already deployed.
+     */
+    context?: WidgetHostContext;
 }
 /**
  * The widget is framed by a host, but the host never supplied an identity —

package/dist/resolve-identity.js

@@ -36,6 +36,8 @@ export function createIdentityResolver(deps) {
                     publicKey: hostId.pubkey,
                     sigType: hostId.sigType,
                     sign: (bytes) => deps.bridge.sign(bytes),
+                    ...(hostId.token ? { token: hostId.token } : {}),
+                    ...(hostId.context ? { context: hostId.context } : {}),
                 };
             }
             // Framed but unanswered: the host owns the identity. Do not downgrade.

package/dist/runtime.d.ts

@@ -1,9 +1,12 @@
 import type { WidgetManifest, WidgetRuntimeApi } from './types.js';
+import type { WidgetHostContext } from './host-bridge.js';
 import type { VaultClient } from './vault-client.js';
 export interface ResolvedRuntimeIdentity {
     source: string;
     publicKey: string;
     sigType?: 'ed25519' | 'sr25519';
+    /** Why the host opened this widget — see `Identity.context`. */
+    context?: WidgetHostContext;
 }
 export interface RuntimeDeps {
     resolveIdentity: (manifest: WidgetManifest) => Promise<ResolvedRuntimeIdentity>;

package/dist/runtime.js

@@ -1,11 +1,12 @@
 export function createWidgetRuntime(manifest, deps) {
     let status = 'anon';
     let publicKey = '';
+    let context;
     let clientP;
     const subs = new Set();
     const emit = (s) => {
         status = s;
-        const snapshot = { publicKey, status };
+        const snapshot = { publicKey, status, ...(context ? { context } : {}) };
         for (const cb of subs)
             cb(snapshot);
     };
@@ -14,6 +15,16 @@ export function createWidgetRuntime(manifest, deps) {
             emit('connecting');
             const id = await deps.resolveIdentity(manifest);
             publicKey = id.publicKey;
+            /*
+             * THE RUN THE HOST OPENED THIS ON, kept so the widget can ask for it.
+             *
+             * It arrived on the handshake and stopped here: the resolver put it on
+             * the resolved identity and nothing carried it the last step into
+             * `identity()`. A widget could therefore be handed the execution it was
+             * opened for and have no way to read it — which is the entire reason the
+             * field exists.
+             */
+            context = id.context;
             const client = deps.buildVaultClient(manifest, id);
             emit('ready');
             return client;
@@ -27,8 +38,14 @@ export function createWidgetRuntime(manifest, deps) {
     return {
         async query(ref, params) { return (await ensureClient()).query(ref, params); },
         async publish(type, payload, context) { return (await ensureClient()).publish(type, payload, context); },
-        async identity() { await ensureClient(); return { publicKey, status }; },
-        async connect() { await ensureClient(); return { publicKey, status }; },
+        async identity() {
+            await ensureClient();
+            return { publicKey, status, ...(context ? { context } : {}) };
+        },
+        async connect() {
+            await ensureClient();
+            return { publicKey, status, ...(context ? { context } : {}) };
+        },
         async connectAgent() { await (await ensureClient()).connectAgent(); },
         async agentStatus() { return (await ensureClient()).agentStatus(); },
         onIdentityChange(cb) { subs.add(cb); return () => subs.delete(cb); },

package/dist/types.d.ts

@@ -1,3 +1,51 @@
+import type { WidgetHostContext } from './host-bridge.js';
+/**
+ * One named read a widget may perform.
+ *
+ * TWO PLACES TO READ FROM, because a widget has two honest questions and only
+ * one of them used to be answerable:
+ *
+ *   the AGENT SERVICE's cubbies — what this agent and its siblings did. A
+ *   workflow runner, a coordinator and three specialists are one service; a
+ *   widget that could only read one of them could only tell part of the story.
+ *   There is no separate per-agent store any more: `ctx.cubby` addresses the
+ *   service, so the widget's own agent's rows are already in there.
+ *
+ *   the vault's MEMORY BANK — what the organisation concluded, which outlives
+ *   every run.
+ *
+ * `sql` means the first and `tool` means the second, and the two are mutually
+ * exclusive. There is no `source` discriminator: beside two already-disjoint
+ * fields it would only be a way for them to disagree.
+ */
+export interface WidgetQueryDecl {
+    id: string;
+    label: string;
+    /**
+     * SQL against one of the agent service's cubbies. Mutually exclusive with
+     * {@link tool}, and one of the two is what says where this query reads.
+     */
+    sql?: string;
+    /** Which of the service's cubbies. Defaults to the widget's `cubbyAlias`. */
+    cubby?: string;
+    /**
+     * A read from the vault's memory bank, named rather than expressed as SQL —
+     * the bank is a gated graph API, not a table, and a SQL string would imply a
+     * reach it does not offer.
+     *
+     * `search` takes the match string as the first parameter; `get` and
+     * `neighbours` take a record id; `countByType` takes none.
+     *
+     * THERE IS NO THIRD PLACE TO READ FROM, so there is no `source` field to
+     * choose one. A widget sees the agent service's cubbies and the vault's
+     * memory; `sql` means the first and `tool` means the second. A discriminator
+     * beside two already-disjoint fields is a way for them to disagree.
+     */
+    tool?: 'search' | 'get' | 'neighbours' | 'countByType';
+    /** `tool` only: row cap. The bank's own default applies when absent. */
+    limit?: number;
+    timeoutMs?: number;
+}
 export interface WidgetManifest {
     schemaVersion: 1;
     widgetId: string;
@@ -16,12 +64,7 @@ export interface WidgetManifest {
         s3GatewayAuthInfo: string;
         rpc: string;
     };
-    queries: Array<{
-        id: string;
-        label: string;
-        sql: string;
-        timeoutMs?: number;
-    }>;
+    queries: WidgetQueryDecl[];
     events?: Array<{
         type: string;
         schemaRef?: string;
@@ -33,6 +76,17 @@ export type IdentityStatus = 'anon' | 'connecting' | 'ready';
 export interface Identity {
     publicKey: string;
     status: IdentityStatus;
+    /**
+     * WHY THE HOST OPENED THIS WIDGET — the run being viewed, or the record.
+     *
+     * Absent when the widget is standalone, or when the host said nothing, and
+     * ABSENT rather than empty: a widget doing `'context' in id` must be able to
+     * tell "the host told me nothing" from "the host told me something empty".
+     *
+     * This is what lets one widget serve two jobs: opened from the Widgets tab it
+     * shows the latest, opened from an execution it shows THAT execution.
+     */
+    context?: WidgetHostContext;
 }
 export interface QueryResult {
     columns: string[];