@swarm-agent/sdk 0.1.47 → 0.1.48

package/dist/permissions.d.ts

@@ -0,0 +1,126 @@
+import type { SwarmTransport } from './transport.js';
+import type { PermissionAction, ResolvePermissionOptions } from './permission-ui.js';
+export * from './permission-ui.js';
+export interface PermissionPolicy {
+    version: number;
+    bash_profile: string;
+    rules?: PermissionRule[];
+    updated_at?: number;
+}
+export interface PermissionRule {
+    id: string;
+    kind: string;
+    decision: string;
+    tool?: string;
+    pattern?: string;
+    created_at?: number;
+    updated_at?: number;
+}
+export interface PermissionRuleInput {
+    kind: string;
+    decision: 'allow' | 'deny';
+    tool?: string;
+    pattern?: string;
+}
+export interface PendingPermissionRecord {
+    id: string;
+    session_id: string;
+    run_id: string;
+    step?: number;
+    call_id?: string;
+    tool_name: string;
+    tool_arguments?: string;
+    tool_call_arguments?: string;
+    approved_arguments?: string;
+    requirement: string;
+    mode: string;
+    status: 'pending' | 'approved' | 'denied' | string;
+    decision?: string;
+    reason?: string;
+    execution_status?: string;
+    permission_requested_at?: number;
+    resolved_at?: number;
+    created_at: number;
+    updated_at: number;
+}
+export interface ResolvePermissionResult {
+    ok: boolean;
+    session_id: string;
+    permission: PendingPermissionRecord;
+    saved_rule?: PermissionRule | null;
+}
+export interface ResolveAllPermissionsResult {
+    ok: boolean;
+    session_id: string;
+    count: number;
+    resolved: PendingPermissionRecord[];
+}
+export interface PermissionExplainResult {
+    decision: string;
+    source: string;
+    reason: string;
+    tool_name?: string;
+    command?: string;
+    rule_preview?: string;
+    bash_profile?: string;
+    profile_decision?: string;
+    profile_reason?: string;
+}
+export declare class SwarmPermissionsNamespace {
+    private readonly transport;
+    constructor(transport: SwarmTransport);
+    private readonly resolving;
+    /**
+     * Retrieves the current account-wide permission policy, including bash profile and persistent rules.
+     */
+    getPolicy(): Promise<PermissionPolicy>;
+    /**
+     * Toggles permissionless mode (bypass permissions).
+     * When enabled, tool executions run autonomously without pausing for manual approvals.
+     */
+    setBypass(enabled: boolean): Promise<boolean>;
+    /**
+     * Updates the bash approval profile ('strict' | 'onboarding' | 'permissive').
+     */
+    setBashProfile(profile: 'strict' | 'onboarding' | 'permissive'): Promise<string>;
+    /**
+     * Adds a persistent permission rule (e.g. allow tool 'search' or allow specific command patterns).
+     */
+    addRule(rule: PermissionRuleInput): Promise<PermissionRule>;
+    /**
+     * Removes a persistent permission rule by ID.
+     */
+    removeRule(ruleId: string): Promise<boolean>;
+    /**
+     * Resets the permission policy to default system state.
+     */
+    resetPolicy(): Promise<PermissionPolicy>;
+    /**
+     * Explains how the permission policy evaluates a given mode, tool, and arguments.
+     */
+    explain(mode: string, tool: string, args?: string): Promise<PermissionExplainResult>;
+    /**
+     * Lists pending permissions for a specific session that are blocking tool execution.
+     */
+    listSessionPending(sessionId: string, limit?: number): Promise<PendingPermissionRecord[]>;
+    /**
+     * Lists all permissions (pending and resolved) for a session.
+     */
+    listSessionAll(sessionId: string, limit?: number): Promise<PendingPermissionRecord[]>;
+    /**
+     * Resolves a single pending permission on a session.
+     * Actions:
+     * - 'allow_once': Approve this exact tool invocation once.
+     * - 'deny' / 'deny_once': Deny this exact tool invocation once.
+     * - 'allow_always': Approve this tool call and create a persistent allow rule.
+     * - 'deny_always': Deny this tool call and create a persistent deny rule.
+     */
+    resolve(sessionId: string, permissionId: string, action: PermissionAction, options?: ResolvePermissionOptions): Promise<ResolvePermissionResult>;
+    /**
+     * Resolves all pending permissions on a session in a single call.
+     */
+    resolveAll(sessionId: string, action: 'allow_once' | 'deny', options?: {
+        reason?: string;
+        limit?: number;
+    }): Promise<ResolveAllPermissionsResult>;
+}

package/dist/permissions.js

@@ -0,0 +1,131 @@
+import { confirmPermissionResolution, permissionId as validatePermissionId, permissionResolutionBody } from './permission-ui.js';
+export * from './permission-ui.js';
+export class SwarmPermissionsNamespace {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    resolving = new Set();
+    /**
+     * Retrieves the current account-wide permission policy, including bash profile and persistent rules.
+     */
+    async getPolicy() {
+        const res = await this.transport.request('/v1/permissions');
+        return res.data.policy;
+    }
+    /**
+     * Toggles permissionless mode (bypass permissions).
+     * When enabled, tool executions run autonomously without pausing for manual approvals.
+     */
+    async setBypass(enabled) {
+        const res = await this.transport.request('/v1/permissions/bypass', { method: 'POST', body: { enabled } });
+        return res.data.bypass_permissions === true;
+    }
+    /**
+     * Updates the bash approval profile ('strict' | 'onboarding' | 'permissive').
+     */
+    async setBashProfile(profile) {
+        const res = await this.transport.request('/v1/permissions/bash-profile', { method: 'POST', body: { bash_profile: profile.trim() } });
+        return res.data.bash_profile;
+    }
+    /**
+     * Adds a persistent permission rule (e.g. allow tool 'search' or allow specific command patterns).
+     */
+    async addRule(rule) {
+        const res = await this.transport.request('/v1/permissions', { method: 'POST', body: rule });
+        return res.data.rule;
+    }
+    /**
+     * Removes a persistent permission rule by ID.
+     */
+    async removeRule(ruleId) {
+        const res = await this.transport.request(`/v1/permissions/${encodeURIComponent(ruleId.trim())}`, { method: 'DELETE' });
+        return res.data.removed === true;
+    }
+    /**
+     * Resets the permission policy to default system state.
+     */
+    async resetPolicy() {
+        const res = await this.transport.request('/v1/permissions/reset', { method: 'POST', body: {} });
+        return res.data.policy;
+    }
+    /**
+     * Explains how the permission policy evaluates a given mode, tool, and arguments.
+     */
+    async explain(mode, tool, args = '') {
+        const query = new URLSearchParams({ mode, tool, arguments: args });
+        const res = await this.transport.request(`/v1/permissions/explain?${query}`);
+        return res.data.explain;
+    }
+    /**
+     * Lists pending permissions for a specific session that are blocking tool execution.
+     */
+    async listSessionPending(sessionId, limit = 50) {
+        sessionId = validatePermissionId(sessionId, 'sessionId');
+        if (!Number.isInteger(limit) || limit < 1 || limit > 1000)
+            throw new Error('limit must be an integer from 1 to 1000');
+        const encId = encodeURIComponent(sessionId);
+        const res = await this.transport.request(`/v3/sessions/${encId}/permissions?status=pending&limit=${limit}`);
+        if (res.data?.ok === true && res.data.count === 0 && res.data.permissions === null)
+            return [];
+        if (res.data?.ok !== true || !Array.isArray(res.data.permissions) || res.data.permissions.some(p => !p || p.session_id !== sessionId || typeof p.id !== 'string' || !p.id)) {
+            throw new Error('Invalid permission list response; refresh the conversation');
+        }
+        return res.data.permissions;
+    }
+    /**
+     * Lists all permissions (pending and resolved) for a session.
+     */
+    async listSessionAll(sessionId, limit = 100) {
+        sessionId = validatePermissionId(sessionId, 'sessionId');
+        if (!Number.isInteger(limit) || limit < 1 || limit > 1000)
+            throw new Error('limit must be an integer from 1 to 1000');
+        const encId = encodeURIComponent(sessionId);
+        const res = await this.transport.request(`/v3/sessions/${encId}/permissions?status=all&limit=${limit}`);
+        if (res.data?.ok === true && res.data.count === 0 && res.data.permissions === null)
+            return [];
+        if (res.data?.ok !== true || !Array.isArray(res.data.permissions) || res.data.permissions.some(p => !p || p.session_id !== sessionId || typeof p.id !== 'string' || !p.id)) {
+            throw new Error('Invalid permission list response; refresh the conversation');
+        }
+        return res.data.permissions;
+    }
+    /**
+     * Resolves a single pending permission on a session.
+     * Actions:
+     * - 'allow_once': Approve this exact tool invocation once.
+     * - 'deny' / 'deny_once': Deny this exact tool invocation once.
+     * - 'allow_always': Approve this tool call and create a persistent allow rule.
+     * - 'deny_always': Deny this tool call and create a persistent deny rule.
+     */
+    async resolve(sessionId, permissionId, action, options = {}) {
+        const session = validatePermissionId(sessionId, 'sessionId');
+        const id = validatePermissionId(permissionId);
+        const body = permissionResolutionBody(action, options);
+        const key = JSON.stringify([session, id]);
+        if (this.resolving.has(key))
+            throw new Error('Permission resolution already in flight');
+        this.resolving.add(key);
+        try {
+            const res = await this.transport.request(`/v3/sessions/${encodeURIComponent(session)}/permissions/${encodeURIComponent(id)}/resolve`, { method: 'POST', body });
+            return confirmPermissionResolution(res.data, session, id, action, options);
+        }
+        finally {
+            this.resolving.delete(key);
+        }
+    }
+    /**
+     * Resolves all pending permissions on a session in a single call.
+     */
+    async resolveAll(sessionId, action, options = {}) {
+        const encSession = encodeURIComponent(sessionId.trim());
+        const res = await this.transport.request(`/v3/sessions/${encSession}/permissions/resolve_all`, {
+            method: 'POST',
+            body: {
+                action,
+                reason: options.reason ?? '',
+                limit: options.limit ?? 50,
+            },
+        });
+        return res.data;
+    }
+}

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, SyncStreamParams, SyncStreamResult, SynthesizeProjectContextParams, UpdateProjectParams, UpdateProjectTaskParams } from './types.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';
 export declare class SwarmProjectsNamespace {
     private readonly transport;
     constructor(transport: SwarmTransport);
@@ -11,10 +11,43 @@ export declare class SwarmProjectsNamespace {
      * Creates a new project in the active account.
      */
     create(params: CreateProjectParams, options?: RequestOptions): Promise<ProjectRecord>;
+    /** Retry the same project's context generation using its latest attempt receipt. */
+    retryContext(projectId: string, expectedAttempt: number, options?: RequestOptions): Promise<ProjectRecord>;
     /**
      * Retrieves a single project by ID.
      */
     get(projectId: string, options?: RequestOptions): Promise<ProjectRecord>;
+    /**
+     * Ensures a project exists by name. If found, returns the existing record;
+     * otherwise creates a new project with the specified name and optional workspace binding.
+     */
+    ensureProject(name: string, options?: {
+        description?: string;
+        workspacePath?: string;
+        workspaceId?: string;
+    }, reqOptions?: RequestOptions): Promise<ProjectRecord>;
+    /**
+     * Retrieves an active orchestrator session for this project, or creates one if none exists.
+     */
+    getOrchestratorSession(projectId: string, options?: {
+        title?: string;
+        mode?: 'auto' | 'plan';
+        agentName?: string;
+    }, reqOptions?: RequestOptions): Promise<SessionRecord>;
+    /** Project orchestrator conversations, not delegated task sessions or workspace chats. */
+    listConversations(projectId: string, params?: {
+        limit?: number;
+    }, reqOptions?: RequestOptions): Promise<SessionRecord[]>;
+    /** 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.
+     */
+    createConversation(projectId: string, options?: {
+        title?: string;
+        mode?: 'auto' | 'plan';
+        agentName?: string;
+        clientRequestId?: string;
+    }, reqOptions?: RequestOptions): Promise<SessionRecord>;
     /**
      * Updates an existing project's metadata, context, or bound workspaces.
      */
@@ -61,6 +94,8 @@ export declare class SwarmProjectsNamespace {
     updateTask(projectId: string, taskId: string, params: UpdateProjectTaskParams, options?: RequestOptions): Promise<ProjectTaskRecord>;
     /** Archives a task only at the supplied revision. */
     archiveTask(projectId: string, taskId: string, revision: number, options?: RequestOptions): Promise<ProjectTaskRecord>;
+    /** Restores task visibility without changing execution or linked sessions. */
+    unarchiveTask(projectId: string, taskId: string, revision: number, options?: RequestOptions): Promise<ProjectTaskRecord>;
     /** Deletes only an archived, unlaunched task at the supplied revision. */
     deleteTask(projectId: string, taskId: string, revision: number, options?: RequestOptions): Promise<DeleteProjectTaskResult>;
     /**

package/dist/projects.js

@@ -29,9 +29,10 @@ export class SwarmProjectsNamespace {
      * Creates a new project in the active account.
      */
     async create(params, options) {
+        const clientRequestId = params.client_request_id ?? `sdk-project-${crypto.randomUUID()}`;
         const res = await this.transport.request('/v3/projects', {
             method: 'POST',
-            body: params,
+            body: { ...params, client_request_id: clientRequestId },
             ...options,
         });
         const data = res.data;
@@ -43,6 +44,14 @@ export class SwarmProjectsNamespace {
         }
         throw new SwarmApiError('Malformed response: missing project record', { status: res.status, details: data });
     }
+    /** Retry the same project's context generation using its latest attempt receipt. */
+    async retryContext(projectId, expectedAttempt, options) {
+        const res = await this.transport.request(`/v3/projects/${encodeURIComponent(projectId.trim())}/context:retry`, { ...options, method: 'POST', body: { expected_attempt: expectedAttempt } });
+        if (!res.data?.project || res.data.project.id !== projectId.trim()) {
+            throw new SwarmApiError('Malformed response: project retry identity mismatch', { status: res.status, details: res.data });
+        }
+        return res.data.project;
+    }
     /**
      * Retrieves a single project by ID.
      */
@@ -58,6 +67,84 @@ export class SwarmProjectsNamespace {
         }
         throw new SwarmApiError('Malformed response: missing project record', { status: res.status, details: data });
     }
+    /**
+     * Ensures a project exists by name. If found, returns the existing record;
+     * otherwise creates a new project with the specified name and optional workspace binding.
+     */
+    async ensureProject(name, options = {}, reqOptions) {
+        const trimmed = name.trim();
+        const existingList = await this.list({ limit: 50 }, reqOptions);
+        const existing = existingList.find((p) => p.name === trimmed);
+        if (existing)
+            return existing;
+        const workspaces = options.workspacePath
+            ? [{ path: options.workspacePath, workspace_id: options.workspaceId }]
+            : undefined;
+        return this.create({
+            name: trimmed,
+            description: options.description ?? `Project ${trimmed}`,
+            workspaces,
+        }, reqOptions);
+    }
+    /**
+     * Retrieves an active orchestrator session for this project, or creates one if none exists.
+     */
+    async getOrchestratorSession(projectId, options = {}, reqOptions) {
+        const sessions = await this.listConversations(projectId, {}, reqOptions);
+        const active = sessions.find((s) => !s.archived_at && !s.archived);
+        if (active)
+            return active;
+        return this.createConversation(projectId, options, reqOptions);
+    }
+    /** Project orchestrator conversations, not delegated task sessions or workspace chats. */
+    async listConversations(projectId, params = {}, reqOptions) {
+        if (!projectId.trim())
+            throw new Error('projectId is required');
+        const q = new URLSearchParams();
+        if (params.limit)
+            q.set('limit', String(params.limit));
+        const suffix = q.size ? `?${q}` : '';
+        const res = await this.transport.request(`/v3/projects/${encodeURIComponent(projectId.trim())}/sessions${suffix}`, { method: 'GET', ...reqOptions });
+        const items = Array.isArray(res.data) ? res.data : res.data?.sessions;
+        if (!Array.isArray(items))
+            throw new SwarmApiError('Malformed conversation list', { status: res.status });
+        return items.map((item) => {
+            const session = item.session ? { ...item.session, projection: item.projection } : item;
+            if (!session?.id)
+                throw new SwarmApiError('Conversation is missing session identity', { status: res.status });
+            return session;
+        });
+    }
+    /** 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.
+     */
+    async createConversation(projectId, options = {}, reqOptions) {
+        const id = projectId.trim();
+        if (!id)
+            throw new Error('projectId is required');
+        if (options.agentName && options.agentName !== 'system-orchestrator') {
+            throw new Error('Project conversations require system-orchestrator; use chat.createSession for standalone chat');
+        }
+        const encId = encodeURIComponent(id);
+        const createRes = await this.transport.request(`/v3/projects/${encId}/sessions`, {
+            method: 'POST',
+            body: {
+                client_request_id: options.clientRequestId ?? `proj-orch-${globalThis.crypto.randomUUID()}`,
+                agent_name: options.agentName ?? 'system-orchestrator',
+                title: options.title ?? 'Orchestrator AI',
+                mode: options.mode ?? 'auto',
+            },
+            ...reqOptions,
+        });
+        const data = createRes.data;
+        if (data && typeof data === 'object' && 'session' in data && data.session) {
+            return data.session;
+        }
+        if (data && 'id' in data && data.id)
+            return data;
+        throw new SwarmApiError('Malformed conversation creation response', { status: createRes.status });
+    }
     /**
      * Updates an existing project's metadata, context, or bound workspaces.
      */
@@ -239,6 +326,14 @@ export class SwarmProjectsNamespace {
             throw new SwarmApiError('Malformed response: missing archived task', { status: res.status, details: res.data });
         return res.data.task;
     }
+    /** Restores task visibility without changing execution or linked sessions. */
+    async unarchiveTask(projectId, taskId, revision, options) {
+        const path = `/v3/projects/${encodeURIComponent(projectId.trim())}/tasks/${encodeURIComponent(taskId.trim())}/unarchive`;
+        const res = await this.transport.request(path, { method: 'POST', body: { revision }, ...options });
+        if (!res.data?.task)
+            throw new SwarmApiError('Malformed response: missing unarchived task', { status: res.status, details: res.data });
+        return res.data.task;
+    }
     /** Deletes only an archived, unlaunched task at the supplied revision. */
     async deleteTask(projectId, taskId, revision, options) {
         const pId = encodeURIComponent(projectId.trim());

package/dist/provider-auth.d.ts

@@ -92,6 +92,21 @@ export declare class SwarmCredentialsNamespace {
         cleanup: Record<string, unknown>;
     }>;
 }
+export interface CodexDeviceCode {
+    verification_url: string;
+    user_code: string;
+    session_id: string;
+    expires_at?: number;
+}
+export interface CodexDeviceLoginOptions {
+    label?: string;
+    active?: boolean;
+    intervalMs?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    onCode?: (code: CodexDeviceCode) => void;
+    onStatus?: (status: CodexLogin) => void;
+}
 export declare class SwarmCodexAuthNamespace {
     private readonly transport;
     constructor(transport: SwarmTransport);
@@ -102,6 +117,20 @@ export declare class SwarmCodexAuthNamespace {
     }): Promise<CodexLogin>;
     status(session_id: string): Promise<CodexLogin>;
     complete(session_id: string, callback_input: string): Promise<CodexLogin>;
+    /**
+     * High-level Codex device login flow.
+     * Starts the OAuth device authorization session, invokes onCode with verification URL
+     * and user code, and polls status until completion, timeout, or abort.
+     */
+    loginDevice(options?: CodexDeviceLoginOptions): Promise<CodexLogin>;
+    /**
+     * Checks whether Codex is already connected and active.
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Retrieves the active Codex credential status if one exists.
+     */
+    getCredential(): Promise<CredentialStatus | null>;
 }
 export interface OnboardingStatus {
     ok: boolean;
@@ -155,6 +184,15 @@ export declare class SwarmOnboardingNamespace {
     constructor(transport: SwarmTransport);
     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.
+     */
+    ensureBootstrapped(options?: {
+        username?: string;
+        swarm_name?: string;
+    }): Promise<OnboardingStatus>;
     /** First credential only. Use auth.credentials.save for subsequent credentials. */
     credential(body: Omit<CredentialInput, 'id'>): Promise<CredentialStatus>;
 }

package/dist/provider-auth.js

@@ -37,6 +37,74 @@ export class SwarmCodexAuthNamespace {
     async complete(session_id, callback_input) {
         return (await this.transport.request('/v1/auth/codex/oauth/complete', { method: 'POST', body: { session_id, callback_input } })).data;
     }
+    /**
+     * High-level Codex device login flow.
+     * Starts the OAuth device authorization session, invokes onCode with verification URL
+     * and user code, and polls status until completion, timeout, or abort.
+     */
+    async loginDevice(options = {}) {
+        const startRes = await this.start({
+            method: 'device',
+            label: options.label ?? 'Codex Device Login',
+            active: options.active ?? true,
+        });
+        if (options.onCode && startRes.verification_url && startRes.user_code) {
+            options.onCode({
+                verification_url: startRes.verification_url,
+                user_code: startRes.user_code,
+                session_id: startRes.session_id,
+                expires_at: startRes.expires_at,
+            });
+        }
+        const intervalMs = Math.max(500, options.intervalMs ?? 2000);
+        const timeoutMs = options.timeoutMs ?? 15 * 60 * 1000;
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (options.signal?.aborted) {
+                throw new Error('Codex device login aborted by caller');
+            }
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+            if (options.signal?.aborted) {
+                throw new Error('Codex device login aborted by caller');
+            }
+            const current = await this.status(startRes.session_id);
+            options.onStatus?.(current);
+            if (current.status === 'success') {
+                return current;
+            }
+            if (current.status === 'error' || current.status === 'failed' || current.status === 'expired') {
+                throw new Error(current.error || `Codex login failed with status: ${current.status}`);
+            }
+        }
+        throw new Error(`Codex device login timed out after ${timeoutMs}ms`);
+    }
+    /**
+     * Checks whether Codex is already connected and active.
+     */
+    async isAuthenticated() {
+        try {
+            const res = await (await this.transport.request('/v1/auth/credentials?provider=codex')).data;
+            if (!res?.records?.length)
+                return false;
+            return res.records.some((r) => r.provider === 'codex' && r.active && r.connection?.connected !== false);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Retrieves the active Codex credential status if one exists.
+     */
+    async getCredential() {
+        try {
+            const res = await (await this.transport.request('/v1/auth/credentials?provider=codex')).data;
+            const match = res?.records?.find((r) => r.provider === 'codex' && r.active);
+            return match ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
 }
 export class SwarmOnboardingNamespace {
     transport;
@@ -47,6 +115,25 @@ export class SwarmOnboardingNamespace {
     async update(body) {
         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.
+     */
+    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 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. */
     async credential(body) {
         return (await this.transport.request('/v1/onboarding/provider/credential', { method: 'POST', body })).data;

package/dist/sessions.d.ts

@@ -52,9 +52,11 @@ export declare class SwarmSessionsNamespace {
     }): Promise<boolean>;
     /**
      * Helper that polls a session until its active run completes, or times out.
+     * Explicit autoApprovePermissions applies only to ordinary tools; questions still require user input.
      */
     waitForRun(sessionId: string, options?: {
         timeoutMs?: number;
         pollIntervalMs?: number;
+        autoApprovePermissions?: boolean;
     }): Promise<SessionDetail>;
 }