@swarm-agent/sdk 0.1.52 → 0.1.53

package/dist/projects.d.ts

@@ -1,5 +1,5 @@
 import type { SwarmTransport } from './transport.js';
-import type { ApproveProjectTaskResult, ClearProjectContextResult, CompleteProjectTaskResult, CreateProjectParams, CreateProjectTaskParams, CreateProjectTaskResult, DeleteProjectMediaResult, DeleteProjectResult, DeleteProjectTaskResult, DeployProjectTaskProgramResult, GetProjectTaskProgramResult, GetProjectTaskResult, IntegrateProjectTaskOptions, IntegrateProjectTaskResult, IntegrateProjectTaskSelection, ListProjectsParams, PreviewProjectTaskParams, ProjectRecord, ProjectTaskApprovalGuards, ProjectTaskMediaRef, ProjectTaskModelPreviewResult, ProjectTaskPreviewResult, ProjectTaskRecord, RedeployProjectTaskJobResult, RefineProjectTaskParams, RefineProjectTaskResult, RejectProjectTaskResult, ReopenProjectTaskResult, RequestOptions, SessionRecord, SyncStreamParams, SyncStreamResult, UpdateProjectParams, UpdateProjectTaskParams } from './types.js';
+import type { ApproveProjectTaskResult, CancelDesignJobResult, ClearProjectContextResult, CompleteProjectTaskResult, CreateDesignJobParams, CreateDesignJobResult, CreateProjectParams, CreateProjectTaskParams, CreateProjectTaskResult, DeleteProjectMediaResult, DeleteProjectResult, DeleteProjectTaskResult, DeployProjectTaskProgramResult, GetProjectTaskProgramResult, GetProjectTaskResult, IntegrateProjectTaskOptions, IntegrateProjectTaskResult, IntegrateProjectTaskSelection, ListProjectsParams, PreviewProjectTaskParams, ProjectRecord, ProjectTaskApprovalGuards, ProjectTaskMediaRef, ProjectTaskModelPreviewResult, ProjectTaskPreviewResult, ProjectTaskRecord, RedeployProjectTaskJobResult, RefineProjectTaskParams, RefineProjectTaskResult, RejectProjectTaskResult, ReopenProjectTaskResult, RequestOptions, SessionRecord, SyncStreamParams, SyncStreamResult, UpdateProjectParams, UpdateProjectTaskParams } from './types.js';
 export declare class SwarmProjectsNamespace {
     private readonly transport;
     constructor(transport: SwarmTransport);
@@ -89,6 +89,16 @@ export declare class SwarmProjectsNamespace {
      * Creates a new autonomous task inside a project.
      */
     createTask(projectId: string, params: CreateProjectTaskParams, options?: RequestOptions): Promise<CreateProjectTaskResult>;
+    /**
+     * Starts a design job: count standalone HTML designs (or an edit of one
+     * existing .html file) written into the project folder. Returns the job's
+     * task at once; read progress with getTask (task.design).
+     */
+    createDesignJob(projectId: string, params: CreateDesignJobParams, options?: RequestOptions): Promise<CreateDesignJobResult>;
+    /**
+     * Stops a running design job. Designs already written stay in the folder.
+     */
+    cancelDesignJob(projectId: string, taskId: string, options?: RequestOptions): Promise<CancelDesignJobResult>;
     /**
      * Retrieves a single task by ID within a project, including model preview.
      */

package/dist/projects.js

@@ -272,6 +272,36 @@ export class SwarmProjectsNamespace {
         }
         throw new SwarmApiError('Malformed response: missing task record', { status: res.status, details: data });
     }
+    /**
+     * Starts a design job: count standalone HTML designs (or an edit of one
+     * existing .html file) written into the project folder. Returns the job's
+     * task at once; read progress with getTask (task.design).
+     */
+    async createDesignJob(projectId, params, options) {
+        const id = encodeURIComponent(projectId.trim());
+        const res = await this.transport.request(`/v3/projects/${id}/design-jobs`, {
+            method: 'POST',
+            body: params,
+            ...options,
+        });
+        const data = res.data;
+        if (data && typeof data === 'object' && data.task && data.task.design) {
+            return { task: data.task };
+        }
+        throw new SwarmApiError('Malformed response: missing design job task', { status: res.status, details: data });
+    }
+    /**
+     * Stops a running design job. Designs already written stay in the folder.
+     */
+    async cancelDesignJob(projectId, taskId, options) {
+        const pId = encodeURIComponent(projectId.trim());
+        const tId = encodeURIComponent(taskId.trim());
+        const res = await this.transport.request(`/v3/projects/${pId}/design-jobs/${tId}/cancel`, { method: 'POST', body: {}, ...options });
+        if (res.data && typeof res.data === 'object' && typeof res.data.status === 'string') {
+            return res.data;
+        }
+        throw new SwarmApiError('Malformed response: missing design job cancel status', { status: res.status, details: res.data });
+    }
     /**
      * Retrieves a single task by ID within a project, including model preview.
      */

package/dist/sessions.js

@@ -28,11 +28,17 @@ export class SwarmSessionsNamespace {
                 workspace_path: params.workspace_path,
                 mode: params.mode ?? 'auto',
                 metadata: params.metadata,
+                ...(params.end_user !== undefined ? { end_user: params.end_user } : {}),
+                ...(params.labels !== undefined ? { labels: params.labels } : {}),
             },
         });
         const data = res.data;
         if (data && typeof data === 'object' && 'session' in data && data.session) {
-            return data.session;
+            return {
+                ...data.session,
+                ...(typeof data.end_user === 'string' ? { end_user: data.end_user } : {}),
+                ...(data.labels && typeof data.labels === 'object' ? { labels: data.labels } : {}),
+            };
         }
         return data;
     }
@@ -102,6 +108,8 @@ export class SwarmSessionsNamespace {
                 messages: data.messages,
                 last_run_id: sessionObj.last_run_id,
                 active_plan: data.active_plan,
+                ...(typeof data.end_user === 'string' ? { end_user: data.end_user } : {}),
+                ...(data.labels && typeof data.labels === 'object' ? { labels: data.labels } : {}),
                 raw: data,
             };
         }

package/dist/types.d.ts

@@ -36,17 +36,62 @@ export interface ScopedTokenRecord {
     scopes: TokenScope[];
     worker_id?: string;
     worker_name?: string;
+    /** The fixed end date, when the key has one (milliseconds; 0 or absent: none). */
     expires_at?: number;
+    /** ai, app, bot or internal (Swarm's own keys). */
+    key_kind?: KeyKind | 'internal';
+    /** An AI key's level (read, write, full); a bot key's gateway or operator; an app key's monitor or trigger. */
+    options?: string[];
+    /** active, expired or revoked. */
+    state?: 'active' | 'expired' | 'revoked';
+    /** When the key stops working on its own (milliseconds): 90 days after its last use, or its fixed end date if sooner. */
+    lapses_at?: number;
+    /** unused (90 days without use) or date (its fixed end date). */
+    lapse_reason?: 'unused' | 'date';
+    /** True when the key carries a fixed end date. */
+    fixed_date?: boolean;
+    /** True only for Swarm's internal keys, which last as long as the setup that made them. */
+    never_expires?: boolean;
     last_used_at?: number;
+    /** Where the key was last used from: "this machine", "tailnet LOGIN" or a network such as 203.0.113.0/24. */
+    last_used_from?: string;
+    /** Every place the key has been used from (newest last, bounded). */
+    seen_from?: string[];
     created_at: number;
     revoked?: boolean;
     revoked_at?: number;
 }
+/** The three kinds of key a person or their AI holds. */
+export type KeyKind = 'ai' | 'app' | 'bot';
+/**
+ * A key for createKey. Every key works while it is used and stops after 90
+ * days unused; expires_in_seconds adds an optional fixed end date (at most 365
+ * days). kind ai: access read, write or full. kind app: scopes, or monitor for
+ * a status-only key. kind bot: agent_name (a sealed agent), operator for the
+ * staff key, and its limits.
+ */
+export interface CreateKeyParams {
+    kind: KeyKind;
+    name: string;
+    access?: 'read' | 'write' | 'full';
+    scopes?: TokenScope[];
+    monitor?: boolean;
+    agent_name?: string;
+    operator?: boolean;
+    messages_per_minute?: number;
+    sessions_per_hour?: number;
+    max_concurrent_runs?: number;
+    end_user_messages_per_minute?: number;
+    end_user_sessions_per_hour?: number;
+    end_user_max_tokens_per_day?: number;
+    expires_in_seconds?: number;
+}
 export interface CreateScopedTokenParams {
     name: string;
     scopes: TokenScope[];
     worker_id?: string;
     worker_name?: string;
+    /** Optional fixed end date (at most 365 days). Without it the key works while used and stops after 90 days unused. */
     expires_in_seconds?: number;
 }
 export interface CreateScopedTokenResult {
@@ -291,6 +336,9 @@ export interface SessionRecord {
     archived?: boolean;
     archived_at?: number;
     last_run_id?: string;
+    /** Set when a gateway created the session for an end user. */
+    end_user?: string;
+    labels?: Record<string, string>;
 }
 export interface CreateSessionParams {
     title?: string;
@@ -302,6 +350,14 @@ export interface CreateSessionParams {
     mode?: 'auto' | 'plan';
     client_request_id?: string;
     metadata?: Record<string, unknown>;
+    /**
+     * Whose conversation this is (your customer or visitor id): 1-128 letters,
+     * digits and `. _ : @ + = -`. Only a gateway token may set it, once; the model
+     * never sees it, and per-end-user limits and usage use it.
+     */
+    end_user?: string;
+    /** Up to 16 labels stored with the session (keys: lowercase identifiers; values: up to 256 characters). */
+    labels?: Record<string, string>;
 }
 export interface ListSessionsParams {
     limit?: number;
@@ -331,6 +387,9 @@ export interface SessionDetail {
     messages?: SessionMessage[];
     last_run_id?: string;
     active_plan?: unknown;
+    /** Set when a gateway created the session for an end user. */
+    end_user?: string;
+    labels?: Record<string, string>;
     raw?: Record<string, unknown>;
 }
 export interface WorkspaceRecord {
@@ -633,9 +692,88 @@ export interface ProjectTaskRecord {
     task_program?: any;
     task_program_id?: string;
     task_program_status?: any;
+    /** Present when the task is a design job (createDesignJob). */
+    design?: ProjectTaskDesignJob;
     created_at: number;
     updated_at: number;
 }
+/** One check finding kept on a design job item. */
+export interface ProjectTaskDesignDiagnostic {
+    kind: string;
+    message?: string;
+}
+/** One design's durable outcome in a design job. */
+export interface ProjectTaskDesignItem {
+    n: number;
+    path?: string;
+    sha256?: string;
+    status: 'passed' | 'repaired' | 'failed' | 'check_unavailable' | 'generation_failed' | 'skipped_budget' | 'cancelled' | 'stale_base' | 'edit_refused' | string;
+    error?: string;
+    variation?: string;
+    check?: string;
+    diagnostics?: ProjectTaskDesignDiagnostic[];
+    repair_edits?: number;
+    repair_refused?: string;
+    check_after_repair?: string;
+    diagnostics_after_repair?: ProjectTaskDesignDiagnostic[];
+    calls: number;
+    tokens: number;
+    /** Absent when the provider reported no usage or the model has no price. */
+    cost_usd?: number;
+    usage_complete: boolean;
+    duration_ms: number;
+}
+/** The request and outcome of a design job. */
+export interface ProjectTaskDesignJob {
+    mode: 'create' | 'edit';
+    brief: string;
+    count: number;
+    style?: string;
+    variations?: string[];
+    batch_name?: string;
+    /** The job's own output folder, relative to the workspace (create). */
+    folder?: string;
+    results_path?: string;
+    edit_path?: string;
+    state: 'running' | 'completed' | 'failed' | 'cancelled';
+    error?: string;
+    provider?: string;
+    model?: string;
+    thinking?: string;
+    items?: ProjectTaskDesignItem[];
+    counts?: Record<string, number>;
+    calls: number;
+    tokens: number;
+    cost_usd: number;
+    cost_complete: boolean;
+    edit_base_sha256?: string;
+    edit_final_sha256?: string;
+    results_error?: string;
+    started_at: number;
+    finished_at?: number;
+}
+/** Body of createDesignJob: make count designs, or edit one HTML file. */
+export interface CreateDesignJobParams {
+    /** Absolute folder of the project; required when the project has several. */
+    workspace?: string;
+    brief: string;
+    /** 1 to 50 (default 1); an edit is always 1. */
+    count?: number;
+    style?: string;
+    variations?: string[];
+    batch_name?: string;
+    /** Parent folder for batches, relative to the workspace (default designs). */
+    folder?: string;
+    /** Edit this existing .html file (relative to the workspace) instead. */
+    edit_path?: string;
+}
+export interface CreateDesignJobResult {
+    task: ProjectTaskRecord;
+}
+export interface CancelDesignJobResult {
+    task_id: string;
+    status: string;
+}
 export interface CreateProjectTaskParams {
     id?: string;
     title: string;
@@ -1035,7 +1173,25 @@ export interface WorkerRevisionRecord {
     committed_by?: string;
     change_summary?: string;
 }
+export interface JobReview {
+    verdict: 'ok' | 'block';
+    head: string;
+    reviewer_job_id: string;
+    model: string;
+    at: number;
+    reason?: string;
+    /** Set when a fixing reviewer committed on top of `head`: the verdict covers `head` only with those fixes. */
+    fix_head?: string;
+    stale: boolean;
+}
 export interface WorkerRunRecord {
+    review?: Partial<JobReview> & {
+        state?: string;
+        project_id?: string;
+        task_id?: string;
+        task_status?: string;
+        next_action?: string;
+    };
     placement?: import('./worker-control.js').WorkerRunPlacement;
     cancel_requested?: boolean;
     id: string;
@@ -1185,6 +1341,8 @@ export interface SetWorkerAutomationEnabledParams {
     expected_worker_revision: number;
 }
 export interface DirectWorkerRequestParams {
+    /** Required for reviewer workers: worker/<worker>/<run> in the same project, with commits. */
+    review_job?: string;
     worker_id: string;
     prompt?: string;
     input?: Record<string, unknown>;

package/dist/workers.js

@@ -608,6 +608,8 @@ export class SwarmWorkersNamespace {
         const body = {};
         if (hasPrompt)
             body.prompt = params.prompt.trim();
+        if (params.review_job !== undefined)
+            body.review_job = params.review_job.trim();
         if (params.input)
             body.input = params.input;
         if (params.idempotency_key)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarm-agent/sdk",
-  "version": "0.1.52",
+  "version": "0.1.53",
   "description": "Official TypeScript SDK for Swarm local AI coding workspace",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,12 +42,12 @@
     "node": ">=22"
   },
   "dependencies": {
-    "ws": "8.18.3"
+    "ws": "8.22.0"
   },
   "devDependencies": {
     "@types/node": "22.19.15",
     "@types/ws": "^8.18.2",
-    "tsx": "4.21.0",
+    "tsx": "4.23.15",
     "typescript": "5.9.3"
   },
   "keywords": [