A local-first multi-agent app development platform, built on PenguinHarness
/**
* Agent.createSession's Workspace handling and vault injection (no network needed; only
* constructs the Session, never sends a request).
*
* Regression: an explicitly given Workspace must be an existing directory. When it
* does not exist, a clear error must be thrown rather than auto-creating it, and bash must not
* be started with an invalid cwd after Session creation, which would throw a misleading
* `spawn bash ENOENT`. A temporary workspace is only created when no Workspace is specified.
*
* vault: the Agent vault's (agent_state/.vault.toml) **key names** are
* injected into the assembled system prompt; values are never injected.
*/
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
import type { OmniMessage } from "../src/omnimessage/index.js";
import type { ModelRef, OpenContextOptions, OpenedContext, SystemConfig } from "../src/index.js";
import {
agentsMdPath,
hooksDir,
projectConfigPath,
skillsDir,
systemConfigPath,
tracesDir,
} from "../src/state/paths.js";
import {
MODEL_CATALOG,
addModel,
createAgent,
DEFAULT_AGENT_ID,
DEFAULT_PROJECT_ID,
imageUrlMessage,
installSkill,
loadProjectConfig,
ModelSwitchRefusedError,
saveProjectConfig,
setVaultEntry,
userText,
} from "../src/index.js";
import { metaMaxTokens } from "../src/agent.js";
import { findLatestTraceFile, readTrace } from "../src/trace/index.js";
import { mapThinkingLevel } from "../src/llm/index.js";
import { stubProviderKeys } from "./provider-keys.js";
import type {
EnvironmentConfig,
EnvironmentServices,
SubagentRunner,
} from "../src/interfaces/index.js";
// Captures the services buildRuntime hands to each Environment, so tests can drive the REAL
// subagent runner (the spawn closure in agent.ts). Spawning only constructs the child Session,
// and pulling a single message from handle.run yields the child session_meta before any LLM
// request is issued — no network is ever touched. The wrapper is otherwise transparent, so
// every other test in this file behaves as with the real class.
const capturedEnvServices = vi.hoisted(() => ({ list: [] as unknown[] }));
vi.mock("../src/environment/index.js", async (importOriginal) => {
const mod = await importOriginal<typeof import("../src/environment/index.js")>();
class CapturingEnvironment extends mod.Environment {
constructor(config: EnvironmentConfig) {
super(config);
capturedEnvServices.list.push(config.services);
}
}
return { ...mod, Environment: CapturingEnvironment };
});
// Captures every GenerativeModelConfig buildRuntime constructs: the effective thinking level
// is no longer observable through session_meta (it holds invariants only) — assertions read
// the construction default from the captured config instead.
const capturedLLMConfigs = vi.hoisted(() => ({ list: [] as { thinkingLevel?: string }[] }));
vi.mock("../src/llm/index.js", async (importOriginal) => {
const mod = await importOriginal<typeof import("../src/llm/index.js")>();
class CapturingGenerativeModel extends mod.GenerativeModel {
constructor(config: ConstructorParameters<typeof mod.GenerativeModel>[0]) {
super(config);
capturedLLMConfigs.list.push(config as { thinkingLevel?: string });
}
}
return { ...mod, GenerativeModel: CapturingGenerativeModel };
});
let tmpRoot: string;
let prevHome: string | undefined;
let restoreKeys: () => void;
beforeEach(async () => {
prevHome = process.env.PENGUIN_HOME;
tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), "penguin-harness-"));
process.env.PENGUIN_HOME = tmpRoot;
restoreKeys = stubProviderKeys();
});
afterEach(async () => {
if (prevHome === undefined) delete process.env.PENGUIN_HOME;
else process.env.PENGUIN_HOME = prevHome;
restoreKeys();
await fs.rm(tmpRoot, { recursive: true, force: true });
});
// effectiveMaxContextLength moved to llm/context-limits.ts; its derivation (window-derived
// compaction threshold, issue #218) is covered in test/context-limits.test.ts.
/**
* Edits the default Agent's on-disk `system_config.yaml`: a Session runs on the Agent State as
* it is on disk when each of its model contexts opens, never on the Agent object's load-time
* snapshot — so a test that wants a config to take effect writes it here.
*/
async function patchSystemConfig(patch: (cfg: SystemConfig) => void): Promise<void> {
const file = systemConfigPath(tmpRoot, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID);
const cfg = parseYaml(await fs.readFile(file, "utf8")) as SystemConfig;
patch(cfg);
await fs.writeFile(file, stringifyYaml(cfg), "utf8");
}
/** Drains the session's lazy first-run bootstrap so the engine (and its LLM) exists for inspection. */
async function bootstrapped(session: unknown): Promise<void> {
const gen = (session as { ensureReady(): AsyncGenerator<unknown> }).ensureReady();
for await (const _ of gen) {
// drain: the bootstrap's own events aren't under test here
}
}
describe("metaMaxTokens (meta-request budget tightened by the per-model cap)", () => {
it("keeps the budget unless the per-model cap is smaller; never raises it", () => {
expect(metaMaxTokens(300, undefined)).toBe(300); // no per-model cap: the budget as-is
expect(metaMaxTokens(300, 8000)).toBe(300); // ample cap: the small budget stays
expect(metaMaxTokens(300, 128)).toBe(128); // pinned below the budget: the cap binds
expect(metaMaxTokens(2048, 1024)).toBe(1024); // vision-describer budget, same rule
expect(metaMaxTokens(300, -1)).toBe(300); // -1 = uncapped: never tightens to -1 (issue #55 sibling)
});
});
describe("Agent.createSession workspace handling", () => {
it("throws a clear error when the given workspace does not exist (no auto-create)", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "nested", "does-not-exist");
await expect(agent.createSession({ workspaceDir: ws })).rejects.toThrow(/does not exist/);
// Must not be auto-created.
await expect(fs.stat(ws)).rejects.toThrow();
});
it("throws when the given workspace path is not a directory", async () => {
const agent = await createAgent();
const filePath = path.join(tmpRoot, "a-file");
await fs.writeFile(filePath, "x", "utf8");
await expect(agent.createSession({ workspaceDir: filePath })).rejects.toThrow(
/is not a directory/,
);
});
it("accepts an existing directory and resolves it to an absolute path", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
expect(session.workspaceDir).toBe(ws);
expect(path.isAbsolute(session.workspaceDir)).toBe(true);
});
it("rejects a model reference that is not in the Project config with a clear error", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-bad-model");
await fs.mkdir(ws, { recursive: true });
// A reference outside the config is not silently allowed (the unique key is provider +
// model_id); the error is thrown before creating the temporary workspace.
await expect(
agent.createSession({
workspaceDir: ws,
modelId: "not-configured-model",
provider: "custom",
}),
).rejects.toThrow(/is not in the Project config/);
await expect(
agent.createSession({ workspaceDir: ws, modelId: "deepseek-v4-pro", provider: "openai" }),
).rejects.toThrow(/\(provider=openai, model_id=deepseek-v4-pro\)/);
});
it("passes model timeout from system_config to GenerativeModel", async () => {
const agent = await createAgent();
await patchSystemConfig((cfg) => {
cfg.model = { ...(cfg.model ?? {}), timeoutMs: 3456 };
});
const ws = path.join(tmpRoot, "ws-timeout");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
await bootstrapped(session);
const llm = (session as unknown as { engine: { deps: { llm: unknown } } }).engine.deps.llm;
expect((llm as { requestTimeoutMs?: number }).requestTimeoutMs).toBe(3456);
});
});
describe("Agent.createSession model reference ((provider, model_id) pair)", () => {
it("records the pair reference in session_meta (default_model when unspecified)", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-ref-default");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
try {
// Defaults to the default_model reference; session_meta carries the pair reference
// (same source that Trace writes).
const meta = session.metaMessage.payload as { provider: string; model_id: string };
expect(meta.provider).toBe("deepseek");
expect(meta.model_id).toBe("deepseek-flash");
expect(session.provider).toBe("deepseek");
expect(session.modelId).toBe("deepseek-flash");
} finally {
session.dispose();
}
});
it("selects the entry named by the pair, even when a second group sells the same model_id", async () => {
// A user-run proxy resells claude-sonnet-4-6 under the same upstream id: the two entries
// coexist and the pair — not the bare id — decides which one (and therefore which
// credential and base_url) the Session runs on.
await addModel(tmpRoot, DEFAULT_PROJECT_ID, {
provider: "myproxy",
model_id: "claude-sonnet-4-6",
});
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-ref-pair");
await fs.mkdir(ws, { recursive: true });
const vendor = await agent.createSession({
workspaceDir: ws,
modelId: "claude-sonnet-4-6",
provider: "anthropic",
});
try {
expect(vendor.provider).toBe("anthropic");
expect(vendor.modelId).toBe("claude-sonnet-4-6");
} finally {
vendor.dispose();
}
const proxied = await agent.createSession({
workspaceDir: ws,
modelId: "claude-sonnet-4-6",
provider: "myproxy",
});
try {
expect(proxied.provider).toBe("myproxy");
expect(proxied.modelId).toBe("claude-sonnet-4-6");
} finally {
proxied.dispose();
}
});
it("rejects half a reference: modelId without provider, and provider without modelId", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-ref-half");
await fs.mkdir(ws, { recursive: true });
// A bare model_id is never resolved against the config, not even when exactly one entry
// carries it (gpt-6-astra is unique here): the group is the caller's to name.
await expect(agent.createSession({ workspaceDir: ws, modelId: "gpt-6-astra" })).rejects.toThrow(
/must be given as a \(provider, model_id\) pair/,
);
// The mirror case: provider alone is not a reference either.
await expect(agent.createSession({ workspaceDir: ws, provider: "deepseek" })).rejects.toThrow(
/must be given as a \(provider, model_id\) pair/,
);
// Neither half given is the documented "use the Project default" path, not an error.
const session = await agent.createSession({ workspaceDir: ws });
try {
expect(session.provider).toBe("deepseek");
expect(session.modelId).toBe("deepseek-flash");
} finally {
session.dispose();
}
});
});
describe("Agent.createSession thinking level (explicit option wins over the Agent config)", () => {
// A context's level is the LLM object's construction default (the Session's live pin
// overrides it per request); nothing is recorded — the level is a per-request parameter.
const defaultLevelOf = async (session: unknown): Promise<unknown> => {
await bootstrapped(session);
return (session as { engine: { deps: { llm: { defaultThinkingLevel?: unknown } } } }).engine
.deps.llm.defaultThinkingLevel;
};
it("falls back to the Agent config for the llm default", async () => {
const agent = await createAgent();
// The seeded Agent config pins thinking_level "medium" — the only source when no option is given.
expect(agent.state.systemConfig.model?.thinking_level).toBe("medium");
const ws = path.join(tmpRoot, "ws-thinking-default");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
try {
expect(await defaultLevelOf(session)).toBe("medium");
expect(mapThinkingLevel("medium")).toBeDefined(); // the name maps onto the wire enum
} finally {
session.dispose();
}
});
it("uses an explicit thinkingLevel over the Agent config (subagent inheritance rides on this)", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-thinking-explicit");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws, thinkingLevel: "high" });
try {
expect(await defaultLevelOf(session)).toBe("high");
} finally {
session.dispose();
}
});
// The full resolution chain (the single rule, comment-pinned at Agent.configuredThinkingLevel
// and mirrored by the web draft picker's display): Agent explicit `model.thinking_level` >
// Project `default_chat.thinking_level` > built-in "medium".
it("falls back to the Project's default_chat.thinking_level when the Agent config has none", async () => {
const cfg = await loadProjectConfig(tmpRoot, DEFAULT_PROJECT_ID);
cfg.default_chat = { thinking_level: "high" };
await saveProjectConfig(tmpRoot, DEFAULT_PROJECT_ID, cfg);
const agent = await createAgent();
// A hand-edited config without a level (the seeded default pins "medium").
await patchSystemConfig((cfg) => {
delete cfg.model?.thinking_level;
});
const ws = path.join(tmpRoot, "ws-thinking-project");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
try {
expect(await defaultLevelOf(session)).toBe("high");
} finally {
session.dispose();
}
});
it("Agent explicit level wins over the project default; built-in medium is the last resort", async () => {
const cfg = await loadProjectConfig(tmpRoot, DEFAULT_PROJECT_ID);
cfg.default_chat = { thinking_level: "low" };
await saveProjectConfig(tmpRoot, DEFAULT_PROJECT_ID, cfg);
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-thinking-chain");
await fs.mkdir(ws, { recursive: true });
// The seeded config's explicit "medium" beats the project's "low".
const explicit = await agent.createSession({ workspaceDir: ws });
try {
expect(await defaultLevelOf(explicit)).toBe("medium");
} finally {
explicit.dispose();
}
// No explicit level and no project default -> the built-in "medium". Both halves of
// the chain are read from disk when a context opens, so the SAME Agent object sees the
// Project config edited underneath it.
const noDefault = await loadProjectConfig(tmpRoot, DEFAULT_PROJECT_ID);
delete noDefault.default_chat;
await saveProjectConfig(tmpRoot, DEFAULT_PROJECT_ID, noDefault);
await patchSystemConfig((cfg) => {
delete cfg.model?.thinking_level;
});
const builtin = await agent.createSession({ workspaceDir: ws });
try {
expect(await defaultLevelOf(builtin)).toBe("medium");
} finally {
builtin.dispose();
}
});
});
describe("run_subagent spawning follows the PARENT session (never the Project default)", () => {
/** The subagent runner captured from the most recently constructed real Environment. */
function lastSpawnedRunner(): SubagentRunner {
const services = capturedEnvServices.list.at(-1) as EnvironmentServices | undefined;
const runner = services?.subagentRunner;
expect(runner).toBeDefined();
return runner!;
}
/**
* Spawns through the real runner and reads the child session_meta — the first message
* handle.run yields, emitted before any LLM request. The child's effective thinking
* level is no longer in session_meta (invariants only): the stream is advanced up to
* the child's tool_list_ready event — the point where the lazy bootstrap has constructed
* the LLM — and the captured config (the last one pushed) is read there; the generator
* is closed right after, so nothing is ever sent upstream.
*/
async function spawnedChildMeta(
runner: SubagentRunner,
input: Parameters<SubagentRunner["spawn"]>[0],
): Promise<{
provider: string;
model_id: string;
workspace: string;
source?: string;
llm: { thinkingLevel?: string };
}> {
const handle = await runner.spawn(input);
let llm: { thinkingLevel?: string } | undefined;
try {
const gen = handle.run({ messages: [userText("noop")] });
const first = await gen.next();
expect(first.done).toBe(false);
const msg = first.value as OmniMessage;
expect(msg.type).toBe("session_meta");
// Child messages are stamped with the child Session id as the origin hop.
expect(msg.origin?.[0]).toBe(handle.sessionId);
for (;;) {
const next = await gen.next();
expect(next.done).toBe(false);
if (((next.value as OmniMessage).payload as { type?: string }).type === "tool_list_ready") {
llm = capturedLLMConfigs.list.at(-1)!;
break;
}
}
await gen.return(null);
return {
...(msg.payload as {
provider: string;
model_id: string;
workspace: string;
source?: string;
}),
llm: llm!,
};
} finally {
handle.dispose();
}
}
it("inherits the parent's model pair, thinking level, and workspace when the args omit them", async () => {
const agent = await createAgent();
await patchSystemConfig((cfg) => {
cfg.model = { ...(cfg.model ?? {}), thinking_level: "high" };
});
const ws = path.join(tmpRoot, "ws-inherit");
await fs.mkdir(ws, { recursive: true });
// The parent runs a NON-default model: the Project default (deepseek pair) must not leak in.
const parent = await agent.createSession({
workspaceDir: ws,
modelId: "claude-sonnet-4-6",
provider: "anthropic",
});
const runner = lastSpawnedRunner();
try {
const child = await spawnedChildMeta(runner, {});
expect(child.provider).toBe("anthropic");
expect(child.model_id).toBe("claude-sonnet-4-6");
expect(child.llm.thinkingLevel).toBe("high");
// Workspace inheritance (behavior that predates model/thinking inheritance): locked here.
expect(child.workspace).toBe(ws);
// The spawn site marks the child's own session_meta as subagent-created — the single
// source of truth the server derives from (its registration fallback cannot mask this).
expect(child.source).toBe("subagent");
} finally {
parent.dispose();
}
});
it("still honors an explicit (provider, model_id) pair over inheritance", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-inherit-explicit");
await fs.mkdir(ws, { recursive: true });
const parent = await agent.createSession({
workspaceDir: ws,
modelId: "claude-sonnet-4-6",
provider: "anthropic",
});
const runner = lastSpawnedRunner();
try {
const child = await spawnedChildMeta(runner, {
modelId: "deepseek-v4-pro",
provider: "deepseek",
});
expect(child.provider).toBe("deepseek");
expect(child.model_id).toBe("deepseek-v4-pro");
// Thinking level and workspace are inherited implicitly even with an explicit model.
expect(child.llm.thinkingLevel).toBe("medium");
expect(child.workspace).toBe(ws);
} finally {
parent.dispose();
}
});
it("passes 'no thinking level' down when the parent has none (the child config never applies)", async () => {
// helper_agent's own seeded config pins "medium". With the config chain always resolving
// (Agent explicit > Project default_chat > built-in "medium"), a parent with NO level can
// only come from the explicit tri-state null (an SDK caller suppressing the chain). That
// null must reach the child as-is: falling back to the child's own config here was the
// fallback hole — the child must show no level at all.
await createAgent({ agentId: "helper_agent" });
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-inherit-none");
await fs.mkdir(ws, { recursive: true });
const parent = await agent.createSession({ workspaceDir: ws, thinkingLevel: null });
// The parent LLM is only constructed by the lazy bootstrap — drive it before reading.
await bootstrapped(parent);
const parentLLM = capturedLLMConfigs.list.at(-1)!;
const runner = lastSpawnedRunner();
try {
expect("thinkingLevel" in parentLLM).toBe(false);
const child = await spawnedChildMeta(runner, { agentId: "helper_agent" });
// The tri-state null reached the child: no level at all, not helper_agent's "medium".
expect("thinkingLevel" in child.llm).toBe(false);
} finally {
parent.dispose();
}
});
it("pins an explicit spawn-time thinking level over inheritance (run_subagent's thinking_level)", async () => {
const agent = await createAgent();
await patchSystemConfig((cfg) => {
cfg.model = { ...(cfg.model ?? {}), thinking_level: "high" };
});
const ws = path.join(tmpRoot, "ws-thinking-override");
await fs.mkdir(ws, { recursive: true });
const parent = await agent.createSession({ workspaceDir: ws });
const runner = lastSpawnedRunner();
try {
const child = await spawnedChildMeta(runner, { thinkingLevel: "low" });
// The explicit level wins over the parent's effective "high"; the rest of the spawn
// still follows the parent (workspace locked here as the cheap witness).
expect(child.llm.thinkingLevel).toBe("low");
expect(child.workspace).toBe(ws);
} finally {
parent.dispose();
}
});
it("pins an explicit spawn-time thinking level even when the parent has no level at all", async () => {
// With the parent suppressing the config chain (tri-state null), an explicit spawn level
// must still apply — the override sits above the inherit-or-null resolution, not below it.
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-thinking-override-none");
await fs.mkdir(ws, { recursive: true });
const parent = await agent.createSession({ workspaceDir: ws, thinkingLevel: null });
const runner = lastSpawnedRunner();
try {
const child = await spawnedChildMeta(runner, { thinkingLevel: "xhigh" });
expect(child.llm.thinkingLevel).toBe("xhigh");
} finally {
parent.dispose();
}
});
it("rejects half a model reference at the runner layer (never completed from the parent's half)", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-inherit-half");
await fs.mkdir(ws, { recursive: true });
const parent = await agent.createSession({ workspaceDir: ws });
const runner = lastSpawnedRunner();
try {
await expect(runner.spawn({ modelId: "claude-sonnet-4-6" })).rejects.toThrow(
/must be given as a \(provider, model_id\) pair/,
);
await expect(runner.spawn({ provider: "anthropic" })).rejects.toThrow(
/must be given as a \(provider, model_id\) pair/,
);
} finally {
parent.dispose();
}
});
it("makes a cross-agent child follow the parent session, not its own Agent config", async () => {
// Seed the second Agent first (spawn verifies its system_config exists); its own seeded
// config (thinking "medium") and the Project default model must both lose to the parent.
await createAgent({ agentId: "helper_agent" });
const agent = await createAgent();
await patchSystemConfig((cfg) => {
cfg.model = { ...(cfg.model ?? {}), thinking_level: "xhigh" };
});
const ws = path.join(tmpRoot, "ws-inherit-cross");
await fs.mkdir(ws, { recursive: true });
const parent = await agent.createSession({
workspaceDir: ws,
modelId: "claude-sonnet-4-6",
provider: "anthropic",
});
const runner = lastSpawnedRunner();
try {
const child = await spawnedChildMeta(runner, { agentId: "helper_agent" });
expect(child.provider).toBe("anthropic");
expect(child.model_id).toBe("claude-sonnet-4-6");
expect(child.llm.thinkingLevel).toBe("xhigh");
expect(child.workspace).toBe(ws);
} finally {
parent.dispose();
}
});
it("inherits the parent's CURRENT model: a child spawned after an in-session switch runs on the switched-to model", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-inherit-switched");
await fs.mkdir(ws, { recursive: true });
const parent = await agent.createSession({ workspaceDir: ws });
const runner = lastSpawnedRunner();
try {
expect(parent.provider).toBe("deepseek");
for await (const _ of parent.switchModel({
provider: "anthropic",
modelId: "claude-sonnet-4-6",
})) {
// a never-run Session switches silently
}
const child = await spawnedChildMeta(runner, {});
expect(child.provider).toBe("anthropic");
expect(child.model_id).toBe("claude-sonnet-4-6");
} finally {
parent.dispose();
}
});
it("forwards the run input as an origin-tagged user message, after session_meta and before any model output", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-input-forward");
await fs.mkdir(ws, { recursive: true });
const parent = await agent.createSession({
workspaceDir: ws,
modelId: "claude-sonnet-4-6",
provider: "anthropic",
});
const runner = lastSpawnedRunner();
const handle = await runner.spawn({});
try {
// The child's user side has no other live source: a session's normal caller typed its
// own input, but this caller is the PARENT — the frontend renders the child conversation
// purely from these forwarded messages. (Regression: the panel showed no user messages
// live, while a reload — child-Trace expansion — did show them.)
const gen = handle.run({ messages: [userText("count the TODO items")] });
const first = (await gen.next()).value as { type: string };
expect(first.type).toBe("session_meta");
// The input yield precedes childSession.run: pulling it never issues an LLM request.
const second = await gen.next();
expect(second.done).toBe(false);
const msg = second.value as {
type: string;
origin?: string[];
payload: { type: string; role?: string; text?: string };
};
expect(msg.origin).toEqual([handle.sessionId]);
expect(msg.type).toBe("model_msg");
expect(msg.payload).toMatchObject({
type: "text",
role: "user",
text: "count the TODO items",
});
await gen.return(null);
} finally {
handle.dispose();
parent.dispose();
}
});
});
describe("Agent.createSession max output tokens (per-model cap wins over the Agent config)", () => {
// Reads a constructed GenerativeModel's request config (private; runtime-accessible for assertion).
const uniConfigOf = (llm: unknown) =>
(llm as { uniConfig?: { max_tokens?: number } }).uniConfig ?? {};
it("uses the entry's max_tokens in llmConfig, and inherits the seeded 32000 when unset", async () => {
// A 32k-context local model: the seeded per-Agent default (32000 output tokens) cannot fit
// into its window together with any prompt — the pinned per-model cap must win.
await addModel(tmpRoot, DEFAULT_PROJECT_ID, {
provider: "custom",
model_id: "local-32k",
client_type: "openai",
context_window: 32768,
max_tokens: 8000,
});
const agent = await createAgent();
expect(agent.state.systemConfig.model?.max_tokens).toBe(32000);
const ws = path.join(tmpRoot, "ws-max-tokens");
await fs.mkdir(ws, { recursive: true });
const pinned = await agent.createSession({
workspaceDir: ws,
modelId: "local-32k",
provider: "custom",
});
try {
await bootstrapped(pinned);
const llm = (pinned as unknown as { engine: { deps: { llm: unknown } } }).engine.deps.llm;
expect(uniConfigOf(llm).max_tokens).toBe(8000);
} finally {
pinned.dispose();
}
// An unannotated entry (the default model) inherits the Agent value, as before.
const inherited = await agent.createSession({ workspaceDir: ws });
try {
await bootstrapped(inherited);
const llm = (inherited as unknown as { engine: { deps: { llm: unknown } } }).engine.deps.llm;
expect(uniConfigOf(llm).max_tokens).toBe(32000);
} finally {
inherited.dispose();
}
});
it("meta requests keep their small budget, tightened when the per-model cap is even smaller", async () => {
await addModel(tmpRoot, DEFAULT_PROJECT_ID, {
provider: "custom",
model_id: "local-32k",
client_type: "openai",
max_tokens: 8000,
});
await addModel(tmpRoot, DEFAULT_PROJECT_ID, {
provider: "custom",
model_id: "tiny-cap",
client_type: "openai",
max_tokens: 128,
});
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-meta-cap");
await fs.mkdir(ws, { recursive: true });
// Ample per-model cap: the title one-shot keeps its own 300 budget (never raised to the cap).
const ample = await agent.createSession({
workspaceDir: ws,
modelId: "local-32k",
provider: "custom",
});
try {
const bare = (ample as unknown as { createBareLLM?: () => unknown }).createBareLLM?.();
expect(uniConfigOf(bare).max_tokens).toBe(300);
} finally {
ample.dispose();
}
// Cap pinned below the budget: the meta request must respect it too.
const tiny = await agent.createSession({
workspaceDir: ws,
modelId: "tiny-cap",
provider: "custom",
});
try {
const bare = (tiny as unknown as { createBareLLM?: () => unknown }).createBareLLM?.();
expect(uniConfigOf(bare).max_tokens).toBe(128);
} finally {
tiny.dispose();
}
});
});
describe("Agent.createSession fast mode (session requests only, never the meta ones)", () => {
const uniConfigOf = (llm: unknown) =>
(llm as { uniConfig?: { fast_mode?: boolean } }).uniConfig ?? {};
it("the entry's fast_mode reaches the session LLM and is withheld from the meta LLM", async () => {
// The scoping decision the whole feature rests on: the premium tier is what the user is
// waiting on, so it rides the session's own requests, while background one-shots (title
// generation here; read_file's vision describer builds from the *vision* model's entry and
// so cannot inherit it at all) stay on the standard tier. Without this test the split is
// asserted only by comments, and a refactor that hoists fastMode into a shared config
// helper would start billing every session title at premium rates with all suites green.
await addModel(tmpRoot, DEFAULT_PROJECT_ID, {
provider: "custom",
model_id: "fast-on",
client_type: "openai",
fast_mode: true,
});
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-fast-mode");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({
workspaceDir: ws,
modelId: "fast-on",
provider: "custom",
});
try {
await bootstrapped(session);
const llm = (session as unknown as { engine: { deps: { llm: unknown } } }).engine.deps.llm;
expect(uniConfigOf(llm).fast_mode).toBe(true);
// The title one-shot on the same model must not carry it.
const bare = (session as unknown as { createBareLLM?: () => unknown }).createBareLLM?.();
expect("fast_mode" in uniConfigOf(bare)).toBe(false);
} finally {
session.dispose();
}
});
it("an unannotated entry puts no fast_mode key on the wire at all", async () => {
// Absent, not false: models without a fast tier reject the parameter, so every existing
// config has to stay byte-identical on the wire.
await addModel(tmpRoot, DEFAULT_PROJECT_ID, {
provider: "custom",
model_id: "fast-off",
client_type: "openai",
});
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-fast-mode-off");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({
workspaceDir: ws,
modelId: "fast-off",
provider: "custom",
});
try {
await bootstrapped(session);
const llm = (session as unknown as { engine: { deps: { llm: unknown } } }).engine.deps.llm;
expect("fast_mode" in uniConfigOf(llm)).toBe(false);
} finally {
session.dispose();
}
});
});
describe("Agent.createSession vault injection", () => {
it("injects vault key names (never values) into the assembled system prompt", async () => {
// Write the Agent vault to disk first; createSession reads that Agent's own .vault.toml.
await setVaultEntry(
tmpRoot,
DEFAULT_PROJECT_ID,
DEFAULT_AGENT_ID,
"VAULT_ONLY_KEY",
"vault-secret-value",
);
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-vault");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
try {
const meta = session.metaMessage.payload as { system_prompt: string };
// The "# Vault" statement is part of the template body; key names are injected at the
// placeholder as a `- KEY` list.
expect(meta.system_prompt).toContain("# Vault");
expect(meta.system_prompt).toContain("- VAULT_ONLY_KEY");
// Values never enter the model context.
expect(meta.system_prompt).not.toContain("vault-secret-value");
} finally {
session.dispose();
}
});
it("keeps the vault statement but lists no keys when the Agent has no vault", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-no-vault");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
try {
const meta = session.metaMessage.payload as { system_prompt: string };
// No vault: the "# Vault" section statement is kept, and the
// placeholder is replaced with an empty string, leaving no residue.
expect(meta.system_prompt).toContain("# Vault");
expect(meta.system_prompt).not.toContain("{{VAULT_KEYS}}");
expect(meta.system_prompt).not.toContain("VAULT_ONLY_KEY");
} finally {
session.dispose();
}
});
});
describe("Agent.createSession skill metadata injection", () => {
it("injects installed skill metadata lines (never bodies) into the assembled system prompt", async () => {
await installSkill(tmpRoot, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID, {
name: "demo-skill",
content:
"---\nname: demo-skill\ndescription: Demo skill for tests.\nversion: 2026.07.16.1\n---\n\nSKILL_BODY_NOT_IN_PROMPT\n",
});
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-skills");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
try {
const meta = session.metaMessage.payload as { system_prompt: string };
expect(meta.system_prompt).toContain("# Skills");
expect(meta.system_prompt).toContain("- `demo-skill` — Demo skill for tests.");
// Only metadata is injected; the model reads the body on demand.
expect(meta.system_prompt).not.toContain("SKILL_BODY_NOT_IN_PROMPT");
expect(meta.system_prompt).not.toContain("{{SKILL_METADATA}}");
} finally {
session.dispose();
}
});
});
describe("Agent model contexts are assembled from the Agent State on disk, at every context open", () => {
const promptOf = (session: { metaMessage: OmniMessage }): string =>
(session.metaMessage.payload as { system_prompt: string }).system_prompt;
const mdFile = () => agentsMdPath(tmpRoot, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID);
const typeOf = (msg: OmniMessage | undefined): string | undefined =>
(msg?.payload as { type?: string } | undefined)?.type;
/** The engine-facing context opener (the Session's wrapper around the Agent's factory), reachable once the first-run bootstrap has resolved the toolset. */
const openerOf = (session: unknown) =>
(
session as {
engine: {
deps: {
openNextContext: (opts: OpenContextOptions) => Promise<OpenedContext>;
};
};
}
).engine.deps.openNextContext;
/** Opens the Session's next context through its opener, collecting the records the opener publishes. */
async function openNext(
session: unknown,
): Promise<{ opened: OpenedContext; records: OmniMessage[] }> {
const records: OmniMessage[] = [];
const opened = await openerOf(session)({ emit: (msg) => records.push(msg) });
return { opened, records };
}
/** The config the most recently constructed GenerativeModel was given. */
const lastBuilt = () =>
capturedLLMConfigs.list.at(-1) as
{ systemPrompt?: string; tools?: { name: string }[]; thinkingLevel?: string } | undefined;
const toolNames = (tools: { name: string }[] | undefined): string[] =>
(tools ?? []).map((t) => t.name);
/** The vault the Environment's command session registry injects at every spawn. */
const environmentVaultOf = (session: unknown): Record<string, string> =>
(session as { environment: { commandSessions: { vault: Record<string, string> } } }).environment
.commandSessions.vault;
it("createSession assembles from disk, not from the Agent's load-time snapshot", async () => {
const agent = await createAgent();
await fs.writeFile(mdFile(), "EDITED AFTER LOAD", "utf8");
await patchSystemConfig((cfg) => {
cfg.max_turns = 7;
});
const ws = path.join(tmpRoot, "ws-md-disk");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
try {
expect(promptOf(session)).toContain("EDITED AFTER LOAD");
expect(
(session as unknown as { engineDeps: { maxTurns?: number } }).engineDeps.maxTurns,
).toBe(7);
// The Agent object's copies are the load-time snapshot; no Session runs on them.
expect(agent.state.agentsMd).not.toContain("EDITED AFTER LOAD");
expect(agent.state.systemConfig.max_turns).not.toBe(7);
} finally {
session.dispose();
}
});
it("the compaction section is re-read from disk on demand, so an edited threshold reaches a running Session", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-live-compaction");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
try {
const readCompaction = (
session as unknown as {
engineDeps: {
readCompaction?: () => Promise<{ maxContextLength: number; mode: string }>;
};
}
).engineDeps.readCompaction!;
await patchSystemConfig((cfg) => {
cfg.compaction = { ...(cfg.compaction ?? {}), max_context_length: 40000, mode: "discard" };
});
// No rotation, no new Session: the reader the engine calls at each checkpoint answers
// from the file as it is now.
expect(await readCompaction()).toMatchObject({ maxContextLength: 40000, mode: "discard" });
await patchSystemConfig((cfg) => {
cfg.compaction = { ...(cfg.compaction ?? {}), max_context_length: 199000 };
});
expect((await readCompaction()).maxContextLength).toBe(199000);
} finally {
session.dispose();
}
});
it("the context opened after compaction is rebuilt whole — prompt, toolset, vault, run settings — and its records describe it", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-rebuild");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
try {
await bootstrapped(session);
expect(toolNames(lastBuilt()!.tools)).toContain("write_file");
expect(environmentVaultOf(session)).toEqual({});
expect(promptOf(session)).not.toContain("EDITED DURING THE OLD CONTEXT");
// Everything edited during the old context — by the model working on its own
// configuration, or by hand in the Agent settings.
await fs.writeFile(mdFile(), "EDITED DURING THE OLD CONTEXT", "utf8");
await setVaultEntry(tmpRoot, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID, "NEW_API_KEY", "shh");
await patchSystemConfig((cfg) => {
cfg.tools = {
...(cfg.tools ?? {}),
builtin: (cfg.tools?.builtin ?? []).filter((t) => t.name !== "write_file"),
};
cfg.compaction = { ...(cfg.compaction ?? {}), mode: "discard" };
cfg.max_turns = 3;
cfg.model = { ...(cfg.model ?? {}), thinking_level: "high" };
});
const { opened, records } = await openNext(session);
// The new LLM object carries the re-assembled prompt, the re-read toolset and the
// config's model defaults…
const after = lastBuilt()!;
expect(after.systemPrompt).toContain("EDITED DURING THE OLD CONTEXT");
expect(after.systemPrompt).toContain("NEW_API_KEY");
expect(toolNames(after.tools)).not.toContain("write_file");
expect(toolNames(after.tools)).toContain("read_file");
expect(after.thinkingLevel).toBe("high");
// …the vault's values went straight into the Environment's command environment…
expect(environmentVaultOf(session)).toEqual({ NEW_API_KEY: "shh" });
// …the engine settings follow the re-read config…
expect(opened.maxTurns).toBe(3);
expect(opened.compaction?.mode).toBe("discard");
// …the meta the rotated Trace file opens with records exactly that prompt (the Session's
// own meta follows the running context), and the toolset record is published for the
// file head and the live stream.
const recorded = (opened.sessionMeta!.payload as { system_prompt: string }).system_prompt;
expect(recorded).toBe(after.systemPrompt);
expect(promptOf(session)).toBe(recorded);
expect(records.map(typeOf)).toEqual(["tool_list_ready"]);
expect(toolNames((records[0]!.payload as { tools: { name: string }[] }).tools)).toEqual(
toolNames(after.tools),
);
} finally {
session.dispose();
}
});
it("a Skill and a hook package written during the old context are the next context's", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-authored");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
const skillDir = path.join(
skillsDir(tmpRoot, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID),
"clock-reading",
);
const hookDir = path.join(hooksDir(tmpRoot, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID), "flow");
try {
await bootstrapped(session);
// Written as plain files, the way a model working on its own configuration does it:
// no installer, and a manifest that lists only the point it uses. The command is
// host-triggered so the Session can be asked for it by name.
await fs.mkdir(skillDir, { recursive: true });
await fs.writeFile(
path.join(skillDir, "SKILL.md"),
"---\nname: clock-reading\ndescription: Reads analog clocks.\n---\n\nLook at the hands.\n",
);
await fs.mkdir(hookDir, { recursive: true });
await fs.writeFile(
path.join(hookDir, "hooks.json"),
JSON.stringify({ user_prompt: [{ command: "start.mjs", trigger: "host" }] }),
);
await fs.writeFile(
path.join(hookDir, "start.mjs"),
'process.stdout.write(JSON.stringify({ context: "started" }));\n',
);
// Nothing changes in the middle of a context.
expect(promptOf(session)).not.toContain("clock-reading");
expect(await session.runUserPromptHook("flow", "go")).toBeNull();
await openNext(session);
expect(promptOf(session)).toContain("`clock-reading` — Reads analog clocks.");
expect(await session.runUserPromptHook("flow", "go")).toEqual({ context: "started" });
// The one switch over every package is read on the same schedule…
await patchSystemConfig((cfg) => {
cfg.hooks = { enabled: false };
});
expect(await session.runUserPromptHook("flow", "go")).toEqual({ context: "started" });
await openNext(session);
expect(await session.runUserPromptHook("flow", "go")).toBeNull();
// …and so is a package's removal.
await patchSystemConfig((cfg) => {
cfg.hooks = { enabled: true };
});
await openNext(session);
expect(await session.runUserPromptHook("flow", "go")).toEqual({ context: "started" });
await fs.rm(hookDir, { recursive: true, force: true });
await openNext(session);
expect(await session.runUserPromptHook("flow", "go")).toBeNull();
} finally {
session.dispose();
}
});
it("session_meta records no level; the config default and a null pin shape only the LLM base", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-thinking-meta");
await fs.mkdir(ws, { recursive: true });
const levelOf = (session: { metaMessage: OmniMessage }) =>
(session.metaMessage.payload as { thinking_level?: string }).thinking_level;
// The seeded config pins "medium"; a `null` pin (a subagent whose parent has none) runs
// without a level. Neither is recorded: the level is a per-request parameter.
const configured = await agent.createSession({ workspaceDir: ws });
const unlevelled = await agent.createSession({ workspaceDir: ws, thinkingLevel: null });
try {
await bootstrapped(configured);
expect(lastBuilt()!.thinkingLevel).toBe("medium");
expect(levelOf(configured)).toBeUndefined();
await bootstrapped(unlevelled);
expect(lastBuilt()!.thinkingLevel).toBeUndefined();
expect(levelOf(unlevelled)).toBeUndefined();
} finally {
configured.dispose();
unlevelled.dispose();
}
});
it("toolPermission and the command policy are strict-tier: an edit lands at the next context open, not mid-context", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-strict-permission");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
const policyOf = () =>
(
session as unknown as { commandPolicy?: () => { enabled?: boolean } | undefined }
).commandPolicy?.();
try {
await bootstrapped(session);
expect(session.toolPermission("read_file")).toBe("r");
const openedWith = policyOf();
await patchSystemConfig((cfg) => {
cfg.tools = {
...(cfg.tools ?? {}),
builtin: (cfg.tools?.builtin ?? []).map((t) =>
t.name === "read_file" ? { ...t, permission: "rw" as const } : t,
),
};
});
await fs.writeFile(
projectConfigPath(tmpRoot, DEFAULT_PROJECT_ID),
"[command_policy]\nenabled = false\n",
"utf8",
);
// The running context's toolset and policy stand until rotation…
expect(session.toolPermission("read_file")).toBe("r");
expect(policyOf()).toBe(openedWith);
// …and the next context opens with both edits.
await openNext(session);
expect(session.toolPermission("read_file")).toBe("rw");
expect(policyOf()).toEqual({ enabled: false });
} finally {
session.dispose();
}
});
it("thinkingLevel is plain engine state: an assignment rides requests while contexts keep their config base", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-thinking-pin");
await fs.mkdir(ws, { recursive: true });
const levelOf = (session: { metaMessage: OmniMessage }) =>
(session.metaMessage.payload as { thinking_level?: string }).thinking_level;
const engineLevelOf = (session: unknown) =>
(session as { engine: { thinkingLevel?: string } }).engine.thinkingLevel;
const session = await agent.createSession({ workspaceDir: ws });
try {
// Assigned before the first run: buffered on the Session, handed to the engine when
// it is built. The context's own base stays the config default ("medium").
session.thinkingLevel = "high";
expect(session.thinkingLevel).toBe("high");
expect(levelOf(session)).toBeUndefined();
await bootstrapped(session);
expect(lastBuilt()!.thinkingLevel).toBe("medium");
expect(engineLevelOf(session)).toBe("high");
// Reassigned mid-session: engine state for every subsequent request; the context a
// compaction opens still bases on the creation option and the config, and the meta
// records nothing.
session.thinkingLevel = "xhigh";
expect(engineLevelOf(session)).toBe("xhigh");
const { opened } = await openNext(session);
expect(
(opened.sessionMeta!.payload as { thinking_level?: string }).thinking_level,
).toBeUndefined();
expect(lastBuilt()!.thinkingLevel).toBe("medium");
expect(session.thinkingLevel).toBe("xhigh");
} finally {
session.dispose();
}
});
it("reconnects the new context's MCP Servers, bracketing the connect with the same event pair the first run uses", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-mcp-rotate");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
// The provider warns on stderr about the unreachable server; keep the test output clean.
const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
try {
await bootstrapped(session);
// A server added during the old context. Its command cannot be spawned, so the connect
// fails fast — and the outcome is recorded rather than hidden.
await patchSystemConfig((cfg) => {
cfg.tools = {
...(cfg.tools ?? {}),
mcpServers: [{ name: "ghost", config: { command: "penguin-no-such-mcp-server" } }],
};
});
const { records } = await openNext(session);
expect(records.map(typeOf)).toEqual([
"mcp_connect_begin",
"mcp_connect_end",
"tool_list_ready",
]);
expect((records[0]!.payload as { servers: string[] }).servers).toEqual(["ghost"]);
const end = records[1]!.payload as {
status: string;
results: { server: string; status: string }[];
};
expect(end.status).toBe("fatal");
expect(end.results).toEqual([expect.objectContaining({ server: "ghost", status: "fatal" })]);
expect(stderr).toHaveBeenCalledWith(
expect.stringContaining('MCP server "ghost" unavailable'),
);
} finally {
stderr.mockRestore();
session.dispose();
}
});
it("an Agent State that cannot be assembled fails the context open outright — no silent fallback", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-unreadable");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
try {
await bootstrapped(session);
const before = promptOf(session);
// system_config.yaml no longer parses — an edit gone wrong mid-context.
await fs.writeFile(systemConfigPath(tmpRoot, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID), "");
await expect(openNext(session)).rejects.toThrow("Invalid Agent State config");
// Nothing was adopted: the Session still describes the context that is running.
expect(promptOf(session)).toBe(before);
} finally {
session.dispose();
}
});
});
describe("Session.switchModel on a real Agent (the composition layer's half)", () => {
const TARGET = { provider: "anthropic", modelId: "claude-sonnet-4-6" };
/** Runs a switch to its end, keeping what it streamed. */
async function drain(gen: AsyncGenerator<OmniMessage, unknown>): Promise<OmniMessage[]> {
const all: OmniMessage[] = [];
for (;;) {
const res = await gen.next();
if (res.done) return all;
all.push(res.value);
}
}
const lastBuilt = () =>
capturedLLMConfigs.list.at(-1) as
{ modelId?: string; apiKey?: string; baseUrl?: string; systemPrompt?: string } | undefined;
const modelIdOf = (session: { metaMessage: OmniMessage }): string =>
(session.metaMessage.payload as { model_id: string }).model_id;
/**
* The opener the Session's engine calls for its next context, and the Session's way of
* telling it which model a switch is moving to: `open()` is a plain rotation, `open(target)`
* a switch's — what `Session.switchModel` sets around the engine's rotation.
*/
function openerOf(session: unknown): (target?: ModelRef) => Promise<OpenedContext> {
const internals = session as {
switchTarget: ModelRef | undefined;
engine: { deps: { openNextContext: (opts: OpenContextOptions) => Promise<OpenedContext> } };
};
return (target) => {
internals.switchTarget = target;
return internals.engine.deps
.openNextContext({ emit: () => {} })
.finally(() => (internals.switchTarget = undefined));
};
}
it("a Session that never ran is re-assembled on the target: nothing recorded, and its first run opens on it", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-switch-fresh");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
try {
expect(session.provider).toBe("deepseek");
expect(session.modelId).toBe("deepseek-flash");
const events = await drain(session.switchModel(TARGET));
expect(events).toEqual([]);
expect(session.provider).toBe("anthropic");
expect(session.modelId).toBe("claude-sonnet-4-6");
// The re-assembled first context's meta names the target, and its prompt was assembled
// for it (the Environment section names the model the context runs on).
expect(modelIdOf(session)).toBe("claude-sonnet-4-6");
expect((session.metaMessage.payload as { system_prompt: string }).system_prompt).toContain(
"claude-sonnet-4-6",
);
// Nothing was recorded: an untouched Session must not look resumable.
expect(await agent.latestSessionId()).toBeNull();
// The first run builds the target's LLM and opens the Trace with the target's meta.
await bootstrapped(session);
expect(lastBuilt()!.modelId).toBe("claude-sonnet-4-6");
const located = await findLatestTraceFile(
tracesDir(tmpRoot, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID),
session.sessionId,
);
const head = (await readTrace(located!.path))[0]!;
expect(head.type).toBe("session_meta");
expect((head.payload as { model_id: string }).model_id).toBe("claude-sonnet-4-6");
} finally {
session.dispose();
}
});
it("refuses a target the Project config does not have, before anything happens", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-switch-unknown");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
try {
// A typed refusal, so a host maps it to its own code without reading the message.
const refusal = await drain(
session.switchModel({ provider: "custom", modelId: "nobody-configured-this" }),
).catch((e: unknown) => e);
expect(refusal).toBeInstanceOf(ModelSwitchRefusedError);
expect(refusal).toMatchObject({
reason: "model_not_configured",
message: expect.stringMatching(/is not in the Project config/) as unknown,
});
expect(session.modelId).toBe("deepseek-flash");
expect(await agent.latestSessionId()).toBeNull();
} finally {
session.dispose();
}
});
it("resolves the target against the Project config on disk, not the Agent's load-time snapshot", async () => {
const agent = await createAgent();
// Configured after the Agent loaded: the snapshot does not know it, the disk does.
await addModel(tmpRoot, DEFAULT_PROJECT_ID, {
provider: "myproxy",
model_id: "claude-sonnet-4-6",
base_url: "https://proxy.invalid/v1",
api_key: "proxy-key",
});
expect(agent.projectConfig.models.some((m) => m.provider === "myproxy")).toBe(false);
const ws = path.join(tmpRoot, "ws-switch-disk");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
try {
await drain(session.switchModel({ provider: "myproxy", modelId: "claude-sonnet-4-6" }));
expect(session.provider).toBe("myproxy");
// The validation constructed the target's bare LLM on the target entry's own credentials.
expect(lastBuilt()).toMatchObject({
modelId: "claude-sonnet-4-6",
apiKey: "proxy-key",
baseUrl: "https://proxy.invalid/v1",
});
// The Agent's own copy of the config followed the read, so a child spawned from here —
// which inherits the model just switched to — finds it configured.
expect(agent.projectConfig.models.some((m) => m.provider === "myproxy")).toBe(true);
const runner = (capturedEnvServices.list.at(-1) as EnvironmentServices).subagentRunner!;
const child = await runner.spawn({});
try {
const gen = child.run({ messages: [userText("noop")] });
const first = await gen.next();
await gen.return(null);
expect((first.value as OmniMessage).payload).toMatchObject({
provider: "myproxy",
model_id: "claude-sonnet-4-6",
});
} finally {
child.dispose();
}
} finally {
session.dispose();
}
});
it("explicit creation credentials stay with the creation model: a context on another model runs on that entry's own", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-switch-creds");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({
workspaceDir: ws,
apiKey: "creation-key",
baseUrl: "https://creation.invalid/v1",
});
try {
// The creation model's bare LLM (the credential check) carries the override.
expect(lastBuilt()).toMatchObject({
modelId: "deepseek-flash",
apiKey: "creation-key",
baseUrl: "https://creation.invalid/v1",
});
await drain(session.switchModel(TARGET));
// The target's validation LLM, and the session LLM the first run builds, do not: the
// key was handed in for one vendor and must never be sent to another.
expect(lastBuilt()!.modelId).toBe("claude-sonnet-4-6");
expect(lastBuilt()!.apiKey).toBeUndefined();
expect(lastBuilt()!.baseUrl).toBeUndefined();
await bootstrapped(session);
expect(lastBuilt()!.modelId).toBe("claude-sonnet-4-6");
expect(lastBuilt()!.apiKey).toBeUndefined();
} finally {
session.dispose();
}
});
it("a rotation keeps the running model unless the opener is told the switch target", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-switch-rotation");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
try {
await bootstrapped(session);
const open = openerOf(session);
// The fold the engine asks for a steering message's images: `null` means the running
// context's model takes them as they are.
const { foldInputImages } = (
session as unknown as {
engine: {
deps: { foldInputImages: (messages: OmniMessage[]) => Promise<OmniMessage[] | null> };
};
}
).engine.deps;
const picture = [imageUrlMessage("https://images.invalid/pic.png")];
// A plain rotation: the same model, re-assembled, with the vision answer its entry gives.
const kept = await open();
expect((kept.sessionMeta!.payload as { model_id: string }).model_id).toBe("deepseek-flash");
const deepseek = agent.projectConfig.models.find((m) => m.model_id === "deepseek-flash")!;
expect((await foldInputImages(picture)) === null).toBe(deepseek.vision !== false);
expect(lastBuilt()!.modelId).toBe("deepseek-flash");
expect(session.modelId).toBe("deepseek-flash");
// A switch's rotation: the target, with its own vision answer and window-derived settings.
const switched = await open({ provider: "anthropic", model_id: "claude-sonnet-4-6" });
expect((switched.sessionMeta!.payload as { model_id: string }).model_id).toBe(
"claude-sonnet-4-6",
);
expect(await foldInputImages(picture)).toBeNull();
expect(lastBuilt()!.modelId).toBe("claude-sonnet-4-6");
expect(lastBuilt()!.systemPrompt).toContain("claude-sonnet-4-6");
// The Session's own answer follows the opened context.
expect(session.provider).toBe("anthropic");
expect(session.modelId).toBe("claude-sonnet-4-6");
} finally {
session.dispose();
}
});
it("an open that fails leaves the running context in place: the Environment is equipped for it again and the next rotation keeps its model", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-switch-open-fails");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({ workspaceDir: ws });
try {
await bootstrapped(session);
const { environment } = session as unknown as {
environment: {
listTools(): Promise<unknown>;
reconfigure(update: { toolConfig: unknown }): void;
};
};
const open = openerOf(session);
const reconfigure = vi.spyOn(environment, "reconfigure");
const target = { provider: "anthropic", model_id: "claude-sonnet-4-6" };
// A plain rotation first, so the running context is one this opener equipped.
await open();
const running = reconfigure.mock.calls[0]![0].toolConfig;
// The target assembles, the Environment is equipped for it, and then its toolset cannot
// be resolved: the open fails.
vi.spyOn(environment, "listTools").mockRejectedValueOnce(new Error("toolset unavailable"));
await expect(open(target)).rejects.toThrow("toolset unavailable");
expect(reconfigure).toHaveBeenCalledTimes(3);
expect(reconfigure.mock.calls[1]![0].toolConfig).not.toBe(running);
expect(reconfigure.mock.calls[2]![0].toolConfig).toBe(running);
expect(session.modelId).toBe("deepseek-flash");
// The running context is still the one a rotation re-assembles.
const kept = await open();
expect((kept.sessionMeta!.payload as { model_id: string }).model_id).toBe("deepseek-flash");
expect(lastBuilt()!.modelId).toBe("deepseek-flash");
// A target gone from the config by the time the context opens is a failure of the
// switch, not its typed refusal: the refusal is the validation's answer, before any event.
const gone = await open({ provider: "custom", model_id: "nobody-configured-this" }).catch(
(e: unknown) => e,
);
expect(gone).toBeInstanceOf(Error);
expect(gone).not.toBeInstanceOf(ModelSwitchRefusedError);
expect((gone as Error).message).toMatch(/is not in the Project config/);
} finally {
session.dispose();
}
});
});
describe("Agent.createSession credential rule (a keyless gateway row never borrows a vendor key)", () => {
it("refuses a keyless gateway preset before any client exists, even with OPENAI_API_KEY set", async () => {
// stubProviderKeys has set OPENAI_API_KEY and friends: the pre-rule behaviour was to hand
// AgentHub no key and let its generic client read the variable — sending the user's
// OpenAI key to the gateway. The preset carries the gateway's base URL and no key.
const preset = MODEL_CATALOG.find((m) => m.provider === "openrouter" && m.retired !== true)!;
expect(process.env.OPENAI_API_KEY).toBeDefined();
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-gateway-keyless");
await fs.mkdir(ws, { recursive: true });
await expect(
agent.createSession({ workspaceDir: ws, provider: preset.provider, modelId: preset.modelId }),
).rejects.toThrow(/has no API key/);
// No Session, so nothing to dispose; the same row with its own key is a normal Session
// (an Agent reads the Project config when it is created, so a fresh one sees the key).
await addModel(tmpRoot, DEFAULT_PROJECT_ID, {
provider: preset.provider,
model_id: preset.modelId,
api_key: "sk-gateway-own-key",
});
const keyed = await createAgent();
const session = await keyed.createSession({
workspaceDir: ws,
provider: preset.provider,
modelId: preset.modelId,
});
try {
expect(session.provider).toBe(preset.provider);
} finally {
session.dispose();
}
});
it("still lets a keyless vendor preset lean on the vendor's own variable", async () => {
const agent = await createAgent();
const ws = path.join(tmpRoot, "ws-vendor-keyless");
await fs.mkdir(ws, { recursive: true });
const session = await agent.createSession({
workspaceDir: ws,
provider: "anthropic",
modelId: "claude-sonnet-4-6",
});
try {
expect(session.modelId).toBe("claude-sonnet-4-6");
} finally {
session.dispose();
}
});
});