@cef-ai/vault-sdk 4.4.0 → 5.2.0

package/dist/core/types.d.ts

@@ -35,15 +35,46 @@ export interface Scope {
     createdAt: string;
 }
 export type AgentConnectionStatus = "provisioning" | "active" | "revoking" | "revoked";
+/**
+ * Per-connection spend ceiling. The orchestrator refuses a new Task once the
+ * connection's cumulative spend on an axis reaches that axis's ceiling.
+ *
+ * The two axes are deliberately separate and never summed:
+ * - `gpuUnits` — compute units the platform itself METERED (a bill).
+ * - `a2aTokens` — tokens an external agent SELF-REPORTED over A2A (a stop
+ *   signal, not a bill; the platform cannot verify it). Always an integer.
+ *
+ * An absent axis, or `0`, means "no ceiling on that axis". vault-api omits the
+ * whole `ceiling` key from an {@link AgentConnection} when neither axis is set.
+ */
+export interface ConnectionCeiling {
+    /** Ceiling on platform-METERED compute units. Absent or 0 = no ceiling. */
+    gpuUnits?: number;
+    /** Ceiling on agent-SELF-REPORTED A2A tokens (integer). Absent or 0 = no ceiling. */
+    a2aTokens?: number;
+}
 export interface AgentConnection {
     vaultId: string;
     agentId: string;
     scope: string;
+    /**
+     * The full set of vault scopes this connection declared, when the server
+     * reports it. Optional and additive: an older vault-api that predates the
+     * scope set omits this field entirely, so callers must not assume it is
+     * present — fall back to the singular `scope` (always present) when it's
+     * absent.
+     */
+    scopes?: string[];
     version: string;
     asPubKey: string;
     cubbyAliases: string[];
     status: AgentConnectionStatus;
     manifest?: unknown;
+    /**
+     * Spend ceiling for this connection. Absent (the key is omitted by
+     * vault-api) = no ceiling on either axis. See {@link ConnectionCeiling}.
+     */
+    ceiling?: ConnectionCeiling;
     createdAt: string;
     updatedAt: string;
 }
@@ -182,17 +213,53 @@ export interface CubbyExecResponse {
     lastInsertId?: number | string;
     [key: string]: unknown;
 }
+/**
+ * Exactly one of `scope` (singular, pre-scope-set callers) or `scopes` (a
+ * set) may be supplied on a connect request/input — never both, never
+ * neither. The `?: never` on each arm's sibling turns "both" into a compile
+ * error for an object literal passed directly at the call site — a plain
+ * (non-exclusive) union of `{ scope: string }` and `{ scopes: string[] }`
+ * would NOT catch this: TypeScript's excess-property check only flags a
+ * property unknown to every constituent, and `scope`/`scopes` are each known
+ * to one constituent, so it would wave a literal naming both straight
+ * through. `?: never` on the sibling closes that gap. A value assembled
+ * dynamically (spread, external data, `any`) can still bypass this — see
+ * `resolveConnectScopes` in `./connect-scopes.js` for the runtime backstop.
+ */
+export type ScopeSelector = {
+    scope: string;
+    scopes?: never;
+} | {
+    scopes: string[];
+    scope?: never;
+};
 /**
  * Body of vault-api `POST /api/v1/vaults/:v/agents`. Card-only: the vault-api
  * re-fetches the manifest from the DDC registry itself and ignores any
  * client-sent `version`/`manifestCid`, so neither is sent.
+ *
+ * `scopes` carries a set of vault scopes for the connection; `scope` is the
+ * pre-existing singular form, kept for callers that predate the set. Send
+ * whichever field the caller supplied — the SDK must not derive one from the
+ * other here. See {@link ScopeSelector} for why exactly one is required.
  */
-export interface ConnectAgentRequest {
+export type ConnectAgentRequest = ScopeSelector & {
     agentId: string;
-    scope: string;
     settings?: Record<string, unknown>;
     agreementSignature?: string;
-}
+    /**
+     * Optional spend ceiling, written atomically with the connection row —
+     * same fields and semantics as the `PUT …/agents/:a/ceiling` body
+     * (`{ gpuUnits, a2aTokens }`, absent axis or `0` = no ceiling on that
+     * axis). Set it here to avoid a window where the connection exists with no
+     * ceiling; use `setCeiling` to change it later.
+     *
+     * Validated client-side exactly like `Agents.setCeiling` before any
+     * request is sent; when present, both axes go on the wire (an absent axis
+     * as `0`). Omitted from the body entirely when `undefined`.
+     */
+    ceiling?: ConnectionCeiling;
+};
 /**
  * ADR-002 object storage (company-memory-bank
  * 04-cef/user-vault/decisions/ADR-002-vault-object-storage.md).

package/dist/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/fluent/agent-connection.d.ts

@@ -1,6 +1,6 @@
 import type { VaultHttpClient } from "../core/http.js";
 import { type ListJobsOptions } from "../internal/browse.js";
-import type { AgentConnection, AgentConnectionStatus, JobsPage } from "../core/types.js";
+import type { AgentConnection, AgentConnectionStatus, ConnectionCeiling, JobsPage } from "../core/types.js";
 import { CubbyHandle } from "./cubby.js";
 export declare class AgentConnectionHandle implements AgentConnection {
     private readonly http;
@@ -8,11 +8,20 @@ export declare class AgentConnectionHandle implements AgentConnection {
     readonly vaultId: string;
     readonly agentId: string;
     readonly scope: string;
+    /**
+     * The full set of vault scopes this connection declared, when the server
+     * reports it. See {@link AgentConnection.scopes}. `this.scope` stays the
+     * single scope `cubby()` addresses — a cubby is keyed by one scope, and
+     * that remains correct even when the connection spans several.
+     */
+    readonly scopes?: string[];
     readonly version: string;
     readonly asPubKey: string;
     readonly cubbyAliases: string[];
     readonly status: AgentConnectionStatus;
     readonly manifest?: unknown;
+    /** Spend ceiling; absent = no ceiling on either axis. See {@link ConnectionCeiling}. */
+    readonly ceiling?: ConnectionCeiling;
     readonly createdAt: string;
     readonly updatedAt: string;
     private readonly api;
@@ -20,6 +29,12 @@ export declare class AgentConnectionHandle implements AgentConnection {
     constructor(http: VaultHttpClient, vaultIdRoot: string, record: AgentConnection);
     cubby(alias: string): CubbyHandle;
     update(settings: Record<string, unknown>): Promise<AgentConnectionHandle>;
+    /**
+     * Replace this connection's spend ceiling (`PUT …/ceiling`) and return a
+     * fresh handle. Absent axis = 0 = no ceiling; `{}` clears both. See
+     * `Agents.setCeiling` for validation.
+     */
+    setCeiling(ceiling: ConnectionCeiling): Promise<AgentConnectionHandle>;
     disconnect(): Promise<void>;
     jobs: {
         list: (o?: ListJobsOptions) => Promise<JobsPage>;

package/dist/fluent/agent-connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-connection.d.ts","sourceRoot":"","sources":["../../src/fluent/agent-connection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,EAAU,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,qBAAa,qBAAsB,YAAW,eAAe;IAgBzD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAhB9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAGb,IAAI,EAAE,eAAe,EACrB,WAAW,EAAE,MAAM,EACpC,MAAM,EAAE,eAAe;IAgBzB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW;IAS3B,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAK/E,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,IAAI;mBACQ,eAAe,KAAQ,OAAO,CAAC,QAAQ,CAAC;MAElD;CACH"}
+{"version":3,"file":"agent-connection.d.ts","sourceRoot":"","sources":["../../src/fluent/agent-connection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,EAAU,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5G,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,qBAAa,qBAAsB,YAAW,eAAe;IAyBzD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAzB9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,wFAAwF;IACxF,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAGb,IAAI,EAAE,eAAe,EACrB,WAAW,EAAE,MAAM,EACpC,MAAM,EAAE,eAAe;IAkBzB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW;IAS3B,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAK/E;;;;OAIG;IACG,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAK5E,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,IAAI;mBACQ,eAAe,KAAQ,OAAO,CAAC,QAAQ,CAAC;MAElD;CACH"}

package/dist/fluent/agent-connection.js

@@ -7,11 +7,20 @@ export class AgentConnectionHandle {
     vaultId;
     agentId;
     scope;
+    /**
+     * The full set of vault scopes this connection declared, when the server
+     * reports it. See {@link AgentConnection.scopes}. `this.scope` stays the
+     * single scope `cubby()` addresses — a cubby is keyed by one scope, and
+     * that remains correct even when the connection spans several.
+     */
+    scopes;
     version;
     asPubKey;
     cubbyAliases;
     status;
     manifest;
+    /** Spend ceiling; absent = no ceiling on either axis. See {@link ConnectionCeiling}. */
+    ceiling;
     createdAt;
     updatedAt;
     api;
@@ -22,11 +31,13 @@ export class AgentConnectionHandle {
         this.vaultId = record.vaultId;
         this.agentId = record.agentId;
         this.scope = record.scope;
+        this.scopes = record.scopes;
         this.version = record.version;
         this.asPubKey = record.asPubKey;
         this.cubbyAliases = record.cubbyAliases;
         this.status = record.status;
         this.manifest = record.manifest;
+        this.ceiling = record.ceiling;
         this.createdAt = record.createdAt;
         this.updatedAt = record.updatedAt;
         this.api = new Agents(http);
@@ -42,6 +53,15 @@ export class AgentConnectionHandle {
         const updated = await this.api.update(this.vaultIdRoot, this.agentId, settings);
         return new AgentConnectionHandle(this.http, this.vaultIdRoot, updated);
     }
+    /**
+     * Replace this connection's spend ceiling (`PUT …/ceiling`) and return a
+     * fresh handle. Absent axis = 0 = no ceiling; `{}` clears both. See
+     * `Agents.setCeiling` for validation.
+     */
+    async setCeiling(ceiling) {
+        const updated = await this.api.setCeiling(this.vaultIdRoot, this.agentId, ceiling);
+        return new AgentConnectionHandle(this.http, this.vaultIdRoot, updated);
+    }
     disconnect() {
         return this.api.disconnect(this.vaultIdRoot, this.agentId);
     }

package/dist/fluent/agent-connection.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-connection.js","sourceRoot":"","sources":["../../src/fluent/agent-connection.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAwB,MAAM,uBAAuB,CAAC;AAErE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,OAAO,qBAAqB;IAgBb;IACA;IAhBV,OAAO,CAAS;IAChB,OAAO,CAAS;IAChB,KAAK,CAAS;IACd,OAAO,CAAS;IAChB,QAAQ,CAAS;IACjB,YAAY,CAAW;IACvB,MAAM,CAAwB;IAC9B,QAAQ,CAAW;IACnB,SAAS,CAAS;IAClB,SAAS,CAAS;IAEV,GAAG,CAAS;IACZ,MAAM,CAAS;IAEhC,YACmB,IAAqB,EACrB,WAAmB,EACpC,MAAuB;QAFN,SAAI,GAAJ,IAAI,CAAiB;QACrB,gBAAW,GAAX,WAAW,CAAQ;QAGpC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC1B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QAClC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QAClC,IAAI,CAAC,GAAG,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,KAAa;QACjB,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CACb,SAAS,IAAI,CAAC,OAAO,kBAAkB,KAAK,wBAAwB,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,EAAE,CAC/G,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACvF,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,QAAiC;QAC5C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAChF,OAAO,IAAI,qBAAqB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACzE,CAAC;IAED,UAAU;QACR,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7D,CAAC;IAED,IAAI,GAAG;QACL,IAAI,EAAE,CAAC,IAAqB,EAAE,EAAqB,EAAE,CACnD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;KAC/D,CAAC;CACH"}
+{"version":3,"file":"agent-connection.js","sourceRoot":"","sources":["../../src/fluent/agent-connection.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAwB,MAAM,uBAAuB,CAAC;AAErE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,OAAO,qBAAqB;IAyBb;IACA;IAzBV,OAAO,CAAS;IAChB,OAAO,CAAS;IAChB,KAAK,CAAS;IACvB;;;;;OAKG;IACM,MAAM,CAAY;IAClB,OAAO,CAAS;IAChB,QAAQ,CAAS;IACjB,YAAY,CAAW;IACvB,MAAM,CAAwB;IAC9B,QAAQ,CAAW;IAC5B,wFAAwF;IAC/E,OAAO,CAAqB;IAC5B,SAAS,CAAS;IAClB,SAAS,CAAS;IAEV,GAAG,CAAS;IACZ,MAAM,CAAS;IAEhC,YACmB,IAAqB,EACrB,WAAmB,EACpC,MAAuB;QAFN,SAAI,GAAJ,IAAI,CAAiB;QACrB,gBAAW,GAAX,WAAW,CAAQ;QAGpC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QAClC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QAClC,IAAI,CAAC,GAAG,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,KAAa;QACjB,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CACb,SAAS,IAAI,CAAC,OAAO,kBAAkB,KAAK,wBAAwB,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,EAAE,CAC/G,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACvF,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,QAAiC;QAC5C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAChF,OAAO,IAAI,qBAAqB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACzE,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,UAAU,CAAC,OAA0B;QACzC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACnF,OAAO,IAAI,qBAAqB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACzE,CAAC;IAED,UAAU;QACR,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7D,CAAC;IAED,IAAI,GAAG;QACL,IAAI,EAAE,CAAC,IAAqB,EAAE,EAAqB,EAAE,CACnD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;KAC/D,CAAC;CACH"}

package/dist/fluent/service.d.ts

@@ -0,0 +1,34 @@
+import type { VaultHttpClient } from "../core/http.js";
+import type { CubbyQueryResponse, CubbyExecResponse } from "../core/types.js";
+import { type CubbyMigration, type ServiceCubby } from "../internal/cubbies.js";
+/**
+ * One agent service's cubbies, in one vault.
+ *
+ * NO SCOPE. A scope is a compartment of a vault, and a cubby addressed inside
+ * one forks the state of whatever owns it — a service connected to `eng` and to
+ * `sales` would have two databases under one alias, remembering different things
+ * depending on which one triggered it. A service's cubbies are global within the
+ * vault, which is why this hangs off the vault rather than off a scope.
+ *
+ * The four things a console does with them: see what exists, read one, write to
+ * one, and create or remove one. Reads need a reader grant; everything else
+ * needs member level, which is not a relaxation — a member can already bring a
+ * cubby into being by writing into an alias that does not exist yet, so gating
+ * the deliberate version harder would only push people to the path with no
+ * schema in it.
+ */
+export declare class ServiceHandle {
+    private readonly vaultId;
+    readonly asPubKey: string;
+    private readonly cubbies;
+    constructor(http: VaultHttpClient, vaultId: string, asPubKey: string);
+    /** Every cubby this service holds in this vault. The registry is the list. */
+    list(): Promise<ServiceCubby[]>;
+    cubby(alias: string): {
+        query<Row = unknown[]>(sql: string, params?: unknown[]): Promise<CubbyQueryResponse<Row>>;
+        exec(sql: string, params?: unknown[]): Promise<CubbyExecResponse>;
+        provision(migrations: CubbyMigration[]): Promise<void>;
+        delete(): Promise<void>;
+    };
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/fluent/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/fluent/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC9E,OAAO,EAAW,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEzF;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,aAAa;IAKtB,OAAO,CAAC,QAAQ,CAAC,OAAO;aACR,QAAQ,EAAE,MAAM;IALlC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;gBAGhC,IAAI,EAAE,eAAe,EACJ,OAAO,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM;IAKlC,8EAA8E;IAC9E,IAAI,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAI/B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG;QACpB,KAAK,CAAC,GAAG,GAAG,OAAO,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1F,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;QAClE,SAAS,CAAC,UAAU,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACvD,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;KACzB;CAYF"}

package/dist/fluent/service.js

@@ -0,0 +1,41 @@
+import { Cubbies } from "../internal/cubbies.js";
+/**
+ * One agent service's cubbies, in one vault.
+ *
+ * NO SCOPE. A scope is a compartment of a vault, and a cubby addressed inside
+ * one forks the state of whatever owns it — a service connected to `eng` and to
+ * `sales` would have two databases under one alias, remembering different things
+ * depending on which one triggered it. A service's cubbies are global within the
+ * vault, which is why this hangs off the vault rather than off a scope.
+ *
+ * The four things a console does with them: see what exists, read one, write to
+ * one, and create or remove one. Reads need a reader grant; everything else
+ * needs member level, which is not a relaxation — a member can already bring a
+ * cubby into being by writing into an alias that does not exist yet, so gating
+ * the deliberate version harder would only push people to the path with no
+ * schema in it.
+ */
+export class ServiceHandle {
+    vaultId;
+    asPubKey;
+    cubbies;
+    constructor(http, vaultId, asPubKey) {
+        this.vaultId = vaultId;
+        this.asPubKey = asPubKey;
+        this.cubbies = new Cubbies(http);
+    }
+    /** Every cubby this service holds in this vault. The registry is the list. */
+    list() {
+        return this.cubbies.serviceList(this.vaultId, this.asPubKey);
+    }
+    cubby(alias) {
+        const { vaultId, asPubKey, cubbies } = this;
+        return {
+            query: (sql, params = []) => cubbies.serviceQuery(vaultId, asPubKey, alias, sql, params),
+            exec: (sql, params = []) => cubbies.serviceExec(vaultId, asPubKey, alias, sql, params),
+            provision: (migrations) => cubbies.serviceProvision(vaultId, asPubKey, alias, migrations),
+            delete: () => cubbies.serviceDelete(vaultId, asPubKey, alias),
+        };
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/fluent/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/fluent/service.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAA0C,MAAM,wBAAwB,CAAC;AAEzF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,aAAa;IAKL;IACD;IALD,OAAO,CAAU;IAElC,YACE,IAAqB,EACJ,OAAe,EAChB,QAAgB;QADf,YAAO,GAAP,OAAO,CAAQ;QAChB,aAAQ,GAAR,QAAQ,CAAQ;QAEhC,IAAI,CAAC,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,8EAA8E;IAC9E,IAAI;QACF,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/D,CAAC;IAED,KAAK,CAAC,KAAa;QAMjB,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;QAC5C,OAAO;YACL,KAAK,EAAE,CAAkB,GAAW,EAAE,SAAoB,EAAE,EAAE,EAAE,CAC9D,OAAO,CAAC,YAAY,CAAM,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC;YAClE,IAAI,EAAE,CAAC,GAAW,EAAE,SAAoB,EAAE,EAAE,EAAE,CAC5C,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC;YAC5D,SAAS,EAAE,CAAC,UAA4B,EAAE,EAAE,CAC1C,OAAO,CAAC,gBAAgB,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC;YAChE,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC;SAC9D,CAAC;IACJ,CAAC;CACF"}

package/dist/fluent/vault.d.ts

@@ -1,8 +1,10 @@
 import type { VaultHttpClient } from "../core/http.js";
 import { type CreateScopeRequest, type UpdateScopeRequest } from "../internal/scopes.js";
 import { Memory } from "../internal/memory.js";
-import type { JobsPage, Scope, VaultCredentialStatus, VaultRecord } from "../core/types.js";
+import { Connections, type AgentAccess, type ConnectorDescriptor, type SetAgentAccessRequest } from "../internal/connectors.js";
+import type { ConnectionCeiling, JobsPage, Scope, ScopeSelector, VaultCredentialStatus, VaultRecord } from "../core/types.js";
 import { ScopeHandle } from "./scope.js";
+import { ServiceHandle } from "./service.js";
 import { AgentConnectionHandle } from "./agent-connection.js";
 import { JobHandle } from "./job.js";
 import type { Signer } from "@cef-ai/signer";
@@ -13,14 +15,16 @@ export interface VaultDeps {
     /** Signer — required for high-level `agents.connect`. */
     signer?: Signer;
 }
-/** Input for the high-level `vault.agents.connect` flow. */
-export interface ConnectAgentInput {
+/**
+ * Input for the high-level `vault.agents.connect` flow. Exactly one of
+ * `scope`/`scopes` is required — see {@link ScopeSelector}.
+ */
+export type ConnectAgentInput = ScopeSelector & {
     /**
      * Marketplace agent id, formatted `<agentServicePubkey>:<alias>`. The AS
      * pubkey is derived from the prefix unless `agentServicePubkey` is passed.
      */
     agentId: string;
-    scope: string;
     settings?: Record<string, unknown>;
     /**
      * Explicit agent-service pubkey. Overrides the value derived from the
@@ -28,7 +32,19 @@ export interface ConnectAgentInput {
      * `<pubkey>:<alias>` form.
      */
     agentServicePubkey?: string;
-}
+    /**
+     * Optional spend ceiling (`{ gpuUnits?, a2aTokens? }`, absent axis or `0` =
+     * no ceiling on that axis), written atomically with the connection row.
+     * Set it here to avoid a window where the connection exists with no
+     * ceiling; use `setCeiling` to change it later.
+     *
+     * Validated like `AgentConnectionHandle.setCeiling` BEFORE the GAR
+     * agreement is signed or any request is sent — an invalid ceiling rejects
+     * with `VaultRequestError(status 0, "BAD_REQUEST")` and costs no wallet
+     * ceremony.
+     */
+    ceiling?: ConnectionCeiling;
+};
 export declare class Vault {
     readonly id: string;
     readonly bucketId: string;
@@ -54,6 +70,13 @@ export declare class Vault {
      * agent-side (`ctx.memory` in `@cef-ai/agent-sdk`).
      */
     readonly memory: Memory;
+    /**
+     * This vault's connections: configured accounts of a connector (Slack,
+     * email, Telegram). Secrets go in on `create`/`update` and never come back
+     * out. An agent's access to one is under `vault.agents`.
+     */
+    readonly connections: Connections;
+    private readonly _access;
     private readonly _gar?;
     private readonly _signer?;
     private readonly _userPubKey;
@@ -66,21 +89,65 @@ export declare class Vault {
         delete: (n: string) => Promise<void>;
     };
     scope(name: string): ScopeHandle;
+    /**
+     * The cubbies an agent SERVICE owns in this vault.
+     *
+     * Off the VAULT, not off a scope. A scope is a compartment of a vault, and a
+     * cubby addressed inside one forks the state of whatever owns it — a service
+     * connected to two of them would remember different things depending on which
+     * one triggered it. A service's cubbies are global within the vault.
+     *
+     * `asPubKey` is the service's public key: the half of an agent id before the
+     * colon. It is named here rather than derived because the caller is a person
+     * or a console, not an agent — an agent reaches its own service through
+     * `ctx.cubby` and cannot name another.
+     */
+    service(asPubKey: string): ServiceHandle;
+    /** The connectors vault-api supports (Slack, email, Telegram): the public catalogue. */
+    connectors(): Promise<ConnectorDescriptor[]>;
     /** True when vault-api reports its S3 credential can no longer be refreshed. */
     isDisconnected(): boolean;
     agents: {
         /**
-         * Connect an agent. Builds and signs the GAR consent agreement
-         * internally, POSTs it to the configured GAR endpoint, then calls
-         * vault-api `POST /agents` with the resulting bare-hex signature.
+         * Connect an agent. Builds and signs ONE GAR consent agreement covering
+         * the whole requested scope set, POSTs it to the configured GAR
+         * endpoint, then calls vault-api `POST /agents` with the resulting
+         * bare-hex signature.
          *
          * Requires both `garEndpoint` and a `signer` on `VaultSDKConfig`.
          * For the low-level surface (pre-signed `agreementSignature`), use
          * `Agents.connect` from `@cef-ai/vault-sdk/internal`.
+         *
+         * Pass `ceiling` to set the connection's spend ceiling in the same
+         * atomic write as the connection row: set it here to avoid a window
+         * where the connection exists with no ceiling; use `setCeiling` to
+         * change it later. It is validated before anything is signed or sent.
+         *
+         * One agreement, not one per scope: the vault-api's connect precheck
+         * (`Agreement.CheckScopeGrant` in the vault repo) keys consent on
+         * (agent-service pubkey, user pubkey) only and explicitly discards the
+         * `scope` argument it's passed — `internal/compute/vault/agreement/
+         * client.go`'s signature names that parameter `_ /* scope *\/`, and its
+         * doc says plainly that GAR's scope list is "opaque" to the vault and
+         * that "scope membership is the user's call at consent time — encoded in
+         * the agreement they sign." Signing N agreements for the same (AS, user)
+         * pair would just answer that one cached check N times — no additional
+         * gate cleared — while costing N wallet ceremonies and N POSTs to the
+         * same GAR key. So `agreementSignature`'s single agreement carries
+         * `metadata.scopes` = the whole effective set, honestly recording what
+         * the user actually consented to.
          */
         connect: (input: ConnectAgentInput) => Promise<AgentConnectionHandle>;
         list: () => Promise<AgentConnectionHandle[]>;
         get: (a: string) => Promise<AgentConnectionHandle>;
+        /** The agent's access to this vault's connections. */
+        connections: (agentId: string) => Promise<AgentAccess[]>;
+        /**
+         * Sets what the agent may do with a connection, in the agent connection's
+         * own scope. Both lists empty deletes the access and resolves `undefined`.
+         */
+        setConnection: (agentId: string, connectionId: string, body: SetAgentAccessRequest) => Promise<AgentAccess | undefined>;
+        removeConnection: (agentId: string, connectionId: string) => Promise<void>;
     };
     jobs: {
         list: (o?: {

package/dist/fluent/vault.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../../src/fluent/vault.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../../src/fluent/vault.ts"],"names":[],"mappings":"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"}

package/dist/fluent/vault.js

@@ -1,8 +1,11 @@
 import { Scopes, } from "../internal/scopes.js";
-import { Agents } from "../internal/agents.js";
+import { Agents, validateCeiling } from "../internal/agents.js";
 import { Browse } from "../internal/browse.js";
 import { Memory } from "../internal/memory.js";
+import { AgentConnectionAccess, Connections, listConnectors, } from "../internal/connectors.js";
+import { resolveConnectScopes } from "../core/connect-scopes.js";
 import { ScopeHandle } from "./scope.js";
+import { ServiceHandle } from "./service.js";
 import { AgentConnectionHandle } from "./agent-connection.js";
 import { JobHandle } from "./job.js";
 import { signAndSubmitAgreement } from "../agreements/sign.js";
@@ -32,6 +35,13 @@ export class Vault {
      * agent-side (`ctx.memory` in `@cef-ai/agent-sdk`).
      */
     memory;
+    /**
+     * This vault's connections: configured accounts of a connector (Slack,
+     * email, Telegram). Secrets go in on `create`/`update` and never come back
+     * out. An agent's access to one is under `vault.agents`.
+     */
+    connections;
+    _access;
     _gar;
     _signer;
     _userPubKey;
@@ -49,6 +59,8 @@ export class Vault {
         this._agents = new Agents(http);
         this._browse = new Browse(http);
         this.memory = new Memory(this._http, this.id);
+        this.connections = new Connections(this._http, this.id);
+        this._access = new AgentConnectionAccess(this._http, this.id);
         this._gar = deps.gar;
         this._signer = deps.signer;
         // Prefer the live signer pubkey (the user's actual key) over whatever the
@@ -68,17 +80,57 @@ export class Vault {
     scope(name) {
         return new ScopeHandle(this._http, this.id, name);
     }
+    /**
+     * The cubbies an agent SERVICE owns in this vault.
+     *
+     * Off the VAULT, not off a scope. A scope is a compartment of a vault, and a
+     * cubby addressed inside one forks the state of whatever owns it — a service
+     * connected to two of them would remember different things depending on which
+     * one triggered it. A service's cubbies are global within the vault.
+     *
+     * `asPubKey` is the service's public key: the half of an agent id before the
+     * colon. It is named here rather than derived because the caller is a person
+     * or a console, not an agent — an agent reaches its own service through
+     * `ctx.cubby` and cannot name another.
+     */
+    service(asPubKey) {
+        return new ServiceHandle(this._http, this.id, asPubKey);
+    }
+    /** The connectors vault-api supports (Slack, email, Telegram): the public catalogue. */
+    connectors() {
+        return listConnectors(this._http);
+    }
     /** True when vault-api reports its S3 credential can no longer be refreshed. */
     isDisconnected() { return this.status === "disconnected"; }
     agents = {
         /**
-         * Connect an agent. Builds and signs the GAR consent agreement
-         * internally, POSTs it to the configured GAR endpoint, then calls
-         * vault-api `POST /agents` with the resulting bare-hex signature.
+         * Connect an agent. Builds and signs ONE GAR consent agreement covering
+         * the whole requested scope set, POSTs it to the configured GAR
+         * endpoint, then calls vault-api `POST /agents` with the resulting
+         * bare-hex signature.
          *
          * Requires both `garEndpoint` and a `signer` on `VaultSDKConfig`.
          * For the low-level surface (pre-signed `agreementSignature`), use
          * `Agents.connect` from `@cef-ai/vault-sdk/internal`.
+         *
+         * Pass `ceiling` to set the connection's spend ceiling in the same
+         * atomic write as the connection row: set it here to avoid a window
+         * where the connection exists with no ceiling; use `setCeiling` to
+         * change it later. It is validated before anything is signed or sent.
+         *
+         * One agreement, not one per scope: the vault-api's connect precheck
+         * (`Agreement.CheckScopeGrant` in the vault repo) keys consent on
+         * (agent-service pubkey, user pubkey) only and explicitly discards the
+         * `scope` argument it's passed — `internal/compute/vault/agreement/
+         * client.go`'s signature names that parameter `_ /* scope *\/`, and its
+         * doc says plainly that GAR's scope list is "opaque" to the vault and
+         * that "scope membership is the user's call at consent time — encoded in
+         * the agreement they sign." Signing N agreements for the same (AS, user)
+         * pair would just answer that one cached check N times — no additional
+         * gate cleared — while costing N wallet ceremonies and N POSTs to the
+         * same GAR key. So `agreementSignature`'s single agreement carries
+         * `metadata.scopes` = the whole effective set, honestly recording what
+         * the user actually consented to.
          */
         connect: async (input) => {
             if (!this._gar) {
@@ -98,18 +150,34 @@ export class Vault {
                     `'${input.agentId}' (expected '<pubkey>:<alias>'); pass ` +
                     `agentServicePubkey explicitly`);
             }
+            // Effective scope set, resolved once — also the runtime backstop for
+            // a dynamically-built `input` naming both `scope` and `scopes` (or
+            // neither), bypassing ScopeSelector's compile-time guarantee for an
+            // object literal. Used only to decide what the single GAR agreement's
+            // `metadata.scopes` contains; the wire body below still sends exactly
+            // whichever field the caller supplied, untouched.
+            const effectiveScopes = resolveConnectScopes(input, "vault.agents.connect");
+            // Validate the ceiling before the wallet ceremony and the GAR POST:
+            // a bad ceiling must not cost a signature (Agents.connect re-validates
+            // the same value — it is the low-level surface's own guard).
+            if (input.ceiling !== undefined)
+                validateCeiling(input.ceiling);
             const { agreementSignature } = await signAndSubmitAgreement({
                 signer: this._signer,
                 vault: { id: this.id, userPubKey: this._userPubKey },
                 agent: { agentId: input.agentId, agentServicePubkey },
-                scope: input.scope,
+                scopes: effectiveScopes,
                 gar: this._gar,
             });
+            const scopeFields = input.scope !== undefined
+                ? { scope: input.scope }
+                : { scopes: input.scopes };
             const req = {
                 agentId: input.agentId,
-                scope: input.scope,
+                ...scopeFields,
                 settings: input.settings ?? {},
                 agreementSignature,
+                ...(input.ceiling !== undefined ? { ceiling: input.ceiling } : {}),
             };
             const conn = await this._agents.connect(this.id, req);
             return new AgentConnectionHandle(this._http, this.id, conn);
@@ -122,6 +190,14 @@ export class Vault {
             const conn = await this._agents.get(this.id, a);
             return new AgentConnectionHandle(this._http, this.id, conn);
         },
+        /** The agent's access to this vault's connections. */
+        connections: (agentId) => this._access.list(agentId),
+        /**
+         * Sets what the agent may do with a connection, in the agent connection's
+         * own scope. Both lists empty deletes the access and resolves `undefined`.
+         */
+        setConnection: (agentId, connectionId, body) => this._access.set(agentId, connectionId, body),
+        removeConnection: (agentId, connectionId) => this._access.remove(agentId, connectionId),
     };
     jobs = {
         list: (o = {}) => this._browse.listJobs(this.id, o),