@swarm-agent/sdk 0.1.51 → 0.1.53

package/dist/agents.d.ts

@@ -1,14 +1,128 @@
+import type { PendingPermissionRecord } from './permissions.js';
 import type { SwarmTransport } from './transport.js';
+/** What a wait returned for. */
+export type SessionWaitReason = 'assistant_message' | 'tool_call' | 'run_ended' | 'session_ended' | 'confirmation';
+/** One answer from `agents.wait`: why it returned and the session's state now. */
+export interface SessionWait {
+    sessionId: string;
+    /** Pass back as `after` to wait for what comes next. */
+    cursor: number;
+    /** Empty when the wait ended without anything to act on (see `timedOut`). */
+    reasons: SessionWaitReason[];
+    timedOut: boolean;
+    /** More events follow the cursor: wait again at once. */
+    more: boolean;
+    /** The cursor was ahead of the session; `cursor` is where it is now. */
+    staleCursor: boolean;
+    /** The conversation was ended (`endSession`): it takes no more messages. */
+    ended: boolean;
+    run?: {
+        run_id: string;
+        status: string;
+        active: boolean;
+    };
+    /** Tool calls waiting for an answer, as `GET .../permissions?status=pending` returns them. */
+    pendingCalls: PendingPermissionRecord[];
+    /** Confirmed calls waiting for the person's approval (at most one); reason `confirmation` wakes a wait. */
+    pendingConfirmations: PendingConfirmation[];
+    /** The session's end user and labels, from the stored session (gateway conversations). */
+    endUser?: string;
+    labels?: Record<string, string>;
+}
+/** One of an agent's conversations, as `agents.listSessions` returns it. */
+export interface AgentSession {
+    id: string;
+    title: string;
+    created_at: number;
+    updated_at: number;
+    message_count: number;
+    last_message_at: number;
+    state: 'active' | 'ended';
+    ended?: {
+        at: number;
+        by: string;
+        reason?: string;
+    };
+    takeover?: Takeover;
+    run_active: boolean;
+    /** Set on gateway conversations, from the stored session. */
+    end_user?: string;
+    labels?: Record<string, string>;
+}
+export interface ListAgentSessionsParams {
+    /** Owner only: the agent to list. A gateway token always lists its own agent. */
+    agent?: string;
+    state?: 'active' | 'ended' | 'all';
+    /** Unix milliseconds. */
+    updatedAfter?: number;
+    updatedBefore?: number;
+    /** `nextCursor` from the previous page. */
+    cursor?: string;
+    /** 1 to 200 (default 50). */
+    limit?: number;
+}
+export type AgentEventKind = 'session.created' | 'message.user' | 'message.assistant' | 'tool.called' | 'tool.answered' | 'tool.failed' | 'session.ended' | 'run.failed' | 'takeover.started' | 'takeover.ended' | 'confirmation.requested' | 'confirmation.decided';
+/**
+ * One entry in an agent's event feed. Message text and tool arguments,
+ * results and reasons are cut to 2000 characters, with `data.truncated` set.
+ */
+export interface AgentEvent {
+    /** Feed position; pass the last `next_after` back as `after`. */
+    seq: number;
+    id: string;
+    at: number;
+    kind: AgentEventKind;
+    session_id: string;
+    /** The conversation's end user and labels (gateway conversations), from the stored session. */
+    end_user?: string;
+    labels?: Record<string, string>;
+    data?: Record<string, unknown>;
+}
+export interface AgentEventPage {
+    events: AgentEvent[];
+    next_after: number;
+    latest_seq: number;
+    oldest_seq: number;
+    /** Entries after your cursor were already dropped (or the cursor is ahead): resync from `next_after`. */
+    gap: boolean;
+}
+export interface AgentEventsParams {
+    /** Owner only: the agent to follow. A gateway or operator token always follows its own agent. */
+    agent?: string;
+    after?: number;
+    /** 1 to 500 (default 100). */
+    limit?: number;
+    /** Kind prefixes, e.g. `['message', 'tool.failed']`. */
+    kinds?: string[];
+    /** Wait up to this many seconds (max 30) for an entry when there is none. */
+    waitSeconds?: number;
+    signal?: AbortSignal;
+}
+/** Yielded by `watchEvents` when entries were missed (dropped by feed retention). */
+export interface AgentEventGap {
+    kind: 'gap';
+    from: number;
+    to: number;
+}
 /** A typed tool the application answers. Swarm validates and waits; it never executes it. */
 export interface ClientToolDefinition {
     name: string;
     description: string;
     /** JSON Schema for the arguments; must be `type: "object"` with only local `$ref`s. */
     input_schema: Record<string, unknown>;
-    /** `write` marks a tool with external effects (confirm with a person before running it). */
+    /** `write` marks a tool with external effects. Write tools are confirmed by default (see `confirm`). */
     effect?: 'read' | 'write';
     /** How long a call waits for an answer before the model gets "client tool timed out" (max 300000). */
     timeout_ms?: number;
+    /**
+     * Each call waits for the person to approve it before your handler runs it.
+     * Default: true for write tools, false for read tools. The model must add a
+     * one-sentence `summary` argument for the approval card; your handler never
+     * receives it.
+     */
+    confirm?: boolean;
+    /** How long a call waits for the person's decision before the model is told nobody answered (default 900000 = 15 min, max 1 day). */
+    confirm_timeout_ms?: number;
 }
 /**
  * An agent whose only capabilities are the client tools listed. It has no
@@ -23,12 +137,16 @@ export interface SealedAgentDefinition {
     provider?: string;
     model?: string;
     thinking?: string;
-    /** Bounds one message's cost. Unset fields use the sealed defaults (4 model calls, 1024 output tokens, last 40 messages, 60 s). */
+    /**
+     * Bounds one message's cost. Unset fields use the sealed defaults (4 model calls, 1024 output tokens, last 40 messages, 60 s).
+     * `retention_days` (1 to 3650; unset keeps them) deletes ended or idle conversations that many days after their last activity.
+     */
     limits?: {
         max_steps?: number;
         max_output_tokens?: number;
         max_history_messages?: number;
         run_timeout_ms?: number;
+        retention_days?: number;
     };
 }
 /** The account's spend today and its daily cap, as the daemon enforces it. */
@@ -40,6 +158,7 @@ export interface SpendToday {
 }
 /** A pending client tool call your application must answer. */
 export interface ClientToolCall {
+    kind: 'call';
     /** Pass to `answer`/`fail`. */
     id: string;
     sessionId: string;
@@ -48,7 +167,97 @@ export interface ClientToolCall {
     /** Already validated by Swarm against the tool's input_schema. */
     arguments: Record<string, unknown>;
     createdAt: number;
+    /**
+     * The session's end user, as your gateway set it at create time. It comes
+     * from the stored session, never from the model: decide whose data the call
+     * may see from this, not from `arguments`.
+     */
+    endUser?: string;
+    labels?: Record<string, string>;
+}
+/** A gateway token's limits; omitted fields keep the daemon defaults (or, on update, their current value). */
+export interface GatewayTokenLimits {
+    /** Messages (model runs) the token may start per minute (default 120). */
+    messagesPerMinute?: number;
+    /** New conversations per hour (default 300). */
+    sessionsPerHour?: number;
+    /** Model runs at once across the agent's conversations (default 4, 1-64). */
+    maxConcurrentRuns?: number;
+    /** Messages per minute for one end user's conversations (default 20). */
+    endUserMessagesPerMinute?: number;
+    /** New conversations per hour for one end user (default 30). */
+    endUserSessionsPerHour?: number;
+    /** Model tokens one end user may use per UTC day (default: no cap). */
+    endUserMaxTokensPerDay?: number;
+}
+/** One end user's model usage for a UTC day, from the provider receipts of their sessions. */
+export interface EndUserUsage {
+    endUser: string;
+    /** False when nothing was recorded for them that day. */
+    recorded: boolean;
+    usage: {
+        total_tokens: number;
+        input_tokens: number;
+        output_tokens: number;
+        receipt_count: number;
+    } & Record<string, unknown>;
+}
+/**
+ * `code` on a 429 from a gateway token: `token_*` is the token's own limit,
+ * `end_user_*` one end user's. Retry after `Retry-After` seconds.
+ */
+export type GatewayLimitCode = 'token_messages_rate_limited' | 'token_sessions_rate_limited' | 'token_concurrent_runs_limited' | 'end_user_messages_rate_limited' | 'end_user_sessions_rate_limited' | 'end_user_daily_tokens_exceeded' | 'rate_limit_capacity_reached';
+/**
+ * A call to a confirmed client tool, waiting for the person's approval. Show
+ * `summary` and `arguments` on a card, then call `confirm` or `reject`.
+ * Nothing has run yet; after approval the same call reaches your handler with
+ * exactly these `arguments`.
+ */
+export interface PendingConfirmation {
+    kind: 'confirmation';
+    /** Pass to `confirm`/`reject`/`decideConfirmation`. */
+    id: string;
+    sessionId: string;
+    runId: string;
+    tool: string;
+    /** The model's one-sentence description of what approving will do. */
+    summary: string;
+    /** What your handler will receive on approval (validated against the tool's schema). */
+    arguments: Record<string, unknown>;
+    /** `sha256:<hex>` of the arguments; an approval must send it back. */
+    argumentsHash: string;
+    createdAt: number;
+    /** After this (unix ms) the model is told nobody answered. */
+    expiresAt: number;
+    /** The session's end user and labels, from the stored session (as on `ClientToolCall`). */
+    endUser?: string;
+    labels?: Record<string, string>;
 }
+/** A confirmation as the daemon stores it, in any state. */
+export interface ClientToolConfirmationRecord {
+    id: string;
+    kind: 'confirmation';
+    status: 'pending' | 'approved' | 'rejected' | 'expired';
+    tool: string;
+    summary: string;
+    arguments: Record<string, unknown>;
+    arguments_hash: string;
+    run_id: string;
+    call_id: string;
+    created_at: number;
+    expires_at: number;
+    decided_at?: number;
+    note?: string;
+    execution_call_id: string;
+    execution_permission_id?: string;
+    execution_deadline?: number;
+    delivered?: boolean;
+    delivered_at?: number;
+    outcome_message_id?: string;
+    continuation_run_id?: string;
+}
+/** Called once for each confirmation `serve` sees: show the approval card from here. */
+export type ConfirmationHandler = (confirmation: PendingConfirmation) => Promise<void> | void;
 /** Throw from a handler to send this message to the model; other errors send "tool failed". */
 export declare class ClientToolError extends Error {
     constructor(message: string);
@@ -58,57 +267,263 @@ export type ClientToolHandler = (args: Record<string, unknown>, call: ClientTool
 export interface ConverseResult {
     reply: string;
     messages: Array<Record<string, any>>;
+    /**
+     * Set when the turn ended waiting for the person to approve a confirmed
+     * tool call: show it, then call `confirm` or `reject` (each returns the
+     * agent's next reply). `reply` holds whatever the agent said before asking.
+     */
+    confirmation?: PendingConfirmation;
 }
+/** Options of `serve`. */
+export interface ServeOptions {
+    signal?: AbortSignal;
+    /** Poll interval, only against a daemon that predates waiting. */
+    intervalMs?: number;
+    /** Fail calls (and hide confirmations) of sessions that belong to anyone else. */
+    endUser?: string;
+    onConfirm?: ConfirmationHandler;
+}
+/** Options of `converse`, `confirm` and `reject`. */
+export interface TurnOptions {
+    timeoutMs?: number;
+    /** Poll interval, only against a daemon that predates waiting. */
+    pollIntervalMs?: number;
+    /** Refuse a session that belongs to anyone else before sending anything. */
+    endUser?: string;
+    onConfirm?: ConfirmationHandler;
+}
+/** Who holds a conversation, as stored in its metadata under `takeover`. */
+export type Takeover = {
+    state: 'human';
+    by: string;
+    since: number;
+} | {
+    state: 'agent';
+    ended_at: number;
+};
 /**
  * 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 declare class SwarmAgentsNamespace {
     private readonly transport;
+    private olderDaemonNoted;
     constructor(transport: SwarmTransport);
+    /** Records, once, that this daemon predates waiting and the SDK polls instead. */
+    private noteOlderDaemon;
     defineClientTool(definition: ClientToolDefinition): Promise<Record<string, unknown>>;
     defineSealedAgent(definition: SealedAgentDefinition): Promise<Record<string, unknown>>;
     /**
      * 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).
      */
     createGatewayToken(agentName: string, options?: {
         name?: string;
         expiresInSeconds?: number;
-        messagesPerMinute?: number;
-        sessionsPerHour?: number;
-    }): Promise<{
+    } & GatewayTokenLimits): Promise<{
         token: string;
         record: Record<string, unknown>;
     }>;
+    /**
+     * 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.
+     */
+    updateGatewayTokenLimits(tokenId: string, limits: GatewayTokenLimits): Promise<Record<string, unknown>>;
+    /**
+     * 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.
+     */
+    startConversation(agentName: string, options?: {
+        endUser?: string;
+        labels?: Record<string, string>;
+        title?: string;
+        clientRequestId?: string;
+        workspacePath?: string;
+        workspaceId?: string;
+    }): Promise<{
+        sessionId: string;
+        endUser?: string;
+        labels?: Record<string, string>;
+    }>;
+    /**
+     * 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`).
+     */
+    endUserUsage(options?: {
+        endUser?: string;
+        date?: string;
+        limit?: number;
+        agentName?: string;
+    }): Promise<{
+        date: string;
+        endUsers: EndUserUsage[];
+        truncated: boolean;
+    }>;
     /** 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.
+     */
+    createOperatorToken(agentName: string, options?: {
+        name?: string;
+        expiresInSeconds?: number;
+    }): Promise<{
+        token: string;
+        record: Record<string, unknown>;
+    }>;
+    /** Who holds a conversation: `{ state: 'human', by, since }`, `{ state: 'agent', ended_at }`, or undefined. */
+    takeoverState(sessionId: string): Promise<Takeover | undefined>;
+    /** A person takes the conversation: the agent's run in flight stops and visitor messages start no runs. */
+    takeOver(sessionId: string, options?: {
+        clientRequestId?: string;
+    }): Promise<Takeover>;
+    /** Hands the conversation back to the agent; the next visitor message runs it again. */
+    handBack(sessionId: string, options?: {
+        clientRequestId?: string;
+    }): Promise<Takeover>;
+    /** Replies as a person during a takeover (an assistant message with source "operator"). */
+    replyAsOperator(sessionId: string, content: string, options?: {
+        clientRequestId?: string;
+    }): Promise<Record<string, unknown>>;
+    private setTakeover;
     spendToday(): Promise<SpendToday>;
     removeAgent(name: string): Promise<void>;
     removeClientTool(name: string): Promise<void>;
-    /** Client tool calls waiting in a session, limited to the tool names you answer. */
-    pendingCalls(sessionId: string, tools: Iterable<string>): Promise<ClientToolCall[]>;
+    /**
+     * 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.
+     */
+    wait(sessionId: string, options?: {
+        after?: number;
+        waitSeconds?: number;
+        signal?: AbortSignal;
+    }): Promise<SessionWait>;
+    /**
+     * 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`.
+     */
+    pendingCalls(sessionId: string, tools: Iterable<string>): Promise<Array<ClientToolCall | PendingConfirmation>>;
+    /** The calls and confirmations a wait reported, for the tools you answer. */
+    private waitItems;
+    /** pendingCalls for daemons that predate waiting (see noteOlderDaemon). */
+    private polledItems;
+    /**
+     * 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`.
+     */
+    listSessions(params?: ListAgentSessionsParams): Promise<{
+        sessions: AgentSession[];
+        nextCursor?: string;
+    }>;
+    /**
+     * Ends a conversation: it accepts no more messages, its run in flight and
+     * pending tool calls stop. Ending an ended conversation changes nothing.
+     */
+    endSession(sessionId: string, options?: {
+        reason?: string;
+        clientRequestId?: string;
+    }): Promise<{
+        ended: {
+            at: number;
+            by: string;
+            reason?: string;
+        };
+        alreadyEnded: boolean;
+        stoppedRunId?: string;
+    }>;
+    /**
+     * Hard deletes a conversation and its messages. The daemon refuses (409)
+     * while a run or tool call is in flight: end the session first.
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /** Reads the agent's event feed after a cursor (`GET /v3/sessions:agent-events`), oldest first. */
+    events(params?: AgentEventsParams): Promise<AgentEventPage>;
+    /**
+     * 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.
+     */
+    watchEvents(params?: Omit<AgentEventsParams, 'waitSeconds' | 'limit'>): AsyncGenerator<AgentEvent | AgentEventGap>;
+    /** Confirmed tool calls in a session waiting for the person's approval (at most one). */
+    confirmations(sessionId: string): Promise<PendingConfirmation[]>;
+    /**
+     * 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.
+     */
+    decideConfirmation(sessionId: string, confirmationId: string, decision: {
+        decision: 'approve' | 'reject';
+        argumentsHash?: string;
+        note?: string;
+    }): Promise<ClientToolConfirmationRecord>;
+    /**
+     * 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.
+     */
+    confirm(sessionId: string, confirmation: PendingConfirmation, handlers: Record<string, ClientToolHandler>, options?: TurnOptions): Promise<ConverseResult>;
+    /**
+     * The person declined: the model is told "the person declined: <note>".
+     * Returns the agent's reply. `endUser` works as on `confirm`.
+     */
+    reject(sessionId: string, confirmation: PendingConfirmation, handlers: Record<string, ClientToolHandler>, options?: TurnOptions & {
+        note?: string;
+    }): Promise<ConverseResult>;
     /** Returns `result` (any JSON value) to the model as the tool's output. */
     answer(sessionId: string, callId: string, result: unknown): Promise<void>;
     /** Returns `reason` to the model as the tool's error. */
     fail(sessionId: string, callId: string, reason: string): Promise<void>;
     /**
      * 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.
      */
-    serve(sessionId: string, handlers: Record<string, ClientToolHandler>, options?: {
-        signal?: AbortSignal;
-        intervalMs?: number;
-    }): Promise<void>;
+    serve(sessionId: string, handlers: Record<string, ClientToolHandler>, options?: ServeOptions): Promise<void>;
+    /** Answers each new call once and shows each new confirmation once. */
+    private handleItems;
+    /** serve for daemons that predate waiting (see noteOlderDaemon). */
+    private servePolling;
     /**
      * 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`.
      */
-    converse(sessionId: string, message: string, handlers: Record<string, ClientToolHandler>, options?: {
-        timeoutMs?: number;
-        pollIntervalMs?: number;
-    }): Promise<ConverseResult>;
+    converse(sessionId: string, message: string, handlers: Record<string, ClientToolHandler>, options?: TurnOptions): Promise<ConverseResult>;
+    /**
+     * 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.
+     */
+    private followTurn;
+    /** followTurn for daemons that predate waiting (see noteOlderDaemon). */
+    private followTurnPolling;
     private resolve;
 }