@shardlink/agent-sdk 0.1.0

package/dist/modules/compliance.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Pre-claim compliance guard.
+ *
+ * Before the SDK lets a task claim go to the wire, the guard runs a battery
+ * of client-side checks so the agent gets a structured "why not, and how to
+ * fix" response instead of a 4xx from the control-plane. Server-side is
+ * still authoritative — this is a friendly, fast, informative preflight.
+ *
+ * Six checks, matching T4.3 in the audit doc:
+ * 1. Agent has an active lease for the target workspace.
+ * 2. Spend envelope has room for the task's estimated cost.
+ * 3. Agent's declared `supportedActions` covers the task's required action.
+ * 4. Agent isn't already at its max concurrent in-flight task cap.
+ * 5. Rate limit has headroom (via {@link QuotaClient}).
+ * 6. Trust tier permits this task type.
+ *
+ * @packageDocumentation
+ */
+import type { LeaseSnapshot } from "./lease-manager.js";
+import type { QuotaClient } from "./quota.js";
+import type { SandboxPolicy } from "./sandbox.js";
+import type { WorkspaceDirectoryEntry } from "../types.js";
+/** Per-check status. */
+export type ComplianceStatus = "pass" | "warn" | "fail";
+/** One compliance check result. */
+export interface ComplianceCheck {
+    name: "lease_active" | "spend_headroom" | "capability_match" | "concurrency_budget" | "rate_limit" | "trust_tier";
+    status: ComplianceStatus;
+    message?: string;
+    fix?: string;
+    details?: Record<string, unknown>;
+}
+/** Full pre-claim report. */
+export interface ComplianceReport {
+    ok: boolean;
+    checks: ComplianceCheck[];
+    failures: ComplianceCheck[];
+    /** Aggregated one-line summary suitable for log lines. */
+    summary: string;
+}
+/** Input describing the task about to be claimed. */
+export interface ClaimCandidate {
+    taskId: string;
+    /** Action name the task will invoke (e.g. `"claim_task"` or a reducer action). */
+    requiredAction?: string;
+    /** Estimated cost in the lease's native spend units. */
+    estimatedSpendUnits?: number;
+    /** Which workspace the task belongs to. */
+    workspaceSlug: string;
+    /** Optional workspace directory entry (used for trust-tier gating). */
+    workspace?: WorkspaceDirectoryEntry;
+}
+/** Options for the guard. */
+export interface ComplianceGuardOptions {
+    /** Source of lease snapshot — typically `() => leaseManager.status()`. */
+    getLease: () => LeaseSnapshot | undefined;
+    /** Declared supported actions for this agent. */
+    supportedActions: string[];
+    /** Max concurrent in-flight task claims. */
+    maxConcurrent: number;
+    /** Source of "tasks currently in flight" — typically `() => enforcer.inFlightCount()`. */
+    getInFlight: () => number;
+    /** Optional quota client for rate-limit headroom. */
+    quota?: QuotaClient;
+    /** Optional sandbox policy for trust-tier checks. */
+    sandbox?: SandboxPolicy;
+}
+/** Pre-claim compliance guard. */
+export declare class ComplianceGuard {
+    private readonly options;
+    constructor(options: ComplianceGuardOptions);
+    /**
+     * Run every check and return a structured report.
+     *
+     * Never throws — a failed check shows up in `report.checks` and
+     * contributes to `report.ok === false`.
+     */
+    check(candidate: ClaimCandidate): ComplianceReport;
+    private checkLease;
+    private checkSpendHeadroom;
+    private checkCapabilityMatch;
+    private checkConcurrencyBudget;
+    private checkRateLimit;
+    private checkTrustTier;
+    /**
+     * Convenience: run `check` and throw a structured {@link ComplianceError}
+     * if the report is not ok. Useful when callers want exception-flow
+     * handling instead of pattern-matching on a report.
+     */
+    enforce(candidate: ClaimCandidate): void;
+}
+/** Error thrown by {@link ComplianceGuard.enforce}. Carries the full report. */
+export declare class ComplianceError extends Error {
+    readonly report: ComplianceReport;
+    constructor(report: ComplianceReport);
+}
+//# sourceMappingURL=compliance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compliance.d.ts","sourceRoot":"","sources":["../../src/modules/compliance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D,wBAAwB;AACxB,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAExD,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC9B,IAAI,EACA,cAAc,GACd,gBAAgB,GAChB,kBAAkB,GAClB,oBAAoB,GACpB,YAAY,GACZ,YAAY,CAAC;IACjB,MAAM,EAAE,gBAAgB,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,6BAA6B;AAC7B,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,2CAA2C;IAC3C,aAAa,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,SAAS,CAAC,EAAE,uBAAuB,CAAC;CACrC;AAED,6BAA6B;AAC7B,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,aAAa,GAAG,SAAS,CAAC;IAC1C,iDAAiD;IACjD,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,0FAA0F;IAC1F,WAAW,EAAE,MAAM,MAAM,CAAC;IAC1B,qDAAqD;IACrD,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,qDAAqD;IACrD,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,kCAAkC;AAClC,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,sBAAsB;IAE5D;;;;;OAKG;IACH,KAAK,CAAC,SAAS,EAAE,cAAc,GAAG,gBAAgB;IAoBlD,OAAO,CAAC,UAAU;IAyClB,OAAO,CAAC,kBAAkB;IA6B1B,OAAO,CAAC,oBAAoB;IAe5B,OAAO,CAAC,sBAAsB;IAqB9B,OAAO,CAAC,cAAc;IAuBtB,OAAO,CAAC,cAAc;IAmCtB;;;;OAIG;IACH,OAAO,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI;CAMzC;AAED,gFAAgF;AAChF,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;gBACtB,MAAM,EAAE,gBAAgB;CAKrC"}

package/dist/modules/compliance.js

@@ -0,0 +1,227 @@
+/**
+ * Pre-claim compliance guard.
+ *
+ * Before the SDK lets a task claim go to the wire, the guard runs a battery
+ * of client-side checks so the agent gets a structured "why not, and how to
+ * fix" response instead of a 4xx from the control-plane. Server-side is
+ * still authoritative — this is a friendly, fast, informative preflight.
+ *
+ * Six checks, matching T4.3 in the audit doc:
+ * 1. Agent has an active lease for the target workspace.
+ * 2. Spend envelope has room for the task's estimated cost.
+ * 3. Agent's declared `supportedActions` covers the task's required action.
+ * 4. Agent isn't already at its max concurrent in-flight task cap.
+ * 5. Rate limit has headroom (via {@link QuotaClient}).
+ * 6. Trust tier permits this task type.
+ *
+ * @packageDocumentation
+ */
+/** Pre-claim compliance guard. */
+export class ComplianceGuard {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Run every check and return a structured report.
+     *
+     * Never throws — a failed check shows up in `report.checks` and
+     * contributes to `report.ok === false`.
+     */
+    check(candidate) {
+        const checks = [
+            this.checkLease(candidate),
+            this.checkSpendHeadroom(candidate),
+            this.checkCapabilityMatch(candidate),
+            this.checkConcurrencyBudget(),
+            this.checkRateLimit(),
+            this.checkTrustTier(candidate)
+        ];
+        const failures = checks.filter((c) => c.status === "fail");
+        const warnings = checks.filter((c) => c.status === "warn");
+        const ok = failures.length === 0;
+        const summary = ok
+            ? warnings.length > 0
+                ? `pass with ${warnings.length} warn(s): ${warnings.map((w) => w.name).join(", ")}`
+                : "pass"
+            : `fail: ${failures.map((f) => f.name).join(", ")}`;
+        return { ok, checks, failures, summary };
+    }
+    checkLease(candidate) {
+        const lease = this.options.getLease();
+        if (!lease) {
+            return {
+                name: "lease_active",
+                status: "fail",
+                message: "No lease snapshot available for this workspace.",
+                fix: "Request a lease via leases.request() or call quickStart() to bootstrap one."
+            };
+        }
+        if (lease.workspaceSlug && lease.workspaceSlug !== candidate.workspaceSlug) {
+            return {
+                name: "lease_active",
+                status: "fail",
+                message: `Lease is for workspace ${lease.workspaceSlug}, not ${candidate.workspaceSlug}.`,
+                fix: "Request a workspace-scoped lease before claiming tasks here."
+            };
+        }
+        if (lease.status === "revoked" || lease.status === "expired") {
+            return {
+                name: "lease_active",
+                status: "fail",
+                message: `Lease status is "${lease.status}".`,
+                fix: "Enable LeaseManager.enableAutoRenew() or call leases.request() to get a fresh lease."
+            };
+        }
+        if (lease.expiresAt !== undefined) {
+            const expiresAt = typeof lease.expiresAt === "number" ? lease.expiresAt : Date.parse(lease.expiresAt);
+            if (Number.isFinite(expiresAt) && expiresAt - Date.now() < 30_000) {
+                return {
+                    name: "lease_active",
+                    status: "warn",
+                    message: "Lease expires in under 30 seconds.",
+                    fix: "Renew the lease before new claims."
+                };
+            }
+        }
+        return { name: "lease_active", status: "pass" };
+    }
+    checkSpendHeadroom(candidate) {
+        const lease = this.options.getLease();
+        if (!lease || typeof lease.spendCap !== "number" || typeof lease.spendUsed !== "number") {
+            return {
+                name: "spend_headroom",
+                status: "warn",
+                message: "Spend cap / usage unknown — cannot verify headroom."
+            };
+        }
+        const remaining = Math.max(0, lease.spendCap - lease.spendUsed);
+        const estimate = candidate.estimatedSpendUnits ?? 1;
+        if (remaining < estimate) {
+            return {
+                name: "spend_headroom",
+                status: "fail",
+                message: `Need ${estimate} units, only ${remaining} remaining.`,
+                fix: "Top up the spend envelope (billing.createEnvelope) or wait for the next lease window."
+            };
+        }
+        if (remaining - estimate < lease.spendCap * 0.1) {
+            return {
+                name: "spend_headroom",
+                status: "warn",
+                message: `Post-claim headroom will be under 10% of cap.`
+            };
+        }
+        return { name: "spend_headroom", status: "pass" };
+    }
+    checkCapabilityMatch(candidate) {
+        if (!candidate.requiredAction) {
+            return { name: "capability_match", status: "pass" };
+        }
+        if (!this.options.supportedActions.includes(candidate.requiredAction)) {
+            return {
+                name: "capability_match",
+                status: "fail",
+                message: `Task requires "${candidate.requiredAction}" but agent only supports [${this.options.supportedActions.join(", ")}].`,
+                fix: "Re-register the runtime with the required action, or skip tasks that need it."
+            };
+        }
+        return { name: "capability_match", status: "pass" };
+    }
+    checkConcurrencyBudget() {
+        const inFlight = this.options.getInFlight();
+        const cap = this.options.maxConcurrent;
+        if (inFlight >= cap) {
+            return {
+                name: "concurrency_budget",
+                status: "fail",
+                message: `Already at max concurrent tasks (${inFlight}/${cap}).`,
+                fix: "Wait for a task to complete or raise maxConcurrent."
+            };
+        }
+        if (inFlight >= cap - 1) {
+            return {
+                name: "concurrency_budget",
+                status: "warn",
+                message: `One claim away from cap (${inFlight}/${cap}).`
+            };
+        }
+        return { name: "concurrency_budget", status: "pass" };
+    }
+    checkRateLimit() {
+        if (!this.options.quota) {
+            return { name: "rate_limit", status: "pass" };
+        }
+        const plan = this.options.quota.planBatch("task-claim", 1);
+        if (plan.safeToRun === 0) {
+            return {
+                name: "rate_limit",
+                status: "fail",
+                message: `Rate-limited; wait ~${plan.suggestedDelayMs}ms.`,
+                fix: "Call quota.waitForQuota('task-claim') before claiming again."
+            };
+        }
+        if (plan.quota.remaining !== null && plan.quota.remaining < 5) {
+            return {
+                name: "rate_limit",
+                status: "warn",
+                message: `Only ${plan.quota.remaining} claims left in this window.`
+            };
+        }
+        return { name: "rate_limit", status: "pass" };
+    }
+    checkTrustTier(candidate) {
+        if (!this.options.sandbox) {
+            return { name: "trust_tier", status: "pass" };
+        }
+        if (!candidate.workspace) {
+            return {
+                name: "trust_tier",
+                status: "warn",
+                message: "No workspace directory entry provided; trust tier check skipped."
+            };
+        }
+        const eligibility = this.options.sandbox.canJoinWorkspace(candidate.workspace);
+        if (!eligibility.eligible) {
+            return {
+                name: "trust_tier",
+                status: "fail",
+                message: eligibility.message ?? `Ineligible: ${eligibility.reason}`,
+                fix: eligibility.reason === "requires_higher_proof"
+                    ? "Complete wallet verification to reach P2 proof level."
+                    : eligibility.reason === "invite_only"
+                        ? "Request an invite from the workspace governor."
+                        : "Resolve blocking qualifications on your agent passport."
+            };
+        }
+        if (eligibility.reason === "suspended_capability") {
+            return {
+                name: "trust_tier",
+                status: "warn",
+                message: eligibility.message ?? "Some workspace capabilities are suspended."
+            };
+        }
+        return { name: "trust_tier", status: "pass" };
+    }
+    /**
+     * Convenience: run `check` and throw a structured {@link ComplianceError}
+     * if the report is not ok. Useful when callers want exception-flow
+     * handling instead of pattern-matching on a report.
+     */
+    enforce(candidate) {
+        const report = this.check(candidate);
+        if (!report.ok) {
+            throw new ComplianceError(report);
+        }
+    }
+}
+/** Error thrown by {@link ComplianceGuard.enforce}. Carries the full report. */
+export class ComplianceError extends Error {
+    report;
+    constructor(report) {
+        super(`[compliance] ${report.summary}`);
+        this.name = "ComplianceError";
+        this.report = report;
+    }
+}
+//# sourceMappingURL=compliance.js.map

package/dist/modules/compliance.js.map

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

package/dist/modules/cross-plane.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Cross-plane orchestration — unified ShardLink + SignalHub helpers.
+ *
+ * Agents often coordinate two planes:
+ * - **ShardLink** (this repo) — task orchestration, reactions, receipts.
+ * - **SignalHub** — signal marketplace where agents buy/sell data streams.
+ *
+ * The ShardLink control-plane already ships "bridge" endpoints for
+ * cross-plane settlement (`/v1/workspaces/:slug/receipts/bridge`,
+ * `/v1/workspaces/:slug/bridge/health`). This module wraps them, plus a
+ * caller-provided **SignalHub adapter** interface so a host application
+ * can plug its SignalHub SDK in without this package taking a direct
+ * dependency on the separate repo.
+ *
+ * @packageDocumentation
+ */
+import type { HttpContext } from "../utils.js";
+import type { StreamClient } from "./streams.js";
+/** The minimum shape the orchestrator needs from a SignalHub client. */
+export interface SignalHubAdapter {
+    /** Acquire a signal under a contract, returning a settlement handle. */
+    acquireSignal(input: {
+        signalContract: string;
+        budgetUsdCents: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<AcquiredSignal>;
+    /** Optional: stream SignalHub events to merge with the ShardLink feed. */
+    events?(handler: (event: CrossPlaneEvent) => void): () => void;
+}
+/** A signal acquired from SignalHub, ready to be bound to a ShardLink task. */
+export interface AcquiredSignal {
+    /** SignalHub contract identifier. */
+    signalContract: string;
+    /** Receipt id from SignalHub (attached to ShardLink task metadata). */
+    signalReceiptId: string;
+    /** Signed payload the agent can feed into task execution. */
+    payload: unknown;
+    /** How much the signal cost (USD cents). */
+    paidUsdCents: number;
+    /** ISO timestamp when the signal was acquired. */
+    acquiredAt: string;
+}
+/** Input for binding a SignalHub purchase to a ShardLink task. */
+export interface AcquireSignalForTaskInput {
+    signalContract: string;
+    workspaceSlug: string;
+    taskId: string;
+    budgetUsdCents: number;
+    metadata?: Record<string, unknown>;
+}
+/** Result of attaching a SignalHub purchase to a ShardLink task. */
+export interface AcquireSignalForTaskResult {
+    signal: AcquiredSignal;
+    /** The ShardLink bridge receipt (if the workspace emits one for signal binding). */
+    bridgeReceipt?: unknown;
+}
+/** A bridge receipt envelope as returned by ShardLink. */
+export interface BridgeReceiptEnvelope {
+    workspaceSlug: string;
+    receiptId: string;
+    payloadHash: string;
+    bridgeEventVersion: string;
+    hmac?: string;
+    hmacKeyId?: string;
+    [key: string]: unknown;
+}
+/** Unified event merged from both planes. */
+export interface CrossPlaneEvent {
+    plane: "shardlink" | "signalhub";
+    type: string;
+    payload: unknown;
+    at: number;
+}
+/** ShardLink-side status projection for a bridged task. */
+export interface BridgeTaskStatus {
+    task_id: string;
+    objective_id: string;
+    status: string;
+    terminal: boolean;
+    /** Identity that claimed the task, or `null` if unclaimed. */
+    claimed_by: string | null;
+    /** ISO timestamp the claim expires, or `null`. */
+    claim_expires_at: string | null;
+    /** ISO timestamp of the last status change. */
+    updated_at: string;
+}
+/** ShardLink-side status projection for a bridged objective. */
+export interface BridgeObjectiveStatus {
+    objective_id: string;
+    status: string;
+    terminal: boolean;
+    /** ISO timestamp of the last status change. */
+    updated_at: string;
+}
+/** Options for the cross-plane client. */
+export interface CrossPlaneClientOptions {
+    /** ShardLink HTTP context. */
+    http: HttpContext;
+    /**
+     * Actor session token bound to the workspace. The caller scopes this
+     * per-workspace (same pattern as `BillingClient` etc.).
+     */
+    actorSessionToken: string;
+    /** Optional SignalHub adapter — without it, only ShardLink-side methods work. */
+    signalHub?: SignalHubAdapter;
+    /** Optional stream client so `activityFeed` can merge ShardLink events. */
+    shardLinkStream?: StreamClient;
+}
+/** Cross-plane orchestrator. */
+export declare class CrossPlaneClient {
+    private readonly options;
+    constructor(options: CrossPlaneClientOptions);
+    /**
+     * Acquire a signal from SignalHub and bind it to a ShardLink task.
+     *
+     * Requires a `signalHub` adapter to be configured. Throws
+     * {@link SignalHubNotConfiguredError} if one wasn't provided.
+     *
+     * @example
+     * ```ts
+     * const bound = await crossPlane.acquireSignalForTask({
+     *   signalContract: "weather.US-W.v1",
+     *   workspaceSlug: "ws_1",
+     *   taskId: "t_42",
+     *   budgetUsdCents: 250
+     * });
+     * ```
+     */
+    acquireSignalForTask(input: AcquireSignalForTaskInput): Promise<AcquireSignalForTaskResult>;
+    /** List bridge receipts for a workspace (paginated). */
+    listBridgeReceipts(input: {
+        workspaceSlug: string;
+        cursor?: number;
+        limit?: number;
+    }): Promise<BridgeReceiptEnvelope[]>;
+    /** Fetch a single bridge receipt by id. */
+    getBridgeReceipt(input: {
+        workspaceSlug: string;
+        receiptId: string;
+    }): Promise<BridgeReceiptEnvelope>;
+    /** Fetch the ShardLink-side status projection for a task (bridge-aware). */
+    getTaskStatus(workspaceSlug: string, taskId: string): Promise<BridgeTaskStatus>;
+    /** Fetch the ShardLink-side status projection for an objective. */
+    getObjectiveStatus(workspaceSlug: string, objectiveId: string): Promise<BridgeObjectiveStatus>;
+    /** Bridge health probe — quick confirmation ShardLink ↔ SignalHub are linked. */
+    bridgeHealth(workspaceSlug: string): Promise<Record<string, unknown>>;
+    /**
+     * Unified activity feed — merges ShardLink stream events with SignalHub
+     * events (if the adapter exposes them) into a single async iterable.
+     *
+     * @example
+     * ```ts
+     * for await (const event of crossPlane.activityFeed()) {
+     *   console.log(event.plane, event.type, event.payload);
+     * }
+     * ```
+     */
+    activityFeed(): AsyncIterable<CrossPlaneEvent>;
+}
+/** Thrown when a SignalHub-requiring method is called without an adapter. */
+export declare class SignalHubNotConfiguredError extends Error {
+    constructor();
+}
+//# sourceMappingURL=cross-plane.d.ts.map

package/dist/modules/cross-plane.d.ts.map

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