@openacp/cli 2026.410.1 → 2026.410.3

package/dist/{channel-CKXNnTy4.d.ts → channel-CFMUPzvH.d.ts}

@@ -1,34 +1,66 @@
+/**
+ * Controls how much detail is shown in agent output.
+ * - `"low"` — minimal: hides thoughts, usage, noisy tool calls
+ * - `"medium"` — balanced: shows tool summaries, hides noise
+ * - `"high"` — full: shows everything including tool output and thoughts
+ */
 type OutputMode = "low" | "medium" | "high";
 /** @deprecated Use OutputMode instead */
 type DisplayVerbosity = OutputMode;
+/** Maps tool call status strings to emoji icons for display. */
 declare const STATUS_ICONS: Record<string, string>;
+/** Maps tool kind strings to emoji icons for display. */
 declare const KIND_ICONS: Record<string, string>;
+/** Links to the web viewer for file contents or diffs. */
 interface ViewerLinks {
     file?: string;
     diff?: string;
 }
+/**
+ * Metadata extracted from a tool_call agent event.
+ * Carried on OutgoingMessage.metadata for rendering by adapters.
+ */
 interface ToolCallMeta {
     id: string;
     name: string;
+    /** Semantic kind (read, edit, execute, search, etc.) used for icon/label selection. */
     kind?: string;
     status?: string;
     content?: unknown;
     rawInput?: unknown;
     viewerLinks?: ViewerLinks;
     viewerFilePath?: string;
+    /** Agent-provided summary override (takes precedence over auto-generated summary). */
     displaySummary?: string;
+    /** Agent-provided title override (takes precedence over auto-generated title). */
     displayTitle?: string;
+    /** Agent-provided kind override (takes precedence over inferred kind). */
     displayKind?: string;
 }
+/** Metadata for a tool_update event — same as ToolCallMeta but status is required. */
 interface ToolUpdateMeta extends ToolCallMeta {
     status: string;
 }
 
+/**
+ * Immutable context for a single user-prompt → agent-response cycle ("turn").
+ *
+ * Sealed when a prompt is dequeued from the PromptQueue and cleared after the turn
+ * completes. Bridges use this to route agent events to the correct adapter when
+ * multiple adapters are attached to the same session.
+ */
 interface TurnContext {
+    /** Unique identifier for this turn — shared between message:queued and message:processing events. */
     turnId: string;
+    /** The adapter that originated this prompt. */
     sourceAdapterId: string;
+    /** Where to send the response: null = silent (suppress), undefined = same as source, string = explicit target. */
     responseAdapterId?: string | null;
 }
+/**
+ * Routing hints attached to an incoming prompt — carried through the queue
+ * and used to construct TurnContext when the prompt is dequeued.
+ */
 interface TurnRouting {
     sourceAdapterId: string;
     responseAdapterId?: string | null;
@@ -47,6 +79,13 @@ declare function createTurnContext(sourceAdapterId: string, responseAdapterId?:
 declare function getEffectiveTarget(ctx: TurnContext): string | null;
 declare function isSystemEvent(event: AgentEvent): boolean;
 
+/**
+ * A file attachment sent to or received from an agent.
+ *
+ * Agents receive attachments as content blocks in their prompt input.
+ * `originalFilePath` preserves the user's original path before any
+ * conversion (e.g., audio transcoding or image resizing).
+ */
 interface Attachment {
     type: 'image' | 'audio' | 'file';
     filePath: string;
@@ -55,6 +94,13 @@ interface Attachment {
     size: number;
     originalFilePath?: string;
 }
+/**
+ * A message arriving from a channel adapter (Telegram, Slack, SSE, etc.)
+ * destined for a session's agent.
+ *
+ * `routing` controls how the message is dispatched when multiple adapters
+ * are attached to the same session (e.g., which adapter should receive the response).
+ */
 interface IncomingMessage {
     channelId: string;
     threadId: string;
@@ -63,41 +109,82 @@ interface IncomingMessage {
     attachments?: Attachment[];
     routing?: TurnRouting;
 }
+/**
+ * A message flowing from the agent back to channel adapters for display.
+ *
+ * The `type` field determines how the adapter renders the message:
+ * - text/thought/plan/error — rendered as formatted text blocks
+ * - tool_call/tool_update — rendered as collapsible tool activity
+ * - usage — token/cost summary (typically shown in a status bar)
+ * - attachment — binary content (image, audio, file)
+ * - session_end — signals the agent turn is complete
+ * - ACP Phase 2 types (mode_change, config_update, etc.) — interactive controls
+ */
 interface OutgoingMessage {
     type: "text" | "thought" | "tool_call" | "tool_update" | "plan" | "usage" | "session_end" | "error" | "attachment" | "system_message" | "mode_change" | "config_update" | "model_update" | "user_replay" | "resource" | "resource_link";
     text: string;
     metadata?: Record<string, unknown>;
     attachment?: Attachment;
 }
+/**
+ * A permission request sent by the agent when it needs user approval.
+ *
+ * The agent blocks until the user picks one of the `options`.
+ * PermissionGate holds the request, emits it to adapters via SessionEv,
+ * and resumes the agent with the chosen option when resolved.
+ */
 interface PermissionRequest {
     id: string;
     description: string;
     options: PermissionOption[];
 }
+/** A single choice within a permission request (e.g., "Allow once", "Deny"). */
 interface PermissionOption {
     id: string;
     label: string;
+    /** Whether this option grants the requested permission. */
     isAllow: boolean;
 }
+/**
+ * A notification pushed to the user outside of the normal message flow.
+ *
+ * Used for background alerts when the user isn't actively watching the session
+ * (e.g., agent completed, permission needed, budget warning).
+ */
 interface NotificationMessage {
     sessionId: string;
     sessionName?: string;
     type: "completed" | "error" | "permission" | "input_required" | "budget_warning";
     summary: string;
+    /** URL to jump directly to the session in the adapter UI. */
     deepLink?: string;
 }
+/** A command exposed by the agent, surfaced as interactive buttons in the chat UI. */
 interface AgentCommand {
     name: string;
     description: string;
     input?: unknown;
 }
-type AgentEvent = {
+/**
+ * Union of all events that an AgentInstance can emit during a prompt turn.
+ *
+ * Each variant maps to an ACP protocol event. AgentInstance translates raw
+ * ACP SDK events into these normalized types, which then flow through
+ * middleware (Hook.AGENT_BEFORE_EVENT) and into SessionBridge for rendering.
+ */
+type AgentEvent = 
+/** Streamed text content from the agent's response. */
+{
     type: "text";
     content: string;
-} | {
+}
+/** Agent's internal reasoning (displayed in a collapsible block). */
+ | {
     type: "thought";
     content: string;
-} | {
+}
+/** Agent started or completed a tool invocation. */
+ | {
     type: "tool_call";
     id: string;
     name: string;
@@ -108,7 +195,9 @@ type AgentEvent = {
     rawInput?: unknown;
     rawOutput?: unknown;
     meta?: unknown;
-} | {
+}
+/** Progress update for an in-flight tool call (partial output, status change). */
+ | {
     type: "tool_update";
     id: string;
     name?: string;
@@ -119,10 +208,14 @@ type AgentEvent = {
     rawInput?: unknown;
     rawOutput?: unknown;
     meta?: unknown;
-} | {
+}
+/** Agent's execution plan with prioritized steps. */
+ | {
     type: "plan";
     entries: PlanEntry[];
-} | {
+}
+/** Token usage and cost report for the current turn. */
+ | {
     type: "usage";
     tokensUsed?: number;
     contextSize?: number;
@@ -130,45 +223,67 @@ type AgentEvent = {
         amount: number;
         currency: string;
     };
-} | {
+}
+/** Agent updated its available slash commands. */
+ | {
     type: "commands_update";
     commands: AgentCommand[];
-} | {
+}
+/** Agent produced an image as output (base64-encoded). */
+ | {
     type: "image_content";
     data: string;
     mimeType: string;
-} | {
+}
+/** Agent produced audio as output (base64-encoded). */
+ | {
     type: "audio_content";
     data: string;
     mimeType: string;
-} | {
+}
+/** Agent ended the session (no more prompts accepted). */
+ | {
     type: "session_end";
     reason: string;
-} | {
+}
+/** Agent-level error (non-fatal — session may continue). */
+ | {
     type: "error";
     message: string;
-} | {
+}
+/** System message injected by OpenACP (not from the agent itself). */
+ | {
     type: "system_message";
     message: string;
-} | {
+}
+/** Agent updated session metadata (title, timestamps). */
+ | {
     type: "session_info_update";
     title?: string;
     updatedAt?: string;
     _meta?: Record<string, unknown>;
-} | {
+}
+/** Agent updated its config options (modes, models, toggles). */
+ | {
     type: "config_option_update";
     options: ConfigOption[];
-} | {
+}
+/** Echoed user message chunk — used for cross-adapter input visibility. */
+ | {
     type: "user_message_chunk";
     content: string;
-} | {
+}
+/** Agent returned a resource's content (file, data). */
+ | {
     type: "resource_content";
     uri: string;
     name: string;
     text?: string;
     blob?: string;
     mimeType?: string;
-} | {
+}
+/** Agent returned a link to a resource (without inline content). */
+ | {
     type: "resource_link";
     uri: string;
     name: string;
@@ -176,14 +291,21 @@ type AgentEvent = {
     title?: string;
     description?: string;
     size?: number;
-} | {
+}
+/** Signals that TTS output should be stripped from the response. */
+ | {
     type: "tts_strip";
 };
+/** A single step in an agent's execution plan. */
 interface PlanEntry {
     content: string;
     status: "pending" | "in_progress" | "completed";
     priority: "high" | "medium" | "low";
 }
+/**
+ * Static definition of an agent — the command, args, and environment
+ * needed to spawn its subprocess.
+ */
 interface AgentDefinition {
     name: string;
     command: string;
@@ -191,7 +313,9 @@ interface AgentDefinition {
     workingDirectory?: string;
     env?: Record<string, string>;
 }
+/** How the agent is distributed and installed. */
 type AgentDistribution = "npx" | "uvx" | "binary" | "custom";
+/** An agent that has been installed locally and is ready to spawn. */
 interface InstalledAgent {
     registryId: string | null;
     name: string;
@@ -202,14 +326,17 @@ interface InstalledAgent {
     env: Record<string, string>;
     workingDirectory?: string;
     installedAt: string;
+    /** Absolute path to the binary on disk (only for "binary" distribution). */
     binaryPath: string | null;
 }
+/** Platform-specific binary download target from the agent registry. */
 interface RegistryBinaryTarget {
     archive: string;
     cmd: string;
     args?: string[];
     env?: Record<string, string>;
 }
+/** Distribution methods available for a registry agent. */
 interface RegistryDistribution {
     npx?: {
         package: string;
@@ -221,8 +348,10 @@ interface RegistryDistribution {
         args?: string[];
         env?: Record<string, string>;
     };
+    /** Platform → arch → binary target mapping. */
     binary?: Record<string, RegistryBinaryTarget>;
 }
+/** An agent entry from the remote agent registry. */
 interface RegistryAgent {
     id: string;
     name: string;
@@ -235,6 +364,7 @@ interface RegistryAgent {
     icon?: string;
     distribution: RegistryDistribution;
 }
+/** Merged view of a registry agent with local install status. */
 interface AgentListItem {
     key: string;
     registryId: string;
@@ -244,8 +374,10 @@ interface AgentListItem {
     distribution: AgentDistribution;
     installed: boolean;
     available: boolean;
+    /** Runtime dependencies that are missing on this machine. */
     missingDeps?: string[];
 }
+/** Result of checking whether an agent can run on this machine. */
 interface AvailabilityResult {
     available: boolean;
     reason?: string;
@@ -254,6 +386,7 @@ interface AvailabilityResult {
         installHint: string;
     }>;
 }
+/** Callbacks for reporting agent installation progress to the UI. */
 interface InstallProgress {
     onStart(agentId: string, agentName: string): void | Promise<void>;
     onStep(step: string): void | Promise<void>;
@@ -261,6 +394,7 @@ interface InstallProgress {
     onSuccess(agentName: string): void | Promise<void>;
     onError(error: string, hint?: string): void | Promise<void>;
 }
+/** Result of an agent install operation. */
 interface InstallResult {
     ok: boolean;
     agentKey: string;
@@ -268,13 +402,30 @@ interface InstallResult {
     hint?: string;
     setupSteps?: string[];
 }
+/**
+ * Session lifecycle status.
+ *
+ * Valid transitions:
+ *   initializing → active | error
+ *   active       → error | finished | cancelled
+ *   error        → active | cancelled  (recovery or user cancels)
+ *   cancelled    → active              (user resumes)
+ *   finished     → (terminal — no transitions)
+ */
 type SessionStatus = "initializing" | "active" | "cancelled" | "finished" | "error";
+/** Record of an agent switch within a session (for history tracking). */
 interface AgentSwitchEntry {
     agentName: string;
     agentSessionId: string;
     switchedAt: string;
     promptCount: number;
 }
+/**
+ * Persisted session state — serialized to the session store (JSON file).
+ *
+ * Generic parameter `P` is the primary adapter's platform-specific data
+ * (e.g., TelegramPlatformData). Additional adapters store data in `platforms`.
+ */
 interface SessionRecord<P = Record<string, unknown>> {
     sessionId: string;
     agentSessionId: string;
@@ -309,11 +460,13 @@ interface SessionRecord<P = Record<string, unknown>> {
         availableModels?: ModelInfo[];
     };
 }
+/** Telegram-specific data stored per session in the session record. */
 interface TelegramPlatformData {
     topicId: number;
     skillMsgId?: number;
     controlMsgId?: number;
 }
+/** A single token usage data point for cost tracking. */
 interface UsageRecord {
     id: string;
     sessionId: string;
@@ -326,6 +479,7 @@ interface UsageRecord {
     };
     timestamp: string;
 }
+/** Usage event emitted on the EventBus for the usage-tracking plugin. */
 interface UsageRecordEvent {
     sessionId: string;
     agentName: string;
@@ -337,25 +491,36 @@ interface UsageRecordEvent {
         currency: string;
     };
 }
+/** An agent operating mode (e.g., "code", "architect", "ask"). */
 interface SessionMode {
     id: string;
     name: string;
     description?: string;
 }
+/** Current mode and all available modes for a session. */
 interface SessionModeState {
     currentModeId: string;
     availableModes: SessionMode[];
 }
+/** A single choice within a select-type config option. */
 interface ConfigSelectChoice {
     value: string;
     name: string;
     description?: string;
 }
+/** A named group of select choices (for categorized dropdowns). */
 interface ConfigSelectGroup {
     group: string;
     name: string;
     options: ConfigSelectChoice[];
 }
+/**
+ * Agent-exposed configuration options surfaced as interactive controls in chat.
+ *
+ * These are settings the agent advertises via the ACP config_option_update event.
+ * Adapters render them as select menus, toggles, etc. in the chat UI.
+ * When the user changes a value, OpenACP sends a setConfigOption request to the agent.
+ */
 type ConfigOption = {
     id: string;
     name: string;
@@ -374,6 +539,7 @@ type ConfigOption = {
     currentValue: boolean;
     _meta?: Record<string, unknown>;
 };
+/** Value payload for updating a config option on the agent. */
 type SetConfigOptionValue = {
     type: "select";
     value: string;
@@ -381,19 +547,28 @@ type SetConfigOptionValue = {
     type: "boolean";
     value: boolean;
 };
+/** An AI model available for the agent to use. */
 interface ModelInfo {
     id: string;
     name: string;
     description?: string;
 }
+/** Current model and all available models for a session. */
 interface SessionModelState {
     currentModelId: string;
     availableModels: ModelInfo[];
 }
+/**
+ * Capabilities advertised by the agent in its initialize response.
+ *
+ * These determine which ACP features the agent supports — OpenACP uses
+ * them to enable/disable UI features (e.g., session list, fork, MCP).
+ */
 interface AgentCapabilities {
     name: string;
     title?: string;
     version?: string;
+    /** Whether the agent supports loading (resuming) existing sessions. */
     loadSession?: boolean;
     promptCapabilities?: {
         image?: boolean;
@@ -411,12 +586,14 @@ interface AgentCapabilities {
     };
     authMethods?: AuthMethod[];
 }
+/** Response from the agent when creating a new session. */
 interface NewSessionResponse {
     sessionId: string;
     modes?: SessionModeState;
     configOptions?: ConfigOption[];
     models?: SessionModelState;
 }
+/** Authentication method supported by the agent. */
 type AuthMethod = {
     type: "agent";
 } | {
@@ -426,14 +603,26 @@ type AuthMethod = {
 } | {
     type: "terminal";
 };
+/** Request to authenticate with a specific method. */
 interface AuthenticateRequest {
     methodId: string;
 }
+/**
+ * Reason why the agent stopped generating.
+ *
+ * - end_turn: agent completed its response normally
+ * - max_tokens / max_turn_requests: hit a limit
+ * - refusal: agent declined the request
+ * - cancelled / interrupted: user or system stopped the prompt
+ * - error: agent encountered an error
+ */
 type StopReason = "end_turn" | "max_tokens" | "max_turn_requests" | "refusal" | "cancelled" | "error" | "interrupted";
+/** Final response from the agent after a prompt completes. */
 interface PromptResponse {
     stopReason: StopReason;
     _meta?: Record<string, unknown>;
 }
+/** A content block within a prompt message sent to the agent. */
 type ContentBlock = {
     type: "text";
     text: string;
@@ -463,6 +652,7 @@ type ContentBlock = {
     description?: string;
     size?: number;
 };
+/** A session entry returned by the agent's session list endpoint. */
 interface SessionListItem {
     sessionId: string;
     title?: string;
@@ -470,10 +660,12 @@ interface SessionListItem {
     updatedAt?: string;
     _meta?: Record<string, unknown>;
 }
+/** Paginated response from the agent's session list endpoint. */
 interface SessionListResponse {
     sessions: SessionListItem[];
     nextCursor?: string;
 }
+/** Configuration for connecting to an MCP (Model Context Protocol) server. */
 type McpServerConfig = {
     type?: "stdio";
     name: string;
@@ -492,10 +684,18 @@ type McpServerConfig = {
     headers?: Record<string, string>;
 };
 
+/**
+ * Configuration for an adapter channel (Telegram, Slack, etc.).
+ * Each adapter defines its own fields beyond `enabled`.
+ */
 interface ChannelConfig {
     enabled: boolean;
     [key: string]: unknown;
 }
+/**
+ * Declares what a messaging platform supports. Core uses these to decide
+ * whether to attempt features like streaming, file uploads, or voice.
+ */
 interface AdapterCapabilities {
     streaming: boolean;
     richFormatting: boolean;
@@ -504,6 +704,17 @@ interface AdapterCapabilities {
     fileUpload: boolean;
     voice: boolean;
 }
+/**
+ * Contract for a messaging platform adapter.
+ *
+ * A "channel" in OpenACP is identified by an adapter name (e.g. "telegram", "slack").
+ * Each session binds to a channel + thread ID — together they form a unique conversation
+ * location. The adapter is responsible for platform-specific I/O: sending messages,
+ * creating threads/topics, handling permission buttons, etc.
+ *
+ * Core calls adapter methods via SessionBridge (for agent events) or directly
+ * (for session lifecycle operations like thread creation and archiving).
+ */
 interface IChannelAdapter {
     readonly name: string;
     readonly capabilities: AdapterCapabilities;
@@ -512,6 +723,7 @@ interface IChannelAdapter {
     sendMessage(sessionId: string, content: OutgoingMessage): Promise<void>;
     sendPermissionRequest(sessionId: string, request: PermissionRequest): Promise<void>;
     sendNotification(notification: NotificationMessage): Promise<void>;
+    /** Create a thread/topic for a session. Returns the platform-specific thread ID. */
     createSessionThread(sessionId: string, name: string): Promise<string>;
     renameSessionThread(sessionId: string, newName: string): Promise<void>;
     deleteSessionThread?(sessionId: string): Promise<void>;
@@ -519,13 +731,19 @@ interface IChannelAdapter {
     stripTTSBlock?(sessionId: string): Promise<void>;
     sendSkillCommands?(sessionId: string, commands: AgentCommand[]): Promise<void>;
     cleanupSkillCommands?(sessionId: string): Promise<void>;
-    /** Flush skill commands that were queued before threadId was available */
+    /** Flush skill commands that were queued before threadId was available. */
     flushPendingSkillCommands?(sessionId: string): Promise<void>;
     cleanupSessionState?(sessionId: string): Promise<void>;
 }
 /**
- * Base class providing default no-op implementations for optional methods.
- * Adapters can extend this or implement IChannelAdapter directly.
+ * Original base class for channel adapters. Provides default no-op implementations
+ * for optional IChannelAdapter methods so subclasses only need to implement the
+ * methods they care about.
+ *
+ * This class predates the adapter-primitives package. It has since been superseded
+ * by MessagingAdapter and StreamAdapter, which add structured send queuing, streaming
+ * support, and platform-specific rendering out of the box.
+ *
  * @deprecated Use MessagingAdapter or StreamAdapter instead. Kept for backward compat during migration.
  */
 declare abstract class ChannelAdapter<TCore = unknown> implements IChannelAdapter {

package/dist/cli.d.ts

@@ -1,11 +1,32 @@
 #!/usr/bin/env node
+/**
+ * Global instance-targeting flags accepted by every CLI command.
+ *
+ * These are extracted from argv before Commander parses the command,
+ * so they are available uniformly without each subcommand declaring them.
+ */
 interface InstanceFlags {
+    /** Use the instance in the current working directory (`.openacp/` in CWD). */
     local: boolean;
+    /** Explicit path to the workspace directory (parent of `.openacp/`). */
     dir?: string;
+    /** Clone a new instance from this source path. */
     from?: string;
+    /** Human-readable label for the instance. */
     name?: string;
 }
+/**
+ * Returns the instance root resolved during CLI startup.
+ *
+ * Available to subcommands that need the resolved path without re-resolving it.
+ * May be null if the command does not require an instance (e.g., `update`, `adopt`).
+ */
 declare function getResolvedInstanceRoot(): string | null;
+/**
+ * Returns the global instance-targeting flags parsed from argv.
+ *
+ * Useful for subcommands that need to inspect raw flags (e.g., to read `--name`).
+ */
 declare function getInstanceFlags(): InstanceFlags;
 
 export { type InstanceFlags, getInstanceFlags, getResolvedInstanceRoot };