@swarm-agent/sdk 0.1.47 → 0.1.49

package/dist/worker-control.js

@@ -0,0 +1,93 @@
+import { SwarmValidationError } from './errors.js';
+const id = (value) => {
+    if (typeof value !== 'string' || !/^[a-zA-Z0-9_.-]{3,128}$/.test(value))
+        throw new SwarmValidationError('Invalid worker control identity');
+    return encodeURIComponent(value);
+};
+const revision = (value, zero = false) => {
+    if (!Number.isSafeInteger(value) || value < (zero ? 0 : 1))
+        throw new SwarmValidationError('Exact revision is required');
+};
+const key = (value) => {
+    if (typeof value !== 'string' || !value.trim() || value !== value.trim() || value.length > 256 || /[/\\\r\n\0]/.test(value))
+        throw new SwarmValidationError('Stable idempotency key is required');
+};
+/** Durable configuration/queued intent only. No SSH, cloud credentials or remote executor. */
+export class SwarmWorkerControlNamespace {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    path(worker, tail) { return `/v3/workers/${id(worker)}/${tail}`; }
+    async call(path, method, field, body, array = false) {
+        const result = await this.transport.request(path, { method, ...(body === undefined ? {} : { body }) });
+        const value = result.data?.[field];
+        if (array ? !Array.isArray(value) : !value || typeof value !== 'object' || Array.isArray(value))
+            throw new SwarmValidationError(`Malformed worker control envelope: ${field}`);
+        return value;
+    }
+    registerSSHTarget(worker, request) {
+        key(request.idempotency_key);
+        return this.call(this.path(worker, 'ssh-targets'), 'POST', 'target', request);
+    }
+    registerGCPTarget(worker, request) {
+        key(request.idempotency_key);
+        return this.call(this.path(worker, 'gcp-targets'), 'POST', 'target', request);
+    }
+    resolveTarget(worker, target) {
+        if (!['ssh', 'gcp'].includes(target.kind) || !Number.isInteger(target.capacity) || target.capacity < 1 || target.capacity > 100)
+            throw new SwarmValidationError('Invalid target capability');
+        return this.call(this.path(worker, 'target-reference'), 'POST', 'target', target);
+    }
+    getContext(worker, atRevision) {
+        if (atRevision !== undefined)
+            revision(atRevision);
+        return this.call(this.path(worker, `context${atRevision === undefined ? '' : `?revision=${atRevision}`}`), 'GET', 'context');
+    }
+    updateContext(worker, request) {
+        revision(request.expected_revision, true);
+        if (!request.provenance.trim())
+            throw new SwarmValidationError('Context provenance is required');
+        return this.call(this.path(worker, 'context'), 'PUT', 'context', request);
+    }
+    proposeDeployment(worker, request) {
+        revision(request.worker_revision);
+        revision(request.context_revision, true);
+        key(request.idempotency_key);
+        if (!['persistent', 'on_demand'].includes(request.lifecycle))
+            throw new SwarmValidationError('Explicit lifecycle is required');
+        return this.call(this.path(worker, 'deployments'), 'POST', 'deployment', request);
+    }
+    listDeployments(worker) { return this.call(this.path(worker, 'deployments'), 'GET', 'deployments', undefined, true); }
+    getDeployment(worker, deployment) { return this.call(this.path(worker, `deployments/${id(deployment)}`), 'GET', 'deployment'); }
+    /** Explicit user approval of the exact digest; does not start a runtime. */
+    approveDeployment(worker, deployment, expectedRevision, approvalDigest) {
+        revision(expectedRevision);
+        if (!approvalDigest.trim())
+            throw new SwarmValidationError('Approval digest required');
+        return this.call(this.path(worker, `deployments/${id(deployment)}/approve`), 'POST', 'deployment', { expected_revision: expectedRevision, approval_digest: approvalDigest });
+    }
+    queueJob(worker, deployment, request) {
+        revision(request.worker_revision);
+        revision(request.deployment_revision);
+        revision(request.context_revision, true);
+        key(request.idempotency_key);
+        return this.call(this.path(worker, `deployments/${id(deployment)}/jobs`), 'POST', 'run', request);
+    }
+    /** Start rejects with service unavailable. Stop is durable pending intent, not acknowledgement. */
+    command(worker, deployment, request) {
+        revision(request.expected_revision);
+        revision(request.generation);
+        key(request.idempotency_key);
+        return this.call(this.path(worker, `deployments/${id(deployment)}/commands`), 'POST', 'command', request);
+    }
+    commands(worker, deployment) { return this.call(this.path(worker, `deployments/${id(deployment)}/commands`), 'GET', 'commands', undefined, true); }
+    acknowledgeCommand(worker, deployment, commandId, ack) {
+        revision(ack.generation);
+        if (!['acknowledged', 'rejected'].includes(ack.status))
+            throw new SwarmValidationError('Invalid command status');
+        if (!ack.evidence_digest || ack.evidence_digest.length !== 64)
+            throw new SwarmValidationError('Invalid evidence digest');
+        return this.call(this.path(worker, `deployments/${id(deployment)}/commands/${id(commandId)}/ack`), 'POST', 'command', ack);
+    }
+}

package/dist/workers.d.ts

@@ -1,4 +1,5 @@
 import type { SwarmTransport } from './transport.js';
+import { SwarmWorkerControlNamespace } from './worker-control.js';
 import type { WorkerRecord, WorkerRevisionRecord, WorkerRunRecord, PortableWorkerDefinition, CreateWorkerParams, UpdateWorkerParams, ListWorkersParams, ListWorkersResult, AttachWorkerAutomationParams, UpdateWorkerAutomationParams, RemoveWorkerAutomationParams, WorkerValidateResult, WorkerExportResult, ImportWorkerOptions, ActivateWorkerParams, PauseWorkerParams, ResumeWorkerParams, ArchiveWorkerParams, DeleteWorkerParams, SetWorkerAutomationEnabledParams, DirectWorkerRequestParams, TestWorkerRunParams, TriggerWorkerParams, MintWorkerTriggerTokenParams, MintWorkerTriggerTokenResult, ListWorkerRunsParams, ListWorkerRunsResult, GetWorkerRunParams, CancelWorkerRunParams } from './types.js';
 /**
  * SwarmWorkersNamespace manages durable, account-owned workers, their revisions,
@@ -7,6 +8,7 @@ import type { WorkerRecord, WorkerRevisionRecord, WorkerRunRecord, PortableWorke
  * Distinct from legacy SwarmAutomationsNamespace which targets /v3/automations/v2.
  */
 export declare class SwarmWorkersNamespace {
+    readonly control: SwarmWorkerControlNamespace;
     private transport;
     constructor(transport: SwarmTransport);
     /**

package/dist/workers.js

@@ -1,3 +1,4 @@
+import { SwarmWorkerControlNamespace } from './worker-control.js';
 import { SwarmValidationError } from './errors.js';
 /**
  * SwarmWorkersNamespace manages durable, account-owned workers, their revisions,
@@ -6,9 +7,11 @@ import { SwarmValidationError } from './errors.js';
  * Distinct from legacy SwarmAutomationsNamespace which targets /v3/automations/v2.
  */
 export class SwarmWorkersNamespace {
+    control;
     transport;
     constructor(transport) {
         this.transport = transport;
+        this.control = new SwarmWorkerControlNamespace(transport);
     }
     /**
      * Creates a new durable worker in idle state.

package/examples/headless-worker-control.ts

@@ -0,0 +1,28 @@
+import type { SwarmClient, WorkerSSHRegistration } from '../src/index.js';
+
+/** Configuration only. Supply an already authenticated private SDK client and
+ * an existing worker. No browser, SSH command, provider key or cloud helper. */
+export async function proposeHeadlessPlacements(
+  client: SwarmClient,
+  workerId: string,
+  targets: WorkerSSHRegistration[],
+) {
+  if (targets.length < 1 || targets.length > 10) throw new Error('Supply 1–10 explicit SSH targets');
+  const worker = await client.workers.get(workerId);
+  if (!worker) throw new Error('Worker not found');
+  const context = await client.workers.control.getContext(worker.id);
+  const proposals = [];
+  for (const registration of targets) {
+    const target = await client.workers.control.registerSSHTarget(worker.id, registration);
+    proposals.push(await client.workers.control.proposeDeployment(worker.id, {
+      worker_revision: worker.revision,
+      context_revision: context.revision,
+      target,
+      lifecycle: 'on_demand',
+      idempotency_key: `placement-${registration.idempotency_key}`,
+    }));
+  }
+  // Present exact revisions/digests to the authorized human. Do not automatically
+  // approve them or report online: every observed_state is currently unavailable.
+  return proposals;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarm-agent/sdk",
-  "version": "0.1.47",
+  "version": "0.1.49",
   "description": "Official TypeScript SDK for Swarm local AI coding workspace",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,11 +9,17 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
     }
   },
   "files": [
     "dist",
     "examples/headless-session.ts",
+    "examples/headless-worker-control.ts",
+    "WORKER_CONTROL.md",
     "README.md",
     "APPLICATIONS.md",
     "HEADLESS_UI.md",
@@ -40,6 +46,7 @@
   },
   "devDependencies": {
     "@types/node": "22.19.15",
+    "@types/ws": "^8.18.2",
     "tsx": "4.21.0",
     "typescript": "5.9.3"
   },