@cef-ai/vault-sdk 4.4.0 → 5.1.0

package/dist/index.js

@@ -5,6 +5,7 @@ export { VaultSDK } from "./client.js";
 export { OnboardingRequiredError, OnboardingTimeoutError, } from "./internal/onboarding.js";
 export { Vault } from "./fluent/vault.js";
 export { ScopeHandle } from "./fluent/scope.js";
+export { ServiceHandle } from "./fluent/service.js";
 export { AgentConnectionHandle } from "./fluent/agent-connection.js";
 export { JobHandle } from "./fluent/job.js";
 export { CubbyHandle } from "./fluent/cubby.js";
@@ -20,15 +21,11 @@ export { VaultRequestError, VaultNotImplementedError, VaultSignerRequiredError,
 // `SignedGrant.role`/`.scopes` instead and end up with a signature it checked
 // and did not act on.
 export { GRANT_ISSUED_AT_HEADER, GRANT_SCHEMA, GRANT_SCHEMA_V2, GRANT_SIGNATURE_HEADER, GrantVerificationError, NO_GRANT_EXPIRY, NO_PRIVACY_CEILING, PRIVACY_CEILINGS, canonicalGrantBytes, canonicalGrantBytesWithCeiling, canonicalPubkeyHex, decodeGrantDoc, grantExpiry, isValidPrivacyCeiling, privacyCeiling, vaultIdFor, verifyGrant, verifyGrantSig, verifySignedRoster, } from "./core/grant-doc.js";
-// Delegate-grant surface — `vault.delegate.{pubkey,grant,revoke}` (see
-// `client.ts`) covers the common connect-time flow, but the frontend also
-// needs direct access to `VaultInfo`'s `DelegateInfo` type (Task 3 left
-// `VaultInfo` itself importable only via `@cef-ai/vault-sdk/internal`) and to
-// `registerDelegate`/`revokeDelegate` for lower-level or custom flows (e.g.
-// re-registering a grant with a pre-fetched pubkey without round-tripping
-// through the SDK instance). Re-exported here via the leaf `delegate-grants`
-// subpath — never the `@cef-ai/account` root barrel — to keep vault-sdk
-// chain-free (ADR-033).
+// Vault-api's delegate identity (`VaultInfo` / `DelegateInfo`) stays exported
+// for the frontend. The `registerDelegate`/`revokeDelegate` re-exports (and
+// the `vault.delegate.{pubkey,grant,revoke}` namespace they backed) were
+// removed with the gateway's `/auth/delegates` API: vault write delegation is
+// now a durable on-chain NonTransfer proxy grant
+// (`@cef-ai/account`'s `ensureVaultDelegate`).
 export { VaultInfo } from "./internal/vault-info.js";
-export { registerDelegate, revokeDelegate, GatewayDelegateError, } from "@cef-ai/account/delegate-grants";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,wEAAwE;AACxE,kCAAkC;AAElC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAOvC,OAAO,EACL,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAOlC,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQhD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAS9C,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAe9D,OAAO,EACL,SAAS,EACT,sBAAsB,EACtB,WAAW,GACZ,MAAM,uBAAuB,CAAC;AAO/B,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAE1B,0EAA0E;AAC1E,wEAAwE;AACxE,8EAA8E;AAC9E,sBAAsB;AACtB,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,8BAA8B,EAC9B,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,cAAc,EACd,UAAU,EACV,WAAW,EACX,cAAc,EACd,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AA0C7B,uEAAuE;AACvE,0EAA0E;AAC1E,wEAAwE;AACxE,8EAA8E;AAC9E,4EAA4E;AAC5E,0EAA0E;AAC1E,6EAA6E;AAC7E,wEAAwE;AACxE,wBAAwB;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAErD,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,oBAAoB,GACrB,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,wEAAwE;AACxE,kCAAkC;AAElC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAOvC,OAAO,EACL,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAOlC,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQhD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAS9C,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAe9D,OAAO,EACL,SAAS,EACT,sBAAsB,EACtB,WAAW,GACZ,MAAM,uBAAuB,CAAC;AAO/B,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAE1B,0EAA0E;AAC1E,wEAAwE;AACxE,8EAA8E;AAC9E,sBAAsB;AACtB,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,8BAA8B,EAC9B,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,cAAc,EACd,UAAU,EACV,WAAW,EACX,cAAc,EACd,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AA4C7B,8EAA8E;AAC9E,4EAA4E;AAC5E,yEAAyE;AACzE,8EAA8E;AAC9E,iDAAiD;AACjD,+CAA+C;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/internal/agents.d.ts

@@ -1,5 +1,5 @@
 import type { VaultHttpClient } from "../core/http.js";
-import type { AgentConnection, AgentConnectionStatus, ConnectAgentRequest } from "../core/types.js";
+import type { AgentConnection, AgentConnectionStatus, ConnectAgentRequest, ConnectionCeiling } from "../core/types.js";
 export interface ListAgentsOptions {
     status?: AgentConnectionStatus;
 }
@@ -7,17 +7,64 @@ export declare class Agents {
     private readonly http;
     constructor(http: VaultHttpClient);
     /**
-     * Low-level surface — POSTs a `ConnectAgentRequest` (`{ agentId, scope,
-     * settings?, agreementSignature? }`) with a pre-signed `agreementSignature`.
-     * `version`/`manifestCid` are not sent; the vault-api resolves the manifest
-     * from the DDC registry. For the high-level flow that signs the GAR
-     * agreement on your behalf, use `vault.agents.connect({ agentId, scope, settings })`
-     * from `@cef-ai/vault-sdk` (requires `garEndpoint` + `wallet` on the SDK config).
+     * Low-level surface — POSTs a `ConnectAgentRequest` (`{ agentId, scope?,
+     * scopes?, settings?, agreementSignature? }`) with a pre-signed
+     * `agreementSignature`. Pass `scopes` for a set of vault scopes, or the
+     * singular `scope` for callers that predate the set — exactly one of the
+     * two is required (`ScopeSelector`); whichever is supplied is sent through
+     * untouched, never derived from the other. `version`/`manifestCid` are not
+     * sent; the vault-api resolves the manifest from the DDC registry. For the
+     * high-level flow that signs the GAR agreement on your behalf, use
+     * `vault.agents.connect({ agentId, scope, settings })` from
+     * `@cef-ai/vault-sdk` (requires `garEndpoint` + `wallet` on the SDK config).
+     *
+     * `ceiling` (optional) is the connection's spend ceiling, written
+     * atomically with the connection row. Set it here to avoid a window where
+     * the connection exists with no ceiling; use {@link setCeiling} to change it
+     * later. It is validated exactly as `setCeiling` validates (see there) and a
+     * violation rejects with `VaultRequestError(status 0, "BAD_REQUEST")` before
+     * any request is made. When present it is sent as `{ gpuUnits, a2aTokens }`
+     * with both axes explicit (absent axis = `0` = no ceiling on that axis);
+     * when `undefined` the `ceiling` key is omitted from the body. The resolved
+     * connection's `ceiling` reports what the server stored (absent when
+     * neither axis is set).
      */
     connect(v: string, req: ConnectAgentRequest): Promise<AgentConnection>;
     list(v: string, opts?: ListAgentsOptions): Promise<AgentConnection[]>;
     get(v: string, a: string): Promise<AgentConnection>;
     update(v: string, a: string, settings: Record<string, unknown>): Promise<AgentConnection>;
+    /**
+     * Set (replace) the connection's spend ceiling —
+     * `PUT /vaults/:v/agents/:a/ceiling`, wallet-signed like {@link update}.
+     *
+     * Both axes are always sent; an absent axis is sent as `0` (= no ceiling on
+     * that axis), so `setCeiling(v, a, {})` clears both. This is a full replace,
+     * not a merge: omitting `a2aTokens` clears an existing token ceiling.
+     *
+     * Validated before sending: only the keys `gpuUnits` and `a2aTokens` are
+     * allowed (any other own key is refused, even with an `undefined` value,
+     * mirroring vault-api's unknown-field refusal); each axis must be a finite
+     * number >= 0; `a2aTokens` must be an integer <= `Number.MAX_SAFE_INTEGER`.
+     * A violation throws {@link VaultRequestError} with `status` 0 and `code`
+     * "BAD_REQUEST" (the same code vault-api uses), and no request is made; the
+     * returned promise rejects. `status` 0 is also what a network failure
+     * carries — distinguish a validation refusal by `code === "BAD_REQUEST"`.
+     *
+     * Resolves to the updated {@link AgentConnection}; its `ceiling` is absent
+     * when both axes are 0.
+     */
+    setCeiling(v: string, a: string, ceiling: ConnectionCeiling): Promise<AgentConnection>;
     disconnect(v: string, a: string): Promise<void>;
 }
+/**
+ * Client-side mirror of vault-api's ceiling validation. Returns the wire body
+ * (`{ gpuUnits, a2aTokens }`, both axes explicit). Throws
+ * `VaultRequestError(status 0, "BAD_REQUEST")` on a violation. Shared by
+ * `setCeiling`, `connect` and the fluent `vault.agents.connect` (which calls it
+ * before the GAR agreement is signed, so a bad ceiling costs no ceremony).
+ */
+export declare function validateCeiling(c: ConnectionCeiling): {
+    gpuUnits: number;
+    a2aTokens: number;
+};
 //# sourceMappingURL=agents.d.ts.map

package/dist/internal/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/internal/agents.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEpG,MAAM,WAAW,iBAAiB;IAAG,MAAM,CAAC,EAAE,qBAAqB,CAAA;CAAE;AAErE,qBAAa,MAAM;IACL,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,eAAe;IAElD;;;;;;;OAOG;IACH,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IAGhE,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAK/E,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAGnD,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC;IAGzF,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGhD"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/internal/agents.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAIvH,MAAM,WAAW,iBAAiB;IAAG,MAAM,CAAC,EAAE,qBAAqB,CAAA;CAAE;AAErE,qBAAa,MAAM;IACL,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,eAAe;IAElD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IAkBtE,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAK/E,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAGnD,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC;IAGzF;;;;;;;;;;;;;;;;;;;OAmBG;IACG,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IAK5F,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGhD;AAMD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,iBAAiB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAiC7F"}

package/dist/internal/agents.js

@@ -1,19 +1,50 @@
 import { endpoints } from "../core/endpoints.js";
+import { resolveConnectScopes } from "../core/connect-scopes.js";
+import { VaultRequestError } from "../core/errors.js";
 export class Agents {
     http;
     constructor(http) {
         this.http = http;
     }
     /**
-     * Low-level surface — POSTs a `ConnectAgentRequest` (`{ agentId, scope,
-     * settings?, agreementSignature? }`) with a pre-signed `agreementSignature`.
-     * `version`/`manifestCid` are not sent; the vault-api resolves the manifest
-     * from the DDC registry. For the high-level flow that signs the GAR
-     * agreement on your behalf, use `vault.agents.connect({ agentId, scope, settings })`
-     * from `@cef-ai/vault-sdk` (requires `garEndpoint` + `wallet` on the SDK config).
+     * Low-level surface — POSTs a `ConnectAgentRequest` (`{ agentId, scope?,
+     * scopes?, settings?, agreementSignature? }`) with a pre-signed
+     * `agreementSignature`. Pass `scopes` for a set of vault scopes, or the
+     * singular `scope` for callers that predate the set — exactly one of the
+     * two is required (`ScopeSelector`); whichever is supplied is sent through
+     * untouched, never derived from the other. `version`/`manifestCid` are not
+     * sent; the vault-api resolves the manifest from the DDC registry. For the
+     * high-level flow that signs the GAR agreement on your behalf, use
+     * `vault.agents.connect({ agentId, scope, settings })` from
+     * `@cef-ai/vault-sdk` (requires `garEndpoint` + `wallet` on the SDK config).
+     *
+     * `ceiling` (optional) is the connection's spend ceiling, written
+     * atomically with the connection row. Set it here to avoid a window where
+     * the connection exists with no ceiling; use {@link setCeiling} to change it
+     * later. It is validated exactly as `setCeiling` validates (see there) and a
+     * violation rejects with `VaultRequestError(status 0, "BAD_REQUEST")` before
+     * any request is made. When present it is sent as `{ gpuUnits, a2aTokens }`
+     * with both axes explicit (absent axis = `0` = no ceiling on that axis);
+     * when `undefined` the `ceiling` key is omitted from the body. The resolved
+     * connection's `ceiling` reports what the server stored (absent when
+     * neither axis is set).
      */
-    connect(v, req) {
-        return this.http.send("POST", endpoints.agents(v), { body: req });
+    async connect(v, req) {
+        // The ceiling is validated (and normalised to the two-axis wire body)
+        // before the request goes out — the same `validateCeiling` setCeiling
+        // uses. Absent → the key stays off the body entirely.
+        const { ceiling, ...rest } = req;
+        const body = ceiling === undefined ? { ...rest } : { ...rest, ceiling: validateCeiling(ceiling) };
+        // Validates the scope selector without rewriting it — `req` is still
+        // forwarded exactly as given below; see resolveConnectScopes for why
+        // this check is needed even though `ConnectAgentRequest` is typed to
+        // forbid both-or-neither already. `connect` is `async` (rather than
+        // just returning the `http.send` promise) specifically so this
+        // validation failure is a rejected promise like every other error from
+        // this method, not a synchronous throw a caller's `await`/`.catch`
+        // wouldn't expect.
+        resolveConnectScopes(req, "Agents.connect");
+        return this.http.send("POST", endpoints.agents(v), { body });
     }
     async list(v, opts = {}) {
         const res = await this.http.send("GET", endpoints.agents(v), { query: { status: opts.status } });
@@ -25,8 +56,79 @@ export class Agents {
     update(v, a, settings) {
         return this.http.send("PATCH", endpoints.agent(v, a), { body: { settings } });
     }
+    /**
+     * Set (replace) the connection's spend ceiling —
+     * `PUT /vaults/:v/agents/:a/ceiling`, wallet-signed like {@link update}.
+     *
+     * Both axes are always sent; an absent axis is sent as `0` (= no ceiling on
+     * that axis), so `setCeiling(v, a, {})` clears both. This is a full replace,
+     * not a merge: omitting `a2aTokens` clears an existing token ceiling.
+     *
+     * Validated before sending: only the keys `gpuUnits` and `a2aTokens` are
+     * allowed (any other own key is refused, even with an `undefined` value,
+     * mirroring vault-api's unknown-field refusal); each axis must be a finite
+     * number >= 0; `a2aTokens` must be an integer <= `Number.MAX_SAFE_INTEGER`.
+     * A violation throws {@link VaultRequestError} with `status` 0 and `code`
+     * "BAD_REQUEST" (the same code vault-api uses), and no request is made; the
+     * returned promise rejects. `status` 0 is also what a network failure
+     * carries — distinguish a validation refusal by `code === "BAD_REQUEST"`.
+     *
+     * Resolves to the updated {@link AgentConnection}; its `ceiling` is absent
+     * when both axes are 0.
+     */
+    async setCeiling(v, a, ceiling) {
+        // `async` so a validation failure is a rejected promise, not a sync throw.
+        const body = validateCeiling(ceiling);
+        return this.http.send("PUT", endpoints.agentCeiling(v, a), { body: { ...body } });
+    }
     disconnect(v, a) {
         return this.http.send("DELETE", endpoints.agent(v, a), { body: {} });
     }
 }
+function invalidCeiling(msg) {
+    return new VaultRequestError(`invalid ceiling: ${msg}`, 0, "BAD_REQUEST");
+}
+/**
+ * Client-side mirror of vault-api's ceiling validation. Returns the wire body
+ * (`{ gpuUnits, a2aTokens }`, both axes explicit). Throws
+ * `VaultRequestError(status 0, "BAD_REQUEST")` on a violation. Shared by
+ * `setCeiling`, `connect` and the fluent `vault.agents.connect` (which calls it
+ * before the GAR agreement is signed, so a bad ceiling costs no ceremony).
+ */
+export function validateCeiling(c) {
+    if (c === null || typeof c !== "object" || Array.isArray(c)) {
+        throw invalidCeiling("expected an object { gpuUnits?, a2aTokens? }");
+    }
+    // Mirror vault-api's DisallowUnknownFields: a misspelled key (`a2a_tokens`)
+    // would otherwise be dropped and its axis sent as 0 — silently clearing a
+    // ceiling in force. Checked before the axes are read. A key present with an
+    // `undefined` value is refused too: the key itself is the mistake.
+    for (const k of Object.keys(c)) {
+        if (k !== "gpuUnits" && k !== "a2aTokens") {
+            throw invalidCeiling(`unknown field ${JSON.stringify(k)} (expected { gpuUnits?, a2aTokens? })`);
+        }
+    }
+    const axis = (name) => {
+        const v = c[name];
+        if (v === undefined)
+            return 0;
+        if (typeof v !== "number" || !Number.isFinite(v)) {
+            throw invalidCeiling(`${name} must be a finite number (got ${String(v)})`);
+        }
+        if (v < 0)
+            throw invalidCeiling(`${name} must be >= 0 (got ${v})`);
+        return v;
+    };
+    const gpuUnits = axis("gpuUnits");
+    const a2aTokens = axis("a2aTokens");
+    if (!Number.isInteger(a2aTokens)) {
+        throw invalidCeiling(`a2aTokens must be an integer (got ${a2aTokens})`);
+    }
+    // Above 2^53 the number no longer round-trips exactly through JSON (and
+    // above 2^63 the server fails to decode it into int64 at all).
+    if (a2aTokens > Number.MAX_SAFE_INTEGER) {
+        throw invalidCeiling(`a2aTokens must be <= Number.MAX_SAFE_INTEGER (got ${a2aTokens})`);
+    }
+    return { gpuUnits, a2aTokens };
+}
 //# sourceMappingURL=agents.js.map

package/dist/internal/agents.js.map

@@ -1 +1 @@
-{"version":3,"file":"agents.js","sourceRoot":"","sources":["../../src/internal/agents.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAKjD,MAAM,OAAO,MAAM;IACY;IAA7B,YAA6B,IAAqB;QAArB,SAAI,GAAJ,IAAI,CAAiB;IAAG,CAAC;IAEtD;;;;;;;OAOG;IACH,OAAO,CAAC,CAAS,EAAE,GAAwB;QACzC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,GAAyC,EAAE,CAAC,CAAC;IAC1G,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,CAAS,EAAE,OAA0B,EAAE;QAChD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAC9B,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAClE,OAAO,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;IACzB,CAAC;IACD,GAAG,CAAC,CAAS,EAAE,CAAS;QACtB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACtD,CAAC;IACD,MAAM,CAAC,CAAS,EAAE,CAAS,EAAE,QAAiC;QAC5D,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;IAChF,CAAC;IACD,UAAU,CAAC,CAAS,EAAE,CAAS;QAC7B,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACvE,CAAC;CACF"}
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../../src/internal/agents.ts"],"names":[],"mappings":"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"}

package/dist/internal/cubbies.d.ts

@@ -11,5 +11,38 @@ export declare class Cubbies {
      * for normal write flows.
      */
     exec(v: string, s: string, a: string, alias: string, sql: string, params?: unknown[]): Promise<CubbyExecResponse>;
+    /**
+     * Read a cubby the AGENT SERVICE owns, rather than one of its agents.
+     *
+     * One database per service, so what a coordinator writes its specialists can
+     * read without a copy. `as` is the service's public key — the half of an
+     * agent id before the colon.
+     */
+    serviceQuery<Row = unknown[]>(v: string, as: string, alias: string, sql: string, params?: unknown[]): Promise<CubbyQueryResponse<Row>>;
+    /** The write half of {@link serviceQuery}; needs a member-level grant. */
+    serviceExec(v: string, as: string, alias: string, sql: string, params?: unknown[]): Promise<CubbyExecResponse>;
+    /**
+     * Every cubby this service holds in (vault, scope).
+     *
+     * There is nothing else to ask: a service cubby has no declaration — an alias
+     * passing the shape rule is legal and the first write creates the file — so
+     * the registry IS the list.
+     */
+    serviceList(v: string, as: string): Promise<ServiceCubby[]>;
+    /** Create one with its schema. Member level, like exec. */
+    serviceProvision(v: string, as: string, alias: string, migrations: CubbyMigration[]): Promise<void>;
+    /** Remove one, and its file. Member level, like exec. */
+    serviceDelete(v: string, as: string, alias: string): Promise<void>;
+}
+/** One migration, as the platform applies them. */
+export interface CubbyMigration {
+    version: number;
+    up: string;
+}
+/** What the registry knows about one cubby of a service. */
+export interface ServiceCubby {
+    alias: string;
+    sizeBytes: number;
+    schemaVersion: number;
 }
 //# sourceMappingURL=cubbies.d.ts.map

package/dist/internal/cubbies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cubbies.d.ts","sourceRoot":"","sources":["../../src/internal/cubbies.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE9E,qBAAa,OAAO;IACN,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,eAAe;IAElD,KAAK,CAAC,GAAG,GAAG,OAAO,EAAE,EACnB,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAClF,OAAO,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAInC;;;;;OAKG;IACH,IAAI,CACF,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAClF,OAAO,CAAC,iBAAiB,CAAC;CAG9B"}
+{"version":3,"file":"cubbies.d.ts","sourceRoot":"","sources":["../../src/internal/cubbies.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE9E,qBAAa,OAAO;IACN,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,eAAe;IAElD,KAAK,CAAC,GAAG,GAAG,OAAO,EAAE,EACnB,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAClF,OAAO,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAInC;;;;;OAKG;IACH,IAAI,CACF,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAClF,OAAO,CAAC,iBAAiB,CAAC;IAI7B;;;;;;OAMG;IACH,YAAY,CAAC,GAAG,GAAG,OAAO,EAAE,EAC1B,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GACxE,OAAO,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAMnC,0EAA0E;IAC1E,WAAW,CACT,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GACxE,OAAO,CAAC,iBAAiB,CAAC;IAM7B;;;;;;OAMG;IACG,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAOjE,2DAA2D;IAC3D,gBAAgB,CACd,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,GACjE,OAAO,CAAC,IAAI,CAAC;IAMhB,yDAAyD;IACzD,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGnE;AAED,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,4DAA4D;AAC5D,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB"}

package/dist/internal/cubbies.js

@@ -16,5 +16,44 @@ export class Cubbies {
     exec(v, s, a, alias, sql, params = []) {
         return this.http.send("POST", endpoints.cubbyExec(v, s, a, alias), { body: { sql, params } });
     }
+    /**
+     * Read a cubby the AGENT SERVICE owns, rather than one of its agents.
+     *
+     * One database per service, so what a coordinator writes its specialists can
+     * read without a copy. `as` is the service's public key — the half of an
+     * agent id before the colon.
+     */
+    serviceQuery(v, as, alias, sql, params = []) {
+        return this.http.send("POST", endpoints.serviceCubbyQuery(v, as, alias), {
+            body: { sql, params },
+        });
+    }
+    /** The write half of {@link serviceQuery}; needs a member-level grant. */
+    serviceExec(v, as, alias, sql, params = []) {
+        return this.http.send("POST", endpoints.serviceCubbyExec(v, as, alias), {
+            body: { sql, params },
+        });
+    }
+    /**
+     * Every cubby this service holds in (vault, scope).
+     *
+     * There is nothing else to ask: a service cubby has no declaration — an alias
+     * passing the shape rule is legal and the first write creates the file — so
+     * the registry IS the list.
+     */
+    async serviceList(v, as) {
+        const body = await this.http.send("GET", endpoints.serviceCubbies(v, as));
+        return body?.data ?? [];
+    }
+    /** Create one with its schema. Member level, like exec. */
+    serviceProvision(v, as, alias, migrations) {
+        return this.http.send("POST", endpoints.serviceCubbyProvision(v, as, alias), {
+            body: { migrations },
+        });
+    }
+    /** Remove one, and its file. Member level, like exec. */
+    serviceDelete(v, as, alias) {
+        return this.http.send("DELETE", endpoints.serviceCubby(v, as, alias));
+    }
 }
 //# sourceMappingURL=cubbies.js.map

package/dist/internal/cubbies.js.map

@@ -1 +1 @@
-{"version":3,"file":"cubbies.js","sourceRoot":"","sources":["../../src/internal/cubbies.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGjD,MAAM,OAAO,OAAO;IACW;IAA7B,YAA6B,IAAqB;QAArB,SAAI,GAAJ,IAAI,CAAiB;IAAG,CAAC;IAEtD,KAAK,CACH,CAAS,EAAE,CAAS,EAAE,CAAS,EAAE,KAAa,EAAE,GAAW,EAAE,SAAoB,EAAE;QAEnF,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;IACjG,CAAC;IAED;;;;;OAKG;IACH,IAAI,CACF,CAAS,EAAE,CAAS,EAAE,CAAS,EAAE,KAAa,EAAE,GAAW,EAAE,SAAoB,EAAE;QAEnF,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;IAChG,CAAC;CACF"}
+{"version":3,"file":"cubbies.js","sourceRoot":"","sources":["../../src/internal/cubbies.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGjD,MAAM,OAAO,OAAO;IACW;IAA7B,YAA6B,IAAqB;QAArB,SAAI,GAAJ,IAAI,CAAiB;IAAG,CAAC;IAEtD,KAAK,CACH,CAAS,EAAE,CAAS,EAAE,CAAS,EAAE,KAAa,EAAE,GAAW,EAAE,SAAoB,EAAE;QAEnF,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;IACjG,CAAC;IAED;;;;;OAKG;IACH,IAAI,CACF,CAAS,EAAE,CAAS,EAAE,CAAS,EAAE,KAAa,EAAE,GAAW,EAAE,SAAoB,EAAE;QAEnF,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;IAChG,CAAC;IAED;;;;;;OAMG;IACH,YAAY,CACV,CAAS,EAAE,EAAU,EAAE,KAAa,EAAE,GAAW,EAAE,SAAoB,EAAE;QAEzE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,iBAAiB,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE;YACvE,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE;SACtB,CAAC,CAAC;IACL,CAAC;IAED,0EAA0E;IAC1E,WAAW,CACT,CAAS,EAAE,EAAU,EAAE,KAAa,EAAE,GAAW,EAAE,SAAoB,EAAE;QAEzE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,gBAAgB,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE;YACtE,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE;SACtB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,WAAW,CAAC,CAAS,EAAE,EAAU;QACrC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAC/B,KAAK,EAAE,SAAS,CAAC,cAAc,CAAC,CAAC,EAAE,EAAE,CAAC,CACvC,CAAC;QACF,OAAO,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC;IAC1B,CAAC;IAED,2DAA2D;IAC3D,gBAAgB,CACd,CAAS,EAAE,EAAU,EAAE,KAAa,EAAE,UAA4B;QAElE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,qBAAqB,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE;YAC3E,IAAI,EAAE,EAAE,UAAU,EAAE;SACrB,CAAC,CAAC;IACL,CAAC;IAED,yDAAyD;IACzD,aAAa,CAAC,CAAS,EAAE,EAAU,EAAE,KAAa;QAChD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;IACxE,CAAC;CACF"}

package/dist/internal/memory.d.ts

@@ -12,12 +12,42 @@ import type { VaultHttpClient } from "../core/http.js";
 export interface MemoryRows {
     columns: string[];
     rows: unknown[][];
+    /**
+     * The paged read tools (`record_search`, `record_list`) mint an opaque
+     * keyset cursor when a full page was returned and more rows exist; pass it
+     * back as the matching tool's `cursor` request param to fetch the next
+     * page. ABSENT on the last page (and on every unpaged tool) — the server
+     * marks it `omitempty`, so its absence means "no more rows". The one
+     * additive sibling key on an otherwise untouched `{ columns, rows }`
+     * envelope: the cursor rides beside the columns, never inside them.
+     */
+    cursor?: string;
 }
 /**
  * The memory bank's READ surface for browser clients (the memory-route UI).
  * One route, five tools: `POST /api/v1/vaults/:vaultId/memory/:tool` with
- * the Go json-tag body keys (`match`, `limit`, `id`, `type`, `privacy` —
- * all `omitempty`, so undefined fields are omitted from the body entirely).
+ * the Go json-tag body keys (`match`, `limit`, `id`, `type`, `privacy`,
+ * `scope`, `cursor`, `edge_type`, `direction`, `domain` — all `omitempty`, so
+ * undefined fields are omitted from the body entirely).
+ *
+ * `scope` narrows within the caller's grants (an ungranted scope yields an
+ * empty result, never an error); `cursor` pages the read tools (see
+ * `MemoryRows.cursor`). `domain` (on `search`, `list`, `countByType` — the
+ * three reads the server applies it to) narrows by the record's SUBJECT tag:
+ * `domain` is the record's subject tag (e.g. sales), NOT the vault scope —
+ * narrowing by it is not an access control; the UI labels it Topic. Two
+ * axes: `scope` is access, `domain` is subject.
+ *
+ * `record_neighbours` filters by `edge_type` and `direction`
+ * (`in`|`out`|`both`, relative to the anchor record — `out` is
+ * anchor → far; absent means `both`). The SDK sends the direction as-given:
+ * enum validation is the server's job, the TS type is the only client-side
+ * constraint.
+ *
+ * `record_search`'s projection is seven positional columns — `id, type,
+ * title, scope, privacy, rank, snippet` (the FTS5 `snippet` is appended
+ * after the six historical columns, aliased because the columns array goes
+ * out verbatim and the UI reads it by name).
  *
  * Writes are agent-side (`ctx.memory` in `@cef-ai/agent-sdk`) per the spec —
  * this class exposes no write methods on purpose.
@@ -26,23 +56,67 @@ export declare class Memory {
     private readonly http;
     private readonly vaultId;
     constructor(http: VaultHttpClient, vaultId: string);
-    /** Full-text search, optionally narrowed to a type and/or privacy class. */
+    /** Full-text search, optionally narrowed to a type, privacy class, and/or scope. */
     search(match: string, opts?: {
         limit?: number;
         type?: string;
         privacy?: string;
+        scope?: string;
+        cursor?: string;
+        /**
+         * The record's subject tag (e.g. `sales`, `hiring`, `engineering`) —
+         * wire `domain`, sent only when set. Narrows WITHIN the caller's
+         * grants; an absent domain adds no predicate.
+         *
+         * `domain` is the record's subject tag (e.g. sales), NOT the vault
+         * scope — narrowing by it is not an access control; the UI labels it
+         * Topic. (The product UI's "Domain" is the vault SCOPE, the access
+         * axis — that is `scope` here.)
+         */
+        domain?: string;
     }): Promise<MemoryRows>;
     /** Browse records newest-first, gated by the caller's grants and ceiling. */
     list(type?: string, opts?: {
         limit?: number;
+        scope?: string;
+        cursor?: string;
+        /**
+         * The record's subject tag (e.g. `sales`, `hiring`, `engineering`) —
+         * wire `domain`, sent only when set. Narrows WITHIN the caller's
+         * grants; an absent domain adds no predicate.
+         *
+         * `domain` is the record's subject tag (e.g. sales), NOT the vault
+         * scope — narrowing by it is not an access control; the UI labels it
+         * Topic. (The product UI's "Domain" is the vault SCOPE, the access
+         * axis — that is `scope` here.)
+         */
+        domain?: string;
     }): Promise<MemoryRows>;
     /** Fetch a single record by id. */
     get(id: string): Promise<MemoryRows>;
     /** Records connected to the given one by a relation. */
     neighbours(id: string, opts?: {
         limit?: number;
+        edgeType?: string;
+        direction?: "in" | "out" | "both";
+    }): Promise<MemoryRows>;
+    /**
+     * Row counts grouped by record type, optionally narrowed to one scope
+     * and/or one subject `domain`.
+     */
+    countByType(opts?: {
+        scope?: string;
+        /**
+         * The record's subject tag (e.g. `sales`, `hiring`, `engineering`) —
+         * wire `domain`, sent only when set. Narrows WITHIN the caller's
+         * grants; an absent domain adds no predicate.
+         *
+         * `domain` is the record's subject tag (e.g. sales), NOT the vault
+         * scope — narrowing by it is not an access control; the UI labels it
+         * Topic. (The product UI's "Domain" is the vault SCOPE, the access
+         * axis — that is `scope` here.)
+         */
+        domain?: string;
     }): Promise<MemoryRows>;
-    /** Row counts grouped by record type. */
-    countByType(): Promise<MemoryRows>;
 }
 //# sourceMappingURL=memory.d.ts.map

package/dist/internal/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/internal/memory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGvD;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,qBAAa,MAAM;IAEf,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM;IAGlC,4EAA4E;IAC5E,MAAM,CACJ,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GAC7D,OAAO,CAAC,UAAU,CAAC;IAMtB,6EAA6E;IAC7E,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAMvE,mCAAmC;IACnC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAMpC,wDAAwD;IACxD,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAQ1E,yCAAyC;IACzC,WAAW,IAAI,OAAO,CAAC,UAAU,CAAC;CAOnC"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/internal/memory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGvD;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC;IAClB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,MAAM;IAEf,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM;IAGlC,oFAAoF;IACpF,MAAM,CACJ,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;QACJ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB;;;;;;;;;WASG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC;KACZ,GACL,OAAO,CAAC,UAAU,CAAC;IActB,6EAA6E;IAC7E,IAAI,CACF,IAAI,CAAC,EAAE,MAAM,EACb,IAAI,GAAE;QACJ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB;;;;;;;;;WASG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC;KACZ,GACL,OAAO,CAAC,UAAU,CAAC;IAYtB,mCAAmC;IACnC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAMpC,wDAAwD;IACxD,UAAU,CACR,EAAE,EAAE,MAAM,EACV,IAAI,GAAE;QACJ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,MAAM,CAAC;KAC9B,GACL,OAAO,CAAC,UAAU,CAAC;IAetB;;;OAGG;IACH,WAAW,CACT,IAAI,GAAE;QACJ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf;;;;;;;;;WASG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC;KACZ,GACL,OAAO,CAAC,UAAU,CAAC;CAOvB"}

package/dist/internal/memory.js

@@ -2,8 +2,28 @@ import { endpoints } from "../core/endpoints.js";
 /**
  * The memory bank's READ surface for browser clients (the memory-route UI).
  * One route, five tools: `POST /api/v1/vaults/:vaultId/memory/:tool` with
- * the Go json-tag body keys (`match`, `limit`, `id`, `type`, `privacy` —
- * all `omitempty`, so undefined fields are omitted from the body entirely).
+ * the Go json-tag body keys (`match`, `limit`, `id`, `type`, `privacy`,
+ * `scope`, `cursor`, `edge_type`, `direction`, `domain` — all `omitempty`, so
+ * undefined fields are omitted from the body entirely).
+ *
+ * `scope` narrows within the caller's grants (an ungranted scope yields an
+ * empty result, never an error); `cursor` pages the read tools (see
+ * `MemoryRows.cursor`). `domain` (on `search`, `list`, `countByType` — the
+ * three reads the server applies it to) narrows by the record's SUBJECT tag:
+ * `domain` is the record's subject tag (e.g. sales), NOT the vault scope —
+ * narrowing by it is not an access control; the UI labels it Topic. Two
+ * axes: `scope` is access, `domain` is subject.
+ *
+ * `record_neighbours` filters by `edge_type` and `direction`
+ * (`in`|`out`|`both`, relative to the anchor record — `out` is
+ * anchor → far; absent means `both`). The SDK sends the direction as-given:
+ * enum validation is the server's job, the TS type is the only client-side
+ * constraint.
+ *
+ * `record_search`'s projection is seven positional columns — `id, type,
+ * title, scope, privacy, rank, snippet` (the FTS5 `snippet` is appended
+ * after the six historical columns, aliased because the columns array goes
+ * out verbatim and the UI reads it by name).
  *
  * Writes are agent-side (`ctx.memory` in `@cef-ai/agent-sdk`) per the spec —
  * this class exposes no write methods on purpose.
@@ -15,16 +35,30 @@ export class Memory {
         this.http = http;
         this.vaultId = vaultId;
     }
-    /** Full-text search, optionally narrowed to a type and/or privacy class. */
+    /** Full-text search, optionally narrowed to a type, privacy class, and/or scope. */
     search(match, opts = {}) {
         return this.http.send("POST", endpoints.memoryTool(this.vaultId, "record_search"), {
-            body: { match, limit: opts.limit, type: opts.type, privacy: opts.privacy },
+            body: {
+                match,
+                limit: opts.limit,
+                type: opts.type,
+                privacy: opts.privacy,
+                scope: opts.scope,
+                cursor: opts.cursor,
+                domain: opts.domain,
+            },
         });
     }
     /** Browse records newest-first, gated by the caller's grants and ceiling. */
     list(type, opts = {}) {
         return this.http.send("POST", endpoints.memoryTool(this.vaultId, "record_list"), {
-            body: { type, limit: opts.limit },
+            body: {
+                type,
+                limit: opts.limit,
+                scope: opts.scope,
+                cursor: opts.cursor,
+                domain: opts.domain,
+            },
         });
     }
     /** Fetch a single record by id. */
@@ -35,11 +69,21 @@ export class Memory {
     }
     /** Records connected to the given one by a relation. */
     neighbours(id, opts = {}) {
-        return this.http.send("POST", endpoints.memoryTool(this.vaultId, "record_neighbours"), { body: { id, limit: opts.limit } });
+        return this.http.send("POST", endpoints.memoryTool(this.vaultId, "record_neighbours"), {
+            body: {
+                id,
+                limit: opts.limit,
+                edge_type: opts.edgeType,
+                direction: opts.direction,
+            },
+        });
     }
-    /** Row counts grouped by record type. */
-    countByType() {
-        return this.http.send("POST", endpoints.memoryTool(this.vaultId, "record_count_by_type"), { body: {} });
+    /**
+     * Row counts grouped by record type, optionally narrowed to one scope
+     * and/or one subject `domain`.
+     */
+    countByType(opts = {}) {
+        return this.http.send("POST", endpoints.memoryTool(this.vaultId, "record_count_by_type"), { body: { scope: opts.scope, domain: opts.domain } });
     }
 }
 //# sourceMappingURL=memory.js.map

package/dist/internal/memory.js.map

@@ -1 +1 @@
-{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/internal/memory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAiBjD;;;;;;;;GAQG;AACH,MAAM,OAAO,MAAM;IAEE;IACA;IAFnB,YACmB,IAAqB,EACrB,OAAe;QADf,SAAI,GAAJ,IAAI,CAAiB;QACrB,YAAO,GAAP,OAAO,CAAQ;IAC/B,CAAC;IAEJ,4EAA4E;IAC5E,MAAM,CACJ,KAAa,EACb,OAA4D,EAAE;QAE9D,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE;YACjF,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE;SAC3E,CAAC,CAAC;IACL,CAAC;IAED,6EAA6E;IAC7E,IAAI,CAAC,IAAa,EAAE,OAA2B,EAAE;QAC/C,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,EAAE;YAC/E,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE;SAClC,CAAC,CAAC;IACL,CAAC;IAED,mCAAmC;IACnC,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE;YAC9E,IAAI,EAAE,EAAE,EAAE,EAAE;SACb,CAAC,CAAC;IACL,CAAC;IAED,wDAAwD;IACxD,UAAU,CAAC,EAAU,EAAE,OAA2B,EAAE;QAClD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CACnB,MAAM,EACN,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,mBAAmB,CAAC,EACvD,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,CACpC,CAAC;IACJ,CAAC;IAED,yCAAyC;IACzC,WAAW;QACT,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CACnB,MAAM,EACN,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,sBAAsB,CAAC,EAC1D,EAAE,IAAI,EAAE,EAAE,EAAE,CACb,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/internal/memory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AA2BjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,OAAO,MAAM;IAEE;IACA;IAFnB,YACmB,IAAqB,EACrB,OAAe;QADf,SAAI,GAAJ,IAAI,CAAiB;QACrB,YAAO,GAAP,OAAO,CAAQ;IAC/B,CAAC;IAEJ,oFAAoF;IACpF,MAAM,CACJ,KAAa,EACb,OAiBI,EAAE;QAEN,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE;YACjF,IAAI,EAAE;gBACJ,KAAK;gBACL,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,MAAM,EAAE,IAAI,CAAC,MAAM;aACpB;SACF,CAAC,CAAC;IACL,CAAC;IAED,6EAA6E;IAC7E,IAAI,CACF,IAAa,EACb,OAeI,EAAE;QAEN,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,EAAE;YAC/E,IAAI,EAAE;gBACJ,IAAI;gBACJ,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,MAAM,EAAE,IAAI,CAAC,MAAM;aACpB;SACF,CAAC,CAAC;IACL,CAAC;IAED,mCAAmC;IACnC,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE;YAC9E,IAAI,EAAE,EAAE,EAAE,EAAE;SACb,CAAC,CAAC;IACL,CAAC;IAED,wDAAwD;IACxD,UAAU,CACR,EAAU,EACV,OAII,EAAE;QAEN,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CACnB,MAAM,EACN,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,mBAAmB,CAAC,EACvD;YACE,IAAI,EAAE;gBACJ,EAAE;gBACF,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,SAAS,EAAE,IAAI,CAAC,QAAQ;gBACxB,SAAS,EAAE,IAAI,CAAC,SAAS;aAC1B;SACF,CACF,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,WAAW,CACT,OAaI,EAAE;QAEN,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CACnB,MAAM,EACN,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,sBAAsB,CAAC,EAC1D,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,CACrD,CAAC;IACJ,CAAC;CACF"}