agency-lang 0.7.7 → 0.8.0

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

@@ -18,7 +18,13 @@ import {
   cliPolicyHandler,
   parsePolicyFile,
   setPolicy,
+  minimalAutoApprovePolicy,
+  recommendedAutoApprovePolicy,
+  builtinPolicy,
+  builtinPolicyNames,
+  BUILTIN_POLICIES,
  } from "std::policy"
+import { loadMcpToolsWithStatus, mergeMcpServers, isMcpAvailable, readProjectMcpConfig } from "std::mcp"
 import { exists } from "std::shell"
 import { commandsDir, expandSlash } from "std::skills"
 import { highlight } from "std::syntax"
@@ -49,15 +55,9 @@ import {
   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 { parseModelFlag, parseModelSpec, knownProviders, embeddingSpecHasProvider, missingProviderEnvVar, Resolved } from "./lib/models.agency"
+import { SLOTS } from "./lib/slots.agency"
 import {
   buildLayers,
   resolveAll,
@@ -71,7 +71,21 @@ import {
   getSearchBackend,
   availableBackendItems,
  } from "./lib/search.agency"
-import { getModelSettings, loadSettings } from "./lib/settings.agency"
+import {
+  CAPABILITY_FIELDS,
+  CapabilityPatch,
+  mergeCapabilityOverride,
+  removeCapabilityField,
+  providerLacksEmbeddings,
+ } from "./lib/capabilities.agency"
+import {
+  Settings,
+  getCapabilitySettings,
+  getModelSettings,
+  getMcpServers,
+  loadSettings,
+  saveSettings,
+ } from "./lib/settings.agency"
 import { truncate, formatArgs, formatToolResponse } from "./lib/utils.agency"
 import {
   configureModels,
@@ -82,6 +96,17 @@ import {
   promoteAll,
   currentProvider,
   resolveMaxToolCallRounds,
+  getCapabilities,
+  getCapabilitiesResolved,
+  getCapabilityModelKey,
+  getCapabilityProvider,
+  refreshCapabilities,
+  embeddingKeyStatus,
+  memoryEnablePlan,
+  overrideFromResolved,
+  embeddingsOverride,
+  providerEnvMissing,
+  demoteProvider,
  } from "./shared.agency"
 import { codeAgent, setCodeOneShot } from "./subagents/code.agency"
 import { explorerAgent } from "./subagents/explorer.agency"
@@ -211,6 +236,9 @@ export def retryReasonLabel(reason: string): string {
   if (reason == "serverError") {
     return "Server error"
   }
+  if (reason == "invalidStructuredOutput") {
+    return "Output failed validation"
+  }
   return reason
 }
 
@@ -314,6 +342,8 @@ def builtinPalette(): Record<string, string> {
     "/models": "List / filter the hosted model catalog",
     "/local": "Switch to a local model",
     "/search": "Choose the web search backend (hosted / Tavily / Brave / off)",
+    "/settings": "View and change capability settings for the current model",
+    "/mcp": "List configured MCP servers and their tools",
     "/paste": "Multi-line paste mode (Ctrl+D submits, Ctrl+C cancels)",
     "/help": "Show available slash commands"
   }
@@ -361,6 +391,15 @@ export def switchModel(
   ctx: Ctx,
   before: Record<string, Resolved>,
 ): { session: Session; resolved: Record<string, Resolved>; changes: SlotChange[] } {
+  // The caller builds ctx from currentProvider(), which returns the
+  // PROMOTED name on openai sessions. priceDefault and the built-in
+  // tables key by public provider names, so demote before resolving —
+  // otherwise a switch that lets any slot fall through to the built-in
+  // defaults fails with "openai-responses has no built-in defaults".
+  const ctx2: Ctx = {
+    provider: demoteProvider(ctx.provider),
+    price: ctx.price
+  }
   let nextSlots: Record<string, string> = {}
   for (key in Object.keys(prior.slots)) {
     nextSlots[key] = prior.slots[key]
@@ -370,9 +409,23 @@ export def switchModel(
     slots: nextSlots
   }
   const parsed = parseModelFlag(spec)
-  if (parsed.slot != "" && parsed.slot != "main" && parsed.slot != "reasoning") {
+  if (parsed.slot != "" && !SLOTS.includes(parsed.slot)) {
     pushMessage(
-      color.red("Unknown model slot '${parsed.slot}'. Valid slots: main, reasoning."),
+      color.red("Unknown model slot '${parsed.slot}'. Valid slots: ${SLOTS.join(", ")}."),
+    )
+    return {
+      session: prior,
+      resolved: before,
+      changes: []
+    }
+  }
+  if (parsed.slot == "embedding" && !embeddingSpecHasProvider(parsed.model)) {
+    // The embedding slot exists to point AWAY from the chat provider, so
+    // the provider can never be inferred. Require the explicit form.
+    pushMessage(
+      color.red(
+      "Embedding models need the provider/model form, e.g. embedding=openai/text-embedding-3-small.",
+    ),
     )
     return {
       session: prior,
@@ -399,7 +452,7 @@ export def switchModel(
     knownProviders(),
     providerEstablished,
   )
-  const all = resolveAll(layers, ctx)
+  const all = resolveAll(layers, ctx2)
   if (isFailure(all)) {
     pushMessage(color.red("Could not switch model: ${all.error}"))
     return {
@@ -423,6 +476,13 @@ export def switchModel(
   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) {
+    // Skip the pause only when startup actually enabled memory WITH the
+    // override. A set-but-keyless slot took the fallback path, so memory
+    // runs on derived embeddings and the provider change still shifts
+    // the embedding space behind recall.
+    if (_memoryEmbeddingsPinned) {
+      return false
+    }
     pushMessage(
       color.dim(
       "Warning: provider changed - memory is paused until restart (recall would be unreliable).",
@@ -433,6 +493,28 @@ export def reactToSlotChange(change: SlotChange): boolean {
     disableMemory() with approve
     return true
   }
+  if (change.slot == "embedding") {
+    const override = overrideFromResolved(change.after)
+    if (override != null) {
+      const missing = missingProviderEnvVar(override.provider)
+      if (missing != "") {
+        pushMessage(
+          color.yellow(
+          "Warning: the embedding slot needs ${missing}, which is not set. The assignment takes effect at next agent start, and memory falls back to the default embedding behavior until it is exported.",
+        ),
+        )
+        return true
+      }
+      // The healthy path must not be silent: enableMemory already ran,
+      // so the user would otherwise believe embeddings switched now.
+      pushMessage(
+        color.dim(
+        "Embedding slot set: memory embeddings use ${override.provider}/${override.model} at next agent start.",
+      ),
+      )
+      return true
+    }
+  }
   return false
 }
 
@@ -467,6 +549,290 @@ export def parseModelsFilters(cmd: string): ModelFilters {
   }
 }
 
+/** Human label for a capability source layer. Interprets the source
+  strings resolveCapabilities emits (capabilities.agency). */
+def capabilitySourceLabel(source: string): string {
+  if (source == "default") {
+    return "built-in default"
+  }
+  if (source == "provider") {
+    return "provider default: ${getCapabilityProvider()}"
+  }
+  if (source == "model") {
+    return "built-in for ${getCapabilityModelKey()}"
+  }
+  if (source == "user-global") {
+    return "your global override"
+  }
+  if (source == "user-provider") {
+    return "your override for ${getCapabilityProvider()}"
+  }
+  return "your override for ${getCapabilityModelKey()}"
+}
+
+/** One "value (source)" cell. The typed Capabilities shape cannot be
+  indexed by a dynamic key, so this is the renderer's per-field switch. */
+def capabilityRow(fieldKey: string): string {
+  const resolved = getCapabilitiesResolved()
+  const values = resolved.values
+  const sources = resolved.sources
+  if (fieldKey == "prompt") {
+    return "${values.prompt}   (${capabilitySourceLabel(sources.prompt)})"
+  }
+  if (fieldKey == "summarize") {
+    return "${values.summarize}   (${capabilitySourceLabel(sources.summarize)})"
+  }
+  if (fieldKey == "memory") {
+    return "${values.memory}   (${capabilitySourceLabel(sources.memory)})"
+  }
+  let cap = "none"
+  if (values.maxTokens != null) {
+    cap = "${values.maxTokens}"
+  }
+  return "${cap}   (${capabilitySourceLabel(sources.maxTokens)})"
+}
+
+/** Render the current profile with per-field provenance. */
+def showCapabilities() {
+  pushMessage("Capabilities for ${getCapabilityModelKey()} (${getCapabilityProvider()}):")
+  for (field in CAPABILITY_FIELDS) {
+    pushMessage("  ${field.label}   ${capabilityRow(field.key)}")
+  }
+}
+
+/** The settings.json key a scope writes under. Global's key is unused. */
+def scopeTargetName(scopeKey: string): string {
+  if (scopeKey == "provider") {
+    return getCapabilityProvider()
+  }
+  return getCapabilityModelKey()
+}
+
+/** Persist one override patch at a scope, then re-resolve. */
+def saveCapabilityOverride(scopeKey: string, patch: CapabilityPatch) {
+  let settings = loadSettings()
+  settings.capabilities = mergeCapabilityOverride(
+    getCapabilitySettings(settings),
+    scopeKey,
+    scopeTargetName(scopeKey),
+    patch,
+  )
+  saveSettings(settings)
+  refreshCapabilities(getCapabilityModelKey(), getCapabilityProvider())
+}
+
+/** Remove one field override at a scope, then re-resolve. */
+def removeCapabilityOverride(scopeKey: string, fieldKey: string) {
+  let settings = loadSettings()
+  settings.capabilities = removeCapabilityField(
+    getCapabilitySettings(settings),
+    scopeKey,
+    scopeTargetName(scopeKey),
+    fieldKey,
+  )
+  saveSettings(settings)
+  refreshCapabilities(getCapabilityModelKey(), getCapabilityProvider())
+}
+
+/** Ask which scope an override applies to. Returns "" on cancel. */
+def pickOverrideScope(): string {
+  let scopeItems: ChoiceItem[] = []
+  scopeItems.push({
+    key: "model",
+    label: "this model (${getCapabilityModelKey()})"
+  })
+  scopeItems.push({
+    key: "provider",
+    label: "this provider (${getCapabilityProvider()})"
+  })
+  scopeItems.push({
+    key: "global",
+    label: "all models"
+  })
+  const scopeKey = chooseOption("Scope", "Where should this apply?", scopeItems, allowCancel: true)
+  if (scopeKey == null) {
+    return ""
+  }
+  return scopeKey
+}
+
+/** Re-apply the resolved cap as the branch default. After a reset the
+  resolved value falls back to a built-in layer, which is always numeric
+  for known providers, so live-apply covers removal too. */
+def applyLiveMaxTokens() {
+  const capValue = getCapabilities().maxTokens
+  if (capValue != null) {
+    setLlmOptions({ maxTokens: capValue })
+  }
+}
+
+/** Positive-integer parse. parseInt and isNaN appear nowhere in the
+  repo's .agency code, so this uses a digits check instead. Returns -1
+  for anything that is not all digits. */
+def parsePositiveInt(text: string): number {
+  // Bound to a const because the parser rejects method calls on string
+  // LITERALS ("0123456789".includes(...) does not parse; a variable does).
+  const digits = "0123456789"
+  const trimmed = text.trim()
+  if (trimmed == "") {
+    return -1
+  }
+  for (ch in trimmed.split("")) {
+    if (!digits.includes(ch)) {
+      return -1
+    }
+  }
+  return Number(trimmed)
+}
+
+/** Interactive edit: field → value → scope → save → live-apply. */
+def editCapabilities() {
+  let fieldItems: ChoiceItem[] = []
+  for (field in CAPABILITY_FIELDS) {
+    fieldItems.push({
+      key: field.key,
+      label: "${field.label} — ${field.description}"
+    })
+  }
+  const fieldKey = chooseOption(
+    "Settings",
+    "Pick a setting to change (empty to exit).",
+    fieldItems,
+    allowCancel: true,
+  )
+  if (fieldKey == "" || fieldKey == null) {
+    return
+  }
+
+  let patch: CapabilityPatch = {}
+  if (fieldKey == "prompt") {
+    let promptItems: ChoiceItem[] = []
+    promptItems.push({
+      key: "large",
+      label: "large — full coordinator prompt"
+    })
+    promptItems.push({
+      key: "small",
+      label: "small — compact prompt for small-context models"
+    })
+    const picked = chooseOption("prompt", "System prompt size.", promptItems, allowCancel: true)
+    if (picked == "" || picked == null) {
+      return
+    }
+    patch = {
+      prompt: picked
+    }
+  }
+  if (fieldKey == "summarize" || fieldKey == "memory") {
+    let onOffItems: ChoiceItem[] = []
+    onOffItems.push({
+      key: "on",
+      label: "on"
+    })
+    onOffItems.push({
+      key: "off",
+      label: "off"
+    })
+    const picked = chooseOption(fieldKey, "Enable ${fieldKey}?", onOffItems, allowCancel: true)
+    if (picked == "" || picked == null) {
+      return
+    }
+    if (fieldKey == "summarize") {
+      patch = {
+        summarize: picked == "on"
+      }
+    } else {
+      patch = {
+        memory: picked == "on"
+      }
+      if (picked == "on") {
+        const status = embeddingKeyStatus(getResolvedSlots())
+        if (status.state == "key-missing") {
+          pushMessage(
+            color.red(
+            "Cannot enable memory: the embedding slot needs ${status.varName}, which is not set. Export it, or point the embedding slot elsewhere via /model.",
+          ),
+          )
+          return
+        }
+        if (status.state == "no-override" && providerLacksEmbeddings(getCapabilityProvider())) {
+          pushMessage(
+            color.dim(
+            "Note: ${getCapabilityProvider()} has no embeddings endpoint, so Tier-2 semantic recall stays off. Point the embedding slot at a provider that has one, e.g. /model embedding=openai/text-embedding-3-small.",
+          ),
+          )
+        }
+      }
+    }
+  }
+  if (fieldKey == "maxTokens") {
+    let capItems: ChoiceItem[] = []
+    capItems.push({
+      key: "reset",
+      label: "reset — remove my override, use the default"
+    })
+    const picked = chooseOption(
+      "maxTokens",
+      "Default output-token cap. Type a number, or pick reset.",
+      capItems,
+      allowFreeText: true,
+      allowCancel: true,
+    )
+    if (picked == "" || picked == null) {
+      return
+    }
+    if (picked == "reset") {
+      const scopeKey = pickOverrideScope()
+      if (scopeKey == "") {
+        return
+      }
+      removeCapabilityOverride(scopeKey, "maxTokens")
+      applyLiveMaxTokens()
+      pushMessage("Override removed.")
+      showCapabilities()
+      return
+    }
+    const parsed = parsePositiveInt(picked)
+    if (parsed <= 0) {
+      pushMessage(color.red("Not a positive number: ${picked}"))
+      return
+    }
+    patch = {
+      maxTokens: parsed
+    }
+  }
+
+  const scopeKey = pickOverrideScope()
+  if (scopeKey == "") {
+    return
+  }
+  saveCapabilityOverride(scopeKey, patch)
+
+  // Live-apply what can apply now; explain what can't.
+  if (fieldKey == "memory") {
+    if (getCapabilities().memory) {
+      // The ON direction cannot live-apply. enableAgentMemory's
+      // `with approve` cannot override the outer policy handler that
+      // startInteractive installed, so the memory-dir fs interrupts
+      // would surface as policy prompts mid-flow, or get denied and
+      // half-apply the toggle. The OFF direction stays live below:
+      // disableMemory raises no fs interrupts and already runs in-REPL
+      // from reactToSlotChange.
+      pushMessage(color.dim("Memory turns on at next agent start (enabling mid-session would raise policy prompts)."))
+    } else {
+      disableMemory() with approve
+    }
+  }
+  if (fieldKey == "maxTokens") {
+    applyLiveMaxTokens()
+  }
+  if (fieldKey == "prompt") {
+    pushMessage(color.dim("Prompt change applies on next agent start (this session's system message is already sent)."))
+  }
+  pushMessage("Saved.")
+  showCapabilities()
+}
+
 // Slash-command + user-message dispatcher invoked by `repl()` for
 // every Enter keystroke. Return `false` to terminate the loop.
 def _runTurn(msg: string): boolean {
@@ -493,10 +859,39 @@ def _runTurn(msg: string): boolean {
   }
   if (trimmed == "/help") {
     pushMessage(
-      "Commands: /exit, /clear, /clear-history, /cost, /model, /models, /local, /search, /paste, /help",
+      "Commands: /exit, /clear, /clear-history, /cost, /model, /models, /local, /search, /settings, /mcp, /paste, /help",
     )
     return true
   }
+  if (trimmed == "/settings") {
+    showCapabilities()
+    editCapabilities()
+    return true
+  }
+  if (trimmed == "/mcp") {
+    if (!isMcpAvailable()) {
+      pushMessage(color.yellow("MCP is not installed. Run: npm install @agency-lang/mcp"))
+      return true
+    }
+    const merged = mergeMcpServers(getMcpServers(loadSettings()), readProjectMcpConfig(cwd()))
+    if (keys(merged).length == 0) {
+      pushMessage(color.dim("No MCP servers configured. Add an mcpServers block to agency.json or settings.json."))
+      return true
+    }
+    pushMessage(color.bold("MCP servers:"))
+    for (name in keys(merged)) {
+      // mcpServerStatus is populated at session start. A server present in the
+      // config but absent from the status map was never loaded (e.g. /mcp run
+      // before startup finished) — show it as unknown rather than connected.
+      let status = mcpServerStatus[name]
+      if (status == null) {
+        status = "not loaded"
+      }
+      pushMessage("  ${name} — ${status}")
+    }
+    pushMessage(color.dim("Loaded ${mcpTools.length} MCP tool(s) this session."))
+    return true
+  }
   if (trimmed == "/search") {
     const opts = availableBackendItems()
     const choice = chooseOption(
@@ -661,7 +1056,7 @@ let first = true
 // subagent. Used to validate the flag and to dispatch in `agentReplyVia`.
 static const START_AGENTS = ["main", "code", "research", "oracle", "explorer", "review"]
 
-static const mainAgentSystemPrompt = """
+static const MAIN_PROMPT_LARGE = """
 You are the top-level coordinator of an Agency-language assistant. You
 receive every user message and decide how to respond.
 
@@ -830,6 +1225,41 @@ unless the user has clearly asked for an action ("do X", "fix Y",
 with them — don't sprint to implementation.
 """
 
+// Compact coordinator prompt for small-context models, ~350 tokens
+// instead of ~3,400. Selected when the capability profile says
+// prompt: "small". An 8K-context model loses 40% of its window to the
+// large prompt before the user types anything. The phrase "compact
+// coordinator" is a deliberate marker that verification greps for in
+// statelogs.
+static const MAIN_PROMPT_SMALL = """
+You are the compact coordinator of an Agency-language assistant. Decide
+how to answer each user message.
+
+Tools (each runs in its own context; pass a self-contained message):
+- `codeAgent(userMsg)` — anything touching code or files: read, write,
+  edit, run, typecheck. Also Agency syntax and CLI questions.
+- `researchAgent(userMsg)` — web search, URL fetches, external facts.
+- `reviewAgent(userMsg)` — check non-trivial new Agency code for
+  syntax and type errors; pass the code to review.
+- `oracleAgent(userMsg)` — deep reasoning on a hard question; include
+  all needed context in the message.
+- `explorerAgent(userMsg)` — broad read-only codebase/docs questions.
+- `generateImageFile(prompt, path, size, images)` — create or edit an
+  image; do not route image work to codeAgent.
+
+Routing rules:
+- Simple chat, greetings, quick factual answers: reply directly, no
+  tools.
+- Anything code- or file-related: codeAgent. Current/external info:
+  researchAgent. Broad "summarize/tour/how does X work" questions:
+  explorerAgent.
+- Surface tool results to the user concisely; do not re-run a tool the
+  user did not ask to re-run.
+
+Style: plain, direct answers in Markdown. No preamble. Keep replies
+short unless the task demands detail.
+"""
+
 // 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 /
@@ -902,19 +1332,101 @@ static const mainAgentTools = [
   generateImageFile,
 ]
 
+// MCP tools are appended to the coordinator's tools. ORDERING CONTRACT:
+// maybeLoadMcp (session start, in main()) must run before mainAgent's first
+// turn, or MCP tools silently vanish.
+let mcpTools: any[] = []
+// Per-server load outcome ("connected" / "unavailable"), for /mcp.
+let mcpServerStatus: Record<string, string> = {}
+
+export def setMcpTools(tools: any[]) {
+  mcpTools = tools
+}
+
+def setMcpServerStatus(status: Record<string, string>) {
+  mcpServerStatus = status
+}
+
+// MCP OAuth notification. The @agency-lang/mcp package opens the browser itself
+// (macOS-only today); we only print the URL so the user can complete auth.
+def onMcpOAuth(data: any) {
+  print(color.yellow("MCP authorization needed — opening browser. If it does not open, visit:\n${data.authUrl}"))
+}
+
+/** Load MCP tools from the project agency.json merged with the global settings
+  and hand them to the coordinator. No-op when @agency-lang/mcp is not installed
+  or no servers are configured. loadMcpTools warns-and-skips internally on any
+  per-server failure, so it always returns an array. */
+def maybeLoadMcp(settings: Settings) {
+  if (!isMcpAvailable()) {
+    return
+  }
+  const merged = mergeMcpServers(getMcpServers(settings), readProjectMcpConfig(cwd()))
+  if (keys(merged).length == 0) {
+    return
+  }
+  // Always returns a result (per-server failures warn-and-skip internally), so
+  // there is no Failure branch. The status map drives /mcp.
+  const loaded = loadMcpToolsWithStatus(merged, onMcpOAuth)
+  setMcpTools(loaded.tools)
+  setMcpServerStatus(loaded.status)
+}
+
+/** Enable memory when the capability profile allows it. When the user
+  pointed the embedding slot at a provider, embeddings run there. A
+  missing API key degrades to the default embedding behavior with one
+  notice. It never blocks startup. */
+// Whether startup actually enabled memory WITH the embedding override.
+// The pause guard in reactToSlotChange consults this instead of
+// re-deriving from the slots: a keyless override took the fallback path,
+// so memory runs on DERIVED embeddings and a main-provider change still
+// shifts the embedding space. Exported mutator so tests can drive the
+// guard directly.
+let _memoryEmbeddingsPinned = false
+
+export def markMemoryEmbeddingsPinned(pinned: boolean) {
+  _memoryEmbeddingsPinned = pinned
+}
+
+def maybeEnableMemory() {
+  const status = embeddingKeyStatus(getResolvedSlots())
+  const plan = memoryEnablePlan(getCapabilities().memory, status)
+  markMemoryEmbeddingsPinned(plan == "enable-override")
+  if (plan == "skip") {
+    return
+  }
+  if (plan == "enable-override") {
+    enableAgentMemory(status.override)
+    return
+  }
+  if (plan == "enable-fallback") {
+    print(
+      color.dim(
+      "Memory: the embedding slot needs ${status.varName}, which is not set. Falling back to the default embedding behavior.",
+    ),
+    )
+  }
+  enableAgentMemory()
+}
+
 def mainAgent(prompt: string | (string | Attachment)[]): string {
-  thread(label: "main", summarize: true, session: "main") {
+  const doSummarize = getCapabilities().summarize
+  thread(label: "main", summarize: doSummarize, 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}")
+      let sysPrompt = MAIN_PROMPT_LARGE
+      if (getCapabilities().prompt == "small") {
+        sysPrompt = MAIN_PROMPT_SMALL
+      }
+      systemMessage("${sysPrompt}${_context}")
       first = false
     }
     const result = llm(prompt, {
       memory: true,
-      tools: mainAgentTools
+      tools: [...mainAgentTools, ...mcpTools]
     })
   }
   return result
@@ -1259,6 +1771,10 @@ node main() {
         optional: true,
         description: "Approval policy for this run: a built-in name (minimal, recommended, with-writes, approve-all) or a path to a policy JSON file. with-writes auto-approves file writes and git changes scoped to the current directory and its children; approve-all approves EVERY interrupt with no scoping (sandbox use only). Overrides the saved policy without persisting it. Pass --policy with no value to list the built-in policies."
       },
+      "agent-home": {
+        type: "string",
+        description: "Directory to use instead of ~/.agency-agent for settings, policy, and history (equivalent to the AGENCY_AGENT_HOME env var; the flag wins when both are set)"
+      },
       local: {
         type: "string",
         optional: true,
@@ -1290,11 +1806,14 @@ node main() {
   },
   )
 
-  // NOTE: --trace / --log-file are declared here only for --help and so
-  // parseArgs accepts them. runBundledAgent extracts them from the forwarded
-  // args and passes them to this process as the AGENCY_CONFIG_OVERRIDES env
-  // var, read when the RuntimeContext is constructed — before this main() runs.
-  // Do not re-handle them here.
+  // NOTE: --trace / --log-file / --agent-home are declared here only for
+  // --help and so parseArgs accepts them. runBundledAgent extracts them from
+  // the forwarded args and passes them to this process via env vars
+  // (AGENCY_CONFIG_OVERRIDES for the first two, AGENCY_AGENT_HOME for the
+  // last), read before this main() runs — the RuntimeContext consumes the
+  // config overrides at construction, and lib/config.agency derives the
+  // settings/policy/history paths from the agent home in its static-const
+  // initializers. Do not re-handle them here.
 
   if (args.flags.debug) {
     AGENT_DEBUG = true
@@ -1359,9 +1878,6 @@ node main() {
     // 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
@@ -1370,6 +1886,7 @@ node main() {
     let modelGlobal = ""
     let fastFlag = ""
     let slowFlag = ""
+    let embeddingFlag = ""
     if (modelArg != "") {
       if (parsed.slot == "") {
         modelGlobal = parsed.model
@@ -1377,10 +1894,20 @@ node main() {
         fastFlag = parsed.model
       } else if (parsed.slot == "reasoning") {
         slowFlag = parsed.model
+      } else if (parsed.slot == "embedding") {
+        if (!embeddingSpecHasProvider(parsed.model)) {
+          print(
+            color.red(
+            "Embedding models need the provider/model form, e.g. --model embedding=openai/text-embedding-3-small.",
+          ),
+          )
+          process.exit(1)
+        }
+        embeddingFlag = parsed.model
       } else {
         print(
           color.red(
-          "Unknown model slot '${parsed.slot}' in --model. Valid slots: main, reasoning.",
+          "Unknown model slot '${parsed.slot}' in --model. Valid slots: ${SLOTS.join(", ")}.",
         ),
         )
         process.exit(1)
@@ -1394,16 +1921,18 @@ node main() {
     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()
+    configureModels(modelGlobal, fastFlag, slowFlag, embeddingFlag, args.flags.provider ?? "")
     configureSearch(false)
   }
 
+  // Persistent knowledge graph, gated on the capability profile. Must run
+  // before any handler/REPL is installed.
+  maybeEnableMemory()
+
+  // Connect configured MCP servers and hand their (policy-gated) tools to the
+  // coordinator. Must run before the first turn (mcpTools ordering contract).
+  maybeLoadMcp(loadSettings())
+
   // 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.
@@ -1434,20 +1963,15 @@ node main() {
     setLlmOptions({ maxToolResultChars: maxResultChars })
   }
 
-  // TEMPORARY: raise the per-turn output cap above smoltalk's 4096 default.
-  // With adaptive thinking on, a hard reasoning turn can spend the entire
-  // 4096-token budget thinking and return an empty reply (no text, no tool
-  // call) — see the empty-output failures on regex-log / protein-assembly.
-  // Capped at 20000: these llm() calls are non-streaming, and the Anthropic
-  // SDK refuses a non-streaming request whose estimated time exceeds 10 min,
-  // which is maxTokens > 21333 (60min * maxTokens / 128000 > 10min). 20000
-  // stays under that and is well within every modern-Claude output cap
-  // (Sonnet 5 = 64K, Opus 4.8 = 128K). Branch-scoped so every subagent
-  // inherits it; per-call `llm(..., { maxTokens })` (e.g. the summarizer's
-  // cap) still wins. Superseded by the declarative capabilities table in
-  // docs/superpowers/specs/2026-07-09-model-capabilities-design.md (§2,
-  // maxTokens applied via setLlmOptions at startup) — remove it then.
-  setLlmOptions({ maxTokens: 20000 })
+  // Per-model default output cap from the capability profile. The hosted
+  // default of 20000 carries the adaptive-thinking empty-reply fix that
+  // used to live here as a TEMPORARY block. Local profiles cap lower.
+  // Branch-scoped, so every subagent inherits it. A per-call
+  // llm(..., { maxTokens }) still wins, e.g. the summarizer's 256.
+  const capsMaxTokens = getCapabilities().maxTokens
+  if (capsMaxTokens != null) {
+    setLlmOptions({ maxTokens: capsMaxTokens })
+  }
 
   // One-shot autonomy: tell the code subagent there is no human to answer
   // questions and no next turn, so it must drive to a finished artifact.