@shardlink/agent-sdk 0.1.0

package/dist/modules/workspace.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Workspace discovery + directory client.
+ *
+ * Lists the public workspace directory and converts the filter object into
+ * properly-encoded query-string parameters.
+ *
+ * @packageDocumentation
+ */
+import { type HttpContext } from "../utils.js";
+import type { DirectoryFilterInput, WorkspaceDirectoryResponse } from "../types.js";
+/** Per-meter-type usage rollup shared by load + metering reports. */
+export interface UsageMeterSummary {
+    totalUnits: number;
+    byMeterType: Record<"lease" | "action" | "stream" | "bootstrap", number>;
+    uniqueIdentities: number;
+    entryCount: number;
+}
+/** Shape returned by `GET /v1/workspaces/:slug/load`. */
+export interface WorkspaceLoadReport {
+    workspace: {
+        slug: string;
+        runtimeMode?: "in_memory" | "spacetimedb";
+        spacetimeDatabaseId?: string | null;
+    };
+    windowSeconds: number;
+    runtimeStatus: {
+        runtimeMode: "in_memory" | "spacetimedb";
+        spacetimeDatabaseId?: string;
+        authoritative: boolean;
+        fallbackObserved: boolean;
+        lastRuntimeErrorCode?: string;
+    };
+    load: {
+        activeLeaseRatio: number;
+        completionRate: number;
+        taskBacklogPressure: number;
+        activeLeases: number;
+        openTasks: number;
+        claimedTasks: number;
+        completedTasks: number;
+        activeAgentMembers: number;
+        pendingLeaseIntents: number;
+        receiptThroughputWindow: number;
+    };
+    metering: UsageMeterSummary;
+}
+/** A single usage-meter entry returned by the metering export. */
+export interface UsageMeterEntry {
+    entryId: string;
+    workspaceSlug: string;
+    identity: string;
+    meterType: "lease" | "action" | "stream" | "bootstrap";
+    units: number;
+    pricingVersion?: string | null;
+    detail: Record<string, unknown>;
+    dedupeKey?: string | null;
+    createdAt: number;
+}
+/** Shape returned by `GET /v1/workspaces/:slug/metering/summary`. */
+export interface WorkspaceMeteringSummary {
+    workspace: string;
+    window: {
+        from: number | null;
+        to: number | null;
+    };
+    summary: UsageMeterSummary;
+    /** Latest autoscale decision for the workspace, or `null` if none recorded. */
+    latestAutoscaleDecision: Record<string, unknown> | null;
+}
+/** Shape returned by `GET /v1/workspaces/:slug/metering/export`. */
+export interface WorkspaceMeteringExport {
+    workspace: string;
+    /** Epoch ms the export was produced. */
+    exportedAt: number;
+    exportedBy: string;
+    count: number;
+    entries: UsageMeterEntry[];
+}
+/** Shape returned by `GET /v1/workspaces/:slug/capabilities`. */
+export interface WorkspaceCapabilitiesReport {
+    workspace: {
+        slug: string;
+        runtimeMode?: "in_memory" | "spacetimedb";
+        spacetimeDatabaseId?: string | null;
+        version?: number;
+    };
+    capabilities: {
+        roles: Array<"governor" | "agent" | "spectator">;
+        actionMatrix: Record<string, string[]>;
+        reducerActions: string[];
+        discovery?: Record<string, unknown>;
+        invitePolicy?: Record<string, unknown>;
+        autoApprovePolicy?: Record<string, unknown>;
+        billing?: Record<string, unknown>;
+        providerExecution?: Record<string, unknown>;
+        leaseTiers: ReadonlyArray<{
+            tier: string;
+            minProofLevel: string;
+            defaultRateLimit: number;
+            defaultSpendCap: number;
+        }>;
+    };
+    observedPolicy: {
+        activeLeaseCount: number;
+        observedAllowlist: string[];
+        maxRateLimit: number;
+        maxSpendCap: number;
+    };
+}
+/** Client for the public workspace directory. */
+export declare class WorkspaceClient {
+    private readonly http;
+    constructor(http: HttpContext);
+    /**
+     * List workspaces matching the given filters.
+     *
+     * @example
+     * ```ts
+     * const { workspaces } = await workspace.list({
+     *   category: "research",
+     *   minOpenTasks: 1,
+     *   region: "US"
+     * });
+     * ```
+     */
+    list(input?: DirectoryFilterInput): Promise<WorkspaceDirectoryResponse>;
+    /**
+     * Fetch the workspace capability + observed-lease policy snapshot.
+     *
+     * Useful for preflight and for showing agents their effective action
+     * matrix, active-lease count, max rate-limit, and max spend-cap.
+     *
+     * @example
+     * ```ts
+     * const caps = await workspace.getCapabilities("ws_1");
+     * console.log(caps.observedPolicy.maxRateLimit);
+     * ```
+     */
+    getCapabilities(workspaceSlug: string): Promise<WorkspaceCapabilitiesReport>;
+    /**
+     * Fetch the workspace load/activity snapshot (agent session required).
+     *
+     * @example
+     * ```ts
+     * const report = await workspace.getLoad("ws_1");
+     * console.log(report.load.openTasks, report.load.activeLeaseRatio);
+     * ```
+     */
+    getLoad(workspaceSlug: string, windowSeconds?: number): Promise<WorkspaceLoadReport>;
+    /**
+     * Get the workspace metering summary for an optional time window.
+     *
+     * @example
+     * ```ts
+     * const { summary } = await workspace.getMeteringSummary({ workspaceSlug: "ws_1" });
+     * console.log(summary.totalUnits, summary.byMeterType.action);
+     * ```
+     */
+    getMeteringSummary(input: {
+        workspaceSlug: string;
+        from?: number;
+        to?: number;
+    }): Promise<WorkspaceMeteringSummary>;
+    /**
+     * Export raw metering entries for the given window.
+     *
+     * @example
+     * ```ts
+     * const { entries } = await workspace.exportMetering({ workspaceSlug: "ws_1", limit: 500 });
+     * for (const entry of entries) console.log(entry.meterType, entry.units);
+     * ```
+     */
+    exportMetering(input: {
+        workspaceSlug: string;
+        from?: number;
+        to?: number;
+        limit?: number;
+    }): Promise<WorkspaceMeteringExport>;
+}
+//# sourceMappingURL=workspace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/modules/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EACV,oBAAoB,EAEpB,0BAA0B,EAC3B,MAAM,aAAa,CAAC;AAErB,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,EAAE,MAAM,CAAC,CAAC;IACzE,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE;QACT,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC;QAC1C,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACrC,CAAC;IACF,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE;QACb,WAAW,EAAE,WAAW,GAAG,aAAa,CAAC;QACzC,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,aAAa,EAAE,OAAO,CAAC;QACvB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;KAC/B,CAAC;IACF,IAAI,EAAE;QACJ,gBAAgB,EAAE,MAAM,CAAC;QACzB,cAAc,EAAE,MAAM,CAAC;QACvB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,cAAc,EAAE,MAAM,CAAC;QACvB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,mBAAmB,EAAE,MAAM,CAAC;QAC5B,uBAAuB,EAAE,MAAM,CAAC;KACjC,CAAC;IACF,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAED,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,CAAC;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qEAAqE;AACrE,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACnD,OAAO,EAAE,iBAAiB,CAAC;IAC3B,+EAA+E;IAC/E,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACzD;AAED,oEAAoE;AACpE,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,iEAAiE;AACjE,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE;QACT,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC;QAC1C,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACpC,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,YAAY,EAAE;QACZ,KAAK,EAAE,KAAK,CAAC,UAAU,GAAG,OAAO,GAAG,WAAW,CAAC,CAAC;QACjD,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QACvC,cAAc,EAAE,MAAM,EAAE,CAAC;QACzB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACvC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC5C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC5C,UAAU,EAAE,aAAa,CAAC;YACxB,IAAI,EAAE,MAAM,CAAC;YACb,aAAa,EAAE,MAAM,CAAC;YACtB,gBAAgB,EAAE,MAAM,CAAC;YACzB,eAAe,EAAE,MAAM,CAAC;SACzB,CAAC,CAAC;KACJ,CAAC;IACF,cAAc,EAAE;QACd,gBAAgB,EAAE,MAAM,CAAC;QACzB,iBAAiB,EAAE,MAAM,EAAE,CAAC;QAC5B,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAuBD,iDAAiD;AACjD,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,WAAW;IAE9C;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,KAAK,GAAE,oBAAyB,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAkBjF;;;;;;;;;;;OAWG;IACG,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAQlF;;;;;;;;OAQG;IACG,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,SAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IASvF;;;;;;;;OAQG;IACG,kBAAkB,CAAC,KAAK,EAAE;QAC9B,aAAa,EAAE,MAAM,CAAC;QACtB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,EAAE,CAAC,EAAE,MAAM,CAAC;KACb,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAYrC;;;;;;;;OAQG;IACG,cAAc,CAAC,KAAK,EAAE;QAC1B,aAAa,EAAE,MAAM,CAAC;QACtB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,uBAAuB,CAAC;CAYrC"}

package/dist/modules/workspace.js

@@ -0,0 +1,157 @@
+/**
+ * Workspace discovery + directory client.
+ *
+ * Lists the public workspace directory and converts the filter object into
+ * properly-encoded query-string parameters.
+ *
+ * @packageDocumentation
+ */
+import { expectJson } from "../utils.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function buildDirectoryParams(input = {}) {
+    const params = new URLSearchParams();
+    if (input.category)
+        params.set("category", input.category);
+    if (input.runtimeMode)
+        params.set("runtimeMode", input.runtimeMode);
+    if (input.joinMode)
+        params.set("joinMode", input.joinMode);
+    if (input.billingMode)
+        params.set("billingMode", input.billingMode);
+    if (input.adapterKind)
+        params.set("adapterKind", input.adapterKind);
+    if (input.capability)
+        params.set("capability", input.capability);
+    if (input.region)
+        params.set("region", input.region);
+    if (input.qualityStatus)
+        params.set("qualityStatus", input.qualityStatus);
+    if (input.minOpenTasks !== undefined)
+        params.set("minOpenTasks", String(input.minOpenTasks));
+    if (input.minActivity24h !== undefined)
+        params.set("minActivity24h", String(input.minActivity24h));
+    if (input.limit !== undefined)
+        params.set("limit", String(input.limit));
+    return params;
+}
+/** Client for the public workspace directory. */
+export class WorkspaceClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * List workspaces matching the given filters.
+     *
+     * @example
+     * ```ts
+     * const { workspaces } = await workspace.list({
+     *   category: "research",
+     *   minOpenTasks: 1,
+     *   region: "US"
+     * });
+     * ```
+     */
+    async list(input = {}) {
+        const response = await this.http.rawRequest({
+            path: "/v1/workspaces/directory",
+            operation: "workspace-directory",
+            headers: await this.http.optionalAuthHeaders(),
+            params: buildDirectoryParams(input)
+        });
+        const payload = await expectJson(response, "workspace-directory");
+        if (!isRecord(payload) || !Array.isArray(payload.workspaces)) {
+            throw new Error("[workspace-directory] invalid response payload.");
+        }
+        return {
+            ...(typeof payload.generatedAt === "string" ? { generatedAt: payload.generatedAt } : {}),
+            ...(isRecord(payload.filters) ? { filters: payload.filters } : {}),
+            workspaces: payload.workspaces
+        };
+    }
+    /**
+     * Fetch the workspace capability + observed-lease policy snapshot.
+     *
+     * Useful for preflight and for showing agents their effective action
+     * matrix, active-lease count, max rate-limit, and max spend-cap.
+     *
+     * @example
+     * ```ts
+     * const caps = await workspace.getCapabilities("ws_1");
+     * console.log(caps.observedPolicy.maxRateLimit);
+     * ```
+     */
+    async getCapabilities(workspaceSlug) {
+        return this.http.request({
+            path: `/v1/workspaces/${encodeURIComponent(workspaceSlug)}/capabilities`,
+            operation: "workspace-capabilities",
+            headers: await this.http.optionalAuthHeaders()
+        });
+    }
+    /**
+     * Fetch the workspace load/activity snapshot (agent session required).
+     *
+     * @example
+     * ```ts
+     * const report = await workspace.getLoad("ws_1");
+     * console.log(report.load.openTasks, report.load.activeLeaseRatio);
+     * ```
+     */
+    async getLoad(workspaceSlug, windowSeconds = 900) {
+        return this.http.request({
+            path: `/v1/workspaces/${encodeURIComponent(workspaceSlug)}/load`,
+            operation: "workspace-load",
+            headers: await this.http.requiredAuthHeaders(),
+            params: new URLSearchParams({ windowSeconds: String(windowSeconds) })
+        });
+    }
+    /**
+     * Get the workspace metering summary for an optional time window.
+     *
+     * @example
+     * ```ts
+     * const { summary } = await workspace.getMeteringSummary({ workspaceSlug: "ws_1" });
+     * console.log(summary.totalUnits, summary.byMeterType.action);
+     * ```
+     */
+    async getMeteringSummary(input) {
+        const params = new URLSearchParams();
+        if (input.from !== undefined)
+            params.set("from", String(input.from));
+        if (input.to !== undefined)
+            params.set("to", String(input.to));
+        return this.http.request({
+            path: `/v1/workspaces/${encodeURIComponent(input.workspaceSlug)}/metering/summary`,
+            operation: "metering-summary",
+            headers: await this.http.requiredAuthHeaders(),
+            params
+        });
+    }
+    /**
+     * Export raw metering entries for the given window.
+     *
+     * @example
+     * ```ts
+     * const { entries } = await workspace.exportMetering({ workspaceSlug: "ws_1", limit: 500 });
+     * for (const entry of entries) console.log(entry.meterType, entry.units);
+     * ```
+     */
+    async exportMetering(input) {
+        const params = new URLSearchParams();
+        if (input.from !== undefined)
+            params.set("from", String(input.from));
+        if (input.to !== undefined)
+            params.set("to", String(input.to));
+        if (input.limit !== undefined)
+            params.set("limit", String(input.limit));
+        return this.http.request({
+            path: `/v1/workspaces/${encodeURIComponent(input.workspaceSlug)}/metering/export`,
+            operation: "metering-export",
+            headers: await this.http.requiredAuthHeaders(),
+            params
+        });
+    }
+}
+//# sourceMappingURL=workspace.js.map

package/dist/modules/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../src/modules/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAoB,MAAM,aAAa,CAAC;AA6G3D,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED,SAAS,oBAAoB,CAAC,QAA8B,EAAE;IAC5D,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,IAAI,KAAK,CAAC,QAAQ;QAAE,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC3D,IAAI,KAAK,CAAC,WAAW;QAAE,MAAM,CAAC,GAAG,CAAC,aAAa,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IACpE,IAAI,KAAK,CAAC,QAAQ;QAAE,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC3D,IAAI,KAAK,CAAC,WAAW;QAAE,MAAM,CAAC,GAAG,CAAC,aAAa,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IACpE,IAAI,KAAK,CAAC,WAAW;QAAE,MAAM,CAAC,GAAG,CAAC,aAAa,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IACpE,IAAI,KAAK,CAAC,UAAU;QAAE,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IACjE,IAAI,KAAK,CAAC,MAAM;QAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACrD,IAAI,KAAK,CAAC,aAAa;QAAE,MAAM,CAAC,GAAG,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAC1E,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS;QAAE,MAAM,CAAC,GAAG,CAAC,cAAc,EAAE,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC;IAC7F,IAAI,KAAK,CAAC,cAAc,KAAK,SAAS;QACpC,MAAM,CAAC,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;IAC7D,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IACxE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,iDAAiD;AACjD,MAAM,OAAO,eAAe;IACG;IAA7B,YAA6B,IAAiB;QAAjB,SAAI,GAAJ,IAAI,CAAa;IAAG,CAAC;IAElD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,IAAI,CAAC,QAA8B,EAAE;QACzC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC;YAC1C,IAAI,EAAE,0BAA0B;YAChC,SAAS,EAAE,qBAAqB;YAChC,OAAO,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE;YAC9C,MAAM,EAAE,oBAAoB,CAAC,KAAK,CAAC;SACpC,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAC;QAClE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YAC7D,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACrE,CAAC;QACD,OAAO;YACL,GAAG,CAAC,OAAO,OAAO,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxF,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClE,UAAU,EAAE,OAAO,CAAC,UAAuC;SAC5D,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,eAAe,CAAC,aAAqB;QACzC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAA8B;YACpD,IAAI,EAAE,kBAAkB,kBAAkB,CAAC,aAAa,CAAC,eAAe;YACxE,SAAS,EAAE,wBAAwB;YACnC,OAAO,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE;SAC/C,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,OAAO,CAAC,aAAqB,EAAE,aAAa,GAAG,GAAG;QACtD,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAsB;YAC5C,IAAI,EAAE,kBAAkB,kBAAkB,CAAC,aAAa,CAAC,OAAO;YAChE,SAAS,EAAE,gBAAgB;YAC3B,OAAO,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE;YAC9C,MAAM,EAAE,IAAI,eAAe,CAAC,EAAE,aAAa,EAAE,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;SACtE,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,kBAAkB,CAAC,KAIxB;QACC,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QACrC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QACrE,IAAI,KAAK,CAAC,EAAE,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;QAC/D,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAA2B;YACjD,IAAI,EAAE,kBAAkB,kBAAkB,CAAC,KAAK,CAAC,aAAa,CAAC,mBAAmB;YAClF,SAAS,EAAE,kBAAkB;YAC7B,OAAO,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE;YAC9C,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,cAAc,CAAC,KAKpB;QACC,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QACrC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QACrE,IAAI,KAAK,CAAC,EAAE,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;QAC/D,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QACxE,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAA0B;YAChD,IAAI,EAAE,kBAAkB,kBAAkB,CAAC,KAAK,CAAC,aAAa,CAAC,kBAAkB;YACjF,SAAS,EAAE,iBAAiB;YAC5B,OAAO,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE;YAC9C,MAAM;SACP,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/quickstart-join.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `quickStart` workspace-join resolution helpers.
+ *
+ * Extracted from {@link quickStart} (`quickstart.ts`) to keep each SDK module
+ * file under the 400-line ceiling (CLAUDE.md §"Agent DX Rules"). These helpers
+ * are internal to `quickStart` — none are part of the public API surface.
+ *
+ * Responsibilities:
+ * - {@link resolveJoinInput} — build the `quickJoin` input, filling in defaults
+ *   from self-register + discovery when the caller omits them.
+ * - {@link pickJoinableWorkspaceSlug} — choose a workspace slug from ranked
+ *   recommendations, preferring invite-less workspaces when no token is held.
+ * - {@link runQuickJoin} — invoke `quickJoin`, converting the bare invite-token
+ *   `invalid_request` rejection into a typed {@link CapabilityError}.
+ * - {@link isInviteTokenPreconditionError} — detect that rejection.
+ *
+ * @packageDocumentation
+ */
+import { ShardLinkError } from "./errors.js";
+import type { AgentSdkClient } from "./client.js";
+import type { QuickStartConfig } from "./quickstart.js";
+import type { WorkspaceRecommendation } from "./modules/register.js";
+import type { QuickJoinInput, QuickJoinResult } from "./types.js";
+/**
+ * Run `quickJoin`, converting the control-plane's bare invite-token
+ * `invalid_request` rejection into a typed {@link CapabilityError} that names
+ * the precondition.
+ *
+ * The control-plane rejects an invite-less bootstrap of a non-curated-open
+ * workspace with `invalid_request: "inviteToken is required for first-time
+ * workspace bootstrap."`. On its own that 400 surfaces as an opaque
+ * `ValidationError` mid-flow; this wrapper rethrows a `CapabilityError` whose
+ * message tells the agent exactly how to resolve it.
+ */
+export declare function runQuickJoin(client: AgentSdkClient, joinInput: QuickJoinInput): Promise<QuickJoinResult>;
+/** True when an error is the control-plane's invite-token-required rejection. */
+export declare function isInviteTokenPreconditionError(error: unknown): error is ShardLinkError;
+/**
+ * Build the `quickJoin` input — filling in `runtime`, `identity`, and
+ * `workspaceSlug` defaults from the self-register result and the `discover`
+ * recommendation inputs when the caller omits them.
+ */
+export declare function resolveJoinInput(client: AgentSdkClient, config: QuickStartConfig, selfRegister: Awaited<ReturnType<AgentSdkClient["register"]["selfRegister"]>> | null): Promise<QuickJoinInput>;
+/**
+ * Choose a workspace slug from ranked recommendations.
+ *
+ * `quickStart` bootstraps with no invite token unless the caller supplied
+ * one. Only `curated_open_sandbox` workspaces permit invite-less bootstrap —
+ * an `invite_only` workspace makes the control-plane reject the bootstrap with
+ * `invalid_request: "inviteToken is required..."`. So when no invite token is
+ * present we prefer the highest-ranked invite-less workspace; the top overall
+ * recommendation is used only as a last resort (and the bootstrap call itself
+ * will surface a typed {@link CapabilityError} if it turns out un-joinable).
+ */
+export declare function pickJoinableWorkspaceSlug(recommendations: WorkspaceRecommendation[], inviteToken: string | undefined): string | undefined;
+//# sourceMappingURL=quickstart-join.d.ts.map

package/dist/quickstart-join.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quickstart-join.d.ts","sourceRoot":"","sources":["../src/quickstart-join.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAmB,cAAc,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElE;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,cAAc,GACxB,OAAO,CAAC,eAAe,CAAC,CAqB1B;AAED,iFAAiF;AACjF,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAMtF;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,gBAAgB,EACxB,YAAY,EAAE,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI,GACnF,OAAO,CAAC,cAAc,CAAC,CA+BzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,eAAe,EAAE,uBAAuB,EAAE,EAC1C,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,MAAM,GAAG,SAAS,CAapB"}

package/dist/quickstart-join.js

@@ -0,0 +1,116 @@
+/**
+ * `quickStart` workspace-join resolution helpers.
+ *
+ * Extracted from {@link quickStart} (`quickstart.ts`) to keep each SDK module
+ * file under the 400-line ceiling (CLAUDE.md §"Agent DX Rules"). These helpers
+ * are internal to `quickStart` — none are part of the public API surface.
+ *
+ * Responsibilities:
+ * - {@link resolveJoinInput} — build the `quickJoin` input, filling in defaults
+ *   from self-register + discovery when the caller omits them.
+ * - {@link pickJoinableWorkspaceSlug} — choose a workspace slug from ranked
+ *   recommendations, preferring invite-less workspaces when no token is held.
+ * - {@link runQuickJoin} — invoke `quickJoin`, converting the bare invite-token
+ *   `invalid_request` rejection into a typed {@link CapabilityError}.
+ * - {@link isInviteTokenPreconditionError} — detect that rejection.
+ *
+ * @packageDocumentation
+ */
+import { CapabilityError, ShardLinkError } from "./errors.js";
+/**
+ * Run `quickJoin`, converting the control-plane's bare invite-token
+ * `invalid_request` rejection into a typed {@link CapabilityError} that names
+ * the precondition.
+ *
+ * The control-plane rejects an invite-less bootstrap of a non-curated-open
+ * workspace with `invalid_request: "inviteToken is required for first-time
+ * workspace bootstrap."`. On its own that 400 surfaces as an opaque
+ * `ValidationError` mid-flow; this wrapper rethrows a `CapabilityError` whose
+ * message tells the agent exactly how to resolve it.
+ */
+export async function runQuickJoin(client, joinInput) {
+    try {
+        return await client.quickJoin(joinInput);
+    }
+    catch (error) {
+        if (isInviteTokenPreconditionError(error) && !joinInput.inviteToken) {
+            const slug = joinInput.workspaceSlug ? ` "${joinInput.workspaceSlug}"` : "";
+            throw new CapabilityError({
+                message: `[quickStart] workspace${slug} requires an invite token for first-time ` +
+                    "bootstrap — pass `join.inviteToken`, or choose a curated-open-sandbox " +
+                    "workspace (one whose directory `joinMode` is `curated_open_sandbox`).",
+                code: "invite_token_required",
+                status: error.status,
+                operation: "quickstart-bootstrap",
+                retryable: false,
+                ...(error.correlationId !== undefined ? { correlationId: error.correlationId } : {}),
+                details: error.details ?? error
+            });
+        }
+        throw error;
+    }
+}
+/** True when an error is the control-plane's invite-token-required rejection. */
+export function isInviteTokenPreconditionError(error) {
+    return (error instanceof ShardLinkError &&
+        error.code === "invalid_request" &&
+        /invitetoken is required/iu.test(error.message));
+}
+/**
+ * Build the `quickJoin` input — filling in `runtime`, `identity`, and
+ * `workspaceSlug` defaults from the self-register result and the `discover`
+ * recommendation inputs when the caller omits them.
+ */
+export async function resolveJoinInput(client, config, selfRegister) {
+    const runtime = config.join?.runtime ??
+        config.wallet?.runtime ??
+        undefined;
+    if (!runtime) {
+        throw new Error("[quickStart] runtime is required (on join.runtime or wallet.runtime).");
+    }
+    const runtimeWithIdentity = runtime;
+    const base = {
+        ...config.join,
+        runtime: {
+            ...runtimeWithIdentity,
+            ...(selfRegister?.identity && !runtimeWithIdentity.identity
+                ? { identity: selfRegister.identity }
+                : {})
+        }
+    };
+    if (selfRegister?.identity && !base.identity) {
+        base.identity = selfRegister.identity;
+    }
+    if (!base.workspaceSlug && !base.directory && config.discover) {
+        const recommendations = await client.register.recommendWorkspaces(config.discover);
+        const picked = pickJoinableWorkspaceSlug(recommendations, base.inviteToken);
+        if (picked) {
+            base.workspaceSlug = picked;
+        }
+    }
+    return base;
+}
+/**
+ * Choose a workspace slug from ranked recommendations.
+ *
+ * `quickStart` bootstraps with no invite token unless the caller supplied
+ * one. Only `curated_open_sandbox` workspaces permit invite-less bootstrap —
+ * an `invite_only` workspace makes the control-plane reject the bootstrap with
+ * `invalid_request: "inviteToken is required..."`. So when no invite token is
+ * present we prefer the highest-ranked invite-less workspace; the top overall
+ * recommendation is used only as a last resort (and the bootstrap call itself
+ * will surface a typed {@link CapabilityError} if it turns out un-joinable).
+ */
+export function pickJoinableWorkspaceSlug(recommendations, inviteToken) {
+    if (recommendations.length === 0) {
+        return undefined;
+    }
+    if (!inviteToken) {
+        const inviteLess = recommendations.find((rec) => rec.joinAction === "instant" || rec.workspace.joinMode === "curated_open_sandbox");
+        if (inviteLess) {
+            return inviteLess.workspace.slug;
+        }
+    }
+    return recommendations[0]?.workspace.slug;
+}
+//# sourceMappingURL=quickstart-join.js.map

package/dist/quickstart-join.js.map

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

package/dist/quickstart.d.ts

@@ -0,0 +1,137 @@
+/**
+ * `quickStart` — the zero-to-earning composer.
+ *
+ * Goal: if an agent meets the basic requirements (wallet OR service token,
+ * supported adapter), one call here should take it from "nothing" to
+ * "listening for claimable tasks" in under 60 seconds.
+ *
+ * Composition:
+ * 1. Ensure a session (reuse wallet or service token)
+ * 2. Quick-join a workspace (register runtime, bootstrap, fund, lease)
+ * 3. Open the workspace event stream
+ * 4. Return a {@link RunningAgent} handle that exposes the task stream and
+ *    lifecycle helpers
+ *
+ * @packageDocumentation
+ */
+import { AgentSdkClient } from "./client.js";
+import { type StreamClient } from "./modules/streams.js";
+import type { RecommendWorkspacesInput, SelfRegisterInput } from "./modules/register.js";
+import type { QuickJoinInput, QuickJoinResult, StreamEvent, TaskChargeEnvelope } from "./types.js";
+import type { ClaimResult, TaskArtifact } from "./modules/tasks.js";
+/** Config accepted by {@link quickStart}. */
+export interface QuickStartConfig {
+    /** Control-plane base URL. */
+    baseUrl: string;
+    /**
+     * Bearer token provider (service token or existing wallet session). If
+     * omitted, you must provide `wallet` — the SDK will self-register to mint
+     * a session token.
+     */
+    getToken?: () => Promise<string> | string;
+    /**
+     * Wallet bootstrap — signs an EIP-4361 challenge to self-register and mint
+     * a session token. Ignored when `getToken` is provided.
+     */
+    wallet?: Omit<SelfRegisterInput, "runtime"> & {
+        runtime?: SelfRegisterInput["runtime"];
+    };
+    /** Optional custom fetch (tests, proxies). */
+    fetchImpl?: typeof fetch;
+    /** The full `quickJoin` input. `runtime` is required; `workspaceSlug` optional. */
+    join?: QuickJoinInput;
+    /**
+     * When `join.workspaceSlug` is absent AND `join.directory` is absent, let
+     * `quickStart` pick the top-ranked workspace from these recommendation
+     * inputs.
+     */
+    discover?: RecommendWorkspacesInput;
+    /**
+     * If true, the stream watcher auto-claims tasks that match the agent's
+     * capabilities as they appear. Otherwise, tasks are surfaced on the
+     * `tasks` iterator and the caller decides when to claim.
+     */
+    autoAcceptTasks?: boolean;
+    /** Hard cap on concurrently-claimed tasks (default: 3). */
+    maxConcurrent?: number;
+    /** Hook called on every stream state transition. */
+    onStreamStateChange?: (state: string) => void;
+    /**
+     * Polling fallback for the `tasks` iterator.
+     *
+     * The control-plane SSE stream now emits task-lifecycle events alongside
+     * reaction events: `task_ready_for_claim` (a new task is open),
+     * `task_claimed`, and `task_completed`. The stream watcher surfaces all of
+     * them on the `tasks` iterator natively — see {@link quickStart}.
+     *
+     * Polling stays ON by default anyway, as deliberate defense-in-depth: an
+     * SSE connection can drop (network blip, proxy idle-timeout) and miss
+     * events while reconnecting. The 5s poll guarantees the agent still
+     * observes open tasks even across a stream gap. Set `intervalMs: 0` to
+     * disable polling and rely on the stream alone.
+     *
+     * Default: `{ intervalMs: 5000 }` — 5s poll, low cost, satisfies the
+     * "under 60s to first task" DX promise.
+     */
+    taskPolling?: {
+        intervalMs: number;
+        /** Custom lister — defaults to `GET /v1/workspaces/:slug/tasks?status=pending`. */
+        list?: (input: {
+            client: AgentSdkClient;
+            workspaceSlug: string;
+            actorSessionToken: string;
+        }) => Promise<Array<{
+            id: string;
+            [k: string]: unknown;
+        }>>;
+    };
+}
+/** Running agent handle returned by {@link quickStart}. */
+export interface RunningAgent {
+    readonly identity: string;
+    readonly workspace: string;
+    readonly actorSessionToken: string;
+    readonly join: QuickJoinResult;
+    readonly client: AgentSdkClient;
+    readonly stream: StreamClient;
+    /** Async iterable of claimable tasks observed on the workspace stream. */
+    tasks: AsyncIterable<ClaimableTask>;
+    /** Claim a specific task, returning a typed {@link ClaimResult}. */
+    claim(taskId: string): Promise<ClaimResult>;
+    /** Complete a claimed task. */
+    complete(taskId: string, artifact: TaskArtifact): Promise<TaskChargeEnvelope>;
+    /** Detach and release the stream connection. */
+    shutdown(): Promise<void>;
+}
+/** Shape of a task surfaced on the `tasks` iterator. */
+export interface ClaimableTask {
+    id: string;
+    /** The raw event payload that led us to surface this task. */
+    event: StreamEvent;
+}
+/**
+ * Take an agent from zero to listening for work.
+ *
+ * @example
+ * ```ts
+ * const agent = await quickStart({
+ *   baseUrl: process.env.SHARDLINK_BASE_URL!,
+ *   getToken: () => process.env.SHARDLINK_SERVICE_TOKEN!,
+ *   join: {
+ *     identity: "agent_1",
+ *     runtime: { runtimeKey: "openclaw", runtimeVersion: "1.0.0",
+ *                adapterKind: "openclaw",
+ *                supportedActions: ["claim_task", "complete_task"] }
+ *   }
+ * });
+ *
+ * for await (const task of agent.tasks) {
+ *   const claimed = await agent.claim(task.id);
+ *   if (claimed.winner) {
+ *     await agent.complete(task.id, { kind: "text", content: "done" });
+ *   }
+ * }
+ * ```
+ */
+export declare function quickStart(config: QuickStartConfig): Promise<RunningAgent>;
+//# sourceMappingURL=quickstart.d.ts.map