@swarm-agent/sdk 0.1.47 → 0.1.49

package/dist/chat.js

@@ -0,0 +1,307 @@
+import { SwarmPermissionsNamespace, isAskUserPermission, permissionId } from './permissions.js';
+import { SwarmRealtimeNamespace } from './realtime.js';
+import { SwarmSessionsNamespace } from './sessions.js';
+import { SwarmTimeoutError } from './errors.js';
+import { SwarmWebSocketBridge } from './websocket.js';
+/**
+ * Dedicated high-level Chat namespace.
+ * Provides streamlined building blocks for interactive AI chat, streaming responses,
+ * live tool call monitoring, and automatic or custom permission handling.
+ */
+export class SwarmChatNamespace {
+    transport;
+    sessions;
+    permissions;
+    realtime;
+    constructor(transport) {
+        this.transport = transport;
+        this.sessions = new SwarmSessionsNamespace(transport);
+        this.permissions = new SwarmPermissionsNamespace(transport);
+        this.realtime = new SwarmRealtimeNamespace(transport);
+    }
+    /**
+     * Attaches a native bidirectional WebSocket bridge to an HTTP or HTTPS server.
+     * Enables browsers to stream tokens, live tool events, and send messages directly over WebSockets.
+     */
+    attachWebSocket(server, options) {
+        return new SwarmWebSocketBridge(server, this, this.permissions, options);
+    }
+    /**
+     * Creates an interactive chat session.
+     * Standalone workspace chat uses Swarm. For project orchestration use
+     * projects.createConversation(projectId); project membership is not workspace authority.
+     */
+    async createSession(options = {}) {
+        if (options.project_id)
+            throw new Error('Use projects.createConversation(projectId) for project orchestrator conversations');
+        return this.sessions.create({
+            title: options.title ?? 'Chat Session',
+            agent_name: options.agent_name ?? 'swarm',
+            workspace_path: options.workspace_path,
+            workspace_id: options.workspace_id,
+            project_id: options.project_id,
+            mode: options.mode ?? 'auto',
+        });
+    }
+    /**
+     * Appends a message to a chat conversation.
+     */
+    async sendMessage(sessionId, content, role = 'user', clientRequestId) {
+        return this.sessions.sendMessage(sessionId, { content, role, client_request_id: clientRequestId });
+    }
+    /**
+     * Lists messages from a session conversation.
+     */
+    async listMessages(sessionId) {
+        const detail = await this.sessions.get(sessionId);
+        return detail.messages || [];
+    }
+    /**
+     * High-level chat execution: sends a message, monitors execution, handles or surfaces
+     * pending permissions, and returns the final assistant reply.
+     */
+    async run(sessionId, options) {
+        const id = permissionId(sessionId, 'sessionId');
+        await this.sessions.sendMessage(id, { content: options.message, role: 'user' });
+        const timeoutMs = options.timeoutMs ?? 180_000;
+        const pollIntervalMs = options.pollIntervalMs ?? 1_000;
+        const deadline = Date.now() + timeoutMs;
+        let lastPendingCount = 0;
+        while (Date.now() < deadline) {
+            if (options.signal?.aborted) {
+                throw new Error('Chat run aborted by caller');
+            }
+            // Check for pending permissions
+            const pending = await this.permissions.listSessionPending(id);
+            if (pending.length > 0) {
+                lastPendingCount = pending.length;
+                if (options.autoApprovePermissions) {
+                    for (const perm of pending) {
+                        if (isAskUserPermission(perm))
+                            continue;
+                        await this.permissions.resolve(id, perm.id, 'allow_once', { reason: 'Approved by explicit application policy' });
+                    }
+                }
+            }
+            const detail = await this.sessions.get(id);
+            const raw = (detail.raw || {});
+            const activeRun = raw.active_run_intent;
+            const state = (detail.state || '').toLowerCase();
+            const isRunning = state.includes('running') || state.includes('in_progress') || !!activeRun;
+            if (!isRunning && pending.length === 0) {
+                const msgs = detail.messages || [];
+                const assistantMsgs = msgs.filter((m) => m.role === 'assistant');
+                const finalMsg = assistantMsgs[assistantMsgs.length - 1];
+                let reply = finalMsg?.content;
+                if (!reply) {
+                    const sysMsg = msgs.find((m) => m.role === 'system' &&
+                        (m.metadata?.message_kind === 'run_failure' || m.content?.includes('[run-failed]')));
+                    reply = sysMsg ? sysMsg.content : 'No response generated from model.';
+                }
+                return {
+                    reply,
+                    sessionId: id,
+                    runId: activeRun?.run_id || detail.last_run_id,
+                    messages: msgs,
+                    pendingPermissions: pending,
+                    session: detail,
+                };
+            }
+            await new Promise((r) => setTimeout(r, pollIntervalMs));
+        }
+        let errorMsg = `Session run did not complete within ${timeoutMs}ms.`;
+        if (lastPendingCount > 0) {
+            errorMsg += ` Execution is paused waiting for ${lastPendingCount} pending tool permission(s). Render the pending requests and explicitly answer or deny via client.permissions.resolve().`;
+        }
+        throw new SwarmTimeoutError(errorMsg, timeoutMs);
+    }
+    /**
+     * Establishes a real-time event stream for a chat session.
+     * Streams text deltas, reasoning deltas, and live tool start/output/completion events like on Swarm.
+     */
+    async stream(sessionId, options = {}) {
+        const id = permissionId(sessionId, 'sessionId');
+        const activeTools = new Map();
+        const seenEventIds = new Set();
+        const previousStreams = new Map();
+        const completedRuns = new Set();
+        const pendingSeen = new Map();
+        const resolving = new Set();
+        const resolved = new Set();
+        let permissionsLive = false;
+        let initialized = false;
+        let observedRun;
+        return this.realtime.watchSession(id, {
+            signal: options.signal,
+            surface: options.surface ?? 'chat',
+            socketFactory: options.socketFactory,
+            onChange: (state) => {
+                permissionsLive = state.status === 'live';
+                options.onState?.(state);
+                const run = state.snapshot.current_run_state_by_session?.[id]
+                    ?? state.snapshot.session_views_by_id?.[id]?.current_run_state;
+                const sessionEvents = state.snapshot.events_by_session?.[id] || [];
+                if (!initialized) {
+                    initialized = true;
+                    // Hydrated history is not a new turn or a new permission request.
+                    for (const evt of sessionEvents)
+                        seenEventIds.add(evt.id);
+                    if (run?.run_id && !run.active)
+                        completedRuns.add(run.run_id);
+                }
+                if (run?.active)
+                    observedRun = run.run_id;
+                for (const item of state.live || []) {
+                    const key = JSON.stringify([item.runId, item.streamId]);
+                    const previous = previousStreams.get(key) ?? '';
+                    if (item.text === previous)
+                        continue;
+                    previousStreams.set(key, item.text);
+                    observedRun = item.runId;
+                    const delta = item.text.startsWith(previous) ? item.text.slice(previous.length) : item.text;
+                    if (item.streamId.includes('reasoning'))
+                        options.onReasoning?.(delta, item.text);
+                    else
+                        options.onText?.(delta, item.text);
+                }
+                // Bound transient state to streams still in the current snapshot.
+                const liveKeys = new Set(state.live.map(item => JSON.stringify([item.runId, item.streamId])));
+                for (const key of previousStreams.keys())
+                    if (!liveKeys.has(key))
+                        previousStreams.delete(key);
+                // 2. Process Realtime Events (Tool streams & Permissions)
+                for (const evt of sessionEvents) {
+                    if (seenEventIds.has(evt.id))
+                        continue;
+                    seenEventIds.add(evt.id);
+                    const payload = evt.payload || {};
+                    const eventType = evt.event_type;
+                    if (eventType === 'session.tool.started') {
+                        const toolId = String(payload.call_id || payload.tool_instance_id || evt.id);
+                        const toolItem = {
+                            id: toolId,
+                            name: String(payload.tool_name || 'tool'),
+                            identity: payload.tool_identity ? String(payload.tool_identity) : undefined,
+                            display: payload.tool_display ? String(payload.tool_display) : undefined,
+                            arguments: payload.arguments ? String(payload.arguments) : undefined,
+                            status: 'running',
+                        };
+                        activeTools.set(toolId, toolItem);
+                        options.onToolStarted?.(toolItem);
+                    }
+                    else if (eventType === 'session.tool.delta') {
+                        const toolId = String(payload.call_id || payload.tool_instance_id || '');
+                        const toolItem = activeTools.get(toolId);
+                        const delta = String(payload.output || '');
+                        if (toolItem && delta) {
+                            toolItem.output = (toolItem.output || '') + delta;
+                            options.onToolDelta?.(toolItem, delta);
+                        }
+                    }
+                    else if (eventType === 'session.tool.completed') {
+                        const toolId = String(payload.call_id || payload.tool_instance_id || '');
+                        let toolItem = activeTools.get(toolId);
+                        if (!toolItem) {
+                            toolItem = {
+                                id: toolId,
+                                name: String(payload.tool_name || 'tool'),
+                                status: 'completed',
+                            };
+                            activeTools.set(toolId, toolItem);
+                        }
+                        toolItem.status = 'completed';
+                        if (payload.output)
+                            toolItem.output = String(payload.output);
+                        if (payload.duration_ms)
+                            toolItem.durationMs = Number(payload.duration_ms);
+                        options.onToolCompleted?.(toolItem);
+                    }
+                    else if (eventType === 'session.tool.failed') {
+                        const toolId = String(payload.call_id || payload.tool_instance_id || '');
+                        let toolItem = activeTools.get(toolId);
+                        if (!toolItem) {
+                            toolItem = {
+                                id: toolId,
+                                name: String(payload.tool_name || 'tool'),
+                                status: 'failed',
+                            };
+                            activeTools.set(toolId, toolItem);
+                        }
+                        toolItem.status = 'failed';
+                        toolItem.error = String(payload.error || 'Tool execution failed');
+                        if (payload.duration_ms)
+                            toolItem.durationMs = Number(payload.duration_ms);
+                        options.onToolCompleted?.(toolItem);
+                    }
+                    if (seenEventIds.size > 4096)
+                        seenEventIds.delete(seenEventIds.values().next().value);
+                }
+                const rawPending = state.snapshot.session_views_by_id?.[id]?.pending_permissions;
+                const pending = rawPending === null ? [] : rawPending;
+                if (permissionsLive && Array.isArray(pending)) {
+                    if (pending.some(p => !p || typeof p.id !== 'string' || !p.id || p.session_id !== id)) {
+                        options.onError?.(new Error('Invalid pending permission snapshot; refresh the conversation'));
+                        return;
+                    }
+                    const pendingIds = new Set(pending.map(p => p.id));
+                    for (const key of pendingSeen.keys())
+                        if (!pendingIds.has(key)) {
+                            pendingSeen.delete(key);
+                            resolved.delete(key);
+                            options.onPermissionRemoved?.(key);
+                        }
+                    for (const raw of pending) {
+                        const permission = raw;
+                        if (permission.session_id !== id || permission.status !== 'pending')
+                            continue;
+                        const fingerprint = JSON.stringify(permission);
+                        if (pendingSeen.get(permission.id) === fingerprint || resolved.has(permission.id))
+                            continue;
+                        pendingSeen.set(permission.id, fingerprint);
+                        const notify = (error) => {
+                            const err = error instanceof Error ? error : new Error(String(error));
+                            if (options.onPermissionError)
+                                options.onPermissionError(err, permission);
+                            else
+                                options.onError?.(err);
+                            return err;
+                        };
+                        const resolver = async (action, input = {}) => {
+                            if (!permissionsLive)
+                                throw new Error('Permission state is reconnecting; wait for fresh hydration');
+                            if (pendingSeen.get(permission.id) !== fingerprint || resolved.has(permission.id))
+                                throw new Error('Permission request is stale; refresh the conversation');
+                            if (resolving.has(permission.id))
+                                throw new Error('Permission resolution already in flight');
+                            resolving.add(permission.id);
+                            try {
+                                const result = await this.permissions.resolve(id, permission.id, action, typeof input === 'string' ? { reason: input } : input);
+                                resolved.add(permission.id);
+                                return result;
+                            }
+                            catch (error) {
+                                throw notify(error);
+                            }
+                            finally {
+                                resolving.delete(permission.id);
+                            }
+                        };
+                        // Catch both synchronous throws and async callback rejections without closing the watch.
+                        void Promise.resolve().then(() => options.onPermissionRequested?.(permission, resolver)).catch(notify);
+                    }
+                }
+                // Once per durable run, including empty/tool-only/failed turns. Never close the watch.
+                if (state.status === 'live' && run?.run_id && !run.active && !completedRuns.has(run.run_id)) {
+                    completedRuns.add(run.run_id);
+                    if (completedRuns.size > 4096)
+                        completedRuns.delete(completedRuns.values().next().value);
+                    if (observedRun === run.run_id || run.completed_at)
+                        options.onComplete?.(state.messages);
+                }
+            },
+            onError: (err) => {
+                options.onError?.(err);
+            },
+        });
+    }
+}

package/dist/client.d.ts

@@ -1,4 +1,6 @@
 import { SwarmAppsNamespace } from './apps.js';
+import { SwarmChatNamespace } from './chat.js';
+import { SwarmPermissionsNamespace } from './permissions.js';
 import { SwarmSettingsNamespace } from './settings.js';
 import { SwarmOnboardingNamespace } from './provider-auth.js';
 import { SwarmRealtimeNamespace } from './realtime.js';
@@ -40,6 +42,10 @@ export declare class SwarmClient {
     readonly workspaces: SwarmWorkspacesNamespace;
     readonly projects: SwarmProjectsNamespace;
     readonly sessions: SwarmSessionsNamespace;
+    /** High-level interactive chat, response streaming, live tool events, and permission handling */
+    readonly chat: SwarmChatNamespace;
+    /** Account and session permission policy, bypass/permissionless mode, and pending approvals */
+    readonly permissions: SwarmPermissionsNamespace;
     readonly apps: SwarmAppsNamespace;
     readonly system: SwarmSystemNamespace;
     readonly deploy: SwarmDeployNamespace;

package/dist/client.js

@@ -1,4 +1,6 @@
 import { SwarmAppsNamespace } from './apps.js';
+import { SwarmChatNamespace } from './chat.js';
+import { SwarmPermissionsNamespace } from './permissions.js';
 import { SwarmSettingsNamespace } from './settings.js';
 import { SwarmOnboardingNamespace } from './provider-auth.js';
 import { SwarmRealtimeNamespace } from './realtime.js';
@@ -39,6 +41,10 @@ export class SwarmClient {
     workspaces;
     projects;
     sessions;
+    /** High-level interactive chat, response streaming, live tool events, and permission handling */
+    chat;
+    /** Account and session permission policy, bypass/permissionless mode, and pending approvals */
+    permissions;
     apps;
     system;
     deploy;
@@ -79,6 +85,8 @@ export class SwarmClient {
         this.workspaces = new SwarmWorkspacesNamespace(this.transport);
         this.projects = new SwarmProjectsNamespace(this.transport);
         this.sessions = new SwarmSessionsNamespace(this.transport);
+        this.chat = new SwarmChatNamespace(this.transport);
+        this.permissions = new SwarmPermissionsNamespace(this.transport);
         this.apps = new SwarmAppsNamespace(this.transport);
         this.system = new SwarmSystemNamespace(this.transport);
         this.deploy = new SwarmDeployNamespace(this.transport);

package/dist/index.d.ts

@@ -2,11 +2,14 @@ export * from './client.js';
 export * from './auth.js';
 export * from './automations.js';
 export * from './workers.js';
+export * from './worker-control.js';
 export * from './deliverables.js';
 export * from './deploy/index.js';
 export * from './notifications.js';
 export * from './sessions.js';
 export * from './projects.js';
+export * from './permissions.js';
+export * from './chat.js';
 export * from './workspaces.js';
 export * from './system.js';
 export * from './transport.js';
@@ -20,4 +23,6 @@ export type { ApplicationAgent, ApplicationAgentWrite, ApplicationConversationPa
 export * from './settings.js';
 export * from './provider-auth.js';
 export * from './realtime.js';
+export * from './websocket.js';
+export * from './browser.js';
 export type { ApplicationResults, ApplicationResultsOptions } from './app-results.js';

package/dist/index.js

@@ -2,11 +2,14 @@ export * from './client.js';
 export * from './auth.js';
 export * from './automations.js';
 export * from './workers.js';
+export * from './worker-control.js';
 export * from './deliverables.js';
 export * from './deploy/index.js';
 export * from './notifications.js';
 export * from './sessions.js';
 export * from './projects.js';
+export * from './permissions.js';
+export * from './chat.js';
 export * from './workspaces.js';
 export * from './system.js';
 export * from './transport.js';
@@ -18,3 +21,5 @@ export { SwarmAppsNamespace } from './apps.js';
 export * from './settings.js';
 export * from './provider-auth.js';
 export * from './realtime.js';
+export * from './websocket.js';
+export * from './browser.js';

package/dist/permission-ui.d.ts

@@ -0,0 +1,50 @@
+import type { PendingPermissionRecord, ResolvePermissionResult } from './permissions.js';
+export type PermissionAction = 'allow_once' | 'deny' | 'deny_once' | 'allow_always' | 'deny_always';
+export interface ResolvePermissionOptions {
+    reason?: string;
+    approvedArguments?: Record<string, unknown> | string;
+}
+export type PermissionResolver = (action: PermissionAction, options?: ResolvePermissionOptions | string) => Promise<ResolvePermissionResult>;
+export interface PermissionChoice {
+    label: string;
+    value: string;
+    description?: string;
+    custom: boolean;
+}
+export interface PermissionQuestion {
+    id: string;
+    question: string;
+    header?: string;
+    required: boolean;
+    options: PermissionChoice[];
+}
+export interface PermissionRequestView {
+    id: string;
+    sessionId: string;
+    toolName: string;
+    status: string;
+    kind: 'tool' | 'ask-user';
+    arguments: Record<string, unknown> | null;
+    rawArguments: string;
+    parseError?: string;
+    title?: string;
+    context?: string;
+    structured: boolean;
+    questions: PermissionQuestion[];
+    /** Conservative per-request actions, not a grant of backend authority. */
+    actions: Array<'allow_once' | 'deny'>;
+}
+export declare function permissionId(value: unknown, label?: string): string;
+export declare function isAskUserPermission(permission: Pick<PendingPermissionRecord, 'tool_name'>): boolean;
+/** Parse untrusted request arguments for text rendering. Never render these fields as HTML. */
+export declare function describePermission(permission: PendingPermissionRecord): PermissionRequestView;
+/** Serialize actual user input using the backend's reason/answers-map contract. */
+export declare function answerPermission(permission: PendingPermissionRecord, answer: string | Record<string, string>): ResolvePermissionOptions;
+/** Validate JavaScript callers before any mutation is sent. */
+export declare function permissionResolutionBody(action: PermissionAction, options?: ResolvePermissionOptions): Record<string, unknown>;
+export declare class PermissionResolutionError extends Error {
+    readonly result?: ResolvePermissionResult | undefined;
+    constructor(message: string, result?: ResolvePermissionResult | undefined);
+}
+/** HTTP success is not proof that a stale decision won. Keep the actual record on conflicts. */
+export declare function confirmPermissionResolution(result: ResolvePermissionResult, sessionId: string, id: string, action: PermissionAction, options?: ResolvePermissionOptions): ResolvePermissionResult;

package/dist/permission-ui.js

@@ -0,0 +1,167 @@
+export function permissionId(value, label = 'permissionId') {
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(`${label} must be a non-empty string`);
+    return value.trim();
+}
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function text(value) { return typeof value === 'string' ? value.trim() : ''; }
+export function isAskUserPermission(permission) {
+    if (typeof permission?.tool_name !== 'string')
+        return false;
+    const name = permission.tool_name.trim().toLowerCase().split('.').at(-1)?.replaceAll('-', '_');
+    return name === 'ask_user' || name === 'askuser';
+}
+/** Parse untrusted request arguments for text rendering. Never render these fields as HTML. */
+export function describePermission(permission) {
+    const id = permissionId(permission?.id);
+    const sessionId = permissionId(permission?.session_id, 'sessionId');
+    const raw = permission.tool_arguments ?? permission.tool_call_arguments ?? '';
+    const view = {
+        id, sessionId, toolName: permission.tool_name, status: permission.status,
+        kind: isAskUserPermission(permission) ? 'ask-user' : 'tool', arguments: null,
+        rawArguments: typeof raw === 'string' ? raw : '', structured: false, questions: [],
+        actions: permission.status === 'pending' ? ['allow_once', 'deny'] : [],
+    };
+    try {
+        const args = raw === '' ? {} : JSON.parse(raw);
+        if (!object(args))
+            throw new Error('Permission arguments must be a JSON object');
+        view.arguments = args;
+        if (view.kind === 'tool')
+            return view;
+        view.title = text(args.title) || undefined;
+        view.context = text(args.context) || undefined;
+        view.structured = Object.hasOwn(args, 'questions');
+        const questions = view.structured ? args.questions : [args];
+        if (!Array.isArray(questions) || questions.length === 0)
+            throw new Error('Ask-user requires questions');
+        const ids = new Set();
+        view.questions = questions.map((q, index) => {
+            if (!object(q) || !text(q.question) || !Array.isArray(q.options))
+                throw new Error('Invalid ask-user question');
+            const id = text(q.id) || `q_${index + 1}`;
+            if (ids.has(id))
+                throw new Error('Duplicate ask-user question ID');
+            ids.add(id);
+            const options = q.options.map((item) => {
+                if (typeof item === 'string' && item.trim())
+                    return { label: item.trim(), value: item.trim(), custom: item === '__custom__' || item === 'Custom response' };
+                if (!object(item))
+                    throw new Error('Invalid ask-user option');
+                const value = text(item.value) || text(item.label);
+                if (!value)
+                    throw new Error('Empty ask-user option');
+                return { value, label: text(item.label) || value, description: text(item.description) || undefined,
+                    custom: item.allow_custom === true || item.allowCustom === true || value === '__custom__' || value === 'Custom response' };
+            });
+            if (options.filter(option => !option.custom).length < 2)
+                throw new Error('Ask-user requires at least two concrete options');
+            return { id, question: text(q.question), header: text(q.header) || undefined, required: q.required !== false, options };
+        });
+    }
+    catch (error) {
+        view.parseError = error instanceof Error ? error.message : String(error);
+        view.questions = [];
+        // A malformed question may be denied, but never silently approved without an answer.
+        if (view.kind === 'ask-user' && permission.status === 'pending')
+            view.actions = ['deny'];
+    }
+    return view;
+}
+/** Serialize actual user input using the backend's reason/answers-map contract. */
+export function answerPermission(permission, answer) {
+    const view = describePermission(permission);
+    if (view.status !== 'pending' || view.kind !== 'ask-user' || view.parseError)
+        throw new Error(view.parseError || 'Expected a pending ask-user request');
+    const validate = (question, value) => {
+        const result = text(value);
+        if (!result)
+            throw new Error(`Answer required for ${question.id}`);
+        if (result === '__custom__')
+            throw new Error('Enter custom response text, not the custom option marker');
+        if (!question.options.some(option => !option.custom && (option.value === result || option.label === result)) && !question.options.some(option => option.custom)) {
+            throw new Error(`Select a supported answer for ${question.id}`);
+        }
+        return result;
+    };
+    if (!view.structured) {
+        if (typeof answer !== 'string')
+            throw new Error('Single question requires a string answer');
+        return { reason: validate(view.questions[0], answer) };
+    }
+    if (!object(answer))
+        throw new Error('Structured questions require an answers map keyed by question ID');
+    const answers = Object.create(null);
+    for (const key of Object.keys(answer))
+        if (!view.questions.some(q => q.id === key))
+            throw new Error(`Unknown question ID: ${key}`);
+    for (const question of view.questions) {
+        if (!Object.hasOwn(answer, question.id) && !question.required)
+            continue;
+        answers[question.id] = validate(question, answer[question.id]);
+    }
+    if (!Object.keys(answers).length)
+        throw new Error('Provide at least one explicit answer');
+    return { reason: JSON.stringify({ answers }) };
+}
+/** Validate JavaScript callers before any mutation is sent. */
+export function permissionResolutionBody(action, options = {}) {
+    if (!['allow_once', 'deny', 'deny_once', 'allow_always', 'deny_always'].includes(action))
+        throw new Error('Unsupported permission action');
+    if (!object(options))
+        throw new Error('Permission resolution options must be an object');
+    if (options.reason !== undefined && typeof options.reason !== 'string')
+        throw new Error('Permission reason must be a string');
+    const body = { action, reason: options.reason ?? '' };
+    if (options.approvedArguments !== undefined) {
+        let args = options.approvedArguments;
+        if (typeof args === 'string') {
+            try {
+                args = JSON.parse(args);
+            }
+            catch {
+                throw new Error('approvedArguments must contain valid JSON');
+            }
+        }
+        if (!object(args))
+            throw new Error('approvedArguments must be a JSON object');
+        // Reject circular or otherwise non-JSON data before transport.
+        body.approved_arguments = JSON.parse(JSON.stringify(args));
+    }
+    return body;
+}
+export class PermissionResolutionError extends Error {
+    result;
+    constructor(message, result) {
+        super(message);
+        this.result = result;
+        this.name = 'PermissionResolutionError';
+    }
+}
+/** HTTP success is not proof that a stale decision won. Keep the actual record on conflicts. */
+export function confirmPermissionResolution(result, sessionId, id, action, options = {}) {
+    const p = result?.permission;
+    const canonical = (value) => JSON.stringify(value, (_key, item) => object(item) ? Object.fromEntries(Object.keys(item).sort().map(key => [key, item[key]])) : item);
+    let argumentsMatch = true;
+    if (options.approvedArguments !== undefined) {
+        try {
+            const expected = typeof options.approvedArguments === 'string' ? JSON.parse(options.approvedArguments) : options.approvedArguments;
+            argumentsMatch = canonical(JSON.parse(p?.approved_arguments ?? 'null')) === canonical(expected);
+        }
+        catch {
+            argumentsMatch = false;
+        }
+    }
+    if (result?.ok !== true || result.session_id !== sessionId || p?.session_id !== sessionId || p.id !== id) {
+        throw new PermissionResolutionError('Invalid permission resolution response; refresh the conversation');
+    }
+    const normalize = (value) => value === 'deny_once' ? 'deny' : value;
+    const expectedStatus = action.startsWith('allow') ? 'approved' : 'denied';
+    if (!argumentsMatch || p.status !== expectedStatus || normalize(p.decision) !== normalize(action) ||
+        (options.reason !== undefined && (p.reason ?? '').trim() !== options.reason.trim())) {
+        throw new PermissionResolutionError('Permission decision was not confirmed (stale, cancelled or resolved differently); refresh before retrying', result);
+    }
+    return result;
+}