acp-probe weekly downloads statistics

acp-probe

Probe any Agent Client Protocol agent for its capabilities — models, modes, configOptions, prompt capabilities, auth methods, MCP transports — without sending a real prompt.

[!NOTE] Stable. As of 1.0.0 the public API is stable and ready for production use. Breaking changes follow semantic versioning and land only in major releases.

What it does

Given an ACP-compatible agent (built-in like claude or codex, or any custom adapter you can spawn), acp-probe performs the ACP initialize + session/new handshake, then optionally pings session/set_config_option to test whether the agent implements that method. Agents that do not implement it respond with the standard JSON-RPC "method not found" error, which the probe catches to flip supportsConfigOption: false in the result. Finally the agent is torn down. The result is a typed, schema-stable AgentProbeResult you can feed into a settings UI, picker, or downstream AcpRuntimeOptions call.

No LLM tokens are consumed. session/new is free; we never call session/prompt.

Install

bun add acp-probe
# or
npm install acp-probe

The only hard dependency is @agentclientprotocol/sdk. acpx is an optional peer — installed, it lets you use the built-in { agent: 'claude' } shorthand; absent, you pass { command } or { argv } yourself.

Quickstart

import { probeAgent } from 'acp-probe'

// Custom ACP command — the canonical entry point. Zero acpx
// involvement; works with any agent you can spawn.
const result = await probeAgent({
  command: 'my-acp-agent --stdio',
})

console.log(result.models)         // ProbedModel[]
console.log(result.modes)          // ProbedMode[]
console.log(result.configOptions)  // ProbedConfigOption[]
console.log(result.reasoning)      // { configId, values, defaultValue } | null
console.log(result.capabilities.promptCapabilities)
//        => { image: boolean, audio: boolean, embeddedContext: boolean }

// Built-in shorthand — requires acpx to be installed.
const claude = await probeAgent({ agent: 'claude' })

Result shape

interface AgentProbeResult {
  agent: {
    id: string | null
    command: string
    argv: readonly string[]
    probedAt: string  // ISO timestamp
    durationMs: number
  }
  protocolVersion: number
  agentInfo: { name; title?; version? } | null
  capabilities: {
    loadSession: boolean
    promptCapabilities: { image; audio; embeddedContext }
    mcpCapabilities: { http; sse; meta? }
    sessionCapabilities: { close; list; resume; fork; additionalDirectories }
    experimental?: { auth; nes; providers; positionEncoding }
  }
  authMethods: AuthMethod[]
  /**
   * Declarative `session/new.models.availableModels[]`. Best for display
   * — **may contain ids that `setConfigOption('model', X)` will not
   * accept**. See "Picking the right model list" below.
   */
  models: Array<{ id; name?; description? }>
  modes: Array<{ id; name?; description? }>
  configOptions: ProbedConfigOption[]
  /** Derived pointer to the configOption with category='thought_level'. */
  reasoning: { configId; values; defaultValue? } | null
  /**
   * Derived pointer to `configOptions[id=model]`. `values` are the ids
   * that `setConfigOption('model', X)` will accept. `null` when the
   * agent doesn't expose a settable model picker.
   */
  modelConfig: { configId; values; currentValue? } | null
  /**
   * True iff the agent implements `session/set_config_option`. False
   * when the agent responds with JSON-RPC "method not found" to a
   * no-op set call, which is how an adapter without configOptions
   * support signals the method is unimplemented.
   */
  supportsConfigOption: boolean
  error?: ProbeError
  /** Verbatim init + session/new responses for callers that need _meta. */
  raw: { initialize; newSession }
}

Picking the right model list

The probe surfaces two model-related lists from ACP because the two protocol surfaces don't always agree:

• result.models — the agent's declarative availableModels[] from session/new. Best for display / browsing / showing the user "what this agent can do". May contain ids the agent will not accept as setConfigOption('model', X) inputs — codex-acp, for example, advertises compound <model>/<effort> ids here that setConfigOption rejects (silently — the next prompt finishes with finishReason: "error" and no error frame).
• result.modelConfig.values — the string ids that the agent's configOptions[id=model] select will accept. null for agents that don't expose configOptions[model] at all, which is also where setConfigOption itself returns -32601 method not found.
• result.configOptions.find(o => o.id === 'model') — the full typed picker option (names, descriptions, currentValue) for the settable values. Use this when you want to render a rich picker UI on top of the settable list.

Display-only browser

import { probeAgent } from 'acp-probe'

const result = await probeAgent({ command: 'npx @zed-industries/codex-acp@^0.12.0' })

for (const m of result.models) {
  console.log(`${m.id}${m.name ? ` — ${m.name}` : ''}`)
}

Mutable picker that drives setConfigOption

import { probeAgent } from 'acp-probe'

const result = await probeAgent({ command: 'npx @zed-industries/codex-acp@^0.12.0' })

if (!result.modelConfig) {
  console.log('This agent does not expose a model picker — skip the UI.')
} else {
  const { values, currentValue } = result.modelConfig
  for (const id of values) {
    console.log(id === currentValue ? `* ${id}` : `  ${id}`)
  }
}

Rich mutable picker (values + names + descriptions)

import { probeAgent } from 'acp-probe'…