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), read from the same snapshot.
	Sessions int `json:"sessions"`
	// Viewers is how many viewers are attached across those sessions,
	// independent of Sessions: an open session with nobody watching still
	// counts toward Sessions but not Viewers.
	Viewers   int       `json:"viewers"`
	StartedAt time.Time `json:"startedAt"`
	// SessionIDs lists every session currently open on the instance, sorted
	// for a deterministic snapshot. A session nobody is watching, or that
	// has emitted no update yet, 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, not ctx, so it outlives the
	// request. cwd is the sandbox workspace. Prefer StartResolved if the
	// agent is 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, so a caller enforcing a policy decision
	// (e.g. Enabled) spawns exactly the record it judged. 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 (controllerGranted true).
	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; the
	// kernel adds nothing to n. ErrNotFound when no instance owns sessionID.
	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 Close, 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 for the session, on top of
	// Cwd. Omitted/empty means none.
	AdditionalDirectories []string

	// McpServers are the already-resolved MCP servers to forward downstream
	// in session/new; the kernel drops any the downstream's advertised
	// mcpCapabilities cannot consume. Nil forwards none.
	McpServers []libacp.McpServer

	// Meta is an opaque session/new `_meta` blob forwarded verbatim; the
	// kernel neither reads nor interprets it. Nil forwards none.
	Meta json.RawMessage

	// Terminal advertises the terminal client capability to the downstream
	// at initialize, iff set — negotiated once per connection, at the first
	// OpenSession. Even when set, every terminal/* is still gated on the
	// session's controller implementing TerminalServer (else
	// MethodNotFound); left false, terminals are never advertised and
	// terminal/* always refuses.
	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: the replayed journal
	// backlog on attach, then every live update.
	//
	// It must not block — it runs on the fan-out path under the session
	// lock, so a blocking call stalls every other viewer and the downstream
	// read loop. Enqueue and return. The 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 session's controller
	// viewer (an observer may later be promoted to controller on detach).
	// Unlike Deliver it runs on its own goroutine and may block awaiting a
	// decision.
	RequestPermission(ctx context.Context, req libacp.RequestPermissionRequest) (libacp.RequestPermissionResponse, error)
}