@shardlink/agent-sdk 0.1.0

package/dist/modules/lease-manager.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Lease auto-management.
+ *
+ * Agents shouldn't have to think about leases. A {@link LeaseManager}
+ * observes the workspace event stream, caches the last known lease state,
+ * and invokes re-request / threshold callbacks on the agent's behalf.
+ *
+ * Design notes:
+ * - The control-plane does not currently expose a dedicated
+ *   `/v1/workspaces/:slug/leases/state` endpoint. Instead, the manager
+ *   keeps an in-memory snapshot seeded from the `lease-request` response
+ *   and continuously updated by stream events (`lease_approved`,
+ *   `lease_revoked`, `lease_expiring`, `spend_envelope_depleting`).
+ * - `enableAutoRenew()` registers a stream handler that re-calls
+ *   `LeaseClient.request` when `lease_expiring` fires.
+ * - `onBudgetThreshold()` fires when the spend-envelope event indicates
+ *   usage has crossed the given percentage.
+ *
+ * @packageDocumentation
+ */
+import type { StreamClient } from "./streams.js";
+import type { LeaseClient } from "./leases.js";
+/** Snapshot of the lease state the manager tracks locally. */
+export interface LeaseSnapshot {
+    /** Workspace this snapshot is scoped to. */
+    workspaceSlug: string;
+    /** Identity the lease is bound to. */
+    identity?: string;
+    /** Lease tier (sandbox/standard/verified/…). */
+    tier?: string;
+    /** Cap in action units. */
+    rateLimit?: number;
+    /** Actions already consumed. */
+    actionCount?: number;
+    /** Spend cap (workspace units, not USD cents). */
+    spendCap?: number;
+    /** Spend already consumed. */
+    spendUsed?: number;
+    /** Pricing version bound to the lease. */
+    pricingVersion?: string;
+    /** ISO timestamp or epoch-ms when the lease expires. */
+    expiresAt?: number | string;
+    /** Lease lifecycle status. */
+    status?: "pending" | "active" | "expired" | "revoked";
+    /** When this snapshot was last updated (ms since epoch). */
+    updatedAt: number;
+}
+export interface AutoRenewConfig {
+    /** Lease tier to request on renewal (defaults to the current tier). */
+    tier?: string;
+    /** Optional pricing quote id to bind to the renewal. */
+    quoteId?: string;
+    /** Optional spend envelope id. */
+    envelopeId?: string;
+    /** Callback fired when auto-renewal succeeds. */
+    onRenewed?: (snapshot: LeaseSnapshot) => void;
+    /** Callback fired when auto-renewal fails. */
+    onFailed?: (error: unknown) => void;
+}
+export interface LeaseManagerOptions {
+    workspaceSlug: string;
+    actorSessionToken: string;
+    leaseClient: LeaseClient;
+    stream: StreamClient;
+    /** Optional seed — useful when you have the initial lease response in hand. */
+    initial?: Partial<LeaseSnapshot>;
+}
+type ThresholdHandler = () => void;
+/**
+ * Observes lease state via the workspace event stream and exposes helpers
+ * for auto-renewal + budget thresholds.
+ */
+export declare class LeaseManager {
+    private snapshot;
+    private readonly options;
+    private readonly thresholdHandlers;
+    private readonly firedThresholds;
+    private autoRenewConfig;
+    private readonly unsubscribes;
+    private renewing;
+    constructor(options: LeaseManagerOptions);
+    /** Current lease snapshot — safe to call without awaiting. */
+    status(): LeaseSnapshot;
+    /** Remaining spend budget in the lease's native units. */
+    remainingBudget(): number;
+    /** Milliseconds remaining until expiry. `Infinity` when unknown. */
+    expiresIn(): number;
+    /**
+     * Update the local snapshot. Useful when you get the fresh lease state
+     * from a `leases/request` response outside the manager.
+     */
+    ingest(partial: Partial<LeaseSnapshot>): void;
+    /**
+     * Enable automatic lease renewal. The manager will call
+     * `leaseClient.request` when a `lease_expiring` event arrives.
+     *
+     * @example
+     * ```ts
+     * lease.enableAutoRenew({ tier: "sandbox" });
+     * ```
+     */
+    enableAutoRenew(config?: AutoRenewConfig): void;
+    /** Disable auto-renewal. */
+    disableAutoRenew(): void;
+    /**
+     * Register a callback that fires when spend usage crosses `percent`.
+     * Each percent threshold fires at most once per lease period — the
+     * tracking resets when `ingest()` or `lease_approved` lowers the usage.
+     */
+    onBudgetThreshold(percent: number, handler: ThresholdHandler): () => void;
+    /** Detach all stream listeners and reset local state. */
+    dispose(): void;
+    private onLeaseEvent;
+    private onLeaseExpiring;
+    private onSpendDepleting;
+    private checkThresholds;
+}
+export {};
+//# sourceMappingURL=lease-manager.d.ts.map

package/dist/modules/lease-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-manager.d.ts","sourceRoot":"","sources":["../../src/modules/lease-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,8BAA8B;IAC9B,MAAM,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IACtD,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAC;IAC9C,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;CAClC;AAED,KAAK,gBAAgB,GAAG,MAAM,IAAI,CAAC;AAiDnC;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4C;IAC9E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;IACtD,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,mBAAmB;IAqBxC,8DAA8D;IAC9D,MAAM,IAAI,aAAa;IAIvB,0DAA0D;IAC1D,eAAe,IAAI,MAAM;IAIzB,oEAAoE;IACpE,SAAS,IAAI,MAAM;IAInB;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI;IAK7C;;;;;;;;OAQG;IACH,eAAe,CAAC,MAAM,GAAE,eAAoB,GAAG,IAAI;IAInD,4BAA4B;IAC5B,gBAAgB,IAAI,IAAI;IAIxB;;;;OAIG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,MAAM,IAAI;IAezE,yDAAyD;IACzD,OAAO,IAAI,IAAI;IAaf,OAAO,CAAC,YAAY;YAWN,eAAe;IA8C7B,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,eAAe;CAsBxB"}

package/dist/modules/lease-manager.js

@@ -0,0 +1,242 @@
+/**
+ * Lease auto-management.
+ *
+ * Agents shouldn't have to think about leases. A {@link LeaseManager}
+ * observes the workspace event stream, caches the last known lease state,
+ * and invokes re-request / threshold callbacks on the agent's behalf.
+ *
+ * Design notes:
+ * - The control-plane does not currently expose a dedicated
+ *   `/v1/workspaces/:slug/leases/state` endpoint. Instead, the manager
+ *   keeps an in-memory snapshot seeded from the `lease-request` response
+ *   and continuously updated by stream events (`lease_approved`,
+ *   `lease_revoked`, `lease_expiring`, `spend_envelope_depleting`).
+ * - `enableAutoRenew()` registers a stream handler that re-calls
+ *   `LeaseClient.request` when `lease_expiring` fires.
+ * - `onBudgetThreshold()` fires when the spend-envelope event indicates
+ *   usage has crossed the given percentage.
+ *
+ * @packageDocumentation
+ */
+import { LeaseError } from "../errors.js";
+/** Compute remaining budget in the lease's native units (0 if unknown). */
+function remainingUnits(snapshot) {
+    if (typeof snapshot.spendCap === "number" && typeof snapshot.spendUsed === "number") {
+        return Math.max(0, snapshot.spendCap - snapshot.spendUsed);
+    }
+    return 0;
+}
+/** Compute time-to-expiry in ms (Infinity if not known). */
+function msUntilExpiry(snapshot) {
+    if (!snapshot.expiresAt) {
+        return Number.POSITIVE_INFINITY;
+    }
+    const asNumber = typeof snapshot.expiresAt === "number" ? snapshot.expiresAt : Date.parse(snapshot.expiresAt);
+    if (Number.isNaN(asNumber)) {
+        return Number.POSITIVE_INFINITY;
+    }
+    return asNumber - Date.now();
+}
+/** Merge a stream-event payload into the lease snapshot. */
+function mergeEventIntoSnapshot(base, payload) {
+    const next = { ...base, updatedAt: Date.now() };
+    if (typeof payload.tier === "string")
+        next.tier = payload.tier;
+    if (typeof payload.rateLimit === "number")
+        next.rateLimit = payload.rateLimit;
+    if (typeof payload.actionCount === "number")
+        next.actionCount = payload.actionCount;
+    if (typeof payload.spendCap === "number")
+        next.spendCap = payload.spendCap;
+    if (typeof payload.spendUsed === "number")
+        next.spendUsed = payload.spendUsed;
+    if (typeof payload.pricingVersion === "string")
+        next.pricingVersion = payload.pricingVersion;
+    if (typeof payload.expiresAt === "number" || typeof payload.expiresAt === "string") {
+        next.expiresAt = payload.expiresAt;
+    }
+    if (payload.status === "pending" ||
+        payload.status === "active" ||
+        payload.status === "expired" ||
+        payload.status === "revoked") {
+        next.status = payload.status;
+    }
+    return next;
+}
+/**
+ * Observes lease state via the workspace event stream and exposes helpers
+ * for auto-renewal + budget thresholds.
+ */
+export class LeaseManager {
+    snapshot;
+    options;
+    thresholdHandlers = new Map();
+    firedThresholds = new Set();
+    autoRenewConfig = null;
+    unsubscribes = [];
+    renewing = false;
+    constructor(options) {
+        this.options = options;
+        this.snapshot = {
+            workspaceSlug: options.workspaceSlug,
+            updatedAt: Date.now(),
+            ...options.initial
+        };
+        this.unsubscribes.push(options.stream.on("lease_approved", (event) => this.onLeaseEvent(event.payload, "active")));
+        this.unsubscribes.push(options.stream.on("lease_revoked", (event) => this.onLeaseEvent(event.payload, "revoked")));
+        this.unsubscribes.push(options.stream.on("lease_expiring", (event) => this.onLeaseExpiring(event.payload)));
+        this.unsubscribes.push(options.stream.on("spend_envelope_depleting", (event) => this.onSpendDepleting(event.payload)));
+    }
+    /** Current lease snapshot — safe to call without awaiting. */
+    status() {
+        return { ...this.snapshot };
+    }
+    /** Remaining spend budget in the lease's native units. */
+    remainingBudget() {
+        return remainingUnits(this.snapshot);
+    }
+    /** Milliseconds remaining until expiry. `Infinity` when unknown. */
+    expiresIn() {
+        return msUntilExpiry(this.snapshot);
+    }
+    /**
+     * Update the local snapshot. Useful when you get the fresh lease state
+     * from a `leases/request` response outside the manager.
+     */
+    ingest(partial) {
+        this.snapshot = { ...this.snapshot, ...partial, updatedAt: Date.now() };
+        this.checkThresholds();
+    }
+    /**
+     * Enable automatic lease renewal. The manager will call
+     * `leaseClient.request` when a `lease_expiring` event arrives.
+     *
+     * @example
+     * ```ts
+     * lease.enableAutoRenew({ tier: "sandbox" });
+     * ```
+     */
+    enableAutoRenew(config = {}) {
+        this.autoRenewConfig = config;
+    }
+    /** Disable auto-renewal. */
+    disableAutoRenew() {
+        this.autoRenewConfig = null;
+    }
+    /**
+     * Register a callback that fires when spend usage crosses `percent`.
+     * Each percent threshold fires at most once per lease period — the
+     * tracking resets when `ingest()` or `lease_approved` lowers the usage.
+     */
+    onBudgetThreshold(percent, handler) {
+        if (percent <= 0 || percent > 100) {
+            throw new Error(`[LeaseManager] threshold percent must be in (0, 100]; got ${percent}.`);
+        }
+        let bucket = this.thresholdHandlers.get(percent);
+        if (!bucket) {
+            bucket = new Set();
+            this.thresholdHandlers.set(percent, bucket);
+        }
+        bucket.add(handler);
+        return () => {
+            bucket?.delete(handler);
+        };
+    }
+    /** Detach all stream listeners and reset local state. */
+    dispose() {
+        for (const unsub of this.unsubscribes) {
+            try {
+                unsub();
+            }
+            catch {
+                // ignore
+            }
+        }
+        this.thresholdHandlers.clear();
+        this.firedThresholds.clear();
+        this.autoRenewConfig = null;
+    }
+    onLeaseEvent(payload, status) {
+        if (!isRecord(payload))
+            return;
+        const leasePayload = isRecord(payload.lease) ? payload.lease : payload;
+        this.snapshot = mergeEventIntoSnapshot({ ...this.snapshot, status }, leasePayload);
+        this.firedThresholds.clear();
+        this.checkThresholds();
+    }
+    async onLeaseExpiring(payload) {
+        if (isRecord(payload)) {
+            const leasePayload = isRecord(payload.lease) ? payload.lease : payload;
+            this.snapshot = mergeEventIntoSnapshot(this.snapshot, leasePayload);
+        }
+        if (!this.autoRenewConfig || this.renewing)
+            return;
+        this.renewing = true;
+        try {
+            const result = await this.options.leaseClient.request({
+                workspaceSlug: this.options.workspaceSlug,
+                actorSessionToken: this.options.actorSessionToken,
+                idempotencyKey: `lease-auto-renew:${this.options.workspaceSlug}:${Date.now()}`,
+                ...((this.autoRenewConfig.tier ?? this.snapshot.tier)
+                    ? { tier: (this.autoRenewConfig.tier ?? this.snapshot.tier) }
+                    : {}),
+                ...(this.autoRenewConfig.quoteId ? { quoteId: this.autoRenewConfig.quoteId } : {}),
+                ...(this.autoRenewConfig.envelopeId ? { envelopeId: this.autoRenewConfig.envelopeId } : {})
+            });
+            const merged = isRecord(result) && isRecord(result.lease) ? result.lease : result;
+            if (isRecord(merged)) {
+                this.snapshot = mergeEventIntoSnapshot({ ...this.snapshot, status: "active" }, merged);
+            }
+            this.firedThresholds.clear();
+            this.autoRenewConfig.onRenewed?.(this.status());
+        }
+        catch (error) {
+            const err = error instanceof Error
+                ? error
+                : new LeaseError({
+                    message: "Lease auto-renew failed.",
+                    code: "lease_renew_failed",
+                    status: 0,
+                    retryable: true
+                });
+            this.autoRenewConfig.onFailed?.(err);
+        }
+        finally {
+            this.renewing = false;
+        }
+    }
+    onSpendDepleting(payload) {
+        if (!isRecord(payload))
+            return;
+        this.snapshot = mergeEventIntoSnapshot(this.snapshot, payload);
+        this.checkThresholds();
+    }
+    checkThresholds() {
+        if (this.snapshot.spendCap === undefined || this.snapshot.spendUsed === undefined) {
+            return;
+        }
+        if (this.snapshot.spendCap <= 0)
+            return;
+        const usagePercent = (this.snapshot.spendUsed / this.snapshot.spendCap) * 100;
+        for (const [threshold, handlers] of this.thresholdHandlers.entries()) {
+            if (usagePercent >= threshold && !this.firedThresholds.has(threshold)) {
+                this.firedThresholds.add(threshold);
+                for (const handler of handlers) {
+                    try {
+                        handler();
+                    }
+                    catch {
+                        // ignore handler errors
+                    }
+                }
+            }
+            if (usagePercent < threshold && this.firedThresholds.has(threshold)) {
+                this.firedThresholds.delete(threshold);
+            }
+        }
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+//# sourceMappingURL=lease-manager.js.map

package/dist/modules/lease-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-manager.js","sourceRoot":"","sources":["../../src/modules/lease-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAsD1C,2EAA2E;AAC3E,SAAS,cAAc,CAAC,QAAuB;IAC7C,IAAI,OAAO,QAAQ,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,QAAQ,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QACpF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,QAAQ,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,4DAA4D;AAC5D,SAAS,aAAa,CAAC,QAAuB;IAC5C,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;QACxB,OAAO,MAAM,CAAC,iBAAiB,CAAC;IAClC,CAAC;IACD,MAAM,QAAQ,GACZ,OAAO,QAAQ,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC/F,IAAI,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3B,OAAO,MAAM,CAAC,iBAAiB,CAAC;IAClC,CAAC;IACD,OAAO,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;AAC/B,CAAC;AAED,4DAA4D;AAC5D,SAAS,sBAAsB,CAC7B,IAAmB,EACnB,OAAgC;IAEhC,MAAM,IAAI,GAAkB,EAAE,GAAG,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IAC/D,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ;QAAE,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC/D,IAAI,OAAO,OAAO,CAAC,SAAS,KAAK,QAAQ;QAAE,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAC9E,IAAI,OAAO,OAAO,CAAC,WAAW,KAAK,QAAQ;QAAE,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IACpF,IAAI,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAAE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC3E,IAAI,OAAO,OAAO,CAAC,SAAS,KAAK,QAAQ;QAAE,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAC9E,IAAI,OAAO,OAAO,CAAC,cAAc,KAAK,QAAQ;QAAE,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAC7F,IAAI,OAAO,OAAO,CAAC,SAAS,KAAK,QAAQ,IAAI,OAAO,OAAO,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QACnF,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACrC,CAAC;IACD,IACE,OAAO,CAAC,MAAM,KAAK,SAAS;QAC5B,OAAO,CAAC,MAAM,KAAK,QAAQ;QAC3B,OAAO,CAAC,MAAM,KAAK,SAAS;QAC5B,OAAO,CAAC,MAAM,KAAK,SAAS,EAC5B,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC/B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,YAAY;IACf,QAAQ,CAAgB;IACf,OAAO,CAAsB;IAC7B,iBAAiB,GAAG,IAAI,GAAG,EAAiC,CAAC;IAC7D,eAAe,GAAG,IAAI,GAAG,EAAU,CAAC;IAC7C,eAAe,GAA2B,IAAI,CAAC;IACtC,YAAY,GAAsB,EAAE,CAAC;IAC9C,QAAQ,GAAG,KAAK,CAAC;IAEzB,YAAY,OAA4B;QACtC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG;YACd,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,GAAG,OAAO,CAAC,OAAO;SACnB,CAAC;QACF,IAAI,CAAC,YAAY,CAAC,IAAI,CACpB,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,gBAAgB,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAC3F,CAAC;QACF,IAAI,CAAC,YAAY,CAAC,IAAI,CACpB,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,eAAe,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAC3F,CAAC;QACF,IAAI,CAAC,YAAY,CAAC,IAAI,CACpB,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,gBAAgB,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CACpF,CAAC;QACF,IAAI,CAAC,YAAY,CAAC,IAAI,CACpB,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,0BAA0B,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAC/F,CAAC;IACJ,CAAC;IAED,8DAA8D;IAC9D,MAAM;QACJ,OAAO,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;IAC9B,CAAC;IAED,0DAA0D;IAC1D,eAAe;QACb,OAAO,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,oEAAoE;IACpE,SAAS;QACP,OAAO,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,OAA+B;QACpC,IAAI,CAAC,QAAQ,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QACxE,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC;IAED;;;;;;;;OAQG;IACH,eAAe,CAAC,SAA0B,EAAE;QAC1C,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC;IAChC,CAAC;IAED,4BAA4B;IAC5B,gBAAgB;QACd,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,iBAAiB,CAAC,OAAe,EAAE,OAAyB;QAC1D,IAAI,OAAO,IAAI,CAAC,IAAI,OAAO,GAAG,GAAG,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,6DAA6D,OAAO,GAAG,CAAC,CAAC;QAC3F,CAAC;QACD,IAAI,MAAM,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;YACnB,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC9C,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACpB,OAAO,GAAG,EAAE;YACV,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAC1B,CAAC,CAAC;IACJ,CAAC;IAED,yDAAyD;IACzD,OAAO;QACL,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtC,IAAI,CAAC;gBACH,KAAK,EAAE,CAAC;YACV,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;QACH,CAAC;QACD,IAAI,CAAC,iBAAiB,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAC7B,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;IAC9B,CAAC;IAEO,YAAY,CAAC,OAAgB,EAAE,MAA4B;QACjE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,OAAO;QAC/B,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC;QACvE,IAAI,CAAC,QAAQ,GAAG,sBAAsB,CACpC,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,EAC5B,YAAuC,CACxC,CAAC;QACF,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAC7B,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC;IAEO,KAAK,CAAC,eAAe,CAAC,OAAgB;QAC5C,IAAI,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACtB,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC;YACvE,IAAI,CAAC,QAAQ,GAAG,sBAAsB,CACpC,IAAI,CAAC,QAAQ,EACb,YAAuC,CACxC,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QACnD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC;gBACpD,aAAa,EAAE,IAAI,CAAC,OAAO,CAAC,aAAa;gBACzC,iBAAiB,EAAE,IAAI,CAAC,OAAO,CAAC,iBAAiB;gBACjD,cAAc,EAAE,oBAAoB,IAAI,CAAC,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE;gBAC9E,GAAG,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;oBACnD,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAW,EAAE;oBACvE,CAAC,CAAC,EAAE,CAAC;gBACP,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClF,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,eAAe,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC5F,CAAC,CAAC;YACH,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;YAClF,IAAI,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBACrB,IAAI,CAAC,QAAQ,GAAG,sBAAsB,CACpC,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,EACtC,MAAiC,CAClC,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;YAC7B,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAClD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,GAAG,GACP,KAAK,YAAY,KAAK;gBACpB,CAAC,CAAC,KAAK;gBACP,CAAC,CAAC,IAAI,UAAU,CAAC;oBACb,OAAO,EAAE,0BAA0B;oBACnC,IAAI,EAAE,oBAAoB;oBAC1B,MAAM,EAAE,CAAC;oBACT,SAAS,EAAE,IAAI;iBAChB,CAAC,CAAC;YACT,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;QACvC,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACxB,CAAC;IACH,CAAC;IAEO,gBAAgB,CAAC,OAAgB;QACvC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,OAAO;QAC/B,IAAI,CAAC,QAAQ,GAAG,sBAAsB,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC/D,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC;IAEO,eAAe;QACrB,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YAClF,OAAO;QACT,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,IAAI,CAAC;YAAE,OAAO;QACxC,MAAM,YAAY,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,GAAG,CAAC;QAC9E,KAAK,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC,iBAAiB,CAAC,OAAO,EAAE,EAAE,CAAC;YACrE,IAAI,YAAY,IAAI,SAAS,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;gBACtE,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;gBACpC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;oBAC/B,IAAI,CAAC;wBACH,OAAO,EAAE,CAAC;oBACZ,CAAC;oBAAC,MAAM,CAAC;wBACP,wBAAwB;oBAC1B,CAAC;gBACH,CAAC;YACH,CAAC;YACD,IAAI,YAAY,GAAG,SAAS,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;gBACpE,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC"}

package/dist/modules/leases.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Lease client — request and inspect workspace leases.
+ *
+ * Approve/revoke are governor-only and live on the workspace routes; this
+ * module covers the agent-facing `request` and local state helpers.
+ *
+ * @packageDocumentation
+ */
+import type { HttpContext } from "../utils.js";
+/** A payment intent created or referenced by a lease request. */
+export interface LeasePaymentIntent {
+    id: string;
+    workspaceId: string;
+    agentIdentity: string;
+    tier: "sandbox" | "standard";
+    amount: number;
+    currency: "USD";
+    status: string;
+    proofLevel: "P0" | "P1" | "P2";
+    pricingVersion?: string;
+    quotedCreditUnits?: number;
+    txRef?: string;
+    createdAt: number;
+}
+/**
+ * Result of {@link LeaseClient.request}. `intentId` is always present; the
+ * pricing/quote fields appear when the request resolved a payment intent or
+ * was backed by an accepted pricing quote.
+ */
+export interface LeaseRequestResult {
+    intentId: string;
+    /** Resolved payment intent, when the runtime returned one. */
+    intent?: LeasePaymentIntent;
+    pricingVersion?: string;
+    amountUsdCents?: number;
+    creditUnits?: number;
+    quoteId?: string;
+    /** ISO timestamp the backing quote expires. */
+    quoteExpiresAt?: string;
+}
+/** Agent-facing lease helper. */
+export declare class LeaseClient {
+    private readonly http;
+    constructor(http: HttpContext);
+    /**
+     * Request a lease on a workspace. Requires a workspace actor session token.
+     *
+     * Attach the pricing quote + envelope ids when the funding flow produced them
+     * so the control-plane can bind the lease to those artefacts.
+     *
+     * @example
+     * ```ts
+     * await leases.request({
+     *   workspaceSlug: "ws_1",
+     *   actorSessionToken,
+     *   tier: "sandbox",
+     *   idempotencyKey: "lease:ws_1:agent_42"
+     * });
+     * ```
+     */
+    request(input: {
+        workspaceSlug: string;
+        actorSessionToken: string;
+        tier?: string;
+        quoteId?: string;
+        envelopeId?: string;
+        idempotencyKey: string;
+    }): Promise<LeaseRequestResult>;
+}
+//# sourceMappingURL=leases.d.ts.map

package/dist/modules/leases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leases.d.ts","sourceRoot":"","sources":["../../src/modules/leases.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAM/C,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,SAAS,GAAG,UAAU,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,KAAK,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,iCAAiC;AACjC,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,WAAW;IAE9C;;;;;;;;;;;;;;;OAeG;IACG,OAAO,CAAC,KAAK,EAAE;QACnB,aAAa,EAAE,MAAM,CAAC;QACtB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;KACxB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAgBhC"}

package/dist/modules/leases.js

@@ -0,0 +1,51 @@
+/**
+ * Lease client — request and inspect workspace leases.
+ *
+ * Approve/revoke are governor-only and live on the workspace routes; this
+ * module covers the agent-facing `request` and local state helpers.
+ *
+ * @packageDocumentation
+ */
+function idempotencyHeader(key) {
+    return { "idempotency-key": key };
+}
+/** Agent-facing lease helper. */
+export class LeaseClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Request a lease on a workspace. Requires a workspace actor session token.
+     *
+     * Attach the pricing quote + envelope ids when the funding flow produced them
+     * so the control-plane can bind the lease to those artefacts.
+     *
+     * @example
+     * ```ts
+     * await leases.request({
+     *   workspaceSlug: "ws_1",
+     *   actorSessionToken,
+     *   tier: "sandbox",
+     *   idempotencyKey: "lease:ws_1:agent_42"
+     * });
+     * ```
+     */
+    async request(input) {
+        const body = {};
+        if (input.tier)
+            body.tier = input.tier;
+        if (input.quoteId)
+            body.quoteId = input.quoteId;
+        if (input.envelopeId)
+            body.envelopeId = input.envelopeId;
+        return this.http.request({
+            path: `/v1/workspaces/${encodeURIComponent(input.workspaceSlug)}/leases/request`,
+            method: "POST",
+            operation: "lease-request",
+            headers: this.http.bearerHeaders(input.actorSessionToken, idempotencyHeader(input.idempotencyKey)),
+            body
+        });
+    }
+}
+//# sourceMappingURL=leases.js.map

package/dist/modules/leases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"leases.js","sourceRoot":"","sources":["../../src/modules/leases.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,SAAS,iBAAiB,CAAC,GAAW;IACpC,OAAO,EAAE,iBAAiB,EAAE,GAAG,EAAE,CAAC;AACpC,CAAC;AAmCD,iCAAiC;AACjC,MAAM,OAAO,WAAW;IACO;IAA7B,YAA6B,IAAiB;QAAjB,SAAI,GAAJ,IAAI,CAAa;IAAG,CAAC;IAElD;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,OAAO,CAAC,KAOb;QACC,MAAM,IAAI,GAA4B,EAAE,CAAC;QACzC,IAAI,KAAK,CAAC,IAAI;YAAE,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvC,IAAI,KAAK,CAAC,OAAO;YAAE,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAChD,IAAI,KAAK,CAAC,UAAU;YAAE,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;QACzD,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAqB;YAC3C,IAAI,EAAE,kBAAkB,kBAAkB,CAAC,KAAK,CAAC,aAAa,CAAC,iBAAiB;YAChF,MAAM,EAAE,MAAM;YACd,SAAS,EAAE,eAAe;YAC1B,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,aAAa,CAC9B,KAAK,CAAC,iBAAiB,EACvB,iBAAiB,CAAC,KAAK,CAAC,cAAc,CAAC,CACxC;YACD,IAAI;SACL,CAAC,CAAC;IACL,CAAC;CACF"}