agency-lang 0.4.0 → 0.6.0

package/dist/lib/agents/agency-agent/agent.agency

@@ -1,16 +1,36 @@
-import { route } from "std::agent"
-import { clearMessages, pushMessage, repl } from "std::cli"
+import { getVersion } from "std::agency"
+import { parseArgs } from "std::args"
+import { clearMessages, pushMessage, repl, clearScreen } from "std::cli"
 import { today } from "std::date"
+import { setAgentCwd } from "std::index"
 import { box, render } from "std::layout"
-import { ScopedRuleFields, cliPolicyHandler } from "std::policy"
+import { setMemoryId } from "std::memory"
+import {
+  ScopedRuleFields,
+  cliPolicyHandler,
+  parsePolicyFile,
+  setPolicy,
+ } from "std::policy"
 import { exists } from "std::shell"
+import { commandsDir, expandSlash } from "std::skills"
 import { highlight } from "std::syntax"
-import { cwd, env } from "std::system"
-import { getCost } from "std::thread"
+import { cwd, env, isTTY, readStdin, setTitle } from "std::system"
+import { getCost, getTokens, systemMessage } from "std::thread"
+import { chooseOption, ChoiceItem } from "std::ui"
 
-import { codeSysPrompt, codeTools } from "./code.agency"
 import { figs, title } from "./images/images.agency"
-import { researchSysPrompt, researchTools } from "./research.agency"
+import { POLICY_PATH, HISTORY_PATH, ALWAYS_FIELDS } from "./lib/config.agency"
+import {
+  minimalAutoApprovePolicy,
+  recommendedAutoApprovePolicy,
+ } from "./lib/defaultPolicy.agency"
+import { truncate, formatArgs, formatToolResponse } from "./lib/utils.agency"
+import { configureModels } from "./shared.agency"
+import { codeAgent } from "./subagents/code.agency"
+import { explorerAgent } from "./subagents/explorer.agency"
+import { oracleAgent } from "./subagents/oracle.agency"
+import { researchAgent } from "./subagents/research.agency"
+import { reviewAgent } from "./subagents/review.agency"
 
 
 // UI mode select — one-line swap between the alt-screen TUI and the
@@ -41,8 +61,8 @@ import { researchSysPrompt, researchTools } from "./research.agency"
  *
  * This file's responsibilities collapse to:
  *   1. Per-turn callback (`_runTurn`) wiring the user message into
- *      route() and printing the reply into the scroll output.
- *   2. Per-kind ALWAYS_FIELDS map for the policy handler's
+ *      `mainAgent` and printing the reply into the scroll output.
+ *   2. Per-effect ALWAYS_FIELDS map for the policy handler's
  *      "approve-always-here" option.
  *   3. Wire the two specialists into one `RouterConfig`.
  *
@@ -57,124 +77,79 @@ import { researchSysPrompt, researchTools } from "./research.agency"
  *   editing `.agency` files.
  */
 
-// Verbose tool-call tracing, opt-in via `AGENT_DEBUG=1`.
-const AGENT_DEBUG = env("AGENT_DEBUG") == "1"
+// Verbose tool-call tracing. Enabled either by `AGENT_DEBUG=1` (legacy)
+// or by passing `--debug` / `--verbose` on the command line (set in main()).
+let AGENT_DEBUG: boolean = env("AGENT_DEBUG") == "1"
+let VERBOSE: boolean = false
 
-callback("onToolCallStart") as data {
-  //if (AGENT_DEBUG) {
-  pushMessage(color.yellow("⏺ ${data.toolName}(${formatArgs(data.args)})"))
-  //}
-}
+// Whether the agent is running in interactive (TTY) mode. Set in main()
+// before any tool calls happen, so the callbacks below can suppress
+// scroll-output writes when stdout is destined for a Unix pipe.
+let _isInteractive: boolean = true
 
-def truncate(str: string, maxLength: number): string {
-  if (str.length <= maxLength) {
-    return str
-  }
-  return str.slice(0, maxLength) + "..."
+// Live tool-call tracing. Always shown in the interactive REPL; in
+// one-shot mode it's suppressed so piped output is just the reply,
+// unless the user opts in with `--verbose` / `--debug` (AGENT_DEBUG).
+def _showTraces(): boolean {
+  return _isInteractive || VERBOSE || AGENT_DEBUG
 }
 
-def formatArgs(args: Record<string, any>): string {
-  const parts = []
-  for (key in args) {
-    const value = args[key]
-    parts.push("${key}: ${truncate(JSON.stringify(value), 50)}")
+callback("onToolCallStart") as data {
+  if (_showTraces()) {
+    pushMessage(color.yellow("⏺ ${data.toolName}(${formatArgs(data.args)})"))
   }
-  return parts.join(", ")
 }
 
 callback("onToolCallEnd") as data {
-  if (AGENT_DEBUG) {
-    pushMessage(
-      color.yellow(
-      "tool return: ${data.toolName} -> ${JSON.stringify(data.result)} ${data.timeTaken}ms",
-    ),
-    )
+  if (_showTraces()) {
+    if (data.result is success(_result)) {
+      pushMessage(color.dim.green("${formatToolResponse(_result)}"))
+    } else if (data.result is failure(_error)) {
+      pushMessage(color.red(" ⎿  Error: ${_error}"))
+    } else {
+      pushMessage(color.dim("${formatToolResponse(data.result)}"))
+    }
   }
 }
 
-// On-disk policy at `$HOME/.agency-agent/policy.json`. We duplicate the
-// home-dir computation here instead of importing `AGENCY_AGENT_DIR` from
-// `shared.agency` because Agency doesn't guarantee imported static-const
-// init runs before the importer reads it (upstream #232).
-const POLICY_FILE = "policy.json"
-const HISTORY_FILE = "history"
+callback("onLLMCallStart") as data {
+  if (AGENT_DEBUG || VERBOSE) {
+    pushMessage(color.green.dim("💬 [${data.model}] ${data.prompt}"))
+  }
+}
 
-def policyDir(): string {
-  const home = env("HOME")
-  if (home == null) {
-    return "./.agency-agent"
+callback("onLLMCallEnd") as data {
+  if (AGENT_DEBUG || VERBOSE) {
+    pushMessage(
+      color.green.dim("💬 [${data.model}] ${renderLLMCallResponse(data.result)}"),
+    )
   }
-  return "${home}/.agency-agent"
 }
 
-def policyPath(): string {
-  return "${policyDir()}/${POLICY_FILE}"
+type ToolCallData = {
+  name: string;
+  arguments: any
 }
 
-def historyPath(): string {
-  return "${policyDir()}/${HISTORY_FILE}"
+type LLMResponse = {
+  output: string | null;
+  toolCalls: ToolCallData[];
+  usage: { inputTokens: number; outputTokens: number; totalTokens: number; cachedInputTokens: number };
+  cost: { inputCost: number; outputCost: number; cachedInputCost: number; totalCost: number; currency: string };
+  model: string
 }
 
-// Per-kind config driving the "approve-always-here" option. For each
-// kind we list the data fields the scoped rule should pin, plus a
-// flag that turns a directory value into a brace-expanded glob so the
-// rule matches `dir` AND `dir/**`. Kinds not present in this map
-// don't offer the option — the user falls back to (a)/(r)/(aa)/(rr).
-const ALWAYS_FIELDS: ScopedRuleFields = {
-  "std::read": [{
-    field: "dir",
-    matchSubpaths: true
-  }],
-  "std::write": [{
-    field: "dir",
-    matchSubpaths: true
-  }],
-  "std::edit": [{
-    field: "dir",
-    matchSubpaths: true
-  }],
-  "std::ls": [{
-    field: "dir",
-    matchSubpaths: true
-  }],
-  "std::glob": [{
-    field: "dir",
-    matchSubpaths: true
-  }],
-  "std::grep": [{
-    field: "dir",
-    matchSubpaths: true
-  }],
-  "std::copy": [
-    {
-    field: "src",
-    matchSubpaths: true
-  },
-    {
-    field: "dest",
-    matchSubpaths: true
-  },
-  ],
-  "std::move": [
-    {
-    field: "src",
-    matchSubpaths: true
-  },
-    {
-    field: "dest",
-    matchSubpaths: true
-  },
-  ],
-  "std::exec": [
-    {
-    field: "command",
-    matchSubpaths: false
-  },
-    {
-    field: "subcommand",
-    matchSubpaths: false
-  },
-  ]
+def renderLLMCallResponse(data: LLMResponse): string {
+  let response = []
+  if (data.output != "" && data.output != null && data.output != undefined) {
+    response.push(data.output)
+  }
+  if (data.toolCalls && data.toolCalls.length > 0) {
+    for (toolCall in data.toolCalls) {
+      response.push(`${toolCall.name}(${formatArgs(toolCall.arguments)})`)
+    }
+  }
+  return response.join("\n")
 }
 
 def loadAgentsMd(dir: string): string {
@@ -199,47 +174,311 @@ def loadAgentsMd(dir: string): string {
 // LLM doesn't have to re-ground each turn. Initialized in `main()`.
 let _context: string = ""
 
+// Project-local slash commands. `cwd()` works at module-init time so
+// we anchor at the user's project root (not the agent's source dir).
+// `with approve` auto-approves the `glob`/`read` during init — the
+// user implicitly opted in by running the agent in this directory.
+static const projectCommands = commandsDir("${cwd()}/.claude/commands") with approve
+
+def builtinPalette(): Record<string, string> {
+  return {
+    "/exit": "Exit the agent",
+    "/clear": "Clear the conversation transcript",
+    "/cost": "Show cumulative LLM cost and tokens",
+    "/paste": "Multi-line paste mode (Ctrl+D submits, Ctrl+C cancels)",
+    "/help": "Show available slash commands"
+  }
+}
+
+// Built-ins win over file commands so a user `/clear.md` can't shadow
+// the built-in `/clear`. Build file entries first, then overlay builtins.
+def mergedPalette(): Record<string, string> {
+  let out: Record<string, string> = {}
+  for (cmd in projectCommands) {
+    let label = cmd.description
+    if (cmd.argHint != "") {
+      label = "${cmd.description} ${cmd.argHint}"
+    }
+    out["/${cmd.name}"] = label
+  }
+  const builtins = builtinPalette()
+  for (key in builtins) {
+    out[key] = builtins[key]
+  }
+  return out
+}
+
 // Slash-command + user-message dispatcher invoked by `repl()` for
 // every Enter keystroke. Return `false` to terminate the loop.
 def _runTurn(msg: string): boolean {
-  if (msg == "") {
+  // Trim once for built-in matching so `"/help\n"` (piped) or
+  // `"  /clear"` behave the same as `"/clear"`. `expandSlash` is
+  // whitespace-tolerant in its own right, but it still receives the
+  // raw `msg` so the LLM sees the exact text the user typed when
+  // nothing matches.
+  const trimmed = msg.trim()
+  if (trimmed == "") {
     return true
   }
-  if (msg == "/exit" || msg == "/quit") {
+  if (trimmed == "/exit" || trimmed == "/quit") {
     return false
   }
-  if (msg == "/clear") {
+  if (trimmed == "/clear") {
     clearMessages()
     return true
   }
-  if (msg == "/help") {
-    pushMessage("Commands: /exit, /clear, /help")
+  if (trimmed == "/help") {
+    pushMessage("Commands: /exit, /clear, /cost, /paste, /help")
     return true
   }
-  const reply = route(
-    {
-    start: "code",
-    agents: {
-      code: {
-        systemPrompt: codeSysPrompt,
-        tools: codeTools,
-        memory: true
-      },
-      research: {
-        systemPrompt: researchSysPrompt,
-        tools: researchTools,
-        memory: true
-      }
-    },
-    maxHops: 3,
-    context: _context
-  },
-    msg,
-  )
-  pushMessage(highlight("${reply}\n", language: "markdown"))
+  if (trimmed == "/cost") {
+    pushMessage("Cost:   $${getCost().toFixed(4)}")
+    pushMessage("Tokens: ${getTokens()}")
+    return true
+  }
+  // Hand the message to the agent. `agentReply` does the slash-command
+  // expansion and the actual agent work; the REPL just renders the reply.
+  const reply = agentReply(msg)
+  if (reply != "" && reply != null && reply != undefined) {
+    pushMessage(highlight("${reply}\n", language: "markdown"))
+  } else {
+    pushMessage(color.red("No reply generated."))
+  }
   return true
 }
 
+let first = true
+
+// Valid `--agent` targets. Empty / "main" routes through the coordinator;
+// the rest route the starting prompt's first turn directly to that
+// subagent. Used to validate the flag and to dispatch in `agentReplyVia`.
+static const START_AGENTS = ["main", "code", "research", "oracle", "explorer", "review"]
+
+static const mainAgentSystemPrompt = """
+You are the top-level coordinator of an Agency-language assistant. You
+receive every user message and decide how to respond.
+
+You have five subagent tools, each running in its own isolated
+context:
+
+- `codeAgent(userMsg)` — anything that touches code or the filesystem:
+  reading, writing, editing, typechecking, running shell commands,
+  and answering Agency syntax / CLI questions. Use this for any task
+  that involves inspecting or modifying source code.
+- `researchAgent(userMsg)` — web search, URL fetches, Wikipedia,
+  external API lookups, summarizing external content.
+- `reviewAgent(userMsg)` — reviews Agency code for syntax and type
+  errors. Call this after `codeAgent` produces non-trivial new or
+  modified Agency code, passing the code to be reviewed.
+- `oracleAgent(userMsg)` — a read-only senior reviewer on a stronger
+  reasoning model. Read the **Oracle** section below — you are
+  expected to use this tool **frequently**.
+- `explorerAgent(userMsg)` — a read-only researcher that produces
+  broad, synthesizing answers about the codebase or bundled docs.
+  Read the **Explorer** section below.
+
+**Answer directly (no tool call) when** the message is conversational,
+a clarifying question, or something you can answer from context alone.
+
+**Delegate when** the message clearly needs one of the subagents'
+capabilities. Pick one based on what the message actually needs —
+don't pre-emptively call multiple subagents.
+
+## Picking between oracle, explorer, and code agent
+
+These three overlap on "reads the codebase," but they're for
+different jobs. Pick by **the shape of the answer the user wants**:
+
+- **oracle** → sharp verdict on a specific plan, diff, or bug.
+  Output: short, decisive ("this plan won't work because X").
+- **explorer** → broad synthesis from reading many files.
+  Output: structured overview ("Agency's five main features
+  are..."). Use for "summarize", "tour", "what are the main",
+  "how does X work across...".
+- **codeAgent** → targeted action: edit, run, typecheck, or
+  answer a focused Agency-syntax question. Output: the edit
+  itself, or a concise factual reply.
+
+Default: if the user asks a broad/synthesizing question,
+`explorerAgent` beats `codeAgent` every time. The code agent is
+optimized for terse action and will under-read on broad asks.
+
+Subagents return summary text. Surface that result to the user (in
+your own words if you're combining multiple results), formatted as
+Markdown.
+
+## Oracle
+
+The oracle is the most powerful tool you have. Use it **FREQUENTLY**.
+It is a read-only senior reviewer running on a stronger reasoning
+model than you. It can read the codebase and the Agency docs but
+cannot write, edit, or run anything. Its job is to **think hard so
+you don't have to guess**.
+
+Call the oracle:
+
+- **Before** dispatching `codeAgent` for any non-trivial task — ask
+  the oracle to sanity-check the plan, find existing code that
+  already solves the problem, or suggest a simpler approach.
+- **After** `codeAgent` produces a non-trivial diff — ask the oracle
+  to review the work for correctness, missed edge cases, and
+  better alternatives.
+- When `codeAgent` reports it's stuck on a bug after one or two
+  attempts — ask the oracle what's actually going on.
+- When the user proposes a plan or approach — ask the oracle
+  whether the plan is sound, **before** you act on it. If the
+  oracle finds a flaw, surface that to the user *before* taking
+  any action.
+- Whenever you're tempted to guess about the codebase ("I think
+  there's probably already a helper for X") — ask the oracle to
+  look.
+
+**Tell the user when you're consulting the oracle.** Say something
+like "Let me ask the oracle to review this plan before we start"
+or "I'll have the oracle look for an existing implementation." The
+visibility is half the value — the user benefits from knowing a
+second opinion is being sought.
+
+Pass the oracle a self-contained question with full context. It
+does not see your conversation. Include the user's request, the
+plan or diff under review, relevant file paths, and the specific
+question you want answered.
+
+Default bias: when in doubt, **consult the oracle**. The cost of
+asking is small; the cost of executing a flawed plan is large.
+
+## Explorer
+
+The explorer is your go-to for **broad, synthesizing questions**
+about the codebase or the bundled Agency docs. It is read-only and
+runs on a stronger reasoning model with extended thinking. Its job
+is **coverage** — it reads widely and returns a structured synthesis.
+
+Call the explorer when the user asks:
+
+- "Summarize the Agency docs" / "What are the main features?"
+- "Give me a tour of `lib/X/`" / "What's in this module?"
+- "How does X work across the codebase?"
+- "Walk me through the compilation pipeline"
+- Anything where a good answer requires reading 5+ files and
+  organizing the findings by theme.
+
+Do NOT use the explorer for:
+- Specific factual lookups ("what does function X return?") — use
+  `codeAgent`.
+- Plan critique or bug diagnosis — use `oracleAgent`.
+- External / web research — use `researchAgent`.
+
+**Tell the user when you're consulting the explorer.** "Let me have
+the explorer go through the docs and put together an overview." Like
+with the oracle, the visibility is part of the value — the user
+benefits from knowing breadth is being applied.
+
+Pass the explorer a self-contained question with explicit scope
+("all of `docs/site/guide/`", "the `lib/parsers/` module"). It does
+not see your conversation. Be clear about the level of detail
+expected.
+
+## Style
+
+Never start a response by calling the user's question or idea good,
+great, fascinating, profound, excellent, or perfect. Skip flattery
+and respond directly. Don't pad replies with "happy to help",
+"certainly", or trailing summaries the user can read in the diff.
+
+**Use ASCII diagrams when they clarify.** For control flow, state
+machines, pipelines, module relationships, or any "how do the parts
+fit together" answer, draw a small ASCII diagram in a fenced
+```text block. Boxes, arrows, and trees beat paragraphs for
+structural explanations:
+
+```text
+parse → SymbolTable.build → preprocess → TypeScriptBuilder → printTs
+```
+
+Keep diagrams small. Skip them where prose or code is clearer —
+diagrams earn their space by showing **relationships** or **flow**.
+
+## Be proactive
+
+When the user asks you to look at, debug, or change a file or some code,
+**delegate to `codeAgent` to do it** — don't ask the user to paste a file
+or describe code a subagent could read. The code agent has `read`, `glob`,
+and `ls` and resolves relative paths against the user's working directory
+automatically, so a bare filename like `foo.agency` is enough. Only ask
+the user for information you genuinely cannot obtain through a subagent.
+
+## Answer before action
+
+When the user asks a question, asks for an opinion, or asks how to
+plan or approach something, **answer the question first**. Don't
+jump straight into delegating to a subagent or making tool calls
+unless the user has clearly asked for an action ("do X", "fix Y",
+"build Z"). If the user is exploring or thinking out loud, think
+with them — don't sprint to implementation.
+"""
+
+static const mainAgentTools = [
+  researchAgent.partial(allowHandoff: false),
+  codeAgent.partial(allowHandoff: false),
+  reviewAgent.partial(allowHandoff: false),
+  oracleAgent.partial(allowHandoff: false),
+  explorerAgent.partial(allowHandoff: false),
+]
+
+def mainAgent(prompt: string): string {
+  thread(label: "main", summarize: true, session: "main") {
+    setMemoryId("main")
+    if (first) {
+      // `_context` carries the per-run grounding (date, cwd, AGENTS.md),
+      // set by `setupSession`. Appending it to the system prompt is what
+      // actually gets that context to the LLM.
+      systemMessage(mainAgentSystemPrompt + _context)
+      first = false
+    }
+    const result = llm(prompt, {
+      memory: true,
+      tools: mainAgentTools
+    })
+  }
+  return result
+}
+
+// Dispatch one turn. `target` empty (or "main") runs the coordinator
+// `mainAgent`, which routes as usual; any subagent name routes the turn
+// directly to that subagent. All subagents share `(userMsg, allowHandoff)`
+// and the seed turn never hands off (allowHandoff: false). Used by both
+// the one-shot path and the interactive seed turn.
+export def agentReplyVia(target: string, userMsg: string): string {
+  const expanded = expandSlash(userMsg, projectCommands)
+  if (target == "code") {
+    return codeAgent(expanded, false)
+  }
+  if (target == "research") {
+    return researchAgent(expanded, false)
+  }
+  if (target == "oracle") {
+    return oracleAgent(expanded, false)
+  }
+  if (target == "explorer") {
+    return explorerAgent(expanded, false)
+  }
+  if (target == "review") {
+    return reviewAgent(expanded, false)
+  }
+  return mainAgent(expanded)
+}
+
+// The agent's core turn, decoupled from the terminal: expand any project
+// slash command, then run the prompt through `mainAgent` and return the
+// reply. The REPL (`main` / `_runTurn`) owns input, output, and built-in
+// commands; everything the *agent* does for a user message lives here, so
+// it can be driven and tested without a terminal or user input. See
+// `tests/agentTurn.agency`.
+export def agentReply(userMsg: string): string {
+  return agentReplyVia("", userMsg)
+}
+
 def roundedCost(): string {
   return "$${getCost().toFixed(4)}"
 }
@@ -258,62 +497,286 @@ def sample(arr: any[]): any {
 
 def printHeader() {
   const fig = sample(figs)
-  const data = box(title: "Agency", padding: 1, borderColor: "cyan", titleColor: "cyan") as b {
+  const data = box(
+    title: "Agency",
+    padding: 1,
+    borderColor: "cyan",
+    titleColor: "cyan",
+    width: "full",
+  ) as b {
     b.row(gap: 1) as r {
-      r.column() as left {
+      r.column(width: "66%") as left {
         left.text("Welcome to the Agency Agent!", bold: true)
         left.text("Ask me to write code, look up docs, or just chat.")
+        left.text("All costs are estimates. Actual costs may be higher.", dim: true)
         left.hline()
         left.text("Getting Started", bold: true, fgColor: "cyan")
         left.text("/help for commands · /exit to quit", dim: true)
       }
       r.vline()
-      r.column() as right {
-        right.raw(fig)
+      r.column(width: "30%", align: "center") as right {
+        right.raw(fig, align: "center")
       }
     }
   }
   print(render(data, color: true))
 }
 
-node main() {
-  printHeader()
+def givePolicyChoice() {
+  const title = "Welcome to the agency agent. Please pick a policy to start."
+  const body = "Don't worry, you can change this later. The policy just controls how the agent asks for your approval when it wants to do something. You can also create your own custom policy file at ${POLICY_PATH} and the agent will use it automatically."
+  let items: ChoiceItem[] = [
+    {
+    key: "minimal",
+    label: "minimal default policy, you do most approvals manually"
+  },
+    {
+    key: "recommended",
+    label: "recommended default policy, allow reading files and browsing the web, no writes"
+  },
+  ]
+
+  const answer = chooseOption(title, body, items, allowFreeText: true)
+  match(answer) {
+    "minimal" => return minimalAutoApprovePolicy
+    "recommended" => return recommendedAutoApprovePolicy
+  }
+}
+
+// Shared session setup for both interactive and one-shot modes. Builds
+// the per-run grounding context, loads (or initializes) the policy, and
+// returns the installed CLI policy handler. `interactive` gates the
+// first-run policy-choice prompt: one-shot has no user to answer it, so
+// it falls back to the recommended default (reads/web auto-approved;
+// writes still require approval, which a non-interactive run can't
+// grant — those tasks block, which is the safe behavior).
+def setupSession(interactive: boolean): any {
+  // Point every path-taking tool at the user's working directory so the
+  // agent's relative file/shell commands resolve against where the user
+  // launched it. The user (via the agent) can change this later with
+  // setAgentCwd.
+  setAgentCwd(cwd())
 
-  // Grounding: the LLM should not have to ask the user where it is
-  // or what day it is. Both are appended once per run so they ride
-  // with the first system message in each specialist's thread.
-  //
-  // Project context: if the user keeps an AGENTS.md at the workspace
-  // root (Anthropic / Pi / Aider all read it), inline it so the LLM
-  // automatically follows the project's conventions.
+  // Grounding: the LLM shouldn't have to ask where it is or what day it
+  // is. Project context: inline an AGENTS.md from the workspace root if
+  // present so the LLM follows the project's conventions.
   const projectContext = loadAgentsMd(cwd()) with approve
   _context = "\n\nCurrent date: ${today()}\nCurrent working directory: ${cwd()}${projectContext}"
 
+  const policy = parsePolicyFile(POLICY_PATH)
+  if (policy is failure(f)) {
+    if (f.status == "doesnt-exist") {
+      if (interactive) {
+        print(color.yellow("No existing policy found at ${POLICY_PATH}."))
+        setPolicy(POLICY_PATH, givePolicyChoice())
+      } else {
+        setPolicy(POLICY_PATH, recommendedAutoApprovePolicy)
+      }
+    } else {
+      print(color.red("Failed to load policy: ${JSON.stringify(f.error)}"))
+      process.exit(1)
+    }
+  } else {
+    setPolicy(POLICY_PATH, policy.value)
+  }
   // Bind the handler to a local var so `with handler` parses (the
   // `with` clause only accepts an identifier, not a call expression).
-  const handler = cliPolicyHandler({
-    file: policyPath(),
-    fields: ALWAYS_FIELDS
-  })
-
-  // The `repl()` widget owns the runloop; every Enter dispatches into
-  // `_runTurn` which calls `route()`. Interrupts raised inside
-  // route() propagate to the policy handler installed by the enclosing
-  // `handle` block via the AsyncLocalStorage handler stack.
+  return cliPolicyHandler(file: POLICY_PATH, fields: ALWAYS_FIELDS)
+}
+
+// One-shot entry: run a single turn through the same `mainAgent` the
+// REPL uses, with the same session setup and policy handler, and return
+// the reply. Used for `agency agent -p "..."`, a positional query, or
+// piped stdin. Slash commands are expanded so `-p /foo bar` works like
+// typing it in the REPL; the loop-only built-ins (`/exit` etc.) are
+// meaningless here and aren't checked.
+def oneShotAgent(target: string, prompt: string): string {
+  _isInteractive = false
+  const handler = setupSession(false)
+  let reply: string = ""
   handle {
+    reply = agentReplyVia(target, prompt)
+  } with (data) {
+    return handler(data)
+  }
+  return reply
+}
+
+// Render one seeded turn into the REPL scroll area: echo the auto-run
+// prompt so the user sees what was asked, then push the agent's reply.
+// Mirrors the reply-rendering half of `_runTurn`.
+def _runSeedTurn(target: string, msg: string) {
+  pushMessage(color.dim("> ${msg}"))
+  const reply = agentReplyVia(target, msg)
+  if (reply != "" && reply != null && reply != undefined) {
+    pushMessage(highlight("${reply}\n", language: "markdown"))
+  } else {
+    pushMessage(color.red("No reply generated."))
+  }
+}
+
+// Start the interactive REPL. When `seedPrompt` is non-empty it is run as
+// the first turn (routed via `seedTarget`) *inside* the handle block so
+// its interrupts reach the policy `handler`; the user is then left at the
+// prompt. `seedPrompt == ""` is the plain REPL with no seed. Subsequent
+// turns always go through `_runTurn` (the coordinator) regardless of
+// `seedTarget` — the target only kicks off the first turn.
+def startInteractive(handler: any, seedTarget: string, seedPrompt: string) {
+  handle {
+    if (seedPrompt != "") {
+      _runSeedTurn(seedTarget, seedPrompt)
+    }
     repl(
       status: _buildStatus,
       onSubmit: _runTurn,
       prompt: "> ",
-      historyFile: historyPath(),
+      historyFile: HISTORY_PATH,
       historyMax: 1000,
-      paletteCommands: {
-      "/exit": "Exit the agent",
-      "/clear": "Clear the conversation transcript",
-      "/help": "Show available slash commands"
-    },
+      paletteCommands: mergedPalette(),
     )
-  } with handler
-
+  } with (data) {
+    return handler(data)
+  }
   print(color.cyan("\nGoodbye!"))
 }
+
+node main() {
+  // Parse CLI flags first — `parseArgs` exits on --help / --version /
+  // usage errors, before any handlers or the TUI are installed.
+  const args = parseArgs(
+    {
+    programName: "agency agent",
+    description: "Agency language assistant — interactive REPL by default; one-shot when piped or passed a query / --print.",
+    version: getVersion(),
+    flags: {
+      print: {
+        type: "boolean",
+        short: "p",
+        description: "Run one-shot: print the reply to stdout and exit (no REPL)"
+      },
+      debug: {
+        type: "boolean",
+        description: "Log tool returns (toolName, result, timing). Same as AGENT_DEBUG=1"
+      },
+      verbose: {
+        type: "boolean",
+        description: "Echo tool-call starts to stdout in non-interactive mode"
+      },
+      model: {
+        type: "string",
+        description: "Model for all LLM calls (overrides provider auto-detection)"
+      },
+      fastmodel: {
+        type: "string",
+        description: "Model for ordinary work (default: per detected provider)"
+      },
+      slowmodel: {
+        type: "string",
+        description: "Model for deep reasoning, e.g. the oracle/explorer subagents"
+      },
+      provider: {
+        type: "string",
+        description: "Force the LLM provider (use when a model name doesn't imply one)"
+      },
+      interactive: {
+        type: "boolean",
+        short: "i",
+        description: "Run the given prompt as the first turn of an interactive session, then hand over the REPL (instead of one-shot)"
+      },
+      agent: {
+        type: "string",
+        description: "Route the starting prompt to a named subagent: code, research, oracle, explorer, review (default: coordinator)"
+      }
+    }
+  },
+  )
+
+  if (args.flags.debug) {
+    AGENT_DEBUG = true
+  }
+  if (args.flags.verbose) {
+    VERBOSE = true
+  }
+
+  // Resolve which models to use. Explicit flags win; otherwise detect a
+  // provider from API-key env vars and use that provider's defaults. The
+  // fast model becomes the run-wide default via `setModel`; the slow
+  // model is read by the deep-reasoning subagents (oracle, explorer).
+  // Resolve + apply the fast/slow models. Absent string flags read as
+  // `undefined`, and agency's `== null` does not match `undefined`, so
+  // normalize via `??` (which does treat `undefined` as nullish) to "".
+  configureModels(
+    args.flags.model ?? "",
+    args.flags.fastmodel ?? "",
+    args.flags.slowmodel ?? "",
+    args.flags.provider ?? "",
+  )
+
+  // Positional args (everything after flags) are joined with spaces to
+  // form the starting prompt. `--` ends flag parsing if a positional
+  // would otherwise look like a flag.
+  const positionalQuery = args.positionals.join(" ")
+  const hasQuery = positionalQuery != ""
+  const startAgent = args.flags.agent ?? ""
+  const wantInteractive = args.flags.interactive
+
+  // Validate the target subagent name up front (empty = coordinator).
+  if (startAgent != "" && !START_AGENTS.includes(startAgent)) {
+    print(
+      color.red(
+      "Unknown --agent value: ${startAgent}. Valid: ${START_AGENTS.join(", ")}",
+    ),
+    )
+    process.exit(1)
+  }
+
+  // Seeded interactive: run the given prompt as the first turn, then hand
+  // the REPL to the user. Requires a seed prompt and a TTY (the REPL reads
+  // stdin). `--print` wins if both are passed — its whole job is to print
+  // and exit with no REPL. Without a TTY (or with `--print`) we fall
+  // through to one-shot below; `--interactive` with no prompt falls through
+  // to the plain REPL.
+  if (wantInteractive && hasQuery && isTTY() && !args.flags.print) {
+    setTitle("Agency Agent")
+    clearScreen()
+    printHeader()
+    const seededHandler = setupSession(true)
+    startInteractive(seededHandler, startAgent, positionalQuery)
+    process.exit(0)
+  }
+
+  // One-shot invocation: run one turn through the same agent the REPL uses
+  // and write the reply to stdout. No banner, no REPL. Entered when
+  // `--print` / `-p` is passed, a positional query is given, or stdin is
+  // piped (no TTY) — so the agent behaves like a Unix filter:
+  // `echo "..." | agency agent`. `--interactive` is NOT a one-shot trigger
+  // on its own: with a TTY and no prompt it falls through to the plain
+  // REPL; without a TTY the `!isTTY()` check below routes it here to
+  // degrade gracefully. The prompt comes from the positional when present,
+  // otherwise from stdin. (Title/clearScreen are skipped so piped output
+  // stays free of escape codes.)
+  const forceOneShot = args.flags.print || hasQuery
+  if (forceOneShot || !isTTY()) {
+    let prompt = positionalQuery
+    if (!hasQuery) {
+      const fromStdin = readStdin()
+      if (fromStdin == null || fromStdin == "") {
+        process.exit(0)
+      }
+      prompt = fromStdin
+    }
+    print(oneShotAgent(startAgent, prompt))
+    process.exit(0)
+  }
+
+  // Plain interactive REPL (no seed). `startInteractive` owns the runloop;
+  // every Enter dispatches into `_runTurn` which calls `mainAgent`.
+  // Interrupts raised during a turn propagate to the policy handler
+  // installed by the enclosing `handle` block via the AsyncLocalStorage
+  // handler stack.
+  setTitle("Agency Agent")
+  clearScreen()
+  printHeader()
+  const handler = setupSession(true)
+  startInteractive(handler, "", "")
+}