@capagents/forgeqe 1.3.2 → 2.0.1

package/skills/testcontainers/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: testcontainers
+description: "Use when a test needs a real database, queue, cache or other service, or when the repository already uses Testcontainers (Java org.testcontainers, .NET Testcontainers, Node testcontainers, Python testcontainers, Go testcontainers-go): starting the service from the test itself with a pinned image, waiting until it is ready, wiring its address into the app under test, sharing one container across tests, and cleaning up."
+agents: [scribe]
+---
+
+# Testcontainers
+
+## Read the setup first
+- **Find what the repository already uses.** Look for the library in the build file:
+  - `pom.xml` or `build.gradle`: `org.testcontainers`
+  - `.csproj`: `Testcontainers.*`
+  - `package.json`: `testcontainers` or `@testcontainers/*`
+  - `pyproject.toml` or `requirements*.txt`: `testcontainers`
+  - `go.mod`: `github.com/testcontainers/testcontainers-go`
+
+  Then find its existing containers: a base class, a fixture, `@Testcontainers`/`@Container`, an `IAsyncLifetime` or `[OneTimeSetUp]`, a Jest `globalSetup`, or a pytest fixture with `scope="session"`. Reuse them. Never start a second container for a service a fixture already gives.
+- **Use the repository's own modules** (`PostgreSQLContainer`, `PostgreSqlBuilder`, `PostgreSqlContainer`, `RedisContainer`, `KafkaContainer`) over a generic container. Use a generic one only when no module exists.
+- **Adding the library:** only when the test needs a real service and nothing in the repository gives one. Pin the version the build file uses for its other test dependencies, or the latest release. Then say so in your summary.
+
+## Images
+- Pin every image to an exact version: `postgres:16.4`, `redis:7.4.1`, `confluentinc/cp-kafka:7.7.1`. Never `latest` or no tag.
+- Use the version the app runs in production when the repository says it (`docker-compose.yml`, deployment files, a README). Otherwise use the newest version of the major the app's driver supports.
+
+## Ready and addresses
+- **Wait for readiness the module's way, or with an explicit wait strategy:** a log line, a health check, or an HTTP path answering 200. Never sleep for a fixed time.
+- **Use the mapped port and host the library gives** (`getMappedPort`, `GetMappedPublicPort`, `getPort()`, `get_exposed_port`, `container.Host`). Never assume a fixed port of this machine: tests run in parallel and on CI.
+- **Hand the address to the app under test** through its own configuration: the connection string or URL setting it already reads. In Spring, use `@DynamicPropertySource` or `@ServiceConnection`. In ASP.NET, use `WebApplicationFactory` with `ConfigureAppConfiguration`. Elsewhere, set an environment variable before the app starts.
+- **Seed data** with the repository's migrations or seed scripts (`withInitScript`, `WithResourceMapping`, running the migration tool against the container). Don't use SQL copied into the test when the repository has migrations.
+
+## Lifetime and speed
+- **Start one container per test class or test session**, not per test, unless tests must not share data. Reset data between tests the way the repository does: transactions rolled back, truncating tables, or a fresh schema.
+- **Leave cleanup to the library** (Ryuk, `await using`, `@Container`, a fixture's teardown). Never call `docker` from a test, and never run `docker rm`.
+
+## What a test must not do
+- **No privileged containers**, host networking (`withNetworkMode("host")`, `NetworkMode = host`), mounting the Docker socket into a container, or `withPrivilegedMode`.
+- **No real credentials.** Use the module's defaults or fixed test values. A secret the app needs comes from the environment the test reads already.
+- **No containers for things the test doesn't use.** A unit test stays a unit test.
+
+## Run one test
+- Docker must be running on the machine, or in CI with the runner's Docker. Run the one test as the repository's own instructions say (`mvn -Dtest=OrderRepositoryIT test`, `dotnet test --filter FullyQualifiedName~OrderRepositoryTests`, `npx jest orders.int.test.ts`, `pytest tests/test_orders.py -k create`, `go test ./... -run TestOrders`).
+- The first run pulls the images, so allow for a slow first run before you judge a timeout.

package/src/agents.ts

@@ -19,12 +19,21 @@ export type AgentEntry = {
   skills?: SkillAgent
   /** Where the code defines it. */
   defined: string
-  /** Most tokens its fixed context (system prompt, and for ForgeQE's agent its tool list) may take. */
+  /**
+   * Most tokens its fixed context may take: the system prompt, and for ForgeQE's agent the capability index and the
+   * core capabilities' tools; each other capability is held to CAPABILITY_TOOL_BUDGET.
+   */
   budget: number
 }
 
+/**
+ * Most tokens one capability's tool definitions may take: a turn of ForgeQE's agent carries the core and the tools of
+ * the capabilities it picks (src/mcp/scope.ts), so each capability, not the whole list, is what has to stay small.
+ */
+export const CAPABILITY_TOOL_BUDGET = 2500
+
 export const AGENTS: AgentEntry[] = [
-  { name: "forgeqe", title: "ForgeQE's agent (shell, forgeqe run, forgeqe mcp)", kind: "agent-runtime", prompts: ["brain"], skills: "forgeqe", defined: "src/brain/index.ts", budget: 26000 },
+  { name: "forgeqe", title: "ForgeQE's agent (shell, forgeqe run, forgeqe mcp)", kind: "agent-runtime", prompts: ["brain"], skills: "forgeqe", defined: "src/brain/index.ts", budget: 10000 },
   { name: "forgeqe-test", title: "Scribe: writes a test from a verified run", kind: "agent-runtime", prompts: ["test-agent"], skills: "scribe", defined: "src/code/runtime.ts", budget: 4900 },
   { name: "forgeqe-read", title: "Scribe, reading the repository before the run arrives", kind: "agent-runtime", prompts: ["test-agent"], skills: "scribe", defined: "src/code/runtime.ts", budget: 4900 },
   { name: "forgeqe-review", title: "Reviewer of Scribe's tests", kind: "agent-runtime", prompts: ["test-reviewer"], skills: "scribe", defined: "src/code/review.ts", budget: 4900 },

package/src/api/plan.ts

@@ -9,6 +9,7 @@ import { knowledgeBlock, readKnowledge, relevantKnowledge } from "../knowledge.t
 import type { Contract, ContractSet, KeyField, Scenario, ScenarioStep } from "./types.ts"
 import { prompt } from "../prompts.ts"
 import { domainNotes } from "../domain.ts"
+import { guardrailsNotes } from "../guardrails.ts"
 
 /**
  * Scenarios planned by a model from test cases (Azure DevOps, Jira, Xray, TestRail, files) or plain English, against
@@ -221,6 +222,7 @@ export async function planScenarios(opts: {
     repo: opts.cwd,
     profile: opts.config.llm,
     domain: domainNotes(opts.config),
+    guardrails: guardrailsNotes(opts.config),
     model: opts.config.code.model,
     bin: opts.config.code.opencode,
     readDirs: [opts.cwd],

package/src/api/write.ts

@@ -17,6 +17,7 @@ import { briefMarkdown, scenarioMarkdown } from "./store.ts"
 import type { ContractSet, Scenario } from "./types.ts"
 import { prompt } from "../prompts.ts"
 import { domainNotes } from "../domain.ts"
+import { guardrailsNotes } from "../guardrails.ts"
 
 /**
  * The coding agent writes API and contract tests for a contract set in the repository's own framework, and ForgeQE
@@ -157,6 +158,7 @@ export async function writeApiTests(opts: {
     repo,
     profile: config.llm,
     domain: domainNotes(config),
+    guardrails: guardrailsNotes(config),
     model: config.code.model,
     bin: config.code.opencode,
     readDirs: [repo, opts.setDir],

package/src/auth/copilot.ts

@@ -0,0 +1,130 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+import { createOpencodeClient } from "@opencode-ai/sdk/v2"
+
+import { allowListEnv } from "../childEnv.ts"
+import { startServer } from "../code/runtime.ts"
+import { COPILOT_PROVIDER_ID, parseCopilotAuth, type CopilotAuth } from "../copilot.ts"
+
+/**
+ * The GitHub Copilot device sign-in, run by the agent runtime's own Copilot provider (the sign-in GitHub supports for
+ * it). The runtime runs in a throwaway folder, so its auth.json exists only until the sign-in is read back and moved
+ * to ForgeQE's credential store.
+ */
+
+export type DeviceLoginIO = {
+  /** The one-time code and the page to enter it on. */
+  showCode(code: string, url: string): void
+  signal?: AbortSignal
+}
+
+/** How long GitHub's device codes stay valid. */
+const DEVICE_CODE_MS = 15 * 60_000
+
+/** The page GitHub asks the user to enter the code on, when it is GitHub's own (or the enterprise host's) https page. */
+export function verificationUrl(raw: string, enterprise?: string): string | null {
+  let u: URL
+  try {
+    u = new URL(raw)
+  } catch {
+    return null
+  }
+  if (u.protocol !== "https:" || u.username || u.password || u.port) return null
+  return u.hostname === (enterprise || "github.com") ? u.toString() : null
+}
+
+/** "Enter code: ABCD-1234" → "ABCD-1234". */
+export function userCode(instructions: string): string | null {
+  return /\b([A-Z0-9]{4}-[A-Z0-9]{4})\b/.exec(instructions || "")?.[1] || null
+}
+
+const message = (error: unknown) => {
+  const e = error as { data?: { message?: string }; name?: string } | undefined
+  return e?.data?.message || e?.name || "no reason given"
+}
+
+/**
+ * Sign in to GitHub Copilot with the device flow: GitHub.com, or `enterprise` (a GitHub Enterprise host such as
+ * acme.ghe.com). Returns the sign-in and the Copilot models it can use.
+ */
+export async function copilotDeviceLogin(bin: string, io: DeviceLoginIO, enterprise?: string): Promise<{ auth: CopilotAuth; models: string[] }> {
+  const dir = mkdtempSync(path.join(os.tmpdir(), "forgeqe-copilot-"))
+  const sub = (name: string) => {
+    const p = path.join(dir, name)
+    mkdirSync(p, { recursive: true, mode: 0o700 })
+    return p
+  }
+  const env = {
+    ...allowListEnv(process.env, []),
+    XDG_DATA_HOME: sub("data"),
+    XDG_CONFIG_HOME: sub("config"),
+    XDG_STATE_HOME: sub("state"),
+    OPENCODE_DISABLE_PROJECT_CONFIG: "1",
+    OPENCODE_CONFIG_CONTENT: JSON.stringify({ $schema: "https://opencode.ai/config.json", share: "disabled", autoupdate: false }),
+  }
+  let server: { url: string; close(): void } | null = null
+  try {
+    server = await startServer(bin, env, 60_000)
+    const client = createOpencodeClient({ baseUrl: server.url, directory: dir })
+    const methods = (await client.provider.auth()).data?.[COPILOT_PROVIDER_ID] || []
+    const method = methods.findIndex((m) => m.type === "oauth")
+    if (method < 0) throw new Error("This agent runtime has no GitHub Copilot sign-in. Run forgeqe setup to install the version ForgeQE pins.")
+    const inputs: Record<string, string> = enterprise ? { deploymentType: "enterprise", enterpriseUrl: enterprise } : { deploymentType: "github.com" }
+    const started = await client.provider.oauth.authorize({ providerID: COPILOT_PROVIDER_ID, method, inputs })
+    if (!started.data) throw new Error(`GitHub did not start the sign-in: ${message(started.error)}`)
+    const url = verificationUrl(started.data.url, enterprise)
+    const code = userCode(started.data.instructions)
+    if (!url || !code) throw new Error("The agent runtime's sign-in did not give a GitHub page and one-time code.")
+    io.showCode(code, url)
+
+    // The callback returns once GitHub has the code entered (or the code expires); a stop gives up waiting.
+    const waited = await new Promise<{ ok: boolean; why?: string }>((resolve) => {
+      const timer = setTimeout(() => resolve({ ok: false, why: "The one-time code expired before it was entered." }), DEVICE_CODE_MS)
+      const stop = () => resolve({ ok: false, why: "Cancelled." })
+      io.signal?.addEventListener("abort", stop, { once: true })
+      client.provider.oauth
+        .callback({ providerID: COPILOT_PROVIDER_ID, method })
+        .then((r) => resolve(r.error ? { ok: false, why: `GitHub did not finish the sign-in: ${message(r.error)}` } : { ok: true }))
+        .catch((err) => resolve({ ok: false, why: `GitHub did not finish the sign-in: ${(err as Error).message}` }))
+        .finally(() => {
+          clearTimeout(timer)
+          io.signal?.removeEventListener("abort", stop)
+        })
+    })
+    if (!waited.ok) throw new Error(waited.why)
+
+    let saved: unknown
+    try {
+      saved = (JSON.parse(readFileSync(path.join(env.XDG_DATA_HOME, "opencode", "auth.json"), "utf8")) as Record<string, unknown>)[COPILOT_PROVIDER_ID]
+    } catch {}
+    const auth = parseCopilotAuth(saved)
+    if (!auth) throw new Error("The agent runtime did not save a GitHub Copilot sign-in.")
+    if ((auth.enterpriseUrl || undefined) !== enterprise) throw new Error("The Copilot sign-in is for a different GitHub than the one chosen.")
+
+    let models: string[] = []
+    try {
+      const list = (await client.provider.list()).data
+      const copilot = list?.all?.find((p) => p.id === COPILOT_PROVIDER_ID)
+      models = Object.keys(copilot?.models || {}).sort()
+    } catch {}
+    return { auth, models }
+  } finally {
+    server?.close()
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+/** The GitHub account a Copilot sign-in belongs to, or undefined when GitHub does not say. */
+export async function copilotAccount(auth: CopilotAuth, fetchImpl: typeof fetch = fetch): Promise<string | undefined> {
+  const api = auth.enterpriseUrl ? `https://api.${auth.enterpriseUrl}` : "https://api.github.com"
+  try {
+    const res = await fetchImpl(`${api}/user`, { headers: { Accept: "application/vnd.github+json", Authorization: `Bearer ${auth.refresh}` }, signal: AbortSignal.timeout(10_000) })
+    if (!res.ok) return undefined
+    const login = ((await res.json()) as { login?: unknown }).login
+    return typeof login === "string" && /^[A-Za-z0-9-]{1,39}$/.test(login) ? login : undefined
+  } catch {
+    return undefined
+  }
+}

package/src/auth/signin.ts

@@ -1,10 +1,14 @@
 import { spawn, spawnSync } from "node:child_process"
 
 import { azCliAuth, resetAzCliAuth } from "../cases/ado.ts"
+import { ghAuthToken } from "../cases/github.ts"
+import { ensureOpencode, INSTALL_HINT } from "../code/runtime.ts"
+import { COPILOT_AUTH_ENV, enterpriseHost, parseCopilotAuth, runtimeHasCopilot } from "../copilot.ts"
 import { basic, http } from "../cases/http.ts"
 import type { AppConfig } from "../config.ts"
 import type { AskQuestion } from "../mcp/tools.ts"
 import { withoutTelemetry } from "../privacy.ts"
+import { copilotAccount, copilotDeviceLogin } from "./copilot.ts"
 import { forgetSystem, fromSaved, readIndex, savedSecrets, saveSystem, storeName, type Via } from "./store.ts"
 
 /** How a sign-in talks to the user: the terminal (`forgeqe auth`) or the shell's dialogs (/auth). */
@@ -19,11 +23,12 @@ export type AuthIO = {
   signal?: AbortSignal
 }
 
-export type SystemId = "azure_devops" | "github" | "jira" | "confluence" | "testrail" | "zephyr" | "qtest" | "xray" | "browserstack" | "testmu"
+export type SystemId = "azure_devops" | "github" | "github_copilot" | "jira" | "confluence" | "testrail" | "zephyr" | "qtest" | "xray" | "browserstack" | "testmu"
 
 export const SYSTEMS: { id: SystemId; label: string; aliases: string[] }[] = [
   { id: "azure_devops", label: "Azure DevOps", aliases: ["ado", "azure", "devops", "azdo", "azure-devops"] },
   { id: "github", label: "GitHub", aliases: ["gh"] },
+  { id: "github_copilot", label: "GitHub Copilot", aliases: ["copilot", "github-copilot", "ghcp"] },
   { id: "jira", label: "Jira", aliases: ["atlassian"] },
   { id: "confluence", label: "Confluence", aliases: ["wiki"] },
   { id: "testrail", label: "TestRail", aliases: [] },
@@ -295,6 +300,51 @@ async function signInGithub(io: AuthIO): Promise<SignInResult> {
   return finish(io, "github", { via: "gh", env: {}, secrets: {}, account }, "GitHub CLI")
 }
 
+/**
+ * GitHub Copilot as the model for ForgeQE's agent and Scribe: the agent runtime's own Copilot device sign-in, kept in
+ * ForgeQE's credential store. The browser engine uses GitHub Models with the GitHub CLI's sign-in, so say whether it has one.
+ */
+async function signInCopilot(io: AuthIO, cfg?: AppConfig): Promise<SignInResult> {
+  const where =
+    (await io.choose({
+      title: "Sign in to GitHub Copilot",
+      detail:
+        "ForgeQE's agent and Scribe then run on your Copilot seat (Pro, Pro+, Business or Enterprise), through the agent runtime's GitHub Copilot sign-in. " +
+        "The browser engine uses GitHub Models with your GitHub CLI sign-in.",
+      options: [
+        { id: "github.com", label: "GitHub.com" },
+        { id: "enterprise", label: "GitHub Enterprise (data residency, e.g. acme.ghe.com)" },
+        { id: "cancel", label: "Cancel" },
+      ],
+    })) || "cancel"
+  if (where === "cancel") throw new Cancelled()
+  let enterprise: string | undefined
+  if (where === "enterprise") {
+    const raw = await ask(io, "Your GitHub Enterprise domain (e.g. acme.ghe.com)")
+    enterprise = enterpriseHost(raw) || undefined
+    if (!enterprise) throw new Error(`"${raw.slice(0, 80)}" is not a GitHub Enterprise domain: give its host, like acme.ghe.com.`)
+  }
+  const bin = await ensureOpencode(cfg?.code.opencode, (text) => io.say(text))
+  if (!bin) throw new Error(`GitHub Copilot signs in through the agent runtime, which is not installed. ${INSTALL_HINT}`)
+  const { auth, models } = await copilotDeviceLogin(
+    bin,
+    {
+      showCode: (code, url) => {
+        io.say(`Your one-time code is ${code}. Enter it on the GitHub page that opens in your browser (${url}), and authorize with the account that has the Copilot seat.`)
+        io.openUrl(url)
+      },
+      signal: io.signal,
+    },
+    enterprise,
+  )
+  const account = await copilotAccount(auth)
+  const result = await finish(io, "github_copilot", { via: "token", env: {}, secrets: { [COPILOT_AUTH_ENV]: JSON.stringify(auth) }, account }, "Copilot device sign-in")
+  if (models.length) io.say(`Copilot models for this seat: ${models.join(", ")}. Put one in llms.json as the github_copilot profile's "model".`)
+  if (!process.env.GITHUB_TOKEN?.trim() && !ghAuthToken())
+    io.say("The browser engine reaches GitHub Models with a GitHub sign-in, and there is none yet: run forgeqe auth login github, or set GITHUB_TOKEN.")
+  return result
+}
+
 async function signInAtlassian(io: AuthIO, cfg: AppConfig | undefined, which: "jira" | "confluence"): Promise<SignInResult> {
   const names = envNames(cfg)[which]
   const label = which === "jira" ? "Jira" : "Confluence"
@@ -441,6 +491,8 @@ export async function signIn(io: AuthIO, system: string | undefined, cfg?: AppCo
         return await signInAdo(io, cfg)
       case "github":
         return await signInGithub(io)
+      case "github_copilot":
+        return await signInCopilot(io, cfg)
       case "jira":
       case "confluence":
         return await signInAtlassian(io, cfg, id)
@@ -507,6 +559,7 @@ export function authStatus(cfg?: AppConfig): string[] {
   const lines = [
     row("azure_devops", "Azure DevOps", ado && `${ado}, ${adoUrl}`),
     `${"GitHub".padEnd(14)}${ghUser ? `GitHub CLI as ${ghUser}` : Bun.which("gh") ? "not signed in" : "GitHub CLI (gh) not installed"}`,
+    row("github_copilot", "Copilot", parseCopilotAuth(process.env[COPILOT_AUTH_ENV]) ? (fromSaved.has(COPILOT_AUTH_ENV) ? "saved sign-in" : "environment") : runtimeHasCopilot() ? "agent runtime's own sign-in" : null),
     row("jira", "Jira", jira && `${jira}, ${jiraUrl}`),
     row("confluence", "Confluence", confHow && `${confHow}, ${conf!.url}`),
     row("testrail", "TestRail", cfg?.sources.testrail || process.env[n.testrail.url] ? source([n.testrail.email, n.testrail.token]) : null),

package/src/brain/index.ts

@@ -9,11 +9,13 @@ import { externalMcp, externalNotes, type ExternalPlan } from "../mcp/external.t
 import { MCP_NAME, TOOL_TIMEOUT_MS, localToolServer } from "../mcp/server.ts"
 import { TOOLS, environmentNotes, type ToolContext } from "../mcp/tools.ts"
 import { createRouter } from "../mcp/routing.ts"
+import { CapabilityScope, capabilityIndex } from "../mcp/scope.ts"
 import { brainPrompt, BRAIN_SCHEMA, cleanFollowUps, type BrainReport, type FollowUp } from "./prompt.ts"
 import { redactSecrets } from "../sessionLogins.ts"
 import { logEvent } from "../sessionLog.ts"
 import { loadSkills } from "../skills/registry.ts"
 import { domainNotes } from "../domain.ts"
+import { guardrailsNotes } from "../guardrails.ts"
 
 export const BRAIN_AGENT = "forgeqe"
 
@@ -119,12 +121,19 @@ export function carryOver(turns: { user: string; reply: string }[], text: string
 /** Routing (src/mcp/routing.ts) is on unless FORGEQE_ROUTING=off, kept for comparing and for finding a routing fault. */
 export const routingOn = (env: Record<string, string | undefined> = process.env) => !/^(off|0|false|no)$/i.test(env.FORGEQE_ROUTING || "")
 
+/** Per-turn tool scope (src/mcp/scope.ts), part of routing; FORGEQE_TOOL_SCOPE=off gives every tool on every turn. */
+export const toolScopeOn = (env: Record<string, string | undefined> = process.env) => routingOn(env) && !/^(off|0|false|no)$/i.test(env.FORGEQE_TOOL_SCOPE || "")
+
+/** Continuations a turn may get after use_capabilities added capabilities, so a confused agent cannot loop. */
+const MAX_SCOPE_CONTINUATIONS = 2
+
 export async function openBrain(opts: BrainOptions): Promise<Brain> {
   const { config } = opts
   const cwd = realpathOr(opts.cwd)
   const context = (): ToolContext => ({ ...opts.context(), config, cwd })
   // Tools listed in one line and playbooks on demand keep every model call small; FORGEQE_ROUTING=off sends it all.
-  const router = routingOn() ? createRouter(TOOLS) : undefined
+  const scope = toolScopeOn() ? new CapabilityScope(config, TOOLS.map((t) => t.name)) : undefined
+  const router = routingOn() ? createRouter(TOOLS, { scope }) : undefined
   const tools = localToolServer({ tools: TOOLS, context, router, instructions: () => environmentNotes(context()), timeoutMs: TOOL_TIMEOUT_MS })
   const external = opts.external || externalMcp(config, Bun.which, process.env, { cwd })
   const notes = [environmentNotes(context()), ...externalNotes(external), ...(opts.notes || [])].filter(Boolean).join("\n")
@@ -142,6 +151,7 @@ export async function openBrain(opts: BrainOptions): Promise<Brain> {
       repo: cwd,
       profile: config.llm,
       domain: domainNotes(config),
+      guardrails: guardrailsNotes(config),
       model: config.code.model,
       bin: config.code.opencode,
       readDirs,
@@ -153,10 +163,11 @@ export async function openBrain(opts: BrainOptions): Promise<Brain> {
       agent: {
         name: BRAIN_AGENT,
         description: "ForgeQE: browser runs, test cases, tests, and CI pipelines",
-        prompt: `${router ? router.parts.core : brainPrompt()}\n\nThis session:\n${notes}`,
+        prompt: `${router ? router.parts.core : brainPrompt()}${scope ? `\n\n${capabilityIndex()}` : ""}\n\nThis session:\n${notes}`,
         skills: "forgeqe",
         // Systems are read through MCP or query_api, never by scripts in the shell that handle tokens themselves.
-        permission: { bash: agentBashPermission(privateEnvNames(config)) },
+        // Container services' secrets are the tests' and the containers', never the agent's to read in its shell.
+        permission: { bash: agentBashPermission([...privateEnvNames(config), ...Object.values(config.containers?.services || {}).flatMap((s) => s.secrets)]) },
       },
       skills: loadSkills(config.skills, cwd).skills,
       schema: BRAIN_SCHEMA,
@@ -184,7 +195,18 @@ export async function openBrain(opts: BrainOptions): Promise<Brain> {
     async ask(text) {
       stopped = false
       logEvent("agent.ask", { model: session.model, characters: text.length })
-      const out = await session.prompt(text)
+      const turn = scope?.beginTurn(text)
+      if (turn) logEvent("agent.scope", { capabilities: turn.choice.reasons })
+      let out = await session.prompt(text, turn ? { tools: turn.tools } : undefined)
+      for (let i = 0; scope && i < MAX_SCOPE_CONTINUATIONS; i++) {
+        const added = scope.takePending()
+        if (!added.length || stopped || out.error === "stopped" || opts.signal?.aborted) break
+        logEvent("agent.scope.added", { capabilities: added })
+        out = await session.prompt(
+          `ForgeQE added ${added.join(", ")}: their tools are available now. Carry on with the user's request from where you stopped; do not repeat what is done.`,
+          { tools: scope.toggles() },
+        )
+      }
       // Written after the turn, when credentials the message gave are remembered and so redacted.
       logEvent("agent.turn", { ask: text, error: out.error, report: out.report, text: out.text })
       if (stopped || out.error === "stopped" || opts.signal?.aborted) return { reply: "", outcome: "stopped" }

package/src/capabilities/guide.ts

@@ -28,6 +28,8 @@ export const GUIDE_EXCLUDED = ["HOW_TO_USE.md#agent-map"]
 
 const AREA_NOTE: Record<Area, string> = {
   Browser: "Goals carried out in a real browser, and the logins they use",
+  Desktop: "Windows thick-client apps: explore a goal, record by hand, replay the saved workflow",
+  Mobile: "Android and iOS apps through Appium or Maestro: explore a goal, replay, run the team's flows",
   "Test cases": "Run, check, write, and explore manual test cases",
   "Automated tests": "Write, heal, find, run, and stabilise tests in your repository",
   "Pull requests": "Reviews, impact, and the tests a change can break",