js/ai/acp/schema
js/ai/acp/schema.ts
internal:ai/acp/schema — stable ACP v1 wire constants and data shapes.
These declarations mirror the schema pinned by fino:ai/acp and contain no
transport, persistence, or connection lifecycle policy.
Useful reference:
- Stable ACP v1 schema: https://github.com/agentclientprotocol/agent-client-protocol/blob/ae596e13351e1196b8b83b73f19beca51355732e/schema/v1/schema.json
Constants
const ACP_PROTOCOL_VERSION
ACP major protocol version implemented by this module.
const ACP_AUTH_REQUIRED
ACP authentication-required error code.
const ACP_RESOURCE_NOT_FOUND
ACP resource-not-found error code.
Types
type AcpMeta = Record<string, unknown> | null
Extension metadata reserved by ACP.
type AcpContentBlock =
| AcpTextContent
| AcpImageContent
| AcpAudioContent
| AcpEmbeddedResource
| AcpResourceLink
Every stable ACP v1 content block.
type AcpPromptContent = AcpContentBlock
Content accepted by session/prompt.
type AcpMcpServer = AcpMcpServerStdio | AcpMcpServerHttp | AcpMcpServerSse
Every stable ACP v1 MCP server descriptor.
type AcpAuthMethod = AcpAuthMethodAgent | AcpAuthMethodTerminal
ACP authentication method.
type AcpSessionConfigOption = AcpSessionConfigSelect | AcpSessionConfigBoolean
Every stable ACP v1 session configuration option.
type AcpToolKind =
| 'read'
| 'edit'
| 'delete'
| 'move'
| 'search'
| 'execute'
| 'think'
| 'fetch'
| 'switch_mode'
| 'other'
ACP tool display category.
type AcpToolCallContent =
| { type: 'content'; content: AcpContentBlock; _meta?: AcpMeta }
| { type: 'diff'; path: string; oldText?: string | null; newText: string; _meta?: AcpMeta }
| { type: 'terminal'; terminalId: string; _meta?: AcpMeta }
Content displayed beneath an ACP tool call.
type AcpSessionUpdate =
| {
sessionUpdate: 'user_message_chunk' | 'agent_message_chunk' | 'agent_thought_chunk';
content: AcpContentBlock;
messageId?: string | null;
_meta?: AcpMeta;
}
| {
sessionUpdate: 'tool_call';
toolCallId: string;
title: string;
kind?: AcpToolKind | null;
status?: 'pending' | 'in_progress' | 'completed' | 'failed' | null;
content?: AcpToolCallContent[] | null;
locations?: AcpToolCallLocation[] | null;
rawInput?: unknown;
rawOutput?: unknown;
_meta?: AcpMeta;
}
| {
sessionUpdate: 'tool_call_update';
toolCallId: string;
title?: string | null;
kind?: AcpToolKind | null;
status?: 'pending' | 'in_progress' | 'completed' | 'failed' | null;
content?: AcpToolCallContent[] | null;
locations?: AcpToolCallLocation[] | null;
rawInput?: unknown;
rawOutput?: unknown;
_meta?: AcpMeta;
}
| { sessionUpdate: 'plan'; entries: AcpPlanEntry[]; _meta?: AcpMeta }
| {
sessionUpdate: 'available_commands_update';
availableCommands: AcpAvailableCommand[];
_meta?: AcpMeta;
}
| { sessionUpdate: 'current_mode_update'; currentModeId: string; _meta?: AcpMeta }
| {
sessionUpdate: 'config_option_update';
configOptions: AcpSessionConfigOption[];
_meta?: AcpMeta;
}
| {
sessionUpdate: 'session_info_update';
title?: string | null;
updatedAt?: string | null;
_meta?: AcpMeta;
}
| {
sessionUpdate: 'usage_update';
used: number;
size: number;
cost?: { amount: number; currency: string; _meta?: AcpMeta } | null;
_meta?: AcpMeta;
}
Every stable ACP v1 session-update shape.
type AcpElicitationRequest =
| {
mode: 'form';
message: string;
requestedSchema: Record<string, unknown>;
sessionId?: string;
toolCallId?: string | null;
requestId?: number | string | null;
_meta?: AcpMeta;
}
| {
mode: 'url';
message: string;
elicitationId: string;
url: string;
sessionId?: string;
toolCallId?: string | null;
requestId?: number | string | null;
_meta?: AcpMeta;
}
| AcpCustomElicitationRequest
ACP form, URL, or implementation-specific elicitation request.
type AcpElicitationResponse =
| { action: 'accept'; content?: Record<string, unknown> | null; _meta?: AcpMeta }
| { action: 'decline' | 'cancel'; _meta?: AcpMeta }
| ({ action: string; _meta?: AcpMeta } & Record<string, unknown>)
ACP elicitation result.
Interfaces
interface AcpAnnotations {
ACP content display annotations.
Properties
audience?: Array<'assistant' | 'user'>
Intended content audiences.
priority?: number
Relative display priority.
lastModified?: string
ISO 8601 last-modified timestamp.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpTextContent {
ACP text content.
Properties
type: 'text'
Content discriminant.
text: string
Markdown-compatible text.
annotations?: AcpAnnotations | null
Optional display annotations.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpImageContent {
ACP image content with base64 bytes.
Properties
type: 'image'
Content discriminant.
data: string
Base64-encoded image bytes.
mimeType: string
Image MIME type.
uri?: string | null
Optional source URI.
annotations?: AcpAnnotations | null
Optional display annotations.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpAudioContent {
ACP audio content with base64 bytes.
Properties
type: 'audio'
Content discriminant.
data: string
Base64-encoded audio bytes.
mimeType: string
Audio MIME type.
annotations?: AcpAnnotations | null
Optional display annotations.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpTextResource {
Text resource embedded directly in content.
Properties
uri: string
Resource URI.
text: string
Embedded text.
mimeType?: string | null
Optional text MIME type.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpBlobResource {
Binary resource embedded directly in content.
Properties
uri: string
Resource URI.
blob: string
Base64-encoded resource bytes.
mimeType?: string | null
Optional binary MIME type.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpEmbeddedResource {
ACP embedded-resource content.
Properties
type: 'resource'
Content discriminant.
resource: AcpTextResource | AcpBlobResource
Embedded text or binary resource.
annotations?: AcpAnnotations | null
Optional display annotations.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpResourceLink {
ACP resource-link content.
Properties
type: 'resource_link'
Content discriminant.
name: string
Resource name.
uri: string
Resource URI.
title?: string | null
Optional display title.
description?: string | null
Optional resource description.
mimeType?: string | null
Optional resource MIME type.
size?: number | null
Optional resource size in bytes.
annotations?: AcpAnnotations | null
Optional display annotations.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpEnvVariable {
ACP name/value environment entry.
Properties
name: string
Environment variable name.
value: string
Environment variable value.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpHttpHeader {
ACP name/value HTTP header.
Properties
name: string
Header name.
value: string
Header value.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpMcpServerStdio {
ACP stdio MCP descriptor.
Properties
name: string
Human-readable server name.
command: string
Absolute executable path.
args: string[]
Process arguments.
env: AcpEnvVariable[]
Process environment overrides.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpMcpServerHttp {
ACP Streamable HTTP MCP descriptor.
Properties
type: 'http'
Transport discriminant.
name: string
Human-readable server name.
url: string
Streamable HTTP endpoint.
headers: AcpHttpHeader[]
Request headers.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpMcpServerSse {
ACP legacy HTTP+SSE MCP descriptor.
Properties
type: 'sse'
Transport discriminant.
name: string
Human-readable server name.
url: string
Legacy SSE endpoint.
headers: AcpHttpHeader[]
Request headers.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpClientCapabilities {
Client capabilities negotiated during initialization.
Properties
fs?: { readTextFile?: boolean; writeTextFile?: boolean; _meta?: AcpMeta }
Client-hosted filesystem operations.
terminal?: boolean
Whether client-hosted terminals are available.
auth?: { terminal?: boolean; _meta?: AcpMeta }
Client authentication capabilities.
elicitation?: {
form?: Record<string, unknown> | null;
url?: Record<string, unknown> | null;
_meta?: AcpMeta;
} | null
Structured user-input capabilities.
session?: {
configOptions?: { boolean?: Record<string, unknown> | null; _meta?: AcpMeta } | null;
_meta?: AcpMeta;
} | null
Session-level client capabilities.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpImplementation {
Implementation identity exchanged during initialization.
Properties
name: string
Machine-readable implementation name.
title?: string | null
Optional display title.
version: string
Implementation version.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpAuthMethodAgent {
Agent-managed authentication method.
Properties
id: string
Authentication method id.
name: string
Display name.
type?: 'agent'
Agent-managed method discriminant.
description?: string | null
Optional instructions.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpAuthMethodTerminal {
Client-launched interactive authentication method.
Properties
id: string
Authentication method id.
name: string
Display name.
type: 'terminal'
Client-launched method discriminant.
description?: string | null
Optional instructions.
args?: string[]
Arguments appended to the configured agent command.
env?: Record<string, string>
Environment overrides for the authentication process.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpSessionMode {
One stable ACP legacy session mode.
Properties
id: string
Mode id.
name: string
Display name.
description?: string | null
Optional mode description.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpSessionModeState {
Current and available session modes.
Properties
currentModeId: string
Selected mode id.
availableModes: AcpSessionMode[]
Modes available in the session.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpSessionConfigSelectOption {
One select configuration value.
Properties
value: string
Wire value id.
name: string
Display name.
description?: string | null
Optional value description.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpSessionConfigSelectGroup {
Grouped select configuration values.
Properties
group: string
Group id.
name: string
Display name.
options: AcpSessionConfigSelectOption[]
Values in this group.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpSessionConfigSelect {
ACP select session configuration.
Properties
type: 'select'
Configuration type discriminant.
id: string
Configuration id.
name: string
Display name.
description?: string | null
Optional configuration description.
category?: 'mode' | 'model' | 'thought_level' | string | null
Standard or custom UI category.
currentValue: string
Selected value id.
options: Array<AcpSessionConfigSelectOption | AcpSessionConfigSelectGroup>
Available values and groups.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpSessionConfigBoolean {
ACP boolean session configuration.
Properties
type: 'boolean'
Configuration type discriminant.
id: string
Configuration id.
name: string
Display name.
description?: string | null
Optional configuration description.
category?: 'mode' | 'model' | 'thought_level' | string | null
Standard or custom UI category.
currentValue: boolean
Current boolean value.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpAvailableCommand {
Slash-command descriptor.
Properties
name: string
Slash-command name without a leading slash.
description: string
Command description.
input?: { hint: string; _meta?: AcpMeta } | null
Optional input hint.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpPlanEntry {
ACP execution-plan entry.
Properties
content: string
Plan step text.
priority: 'high' | 'medium' | 'low'
Relative step priority.
status: 'pending' | 'in_progress' | 'completed'
Current step state.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpToolCallLocation {
File location affected by an ACP tool call.
Properties
path: string
Absolute file path.
line?: number | null
Optional zero-based line number.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpCreateTerminalOptions {
Terminal creation options excluding the bound session id.
Properties
command: string
Command to execute.
args?: string[]
Command arguments.
env?: AcpEnvVariable[]
Environment overrides.
cwd?: string | null
Absolute working directory.
outputByteLimit?: number | null
Maximum retained output bytes.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpTerminalOutput {
Terminal output and optional exit status.
Properties
output: string
Captured terminal output.
truncated: boolean
Whether leading output was truncated.
exitStatus?: { exitCode?: number | null; signal?: string | null; _meta?: AcpMeta } | null
Process status when it has exited.
_meta?: AcpMeta
Opaque extension metadata.
interface AcpCustomElicitationRequest extends Record<string, unknown> {
Implementation-specific elicitation request.
Properties
mode: `_${string}`
Underscore-prefixed extension mode.
message: string
Human-readable request.
sessionId?: string
Session scope, when applicable.
toolCallId?: string | null
Tool-call scope, when applicable.
requestId?: number | string | null
Non-session request scope, when applicable.
_meta?: AcpMeta
Opaque extension metadata.