@swarm-agent/sdk 0.1.47

package/dist/sessions.js

@@ -0,0 +1,194 @@
+import { SwarmTimeoutError } from './errors.js';
+function generateRequestId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return `sdk-session-${crypto.randomUUID()}`;
+    }
+    return `sdk-session-${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 10)}`;
+}
+export class SwarmSessionsNamespace {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Creates a new durable V3 session.
+     */
+    async create(params) {
+        const clientRequestId = params.client_request_id || generateRequestId();
+        const agentName = params.agent_name || params.agent || 'swarm';
+        const res = await this.transport.request('/v3/sessions', {
+            method: 'POST',
+            body: {
+                client_request_id: clientRequestId,
+                agent_name: agentName,
+                title: params.title,
+                workspace_id: params.workspace_id,
+                workspace_path: params.workspace_path,
+                mode: params.mode ?? 'auto',
+                metadata: params.metadata,
+            },
+        });
+        const data = res.data;
+        if (data && typeof data === 'object' && 'session' in data && data.session) {
+            return data.session;
+        }
+        return data;
+    }
+    /**
+     * Lists durable sessions for the active account.
+     */
+    async list(params = {}) {
+        const q = new URLSearchParams();
+        if (params.limit && params.limit > 0)
+            q.set('limit', params.limit.toString());
+        if (params.state)
+            q.set('state', params.state);
+        if (params.workspace_id)
+            q.set('workspace_id', params.workspace_id);
+        if (params.category)
+            q.set('category', params.category);
+        if (params.cursor)
+            q.set('cursor', params.cursor);
+        const queryStr = q.toString() ? `?${q.toString()}` : '';
+        const res = await this.transport.request(`/v3/sessions${queryStr}`, { method: 'GET' });
+        const data = res.data;
+        if (Array.isArray(data)) {
+            return data;
+        }
+        if (data && typeof data === 'object' && 'sessions' in data && Array.isArray(data.sessions)) {
+            return data.sessions;
+        }
+        return [];
+    }
+    /**
+     * Retrieves full details, history, and state for a single session.
+     */
+    async get(sessionId) {
+        const id = encodeURIComponent(sessionId.trim());
+        const res = await this.transport.request(`/v3/sessions/${id}`, {
+            method: 'GET',
+        });
+        const data = res.data;
+        if (data && typeof data === 'object') {
+            const sessionObj = data.session || data;
+            return {
+                id: sessionObj.id || sessionObj.session_id || sessionId,
+                title: sessionObj.title || '',
+                workspace_id: sessionObj.workspace_id,
+                workspace_path: sessionObj.workspace_path,
+                state: sessionObj.state || data.projection?.state || 'idle',
+                mode: sessionObj.mode,
+                agent_name: sessionObj.agent_name,
+                created_at: sessionObj.created_at,
+                updated_at: sessionObj.updated_at,
+                archived: sessionObj.archived,
+                messages: data.messages,
+                last_run_id: sessionObj.last_run_id,
+                active_plan: data.active_plan,
+                raw: data,
+            };
+        }
+        return data;
+    }
+    /** Approve one exact pending tool call; no persistent rule or bypass is created. */
+    async approvePermissionOnce(sessionId, permissionId, reason) {
+        const res = await this.transport.request(`/v3/sessions/${encodeURIComponent(sessionId.trim())}/permissions/${encodeURIComponent(permissionId.trim())}/resolve`, { method: 'POST', body: { action: 'allow_once', reason } });
+        return res.data;
+    }
+    /** Resolve one exact pending tool permission; never changes account-wide policy. */
+    async denyPermission(sessionId, permissionId, reason) {
+        const res = await this.transport.request(`/v3/sessions/${encodeURIComponent(sessionId.trim())}/permissions/${encodeURIComponent(permissionId.trim())}/resolve`, { method: 'POST', body: { action: 'deny', reason } });
+        return res.data;
+    }
+    /**
+     * Archives a session.
+     */
+    async archive(sessionId) {
+        const id = encodeURIComponent(sessionId.trim());
+        const res = await this.transport.request(`/v3/sessions/${id}/archive`, {
+            method: 'POST',
+        });
+        return res.data?.ok === true;
+    }
+    /**
+     * Unarchives a previously archived session.
+     */
+    async unarchive(sessionId) {
+        const res = await this.transport.request('/v3/sessions:unarchive', {
+            method: 'POST',
+            body: {
+                session_id: sessionId.trim(),
+            },
+        });
+        return res.data?.ok === true;
+    }
+    /**
+     * Deletes a session and triggers cascading cancellation of associated runs and worktrees.
+     */
+    async delete(sessionId) {
+        const id = encodeURIComponent(sessionId.trim());
+        const res = await this.transport.request(`/v3/sessions/${id}`, {
+            method: 'DELETE',
+        });
+        return res.data?.ok === true;
+    }
+    /**
+     * Appends a message to a session conversation.
+     */
+    async sendMessage(sessionId, params) {
+        const id = encodeURIComponent(sessionId.trim());
+        const clientRequestId = params.client_request_id || generateRequestId();
+        const res = await this.transport.request(`/v3/sessions/${id}/messages`, {
+            method: 'POST',
+            body: {
+                client_request_id: clientRequestId,
+                content: params.content,
+                role: params.role ?? 'user',
+            },
+        });
+        return res.data;
+    }
+    /**
+     * Stops an active execution run for a session.
+     */
+    async stopRun(sessionId, params) {
+        const id = encodeURIComponent(sessionId.trim());
+        let target = params.target_swarm_id?.trim();
+        if (!target) {
+            const session = await this.get(sessionId);
+            const rawSession = session.raw?.session;
+            const runtime = rawSession?.metadata?.swarm_v3_runtime_swarm_id;
+            target = typeof runtime === 'string' ? runtime.trim() : undefined;
+            if (!target)
+                throw new Error('Session has no authoritative runtime identity; supply target_swarm_id');
+        }
+        const res = await this.transport.request(`/v3/sessions/${id}/run/stop`, {
+            method: 'POST',
+            body: {
+                run_id: params.run_id,
+                target_swarm_id: target,
+            },
+        });
+        return res.data?.ok === true;
+    }
+    /**
+     * Helper that polls a session until its active run completes, or times out.
+     */
+    async waitForRun(sessionId, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 60_000;
+        const pollIntervalMs = options.pollIntervalMs ?? 1_000;
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const detail = await this.get(sessionId);
+            const raw = (detail.raw || {});
+            const activeRun = raw.active_run_intent;
+            const state = (detail.state || '').toLowerCase();
+            const isRunning = state.includes('running') || state.includes('in_progress') || !!activeRun;
+            if (!isRunning) {
+                return detail;
+            }
+            await new Promise((r) => setTimeout(r, pollIntervalMs));
+        }
+        throw new SwarmTimeoutError(`Session run did not complete within ${timeoutMs}ms`, timeoutMs);
+    }
+}

package/dist/settings.d.ts

@@ -0,0 +1,85 @@
+import type { SwarmTransport } from './transport.js';
+export interface ProviderStatus {
+    id: string;
+    ready: boolean;
+    runnable: boolean;
+    reason?: string;
+    run_reason?: string;
+    default_model?: string;
+    default_thinking?: string;
+    auth_methods?: {
+        id: string;
+        label: string;
+        credential_type?: string;
+        description?: string;
+    }[];
+}
+export interface ModelAssignment {
+    provider: string;
+    model: string;
+    thinking: string;
+    service_tier?: string;
+    context_mode?: string;
+}
+export type SystemAgentSlot = 'compact' | 'finder' | 'coder' | 'designer' | 'router';
+export interface AgentModelSettings {
+    account_scope_id: string;
+    updated_at: number;
+    swarm: {
+        action: ModelAssignment;
+        plan: ModelAssignment;
+    };
+    system_agents: Record<SystemAgentSlot, ModelAssignment>;
+}
+export interface AgentModelSettingsResponse {
+    ok: boolean;
+    agent_model_settings: AgentModelSettings;
+    roles: Record<string, string>[];
+}
+/** Catalog extensions are preserved as unknown, never interpreted as runtime capability grants. */
+export interface ModelCatalogEntry {
+    provider: string;
+    model: string;
+    display_name?: string;
+    provider_display_name?: string;
+    catalog_id?: string;
+    context_window: number;
+    max_output_tokens: number;
+    reasoning: boolean;
+    thinking_options?: string[];
+    default_thinking?: string;
+    service_tiers?: string[];
+    default_service_tier?: string;
+    context_modes?: {
+        mode: string;
+        label?: string;
+        context_window?: number;
+        default?: boolean;
+    }[];
+    source: string;
+    fetched_at: number;
+    expires_at: number;
+    [extension: string]: unknown;
+}
+export interface ModelCatalogResponse {
+    ok: boolean;
+    provider: string;
+    count: number;
+    records: ModelCatalogEntry[];
+    meta?: Record<string, unknown>;
+    catalog_status: {
+        configured: boolean;
+        [key: string]: unknown;
+    };
+}
+/** Account-scoped settings. Requires the local administrative connection, not a session token. */
+export declare class SwarmSettingsNamespace {
+    private readonly transport;
+    constructor(transport: SwarmTransport);
+    providers(): Promise<ProviderStatus[]>;
+    models(provider: string, limit?: number): Promise<ModelCatalogResponse>;
+    agentModels(): Promise<AgentModelSettingsResponse>;
+    setSwarmModel(slot: 'action' | 'plan', assignment: ModelAssignment): Promise<AgentModelSettingsResponse>;
+    setSystemAgentModel(slot: SystemAgentSlot, assignment: ModelAssignment): Promise<AgentModelSettingsResponse>;
+    private patch;
+}

package/dist/settings.js

@@ -0,0 +1,26 @@
+/** Account-scoped settings. Requires the local administrative connection, not a session token. */
+export class SwarmSettingsNamespace {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async providers() {
+        return (await this.transport.request('/v1/providers')).data.providers;
+    }
+    async models(provider, limit = 500) {
+        const query = new URLSearchParams({ provider, limit: String(limit) });
+        return (await this.transport.request(`/v1/model/catalog?${query}`)).data;
+    }
+    async agentModels() {
+        return (await this.transport.request('/v1/agent-model-settings')).data;
+    }
+    async setSwarmModel(slot, assignment) {
+        return this.patch({ swarm: { [slot]: assignment } });
+    }
+    async setSystemAgentModel(slot, assignment) {
+        return this.patch({ system_agents: { [slot]: assignment } });
+    }
+    async patch(body) {
+        return (await this.transport.request('/v1/agent-model-settings', { method: 'PATCH', body })).data;
+    }
+}

package/dist/storage/adapters/memory.d.ts

@@ -0,0 +1,13 @@
+import type { StorageDriver } from '../types.js';
+export declare class MemoryStorageDriver implements StorageDriver {
+    private store;
+    private textEncoder;
+    private textDecoder;
+    read(key: string): Promise<Uint8Array | null>;
+    readString(key: string): Promise<string | null>;
+    write(key: string, data: Uint8Array | string): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+    exists(key: string): Promise<boolean>;
+    clear(): void;
+}

package/dist/storage/adapters/memory.js

@@ -0,0 +1,35 @@
+export class MemoryStorageDriver {
+    store = new Map();
+    textEncoder = new TextEncoder();
+    textDecoder = new TextDecoder();
+    async read(key) {
+        const val = this.store.get(key);
+        return val ? new Uint8Array(val) : null;
+    }
+    async readString(key) {
+        const bytes = await this.read(key);
+        return bytes ? this.textDecoder.decode(bytes) : null;
+    }
+    async write(key, data) {
+        const bytes = typeof data === 'string' ? this.textEncoder.encode(data) : new Uint8Array(data);
+        this.store.set(key, bytes);
+    }
+    async delete(key) {
+        this.store.delete(key);
+    }
+    async list(prefix) {
+        const keys = [];
+        for (const key of this.store.keys()) {
+            if (key.startsWith(prefix)) {
+                keys.push(key);
+            }
+        }
+        return keys.sort();
+    }
+    async exists(key) {
+        return this.store.has(key);
+    }
+    clear() {
+        this.store.clear();
+    }
+}

package/dist/storage/adapters/s3.d.ts

@@ -0,0 +1,31 @@
+import type { StorageDriver } from '../types.js';
+export interface S3DriverConfig {
+    bucket: string;
+    endpoint?: string;
+    region?: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    sessionToken?: string;
+    forcePathStyle?: boolean;
+}
+export declare class S3StorageDriver implements StorageDriver {
+    private bucket;
+    private endpoint;
+    private region;
+    private accessKeyId?;
+    private secretAccessKey?;
+    private sessionToken?;
+    private forcePathStyle;
+    constructor(config: S3DriverConfig);
+    private getUrl;
+    private sha256Hex;
+    private hmacSha256;
+    private getSigningKey;
+    private signRequest;
+    read(key: string): Promise<Uint8Array | null>;
+    readString(key: string): Promise<string | null>;
+    write(key: string, data: Uint8Array | string, contentType?: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+    exists(key: string): Promise<boolean>;
+}

package/dist/storage/adapters/s3.js

@@ -0,0 +1,171 @@
+export class S3StorageDriver {
+    bucket;
+    endpoint;
+    region;
+    accessKeyId;
+    secretAccessKey;
+    sessionToken;
+    forcePathStyle;
+    constructor(config) {
+        this.bucket = config.bucket;
+        this.region = config.region || 'us-east-1';
+        this.endpoint = (config.endpoint || `https://s3.${this.region}.amazonaws.com`).replace(/\/+$/, '');
+        this.accessKeyId = config.accessKeyId;
+        this.secretAccessKey = config.secretAccessKey;
+        this.sessionToken = config.sessionToken;
+        this.forcePathStyle = config.forcePathStyle ?? true;
+    }
+    getUrl(key) {
+        const cleanKey = key.replace(/^\/+/, '');
+        if (this.forcePathStyle) {
+            return new URL(`${this.endpoint}/${this.bucket}/${cleanKey}`);
+        }
+        const endpointUrl = new URL(this.endpoint);
+        return new URL(`${endpointUrl.protocol}//${this.bucket}.${endpointUrl.host}/${cleanKey}`);
+    }
+    async sha256Hex(data) {
+        const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+        const hashBuffer = await crypto.subtle.digest('SHA-256', bytes);
+        return Array.from(new Uint8Array(hashBuffer))
+            .map((b) => b.toString(16).padStart(2, '0'))
+            .join('');
+    }
+    async hmacSha256(key, data) {
+        const cryptoKey = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+        const dataBytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+        const signature = await crypto.subtle.sign('HMAC', cryptoKey, dataBytes);
+        return new Uint8Array(signature);
+    }
+    async getSigningKey(dateStamp) {
+        const kSecret = new TextEncoder().encode(`AWS4${this.secretAccessKey || ''}`);
+        const kDate = await this.hmacSha256(kSecret, dateStamp);
+        const kRegion = await this.hmacSha256(kDate, this.region);
+        const kService = await this.hmacSha256(kRegion, 's3');
+        return this.hmacSha256(kService, 'aws4_request');
+    }
+    async signRequest(method, url, headers, payloadHash) {
+        if (!this.accessKeyId || !this.secretAccessKey) {
+            return headers;
+        }
+        const now = new Date();
+        const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, '');
+        const dateStamp = amzDate.substring(0, 8);
+        const signedHeadersList = ['host', 'x-amz-content-sha256', 'x-amz-date'];
+        const reqHeaders = {
+            ...headers,
+            host: url.host,
+            'x-amz-date': amzDate,
+            'x-amz-content-sha256': payloadHash,
+        };
+        if (this.sessionToken) {
+            reqHeaders['x-amz-security-token'] = this.sessionToken;
+            signedHeadersList.push('x-amz-security-token');
+        }
+        signedHeadersList.sort();
+        const signedHeadersStr = signedHeadersList.join(';');
+        const canonicalHeaders = signedHeadersList
+            .map((h) => `${h}:${reqHeaders[h].trim()}\n`)
+            .join('');
+        const canonicalUri = url.pathname;
+        const searchParams = new URLSearchParams(url.search);
+        searchParams.sort();
+        const canonicalQueryString = searchParams.toString();
+        const canonicalRequest = [
+            method,
+            canonicalUri,
+            canonicalQueryString,
+            canonicalHeaders,
+            signedHeadersStr,
+            payloadHash,
+        ].join('\n');
+        const algorithm = 'AWS4-HMAC-SHA256';
+        const credentialScope = `${dateStamp}/${this.region}/s3/aws4_request`;
+        const hashedCanonicalRequest = await this.sha256Hex(canonicalRequest);
+        const stringToSign = [
+            algorithm,
+            amzDate,
+            credentialScope,
+            hashedCanonicalRequest,
+        ].join('\n');
+        const signingKey = await this.getSigningKey(dateStamp);
+        const signatureBytes = await this.hmacSha256(signingKey, stringToSign);
+        const signature = Array.from(signatureBytes)
+            .map((b) => b.toString(16).padStart(2, '0'))
+            .join('');
+        reqHeaders['Authorization'] = `${algorithm} Credential=${this.accessKeyId}/${credentialScope}, SignedHeaders=${signedHeadersStr}, Signature=${signature}`;
+        return reqHeaders;
+    }
+    async read(key) {
+        const url = this.getUrl(key);
+        const payloadHash = await this.sha256Hex('');
+        const headers = await this.signRequest('GET', url, {}, payloadHash);
+        const res = await fetch(url.toString(), { method: 'GET', headers });
+        if (res.status === 404) {
+            return null;
+        }
+        if (!res.ok) {
+            throw new Error(`S3 read error ${res.status}: ${await res.text()}`);
+        }
+        const buf = await res.arrayBuffer();
+        return new Uint8Array(buf);
+    }
+    async readString(key) {
+        const bytes = await this.read(key);
+        return bytes ? new TextDecoder().decode(bytes) : null;
+    }
+    async write(key, data, contentType = 'application/octet-stream') {
+        const url = this.getUrl(key);
+        const body = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+        const payloadHash = await this.sha256Hex(body);
+        const headers = await this.signRequest('PUT', url, { 'content-type': contentType }, payloadHash);
+        const res = await fetch(url.toString(), {
+            method: 'PUT',
+            headers,
+            body: body,
+        });
+        if (!res.ok) {
+            throw new Error(`S3 write error ${res.status}: ${await res.text()}`);
+        }
+    }
+    async delete(key) {
+        const url = this.getUrl(key);
+        const payloadHash = await this.sha256Hex('');
+        const headers = await this.signRequest('DELETE', url, {}, payloadHash);
+        const res = await fetch(url.toString(), { method: 'DELETE', headers });
+        if (!res.ok && res.status !== 404) {
+            throw new Error(`S3 delete error ${res.status}: ${await res.text()}`);
+        }
+    }
+    async list(prefix) {
+        const cleanPrefix = prefix.replace(/^\/+/, '');
+        const url = this.forcePathStyle
+            ? new URL(`${this.endpoint}/${this.bucket}?list-type=2&prefix=${encodeURIComponent(cleanPrefix)}`)
+            : new URL(`${new URL(this.endpoint).protocol}//${this.bucket}.${new URL(this.endpoint).host}?list-type=2&prefix=${encodeURIComponent(cleanPrefix)}`);
+        const payloadHash = await this.sha256Hex('');
+        const headers = await this.signRequest('GET', url, {}, payloadHash);
+        const res = await fetch(url.toString(), { method: 'GET', headers });
+        if (!res.ok) {
+            throw new Error(`S3 list error ${res.status}: ${await res.text()}`);
+        }
+        const xml = await res.text();
+        const keys = [];
+        const keyMatches = xml.matchAll(/<Key>(.*?)<\/Key>/g);
+        for (const match of keyMatches) {
+            if (match[1]) {
+                keys.push(match[1]);
+            }
+        }
+        return keys;
+    }
+    async exists(key) {
+        const url = this.getUrl(key);
+        const payloadHash = await this.sha256Hex('');
+        const headers = await this.signRequest('HEAD', url, {}, payloadHash);
+        const res = await fetch(url.toString(), { method: 'HEAD', headers });
+        if (res.status === 200)
+            return true;
+        if (res.status === 404)
+            return false;
+        throw new Error(`S3 exists error ${res.status}`);
+    }
+}