Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

31.6 KB
Raw Blame
/**
 * What the Environment side needs: the contract `context_engine` executes an approved tool
 * call through, plus the configuration and runtime services an Environment is built with.
 *
 * Two planes live in this file and must not be confused (see the docs page):
 * - the **message plane** — `executeTool`, which the engine drives: an OmniMessage tool call
 *   in, a stream of OmniMessage out, nothing else;
 * - the **management plane** — the tool list, the permission lookup, the background command
 *   and subagent listings, their stop/steer entry points and the listener attachments. These
 *   never pass through `context_engine`: they serve a host's own UI (the Web App's process
 *   and subagents panels, an approval mode's permission check) and are ordinary method calls
 *   returning ordinary data.
 *
 * Docs: packages/docs/content/interfaces.{zh,en}.md (site path /docs/interfaces).
 */
import type { OmniMessage, ToolCallPayload, ToolDefinition } from "../omnimessage/types.js";
import type { ApproveFn, RunCutoff, ThinkingLevelName } from "./shared.js";
import type { LLMInterface } from "./llm.js";
// Concrete classes, used only for EnvironmentServices type annotations (type-only import; no runtime dependency, no circular reference).
import type { CommandSessionManager } from "../environment/tools/command/session-manager.js";
import type { SubagentSessionManager } from "../environment/tools/subagent/session-manager.js";

// ---------------------------------------------------------------------------
// Tool configuration
// ---------------------------------------------------------------------------

/** Tool permission: read-only / read-write. */
export type ToolPermission = "r" | "rw";

/**
 * Runtime configuration for a single tool.
 * Docs: /docs/tools § "Configuration fields".
 */
export interface ToolDefinitionConfig {
  name: string;
  description: string;
  parameters?: Record<string, unknown>;
  permission?: ToolPermission;
  /**
   * Which class of session model this entry targets: `"vision"` only for models that support
   * images, `"text-only"` only for text-only models; omitted means available for all models.
   * Filtered by session model at assembly time (see `selectBuiltinToolsForModel`). The
   * built-in defaults set it on no entry — read_file serves both classes and decides at
   * runtime — so it is a config feature for entries that need a per-class definition.
   */
  forModel?: "vision" | "text-only";
  /** Timeout for a single tool call (ms); on timeout, ends as `failed`; <=0 disables it. */
  timeoutMs?: number;
  /** Max length of tool output; Environment truncates from the front (keeping the head) if exceeded; <=0 disables it. */
  maxOutputLength?: number;
  /**
   * Per-tool toggle for the optional `description` call argument (a model-written sentence
   * shown to the user while the call runs). The argument itself is declared as a normal
   * property in this entry's `parameters` (editable config is the single source of truth);
   * setting `call_description: false` filters that property out of the schema handed to the
   * LLM at assembly time (in-memory only — the stored YAML is never rewritten). Missing =
   * true (the property stays). No effect on entries whose parameters declare no
   * `description` property.
   */
  call_description?: boolean;
}

/**
 * One MCP Server entry from `system_config.yaml` (`tools.mcpServers`). `name` scopes the
 * server's tools as `mcp__<name>__<tool>`; `config` stays an open object at this seam (the
 * stored YAML is schema-free) and is typed/validated at Environment assembly time by
 * `environment/mcp/config.ts`: `transport: "stdio" | "http" | "sse"` (inferable from
 * `command` / `url`), the per-transport fields (stdio: `command`/`args`/`env`/`cwd`;
 * http/sse: `url`/`headers`), and the shared optional `connectTimeoutMs` / `timeoutMs` /
 * `maxOutputLength`.
 * Docs: /docs/tools § "MCP servers".
 */
export interface MCPServerConfig {
  name: string;
  config: Record<string, unknown>;
}

/** Set of tool configs required to initialize Environment. */
export interface ToolConfig {
  customTools: ToolDefinitionConfig[];
  mcpServers: MCPServerConfig[];
}

// ---------------------------------------------------------------------------
// Subagents, services and configuration
// ---------------------------------------------------------------------------

/**
 * Handle for a child Agent session: derived by `SubagentRunner.spawn`,
 * representing a child Session that can run over multiple turns. Deriving (spawn) is separate
 * from running (run), so the same child Session can accept an additional Prompt and keep running
 * after a turn ends (a long-running subagent, accessed via `input_subagent`).
 * Docs: /docs/interfaces § "Subagent interfaces".
 */
export interface SubagentHandle {
  /** The child Session's id: the origin hop of messages produced by run; `subagent_id` is derived from its tail for the frontend to correlate. */
  sessionId: string;
  /**
   * One-shot take of the child's origin-tagged `session_meta`: a background launch
   * (run_subagent with `run_in_background`) forwards it synchronously so hosts learn of the
   * child before any collect window runs; `run` then skips its own meta forwarding. Null
   * once taken (or once `run` already sent it). Optional — older embedders' handles simply
   * leave background launches without an upfront meta.
   */
  takeMeta?(): OmniMessage | null;
  /**
   * Runs one turn of a task on the child Session. Emitted child-session messages **all already
   * carry the origin marker** (the child Session id); the first message of the first run is the
   * child Session's `session_meta`, and tool_calls received by the forwarded approval callback
   * carry origin as well. The generator's return value says whether the round was cut off
   * early (`RunCutoff`) or ran to completion (`null`) — the parent reports a cut-off round
   * as failed instead of handing the model a half answer as a result.
   */
  run(input: {
    /**
     * The round's input, in the shape `Session.run` takes a Prompt in — the same OmniMessage
     * list `steer` carries, so both ways into a child session speak one vocabulary. The
     * caller owns the messages' `sender`: the model's dispatch is `parent_agent`, a human's
     * message from a host panel carries none.
     */
    messages: OmniMessage[];
    signal?: AbortSignal;
    /** The parent Agent's approval callback; forwarded to the child Session to inherit the parent's approval mode. */
    approve?: ApproveFn;
  }): AsyncGenerator<OmniMessage, RunCutoff | null>;
  /**
   * Queues a steering message for the child Session's running Task (the same mechanism as a
   * user steering the main session: delivered as a `[user_steering]` user message at the
   * child's next input assembly). Returns false when no run is in flight — the caller then
   * falls back to a follow-up run. Optional so older embedders' handles keep compiling; a
   * handle without it simply reports "not steerable".
   */
  steer?(messages: OmniMessage[]): boolean;
  /** Pins the child Session's thinking level (`Session.thinkingLevel`: applied from its next LLM request) — a host panel's pick on a live child. Optional, like `steer`. */
  setThinkingLevel?(level: ThinkingLevelName): void;
  /** Releases runtime resources held by the child Session (e.g. its managed command sessions). Idempotent. */
  dispose(): void;
}

/** Every thinking level name, the `ThinkingLevelName` vocabulary as a runtime list (validating a wire value — the server's PATCH and Agent-config routes). */
export const THINKING_LEVEL_NAMES: readonly ThinkingLevelName[] = [
  "none",
  "low",
  "medium",
  "high",
  "xhigh",
  "max",
];

/**
 * Thinking levels the model may request for a spawned child Session (`run_subagent`'s
 * `thinking_level` argument): the selectable tiers only — never `"none"`, mirroring the
 * user-facing pickers (many models cannot disable thinking; see the web picker's
 * SELECTABLE_THINKING_LEVELS and project-config's DEFAULT_CHAT_THINKING_LEVELS). Omitting the
 * argument inherits the parent Session's effective level, so a parent genuinely running
 * without a level still passes that down.
 */
export const SUBAGENT_THINKING_LEVELS: readonly ThinkingLevelName[] = [
  "low",
  "medium",
  "high",
  "xhigh",
  "max",
];

/**
 * Child Agent runner: injected into the `run_subagent` tool so it can
 * derive and run a child Agent without a reverse dependency on Agent/Session, avoiding circular
 * dependencies. The concrete implementation is provided by the SDK composition layer (where
 * `createAgent` lives), which internally derives via `createAgent` → `createSession` and hands
 * back a `SubagentHandle`.
 * Docs: /docs/interfaces § "Subagent interfaces".
 */
export interface SubagentRunner {
  /**
   * Derives a child Agent and creates a child Session. Precheck errors such as exceeding the
   * depth limit or a nonexistent target agent are expressed by throwing (collapsed to `failed`
   * by Environment).
   */
  spawn(input: {
    /** The child Agent's agentId; if omitted, reuses the current Agent (self-invocation). */
    agentId?: string;
    /**
     * Upstream model id for the child Session, paired with `provider` — a model reference is
     * always the complete pair. Omit both to inherit the parent Session's model; supplying
     * one half without the other is rejected.
     */
    modelId?: string;
    /** Provider group for `modelId`; required whenever `modelId` is given. */
    provider?: string;
    /**
     * Explicit thinking level for the child Session; omitted inherits the parent Session's
     * effective level (including "no level" when the parent has none). The `run_subagent`
     * tool restricts its `thinking_level` argument to {@link SUBAGENT_THINKING_LEVELS}.
     */
    thinkingLevel?: ThinkingLevelName;
  }): Promise<SubagentHandle>;
  /**
   * Revives a released child Session by id (`resumeSession` semantics: its own history,
   * model and Workspace) and hands back a handle for re-management — the revival path shared
   * by the host (see SubagentMessageOptions.resume) and by input_subagent on a released
   * `subagent_id`. `agentId` names the owning Agent; omitted = the parent Agent's own (a
   * self-spawn's child). A missing or unrecoverable session is expressed by throwing.
   * Optional — a runner without it simply leaves revival unavailable.
   */
  resume?(input: { agentId?: string; sessionId: string }): Promise<SubagentHandle>;
}

/**
 * Proxy-reading service for read_file's image branch: injected when the session model doesn't
 * support images (vision=false) — images are handed to the configured vision model for
 * description and the tool returns text, avoiding a 400 from feeding images back into a
 * tool_result for a provider that doesn't support images. Its presence is also how read_file
 * learns the session model cannot view images: absent, an image is returned as image content.
 * Docs: /docs/interfaces § "VisionDescriberService".
 */
export interface VisionDescriberService {
  /** Vision model id; null when the Project has no `vision_model` configured (or it's invalid), in which case the tool ends with a failed explanation. */
  modelId: string | null;
  /** Constructs a single-shot LLM for this vision model (no tools, no system prompt); omitted when `modelId` is null. */
  createLLM?: () => LLMInterface;
}

/**
 * Runtime services Environment injects into individual tools (e.g. `run_subagent` needs `SubagentRunner`); most tools don't use these.
 * Docs: /docs/interfaces § "ToolExecutionRequest and EnvironmentConfig".
 */
export interface EnvironmentServices {
  subagentRunner?: SubagentRunner;
  /** Injected when (and only when) the running context's model doesn't support images: read_file then describes an image through it instead of returning image content. Follows the model across an in-session switch (`Environment.reconfigure` re-injects or removes it as each context opens). */
  visionDescriber?: VisionDescriberService;
  /** Registry of long-running command sessions (shared by `exec_command` / `input_command`); constructed and injected internally by Environment. */
  commandSessions?: CommandSessionManager;
  /** Registry of background subagent sessions (shared by `run_subagent` / `input_subagent`); constructed and injected internally by Environment. */
  subagentSessions?: SubagentSessionManager;
  /**
   * Sink for background-task completion reports (`run_in_background` launches): tools arm a
   * completion watcher that calls this when the task settles; Environment forwards it to the
   * listener the Session attached (see EnvironmentInterface.setBackgroundTaskListener).
   * Injected internally by Environment.
   */
  backgroundDone?: (event: BackgroundTaskDoneEvent) => void;
  /**
   * Live forwarding sink for background-launched subagents: the child's origin-tagged
   * messages flow here the moment its pump produces them, so hosts can stream them to the
   * frontend past the launching turn's end (display copies only — the child's own Trace is
   * the durable record). Injected internally by Environment; forwarded to the listener the
   * Session attached (see EnvironmentInterface.setBackgroundMessageListener).
   */
  backgroundForward?: (msg: OmniMessage) => void;
}

/**
 * Completion report of one background-launched task (`exec_command` / `run_subagent` with
 * `run_in_background`), emitted when the task settles and delivered to the Session as a
 * harness user message (see Session's background-notice queue).
 */
export interface BackgroundTaskDoneEvent {
  /** Which background family settled. */
  kind: "command" | "subagent";
  /** The registry handle the model holds: `process_id` or `subagent_id`. */
  id: string;
  /** What was launched: the command string, or the subagent prompt's first line (display only, truncated by the producer). */
  label: string;
  /**
   * Terminal status of the run. `stopped` is a command somebody ended on purpose (a stop
   * signal from outside, a capacity eviction) — settled, but not a failure to react to;
   * `failed` stays for outcomes nobody asked for (a spawn error, a non-zero exit, a fault
   * signal).
   */
  status: "completed" | "failed" | "stopped";
  /** One-line terminal detail (exit code / signal / subagent note); empty when there is none. */
  detail: string;
  /** Tail of the yet-undelivered output at settle time (capped by the producer); empty when nothing was pending. */
  output: string;
}

/** Docs: /docs/interfaces § "ToolExecutionRequest and EnvironmentConfig". */
export interface EnvironmentConfig {
  workspaceDir: string;
  toolConfig: ToolConfig;
  /**
   * This Session's private scratchpad directory (`scratchpad/<sessionId>`), the generic
   * Session-scoped storage root for Environment by-products. Currently it backs
   * truncated-tool-output recovery: output beyond an entry's `maxOutputLength` is saved under
   * `<sessionScratchpadDir>/truncated-tool-output/`. Agent Sessions always pass it; standalone
   * embedders without a stable Session directory omit it and keep truncation-only behavior.
   */
  sessionScratchpadDir?: string;
  /** Runtime services (optional); Environment forwards these to each tool factory to use as needed. */
  services?: EnvironmentServices;
  /**
   * Agent vault environment variables (key-value pairs, taken from the Agent's
   * `agent_state/.vault.toml`): injected into the exec_command / input_command subprocess
   * environment; hardened entries cannot be overridden.
   */
  vault?: Record<string, string>;
  /**
   * Proxy policy for exec_command / input_command subprocess environments (see
   * {@link ProxyEnvPolicy}). Threaded by the Web server from its admin-level proxy
   * settings; re-read at every spawn so a settings change needs no restart. Absent, or a
   * getter returning null = the host environment passes through unchanged (the default
   * for SDK/CLI standalone use).
   */
  proxyEnv?: () => ProxyEnvPolicy | null;
  /**
   * Harness-control variables for exec_command / input_command subprocess environments
   * (see {@link CreateAgentOptions.controlEnv}): the hosting server injects its own API
   * address, its local API token and this Session's coordinates so commands the Agent
   * runs can drive the harness back through the CLI/API. Re-read at every spawn like
   * `proxyEnv`. These entries override vault entries of the same name (sanctioned host
   * wiring outranks per-Agent variables) but never the hardened entries. Absent = nothing
   * is injected (SDK/CLI standalone use).
   */
  controlEnv?: () => Record<string, string>;
  /**
   * Directories put at the FRONT of PATH for exec_command / input_command subprocesses
   * (see {@link CreateAgentOptions.pathPrepend}). Applied in two places, because one is
   * not enough: onto the inherited PATH of the child environment — before the vault, so a
   * vault `PATH` still replaces the whole inherited value — and as a statement in front of
   * the command string, which is what survives a login profile rewriting PATH after the
   * child environment was set. The statement runs last, so these directories lead whatever
   * PATH the shell ended up with, a vault `PATH` included. Re-read at every spawn like
   * `proxyEnv`. Absent, or a getter returning nothing = PATH is untouched.
   */
  pathPrepend?: () => string[];
  /**
   * Sandbox-confinement seam for everything the Environment spawns for the Session: the
   * exec_command / input_command subprocesses, the stdio MCP Servers, and the helper the
   * file tools work through when the Session is confined (see {@link SpawnConfiner} and
   * tools/fs-worker.ts). Like {@link EnvironmentConfig.proxyEnv} it is a getter re-read
   * at every spawn, so the hosting server can change the active confiner at runtime
   * (e.g. via a platform hot push) and reach Sessions that are already running. Absent,
   * or a getter returning null = everything spawns unconfined (the default for SDK/CLI
   * standalone use).
   */
  confineSpawn?: () => SpawnConfiner | null;
}

/**
 * Proxy policy applied to command subprocess environments (see
 * {@link EnvironmentConfig.proxyEnv}):
 * - `{ mode: "strip" }` — the proxy variables (HTTP_PROXY / HTTPS_PROXY / ALL_PROXY, any
 *   casing) are removed; NO_PROXY is kept (inert without them, and commands that set
 *   their own proxy still honor it). The hosting server's proxy switch in the off state.
 * - `{ mode: "inject", url, noProxy }` — the explicit proxy wins over ambient env:
 *   HTTP_PROXY / HTTPS_PROXY (plus their lowercase twins) are set to `url` and
 *   NO_PROXY / no_proxy to `noProxy`, overriding inherited values; an inherited
 *   ALL_PROXY (any casing) is removed for the same reason. The caller supplies `noProxy`
 *   pre-merged (the hosting server includes the loopback names).
 * - `null` (or no getter at all) — pass through unchanged.
 * The Agent vault still overrides whichever of these the policy produced: a per-Agent
 * explicit variable outranks the host-level policy.
 */
export type ProxyEnvPolicy = { mode: "strip" } | { mode: "inject"; url: string; noProxy: string };

/**
 * Rewrites the exact argv a command session is about to spawn so it executes
 * confined — typically the original invocation wrapped in a sandbox runner
 * (`[runner, ...profileArgs, "--", ...argv]`). Mechanism only: which confinement
 * policy applies, and which backend enforces it, is decided by whoever supplies
 * the confiner (the hosting server's platform layer); this seam never interprets
 * the argv. Fail-closed by contract: a confiner that cannot enforce its policy
 * must THROW — the error surfaces as the command's spawn failure instead of the
 * command running unconfined. Returning the argv unchanged is reserved for
 * policies that genuinely mean "unconfined".
 * @param argv - the exact argv about to be spawned (`[shellCommand, ...shellArgs, cmd]`), not a shell string.
 * @param opts - spawn context: `cwd` is the working directory of THIS command (per-call,
 *   may differ from the workspace); `workspaceDir` is the Session's Workspace root — the
 *   directory a workspace-scoped confinement policy should treat as writable, never
 *   inferred from `cwd` (a command may run in a workdir outside the Workspace);
 *   `scratchpadDir` is the Session's scratchpad, writable beside the workspace under
 *   that policy (absent for a Session without one).
 * @returns what to spawn instead: the argv, and any environment entries the runner
 *   itself needs (see {@link ConfinedSpawn}).
 */
export type SpawnConfiner = (
  argv: readonly string[],
  opts: { cwd: string; workspaceDir: string; scratchpadDir?: string },
) => ConfinedSpawn;

/**
 * A confiner's answer. `argv` replaces the spawn's argv wholesale; `env` is laid over
 * the environment the manager assembled for the command — entries the runner needs to
 * be a runner at all (an interpreter switch, say), never the command's own settings,
 * which stay the manager's to decide.
 */
export interface ConfinedSpawn {
  argv: readonly string[];
  env?: Readonly<Record<string, string>>;
  /**
   * Whole lines the runner itself prints at the head of stderr before it execs the command
   * (a report, not an error — the Landlock launcher's "partial enforcement" on an older
   * kernel). The spawn drops them from the head of the command's stderr, matched by exact
   * line, case-insensitively; the command's own output is never examined past its first line.
   */
  runnerLines?: readonly string[];
}

/**
 * An approved tool-call execution request.
 * Docs: /docs/interfaces § "ToolExecutionRequest and EnvironmentConfig".
 */
export interface ToolExecutionRequest {
  /** The OmniMessage whose payload.type === "tool_call". */
  toolCall: OmniMessage<ToolCallPayload>;
  signal?: AbortSignal;
  /** The parent Agent's approval callback; forwarded to tools that need to derive a child Session (run_subagent), implementing approval inheritance. */
  approve?: ApproveFn;
}

/**
 * Outcome of a detach request (`EnvironmentInterface.detachToolCall`):
 * - `detached` — the call was asked to hand its work back as a background task;
 * - `not_running` — no call with that id is executing right now (unknown, or already finished);
 * - `not_detachable` — the call is running, but its tool has no background form.
 * The three are separate because a host answers them differently — the last one is a
 * permanent property of the tool, while the first two describe a moment.
 */
export type ToolDetachResult = "detached" | "not_running" | "not_detachable";

/**
 * The opening phrase of the note a detached call returns. Shared because a render layer has
 * to recognize a detached call from the stored output alone — the click that detached it is
 * not in the Trace, and a reloaded page has nothing else to go on — so the sentence the tool
 * writes and the string that matches it must be one value.
 */
export const DETACHED_TOOL_NOTE_PREFIX = "[moved to the background by the user";

/**
 * One background command process owned by the environment (an exec_command promoted past
 * its yield window): the registry handle plus display metadata for a host UI's process
 * list. `pid` is the shell leading the process group (null when the spawn itself failed);
 * `startedAt` is epoch milliseconds.
 */
export interface BackgroundCommandInfo {
  processId: string;
  pid: number | null;
  cmd: string;
  cwd: string;
  startedAt: number;
  running: boolean;
  /**
   * The service the process serves, when one was detected: the last local URL its output
   * printed (may carry a path), else `http://localhost:<port>` synthesized from a listen-port
   * probe of its process group (refresh via `probeBackgroundCommandServices`). Absent when
   * neither source has one.
   */
  serviceUrl?: string;
}

/**
 * One live subagent child session owned by the environment: the child Session id (the origin
 * hop the frontend already correlates by), the registry handle when the session was promoted
 * to the background (null while it only lives inside a foreground collect window), and
 * whether a round is currently running.
 */
export interface BackgroundSubagentInfo {
  sessionId: string;
  subagentId: string | null;
  running: boolean;
}

/**
 * Outcome of a host-initiated subagent message (`sendToBackgroundSubagent`): `steered` = the
 * child was mid-run and the text was queued as a steering message; `started` = the child was
 * idle and the text began a follow-up run on the same child Session; `resumed` = no live
 * child bore the id, so the session was revived through `SubagentRunner.resume` and the text
 * began its next round; `busy` = the child cannot take the message right now (mid-run on a
 * handle that predates steering, or no room to re-manage a resumed session); `gone` = no
 * live child and no way to resume (resume not requested/available, or the session's record
 * is unrecoverable).
 */
export type SubagentMessageOutcome = "steered" | "started" | "resumed" | "busy" | "gone";

/** Options of a host-initiated subagent message (see EnvironmentInterface.sendToBackgroundSubagent). */
export interface SubagentMessageOptions {
  /**
   * Enables the resume fallback when no live child bears the session id: the child Session
   * is revived (its own history, model and Workspace — `resumeSession` semantics) and
   * re-managed, and the text starts its next round. `agentId` names the Agent that owns the
   * child session (the host reads it from its session registry).
   */
  resume?: { agentId: string };
}

/**
 * Environment interface: executes approved tool calls within the Workspace.
 * `executeTool` yields `partial_tool_call_output` as an async generator and ends with exactly one
 * complete `tool_call_output`; nested session messages carrying an origin marker (e.g. forwarded
 * by run_subagent) pass through unchanged.
 *
 * **Rendering** of tool calls is not this interface's concern (nor core's): streaming rendering is
 * handled by the CLI / Web frontend itself.
 * Docs: /docs/interfaces § "EnvironmentInterface".
 */
export interface EnvironmentInterface {
  listTools(): Promise<ToolDefinition[]>;
  executeTool(request: ToolExecutionRequest): AsyncGenerator<OmniMessage>;
  /** Looks up a tool's permission level (for frontend permission-mode decisions); returns undefined for unknown tools. */
  toolPermission(name: string): ToolPermission | undefined;
  /** Background command processes this environment currently owns (host UI process list). Optional — standalone embedders may not track any. */
  listBackgroundCommands?(): BackgroundCommandInfo[];
  /** Kills one background command process by id (whole process group); false when the id is unknown. Optional, like listBackgroundCommands. */
  killBackgroundCommand?(processId: string): boolean;
  /**
   * Asks one EXECUTING tool call to hand its work back as a background task, so the turn can
   * close and the conversation carry on (the Web App's per-card button). Addressed by
   * tool_call_id, the only handle a host has on a single call. Not an abort: the call ends
   * `completed` with a registry handle, nothing is killed, and the work's completion arrives
   * later as the usual background report. Optional, like listBackgroundCommands.
   */
  detachToolCall?(toolCallId: string): ToolDetachResult;
  /**
   * Whether a background subagent session is mid-round. Hosts pin a Session's runtime entry
   * on it: a `run_in_background` child outlives the call that launched it, and evicting the
   * Session while it works strands its completion report and live messages. Optional, like
   * listBackgroundCommands.
   */
  hasRunningBackgroundSubagents?(): boolean;
  /**
   * All live subagent child sessions (foreground-window ones included), for a host UI's
   * subagents panel. Optional, like listBackgroundCommands.
   */
  listBackgroundSubagents?(): BackgroundSubagentInfo[];
  /**
   * Host-initiated message to one child session, by child Session id: steering while the
   * child runs, a follow-up run while it is idle, a revival (`opts.resume`) when the session
   * is no longer live (see SubagentMessageOutcome/SubagentMessageOptions). The human and the
   * model (`input_subagent`) converge on the managed session's same channel, and both hand
   * it the same thing — an OmniMessage list, whichever state the child is in. Optional.
   */
  sendToBackgroundSubagent?(
    childSessionId: string,
    messages: OmniMessage[],
    opts?: SubagentMessageOptions,
  ): Promise<SubagentMessageOutcome>;
  /**
   * Host-initiated abort of one child session's CURRENT run (the child-session equivalent of
   * the user's stop button): the session survives for follow-ups — a subagent session is
   * never destroyed. False when the child is unknown or idle. Optional.
   */
  abortBackgroundSubagentRun?(childSessionId: string): boolean;
  /**
   * Host-initiated pin of one live child session's thinking level (the child-session
   * equivalent of assigning `Session.thinkingLevel`: applied from the child's next LLM
   * request). False when the child is not live — a released child is revived through the
   * host's loader, which restores the pin it stores. Optional.
   */
  setBackgroundSubagentThinkingLevel?(childSessionId: string, level: ThinkingLevelName): boolean;
  /**
   * Attaches the single listener for subagent run-state changes (a round starting or
   * settling on any live child). The host re-reads `listBackgroundSubagents` on each ping —
   * the event carries no payload, so state reads stay race-free against the listing.
   * Optional, same single-listener pattern as setBackgroundTaskListener.
   */
  setSubagentStateListener?(listener: () => void): void;
  /**
   * Attaches the single listener for background-task state changes: a command session
   * promoted to the background, exited, stopped or removed; a subagent session promoted,
   * starting or settling a round, or released. Payload-free — the host re-reads
   * `listBackgroundCommands` / `listBackgroundSubagents` on each ping, and reads them once
   * when it attaches (pings before that are not buffered). Optional, same single-listener
   * pattern as setSubagentStateListener.
   */
  setBackgroundStateListener?(listener: () => void): void;
  /**
   * Attaches the host's session-lifetime fallback approval sink for child sessions: a child
   * approval with no window sink (an active run_subagent/input_subagent call) and no
   * background-launch standing sink is consulted through this instead of waiting for the
   * model's next poll — the host escalates it to the user, the parent session idle included.
   * Window sinks and standing sinks keep precedence while present. Optional: hosts that
   * never attach one (e.g. the CLI) keep the poll-window-only approval semantics.
   */
  setSubagentApprovalFallback?(approve: ApproveFn): void;
  /**
   * Refreshes the listen-port probe behind `BackgroundCommandInfo.serviceUrl` for running
   * sessions whose output printed no URL (TTL-cached and time-bounded per session; see
   * command/port-probe.ts). Hosts call it before reading the list when they want probed
   * URLs; the list itself stays synchronous. Optional, like listBackgroundCommands.
   */
  probeBackgroundCommandServices?(): Promise<void>;
  /**
   * Attaches the single listener for background-task completion reports (`run_in_background`
   * launches). Events fired before a listener exists are buffered and flushed on attach; after
   * `dispose()` no further events fire. Optional — environments without background tools omit it.
   */
  setBackgroundTaskListener?(listener: (event: BackgroundTaskDoneEvent) => void): void;
  /**
   * Attaches the single listener for live-forwarded background-subagent messages (see
   * EnvironmentServices.backgroundForward). Same buffering and dispose semantics as
   * setBackgroundTaskListener. Optional.
   */
  setBackgroundMessageListener?(listener: (msg: OmniMessage) => void): void;
  /** Releases runtime resources held by the environment (e.g. managed long-running command sessions); called by the host when the Session ends. Optional, idempotent. */
  dispose?(): void;
}