@cef-ai/widget-runtime 1.1.1 → 2.0.0

package/dist/vault-client.js

@@ -1,5 +1,5 @@
 // packages/widget-runtime/src/vault-client.ts
-import { AgentNotConnectedError } from './types.js';
+import {} from './types.js';
 /**
  * Normalise the raw result from cubbies.query into a uniform QueryResult.
  * The platform returns `{columns: string[], rows: unknown[][]}` (positional).
@@ -23,78 +23,123 @@ 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) {
     let sdk;
     let vaultP;
-    let agentHandleP;
     const getSdk = () => (sdk ?? (sdk = makeSdk()));
     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 = getSdk().vault.ensure({
+            onboard: false,
+            ...(hostToken ? { delegationToken: hostToken } : {}),
+        }).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 +151,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 };
+}