@cef-ai/vault-sdk 0.1.0 → 0.2.0

package/README.md

@@ -11,29 +11,89 @@ pnpm add @cef-ai/vault-sdk
 
 ## Quickstart
 
+Browser app driving onboarding through an embed-wallet:
+
 ```ts
-import { VaultSDK, CereWallet } from "@cef-ai/vault-sdk";
+import { VaultSDK, type EnsureProgressEvent } from "@cef-ai/vault-sdk";
 
-const wallet = await CereWallet.fromMnemonic(process.env.WALLET_MNEMONIC!);
 const sdk = new VaultSDK({
   endpoint: "https://vault.cere.io",
-  garEndpoint: "https://gar.cere.io", // required for vault.agents.connect
-  wallet,
+  garEndpoint: "https://gar.cere.io",
+  rpcEndpoint: "wss://rpc.devnet.cere.network/ws",
+  s3GatewayAuthInfoUrl: "https://ddc-s3-gateway.compute.dev.ddcdragon.com/auth/info",
+  wallet: myWallet,                          // any `Wallet` adapter
+  embedWalletForOnboarding: myEmbedWallet,   // optional; chain-side autoAddProxy
+});
+
+const vault = await sdk.vault.ensure({
+  onProgress: (e: EnsureProgressEvent) => console.log(e.kind),
 });
-const vault = await sdk.vault.ensure({ delegationToken });
 
 await vault.scope("default").publish({
   type: "user_message",
   context: "conv-42",
   payload: { text: "Hi" },
 });
+```
 
-const sub = vault.scope("default").subscribe(
-  { context: "conv-42", types: ["assistant_message"] },
-  (event) => console.log(event.payload),
-);
+Server-side (pre-provisioned wallet, skip onboarding):
+
+```ts
+import { VaultSDK, CereWallet } from "@cef-ai/vault-sdk";
+
+const wallet = await CereWallet.fromMnemonic(process.env.WALLET_MNEMONIC!);
+const sdk = new VaultSDK({
+  endpoint: "https://vault.cere.io",
+  garEndpoint: "https://gar.cere.io",
+  s3GatewayAuthInfoUrl: "https://ddc-s3-gateway.compute.dev.ddcdragon.com/auth/info",
+  wallet,
+});
+const vault = await sdk.vault.ensure({ onboard: false });
 ```
 
+## Onboarding
+
+`vault.ensure()` runs the DDC onboarding pipeline by default. It probes the
+gateway, optionally bootstraps a devnet wallet, submits the on-chain
+`proxy.addProxy` extrinsic, and polls until the gateway sees the proxy.
+Internally:
+
+1. **Status check** — `GET /auth/onboarding/status` (404 means prod, skip).
+2. **Bootstrap (devnet only)** — if `faucet_eligible` or `ddc_seed_eligible`,
+   `POST /auth/onboarding/bootstrap` to drip CERE and seed the DDC deposit.
+3. **autoAddProxy** — when the wallet is not yet a registered gateway proxy,
+   submit `proxy.addProxy(<gateway>, NonTransfer, 0)` via the configured
+   `embedWalletForOnboarding`.
+4. **Poll-until-ready** — re-fetch status until `gateway_is_proxy === true`
+   or the time budget is exhausted (defaults: 2 s interval / 60 s budget).
+
+`onProgress` receives an `EnsureProgressEvent` for each stage:
+
+| Kind | Meaning |
+| --- | --- |
+| `inspecting-wallet` | Gateway status probe is in flight. |
+| `funding-wallet` | Devnet auto-fund (CERE drip + DDC seed deposit); never fires on prod. |
+| `gateway-authorization-required` | Onboarding required; carries `status: OnboardingStatus`. |
+| `authorizing-gateway` | Wallet popup is open for the `addProxy` signature. |
+| `authorization-submitted` | Extrinsic accepted into the mempool; carries `txHash`. |
+| `awaiting-chain-confirmation` | Polling the gateway until it sees the proxy. |
+| `gateway-authorized` | Gateway confirmed the proxy on-chain. |
+| `signing-delegation` | Building the DDC delegation token from the wallet. |
+| `provisioning-vault` | Calling `POST /api/v1/vaults` to claim the record. |
+
+Two errors can surface:
+
+- `OnboardingTimeoutError` — the proxy poll exhausted its budget. The
+  extrinsic may still confirm later; calling `ensure()` again is safe.
+- `OnboardingRequiredError` — `ensure({ onboard: false })` was passed but
+  the gateway reports the wallet still needs the proxy step. Server flows
+  catch this to fail fast.
+
+`@cere-ddc-sdk/blockchain` (used by `autoAddProxy`) and
+`@cere-ddc-sdk/ddc-client` (used to build the delegation token internally)
+are declared as `optionalDependencies`. Apps that exercise the onboarding
+or internal-token-build paths must install them as direct dependencies.
+
 ## Connecting an agent
 
 `vault.agents.connect({ manifest, scope, settings })` is the high-level entry
@@ -58,28 +118,34 @@ already have a pre-signed `agreementSignature` (e.g. from a custodial flow),
 drop down to the low-level `Agents.connect(vaultId, ConnectAgentRequest)`
 exported from `@cef-ai/vault-sdk/internal`.
 
-For delegation-token construction (`vault.ensure({ delegationToken })`),
-see `examples/vault-chat/utils/vault-token.ts` — the SDK accepts the token
-as opaque to avoid a runtime dep on `@cere-ddc-sdk/ddc-client`.
-
 ## Surface
 
 | Method | Maps to |
 | --- | --- |
-| `sdk.vault.ensure()` / `.current()` / `.rotateCredentials()` | `POST` / `GET` / `PUT /api/v1/vaults[/credentials]` |
+| `sdk.vault.ensure({ onboard?, onProgress?, delegationToken? })` | runs the onboarding pipeline + `POST /api/v1/vaults` |
+| `sdk.vault.current()` / `.rotateCredentials()` | `GET` / `PUT /api/v1/vaults[/credentials]` |
 | `vault.scopes.{list,get,create,update,delete}` | `/api/v1/vaults/:v/scopes` |
 | `vault.agents.connect({ manifest, scope, settings })` (signs GAR internally) | `POST {garEndpoint}/api/v1/agreements` + `POST /api/v1/vaults/:v/agents` |
 | `vault.agents.{list,get}` → `AgentConnectionHandle` | `/api/v1/vaults/:v/agents` |
 | `handle.update(settings)` / `handle.disconnect()` | `PATCH` / `DELETE` |
 | `handle.cubby(alias).query(...)` / `.exec(...)` | `/scopes/:s/cubbies/:alias/{query,exec}` |
-| `handle.jobs.list()` | `/agents/:a/jobs` |
+| `handle.jobs.list({ state?, cursor?, limit? })` | `/agents/:a/jobs` |
 | `vault.scope(s).publish(input)` | `POST /scopes/:s/events` |
-| `vault.scope(s).subscribe(filter, handler)` | poll-backed long-poll over `/streams/:c/events` |
+| `vault.scope(s).subscribe(filter, handler, opts?)` | poll-backed long-poll over `/streams/:c/events` |
+| `vault.scope(s).subscribeAll(filter, handler, { refreshIntervalMs? })` | fans out across `streams.list()`; refreshes every 30 s by default |
 | `vault.scope(s).streams.list()` / `.get(c)` / `.stream(c).events.list()` | `/scopes/:s/streams[/:c[/events]]` |
-| `vault.jobs.list()` / `.get(id).activities.list()` | `/jobs[/...]` |
-| `sdk.marketplace.getAgent(id, version?)` | public `GET /api/v1/marketplace/agents/...` |
+| `vault.jobs.list({ state? })` / `.get(jobId).activities.list()` | `/jobs[/...]` |
+| `handle.jobs.get(jobId).activities.subscribe({ since? }, handler)` | poll-backed activity tail with seen-id dedupe |
+| `sdk.marketplace.getAgent(id, version?)` | public `GET /api/v1/marketplace/agents/:id[/versions/:v]` |
+| `sdk.marketplace.list({ limit?, cursor?, query? })` | public `GET /api/v1/marketplace/agents` |
 | `sdk.health.live()` / `.ready()` | public `GET /health` / `/ready` |
 
+`Scope.metadata: Record<string, unknown>` is a free-form, server-stored map.
+`vault.scopes.update(name, { metadata })` is a partial patch — server
+semantics are shallow-merge per top-level key (keys in the patch overwrite,
+others are preserved). The SDK whitelists the request body so only the keys
+you supply reach the wire.
+
 ## Pluggable auth
 
 `VaultSDK` accepts either a `wallet` (default → `WalletAuthProvider`) or a
@@ -100,6 +166,11 @@ The `Wallet` interface is `{ pubkey(), sign(bytes), sigType?() }`.
 - `CereWallet.fromMnemonic(mnemonic, type?)` — wraps `UriSigner`.
 - `CereWallet.fromKeystore(json, passphrase, type?)` — Cere/Polkadot JSON keystore.
 
+Browser apps using `@cere/embed-wallet` should write a thin adapter
+implementing the 3-method `Wallet` interface against the embed-wallet's
+signer surface; the chat-app pattern at `cef-chat/src/lib/wallet/embed-adapter.ts`
+is a working reference.
+
 The `UriSigner` / `JsonSigner` classes powering `CereWallet` are vendored
 from [`@cere-activity-sdk/signers`](https://github.com/cere-io/cere-activity-sdk/tree/main/packages/signers)
 (Apache-2.0); see `src/wallet/cere-internal/README.md` for attribution and
@@ -113,8 +184,13 @@ Browser-extension and CereWalletNative adapters live in their own packages.
 
 `@cef-ai/vault-sdk/internal` re-exports `Vaults`, `Scopes`, `Agents`,
 `Events`, `Browse`, `Cubbies`, `Health`, `Marketplace`, plus
-`VaultHttpClient` and `endpoints`. Use it only when the fluent surface
-isn't enough.
+`VaultHttpClient` and `endpoints`.
+
+Onboarding primitives (`runOnboarding`, `pollUntilProxyReady`,
+`getOnboardingStatus`, `runBootstrap`, `walletToOnboardingSigner`),
+`autoAddProxy`, and `getGatewayInfo` live under their respective files in
+`src/internal/` for advanced consumers that need to drive the pipeline
+piecewise. Use them only when the fluent surface isn't enough.
 
 ## Spec
 

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import { Marketplace } from "./internal/marketplace.js";
 import { Health } from "./internal/health.js";
 import { Vault } from "./fluent/vault.js";
+import { type OnboardingStatus } from "./internal/onboarding.js";
 import type { AuthProvider } from "./auth/provider.js";
 import type { Wallet } from "./wallet/adapter.js";
 export interface VaultSDKConfig {
@@ -23,23 +24,116 @@ export interface VaultSDKConfig {
     auth?: AuthProvider;
     fetch?: typeof fetch;
     timeoutMs?: number;
+    /**
+     * S3 Gateway ed25519 pubkey (`0x`-hex or bare hex). When set, the SDK can
+     * build a delegation token internally on `vault.ensure()` if none is passed.
+     * Skip the round-trip when you know the gateway identity ahead of time.
+     */
+    s3GatewayPubkey?: string;
+    /**
+     * Fallback URL used to fetch the gateway pubkey when `s3GatewayPubkey` is
+     * not set. Defaults to the dev gateway. Override for prod.
+     */
+    s3GatewayAuthInfoUrl?: string;
+    /**
+     * Cere chain WebSocket RPC endpoint. Used by the onboarding pipeline when
+     * the wallet has not yet registered the gateway as an on-chain proxy and
+     * `vault.ensure()` needs to submit `proxy.addProxy` on the user's behalf.
+     * Defaults to the Cere devnet RPC.
+     */
+    rpcEndpoint?: string;
+    /**
+     * Cere embed-wallet instance (NOT the SDK `Wallet` adapter) used by the
+     * onboarding pipeline when it must submit an extrinsic via
+     * `@cere-ddc-sdk/blockchain`'s `CereWalletSigner`. Carries the
+     * Polkadot-extension-style API the chain client needs — a level lower
+     * than the pure signing surface our `Wallet` adapter exposes. Required
+     * only when `vault.ensure()` discovers onboarding-needed; can be omitted
+     * if `ensure({ onboard: false })` is used or the wallet is already a
+     * registered proxy.
+     */
+    embedWalletForOnboarding?: unknown;
 }
 export interface EnsureVaultOptions {
     name?: string;
-    /** DDC delegation token issued during onboarding. Opaque base58 string. */
-    delegationToken: string;
+    /**
+     * Pre-built DDC delegation token. Optional: if omitted, the SDK builds one
+     * internally using the configured `wallet` and either `s3GatewayPubkey`
+     * (static) or `s3GatewayAuthInfoUrl` (fetched). Building requires the
+     * optional dep `@cere-ddc-sdk/ddc-client` to be installed.
+     */
+    delegationToken?: string;
+    /**
+     * Run the DDC onboarding pipeline (status / bootstrap / addProxy / poll)
+     * before claiming the vault. Defaults to `true`. Set `false` for server
+     * flows that assume pre-provisioned wallets — in that case, an
+     * `OnboardingRequiredError` is raised if the gateway later reports the
+     * wallet still needs the proxy registration step.
+     */
+    onboard?: boolean;
+    /** Progress hook for UIs that want to drive a stepper / spinner. */
+    onProgress?: (e: EnsureProgressEvent) => void;
+    /** Poll cadence while waiting for the gateway to see the new proxy. */
+    proxyPollIntervalMs?: number;
+    /** Total time budget for the proxy-confirmation poll. */
+    proxyPollTimeoutMs?: number;
 }
+/**
+ * Progress signal emitted by `vault.ensure()` so UIs can render a
+ * stepper without polling internal state. The order is roughly the
+ * order of emission, but `gateway-authorization-required` and friends
+ * only fire on the onboarding-required path.
+ */
+export type EnsureProgressEvent = {
+    kind: "inspecting-wallet";
+} | {
+    kind: "funding-wallet";
+} | {
+    kind: "gateway-authorization-required";
+    status: OnboardingStatus;
+} | {
+    kind: "authorizing-gateway";
+} | {
+    kind: "authorization-submitted";
+    txHash: string;
+} | {
+    kind: "awaiting-chain-confirmation";
+} | {
+    kind: "gateway-authorized";
+} | {
+    kind: "signing-delegation";
+} | {
+    kind: "provisioning-vault";
+};
 export declare class VaultSDK {
     private readonly http;
     private readonly marketplaceHttp;
     private readonly vaults;
     private readonly gar?;
     private readonly wallet?;
+    private readonly s3GatewayPubkey?;
+    private readonly s3GatewayAuthInfoUrl;
+    private readonly rpcEndpoint;
+    private readonly embedWalletForOnboarding?;
+    private readonly fetchFn;
+    private cachedGatewayPubkey?;
     readonly marketplace: Marketplace;
     readonly health: Health;
     constructor(config: VaultSDKConfig);
+    /**
+     * Resolves the gateway pubkey: prefers the static config, falls back to
+     * `/auth/info` (cached for the SDK's lifetime).
+     */
+    private resolveGatewayPubkey;
+    /**
+     * Strip `/auth/info` (and any trailing slash) off the configured auth-info
+     * URL to reach the gateway base — the prefix the onboarding endpoints sit
+     * under. Belongs here, not in onboarding.ts, because the strip is purely
+     * a config-shape concern.
+     */
+    private gatewayBaseUrl;
     vault: {
-        ensure: (opts: EnsureVaultOptions) => Promise<Vault>;
+        ensure: (opts?: EnsureVaultOptions) => Promise<Vault>;
         current: () => Promise<Vault>;
         /** Rotate the SigV4 delegation credential. */
         rotateCredentials: (vaultId: string, delegationToken: string) => Promise<Vault>;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAG1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAGlD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAY;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,cAAc;IA8BlC,KAAK;uBACkB,kBAAkB,KAAG,OAAO,CAAC,KAAK,CAAC;uBAOrC,OAAO,CAAC,KAAK,CAAC;QAIjC,8CAA8C;qCAEnC,MAAM,mBACE,MAAM,KACtB,OAAO,CAAC,KAAK,CAAC;MAMjB;CACH"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -6,12 +6,23 @@ import { Health } from "./internal/health.js";
 import { Vault } from "./fluent/vault.js";
 import { WalletAuthProvider } from "./auth/wallet.js";
 import { GarClient } from "./agreements/gar-client.js";
+import { buildVaultDelegationToken, fetchGatewayPubkey, } from "./internal/delegation-token.js";
+import { OnboardingRequiredError, OnboardingTimeoutError, pollUntilProxyReady, runOnboarding, walletToOnboardingSigner, } from "./internal/onboarding.js";
+import { autoAddProxy } from "./internal/auto-add-proxy.js";
+const DEFAULT_S3_GATEWAY_AUTH_INFO_URL = "https://ddc-s3-gateway.compute.dev.ddcdragon.com/auth/info";
+const DEFAULT_RPC_ENDPOINT = "wss://rpc.devnet.cere.network/ws";
 export class VaultSDK {
     http;
     marketplaceHttp;
     vaults;
     gar;
     wallet;
+    s3GatewayPubkey;
+    s3GatewayAuthInfoUrl;
+    rpcEndpoint;
+    embedWalletForOnboarding;
+    fetchFn;
+    cachedGatewayPubkey;
     marketplace;
     health;
     constructor(config) {
@@ -36,15 +47,102 @@ export class VaultSDK {
             }));
         }
         this.wallet = config.wallet;
+        this.s3GatewayPubkey = config.s3GatewayPubkey;
+        this.s3GatewayAuthInfoUrl =
+            config.s3GatewayAuthInfoUrl ?? DEFAULT_S3_GATEWAY_AUTH_INFO_URL;
+        this.rpcEndpoint = config.rpcEndpoint ?? DEFAULT_RPC_ENDPOINT;
+        this.embedWalletForOnboarding = config.embedWalletForOnboarding;
+        this.fetchFn = config.fetch ?? fetch.bind(globalThis);
         this.vaults = new Vaults(this.http);
         this.marketplace = new Marketplace(this.marketplaceHttp);
         this.health = new Health(this.http);
     }
+    /**
+     * Resolves the gateway pubkey: prefers the static config, falls back to
+     * `/auth/info` (cached for the SDK's lifetime).
+     */
+    async resolveGatewayPubkey() {
+        if (this.s3GatewayPubkey)
+            return this.s3GatewayPubkey;
+        if (this.cachedGatewayPubkey)
+            return this.cachedGatewayPubkey;
+        const pk = await fetchGatewayPubkey(this.s3GatewayAuthInfoUrl, this.fetchFn);
+        this.cachedGatewayPubkey = pk;
+        return pk;
+    }
+    /**
+     * Strip `/auth/info` (and any trailing slash) off the configured auth-info
+     * URL to reach the gateway base — the prefix the onboarding endpoints sit
+     * under. Belongs here, not in onboarding.ts, because the strip is purely
+     * a config-shape concern.
+     */
+    gatewayBaseUrl() {
+        return this.s3GatewayAuthInfoUrl
+            .replace(/\/auth\/info\/?$/, "")
+            .replace(/\/+$/, "");
+    }
     vault = {
-        ensure: async (opts) => {
+        ensure: async (opts = {}) => {
+            const onProgress = opts.onProgress ?? (() => { });
+            const wantOnboard = opts.onboard !== false;
+            // Onboarding pipeline. Only runs when (a) the consumer hasn't opted
+            // out, and (b) we have a wallet to drive the gateway interactions.
+            // The wallet-less path skips silently — server-side flows that pass
+            // a pre-built `delegationToken` shouldn't touch the chain.
+            if (wantOnboard && this.wallet) {
+                const signer = walletToOnboardingSigner(this.wallet);
+                const gw = this.gatewayBaseUrl();
+                onProgress({ kind: "inspecting-wallet" });
+                const onb = await runOnboarding(gw, signer, this.fetchFn, () => {
+                    onProgress({ kind: "funding-wallet" });
+                });
+                if (onb.kind === "awaiting-proxy") {
+                    if (!this.embedWalletForOnboarding) {
+                        throw new OnboardingRequiredError("Onboarding required but no embed-wallet was provided to VaultSDK config. "
+                            + "Pass `embedWalletForOnboarding` or call ensure({ onboard: false }) and "
+                            + "run onboarding externally.");
+                    }
+                    onProgress({ kind: "gateway-authorization-required", status: onb.status });
+                    const gatewayPubkey = await this.resolveGatewayPubkey();
+                    onProgress({ kind: "authorizing-gateway" });
+                    const { txHash } = await autoAddProxy({
+                        rpcEndpoint: this.rpcEndpoint,
+                        gatewayPubKeyHex: gatewayPubkey,
+                        embedWallet: this.embedWalletForOnboarding,
+                    });
+                    onProgress({ kind: "authorization-submitted", txHash });
+                    onProgress({ kind: "awaiting-chain-confirmation" });
+                    const ready = await pollUntilProxyReady(gw, signer, {
+                        intervalMs: opts.proxyPollIntervalMs ?? 2000,
+                        timeoutMs: opts.proxyPollTimeoutMs ?? 60_000,
+                        fetchImpl: this.fetchFn,
+                    });
+                    if (!ready) {
+                        throw new OnboardingTimeoutError("Gateway did not see the on-chain proxy within the timeout window. "
+                            + "The transaction may still confirm later — try ensure() again.");
+                    }
+                    onProgress({ kind: "gateway-authorized" });
+                }
+                // 'skipped' (production gateway 404'd) and 'ready' both fall
+                // through silently to the existing claim path.
+            }
+            let delegationToken = opts.delegationToken;
+            if (!delegationToken) {
+                if (!this.wallet) {
+                    throw new Error("vault.ensure() needs either a `delegationToken` or a `wallet` "
+                        + "configured on VaultSDKConfig to build one internally.");
+                }
+                onProgress({ kind: "signing-delegation" });
+                const gatewayPubkey = await this.resolveGatewayPubkey();
+                delegationToken = await buildVaultDelegationToken({
+                    wallet: this.wallet,
+                    gatewayPubkey,
+                });
+            }
+            onProgress({ kind: "provisioning-vault" });
             const rec = await this.vaults.claim({
                 name: opts.name,
-                delegation_token: opts.delegationToken,
+                delegation_token: delegationToken,
             });
             return new Vault(this.http, rec, { gar: this.gar, wallet: this.wallet });
         },

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,gBAAgB;AAChB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACvD,OAAO,EACL,yBAAyB,EACzB,kBAAkB,GACnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EACb,wBAAwB,GAEzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAK5D,MAAM,gCAAgC,GACpC,4DAA4D,CAAC;AAE/D,MAAM,oBAAoB,GAAG,kCAAkC,CAAC;AA+FhE,MAAM,OAAO,QAAQ;IACF,IAAI,CAAkB;IACtB,eAAe,CAAkB;IACjC,MAAM,CAAS;IACf,GAAG,CAAa;IAChB,MAAM,CAAU;IAChB,eAAe,CAAU;IACzB,oBAAoB,CAAS;IAC7B,WAAW,CAAS;IACpB,wBAAwB,CAAW;IACnC,OAAO,CAAe;IAC/B,mBAAmB,CAAU;IAC5B,WAAW,CAAc;IACzB,MAAM,CAAS;IAExB,YAAY,MAAsB;QAChC,MAAM,IAAI,GACR,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACrF,IAAI,CAAC,IAAI,GAAG,IAAI,eAAe,CAAC;YAC9B,GAAG,EAAE,MAAM,CAAC,QAAQ;YACpB,IAAI;YACJ,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC,CAAC;QACH,IAAI,CAAC,eAAe,GAAG,IAAI,eAAe,CAAC;YACzC,GAAG,EAAE,MAAM,CAAC,mBAAmB,IAAI,MAAM,CAAC,QAAQ;YAClD,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC,CAAC;QACH,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;YACvB,yEAAyE;YACzE,IAAI,CAAC,GAAG,GAAG,IAAI,SAAS,CACtB,IAAI,eAAe,CAAC;gBAClB,GAAG,EAAE,MAAM,CAAC,WAAW;gBACvB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,SAAS,EAAE,MAAM,CAAC,SAAS;aAC5B,CAAC,CACH,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC;QAC9C,IAAI,CAAC,oBAAoB;YACvB,MAAM,CAAC,oBAAoB,IAAI,gCAAgC,CAAC;QAClE,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,oBAAoB,CAAC;QAC9D,IAAI,CAAC,wBAAwB,GAAG,MAAM,CAAC,wBAAwB,CAAC;QAChE,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACtD,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,WAAW,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QACzD,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,oBAAoB;QAChC,IAAI,IAAI,CAAC,eAAe;YAAE,OAAO,IAAI,CAAC,eAAe,CAAC;QACtD,IAAI,IAAI,CAAC,mBAAmB;YAAE,OAAO,IAAI,CAAC,mBAAmB,CAAC;QAC9D,MAAM,EAAE,GAAG,MAAM,kBAAkB,CAAC,IAAI,CAAC,oBAAoB,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7E,IAAI,CAAC,mBAAmB,GAAG,EAAE,CAAC;QAC9B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;;;;OAKG;IACK,cAAc;QACpB,OAAO,IAAI,CAAC,oBAAoB;aAC7B,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;aAC/B,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACzB,CAAC;IAED,KAAK,GAAG;QACN,MAAM,EAAE,KAAK,EAAE,OAA2B,EAAE,EAAkB,EAAE;YAC9D,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACjD,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC;YAE3C,oEAAoE;YACpE,mEAAmE;YACnE,oEAAoE;YACpE,2DAA2D;YAC3D,IAAI,WAAW,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAC/B,MAAM,MAAM,GAAG,wBAAwB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACrD,MAAM,EAAE,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;gBACjC,UAAU,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,CAAC,CAAC;gBAC1C,MAAM,GAAG,GAAG,MAAM,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE;oBAC7D,UAAU,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC,CAAC;gBACzC,CAAC,CAAC,CAAC;gBACH,IAAI,GAAG,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;oBAClC,IAAI,CAAC,IAAI,CAAC,wBAAwB,EAAE,CAAC;wBACnC,MAAM,IAAI,uBAAuB,CAC/B,2EAA2E;8BACzE,yEAAyE;8BACzE,4BAA4B,CAC/B,CAAC;oBACJ,CAAC;oBACD,UAAU,CAAC,EAAE,IAAI,EAAE,gCAAgC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;oBAC3E,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,oBAAoB,EAAE,CAAC;oBACxD,UAAU,CAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,CAAC,CAAC;oBAC5C,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC;wBACpC,WAAW,EAAE,IAAI,CAAC,WAAW;wBAC7B,gBAAgB,EAAE,aAAa;wBAC/B,WAAW,EAAE,IAAI,CAAC,wBAAwB;qBAC3C,CAAC,CAAC;oBACH,UAAU,CAAC,EAAE,IAAI,EAAE,yBAAyB,EAAE,MAAM,EAAE,CAAC,CAAC;oBACxD,UAAU,CAAC,EAAE,IAAI,EAAE,6BAA6B,EAAE,CAAC,CAAC;oBACpD,MAAM,KAAK,GAAG,MAAM,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE;wBAClD,UAAU,EAAE,IAAI,CAAC,mBAAmB,IAAI,IAAI;wBAC5C,SAAS,EAAE,IAAI,CAAC,kBAAkB,IAAI,MAAM;wBAC5C,SAAS,EAAE,IAAI,CAAC,OAAO;qBACxB,CAAC,CAAC;oBACH,IAAI,CAAC,KAAK,EAAE,CAAC;wBACX,MAAM,IAAI,sBAAsB,CAC9B,oEAAoE;8BAClE,+DAA+D,CAClE,CAAC;oBACJ,CAAC;oBACD,UAAU,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC,CAAC;gBAC7C,CAAC;gBACD,6DAA6D;gBAC7D,+CAA+C;YACjD,CAAC;YAED,IAAI,eAAe,GAAG,IAAI,CAAC,eAAe,CAAC;YAC3C,IAAI,CAAC,eAAe,EAAE,CAAC;gBACrB,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;oBACjB,MAAM,IAAI,KAAK,CACb,gEAAgE;0BAC9D,uDAAuD,CAC1D,CAAC;gBACJ,CAAC;gBACD,UAAU,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC,CAAC;gBAC3C,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,oBAAoB,EAAE,CAAC;gBACxD,eAAe,GAAG,MAAM,yBAAyB,CAAC;oBAChD,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,aAAa;iBACd,CAAC,CAAC;YACL,CAAC;YACD,UAAU,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC,CAAC;YAC3C,MAAM,GAAG,GAAgB,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC/C,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,gBAAgB,EAAE,eAAe;aAClC,CAAC,CAAC;YACH,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3E,CAAC;QACD,OAAO,EAAE,KAAK,IAAoB,EAAE;YAClC,MAAM,GAAG,GAAgB,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACrD,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3E,CAAC;QACD,8CAA8C;QAC9C,iBAAiB,EAAE,KAAK,EACtB,OAAe,EACf,eAAuB,EACP,EAAE;YAClB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,OAAO,EAAE;gBACvD,gBAAgB,EAAE,eAAe;aAClC,CAAC,CAAC;YACH,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3E,CAAC;KACF,CAAC;CACH"}

package/dist/core/endpoints.d.ts

@@ -17,6 +17,7 @@ export declare const endpoints: {
     readonly jobActivity: (v: string, j: string, a: string) => string;
     readonly cubbyQuery: (v: string, s: string, alias: string) => string;
     readonly cubbyExec: (v: string, s: string, alias: string) => string;
+    readonly marketplaceAgents: () => string;
     readonly marketplaceAgent: (a: string) => string;
     readonly marketplaceAgentVersion: (a: string, v: string) => string;
     readonly health: () => string;

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

@@ -1 +1 @@
-{"version":3,"file":"endpoints.d.ts","sourceRoot":"","sources":["../../src/core/endpoints.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,SAAS;;wBAET,MAAM;mCACK,MAAM;yBAChB,MAAM;wBACP,MAAM,KAAK,MAAM;yBAChB,MAAM;wBACP,MAAM,KAAK,MAAM;8BACX,MAAM,KAAK,MAAM;+BAChB,MAAM,KAAK,MAAM;yBACvB,MAAM,KAAK,MAAM,OAAO,MAAM;+BAExB,MAAM,KAAK,MAAM,OAAO,MAAM;uBAEtC,MAAM;sBACP,MAAM,KAAK,MAAM;4BACX,MAAM,KAAK,MAAM;gCACb,MAAM,KAAK,MAAM;8BACnB,MAAM,KAAK,MAAM,KAAK,MAAM;6BAE7B,MAAM,KAAK,MAAM,SAAS,MAAM;4BAEjC,MAAM,KAAK,MAAM,SAAS,MAAM;mCAEzB,MAAM;0CACC,MAAM,KAAK,MAAM;;;;CAKtC,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC"}
+{"version":3,"file":"endpoints.d.ts","sourceRoot":"","sources":["../../src/core/endpoints.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,SAAS;;wBAET,MAAM;mCACK,MAAM;yBAChB,MAAM;wBACP,MAAM,KAAK,MAAM;yBAChB,MAAM;wBACP,MAAM,KAAK,MAAM;8BACX,MAAM,KAAK,MAAM;+BAChB,MAAM,KAAK,MAAM;yBACvB,MAAM,KAAK,MAAM,OAAO,MAAM;+BAExB,MAAM,KAAK,MAAM,OAAO,MAAM;uBAEtC,MAAM;sBACP,MAAM,KAAK,MAAM;4BACX,MAAM,KAAK,MAAM;gCACb,MAAM,KAAK,MAAM;8BACnB,MAAM,KAAK,MAAM,KAAK,MAAM;6BAE7B,MAAM,KAAK,MAAM,SAAS,MAAM;4BAEjC,MAAM,KAAK,MAAM,SAAS,MAAM;;mCAGzB,MAAM;0CACC,MAAM,KAAK,MAAM;;;;CAKtC,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC"}

package/dist/core/endpoints.js

@@ -19,6 +19,7 @@ export const endpoints = {
     jobActivity: (v, j, a) => `${API_BASE}/vaults/${seg(v)}/jobs/${seg(j)}/activities/${seg(a)}`,
     cubbyQuery: (v, s, alias) => `${API_BASE}/vaults/${seg(v)}/scopes/${seg(s)}/cubbies/${seg(alias)}/query`,
     cubbyExec: (v, s, alias) => `${API_BASE}/vaults/${seg(v)}/scopes/${seg(s)}/cubbies/${seg(alias)}/exec`,
+    marketplaceAgents: () => `${API_BASE}/marketplace/agents`,
     marketplaceAgent: (a) => `${API_BASE}/marketplace/agents/${seg(a)}`,
     marketplaceAgentVersion: (a, v) => `${API_BASE}/marketplace/agents/${seg(a)}/versions/${seg(v)}`,
     health: () => `/health`,

package/dist/core/endpoints.js.map

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

package/dist/core/types.d.ts

@@ -13,6 +13,11 @@ export interface Scope {
     name: string;
     displayName?: string;
     streamLabel?: string;
+    /**
+     * Free-form, top-level shallow-merge map. Server semantics: keys present
+     * in the patch overwrite stored keys; absent keys are preserved.
+     */
+    metadata?: Record<string, unknown>;
     createdAt: string;
 }
 export type AgentConnectionStatus = "provisioning" | "active" | "revoking" | "revoked";

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/job.d.ts

@@ -1,7 +1,17 @@
 import type { VaultHttpClient } from "../core/http.js";
 import { type ListActivitiesOptions } from "../internal/browse.js";
 import type { Activity, ActivitiesPage, Job } from "../core/types.js";
+import type { SubscribeOptions, Subscription } from "./subscribe.js";
+export interface ActivitySubscribeFilter {
+    /**
+     * Only deliver activities whose `startedAt` (or `endedAt` for terminal
+     * states) is at or after this ISO-8601 timestamp. Applied client-side.
+     */
+    since?: string;
+}
+export type ActivityHandler = (activity: Activity) => void | Promise<void>;
 export declare class JobHandle {
+    private readonly http;
     private readonly vaultId;
     readonly jobId: string;
     private readonly browse;
@@ -10,6 +20,12 @@ export declare class JobHandle {
     activities: {
         list: (o?: ListActivitiesOptions) => Promise<ActivitiesPage>;
         get: (a: string) => Promise<Activity>;
+        /**
+         * Poll-backed subscription over `ListActivities`. Mirrors the structure
+         * of `subscribe.ts`: tracks seen activity ids, filters duplicates,
+         * supports `unsubscribe()`. Stops cleanly via the returned handle.
+         */
+        subscribe: (filter: ActivitySubscribeFilter, handler: ActivityHandler, opts?: SubscribeOptions) => Subscription;
     };
     /**
      * Walk caused-by edges. Server tree route is not yet implemented (returns

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

@@ -1 +1 @@
-{"version":3,"file":"job.d.ts","sourceRoot":"","sources":["../../src/fluent/job.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAU,KAAK,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AAEtE,qBAAa,SAAS;IAIlB,OAAO,CAAC,QAAQ,CAAC,OAAO;aACR,KAAK,EAAE,MAAM;IAJ/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAE9B,IAAI,EAAE,eAAe,EACJ,OAAO,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM;IAI/B,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACnB,UAAU;mBACE,qBAAqB,KAAQ,OAAO,CAAC,cAAc,CAAC;iBAErD,MAAM,KAAG,OAAO,CAAC,QAAQ,CAAC;MACnC;IACF;;;OAGG;IACH,IAAI,IAAI,KAAK;CAKd"}
+{"version":3,"file":"job.d.ts","sourceRoot":"","sources":["../../src/fluent/job.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAU,KAAK,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAErE,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE3E,qBAAa,SAAS;IAGlB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;aACR,KAAK,EAAE,MAAM;IAJ/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEb,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM;IAI/B,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACnB,UAAU;mBACE,qBAAqB,KAAQ,OAAO,CAAC,cAAc,CAAC;iBAErD,MAAM,KAAG,OAAO,CAAC,QAAQ,CAAC;QACnC;;;;WAIG;4BAEO,uBAAuB,WACtB,eAAe,SAClB,gBAAgB,KACrB,YAAY;MAGf;IACF;;;OAGG;IACH,IAAI,IAAI,KAAK;CAKd"}

package/dist/fluent/job.js

@@ -1,9 +1,11 @@
 import { Browse } from "../internal/browse.js";
 export class JobHandle {
+    http;
     vaultId;
     jobId;
     browse;
     constructor(http, vaultId, jobId) {
+        this.http = http;
         this.vaultId = vaultId;
         this.jobId = jobId;
         this.browse = new Browse(http);
@@ -12,6 +14,12 @@ export class JobHandle {
     activities = {
         list: (o = {}) => this.browse.listActivities(this.vaultId, this.jobId, o),
         get: (a) => this.browse.getActivity(this.vaultId, this.jobId, a),
+        /**
+         * Poll-backed subscription over `ListActivities`. Mirrors the structure
+         * of `subscribe.ts`: tracks seen activity ids, filters duplicates,
+         * supports `unsubscribe()`. Stops cleanly via the returned handle.
+         */
+        subscribe: (filter, handler, opts = {}) => subscribeActivities(this.browse, this.vaultId, this.jobId, filter, handler, opts),
     };
     /**
      * Walk caused-by edges. Server tree route is not yet implemented (returns
@@ -21,4 +29,51 @@ export class JobHandle {
         throw new Error("JobHandle.tree() requires the orchestrator's tree route which is not yet implemented (returns 501).");
     }
 }
+function subscribeActivities(browse, vaultId, jobId, filter, handler, opts) {
+    const interval = opts.intervalMs ?? 1000;
+    const pageSize = opts.pageSize ?? 100;
+    const onError = opts.onError ?? ((e) => {
+        console.warn("[vault-sdk] activities.subscribe poll failed:", e);
+    });
+    const seen = new Set();
+    let cursor;
+    let stopped = false;
+    let closeResolve;
+    const closed = new Promise((r) => (closeResolve = r));
+    const sinceMs = filter.since ? Date.parse(filter.since) : undefined;
+    const tick = async () => {
+        while (!stopped) {
+            try {
+                const page = await browse.listActivities(vaultId, jobId, {
+                    cursor, limit: pageSize,
+                });
+                for (const activity of page.items) {
+                    if (seen.has(activity.activityId))
+                        continue;
+                    seen.add(activity.activityId);
+                    if (sinceMs !== undefined) {
+                        const t = activity.startedAt ?? activity.endedAt;
+                        if (t && Date.parse(t) < sinceMs)
+                            continue;
+                    }
+                    await handler(activity);
+                }
+                if (page.nextCursor)
+                    cursor = page.nextCursor;
+            }
+            catch (err) {
+                onError(err);
+            }
+            if (stopped)
+                break;
+            await new Promise((r) => setTimeout(r, interval));
+        }
+        closeResolve();
+    };
+    void tick();
+    return {
+        unsubscribe() { stopped = true; },
+        closed,
+    };
+}
 //# sourceMappingURL=job.js.map