agency-lang 0.3.0 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@ Agency is a language for building agents that compiles to TypeScript.
 ## Installation
 
 ```bash
-npm install agency-lang zod
+pnpm install agency-lang
 ```
 
 ## Quick Start
@@ -31,5 +31,7 @@ Now read [the docs](https://agency-lang.com) to learn more about the language an
 
 Weather data in the standard library (`std::weather`) is provided by [Open-Meteo](https://open-meteo.com/). Data is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). The free API is for non-commercial use only; commercial use requires a [paid subscription](https://open-meteo.com/en/pricing).
 
+The bundled agent's coding workflow skills (brainstorming, writing-plans, executing-plans, TDD, systematic debugging, verification-before-completion) are vendored from the [Superpowers](https://github.com/obra/superpowers) plugin by Jesse Vincent, used under the MIT license. See `lib/agents/agency-agent/skills/superpowers/ATTRIBUTION.txt`.
+
 ## License
 MIT. See [LICENSE](./LICENSE).

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

@@ -1,199 +1,319 @@
-import { addTask, listTasks, markTaskDone } from "./subagents/task.agency"
-import { writeToPlan, readPlan } from "./subagents/plan.agency"
-import { writeCode, appendCode, readCode } from "./subagents/code.agency"
-import { syntaxHighlight } from "../../utils/agentUtils.js"
-import { systemMessage } from "std::thread"
-// todo allow this
-// import { Plan } from "./subagents/plan.agency"
-
-systemPrompt = read("./prompts/system.md")
-planPrompt = read("./prompts/plan.md")
-
-type Mode = "create" | "modify"
-type NextAction = { type: "askUser"; question: string } | { type: "done" } | { type: "start" }
-
-strategy = { 
-  type: "race",
-  params: { 
-    strategies: [
-      { 
-      type: "fallback",
-      params: { 
-        strategies: ["gemini-2.5-flash", "gemini-2.5-pro"],
-        config: { 
-          fallbackOn: ["error"]
-        }
-      }
-    },
-      { 
-      type: "fallback",
-      params: { 
-        strategies: ["gemini-2.5-flash-lite", "gemini-2.5-pro"],
-        config: { 
-          fallbackOn: ["error"]
-        }
-      }
-    }
-    ]
-  }
+import { route } from "std::agent"
+import { clearMessages, pushMessage, repl } from "std::cli"
+import { today } from "std::date"
+import { box, render } from "std::layout"
+import { ScopedRuleFields, cliPolicyHandler } from "std::policy"
+import { exists } from "std::shell"
+import { highlight } from "std::syntax"
+import { cwd, env } from "std::system"
+import { getCost } from "std::thread"
+
+import { codeSysPrompt, codeTools } from "./code.agency"
+import { figs, title } from "./images/images.agency"
+import { researchSysPrompt, researchTools } from "./research.agency"
+
+
+// UI mode select — one-line swap between the alt-screen TUI and the
+// line-mode REPL. Both modules expose the same `repl` / `pushMessage`
+// / `clearMessages` surface (line mode re-exports `pushMessage` and
+// `clearMessages` from `std::ui`). Trial both and decide. See
+// `docs/superpowers/ideas/2026-06-02-line-mode-agent.md`.
+//
+//import { clearMessages, pushMessage, repl } from "std::ui"
+
+/*
+ * Agency Agent — helps users create and modify Agency code.
+ *
+ * Multi-thread architecture: the agent splits work across two
+ * specialists, each with its own thread / system prompt / tool set:
+ *   - `code.agency`     — writes, edits, typechecks, runs code
+ *   - `research.agency` — looks up docs, fetches URLs, browses web
+ *
+ * The standard library does the heavy lifting:
+ *   - `std::agent.route` runs the per-turn hop loop, owns the
+ *     handoff signal, and force-answers when the hop limit is hit.
+ *   - `std::policy.cliPolicyHandler` provides the interactive
+ *     approve/reject/always menu and persists "always" decisions to
+ *     `~/.agency-agent/policy.json`.
+ *   - `std::ui.repl` provides the terminal UI: a bordered scroll
+ *     output area, status line (cost + label), command palette
+ *     opened with `/`, and history-aware input bar.
+ *
+ * This file's responsibilities collapse to:
+ *   1. Per-turn callback (`_runTurn`) wiring the user message into
+ *      route() and printing the reply into the scroll output.
+ *   2. Per-kind ALWAYS_FIELDS map for the policy handler's
+ *      "approve-always-here" option.
+ *   3. Wire the two specialists into one `RouterConfig`.
+ *
+ * Other features:
+ * - Doc-as-skills: bundles `docs/site/guide` etc. (copied to
+ *   `dist/lib/agents/docs/` at build time, see makefile) and
+ *   exposes each Markdown file as a skill the research agent can
+ *   read on demand.
+ * - Typechecking: the code agent can call `typecheck` on any
+ *   source it generates to verify the code before showing it.
+ * - File I/O tools: `read`, `write`, `edit` for actually creating /
+ *   editing `.agency` files.
+ */
+
+// Verbose tool-call tracing, opt-in via `AGENT_DEBUG=1`.
+const AGENT_DEBUG = env("AGENT_DEBUG") == "1"
+
+callback("onToolCallStart") as data {
+  //if (AGENT_DEBUG) {
+  pushMessage(color.yellow("⏺ ${data.toolName}(${formatArgs(data.args)})"))
+  //}
 }
 
-config = { 
-  strategy: strategy,
-  responseFormatOptions: { 
-    strict: true,
-    numRetries: 2,
-    allowExtraKeys: true
+def truncate(str: string, maxLength: number): string {
+  if (str.length <= maxLength) {
+    return str
   }
+  return str.slice(0, maxLength) + "..."
 }
-/* config = {
-model: {
-optimizeFor: ["reasoning", "speed", "cost"],
-providers: ["openai", "google"],
-limit: {
-cost: 40
+
+def formatArgs(args: Record<string, any>): string {
+  const parts = []
+  for (key in args) {
+    const value = args[key]
+    parts.push("${key}: ${truncate(JSON.stringify(value), 50)}")
+  }
+  return parts.join(", ")
 }
-},
-responseFormatOptions: {
-strict: true
+
+callback("onToolCallEnd") as data {
+  if (AGENT_DEBUG) {
+    pushMessage(
+      color.yellow(
+      "tool return: ${data.toolName} -> ${JSON.stringify(data.result)} ${data.timeTaken}ms",
+    ),
+    )
+  }
 }
-} */
 
-def printCode(code: string): string {
-  """
-  Use this tool to print code to the terminal with syntax highlighting.
-  Use this to print any generated code you want the user to look at.
-  """
-  print(syntaxHighlight(code, "ts"))
-  return "printed code successfully"
+// On-disk policy at `$HOME/.agency-agent/policy.json`. We duplicate the
+// home-dir computation here instead of importing `AGENCY_AGENT_DIR` from
+// `shared.agency` because Agency doesn't guarantee imported static-const
+// init runs before the importer reads it (upstream #232).
+const POLICY_FILE = "policy.json"
+const HISTORY_FILE = "history"
+
+def policyDir(): string {
+  const home = env("HOME")
+  if (home == null) {
+    return "./.agency-agent"
+  }
+  return "${home}/.agency-agent"
 }
 
-def writeCodeWithConfirm(filename: string, content: string): string {
-  """
-  Use this tool to write code to a file to the filesystem. The filename should include the path and extension (e.g., 'lib/agents/myAgent.agency').
-  """
-  print(color.yellow())
-  message = "\nYou're about to write to the file ${filename} with the following content\n\n"
-  return interrupt({ 
-    tool: "writeCodeWithConfirm",
-    message: message,
-    content: content
-  })
-  write(filename, content)
+def policyPath(): string {
+  return "${policyDir()}/${POLICY_FILE}"
 }
 
-node main() {
-  print(color.cyan("Welcome to the Agency Agent!"))
-  print(color.cyan("Would you like to create a new agent or modify an existing one?"))
-  userinput = input("(create/modify) ")
-  thread {
-    mode: Mode = llm("categorize this user response as 'create' or 'modify': ${userinput}", config)
-  }
-  print(color.cyan("Great! Let's ${mode} an agent."))
-  match(mode) {
-    "create" => return plan("create", "", null)
-    "modify" => return readExisting()
-  }
+def historyPath(): string {
+  return "${policyDir()}/${HISTORY_FILE}"
 }
 
-node readExisting() {
-  filepath = input("Enter the path to the .agency file you want to modify: ")
-  existingCode = read(filepath)
-  print(color.cyan("Here's the existing code:"))
-  printCode(existingCode)
-  return plan("modify", existingCode, filepath)
+// Per-kind config driving the "approve-always-here" option. For each
+// kind we list the data fields the scoped rule should pin, plus a
+// flag that turns a directory value into a brace-expanded glob so the
+// rule matches `dir` AND `dir/**`. Kinds not present in this map
+// don't offer the option — the user falls back to (a)/(r)/(aa)/(rr).
+const ALWAYS_FIELDS: ScopedRuleFields = {
+  "std::read": [{
+    field: "dir",
+    matchSubpaths: true
+  }],
+  "std::write": [{
+    field: "dir",
+    matchSubpaths: true
+  }],
+  "std::edit": [{
+    field: "dir",
+    matchSubpaths: true
+  }],
+  "std::ls": [{
+    field: "dir",
+    matchSubpaths: true
+  }],
+  "std::glob": [{
+    field: "dir",
+    matchSubpaths: true
+  }],
+  "std::grep": [{
+    field: "dir",
+    matchSubpaths: true
+  }],
+  "std::copy": [
+    {
+    field: "src",
+    matchSubpaths: true
+  },
+    {
+    field: "dest",
+    matchSubpaths: true
+  },
+  ],
+  "std::move": [
+    {
+    field: "src",
+    matchSubpaths: true
+  },
+    {
+    field: "dest",
+    matchSubpaths: true
+  },
+  ],
+  "std::exec": [
+    {
+    field: "command",
+    matchSubpaths: false
+  },
+    {
+    field: "subcommand",
+    matchSubpaths: false
+  },
+  ]
 }
 
-node printSample() {
-  codeSample = read("./prompts/codeSample.agency")
-  print(color.cyan("Here's a sample of how you might structure your code in the agency language:"))
-  printCode(codeSample)
+def loadAgentsMd(dir: string): string {
+  """
+  Read `AGENTS.md` from `dir` if it exists and return it wrapped in a
+  <project_context> block ready to splice into a system prompt. Returns
+  an empty string if there is no AGENTS.md or it cannot be read. The
+  read is auto-approved — the user implicitly opted in to scanning the
+  project directory by running the agent there.
+  """
+  if (!exists("AGENTS.md", dir)) {
+    return ""
+  }
+  const result = read("AGENTS.md", dir) with approve
+  if (isFailure(result)) {
+    return ""
+  }
+  return "\n\n<project_context>\n${result.value}\n</project_context>"
 }
 
-node plan(mode, existingCode, existingFilename: string | null) {
-  print(color.cyan("Let's start by coming up with a plan for what you want to accomplish."))
-  modeContext = ""
-  if (mode == "modify") {
-    modeContext = """
-    You are in MODIFY mode. The user has an existing agent they want to modify. Here is the existing code:
-    
-    ```
-    ${existingCode}
-    ```
-    
-    Focus on understanding what changes the user wants to make to this existing agent.
-    """
+// Per-turn grounding context. Captured at startup and re-used so the
+// LLM doesn't have to re-ground each turn. Initialized in `main()`.
+let _context: string = ""
+
+// Slash-command + user-message dispatcher invoked by `repl()` for
+// every Enter keystroke. Return `false` to terminate the loop.
+def _runTurn(msg: string): boolean {
+  if (msg == "") {
+    return true
   }
-  thread {
-    systemMessage("${systemPrompt}\n\n${planPrompt}${modeContext}")
-    userMsg = input("What would you like to accomplish today? ")
-    nextAction: NextAction = { 
-      type: "start"
-    }
-    while (nextAction.type != "done") {
-      nextAction: NextAction = llm("${userMsg}", { ...config, tools: [writeToPlan, readPlan, print] })
-      if (nextAction.type == "askUser") {
-        userMsg = input("${nextAction.question} ")
+  if (msg == "/exit" || msg == "/quit") {
+    return false
+  }
+  if (msg == "/clear") {
+    clearMessages()
+    return true
+  }
+  if (msg == "/help") {
+    pushMessage("Commands: /exit, /clear, /help")
+    return true
+  }
+  const reply = route(
+    {
+    start: "code",
+    agents: {
+      code: {
+        systemPrompt: codeSysPrompt,
+        tools: codeTools,
+        memory: true
+      },
+      research: {
+        systemPrompt: researchSysPrompt,
+        tools: researchTools,
+        memory: true
       }
-    }
+    },
+    maxHops: 3,
+    context: _context
+  },
+    msg,
+  )
+  pushMessage(highlight("${reply}\n", language: "markdown"))
+  return true
+}
+
+def roundedCost(): string {
+  return "$${getCost().toFixed(4)}"
+}
 
-    plan = readPlan()
-    print(color.cyan("Here's the plan we've come up with"))
-    printJSON(plan)
+def _buildStatus(): { left: string; right: string; context: string } {
+  return {
+    left: "",
+    right: roundedCost(),
+    context: ""
   }
-  return design(plan, mode, existingCode, existingFilename)
 }
 
-type Plan = {
-  overallGoal: string;
-  desiredActions: string[] # array of descriptions of each action
+def sample(arr: any[]): any {
+  return arr[Math.floor(Math.random() * arr.length)]
 }
 
-type DesignAction = { type: "askUser"; question: string } | { type: "done"; finalCode: string; filename: string } | { type: "start" }
-
-node design(plan, mode, existingCode, existingFilename: string | null) {
-  designPrompt = read("./prompts/design.md")
-  prompt = ""
-  if (mode == "modify") {
-    print(color.cyan("Now let's modify the existing agent based on the plan."))
-    prompt = """
-    You are in MODIFY mode. Here is the existing agent code:
-    
-    ```
-    ${existingCode}
-    ```
-    
-    The user wants to make the following modifications:
-    Goal: ${plan.overallGoal}
-    Desired changes: ${plan.desiredActions}
-    
-    Modify the existing code to accomplish these changes. Preserve the existing style and structure where possible.
-    """
-  } else {
-    print(color.cyan("Now let's design an agent to accomplish that plan."))
-    prompt = """
-    Help the user design an agent that can accomplish the following goal: ${plan.overallGoal}
-    with the following actions: ${plan.desiredActions}.
-    """
-  }
-  thread {
-    systemMessage(designPrompt)
-    userMsg = prompt
-    nextAction: DesignAction = { 
-      type: "start"
-    }
-    i = 0
-    while (nextAction.type != "done") {
-      i += 1
-      print(color.blue("Design iteration ${i}"))
-      nextAction: DesignAction = llm("${userMsg}", config)
-      if (nextAction.type == "askUser") {
-        userMsg = input("\n${nextAction.question} ")
+def printHeader() {
+  const fig = sample(figs)
+  const data = box(title: "Agency", padding: 1, borderColor: "cyan", titleColor: "cyan") as b {
+    b.row(gap: 1) as r {
+      r.column() as left {
+        left.text("Welcome to the Agency Agent!", bold: true)
+        left.text("Ask me to write code, look up docs, or just chat.")
+        left.hline()
+        left.text("Getting Started", bold: true, fgColor: "cyan")
+        left.text("/help for commands · /exit to quit", dim: true)
+      }
+      r.vline()
+      r.column() as right {
+        right.raw(fig)
       }
     }
   }
-  print(color.green("Great! We've designed the agent. Now let's write the code for it."))
-  printJSON(color.magenta(nextAction))
-  nextAction.filename = nextAction.filename || "agent.agency"
-  writeCodeWithConfirm(existingFilename || nextAction.filename, nextAction.finalCode)
-}
+  print(render(data, color: true))
+}
+
+node main() {
+  printHeader()
+
+  // Grounding: the LLM should not have to ask the user where it is
+  // or what day it is. Both are appended once per run so they ride
+  // with the first system message in each specialist's thread.
+  //
+  // Project context: if the user keeps an AGENTS.md at the workspace
+  // root (Anthropic / Pi / Aider all read it), inline it so the LLM
+  // automatically follows the project's conventions.
+  const projectContext = loadAgentsMd(cwd()) with approve
+  _context = "\n\nCurrent date: ${today()}\nCurrent working directory: ${cwd()}${projectContext}"
+
+  // Bind the handler to a local var so `with handler` parses (the
+  // `with` clause only accepts an identifier, not a call expression).
+  const handler = cliPolicyHandler({
+    file: policyPath(),
+    fields: ALWAYS_FIELDS
+  })
+
+  // The `repl()` widget owns the runloop; every Enter dispatches into
+  // `_runTurn` which calls `route()`. Interrupts raised inside
+  // route() propagate to the policy handler installed by the enclosing
+  // `handle` block via the AsyncLocalStorage handler stack.
+  handle {
+    repl(
+      status: _buildStatus,
+      onSubmit: _runTurn,
+      prompt: "> ",
+      historyFile: historyPath(),
+      historyMax: 1000,
+      paletteCommands: {
+      "/exit": "Exit the agent",
+      "/clear": "Clear the conversation transcript",
+      "/help": "Show available slash commands"
+    },
+    )
+  } with handler
+
+  print(color.cyan("\nGoodbye!"))
+}