@visual-z/xeno 0.5.0 → 0.7.0

package/src/apps/shell.ts

@@ -81,6 +81,11 @@ import {
   openSessionFor, sessionDirFor, retryHandler, whyNot, splitModelPatterns, runModelsRefresh, sessionToolCatalog, type App,
 } from "./startup.ts";
 import type { TurnSurface, Ui } from "./ui/surface.ts";
+import { runManualUpdate } from "./update-check.ts";
+import { presentQuestions } from "./question-ui.ts";
+import { bindAppWorkflow, setAppWorkflow } from "./workflow.ts";
+import { appReviewSnapshot, runReview, reviewScopeFromText } from "./review.ts";
+import { selectAppAgent, listAppAgents } from "./agent-profiles.ts";
 
 /**
  * One line. Listing all ~40 commands here wrapped into a two-line wall that
@@ -113,6 +118,11 @@ function extensionContext(app: App, tui?: Ui): ExtensionContext {
 }
 
 async function bindExtensions(app: App, tui?: Ui): Promise<void> {
+  bindAppWorkflow(app);
+  if (tui) {
+    const control = sessionControl(app.session);
+    control.questionSlot.current = (request, signal) => control.askQuestion(request, signal, current => presentQuestions(tui.extensionUi, current, signal));
+  }
   tui?.bindExtensionRegistry();
   const registry = app.extensions; if (!registry) return;
   const history = await readNodeHistory(app.logDir, app.session.state.node);
@@ -426,6 +436,24 @@ type Outcome = "continue" | "quit" | { login: string };
 
 async function execute(app: App, command: Command, tui: Ui | null): Promise<Outcome> {
   switch (command.kind) {
+    case "workflow":
+      await setAppWorkflow(app, command.mode); app.io.say(`  Workflow: ${command.mode}`); await tui?.refreshResources(); return "continue";
+    case "agent":
+      if (command.name) { await selectAppAgent(app, command.name); await bindExtensions(app, tui ?? undefined); await tui?.refreshResources(); }
+      else app.io.say(await listAppAgents(app)); return "continue";
+    case "mcp": {
+      const manager = app.foundation?.mcp; if (!manager) throw Error("MCP resources are unavailable");
+      if (command.action === "status") app.io.say(JSON.stringify(manager.status(), null, 2));
+      else {
+        if (!command.name) throw Error(`Use /mcp ${command.action} <server>`);
+        if (command.action === "login") await manager.login(command.name, url => { app.io.say(`  Complete MCP login: ${url.href}`); }, tui?.signal);
+        else await manager.logout(command.name);
+        await reloadAppResources(app); await bindExtensions(app, tui ?? undefined); await tui?.refreshResources();
+      }
+      return "continue";
+    }
+    case "diff": { const snapshot = await appReviewSnapshot(app, reviewScopeFromText(command.args), tui?.signal); app.io.say(`${snapshot.label}\n${snapshot.diff || "(no captured changes)"}\n${snapshot.limitations.join("\n")}`); return "continue"; }
+    case "review": await runReview(app, reviewScopeFromText(command.args), tui?.signal); await tui?.syncTranscript(); return "continue";
     case "extension":
       if (tui) tui.runExtensionCommand(command.name, command.args);
       else { await bindExtensions(app); await app.extensions?.command(command.name, command.args); }
@@ -626,6 +654,10 @@ async function execute(app: App, command: Command, tui: Ui | null): Promise<Outc
       if (tui) tui.showDocument("Changelog", text); else app.io.say(text);
       return "continue";
     }
+    case "update":
+      if (tui) tui.checkForUpdate();
+      else await runManualUpdate({ offline: app.args.offline === true }, app.io.say);
+      return "continue";
     case "copy":
       await copyLastReply(app, tui ?? undefined);
       return "continue";
@@ -707,7 +739,7 @@ function printUsage(app: App): void {
   } else {
     return assertNever(dollars, "printUsage");
   }
-  app.io.say(`  wall clock        ${(t.ms / 1000).toFixed(1)}s`);
+  app.io.say(`  model time        ${(t.ms / 1000).toFixed(1)}s`);
   app.io.say("");
 }
 
@@ -1625,6 +1657,7 @@ async function adoptLogDir(app: App, logDir: string): Promise<boolean> {
     app.resources = opened.resources.index;
     app.projectTrusted = opened.resources.trusted;
     app.extensions = opened.resources.extensions;
+    app.foundation = opened.resources.foundation;
   } catch (err) {
     app.io.say(app.io.palette.red(`  ${describeError(err)}`));
     return false;
@@ -1868,6 +1901,10 @@ export async function runTurn(
   let live = false;
   let skipFinal = false;
   const json = app.args?.mode === "json";
+  const checkedOutput = app.session.config.validateOutput !== undefined;
+  let finalText: string[] = [];
+  let completed = false;
+  let failure: string | undefined;
   const pull = tui?.pullQueued?.bind(tui);
   const registry = app.extensions;
   const before = await registry?.emit("before_agent_start", { prompt: userInputData(prompt).text, systemPrompt: app.session.config.frozen.system }) ?? [];
@@ -1878,6 +1915,14 @@ export async function runTurn(
   await registry?.emit("agent_start");
   await registry?.emit("turn_start", { turnIndex: 0 });
   try { for await (const e of skill ? app.session.sendSkill(skill, prompt, signal) : sessionControl(app.session).send(prompt, signal, pull)) {
+    // The log retains every response, but a script's final answer must be the
+    // accepted last response. A rejected JSON document cannot be unwritten.
+    if (e.kind === "turn_start" || e.kind === "discard") finalText = [];
+    if (e.kind === "assistant_text") finalText.push(e.text ?? "");
+    if (e.kind === "done") {
+      completed = e.outcome?.status === "completed";
+      if (checkedOutput && !completed) failure = e.reason ?? "output schema validation did not complete";
+    }
     tui?.observeEvent?.(e);
     if (e.kind === "text_delta" || e.kind === "thinking_delta") await registry?.emit("message_update", { assistantMessageEvent: { type: e.kind, delta: e.text } });
     if (e.kind === "assistant_text") await registry?.emit("message_end", { message: { role: "assistant", content: [{ type: "text", text: e.text }] } });
@@ -1887,6 +1932,7 @@ export async function runTurn(
       if (payload !== null) process.stdout.write(`${JSON.stringify(payload)}\n`);
       continue;
     }
+    if (checkedOutput && !tui && e.kind === "assistant_text") continue;
     if (e.kind === "progress") { if (e.progress) tui?.pushProgress?.(e.progress); continue; }
     if (tui?.syncTranscript) {
       if (e.kind === "usage" && e.ok === false && e.prefix && app.ui?.settings.showCacheMissNotices === true)
@@ -1940,6 +1986,14 @@ export async function runTurn(
       app.io.say(line);
     }
   } } finally { await registry?.emit("agent_end", { messages: structuredClone(app.session.state.events) }); }
+  if (failure) throw Error(failure);
+  if (completed) {
+    const text = finalText.join("\n");
+    if (checkedOutput && !tui && !json) {
+      if (app.io.answer) app.io.answer(text); else app.io.say(text);
+    }
+    if (app.args?.outputLastMessage) await writeFile(resolve(app.args.outputLastMessage), text.endsWith("\n") ? text : text + "\n", "utf8");
+  }
 }
 
 // ---------------------------------------------------------------------------

package/src/apps/startup.ts

@@ -39,6 +39,7 @@ import type { Settings } from "../core/settings.ts";
 import { readModelSources, readCatalogCacheText, writeCatalogCache, catalogCachePath } from "../store/models.ts";
 import { refreshRemoteCatalog } from "../runtime/models-fetch.ts";
 import { readCursor, writeCursor, type Cursor } from "../store/log.ts";
+import { getBlob } from "../store/blobs.ts";
 import { resolveLogDir, findSessionByPrefix, listSessions, sessionsDir, type ResolveLogOpts } from "../store/sessions.ts";
 import { recoverCut } from "../store/recovery.ts";
 import { planSessionEntry, restoreSessionModel } from "../core/session-entry.ts";
@@ -63,6 +64,13 @@ import {
 import { colorEnabled, createPalette, describeError, stdinIsTty, stdoutIsTty, type Palette } from "./render.ts";
 import { type ActionId, type Keymap } from "../core/keymap.ts";
 import type { StartupInput } from "./startup-input.ts";
+import { FoundationRuntime } from "../runtime/foundation.ts";
+import { readFoundationConfig, readOutputSchema } from "../store/foundation-config.ts";
+import { outputValidator } from "../runtime/output-schema.ts";
+import { loadAgentProfileLayers } from "../runtime/agent-profiles.ts";
+import { resolveAgentProfile, builtinAgentProfileLayer, type ResolvedAgentProfile } from "../core/agent-profile.ts";
+import { workflowToolNames, workflowInstructions, isWorkflowMode, type WorkflowMode } from "../core/workflow-mode.ts";
+import { resolveContextWorkspace } from "../store/context-files.ts";
 
 export const SYSTEM_PROMPT = systemPromptFor(TOOL_SCHEMAS.map((tool) => tool.name));
 
@@ -126,6 +134,15 @@ export type AskSlot = {
 };
 
 export interface Args {
+  agentBase?: { model: string; provider: string; thinking: string; maxTurns: number; excludeTools: string[]; noTools: boolean; noBuiltinTools: boolean;
+    tools?: string[]; toolProfile?: ToolProfile; timeBudgetMs?: number; workflow?: WorkflowMode };
+  clientMcp?: import("../core/mcp-config.ts").McpServers;
+  workflow?: WorkflowMode;
+  agent?: string;
+  outputSchema?: string;
+  outputLastMessage?: string;
+  cliFlags?: readonly string[];
+  role?: ResolvedAgentProfile;
   shellCheckpoints?: boolean;
   workspace: string;
   /**
@@ -155,6 +172,7 @@ export interface Args {
   modelSearch?: string;
   help?: boolean;
   version?: boolean;
+  manualUpdateCheck?: boolean;
   exportFile?: string;
   offline?: boolean;
   tuiMode?: "regular" | "fullscreen";
@@ -233,14 +251,15 @@ export interface Args {
 }
 
 /**
- * Names `parseArgs` actually accepts. `--refresh` is not here: it is only
- * valid after the `models` subcommand, and listing it would make a top-level
+ * Names `parseArgs` actually accepts. Subcommand-only `--refresh` and
+ * `--check` are not here; listing them would make a top-level
  * `--refresh` suggest itself while still being rejected.
  *
  * Keep in sync with the branches in `parseArgs`. A missing entry still
  * parses; it just cannot be offered as a suggestion.
  */
 const KNOWN_FLAGS: readonly string[] = [
+  "--workflow", "--agent", "--output-schema", "--output-last-message",
   "--checkpoint-shell",
   "--workspace", "-w",
   "--path-root",
@@ -337,7 +356,9 @@ function rejectUnknownFlag(flag: string): never {
 
 export function parseArgs(argv: string[], options: { deferExtensions?: boolean; flags?: ReadonlyMap<string, ExtensionFlag> } = {}): Args {
   let selectedTheme: string | undefined;
+  let updateExtensions = false;
   const args: Args = {
+    cliFlags: argv.filter(value => value.startsWith("-")),
     workspace: process.cwd(), logDir: "", maxTurns: 40, prompt: "",
     // Overridable so a node boundary can be forced in a short session --
     // otherwise cutting is only reachable after tens of thousands of tokens,
@@ -362,7 +383,10 @@ export function parseArgs(argv: string[], options: { deferExtensions?: boolean;
       console.error(`${a} requires a value`);
       process.exit(1);
     }
-    if (a === "--checkpoint-shell") args.shellCheckpoints = true;
+    if (a === "--workflow") { const mode = argv[++i]; if (!mode || !isWorkflowMode(mode)) throw Error("--workflow requires build or plan"); args.workflow = mode; }
+    else if (a === "--agent") { const name = argv[++i]; if (!name || name.startsWith("-")) throw Error("--agent requires a profile name"); args.agent = name; }
+    else if (a === "--output-schema" || a === "--output-last-message") { const path = argv[++i]; if (!path || path.startsWith("-")) throw Error(`${a} requires a file path`); if (a === "--output-schema") args.outputSchema = resolve(path); else args.outputLastMessage = resolve(path); }
+    else if (a === "--checkpoint-shell") args.shellCheckpoints = true;
     else if (a === "--workspace" || a === "-w") args.workspace = argv[++i] ?? args.workspace;
     else if (a === "--path-root") args.pathRoot = resolve(argv[++i] ?? "/");
     else if (a === "--state-dir") args.stateDir = resolve(argv[++i] ?? ".");
@@ -398,7 +422,8 @@ export function parseArgs(argv: string[], options: { deferExtensions?: boolean;
     else if (a === "config" && i === 0) args.configCommand = true;
     else if ((a === "install" || a === "remove" || a === "update" || a === "list") && i === 0) args.packageCommand = {operation:a,sources:[]};
     else if ((a === "--local" || a === "-l") && (args.packageCommand || args.configCommand)) { args.local=true; if(args.packageCommand)args.packageCommand.local=true; }
-    else if (a === "--extensions" && args.packageCommand?.operation === "update") { /* Package-only update; xeno never self-updates. */ }
+    else if (a === "--extensions" && args.packageCommand?.operation === "update") updateExtensions = true;
+    else if (a === "--check" && args.packageCommand?.operation === "update") args.manualUpdateCheck = true;
     else if (a === "--refresh" && args.modelsCommand) {
       args.modelsRefresh = true;
     }
@@ -424,7 +449,7 @@ export function parseArgs(argv: string[], options: { deferExtensions?: boolean;
     }
     else if (a === "--tool-profile") {
       const value = argv[++i] ?? "";
-      if (!isToolProfile(value)) throw new Error("unknown tool profile; choose coding, readonly, research, data or full");
+      if (!isToolProfile(value)) throw new Error("unknown tool profile; choose coding, readonly, research, data, foundation or full");
       args.toolProfile = value;
     }
     else if (a === "--exclude-tools" || a === "-xt") args.excludeTools = parseToolList(argv[++i] ?? "");
@@ -496,6 +521,9 @@ export function parseArgs(argv: string[], options: { deferExtensions?: boolean;
     else args.prompt += (args.prompt ? " " : "") + a;
   }
   if (selectedTheme !== undefined) args.theme = selectedTheme;
+  if (args.manualUpdateCheck && (args.packageCommand!.sources.length || args.local || updateExtensions || args.prompt)) {
+    throw new Error("update --check cannot be combined with package sources, --local, or --extensions");
+  }
   return args;
 }
 
@@ -718,6 +746,7 @@ export interface AppIO {
 }
 
 export interface App {
+  foundation?: FoundationRuntime;
   args: Args;
   session: Session;
   workspace: string;
@@ -847,6 +876,11 @@ export function toolSelectionOf(args: Args) {
   };
 }
 
+export function processPermissionRules(args: Args, foundation?: FoundationRuntime, hostRules?: readonly PermissionRule[]): PermissionRule[] {
+  const configured = [...args.role?.profile.permissions ?? [], ...foundation?.permissions ?? []];
+  return [...(args.yolo ? configured.filter(rule => rule.action === "deny") : configured), ...(hostRules ?? rulesWithAllowTools(args.allowTools, { yolo: args.yolo }))];
+}
+
 /**
  * Schema assembly: every tool is tagged with a source here so
  * `--no-builtin-tools` can drop a category without a later cross-layer
@@ -858,13 +892,15 @@ export function toolSelectionOf(args: Args) {
  * argument.
  */
 export function sessionToolCatalog(args: Args, extensions?: ExtensionRegistry, previous: readonly unknown[] = [], builtinDefaults?: readonly string[]) {
-  const custom = [...extensions?.definitions().values() ?? []].map(({ name, description, input_schema }) => ({ name, description, input_schema, source: "extension" as const }));
+  const custom = [...extensions?.definitions().values() ?? []].map(tool => ({ ...tool, source: extensions?.builtinTools.has(tool.name) ? "builtin" as const : "extension" as const }));
   // O.7/D6: a cold app open uses saved capabilities as defaults, never today's profile.
   // Explicit selection still wins; extension loading and current exclusions remain live.
   const retained = builtinDefaults !== undefined && args.tools === undefined && args.toolProfile === undefined ? new Set(builtinDefaults) : undefined;
   const available = [...TOOL_DEFINITIONS.filter(tool => !extensions?.tools.has(tool.name) &&
-    (retained === undefined ? !tool.optional || args.tools?.includes(tool.name) : retained.has(tool.name))).map((t) => ({ ...t, source: "builtin" as const })), ...custom];
-  const selected = selectTools(available, { ...toolSelectionOf(args), ...(retained ? { profile: "full" as const } : {}) });
+    (retained === undefined ? !tool.optional || args.tools?.includes(tool.name) : retained.has(tool.name))).map((t) => ({ ...t, source: "builtin" as const })),
+    ...custom.filter(tool => tool.source !== "builtin" || retained === undefined || retained.has(tool.name))];
+  const admitted = new Set(workflowToolNames(available, args.workflow ?? "build"));
+  const selected = selectTools(available, { ...toolSelectionOf(args), ...(retained ? { profile: "full" as const } : {}) }).filter(tool => admitted.has(tool.name));
   const deferred = selected.filter(tool => tool.source === "extension" && extensions?.tools.get(tool.name)?.exposure === "deferred")
     .map(({ name, description, input_schema }) => ({ name, description, input_schema }));
   const deferredNames = new Set(deferred.map(tool => tool.name));
@@ -904,6 +940,7 @@ export function createSessionFor(opts: {
   oauth?: boolean;
   effects?: ResolveEffects;
   extensions?: ExtensionRegistry;
+  foundation?: FoundationRuntime;
   acceptanceContract?: AcceptanceContract;
   skills?: readonly Skill[];
 }): Session {
@@ -914,10 +951,14 @@ export function createSessionFor(opts: {
   const tools: ToolContext = {
     root: workspace,
     ...DEFAULT_TOOL_CONTEXT,
+    workflowMode: args.workflow ?? "build",
+    appOwnsPermissions: true,
+    ...(opts.foundation ? { questionSlot: opts.foundation.questionSlot,
+      instructionCheck: (ctx: ToolContext, name: string, input: unknown) => opts.foundation!.instructions(ctx, name, input, args.noContextFiles) } : {}),
     ...(args.pathRoot === undefined ? {} : { pathRoot: args.pathRoot }),
     allow: names,
     deferredTools: deferred,
-    rules: rulesWithAllowTools(args.allowTools, { yolo: args.yolo }),
+    rules: processPermissionRules(args, opts.foundation),
     sessionRules,
     askSlot,
     ...(opts.extensions ? { extensions: opts.extensions.definitions(), extensionHooks: opts.extensions.toolHooks() } : {}),
@@ -930,6 +971,7 @@ export function createSessionFor(opts: {
       shellCheckpoints: args.shellCheckpoints === true,
       tools,
       maxTurns: args.maxTurns,
+      ...(args.agent ? { agentProfile: { name: args.agent, workflowExplicit: args.cliFlags?.includes("--workflow") === true } } : {}),
       ...cliSessionConfig(args),
       ...(opts.skills ? { skills: opts.skills } : {}),
       ...(opts.acceptanceContract ? { acceptanceContract: opts.acceptanceContract } : {}),
@@ -991,14 +1033,44 @@ async function prepareExtensionPackages(args: Args, workspace: string): Promise<
   args.extensionPaths=(args.extensionPaths??[]).filter(path=>!remote.includes(path));
 }
 
-export async function loadSessionResources(args: Args, workspace: string, io: AppIO, trustOverride?: boolean): Promise<{
-  loadedContext: LoadedContext; slash: SlashCatalog; ui: UiState; index: ResourceIndex; trusted: boolean; system: string; extensions: ExtensionRegistry;
+export async function loadSessionResources(args: Args, workspace: string, io: AppIO, trustOverride?: boolean, questionSlot?: import("../runtime/question-tool.ts").QuestionSlot): Promise<{
+  loadedContext: LoadedContext; slash: SlashCatalog; ui: UiState; index: ResourceIndex; trusted: boolean; system: string; extensions: ExtensionRegistry; foundation: FoundationRuntime;
 }> {
   const { trusted } = await projectTrust(workspace, trustOverride ?? args.approve);
+  const profiles = await loadAgentProfileLayers({ workspace, trustProject: trusted });
+  for (const diagnostic of profiles.diagnostics) io.say(diagnostic);
+  if (args.agent) {
+    if (!args.agentBase) args.agentBase = { model: args.model, provider: args.provider, thinking: args.thinking ?? "", maxTurns: args.maxTurns, excludeTools: [...args.excludeTools], noTools: args.noTools, noBuiltinTools: args.noBuiltinTools,
+      ...(args.tools ? { tools: [...args.tools] } : {}), ...(args.toolProfile ? { toolProfile: args.toolProfile } : {}), ...(args.timeBudgetMs ? { timeBudgetMs: args.timeBudgetMs } : {}), ...(args.workflow ? { workflow: args.workflow } : {}) };
+    const explicitWorkflow = args.cliFlags?.includes("--workflow") ? args.workflow : undefined;
+    delete args.tools; delete args.toolProfile; delete args.timeBudgetMs; delete args.workflow;
+    Object.assign(args, args.agentBase);
+    if (explicitWorkflow) args.workflow = explicitWorkflow;
+    if (profiles.diagnostics.length) throw Error("Agent profile configuration is invalid; fix the reported file before selecting a role");
+    const role = resolveAgentProfile(args.agent, [builtinAgentProfileLayer(), ...profiles.layers]);
+    if (!role) throw Error(`Unknown agent profile: ${args.agent}`);
+    args.role = role;
+    const profile = role.profile, explicit = (name: string) => args.cliFlags?.includes(name) === true;
+    if (profile.mode && !explicit("--workflow")) args.workflow = profile.mode;
+    if (profile.model) { if (!explicit("--model") && !explicit("-m")) args.model = profile.model.id; if (!explicit("--provider")) args.provider = profile.model.provider; if (profile.model.thinking && !explicit("--thinking")) args.thinking = profile.model.thinking; }
+    if (profile.tools?.profile && !explicit("--tool-profile")) args.toolProfile = profile.tools.profile;
+    if (profile.tools?.only && !explicit("--tools") && !explicit("-t")) args.tools = [...profile.tools.only];
+    if (profile.tools?.exclude && !explicit("--exclude-tools") && !explicit("-xt")) args.excludeTools = [...profile.tools.exclude];
+    if (profile.tools?.none !== undefined && !explicit("--no-tools")) args.noTools = profile.tools.none;
+    if (profile.tools?.noBuiltin !== undefined && !explicit("--no-builtin-tools")) args.noBuiltinTools = profile.tools.noBuiltin;
+    if (profile.budget?.maxTurns && !explicit("--max-turns")) args.maxTurns = profile.budget.maxTurns;
+    if (profile.budget?.timeBudgetMs && !explicit("--time-budget")) args.timeBudgetMs = profile.budget.timeBudgetMs;
+  }
+  const foundationConfig = await readFoundationConfig(configDir(), workspace, trusted);
+  if (args.clientMcp) { const { parseMcpServers } = await import("../core/mcp-config.ts"); foundationConfig["mcp"] = { ...parseMcpServers(foundationConfig["mcp"]), ...args.clientMcp }; }
+  const foundation = new FoundationRuntime(workspace, foundationConfig, args.offline === true || process.env["XENO_OFFLINE"] === "1", configDir(), questionSlot);
   await prepareExtensionPackages(args,workspace);
   const index = await discoverResources({ ...args, workspace, trusted });
   const extensions = new ExtensionRegistry({ reserved: COMMANDS.map(command => command.name), reservedFlags: KNOWN_FLAGS.map(flag => flag.replace(/^-+/, "")),
     flagValue: (name, definition) => args.extensionFlags && Object.hasOwn(args.extensionFlags, name) ? args.extensionFlags[name] : extensionFlagValue(name, definition, args.extensionInputs && Object.hasOwn(args.extensionInputs, name) ? args.extensionInputs[name] : undefined), report: io.say });
+  extensions.own(() => foundation.dispose());
+  try {
+  await foundation.register(extensions);
   await extensions.load(index);
   if(args.extensionArgv) {
     const validated = parseArgs(args.extensionArgv, { flags: extensions.flags, ...(args.help ? { deferExtensions: true } : {}) });
@@ -1006,7 +1078,8 @@ export async function loadSessionResources(args: Args, workspace: string, io: Ap
     args.prompt = validated.prompt; args.extensionFlags = validated.extensionFlags ?? {};
   }
   const loaded = await loadUiResources({ ...args, workspace, trusted, ...(args.theme ? { theme: args.theme } : {}) }, index);
-  const loadedContext = await loadContext({ workspace, cwd: workspace, configDir: configDir(),
+  const instructionRoot = await resolveContextWorkspace(workspace);
+  const loadedContext = await loadContext({ workspace: instructionRoot, cwd: workspace, configDir: configDir(),
     noContextFiles: args.noContextFiles, appendSystemPrompt: args.appendSystemPrompt,
     ...(args.systemPrompt === null ? {} : { systemPrompt: args.systemPrompt }) });
   for (const notice of loadedContext.notices) if (notice.kind === "skipped" || notice.truncated) io.say(io.palette.yellow(formatNotice(notice)));
@@ -1014,11 +1087,13 @@ export async function loadSessionResources(args: Args, workspace: string, io: Ap
     noPromptTemplates: args.noPromptTemplates, skillPaths: args.skillPaths, promptTemplatePaths: args.promptTemplatePaths }, index);
   const slash = resolveSlashCatalog(text.prompts, text.skills);
   for (const line of new Set([...loaded.diagnostics, ...text.diagnostics, ...slash.diagnostics])) io.say(io.palette.yellow(`  ${line}`));
-  const system = appendSkillsToSystem(assembleSystemPrompt(systemPromptFor(visibleSchemas(args, extensions).map(tool => tool.name), sessionEnvironment(workspace)), loadedContext), text.skills);
+  const system = appendSkillsToSystem(assembleSystemPrompt([systemPromptFor(visibleSchemas(args, extensions).map(tool => tool.name), sessionEnvironment(workspace)), workflowInstructions(args.workflow ?? "build"), args.role?.profile.instructions ?? "",
+    ...(args.outputSchema ? ["Return the final answer as JSON matching this schema. Do not use Markdown fences:\n" + JSON.stringify(await readOutputSchema(args.outputSchema))] : [])].filter(Boolean).join("\n\n"), loadedContext), text.skills);
   const ui = toUiState(loaded, colorEnabled());
   // Also reached on /resume and /reload: `auto` is resolved once per process by the Tui (apps/shell.ts), not here.
   if (args.tuiMode) ui.settings = { ...ui.settings, tuiMode: args.tuiMode };
-  return { loadedContext, slash: { ...slash.catalog, skillExecution: true, skillCommands: loaded.settings.enableSkillCommands !== false }, ui, index, trusted, system, extensions };
+  return { loadedContext, slash: { ...slash.catalog, skillExecution: true, skillCommands: loaded.settings.enableSkillCommands !== false }, ui, index, trusted, system, extensions, foundation };
+  } catch (error) { await extensions.dispose().catch(() => {}); throw error; }
 }
 
 /**
@@ -1030,24 +1105,56 @@ export async function openSessionFor(opts: OpenSessionOptions): Promise<{
   session: Session; priorCursor: Cursor | null; providerConfig: ProviderConfig; credential: Resolved;
   workspace: string; blobDir: string; system: string; resources: Awaited<ReturnType<typeof loadSessionResources>>;
 }> {
+  const resourceSelector = () => JSON.stringify([opts.args.agent, opts.args.workflow, opts.args.toolProfile, opts.args.cliFlags]);
+  const preparedSelector = resourceSelector();
   opts.startupPhase?.("Reading session history");
   const recorded = await readCursor(opts.logDir);
   const priorCursor = recorded === null ? null : await recoverCut(opts.logDir, recorded);
+  // A durable selector restores intent, while current trusted files supply code
+  // and permission authority. Missing/revoked project roles fail by name.
+  if (priorCursor?.context_ref) {
+    const savedContext = await getBlob(join(opts.logDir, "artifacts"), priorCursor.context_ref);
+    if (!savedContext) throw Error("missing frozen session context");
+    const metadata: unknown = JSON.parse(savedContext);
+    if (metadata && typeof metadata === "object") {
+      if (!("agentProfile" in metadata) && !opts.args.cliFlags?.includes("--workflow") && "workflowMode" in metadata) {
+        if (metadata.workflowMode !== "build" && metadata.workflowMode !== "plan") throw Error("unsupported saved workflow mode");
+        opts.args.workflow = metadata.workflowMode;
+      }
+      if ("workflowToolProfile" in metadata && metadata.workflowToolProfile !== undefined) {
+        if (metadata.workflowToolProfile !== "foundation") throw Error("unsupported saved workflow tool profile");
+        if (!opts.args.cliFlags?.some(flag => ["--tool-profile", "--tools", "-t", "--no-tools", "--no-builtin-tools"].includes(flag))) opts.args.toolProfile = "foundation";
+      }
+    }
+    if (metadata && typeof metadata === "object" && "agentProfile" in metadata && metadata.agentProfile !== undefined) {
+      const role = metadata.agentProfile;
+      if (!role || typeof role !== "object" || !("name" in role) || typeof role.name !== "string" || !/^[a-z][a-z0-9_-]{0,63}$/.test(role.name) || !("workflowExplicit" in role) || typeof role.workflowExplicit !== "boolean") throw Error("unsupported saved agent profile selector");
+      if (!opts.args.cliFlags?.includes("--agent")) opts.args.agent = role.name;
+      if (role.workflowExplicit && !opts.args.cliFlags?.includes("--workflow") && "workflowMode" in metadata) {
+        if (metadata.workflowMode !== "build" && metadata.workflowMode !== "plan") throw Error("unsupported saved workflow mode");
+        opts.args.workflow = metadata.workflowMode; opts.args.cliFlags = [...opts.args.cliFlags ?? [], "--workflow"];
+      }
+    }
+  }
   const workspace = priorCursor?.workspace ?? opts.workspace;
   if (opts.args.pathRoot) {
     const rel = relative(opts.args.pathRoot, workspace);
     if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new Error("saved workspace is outside --path-root");
   }
-  if (opts.preparedResources && opts.preparedResources.workspace !== workspace) await opts.preparedResources.value.extensions.dispose();
+  const reusePrepared = opts.preparedResources?.workspace === workspace && preparedSelector === resourceSelector();
+  if (opts.preparedResources && !reusePrepared) await opts.preparedResources.value.extensions.dispose();
   opts.startupPhase?.("Loading session resources");
-  const resources = opts.preparedResources?.workspace === workspace ? opts.preparedResources.value
+  const resources = opts.preparedResources && reusePrepared ? opts.preparedResources.value
     : await loadSessionResources(opts.args, workspace, opts.io, workspace === opts.workspace ? opts.projectTrusted : undefined);
+  let openedSession: Session | undefined;
+  try {
   const interactive = opts.interactive && !opts.args.print && !opts.args.prompt && opts.args.mode !== "json";
   const named = [...opts.args.tools ?? [], ...opts.args.excludeTools, ...opts.args.allowTools];
   const unknown = unknownToolNames(named).filter(name => !resources.extensions.definitions().has(name));
   if (unknown.length) throw new Error(`unknown tool: ${unknown.join(", ")}`);
   const saved = priorCursor === null ? undefined : restoreSessionModel(priorCursor, opts.catalog);
   const flags = { ...opts.modelFlags ?? { model: "", provider: "" } };
+  if (opts.args.agent) { flags.model = opts.args.model; flags.provider = opts.args.provider; }
   const parsedModel = flags.model ? scopedModels([flags.model], flags.provider ? opts.catalog.filter(model => model.provider === flags.provider) : opts.catalog, true).entries[0] : undefined;
   if (parsedModel) flags.model = modelKey(parsedModel.model);
   const explicit = flags.model.length > 0 || flags.provider.length > 0;
@@ -1093,6 +1200,7 @@ export async function openSessionFor(opts: OpenSessionOptions): Promise<{
     ...opts,
     system: resources.system,
     extensions: resources.extensions,
+    foundation: resources.foundation,
     skills: [...resources.slash.skills.values()],
     ...(acceptanceContract ? { acceptanceContract } : {}),
     workspace: priorCursor?.workspace ?? opts.workspace,
@@ -1102,21 +1210,31 @@ export async function openSessionFor(opts: OpenSessionOptions): Promise<{
     credential: restoringCredential,
     ...(oauth(restoring, restoringCredential) ? { oauth: true } : {}),
   });
+  openedSession = session;
   opts.startupPhase?.("Opening session history");
   await session.start();
+  const requestedWorkflow = opts.args.workflow;
+  if (requestedWorkflow === undefined && session.config.tools.workflowMode) opts.args.workflow = session.config.tools.workflowMode;
+  if (opts.args.outputSchema) session.config.validateOutput = outputValidator(await readOutputSchema(opts.args.outputSchema));
   resources.slash = { ...resources.slash, skills: new Map((session.config.skills ?? []).map(skill => [skill.name, skill])) };
   const restoredTools = sessionToolCatalog(opts.args, resources.extensions, session.config.frozen.tools,
     priorCursor === null ? undefined : declaredToolNames(session.config.frozen.tools));
-  const refreshResources = resources.extensions.loaded.length > 0 || session.config.frozen.tools.some(tool =>
+  const refreshResources = opts.args.agent !== undefined || opts.args.outputSchema !== undefined || opts.args.cliFlags?.includes("--workflow") === true || resources.extensions.loaded.length > 0 || session.config.frozen.tools.some(tool =>
     typeof tool === "object" && tool !== null && "name" in tool && typeof tool.name === "string" && unknownToolNames([tool.name]).length);
-  const explicitTools = opts.args.tools !== undefined || opts.args.toolProfile !== undefined || opts.args.noTools ||
+  const explicitTools = requestedWorkflow !== undefined || opts.args.agent !== undefined || opts.args.tools !== undefined || opts.args.toolProfile !== undefined || opts.args.noTools ||
     opts.args.noBuiltinTools || opts.args.excludeTools.length > 0;
-  if (refreshResources || (priorCursor !== null && explicitTools)) {
-    await session.reloadResources({ system: refreshResources ? resources.system : session.config.frozen.system, tools: restoredTools.schemas });
+  const previousMode = session.config.tools.workflowMode, previousProfile = session.config.agentProfile, previousScope = session.config.workflowToolProfile;
+  session.config.tools.workflowMode = opts.args.workflow ?? "build";
+  if (opts.args.agent) session.config.agentProfile = { name: opts.args.agent, workflowExplicit: opts.args.cliFlags?.includes("--workflow") === true };
+  if (opts.args.toolProfile === "foundation") session.config.workflowToolProfile = "foundation"; else delete session.config.workflowToolProfile;
+  const metadataChanged = previousMode !== session.config.tools.workflowMode || JSON.stringify(previousProfile) !== JSON.stringify(session.config.agentProfile) || previousScope !== session.config.workflowToolProfile;
+  if (refreshResources || (priorCursor !== null && (explicitTools || metadataChanged))) {
+    await session.reloadResources({ system: refreshResources ? resources.system : session.config.frozen.system, tools: restoredTools.schemas }, undefined, undefined, metadataChanged);
   }
   // Admission follows this app's selected declaration; current process approval rules stay intact.
   // Keep this out of Session.start(): an SDK caller can intentionally supply a narrower allowlist.
   session.config.tools.allow = declaredToolNames(session.config.frozen.tools);
+  session.config.tools.workflowMode = opts.args.workflow ?? "build";
   session.config.tools.deferredTools = restoredTools.deferred;
   if (restoring.id !== spec.id || restoring.provider !== spec.provider) {
     await session.switchModel(createProvider(providerConfig, credential.ok ? credential.key : "", retryHandler(opts.io),
@@ -1128,6 +1246,11 @@ export async function openSessionFor(opts: OpenSessionOptions): Promise<{
   if (resources.ui.settings.scopedModels) for (const warning of scopedModels(resources.ui.settings.scopedModels, opts.catalog).diagnostics) opts.io.say(`  ${warning}`);
   return { session, priorCursor, providerConfig, credential, workspace: session.config.tools.root,
     blobDir: session.config.blobDir ?? opts.blobDir, system: session.config.frozen.system, resources };
+  } catch (error) {
+    await openedSession?.dispose().catch(() => {});
+    await resources.extensions.dispose().catch(() => {});
+    throw error;
+  }
 }
 
 export async function startup(args: Args, input?: StartupInput): Promise<App> {
@@ -1365,6 +1488,7 @@ export async function startup(args: Args, input?: StartupInput): Promise<App> {
     auth, effects, loadedContext: opened.resources.loadedContext, credentialOf, catalog, io, askSlot,
     ui: opened.resources.ui, slash: opened.resources.slash, resources: opened.resources.index, projectTrusted: opened.resources.trusted,
     extensions: opened.resources.extensions,
+    foundation: opened.resources.foundation,
   };
 }
 
@@ -1464,11 +1588,14 @@ export function printCliHelp(flags?: ReadonlyMap<string, ExtensionFlag>): void {
           "            [-n|--name name] [--session-id id] [--version|-v]\n" +
           "            [models --refresh]\n" +
           "            [install|remove <source>... [--local]] [update [source] [--extensions]] [list]\n" +
+          "            [update --check]  Check for a newer xeno without installing\n" +
           "            [config [--local]] [--export session [output.html]] [--offline]\n" +
           "            [--system-prompt <text-or-file>] [--append-system-prompt <text>]\n" +
           "            [--no-context-files|-nc]\n" +
           "            [--tools names] [--exclude-tools names] [--no-tools]\n" +
-          "            [--tool-profile coding|readonly|research|data|full]\n" +
+          "            [--tool-profile coding|readonly|research|data|foundation|full]\n" +
+          "            [--workflow build|plan] [--agent name]\n" +
+          "            [--output-schema schema.json] [--output-last-message file]\n" +
           "            [--acceptance-file contract.json]\n" +
           "            [--control-socket /private/directory/control.sock]\n" +
           "            [--no-builtin-tools]\n" +
@@ -1481,6 +1608,8 @@ export function printCliHelp(flags?: ReadonlyMap<string, ExtensionFlag>): void {
           "            [-p <prompt>] [prompt...]\n\n" +
           "  xeno app-server [session/model flags] runs the experimental JSONL control interface.\n" +
           "  xeno app-server schema prints its versioned request schema without startup.\n" +
+          "  xeno acp [session/model flags] serves the standard ACP protocol over stdio.\n" +
+          "  xeno review [working|last-turn|branch <base>|commit <ref>] runs an independent read-only review.\n" +
           "  --control-socket attaches local adapters to the same live session as the TUI.\n" +
           "  /control opens goal, progress and context panels; XENO_PROGRAM_STATUS=auto|1|0 controls terminal status.\n\n" +
           "  Starts a new session by default; --fresh is an explicit alias. Nothing is deleted.\n" +
@@ -1496,7 +1625,13 @@ export function printCliHelp(flags?: ReadonlyMap<string, ExtensionFlag>): void {
           "  --system-prompt replaces the built-in instructions (text, or a file that exists).\n" +
           "  --append-system-prompt appends; repeatable. -nc skips AGENTS.md discovery.\n" +
           "  --tools is a strict allowlist; excluded tools leave the schema.\n" +
-          "  New sessions use coding (10 tools); full exposes default built-ins.\n" +
+          "  New sessions keep coding (10 tools); foundation adds the new basic workflows.\n" +
+          "  --agent build|plan selects foundation; full exposes the complete builtin catalog.\n" +
+          "  Plan admits read tools plus note/question; Build admits the selected capability set.\n" +
+          "  /agent selects named profiles from ~/.xeno/agents.json and trusted .xeno/agents.json.\n" +
+          "  foundation.json configures MCP, web search, formatters, LSP and resource permissions.\n" +
+          "  --output-schema validates final JSON without coercion; invalid output exits 1.\n" +
+          "  --output-last-message writes the accepted final answer after the owner completes.\n" +
           "  --no-builtin-tools drops built-ins and keeps any other source; --tools still wins.\n" +
           "  Shell entry points (exec_command, environment, bash, target) ask before they run.\n" +
           "  --allow-tools exec_command skips asks for that tool for this process.\n" +