@swarm-agent/sdk 0.1.47

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/usage.d.ts

@@ -0,0 +1,106 @@
+import type { SwarmTransport } from './transport.js';
+export interface UsageScope {
+    kind: 'task' | 'worker' | 'worker_run';
+    id: string;
+    /** Project identity for tasks; worker identity for worker runs. */
+    project_id?: string;
+}
+export interface UsageScopeTotal extends UsageScope {
+    total_tokens: number;
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens: number;
+    cache_write_tokens: number;
+    thinking_tokens: number;
+    media_cost_usd: number;
+    media_receipts: number;
+    /** Only observed receipts; this is not proof of complete historical coverage. */
+    coverage: 'observed_receipts_only' | 'repaired_receipts_incomplete' | 'no_records' | '';
+    catalog_cost_usd: number;
+    provider_cost_usd: number;
+    provider_estimate_cost_usd: number;
+    nominal_subscription_cost_usd: number;
+    unknown_receipts: number;
+    free_receipts: number;
+    subscription_receipts: number;
+    receipt_count: number;
+    history_complete: boolean;
+    revision: number;
+}
+export interface UsageScopeRepairResult {
+    scanned: number;
+    repaired: number;
+    unresolved: number;
+    next_cursor?: string;
+    history_complete: boolean;
+}
+export declare class SwarmUsageNamespace {
+    private readonly transport;
+    constructor(transport: SwarmTransport);
+    workerBudget(workerId: string): Promise<WorkerBudgetStatus>;
+    /** User-only revision-guarded policy. Zero unsets a cap, never usage. In-flight
+     * provider work may overshoot; this is not an invoice-hard spending guarantee. */
+    setWorkerBudget(workerId: string, policy: WorkerBudgetUpdate): Promise<WorkerBudgetPolicy>;
+    private requestWorkerBudget;
+    /** Explicit bounded maintenance; no account charges are replayed. A finished
+     * cursor does not certify unavailable historic lineage or receipt indexes. */
+    repair(cursor?: string, limit?: number): Promise<UsageScopeRepairResult>;
+    /** Indexed cumulative receipt projection, not current context occupancy.
+     * recorded=false means no projection, not proof of free/zero historical usage.
+     * Optional date is one indexed UTC day; omitted date is lifetime observed usage.
+     * Refresh affected scopes from durable usage.scope.updated events, not polling.
+     */
+    scope(scope: UsageScope, date?: string): Promise<{
+        usage: UsageScopeTotal;
+        recorded: boolean;
+    }>;
+}
+/** Durable realtime event payload. Hydrate affected cards with scope(); no
+ * session subscription or recurring refresh is needed for scope invalidations. */
+export interface UsageScopeUpdatedPayload {
+    scope_totals: UsageScopeTotal[];
+}
+export interface WorkerBudgetUpdate {
+    expected_revision: number;
+    daily_cost_limit_usd: number;
+    daily_tokens_limit: number;
+}
+export interface WorkerBudgetPolicy {
+    account_scope_id: string;
+    worker_id: string;
+    revision: number;
+    daily_cost_limit_usd: number;
+    daily_tokens_limit: number;
+    updated_at: number;
+}
+/** Indexed observed receipts, never an invoice-hard guarantee. Null remaining is unset. */
+export interface WorkerBudgetStatus extends WorkerBudgetPolicy {
+    date: string;
+    usage: UsageScopeTotal;
+    remaining_cost_usd: number | null;
+    remaining_tokens: number | null;
+    blocked: boolean;
+    blocked_reason?: string;
+    inflight: boolean;
+    account_policy: {
+        account_scope_id: string;
+        enabled: boolean;
+        daily_cost_limit_usd: number;
+        daily_tokens_limit?: number;
+        updated_at: number;
+    };
+    account_usage: {
+        account_scope_id: string;
+        date: string;
+        total_cost_usd: number;
+        total_tokens: number;
+        unknown_receipts?: number;
+        pricing_coverage_version?: number;
+        pricing_coverage_incomplete?: boolean;
+    };
+    account_remaining_cost_usd: number | null;
+    account_remaining_tokens: number | null;
+    account_inflight: boolean;
+    account_coverage: 'no_records' | 'observed_receipts_only' | 'legacy_pricing_incomplete';
+    limitations: string;
+}

package/dist/usage.js

@@ -0,0 +1,82 @@
+import { SwarmValidationError } from './errors.js';
+export class SwarmUsageNamespace {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async workerBudget(workerId) {
+        const status = await this.requestWorkerBudget(workerId);
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(status.date) || !status.usage ||
+            typeof status.blocked !== 'boolean' || typeof status.inflight !== 'boolean' ||
+            !status.account_policy || !status.account_usage || typeof status.account_inflight !== 'boolean' ||
+            typeof status.limitations !== 'string' || !['no_records', 'observed_receipts_only', 'legacy_pricing_incomplete'].includes(status.account_coverage) ||
+            ![status.remaining_cost_usd, status.remaining_tokens, status.account_remaining_cost_usd, status.account_remaining_tokens]
+                .every(value => value === null || (typeof value === 'number' && Number.isFinite(value) && value >= 0))) {
+            throw new SwarmValidationError('Malformed worker budget status');
+        }
+        return status;
+    }
+    /** User-only revision-guarded policy. Zero unsets a cap, never usage. In-flight
+     * provider work may overshoot; this is not an invoice-hard spending guarantee. */
+    async setWorkerBudget(workerId, policy) {
+        if (!policy || !Number.isSafeInteger(policy.expected_revision) || policy.expected_revision < 0 ||
+            !Number.isFinite(policy.daily_cost_limit_usd) || policy.daily_cost_limit_usd < 0 ||
+            !Number.isSafeInteger(policy.daily_tokens_limit) || policy.daily_tokens_limit < 0) {
+            throw new SwarmValidationError('Valid worker budget policy is required');
+        }
+        return this.requestWorkerBudget(workerId, policy);
+    }
+    async requestWorkerBudget(workerId, policy) {
+        if (typeof workerId !== 'string' || !/^[a-zA-Z0-9_.-]{3,128}$/.test(workerId)) {
+            throw new SwarmValidationError('Valid worker identity is required');
+        }
+        const result = await this.transport.request(`/v3/usage/worker-budget?${new URLSearchParams({ worker_id: workerId })}`, policy ? { method: 'PUT', body: policy } : { method: 'GET' });
+        if (!result.data || result.data.worker_id !== workerId || !Number.isSafeInteger(result.data.revision)) {
+            throw new SwarmValidationError('Malformed worker budget response');
+        }
+        return result.data;
+    }
+    /** Explicit bounded maintenance; no account charges are replayed. A finished
+     * cursor does not certify unavailable historic lineage or receipt indexes. */
+    async repair(cursor = '', limit = 100) {
+        if (typeof cursor !== 'string' || cursor.length > 3072 || !Number.isInteger(limit) || limit < 1 || limit > 100) {
+            throw new SwarmValidationError('Valid bounded usage repair request is required');
+        }
+        const result = await this.transport.request('/v3/usage/scopes/repair', {
+            method: 'POST', body: { cursor, limit },
+        });
+        if (!result.data || typeof result.data.history_complete !== 'boolean') {
+            throw new SwarmValidationError('Malformed usage repair response');
+        }
+        return result.data;
+    }
+    /** Indexed cumulative receipt projection, not current context occupancy.
+     * recorded=false means no projection, not proof of free/zero historical usage.
+     * Optional date is one indexed UTC day; omitted date is lifetime observed usage.
+     * Refresh affected scopes from durable usage.scope.updated events, not polling.
+     */
+    async scope(scope, date) {
+        if (!scope || !['task', 'worker', 'worker_run'].includes(scope.kind) ||
+            typeof scope.id !== 'string' || !scope.id.trim() || scope.id.length > 256 ||
+            (scope.kind !== 'worker' && !scope.project_id?.trim()) ||
+            (scope.kind === 'worker' && scope.project_id) ||
+            (scope.project_id !== undefined && scope.project_id.length > 256)) {
+            throw new SwarmValidationError('Valid usage scope identity is required');
+        }
+        if (date !== undefined && (!/^\d{4}-\d{2}-\d{2}$/.test(date) ||
+            !Number.isFinite(Date.parse(`${date}T00:00:00Z`)) ||
+            new Date(`${date}T00:00:00Z`).toISOString().slice(0, 10) !== date)) {
+            throw new SwarmValidationError('Valid UTC usage date is required');
+        }
+        const query = new URLSearchParams({ kind: scope.kind, id: scope.id });
+        if (scope.project_id)
+            query.set('project_id', scope.project_id);
+        if (date)
+            query.set('date', date);
+        const result = await this.transport.request(`/v3/usage/scope?${query}`, { method: 'GET' });
+        if (!result.data?.usage || typeof result.data.recorded !== 'boolean') {
+            throw new SwarmValidationError('Malformed usage scope response');
+        }
+        return result.data;
+    }
+}

package/dist/workers.d.ts

@@ -0,0 +1,146 @@
+import type { SwarmTransport } from './transport.js';
+import type { WorkerRecord, WorkerRevisionRecord, WorkerRunRecord, PortableWorkerDefinition, CreateWorkerParams, UpdateWorkerParams, ListWorkersParams, ListWorkersResult, AttachWorkerAutomationParams, UpdateWorkerAutomationParams, RemoveWorkerAutomationParams, WorkerValidateResult, WorkerExportResult, ImportWorkerOptions, ActivateWorkerParams, PauseWorkerParams, ResumeWorkerParams, ArchiveWorkerParams, DeleteWorkerParams, SetWorkerAutomationEnabledParams, DirectWorkerRequestParams, TestWorkerRunParams, TriggerWorkerParams, MintWorkerTriggerTokenParams, MintWorkerTriggerTokenResult, ListWorkerRunsParams, ListWorkerRunsResult, GetWorkerRunParams, CancelWorkerRunParams } from './types.js';
+/**
+ * SwarmWorkersNamespace manages durable, account-owned workers, their revisions,
+ * attached automations, and portable import/export definitions over canonical /v3/workers APIs.
+ *
+ * Distinct from legacy SwarmAutomationsNamespace which targets /v3/automations/v2.
+ */
+export declare class SwarmWorkersNamespace {
+    private transport;
+    constructor(transport: SwarmTransport);
+    /**
+     * Creates a new durable worker in idle state.
+     * Requires nonblank name and idempotency_key; instructions may be empty.
+     * Server assigns stable identity and initial revision 1.
+     */
+    create(params: CreateWorkerParams): Promise<WorkerRecord>;
+    /**
+     * Retrieves a durable worker by its server ID or attached automation ID.
+     */
+    get(id: string): Promise<WorkerRecord | null>;
+    /**
+     * Lists durable workers with pagination, lifecycle filters, and cursor support.
+     */
+    list(params?: ListWorkersParams): Promise<ListWorkersResult>;
+    /**
+     * Updates a worker's definition with an explicit expected revision for optimistic concurrency.
+     * Body carries expected_revision only (no query params, no local_bindings).
+     */
+    update(id: string, expectedRevision: number, params: UpdateWorkerParams): Promise<WorkerRecord>;
+    /**
+     * Validates a portable worker definition document without persisting it.
+     * Sends raw PortableWorkerDefinition body and expects { valid: true, worker: doc }.
+     */
+    validate(definition: PortableWorkerDefinition | string): Promise<WorkerValidateResult>;
+    /**
+     * Exports a complete portable worker definition.
+     * Returns { worker: doc }.
+     */
+    export(id: string): Promise<WorkerExportResult>;
+    /**
+     * Imports a portable worker definition.
+     * Sends raw document body.
+     * - If mode is 'new' (default when targetWorkerId omitted): requires idempotencyKey option, queries ?mode=new&idempotency_key=...
+     * - If mode is 'update' (or targetWorkerId provided): requires targetWorkerId and expectedRevision, queries ?mode=update&worker_id=...&expected_revision=...
+     */
+    import(definition: PortableWorkerDefinition | string, options?: ImportWorkerOptions): Promise<WorkerRecord>;
+    /**
+     * Attaches an automation definition to the worker.
+     * Body carries { expected_worker_revision, automation }, no query param.
+     */
+    attachAutomation(params: AttachWorkerAutomationParams): Promise<WorkerRecord>;
+    /**
+     * Updates an existing attached automation definition on the worker.
+     * Body carries { expected_worker_revision, automation }, no query param.
+     */
+    updateAutomation(params: UpdateWorkerAutomationParams): Promise<WorkerRecord>;
+    /**
+     * Detaches/removes an automation definition from the worker.
+     */
+    removeAutomation(params: RemoveWorkerAutomationParams): Promise<WorkerRecord>;
+    /**
+     * Activates a stored worker with approved local workspace bindings.
+     * Transitions worker from idle/paused to active state.
+     */
+    activate(params: ActivateWorkerParams): Promise<WorkerRecord>;
+    /**
+     * Local deployment alias for activate: validates and activates with approved bindings.
+     */
+    deploy(params: ActivateWorkerParams): Promise<WorkerRecord>;
+    /**
+     * Pauses an active worker, closing admission and invalidating queued work.
+     */
+    pause(params: PauseWorkerParams): Promise<WorkerRecord>;
+    /**
+     * Resumes a paused worker without replaying cancelled work.
+     */
+    resume(params: ResumeWorkerParams): Promise<WorkerRecord>;
+    /**
+     * Archives a worker, stopping future work and disabling automations.
+     * Rejects if there are active running executions.
+     */
+    archive(params: ArchiveWorkerParams): Promise<WorkerRecord>;
+    /**
+     * Deletes a worker with safe stop barrier enforcement (tombstone).
+     * Rejects if there are active running executions.
+     */
+    delete(params: DeleteWorkerParams): Promise<{
+        ok: boolean;
+        deleted: boolean;
+    }>;
+    /**
+     * Enables a specific attached automation on the worker.
+     */
+    enableAutomation(params: SetWorkerAutomationEnabledParams): Promise<WorkerRecord>;
+    /**
+     * Disables a specific attached automation on the worker without stopping other jobs.
+     */
+    disableAutomation(params: SetWorkerAutomationEnabledParams): Promise<WorkerRecord>;
+    /**
+     * Dispatches a direct execution request to the worker without creating a persistent automation.
+     */
+    directRequest(params: DirectWorkerRequestParams): Promise<WorkerRunRecord>;
+    /**
+     * Dispatches an explicitly labelled test run. Does not enable schedules.
+     */
+    testRun(params: TestWorkerRunParams): Promise<WorkerRunRecord>;
+    /**
+     * Dispatches an authenticated external trigger to the worker or specific automation.
+     */
+    trigger(params: TriggerWorkerParams): Promise<WorkerRunRecord>;
+    /**
+     * Mints an authenticated scoped trigger token for this worker.
+     */
+    mintTriggerToken(params: MintWorkerTriggerTokenParams): Promise<MintWorkerTriggerTokenResult>;
+    /**
+     * Lists historical and active execution runs for a worker with pagination.
+     */
+    listRuns(params: ListWorkerRunsParams): Promise<ListWorkerRunsResult>;
+    /**
+     * Retrieves a single worker execution run by ID.
+     */
+    getRun(params: GetWorkerRunParams): Promise<WorkerRunRecord | null>;
+    /**
+     * Cancels an active or admitted execution run.
+     */
+    cancelRun(params: CancelWorkerRunParams): Promise<WorkerRunRecord>;
+    /**
+     * Retrieves revision history snapshots for a worker.
+     */
+    getHistory(params: {
+        worker_id: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        history: WorkerRevisionRecord[];
+        next_cursor?: string;
+    }>;
+    /**
+     * Retrieves a specific pinned revision snapshot of a worker.
+     */
+    getRevision(params: {
+        worker_id: string;
+        revision: number;
+    }): Promise<WorkerRevisionRecord | null>;
+}