agency-lang 0.6.4 → 0.7.0

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

@@ -1,10 +1,26 @@
 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 {
+  clearMessages,
+  pushMessage,
+  repl,
+  clearScreen,
+  clearHistory,
+ } from "std::ui/cli"
 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 { keys } from "std::object"
+import { basename, dirname } from "std::path"
+import { box, render } from "std::ui/layout"
+import { listHostedModels, hostedModelInfo } from "std::llm"
+import { setMemoryId, disableMemory } from "std::memory"
 import {
   ScopedRuleFields,
   cliPolicyHandler,
@@ -15,17 +31,42 @@ 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 { figs, title } from "./images/images.agency"
+import { detectAttachments, modalityFilter } from "./lib/attachments.agency"
 import { POLICY_PATH, HISTORY_PATH, ALWAYS_FIELDS } from "./lib/config.agency"
 import {
   minimalAutoApprovePolicy,
   recommendedAutoApprovePolicy,
  } 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"
@@ -126,13 +167,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 +247,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 +287,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 +316,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 +465,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 +512,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 +644,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 +662,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 +809,81 @@ 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 +916,28 @@ 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
@@ -558,9 +1008,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
   }
 }
 
@@ -616,7 +1066,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 +1086,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 +1159,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 +1169,16 @@ node main() {
       agent: {
         type: "string",
         description: "Route the starting prompt to a named subagent: code, research, oracle, explorer, review (default: coordinator)"
+      },
+      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."
       }
     }
   },
@@ -719,19 +1191,98 @@ node main() {
     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 ?? "",
-  )
+  // 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
@@ -801,3 +1352,4 @@ node main() {
   const handler = setupSession(true)
   startInteractive(handler, "", "")
 }
+