import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import path from "node:path"; import { afterEach, describe, expect, it } from "vitest"; import { createTestSession, type TestSession } from "../../../test/harness"; import { DEFAULT_FANOUT_TOOLS, DEFAULT_MODEL_TIERS, effectiveModelTiers, fanoutToolPolicyPrompt, loadUltraSettings, modelTierPrompt, parseUltraSettings, ULTRA_DEFAULTS, } from "../settings.ts"; const extensionPath = path.resolve(import.meta.dirname, "../index.ts"); let t: TestSession | undefined; let root: string | undefined; afterEach(() => { t?.dispose(); t = undefined; if (root) rmSync(root, { recursive: true, force: true }); root = undefined; }); type Sources = { user?: unknown; project?: unknown; untrusted?: boolean }; /** Start a sandboxed session whose settings files hold the given `ultra` blocks. */ async function start(input: Sources): Promise { root = mkdtempSync(path.join(tmpdir(), "pi-ext-ultra-settings-")); const write = (dir: string, ultra: unknown) => { mkdirSync(dir, { recursive: true }); writeFileSync(path.join(dir, "settings.json"), JSON.stringify({ ultra })); }; if ("user" in input) write(path.join(root, ".test-home/.pi/agent"), input.user); if ("project" in input) write(path.join(root, ".pi"), input.project); t = await createTestSession({ cwd: root, extensions: [extensionPath] }); if (input.untrusted) t.session.settingsManager.setProjectTrusted(false); return t; } async function resolve(input: Sources) { const session = await start(input); return loadUltraSettings( { getFlag: () => undefined }, session.session.extensionRunner.createCommandContext(), ); } describe("ULTRA_DEFAULTS", () => { it("matches the documented defaults", () => { expect(ULTRA_DEFAULTS).toEqual({ enabled: true, autoEnable: false, concurrency: 5, maxRetries: 2, subagentExtensions: "all", fanoutToolAllowlist: DEFAULT_FANOUT_TOOLS, subagentSkills: "all", subagentSessionRetention: "all", modelTiers: DEFAULT_MODEL_TIERS, providerModelTiers: {}, actionSummarizerModel: null, }); expect(parseUltraSettings({})).toEqual(ULTRA_DEFAULTS); }); }); describe("parseUltraSettings", () => { it("accepts every known key", () => { expect( parseUltraSettings({ enabled: false, autoEnable: true, concurrency: 8, maxRetries: 1, subagentExtensions: [" alpha ", "beta", "alpha"], fanoutToolAllowlist: ["web", "web", "bash"], subagentSkills: "none", subagentSessionRetention: "none", actionSummarizerModel: " openai/gpt-5-mini ", modelTiers: { small: { model: "openai/gpt-5-mini" } }, }), ).toEqual({ ...ULTRA_DEFAULTS, enabled: false, autoEnable: true, concurrency: 8, maxRetries: 1, subagentExtensions: ["alpha", "beta"], fanoutToolAllowlist: [...DEFAULT_FANOUT_TOOLS, "web"], subagentSkills: "none", subagentSessionRetention: "none", actionSummarizerModel: "openai/gpt-5-mini", modelTiers: { ...DEFAULT_MODEL_TIERS, small: { ...DEFAULT_MODEL_TIERS.small, model: "openai/gpt-5-mini" }, }, }); expect( parseUltraSettings({ subagentExtensions: "none" }).subagentExtensions, ).toBe("none"); expect( parseUltraSettings({ actionSummarizerModel: null }).actionSummarizerModel, ).toBeNull(); expect( fanoutToolPolicyPrompt( parseUltraSettings({ fanoutToolAllowlist: ["web"] }) .fanoutToolAllowlist, ), ).toContain("bash, web"); }); it.each([ [7, "ultra must be an object."], [{ auto_enable: true }, "unknown key ultra.auto_enable."], [{ bogus: 1 }, "unknown key ultra.bogus."], [{ enabled: "false" }, "ultra.enabled must be a boolean."], [{ autoEnable: "true" }, "ultra.autoEnable must be a boolean."], [{ concurrency: "8" }, "ultra.concurrency must be a number."], [{ maxRetries: null }, "ultra.maxRetries must be a number."], [{ subagentExtensions: "lots" }, "ultra.subagentExtensions must be"], [{ subagentExtensions: ["alpha", 7] }, "ultra.subagentExtensions must be"], [{ subagentExtensions: [""] }, "ultra.subagentExtensions must be"], [{ fanoutToolAllowlist: "web" }, "ultra.fanoutToolAllowlist"], [{ fanoutToolAllowlist: [""] }, "ultra.fanoutToolAllowlist"], [{ fanoutToolAllowlist: [" web"] }, "ultra.fanoutToolAllowlist"], [{ fanoutToolAllowlist: [4] }, "ultra.fanoutToolAllowlist"], [{ subagentSkills: true }, 'ultra.subagentSkills must be "all" or "none".'], [ { subagentSessionRetention: "failures" }, 'ultra.subagentSessionRetention must be "all" or "none".', ], [{ actionSummarizerModel: " " }, "ultra.actionSummarizerModel must be"], ] as const)("rejects %j", (raw, error) => { expect(() => parseUltraSettings(raw)).toThrow(error); }); }); describe("model tiers", () => { it("ships five session-model tiers without a closed name enum", () => { expect(Object.keys(DEFAULT_MODEL_TIERS)).toEqual([ "tiny", "small", "medium", "large", "huge", ]); expect( Object.values(DEFAULT_MODEL_TIERS).map((tier) => [ tier.model, tier.thinkingLevel, ]), ).toEqual([ [null, "low"], [null, "low"], [null, "medium"], [null, "high"], [null, "max"], ]); }); it("merges per-field instruction overrides and custom tiers without mutating sources", async () => { const user = { modelTiers: { large: { model: "openai/gpt-6-astra", instructions: "Old selection guidance.", }, code_audit: { model: "custom/model-v2", thinkingLevel: "high", instructions: "Audit code.", }, }, }; const project = { modelTiers: { large: { instructions: "Only for architecture." }, code_audit: { thinkingLevel: "max" }, }, }; const result = await resolve({ user, project }); expect(result.modelTiers.large).toEqual({ model: "openai/gpt-6-astra", thinkingLevel: "high", instructions: "Only for architecture.", }); expect(result.modelTiers.code_audit).toEqual({ model: "custom/model-v2", thinkingLevel: "max", instructions: "Audit code.", }); result.modelTiers.small.instructions = "Mutated result"; expect(parseUltraSettings({}).modelTiers.small.instructions).toBe( DEFAULT_MODEL_TIERS.small.instructions, ); const prompt = modelTierPrompt(result.modelTiers); expect(prompt).toContain("- code_audit: custom/model-v2; max; Audit code."); expect(prompt).toContain("Only for architecture."); expect(prompt).not.toContain("Old selection guidance."); expect(prompt).not.toContain(DEFAULT_MODEL_TIERS.large.instructions); }); it("renders compact tier data without changing custom instructions or routing defaults", () => { const tiers = { ...DEFAULT_MODEL_TIERS, custom: { model: "custom/model", thinkingLevel: "high" as const, instructions: "Inspect A | B.\nKeep `field` exact.", }, }; const prompt = modelTierPrompt(tiers); for (const instruction of [ "Orchestrator only.", "default thinkingLevel", "Default small; tiny only for determined outcomes.", "Choose lowest adequate tier; lower wins ties.", "residual decisions, dependencies, ambiguity, and consequence", "credit upstream findings", "outweigh handoffs", "minimum sufficient context", "verify proportionately to risk", "Ask user for missing decisions", "missing child evidence or authority as blockers", "not reasons to escalate tiers", ]) expect(prompt).toContain(instruction); for (const [name, tier] of Object.entries(tiers)) { expect(prompt).toContain( `- ${name}: ${tier.model ?? "session model"}; ${tier.thinkingLevel}; ${tier.instructions}`, ); } expect(prompt.match(/default thinkingLevel/g)).toHaveLength(1); expect(modelTierPrompt(DEFAULT_MODEL_TIERS).length).toBeLessThan(1_250); }); it("inherits fallback instructions when settings override only routing", () => { const overrides = Object.fromEntries( Object.entries(DEFAULT_MODEL_TIERS).map(([name, tier]) => [ name, { model: `custom/${name}`, thinkingLevel: tier.thinkingLevel, }, ]), ); const result = parseUltraSettings({ modelTiers: overrides }); for (const [name, fallback] of Object.entries(DEFAULT_MODEL_TIERS)) { expect(result.modelTiers[name]).toEqual({ model: `custom/${name}`, thinkingLevel: fallback.thinkingLevel, instructions: fallback.instructions, }); } }); it("allows null to restore session-model routing", () => { const result = parseUltraSettings({ modelTiers: { small: { model: null } }, }); expect(result.modelTiers.small.model).toBeNull(); }); it.each([ [null, "must be an object"], [[], "must be an object"], [{ small: "openai/model:low" }, "must be an object"], [{ "bad/name": {} }, "invalid tier name"], [{ Bad: {} }, "invalid tier name"], [{ constructor: {} }, "invalid tier name"], [JSON.parse('{"__proto__":{}}'), "invalid tier name"], [{ small: { model: "" } }, "provider/model"], [{ small: { model: "small" } }, "provider/model"], [{ small: { model: "openai/model:high" } }, "set thinkingLevel separately"], [{ small: { model: "openai/model with spaces" } }, "provider/model"], [{ small: { model: 7 } }, "provider/model"], [{ small: { thinkingLevel: "ultra" } }, "thinkingLevel must be"], [{ small: { thinkingLevel: null } }, "thinkingLevel must be"], [{ small: { instructions: " " } }, "non-empty string"], [{ small: { instructions: 7 } }, "non-empty string"], [{ small: { instruction: "typo" } }, "unknown field"], [ { incomplete: { model: "openai/model" } }, "requires model, thinkingLevel, and instructions", ], ] as const)( "rejects malformed tier configuration %j", (modelTiers, error) => { expect(() => parseUltraSettings({ modelTiers })).toThrow(error); }, ); }); describe("providerModelTiers setting", () => { const base = parseUltraSettings({}); it("defaults to no provider overrides and extracts typed provider blocks", () => { expect(ULTRA_DEFAULTS.providerModelTiers).toEqual({}); expect( parseUltraSettings({ providerModelTiers: { zai: { small: { model: "zai/glm-4.7", thinkingLevel: "high" } }, }, }).providerModelTiers, ).toEqual({ zai: { small: { model: "zai/glm-4.7", thinkingLevel: "high" } }, }); expect(effectiveModelTiers(base, "openai-codex")).toBe(base.modelTiers); expect(effectiveModelTiers(base, undefined)).toBe(base.modelTiers); }); it("folds matching provider overrides per field and renders them", async () => { const settings = await resolve({ user: { providerModelTiers: { zai: { tiny: { model: "zai/glm-4.7-flash" }, large: { model: "zai/glm-4.7", instructions: "Provider flagship only.", }, }, }, }, project: { providerModelTiers: { zai: { large: { model: "zai/glm-4.6" } }, "klaus-custom": { medium: { model: "klaus/fable" } }, }, }, }); const zai = effectiveModelTiers(settings, "zai"); expect(zai.large).toEqual({ model: "zai/glm-4.6", thinkingLevel: DEFAULT_MODEL_TIERS.large.thinkingLevel, instructions: "Provider flagship only.", }); expect(zai.tiny.model).toBe("zai/glm-4.7-flash"); expect(zai.small).toEqual(DEFAULT_MODEL_TIERS.small); expect(effectiveModelTiers(settings, "klaus-custom").medium.model).toBe( "klaus/fable", ); expect(effectiveModelTiers(settings, "unknown-provider")).toBe( settings.modelTiers, ); expect(settings.modelTiers.large.model).toBeNull(); expect(modelTierPrompt(zai)).toContain( "- large: zai/glm-4.6; high; Provider flagship only.", ); }); it.each([ [7, "ultra.providerModelTiers must be an object."], [{ "bad provider": {} }, "invalid provider name"], [{ zai: 7 }, "ultra.providerModelTiers.zai must be an object."], [ { zai: { small: { model: "small" } } }, "ultra.providerModelTiers.zai.small.model must be provider/model", ], [ { zai: { missing_tier: { model: "zai/glm-4.7" } } }, "ultra.providerModelTiers.zai.missing_tier: unknown tier.", ], ] as const)( "rejects malformed provider tier configuration %j", (providerModelTiers, error) => { expect(() => parseUltraSettings({ providerModelTiers })).toThrow(error); }, ); }); describe("ultra settings resolution", () => { it("defaults without settings files", async () => { expect(await resolve({})).toEqual(ULTRA_DEFAULTS); }); it("deep-merges trusted project over user settings", async () => { expect( await resolve({ user: { autoEnable: true, concurrency: 10, fanoutToolAllowlist: ["web"], actionSummarizerModel: "openai/gpt-5-mini", modelTiers: { small: { model: "openai/gpt-5-mini" } }, }, project: { concurrency: 3, fanoutToolAllowlist: ["search"], actionSummarizerModel: null, modelTiers: { large: { model: "openai/gpt-5" } }, }, }), ).toEqual({ ...ULTRA_DEFAULTS, autoEnable: true, concurrency: 3, fanoutToolAllowlist: [...DEFAULT_FANOUT_TOOLS, "search"], modelTiers: { ...DEFAULT_MODEL_TIERS, small: { ...DEFAULT_MODEL_TIERS.small, model: "openai/gpt-5-mini" }, large: { ...DEFAULT_MODEL_TIERS.large, model: "openai/gpt-5" }, }, }); }); it("ignores untrusted project settings", async () => { const settings = await resolve({ user: { concurrency: 7 }, project: { concurrency: 3, enabled: false }, untrusted: true, }); expect(settings.concurrency).toBe(7); expect(settings.enabled).toBe(true); }); it.each([ [ "invalid project", { user: { concurrency: 7 }, project: { concurrency: "3" } }, "Invalid ultra from merged project and user settings: ultra.concurrency must be a number.", ], [ "invalid user", { user: { enabled: "yes" } }, "Invalid ultra from user settings: ultra.enabled must be a boolean.", ], [ "non-object project", { user: { concurrency: 7 }, project: true }, "Invalid ultra from project settings: ultra must be an object.", ], ] satisfies [string, Sources, string][])( "rejects %s without falling through", async (_name, input, error) => { await expect(resolve(input)).rejects.toThrow(error); const [extension] = t?.session.extensionRunner.extensions ?? []; await expect( extension.commands .get("ultra") ?.handler("", t?.session.extensionRunner.createCommandContext()), ).rejects.toThrow(error); }, ); it("auto-enables from ultra.autoEnable", async () => { const session = await start({ user: { autoEnable: true } }); expect(session.session.getActiveToolNames()).toContain("run_workflow"); }); it("rejects the old ultra.auto_enable key", async () => { await expect(resolve({ user: { auto_enable: true } })).rejects.toThrow( "Invalid ultra from user settings: unknown key ultra.auto_enable.", ); expect(t?.session.getActiveToolNames()).not.toContain("run_workflow"); }); });