/** * Agent-instance roster helpers (Issue #1000). * * Shared by the `instances` command (add/remove/alias/kill/list) and the * `send --instance ... --register` option. All roster mutations go through * PATCH /api/worktrees/[id] (`agentInstances`), the same endpoint the * AgentInstancesPane UI uses, so CLI-created instances show up in the UI and * vice versa. * * Uses a RELATIVE path (not `@/`) to import server-side constants: CLI builds * via tsconfig.cli.json set `"paths": {}`. Mirrors the existing pattern in * ../config/cli-tool-ids.ts. */ import { type ApiClient } from './api-client'; import type { AgentInstance } from '../types/api-responses'; import { MAX_AGENT_INSTANCES, MAX_AGENT_ALIAS_LENGTH } from '../../lib/cli-tools/types'; import { MIN_AGENT_INSTANCES } from '../../lib/agent-instances-validator'; export { MAX_AGENT_INSTANCES, MAX_AGENT_ALIAS_LENGTH, MIN_AGENT_INSTANCES }; /** * Fetch the current agent-instance roster for a worktree. */ export declare function fetchAgentInstances(client: ApiClient, worktreeId: string): Promise; /** A roster, and the revision it was read at. An older server gives none. */ export interface AgentRosterSnapshot { instances: AgentInstance[]; revision?: string; } /** * Fetch the roster with its revision, for a write that replaces it (Issue #4132). */ export declare function fetchAgentRoster(client: ApiClient, worktreeId: string): Promise; /** * Persist a full roster replacement. `order` is re-normalized to array * position, matching AgentInstancesPane's persist() behavior. * * @param expectedRosterRevision - When given, the server refuses a roster that has moved * on (Issue #4132). Omitted, whatever is there is replaced. */ export declare function saveAgentInstances(client: ApiClient, worktreeId: string, instances: AgentInstance[], expectedRosterRevision?: string): Promise; /** * Save a change to the roster, as long as it is the roster the change was built on * (Issue #4132). The write replaces the whole list, so an add made elsewhere since the * read would be erased. A server that has moved on answers 409, and `build` runs again * on what is really there, so it decides again as well (an id is taken, a row has gone). * * @param first - The roster already read, which the first attempt builds on * @param build - The next roster, or null when there is nothing left to do * @returns What was saved, or null when `build` said there was nothing to do * @throws {RoleCliError} `roster_changed` (exit 31): the roster kept moving through every * attempt, so nothing was saved to it (Issue #4149). What the command did before the save * stands: `remove --kill` has stopped the session. `send --register` has sent the message, * and turns this, like any other failure here (Issue #4159), into a warning for that reason. * @throws {ApiError} The server refused for another reason */ export declare function saveRosterChange(client: ApiClient, worktreeId: string, first: AgentRosterSnapshot, build: (base: AgentInstance[]) => AgentInstance[] | null): Promise; /** Why the server would refuse a row added to the roster (Issue #4458). */ export interface RosterAdditionRefusal { /** The roster has no room left: it already holds MAX_AGENT_INSTANCES. */ atLimit: boolean; /** The server's own sentence for it (`validateAgentInstancesInput`). */ error: string; } /** * Whether the roster write would refuse `added` appended to `base`, asked of the server's * own validator rather than a copy of its rules (Issue #4458): the limit, the room left * under it, the id pattern and length, the primary anchor and the alias length of `added`. * * Every add path asks this (send --register with and without --role, instances add with * and without --role, first build and rebuild after ROSTER_CHANGED), and `added` is judged * whatever the rows of `base` look like (J1). A bad row of `base` is not this add's to * judge: the save goes ahead and the server answers it (#4149). * * @returns null when nothing about `added` or the room for it would be refused */ export declare function rosterAdditionRefusal(base: ReadonlyArray, added: Pick): RosterAdditionRefusal | null; /** * Generate a unique instance id for `cliTool`. Mirrors * AgentInstancesPane.tsx's nextInstanceId(): claims the primary id * (`id === cliTool`) when free, otherwise the smallest free `{cliTool}-{n}` * suffix (n >= 2). */ export declare function nextInstanceId(cliTool: string, existing: ReadonlyArray<{ id: string; }>): string; /** * Default alias for a freshly-added instance (tool display name, suffixed * for non-primary instances). Mirrors AgentInstancesPane.tsx's defaultAlias(). * * @param cliTool - Caller must have already validated this via isCliToolId(). */ export declare function defaultAlias(cliTool: string, id: string): string; //# sourceMappingURL=agent-instances.d.ts.map