Support asynchronous commands for custom ACP providers

[bwestlund17]

Summary

• let custom ACP providers opt into Paseo's existing initial-command wait through durable provider params
• preserve ACP command input hints in Paseo autocomplete entries
• document the configuration for agents that publish available_commands_update after session/new

Problem

Generic ACP draft sessions call listCommands() immediately after session/new. Providers such as zcode-acp-server publish commands asynchronously, so the new-agent composer can cache an empty list. The same timing class already has provider-specific handling for Cursor, Trae, and Kiro.

Verification

• npx vitest run packages/server/src/server/agent/providers/generic-acp-agent.test.ts --bail=1
• targeted ACP command translation test
• npm run build:server
• npm run typecheck
• targeted lint and formatting
• isolated Paseo 0.4 daemon with real ZCode ACP: GLM-5.3 draft query returned 78 commands, including argument hints

Configuration

"params": {
  "waitForInitialCommands": true,
  "initialCommandsWaitTimeoutMs": 1500
}

[greptile-apps]

Greptile Summary

The PR lets custom ACP providers opt into bounded initial-command waiting and preserves ACP command argument hints in autocomplete results.

• Adds validated durable provider parameters for enabling the wait and configuring its timeout.
• Maps ACP command input hints into Paseo slash-command metadata.
• Documents asynchronous command discovery and adds focused translation and option-forwarding tests.

Confidence Score: 4/5

The PR appears safe to merge, with only a non-blocking test-design issue that leaves the new configuration path insufficiently verified at its caller-facing interface.

The production changes reuse the existing bounded command-readiness lifecycle and preserve a typed string hint, while the added generic-provider test checks constructor plumbing rather than proving the resulting session behavior.

Files Needing Attention: packages/server/src/server/agent/providers/generic-acp-agent.test.ts

Important Files Changed

Filename	Overview
packages/server/src/server/agent/providers/generic-acp-agent.ts	Adds validated provider parameters and applies explicit client-option precedence when forwarding initial-command wait settings.
packages/server/src/server/agent/providers/acp-agent.ts	Preserves optional ACP command input hints when translating command updates into autocomplete entries.
packages/server/src/server/agent/providers/generic-acp-agent.test.ts	Covers option forwarding but asserts mocked superclass internals instead of observable command-listing behavior.
packages/server/src/server/agent/providers/acp-agent.test.ts	Extends asynchronous command-update coverage to verify that input hints are preserved.
docs/custom-providers.md	Documents how custom ACP providers opt into bounded waiting for asynchronously published commands.

Sequence Diagram

sequenceDiagram
  participant Config as Provider config
  participant Client as GenericACPAgentClient
  participant Session as ACPAgentSession
  participant Provider as ACP provider
  participant Composer as New-agent composer
  Config->>Client: waitForInitialCommands + timeout
  Client->>Session: create session with wait options
  Session->>Provider: session/new
  Composer->>Session: listCommands()
  Session->>Session: wait for initial update or timeout
  Provider-->>Session: available_commands_update
  Session-->>Composer: commands with argument hints

Loading

_{Reviews (1): Last reviewed commit: "Let custom ACP providers publish command..." | Re-trigger Greptile}

[greptile-apps]

Test asserts constructor internals

This test only inspects captured ACPAgentClient constructor options instead of creating a session and observing listCommands(), coupling coverage to implementation details without verifying that provider parameters produce the caller-facing asynchronous-command behavior.

Rule Used: # Code Review Pattern Reference: Slop, Tests, Feat... (source)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!