@swarm-agent/sdk 0.1.47

package/dist/workspaces.d.ts

@@ -0,0 +1,81 @@
+import type { SwarmTransport } from './transport.js';
+import type { WorkspaceRecord } from './types.js';
+export declare class SwarmWorkspacesNamespace {
+    private transport;
+    constructor(transport: SwarmTransport);
+    createFolder(parent_path: string, name: string): Promise<WorkspaceFolder>;
+    add(body: {
+        path: string;
+        name?: string;
+        theme_id?: string;
+        make_current?: boolean;
+        confirm_committed_only?: boolean;
+    }): Promise<WorkspaceResolution>;
+    inspectRepository(path: string): Promise<WorkspaceRepository>;
+    setupRepository(path: string, expected_resolved_path: string): Promise<WorkspaceRepository>;
+    reviewRepository(path: string): Promise<WorkspaceRepositoryReview>;
+    baselineRepository(body: {
+        path: string;
+        expected_resolved_path: string;
+        review_digest: string;
+        selected_paths: string[];
+        confirm_baseline: boolean;
+        confirm_omissions: boolean;
+    }): Promise<WorkspaceRepository>;
+    /**
+     * Lists all workspaces registered with the daemon for the active principal.
+     */
+    list(options?: {
+        limit?: number;
+    }): Promise<WorkspaceRecord[]>;
+    /**
+     * Retrieves the currently active workspace.
+     */
+    current(): Promise<WorkspaceRecord | null>;
+    /**
+     * Resolves a host filesystem path to a registered workspace record.
+     */
+    resolve(path: string): Promise<WorkspaceRecord>;
+}
+export interface WorkspaceFolder {
+    path: string;
+    name: string;
+    parent_path: string;
+    requires_sudo: boolean;
+    permission_error_message?: string;
+}
+export interface WorkspaceResolution {
+    requested_path: string;
+    resolved_path: string;
+    workspace_path: string;
+    workspace_name: string;
+    workspace_id?: string;
+    local_workspace_binding_id?: string;
+    workspace_generation?: number;
+    workspace_state?: string;
+    [key: string]: unknown;
+}
+export interface WorkspaceRepository {
+    state: string;
+    path: string;
+    repository_root?: string;
+    head_commit?: string;
+    can_setup: boolean;
+    needs_review?: boolean;
+    message: string;
+    content_ready: boolean;
+    runtime_accessible: boolean;
+    actions?: string[];
+}
+export interface WorkspaceRepositoryReview {
+    repository: WorkspaceRepository;
+    digest: string;
+    warning: string;
+    files: {
+        path: string;
+        size: number;
+        mode: number;
+        digest: string;
+        selectable: boolean;
+    }[];
+}

package/dist/workspaces.js

@@ -0,0 +1,58 @@
+export class SwarmWorkspacesNamespace {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async createFolder(parent_path, name) {
+        return (await this.transport.request('/v1/workspace/folders/create', { method: 'POST', body: { parent_path, name } })).data.folder;
+    }
+    async add(body) {
+        return (await this.transport.request('/v1/workspace/add', { method: 'POST', body })).data.workspace;
+    }
+    async inspectRepository(path) {
+        return (await this.transport.request(`/v1/workspace/repository?${new URLSearchParams({ path })}`)).data.repository;
+    }
+    async setupRepository(path, expected_resolved_path) {
+        return (await this.transport.request('/v1/workspace/repository/setup', { method: 'POST', body: { path, expected_resolved_path } })).data.repository;
+    }
+    async reviewRepository(path) {
+        return (await this.transport.request(`/v1/workspace/repository/review?${new URLSearchParams({ path })}`)).data.review;
+    }
+    async baselineRepository(body) {
+        return (await this.transport.request('/v1/workspace/repository/baseline', { method: 'POST', body })).data.repository;
+    }
+    /**
+     * Lists all workspaces registered with the daemon for the active principal.
+     */
+    async list(options = {}) {
+        const q = new URLSearchParams();
+        if (options.limit && options.limit > 0) {
+            q.set('limit', options.limit.toString());
+        }
+        const queryStr = q.toString() ? `?${q.toString()}` : '';
+        const res = await this.transport.request(`/v1/workspace/list${queryStr}`, { method: 'GET' });
+        const workspaces = res.data?.workspaces ?? [];
+        return workspaces.map((w) => ({
+            ...w,
+            name: w.name || w.workspace_name || '',
+            workspace_name: w.workspace_name || w.name || '',
+        }));
+    }
+    /**
+     * Retrieves the currently active workspace.
+     */
+    async current() {
+        const res = await this.transport.request('/v1/workspace/current', { method: 'GET' });
+        return res.data?.workspace ?? null;
+    }
+    /**
+     * Resolves a host filesystem path to a registered workspace record.
+     */
+    async resolve(path) {
+        const res = await this.transport.request('/v1/workspace/resolve', {
+            method: 'POST',
+            body: { path },
+        });
+        return res.data.workspace;
+    }
+}

package/examples/headless-session.ts

@@ -0,0 +1,85 @@
+import { open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+import { pathToFileURL } from 'node:url';
+import { SwarmClient } from '@swarm-agent/sdk';
+
+// Uses the installed package (or package self-reference after npm run build).
+// No Desktop bootstrap, privileged socket, automatic approval, or status polling.
+export async function runHeadlessSession(
+  client: SwarmClient,
+  prompt: string,
+  ask: (question: string) => Promise<string>,
+  show: (value: string) => void,
+): Promise<void> {
+  const session = await client.sessions.create({
+    title: 'Headless SDK session', workspace_path: '/project', mode: 'auto',
+  });
+  show(`Session: ${session.id}`);
+  const receipt = await client.sessions.sendMessage(session.id, { content: prompt });
+  if (!receipt?.run_intent?.run_id) throw new Error('Prompt accepted without a run receipt; inspect the session before retrying');
+  show(`Run: ${receipt.run_intent.run_id}; receipt is not completion.`);
+  for (;;) {
+    const detail = await client.sessions.get(session.id);
+    const raw = detail.raw as Record<string, any>;
+    show(JSON.stringify({
+      state: detail.state, messages: detail.messages,
+      active_run_intent: raw.active_run_intent,
+      current_run_state: raw.current_run_state,
+      pending_permissions: raw.pending_permissions,
+      active_plan: raw.active_plan,
+    }, null, 2));
+    const command = (await ask('refresh | allow <permission-id> | deny <permission-id> | stop | quit: ')).trim();
+    if (command === 'quit') return; // Disconnecting does NOT stop a durable run.
+    if (command === 'refresh') continue; // Explicit user refresh, never a timer.
+    if (command === 'stop') {
+      const runId = raw.active_run_intent?.run_id;
+      if (!runId) { show('No active run in the current snapshot.'); continue; }
+      await client.sessions.stopRun(session.id, { run_id: runId });
+      continue;
+    }
+    const match = /^(allow|deny) (\S+)$/.exec(command);
+    const pending = Array.isArray(raw.pending_permissions) ? raw.pending_permissions : [];
+    const permission = match && pending.find((p: any) => p.id === match[2]);
+    if (!match || !permission) { show('Choose an exact permission ID from the current snapshot, or refresh.'); continue; }
+    // A second explicit confirmation prevents accidental approval on pasted input.
+    if (match[1] === 'allow') {
+      if (await ask(`Approve ONLY ${permission.id} once? Type yes: `) !== 'yes') continue;
+      await client.sessions.approvePermissionOnce(session.id, permission.id, 'Explicit SDK operator approval');
+    } else {
+      await client.sessions.denyPermission(session.id, permission.id, 'SDK operator denied');
+    }
+  }
+}
+
+async function main(): Promise<void> {
+  const file = process.env.SWARM_SDK_TOKEN_FILE;
+  if (!file) throw new Error('Set SWARM_SDK_TOKEN_FILE to the private token JSON export');
+  const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  let token: string;
+  try {
+    const st = await handle.stat();
+    if (!st.isFile() || (st.mode & 0o077) !== 0 || st.size > 16384) throw new Error('Token file must be a private regular file, at most 16384 bytes');
+    token = JSON.parse(await handle.readFile('utf8')).token;
+    if (typeof token !== 'string' || !token.startsWith('swk_')) throw new Error('Invalid scoped token file');
+  } finally { await handle.close(); }
+  const url = new URL(process.env.SWARM_SDK_URL ?? 'http://127.0.0.1:7783');
+  if (url.protocol !== 'http:' || !['127.0.0.1', '[::1]'].includes(url.hostname) || url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+    throw new Error('This example requires the loopback-published HTTP endpoint');
+  }
+  const client = new SwarmClient({ baseUrl: url.origin, token, timeoutMs: 15000 });
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const prompt = await rl.question('Prompt for /project: ');
+    if (!prompt.trim()) throw new Error('Prompt is required');
+    await runHeadlessSession(client, prompt, q => rl.question(q), text => console.log(text));
+  } finally { rl.close(); }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch(() => {
+    // API/transport errors may carry private response bodies. Do not dump them.
+    console.error('SDK operation failed. Check listener, token expiry/scopes and session state before retrying; details withheld.');
+    process.exitCode = 1;
+  });
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@swarm-agent/sdk",
+  "version": "0.1.47",
+  "description": "Official TypeScript SDK for Swarm local AI coding workspace",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "examples/headless-session.ts",
+    "README.md",
+    "APPLICATIONS.md",
+    "HEADLESS_UI.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/swarm-agent/swarm.git"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "npm run build",
+    "test": "tsx --test --test-concurrency=1 ./src/__tests__/*.spec.ts"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "ws": "8.18.3"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.15",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3"
+  },
+  "keywords": [
+    "swarm",
+    "sdk",
+    "ai",
+    "agents",
+    "automation",
+    "workers"
+  ],
+  "author": "Swarm Team",
+  "license": "Apache-2.0"
+}