acpmock

package
v0.5.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 22 Imported by: 0

README

ACP mock fixtures

Fixtures use version 2, named agents, and prompt-matched turns containing ordered steps. Use typed match.turn_source and match.user_text to select a turn. The mock driver runs as an ACP agent subprocess; see testdata/ for complete fixtures.

Preparing the driver

The Go CI shards build cmd/acpmock-driver once per job before running scenarios, with a separate five-minute setup budget. COMPOZY_TEST_ACPMOCK_DRIVER_BIN points every package and integration step in that job at the same executable. This keeps cold compilation out of scenario setup without changing any assertion or test deadline. The local fallback still builds lazily with its existing bounded context and shares the result across concurrent callers in each package process; its owning test clears the CI override so that fallback remains exercised.

Calling hosted native tools

native_tool_call executes a real native tool from the agent process through the compozy-hosted-tools stdio MCP server injected in ACP session/new or session/load. It uses MCP tools/call; no operator API invocation or synthetic tool response is involved.

{
  "kind": "native_tool_call",
  "tool_id": "compozy__subagent_delegate",
  "tool_call_id": "delegate-child",
  "raw_input": {
    "task": "child work",
    "title": "Fixture delegation",
    "target": { "agent": "subagent-worker" }
  }
}
  • tool_id must identify a compozy__ native tool. tool_call_id is required and is forwarded as MCP _meta.toolCallId and used by both ACP session updates.
  • raw_input is a required JSON object; use {} for a tool without arguments.
  • The ACP tool_call starts in progress, followed by tool_call_update with the real result as rawOutput (structured content when available, otherwise MCP content). MCP text content is also included. The default title is tool_id; title can override it.
  • Successful calls finish as completed; MCP error results finish as failed. Transport failures emit a failed update and fail the prompt. Prompt cancellation cancels the pending MCP request.
  • status, raw_output, and content_text cannot script a native result. Use the existing tool_call step when a scenario intentionally needs synthetic ACP events.
  • Agents with this step connect their hosted MCP server at session initialization and reuse that connection across calls and turns. This preserves the single-use bind nonce. The connection closes on session close or driver shutdown. Fixtures without native calls continue to leave the injected server untouched. Sessions the daemon starts without that server, such as Goal judges, still start; only a native step executed there fails.

testdata/native_tool_delegate_fixture.json supplies subagent-delegator and subagent-worker. Register both under those agent names, prompt the parent with delegate child work, and inspect its transcript for delegate-child. The parent discovers capabilities, delegates asynchronously, and ends its turn; the worker answers and the parent accepts the synthetic completion wake. This fixture can be used by browser E2E.

Subagent steering fixtures may set agent steer_outcome to injected, failed, or pending_injection. Pending injection returns acceptance without an ACP completion channel. A driver_control step with action: "wait_for_steer" waits on the steering request, then continues the scripted turn to its normal completion. Use block_until_cancel when the integration test must hold the pending window open across another child settlement. Native-tool steps may set omit_tool_call_id: true to omit provider _meta.toolCallId while retaining the transcript tool ID; this exercises the hosted request-ID fallback.

A fail_prompt driver control may set when_path_missing to a path relative to the driver's working directory. The step then fails the prompt only while that path is absent and otherwise lets the turn continue. testdata/provider_error_fixture.json agent signin-agent uses .provider-credential this way to stand in for a provider sign-in that a lab removes and restores (RT-provider-auth-recovery).

Documentation

Index

Constants

View Source
const (
	ProviderName   = "acpmock"
	ProviderClaude = "claude"
)

Provider identities supported by provider-aware fixture scenarios.

View Source
const FixtureVersion = 2

Variables

This section is empty.

Functions

func BuildCommand

func BuildCommand(
	driverPath string,
	fixturePath string,
	fixtureAgent string,
	diagnosticsPath string,
	effectiveProvider ...string,
) string

BuildCommand renders the test-only ACP driver command string stored in AGENT.md.

func DefaultDriverPath

func DefaultDriverPath() (string, error)

DefaultDriverPath resolves or builds the test-only ACP mock driver binary.

func ProviderConfig

func ProviderConfig(command ...string) compozyconfig.ProviderConfig

ProviderConfig returns the local auth-free provider config for ACP mock agents.

func ProviderConfigForIdentity

func ProviderConfigForIdentity(provider string, command ...string) (compozyconfig.ProviderConfig, error)

ProviderConfigForIdentity returns an ACP mock config under one typed native provider identity.

func RequireDriver

func RequireDriver(t testing.TB) string

RequireDriver resolves the ACP mock driver binary or fails the current test.

Types

type AgentFixture

type AgentFixture struct {
	// SteerOutcome advertises the steering extension and returns this scripted outcome.
	SteerOutcome    string   `json:"steer_outcome,omitempty"`
	Name            string   `json:"name"`
	Provider        string   `json:"provider"`
	Model           string   `json:"model,omitempty"`
	ReasoningEffort string   `json:"reasoning_effort,omitempty"`
	Permissions     string   `json:"permissions,omitempty"`
	Tools           []string `json:"tools,omitempty"`
	Prompt          string   `json:"prompt,omitempty"`
	LoadSession     *bool    `json:"load_session,omitzero"`
	// ForkSession advertises the unstable ACP session/fork capability; the driver answers
	// session/fork with a clone id after sending clone-id updates first (OpenCode shape).
	ForkSession bool `json:"fork_session,omitzero"`
	// ForkError makes session/fork fail with this message.
	ForkError string `json:"fork_error,omitempty"`
	// LoadMissing makes session/load fail with ACP resource-not-found for any id.
	LoadMissing bool `json:"load_missing,omitzero"`
	// LoadDelayMS holds session/load open to script a provider that resumes slowly.
	LoadDelayMS   int                          `json:"load_delay_ms,omitzero"`
	ConfigOptions []SessionConfigOptionFixture `json:"config_options,omitempty"`
	Turns         []TurnFixture                `json:"turns"`
}

AgentFixture describes one named ACP mock agent inside a fixture file.

func (AgentFixture) RejectsConfigValue

func (a AgentFixture) RejectsConfigValue(configID string, value string) bool

RejectsConfigValue reports whether the fixture scripts a set_config_option failure.

func (AgentFixture) SelectTurn

func (a AgentFixture) SelectTurn(prompt string, meta ...acp.PromptMeta) (TurnFixture, error)

SelectTurn returns the first turn that matches stable prompt fields.

func (AgentFixture) SupportsLoadSession

func (a AgentFixture) SupportsLoadSession() bool

SupportsLoadSession reports the fixture's advertised ACP session/load capability.

func (AgentFixture) Validate

func (a AgentFixture) Validate(path string) error

Validate ensures the agent fixture is usable.

type DiagnosticsRecord

type DiagnosticsRecord struct {
	CompozySessionID  string             `json:"compozy_session_id,omitempty"`
	AgentName         string             `json:"agent_name"`
	Provider          string             `json:"provider,omitempty"`
	SessionID         string             `json:"session_id"`
	ProtocolMethod    string             `json:"protocol_method,omitempty"`
	ConfigOptionID    string             `json:"config_option_id,omitempty"`
	ConfigOptionValue string             `json:"config_option_value,omitempty"`
	LifecycleEvent    string             `json:"lifecycle_event,omitempty"`
	MCPServers        []acpsdk.McpServer `json:"mcp_servers,omitempty"`

	PromptIndex int               `json:"prompt_index"`
	Prompt      string            `json:"prompt"`
	PromptMeta  acp.PromptMeta    `json:"prompt_meta"`
	TurnName    string            `json:"turn_name,omitempty"`
	Match       TurnMatch         `json:"match"`
	Steps       []DiagnosticsStep `json:"steps"`
}

DiagnosticsRecord captures one protocol, lifecycle, or prompt event emitted by the ACP mock driver.

func DiagnosticsForCompozySession

func DiagnosticsForCompozySession(records []DiagnosticsRecord, compozySessionID string) []DiagnosticsRecord

DiagnosticsForCompozySession returns records owned by one daemon session in append order.

func DiagnosticsForProvider

func DiagnosticsForProvider(records []DiagnosticsRecord, provider string) []DiagnosticsRecord

DiagnosticsForProvider returns structured records for one canonical provider identity.

func PromptDiagnostics

func PromptDiagnostics(records []DiagnosticsRecord) []DiagnosticsRecord

PromptDiagnostics returns diagnostics emitted for prompt execution turns only.

func ProtocolDiagnostics

func ProtocolDiagnostics(records []DiagnosticsRecord) []DiagnosticsRecord

ProtocolDiagnostics returns diagnostics emitted when the driver receives ACP protocol methods.

func ReadDiagnostics

func ReadDiagnostics(path string) (records []DiagnosticsRecord, err error)

ReadDiagnostics decodes newline-delimited diagnostics written by the mock driver.

type DiagnosticsStep

type DiagnosticsStep struct {
	Kind         StepKind            `json:"kind"`
	Text         string              `json:"text,omitempty"`
	ToolCallID   string              `json:"tool_call_id,omitempty"`
	Decision     string              `json:"decision,omitempty"`
	Command      string              `json:"command,omitempty"`
	Args         []string            `json:"args,omitempty"`
	ExitCode     *int                `json:"exit_code,omitzero"`
	Output       string              `json:"output,omitempty"`
	Error        string              `json:"error,omitempty"`
	DriverAction DriverControlAction `json:"driver_action,omitempty"`
}

DiagnosticsStep captures one executed fixture step with any observed runtime outputs.

type DriverControlAction

type DriverControlAction string

DriverControlAction identifies one supported driver fault injection action.

const (
	DriverControlDisconnect       DriverControlAction = "disconnect"
	DriverControlWriteRawJSONRPC  DriverControlAction = "write_raw_jsonrpc"
	DriverControlBlockUntilCancel DriverControlAction = "block_until_cancel"
	DriverControlDelay            DriverControlAction = "delay"
	// DriverControlHoldIgnoringCancel keeps the turn open for delay_ms while ignoring
	// prompt cancellation, so stop ladders must escalate past the cooperative phase.
	DriverControlHoldIgnoringCancel DriverControlAction = "hold_ignoring_cancel"
	// DriverControlFailPrompt answers the matched session/prompt with a JSON-RPC error
	// carrying error_message, the shape a provider rate limit or auth lapse reaches the
	// daemon in after the session was accepted.
	DriverControlFailPrompt   DriverControlAction = "fail_prompt"
	DriverControlWaitForSteer DriverControlAction = "wait_for_steer"
)

type DriverControlStep

type DriverControlStep struct {
	Action     DriverControlAction `json:"action"`
	RawJSONRPC string              `json:"raw_jsonrpc,omitempty"`
	Async      bool                `json:"async,omitzero"`
	DelayMS    int                 `json:"delay_ms,omitzero"`
	// ErrorMessage is the JSON-RPC error message fail_prompt answers session/prompt with.
	ErrorMessage string `json:"error_message,omitempty"`
	// ErrorCode is the optional JSON-RPC error code for fail_prompt (default -32603).
	ErrorCode int `json:"error_code,omitzero"`
	// WhenPathMissing makes fail_prompt fire only while this path, relative to the driver's
	// working directory, is absent; otherwise the step passes and the turn continues. It lets a
	// lab remove and restore a stand-in provider credential.
	WhenPathMissing string `json:"when_path_missing,omitempty"`
}

DriverControlStep injects driver-level protocol or lifecycle faults.

func (DriverControlStep) Validate

func (d DriverControlStep) Validate(path string) error

Validate ensures the driver-control payload is internally consistent.

type Fixture

type Fixture struct {
	Version int            `json:"version"`
	Agents  []AgentFixture `json:"agents"`
}

Fixture describes one deterministic multi-agent ACP mock scenario.

func LoadFixture

func LoadFixture(path string) (Fixture, error)

LoadFixture parses and validates one fixture file.

func ParseFixture

func ParseFixture(data []byte) (Fixture, error)

ParseFixture decodes and validates fixture JSON.

func (Fixture) Agent

func (f Fixture) Agent(name string) (AgentFixture, error)

Agent returns one named fixture agent.

func (Fixture) Validate

func (f Fixture) Validate() error

Validate ensures the fixture can drive deterministic ACP scenarios.

type RegisterOptions

type RegisterOptions struct {
	FixturePath     string
	FixtureAgent    string
	AgentName       string
	ProviderName    string
	DriverPath      string
	DiagnosticsPath string
	Tools           []string
}

RegisterOptions describes one temporary fixture-backed AGENT.md registration.

type Registration

type Registration struct {
	AgentName       string
	FixtureAgent    string
	FixturePath     string
	DriverPath      string
	DiagnosticsPath string
	AgentDefPath    string
	Command         string
	Provider        string
	Model           string
	Permissions     string
}

Registration captures one temporary mock-agent definition written into Compozy home.

func Register

func Register(homePaths compozyconfig.HomePaths, opts RegisterOptions) (Registration, error)

Register writes one temporary fixture-backed AGENT.md file into the supplied Compozy home.

type SessionConfigOptionFixture

type SessionConfigOptionFixture struct {
	ID       string                            `json:"id"`
	Name     string                            `json:"name"`
	Category string                            `json:"category,omitempty"`
	Current  string                            `json:"current"`
	Values   []SessionConfigOptionValueFixture `json:"values"`
}

SessionConfigOptionFixture describes one deterministic ACP session config select option.

func (SessionConfigOptionFixture) Validate

func (o SessionConfigOptionFixture) Validate(path string) error

Validate ensures one session config option is deterministic and selectable.

type SessionConfigOptionValueFixture

type SessionConfigOptionValueFixture struct {
	Value string `json:"value"`
	Label string `json:"label,omitempty"`
	// RejectSet makes session/set_config_option to this advertised value fail, which
	// scripts a start that ACP accepted (session/new returned) and then failed.
	RejectSet bool `json:"reject_set,omitzero"`
}

SessionConfigOptionValueFixture describes one selectable ACP config option value.

type Step

type Step struct {
	OmitToolCallID bool     `json:"omit_tool_call_id,omitzero"`
	Kind           StepKind `json:"kind"`

	Text   string   `json:"text,omitempty"`
	Chunks []string `json:"chunks,omitempty"`
	// BurstCount repeats Text without delivery pacing to exercise transport pressure.
	BurstCount int `json:"burst_count,omitzero"`

	ToolID      string          `json:"tool_id,omitempty"`
	ToolCallID  string          `json:"tool_call_id,omitempty"`
	Title       string          `json:"title,omitempty"`
	ToolKind    string          `json:"tool_kind,omitempty"`
	Path        string          `json:"path,omitempty"`
	Status      string          `json:"status,omitempty"`
	ContentText string          `json:"content_text,omitempty"`
	RawInput    json.RawMessage `json:"raw_input,omitempty"`
	RawOutput   json.RawMessage `json:"raw_output,omitempty"`

	ExpectDecision string `json:"expect_decision,omitempty"`
	EmitDecision   bool   `json:"emit_decision,omitzero"`
	EmitText       string `json:"emit_text,omitempty"`

	Command              string             `json:"command,omitempty"`
	Args                 []string           `json:"args,omitempty"`
	Cwd                  string             `json:"cwd,omitempty"`
	ExpectExitCode       *int               `json:"expect_exit_code,omitzero"`
	ExpectOutputContains string             `json:"expect_output_contains,omitempty"`
	ExpectErrorContains  string             `json:"expect_error_contains,omitempty"`
	EmitOutput           bool               `json:"emit_output,omitzero"`
	DriverControl        *DriverControlStep `json:"driver_control,omitzero"`
}

Step describes one deterministic ACP action emitted or executed by the driver.

func (Step) Validate

func (s Step) Validate(path string) error

Validate ensures the step kind and payload are internally consistent.

type StepKind

type StepKind string
const (
	StepKindAssistant      StepKind = "assistant"
	StepKindThought        StepKind = "thought"
	StepKindToolCall       StepKind = "tool_call"
	StepKindNativeToolCall StepKind = "native_tool_call"
	StepKindPermission     StepKind = "permission"
	StepKindCommand        StepKind = "command_exec"
	StepKindDriverControl  StepKind = "driver_control"
)

type TurnFixture

type TurnFixture struct {
	UsageUpdates []UsageUpdate `json:"usage_updates,omitempty"`
	Name         string        `json:"name,omitempty"`
	Match        TurnMatch     `json:"match"`
	Steps        []Step        `json:"steps"`
	StopReason   string        `json:"stop_reason,omitempty"`
	Usage        *TurnUsage    `json:"usage,omitzero"`
}

TurnFixture describes one deterministic prompt turn for an agent.

func (TurnFixture) Validate

func (t TurnFixture) Validate(path string) error

Validate ensures the turn fixture is usable.

type TurnMatch

type TurnMatch struct {
	CompactionNotice *bool  `json:"compaction_notice,omitempty"`
	SituationFull    *bool  `json:"situation_full,omitempty"`
	TurnSource       string `json:"turn_source,omitempty"`
	UserText         string `json:"user_text,omitempty"`
	// UserTextContains matches a substring after the same canonical whitespace normalization as UserText.
	UserTextContains string `json:"user_text_contains,omitempty"`
	// RawUserTextContains matches a substring before prompt augmentation is stripped.
	RawUserTextContains string `json:"raw_user_text_contains,omitempty"`

	Goal  *TurnMatchGoal  `json:"goal,omitempty"`
	Judge *TurnMatchJudge `json:"judge,omitempty"`
}

TurnMatch routes a prompt to a turn fixture using stable prompt fields.

func (TurnMatch) Normalize

func (m TurnMatch) Normalize() TurnMatch

Normalize returns a trimmed copy of the turn matcher.

func (TurnMatch) Validate

func (m TurnMatch) Validate(path string) error

Validate ensures the turn match contains at least one supported stable selector.

type TurnMatchGoal

type TurnMatchGoal struct {
	Kind          string `json:"kind,omitempty"`
	RunID         string `json:"run_id,omitempty"`
	NodeID        string `json:"node_id,omitempty"`
	Generation    int64  `json:"generation,omitzero"`
	ItemIndex     *int   `json:"item_index,omitzero"`
	Turn          *int   `json:"turn,omitzero"`
	PromptAttempt *int   `json:"prompt_attempt,omitzero"`
	PromptID      string `json:"prompt_id,omitempty"`
}

TurnMatchGoal captures exact Goal prompt metadata fields.

func (TurnMatchGoal) IsZero

func (m TurnMatchGoal) IsZero() bool

IsZero reports whether the matcher selects no Goal fields.

func (TurnMatchGoal) Normalize

func (m TurnMatchGoal) Normalize() TurnMatchGoal

Normalize returns an isolated, trimmed Goal matcher.

func (TurnMatchGoal) Validate

func (m TurnMatchGoal) Validate(_ string) error

Validate ensures at least one exact Goal selector is present.

type TurnMatchJudge

type TurnMatchJudge struct {
	Role          string `json:"role,omitempty"`
	Attempt       int    `json:"attempt,omitzero"`
	CorrelationID string `json:"correlation_id,omitempty"`
	GateID        string `json:"gate_id,omitempty"`
	CriterionID   string `json:"criterion_id,omitempty"`
}

TurnMatchJudge captures exact daemon-owned judge prompt metadata fields.

func (TurnMatchJudge) IsZero

func (m TurnMatchJudge) IsZero() bool

IsZero reports whether the matcher selects no judge fields.

func (TurnMatchJudge) Normalize

func (m TurnMatchJudge) Normalize() TurnMatchJudge

Normalize returns a trimmed judge matcher.

func (TurnMatchJudge) Validate

func (m TurnMatchJudge) Validate(_ string) error

Validate ensures at least one exact judge selector is present.

type TurnUsage

type TurnUsage struct {
	CacheReadTokens  *int `json:"cache_read_tokens,omitzero"`
	CacheWriteTokens *int `json:"cache_write_tokens,omitzero"`
	InputTokens      int  `json:"input_tokens"`
	OutputTokens     int  `json:"output_tokens"`
	TotalTokens      *int `json:"total_tokens,omitzero"`
}

func (TurnUsage) Validate

func (u TurnUsage) Validate(path string) error

Validate rejects impossible aggregate token counts.

type UsageUpdate

type UsageUpdate struct {
	Used int            `json:"used"`
	Size int            `json:"size"`
	Meta map[string]any `json:"meta,omitempty"`
}

TurnUsage scripts deterministic aggregate token usage for one ACP prompt response.

Directories

Path Synopsis
cmd
acpmock-driver command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL