@cef-ai/widget-runtime 1.1.1 → 2.0.0

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,19 @@ 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();
+            // 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 };
         },
         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 +59,17 @@ 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));
+            return createVaultClient(m, makeSdk, hostToken);
         },
     };
     // Build the mount deps (audio uploader) for config-driven audio kinds.
@@ -85,13 +95,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 +136,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,19 @@ 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;
+}
 export interface IdentityRequest {
     type: typeof IDENTITY_REQUEST_TYPE;
     requestId: string;
@@ -34,6 +47,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 +122,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/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/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[];

package/dist/vault-client.d.ts

@@ -1,8 +1,9 @@
-import { type WidgetManifest, type QueryResult } from './types.js';
+import { type QueryResult, type WidgetManifest } from './types.js';
 export interface VaultSdkLike {
     vault: {
         ensure: (opts?: {
             onboard?: boolean;
+            delegationToken?: string;
         }) => Promise<VaultLike>;
     };
 }
@@ -25,6 +26,31 @@ interface VaultLike {
             eventId: string;
         }>;
     };
+    /**
+     * The agent-SERVICE cubbies: one database per service, global within the
+     * vault, so a widget reads what its agent's siblings wrote wherever the run
+     * came from. Optional on the structural type because a host running an older
+     * vault-sdk does not have `vault.service`.
+     */
+    service?: (asPubKey: string) => {
+        cubby: (alias: string) => CubbyHandleLike;
+    };
+    /**
+     * The vault's memory bank — the read half. Same `{columns, rows}` shape the
+     * cubby returns, which is why one normaliser serves both.
+     */
+    memory?: MemoryLike;
+}
+/** The bank's read surface, as much of it as a widget can name. */
+interface MemoryLike {
+    search: (match: string, opts?: {
+        limit?: number;
+    }) => Promise<unknown>;
+    get: (id: string) => Promise<unknown>;
+    neighbours: (id: string, opts?: {
+        limit?: number;
+    }) => Promise<unknown>;
+    countByType: () => Promise<unknown>;
 }
 interface CubbyHandleLike {
     query: (sql: string, params?: unknown[]) => Promise<unknown>;
@@ -41,5 +67,24 @@ export interface VaultClient {
     connectAgent(): Promise<void>;
     agentStatus(): Promise<'connected' | 'disconnected'>;
 }
-export declare function createVaultClient(manifest: WidgetManifest, makeSdk: () => VaultSdkLike): VaultClient;
+export declare function createVaultClient(manifest: WidgetManifest, makeSdk: () => VaultSdkLike, 
+/**
+ * The host's delegation, when it gave one — handed to `ensure()` as well as
+ * used for auth.
+ *
+ * WHY BOTH. With a token the SDK is built with `auth` and NO `signer`, on
+ * purpose: the handle structurally cannot sign, which is what keeps a keyless
+ * passkey session from stepping up on every request. But `vault.ensure()`
+ * does not look at `auth` — it needs a `delegationToken` or a `signer`, and
+ * with neither it throws before the first query runs:
+ *
+ *   vault.ensure() needs either a `delegationToken` or a `signer` configured
+ *   on VaultSDKConfig (the signer drives the on-chain vault-delegate grant).
+ *
+ * So a framed widget with a host delegation — the configuration this whole
+ * tier is built around — could authenticate every request and never reach
+ * one. The token IS the authorization, which is exactly the case `ensure`
+ * documents `delegationToken` for.
+ */
+hostToken?: string): VaultClient;
 export {};