@swarm-agent/sdk 0.1.47

package/dist/projects.js

@@ -0,0 +1,513 @@
+import { SwarmApiError, SwarmTimeoutError, } from './errors.js';
+export class SwarmProjectsNamespace {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    // ==========================================================================
+    // Project CRUD Operations
+    // ==========================================================================
+    /**
+     * Lists projects across the active account.
+     */
+    async list(params = {}, options) {
+        const q = new URLSearchParams();
+        if (typeof params.limit === 'number' && params.limit > 0) {
+            q.set('limit', String(params.limit));
+        }
+        const queryStr = q.toString() ? `?${q.toString()}` : '';
+        const res = await this.transport.request(`/v3/projects${queryStr}`, { method: 'GET', ...options });
+        if (Array.isArray(res.data)) {
+            return res.data;
+        }
+        if (res.data && typeof res.data === 'object' && 'projects' in res.data && Array.isArray(res.data.projects)) {
+            return res.data.projects;
+        }
+        return [];
+    }
+    /**
+     * Creates a new project in the active account.
+     */
+    async create(params, options) {
+        const res = await this.transport.request('/v3/projects', {
+            method: 'POST',
+            body: params,
+            ...options,
+        });
+        const data = res.data;
+        if (data && typeof data === 'object' && 'project' in data && data.project) {
+            return data.project;
+        }
+        if (data && typeof data === 'object' && 'id' in data) {
+            return data;
+        }
+        throw new SwarmApiError('Malformed response: missing project record', { status: res.status, details: data });
+    }
+    /**
+     * Retrieves a single project by ID.
+     */
+    async get(projectId, options) {
+        const id = encodeURIComponent(projectId.trim());
+        const res = await this.transport.request(`/v3/projects/${id}`, { method: 'GET', ...options });
+        const data = res.data;
+        if (data && typeof data === 'object' && 'project' in data && data.project) {
+            return data.project;
+        }
+        if (data && typeof data === 'object' && 'id' in data) {
+            return data;
+        }
+        throw new SwarmApiError('Malformed response: missing project record', { status: res.status, details: data });
+    }
+    /**
+     * Updates an existing project's metadata, context, or bound workspaces.
+     */
+    async update(projectId, params, options) {
+        const id = encodeURIComponent(projectId.trim());
+        const res = await this.transport.request(`/v3/projects/${id}`, {
+            method: 'PATCH',
+            body: params,
+            ...options,
+        });
+        const data = res.data;
+        if (data && typeof data === 'object' && 'project' in data && data.project) {
+            return data.project;
+        }
+        if (data && typeof data === 'object' && 'id' in data) {
+            return data;
+        }
+        throw new SwarmApiError('Malformed response: missing project record', { status: res.status, details: data });
+    }
+    /**
+     * Deletes a project by ID.
+     */
+    async delete(projectId, options) {
+        const id = encodeURIComponent(projectId.trim());
+        const res = await this.transport.request(`/v3/projects/${id}`, { method: 'DELETE', ...options });
+        return res.data ?? { status: 'deleted', id: projectId.trim() };
+    }
+    /**
+     * Synthesizes Markdown project context from project name and linked workspaces.
+     */
+    async synthesizeContext(params, options) {
+        const res = await this.transport.request('/v3/projects/synthesize-context', {
+            method: 'POST',
+            body: params,
+            ...options,
+        });
+        return res.data?.project_context ?? '';
+    }
+    /**
+     * Clears orchestrator context for a project, archiving old session and provisioning replacement.
+     */
+    async clearContext(projectId, options) {
+        const id = encodeURIComponent(projectId.trim());
+        const res = await this.transport.request(`/v3/projects/${id}/orchestrator:clear-context`, { method: 'POST', ...options });
+        return res.data ?? { status: 'cleared' };
+    }
+    // ==========================================================================
+    // Project Media Sub-resource
+    // ==========================================================================
+    /**
+     * Lists media items attached to a project.
+     */
+    async listMedia(projectId, options) {
+        const id = encodeURIComponent(projectId.trim());
+        const res = await this.transport.request(`/v3/projects/${id}/media`, { method: 'GET', ...options });
+        if (Array.isArray(res.data)) {
+            return res.data;
+        }
+        if (res.data && typeof res.data === 'object' && 'media' in res.data && Array.isArray(res.data.media)) {
+            return res.data.media;
+        }
+        return [];
+    }
+    /**
+     * Uploads or attaches a media item to a project.
+     */
+    async uploadMedia(projectId, media, options) {
+        const id = encodeURIComponent(projectId.trim());
+        const res = await this.transport.request(`/v3/projects/${id}/media`, {
+            method: 'POST',
+            body: media,
+            ...options,
+        });
+        const data = res.data;
+        if (data && typeof data === 'object' && 'media' in data && data.media) {
+            return data.media;
+        }
+        if (data && typeof data === 'object' && 'id' in data) {
+            return data;
+        }
+        throw new SwarmApiError('Malformed response: missing media record', { status: res.status, details: data });
+    }
+    /**
+     * Removes an attached media item from a project.
+     */
+    async deleteMedia(projectId, mediaId, options) {
+        const pId = encodeURIComponent(projectId.trim());
+        const mId = encodeURIComponent(mediaId.trim());
+        const res = await this.transport.request(`/v3/projects/${pId}/media/${mId}`, { method: 'DELETE', ...options });
+        return res.data ?? { removed: true, media_id: mediaId.trim(), uploaded_media: [] };
+    }
+    // ==========================================================================
+    // Project Tasks CRUD & Previews
+    // ==========================================================================
+    /**
+     * Lists tasks associated with a project.
+     */
+    async listTasks(projectId, options, view = 'active') {
+        const id = encodeURIComponent(projectId.trim());
+        const res = await this.transport.request(`/v3/projects/${id}/tasks${view === 'archived' ? '?view=archived' : ''}`, { method: 'GET', ...options });
+        if (Array.isArray(res.data)) {
+            return res.data;
+        }
+        if (res.data && typeof res.data === 'object' && 'tasks' in res.data && Array.isArray(res.data.tasks)) {
+            return res.data.tasks;
+        }
+        return [];
+    }
+    /**
+     * Creates a new autonomous task inside a project.
+     */
+    async createTask(projectId, params, options) {
+        const id = encodeURIComponent(projectId.trim());
+        const res = await this.transport.request(`/v3/projects/${id}/tasks`, {
+            method: 'POST',
+            body: params,
+            ...options,
+        });
+        const data = res.data;
+        if (data && typeof data === 'object' && 'task' in data && data.task) {
+            return {
+                task: data.task,
+                model_preview: data.model_preview,
+            };
+        }
+        if (data && typeof data === 'object' && 'id' in data) {
+            return {
+                task: data,
+            };
+        }
+        throw new SwarmApiError('Malformed response: missing task record', { status: res.status, details: data });
+    }
+    /**
+     * Retrieves a single task by ID within a project, including model preview.
+     */
+    async getTask(projectId, taskId, options) {
+        const pId = encodeURIComponent(projectId.trim());
+        const tId = encodeURIComponent(taskId.trim());
+        const res = await this.transport.request(`/v3/projects/${pId}/tasks/${tId}`, { method: 'GET', ...options });
+        const data = res.data;
+        if (data && typeof data === 'object' && 'task' in data && data.task) {
+            return {
+                task: data.task,
+                model_preview: data.model_preview,
+            };
+        }
+        if (data && typeof data === 'object' && 'id' in data) {
+            return {
+                task: data,
+            };
+        }
+        throw new SwarmApiError('Malformed response: missing task record', { status: res.status, details: data });
+    }
+    /**
+     * Updates an existing pending or queued task in a project.
+     */
+    async updateTask(projectId, taskId, params, options) {
+        const pId = encodeURIComponent(projectId.trim());
+        const tId = encodeURIComponent(taskId.trim());
+        const res = await this.transport.request(`/v3/projects/${pId}/tasks/${tId}`, {
+            method: 'PATCH',
+            body: params,
+            ...options,
+        });
+        const data = res.data;
+        if (data && typeof data === 'object' && 'task' in data && data.task) {
+            return data.task;
+        }
+        if (data && typeof data === 'object' && 'id' in data) {
+            return data;
+        }
+        throw new SwarmApiError('Malformed response: missing task record', { status: res.status, details: data });
+    }
+    /** Archives a task only at the supplied revision. */
+    async archiveTask(projectId, taskId, revision, options) {
+        const path = `/v3/projects/${encodeURIComponent(projectId.trim())}/tasks/${encodeURIComponent(taskId.trim())}/archive`;
+        const res = await this.transport.request(path, { method: 'POST', body: { revision }, ...options });
+        if (!res.data?.task)
+            throw new SwarmApiError('Malformed response: missing archived task', { status: res.status, details: res.data });
+        return res.data.task;
+    }
+    /** Deletes only an archived, unlaunched task at the supplied revision. */
+    async deleteTask(projectId, taskId, revision, options) {
+        const pId = encodeURIComponent(projectId.trim());
+        const tId = encodeURIComponent(taskId.trim());
+        const res = await this.transport.request(`/v3/projects/${pId}/tasks/${tId}?revision=${encodeURIComponent(String(revision))}`, { method: 'DELETE', ...options });
+        return res.data ?? { status: 'deleted', task_id: taskId.trim() };
+    }
+    /**
+     * Previews how a task will be routed, planned, and modeled before creating it.
+     */
+    async previewTask(projectId, params, options) {
+        const id = encodeURIComponent(projectId.trim());
+        const res = await this.transport.request(`/v3/projects/${id}/tasks:preview`, {
+            method: 'POST',
+            body: params,
+            ...options,
+        });
+        return res.data;
+    }
+    /**
+     * Retrieves the authoritative model preview for an existing task.
+     */
+    async getTaskModelPreview(projectId, taskId, options) {
+        const pId = encodeURIComponent(projectId.trim());
+        const tId = encodeURIComponent(taskId.trim());
+        const res = await this.transport.request(`/v3/projects/${pId}/tasks/${tId}/model-preview`, { method: 'GET', ...options });
+        return res.data;
+    }
+    // ==========================================================================
+    // Task Plan Lifecycle: Approval, Rejection, Reopening, Refinement, Completion
+    // ==========================================================================
+    /**
+     * Approves a task session with optional exact revision guards.
+     * If the task is bound to a structured plan, exact session_id, plan_id, and definition_revision
+     * guards are enforced by the backend to prevent stale approvals.
+     */
+    async approveTask(projectId, taskId, guards, options) {
+        const pId = encodeURIComponent(projectId.trim());
+        const tId = encodeURIComponent(taskId.trim());
+        const res = await this.transport.request(`/v3/projects/${pId}/tasks/${tId}/approve`, {
+            method: 'POST',
+            body: guards ?? {},
+            ...options,
+        });
+        const data = res.data;
+        if (data && typeof data === 'object' && 'task' in data && data.task) {
+            return {
+                status: data.status ?? 'approved',
+                task: data.task,
+            };
+        }
+        throw new SwarmApiError('Malformed response: missing task in approve response', {
+            status: res.status,
+            details: data,
+        });
+    }
+    /**
+     * Convenient alias for approveTask.
+     */
+    async acceptTask(projectId, taskId, guards, options) {
+        return this.approveTask(projectId, taskId, guards, options);
+    }
+    /**
+     * Rejects a task and marks its bound plan as rejected.
+     */
+    async rejectTask(projectId, taskId, guards, options) {
+        const pId = encodeURIComponent(projectId.trim());
+        const tId = encodeURIComponent(taskId.trim());
+        const res = await this.transport.request(`/v3/projects/${pId}/tasks/${tId}/reject`, { method: 'POST', body: guards ?? {}, ...options });
+        const data = res.data;
+        if (data && typeof data === 'object' && 'task' in data && data.task) {
+            return {
+                status: data.status ?? 'rejected',
+                task: data.task,
+            };
+        }
+        throw new SwarmApiError('Malformed response: missing task in reject response', {
+            status: res.status,
+            details: data,
+        });
+    }
+    /**
+     * Reopens a completed or needs_review task with optional feedback instructions.
+     */
+    async reopenTask(projectId, taskId, params, options) {
+        const pId = encodeURIComponent(projectId.trim());
+        const tId = encodeURIComponent(taskId.trim());
+        const res = await this.transport.request(`/v3/projects/${pId}/tasks/${tId}/reopen`, {
+            method: 'POST',
+            body: params ?? {},
+            ...options,
+        });
+        const data = res.data;
+        if (data && typeof data === 'object' && 'task' in data && data.task) {
+            return {
+                status: data.status ?? 'reopened',
+                task: data.task,
+            };
+        }
+        throw new SwarmApiError('Malformed response: missing task in reopen response', {
+            status: res.status,
+            details: data,
+        });
+    }
+    /**
+     * Marks a task as accepted and completed by the user.
+     */
+    async completeTask(projectId, taskId, options) {
+        const pId = encodeURIComponent(projectId.trim());
+        const tId = encodeURIComponent(taskId.trim());
+        const res = await this.transport.request(`/v3/projects/${pId}/tasks/${tId}/complete`, { method: 'POST', ...options });
+        const data = res.data;
+        if (data && typeof data === 'object' && 'task' in data && data.task) {
+            return {
+                status: data.status ?? 'completed',
+                task: data.task,
+            };
+        }
+        throw new SwarmApiError('Malformed response: missing task in complete response', {
+            status: res.status,
+            details: data,
+        });
+    }
+    /**
+     * Refines a task plan based on user feedback directives or error recovery strategy.
+     */
+    async refineTask(projectId, taskId, params, options) {
+        const pId = encodeURIComponent(projectId.trim());
+        const tId = encodeURIComponent(taskId.trim());
+        const res = await this.transport.request(`/v3/projects/${pId}/tasks/${tId}/refine`, {
+            method: 'POST',
+            body: params,
+            ...options,
+        });
+        const data = res.data;
+        if (data && typeof data === 'object' && 'task' in data && data.task) {
+            return {
+                status: data.status ?? 'refined',
+                task: data.task,
+            };
+        }
+        throw new SwarmApiError('Malformed response: missing task in refine response', {
+            status: res.status,
+            details: data,
+        });
+    }
+    // ==========================================================================
+    // Task Integration & Task Program Execution
+    // ==========================================================================
+    /**
+     * Integrates task commits into the parent workspace repository.
+     */
+    async integrateTask(projectId, taskId, options) {
+        const pId = encodeURIComponent(projectId.trim());
+        const tId = encodeURIComponent(taskId.trim());
+        const res = await this.transport.request(`/v3/projects/${pId}/tasks/${tId}/integrate`, { method: 'POST', ...options });
+        return res.data;
+    }
+    /**
+     * Deploys a task program for staged multi-agent execution.
+     */
+    async deployTaskProgram(projectId, taskId, options) {
+        const pId = encodeURIComponent(projectId.trim());
+        const tId = encodeURIComponent(taskId.trim());
+        const res = await this.transport.request(`/v3/projects/${pId}/tasks/${tId}/program:deploy`, { method: 'POST', ...options });
+        return res.data;
+    }
+    /**
+     * Redeploys a failed or rejected job within a deployed task program.
+     */
+    async redeployTaskProgramJob(projectId, taskId, params, options) {
+        const pId = encodeURIComponent(projectId.trim());
+        const tId = encodeURIComponent(taskId.trim());
+        const res = await this.transport.request(`/v3/projects/${pId}/tasks/${tId}/program:redeploy-job`, {
+            method: 'POST',
+            body: params,
+            ...options,
+        });
+        return res.data;
+    }
+    /**
+     * Inspects the durable TaskProgramRecord for a deployed task program.
+     */
+    async getTaskProgram(projectId, taskId, options) {
+        const pId = encodeURIComponent(projectId.trim());
+        const tId = encodeURIComponent(taskId.trim());
+        const res = await this.transport.request(`/v3/projects/${pId}/tasks/${tId}/program`, { method: 'GET', ...options });
+        return res.data;
+    }
+    // ==========================================================================
+    // Sync Stream, Event Replay, and Polling Helpers
+    // ==========================================================================
+    /**
+     * Streams outbox events after an opaque endpoint cursor via HTTP POST /v3/sync/stream.
+     * Cursors remain strictly opaque strings.
+     */
+    async syncStream(params, options) {
+        const res = await this.transport.request('/v3/sync/stream', {
+            method: 'POST',
+            body: params,
+            ...options,
+        });
+        return res.data;
+    }
+    /**
+     * Replays events starting after an opaque endpoint cursor.
+     */
+    async replayEvents(cursor, params = {}, options) {
+        return this.syncStream({
+            ...params,
+            endpoint_cursor: cursor,
+        }, options);
+    }
+    /**
+     * Polls a task until a predicate condition is satisfied, or times out/aborts.
+     */
+    async waitForTask(projectId, taskId, predicate, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 60_000;
+        const pollIntervalMs = options.pollIntervalMs ?? 500;
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (options.signal?.aborted) {
+                throw new SwarmApiError('Request aborted by caller', { status: 0 });
+            }
+            const { task } = await this.getTask(projectId, taskId, {
+                signal: options.signal,
+                timeoutMs: options.timeoutMs,
+            });
+            if (predicate(task)) {
+                return task;
+            }
+            await new Promise((resolve, reject) => {
+                const timer = setTimeout(resolve, pollIntervalMs);
+                if (options.signal) {
+                    options.signal.addEventListener('abort', () => {
+                        clearTimeout(timer);
+                        reject(new SwarmApiError('Request aborted by caller', { status: 0 }));
+                    }, { once: true });
+                }
+            });
+        }
+        throw new SwarmTimeoutError(`Task did not satisfy condition within ${timeoutMs}ms`, timeoutMs);
+    }
+    /**
+     * Async generator yielding sync stream events starting after an opaque cursor,
+     * respecting cancellation via AbortSignal.
+     */
+    async *streamEvents(initialCursor, params = {}, options = {}) {
+        let cursor = initialCursor;
+        const pollIntervalMs = options.pollIntervalMs ?? 500;
+        while (!options.signal?.aborted) {
+            const res = await this.syncStream({ ...params, endpoint_cursor: cursor }, { signal: options.signal, timeoutMs: options.timeoutMs });
+            cursor = res.endpoint_cursor;
+            for (const event of res.events || []) {
+                yield event;
+            }
+            if (!res.has_more) {
+                if (options.signal?.aborted)
+                    break;
+                await new Promise((resolve) => {
+                    const timer = setTimeout(resolve, pollIntervalMs);
+                    if (options.signal) {
+                        options.signal.addEventListener('abort', () => {
+                            clearTimeout(timer);
+                            resolve();
+                        }, { once: true });
+                    }
+                });
+            }
+        }
+    }
+}

package/dist/provider-auth.d.ts

@@ -0,0 +1,160 @@
+import type { SwarmTransport } from './transport.js';
+export interface CredentialInput {
+    provider: string;
+    type: string;
+    id?: string;
+    label?: string;
+    tags?: string[];
+    api_key?: string;
+    access_token?: string;
+    refresh_token?: string;
+    expires_at?: number;
+    account_id?: string;
+    active?: boolean;
+}
+export interface CredentialConnection {
+    connected: boolean;
+    method?: string;
+    message?: string;
+    verified_at?: number;
+}
+/** Redacted server status: never includes credential material. */
+export interface CredentialStatus {
+    id: string;
+    provider: string;
+    active: boolean;
+    auth_type: string;
+    label?: string;
+    tags?: string[];
+    updated_at: number;
+    created_at: number;
+    expires_at?: number;
+    last4?: string;
+    has_refresh_token?: boolean;
+    has_account_id?: boolean;
+    storage_mode: string;
+    connection?: CredentialConnection;
+    auto_defaults?: {
+        applied: boolean;
+        error?: string;
+        provider?: string;
+        model?: string;
+        thinking?: string;
+        global_model?: boolean;
+        agents?: string[];
+        subagents?: string[];
+        utility_provider?: string;
+        utility_model?: string;
+        utility_thinking?: string;
+    };
+}
+export interface CredentialList {
+    provider?: string;
+    query?: string;
+    total: number;
+    records: CredentialStatus[];
+    providers?: string[];
+}
+export interface CodexLogin {
+    session_id: string;
+    provider: string;
+    method: 'browser' | 'manual' | 'device';
+    label?: string;
+    active: boolean;
+    auth_url?: string;
+    verification_url?: string;
+    user_code?: string;
+    expires_at?: number;
+    status: string;
+    error?: string;
+    credential?: CredentialStatus;
+}
+export declare class SwarmCredentialsNamespace {
+    private readonly transport;
+    constructor(transport: SwarmTransport);
+    list(options?: {
+        provider?: string;
+        query?: string;
+        limit?: number;
+    }): Promise<CredentialList>;
+    save(input: CredentialInput): Promise<CredentialStatus>;
+    activate(provider: string, id: string): Promise<CredentialStatus>;
+    verify(provider: string, id: string): Promise<{
+        provider: string;
+        id: string;
+        connection: CredentialConnection;
+    }>;
+    delete(provider: string, id: string): Promise<{
+        ok: boolean;
+        deleted: boolean;
+        provider: string;
+        id: string;
+        cleanup: Record<string, unknown>;
+    }>;
+}
+export declare class SwarmCodexAuthNamespace {
+    private readonly transport;
+    constructor(transport: SwarmTransport);
+    start(input: {
+        method: 'browser' | 'manual' | 'device';
+        label?: string;
+        active?: boolean;
+    }): Promise<CodexLogin>;
+    status(session_id: string): Promise<CodexLogin>;
+    complete(session_id: string, callback_input: string): Promise<CodexLogin>;
+}
+export interface OnboardingStatus {
+    ok: boolean;
+    needs_onboarding: boolean;
+    identity: {
+        bootstrapped: boolean;
+        user_id?: string;
+        account_scope_id?: string;
+        username?: string;
+        team_id?: string;
+        team_display_name?: string;
+        team_default?: boolean;
+        membership_role?: string;
+    };
+    heuristics: {
+        missing_swarm_name: boolean;
+        credential_count: number;
+        agent_count: number;
+        saved_workspace_count: number;
+        vault_configured: boolean;
+    };
+    config: {
+        swarm_name: string;
+        desktop_onboarding_complete: boolean;
+        mode: string;
+        port: number;
+        desktop_port: number;
+        advertise_port: number;
+        peer_transport_port: number;
+        [key: string]: unknown;
+    };
+    workspace_guidance?: Record<string, unknown>;
+    session?: {
+        expires_at?: string;
+    };
+    tailscale: Record<string, unknown>;
+}
+export interface OnboardingUpdate {
+    username?: string;
+    swarm_name?: string;
+    desktop_onboarding_complete?: boolean;
+    mode?: string;
+    port?: number;
+    advertise_host?: string;
+    advertise_port?: number;
+    tailscale_url?: string;
+    peer_transport_port?: number;
+}
+export declare class SwarmOnboardingNamespace {
+    private readonly transport;
+    constructor(transport: SwarmTransport);
+    get(): Promise<OnboardingStatus>;
+    update(body: OnboardingUpdate): Promise<OnboardingStatus>;
+    /** First credential only. Use auth.credentials.save for subsequent credentials. */
+    credential(body: Omit<CredentialInput, 'id'>): Promise<CredentialStatus>;
+}