@cef-ai/widget-runtime 1.1.1 → 2.1.0

package/dist/vault-client.d.ts

@@ -1,11 +1,46 @@
-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>;
+        /**
+         * 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: {
@@ -25,6 +60,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 +101,39 @@ 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, 
+/**
+ * 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 { AgentNotConnectedError } from './types.js';
+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).
@@ -23,78 +52,163 @@ function normaliseQueryResult(raw) {
     console.warn('[widget-runtime] unrecognized cubby query result shape; treating as empty', raw);
     return { columns: [], rows: [], meta: { rowCount: 0 } };
 }
+export function createVaultClient(manifest, makeSdk, 
 /**
- * Map a cubbies.query rejection to AgentNotConnectedError when the error
- * indicates a 404 / agent-not-connected condition.
+ * 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.
  */
-function mapQueryError(err, agentId) {
-    if (err && typeof err === 'object') {
-        const status = err.status;
-        const message = err.message;
-        if (status === 404 ||
-            (typeof message === 'string' && /not.?connected|404/i.test(message))) {
-            throw new AgentNotConnectedError(agentId);
-        }
-    }
-    throw err;
-}
-export function createVaultClient(manifest, makeSdk) {
+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;
-    let agentHandleP;
     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 }).catch((err) => {
+        vaultP ?? (vaultP = openVault().catch((err) => {
             vaultP = undefined;
             throw err;
         }));
         return vaultP;
     };
-    // Memoised agent-connection handle for cubby reads. Cached so polling
-    // queries don't re-fetch the connection record on every call (matching the
-    // single-request-per-query cost of the prior path). Reset on (re)connect
-    // and on read failure so a stale handle can't pin a disconnected state.
-    const getAgentHandle = () => {
-        agentHandleP ?? (agentHandleP = getVault()
-            .then((vault) => vault.agents.get(manifest.agentId))
-            .catch((err) => {
-            agentHandleP = undefined;
-            throw err;
-        }));
-        return agentHandleP;
+    const declFor = (ref) => manifest.queries.find((q) => q.id === ref);
+    /**
+     * The agent service a widget belongs to — the half of its agent id before the
+     * colon.
+     *
+     * DERIVED, never declared. A widget that could name its own service could
+     * name somebody else's, and then a query's reach would be a field in a file
+     * uploaded to a content gateway rather than a property of who published it.
+     * This way the only service a widget can read is the one that shipped it.
+     */
+    const ownService = () => {
+        const at = manifest.agentId.indexOf(':');
+        return at > 0 ? manifest.agentId.slice(0, at) : '';
+    };
+    /** Read the service's cubby — what this agent's siblings wrote. The default. */
+    const queryService = async (decl, params) => {
+        const vault = await getVault();
+        if (!vault.service) {
+            throw new Error('[widget-runtime] this host\'s vault-sdk has no agent-service cubby surface, '
+                + `so the query "${decl.id}" cannot be answered here`);
+        }
+        const asPubKey = ownService();
+        if (!asPubKey) {
+            throw new Error(`[widget-runtime] "${decl.id}" reads the agent service's cubby, but `
+                + `"${manifest.agentId}" carries no service key to read it from`);
+        }
+        // WHICH of the service's cubbies. `cubbyAlias` is the default, and it is
+        // legitimately EMPTY for a widget that declares no cubby of its own —
+        // `buildWidgetManifestForDecl` writes "" in that case — so a `service`
+        // query that also names none has no alias at all. Left unguarded that
+        // reaches vault-api as `/cubbies//query` and comes back as an alias-shape
+        // 400, which sends the author to look at their SQL.
+        const alias = decl.cubby ?? manifest.cubbyAlias;
+        if (!alias) {
+            throw new Error(`[widget-runtime] "${decl.id}" reads the agent service's cubby but names `
+                + 'none, and this widget has no cubbyAlias to fall back on — set `cubby` on the query');
+        }
+        return vault.service(asPubKey).cubby(alias).query(decl.sql ?? '', params);
+    };
+    /**
+     * Read the vault's memory bank.
+     *
+     * Named tools rather than SQL, because the bank is a gated graph API and not
+     * a table: the gate decides which records the caller may see, and a SQL
+     * string would imply a reach the surface does not offer.
+     */
+    const queryMemory = async (decl, params) => {
+        const vault = await getVault();
+        if (!vault.memory) {
+            throw new Error('[widget-runtime] this host\'s vault-sdk has no memory surface, '
+                + `so the query "${decl.id}" cannot be answered here`);
+        }
+        const first = params[0];
+        const limit = decl.limit;
+        switch (decl.tool ?? 'search') {
+            case 'search':
+                return vault.memory.search(String(first ?? ''), limit ? { limit } : undefined);
+            case 'get':
+                return vault.memory.get(String(first ?? ''));
+            case 'neighbours':
+                return vault.memory.neighbours(String(first ?? ''), limit ? { limit } : undefined);
+            case 'countByType':
+                return vault.memory.countByType();
+            default:
+                throw new Error(`[widget-runtime] "${decl.id}" names no memory tool this runtime knows`);
+        }
     };
-    const resolveSql = (ref) => manifest.queries.find((q) => q.id === ref)?.sql ?? ref;
     return {
         async query(ref, params) {
-            // Cubby reads go through vault-sdk's agentId-keyed endpoint. This was
-            // briefly routed via @cef-ai/client-sdk because vault-sdk@0.5.0
-            // percent-encoded the agentId ':' → '%3A' → 404; fixed in 0.5.1.
-            let raw;
-            try {
-                const handle = await getAgentHandle();
-                // vault-sdk 2.x throws synchronously from `.cubby(alias)` when the
-                // alias isn't in the connection's declared aliases (e.g. the agent
-                // isn't connected yet, so the handle carries no aliases). Map that to
-                // AgentNotConnectedError instead of letting an opaque throw escape.
-                let cubbyHandle;
-                try {
-                    cubbyHandle = handle.cubby(manifest.cubbyAlias);
-                }
-                catch {
-                    throw new AgentNotConnectedError(manifest.agentId);
-                }
-                raw = await cubbyHandle.query(resolveSql(ref), params ?? []);
-            }
-            catch (err) {
-                agentHandleP = undefined; // force a fresh handle on the next read
-                if (err instanceof AgentNotConnectedError)
-                    throw err;
-                mapQueryError(err, manifest.agentId);
+            const decl = declFor(ref);
+            // TWO PLACES, AND THE DECLARATION SAYS WHICH. `tool` is the memory bank;
+            // anything else is SQL against one of the agent service's cubbies. A ref
+            // matching no declaration is raw SQL, which is a cubby read.
+            //
+            // Neither is agent-connection shaped — a cubby read addresses the
+            // SERVICE, the bank addresses the vault — so neither can fail as "agent
+            // not connected".
+            if (decl?.tool) {
+                return normaliseQueryResult(await queryMemory(decl, params ?? []));
             }
-            return normaliseQueryResult(raw);
+            return normaliseQueryResult(await queryService(decl ?? { id: ref, label: ref, sql: ref }, params ?? []));
         },
         async publish(type, payload, context) {
             const vault = await getVault();
@@ -106,7 +220,6 @@ export function createVaultClient(manifest, makeSdk) {
             // The vault-api resolves the manifest from the DDC registry and the SDK
             // signs the GAR agreement internally — no marketplace.getAgent() fetch.
             await vault.agents.connect({ agentId: manifest.agentId, scope: manifest.scope });
-            agentHandleP = undefined; // drop any cached pre-connect handle
         },
         async agentStatus() {
             try {

package/dist/vault-sdk-config.d.ts

@@ -0,0 +1,26 @@
+import type { VaultSDKConfig, Signer } from '@cef-ai/vault-sdk';
+import type { WidgetManifest } from './types.js';
+/**
+ * Build the VaultSDK config the runtime constructs everywhere it talks to a
+ * user's vault — `buildVaultClient`'s SDK (queries/publish/connect) and the
+ * ADR-002 audio uploader's SDK. One builder so the two cannot drift.
+ *
+ * A TOKEN BEATS A SIGNER, when the host supplied one. `auth` overrides
+ * `signer` in `VaultSDKConfig`, so a config built with a delegation provider
+ * structurally CANNOT sign — which is the point: on the passkey wallet every
+ * signature from a keyless session raises a step-up, so a widget that signs per
+ * request raises a ceremony per request. The delegation was minted once, by a
+ * host that already had a session, and authenticates the same calls.
+ *
+ * `chainUrl` (the manifest's `endpoints.rpc`) is required by
+ * `vault.ensure()`'s wallet path: the SDK grants vault-api durable write
+ * delegation by submitting an on-chain `NonTransfer` proxy before claiming
+ * the vault, and needs a Cere node WS URL to do it. Both runtime call sites
+ * use `ensure({ onboard: false })` — that skips the gateway onboarding
+ * round-trip but NOT the grant step, so without `chainUrl` every widget boot
+ * would die on an actionable-but-user-visible config error. The manifest's
+ * `rpc` is baked per environment by the CLI's env table (devnet / testnet /
+ * mainnet), so the runtime inherits the deployment's chain instead of
+ * hard-coding one.
+ */
+export declare function toVaultSdkConfig(endpoints: WidgetManifest['endpoints'], signer: Signer, token?: string): VaultSDKConfig;

package/dist/vault-sdk-config.js

@@ -0,0 +1,37 @@
+// packages/widget-runtime/src/vault-sdk-config.ts
+import { DelegationAuthProvider } from '@cef-ai/vault-sdk';
+/**
+ * Build the VaultSDK config the runtime constructs everywhere it talks to a
+ * user's vault — `buildVaultClient`'s SDK (queries/publish/connect) and the
+ * ADR-002 audio uploader's SDK. One builder so the two cannot drift.
+ *
+ * A TOKEN BEATS A SIGNER, when the host supplied one. `auth` overrides
+ * `signer` in `VaultSDKConfig`, so a config built with a delegation provider
+ * structurally CANNOT sign — which is the point: on the passkey wallet every
+ * signature from a keyless session raises a step-up, so a widget that signs per
+ * request raises a ceremony per request. The delegation was minted once, by a
+ * host that already had a session, and authenticates the same calls.
+ *
+ * `chainUrl` (the manifest's `endpoints.rpc`) is required by
+ * `vault.ensure()`'s wallet path: the SDK grants vault-api durable write
+ * delegation by submitting an on-chain `NonTransfer` proxy before claiming
+ * the vault, and needs a Cere node WS URL to do it. Both runtime call sites
+ * use `ensure({ onboard: false })` — that skips the gateway onboarding
+ * round-trip but NOT the grant step, so without `chainUrl` every widget boot
+ * would die on an actionable-but-user-visible config error. The manifest's
+ * `rpc` is baked per environment by the CLI's env table (devnet / testnet /
+ * mainnet), so the runtime inherits the deployment's chain instead of
+ * hard-coding one.
+ */
+export function toVaultSdkConfig(endpoints, signer, token) {
+    const base = {
+        endpoint: endpoints.vault,
+        garEndpoint: endpoints.gar,
+        marketplaceEndpoint: endpoints.marketplace,
+        s3GatewayAuthInfoUrl: endpoints.s3GatewayAuthInfo,
+        chainUrl: endpoints.rpc,
+    };
+    if (token)
+        return { ...base, auth: new DelegationAuthProvider(token) };
+    return { ...base, signer };
+}