@cef-ai/widget-runtime 2.0.0 → 2.1.1

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/entry.js

@@ -47,7 +47,23 @@ function boot() {
             // Remembered for buildVaultClient, which is synchronous and runs after
             // this. The resolver is memoised, so this is the same identity.
             hostDelegation = id.token;
-            return { source: id.source, publicKey: id.publicKey, sigType: id.sigType };
+            /*
+             * 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';
@@ -69,7 +85,12 @@ function boot() {
             // asked for a passkey forever. `sign` stays wired for hosts that supply
             // no token.
             const makeSdk = () => new VaultSDK(toVaultSdkConfig(m.endpoints, vaultSdkSigner, hostToken));
-            return createVaultClient(m, makeSdk, 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.
@@ -101,7 +122,13 @@ function boot() {
                 // 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 });
+                // With a token that SDK has no signer, and `ensure()` does not read
+                // `auth`: it needs the token handed to it, or it throws before the
+                // first chunk. Without one the key stays absent so the signer path runs.
+                const ensuredVault = await sdk.vault.ensure({
+                    onboard: false,
+                    ...(id.token ? { delegationToken: id.token } : {}),
+                });
                 return createVaultObjectUploader({ objects: ensuredVault.scope(manifest.scope).objects });
             })().catch((err) => { uploaderP = null; throw err; });
             return uploaderP;

package/dist/host-bridge.d.ts

@@ -33,6 +33,31 @@ export interface WidgetHostContext {
     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;

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/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/vault-client.d.ts

@@ -5,8 +5,42 @@ export interface VaultSdkLike {
             onboard?: boolean;
             delegationToken?: string;
         }) => Promise<VaultLike>;
+        /**
+         * SOMEBODY ELSE'S VAULT, by id — what `ensure()` structurally cannot give
+         * you. `ensure` claims the CALLER'S OWN vault, and the host's delegation
+         * authenticates the caller rather than naming a vault, so with only those
+         * two a widget opened on an org's run read the viewer's own database.
+         *
+         * OPTIONAL on this structural type because a host pinned to an older
+         * vault-sdk does not have it — and a widget the host named a vault for must
+         * then refuse rather than quietly read the wrong one.
+         */
+        byId?: (vaultId: string) => Promise<VaultLike>;
     };
 }
+/**
+ * The host named a vault this widget cannot open.
+ *
+ * WHY THIS IS AN ERROR AND NOT AN EMPTY RESULT, which is the whole point of the
+ * type. The failure it replaces was silent: the widget opened the wrong vault,
+ * queried it successfully, got zero rows, and rendered "No candidate has been
+ * reviewed yet" — about a run whose own `_cubbyQueries` log showed the INSERT
+ * landing with `rowsAffected: 1`. A confident lie, indistinguishable from the
+ * honest empty case, and it cost hours. So when the id is supplied and unusable
+ * the runtime says so instead of answering; there is no fallback path, because
+ * the fallback IS the bug.
+ *
+ * Shaped after `WidgetSignedOutError`: a named class whose message names itself
+ * first, so it reads the same in a console, in a rejected promise, and in the
+ * frame `mountKind` renders it into.
+ */
+export declare class WidgetVaultUnreachableError extends Error {
+    /** The vault the host named. Carried so a renderer can name it too. */
+    readonly vaultId: string;
+    /** What `vault.byId` said, when it said anything. */
+    readonly reason: string;
+    constructor(vaultId: string, cause?: unknown);
+}
 interface VaultLike {
     id: string;
     agents: {
@@ -86,5 +120,20 @@ export declare function createVaultClient(manifest: WidgetManifest, makeSdk: ()
  * one. The token IS the authorization, which is exactly the case `ensure`
  * documents `delegationToken` for.
  */
-hostToken?: string): VaultClient;
+hostToken?: string, 
+/**
+ * WHICH VAULT, when the host named one (`WidgetHostContext.vaultId`).
+ *
+ * WHY IT IS SEPARATE FROM THE TOKEN, which is the mistake this fixes. The
+ * host already passed a credential, so the widget authenticated fine and
+ * raised no passkey — but a delegation says WHO, not WHICH VAULT, and
+ * `ensure()` claims the caller's OWN. A workflow runs in the vault of the org
+ * that owns its agent service, so for a member of somebody else's service the
+ * two are different databases and the widget read the empty one.
+ *
+ * ABSENT IS THE DEFAULT AND STAYS EXACTLY AS IT WAS: `ensure({onboard:false})`
+ * with the host's delegation. Present means open THAT vault and, if it cannot
+ * be opened, refuse — see {@link WidgetVaultUnreachableError}.
+ */
+hostVaultId?: string): VaultClient;
 export {};

package/dist/vault-client.js

@@ -1,5 +1,34 @@
 // packages/widget-runtime/src/vault-client.ts
 import {} from './types.js';
+/**
+ * The host named a vault this widget cannot open.
+ *
+ * WHY THIS IS AN ERROR AND NOT AN EMPTY RESULT, which is the whole point of the
+ * type. The failure it replaces was silent: the widget opened the wrong vault,
+ * queried it successfully, got zero rows, and rendered "No candidate has been
+ * reviewed yet" — about a run whose own `_cubbyQueries` log showed the INSERT
+ * landing with `rowsAffected: 1`. A confident lie, indistinguishable from the
+ * honest empty case, and it cost hours. So when the id is supplied and unusable
+ * the runtime says so instead of answering; there is no fallback path, because
+ * the fallback IS the bug.
+ *
+ * Shaped after `WidgetSignedOutError`: a named class whose message names itself
+ * first, so it reads the same in a console, in a rejected promise, and in the
+ * frame `mountKind` renders it into.
+ */
+export class WidgetVaultUnreachableError extends Error {
+    constructor(vaultId, cause) {
+        const reason = cause === undefined
+            ? 'this build of the runtime has no vault.byId to open it with'
+            : (cause instanceof Error ? cause.message : String(cause));
+        super(`WidgetVaultUnreachableError: the host opened this widget on vault ${vaultId}, `
+            + `and it cannot be read from here (${reason}). Falling back to your own vault would `
+            + 'answer from a different database — which looks exactly like a run that produced nothing.');
+        this.name = 'WidgetVaultUnreachableError';
+        this.vaultId = vaultId;
+        this.reason = reason;
+    }
+}
 /**
  * Normalise the raw result from cubbies.query into a uniform QueryResult.
  * The platform returns `{columns: string[], rows: unknown[][]}` (positional).
@@ -42,18 +71,58 @@ export function createVaultClient(manifest, makeSdk,
  * one. The token IS the authorization, which is exactly the case `ensure`
  * documents `delegationToken` for.
  */
-hostToken) {
+hostToken, 
+/**
+ * WHICH VAULT, when the host named one (`WidgetHostContext.vaultId`).
+ *
+ * WHY IT IS SEPARATE FROM THE TOKEN, which is the mistake this fixes. The
+ * host already passed a credential, so the widget authenticated fine and
+ * raised no passkey — but a delegation says WHO, not WHICH VAULT, and
+ * `ensure()` claims the caller's OWN. A workflow runs in the vault of the org
+ * that owns its agent service, so for a member of somebody else's service the
+ * two are different databases and the widget read the empty one.
+ *
+ * ABSENT IS THE DEFAULT AND STAYS EXACTLY AS IT WAS: `ensure({onboard:false})`
+ * with the host's delegation. Present means open THAT vault and, if it cannot
+ * be opened, refuse — see {@link WidgetVaultUnreachableError}.
+ */
+hostVaultId) {
     let sdk;
     let vaultP;
     const getSdk = () => (sdk ?? (sdk = makeSdk()));
+    /**
+     * THE VAULT THIS WIDGET READS — the one the host named, else the caller's.
+     *
+     * There is deliberately no third branch. A named vault that will not open is
+     * an error, never a quiet fall-through to `ensure()`: the fall-through is
+     * indistinguishable from an empty result, and being indistinguishable from an
+     * empty result is the bug.
+     */
+    const openVault = async () => {
+        if (!hostVaultId) {
+            // `onboard: false` preserves the old lightweight ensure(): claim the vault
+            // with a wallet-built delegation token, skipping the gateway onboarding
+            // status/bootstrap round-trip (widgets assume a provisioned wallet).
+            return getSdk().vault.ensure({
+                onboard: false,
+                ...(hostToken ? { delegationToken: hostToken } : {}),
+            });
+        }
+        const vaultNs = getSdk().vault;
+        if (typeof vaultNs.byId !== 'function') {
+            throw new WidgetVaultUnreachableError(hostVaultId);
+        }
+        try {
+            return await vaultNs.byId(hostVaultId);
+        }
+        catch (err) {
+            // Not found, no access, network — all one answer to the reader: this is
+            // not your vault and nothing here can show you what is in it.
+            throw new WidgetVaultUnreachableError(hostVaultId, err);
+        }
+    };
     const getVault = () => {
-        // `onboard: false` preserves the old lightweight ensure(): claim the vault
-        // with a wallet-built delegation token, skipping the gateway onboarding
-        // status/bootstrap round-trip (widgets assume a provisioned wallet).
-        vaultP ?? (vaultP = getSdk().vault.ensure({
-            onboard: false,
-            ...(hostToken ? { delegationToken: hostToken } : {}),
-        }).catch((err) => {
+        vaultP ?? (vaultP = openVault().catch((err) => {
             vaultP = undefined;
             throw err;
         }));