agency-lang 0.6.5 → 0.7.1

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

@@ -1,10 +1,18 @@
 import { getVersion } from "std::agency"
+import {
+  printLocalCatalog,
+  localModelsSupported,
+  listModelNames,
+ } from "std::agency/local"
 import { parseArgs } from "std::args"
-import { clearMessages, pushMessage, repl, clearScreen } from "std::cli"
+import { map } from "std::array"
 import { today } from "std::date"
-import { setAgentCwd } from "std::index"
-import { box, render } from "std::layout"
-import { setMemoryId } from "std::memory"
+import { generateImage } from "std::image"
+import { applyAgentCwd, setAgentCwd } from "std::index"
+import { listHostedModels, hostedModelInfo } from "std::llm"
+import { setMemoryId, disableMemory } from "std::memory"
+import { keys } from "std::object"
+import { basename, dirname } from "std::path"
 import {
   ScopedRuleFields,
   cliPolicyHandler,
@@ -15,17 +23,65 @@ import { exists } from "std::shell"
 import { commandsDir, expandSlash } from "std::skills"
 import { highlight } from "std::syntax"
 import { cwd, env, isTTY, readStdin, setTitle } from "std::system"
-import { getCost, getModelCosts, systemMessage } from "std::thread"
+import {
+  Attachment,
+  attachToReply,
+  getCost,
+  getModelCosts,
+  image,
+  systemMessage,
+ } from "std::thread"
 import { chooseOption, ChoiceItem } from "std::ui"
+import {
+  clearMessages,
+  pushMessage,
+  repl,
+  clearScreen,
+  clearHistory,
+ } from "std::ui/cli"
+import { box, render } from "std::ui/layout"
 
 import { figs, title } from "./images/images.agency"
-import { POLICY_PATH, HISTORY_PATH, ALWAYS_FIELDS } from "./lib/config.agency"
+import { detectAttachments, modalityFilter } from "./lib/attachments.agency"
+import {
+  POLICY_PATH,
+  SESSION_POLICY_PATH,
+  HISTORY_PATH,
+  ALWAYS_FIELDS,
+ } from "./lib/config.agency"
 import {
   minimalAutoApprovePolicy,
   recommendedAutoApprovePolicy,
+  builtinPolicy,
+  builtinPolicyNames,
+  BUILTIN_POLICIES,
  } from "./lib/defaultPolicy.agency"
+import { filterHostedModels, ModelFilters } from "./lib/modelFilters.agency"
+import { parseModelFlag, knownProviders, Resolved } from "./lib/models.agency"
+import {
+  buildLayers,
+  resolveAll,
+  diffResolved,
+  Ctx,
+  SlotChange,
+ } from "./lib/resolution.agency"
+import {
+  configureSearch,
+  setSearchBackend,
+  getSearchBackend,
+  availableBackendItems,
+ } from "./lib/search.agency"
+import { getModelSettings, loadSettings } from "./lib/settings.agency"
 import { truncate, formatArgs, formatToolResponse } from "./lib/utils.agency"
-import { configureModels } from "./shared.agency"
+import {
+  configureModels,
+  configureLocalModel,
+  enableAgentMemory,
+  getResolvedSlots,
+  applyResolved,
+  promoteAll,
+  currentProvider,
+ } from "./shared.agency"
 import { codeAgent } from "./subagents/code.agency"
 import { explorerAgent } from "./subagents/explorer.agency"
 import { oracleAgent } from "./subagents/oracle.agency"
@@ -87,6 +143,11 @@ let VERBOSE: boolean = false
 // scroll-output writes when stdout is destined for a Unix pipe.
 let _isInteractive: boolean = true
 
+// The `--policy` argument (a built-in name or a policy-file path), or ""
+// when the flag is absent. Set in main() before `setupSession` runs;
+// consumed there to override the saved policy for this run only.
+let _policyArg: string = ""
+
 // 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).
@@ -126,13 +187,75 @@ callback("onLLMCallEnd") as data {
   }
 }
 
+// Map a transient LLM retry reason (an `LLMRetryReason` from the runtime
+// retry layer) to a short, human-facing label. `connectionLost` is the
+// lost-internet / closed-the-laptop case; the rest cover provider hiccups
+// and our own per-call timeout.
+export def retryReasonLabel(reason: string): string {
+  if (reason == "connectionLost") {
+    return "Connection lost"
+  }
+  if (reason == "timeout") {
+    return "Request timed out"
+  }
+  if (reason == "streamInterrupted") {
+    return "Connection interrupted"
+  }
+  if (reason == "rateLimit") {
+    return "Rate limited"
+  }
+  if (reason == "overloaded") {
+    return "Model overloaded"
+  }
+  if (reason == "serverError") {
+    return "Server error"
+  }
+  return reason
+}
+
+// A transient LLM failure (lost connection, timeout, server hiccup) the
+// runtime is about to retry. Surface a dim, one-line heads-up so the user
+// understands the pause instead of staring at a frozen prompt — this is the
+// "lost internet / closed the laptop" experience the abort taxonomy made
+// distinguishable. Gated like the other traces so piped one-shot output
+// stays clean. `attempt` is the 1-based retry number; `maxRetries` is the
+// configured retry budget.
+callback("onLLMRetry") as data {
+  if (_showTraces()) {
+    pushMessage(
+      color.dim(
+      "⟳ ${retryReasonLabel(data.reason)} — retrying (${data.attempt}/${data.maxRetries})…",
+    ),
+    )
+  }
+}
+
+// Turn a terminal (retries-exhausted) LLM failure into a short, actionable
+// message. The runtime's exhausted-retry error text embeds the reason in
+// parens, e.g. "LLM call failed after 3 attempts (connectionLost): ...". We
+// recognize the transport reasons that mean "the network or model dropped"
+// and give concrete advice; anything else echoes the raw error so nothing
+// is hidden.
+export def formatTurnFailure(errText: string): string {
+  if (errText.includes("(connectionLost)") || errText.includes("(streamInterrupted)")) {
+    return "⚠ Lost the connection to the model and couldn't recover after retrying.\nCheck your internet connection and try again."
+  }
+  if (errText.includes("(timeout)")) {
+    return "⚠ The model took too long to respond — the request timed out after retrying.\nTry again, perhaps with a smaller request."
+  }
+  if (errText.includes("(rateLimit)") || errText.includes("(overloaded)") || errText.includes("(serverError)")) {
+    return "⚠ The model provider is busy and the request failed after retrying.\nWait a moment and try again."
+  }
+  return "⚠ The request failed: ${errText}"
+}
+
 type ToolCallData = {
   name: string;
   arguments: any
 }
 
 type LLMResponse = {
-  output: string | null;
+  output?: string;
   toolCalls: ToolCallData[];
   usage: { inputTokens: number; outputTokens: number; totalTokens: number; cachedInputTokens: number };
   cost: { inputCost: number; outputCost: number; cachedInputCost: number; totalCost: number; currency: string };
@@ -144,7 +267,7 @@ def renderLLMCallResponse(data: LLMResponse): string {
   if (data.output != "" && data.output != null && data.output != undefined) {
     response.push(data.output)
   }
-  if (data.toolCalls && data.toolCalls.length > 0) {
+  if (data.toolCalls.length > 0) {
     for (toolCall in data.toolCalls) {
       response.push(`${toolCall.name}(${formatArgs(toolCall.arguments)})`)
     }
@@ -184,7 +307,12 @@ def builtinPalette(): Record<string, string> {
   return {
     "/exit": "Exit the agent",
     "/clear": "Clear the conversation transcript",
+    "/clear-history": "Clear the input history (recall + saved file)",
     "/cost": "Show cumulative LLM cost and tokens",
+    "/model": "Switch the model (bare to pick, or slot=model)",
+    "/models": "List / filter the hosted model catalog",
+    "/local": "Switch to a local model",
+    "/search": "Choose the web search backend (hosted / Tavily / Brave / off)",
     "/paste": "Multi-line paste mode (Ctrl+D submits, Ctrl+C cancels)",
     "/help": "Show available slash commands"
   }
@@ -208,6 +336,136 @@ def mergedPalette(): Record<string, string> {
   return out
 }
 
+// In-session model selection state. One mutable cell holding the current
+// Session (the pin + per-slot overrides chosen via /model this run). switchModel
+// is pure over this value — it copies, never mutates — so it stays testable.
+export type Session = {
+  pin: string;
+  slots: Record<string, string>
+}
+
+let _session: Session = {
+  pin: "",
+  slots: {}
+}
+
+/** Apply an in-session model selection. Copies `prior` (never mutates), folds in
+  the new spec (bare → pin; slot=model → per-slot), resolves, applies, and returns
+  the new session + assignment + the slots that changed (so the caller can react,
+  e.g. the cross-provider recall notice). Turn-boundary semantics: takes effect on
+  the NEXT turn; no in-flight call is mutated. */
+export def switchModel(
+  prior: Session,
+  spec: string,
+  ctx: Ctx,
+  before: Record<string, Resolved>,
+): { session: Session; resolved: Record<string, Resolved>; changes: SlotChange[] } {
+  let nextSlots: Record<string, string> = {}
+  for (key in Object.keys(prior.slots)) {
+    nextSlots[key] = prior.slots[key]
+  }
+  let next: Session = {
+    pin: prior.pin,
+    slots: nextSlots
+  }
+  const parsed = parseModelFlag(spec)
+  if (parsed.slot != "" && parsed.slot != "main" && parsed.slot != "reasoning") {
+    pushMessage(
+      color.red("Unknown model slot '${parsed.slot}'. Valid slots: main, reasoning."),
+    )
+    return {
+      session: prior,
+      resolved: before,
+      changes: []
+    }
+  }
+  if (parsed.slot == "") {
+    next.pin = parsed.model
+  } else {
+    next.slots[parsed.slot] = parsed.model
+  }
+
+  // A saved provider (settings.model.provider) means a provider is established,
+  // so a unified provider/model spec should not be split during resolution.
+  const settings = getModelSettings(loadSettings())
+  const providerEstablished = settings.provider != null && settings.provider != ""
+  const layers = buildLayers(
+    next.pin,
+    next.slots,
+    "",
+    {},
+    settings,
+    knownProviders(),
+    providerEstablished,
+  )
+  const all = resolveAll(layers, ctx)
+  if (isFailure(all)) {
+    pushMessage(color.red("Could not switch model: ${all.error}"))
+    return {
+      session: prior,
+      resolved: before,
+      changes: []
+    }
+  }
+  const resolved = promoteAll(all.value)
+  applyResolved(resolved)
+  return {
+    session: next,
+    resolved: resolved,
+    changes: diffResolved(before, resolved)
+  }
+}
+
+/** React to one resolved-slot change. Phase 1: a `main`-slot provider change
+  means the embedding space behind memory changed, so pause memory and warn.
+  (std::memory has no tier-2-only toggle yet -- full pause; structured recall
+  returns when a selective toggle lands.) Returns true if it emitted the notice. */
+export def reactToSlotChange(change: SlotChange): boolean {
+  if (change.slot == "main" && change.before.provider != change.after.provider) {
+    pushMessage(
+      color.dim(
+      "Warning: provider changed - memory is paused until restart (recall would be unreliable).",
+    ),
+    )
+    // `with approve`: the agent is deliberately auto-pausing memory on a
+    // provider switch, not asking the user — so don't surface an approval prompt.
+    disableMemory() with approve
+    return true
+  }
+  return false
+}
+
+// ChoiceItem list for the model pickers: the hosted catalog, filtered, each
+// labeled with provider + input price for an informed pick.
+export def modelChoiceItems(filters: ModelFilters): ChoiceItem[] {
+  let items: ChoiceItem[] = []
+  for (model in filterHostedModels(listHostedModels(), filters)) {
+    const label = "${model.name}  (${model.provider}, $${model.inputCost}/1M in)"
+    items.push({
+      key: model.name,
+      label: label
+    })
+  }
+  return items
+}
+
+// Parse a `/models [provider]` command line into filters. Bare `/models` (or a
+// trailing-space-only arg) yields no filters; `/models <provider>` narrows to
+// one provider. Extracted from the handler so it is unit-testable.
+export def parseModelsFilters(cmd: string): ModelFilters {
+  const prefix = "/models "
+  if (!cmd.startsWith(prefix)) {
+    return {}
+  }
+  const arg = cmd.substring(prefix.length).trim()
+  if (arg == "") {
+    return {}
+  }
+  return {
+    provider: arg
+  }
+}
+
 // Slash-command + user-message dispatcher invoked by `repl()` for
 // every Enter keystroke. Return `false` to terminate the loop.
 def _runTurn(msg: string): boolean {
@@ -227,8 +485,30 @@ def _runTurn(msg: string): boolean {
     clearMessages()
     return true
   }
+  if (trimmed == "/clear-history") {
+    clearHistory()
+    pushMessage("Input history cleared.")
+    return true
+  }
   if (trimmed == "/help") {
-    pushMessage("Commands: /exit, /clear, /cost, /paste, /help")
+    pushMessage(
+      "Commands: /exit, /clear, /clear-history, /cost, /model, /models, /local, /search, /paste, /help",
+    )
+    return true
+  }
+  if (trimmed == "/search") {
+    const opts = availableBackendItems()
+    const choice = chooseOption(
+      "Web search backend",
+      "Pick how this agent searches the web. Current: ${getSearchBackend()}",
+      opts,
+      false,
+      true,
+    )
+    if (choice != "" && choice != null && choice != undefined) {
+      setSearchBackend(choice)
+      pushMessage("Web search backend set to: ${choice}")
+    }
     return true
   }
   if (trimmed == "/cost") {
@@ -252,18 +532,123 @@ def _runTurn(msg: string): boolean {
       pushMessage("")
       pushMessage("By model:")
       for (m in byModel) {
-        pushMessage("  ${m.model}  ↑${m.inputTokens} ↓${m.outputTokens}  $${m.cost.toFixed(4)}")
+        pushMessage(
+          "  ${m.model}  ↑${m.inputTokens} ↓${m.outputTokens}  $${m.cost.toFixed(4)}",
+        )
       }
     }
     return true
   }
+  if (trimmed == "/model" || trimmed.startsWith("/model ")) {
+    let spec = ""
+    if (trimmed != "/model") {
+      spec = trimmed.substring(7).trim()
+    }
+    if (spec == "") {
+      pushMessage("Current models:")
+      const current = getResolvedSlots()
+      for (slot in Object.keys(current)) {
+        const resolved = current[slot]
+        if (resolved != null) {
+          pushMessage("  ${slot}: ${resolved.model} (${resolved.via})")
+        }
+      }
+      const items = modelChoiceItems({})
+      const choice = chooseOption(
+        "Model",
+        "Pick a model, or type one (or slot=model, e.g. reasoning=claude-opus-4-8). Empty to cancel.",
+        items,
+        allowFreeText: true,
+        allowCancel: true,
+      )
+      if (choice == "" || choice == null) {
+        return true
+      }
+      spec = choice
+    }
+    const ctx: Ctx = {
+      provider: currentProvider(),
+      price: "standard"
+    }
+    const out = switchModel(_session, spec, ctx, getResolvedSlots())
+    _session = out.session
+    for (change in out.changes) {
+      reactToSlotChange(change)
+    }
+    pushMessage("Model set:")
+    for (slot in Object.keys(out.resolved)) {
+      const resolved = out.resolved[slot]
+      if (resolved != null) {
+        pushMessage(color.dim("  ${slot}: ${resolved.model} (${resolved.via})"))
+      }
+    }
+    return true
+  }
+  if (trimmed == "/models" || trimmed.startsWith("/models ")) {
+    const filters = parseModelsFilters(trimmed)
+    const models = filterHostedModels(listHostedModels(), filters)
+    if (models.length == 0) {
+      pushMessage("No models match.")
+      return true
+    }
+    for (model in models) {
+      pushMessage(
+        "  ${model.name}  (${model.provider}, $${model.inputCost}/1M in, ${model.contextWindow} ctx)",
+      )
+    }
+    return true
+  }
+  if (trimmed == "/local") {
+    if (!localModelsSupported()) {
+      pushMessage(
+        color.yellow(
+        "Local models need smoltalk-llama-cpp. Install:  ! npm i -g smoltalk-llama-cpp",
+      ),
+      )
+      return true
+    }
+    let items: ChoiceItem[] = []
+    for (modelName in listModelNames()) {
+      items.push({
+        key: modelName.name,
+        label: modelName.name
+      })
+    }
+    const choice = chooseOption(
+      "Local model",
+      "Pick a local model, or type an hf: URI / .gguf path (downloads on first use):",
+      items,
+      allowFreeText: true,
+      allowCancel: true,
+    )
+    if (choice == "" || choice == null) {
+      return true
+    }
+    const before = getResolvedSlots()
+    configureLocalModel(choice)
+    configureSearch(true)
+    for (change in diffResolved(before, getResolvedSlots())) {
+      reactToSlotChange(change)
+    }
+    pushMessage("Switched to local model: ${choice}")
+    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."))
+  // Wrap in `try` so a terminal LLM failure (e.g. the connection dropped and
+  // retries were exhausted) renders a friendly heads-up instead of a raw
+  // Failure object. Aborts/interrupts are NOT caught here — `try` re-throws
+  // them so an Esc-cancel still reaches the policy handler.
+  const result = try agentReply(msg)
+  if (result is success(reply)) {
+    if (reply != "" && reply != null && reply != undefined) {
+      pushMessage(highlight("${reply}\n", language: "markdown"))
+    } else {
+      pushMessage(color.red("No reply generated."))
+    }
+  } else if (result is failure(f)) {
+    pushMessage(color.red(formatTurnFailure("${f.error}")))
   }
   return true
 }
@@ -279,8 +664,8 @@ 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:
+You have five subagent tools (each running in its own isolated
+context) and one direct tool:
 
 - `codeAgent(userMsg)` — anything that touches code or the filesystem:
   reading, writing, editing, typechecking, running shell commands,
@@ -297,6 +682,11 @@ context:
 - `explorerAgent(userMsg)` — a read-only researcher that produces
   broad, synthesizing answers about the codebase or bundled docs.
   Read the **Explorer** section below.
+- `generateImageFile(prompt, path, size, images)` — generate an image
+  from a text prompt (or modify existing images by passing their paths
+  in `images`) and save it to `path`. Call it directly whenever the
+  user asks you to create, draw, edit, or restyle an image — do NOT
+  route image generation to `codeAgent`.
 
 **Answer directly (no tool call) when** the message is conversational,
 a clarifying question, or something you can answer from context alone.
@@ -439,22 +829,86 @@ unless the user has clearly asked for an action ("do X", "fix Y",
 with them — don't sprint to implementation.
 """
 
+// Exported for tests: agent-cwd resolution of edit inputs is a spec
+// invariant with no other observable (the deterministic image client
+// ignores its images argument). generateImage accepts path / URL /
+// data-URI strings, so only local paths get agent-cwd resolution —
+// running a URL through applyAgentCwd would mangle it into
+// "<agentCwd>/https:/…".
+export def resolveEditInputs(images: string[]): string[] {
+  return map(images) as inputPath {
+    if (inputPath.startsWith("http://") || inputPath.startsWith("https://") || inputPath.startsWith("data:")) {
+      return inputPath
+    }
+    return applyAgentCwd(inputPath)
+  }
+}
+
+// Direct image generation for the coordinator. Saves to disk and
+// returns the path — never base64, which would flood the LLM context.
+// The write rides the std::writeBinary interrupt gate (writes are not
+// auto-approved by policy) and generation cost accrues to the agent's
+// cost tracking like any llm() call.
+export def generateImageFile(
+  prompt: string,
+  path: string,
+  size: string = "",
+  images: string[] = [],
+): string {
+  """
+  Generate an image from a text prompt and save it to `path`. To MODIFY
+  existing images (edit / variation), pass their paths in `images`.
+  Returns the saved path on success. Use this when the user asks to
+  create, draw, edit, or restyle an image.
+
+  @param prompt - What to generate, or how to modify the input images.
+  @param path - Where to save the resulting image (e.g. "diagram.png").
+  @param size - Optional size like "1024x1024".
+  @param images - Optional input image paths to edit / vary.
+  """
+  // LLM-supplied paths resolve against the agent cwd, like every other
+  // agent file tool.
+  const inputs = resolveEditInputs(images)
+  const generated = generateImage(prompt, size: size, images: inputs)
+  if (isFailure(generated)) {
+    return "Image generation failed: ${generated.error}"
+  }
+  // writeBinary rejects an absolute filename when dir is set, so split
+  // path into (dir, name); useAgentCwd resolves a relative dir against
+  // the agent cwd (absolute dirs pass through untouched).
+  const written = writeBinary(
+    basename(path),
+    generated.value.base64,
+    dirname(path),
+    useAgentCwd: true,
+  )
+  if (isFailure(written)) {
+    return "Generated the image, but saving to ${path} failed: ${written.error}"
+  }
+  // Show the model what it made (generate -> view -> refine). The loop
+  // inlines the bytes when it builds the injected user message; the
+  // path resolves the same way the write did.
+  attachToReply(image(applyAgentCwd(path)))
+  return "Saved image to ${path}"
+}
+
 static const mainAgentTools = [
   researchAgent.partial(allowHandoff: false),
   codeAgent.partial(allowHandoff: false),
   reviewAgent.partial(allowHandoff: false),
   oracleAgent.partial(allowHandoff: false),
   explorerAgent.partial(allowHandoff: false),
+  generateImageFile,
 ]
 
-def mainAgent(prompt: string): string {
+def mainAgent(prompt: string | (string | Attachment)[]): 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)
+      systemMessage("${mainAgentSystemPrompt}${_context}")
       first = false
     }
     const result = llm(prompt, {
@@ -487,7 +941,30 @@ export def agentReplyVia(target: string, userMsg: string): string {
   if (target == "review") {
     return reviewAgent(expanded, false)
   }
-  return mainAgent(expanded)
+  // Auto-attach image/PDF files the user referenced (drag-drop or typed
+  // path), filtered to what the resolved model accepts. Never silent:
+  // every attach and every skip prints a visible line.
+  const detected = modalityFilter(detectAttachments(expanded))
+  for (skippedFile in detected.skipped) {
+    pushMessage(
+      color.yellow("📎 skipped ${skippedFile.label} (${skippedFile.reason})"),
+    )
+  }
+  if (detected.attached.length == 0) {
+    // Deliberate special case: a text-only turn stays a bare string. A
+    // one-element array is API-equivalent, but the stored thread message
+    // shape (string vs parts array) — and with it every serialized
+    // session and message fixture — would change for EVERY turn.
+    return mainAgent(expanded)
+  }
+  for (item in detected.attached) {
+    pushMessage(color.dim("📎 attached ${item.label}"))
+  }
+  const attachments = map(detected.attached) as item {
+    return item.attachment
+  }
+  const parts: (string | Attachment)[] = [expanded, ...attachments]
+  return mainAgent(parts)
 }
 
 // The agent's core turn, decoupled from the terminal: expand any project
@@ -543,6 +1020,21 @@ def printHeader() {
   print(render(data, color: true))
 }
 
+// Print `--policy` usage and list the built-in policies (name + one-line
+// description). Shown when `--policy` is passed with no value.
+def printPolicyHelp() {
+  print(color.bold("Usage: agency agent --policy <name | path>"))
+  print(
+    "Select the approval policy for this run: a built-in name below, or a path to a policy JSON file.",
+  )
+  print("")
+  print(color.bold("Built-in policies:"))
+  for (p in BUILTIN_POLICIES) {
+    print("  ${color.cyan(p.name)}")
+    print("      ${p.description}")
+  }
+}
+
 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."
@@ -558,9 +1050,9 @@ def givePolicyChoice() {
   ]
 
   const answer = chooseOption(title, body, items, allowFreeText: true)
-  match(answer) {
-    "minimal" => return minimalAutoApprovePolicy
-    "recommended" => return recommendedAutoApprovePolicy
+  return match(answer) {
+    "minimal" => minimalAutoApprovePolicy
+    "recommended" => recommendedAutoApprovePolicy
   }
 }
 
@@ -584,25 +1076,66 @@ def setupSession(interactive: boolean): any {
   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())
+  // Which file the handler persists against, and an optional in-memory
+  // policy to start from. Normally the user's saved policy loaded from
+  // POLICY_PATH; a `--policy` override redirects this (see below) so the
+  // saved policy is never read or written.
+  let policyFile = POLICY_PATH
+  let sessionPolicy: any = null
+
+  if (_policyArg != "") {
+    // `--policy` override: a built-in name or a path to a policy file.
+    // The cwd-scoped built-ins pin the launch directory, so we resolve
+    // them against `cwd()` (what `setAgentCwd` just stored, and what the
+    // write/git/bash interrupts resolve their default paths back to).
+    const builtin = builtinPolicy(_policyArg, cwd())
+    if (builtin != null) {
+      // Hand the policy to the handler in memory (no disk write): a
+      // one-off, cwd-scoped override must not clobber the saved policy
+      // or leak into a later run from a different directory. Any new
+      // interactive "always" decision persists to the session file.
+      policyFile = SESSION_POLICY_PATH
+      sessionPolicy = builtin
+    } else {
+      // Not a built-in name — treat it as a policy file path and use it
+      // directly (the handler loads/persists it). Validate up front so a
+      // typo fails fast instead of silently starting from empty.
+      const loaded = parsePolicyFile(_policyArg)
+      if (loaded is failure(f)) {
+        print(
+          color.red(
+          "--policy '${_policyArg}' is neither a built-in policy (${builtinPolicyNames().join(", ")}) nor a readable policy file (${f.status}).",
+        ),
+        )
+        process.exit(1)
+      }
+      policyFile = _policyArg
+    }
+  } else {
+    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 {
-        setPolicy(POLICY_PATH, recommendedAutoApprovePolicy)
+        print(color.red("Failed to load policy: ${JSON.stringify(f.error)}"))
+        process.exit(1)
       }
     } else {
-      print(color.red("Failed to load policy: ${JSON.stringify(f.error)}"))
-      process.exit(1)
+      setPolicy(POLICY_PATH, policy.value)
     }
-  } 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)
+  return cliPolicyHandler(
+    file: policyFile,
+    fields: ALWAYS_FIELDS,
+    policy: sessionPolicy,
+  )
 }
 
 // One-shot entry: run a single turn through the same `mainAgent` the
@@ -616,7 +1149,15 @@ def oneShotAgent(target: string, prompt: string): string {
   const handler = setupSession(false)
   let reply: string = ""
   handle {
-    reply = agentReplyVia(target, prompt)
+    // `try` converts a terminal LLM failure (retries exhausted on a dropped
+    // connection / timeout) into a friendly message; aborts/interrupts still
+    // propagate to the handler below.
+    const result = try agentReplyVia(target, prompt)
+    if (result is success(r)) {
+      reply = r
+    } else if (result is failure(f)) {
+      reply = formatTurnFailure("${f.error}")
+    }
   } with (data) {
     return handler(data)
   }
@@ -628,11 +1169,15 @@ def oneShotAgent(target: string, prompt: string): string {
 // 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."))
+  const result = try agentReplyVia(target, msg)
+  if (result is success(reply)) {
+    if (reply != "" && reply != null && reply != undefined) {
+      pushMessage(highlight("${reply}\n", language: "markdown"))
+    } else {
+      pushMessage(color.red("No reply generated."))
+    }
+  } else if (result is failure(f)) {
+    pushMessage(color.red(formatTurnFailure("${f.error}")))
   }
 }
 
@@ -697,7 +1242,7 @@ node main() {
       },
       provider: {
         type: "string",
-        description: "Force the LLM provider. Given alone (openai/anthropic/google) it selects that provider's default models and skips env auto-detection; pair it with --model for a custom/local model name"
+        description: "Force the LLM provider. Given alone (openai/anthropic/google/openrouter) it selects that provider's default models and skips env auto-detection; pair it with --model for any other provider (e.g. litellm, openai-compat, or a custom/local model)"
       },
       interactive: {
         type: "boolean",
@@ -707,6 +1252,21 @@ node main() {
       agent: {
         type: "string",
         description: "Route the starting prompt to a named subagent: code, research, oracle, explorer, review (default: coordinator)"
+      },
+      policy: {
+        type: "string",
+        optional: true,
+        description: "Approval policy for this run: a built-in name (minimal, recommended, with-writes, with-bash) or a path to a policy JSON file. with-writes/with-bash auto-approve writes (and, for with-bash, shell) scoped to the current directory and its children. Overrides the saved policy without persisting it. Pass --policy with no value to list the built-in policies."
+      },
+      local: {
+        type: "string",
+        optional: true,
+        description: "Run a local model (downloads if needed): a curated short name, an hf: URI, or a .gguf path. Run without a value for guided setup. Pins all slots to the local model; mutually exclusive with --model/--fastmodel/--slowmodel. Requires: npm i -g smoltalk-llama-cpp"
+      },
+      "local-model": {
+        type: "string",
+        optional: true,
+        description: "Deprecated alias for --local."
       }
     }
   },
@@ -718,20 +1278,107 @@ node main() {
   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 ?? "",
-  )
+  // `--policy` is an optional-value flag: a bare `--policy` (no name or
+  // path) prints the usage + the built-in policies and exits, rather than
+  // silently doing nothing.
+  if (args.flags.policy == "") {
+    printPolicyHelp()
+    process.exit(0)
+  }
+  _policyArg = args.flags.policy ?? ""
+
+  // Model setup. `--local` (deprecated alias: `--local-model`) is an optional-
+  // value flag with three states: absent (null); bare empty-string for guided
+  // setup; a value for that local model. `--local` and the hosted flags
+  // (--model / --fastmodel / --slowmodel) are mutually exclusive -- local and
+  // hosted are different in kind (provider llama-cpp, no embedding endpoint).
+  const localVal = args.flags["local"] ?? args.flags["local-model"]
+  const modelArg = args.flags.model ?? ""
+  const hasModelFlags = modelArg != "" || (args.flags.fastmodel ?? "") != "" || (args.flags.slowmodel ?? "") != ""
+  if (localVal != null && hasModelFlags) {
+    print(
+      color.red("Pass either --model (hosted) or --local (local), not both."),
+    )
+    process.exit(1)
+  }
+  if (localVal == "") {
+    // Bare --local: guided setup. Non-interactive can't prompt, so keep the
+    // print-catalog-and-exit behavior there.
+    if (!isTTY()) {
+      printLocalCatalog()
+      process.exit(0)
+    }
+    if (!localModelsSupported()) {
+      print(color.yellow("Local models need the smoltalk-llama-cpp package."))
+      print("Install it, then re-run:  ! npm i -g smoltalk-llama-cpp")
+      process.exit(1)
+    }
+    let items: ChoiceItem[] = []
+    for (modelName in listModelNames()) {
+      items.push({
+        key: modelName.name,
+        label: modelName.name
+      })
+    }
+    const choice = chooseOption(
+      "Local model",
+      "Pick a model, or type an hf: URI / .gguf path (downloads on first use):",
+      items,
+      allowFreeText: true,
+      allowCancel: true,
+    )
+    if (choice == "" || choice == null) {
+      process.exit(0)
+    }
+    configureLocalModel(choice)
+    configureSearch(true)
+    // fall through into the session on the chosen local model
+  } else if (localVal != null) {
+    configureLocalModel(localVal)
+    // Intentionally do NOT enable memory for a local model: the llama-cpp
+    // provider has no embedding endpoint, so memory would only emit a
+    // "Tier-2 disabled" notice. std::memory calls no-op while it's off.
+    configureSearch(true)
+  } else {
+    // Hosted path. --model accepts `slot=model` (per-slot) or a bare model
+    // (global pin); explicit --fastmodel/--slowmodel win over a --model slot=.
+    const parsed = parseModelFlag(modelArg)
+    let modelGlobal = ""
+    let fastFlag = ""
+    let slowFlag = ""
+    if (modelArg != "") {
+      if (parsed.slot == "") {
+        modelGlobal = parsed.model
+      } else if (parsed.slot == "main") {
+        fastFlag = parsed.model
+      } else if (parsed.slot == "reasoning") {
+        slowFlag = parsed.model
+      } else {
+        print(
+          color.red(
+          "Unknown model slot '${parsed.slot}' in --model. Valid slots: main, reasoning.",
+        ),
+        )
+        process.exit(1)
+      }
+    }
+    const fm = args.flags.fastmodel ?? ""
+    const sm = args.flags.slowmodel ?? ""
+    if (fm != "") {
+      fastFlag = fm
+    }
+    if (sm != "") {
+      slowFlag = sm
+    }
+    configureModels(modelGlobal, fastFlag, slowFlag, args.flags.provider ?? "")
+    // Persistent knowledge graph — enabled for hosted providers, skipped for
+    // local models. (Some hosted providers, e.g. anthropic, still lack an
+    // embedding endpoint and just disable Tier-2 recall with a one-time
+    // notice; structured recall works regardless.) Must run before any
+    // handler/REPL is installed.
+    enableAgentMemory()
+    configureSearch(false)
+  }
 
   // Positional args (everything after flags) are joined with spaces to
   // form the starting prompt. `--` ends flag parsing if a positional