mockhost

package
v0.1.2 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package mockhost is the scripted ACP client of the testkit (SPEC §5.9). It drives a provider or a router plugin either in-process (plugin.Run / plugin.RunRouter over pipes) or as a started binary, mirrors the protocol methods, collects session/update notifications, auto-answers permission requests, and runs scenario files.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Driver

type Driver struct {
	// contains filtered or unexported fields
}

Driver drives one plugin binary without a testing.TB: every failure is returned as an error, and scenarios return structured results. It is the surface the conformance CLI uses.

func StartDriver

func StartDriver(binaryPath string, opts ...StartOption) (*Driver, error)

StartDriver launches a plugin binary and returns a Driver that drives it.

func (Driver) Action

func (c Driver) Action(id string) (protocol.ActionResult, error)

Action runs one _arvel/action.

func (Driver) Call

func (c Driver) Call(ctx context.Context, method string, params, result any) error

Call performs a JSON-RPC call with the given context. The context is the caller's deadline; it is not extended with the host's default timeout.

func (Driver) Cancel

func (c Driver) Cancel(id string) error

Cancel sends session/cancel for a session.

func (Driver) Close

func (c Driver) Close()

Close tears the connection down. It is idempotent and safe to call from t.Cleanup or defer.

func (Driver) Initialize

func (c Driver) Initialize(meta protocol.InitMeta) (protocol.InitResultMeta, error)

Initialize sends initialize and returns the decoded _meta.arvel, using the host's default timeout.

func (Driver) InitializeCtx

func (c Driver) InitializeCtx(ctx context.Context, meta protocol.InitMeta) (protocol.InitResultMeta, error)

InitializeCtx sends initialize under the caller's context (deadline).

func (Driver) LoadSession

func (c Driver) LoadSession(id string, meta protocol.SessionMeta) error

LoadSession resumes a session.

func (Driver) Models

func (c Driver) Models(refresh bool) (protocol.ModelsResult, error)

Models answers _arvel/models.

func (Driver) NewSession

func (c Driver) NewSession(meta protocol.SessionMeta) (string, error)

NewSession creates a session and returns its id.

func (Driver) PermissionsSeen

func (c Driver) PermissionsSeen() int

PermissionsSeen reports how many permission requests arrived on the host.

func (Driver) Prompt

func (c Driver) Prompt(id string, blocks []acp.ContentBlock) (PromptResult, error)

Prompt runs one turn and returns its stop reason and turn metadata.

func (Driver) RouteEffort

func (c Driver) RouteEffort(p protocol.RouteEffortParams) (protocol.RouteEffortResult, error)

RouteEffort calls _arvel/route/effort.

func (Driver) RouteExplain

func (c Driver) RouteExplain(p protocol.RoutePlanParams) (protocol.RouteExplainResult, error)

RouteExplain calls _arvel/route/explain.

func (Driver) RouteMessage

func (c Driver) RouteMessage(p protocol.RouteMessageParams) (protocol.RouteMessageResult, error)

RouteMessage calls _arvel/route/message.

func (Driver) RoutePlan

func (c Driver) RoutePlan(p protocol.RoutePlanParams) (protocol.RoutePlanResult, error)

RoutePlan calls _arvel/route/plan.

func (Driver) RunErr

func (c Driver) RunErr() error

RunErr returns the error plugin.Run / plugin.RunRouter returned, if any.

func (*Driver) RunScenario

func (d *Driver) RunScenario(sc *scenario.Scenario, opts ScenarioOptions) (ScenarioResult, error)

RunScenario runs one scenario against the driver and returns a structured result. The plugin process must already be started (see StartDriver).

func (Driver) SetConfigOption

func (c Driver) SetConfigOption(id, configID, value string) error

SetConfigOption changes a session config option.

func (*Driver) Shutdown

func (d *Driver) Shutdown() error

Shutdown sends _arvel/shutdown, closes the plugin's stdin and waits for the plugin to exit, returning an error on failure or timeout.

func (*Driver) ShutdownExit

func (d *Driver) ShutdownExit(timeout time.Duration) (int, error)

ShutdownExit sends _arvel/shutdown and waits up to timeout for the plugin to exit, returning its exit code. A non-zero exit is not an error; the caller interprets the code.

func (Driver) Status

func (c Driver) Status() (protocol.Status, error)

Status answers _arvel/status.

func (Driver) Stderr

func (c Driver) Stderr() string

Stderr returns the captured stderr text of the plugin process.

func (Driver) Stdout

func (c Driver) Stdout() string

Stdout returns the raw protocol output read from the plugin, including unknown fields and notifications that typed decoding would discard.

func (Driver) Updates

func (c Driver) Updates(id string) []map[string]any

Updates returns the session/update objects collected for a session, in arrival order. Each map is the decoded ACP SessionUpdate ("update" field).

func (Driver) Usage

func (c Driver) Usage() (protocol.Usage, error)

Usage answers _arvel/usage.

type Host

type Host struct {
	// contains filtered or unexported fields
}

Host drives one plugin through the testing.TB surface: a provider or a router, in-process or as a binary. The protocol logic lives on the embedded core; Host only adds t.Fatalf / t.Cleanup behavior.

func InProcess

func InProcess(t testing.TB, p plugin.Provider, opts ...plugin.Option) *Host

InProcess starts a provider in-process and returns a Host that drives it.

func InProcessRouter

func InProcessRouter(t testing.TB, r plugin.Router, opts ...plugin.Option) *Host

InProcessRouter starts a router in-process and returns a Host that drives it.

func Start

func Start(t testing.TB, binaryPath string, opts ...StartOption) *Host

Start launches a plugin binary and returns a Host that drives it. It works for both provider and router binaries, which share the same stdio transport.

func (Host) Action

func (c Host) Action(id string) (protocol.ActionResult, error)

Action runs one _arvel/action.

func (Host) Call

func (c Host) Call(ctx context.Context, method string, params, result any) error

Call performs a JSON-RPC call with the given context. The context is the caller's deadline; it is not extended with the host's default timeout.

func (Host) Cancel

func (c Host) Cancel(id string) error

Cancel sends session/cancel for a session.

func (Host) Close

func (c Host) Close()

Close tears the connection down. It is idempotent and safe to call from t.Cleanup or defer.

func (Host) Initialize

func (c Host) Initialize(meta protocol.InitMeta) (protocol.InitResultMeta, error)

Initialize sends initialize and returns the decoded _meta.arvel, using the host's default timeout.

func (Host) InitializeCtx

func (c Host) InitializeCtx(ctx context.Context, meta protocol.InitMeta) (protocol.InitResultMeta, error)

InitializeCtx sends initialize under the caller's context (deadline).

func (Host) LoadSession

func (c Host) LoadSession(id string, meta protocol.SessionMeta) error

LoadSession resumes a session.

func (Host) Models

func (c Host) Models(refresh bool) (protocol.ModelsResult, error)

Models answers _arvel/models.

func (Host) NewSession

func (c Host) NewSession(meta protocol.SessionMeta) (string, error)

NewSession creates a session and returns its id.

func (Host) PermissionsSeen

func (c Host) PermissionsSeen() int

PermissionsSeen reports how many permission requests arrived on the host.

func (Host) Prompt

func (c Host) Prompt(id string, blocks []acp.ContentBlock) (PromptResult, error)

Prompt runs one turn and returns its stop reason and turn metadata.

func (Host) RouteEffort

func (c Host) RouteEffort(p protocol.RouteEffortParams) (protocol.RouteEffortResult, error)

RouteEffort calls _arvel/route/effort.

func (Host) RouteExplain

func (c Host) RouteExplain(p protocol.RoutePlanParams) (protocol.RouteExplainResult, error)

RouteExplain calls _arvel/route/explain.

func (Host) RouteMessage

func (c Host) RouteMessage(p protocol.RouteMessageParams) (protocol.RouteMessageResult, error)

RouteMessage calls _arvel/route/message.

func (Host) RoutePlan

func (c Host) RoutePlan(p protocol.RoutePlanParams) (protocol.RoutePlanResult, error)

RoutePlan calls _arvel/route/plan.

func (Host) RunErr

func (c Host) RunErr() error

RunErr returns the error plugin.Run / plugin.RunRouter returned, if any.

func (*Host) RunScenario

func (h *Host) RunScenario(t testing.TB, file string)

RunScenario loads a scenario file, initializes the host from its connection and runs every step, failing the test on the first mismatch.

func (Host) SetConfigOption

func (c Host) SetConfigOption(id, configID, value string) error

SetConfigOption changes a session config option.

func (*Host) Shutdown

func (h *Host) Shutdown()

Shutdown sends _arvel/shutdown and waits for the plugin to exit, failing the test on error or timeout.

func (Host) Status

func (c Host) Status() (protocol.Status, error)

Status answers _arvel/status.

func (Host) Stderr

func (c Host) Stderr() string

Stderr returns the captured stderr text of the plugin process.

func (Host) Stdout

func (c Host) Stdout() string

Stdout returns the raw protocol output read from the plugin, including unknown fields and notifications that typed decoding would discard.

func (Host) Updates

func (c Host) Updates(id string) []map[string]any

Updates returns the session/update objects collected for a session, in arrival order. Each map is the decoded ACP SessionUpdate ("update" field).

func (Host) Usage

func (c Host) Usage() (protocol.Usage, error)

Usage answers _arvel/usage.

type PromptResult

type PromptResult struct {
	StopReason acp.StopReason
	Meta       protocol.TurnMeta
}

PromptResult is the outcome of a session/prompt call.

type ScenarioOptions

type ScenarioOptions struct {
	// Tmpdir is the value of the {{tmpdir}} placeholder.
	Tmpdir string
	// FakevendorDir is the directory holding fakevendor scripts, resolved as
	// <dir>/<name>.yaml for the {{fakevendor:name}} placeholder.
	FakevendorDir string
	// Sandbox, when non-nil, is injected into initialize._meta.arvel.sandbox
	// (PROTOCOL §15). The proxy check uses it to send a sandbox.proxy.
	Sandbox *protocol.SandboxInfo
}

ScenarioOptions customize how a scenario is run against a Driver.

type ScenarioResult

type ScenarioResult struct {
	Name  string       `json:"name"`
	Pass  bool         `json:"pass"`
	Steps []StepResult `json:"steps"`
	// Updates holds every session/update notification collected during the run,
	// keyed by session id. It lets the conformance CLI inspect what the plugin
	// streamed back (for example a fake vendor's reported environment).
	Updates map[string][]map[string]any `json:"updates,omitempty"`
}

ScenarioResult is the outcome of one scenario run.

func (ScenarioResult) Summary

func (r ScenarioResult) Summary() (passed, failed int)

Summary returns the number of passing and failing steps.

type StartOption

type StartOption func(*startOptions)

StartOption configures Start.

func WithArgs

func WithArgs(args ...string) StartOption

WithArgs sets the arguments passed to the plugin binary.

func WithDir

func WithDir(dir string) StartOption

WithDir sets the working directory of the plugin process.

func WithEnv

func WithEnv(env []string) StartOption

WithEnv sets the environment of the plugin process. A nil env means the default minimal environment (see procx.Start).

type StepResult

type StepResult struct {
	Call string `json:"call"`
	Pass bool   `json:"pass"`
	Err  string `json:"error,omitempty"`
}

StepResult is the outcome of one scenario step.

Jump to

Keyboard shortcuts

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