agentinstance

type Event struct {
	Kind       EventKind        `json:"kind"`
	InstanceID string           `json:"instanceId"`
	AgentID    string           `json:"agentId"`
	AgentName  string           `json:"agentName"`
	State      string           `json:"state,omitempty"`      // EventStateChange
	SessionID  libacp.SessionID `json:"sessionId,omitempty"`  // EventAttach / EventDetach / EventUnsupervisedDeny
	ViewerID   string           `json:"viewerId,omitempty"`   // EventAttach / EventDetach
	Controller bool             `json:"controller,omitempty"` // EventAttach
	Time       time.Time        `json:"time"`
}

type EventKind string

type EventSink func(Event)

type FleetEntry struct {
	AgentID   string           `json:"agentId"`
	AgentName string           `json:"agentName"`
	Kind      string           `json:"kind"`
	Instances []InstanceStatus `json:"instances"`
}

type InstanceStatus struct {
	ID        string `json:"id"`
	AgentID   string `json:"agentId"`
	AgentName string `json:"agentName"`
	Kind      string `json:"kind"`
	State     string `json:"state"`
	// Sessions is how many downstream sessions are open on the instance, always
	// len(SessionIDs).
	Sessions int `json:"sessions"`
	// Viewers is how many viewers are attached across those sessions, independent of
	// Sessions.
	Viewers   int       `json:"viewers"`
	StartedAt time.Time `json:"startedAt"`
	// SessionIDs lists every session currently open on the instance, sorted for a
	// deterministic snapshot; an unwatched or silent session is still listed.
	SessionIDs []string `json:"sessionIds"`
}

type Manager interface {
	// Start resolves agentName via the registry and brings up an instance bound to the
	// Manager's root context (cwd is the sandbox workspace); prefer StartResolved if
	// already resolved.
	Start(ctx context.Context, agentName, cwd string) (instanceID string, err error)

	// StartResolved spawns an instance from an already-resolved agent with no registry
	// read of its own; cwd is the sandbox workspace root, overridden by the agent's own
	// declared Cwd if set.
	StartResolved(ctx context.Context, agent *runtimetypes.Agent, cwd string) (instanceID string, err error)

	// Attach registers viewer against (instanceID, sessionID), replaying the journal
	// then joining the live fan-out; the first viewer of a session becomes its controller.
	Attach(ctx context.Context, instanceID string, sessionID libacp.SessionID, viewer Viewer) (controllerGranted bool, err error)

	// Detach removes viewerID from (instanceID, sessionID)'s fan-out,
	// promoting the earliest-attached survivor if it was the controller.
	Detach(instanceID string, sessionID libacp.SessionID, viewerID string) error

	// List returns every declared agent joined with its live instances
	// (empty = not running).
	List(ctx context.Context) ([]FleetEntry, error)

	// Get returns the status of one instance.
	Get(instanceID string) (InstanceStatus, error)

	// OpenSession drives the downstream ACP handshake on instanceID
	// (initialize once, then session/new) and returns the downstream
	// session id that Attach and the other session methods use.
	OpenSession(ctx context.Context, instanceID string, spec SessionSpec) (libacp.SessionID, error)

	// Prompt drives one downstream session/prompt turn and returns its stop reason; a
	// ctx cancellation or concurrent Cancel resolves as StopReasonCancelled with a nil
	// error.
	Prompt(ctx context.Context, instanceID string, sessionID libacp.SessionID, prompt []libacp.ContentBlock) (libacp.StopReason, error)

	// DeliverToSession injects n into sessionID's fan-out on whichever live instance
	// owns that session, as if it were a downstream update; ErrNotFound when no instance
	// owns it.
	DeliverToSession(ctx context.Context, sessionID libacp.SessionID, n libacp.SessionNotification) error

	// Cancel cancels sessionID's in-flight prompt turn. Safe with no turn in flight.
	Cancel(instanceID string, sessionID libacp.SessionID) error

	// CloseSession ends sessionID and drops its kernel state without stopping the
	// instance; only the consumer that called OpenSession should call this.
	CloseSession(instanceID string, sessionID libacp.SessionID) error

	// SetConfigOption forwards a config-option change downstream and adopts the
	// confirmed value; the synthetic mode/model ids map to session/set_mode and
	// session/set_model, every other id forwards to session/set_config_option.
	SetConfigOption(ctx context.Context, instanceID string, sessionID libacp.SessionID, configID string, value libacp.SessionConfigOptionValue) error

	// SessionConfigOptions returns sessionID's captured config-option
	// surface (synthetic mode + model selects, then the downstream's own),
	// or nil for an unknown session.
	SessionConfigOptions(instanceID string, sessionID libacp.SessionID) ([]libacp.SessionConfigOption, error)

	// AvailableCommands returns sessionID's captured slash-command menu, or nil for an unknown session.
	AvailableCommands(instanceID string, sessionID libacp.SessionID) ([]libacp.AvailableCommand, error)

	// Stop tears an instance down and removes it from the registry, preventing any
	// watchDog restart. Idempotent.
	Stop(instanceID string) error

	// Close stops every instance and cancels the Manager's root context, after which
	// Start returns an error. Idempotent.
	Close() error
}

type Option func(*manager)

type PermissionFallback func(ctx context.Context, req UnattendedPermission) (libacp.RequestPermissionResponse, error)

type SessionSpec struct {
	// Cwd is the downstream session's working directory; ACP requires one,
	// and spec-correct agents expect it absolute.
	Cwd string

	// AdditionalDirectories are extra absolute workspace roots beyond Cwd; omitted/empty
	// means none.
	AdditionalDirectories []string

	// McpServers are the already-resolved MCP servers to forward in session/new,
	// filtered to what the downstream's mcpCapabilities can consume; nil forwards none.
	McpServers []libacp.McpServer

	// Meta is an opaque session/new `_meta` blob forwarded verbatim, unread by the
	// kernel; nil forwards none.
	Meta json.RawMessage

	// Terminal, if set, advertises the terminal client capability to the downstream at
	// initialize; terminal/* is refused unless the session's controller implements
	// TerminalServer.
	Terminal bool
}

type TerminalServer interface {
	CreateTerminal(ctx context.Context, req libacp.CreateTerminalRequest) (libacp.CreateTerminalResponse, error)
	TerminalOutput(ctx context.Context, req libacp.TerminalOutputRequest) (libacp.TerminalOutputResponse, error)
	WaitForTerminalExit(ctx context.Context, req libacp.WaitForTerminalExitRequest) (libacp.WaitForTerminalExitResponse, error)
	KillTerminal(ctx context.Context, req libacp.KillTerminalRequest) (libacp.KillTerminalResponse, error)
	ReleaseTerminal(ctx context.Context, req libacp.ReleaseTerminalRequest) (libacp.ReleaseTerminalResponse, error)
}

type UnattendedPermission struct {
	InstanceID string
	AgentID    string
	AgentName  string
	// SessionID is the downstream session the request arrived on.
	SessionID libacp.SessionID
	Request   libacp.RequestPermissionRequest
}

type Viewer interface {
	// ID uniquely identifies this viewer within a session; two viewers on the
	// same session must not share an ID.
	ID() string

	// Deliver receives one session update, in order (replayed backlog then live); it
	// must not block since it runs under the session lock, and its returned error is
	// advisory only.
	Deliver(ctx context.Context, n libacp.SessionNotification) error

	// RequestPermission answers the downstream agent's session/request_permission;
	// called only on the controller viewer, it runs on its own goroutine and may block
	// awaiting a decision.
	RequestPermission(ctx context.Context, req libacp.RequestPermissionRequest) (libacp.RequestPermissionResponse, error)
}