@swarm-agent/sdk 0.1.48 → 0.1.50

package/dist/copy-tags.js

@@ -0,0 +1,133 @@
+/**
+ * Swarm agents wrap copyable snippets (commands, config, file payloads) in
+ * `<copy label="...">…</copy>` tags. Swarm's own desktop and terminal UIs render
+ * them as copy buttons; everywhere else they are noise. `copyTagsToMarkdown`
+ * turns each tag into a plain Markdown code block (with its label, if any, as a
+ * bold line above it), so any Markdown renderer shows it correctly.
+ *
+ * Rules (same parsing as Swarm's own renderers):
+ * - Tags inside fenced code blocks (``` or ~~~) are left untouched.
+ * - The label comes from `label`, `title` or `name`.
+ * - A tag that is never closed becomes a code block running to the end.
+ * - Text without copy tags is returned unchanged.
+ *
+ * Pass `{ streaming: true }` for text that is still arriving: a half-written tag
+ * at the very end is hidden, so converting the growing text only ever appends.
+ *
+ * The SDK applies it by default to assistant text from `chat.run`,
+ * `chat.listMessages` and `chat.stream` (`onText`, `onComplete`); pass
+ * `rawCopyTags: true` there to get the original text. Lower-level reads
+ * (`sessions.get`, `realtime.watchSession`) return the stored text unchanged.
+ */
+export function copyTagsToMarkdown(text, options = {}) {
+    if (typeof text !== 'string' || !text)
+        return text;
+    const streaming = options.streaming === true;
+    if (!(streaming ? /</.test(text) : /<copy[\s>]/i.test(text)))
+        return text;
+    const source = text.replace(/\r\n?/g, '\n');
+    const protectedRanges = fencedRanges(source);
+    let out = '';
+    let cursor = 0;
+    while (cursor < source.length) {
+        const open = nextOpenTag(source, cursor, protectedRanges);
+        if (!open) {
+            out += source.slice(cursor);
+            break;
+        }
+        out += source.slice(cursor, open.start);
+        const afterOpen = source.slice(open.end);
+        const closeIndex = afterOpen.toLowerCase().indexOf('</copy>');
+        if (closeIndex < 0) {
+            let body = afterOpen;
+            if (streaming)
+                body = body.replace(PARTIAL_CLOSE_TAIL, '');
+            return out + renderBlock(out, tagLabel(open.tag), body.replace(/^\n+/, ''), false, streaming);
+        }
+        // Streaming keeps trailing newlines it may already have delivered.
+        const body = afterOpen.slice(0, closeIndex).replace(streaming ? /^\n+/ : /^\n+|\n+$/g, '');
+        out += renderBlock(out, tagLabel(open.tag), body, true, streaming);
+        cursor = open.end + closeIndex + '</copy>'.length;
+        if (cursor < source.length && source[cursor] !== '\n')
+            out += '\n';
+    }
+    if (streaming && !inside(out.length - 1, fencedRanges(out)))
+        out = out.replace(PARTIAL_OPEN_TAIL, '');
+    return out;
+}
+/** True when `text` contains at least one `<copy>` tag outside fenced code. */
+export function hasCopyTags(text) {
+    if (typeof text !== 'string' || !/<copy[\s>]/i.test(text))
+        return false;
+    const source = text.replace(/\r\n?/g, '\n');
+    return nextOpenTag(source, 0, fencedRanges(source)) !== undefined;
+}
+const OPEN_TAG = /<copy(?:\s+[^>]*)?>/gi;
+const LABEL_ATTR = /\b(?:label|title|name)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i;
+// Streaming only: a tag cut off at the very end (`<`, `<co`, `<copy label="x`).
+const PARTIAL_OPEN_TAIL = /<(?:c(?:o(?:p(?:y(?:\s[^<>]*)?)?)?)?)?$/i;
+const PARTIAL_CLOSE_TAIL = /<\/?(?:c(?:o(?:p(?:y)?)?)?)?$/i;
+function renderBlock(before, label, body, closed, streaming) {
+    let longest = 0;
+    for (const run of body.match(/`+/g) ?? [])
+        longest = Math.max(longest, run.length);
+    // Streaming uses a 4-backtick fence so a payload that later shows a ``` line does
+    // not force re-fencing text that was already delivered.
+    const fence = '`'.repeat(Math.max(streaming ? 4 : 3, longest + 1));
+    const lead = before === '' || before.endsWith('\n') ? '' : '\n';
+    const title = label ? `**${label}**\n` : '';
+    // An open (still streaming) block gets no trailing newline, so later text only appends.
+    return closed
+        ? `${lead}${title}${fence}\n${body}${body && !body.endsWith('\n') ? '\n' : ''}${fence}`
+        : `${lead}${title}${fence}\n${body}`;
+}
+function tagLabel(tag) {
+    const match = LABEL_ATTR.exec(tag);
+    if (!match)
+        return '';
+    return (match[1] ?? match[2] ?? match[3] ?? '').trim();
+}
+function inside(index, ranges) {
+    return ranges.some((range) => index >= range.start && index < range.end);
+}
+function nextOpenTag(text, from, ranges) {
+    OPEN_TAG.lastIndex = from;
+    for (let match = OPEN_TAG.exec(text); match; match = OPEN_TAG.exec(text)) {
+        const start = match.index;
+        const range = ranges.find((r) => start >= r.start && start < r.end);
+        if (range) {
+            OPEN_TAG.lastIndex = Math.max(range.end, start + match[0].length);
+            continue;
+        }
+        return { start, end: start + match[0].length, tag: match[0] };
+    }
+    return undefined;
+}
+function fencedRanges(text) {
+    const ranges = [];
+    let fence;
+    let lineStart = 0;
+    while (lineStart < text.length) {
+        const newline = text.indexOf('\n', lineStart);
+        const lineEnd = newline < 0 ? text.length : newline;
+        const next = newline < 0 ? text.length : newline + 1;
+        const line = text.slice(lineStart, lineEnd).trim();
+        const marker = line[0];
+        if (marker === '`' || marker === '~') {
+            let count = 0;
+            while (line[count] === marker)
+                count++;
+            const info = line.slice(count).trim();
+            if (!fence && count >= 3)
+                fence = { marker, count, start: lineStart };
+            else if (fence && marker === fence.marker && count >= fence.count && info === '') {
+                ranges.push({ start: fence.start, end: next });
+                fence = undefined;
+            }
+        }
+        lineStart = next;
+    }
+    if (fence)
+        ranges.push({ start: fence.start, end: text.length });
+    return ranges;
+}

package/dist/errors.d.ts

@@ -34,3 +34,19 @@ export declare class SwarmValidationError extends SwarmError {
     readonly details?: unknown;
     constructor(message: string, details?: unknown);
 }
+/**
+ * `chat_reconnecting`: the connection to this conversation is being restored; retry shortly.
+ * `chat_disconnected`: the connection is down and will not come back on its own; call `connect()`.
+ * `chat_not_subscribed`: the conversation is not open in this client; `subscribe()` to it first.
+ */
+export type SwarmChatNotReadyCode = 'chat_reconnecting' | 'chat_disconnected' | 'chat_not_subscribed';
+/**
+ * A browser chat send refused before anything reached Swarm. The message is plain enough
+ * to show people; apps branch on `code` (or `retryable`) instead of matching text.
+ */
+export declare class SwarmChatNotReadyError extends SwarmError {
+    readonly code: SwarmChatNotReadyCode;
+    /** True when retrying the same send shortly is expected to work without app action. */
+    readonly retryable: boolean;
+    constructor(code: SwarmChatNotReadyCode);
+}

package/dist/errors.js

@@ -66,3 +66,24 @@ export class SwarmValidationError extends SwarmError {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
+const chatNotReadyMessages = {
+    chat_reconnecting: 'Not sent: reconnecting to Swarm, try again in a moment',
+    chat_disconnected: 'Not sent: disconnected from Swarm, reconnect and try again',
+    chat_not_subscribed: 'Not sent: this conversation is not open yet, open it and try again',
+};
+/**
+ * A browser chat send refused before anything reached Swarm. The message is plain enough
+ * to show people; apps branch on `code` (or `retryable`) instead of matching text.
+ */
+export class SwarmChatNotReadyError extends SwarmError {
+    code;
+    /** True when retrying the same send shortly is expected to work without app action. */
+    retryable;
+    constructor(code) {
+        super(chatNotReadyMessages[code]);
+        this.name = 'SwarmChatNotReadyError';
+        this.code = code;
+        this.retryable = code === 'chat_reconnecting';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './client.js';
+export * from './local-connection.js';
 export * from './auth.js';
 export * from './automations.js';
 export * from './workers.js';
@@ -6,12 +7,17 @@ export * from './worker-control.js';
 export * from './deliverables.js';
 export * from './deploy/index.js';
 export * from './notifications.js';
+export * from './signals.js';
+export * from './box.js';
 export * from './sessions.js';
 export * from './projects.js';
 export * from './permissions.js';
 export * from './chat.js';
+export * from './copy-tags.js';
 export * from './workspaces.js';
 export * from './system.js';
+export * from './remote.js';
+export * from './agents.js';
 export * from './transport.js';
 export * from './errors.js';
 export * from './types.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './client.js';
+export * from './local-connection.js';
 export * from './auth.js';
 export * from './automations.js';
 export * from './workers.js';
@@ -6,12 +7,17 @@ export * from './worker-control.js';
 export * from './deliverables.js';
 export * from './deploy/index.js';
 export * from './notifications.js';
+export * from './signals.js';
+export * from './box.js';
 export * from './sessions.js';
 export * from './projects.js';
 export * from './permissions.js';
 export * from './chat.js';
+export * from './copy-tags.js';
 export * from './workspaces.js';
 export * from './system.js';
+export * from './remote.js';
+export * from './agents.js';
 export * from './transport.js';
 export * from './errors.js';
 export * from './types.js';

package/dist/local-connection.d.ts

@@ -0,0 +1,39 @@
+/**
+ * How a client with no explicit address finds this machine's Swarm.
+ *
+ * Order: an explicit `socketPath`/`baseUrl`, then `SWARM_SOCKET_PATH`, then
+ * `SWARM_API_URL`/`SWARM_DESKTOP_URL`, then (Node only) the owner socket of a
+ * system install when it exists and this process may connect to it, then the
+ * daemon's default loopback API at http://127.0.0.1:7781.
+ *
+ * Browsers never touch the filesystem: the probe uses Node's synchronous
+ * `process.getBuiltinModule`, which no bundler resolves and no browser has.
+ */
+/** Owner socket of a Linux system install (`/var/lib/swarmd` data root, main lane). */
+export declare const SWARM_OWNER_SOCKET_PATH = "/var/lib/swarmd/local-transport/api.sock";
+/** The daemon's default loopback API address. */
+export declare const SWARM_DEFAULT_API_URL = "http://127.0.0.1:7781";
+export interface SwarmConnectionInput {
+    baseUrl?: string;
+    socketPath?: string;
+}
+export interface SwarmConnectionOptions {
+    /** Environment to read; defaults to `process.env` in Node, `{}` elsewhere. */
+    env?: Record<string, string | undefined>;
+    /** Owner socket to probe; defaults to {@link SWARM_OWNER_SOCKET_PATH}. */
+    ownerSocketPath?: string;
+    /** Returns true when `path` is a socket this process may connect to. */
+    isUsableSocket?: (path: string) => boolean;
+}
+export interface SwarmConnection {
+    baseUrl: string;
+    socketPath?: string;
+}
+/**
+ * True when `path` exists, is a Unix socket and is readable and writable by
+ * this process. Any error (missing, no permission on a parent directory, not
+ * Node) means "not usable"; it never throws.
+ */
+export declare function isUsableSwarmSocket(path: string): boolean;
+/** Resolves where a client with the given explicit settings connects. */
+export declare function resolveSwarmConnection(input?: SwarmConnectionInput, options?: SwarmConnectionOptions): SwarmConnection;

package/dist/local-connection.js

@@ -0,0 +1,56 @@
+/**
+ * How a client with no explicit address finds this machine's Swarm.
+ *
+ * Order: an explicit `socketPath`/`baseUrl`, then `SWARM_SOCKET_PATH`, then
+ * `SWARM_API_URL`/`SWARM_DESKTOP_URL`, then (Node only) the owner socket of a
+ * system install when it exists and this process may connect to it, then the
+ * daemon's default loopback API at http://127.0.0.1:7781.
+ *
+ * Browsers never touch the filesystem: the probe uses Node's synchronous
+ * `process.getBuiltinModule`, which no bundler resolves and no browser has.
+ */
+/** Owner socket of a Linux system install (`/var/lib/swarmd` data root, main lane). */
+export const SWARM_OWNER_SOCKET_PATH = '/var/lib/swarmd/local-transport/api.sock';
+/** The daemon's default loopback API address. */
+export const SWARM_DEFAULT_API_URL = 'http://127.0.0.1:7781';
+function processEnv() {
+    return typeof process !== 'undefined' && process?.env ? process.env : {};
+}
+/**
+ * True when `path` exists, is a Unix socket and is readable and writable by
+ * this process. Any error (missing, no permission on a parent directory, not
+ * Node) means "not usable"; it never throws.
+ */
+export function isUsableSwarmSocket(path) {
+    if (typeof process === 'undefined' || typeof process?.getBuiltinModule !== 'function')
+        return false;
+    try {
+        const fs = process.getBuiltinModule('node:fs');
+        if (!fs?.statSync(path)?.isSocket())
+            return false;
+        fs.accessSync(path, fs.constants.R_OK | fs.constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolves where a client with the given explicit settings connects. */
+export function resolveSwarmConnection(input = {}, options = {}) {
+    const env = options.env ?? processEnv();
+    const explicitUrl = input.baseUrl || env.SWARM_API_URL || env.SWARM_DESKTOP_URL;
+    const baseUrl = (explicitUrl || SWARM_DEFAULT_API_URL).replace(/\/+$/, '');
+    if (input.socketPath)
+        return { baseUrl, socketPath: input.socketPath };
+    if (input.baseUrl)
+        return { baseUrl };
+    if (env.SWARM_SOCKET_PATH)
+        return { baseUrl, socketPath: env.SWARM_SOCKET_PATH };
+    if (explicitUrl)
+        return { baseUrl };
+    const ownerSocket = options.ownerSocketPath ?? SWARM_OWNER_SOCKET_PATH;
+    const usable = options.isUsableSocket ?? isUsableSwarmSocket;
+    if (usable(ownerSocket))
+        return { baseUrl, socketPath: ownerSocket };
+    return { baseUrl };
+}

package/dist/permission-ui.d.ts

@@ -27,6 +27,7 @@ export interface PermissionRequestView {
     arguments: Record<string, unknown> | null;
     rawArguments: string;
     parseError?: string;
+    /** Plain-text heading: the request's own title, else a fallback (bash command, first ask-user question, tool + action). Never HTML. */
     title?: string;
     context?: string;
     structured: boolean;

package/dist/permission-ui.js

@@ -15,6 +15,11 @@ export function isAskUserPermission(permission) {
 }
 /** Parse untrusted request arguments for text rendering. Never render these fields as HTML. */
 export function describePermission(permission) {
+    const view = describePermissionRequest(permission);
+    view.title = view.title || permissionFallbackTitle(view);
+    return view;
+}
+function describePermissionRequest(permission) {
     const id = permissionId(permission?.id);
     const sessionId = permissionId(permission?.session_id, 'sessionId');
     const raw = permission.tool_arguments ?? permission.tool_call_arguments ?? '';
@@ -165,3 +170,35 @@ export function confirmPermissionResolution(result, sessionId, id, action, optio
     }
     return result;
 }
+const TITLE_MAX = 160;
+/** One plain-text line: control characters and runs of whitespace collapse, long text is cut. */
+function titleLine(value) {
+    const line = value.replace(/[\u0000-\u001f\u007f\s]+/g, ' ').trim();
+    return line.length > TITLE_MAX ? `${line.slice(0, TITLE_MAX - 1).trimEnd()}…` : line;
+}
+function humanize(value) {
+    const words = value.trim().split('.').at(-1).replace(/[_-]+/g, ' ').replace(/([a-z])([A-Z])/g, '$1 $2').trim().toLowerCase();
+    return words ? words[0].toUpperCase() + words.slice(1) : '';
+}
+/**
+ * Plain-text fallback title when the request carries none: bash shows its command,
+ * ask-user its first question, any other tool its humanized name plus action/subject.
+ * Built only from untrusted strings; render it as text, never as HTML.
+ */
+function permissionFallbackTitle(view) {
+    const args = view.arguments ?? {};
+    const tool = text(view.toolName).toLowerCase().split('.').at(-1) ?? '';
+    if ((tool === 'bash' || tool === 'shell') && text(args.command))
+        return titleLine(text(args.command));
+    if (view.kind === 'ask-user') {
+        const first = view.questions[0]?.question
+            || (Array.isArray(args.questions) && object(args.questions[0]) ? text(args.questions[0].question) : '')
+            || text(args.question);
+        if (first)
+            return titleLine(first);
+    }
+    const name = humanize(text(view.toolName)) || 'Tool request';
+    const action = text(args.action) ? humanize(text(args.action)).toLowerCase() : '';
+    const subject = [args.title, args.name, args.path, args.file_path, args.url, args.query].map(text).find(Boolean) ?? '';
+    return titleLine(`${name}${action ? `: ${action}` : ''}${subject ? ` (${subject})` : ''}`);
+}

package/dist/permissions.d.ts

@@ -74,6 +74,10 @@ export declare class SwarmPermissionsNamespace {
      * Retrieves the current account-wide permission policy, including bash profile and persistent rules.
      */
     getPolicy(): Promise<PermissionPolicy>;
+    /**
+     * Whether permissionless mode (bypass permissions) is on.
+     */
+    bypass(): Promise<boolean>;
     /**
      * Toggles permissionless mode (bypass permissions).
      * When enabled, tool executions run autonomously without pausing for manual approvals.

package/dist/permissions.js

@@ -13,6 +13,13 @@ export class SwarmPermissionsNamespace {
         const res = await this.transport.request('/v1/permissions');
         return res.data.policy;
     }
+    /**
+     * Whether permissionless mode (bypass permissions) is on.
+     */
+    async bypass() {
+        const res = await this.transport.request('/v1/permissions');
+        return res.data.bypass_permissions === true;
+    }
     /**
      * Toggles permissionless mode (bypass permissions).
      * When enabled, tool executions run autonomously without pausing for manual approvals.

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, IntegrateProjectTaskResult, ListProjectsParams, PreviewProjectTaskParams, ProjectRecord, ProjectTaskApprovalGuards, ProjectTaskMediaRef, ProjectTaskModelPreviewResult, ProjectTaskPreviewResult, ProjectTaskRecord, RedeployProjectTaskJobResult, RefineProjectTaskParams, RefineProjectTaskResult, RejectProjectTaskResult, ReopenProjectTaskResult, RequestOptions, SessionRecord, SyncStreamParams, SyncStreamResult, SynthesizeProjectContextParams, UpdateProjectParams, UpdateProjectTaskParams } from './types.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, SynthesizeProjectContextParams, UpdateProjectParams, UpdateProjectTaskParams } from './types.js';
 export declare class SwarmProjectsNamespace {
     private readonly transport;
     constructor(transport: SwarmTransport);
@@ -38,9 +38,18 @@ export declare class SwarmProjectsNamespace {
     listConversations(projectId: string, params?: {
         limit?: number;
     }, reqOptions?: RequestOptions): Promise<SessionRecord[]>;
+    /** Rename a project conversation (a conversation ID is its session ID); see sessions.rename. */
+    renameConversation(conversationId: string, title: string, options?: {
+        clientRequestId?: string;
+    }): Promise<{
+        ok: boolean;
+        session_id: string;
+        title: string;
+    }>;
     /** Create an independent project conversation without archiving existing conversations.
      * Models/context resolve on the daemon. Project conversations never bind a workspace.
-     * Reuse clientRequestId when retrying an uncertain creation result.
+     * Reuse clientRequestId when retrying an uncertain creation result. Without a title the
+     * conversation is named from its first message; rename it with renameConversation.
      */
     createConversation(projectId: string, options?: {
         title?: string;
@@ -136,8 +145,14 @@ export declare class SwarmProjectsNamespace {
     refineTask(projectId: string, taskId: string, params: RefineProjectTaskParams, options?: RequestOptions): Promise<RefineProjectTaskResult>;
     /**
      * Integrates task commits into the parent workspace repository.
+     *
+     * The daemon only integrates an exact selection: the task's current session and its
+     * captured source/target branches. With no options the SDK fetches the task
+     * (`getTask`, which runs a fresh delivery assessment) and builds that selection from
+     * it; pass `options.selection` to override individual fields. A stale selection is
+     * refused by the daemon with a conflict error rather than integrating the wrong lane.
      */
-    integrateTask(projectId: string, taskId: string, options?: RequestOptions): Promise<IntegrateProjectTaskResult>;
+    integrateTask(projectId: string, taskId: string, options?: IntegrateProjectTaskOptions): Promise<IntegrateProjectTaskResult>;
     /**
      * Deploys a task program for staged multi-agent execution.
      */
@@ -180,3 +195,10 @@ export declare class SwarmProjectsNamespace {
         timeoutMs?: number;
     }): AsyncIterableIterator<TEvent>;
 }
+/**
+ * Builds the integrate selection the daemon checks from a fresh task record.
+ * Branch precedence: the detail GET's delivery assessment (the daemon's own view of
+ * the captured lane), then the task's recorded worktree/base branch, then the active
+ * attempt's. The daemon still verifies every field against the owned session.
+ */
+export declare function integrationSelectionFromTask(task: ProjectTaskRecord): Partial<IntegrateProjectTaskSelection>;

package/dist/projects.js

@@ -1,4 +1,5 @@
-import { SwarmApiError, SwarmTimeoutError, } from './errors.js';
+import { SwarmApiError, SwarmTimeoutError, SwarmValidationError, } from './errors.js';
+import { SwarmSessionsNamespace } from './sessions.js';
 export class SwarmProjectsNamespace {
     transport;
     constructor(transport) {
@@ -115,9 +116,14 @@ export class SwarmProjectsNamespace {
             return session;
         });
     }
+    /** Rename a project conversation (a conversation ID is its session ID); see sessions.rename. */
+    async renameConversation(conversationId, title, options = {}) {
+        return new SwarmSessionsNamespace(this.transport).rename(conversationId, title, options);
+    }
     /** Create an independent project conversation without archiving existing conversations.
      * Models/context resolve on the daemon. Project conversations never bind a workspace.
-     * Reuse clientRequestId when retrying an uncertain creation result.
+     * Reuse clientRequestId when retrying an uncertain creation result. Without a title the
+     * conversation is named from its first message; rename it with renameConversation.
      */
     async createConversation(projectId, options = {}, reqOptions) {
         const id = projectId.trim();
@@ -132,7 +138,7 @@ export class SwarmProjectsNamespace {
             body: {
                 client_request_id: options.clientRequestId ?? `proj-orch-${globalThis.crypto.randomUUID()}`,
                 agent_name: options.agentName ?? 'system-orchestrator',
-                title: options.title ?? 'Orchestrator AI',
+                title: options.title,
                 mode: options.mode ?? 'auto',
             },
             ...reqOptions,
@@ -485,11 +491,36 @@ export class SwarmProjectsNamespace {
     // ==========================================================================
     /**
      * Integrates task commits into the parent workspace repository.
-     */
-    async integrateTask(projectId, taskId, options) {
+     *
+     * The daemon only integrates an exact selection: the task's current session and its
+     * captured source/target branches. With no options the SDK fetches the task
+     * (`getTask`, which runs a fresh delivery assessment) and builds that selection from
+     * it; pass `options.selection` to override individual fields. A stale selection is
+     * refused by the daemon with a conflict error rather than integrating the wrong lane.
+     */
+    async integrateTask(projectId, taskId, options = {}) {
+        const { selection: overrides, body, ...requestOptions } = options;
         const pId = encodeURIComponent(projectId.trim());
         const tId = encodeURIComponent(taskId.trim());
-        const res = await this.transport.request(`/v3/projects/${pId}/tasks/${tId}/integrate`, { method: 'POST', ...options });
+        // A caller-supplied raw body is treated as overrides too (older workaround shape).
+        const given = {
+            ...(body && typeof body === 'object' ? body : {}),
+            ...(overrides ?? {}),
+        };
+        let selection = given;
+        if (!given.session_id || !given.source_branch || !given.target_branch) {
+            const { task } = await this.getTask(projectId, taskId, {
+                signal: requestOptions.signal,
+                timeoutMs: requestOptions.timeoutMs,
+                headers: requestOptions.headers,
+            });
+            selection = { ...integrationSelectionFromTask(task), ...stripUndefined(given) };
+        }
+        const missing = ['session_id', 'source_branch', 'target_branch'].filter((key) => typeof selection[key] !== 'string' || !selection[key].trim());
+        if (missing.length > 0) {
+            throw new SwarmValidationError(`Task ${taskId} cannot be integrated: no ${missing.join(', ')} on the task record (it has no captured worktree lane yet). Pass options.selection to supply them.`, { missing, selection });
+        }
+        const res = await this.transport.request(`/v3/projects/${pId}/tasks/${tId}/integrate`, { ...requestOptions, method: 'POST', body: stripUndefined(selection) });
         return res.data;
     }
     /**
@@ -606,3 +637,31 @@ export class SwarmProjectsNamespace {
         }
     }
 }
+function nonEmpty(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+}
+/**
+ * Builds the integrate selection the daemon checks from a fresh task record.
+ * Branch precedence: the detail GET's delivery assessment (the daemon's own view of
+ * the captured lane), then the task's recorded worktree/base branch, then the active
+ * attempt's. The daemon still verifies every field against the owned session.
+ */
+export function integrationSelectionFromTask(task) {
+    const assessment = task.delivery_assessment;
+    const attempts = Array.isArray(task.attempts) ? task.attempts : [];
+    const activeAttempt = attempts.find((a) => a && a.id && a.id === task.active_attempt_id) ??
+        attempts.find((a) => a && nonEmpty(a.session_id) && a.session_id === task.session_id);
+    const observed = assessment?.freshness === 'observed';
+    return stripUndefined({
+        session_id: nonEmpty(task.session_id) ?? nonEmpty(assessment?.session_id),
+        source_branch: nonEmpty(assessment?.source_branch) ?? nonEmpty(task.worktree_branch) ?? nonEmpty(activeAttempt?.worktree_branch),
+        target_branch: nonEmpty(assessment?.target_branch) ?? nonEmpty(task.base_branch) ?? nonEmpty(activeAttempt?.base_branch),
+        revision: typeof task.revision === 'number' ? task.revision : undefined,
+        attempt_id: nonEmpty(task.active_attempt_id) ?? nonEmpty(assessment?.attempt_id),
+        source_head: observed ? nonEmpty(assessment?.source_oid) : undefined,
+        target_head: observed ? nonEmpty(assessment?.target_oid) : undefined,
+    });
+}

package/dist/provider-auth.d.ts

@@ -185,9 +185,11 @@ export declare class SwarmOnboardingNamespace {
     get(): Promise<OnboardingStatus>;
     update(body: OnboardingUpdate): Promise<OnboardingStatus>;
     /**
-     * Ensures the headless daemon identity is bootstrapped.
-     * If the daemon requires onboarding, it automatically sets default identity parameters
-     * so provider authentication and sessions can immediately proceed without manual wizard steps.
+     * Ensures the daemon identity (owner name and Swarm name) is bootstrapped, so
+     * provider authentication and sessions can proceed. The owner name is kept as typed.
+     * This only creates identity: it does not mark onboarding finished, so
+     * `config.desktop_onboarding_complete` stays false until your app (or the desktop)
+     * finishes its own setup and calls `update({ desktop_onboarding_complete: true })`.
      */
     ensureBootstrapped(options?: {
         username?: string;

package/dist/provider-auth.js

@@ -116,22 +116,20 @@ export class SwarmOnboardingNamespace {
         return (await this.transport.request('/v1/onboarding', { method: 'POST', body })).data;
     }
     /**
-     * Ensures the headless daemon identity is bootstrapped.
-     * If the daemon requires onboarding, it automatically sets default identity parameters
-     * so provider authentication and sessions can immediately proceed without manual wizard steps.
+     * Ensures the daemon identity (owner name and Swarm name) is bootstrapped, so
+     * provider authentication and sessions can proceed. The owner name is kept as typed.
+     * This only creates identity: it does not mark onboarding finished, so
+     * `config.desktop_onboarding_complete` stays false until your app (or the desktop)
+     * finishes its own setup and calls `update({ desktop_onboarding_complete: true })`.
      */
     async ensureBootstrapped(options = {}) {
         const status = await this.get();
-        if (!status.needs_onboarding && status.identity?.bootstrapped) {
-            return status;
-        }
         if (status.identity?.bootstrapped) {
-            return this.update({ desktop_onboarding_complete: true });
+            return status;
         }
         return this.update({
             username: options.username ?? 'owner',
             swarm_name: options.swarm_name ?? 'Headless Swarm',
-            desktop_onboarding_complete: true,
         });
     }
     /** First credential only. Use auth.credentials.save for subsequent credentials. */