A local-first multi-agent app development platform, built on PenguinHarness
/**
* Agent and the `createAgent` entry point.
*
* `createAgent` is the unified way to create/load an Agent: it initializes Agent State
* if the directory is empty, otherwise loads by agentId.
* An Agent has exactly one Agent State and can run multiple times; the
* Workspace is determined when a Session is created.
*
* A Session runs on **model contexts**, each assembled from the Agent State as it is on disk
* the moment the context opens — Session creation, the context a completed compaction opens,
* a resume that finds its context closed — and fixed until the context closes (see
* `assembleContext`). The model is a fact of the context too: every rotation keeps the
* closing context's model except the one a user's in-session switch drives, which opens the
* next context on the model they picked (see `Session.switchModel`). The Agent object's own
* `state` is the load-time snapshot, used for identity and initialization; no Session runs on
* it.
*/
import fs from "node:fs/promises";
import path from "node:path";
import { parse as parseYaml } from "yaml";
import {
assertValidId,
assembleSystemPrompt,
buildToolConfig,
selectBuiltinToolsForModel,
DEFAULT_COMPACTION_PROMPT,
formatModelRef,
getModel,
listInstalledSkills,
listScheduleNames,
loadAgentState,
loadAgentVault,
loadProjectConfig,
listInstalledHooks,
projectDir,
resolveSessionMemory,
resolveModelCredential,
resolveModelRef,
sameModelRef,
sessionScratchpadDir,
systemConfigPath,
tracesDir,
type AgentState,
type CompactionConfig,
type InstalledHook,
type ModelRef,
type ModelEntry,
type ProjectConfig,
type SystemConfig,
} from "./state/index.js";
import {
DEFAULT_MAX_CONTEXT_LENGTH,
GenerativeModel,
ToolCallIdAllocator,
effectiveMaxContextLength,
} from "./llm/index.js";
import { Environment } from "./environment/index.js";
import {
Writer,
findLatestTraceFile,
latestSessionId as latestTraceSessionId,
readTraceTolerant,
resumeTrace,
} from "./trace/index.js";
import { ModelSwitchRefusedError, Session } from "./session.js";
import { scriptPreToolUseHook, scriptStopHook, scriptUserPromptHook } from "./hooks/script-hook.js";
import type { ScriptHookOptions } from "./hooks/script-hook.js";
import type { HookSubagentRequest, SessionHooks } from "./hooks/stop-hook.js";
import { predatesEveryPromptHooks, userPromptTrigger } from "./plugins/index.js";
import type {
ModelSwitchSupport,
SessionConfig,
SessionOpenContextOptions,
SessionOpenedContext,
} from "./session.js";
import {
createTempWorkspace,
formatSessionId,
mcpConnectOutcome,
sessionEnvironment,
} from "./internal/session-support.js";
import {
compactionEnd,
mcpConnectBegin,
mcpConnectEnd,
normalizeSessionSource,
sessionMeta,
toolListReady,
userText,
withOrigin,
} from "./omnimessage/index.js";
import type {
MessageOrigin,
OmniMessage,
SessionMetaPayload,
SessionSource,
ToolCallPayload,
} from "./omnimessage/index.js";
import { SUBAGENT_NAME } from "./environment/tools/run-subagent.js";
import { INPUT_SUBAGENT_NAME } from "./environment/tools/input-subagent.js";
import type { CompactionSettings, OpenContextOptions } from "./engine/context-engine.js";
import { catalogImageLimit, catalogSupportsVideo } from "./state/model-catalog.js";
import type {
ApproveFn,
CommandPolicyConfig,
GenerativeModelConfig,
ProxyEnvPolicy,
SpawnConfiner,
SubagentHandle,
SubagentRunner,
ThinkingLevelName,
ToolConfig,
ToolDefinition,
VisionDescriberService,
} from "./interfaces/index.js";
/**
* Maximum subagent spawn depth. Currently capped at 1 level (a subagent cannot spawn
* another subagent); the depth mechanism is designed to support multiple levels —
* raise this constant to allow deeper nesting.
*/
const MAX_SUBAGENT_DEPTH = 1;
export interface CreateAgentOptions {
agentId?: string;
projectId?: string;
/** Local data root directory; defaults to `resolveRoot()` (ADELIE_HOME or ~/.adelie/data). */
root?: string;
/**
* Proxy policy for exec_command subprocess environments of every Session this Agent
* creates or resumes — and of its subagents' Sessions, which inherit the getter (see
* {@link ProxyEnvPolicy}: strip the proxy variables, inject an explicit proxy over the
* inherited env, or null = pass through). The Web server threads its admin-level proxy
* settings through here; the getter is re-read at every command spawn, so a settings
* change needs no restart. Absent = pass through (SDK/CLI standalone use follows the
* user's own shell environment).
*/
proxyEnv?: () => ProxyEnvPolicy | null;
/**
* Harness-control variables for the command subprocesses of every Session this Agent
* creates or resumes. The hosting server passes a policy getter here; core evaluates it
* with each Session's own coordinates (subagent Sessions get their own agent/session
* ids — a child Agent inherits the getter like `proxyEnv`, and its Sessions call it with
* their own context). The returned entries override vault entries of the same name (see
* {@link EnvironmentConfig.controlEnv}). Absent = nothing is injected (SDK/CLI
* standalone use).
*/
controlEnv?: (ctx: ControlEnvContext) => Record<string, string>;
/**
* Directories put at the FRONT of PATH for the command subprocesses — and the hook
* scripts — of every Session this Agent creates or resumes, and of its subagents'
* Sessions, which inherit the getter like `proxyEnv`. The Web server points it at the
* shim directory holding its own `penguin`, so a command an Agent runs reaches the CLI
* of the harness that is running it rather than whatever is installed globally. Re-read
* at every spawn. Absent = PATH is untouched (SDK/CLI standalone use).
*/
pathPrepend?: () => string[];
/**
* Sandbox-confinement seam for the command subprocesses of every Session this Agent
* creates or resumes — and of its subagents' Sessions, which inherit the getter (see
* {@link SpawnConfiner}). Host policy exactly like `proxyEnv`: re-read at every
* spawn, so the hosting server can swap the active confiner without restarting
* Sessions. Evaluated with the Session's coordinates, like `controlEnv`, so a host can
* keep a policy per Session. Absent = commands spawn unconfined.
*/
confineSpawn?: (ctx: ControlEnvContext) => SpawnConfiner | null;
/**
* What a host adds to every Session this Agent assembles — see {@link AgentAssembly}.
* Host policy like
* `proxyEnv`: inherited by subagents' Agents, re-read at every Session creation so a
* hot push that changes the set reaches the next Session without a restart.
*/
assembly?: AgentAssembly;
}
/**
* The host's contributions to Session assembly. Everything an Agent's own folder
* decides (system prompt, tool selection, MCP servers, model, compaction, memory) stays
* in its config; this is what the HOSTING PROCESS adds on top, for every Agent.
*/
export interface AgentAssembly {
/**
* Sections appended to the assembled system prompt, in order, each as `# <title>` +
* text. Empty = the prompt is exactly the Agent's own.
*/
promptSections?(): readonly PromptSection[];
/**
* Resolves a model credential immediately before an upstream request. Hosting processes can
* rotate short-lived credentials here; core neither knows nor interprets the provider.
*/
resolveModelApiKey?(context: ModelRequestContext): Promise<string | undefined>;
}
export interface ModelRequestContext {
projectId: string;
agentId?: string;
sessionId?: string;
provider: string;
modelId: string;
}
export interface PromptSection {
/** The `# ` heading the section is appended under. */
title: string;
text: string;
}
/** The Session coordinates a {@link CreateAgentOptions.controlEnv} policy is evaluated with. */
export interface ControlEnvContext {
projectId: string;
agentId: string;
sessionId: string;
}
export interface CreateSessionOptions {
/** Workspace for this run; if unspecified, a temporary Workspace is created under the Agent directory. */
workspaceDir?: string;
/**
* Model used for this Session (upstream model_id); must be given together with `provider`.
* Omit both to use the Project's default Model.
*/
modelId?: string;
/**
* Provider grouping for `modelId`: the two together form the paired reference. It is never
* inferred, so it's "both or neither" — either half alone is an error, not a lookup.
*/
provider?: string;
/**
* Thinking level for this Session — a tri-state:
* - a `ThinkingLevelName` pins the level;
* - `undefined` (omitted) falls back to the config chain: the Agent's explicit
* `model.thinking_level` > the Project's `default_chat.thinking_level` > the built-in
* `"medium"` (see `configuredThinkingLevel`), read again for every model context the
* Session opens;
* - `null` means "no thinking level": the config fallback is suppressed entirely
* (nothing goes into the LLM config).
* Subagent spawning passes the parent Session's effective level (its level, or `null`
* when the parent has none) unless the spawn requests an explicit level (`run_subagent`'s
* `thinking_level`) — either way a child Session never falls back to the child Agent's
* own config.
*/
thinkingLevel?: ThinkingLevelName | null;
/**
* Explicit credentials; if unspecified, falls back to the credentials in the Project config,
* then — only when the entry's requests go to the vendor's own endpoint (no base URL, or a
* vendor endpoint) — to the vendor's environment variable, read by AgentHub. A keyless entry
* pointed anywhere else (a gateway, a self-hosted server) is refused with a
* ModelCredentialError; see resolveModelCredential.
*/
apiKey?: string;
baseUrl?: string;
/** Internal use: this Session's depth in the subagent spawn chain (0 at the top level), used to cap spawn depth. */
subagentDepth?: number;
/**
* What kind of conversation this is, recorded in session_meta; absent = `user`, a person's.
* The subagent spawn site passes `subagent`; a host passes the source its caller stands for
* (the server: `schedule` for a scheduled task, `cli` for `penguin run`, `api` for the Agent API,
* `company` for company mode's desk and ticket Sessions).
*/
source?: SessionSource;
}
export interface ResumeSessionOptions {
/** Id of the Session to resume. */
sessionId: string;
/** Explicit credentials; if unspecified, falls back to the Project config, then to the vendor's environment variable on the same terms as CreateSessionOptions.apiKey. */
apiKey?: string;
baseUrl?: string;
}
/**
* The facts fixed for a Session's lifetime — every model context of the Session is opened
* against them. Everything else a context runs with — the model included — comes from the
* Agent State and the Project config as they are on disk when the context opens (see
* `Agent.assembleContext`).
*/
interface SessionSpec {
sessionId: string;
workspaceDir: string;
/** The model the Session was created on (or resumed on). The model a context runs on is the context's own fact (see AssembledContext.modelEntry); this one only says which entry the credentials below were given for. */
creationRef: ModelRef;
/**
* Explicit credentials the SDK caller gave (CreateSessionOptions / ResumeSessionOptions
* `apiKey` / `baseUrl`). They were given for `creationRef` and apply to that entry alone: a
* context an in-session switch opens on another model runs on that entry's own configured
* credentials (a key handed in for one vendor must never be sent to another).
*/
credentialOverride: { apiKey: string | undefined; baseUrl: string | undefined };
/**
* The Session's thinking-level pin, the tri-state of {@link CreateSessionOptions.thinkingLevel}:
* a value pins every context opened from now on; `null` runs them without a level;
* `undefined` reads the Agent config's default when each context opens. Fixed at
* creation: a mid-session change (`Session.thinkingLevel`) is engine state — it rides
* requests but reshapes no context and never lands here.
*/
thinkingLevel: ThinkingLevelName | null | undefined;
subagentDepth: number;
source: SessionSource;
}
/**
* A Session's runtime components, assembled once by `buildRuntime` (shared by createSession
* and resumeSession) around the context the Session starts in.
*/
interface SessionRuntime {
/** Session-lifetime Environment, equipped with the initial context's toolset and vault (a later context re-equips it — see openNextContext). */
environment: Environment;
/**
* Opens the Session's FIRST context, lazily at the start of the first run: resolves the
* toolset (the Environment's first listTools connects any configured MCP Servers,
* published through `opts.emit` as the connect pair, then the toolset record) and builds
* that context's LLM object. Kept out of createSession on purpose — Session creation
* stays instant and the records stream on the run. The same opening procedure as
* `openNextContext`: only what is being opened differs.
*/
bootstrap: (opts: OpenContextOptions) => Promise<{ llm: GenerativeModel }>;
/**
* Opens the context that follows a completed compaction (see ContextEngineDeps.openNextContext):
* the whole configuration assembled anew from the Agent State, the Environment re-equipped
* with it, then the same opening procedure as `bootstrap` — and the session_meta recording
* the context alongside its engine settings, with the hooks the context runs with.
*/
openNextContext: (opts: SessionOpenContextOptions) => Promise<SessionOpenedContext>;
/** The running context's command policy — follows the rotation (see SessionConfig.commandPolicy). */
commandPolicy: () => CommandPolicyConfig | undefined;
/** The running context's model window — follows the rotation, so the live compaction reader caps the threshold against the model that is running (see `compactionReader`). */
contextWindow: () => number | undefined;
/** The composition layer's half of an in-session model switch (see SessionConfig.modelSwitch). */
modelSwitch: ModelSwitchSupport;
createBareLLM: () => GenerativeModel;
/** The child-session runner the run_subagent tool uses; sessionHooks' subagent spawner shares it. */
subagentRunner: SubagentRunner;
}
/**
* What one model context runs with, assembled from the Agent State as it was on disk at the
* moment the context opened; immutable for the context's lifetime.
*/
interface AssembledContext {
/** The model this context runs on: its entry as resolved from the Project config when the context opened — reference, credentials, window and per-model annotations. */
modelEntry: ModelEntry;
systemPrompt: string;
/** The vault's values, for the Environment's command subprocesses; only the key names enter the prompt. */
vault: Record<string, string>;
toolConfig: ToolConfig;
/** The Project's command policy as read when this context opened (`[command_policy]` of `.project_config.toml`) — Project-owned rather than Agent State, rotated on the same strict-tier schedule. */
commandPolicy: CommandPolicyConfig | undefined;
/** The context's effective thinking level: the Session's pin, or the config default read now. */
thinkingLevel: ThinkingLevelName | undefined;
maxTokens: number | undefined;
requestTimeoutMs: number | undefined;
/** `system_config.max_turns`; the engine treats absent as unlimited (-1). */
maxTurns: number | undefined;
compaction: CompactionSettings;
/**
* The hook packages this context consults: the ones installed in `agent_state/hooks/`
* when it opened. Empty with `hooks.enabled: false` — the one switch over all of them,
* the packages stay installed — and for a child Session, which carries no hooks: a
* subagent's work belongs to its parent's Trace, and a child could not spawn a subagent
* anyway.
*/
hookPackages: InstalledHook[];
/** The session_meta describing this context: the prompt and the model it runs with, and the Session-fixed facts. */
meta: SessionMetaPayload;
}
// Compaction-threshold derivation (`effectiveMaxContextLength`) lives with the rest of the
// window arithmetic in llm/context-limits.ts; re-exported by llm/index.js.
/**
* The Session's compaction settings as they follow from a `compaction` section: defaults
* filled in, the threshold capped by what the model's window leaves room for, and an unknown
* mode read as the default `summarize`.
*
* Stated once because two callers need the same answer from the same input — the context
* assembly below, and the live re-reader every checkpoint calls (see `compactionReader`). Two
* copies of the rule would let a running Session compact at a threshold no rotation would
* have chosen.
*/
function resolveCompaction(
config: CompactionConfig | undefined,
contextWindow: number | undefined,
): CompactionSettings {
return {
maxContextLength: effectiveMaxContextLength(
config?.max_context_length ?? DEFAULT_MAX_CONTEXT_LENGTH,
contextWindow,
),
maxSessionTurns: config?.max_session_turns ?? -1,
mode: config?.mode === "discard" ? "discard" : "summarize",
prompt: config?.prompt ?? DEFAULT_COMPACTION_PROMPT,
};
}
/**
* The credential a Session's (or a describer's) client is built with for a model entry: the
* explicit override, else the entry's inline fields, else — only where resolveModelCredential
* allows it — nothing, so the routed client reads its own environment variable. A keyless
* entry whose endpoint is not the vendor's own throws its ModelCredentialError here, which
* hosts file with the SDKs' missing-credential errors (the server's `isMissingCredential`).
*/
function entryCredential(
entry: ModelEntry,
opts: { apiKey?: string | undefined; baseUrl?: string | undefined },
): { apiKey?: string; baseUrl?: string } {
return resolveModelCredential({
provider: entry.provider,
modelId: entry.model_id,
clientType: entry.client_type,
baseUrl: opts.baseUrl ?? entry.base_url,
apiKey: opts.apiKey ?? entry.api_key,
});
}
/** The message for a model reference that names no entry in the Project config. */
function modelNotConfigured(ref: ModelRef): string {
return `Model is not in the Project config: ${formatModelRef(ref)}. Use \`penguin config model list\` to see the configured models, or \`penguin config model add\` to add one.`;
}
/**
* Output cap for meta requests (title generation / vision describing): these carry their own
* small hardcoded budget, tightened further by the entry's per-model `max_tokens` when that is
* smaller — a cap the user pinned below the budget must bind every request to that model. The
* budget is never raised. A non-positive cap (-1 = uncapped) never tightens: Math.min against
* it would send max_tokens -1 on the wire, and meta requests must keep their small budget.
*/
export function metaMaxTokens(budget: number, modelCap: number | undefined): number {
return modelCap !== undefined && modelCap > 0 ? Math.min(budget, modelCap) : budget;
}
/** The assembled prompt plus the host's sections, each under its own heading. */
function withPromptSections(prompt: string, sections: readonly PromptSection[]): string {
if (sections.length === 0) return prompt;
return [prompt, ...sections.map((s) => `# ${s.title}\n${s.text}`)].join("\n\n");
}
/** Create or load an Agent (the one init-enabled use of `loadAgentState`). */
export async function createAgent(opts: CreateAgentOptions = {}): Promise<Agent> {
const state = await loadAgentState({
...(opts.agentId !== undefined ? { agentId: opts.agentId } : {}),
...(opts.projectId !== undefined ? { projectId: opts.projectId } : {}),
...(opts.root !== undefined ? { root: opts.root } : {}),
init: {},
});
const projectConfig = await loadProjectConfig(state.root, state.projectId);
return new Agent(
state,
projectConfig,
opts.proxyEnv,
opts.controlEnv,
opts.pathPrepend,
opts.confineSpawn,
opts.assembly,
);
}
export class Agent {
constructor(
readonly state: AgentState,
/** The Project config as this Agent last read it from disk (see `projectConfig`). */
private config: ProjectConfig,
/** See {@link CreateAgentOptions.proxyEnv}; forwarded into every Session's Environment. */
private readonly proxyEnv?: () => ProxyEnvPolicy | null,
/** See {@link CreateAgentOptions.controlEnv}; evaluated per Session with that Session's coordinates. */
private readonly controlEnv?: (ctx: ControlEnvContext) => Record<string, string>,
/** See {@link CreateAgentOptions.pathPrepend}; forwarded into every Session's Environment and hooks. */
private readonly pathPrepend?: () => string[],
/** See {@link CreateAgentOptions.confineSpawn}; evaluated per Session with that Session's coordinates. */
private readonly confineSpawn?: (ctx: ControlEnvContext) => SpawnConfiner | null,
/** See {@link CreateAgentOptions.assembly}; read at every Session creation. */
private readonly assembly?: AgentAssembly,
) {}
/**
* The Project config as this Agent last read it from disk: when it was created, and again
* whenever a model switch resolved its target (see `modelEntryOnDisk`). Session creation
* and resumption resolve their model against it.
*/
get projectConfig(): ProjectConfig {
return this.config;
}
/**
* A Session's default thinking level when no explicit per-session level is given — the
* resolution chain (the single rule, keep both sites on it): the Agent's explicit
* `model.thinking_level` > the Project's `default_chat.thinking_level` > the built-in
* `"medium"` (the documented Agent default). Read against the Agent State and the Project
* config a context is assembled from, so the default follows both files into each new
* context. Mirrored by
* the web draft picker's DISPLAY (web features/chat/thinking-level.ts
* `effectiveThinkingLevel`): the picker shows this effective value, and a pick writes
* through to the AGENT config — the project default is only ever a fallback, never
* overwritten from there.
*/
private configuredThinkingLevel(
state: AgentState,
projectConfig: ProjectConfig,
): ThinkingLevelName {
return (
state.systemConfig.model?.thinking_level ??
projectConfig.default_chat?.thinking_level ??
"medium"
);
}
/**
* Assembles what a model context runs with, from the Agent State as it is on disk **now**:
* `system_config.yaml` in full — the prompt template with its section prompts and toggles,
* the builtin tool entries and MCP Servers, the compaction settings, `max_turns`, the
* model defaults — plus `AGENTS.md`, the vault, the installed Skills' metadata, the
* installed hook packages, the Memory indexes, the schedule roster and the Environment
* values (the date included). Every
* context opener goes through here — createSession, the context a completed compaction
* opens (buildRuntime's openNextContext) and a resume that finds its context closed — so an
* edit made during one context, by the user or by the model working on its own
* configuration, lands in the next context and never in the one that is running. What
* stays fixed is the Session itself (`spec`): id, Workspace, origin, depth and the
* thinking-level pin. The model is the caller's to name: `modelEntry` is the entry the
* context runs on — the closing context's for an ordinary rotation, the one the user picked
* for a switch (see `modelEntryOnDisk`).
*
* The vault's values go to the Environment's command subprocesses and only its **key
* names** enter the prompt (so the model knows which API keys are available); Skills only
* inject metadata (name and description) and the model reads the body on demand via shell;
* Memory likewise injects only its index; Schedules inject only task names.
*
* `systemPrompt`, when given, is used instead of assembling it: a
* resume of an open context keeps the prompt its Trace recorded, since the history
* replayed into it was produced under that request prefix.
* Docs: /docs/agent-loop § "Compaction".
*/
private async assembleContext(
spec: SessionSpec,
modelEntry: ModelEntry,
opts: { systemPrompt?: string } = {},
): Promise<AssembledContext> {
const { root, projectId, agentId } = this.state;
const state = await loadAgentState({ root, projectId, agentId });
const vault = await loadAgentVault(root, projectId, agentId);
// Strict-tier alongside the Agent State even though it is Project-owned: the command
// policy this context runs under (and the Project half of the thinking-level chain) is
// the one on disk at its open.
const projectConfig = await loadProjectConfig(root, projectId);
const commandPolicy = projectConfig.command_policy;
// Hook packages are not part of the request prefix, and are read on the same schedule
// all the same: a package the model wrote during one context is consulted from the next.
const child = spec.subagentDepth > 0 || spec.source === "subagent";
const hookPackages =
child || state.systemConfig.hooks?.enabled === false
? []
: await listInstalledHooks(root, projectId, agentId);
let systemPrompt = opts.systemPrompt;
if (systemPrompt === undefined) {
const installedSkills = await listInstalledSkills(root, projectId, agentId);
// Schedule task names for the {{SCHEDULES}} roster (names only; the files' contents are
// the server-side scheduler's concern).
const scheduleNames = await listScheduleNames(root, projectId, agentId);
// Memory for this Session: null when the Agent has Memory off; a temporary Workspace
// gets the user scope only (nothing written against it could ever be read back).
const memory = await resolveSessionMemory({
root,
projectId,
agentId,
workspaceDir: spec.workspaceDir,
enabled: state.systemConfig.memory?.enabled !== false,
});
systemPrompt = withPromptSections(
assembleSystemPrompt(
state,
sessionEnvironment(spec.workspaceDir, spec.sessionId, {
agentId,
projectDir: projectDir(root, projectId),
provider: modelEntry.provider,
modelId: modelEntry.model_id,
}),
Object.keys(vault),
installedSkills,
memory,
scheduleNames,
),
this.assembly?.promptSections?.() ?? [],
);
}
// Tool exposure is capped by depth: a (leaf) child Agent that has reached the max spawn
// depth no longer gets run_subagent or input_subagent (the latter depends on the
// subagent_id produced by the former, so exposing it alone is meaningless). Tool entries
// are also selected by the context model's type through their forModel annotation
// (entries without it are unaffected — the built-in set carries none; read_file decides
// per model at runtime through the injected vision describer).
const canSpawn = spec.subagentDepth < MAX_SUBAGENT_DEPTH;
const baseToolConfig = buildToolConfig(state);
const modelVision = modelEntry.vision !== false;
let customTools = selectBuiltinToolsForModel(baseToolConfig.customTools, modelVision);
if (!canSpawn) {
customTools = customTools.filter(
(d) =>
d.name !== SUBAGENT_NAME &&
d.name !== INPUT_SUBAGENT_NAME &&
// Legacy entry still present in stale stored configs; the registry no longer
// assembles it, this just keeps the leaf filter symmetrical.
d.name !== "kill_subagent",
);
}
const toolConfig: ToolConfig = { ...baseToolConfig, customTools };
// The context's base thinking level — the Session's tri-state pin: a value wins over
// every config; `null` — how subagent spawning says "the parent has none" — suppresses
// the config fallback entirely; only `undefined` (no pin) reads the config chain,
// against this context's State (Agent explicit > Project default_chat > built-in
// "medium", see configuredThinkingLevel). A per-request parameter, not part of the
// prefix: this is only the base the Session's live pin overrides, and nothing records it.
const pin = spec.thinkingLevel;
const thinkingLevel =
pin === null ? undefined : (pin ?? this.configuredThinkingLevel(state, projectConfig));
// Compaction config: this context's baseline. It is no longer the last word — the engine
// re-reads the section at every compaction checkpoint through `compactionReader` — but a
// context still opens on the configuration that was on disk when it opened.
const compaction = resolveCompaction(state.systemConfig.compaction, modelEntry.context_window);
// session_meta: this context's runtime configuration — the assembled prompt goes both to
// the LLM and in here, so the Trace can audit the actual effective value and a resume
// rebuilds the same request prefix; the toolset travels as the tool_list_ready event (it
// is only known once the context's MCP Servers connected).
const meta: SessionMetaPayload = {
session_id: spec.sessionId,
provider: modelEntry.provider,
model_id: modelEntry.model_id,
model_context_window: modelEntry.context_window ?? "unknown",
system_prompt: systemPrompt,
agent_state: state.stateDir,
workspace: spec.workspaceDir,
source: spec.source,
};
return {
modelEntry,
systemPrompt,
vault,
toolConfig,
commandPolicy,
thinkingLevel,
// Configured output cap: the entry's per-model annotation wins over the Agent's
// system_config value; unset inherits the Agent value. This is a ceiling, not the
// literal wire value: GenerativeModel clamps each request's effective cap to what the
// entry's context window can still fit (see llm/context-limits.ts, issue #218), so the
// seeded per-Agent default (32000) no longer needs a manual per-model override to work
// against e.g. a 32768-token window — setting the entry's `context_window` is enough.
maxTokens: modelEntry.max_tokens ?? state.systemConfig.model?.max_tokens,
requestTimeoutMs: state.systemConfig.model?.timeoutMs,
// Max turns is an Agent runtime parameter (system_config), not a Session option.
maxTurns: state.systemConfig.max_turns,
compaction,
hookPackages,
meta,
};
}
/**
* The entry `ref` names in the Project config **as it is on disk**, or undefined: the user
* picks a switch target from the models configured now, and a long-lived Agent must not
* answer from the ones configured when it loaded. The Agent's own copy follows the read, so
* what is resolved against it afterwards — a subagent spawned on the model just switched to,
* the vision model a text-only target describes images with — sees the same config.
*/
private async modelEntryOnDisk(ref: ModelRef): Promise<ModelEntry | undefined> {
this.config = await loadProjectConfig(this.state.root, this.state.projectId);
return getModel(this.config, ref);
}
/**
* Create a Session in the specified (or a temporary) Workspace.
* Docs: /docs/sessions-and-traces § "Run model".
*/
async createSession(opts: CreateSessionOptions = {}): Promise<Session> {
// Model is validated first (before creating the Workspace, so failure leaves no
// temporary workspace behind): the reference must be the complete (provider, model_id)
// pair — the config's unique key — and must name an entry in the Project config; a
// reference outside the config throws immediately rather than passing silently,
// otherwise credentials, pricing, and the context window would all be unavailable.
// Half a reference is always an error: the missing half is never inferred, since a
// guessed provider would send the entry's credential to a vendor nobody named.
if ((opts.modelId === undefined) !== (opts.provider === undefined)) {
throw new Error(
"A model reference must be given as a (provider, model_id) pair: both must be specified, or neither (to use the Project's default model).",
);
}
let ref: ModelRef;
if (opts.modelId !== undefined && opts.provider !== undefined) {
// Pair validation only (resolveModelRef): the pair either names a configured entry or errors.
ref = resolveModelRef(this.projectConfig, opts.modelId, opts.provider);
} else if (this.projectConfig.default_model) {
ref = this.projectConfig.default_model;
} else {
throw new Error(
"No modelId was specified and the Project config has no default_model. Use `penguin config model add/default` to set the default model.",
);
}
const modelEntry = getModel(this.projectConfig, ref);
if (!modelEntry) throw new Error(modelNotConfigured(ref));
// Credentials are inlined on the model entry (single config file); an explicit
// argument takes priority. With neither, the entry may lean on the environment only
// where the rule in resolveModelCredential allows (the vendor's own endpoint): a keyless
// row pointed elsewhere is refused here, before any client exists. Called for that
// refusal alone: each context's clients resolve the credential of the entry the context
// runs on (see buildRuntime's `credentialsFor`).
entryCredential(modelEntry, opts);
// An explicit Workspace must already exist as a directory: if it
// doesn't, throw rather than auto-create (to avoid a typo silently working in
// the wrong location); a temporary workspace is only created when unspecified.
let workspaceDir: string;
if (opts.workspaceDir) {
workspaceDir = path.resolve(opts.workspaceDir);
let stat;
try {
stat = await fs.stat(workspaceDir);
} catch {
throw new Error(
`Workspace does not exist: ${workspaceDir}. Specify an existing directory, or omit the Workspace to use a temporary workspace.`,
);
}
if (!stat.isDirectory()) {
throw new Error(`Workspace is not a directory: ${workspaceDir}.`);
}
} else {
workspaceDir = await createTempWorkspace(
this.state.root,
this.state.projectId,
this.state.agentId,
);
}
const sessionId = formatSessionId();
const spec: SessionSpec = {
sessionId,
workspaceDir,
creationRef: ref,
credentialOverride: { apiKey: opts.apiKey, baseUrl: opts.baseUrl },
thinkingLevel: opts.thinkingLevel,
subagentDepth: opts.subagentDepth ?? 0,
source: opts.source ?? "user",
};
// The first context: assembled from the Agent State on disk now (never from this Agent
// object's load-time snapshot — a long-lived Agent, a self-spawned subagent's for
// instance, would otherwise start Sessions on stale configuration).
const context = await this.assembleContext(spec, modelEntry);
const rt = this.buildRuntime(spec, context);
const trace = new Writer({
tracesDir: tracesDir(this.state.root, this.state.projectId, this.state.agentId),
sessionId,
});
return this.newSession(spec, context, rt, trace);
}
/**
* Resume an existing Session and continue the conversation.
*
* The resume source is the Session's **latest-index** Trace file: the Session-fixed facts
* are read from its `session_meta` (the Workspace carries over from the original Session and
* cannot be changed), the model is the one that file's `session_meta` records — a model switch
* opens its new context's file at once, so the latest file always names the model the Session
* runs on — and the context is assembled from the current Agent State, keeping the recorded
* system prompt when the file's context is still open (see below). A resume never changes the
* model on its own; switching goes through `Session.switchModel`. The replayed,
* already-committed history is injected once via AgentHub's
* setHistory (used only on resume); any leftover input is rebuilt as carry-over (paired
* fallback placeholders are synthesized in memory only, never written to the Trace).
* Messages after resume continue in the original Trace file (the file follows the
* context, not the date), and Token / turn-count stats carry over from their original
* values.
* Docs: /docs/sessions-and-traces § "Session recovery".
*/
async resumeSession(opts: ResumeSessionOptions): Promise<Session> {
const { sessionId } = opts;
const dir = tracesDir(this.state.root, this.state.projectId, this.state.agentId);
const located = await findLatestTraceFile(dir, sessionId);
if (!located) {
throw new Error(
`Session does not exist: ${sessionId} (no matching Trace file found under ${dir}).`,
);
}
const resumed = resumeTrace(await readTraceTolerant(located.path));
if (!resumed.meta) {
throw new Error(`Trace is missing session_meta and cannot be resumed: ${located.path}`);
}
const meta = resumed.meta.payload;
// Model reference is stored as a pair in session_meta; a missing provider means legacy data (no migration since the product hasn't shipped yet).
if (typeof meta.provider !== "string") {
throw new Error(
`Trace is from legacy data (session_meta is missing provider; the model reference is not split into separate fields): ${located.path}. Delete the data directory and recreate the Session.`,
);
}
// The Workspace carries over from the original Session and must still exist (throw if missing, never auto-create).
const workspaceDir = meta.workspace;
let stat;
try {
stat = await fs.stat(workspaceDir);
} catch {
throw new Error(
`The original Session's Workspace no longer exists: ${workspaceDir}; cannot resume.`,
);
}
if (!stat.isDirectory()) {
throw new Error(
`The original Session's Workspace is not a directory: ${workspaceDir}; cannot resume.`,
);
}
// The Model carries over from the Trace (the latest file's paired reference) and must still
// be present in the Project config.
const ref: ModelRef = { provider: meta.provider, model_id: meta.model_id };
const modelEntry = getModel(this.projectConfig, ref);
if (!modelEntry) {
throw new Error(
`The original Session's Model is not in the Project config: ${formatModelRef(ref)}. Use \`penguin config model add\` to configure it again before resuming.`,
);
}
// Same credential rule as createSession (see entryCredential): a key deleted since the
// Session was created surfaces here, at resume.
entryCredential(modelEntry, opts);
// No level at resume: the host re-applies its stored value (Session.thinkingLevel) when it holds one,
// and contexts opened without a pin read the Agent config's chain (the same chain
// createSession uses). The source carries over from the original session_meta (a
// resumed subagent / scheduled / CLI Session stays what it was); the on-disk value is
// untrusted and is narrowed (a Trace from before the source was required reads as
// `user`, the retired `benchmark` as `cli`, junk as `user`).
const spec: SessionSpec = {
sessionId,
workspaceDir,
creationRef: ref,
credentialOverride: { apiKey: opts.apiKey, baseUrl: opts.baseUrl },
thinkingLevel: undefined,
subagentDepth: 0,
source: normalizeSessionSource(meta.source),
};
// The context follows the Trace. A context a completed compaction closed is opened here
// for the first time — nothing was produced under any configuration yet — so it is
// assembled from the current Agent State exactly as the compaction would have opened it,
// and the rotation deferred to the first write records its meta at the new file's head.
// An open context keeps the system prompt its file recorded — the history replayed into
// it was produced under that request prefix — while its tools, Environment, vault and
// run parameters can only come from the current Agent State: the Trace records no
// executable configuration (tool definitions travel with every Request and are not part
// of the history). The thinking level is a per-request parameter, not part of the
// recorded prefix: it resolves from the pin and the config like on any other open.
const context = await this.assembleContext(
spec,
modelEntry,
resumed.contextClosed ? {} : { systemPrompt: meta.system_prompt },
);
const rt = this.buildRuntime(spec, context);
// History is injected once into the freshly built context object as part of the lazy
// bootstrap (setHistory is only used on resume); Session cumulative Token counts carry
// over the same way. The wrap keeps the descriptive error: bad tool arguments in the
// history (e.g. truncated JSON written by a third-party OpenAI-compatible endpoint)
// throw a raw SyntaxError during conversion, and the message must indicate Trace
// history corruption rather than a regular runtime error. With the bootstrap being
// lazy, that corruption now surfaces on the first run instead of at resume time —
// the price of a resume that no longer blocks on MCP connects.
const bootstrap: typeof rt.bootstrap = async (opts) => {
const r = await rt.bootstrap(opts);
if (resumed.history.length > 0) {
try {
r.llm.setHistory(resumed.history);
} catch (err) {
const detail = err instanceof Error ? err.message : String(err);
throw new Error(
`Resume failed: the Trace history could not be injected (records may be corrupted, e.g. invalid tool-argument JSON): ${detail}`,
);
}
}
return r;
};
// Continue writing to the original Trace file (the Trace only records real messages; synthesized paired placeholders are re-emitted in memory alongside carry-over).
const trace = new Writer({
tracesDir: dir,
sessionId,
dateDir: located.dateDir,
startIndex: located.index,
});
// A compaction the user quit out of (a compaction_begin with no end — the process died
// mid-request) is simply a **failed** compaction: close the span with a `failed`
// compaction_end before any new record lands, and discard whatever half-summary it had
// written — nothing is reconstructed from it (the original context is intact and the
// standing threshold makes the compaction up at the next trigger). Closing the span is
// what keeps the rest of the conversation visible: readers treat messages between the
// paired events as compaction-internal, so an unclosed span would hide everything the
// user sends afterwards, and tool outputs whose calls it swallowed would render as
// "unknown tool" cards (issue #288). Best-effort like every Trace write: a failure here
// must not block the resume itself.
if (resumed.danglingCompaction) {
try {
await trace.write(compactionEnd({ ...resumed.danglingCompaction, status: "retryable" }));
} catch (err) {
const detail = err instanceof Error ? err.message : String(err);
process.stderr.write(`[trace] interrupted-compaction closure failed: ${detail}\n`);
}
}
return this.newSession(spec, context, rt, trace, {
bootstrap,
// session_meta is already in the original Trace file, so it isn't rewritten; on the first write after a compaction-triggered rotation, the file is split first.
metaAlreadyWritten: true,
initialEngineState: {
carryOver: resumed.carryOver,
...(resumed.pendingSummary ? { pendingSummary: resumed.pendingSummary } : {}),
...(resumed.openingSummary ? { openingSummary: resumed.openingSummary } : {}),
sessionTurns: resumed.sessionTurns,
sessionTokens: resumed.sessionTokens,
lastRequestTotal: resumed.lastRequestTotal,
pendingTraceRotation: resumed.contextClosed,
// A closed context is one a completed compaction opened: the same fact drives the
// deferred Trace rotation above and the "just compacted" compaction reason, but they
// are separate meanings and stay separate fields. A file past the first was opened by
// a compaction too, so one with no completed turn yet — a model switch's eagerly opened
// file, or any new context the process died in before its first answer — is just as
// freshly compacted (read structurally, from the index, never from its records).
fromCompaction: resumed.contextClosed || (located.index > 1 && resumed.sessionTurns === 0),
},
resumedHistory: resumed.renderMessages,
});
}
/**
* The Session's live compaction reader: what takes `compaction` out of the set of settings
* a model context freezes when it opens. The engine calls it at every compaction checkpoint,
* so a threshold, turn count, mode or prompt saved to the Agent's `system_config.yaml`
* reaches the conversation that is running instead of waiting for the next rotation.
*
* Cached by the file's identity on disk, so an unchanged file costs one `stat` per checkpoint
* and nothing else. Three fields, because no one of them is enough: the inode number changes
* whenever the config is saved through `atomicWriteFile` (a temp file renamed over the name,
* which is also why a reader never sees a half-written config), while an in-place rewrite
* keeps the inode and is caught by the nanosecond mtime — `mtimeMs` alone cannot separate two
* saves inside the same millisecond, and a threshold dragged in the Web App can produce
* exactly that. Size is the cheap third opinion for a filesystem with a coarse clock.
*
* Only the `compaction` section is honoured here. Everything else in the config is strict
* tier and belongs to the context that was assembled from it; reading the file is not
* licence to apply the rest of it mid-context.
*
* The model's context window comes from the running context's entry (`contextWindow`, a
* getter because an in-session model switch moves it), so one reader serves every context
* the Session opens and caps the threshold against the model that is running. A parse that
* fails throws: the engine keeps the settings in force and warns once, which is the right
* answer for a file being rewritten badly.
*/
private compactionReader(
contextWindow: () => number | undefined,
): () => Promise<CompactionSettings> {
const { root, projectId, agentId } = this.state;
const configPath = systemConfigPath(root, projectId, agentId);
let cachedKey: string | null = null;
let cached: CompactionSettings | null = null;
return async (): Promise<CompactionSettings> => {
const stat = await fs.stat(configPath, { bigint: true });
const window = contextWindow();
const key = `${stat.mtimeNs}:${stat.size}:${stat.ino}:${window ?? "unknown"}`;
if (cached !== null && key === cachedKey) return cached;
const parsed = parseYaml(await fs.readFile(configPath, "utf8")) as unknown;
if (parsed === null || typeof parsed !== "object") {
throw new Error(`Invalid Agent State config: ${configPath} is empty or corrupted.`);
}
cached = resolveCompaction((parsed as SystemConfig).compaction, window);
cachedKey = key;
return cached;
};
}
/**
* Constructs the Session for `spec` running on `context` — the one assembly behind
* createSession and resumeSession, so initialization and resumption cannot drift apart.
* `extras` carries the resume-only fields (its history-injecting bootstrap wrapper, the
* replay-derived engine state); spread last, so an override there wins.
*/
private newSession(
spec: SessionSpec,
context: AssembledContext,
rt: SessionRuntime,
trace: Writer,
extras: Partial<SessionConfig> = {},
): Session {
const { root, projectId, agentId } = this.state;
return new Session({
meta: context.meta,
bootstrap: rt.bootstrap,
cancelBootstrap: () => rt.environment.cancelMcpConnect(),
environment: rt.environment,
trace,
openNextContext: rt.openNextContext,
// The first context's hooks; each context `openNextContext` opens brings its own.
hooks: this.sessionHooks(rt.subagentRunner, context.hookPackages, spec),
createBareLLM: rt.createBareLLM,
compaction: context.compaction,
// Live tier: the baseline above is what this context opened on, and this is how every
// checkpoint after it asks the disk again.
readCompaction: this.compactionReader(rt.contextWindow),
// Where an input image lands when it becomes a path line (see SessionConfig.imagesDir).
imagesDir: sessionScratchpadDir(root, projectId, agentId, spec.sessionId),
modelHasVision: context.modelEntry.vision !== false,
modelSwitch: rt.modelSwitch,
...(context.maxTurns !== undefined ? { maxTurns: context.maxTurns } : {}),
// Sandbox command policy, strict-tier like the rest of the context (though
// Project-owned, never Agent State): read from disk when each context opens, so an
// edit applies at the Session's next rotation. Absent config means the factory rule
// set, on. Tool permissions need no seam of their own: Session.toolPermission
// answers from the Environment's toolset, which each rotation re-equips.
commandPolicy: rt.commandPolicy,
...extras,
});
}
/** Id of the most recent Session under the current Agent (determined by the timestamp in session_id); returns null if there is no Session. */
async latestSessionId(): Promise<string | null> {
return latestTraceSessionId(
tracesDir(this.state.root, this.state.projectId, this.state.agentId),
);
}
/**
* Assembles a Session's runtime components (shared by createSession and resumeSession)
* around the context it starts in — see {@link SessionRuntime} for what each part does.
*/
private buildRuntime(spec: SessionSpec, initial: AssembledContext): SessionRuntime {
const { sessionId, workspaceDir, subagentDepth } = spec;
// The context the Session is running: the initial one, then whatever `openNextContext` last
// opened (or a never-run Session's model switch re-assembled, see `modelSwitch` below). Its
// model entry is the model the Session is on.
let current = initial;
// The host's per-request credential resolver for one entry (see
// AgentAssembly.resolveModelApiKey), when the host supplies one.
const apiKeyResolverFor = (entry: ModelEntry): Pick<GenerativeModelConfig, "resolveApiKey"> =>
this.assembly?.resolveModelApiKey
? {
resolveApiKey: () =>
this.assembly!.resolveModelApiKey!({
projectId: this.state.projectId,
agentId: this.state.agentId,
sessionId,
provider: entry.provider,
modelId: entry.model_id,
}),
}
: {};
// The credentials a context's LLM objects run on: the caller's explicit override for the
// entry it was given for (the creation model), every other entry's own configured pair —
// under the one credential rule (see entryCredential), so a keyless entry pointed away
// from its vendor is refused here too — plus the host's resolver for that entry.
const credentialsFor = (
entry: ModelEntry,
): Pick<GenerativeModelConfig, "apiKey" | "baseUrl" | "resolveApiKey"> => ({
...entryCredential(
entry,
sameModelRef(entry, spec.creationRef) ? spec.credentialOverride : {},
),
...apiKeyResolverFor(entry),
});
// Child-Agent runner: injected into the run_subagent tool so it doesn't need to
// depend on Agent/Session (breaking a circular dependency). The model can
// optionally choose agentId (omitted = call the current Agent), the child
// Session's model (omitted = the parent Session's model), and its thinking level
// (omitted = the parent Session's effective level); an explicit model reference
// is forwarded to createSession as-is and must be a complete (provider, model_id)
// pair — half a reference is rejected there rather than being guessed here. Precheck
// errors (depth limit exceeded / agent doesn't exist) are expressed as throws, which
// the Environment collapses to failed.
// Docs: /docs/interfaces § "Subagent interfaces"
const parentAgent = this;
const { root, projectId, agentId: parentAgentId } = this.state;
const subagentRunner: SubagentRunner = {
// Spawn and run are separate: the same child Session can run for multiple turns
// (continuing via input_subagent appending a prompt); resource cleanup is
// consolidated in handle.dispose (called by the managing ManagedSubagentSession).
async spawn({ agentId, modelId, provider, thinkingLevel: spawnThinkingLevel }) {
if (subagentDepth >= MAX_SUBAGENT_DEPTH) {
throw new Error(
`subagent depth limit ${MAX_SUBAGENT_DEPTH} reached; not spawning another subagent`,
);
}
if (agentId !== undefined && agentId !== parentAgentId) {
try {
assertValidId("agent_id", agentId);
await fs.access(systemConfigPath(root, projectId, agentId));
} catch {
throw new Error(
`subagent error: agent "${agentId}" does not exist or is not accessible`,
);
}
}
const childAgent =
agentId !== undefined && agentId !== parentAgentId
? await createAgent({
root,
projectId,
agentId,
// A child Agent loads its own vault/config, but the proxy-env, control-env
// and spawn-confinement getters are host policy, not Agent state: the
// subagent's commands run in the same serving process, so they follow the
// same settings as the parent's — controlEnv is then evaluated with the
// child Session's own coordinates.
...(parentAgent.proxyEnv ? { proxyEnv: parentAgent.proxyEnv } : {}),
...(parentAgent.controlEnv ? { controlEnv: parentAgent.controlEnv } : {}),
...(parentAgent.pathPrepend ? { pathPrepend: parentAgent.pathPrepend } : {}),
...(parentAgent.confineSpawn ? { confineSpawn: parentAgent.confineSpawn } : {}),
...(parentAgent.assembly ? { assembly: parentAgent.assembly } : {}),
})
: parentAgent;
// The child Session follows the PARENT Session, never the Project default: with the
// model pair fully omitted it reuses the parent's CURRENT (provider, model_id) — the
// model the parent's running context is on, after any in-session switch — the same
// Project-config entry, so max_tokens / context_window / vision follow
// automatically. An explicit pair still wins, and half a pair is forwarded as-is so
// createSession rejects it (never silently completed from the parent's here).
const childModel =
modelId === undefined && provider === undefined
? { modelId: current.modelEntry.model_id, provider: current.modelEntry.provider }
: {
...(modelId !== undefined ? { modelId } : {}),
...(provider !== undefined ? { provider } : {}),
};
// An explicit spawn-time level (run_subagent's `thinking_level`) pins the child;
// otherwise the parent Session's creation-time level, else the base its running
// context opened with, is passed down as a tri-state: `null` when the parent has
// none, so the child never falls back to its own Agent config (which would apply on
// a cross-agent spawn). A mid-session `Session.thinkingLevel` assignment is engine
// state and is not inherited — the spawn argument exists for explicit control.
const parentLevel =
spec.thinkingLevel === undefined ? current.thinkingLevel : spec.thinkingLevel;
const childSession = await childAgent.createSession({
workspaceDir,
...childModel,
thinkingLevel: spawnThinkingLevel ?? parentLevel ?? null,
subagentDepth: subagentDepth + 1,
source: "subagent",
});
return subagentHandleFor(childSession);
},
// Revival: a RELEASED child session resumes with its own history, model and Workspace
// (resumeSession semantics) — reached by the panel and by input_subagent on a released
// id alike. The owning Agent comes from the caller's record (the host's session
// registry, or the spawn-time tombstone); omitted or self-owned reuses the parent
// Agent instance.
async resume({ agentId, sessionId }) {
if (agentId !== undefined) assertValidId("agent_id", agentId);
const childAgent =
agentId === undefined || agentId === parentAgentId
? parentAgent
: await createAgent({
root,
projectId,
agentId,
...(parentAgent.proxyEnv ? { proxyEnv: parentAgent.proxyEnv } : {}),
...(parentAgent.controlEnv ? { controlEnv: parentAgent.controlEnv } : {}),
...(parentAgent.pathPrepend ? { pathPrepend: parentAgent.pathPrepend } : {}),
...(parentAgent.confineSpawn ? { confineSpawn: parentAgent.confineSpawn } : {}),
...(parentAgent.assembly ? { assembly: parentAgent.assembly } : {}),
});
const childSession = await childAgent.resumeSession({ sessionId });
return subagentHandleFor(childSession);
},
};
/**
* Wraps a child Session as a SubagentHandle — shared by spawn and resume. All
* child-session messages are tagged with an origin (the child Session id, prepended as
* one hop from outer to inner); the first turn forwards the child's session_meta first
* (including agent_state and other metadata) so the parent frontend can recognize the
* nested session (for rendering, stats, approval visibility); the parent Trace skips
* these accordingly (the child Session has its own Trace, linked by session id).
*/
function subagentHandleFor(childSession: Session): SubagentHandle {
const hop: MessageOrigin = childSession.sessionId;
let metaSent = false;
return {
sessionId: hop,
// One-shot upfront meta for background launches (see SubagentHandle.takeMeta):
// shares metaSent with run, so the meta reaches the parent stream exactly once
// whichever side sends it first.
takeMeta() {
if (metaSent) return null;
metaSent = true;
return withOrigin(childSession.metaMessage, hop);
},
async *run({ messages, signal, approve }) {
if (!metaSent) {
metaSent = true;
yield withOrigin(childSession.metaMessage, hop);
}
// Pass through the parent's approval callback: the child Session inherits
// the parent Agent's approval mode (with no callback, the child engine
// defaults to deny). The tool_call received for approval also carries the
// origin, so the approval UI can identify which tool a subagent is calling.
const childApprove = approve
? (tc: OmniMessage<ToolCallPayload>) => approve(withOrigin(tc, hop))
: undefined;
// The engine writes a run's input to the CHILD's own Trace but never replays
// it to its consumer (a session's normal caller typed that input itself) —
// here the consumer is the PARENT, whose frontend has never seen the child's
// prompt. Forward the input messages themselves (origin-tagged, ahead of the
// run's output) so the live nested view shows the child's user side exactly
// like a reloaded one (history expansion splices the child Trace, which
// carries these same messages). The parent engine drops origin messages from
// the parent Trace, so replay never duplicates them. Later rounds
// (input_subagent follow-up prompts, a host panel's message) come through this
// same generator and are forwarded the same way.
// The caller owns each message's `sender` — "parent_agent" for the model's own
// dispatch, none for a human's message from a host panel — so the child's Trace
// records who actually spoke.
for (const input of messages) yield withOrigin(input, hop);
// Manual iteration so the child run's return value — whether the round was cut
// off — propagates to the handle's own return for the parent's round report.
const it = childSession.run(messages, {
...(signal ? { signal } : {}),
...(childApprove ? { approve: childApprove } : {}),
});
for (;;) {
const res = await it.next();
if (res.done) return res.value;
yield withOrigin(res.value, hop);
}
},
// Mid-run steering rides the child Session's own steering queue — the same
// mechanism a user steers the main session with. The queued message keeps its
// caller-chosen sender ("parent_agent" from input_subagent, none from a human
// panel), and the delivered [user_steering] message streams back out through
// `run` with the origin hop like every other child message.
steer(messages) {
return childSession.steer(messages);
},
setThinkingLevel(level) {
childSession.thinkingLevel = level;
},
dispose() {
childSession.dispose();
},
};
}
// When a context's model doesn't support images (vision=false): inject a vision model
// service for read_file's image branch — images are described by the Project config's
// vision_model (a paired reference), and the tool returns text instead of image content.
// Even when unconfigured or invalid, it is still injected (modelId=null): its presence is
// what tells read_file the session model cannot view images; the tool then finishes with a
// failed explanation, and images are never allowed into that session's history. Decided
// per context (a model switch can move to or from a text-only model): the Environment is
// handed the answer for each context it is equipped for.
const visionDescriberFor = (entry: ModelEntry): VisionDescriberService | undefined => {
if (entry.vision !== false) return undefined;
const visionRef = this.projectConfig.vision_model;
const visionEntry = visionRef ? getModel(this.projectConfig, visionRef) : undefined;
if (!visionEntry || visionEntry.vision === false) return { modelId: null };
return {
// The model attribution in the tool output matches the request's source: both are the entry's upstream model_id.
modelId: visionEntry.model_id,
// Resolved on each call rather than once here: the same credential rule as the
// session model (a keyless entry pointed away from its vendor is refused), and a
// refusal is a failed read_file, not a failed Session.
createLLM: () =>
new GenerativeModel({
modelId: visionEntry.model_id,
...entryCredential(visionEntry, {}),
...apiKeyResolverFor(visionEntry),
...(visionEntry.client_type !== undefined
? { clientType: visionEntry.client_type }
: {}),
tools: [],
thinkingLevel: "none",
// The describing budget, tightened by the vision entry's own pinned cap when smaller.
maxTokens: metaMaxTokens(2048, visionEntry.max_tokens),
// Same window derivation as ordinary requests (a formality here: the meta
// budget is far below any real window, so the clamp never binds).
...(visionEntry.context_window !== undefined
? { contextWindow: visionEntry.context_window }
: {}),
sessionId,
requestTimeoutMs: 60_000,
}),
};
};
const visionDescriber = visionDescriberFor(initial.modelEntry);
// Environment binds the Workspace for the Session's lifetime and is equipped with the
// initial context's tool config and vault (a later context re-equips it, see
// openNextContext). The toolset is resolved lazily by the bootstrap below (Session's first
// run), not here — its first listTools connects any configured MCP Servers, and that
// wait belongs on the run stream (bracketed by mcp_connect events), not inside
// createSession. Vault environment variables are injected into command subprocesses; a
// child Agent loads **its own** vault via createAgent rather than inheriting the
// parent's.
const environment = new Environment({
workspaceDir,
toolConfig: initial.toolConfig,
// The Session's generic scratchpad root; Environment derives its truncated-tool-output
// recovery directory from it.
sessionScratchpadDir: sessionScratchpadDir(
this.state.root,
this.state.projectId,
this.state.agentId,
sessionId,
),
services: { subagentRunner, ...(visionDescriber ? { visionDescriber } : {}) },
...(Object.keys(initial.vault).length > 0 ? { vault: initial.vault } : {}),
...(this.proxyEnv ? { proxyEnv: this.proxyEnv } : {}),
// The control-env policy is bound to THIS Session's coordinates here (sessionId is
// final by now); the getter shape keeps it re-evaluated at every command spawn, so
// the host can rotate what it injects (e.g. its API token) without a rebuild.
...(this.controlEnv
? {
controlEnv: () =>
this.controlEnv!({
projectId: this.state.projectId,
agentId: this.state.agentId,
sessionId,
}),
}
: {}),
...(this.pathPrepend ? { pathPrepend: this.pathPrepend } : {}),
// Bound to THIS Session's coordinates like controlEnv: the host may confine each
// Session under its own policy, and the getter is still re-read at every spawn.
...(this.confineSpawn
? {
confineSpawn: () =>
this.confineSpawn!({
projectId: this.state.projectId,
agentId: this.state.agentId,
sessionId,
}),
}
: {}),
});
// The tool_call_id uniqueness registry is shared by every context's LLM object: its
// uniqueness scope is the Session's whole render span, so same-named tool calls after
// compaction don't collide with earlier cards' ids.
const toolCallIds = new ToolCallIdAllocator();
// The LLM object of one context: the context's model entry and its credentials, plus the
// context's prompt, toolset and model defaults. The model id sent to AgentHub is always
// the entry's upstream `model_id` (client_type inference/passing follows it);
// session_meta, Trace, usage, pricing, and catalog matching all use the (provider,
// model_id) pair as the primary key.
const buildLLM = (context: AssembledContext, tools: ToolDefinition[]): GenerativeModel => {
const entry = context.modelEntry;
// The seller's per-request image cap, from the catalog (Abliteration's is 4): a
// conversation that accumulates pictures would otherwise fail every later request.
const imageLimit = catalogImageLimit(entry.provider, entry.model_id);
// Video input is opt-in per model (the opposite default of vision): either the Project's
// row carries the catalog's `video` annotation, or the catalog itself records it — the
// second answer covers a Project whose presets predate the row and has not synced since.
// One video per request: the budget exists to keep a replayed conversation's body inside
// the provider's limit, and the video that matters is the newest one.
const videoLimit =
entry.video === true || catalogSupportsVideo(entry.provider, entry.model_id)
? 1
: undefined;
return new GenerativeModel({
modelId: entry.model_id,
toolCallIds,
...credentialsFor(entry),
...(entry.client_type !== undefined ? { clientType: entry.client_type } : {}),
tools,
systemPrompt: context.systemPrompt,
...(entry.context_window !== undefined ? { contextWindow: entry.context_window } : {}),
...(imageLimit !== undefined ? { maxImages: imageLimit } : {}),
...(videoLimit !== undefined ? { maxVideos: videoLimit } : {}),
...(context.maxTokens !== undefined ? { maxTokens: context.maxTokens } : {}),
// Fast mode is a session-request annotation: it rides every context's LLM object,
// while the bare/meta LLM below and the vision describer deliberately skip it — their
// background requests gain nothing user-facing from a premium tier, and skipping
// keeps them working (titles included) even while the annotation is enabled on a
// model that rejects it.
...(entry.fast_mode === true ? { fastMode: true } : {}),
...(context.thinkingLevel !== undefined ? { thinkingLevel: context.thinkingLevel } : {}),
sessionId,
...(context.requestTimeoutMs !== undefined
? { requestTimeoutMs: context.requestTimeoutMs }
: {}),
});
};
// THE opening procedure — behind the first run's bootstrap and every post-compaction
// openNextContext alike, so initialization and rotation cannot drift apart: connects
// whatever MCP Servers are still pending on the Environment (publishing the connect
// pair around the wait when there are any — at the first open that is every configured
// server), resolves the toolset, publishes the toolset record, and builds the context's
// LLM object. The caller's `emit` decides where the records go live (the Session's
// first-run pump, or the engine's rotation pump).
const openAssembled = async (
context: AssembledContext,
emit: OpenContextOptions["emit"],
): Promise<{ llm: GenerativeModel }> => {
const pending = environment.pendingMcpServerNames();
if (pending.length > 0) emit(mcpConnectBegin(pending));
const tools = await environment.listTools();
if (pending.length > 0) {
emit(mcpConnectEnd(mcpConnectOutcome(environment.mcpConnectResults())));
}
emit(toolListReady(tools));
return { llm: buildLLM(context, tools) };
};
// The first context's opener (see SessionRuntime.bootstrap).
const bootstrap = async (opts: OpenContextOptions): Promise<{ llm: GenerativeModel }> =>
openAssembled(current, opts.emit);
// Equips the Environment for a context: its toolset (selected for its model's type), its
// vault, and the vision answer read_file needs.
const equip = (context: AssembledContext): void =>
environment.reconfigure({
toolConfig: context.toolConfig,
vault: context.vault,
visionDescriber: visionDescriberFor(context.modelEntry) ?? null,
});
// What an assembled context tells the Session and its engine beyond its LLM (see
// SessionOpenedContext): its meta and engine settings, its vision answer, and the hooks
// it runs with.
const contextFacts = (context: AssembledContext): Omit<SessionOpenedContext, "llm"> => ({
sessionMeta: sessionMeta(context.meta),
maxTurns: context.maxTurns ?? -1,
compaction: context.compaction,
modelHasVision: context.modelEntry.vision !== false,
hooks: this.sessionHooks(subagentRunner, context.hookPackages, spec),
});
// A switch target's entry once the switch is under way (the opener, or the never-run
// re-assembly): validated a moment ago, so one that is gone by now is a failure, not the
// refusal `modelSwitch.validate` answers with.
const switchTargetEntry = async (ref: ModelRef): Promise<ModelEntry> => {
const entry = await this.modelEntryOnDisk(ref);
if (!entry) throw new Error(modelNotConfigured(ref));
return entry;
};
// The context that follows a completed compaction: assembled anew from the Agent State
// as it is now — an edit the model (or the user) made during the old context to
// AGENTS.md, system_config.yaml, the vault, the Skills or the MCP Servers lands here —
// on the model the closing context ran on, or on the one a model switch names
// (`modelRef`, resolved against the Project config on disk). The Environment is
// re-equipped with the new toolset and vault, then the context is opened by the same
// procedure as the first one — the engine yields the published records live and writes
// them at the head of the rotated Trace file. An Agent State that cannot be assembled (a
// config that no longer parses) throws: the run fails with that error and the engine
// keeps the old context. So does this layer when the open itself fails: `current` moves
// only once the context is open, and the Environment goes back to the running one.
const openNextContext = async ({
emit,
modelRef,
}: SessionOpenContextOptions): Promise<SessionOpenedContext> => {
const entry = modelRef ? await switchTargetEntry(modelRef) : current.modelEntry;
const next = await this.assembleContext(spec, entry);
equip(next);
let llm: GenerativeModel;
try {
({ llm } = await openAssembled(next, emit));
} catch (err) {
equip(current);
throw err;
}
current = next;
return { llm, ...contextFacts(next) };
};
// Bare LLM for one-off out-of-band requests (meta requests like generateTitle): the
// running context's Model/credentials (or the given entry's), no tools, no system prompt,
// thinking disabled, a small output cap, and an independent timeout.
const createBareLLM = (entry: ModelEntry = current.modelEntry): GenerativeModel =>
new GenerativeModel({
modelId: entry.model_id,
...credentialsFor(entry),
...(entry.client_type !== undefined ? { clientType: entry.client_type } : {}),
tools: [],
thinkingLevel: "none",
// The meta budget, tightened by the entry's pinned per-model cap when smaller.
maxTokens: metaMaxTokens(300, entry.max_tokens),
// Same window derivation as ordinary requests (a formality here: the meta budget
// is far below any real window, so the clamp never binds).
...(entry.context_window !== undefined ? { contextWindow: entry.context_window } : {}),
sessionId,
requestTimeoutMs: 30_000,
});
// Credential validation stays at Session-creation time even though the session LLM is
// built lazily now: provider SDKs throw at **client construction** when a credential
// is missing (e.g. OpenAI-protocol models without apiKey/OPENAI_API_KEY), and hosts
// map that into their clean "credential missing" error before any Session or Trace
// exists. Constructing the bare LLM (same credentials, no tools, no network) keeps
// that throw here; the instance is discarded.
createBareLLM();
// The composition layer's half of an in-session model switch (see Session.switchModel):
// the target is validated exactly as a creation model is — configured on disk, credential
// present at client construction — before anything is sent or recorded; a Session that
// never ran has its first context assembled again on the target, which the bootstrap then
// opens like any first context.
const modelSwitch: ModelSwitchSupport = {
validate: async (ref) => {
const entry = await this.modelEntryOnDisk(ref);
if (!entry)
throw new ModelSwitchRefusedError("model_not_configured", modelNotConfigured(ref));
try {
createBareLLM(entry);
} catch (err) {
// A configured target whose client cannot be built — a missing credential foremost:
// a refusal with the loader's own wording, not a failure of the switch.
throw new ModelSwitchRefusedError(
"model_unavailable",
err instanceof Error ? err.message : String(err),
);
}
},
reassembleInitialContext: async (ref) => {
const next = await this.assembleContext(spec, await switchTargetEntry(ref));
equip(next);
current = next;
return contextFacts(next);
},
};
return {
environment,
bootstrap,
openNextContext,
commandPolicy: () => current.commandPolicy,
contextWindow: () => current.modelEntry.context_window,
modelSwitch,
createBareLLM,
subagentRunner,
};
}
/**
* The hooks a model context runs with, built from the hook packages it was assembled with
* (see AssembledContext.hookPackages): each command run as a script (hooks/script-hook.ts),
* plus the spawner that honors a stop hook's `subagent` answer — a detached child Session
* of this Agent (or the one it names) whose stream is dropped (its own Trace is the
* record) and which inherits the run's approval callback.
*
* Always a whole set, empty lists included: the Session replaces its hooks with it when
* the context opens, which is how uninstalling the last package reaches a conversation
* that is running. This is the one place a Session's hooks are assembled.
*/
private sessionHooks(
runner: SubagentRunner,
installed: readonly InstalledHook[],
spec: SessionSpec,
): SessionHooks {
const { root, projectId, agentId } = this.state;
const ctx: ControlEnvContext = { projectId, agentId, sessionId: spec.sessionId };
// A hook script is spawned the way a command is: the same PATH front (see
// CreateAgentOptions.pathPrepend — only the environment half applies, a hook is run
// as `node <script>` with no shell to re-order PATH afterwards), and the same sandbox
// (CreateAgentOptions.confineSpawn, bound to this Session's coordinates and re-read
// at every run), with the Session's Workspace and scratchpad as its scope.
const options: ScriptHookOptions = {
...(this.pathPrepend ? { pathPrepend: this.pathPrepend } : {}),
...(this.confineSpawn ? { confineSpawn: () => this.confineSpawn!(ctx) } : {}),
scope: {
workspaceDir: spec.workspaceDir,
scratchpadDir: sessionScratchpadDir(root, projectId, agentId, spec.sessionId),
},
};
const withTimeout = (timeoutS: number | undefined): ScriptHookOptions => ({
...options,
...(timeoutS !== undefined ? { timeoutS } : {}),
});
const stop = installed.flatMap((hook) =>
hook.stop.map((cmd) =>
scriptStopHook(hook.name, hook.dir, cmd.command, withTimeout(cmd.timeout)),
),
);
const preToolUse = installed.flatMap((hook) =>
hook.pre_tool_use.map((cmd) =>
scriptPreToolUseHook(hook.name, hook.dir, cmd.command, withTimeout(cmd.timeout)),
),
);
const userPrompt = installed.flatMap((hook) => {
remindToUpdate(hook);
return hook.user_prompt.map((cmd) =>
scriptUserPromptHook(hook.name, hook.dir, cmd.command, {
...withTimeout(cmd.timeout),
trigger: userPromptTrigger(hook.version, cmd),
}),
);
});
return {
stop,
preToolUse,
userPrompt,
spawnSubagent: async (request: HookSubagentRequest, approve?: ApproveFn) => {
const handle = await runner.spawn({
...(request.agentId !== undefined ? { agentId: request.agentId } : {}),
});
// The child's upfront session_meta goes back to the Session, which streams it behind
// the hook event so a host registers the child session (a row, a place in the
// subagent listing) the way it does a tool-spawned one; the detached run then skips
// its own meta forwarding.
const meta = handle.takeMeta?.() ?? null;
runDetached(handle, [userText(request.prompt, "harness")], approve);
return { sessionId: handle.sessionId, meta };
},
};
}
}
/** Package directories already named by {@link remindToUpdate} in this process. */
const remindedPackages = new Set<string>();
/**
* COMPAT (remove at 0.3.0 release preparation, together with the rule it reports — see
* plugins' userPromptTrigger): says once per process, per package directory, that an
* installed package predates `user_prompt` commands running on every Prompt and is being
* read the old way. The user-facing reminder is the plugin library's update notice; this
* line is for whoever reads the host's log.
*/
function remindToUpdate(hook: InstalledHook): void {
if (!predatesEveryPromptHooks(hook.version)) return;
if (!hook.user_prompt.some((cmd) => cmd.trigger === undefined)) return;
if (remindedPackages.has(hook.dir)) return;
remindedPackages.add(hook.dir);
process.stderr.write(
`[hooks] ${hook.name} ${hook.version} (${hook.dir}) predates user_prompt hooks running on every prompt: its user_prompt commands run only when the host starts them by name. Update the package from the plugin library; this compatibility reading ends with 0.3.0.\n`,
);
}
/** Drives a hook-spawned child to completion in the background, dropping its stream (its own Trace is the record), and releases it. */
function runDetached(handle: SubagentHandle, messages: OmniMessage[], approve?: ApproveFn): void {
void (async () => {
try {
const it = handle.run({ messages, ...(approve ? { approve } : {}) });
for (;;) {
const res = await it.next();
if (res.done) break;
}
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
process.stderr.write(`[hooks] subagent ${handle.sessionId} failed: ${message}\n`);
} finally {
handle.dispose();
}
})();
}