@swarm-agent/sdk 0.1.47

package/dist/apps.d.ts

@@ -0,0 +1,82 @@
+import type { ApplicationResultsOptions } from './app-results.js';
+import type { SessionWatchOptions, SessionWatch } from './realtime.js';
+import type { WorkerAutomationInput, TriggerWorkerParams } from './types.js';
+import type { SwarmTransport } from './transport.js';
+import type { SessionRecord, CreateSessionParams, CreateProjectTaskParams, ProjectTaskRecord, WorkerRecord, WorkerRunRecord } from './types.js';
+export interface ApplicationAgent {
+    id: string;
+    name: string;
+    instructions: string;
+    context: string;
+    revision: number;
+    project_id?: string;
+    worker_ids?: string[];
+}
+export type ApplicationAgentWrite = Omit<ApplicationAgent, 'id' | 'revision'> & {
+    expected_revision: number;
+};
+export type ApplicationConversationParams = CreateSessionParams & {
+    client_request_id: string;
+    revision: number;
+};
+export interface ApplicationConversationSnapshot {
+    session: SessionRecord;
+    messages?: Array<{
+        id: string;
+        role: string;
+        content: string;
+    }>;
+    [key: string]: unknown;
+}
+/** Application context and owned conversations; not a second execution engine. */
+export declare class SwarmAppsNamespace {
+    private readonly transport;
+    constructor(transport: SwarmTransport);
+    watchResults(id: string, options: ApplicationResultsOptions): SessionWatch;
+    private path;
+    list(params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        agents: ApplicationAgent[];
+        next_cursor?: string;
+    }>;
+    tasks(id: string, signal?: AbortSignal): Promise<{
+        tasks: ProjectTaskRecord[];
+    }>;
+    createTask(id: string, input: CreateProjectTaskParams): Promise<{
+        task: ProjectTaskRecord;
+    }>;
+    worker(id: string, workerId: string, signal?: AbortSignal): Promise<{
+        worker: WorkerRecord;
+    }>;
+    runs(id: string, workerId: string, signal?: AbortSignal): Promise<{
+        runs: WorkerRunRecord[];
+    }>;
+    /** Configuration changes retain canonical worker review/approval gates. */
+    configureAutomation(id: string, workerId: string, expectedRevision: number, automation: WorkerAutomationInput, automationId?: string): Promise<{
+        worker: WorkerRecord;
+    }>;
+    trigger(id: string, input: TriggerWorkerParams & {
+        idempotency_key: string;
+    }): Promise<Record<string, unknown>>;
+    /** Ownership is checked before opening the canonical V3 session stream. */
+    watchConversation(id: string, sessionId: string, options: SessionWatchOptions): Promise<SessionWatch>;
+    /** Create with expected_revision=0; update with the revision last read. */
+    put(id: string, input: ApplicationAgentWrite): Promise<ApplicationAgent>;
+    get(id: string, signal?: AbortSignal): Promise<ApplicationAgent>;
+    /** Context is pinned for the lifetime of this conversation, including restart. */
+    createConversation(id: string, input: ApplicationConversationParams): Promise<SessionRecord>;
+    conversations(id: string): Promise<{
+        sessions: SessionRecord[];
+        scan_limit: number;
+        scan_limit_reached: boolean;
+    }>;
+    /** Reopen by durable id, with server-side agent ownership validation. */
+    conversation(id: string, sessionId: string): Promise<ApplicationConversationSnapshot>;
+    /** Event IDs should be stable across delivery retries. Content is a user message, not instructions. */
+    send(id: string, sessionId: string, input: {
+        content: string;
+        client_request_id: string;
+    }): Promise<Record<string, unknown>>;
+}

package/dist/apps.js

@@ -0,0 +1,89 @@
+import { watchApplicationResults } from './app-results.js';
+import { SwarmRealtimeNamespace } from './realtime.js';
+function segment(value) {
+    if (!value.trim() || value === '.' || value === '..' || /[/\\]/.test(value))
+        throw new Error('A nonempty resource id without path separators is required');
+    return encodeURIComponent(value);
+}
+/** Application context and owned conversations; not a second execution engine. */
+export class SwarmAppsNamespace {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    watchResults(id, options) {
+        segment(id);
+        return watchApplicationResults(this, this.transport, id, options);
+    }
+    path(id) { return `/v3/application-agents/${segment(id)}`; }
+    async list(params = {}) {
+        const q = new URLSearchParams();
+        if (params.limit !== undefined)
+            q.set('limit', String(params.limit));
+        if (params.cursor)
+            q.set('cursor', params.cursor);
+        return (await this.transport.request(`/v3/application-agents?${q}`, { method: 'GET' })).data;
+    }
+    async tasks(id, signal) {
+        return (await this.transport.request(`${this.path(id)}/tasks`, { method: 'GET', signal })).data;
+    }
+    async createTask(id, input) {
+        return (await this.transport.request(`${this.path(id)}/tasks`, { method: 'POST', body: input })).data;
+    }
+    async worker(id, workerId, signal) {
+        return (await this.transport.request(`${this.path(id)}/workers/${segment(workerId)}`, { method: 'GET', signal })).data;
+    }
+    async runs(id, workerId, signal) {
+        return (await this.transport.request(`${this.path(id)}/workers/${segment(workerId)}/runs`, { method: 'GET', signal })).data;
+    }
+    /** Configuration changes retain canonical worker review/approval gates. */
+    async configureAutomation(id, workerId, expectedRevision, automation, automationId) {
+        if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 1)
+            throw new Error('A positive worker revision is required');
+        const path = `${this.path(id)}/workers/${segment(workerId)}/automations${automationId === undefined ? '' : `/${segment(automationId)}`}`;
+        return (await this.transport.request(path, { method: automationId === undefined ? 'POST' : 'PUT', body: { expected_worker_revision: expectedRevision, automation } })).data;
+    }
+    async trigger(id, input) {
+        if (!input.idempotency_key.trim())
+            throw new Error('A stable delivery id is required');
+        const suffix = input.automation_id === undefined ? '/trigger' : `/automations/${segment(input.automation_id)}/trigger`;
+        return (await this.transport.request(`${this.path(id)}/workers/${segment(input.worker_id)}${suffix}`, {
+            method: 'POST', body: { payload: input.payload, idempotency_key: input.idempotency_key },
+        })).data;
+    }
+    /** Ownership is checked before opening the canonical V3 session stream. */
+    async watchConversation(id, sessionId, options) {
+        await this.conversation(id, sessionId);
+        return new SwarmRealtimeNamespace(this.transport).watchSession(sessionId, options);
+    }
+    /** Create with expected_revision=0; update with the revision last read. */
+    async put(id, input) {
+        return (await this.transport.request(this.path(id), { method: 'PUT', body: input })).data;
+    }
+    async get(id, signal) {
+        return (await this.transport.request(this.path(id), { method: 'GET', signal })).data;
+    }
+    /** Context is pinned for the lifetime of this conversation, including restart. */
+    async createConversation(id, input) {
+        const { revision, ...params } = input;
+        if (!Number.isSafeInteger(revision) || revision < 1)
+            throw new Error('A positive agent revision is required');
+        const response = await this.transport.request(`${this.path(id)}/conversations?revision=${revision}`, {
+            method: 'POST', body: { ...params, agent_name: params.agent_name ?? params.agent ?? 'swarm' },
+        });
+        return response.data.session;
+    }
+    async conversations(id) {
+        return (await this.transport.request(`${this.path(id)}/conversations`, { method: 'GET' })).data;
+    }
+    /** Reopen by durable id, with server-side agent ownership validation. */
+    async conversation(id, sessionId) {
+        return (await this.transport.request(`${this.path(id)}/conversations/${segment(sessionId)}`, { method: 'GET' })).data;
+    }
+    /** Event IDs should be stable across delivery retries. Content is a user message, not instructions. */
+    async send(id, sessionId, input) {
+        return (await this.transport.request(`${this.path(id)}/conversations/${segment(sessionId)}/messages`, {
+            method: 'POST', body: { ...input, role: 'user' },
+        })).data;
+    }
+}

package/dist/auth.d.ts

@@ -0,0 +1,45 @@
+import { SwarmCredentialsNamespace, SwarmCodexAuthNamespace } from './provider-auth.js';
+import type { SwarmTransport } from './transport.js';
+import type { CreateScopedTokenParams, CreateScopedTokenResult, DesktopSessionBootstrap, ScopedTokenRecord } from './types.js';
+export declare class SwarmAuthNamespace {
+    readonly credentials: SwarmCredentialsNamespace;
+    readonly codex: SwarmCodexAuthNamespace;
+    private transport;
+    private onTokenUpdate?;
+    constructor(transport: SwarmTransport, onTokenUpdate?: (token: string) => void);
+    /**
+     * Bootstraps local desktop session credentials.
+     * Useful in local development or testbench environments to obtain administrative tokens.
+     * By default, automatically updates the client's bearer token with the returned token.
+     */
+    bootstrapDesktopSession(options?: {
+        origin?: string;
+        updateClientToken?: boolean;
+    }): Promise<DesktopSessionBootstrap>;
+    /**
+     * Creates a new scoped deploy token with granular permission scopes.
+     * Returns the plaintext token (prefixed with 'swk_') along with the token record.
+     * Store the token securely—it cannot be retrieved again in plaintext!
+     */
+    createScopedToken(params: CreateScopedTokenParams): Promise<CreateScopedTokenResult>;
+    /**
+     * Lists all scoped deploy tokens for the active account.
+     * Secret hashes are masked; hints (e.g. 'swk_...abcd') are displayed.
+     */
+    listScopedTokens(): Promise<ScopedTokenRecord[]>;
+    /**
+     * Revokes a scoped token by ID.
+     * The token immediately ceases to authenticate requests.
+     */
+    revokeScopedToken(tokenId: string): Promise<ScopedTokenRecord>;
+    /**
+     * Deletes or purges a scoped token.
+     * If purge is true, the token record and index are permanently deleted from store.
+     */
+    deleteScopedToken(tokenId: string, options?: {
+        purge?: boolean;
+    }): Promise<{
+        ok: boolean;
+        deleted: boolean;
+    }>;
+}

package/dist/auth.js

@@ -0,0 +1,89 @@
+import { SwarmCredentialsNamespace, SwarmCodexAuthNamespace } from './provider-auth.js';
+export class SwarmAuthNamespace {
+    credentials;
+    codex;
+    transport;
+    onTokenUpdate;
+    constructor(transport, onTokenUpdate) {
+        this.transport = transport;
+        this.credentials = new SwarmCredentialsNamespace(transport);
+        this.codex = new SwarmCodexAuthNamespace(transport);
+        this.onTokenUpdate = onTokenUpdate;
+    }
+    /**
+     * Bootstraps local desktop session credentials.
+     * Useful in local development or testbench environments to obtain administrative tokens.
+     * By default, automatically updates the client's bearer token with the returned token.
+     */
+    async bootstrapDesktopSession(options = {}) {
+        const baseUrl = this.transport.getConfig().baseUrl.replace(/\/+$/, '');
+        const origin = options.origin ?? baseUrl;
+        const res = await this.transport.request('/v1/auth/desktop/session', {
+            method: 'GET',
+            headers: {
+                'Origin': origin,
+                'Referer': `${origin}/app`,
+                'Sec-Fetch-Site': 'same-origin',
+            },
+        });
+        const data = res.data;
+        if (options.updateClientToken !== false && data?.token) {
+            this.transport.setConfig({ token: data.token });
+            if (this.onTokenUpdate) {
+                this.onTokenUpdate(data.token);
+            }
+        }
+        return data;
+    }
+    /**
+     * Creates a new scoped deploy token with granular permission scopes.
+     * Returns the plaintext token (prefixed with 'swk_') along with the token record.
+     * Store the token securely—it cannot be retrieved again in plaintext!
+     */
+    async createScopedToken(params) {
+        const res = await this.transport.request('/v3/auth/tokens', {
+            method: 'POST',
+            body: {
+                name: params.name,
+                scopes: params.scopes,
+                worker_id: params.worker_id,
+                worker_name: params.worker_name,
+                expires_in_seconds: params.expires_in_seconds,
+            },
+        });
+        return res.data;
+    }
+    /**
+     * Lists all scoped deploy tokens for the active account.
+     * Secret hashes are masked; hints (e.g. 'swk_...abcd') are displayed.
+     */
+    async listScopedTokens() {
+        const res = await this.transport.request('/v3/auth/tokens', {
+            method: 'GET',
+        });
+        return res.data?.tokens ?? [];
+    }
+    /**
+     * Revokes a scoped token by ID.
+     * The token immediately ceases to authenticate requests.
+     */
+    async revokeScopedToken(tokenId) {
+        const id = encodeURIComponent(tokenId.trim());
+        const res = await this.transport.request(`/v3/auth/tokens/${id}/revoke`, {
+            method: 'POST',
+        });
+        return res.data.record;
+    }
+    /**
+     * Deletes or purges a scoped token.
+     * If purge is true, the token record and index are permanently deleted from store.
+     */
+    async deleteScopedToken(tokenId, options = {}) {
+        const id = encodeURIComponent(tokenId.trim());
+        const query = options.purge ? '?purge=true' : '';
+        const res = await this.transport.request(`/v3/auth/tokens/${id}${query}`, {
+            method: 'DELETE',
+        });
+        return res.data;
+    }
+}

package/dist/automations.d.ts

@@ -0,0 +1,74 @@
+import type { SwarmTransport } from './transport.js';
+import type { AutomationV2ListParams, AutomationV2Progress, AutomationV2Record, AutomationV2TriggerParams, AutomationV2TriggerResult, AutomationV2WebhookRecord, CreateWebhookParams, WebhookTestParams, WebhookTestResult } from './types.js';
+export declare class SwarmAutomationsNamespace {
+    private transport;
+    constructor(transport: SwarmTransport);
+    /**
+     * Immediately triggers an on-demand worker execution with caller-supplied context.
+     * Admitted occurrences execute in an isolated Git worktree with runtime context
+     * injected into the agent's goal and execution metadata.
+     */
+    trigger(params: AutomationV2TriggerParams): Promise<AutomationV2TriggerResult>;
+    /**
+     * Lists all automations/workers in the specified workspace.
+     */
+    list(params?: AutomationV2ListParams): Promise<AutomationV2Record[]>;
+    /**
+     * Retrieves an automation review/definition for a given worker_id or session_id.
+     */
+    get(params: {
+        workspace_id: string;
+        worker_id?: string;
+        session_id?: string;
+    }): Promise<AutomationV2Record | null>;
+    /**
+     * Fetches the current progress, execution history, and upcoming forecast for a worker.
+     */
+    getProgress(params: {
+        workspace_id: string;
+        worker_id?: string;
+        session_id?: string;
+        timezone?: string;
+        cursor?: string;
+    }): Promise<AutomationV2Progress>;
+    /**
+     * Deletes an automation permanently, cancelling pending runs and purging accepted records.
+     */
+    delete(params: {
+        workspace_id: string;
+        session_id: string;
+        generation?: number;
+    }): Promise<boolean>;
+    /**
+     * Pauses an active automation schedule.
+     */
+    pause(params: {
+        workspace_id: string;
+        session_id: string;
+        generation: number;
+    }): Promise<boolean>;
+    /**
+     * Resumes a paused automation schedule.
+     */
+    resume(params: {
+        workspace_id: string;
+        session_id: string;
+        generation: number;
+    }): Promise<boolean>;
+    /**
+     * Lists all configured push alert webhooks for the account.
+     */
+    listWebhooks(): Promise<AutomationV2WebhookRecord[]>;
+    /**
+     * Creates or updates a push alert webhook destination.
+     */
+    createWebhook(params: CreateWebhookParams): Promise<AutomationV2WebhookRecord>;
+    /**
+     * Deletes a push alert webhook destination by ID.
+     */
+    deleteWebhook(id: string): Promise<boolean>;
+    /**
+     * Sends a synchronous test notification ping to a webhook destination.
+     */
+    testWebhook(params: WebhookTestParams): Promise<WebhookTestResult>;
+}

package/dist/automations.js

@@ -0,0 +1,159 @@
+export class SwarmAutomationsNamespace {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Immediately triggers an on-demand worker execution with caller-supplied context.
+     * Admitted occurrences execute in an isolated Git worktree with runtime context
+     * injected into the agent's goal and execution metadata.
+     */
+    async trigger(params) {
+        const res = await this.transport.request('/v3/automations/v2/trigger', {
+            method: 'POST',
+            body: {
+                workspace_id: params.workspace_id,
+                worker_id: params.worker_id,
+                session_id: params.session_id,
+                automation_id: params.automation_id,
+                context: params.context ?? {},
+            },
+        });
+        return res.data;
+    }
+    /**
+     * Lists all automations/workers in the specified workspace.
+     */
+    async list(params) {
+        const q = new URLSearchParams();
+        if (params?.workspace_id)
+            q.set('workspace_id', params.workspace_id);
+        q.set('action', 'list');
+        if (params?.archived_mode)
+            q.set('archived_mode', params.archived_mode);
+        if (params?.cursor)
+            q.set('cursor', params.cursor);
+        if (params?.limit)
+            q.set('limit', params.limit.toString());
+        const res = await this.transport.request(`/v3/automations/v2?${q.toString()}`, { method: 'GET' });
+        return res.data?.records ?? [];
+    }
+    /**
+     * Retrieves an automation review/definition for a given worker_id or session_id.
+     */
+    async get(params) {
+        const q = new URLSearchParams();
+        q.set('workspace_id', params.workspace_id);
+        if (params.worker_id)
+            q.set('worker_id', params.worker_id);
+        if (params.session_id)
+            q.set('session_id', params.session_id);
+        const res = await this.transport.request(`/v3/automations/v2/review?${q.toString()}`, { method: 'GET' });
+        return res.data?.record ?? null;
+    }
+    /**
+     * Fetches the current progress, execution history, and upcoming forecast for a worker.
+     */
+    async getProgress(params) {
+        const q = new URLSearchParams();
+        q.set('workspace_id', params.workspace_id);
+        if (params.worker_id)
+            q.set('worker_id', params.worker_id);
+        if (params.session_id)
+            q.set('session_id', params.session_id);
+        if (params.timezone)
+            q.set('timezone', params.timezone);
+        if (params.cursor)
+            q.set('cursor', params.cursor);
+        const res = await this.transport.request(`/v3/automations/v2/progress?${q.toString()}`, { method: 'GET' });
+        return res.data;
+    }
+    /**
+     * Deletes an automation permanently, cancelling pending runs and purging accepted records.
+     */
+    async delete(params) {
+        const res = await this.transport.request('/v3/automations/v2/control', {
+            method: 'POST',
+            body: {
+                action: 'delete_automation',
+                workspace_id: params.workspace_id,
+                session_id: params.session_id,
+                generation: params.generation ?? 1,
+            },
+        });
+        return Boolean(res.data);
+    }
+    /**
+     * Pauses an active automation schedule.
+     */
+    async pause(params) {
+        const res = await this.transport.request('/v3/automations/v2/control', {
+            method: 'POST',
+            body: {
+                action: 'pause',
+                workspace_id: params.workspace_id,
+                session_id: params.session_id,
+                generation: params.generation,
+            },
+        });
+        return res.data?.ok === true;
+    }
+    /**
+     * Resumes a paused automation schedule.
+     */
+    async resume(params) {
+        const res = await this.transport.request('/v3/automations/v2/control', {
+            method: 'POST',
+            body: {
+                action: 'resume',
+                workspace_id: params.workspace_id,
+                session_id: params.session_id,
+                generation: params.generation,
+            },
+        });
+        return res.data?.ok === true;
+    }
+    /**
+     * Lists all configured push alert webhooks for the account.
+     */
+    async listWebhooks() {
+        const res = await this.transport.request('/v3/automations/v2/webhooks', { method: 'GET' });
+        return res.data?.webhooks ?? [];
+    }
+    /**
+     * Creates or updates a push alert webhook destination.
+     */
+    async createWebhook(params) {
+        const res = await this.transport.request('/v3/automations/v2/webhooks', {
+            method: 'POST',
+            body: {
+                id: params.id,
+                workspace_id: params.workspace_id,
+                worker_id: params.worker_id,
+                url: params.url,
+                secret: params.secret,
+                format: params.format ?? 'generic',
+                events: params.events ?? ['*'],
+                enabled: params.enabled ?? true,
+            },
+        });
+        return res.data.webhook;
+    }
+    /**
+     * Deletes a push alert webhook destination by ID.
+     */
+    async deleteWebhook(id) {
+        const res = await this.transport.request(`/v3/automations/v2/webhooks/${encodeURIComponent(id)}`, { method: 'DELETE' });
+        return res.data?.ok === true;
+    }
+    /**
+     * Sends a synchronous test notification ping to a webhook destination.
+     */
+    async testWebhook(params) {
+        const res = await this.transport.request('/v3/automations/v2/webhooks/test', {
+            method: 'POST',
+            body: params,
+        });
+        return res.data;
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,61 @@
+import { SwarmAppsNamespace } from './apps.js';
+import { SwarmSettingsNamespace } from './settings.js';
+import { SwarmOnboardingNamespace } from './provider-auth.js';
+import { SwarmRealtimeNamespace } from './realtime.js';
+import { SwarmUsageNamespace } from './usage.js';
+import { SwarmAuthNamespace } from './auth.js';
+import { SwarmAutomationsNamespace } from './automations.js';
+import { SwarmWorkersNamespace } from './workers.js';
+import { SwarmDeliverablesNamespace } from './deliverables.js';
+import { SwarmDeployNamespace } from './deploy/index.js';
+import { SwarmNotificationsNamespace } from './notifications.js';
+import { SwarmProjectsNamespace } from './projects.js';
+import { SwarmSessionsNamespace } from './sessions.js';
+import { SwarmSystemNamespace } from './system.js';
+import { SwarmStorageNamespace } from './storage/index.js';
+import { SwarmTransport } from './transport.js';
+import type { ResolvedSwarmClientConfig, SwarmClientConfig } from './types.js';
+import { SwarmWorkspacesNamespace } from './workspaces.js';
+export declare class SwarmClient {
+    readonly config: ResolvedSwarmClientConfig;
+    readonly transport: SwarmTransport;
+    readonly auth: SwarmAuthNamespace;
+    readonly settings: SwarmSettingsNamespace;
+    readonly onboarding: SwarmOnboardingNamespace;
+    readonly realtime: SwarmRealtimeNamespace;
+    /**
+     * Legacy automations namespace targeting /v3/automations/v2.
+     * Note: This is legacy automation API, not the canonical durable worker identity authority.
+     */
+    readonly automations: SwarmAutomationsNamespace;
+    /**
+     * Canonical durable worker namespace managing account-owned workers,
+     * revisions, attached automations, and portable import/export definitions over /v3/workers.
+     */
+    readonly workers: SwarmWorkersNamespace;
+    readonly usage: SwarmUsageNamespace;
+    readonly deliverables: SwarmDeliverablesNamespace;
+    /** Convenient alias for deliverables namespace: mailbox */
+    readonly mailbox: SwarmDeliverablesNamespace;
+    readonly workspaces: SwarmWorkspacesNamespace;
+    readonly projects: SwarmProjectsNamespace;
+    readonly sessions: SwarmSessionsNamespace;
+    readonly apps: SwarmAppsNamespace;
+    readonly system: SwarmSystemNamespace;
+    readonly deploy: SwarmDeployNamespace;
+    readonly notifications: SwarmNotificationsNamespace;
+    /** Convenient alias for notifications namespace: inbox */
+    readonly inbox: SwarmNotificationsNamespace;
+    readonly storage: SwarmStorageNamespace;
+    /** Convenient alias for cloud storage connections: cloud */
+    readonly cloud: SwarmStorageNamespace;
+    constructor(config?: SwarmClientConfig);
+    /**
+     * Updates the bearer authentication token for all subsequent client requests.
+     */
+    setToken(token: string): void;
+}
+/**
+ * Factory function to create a new SwarmClient instance.
+ */
+export declare function createSwarmClient(config?: SwarmClientConfig): SwarmClient;