@swarm-agent/sdk 0.1.47

package/dist/client.js

@@ -0,0 +1,103 @@
+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 { SwarmWorkspacesNamespace } from './workspaces.js';
+export class SwarmClient {
+    config;
+    transport;
+    auth;
+    settings;
+    onboarding;
+    realtime;
+    /**
+     * Legacy automations namespace targeting /v3/automations/v2.
+     * Note: This is legacy automation API, not the canonical durable worker identity authority.
+     */
+    automations;
+    /**
+     * Canonical durable worker namespace managing account-owned workers,
+     * revisions, attached automations, and portable import/export definitions over /v3/workers.
+     */
+    workers;
+    usage;
+    deliverables;
+    /** Convenient alias for deliverables namespace: mailbox */
+    mailbox;
+    workspaces;
+    projects;
+    sessions;
+    apps;
+    system;
+    deploy;
+    notifications;
+    /** Convenient alias for notifications namespace: inbox */
+    inbox;
+    storage;
+    /** Convenient alias for cloud storage connections: cloud */
+    cloud;
+    constructor(config = {}) {
+        const env = typeof process !== 'undefined' && process?.env ? process.env : {};
+        const baseUrl = config.baseUrl ||
+            env.SWARM_API_URL ||
+            env.SWARM_DESKTOP_URL ||
+            'http://127.0.0.1:18080';
+        const socketPath = config.socketPath || env.SWARM_SOCKET_PATH;
+        const token = config.token || env.SWARM_AUTH_TOKEN || env.SWARM_DEPLOY_TOKEN;
+        const resolved = {
+            baseUrl: baseUrl.replace(/\/+$/, ''),
+            token,
+            socketPath,
+            defaultHeaders: config.defaultHeaders ?? {},
+            timeoutMs: config.timeoutMs ?? 30_000,
+        };
+        this.transport = new SwarmTransport(resolved);
+        this.config = this.transport.getConfig();
+        this.auth = new SwarmAuthNamespace(this.transport, (token) => {
+            this.config.token = token;
+        });
+        this.settings = new SwarmSettingsNamespace(this.transport);
+        this.onboarding = new SwarmOnboardingNamespace(this.transport);
+        this.realtime = new SwarmRealtimeNamespace(this.transport);
+        this.automations = new SwarmAutomationsNamespace(this.transport);
+        this.workers = new SwarmWorkersNamespace(this.transport);
+        this.usage = new SwarmUsageNamespace(this.transport);
+        this.deliverables = new SwarmDeliverablesNamespace(this.transport);
+        this.mailbox = this.deliverables;
+        this.workspaces = new SwarmWorkspacesNamespace(this.transport);
+        this.projects = new SwarmProjectsNamespace(this.transport);
+        this.sessions = new SwarmSessionsNamespace(this.transport);
+        this.apps = new SwarmAppsNamespace(this.transport);
+        this.system = new SwarmSystemNamespace(this.transport);
+        this.deploy = new SwarmDeployNamespace(this.transport);
+        this.notifications = new SwarmNotificationsNamespace(this.transport);
+        this.inbox = this.notifications;
+        this.storage = new SwarmStorageNamespace(this.transport);
+        this.cloud = this.storage;
+    }
+    /**
+     * Updates the bearer authentication token for all subsequent client requests.
+     */
+    setToken(token) {
+        this.transport.setConfig({ token });
+        this.config.token = token;
+    }
+}
+/**
+ * Factory function to create a new SwarmClient instance.
+ */
+export function createSwarmClient(config) {
+    return new SwarmClient(config);
+}

package/dist/deliverables.d.ts

@@ -0,0 +1,42 @@
+import type { SwarmTransport } from './transport.js';
+import type { CreateDeliverableParams, DeliverableFilter, DeliverableRecord } from './types.js';
+export declare class SwarmDeliverablesNamespace {
+    private readonly transport;
+    constructor(transport: SwarmTransport);
+    /**
+     * Submits a new deliverable (e.g. social post batch, alert, report, PR draft) to the Agent Mailbox.
+     */
+    submit(params: CreateDeliverableParams): Promise<DeliverableRecord>;
+    /**
+     * Lists deliverables across the account, optionally filtered by status, worker, kind, or workspace.
+     */
+    list(filter?: DeliverableFilter): Promise<DeliverableRecord[]>;
+    /**
+     * Fetches a single deliverable by ID.
+     */
+    get(id: string): Promise<DeliverableRecord>;
+    /**
+     * Approves a deliverable, triggering any linked publication action (e.g. publish to X, webhook).
+     */
+    approve(id: string, params?: {
+        parameters?: Record<string, unknown>;
+    }): Promise<{
+        deliverable: DeliverableRecord;
+        action_result?: Record<string, unknown>;
+    }>;
+    /**
+     * Dismisses a pending deliverable without executing its publication action.
+     */
+    dismiss(id: string): Promise<DeliverableRecord>;
+    /**
+     * Requests changes on a deliverable, sending it back to the worker with feedback notes and optional tags.
+     */
+    requestChanges(id: string, params: {
+        notes: string;
+        tags?: string[];
+    }): Promise<DeliverableRecord>;
+    /**
+     * Deletes a deliverable permanently from the mailbox.
+     */
+    delete(id: string): Promise<void>;
+}

package/dist/deliverables.js

@@ -0,0 +1,83 @@
+export class SwarmDeliverablesNamespace {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Submits a new deliverable (e.g. social post batch, alert, report, PR draft) to the Agent Mailbox.
+     */
+    async submit(params) {
+        const res = await this.transport.request('/v3/deliverables', {
+            method: 'POST',
+            body: params,
+        });
+        return res.data.deliverable;
+    }
+    /**
+     * Lists deliverables across the account, optionally filtered by status, worker, kind, or workspace.
+     */
+    async list(filter = {}) {
+        const q = new URLSearchParams();
+        if (filter.status)
+            q.set('status', filter.status);
+        if (filter.worker_id)
+            q.set('worker_id', filter.worker_id);
+        if (filter.kind)
+            q.set('kind', filter.kind);
+        if (filter.workspace_id)
+            q.set('workspace_id', filter.workspace_id);
+        if (typeof filter.limit === 'number')
+            q.set('limit', String(filter.limit));
+        const path = q.toString() ? `/v3/deliverables?${q.toString()}` : '/v3/deliverables';
+        const res = await this.transport.request(path, {
+            method: 'GET',
+        });
+        return res.data.deliverables || [];
+    }
+    /**
+     * Fetches a single deliverable by ID.
+     */
+    async get(id) {
+        const res = await this.transport.request(`/v3/deliverables/${encodeURIComponent(id)}`, {
+            method: 'GET',
+        });
+        return res.data.deliverable;
+    }
+    /**
+     * Approves a deliverable, triggering any linked publication action (e.g. publish to X, webhook).
+     */
+    async approve(id, params = {}) {
+        const res = await this.transport.request(`/v3/deliverables/${encodeURIComponent(id)}/approve`, {
+            method: 'POST',
+            body: params,
+        });
+        return res.data;
+    }
+    /**
+     * Dismisses a pending deliverable without executing its publication action.
+     */
+    async dismiss(id) {
+        const res = await this.transport.request(`/v3/deliverables/${encodeURIComponent(id)}/dismiss`, {
+            method: 'POST',
+        });
+        return res.data.deliverable;
+    }
+    /**
+     * Requests changes on a deliverable, sending it back to the worker with feedback notes and optional tags.
+     */
+    async requestChanges(id, params) {
+        const res = await this.transport.request(`/v3/deliverables/${encodeURIComponent(id)}/request_changes`, {
+            method: 'POST',
+            body: params,
+        });
+        return res.data.deliverable;
+    }
+    /**
+     * Deletes a deliverable permanently from the mailbox.
+     */
+    async delete(id) {
+        await this.transport.request(`/v3/deliverables/${encodeURIComponent(id)}`, {
+            method: 'DELETE',
+        });
+    }
+}

package/dist/deploy/dockerfile.d.ts

@@ -0,0 +1,14 @@
+import type { BuildStrategy, SourceConfig } from './types.js';
+export interface DockerfileOptions {
+    /** Required qualified release manifest image, never a mutable tag. */
+    runtimeImage?: string;
+    /** Legacy source-build options are rejected, not silently ignored. */
+    source?: SourceConfig;
+    port?: number;
+    strategy?: BuildStrategy;
+    goVersion?: string;
+    packagePath?: string;
+}
+/** Consume the canonical CGO/glibc/FFF runtime; never rebuild the daemon here. */
+export declare function generateOptimizedDockerfile(options?: DockerfileOptions): string;
+export declare function generateDockerIgnore(): string;

package/dist/deploy/dockerfile.js

@@ -0,0 +1,14 @@
+import { SwarmValidationError } from '../errors.js';
+/** Consume the canonical CGO/glibc/FFF runtime; never rebuild the daemon here. */
+export function generateOptimizedDockerfile(options = {}) {
+    if (options.source || options.strategy || options.goVersion || options.packagePath || options.port !== undefined) {
+        throw new SwarmValidationError('Source builds and listener overrides are unsupported. Use the qualified runtimeImage and the private application recipe.');
+    }
+    if (!/^ghcr\.io\/swarm-agent\/swarm-headless@sha256:[a-f0-9]{64}$/.test(options.runtimeImage ?? '')) {
+        throw new SwarmValidationError('runtimeImage must be ghcr.io/swarm-agent/swarm-headless@sha256:<64 lowercase hex characters> from the qualified release manifest.');
+    }
+    return `# Canonical runtime; inherits non-root identity, private listeners and durable volumes.\nFROM ${options.runtimeImage}\n`;
+}
+export function generateDockerIgnore() {
+    return `.git\n.github\nnode_modules\n**/node_modules\n*.log\n*.tmp\n.env\n.env.*\n*.sock\ntmp\n.vscode\n.idea\n`;
+}

package/dist/deploy/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Deployment namespace and multi-cloud providers for Swarm.
+ */
+import type { SwarmTransport } from '../transport.js';
+import type { CloudDeployProvider, CloudTarget, CreateManifestOptions, DeployCommand, DeployExecutionResult, DeployPlan, ExecuteDeployOptions, SwarmDeployManifest, ValidationResult } from './types.js';
+export * from './types.js';
+export * from './manifest.js';
+export * from './dockerfile.js';
+export * from './providers/gcp-cloud-run.js';
+export * from './providers/gcp-compute.js';
+export * from './worker-cloud-deployer.js';
+export declare class SwarmDeployNamespace {
+    protected readonly transport?: SwarmTransport | undefined;
+    private readonly providers;
+    constructor(transport?: SwarmTransport | undefined);
+    /**
+     * Registers a new cloud deployment provider (extensible for AWS, Azure, Fly.io, etc.).
+     */
+    registerProvider(provider: CloudDeployProvider): void;
+    /**
+     * Retrieves the deployment provider registered for a target platform.
+     */
+    getProvider(target: CloudTarget): CloudDeployProvider;
+    /**
+     * Returns all currently registered cloud deployment providers.
+     */
+    listProviders(): CloudDeployProvider[];
+    /**
+     * Creates a typed deployment manifest using proven best-practice presets.
+     */
+    createManifest(options?: CreateManifestOptions): SwarmDeployManifest;
+    /**
+     * Parses, resolves environment variables, and validates a deployment manifest.
+     */
+    loadManifest(input: string | Record<string, unknown>, envLookup?: Record<string, string>): SwarmDeployManifest;
+    /**
+     * Serializes a manifest to formatted JSON.
+     */
+    serializeManifest(manifest: SwarmDeployManifest, indent?: number): string;
+    /**
+     * Validates a deployment manifest against its target provider rules.
+     */
+    validate(manifest: SwarmDeployManifest): ValidationResult;
+    /**
+     * Generates a complete, structured deployment plan including artifacts, shell commands, and cost estimates.
+     */
+    plan(input: SwarmDeployManifest | CreateManifestOptions | string | Record<string, unknown>): DeployPlan;
+    /**
+     * Generates all required deployment artifacts (Dockerfile, scripts, config files) as a key-value record.
+     */
+    generateArtifacts(input: SwarmDeployManifest | CreateManifestOptions | string | Record<string, unknown>): Record<string, string>;
+    /**
+     * Generates sequential shell commands required to execute the build and deployment.
+     */
+    generateCommands(input: SwarmDeployManifest | CreateManifestOptions | string | Record<string, unknown>): DeployCommand[];
+    /**
+     * Writes all generated deployment artifacts to a target directory on disk.
+     */
+    writeArtifacts(targetDir: string, input: SwarmDeployManifest | CreateManifestOptions | string | Record<string, unknown> | DeployPlan): Promise<string[]>;
+    /**
+     * Programmatically executes the deployment plan.
+     * In dryRun mode, validates prerequisites, writes artifacts, and simulates command execution.
+     * In live mode, executes sequential pipeline commands and verifies service reachability.
+     */
+    execute(input: SwarmDeployManifest | CreateManifestOptions | string | Record<string, unknown> | DeployPlan, options?: ExecuteDeployOptions): Promise<DeployExecutionResult>;
+    private ensureManifest;
+}

package/dist/deploy/index.js

@@ -0,0 +1,226 @@
+/**
+ * Deployment namespace and multi-cloud providers for Swarm.
+ */
+import { SwarmNotFoundError, SwarmValidationError } from '../errors.js';
+import { createDeployManifest, loadDeployManifest, serializeDeployManifest } from './manifest.js';
+import { GcpCloudRunProvider } from './providers/gcp-cloud-run.js';
+import { GcpComputeEngineProvider } from './providers/gcp-compute.js';
+export * from './types.js';
+export * from './manifest.js';
+export * from './dockerfile.js';
+export * from './providers/gcp-cloud-run.js';
+export * from './providers/gcp-compute.js';
+export * from './worker-cloud-deployer.js';
+export class SwarmDeployNamespace {
+    transport;
+    providers = new Map();
+    constructor(transport) {
+        this.transport = transport;
+        // Register default providers
+        this.registerProvider(new GcpCloudRunProvider());
+        this.registerProvider(new GcpComputeEngineProvider());
+    }
+    /**
+     * Registers a new cloud deployment provider (extensible for AWS, Azure, Fly.io, etc.).
+     */
+    registerProvider(provider) {
+        this.providers.set(provider.target, provider);
+    }
+    /**
+     * Retrieves the deployment provider registered for a target platform.
+     */
+    getProvider(target) {
+        const provider = this.providers.get(target);
+        if (!provider) {
+            const available = Array.from(this.providers.keys()).join(', ');
+            throw new SwarmNotFoundError(`No deployment provider registered for target '${target}'. Available targets: ${available}`, { code: 'PROVIDER_NOT_FOUND' });
+        }
+        return provider;
+    }
+    /**
+     * Returns all currently registered cloud deployment providers.
+     */
+    listProviders() {
+        return Array.from(this.providers.values());
+    }
+    /**
+     * Creates a typed deployment manifest using proven best-practice presets.
+     */
+    createManifest(options) {
+        return createDeployManifest(options);
+    }
+    /**
+     * Parses, resolves environment variables, and validates a deployment manifest.
+     */
+    loadManifest(input, envLookup) {
+        return loadDeployManifest(input, envLookup);
+    }
+    /**
+     * Serializes a manifest to formatted JSON.
+     */
+    serializeManifest(manifest, indent = 2) {
+        return serializeDeployManifest(manifest, indent);
+    }
+    /**
+     * Validates a deployment manifest against its target provider rules.
+     */
+    validate(manifest) {
+        const provider = this.getProvider(manifest.target);
+        return provider.validate(manifest);
+    }
+    /**
+     * Generates a complete, structured deployment plan including artifacts, shell commands, and cost estimates.
+     */
+    plan(input) {
+        const manifest = this.ensureManifest(input);
+        const provider = this.getProvider(manifest.target);
+        return provider.plan(manifest);
+    }
+    /**
+     * Generates all required deployment artifacts (Dockerfile, scripts, config files) as a key-value record.
+     */
+    generateArtifacts(input) {
+        const manifest = this.ensureManifest(input);
+        const provider = this.getProvider(manifest.target);
+        return provider.generateArtifacts(manifest);
+    }
+    /**
+     * Generates sequential shell commands required to execute the build and deployment.
+     */
+    generateCommands(input) {
+        const manifest = this.ensureManifest(input);
+        const provider = this.getProvider(manifest.target);
+        return provider.generateCommands(manifest);
+    }
+    /**
+     * Writes all generated deployment artifacts to a target directory on disk.
+     */
+    async writeArtifacts(targetDir, input) {
+        const plan = typeof input === 'object' && input !== null && 'artifacts' in input
+            ? input
+            : this.plan(input);
+        const validation = this.validate(plan.manifest);
+        if (!validation.valid)
+            throw new SwarmValidationError(validation.errors.join('; '));
+        const modFs = 'node:fs';
+        const modPath = 'node:path';
+        const fs = await import(modFs);
+        const path = await import(modPath);
+        await fs.promises.mkdir(targetDir, { recursive: true });
+        const writtenFiles = [];
+        for (const [filename, content] of Object.entries(plan.artifacts)) {
+            const filePath = path.join(targetDir, filename);
+            await fs.promises.writeFile(filePath, content, 'utf8');
+            if (filename.endsWith('.sh')) {
+                await fs.promises.chmod(filePath, 0o755).catch(() => { });
+            }
+            writtenFiles.push(filePath);
+        }
+        return writtenFiles;
+    }
+    /**
+     * Programmatically executes the deployment plan.
+     * In dryRun mode, validates prerequisites, writes artifacts, and simulates command execution.
+     * In live mode, executes sequential pipeline commands and verifies service reachability.
+     */
+    async execute(input, options = {}) {
+        const startTime = Date.now();
+        const plan = typeof input === 'object' && input !== null && 'artifacts' in input
+            ? input
+            : this.plan(input);
+        const validation = this.validate(plan.manifest);
+        if (!validation.valid)
+            throw new SwarmValidationError(validation.errors.join('; '));
+        const modFs = 'node:fs';
+        const modPath = 'node:path';
+        const modOs = 'node:os';
+        const modCp = 'node:child_process';
+        const modUtil = 'node:util';
+        const fs = await import(modFs);
+        const path = await import(modPath);
+        const os = await import(modOs);
+        const { exec } = await import(modCp);
+        const { promisify } = await import(modUtil);
+        const execAsync = promisify(exec);
+        const targetDir = options.outputDir || (await fs.promises.mkdtemp(path.join(os.tmpdir(), 'swarm-deploy-')));
+        await this.writeArtifacts(targetDir, plan);
+        const stepOutputs = {};
+        let serviceUrl;
+        let externalIp;
+        if (options.dryRun) {
+            for (const cmd of plan.commands) {
+                options.onLog?.(`[DRY RUN] [${cmd.phase}] ${cmd.title}: ${cmd.command}`, cmd.phase);
+                stepOutputs[cmd.title] = `(simulated: ${cmd.command})`;
+            }
+            return {
+                success: true,
+                target: plan.target,
+                durationMs: Date.now() - startTime,
+                stepOutputs,
+                outputDir: targetDir,
+            };
+        }
+        try {
+            for (const cmd of plan.commands) {
+                // Skip cleanup step during initial deployment execution
+                if (cmd.phase === 'cleanup') {
+                    continue;
+                }
+                options.onLog?.(`[${cmd.phase}] ${cmd.title}...`, cmd.phase);
+                const procEnv = typeof process !== 'undefined' ? process.env : {};
+                const execEnv = {
+                    ...procEnv,
+                    ...(options.env || {}),
+                };
+                const { stdout, stderr } = await execAsync(cmd.command, {
+                    cwd: targetDir,
+                    env: execEnv,
+                    timeout: 600_000,
+                });
+                const output = (stdout + (stderr ? `\n${stderr}` : '')).trim();
+                stepOutputs[cmd.title] = output;
+                options.onLog?.(output, cmd.phase);
+                // Extract Cloud Run URL or Compute NAT IP if present
+                const urlMatch = output.match(/https:\/\/[a-z0-9-]+\.[a-z0-9.-]+\.run\.app/i);
+                if (urlMatch) {
+                    serviceUrl = urlMatch[0];
+                }
+                const ipMatch = output.match(/\b(?:\d{1,3}\.){3}\d{1,3}\b/);
+                if (ipMatch && plan.target === 'gcp-compute-engine' && cmd.phase === 'verify') {
+                    externalIp = ipMatch[0];
+                }
+            }
+            return {
+                success: true,
+                target: plan.target,
+                durationMs: Date.now() - startTime,
+                stepOutputs,
+                serviceUrl,
+                externalIp,
+                outputDir: targetDir,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                target: plan.target,
+                durationMs: Date.now() - startTime,
+                stepOutputs,
+                outputDir: targetDir,
+                error: err.message || String(err),
+            };
+        }
+    }
+    ensureManifest(input) {
+        if (typeof input === 'string') {
+            return this.loadManifest(input);
+        }
+        if (typeof input === 'object' && input !== null) {
+            if ('version' in input && input.version === '1.0' && 'target' in input && 'source' in input) {
+                return input;
+            }
+            return this.createManifest(input);
+        }
+        return this.createManifest();
+    }
+}

package/dist/deploy/manifest.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Manifest parsing, creation, and resolution for Swarm deployments.
+ */
+import type { CreateManifestOptions, SwarmDeployManifest } from './types.js';
+/**
+ * Creates a well-formed SwarmDeployManifest using proven best-practice presets.
+ */
+export declare function createDeployManifest(options?: CreateManifestOptions): SwarmDeployManifest;
+/**
+ * Loads, validates, and resolves a SwarmDeployManifest from a JSON string or raw object.
+ * Automatically expands ${VAR_NAME} placeholders using environment variables or optional dictionary.
+ */
+export declare function loadDeployManifest(input: string | Record<string, unknown>, envLookup?: Record<string, string>): SwarmDeployManifest;
+/**
+ * Serializes a deployment manifest to formatted JSON.
+ */
+export declare function serializeDeployManifest(manifest: SwarmDeployManifest, indent?: number): string;