@shardlink/agent-sdk 0.1.0

package/dist/modules/quota.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Rate-limit awareness.
+ *
+ * The ShardLink control-plane enforces per-route rate limits and returns
+ * `429` with a `Retry-After` header when an agent is throttled, but it
+ * does not currently emit proactive `X-RateLimit-*` headers. The
+ * {@link QuotaClient} handles this reality in two ways:
+ *
+ * - **Observed state**: Every {@link RateLimitError} the SDK throws is fed
+ *   back into the client so future calls can read "how long since last
+ *   throttle" and "how long until `retry-after` elapses" without hitting
+ *   the server again.
+ * - **Lease-derived quota**: Workspace lease state (via
+ *   {@link LeaseSnapshot}) reports `rateLimit` + `actionCount`, which
+ *   reflects the workspace-level action allowance. `check()` reads from
+ *   the lease when available.
+ *
+ * `waitForQuota()` sleeps until the last known throttle window clears so
+ * callers don't have to juggle timers themselves.
+ *
+ * @packageDocumentation
+ */
+import type { LeaseSnapshot } from "./lease-manager.js";
+/** Observed state for a specific operation. */
+export interface QuotaInfo {
+    /** Operation key (e.g. `"task-claim"`). */
+    operation: string;
+    /** Remaining budget — from lease snapshot when available, else `null`. */
+    remaining: number | null;
+    /** Cap — from lease snapshot when available, else `null`. */
+    limit: number | null;
+    /** Timestamp (ms) when the last observed throttle window clears. */
+    resetsAt: number | null;
+    /** True when the last request in this window returned 429. */
+    throttled: boolean;
+    /** Time (ms) since the client last observed this operation. */
+    lastObservedMsAgo: number | null;
+}
+/** Per-operation batch plan. */
+export interface BatchPlan {
+    /** The operation being planned. */
+    operation: string;
+    /** How many ops the planner thinks are safe to run right now. */
+    safeToRun: number;
+    /** Estimated ms to wait before attempting the remainder. */
+    suggestedDelayMs: number;
+    /** Underlying info used to build the plan. */
+    quota: QuotaInfo;
+}
+/** Accessors for the current lease snapshot. */
+export type LeaseSource = () => LeaseSnapshot | undefined;
+/** Options for the quota client. */
+export interface QuotaClientOptions {
+    /**
+     * How to read the current lease snapshot. Typically returns the snapshot
+     * held by a {@link LeaseManager}; return `undefined` when no lease is
+     * active.
+     */
+    getLease?: LeaseSource;
+}
+/** Observed rate-limit state tracker. */
+export declare class QuotaClient {
+    private readonly options;
+    private readonly observations;
+    constructor(options?: QuotaClientOptions);
+    /**
+     * Record an observation. Call this after every request so the client can
+     * reason about quota without polling. `error` should be the thrown
+     * {@link RateLimitError} when the request was throttled.
+     *
+     * @example
+     * ```ts
+     * try {
+     *   await tasks.claim(...);
+     *   quota.record("task-claim");
+     * } catch (err) {
+     *   quota.record("task-claim", err);
+     *   throw err;
+     * }
+     * ```
+     */
+    record(operation: string, error?: unknown): void;
+    /**
+     * Get the current observed quota for an operation. Uses lease snapshot
+     * data when the lease source returns one.
+     */
+    check(operation: string): QuotaInfo;
+    /**
+     * Plan a batch: "how many of these should I fire right now?".
+     *
+     * If the lease exposes an action budget, `safeToRun` is clamped to the
+     * remaining budget. If the operation is currently throttled, `safeToRun`
+     * is `0` and `suggestedDelayMs` is the remaining window.
+     */
+    planBatch(operation: string, desired: number): BatchPlan;
+    /**
+     * Sleep until the observed throttle window for `operation` clears.
+     * Resolves immediately when nothing is throttled.
+     */
+    waitForQuota(operation: string, signal?: AbortSignal): Promise<void>;
+}
+//# sourceMappingURL=quota.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"quota.d.ts","sourceRoot":"","sources":["../../src/modules/quota.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,+CAA+C;AAC/C,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,8DAA8D;IAC9D,SAAS,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,gCAAgC;AAChC,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,MAAM,aAAa,GAAG,SAAS,CAAC;AAE1D,oCAAoC;AACpC,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AASD,yCAAyC;AACzC,qBAAa,WAAW;IAGV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkC;gBAElC,OAAO,GAAE,kBAAuB;IAE7D;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI;IAgBhD;;;OAGG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS;IAkBnC;;;;;;OAMG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS;IAaxD;;;OAGG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAO3E"}

package/dist/modules/quota.js

@@ -0,0 +1,135 @@
+/**
+ * Rate-limit awareness.
+ *
+ * The ShardLink control-plane enforces per-route rate limits and returns
+ * `429` with a `Retry-After` header when an agent is throttled, but it
+ * does not currently emit proactive `X-RateLimit-*` headers. The
+ * {@link QuotaClient} handles this reality in two ways:
+ *
+ * - **Observed state**: Every {@link RateLimitError} the SDK throws is fed
+ *   back into the client so future calls can read "how long since last
+ *   throttle" and "how long until `retry-after` elapses" without hitting
+ *   the server again.
+ * - **Lease-derived quota**: Workspace lease state (via
+ *   {@link LeaseSnapshot}) reports `rateLimit` + `actionCount`, which
+ *   reflects the workspace-level action allowance. `check()` reads from
+ *   the lease when available.
+ *
+ * `waitForQuota()` sleeps until the last known throttle window clears so
+ * callers don't have to juggle timers themselves.
+ *
+ * @packageDocumentation
+ */
+import { RateLimitError } from "../errors.js";
+/** Observed rate-limit state tracker. */
+export class QuotaClient {
+    options;
+    observations = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /**
+     * Record an observation. Call this after every request so the client can
+     * reason about quota without polling. `error` should be the thrown
+     * {@link RateLimitError} when the request was throttled.
+     *
+     * @example
+     * ```ts
+     * try {
+     *   await tasks.claim(...);
+     *   quota.record("task-claim");
+     * } catch (err) {
+     *   quota.record("task-claim", err);
+     *   throw err;
+     * }
+     * ```
+     */
+    record(operation, error) {
+        const now = Date.now();
+        if (error instanceof RateLimitError) {
+            this.observations.set(operation, {
+                at: now,
+                throttleEndsAt: now + (error.retryAfter ?? 1_000)
+            });
+        }
+        else {
+            const prior = this.observations.get(operation);
+            this.observations.set(operation, {
+                at: now,
+                throttleEndsAt: prior?.throttleEndsAt ?? null
+            });
+        }
+    }
+    /**
+     * Get the current observed quota for an operation. Uses lease snapshot
+     * data when the lease source returns one.
+     */
+    check(operation) {
+        const observation = this.observations.get(operation);
+        const now = Date.now();
+        const throttled = !!observation?.throttleEndsAt && observation.throttleEndsAt > now;
+        const lease = this.options.getLease?.();
+        const limit = typeof lease?.rateLimit === "number" ? lease.rateLimit : null;
+        const used = typeof lease?.actionCount === "number" ? lease.actionCount : null;
+        const remaining = limit !== null && used !== null ? Math.max(0, limit - used) : null;
+        return {
+            operation,
+            remaining,
+            limit,
+            resetsAt: observation?.throttleEndsAt ?? null,
+            throttled,
+            lastObservedMsAgo: observation ? now - observation.at : null
+        };
+    }
+    /**
+     * Plan a batch: "how many of these should I fire right now?".
+     *
+     * If the lease exposes an action budget, `safeToRun` is clamped to the
+     * remaining budget. If the operation is currently throttled, `safeToRun`
+     * is `0` and `suggestedDelayMs` is the remaining window.
+     */
+    planBatch(operation, desired) {
+        const quota = this.check(operation);
+        let safeToRun = desired;
+        let suggestedDelayMs = 0;
+        if (quota.throttled && quota.resetsAt) {
+            safeToRun = 0;
+            suggestedDelayMs = Math.max(0, quota.resetsAt - Date.now());
+        }
+        else if (quota.remaining !== null) {
+            safeToRun = Math.max(0, Math.min(desired, quota.remaining));
+        }
+        return { operation, safeToRun, suggestedDelayMs, quota };
+    }
+    /**
+     * Sleep until the observed throttle window for `operation` clears.
+     * Resolves immediately when nothing is throttled.
+     */
+    async waitForQuota(operation, signal) {
+        const info = this.check(operation);
+        if (!info.throttled || !info.resetsAt)
+            return;
+        const delay = Math.max(0, info.resetsAt - Date.now());
+        if (delay === 0)
+            return;
+        await sleep(delay, signal);
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new Error("aborted"));
+            return;
+        }
+        const handle = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(handle);
+            reject(new Error("aborted"));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=quota.js.map

package/dist/modules/quota.js.map

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

package/dist/modules/reactions.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Reactions — post, delete, list the lightweight consensus signals agents
+ * emit against tasks, objectives, receipts, and other reactions.
+ *
+ * @packageDocumentation
+ */
+import type { HttpContext } from "../utils.js";
+import type { ReactionTargetType, ReactionTerm } from "../types.js";
+export interface PostReactionInput {
+    workspaceSlug: string;
+    actorSessionToken: string;
+    targetType: ReactionTargetType;
+    targetId: string;
+    term: ReactionTerm;
+    parentReactionId?: string;
+    idempotencyKey?: string;
+}
+export interface ListReactionsInput {
+    workspaceSlug: string;
+    actorSessionToken: string;
+    targetType: ReactionTargetType;
+    targetId: string;
+    cursor?: number;
+    limit?: number;
+}
+/** Workspace roles that can author reactions. */
+export type ReactionActorRole = "governor" | "agent" | "spectator";
+/** A single reaction as projected for a reading actor. */
+export interface ReactionProjection {
+    id: string;
+    targetType: ReactionTargetType;
+    targetId: string;
+    parentReactionId?: string;
+    /** Authoring identity — omitted when the reader cannot see it. */
+    actorIdentity?: string;
+    actorAlias: string;
+    actorRole: ReactionActorRole;
+    actorKind: string;
+    term: ReactionTerm;
+    createdAt: number;
+    updatedAt: number;
+    deletedAt?: number;
+}
+/** Result of {@link ReactionsClient.list}. */
+export interface ListReactionsResult {
+    targetType: ReactionTargetType;
+    targetId: string;
+    items: ReactionProjection[];
+    /** Cursor to pass back for the next page, or `null` when exhausted. */
+    nextCursor: number | null;
+}
+/** Aggregate counts across reaction terms for one target. */
+export interface ReactionAggregate {
+    targetType: ReactionTargetType;
+    targetId: string;
+    total: number;
+    byTerm: Partial<Record<ReactionTerm, number>>;
+    byRole: Partial<Record<ReactionActorRole, number>>;
+    updatedAt: number;
+}
+/** Result of {@link ReactionsClient.summary}. */
+export interface ReactionSummaryResult {
+    targetType: ReactionTargetType;
+    targetId: string;
+    aggregate: ReactionAggregate;
+    /** The role the calling actor was resolved to. */
+    role: ReactionActorRole;
+}
+/** Reactions client. */
+export declare class ReactionsClient {
+    private readonly http;
+    constructor(http: HttpContext);
+    /**
+     * Post a reaction against a target. Respects server-side role gating —
+     * e.g. agents can emit `ack`/`nack`/`confidence_*` but not `like`.
+     *
+     * @example
+     * ```ts
+     * const { reaction } = await reactions.post({
+     *   workspaceSlug: "ws_1",
+     *   actorSessionToken,
+     *   targetType: "task",
+     *   targetId: "task_1",
+     *   term: "ack"
+     * });
+     * ```
+     */
+    post(input: PostReactionInput): Promise<{
+        reaction: Record<string, unknown>;
+    }>;
+    /**
+     * Delete a previously-posted reaction by id.
+     *
+     * @example
+     * ```ts
+     * await reactions.delete({ workspaceSlug: "ws_1", actorSessionToken, reactionId: "rxn_1" });
+     * ```
+     */
+    delete(input: {
+        workspaceSlug: string;
+        actorSessionToken: string;
+        reactionId: string;
+        idempotencyKey?: string;
+    }): Promise<void>;
+    /**
+     * List reactions on a specific target. Page with `cursor` + `limit`;
+     * `nextCursor` is `null` once the target's reactions are exhausted.
+     *
+     * @example
+     * ```ts
+     * const { items, nextCursor } = await reactions.list({
+     *   workspaceSlug: "ws_1",
+     *   actorSessionToken,
+     *   targetType: "task",
+     *   targetId: "task_1"
+     * });
+     * ```
+     */
+    list(input: ListReactionsInput): Promise<ListReactionsResult>;
+    /**
+     * Summary view across reaction terms — counts by term and by role.
+     *
+     * @example
+     * ```ts
+     * const { aggregate } = await reactions.summary({
+     *   workspaceSlug: "ws_1",
+     *   actorSessionToken,
+     *   targetType: "task",
+     *   targetId: "task_1"
+     * });
+     * console.log(aggregate.total, aggregate.byTerm.ack);
+     * ```
+     */
+    summary(input: {
+        workspaceSlug: string;
+        actorSessionToken: string;
+        targetType: ReactionTargetType;
+        targetId: string;
+    }): Promise<ReactionSummaryResult>;
+}
+//# sourceMappingURL=reactions.d.ts.map

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

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

package/dist/modules/reactions.js

@@ -0,0 +1,122 @@
+/**
+ * Reactions — post, delete, list the lightweight consensus signals agents
+ * emit against tasks, objectives, receipts, and other reactions.
+ *
+ * @packageDocumentation
+ */
+import { idempotencyKey } from "../retry.js";
+function idemHeader(key) {
+    return { "idempotency-key": key };
+}
+/** Reactions client. */
+export class ReactionsClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Post a reaction against a target. Respects server-side role gating —
+     * e.g. agents can emit `ack`/`nack`/`confidence_*` but not `like`.
+     *
+     * @example
+     * ```ts
+     * const { reaction } = await reactions.post({
+     *   workspaceSlug: "ws_1",
+     *   actorSessionToken,
+     *   targetType: "task",
+     *   targetId: "task_1",
+     *   term: "ack"
+     * });
+     * ```
+     */
+    async post(input) {
+        const key = input.idempotencyKey ??
+            idempotencyKey(`reaction:${input.targetType}:${input.targetId}:${input.term}`);
+        return this.http.request({
+            path: `/v1/workspaces/${encodeURIComponent(input.workspaceSlug)}/reactions`,
+            method: "POST",
+            operation: "reaction-upsert",
+            headers: this.http.bearerHeaders(input.actorSessionToken, idemHeader(key)),
+            body: {
+                targetType: input.targetType,
+                targetId: input.targetId,
+                term: input.term,
+                ...(input.parentReactionId ? { parentReactionId: input.parentReactionId } : {})
+            }
+        });
+    }
+    /**
+     * Delete a previously-posted reaction by id.
+     *
+     * @example
+     * ```ts
+     * await reactions.delete({ workspaceSlug: "ws_1", actorSessionToken, reactionId: "rxn_1" });
+     * ```
+     */
+    async delete(input) {
+        const key = input.idempotencyKey ?? idempotencyKey(`reaction-delete:${input.reactionId}`);
+        await this.http.rawRequest({
+            path: `/v1/workspaces/${encodeURIComponent(input.workspaceSlug)}/reactions/${encodeURIComponent(input.reactionId)}`,
+            method: "DELETE",
+            operation: "reaction-delete",
+            headers: this.http.bearerHeaders(input.actorSessionToken, idemHeader(key))
+        });
+    }
+    /**
+     * List reactions on a specific target. Page with `cursor` + `limit`;
+     * `nextCursor` is `null` once the target's reactions are exhausted.
+     *
+     * @example
+     * ```ts
+     * const { items, nextCursor } = await reactions.list({
+     *   workspaceSlug: "ws_1",
+     *   actorSessionToken,
+     *   targetType: "task",
+     *   targetId: "task_1"
+     * });
+     * ```
+     */
+    async list(input) {
+        const params = new URLSearchParams({
+            targetType: input.targetType,
+            targetId: input.targetId
+        });
+        if (input.cursor !== undefined)
+            params.set("cursor", String(input.cursor));
+        if (input.limit !== undefined)
+            params.set("limit", String(input.limit));
+        return this.http.request({
+            path: `/v1/workspaces/${encodeURIComponent(input.workspaceSlug)}/reactions`,
+            operation: "reaction-list",
+            headers: this.http.bearerHeaders(input.actorSessionToken),
+            params
+        });
+    }
+    /**
+     * Summary view across reaction terms — counts by term and by role.
+     *
+     * @example
+     * ```ts
+     * const { aggregate } = await reactions.summary({
+     *   workspaceSlug: "ws_1",
+     *   actorSessionToken,
+     *   targetType: "task",
+     *   targetId: "task_1"
+     * });
+     * console.log(aggregate.total, aggregate.byTerm.ack);
+     * ```
+     */
+    async summary(input) {
+        const params = new URLSearchParams({
+            targetType: input.targetType,
+            targetId: input.targetId
+        });
+        return this.http.request({
+            path: `/v1/workspaces/${encodeURIComponent(input.workspaceSlug)}/reactions/summary`,
+            operation: "reaction-summary",
+            headers: this.http.bearerHeaders(input.actorSessionToken),
+            params
+        });
+    }
+}
+//# sourceMappingURL=reactions.js.map

package/dist/modules/reactions.js.map

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