agenthost

type Agent interface {
	// Connect spawns or attaches to the agent and returns a live Handle
	// wired to harness. harness is supplied by the caller: a production
	// harness assembling real permission/fs/terminal handling, a minimal
	// test harness, or libacp.UnimplementedClient{} as a no-op, can all be
	// passed here unchanged — Connect never builds one itself.
	Connect(ctx context.Context, harness libacp.Client) (*Handle, error)
}

type ExternalACPAgent struct {
	Config runtimetypes.ExternalACPConfig

	// Stderr, if set, receives the spawned subprocess's stderr as it is
	// written (see acpexec.WithStderr). Defaults to io.Discard.
	Stderr io.Writer

	// KillGrace, if positive, overrides how long teardown waits for the
	// spawned agent to exit after its stdin is closed before killing it
	// (see acpexec.WithKillGrace; default 5s). Persistent agents — testy,
	// most editor adapters — never exit on stdin-close, so a short grace
	// here is what keeps their teardown from stalling for the full default.
	KillGrace time.Duration
}

type Handle struct {
	// Conn is the live ACP client-side connection to the agent. Callers
	// issue ACP calls against it directly: Initialize, NewSession, Prompt,
	// and so on (see libacp/clientconn.go for the full outbound surface).
	Conn *libacp.ClientSideConnection
	// contains filtered or unexported fields
}

type McpServerResolver interface {
	GetByName(ctx context.Context, name string) (*runtimetypes.MCPServer, error)
}

type RecordingHarness struct {
	libacp.UnimplementedClient
	// contains filtered or unexported fields
}

type TurnRequest struct {
	// Cwd is the session working directory. Required: ACP's session/new
	// requires one, and spec-correct agents expect it to be absolute.
	Cwd string

	// Prompt is the user prompt for the driven turn. Required.
	Prompt []libacp.ContentBlock

	// ClientInfo identifies this host to the agent. Defaults to a
	// "contenox-agenthost" identity when nil. The ACP spec requires both
	// name and version, and real-world agents (the claude-code-acp adapter)
	// hard-reject an initialize without a version — so DriveTurn fills an
	// empty Version with the runtime's own before sending.
	ClientInfo *libacp.Implementation

	// ClientCapabilities advertises what the supplied harness can actually
	// serve. The zero value (nothing advertised) is the honest match for
	// RecordingHarness.
	ClientCapabilities libacp.ClientCapabilities

	// McpServers are MCP servers passed down to the agent in session/new —
	// typically the resolved form of the agent's mcp_servers allowlist (see
	// ResolveForwardedMcpServers). DriveTurn filters them against the
	// agent's initialize-advertised mcpCapabilities before sending; what was
	// kept and dropped is reported on TurnResult.
	McpServers []libacp.McpServer

	// Stderr, if set, receives the spawned agent's stderr as it is written —
	// pass a buffer so a failing turn is diagnosable without rerunning.
	Stderr io.Writer

	// KillGrace, if positive, bounds how long teardown waits for the agent
	// to exit on stdin-close before killing it (see
	// ExternalACPAgent.KillGrace). Set it short for persistent agents that
	// never exit on their own.
	KillGrace time.Duration
}

type TurnResult struct {
	Initialize libacp.InitializeResponse
	SessionID  libacp.SessionID
	StopReason libacp.StopReason

	// ForwardedMcpServers and DroppedMcpServers name which of
	// TurnRequest.McpServers actually reached the agent in session/new and
	// which were withheld because the agent's mcpCapabilities can't consume
	// their transport. Callers surface these so a user who allowlisted a
	// server learns when the agent never saw it.
	ForwardedMcpServers []string
	DroppedMcpServers   []string
}