@swarm-agent/sdk 0.1.52 → 0.1.53

package/dist/agents.js

@@ -1,4 +1,83 @@
+import { SwarmApiError } from './errors.js';
 import { SwarmSessionsNamespace } from './sessions.js';
+const WAIT_SECONDS = 25;
+// Exactly what daemons released before GET /v3/sessions/{id}/wait answer for
+// that route: 404, or these unknown-route refusals. Anything else is a real error.
+const OLDER_DAEMON_WAIT_REFUSALS = new Set([
+    'unknown sessions v3 path',
+    'route unavailable to an agent-bound token',
+    'route unavailable to an operator token',
+    'route unavailable on container SDK listener',
+]);
+function daemonHasNoWait(error) {
+    if (!(error instanceof SwarmApiError))
+        return false;
+    if (error.status === 404)
+        return error.message !== 'session not found';
+    return (error.status === 400 || error.status === 403) && OLDER_DAEMON_WAIT_REFUSALS.has(error.message);
+}
+/** The pending records that are calls to the tools you answer, with parsed arguments. */
+function clientToolCalls(sessionId, records, tools, owner) {
+    const names = new Set(tools);
+    const calls = [];
+    for (const record of records) {
+        if (!names.has(record.tool_name) || record.session_id !== sessionId)
+            continue;
+        let args;
+        try {
+            args = JSON.parse(record.tool_call_arguments || record.tool_arguments || '{}');
+        }
+        catch {
+            args = null;
+        }
+        if (!args || typeof args !== 'object' || Array.isArray(args))
+            continue;
+        calls.push({ kind: 'call', id: record.id, sessionId, runId: record.run_id, tool: record.tool_name, arguments: args, createdAt: record.created_at, ...owner });
+    }
+    return calls;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        const finish = () => { clearTimeout(timer); signal?.removeEventListener('abort', finish); resolve(); };
+        const timer = setTimeout(finish, ms);
+        signal?.addEventListener('abort', finish, { once: true });
+    });
+}
+const LIMIT_FIELDS = [
+    ['messagesPerMinute', 'messages_per_minute'],
+    ['sessionsPerHour', 'sessions_per_hour'],
+    ['maxConcurrentRuns', 'max_concurrent_runs'],
+    ['endUserMessagesPerMinute', 'end_user_messages_per_minute'],
+    ['endUserSessionsPerHour', 'end_user_sessions_per_hour'],
+    ['endUserMaxTokensPerDay', 'end_user_max_tokens_per_day'],
+];
+function limitBody(limits, keepZero) {
+    const body = {};
+    for (const [key, field] of LIMIT_FIELDS) {
+        const value = limits[key];
+        if (value === undefined || (!keepZero && !value))
+            continue;
+        if (!Number.isInteger(value) || value < 0)
+            throw new Error(`${key} must be a non-negative integer`);
+        body[field] = value;
+    }
+    return body;
+}
+function endUserFields(data) {
+    const out = {};
+    if (typeof data?.end_user === 'string')
+        out.endUser = data.end_user;
+    if (data?.labels && typeof data.labels === 'object' && !Array.isArray(data.labels))
+        out.labels = data.labels;
+    return out;
+}
+function pendingConfirmation(sessionId, record, owner) {
+    return {
+        kind: 'confirmation', id: record.id, sessionId, runId: record.run_id, tool: record.tool, summary: record.summary,
+        arguments: record.arguments ?? {}, argumentsHash: record.arguments_hash, createdAt: record.created_at, expiresAt: record.expires_at,
+        ...owner,
+    };
+}
 /** Throw from a handler to send this message to the model; other errors send "tool failed". */
 export class ClientToolError extends Error {
     constructor(message) {
@@ -12,15 +91,31 @@ function toolName(name) {
         throw new Error('tool and agent names are lowercase letters, digits and underscores');
     return name;
 }
+function requestId(prefix) {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function')
+        return `${prefix}-${crypto.randomUUID()}`;
+    return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 10)}`;
+}
+function operatorRequestId() {
+    return requestId('sdk-operator');
+}
 /**
  * Sealed agents and client tools (`/v2/agents`, `/v2/custom-tools`). Defining
  * them needs the owner or an `admin` token: keep this in a trusted backend.
  */
 export class SwarmAgentsNamespace {
     transport;
+    olderDaemonNoted = false;
     constructor(transport) {
         this.transport = transport;
     }
+    /** Records, once, that this daemon predates waiting and the SDK polls instead. */
+    noteOlderDaemon() {
+        if (this.olderDaemonNoted)
+            return;
+        this.olderDaemonNoted = true;
+        console.debug('swarm sdk: this daemon has no GET /v3/sessions/{id}/wait (it predates it); serve and converse poll instead');
+    }
     async defineClientTool(definition) {
         const name = toolName(definition.name);
         const res = await this.transport.request(`/v2/custom-tools/${name}`, {
@@ -31,6 +126,8 @@ export class SwarmAgentsNamespace {
                 input_schema: definition.input_schema,
                 effect: definition.effect ?? 'read',
                 ...(definition.timeout_ms !== undefined ? { timeout_ms: definition.timeout_ms } : {}),
+                ...(definition.confirm !== undefined ? { confirm: definition.confirm } : {}),
+                ...(definition.confirm_timeout_ms !== undefined ? { confirm_timeout_ms: definition.confirm_timeout_ms } : {}),
             },
         });
         return res.data.custom_tool;
@@ -61,6 +158,8 @@ export class SwarmAgentsNamespace {
      * Mints the token a gateway holds to serve one sealed agent. It can only
      * create and use that agent's sessions and answer its client tool calls;
      * it stops working if the agent is given any built-in tool. Owner only.
+     * Like every key it works while used and stops after 90 days unused;
+     * expiresInSeconds adds an optional fixed end date (at most 365 days).
      */
     async createGatewayToken(agentName, options = {}) {
         const agent = toolName(agentName);
@@ -68,14 +167,112 @@ export class SwarmAgentsNamespace {
             method: 'POST',
             body: {
                 name: options.name ?? `${agent} gateway`, agent_name: agent,
-                ...(options.expiresInSeconds ? { expires_in_seconds: options.expiresInSeconds } : {}),
-                ...(options.messagesPerMinute ? { messages_per_minute: options.messagesPerMinute } : {}),
-                ...(options.sessionsPerHour ? { sessions_per_hour: options.sessionsPerHour } : {}),
+                expires_in_seconds: options.expiresInSeconds,
+                ...limitBody(options, false),
             },
         });
         return { token: res.data.token, record: res.data.record };
     }
+    /**
+     * Changes a gateway token's limits in place (owner only); fields you omit
+     * keep their value, 0 restores the default. Applies from its next request.
+     */
+    async updateGatewayTokenLimits(tokenId, limits) {
+        if (typeof tokenId !== 'string' || !tokenId)
+            throw new Error('tokenId is required');
+        const body = limitBody(limits, true);
+        if (Object.keys(body).length === 0)
+            throw new Error('give at least one limit to change');
+        const res = await this.transport.request(`/v3/auth/tokens/${encodeURIComponent(tokenId)}/limits`, { method: 'POST', body });
+        return res.data.record;
+    }
+    /**
+     * Creates a conversation with a sealed agent for one end user (gateway
+     * token). `endUser` is stored with the session once and cannot change; the
+     * model never sees it. Pass the same `clientRequestId` to retry safely.
+     */
+    async startConversation(agentName, options = {}) {
+        const agent = toolName(agentName);
+        const session = await new SwarmSessionsNamespace(this.transport).create({
+            agent_name: agent,
+            ...(options.title !== undefined ? { title: options.title } : {}),
+            ...(options.clientRequestId !== undefined ? { client_request_id: options.clientRequestId } : {}),
+            ...(options.workspacePath !== undefined ? { workspace_path: options.workspacePath } : {}),
+            ...(options.workspaceId !== undefined ? { workspace_id: options.workspaceId } : {}),
+            ...(options.endUser !== undefined ? { end_user: options.endUser } : {}),
+            ...(options.labels !== undefined ? { labels: options.labels } : {}),
+        });
+        if (options.endUser !== undefined && session.end_user !== options.endUser) {
+            throw new Error('the daemon did not confirm the conversation\'s end user');
+        }
+        return { sessionId: session.id, ...(session.end_user !== undefined ? { endUser: session.end_user } : {}), ...(session.labels ? { labels: session.labels } : {}) };
+    }
+    /**
+     * One UTC day's model usage of the agent's conversations, by end user (a
+     * gateway token reads its own agent; the owner passes `agentName`).
+     */
+    async endUserUsage(options = {}) {
+        const query = new URLSearchParams();
+        if (options.agentName)
+            query.set('agent_name', toolName(options.agentName));
+        if (options.endUser !== undefined)
+            query.set('end_user', options.endUser);
+        if (options.date)
+            query.set('date', options.date);
+        if (options.limit !== undefined)
+            query.set('limit', String(options.limit));
+        const suffix = query.toString() ? `?${query.toString()}` : '';
+        const res = await this.transport.request(`/v3/sessions:end-user-usage${suffix}`);
+        return {
+            date: res.data.date,
+            truncated: Boolean(res.data.truncated),
+            endUsers: (res.data.end_users ?? []).map((row) => ({ endUser: row.end_user, recorded: row.recorded, usage: row.usage })),
+        };
+    }
     /** Today's spend against the daily cap. A gateway token may read it. */
+    /**
+     * Mints the human-takeover token for one sealed agent: it can read that
+     * agent's conversations, take one over (the agent stops replying), reply as a
+     * person and hand it back. It cannot post as the visitor, start runs or answer
+     * tool calls. Owner only. Like every key it works while used and stops after
+     * 90 days unused; expiresInSeconds adds an optional fixed end date.
+     */
+    async createOperatorToken(agentName, options = {}) {
+        const agent = toolName(agentName);
+        const res = await this.transport.request('/v3/auth/tokens', {
+            method: 'POST',
+            body: { name: options.name ?? `${agent} operator`, agent_name: agent, operator: true, expires_in_seconds: options.expiresInSeconds },
+        });
+        return { token: res.data.token, record: res.data.record };
+    }
+    /** Who holds a conversation: `{ state: 'human', by, since }`, `{ state: 'agent', ended_at }`, or undefined. */
+    async takeoverState(sessionId) {
+        const res = await this.transport.request(`/v3/sessions/${encodeURIComponent(sessionId)}/takeover`);
+        return res.data.takeover ?? undefined;
+    }
+    /** A person takes the conversation: the agent's run in flight stops and visitor messages start no runs. */
+    async takeOver(sessionId, options = {}) {
+        return this.setTakeover(sessionId, 'start', options.clientRequestId);
+    }
+    /** Hands the conversation back to the agent; the next visitor message runs it again. */
+    async handBack(sessionId, options = {}) {
+        return this.setTakeover(sessionId, 'end', options.clientRequestId);
+    }
+    /** Replies as a person during a takeover (an assistant message with source "operator"). */
+    async replyAsOperator(sessionId, content, options = {}) {
+        const res = await this.transport.request(`/v3/sessions/${encodeURIComponent(sessionId)}/operator-messages`, {
+            method: 'POST',
+            body: { content, client_request_id: options.clientRequestId ?? operatorRequestId() },
+        });
+        return res.data.message;
+    }
+    async setTakeover(sessionId, action, clientRequestId) {
+        const res = await this.transport.request(`/v3/sessions/${encodeURIComponent(sessionId)}/takeover`, {
+            method: 'POST',
+            body: { action, client_request_id: clientRequestId ?? operatorRequestId() },
+        });
+        return res.data.takeover;
+    }
     async spendToday() {
         const res = await this.transport.request('/v3/sessions:usage-limits');
         return res.data.limits;
@@ -86,26 +283,196 @@ export class SwarmAgentsNamespace {
     async removeClientTool(name) {
         await this.transport.request(`/v2/custom-tools/${toolName(name)}`, { method: 'DELETE' });
     }
-    /** Client tool calls waiting in a session, limited to the tool names you answer. */
+    /**
+     * Waits on one conversation (`GET /v3/sessions/{id}/wait`). Without `after`
+     * it answers at once with the current state and cursor. With `after` it
+     * returns as soon as there is a new assistant message, a pending tool call,
+     * a confirmation waiting for the person, the end of a run or of the
+     * session, or after `waitSeconds` (default 25, max 30). A gateway token may
+     * wait only on its agent's sessions.
+     */
+    async wait(sessionId, options = {}) {
+        const q = new URLSearchParams();
+        let seconds = 0;
+        if (typeof options.after === 'number') {
+            q.set('after', String(options.after));
+            seconds = Math.max(0, Math.min(30, Math.floor(options.waitSeconds ?? WAIT_SECONDS)));
+            q.set('wait_seconds', String(seconds));
+        }
+        const path = `/v3/sessions/${encodeURIComponent(sessionId)}/wait${q.toString() ? `?${q.toString()}` : ''}`;
+        const res = await this.transport.request(path, { signal: options.signal, timeoutMs: (seconds + 15) * 1000 });
+        const d = res.data;
+        const owner = endUserFields(d);
+        return {
+            sessionId: d.session_id ?? sessionId, cursor: d.cursor, reasons: d.reasons ?? [], timedOut: !!d.timed_out,
+            more: !!d.more, staleCursor: !!d.stale_cursor, ended: !!d.ended, run: d.run ?? undefined, pendingCalls: d.pending_calls ?? [],
+            pendingConfirmations: (d.pending_confirmations ?? []).filter((record) => record.status === 'pending').map((record) => pendingConfirmation(sessionId, record, owner)),
+            ...owner,
+        };
+    }
+    /**
+     * What waits on your application in a session, limited to the tool names you
+     * answer: client tool calls to run (`kind: 'call'`) and confirmed calls
+     * waiting for the person's approval (`kind: 'confirmation'`). Both carry the
+     * session's `endUser` and `labels`.
+     */
     async pendingCalls(sessionId, tools) {
+        const names = [...tools];
+        let state;
+        try {
+            state = await this.wait(sessionId);
+        }
+        catch (error) {
+            if (!daemonHasNoWait(error))
+                throw error;
+            this.noteOlderDaemon();
+            return this.polledItems(sessionId, names);
+        }
+        return this.waitItems(sessionId, state, names);
+    }
+    /** The calls and confirmations a wait reported, for the tools you answer. */
+    waitItems(sessionId, state, tools) {
+        const owner = { ...(state.endUser !== undefined ? { endUser: state.endUser } : {}), ...(state.labels ? { labels: state.labels } : {}) };
         const names = new Set(tools);
+        return [...clientToolCalls(sessionId, state.pendingCalls, tools, owner), ...state.pendingConfirmations.filter((confirmation) => names.has(confirmation.tool))];
+    }
+    /** pendingCalls for daemons that predate waiting (see noteOlderDaemon). */
+    async polledItems(sessionId, tools) {
         const res = await this.transport.request(`/v3/sessions/${encodeURIComponent(sessionId)}/permissions?status=pending&limit=100`);
-        const calls = [];
-        for (const record of res.data.permissions ?? []) {
-            if (!names.has(record.tool_name) || record.session_id !== sessionId)
-                continue;
-            let args;
+        // The end user comes with the delivery, from the stored session.
+        const items = clientToolCalls(sessionId, res.data.permissions ?? [], tools, endUserFields(res.data));
+        const names = new Set(tools);
+        for (const confirmation of await this.confirmations(sessionId)) {
+            if (names.has(confirmation.tool))
+                items.push(confirmation);
+        }
+        return items;
+    }
+    /**
+     * Lists the agent's conversations, most recently updated first
+     * (`GET /v3/sessions:agent`). A gateway or operator token lists its own
+     * agent; the owner passes `agent`. Page with `nextCursor`.
+     */
+    async listSessions(params = {}) {
+        const q = new URLSearchParams();
+        if (params.agent)
+            q.set('agent', toolName(params.agent));
+        if (params.state)
+            q.set('state', params.state);
+        if (typeof params.updatedAfter === 'number')
+            q.set('updated_after', String(params.updatedAfter));
+        if (typeof params.updatedBefore === 'number')
+            q.set('updated_before', String(params.updatedBefore));
+        if (params.cursor)
+            q.set('cursor', params.cursor);
+        if (typeof params.limit === 'number')
+            q.set('limit', String(params.limit));
+        const res = await this.transport.request(`/v3/sessions:agent${q.toString() ? `?${q.toString()}` : ''}`);
+        return { sessions: res.data.sessions ?? [], ...(res.data.next_cursor ? { nextCursor: res.data.next_cursor } : {}) };
+    }
+    /**
+     * Ends a conversation: it accepts no more messages, its run in flight and
+     * pending tool calls stop. Ending an ended conversation changes nothing.
+     */
+    async endSession(sessionId, options = {}) {
+        const res = await this.transport.request(`/v3/sessions/${encodeURIComponent(sessionId)}/end`, { method: 'POST', body: { client_request_id: options.clientRequestId ?? requestId('sdk-end'), ...(options.reason ? { reason: options.reason } : {}) } });
+        return { ended: res.data.ended, alreadyEnded: !!res.data.already_ended, ...(res.data.stopped_run_id ? { stoppedRunId: res.data.stopped_run_id } : {}) };
+    }
+    /**
+     * Hard deletes a conversation and its messages. The daemon refuses (409)
+     * while a run or tool call is in flight: end the session first.
+     */
+    async deleteSession(sessionId) {
+        await this.transport.request(`/v3/sessions/${encodeURIComponent(sessionId)}`, { method: 'DELETE' });
+    }
+    /** Reads the agent's event feed after a cursor (`GET /v3/sessions:agent-events`), oldest first. */
+    async events(params = {}) {
+        const q = new URLSearchParams();
+        if (params.agent)
+            q.set('agent', toolName(params.agent));
+        if (typeof params.after === 'number')
+            q.set('after', String(params.after));
+        if (typeof params.limit === 'number')
+            q.set('limit', String(params.limit));
+        if (params.kinds?.length)
+            q.set('kind', params.kinds.join(','));
+        const seconds = Math.max(0, Math.min(30, Math.floor(params.waitSeconds ?? 0)));
+        if (seconds > 0)
+            q.set('wait', String(seconds));
+        const res = await this.transport.request(`/v3/sessions:agent-events${q.toString() ? `?${q.toString()}` : ''}`, { signal: params.signal, timeoutMs: (seconds + 15) * 1000 });
+        const { events, next_after, latest_seq, oldest_seq, gap } = res.data;
+        return { events: events ?? [], next_after, latest_seq, oldest_seq, gap: !!gap };
+    }
+    /**
+     * Follows the agent's event feed until `signal` aborts, waiting on the
+     * daemon between entries (no polling). Yields a gap record when entries
+     * after the cursor were already dropped by the feed's retention.
+     */
+    async *watchEvents(params = {}) {
+        let after = params.after ?? 0;
+        while (!params.signal?.aborted) {
+            let page;
             try {
-                args = JSON.parse(record.tool_call_arguments || record.tool_arguments || '{}');
+                page = await this.events({ ...params, after, waitSeconds: WAIT_SECONDS });
             }
-            catch {
-                args = null;
+            catch (error) {
+                if (params.signal?.aborted)
+                    return;
+                throw error;
             }
-            if (!args || typeof args !== 'object' || Array.isArray(args))
-                continue;
-            calls.push({ id: record.id, sessionId, runId: record.run_id, tool: record.tool_name, arguments: args, createdAt: record.created_at });
+            if (page.gap)
+                yield { kind: 'gap', from: after, to: page.next_after };
+            for (const event of page.events)
+                yield event;
+            after = page.next_after;
         }
-        return calls;
+    }
+    /** Confirmed tool calls in a session waiting for the person's approval (at most one). */
+    async confirmations(sessionId) {
+        const res = await this.transport.request(`/v3/sessions/${encodeURIComponent(sessionId)}/confirmations`);
+        const owner = endUserFields(res.data);
+        return (res.data.confirmations ?? []).filter((record) => record.status === 'pending').map((record) => pendingConfirmation(sessionId, record, owner));
+    }
+    /**
+     * Records the person's decision on a confirmation and returns its new state.
+     * Approving needs the hash of the arguments the person was shown; the call
+     * then waits for your handler like any other. `confirm` and `reject` do this
+     * and also wait for the agent's reply.
+     */
+    async decideConfirmation(sessionId, confirmationId, decision) {
+        if (typeof confirmationId !== 'string' || !confirmationId)
+            throw new Error('confirmationId is required');
+        if (decision.decision === 'approve' && !decision.argumentsHash)
+            throw new Error('approving needs the argumentsHash the person was shown');
+        const res = await this.transport.request(`/v3/sessions/${encodeURIComponent(sessionId)}/confirmations/${encodeURIComponent(confirmationId)}`, {
+            method: 'POST',
+            body: {
+                decision: decision.decision,
+                ...(decision.argumentsHash ? { arguments_hash: decision.argumentsHash } : {}),
+                ...(decision.note ? { note: decision.note } : {}),
+            },
+        });
+        return res.data.confirmation;
+    }
+    /**
+     * The person approved: runs the confirmed call through `handlers` (with
+     * exactly the confirmation's arguments) and returns the agent's reply. With
+     * `endUser`, it refuses a session that belongs to anyone else before
+     * recording the approval.
+     */
+    async confirm(sessionId, confirmation, handlers, options = {}) {
+        return this.followTurn(sessionId, handlers, options, async () => {
+            await this.decideConfirmation(sessionId, confirmation.id, { decision: 'approve', argumentsHash: confirmation.argumentsHash });
+        });
+    }
+    /**
+     * The person declined: the model is told "the person declined: <note>".
+     * Returns the agent's reply. `endUser` works as on `confirm`.
+     */
+    async reject(sessionId, confirmation, handlers, options = {}) {
+        return this.followTurn(sessionId, handlers, options, async () => {
+            await this.decideConfirmation(sessionId, confirmation.id, { decision: 'reject', note: options.note });
+        });
     }
     /** Returns `result` (any JSON value) to the model as the tool's output. */
     async answer(sessionId, callId, result) {
@@ -117,57 +484,182 @@ export class SwarmAgentsNamespace {
     }
     /**
      * Answers one session's client tool calls with `handlers` until `signal`
-     * aborts. Each call is answered at most once; a handler error fails the
-     * call with "tool failed" unless it is a ClientToolError.
+     * aborts or the conversation has ended, waiting on the daemon between steps
+     * (`intervalMs` applies only to daemons that predate waiting). Each call is
+     * answered at most once; a handler error fails the call with "tool failed"
+     * unless it is a ClientToolError. With `endUser`, a call whose session
+     * belongs to anyone else is failed unanswered, and such a confirmation is
+     * not passed to `onConfirm`. Confirmations are never answered here:
+     * `onConfirm` is called once for each (show the approval card), and
+     * `confirm` or `reject` records the person's decision.
      */
     async serve(sessionId, handlers, options = {}) {
         const handled = new Set();
-        const interval = Math.max(50, options.intervalMs ?? 250);
+        const tools = Object.keys(handlers);
+        let cursor;
         while (!options.signal?.aborted) {
-            for (const call of await this.pendingCalls(sessionId, Object.keys(handlers))) {
-                if (handled.has(call.id))
-                    continue;
-                handled.add(call.id);
-                try {
-                    await this.answer(sessionId, call.id, await handlers[call.tool](call.arguments, call));
-                }
-                catch (error) {
-                    await this.fail(sessionId, call.id, error instanceof ClientToolError ? error.message : 'tool failed').catch(() => undefined);
+            let state;
+            try {
+                state = await this.wait(sessionId, cursor === undefined ? { signal: options.signal } : { after: cursor, signal: options.signal });
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    return;
+                if (cursor === undefined && daemonHasNoWait(error)) {
+                    this.noteOlderDaemon();
+                    return this.servePolling(sessionId, handlers, handled, options);
                 }
+                throw error;
+            }
+            cursor = state.cursor;
+            await this.handleItems(sessionId, this.waitItems(sessionId, state, tools), handlers, handled, options);
+            // An ended conversation starts no more runs, so no more calls come.
+            if (state.ended && !state.run?.active)
+                return;
+        }
+    }
+    /** Answers each new call once and shows each new confirmation once. */
+    async handleItems(sessionId, items, handlers, handled, options) {
+        for (const item of items) {
+            if (handled.has(item.id))
+                continue;
+            handled.add(item.id);
+            if (item.kind === 'confirmation') {
+                if (options.endUser === undefined || item.endUser === options.endUser)
+                    await options.onConfirm?.(item);
+                continue;
+            }
+            if (options.endUser !== undefined && item.endUser !== options.endUser) {
+                await this.fail(sessionId, item.id, 'tool failed').catch(() => undefined);
+                continue;
             }
-            await new Promise((resolve) => {
-                const timer = setTimeout(resolve, interval);
-                options.signal?.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
-            });
+            try {
+                await this.answer(sessionId, item.id, await handlers[item.tool](item.arguments, item));
+            }
+            catch (error) {
+                await this.fail(sessionId, item.id, error instanceof ClientToolError ? error.message : 'tool failed').catch(() => undefined);
+            }
+        }
+    }
+    /** serve for daemons that predate waiting (see noteOlderDaemon). */
+    async servePolling(sessionId, handlers, handled, options) {
+        const interval = Math.max(50, options.intervalMs ?? 250);
+        const tools = Object.keys(handlers);
+        while (!options.signal?.aborted) {
+            await this.handleItems(sessionId, await this.polledItems(sessionId, tools), handlers, handled, options);
+            await sleep(interval, options.signal);
         }
     }
     /**
      * Sends one user message to a sealed agent's session, answers its client
      * tool calls with `handlers` while it runs, and returns once the run has
      * finished. This is the whole loop a gateway needs per visitor message.
+     * It waits on the daemon between steps; `pollIntervalMs` applies only to
+     * daemons that predate waiting. With `endUser`, it refuses a session that
+     * belongs to anyone else before sending, and answers only that end user's
+     * calls. When the agent asks the person to approve a confirmed tool call,
+     * the result carries `confirmation`: pass it to `confirm` or `reject`.
      */
     async converse(sessionId, message, handlers, options = {}) {
         const sessions = new SwarmSessionsNamespace(this.transport);
-        const before = new Set(((await sessions.get(sessionId)).messages ?? []).map((m) => m.id));
+        return this.followTurn(sessionId, handlers, options, async () => {
+            await sessions.sendMessage(sessionId, { content: message });
+        });
+    }
+    /**
+     * Starts a turn with `start`, answers client tool calls while it runs, and
+     * returns once the agent has replied or has asked for a confirmation. With
+     * `endUser`, it refuses a session that belongs to anyone else before
+     * `start` runs.
+     */
+    async followTurn(sessionId, handlers, options, start) {
+        const sessions = new SwarmSessionsNamespace(this.transport);
+        const initial = await sessions.get(sessionId);
+        if (options.endUser !== undefined && initial.end_user !== options.endUser) {
+            throw new Error('This conversation belongs to another end user');
+        }
+        let begin;
+        try {
+            begin = await this.wait(sessionId);
+        }
+        catch (error) {
+            if (!daemonHasNoWait(error))
+                throw error;
+            this.noteOlderDaemon();
+            return this.followTurnPolling(sessionId, initial, handlers, options, start);
+        }
+        if (begin.ended)
+            throw new Error('The conversation has ended; start a new session');
+        const before = new Set((initial.messages ?? []).map((m) => m.id));
+        const earlier = (initial.raw ?? {}).pending_confirmation?.id;
+        const serving = { onConfirm: options.onConfirm, ...(options.endUser !== undefined ? { endUser: options.endUser } : {}) };
+        const tools = Object.keys(handlers);
+        const deadline = Date.now() + (options.timeoutMs ?? 120_000);
+        const handled = new Set();
+        await start();
+        let cursor = begin.cursor;
+        for (;;) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                throw new Error('The agent did not finish in time; the run may still complete');
+            const state = await this.wait(sessionId, { after: cursor, waitSeconds: Math.min(WAIT_SECONDS, Math.ceil(remaining / 1000)) });
+            cursor = state.cursor;
+            const items = this.waitItems(sessionId, state, tools);
+            await this.handleItems(sessionId, items, handlers, handled, serving);
+            const calls = items.filter((item) => item.kind === 'call');
+            if (calls.length > 0 || state.run?.active || state.more)
+                continue;
+            const asked = items.find((item) => item.kind === 'confirmation' && item.id !== earlier);
+            if (state.reasons.length === 0 && !state.ended && !asked)
+                continue;
+            const detail = await sessions.get(sessionId);
+            const added = (detail.messages ?? []).filter((m) => !before.has(m.id));
+            const failure = added.find((m) => m.role === 'system' && m.metadata?.message_kind === 'run_failure');
+            if (failure)
+                throw new Error(`The agent's run failed: ${String(failure.content ?? '').slice(0, 300)}`);
+            const reply = added.filter((m) => m.role === 'assistant').map((m) => String(m.content ?? '')).join('\n\n');
+            if (asked)
+                return { reply, messages: added, confirmation: asked };
+            if (added.some((m) => m.role === 'assistant'))
+                return { reply, messages: added };
+            if (state.ended)
+                throw new Error('The conversation was ended before the agent replied');
+        }
+    }
+    /** followTurn for daemons that predate waiting (see noteOlderDaemon). */
+    async followTurnPolling(sessionId, initial, handlers, options, start) {
+        const sessions = new SwarmSessionsNamespace(this.transport);
+        const before = new Set((initial.messages ?? []).map((m) => m.id));
+        const earlier = (initial.raw ?? {}).pending_confirmation?.id;
         const controller = new AbortController();
-        const serving = this.serve(sessionId, handlers, { signal: controller.signal, intervalMs: options.pollIntervalMs ?? 200 });
+        const serving = this.servePolling(sessionId, handlers, new Set(), {
+            signal: controller.signal,
+            intervalMs: options.pollIntervalMs ?? 200,
+            onConfirm: options.onConfirm,
+            ...(options.endUser !== undefined ? { endUser: options.endUser } : {}),
+        });
         const deadline = Date.now() + (options.timeoutMs ?? 120_000);
         try {
-            await sessions.sendMessage(sessionId, { content: message });
+            await start();
             for (;;) {
                 const detail = await sessions.get(sessionId);
                 const raw = (detail.raw ?? {});
                 const added = (detail.messages ?? []).filter((m) => !before.has(m.id));
                 const pending = Array.isArray(raw.pending_permissions) ? raw.pending_permissions.length : 0;
                 const failure = added.find((m) => m.role === 'system' && m.metadata?.message_kind === 'run_failure');
+                const reply = added.filter((m) => m.role === 'assistant').map((m) => String(m.content ?? '')).join('\n\n');
                 if (!raw.active_run_intent && failure)
                     throw new Error(`The agent's run failed: ${String(failure.content ?? '').slice(0, 300)}`);
+                const asked = raw.pending_confirmation;
+                if (!raw.active_run_intent && asked?.id && asked.id !== earlier) {
+                    return { reply, messages: added, confirmation: pendingConfirmation(sessionId, asked, endUserFields(raw)) };
+                }
                 if (!raw.active_run_intent && pending === 0 && added.some((m) => m.role === 'assistant')) {
-                    return { reply: added.filter((m) => m.role === 'assistant').map((m) => String(m.content ?? '')).join('\n\n'), messages: added };
+                    return { reply, messages: added };
                 }
                 if (Date.now() > deadline)
                     throw new Error('The agent did not finish in time; the run may still complete');
-                await new Promise((resolve) => setTimeout(resolve, options.pollIntervalMs ?? 400));
+                await sleep(options.pollIntervalMs ?? 400);
             }
         }
         finally {