@preapexis/piexis 0.2.2 → 0.2.5

package/extensions/ui.ts

@@ -1,20 +1,108 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { truncateToWidth } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 
+import { readFileSync } from "node:fs";
 import { basename } from "node:path";
+import { agentConfigCapabilities } from "../lib/agent-config.ts";
+import { hasProjectAgentConfig, loadAgentConfig } from "../lib/agents.ts";
+
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+const WORDMARK = [
+  "██████╗ ██╗███████╗██╗  ██╗██╗███████╗",
+  "██╔══██╗██║██╔════╝╚██╗██╔╝██║██╔════╝",
+  "██████╔╝██║█████╗   ╚███╔╝ ██║███████╗",
+  "██╔═══╝ ██║██╔══╝   ██╔██╗ ██║╚════██║",
+  "██║     ██║███████╗██╔╝ ██╗██║███████║",
+  "╚═╝     ╚═╝╚══════╝╚═╝  ╚═╝╚═╝╚══════╝"
+];
+const WORDMARK_WIDTH = Math.max(...WORDMARK.map((line) => visibleWidth(line)));
+
+const fmt = (n: number) => {
+  if (n < 1_000) return `${n}`;
+  if (n < 1_000_000) return `${(n / 1_000).toFixed(1)}k`;
+  return `${(n / 1_000_000).toFixed(1)}m`;
+};
+
+type Seg = { text: string; priority: number };
+
+// Drop optional fields before shortening the last (highest-priority) field.
+function justify(left: string, right: Seg[], sep: string, width: number): string {
+  const segs = [...right];
+  while (segs.length) {
+    const r = segs.map((s) => s.text).join(sep);
+    const gap = width - visibleWidth(left) - visibleWidth(r);
+    if (gap >= 2) return left + " ".repeat(gap) + r;
+    let weakest = 0;
+    segs.forEach((s, i) => {
+      if (s.priority < segs[weakest].priority) weakest = i;
+    });
+    if (segs.length === 1) {
+      const available = width - visibleWidth(left) - 2;
+      if (available > 0) {
+        const text = truncateToWidth(r, available, "…");
+        return left + " ".repeat(width - visibleWidth(left) - visibleWidth(text)) + text;
+      }
+      break;
+    }
+    segs.splice(weakest, 1);
+  }
+  return truncateToWidth(left, width, "…");
+}
 
 export default function (pi: ExtensionAPI) {
+  // Jiti can retain imported JSON across reloads; read it once per extension runtime.
+  const tipList: { category: string; text: string }[] = JSON.parse(
+    readFileSync(new URL("../lib/ui-tips.json", import.meta.url), "utf8")
+  );
+  if (!Array.isArray(tipList) || tipList.some((tip) =>
+    typeof tip?.category !== "string" || !tip.category.trim() ||
+    typeof tip?.text !== "string" || !tip.text.trim()
+  )) {
+    throw new Error("Invalid ui-tips.json: expected tips with non-empty category and text strings.");
+  }
+
   let state = "ready";
   let activeTool = "";
   let redraw = () => {};
+  let remainingTips: typeof tipList = [];
+  let agentSetupTips: string[] = [];
 
   function update() {
     redraw();
   }
 
   pi.on("session_start", async (_event, ctx) => {
+    state = "ready";
+    activeTool = "";
+    redraw = () => {};
+    if (ctx.mode !== "tui") return;
+
     const project = basename(ctx.cwd);
+    agentSetupTips = [];
+    try {
+      if (ctx.isProjectTrusted() && await hasProjectAgentConfig(ctx.cwd)) {
+        const config = await loadAgentConfig(ctx.cwd, getAgentDir(), true);
+        for (const key of Object.keys(agentConfigCapabilities) as (keyof typeof agentConfigCapabilities)[]) {
+          if (config[key] === undefined) agentSetupTips.push(`Agent config: add ${key} to ${agentConfigCapabilities[key]}.`);
+        }
+      }
+    } catch {
+      agentSetupTips = ["Agent config: fix agent.json so PieXis can apply your agent settings."];
+    }
+    const selectedTips: typeof tipList = [];
+    for (let i = 0; i < Math.min(3, tipList.length); i++) {
+      if (remainingTips.length === 0) {
+        remainingTips = tipList.filter((tip) => !selectedTips.includes(tip));
+      }
+      const differentCategories = remainingTips.filter(
+        (tip) => !selectedTips.some((selected) => selected.category === tip.category)
+      );
+      const candidates = differentCategories.length > 0 ? differentCategories : remainingTips;
+      const tip = candidates[Math.floor(Math.random() * candidates.length)];
+      selectedTips.push(remainingTips.splice(remainingTips.indexOf(tip), 1)[0]);
+    }
 
     // Put project info in the terminal tab instead of wasting TUI rows.
     ctx.ui.setTitle(`π ${project}`);
@@ -23,82 +111,126 @@ export default function (pi: ExtensionAPI) {
     // stay attached to the editor forever, making the onboarding copy noisy.
     ctx.ui.setHeader((_tui, theme) => ({
       render(width: number) {
-        const rule = theme.fg(
-          "dim",
-          "─".repeat(Math.max(0, Math.min(width, 72)))
-        );
-        const lines =
-          width < 72
-            ? [
-                `${theme.fg("accent", "✦")} ${theme.bold("PieXis")}  ${theme.fg("dim", project)}`,
-                `${theme.fg("muted", "Try:")} explain code · find bugs · review diffs · run tests`,
-                `${theme.fg("dim", "/plan <task> · Alt+M modes · /help for commands")}`
-              ]
-            : [
-                `${theme.fg("accent", "✦")} ${theme.bold("PieXis")}  ${theme.fg("dim", "permission-aware coding workspace")}  ${theme.fg("muted", project)}`,
-                rule,
-                `${theme.fg("muted", "Try:")} explain code · find bugs · review diffs · trace behavior     ${theme.fg("muted", "Build:")} edit · refactor · test`,
-                `${theme.fg("muted", "Run:")} tests · lint · typecheck · Git     ${theme.fg("muted", "Plan:")} /plan <task> · Alt+M modes     ${theme.fg("dim", "Mention files, constraints, and expected behavior.")}`
-              ];
-        return lines.map((line) => truncateToWidth(line, width, ""));
+        if (width <= 0) return [];
+
+        const left = width < WORDMARK_WIDTH
+          ? [`${theme.fg("accent", "✦")} ${theme.bold("PieXis")}`]
+          : WORDMARK.map((line) => theme.fg("accent", line));
+
+        const tips = [
+          theme.fg("accent", theme.bold("Get started with PieXis")),
+          theme.fg("muted", "Questions, skills, prompts & stats."),
+          ...agentSetupTips.map((tip) => theme.fg("warning", tip)),
+          ...selectedTips.map((tip) =>
+            `${theme.fg("accent", `[${tip.category}]`)} ${theme.fg("muted", tip.text)}`
+          ),
+          theme.fg("dim", "/help · /summary · /commit")
+        ];
+        const tipWidth = width - WORDMARK_WIDTH - 3;
+        if (tipWidth >= 32) {
+          const right = tips.flatMap((line) => wrapTextWithAnsi(line, tipWidth));
+          return Array.from({ length: Math.max(left.length, right.length) }, (_, index) => {
+            const line = truncateToWidth(left[index] ?? "", WORDMARK_WIDTH, "");
+            const padding = " ".repeat(WORDMARK_WIDTH - visibleWidth(line) + 3);
+            return line + padding + (right[index] ?? "");
+          });
+        }
+
+        return [
+          ...left.map((line) => truncateToWidth(line, width, "")),
+          "",
+          ...tips.flatMap((line) => wrapTextWithAnsi(line, width))
+        ];
       },
       invalidate() {}
     }));
 
     ctx.ui.setFooter((tui, theme, footerData) => {
       redraw = () => tui.requestRender();
+      const unsubscribe = footerData.onBranchChange(() => tui.requestRender());
 
-      const unsubscribe = footerData.onBranchChange(() => {
-        tui.requestRender();
-      });
+      // Spinner animation, only while busy.
+      const timer = setInterval(() => {
+        if (state !== "ready") tui.requestRender();
+      }, 100);
+      timer.unref?.();
 
       return {
         invalidate() {},
 
         render(width: number) {
-          const branch = footerData.getGitBranch() ?? "—";
+          if (width <= 0) return [];
+          const dim = (s: string) => theme.fg("dim", s);
+          const muted = (s: string) => theme.fg("muted", s);
+          const sep = dim(" · ");
+          const prompts = ctx.sessionManager.getEntries().filter(
+            (entry) => entry.type === "message" && entry.message.role === "user"
+          ).length;
 
-          const model = ctx.model?.id?.replace(/^gpt-/, "") ?? "—";
-          const effort = ctx.thinkingLevel ?? "off";
-
-          const usage = ctx.getContextUsage();
-
-          const context =
-            usage?.percent != null
-              ? `ctx ${Math.round(usage.percent)}%`
-              : "ctx —";
+          let input = 0, output = 0, cacheRead = 0, cacheWrite = 0, cost = 0;
+          for (const entry of ctx.sessionManager.getBranch()) {
+            if (entry.type !== "message" || entry.message.role !== "assistant") continue;
+            const u = entry.message.usage;
+            if (!u) continue;
+            input += u.input;
+            output += u.output;
+            cacheRead += u.cacheRead;
+            cacheWrite += u.cacheWrite;
+            cost += u.cost?.total ?? 0;
+          }
 
-          let activity: string;
+          const frame = SPINNER[Math.floor(Date.now() / 100) % SPINNER.length];
+          const activity = state === "tool" ? `${frame} ${activeTool}`
+            : state === "thinking" ? `${frame} thinking` : "● ready";
+          const agent = footerData.getExtensionStatuses?.().get("piexis-agent");
+          const branch = footerData.getGitBranch();
+          // Reserve a small model slot; long tool names must not displace the profile.
+          const modelReserve = width >= 32 ? 9 : 0;
+          const profile = agent && visibleWidth(agent) + 6 + modelReserve <= width
+            ? theme.fg("accent", agent) + sep : "";
+          const activityWidth = Math.max(1, Math.min(24, width - visibleWidth(profile) - modelReserve));
+          const left1 = profile + theme.fg(state === "ready" ? "success" : "accent",
+            truncateToWidth(activity, activityWidth, "…"));
+          const row1 = justify(left1, [
+            { text: ctx.model?.id ?? "—", priority: 5 },
+            { text: muted(`think ${pi.getThinkingLevel()}`), priority: 4 },
+            ...(branch ? [{ text: dim(`⎇ ${truncateToWidth(branch, Math.max(8, Math.floor(width / 4)), "…")}`), priority: 3 }] : []),
+            { text: dim(`${prompts} prompts`), priority: 2 },
+            ...(agent ? [{ text: dim("[Alt+A]"), priority: 1 }] : [])
+          ], sep, width);
 
-          if (state === "tool") {
-            activity = theme.fg("accent", `◆ ${activeTool}`);
-          } else if (state === "thinking") {
-            activity = theme.fg("accent", "◆ thinking");
-          } else {
-            activity = theme.fg("success", "● ready");
-          }
+          const usage = ctx.getContextUsage();
+          const pct = usage?.percent ?? null;
+          const tone = pct == null ? "dim" : pct >= 90 ? "error" : pct >= 70 ? "warning" : "success";
+          const pctText = pct == null ? "—" : `${Math.round(pct)}%`;
+          const costText = `$${cost < 0.01 ? cost.toFixed(4) : cost.toFixed(2)}`;
+          const barWidth = Math.min(12, Math.max(0,
+            width - visibleWidth(`ctx  ${pctText}`) - visibleWidth(costText) - 2));
+          const filled = pct == null ? 0 : Math.round((Math.min(100, Math.max(0, pct)) / 100) * barWidth);
+          const bar = theme.fg(tone, "━".repeat(filled)) + dim("─".repeat(barWidth - filled));
+          const cap = usage
+            ? `${usage.tokens == null ? "—" : fmt(usage.tokens)}/${fmt(usage.contextWindow)}`
+            : "—/—";
+          const context = `${muted("ctx")} ${barWidth ? bar + " " : ""}${theme.fg(tone, pctText)}`;
+          const tokens = muted(`↑${fmt(input)} ↓${fmt(output)}`);
+          const promptTotal = input + cacheRead + cacheWrite;
+          const hit = promptTotal > 0 ? Math.round((cacheRead / promptTotal) * 100) : null;
+          // Add capacity only when it leaves room for the basic token totals and cost.
+          const showCapacity = visibleWidth(context + " " + cap + tokens + costText) + 7 <= width;
+          const left2 = context + (showCapacity ? " " + dim(cap) : "");
+          const row2 = justify(left2, [
+            { text: tokens, priority: 2 },
+            ...(hit == null ? [] : [{ text: dim(`cache ${hit}%`), priority: 1 }]),
+            { text: muted(costText), priority: 3 }
+          ], sep, width);
 
-          const statuses = [...footerData.getExtensionStatuses().values()];
-          // Keep this tolerant of theme/icon changes in the permission extension.
-          const modeStatus =
-            statuses.find((status) =>
-              /(?:manual|accept edits|plan|auto|don't ask|bypass permissions).*on/i.test(
-                status
-              )
-            ) ?? "";
-          const line =
-            `${activity}` +
-            (modeStatus ? theme.fg("accent", ` │ ${modeStatus}`) : "") +
-            theme.fg(
-              "dim",
-              ` │ ${branch}` + ` │ ${model}` + ` │ ${context}`
-            );
-
-          return [truncateToWidth(line, width, "")];
+          return [row1, row2];
         },
 
         dispose() {
+          clearInterval(timer);
           unsubscribe();
+          redraw = () => {};
         }
       };
     });
@@ -112,6 +244,20 @@ export default function (pi: ExtensionAPI) {
     update();
   });
 
+  pi.on("turn_start", async () => {
+    state = "thinking";
+    activeTool = "";
+    update();
+  });
+
+  pi.on("message_end", async () => {
+    update();
+  });
+
+  pi.on("session_compact", async () => {
+    update();
+  });
+
   pi.on("tool_call", async (event) => {
     state = "tool";
     activeTool = event.toolName;

package/extensions/webui.ts

@@ -0,0 +1,45 @@
+import { randomBytes } from "node:crypto";
+import { spawn, type ChildProcess } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { createServer } from "node:net";
+import path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+async function availablePort(): Promise<number> {
+  const server = createServer();
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+  const address = server.address();
+  await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+  if (!address || typeof address === "string") throw new Error("Could not select a local PIXIS WebUI port.");
+  return address.port;
+}
+
+/** Starts the separate local WebUI; Pi's TUI remains usable in this process. */
+export default function webui(pi: ExtensionAPI) {
+  const servers = new Map<string, ChildProcess>();
+  const launcher = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../bin/piexis-web.mjs");
+
+  pi.registerCommand("webui", {
+    description: "Start the local PIXIS WebUI for this workspace",
+    handler: async (_args, ctx) => {
+      const running = servers.get(ctx.cwd);
+      if (running && running.exitCode === null && !running.killed) {
+        ctx.ui.notify("PIXIS WebUI is already running for this workspace.", "info");
+        return;
+      }
+      const token = randomBytes(32).toString("base64url");
+      const port = await availablePort();
+      const child = spawn(process.execPath, [launcher, "--workspace", ctx.cwd, "--port", `${port}`, "--token", token], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true
+      });
+      child.unref();
+      servers.set(ctx.cwd, child);
+      ctx.ui.notify(`PIXIS WebUI started: http://127.0.0.1:${port}/#token=${token}`, "info");
+    }
+  });
+}

package/lib/agent-config.ts

@@ -0,0 +1,55 @@
+export const agentNames = ["plan", "orchestrator", "debug", "ask", "code"] as const;
+export type AgentName = typeof agentNames[number];
+export const effortLevels = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type Effort = typeof effortLevels[number];
+
+export const agentConfigSchemaUrl = "https://raw.githubusercontent.com/VarunGaikwad/piexis/main/schemas/agent.schema.json";
+
+export interface AgentConfig {
+  "$schema"?: string;
+  model?: string;
+  small_model?: string;
+  subagent_model?: string;
+  delegate_exploration?: boolean;
+  subagent_variant_overrides?: Partial<Record<AgentName, { model?: string; effort?: Effort }>>;
+}
+
+/**
+ * Static values written to a newly created .pi/agent.json.
+ * Add new static AgentConfig properties here so project setup includes them.
+ */
+export const initialAgentConfigDefaults = {
+  "$schema": agentConfigSchemaUrl,
+  delegate_exploration: false,
+} satisfies Pick<AgentConfig, "$schema" | "delegate_exploration">;
+
+/** Header copy for incomplete project agent configuration. */
+export type AgentConfigSetting = Exclude<keyof AgentConfig, "$schema">;
+
+export const agentConfigCapabilities = {
+  model: "choose the default main model",
+  small_model: "use a cheaper model for eligible small tasks",
+  subagent_model: "choose the normal model for delegated work",
+  delegate_exploration: "opt in to cheap, read-only codebase exploration",
+  subagent_variant_overrides: "customize model and effort for each agent profile",
+} satisfies Record<AgentConfigSetting, string>;
+
+export function createInitialAgentConfig(selected: string, inherited: AgentConfig): AgentConfig {
+  const efforts: Record<AgentName, Effort> = { plan: "high", orchestrator: "high", debug: "high", ask: "low", code: "medium" };
+  const overrides: NonNullable<AgentConfig["subagent_variant_overrides"]> = {};
+  for (const name of agentNames) {
+    overrides[name] = {
+      model: inherited.subagent_model ?? selected,
+      effort: efforts[name],
+      ...inherited.subagent_variant_overrides?.[name],
+    };
+  }
+  return {
+    "$schema": initialAgentConfigDefaults.$schema,
+    model: selected,
+    small_model: inherited.small_model ?? selected,
+    subagent_model: inherited.subagent_model ?? selected,
+    delegate_exploration: inherited.delegate_exploration ?? initialAgentConfigDefaults.delegate_exploration,
+    subagent_variant_overrides: overrides,
+  };
+}

package/lib/agents.ts

@@ -0,0 +1,208 @@
+import { link, lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { agentNames, createInitialAgentConfig, effortLevels, type AgentConfig, type AgentName, type Effort } from "./agent-config.ts";
+
+export { agentNames, type AgentConfig, type AgentName, effortLevels, type Effort } from "./agent-config.ts";
+
+export const profiles: Record<AgentName, string> = {
+  plan: "Explore the request and relevant code, clarify important unknowns, and return an actionable plan with acceptance checks. Do not implement or delegate implementation. Stop after the plan.",
+  orchestrator: "Break work into focused tasks and delegate to plan, debug, ask, or code using subagent. Include all necessary context in each task; children do not inherit the conversation. Keep overlapping file changes sequential. Inspect results, resolve disagreements, and report verification evidence. Do not delegate the same orchestration task recursively.",
+  debug: "Reproduce or establish evidence for the failure, trace its cause before editing, and make the smallest justified fix. Verify with a regression check. Separate confirmed facts from hypotheses and report any unexecuted checks.",
+  ask: "Answer the user's question using relevant code or documentation as evidence. Do not change files or delegate changes. When context is missing, ask rather than invent facts. Stop when the question is answered.",
+  code: "Implement the requested scope using existing repository patterns. Preserve unrelated changes, add focused coverage for behavior changes, run relevant checks, and report results. Stop when acceptance conditions are met.",
+};
+
+export function isAgentName(value: unknown): value is AgentName {
+  return typeof value === "string" && agentNames.includes(value as AgentName);
+}
+
+function object(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  return value as Record<string, unknown>;
+}
+
+function model(value: unknown, label: string): string {
+  if (typeof value !== "string" || !/^[^\s/]+\/\S+$/.test(value)) {
+    throw new Error(`${label} must be an exact provider/model ID`);
+  }
+  return value;
+}
+
+export function parseAgentConfig(value: unknown): AgentConfig {
+  const source = object(value, "Agent configuration");
+  const result: AgentConfig = {};
+  for (const key of Object.keys(source)) {
+    if (!["$schema", "model", "small_model", "subagent_model", "delegate_exploration", "subagent_variant_overrides"].includes(key)) {
+      throw new Error(`Unknown agent configuration key: ${key}`);
+    }
+  }
+  if (source.$schema !== undefined) {
+    if (typeof source.$schema !== "string") throw new Error("$schema must be a string");
+    result.$schema = source.$schema;
+  }
+  for (const key of ["model", "small_model", "subagent_model"] as const) {
+    if (source[key] !== undefined) result[key] = model(source[key], key);
+  }
+  if (source.delegate_exploration !== undefined) {
+    if (typeof source.delegate_exploration !== "boolean") throw new Error("delegate_exploration must be a boolean");
+    result.delegate_exploration = source.delegate_exploration;
+  }
+  if (source.subagent_variant_overrides !== undefined) {
+    result.subagent_variant_overrides = {};
+    for (const [name, value] of Object.entries(object(source.subagent_variant_overrides, "subagent_variant_overrides"))) {
+      if (!isAgentName(name)) throw new Error(`Unknown agent variant: ${name}`);
+      const override = object(value, `Override ${name}`);
+      for (const key of Object.keys(override)) {
+        if (key !== "model" && key !== "effort") throw new Error(`Unknown override key: ${name}.${key}`);
+      }
+      const parsed: { model?: string; effort?: Effort } = {};
+      if (override.model !== undefined) parsed.model = model(override.model, `${name}.model`);
+      if (override.effort !== undefined) {
+        if (!effortLevels.includes(override.effort as Effort)) throw new Error(`Invalid effort for ${name}`);
+        parsed.effort = override.effort as Effort;
+      }
+      result.subagent_variant_overrides[name] = parsed;
+    }
+  }
+  return result;
+}
+
+export async function loadAgentConfig(cwd: string, agentDir: string, trusted: boolean): Promise<AgentConfig> {
+  async function load(directory: string): Promise<AgentConfig> {
+    for (const name of ["agent.json", "agents.json"]) {
+      const path = join(directory, name);
+      try { return parseAgentConfig(JSON.parse(await readFile(path, "utf8"))); }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+        throw new Error(`${path}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    return {};
+  }
+  const global = await load(agentDir);
+  const project = trusted ? await load(join(cwd, ".pi")) : {};
+  const overrides = { ...global.subagent_variant_overrides };
+  for (const name of agentNames) {
+    if (project.subagent_variant_overrides?.[name]) {
+      overrides[name] = { ...overrides[name], ...project.subagent_variant_overrides[name] };
+    }
+  }
+  return { ...global, ...project, subagent_variant_overrides: overrides };
+}
+
+export async function hasProjectAgentConfig(cwd: string): Promise<boolean> {
+  for (const name of ["agent.json", "agents.json"]) {
+    try { await lstat(join(cwd, ".pi", name)); return true; }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  }
+  return false;
+}
+
+/** Create an opt-in project scaffold atomically, never replace existing or legacy configuration. */
+export async function initializeAgentConfig(cwd: string, agentDir: string, defaultModel: string | undefined, signal?: AbortSignal): Promise<boolean> {
+  const directory = join(cwd, ".pi");
+  const path = join(directory, "agent.json");
+  return withFileMutationQueue(path, async () => {
+    signal?.throwIfAborted();
+    if (await hasProjectAgentConfig(cwd)) return false;
+    if (!defaultModel) throw new Error("No active model; select a model and create .pi/agent.json manually.");
+    const inherited = await loadAgentConfig(cwd, agentDir, false);
+    const selected = inherited.model ?? model(defaultModel, "Default model");
+    const config = createInitialAgentConfig(selected, inherited);
+    signal?.throwIfAborted();
+    await mkdir(directory, { recursive: true });
+    const temporary = join(directory, `.agent.json.piexis-${randomUUID()}.tmp`);
+    try {
+      await writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+      signal?.throwIfAborted();
+      if (await hasProjectAgentConfig(cwd)) return false;
+      // Unlike rename, link fails if another writer has already created the destination.
+      try { await link(temporary, path); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code === "EEXIST") return false; throw error; }
+      return true;
+    } finally { await rm(temporary, { force: true }); }
+  });
+}
+
+export async function completeProjectAgentConfig(cwd: string, agentDir: string, defaultModel: string | undefined, signal?: AbortSignal): Promise<"created" | "updated" | "complete"> {
+  const directory = join(cwd, ".pi");
+  let path: string | undefined;
+  for (const name of ["agent.json", "agents.json"]) {
+    const candidate = join(directory, name);
+    try { await lstat(candidate); path = candidate; break; }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  }
+  if (!path) {
+    if (!await initializeAgentConfig(cwd, agentDir, defaultModel, signal)) return "complete";
+    return "created";
+  }
+  return withFileMutationQueue(path, async () => {
+    signal?.throwIfAborted();
+    if (!(await lstat(path!)).isFile()) throw new Error(`${path} must be a regular file`);
+    const source = parseAgentConfig(JSON.parse(await readFile(path!, "utf8")));
+    const inherited = await loadAgentConfig(cwd, agentDir, false);
+    const selected = source.model ?? inherited.model ?? (defaultModel ? model(defaultModel, "Default model") : undefined);
+    if (!selected) throw new Error("No active model; select a model and configure .pi/agent.json manually.");
+    const defaults = createInitialAgentConfig(selected, inherited);
+    const overrides: NonNullable<AgentConfig["subagent_variant_overrides"]> = {};
+    let changed = Object.keys(defaults).some((key) => source[key as keyof AgentConfig] === undefined);
+    for (const name of agentNames) {
+      const expected = defaults.subagent_variant_overrides![name]!;
+      const actual = source.subagent_variant_overrides?.[name];
+      if (!actual?.model || actual.effort === undefined) changed = true;
+      overrides[name] = { ...expected, ...actual };
+    }
+    if (!changed) return "complete";
+    const config: AgentConfig = { ...defaults, ...source, subagent_variant_overrides: overrides };
+    const temporary = join(directory, `.${basename(path!)}.piexis-${randomUUID()}.tmp`);
+    try {
+      await writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+      signal?.throwIfAborted();
+      await rename(temporary, path!);
+      return "updated";
+    } finally { await rm(temporary, { force: true }); }
+  });
+}
+
+export function isSmallTask(agent: AgentName, task: string): boolean {
+  // shortcut: conservative text heuristic, replace with evaluated routing if real tasks outgrow it.
+  if (task.length > 400 || task.split(/\s+/).length > 65) return false;
+  if (/\b(architect\w*|design|implement|investigate|debug|refactor|migrat\w*|security|race|performance|across|multiple|entire|comprehensive)\b/i.test(task)) return false;
+  if (agent === "ask") return /^\s*(find|locate|list|what (is|does|file)|where (is|are)|explain|summari[sz]e)\b/i.test(task);
+  if (agent === "code") return /^\s*(fix (a |the )?typo|correct (a |the )?typo|rename (a |the )?(variable|symbol)|update (a |the )?(comment|label))\b/i.test(task);
+  return false;
+}
+
+export function routeSubagent(config: AgentConfig, agent: AgentName, task: string, currentModel: string, currentEffort: Effort, exploration = false) {
+  if (exploration) {
+    if (!config.small_model) throw new Error("Exploration delegation requires small_model in agent.json");
+    return { model: config.small_model, effort: "low" as Effort, reason: "configured exploration small model" };
+  }
+  const override = config.subagent_variant_overrides?.[agent];
+  const small = Boolean(config.small_model && isSmallTask(agent, task) && !override?.model);
+  return {
+    model: override?.model ?? (small ? config.small_model! : config.subagent_model ?? currentModel),
+    effort: override?.effort ?? (small ? "low" : currentEffort),
+    reason: override?.model ? "variant override" : small ? "automatic small task" : "default subagent",
+  };
+}
+
+export function subagentTools(agent: AgentName, active: string[], depth: number, allowExplorationDelegation = false): string[] {
+  if (agent === "plan" || agent === "ask") {
+    return active.filter((name) => ["read", "grep", "find", "ls"].includes(name) || (allowExplorationDelegation && depth < 2 && name === "subagent"));
+  }
+  return active.filter((name) => name !== "AskQuestion" && (name !== "subagent" || depth < 2));
+}
+
+export function childResourceArgs(argv: string[]): string[] {
+  const result: string[] = [];
+  const values = ["--extension", "-e", "--skill", "--prompt-template", "--system-prompt", "--append-system-prompt"];
+  const flags = ["--no-extensions", "-ne", "--no-skills", "-ns", "--no-prompt-templates", "-np", "--no-context-files", "-nc", "--no-mcp", "--offline"];
+  for (let i = 0; i < argv.length && argv[i] !== "--"; i++) {
+    if (values.includes(argv[i]) && argv[i + 1] !== undefined) result.push(argv[i], argv[++i]);
+    else if (flags.includes(argv[i])) result.push(argv[i]);
+  }
+  return result;
+}