agency-lang 0.5.0 → 0.6.0

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

@@ -1,8 +1,8 @@
 import { getVersion } from "std::agency"
-import { route } from "std::agent"
 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 { setMemoryId } from "std::memory"
 import {
@@ -25,15 +25,11 @@ import {
   recommendedAutoApprovePolicy,
  } from "./lib/defaultPolicy.agency"
 import { truncate, formatArgs, formatToolResponse } from "./lib/utils.agency"
-import { codeSysPrompt, codeTools, codeAgent } from "./subagents/code.agency"
+import { configureModels } from "./shared.agency"
+import { codeAgent } from "./subagents/code.agency"
 import { explorerAgent } from "./subagents/explorer.agency"
-import { oneShotAgent } from "./subagents/oneShot.agency"
 import { oracleAgent } from "./subagents/oracle.agency"
-import {
-  researchSysPrompt,
-  researchTools,
-  researchAgent,
- } from "./subagents/research.agency"
+import { researchAgent } from "./subagents/research.agency"
 import { reviewAgent } from "./subagents/review.agency"
 
 
@@ -65,8 +61,8 @@ import { reviewAgent } from "./subagents/review.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`.
  *
@@ -91,17 +87,28 @@ let VERBOSE: boolean = false
 // scroll-output writes when stdout is destined for a Unix pipe.
 let _isInteractive: boolean = true
 
+// 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
+}
+
 callback("onToolCallStart") as data {
-  pushMessage(color.yellow("⏺ ${data.toolName}(${formatArgs(data.args)})"))
+  if (_showTraces()) {
+    pushMessage(color.yellow("⏺ ${data.toolName}(${formatArgs(data.args)})"))
+  }
 }
 
 callback("onToolCallEnd") as data {
-  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)}"))
+  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)}"))
+    }
   }
 }
 
@@ -178,6 +185,7 @@ def builtinPalette(): Record<string, string> {
     "/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"
   }
 }
@@ -220,7 +228,7 @@ def _runTurn(msg: string): boolean {
     return true
   }
   if (trimmed == "/help") {
-    pushMessage("Commands: /exit, /clear, /cost, /help")
+    pushMessage("Commands: /exit, /clear, /cost, /paste, /help")
     return true
   }
   if (trimmed == "/cost") {
@@ -228,10 +236,9 @@ def _runTurn(msg: string): boolean {
     pushMessage("Tokens: ${getTokens()}")
     return true
   }
-  // Expand `/foo args` to the rendered command body. Unknown `/foo`
-  // inputs fall through unchanged — matches Claude Code.
-  const prompt = expandSlash(msg, projectCommands)
-  const reply = mainAgent(prompt)
+  // 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 {
@@ -241,6 +248,12 @@ def _runTurn(msg: string): boolean {
 }
 
 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.
@@ -386,6 +399,15 @@ 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
@@ -408,7 +430,10 @@ def mainAgent(prompt: string): string {
   thread(label: "main", summarize: true, session: "main") {
     setMemoryId("main")
     if (first) {
-      systemMessage(mainAgentSystemPrompt)
+      // `_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, {
@@ -419,28 +444,39 @@ def mainAgent(prompt: string): string {
   return result
 }
 
-def routeAgent(prompt: string): string {
-  const reply = route(
-    {
-    start: "code",
-    agents: {
-      code: {
-        type: "agent",
-        name: "code",
-        agent: codeAgent
-      },
-      research: {
-        type: "agent",
-        name: "research",
-        agent: researchAgent
-      }
-    },
-    maxHops: 3,
-    context: _context
-  },
-    prompt,
-  )
-  return reply
+// 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 {
@@ -461,9 +497,15 @@ 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)
@@ -472,8 +514,8 @@ def printHeader() {
         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")
       }
     }
   }
@@ -501,6 +543,103 @@ def givePolicyChoice() {
   }
 }
 
+// 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 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).
+  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: HISTORY_PATH,
+      historyMax: 1000,
+      paletteCommands: mergedPalette(),
+    )
+  } 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.
@@ -522,6 +661,31 @@ node main() {
       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)"
       }
     }
   },
@@ -534,74 +698,85 @@ node main() {
     VERBOSE = true
   }
 
-  setTitle("Agency Agent")
-  clearScreen()
+  // 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 one-shot prompt. `--` ends flag parsing if a positional
+  // 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)
+  }
 
-  // Non-interactive (piped) invocation: read the whole prompt from
-  // stdin, run one turn of `route()`, write the reply to stdout, and
-  // exit. No banner, no REPL, no slash commands. This lets the agent
-  // behave like a normal Unix filter: `echo "..." | pnpm run agency agent`.
-  //
-  // Also entered when `--print` / `-p` is passed, or when a positional
-  // query is given. In those cases stdin isn't read — the prompt comes
-  // from the positional.
-  const forceOneShot = args.flags.print || hasQuery
-  if (forceOneShot || !isTTY()) {
-    const result = oneShotAgent()
-    print(result)
+  // 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)
   }
 
-  printHeader()
-
-  // 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.
-  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)) {
-    const { status, error } = f
-    print(f, status, error)
-    if (status == "doesnt-exist") {
-      print(color.yellow("No existing policy found at ${POLICY_PATH}."))
-      const choice = givePolicyChoice()
-      setPolicy(POLICY_PATH, choice)
-    } else {
-      print(color.red("Failed to load policy: ${JSON.stringify(error)}"))
-      process.exit(1)
+  // 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
     }
-  } else {
-    setPolicy(POLICY_PATH, policy.value)
+    print(oneShotAgent(startAgent, prompt))
+    process.exit(0)
   }
-  // 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: POLICY_PATH, 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.
-  handle {
-    repl(
-      status: _buildStatus,
-      onSubmit: _runTurn,
-      prompt: "> ",
-      historyFile: HISTORY_PATH,
-      historyMax: 1000,
-      paletteCommands: mergedPalette(),
-    )
-  } with handler
-
-  print(color.cyan("\nGoodbye!"))
+  // 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, "", "")
 }