@capagents/forgeqe 1.3.1 → 2.0.0

package/src/run.ts

@@ -4,6 +4,7 @@ import { createRequire } from "node:module"
 import path from "node:path"
 
 import { assertGoalUrlsAllowed, hostAllowed, normalizeHttpUrl } from "./guard.ts"
+import { ghAuthToken } from "./cases/github.ts"
 import { missingKey } from "./llm.ts"
 import type { AgentEvent, ReplayMode, RunResult } from "./types.ts"
 import { browserConfigFor, type AppConfig, type BrowserProvider } from "./config.ts"
@@ -21,7 +22,9 @@ import { historyFile, recordQuality } from "./quality/history.ts"
 import { compareVisual, engineVisual } from "./quality/visual.ts"
 import { enginePrompts, prompt } from "./prompts.ts"
 import { knowledgeBlock, readKnowledge, relevantKnowledge } from "./knowledge.ts"
+import { environmentBrief } from "./environments.ts"
 import { registryMode } from "./registry/index.ts"
+import { guardrailsNotes } from "./guardrails.ts"
 
 export type ExecuteOptions = {
   config: AppConfig
@@ -211,7 +214,7 @@ export async function executeRun(opts: ExecuteOptions): Promise<{ result: RunRes
     return withReport(out)
   }
 
-  const missing = missingKey(opts.config.llm)
+  const missing = missingKey(opts.config.llm, "engine", ghAuthToken)
   if (missing) throw new Error(missing)
   // A remote grid's keys are checked here, before the engine starts, rather than failing inside it.
   if (browser.remote) {
@@ -220,9 +223,10 @@ export async function executeRun(opts: ExecuteOptions): Promise<{ result: RunRes
   }
   const log = (text: string) => opts.onEvent?.({ type: "log", level: "info", text })
   const python = await ensureEngine(log)
-  // The browser agent's added instructions: forgeqe.yaml's, prompts/browser-extra.md, and the product knowledge that matches the goal.
+  // The browser agent's added instructions: forgeqe.yaml's, prompts/browser-extra.md, the product knowledge that matches the goal, and the guardrails.
   const knowledge = opts.config.knowledge && opts.config.knowledge.browserMaxChars > 0 ? knowledgeBlock(relevantKnowledge(readKnowledge(opts.config.knowledge.dir), goal, opts.config.knowledge.browserMaxChars, 2)) : ""
-  const extend = [opts.config.prompts.guiderails, opts.config.prompts.stepInstruction, prompt("browser-extra"), knowledge]
+  // The team's guardrails come last, so nothing added after them reads as overriding them.
+  const extend = [opts.config.prompts.stepInstruction, prompt("browser-extra"), knowledge, environmentBrief(opts.config, "browser"), guardrailsNotes(opts.config) || ""]
     .map((s) => s.trim())
     .filter(Boolean)
     .join("\n\n")

package/src/tokenomics/ledger.ts

@@ -18,7 +18,7 @@ import { costOf, recordUsage, type Price, type Role } from "../usage.ts"
 export type Trigger = "tui" | "cli" | "mcp" | "ci" | "monitor" | "schedule"
 
 /** What a call was for, from the tools it asked for: no tools is the model thinking or answering. */
-export type Purpose = "reasoning" | "planning" | "search" | "file read" | "edit" | "shell" | "browser" | "integration" | "delegation" | "unattributed"
+export type Purpose = "reasoning" | "planning" | "search" | "file read" | "edit" | "shell" | "browser" | "desktop" | "mobile" | "integration" | "delegation" | "unattributed"
 
 /** What ForgeQE was doing when the call was made. Set with withUsageScope; inner scopes add to outer ones. */
 export type UsageScope = {
@@ -130,6 +130,8 @@ export function purposeOf(tools: string[] | undefined): Purpose {
 const DEFAULT_JOB: Record<Role, string> = {
   "ForgeQE's agent": "chat",
   "browser agent": "browser test",
+  "desktop agent": "desktop test",
+  "mobile agent": "mobile test",
   Scribe: "write tests",
   reviewer: "review",
   judge: "eval",

package/src/tui/App.tsx

@@ -15,6 +15,7 @@ import { FAILURE_ACTION, FAILURE_LABEL } from "../cases/failure.ts"
 import { authStatus, openInBrowser, signIn, signOut, type AuthIO } from "../auth/signin.ts"
 import { HELP, parseCommand } from "../commands.ts"
 import { loadConfig, selectProfile, type AppConfig, type BrowserProvider } from "../config.ts"
+import { appsText, exportEnvironment, withEnvironment } from "../environments.ts"
 import { TOOLS, type AskQuestion, type ToolEvent } from "../mcp/tools.ts"
 import type { executeRun } from "../run.ts"
 import { bundleLogs, logEvent } from "../sessionLog.ts"
@@ -1443,6 +1444,28 @@ export function App({ options }: { options: TuiOptions }) {
       }
       return
     }
+    if (cmd.type === "env") {
+      try {
+        const cfg = configRef.current
+        if (!cfg) throw new Error("Config is not loaded.")
+        if (!cmd.name) {
+          push("sys", appsText(cfg))
+          return
+        }
+        configRef.current = withEnvironment(cfg, cmd.name)
+        exportEnvironment(configRef.current)
+        // Reloads in this session (/init, a profile switch) keep the environment.
+        process.env.FORGEQE_ENV = cmd.name
+        push("sys", `environment  ${cmd.name}`)
+        if (brainRef.current) {
+          closeBrain()
+          push("sys", "The agent switches to this environment on your next message and keeps the conversation.")
+        }
+      } catch (err) {
+        push("err", (err as Error).message)
+      }
+      return
+    }
     if (cmd.type === "init") {
       // forgeqe init in this folder, then the session reads what it wrote: the start screen updates at once.
       try {

package/src/update.ts

@@ -1,5 +1,6 @@
-import { spawnSync } from "node:child_process"
-import { existsSync, readFileSync, realpathSync, statSync } from "node:fs"
+import { spawn, spawnSync } from "node:child_process"
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
 import path from "node:path"
 import { packageVersion } from "./tui/theme.ts"
 
@@ -28,19 +29,50 @@ export interface UpdateDeps {
   platform: NodeJS.Platform
   sleep: (ms: number) => Promise<void>
   now: () => number
+  /**
+   * Windows: starts `script` (a .cmd) detached, to run once this process has exited, and returns its log file.
+   * A running ForgeQE keeps files of its own install open (its launcher, native libraries), and Windows does not
+   * let an installer replace a file that is in use, so the update cannot run from inside ForgeQE.
+   */
+  defer?: (script: string) => string
+}
+
+/**
+ * How to start `cmd` on `platform`. Windows runs .cmd and .bat files (npm, pyenv-win) only through a shell, which Node
+ * refuses to do on its own (EINVAL), so those go through cmd.exe with each argument quoted.
+ */
+export function spawnPlan(cmd: string, args: string[], platform: NodeJS.Platform): { cmd: string; args: string[]; shell: boolean } {
+  if (platform !== "win32" || /\.exe$/i.test(cmd)) return { cmd, args, shell: false }
+  return { cmd: winQuote(cmd), args: args.map(winQuote), shell: true }
+}
+
+/** One argument for cmd.exe: quoted when it has a space or a character cmd.exe would read. */
+export function winQuote(a: string): string {
+  return /[\s&|<>^()%!"]/.test(a) ? `"${a.replace(/"/g, '""')}"` : a
 }
 
 export function defaultDeps(): UpdateDeps {
   return {
     fetch,
     run: (cmd, args) => {
-      const r = spawnSync(cmd, args, { encoding: "utf8" })
+      const plan = spawnPlan(cmd, args, process.platform)
+      const r = spawnSync(plan.cmd, plan.args, { encoding: "utf8", shell: plan.shell, windowsHide: true })
       return { status: r.error ? null : r.status, stdout: r.stdout || "", stderr: r.stderr || (r.error ? String(r.error.message) : "") }
     },
     env: process.env,
     platform: process.platform,
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
     now: () => Date.now(),
+    defer: (script) => {
+      const dir = path.join(tmpdir(), "forgeqe-update")
+      mkdirSync(dir, { recursive: true })
+      const stamp = new Date().toISOString().replace(/[:.]/g, "-")
+      const file = path.join(dir, `update-${stamp}.cmd`)
+      const log = path.join(dir, `update-${stamp}.log`)
+      writeFileSync(file, script.replace(/\{LOG\}/g, log).replace(/\n/g, "\r\n"))
+      spawn("cmd.exe", ["/d", "/c", file], { detached: true, stdio: "ignore", windowsHide: true }).unref()
+      return log
+    },
   }
 }
 
@@ -142,12 +174,33 @@ function packageDirOf(file: string): string | undefined {
   return undefined
 }
 
+/**
+ * The package a `forgeqe` on PATH belongs to when it is a copy or a wrapper, not a link: npm on Windows writes
+ * forgeqe.cmd next to node_modules; bun on Windows writes forgeqe.exe in ~/.bun/bin for ~/.bun/install/global; an npm
+ * prefix elsewhere keeps packages in <prefix>/lib/node_modules.
+ */
+function packageOfShim(binDir: string): string | undefined {
+  const parts = NPM_PACKAGE.split("/")
+  for (const dir of [path.join(binDir, "node_modules", ...parts), path.join(binDir, "..", "install", "global", "node_modules", ...parts), path.join(binDir, "..", "lib", "node_modules", ...parts)]) {
+    const found = packageDirOf(path.join(dir, "package.json"))
+    if (found) return path.resolve(found)
+  }
+  return undefined
+}
+
 function pythonOfScript(script: string, platform: NodeJS.Platform): string | undefined {
   if (platform === "win32") {
     const dir = path.dirname(script)
-    if (path.basename(dir).toLowerCase() !== "scripts") return undefined
     const python = path.join(path.dirname(dir), "python.exe")
-    return existsSync(python) ? python : undefined
+    if (path.basename(dir).toLowerCase() === "scripts" && existsSync(python)) return python
+    // pip's forgeqe.exe carries the Python it was installed for (`#!C:\...\python.exe` near its end): the way to find
+    // it for `pip install --user`, whose Scripts folder is not next to python.exe.
+    try {
+      const text = readFileSync(script).toString("latin1")
+      const m = [...text.matchAll(/#!\s*"?([^"\r\n]*?pythonw?\.exe)"?/gi)].pop()
+      if (m && existsSync(m[1])) return m[1]
+    } catch {}
+    return undefined
   }
   let first = ""
   try {
@@ -182,7 +235,10 @@ export function findInstalls(deps: UpdateDeps): Install[] {
       }
       if (seen.has(target)) continue
       seen.add(target)
-      const pkgDir = packageDirOf(target)
+      const pkgDir = packageDirOf(target) || packageOfShim(dir)
+      // npm on Windows writes forgeqe, forgeqe.cmd and forgeqe.ps1 for one install.
+      if (pkgDir && seen.has(`pkg:${pkgDir}`)) continue
+      if (pkgDir) seen.add(`pkg:${pkgDir}`)
       if (pkgDir) {
         let version = ""
         try {
@@ -233,6 +289,47 @@ export function commandLine([cmd, args]: [string, string[]]): string {
   return [cmd, ...args].map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(" ")
 }
 
+/** What to do when an installer refuses for a reason the machine sets, not ForgeQE (Linux: root-owned npm, PEP 668). */
+export function failureHint(kind: InstallKind, output: string, platform: NodeJS.Platform): string {
+  if (/EACCES|permission denied/i.test(output) && kind === "npm") {
+    return platform === "win32"
+      ? "npm's global folder is not writable: run the terminal as administrator, or install with bun (bun add -g @capagents/forgeqe)."
+      : "npm's global folder belongs to root: run sudo npm install -g @capagents/forgeqe, or give npm a folder of your own (npm config set prefix ~/.npm-global)."
+  }
+  if (/externally-managed-environment/i.test(output)) {
+    return "This Python is managed by the system and pip will not change it: install with pipx install forgeqe-cli, or in a virtual environment."
+  }
+  if (/EBUSY|EPERM|being used by another process/i.test(output)) {
+    return "A file of the install is in use: close every ForgeQE window and run forgeqe update again."
+  }
+  return ""
+}
+
+/**
+ * The .cmd that updates Windows installs after the ForgeQE that started it has exited: it waits for these processes
+ * (ForgeQE and its launcher), runs each install's commands, and writes everything to {LOG}.
+ */
+export function windowsUpdateScript(steps: { kind: InstallKind; bin: string; commands: Array<[string, string[]]> }[], pids: number[], version: string): string {
+  const lines = ["@echo off", "setlocal", ":wait"]
+  for (const pid of pids.filter((p) => Number.isInteger(p) && p > 0)) {
+    // ping waits a second where timeout cannot (a detached script has no console); System32 paths, so Git's find
+    // or another tasklist on PATH is never the one that runs.
+    lines.push(`"%SystemRoot%\\System32\\tasklist.exe" /FI "PID eq ${pid}" 2>nul | "%SystemRoot%\\System32\\find.exe" " ${pid} " >nul && (ping -n 2 127.0.0.1 >nul & goto wait)`)
+  }
+  lines.push(`echo Updating ForgeQE to ${version} > "{LOG}"`)
+  for (const step of steps) {
+    lines.push(`echo. >> "{LOG}"`, `echo Updating the ${step.kind} install (${step.bin}) >> "{LOG}"`)
+    for (const [cmd, args] of step.commands) {
+      const line = [cmd, ...args].map(winQuote).join(" ")
+      const cacheStep = args[0] === "pm" && args[1] === "cache"
+      lines.push(`echo $ ${line.replace(/[&|<>^]/g, "^$&")} >> "{LOG}"`)
+      lines.push(`call ${line} >> "{LOG}" 2>&1${cacheStep ? "" : ` || echo FAILED: ${step.kind} install >> "{LOG}"`}`)
+    }
+  }
+  lines.push(`echo. >> "{LOG}"`, `echo Done. Open a new terminal and run: forgeqe --version >> "{LOG}"`)
+  return `${lines.join("\n")}\n`
+}
+
 export interface UpdateOptions {
   /** A version to install instead of the latest. */
   version?: string
@@ -283,6 +380,16 @@ export async function update(opts: UpdateOptions = {}, deps: UpdateDeps = defaul
     }
   }
 
+  if (deps.platform === "win32" && deps.defer) {
+    // Windows will not replace files the running ForgeQE holds open, so the installs update once it has exited.
+    const steps = stale.map((inst) => ({ kind: inst.kind, bin: inst.bin, commands: updateCommands(inst, target, deps.env) }))
+    for (const step of steps) for (const c of step.commands) log(`  $ ${commandLine(c)}`)
+    const logFile = deps.defer(windowsUpdateScript(steps, [process.pid, process.ppid], target))
+    log(`\nThe update to ${target} starts as soon as this command exits (Windows locks the files a running ForgeQE uses).`)
+    log(`It writes what it does to ${logFile}. Then open a new terminal and run forgeqe --version.`)
+    return 0
+  }
+
   let failed = 0
   for (const inst of stale) {
     log(`\nUpdating the ${inst.kind} install (${inst.bin})`)
@@ -293,7 +400,10 @@ export async function update(opts: UpdateOptions = {}, deps: UpdateDeps = defaul
         const cacheStep = c[1][0] === "pm" && c[1][1] === "cache"
         if (cacheStep) continue
         failed++
-        log((r.stderr || r.stdout).trim().split("\n").slice(-5).map((l) => `  ${l}`).join("\n"))
+        const output = (r.stderr || r.stdout).trim()
+        log(output.split("\n").slice(-5).map((l) => `  ${l}`).join("\n"))
+        const hint = failureHint(inst.kind, output, deps.platform)
+        if (hint) log(`  ${hint}`)
         break
       }
     }
@@ -306,6 +416,6 @@ export async function update(opts: UpdateOptions = {}, deps: UpdateDeps = defaul
     log(`\n${behind.length || failed} install(s) are still behind ${target}; the output above says why.`)
     return 1
   }
-  log(`\nforgeqe ${target} is installed. Open a new terminal (or run hash -r) if the shell still finds the old one.`)
+  log(`\nforgeqe ${target} is installed. Open a new terminal${deps.platform === "win32" ? "" : " (or run hash -r)"} if the shell still finds the old one.`)
   return 0
 }

package/src/usage.ts

@@ -98,7 +98,7 @@ export function usageLine(usage: Usage, cost?: Cost | null): string {
 // The meter: every model session reports here, by role
 // ---------------------------------------------------------------------------------------------
 
-export type Role = "ForgeQE's agent" | "browser agent" | "Scribe" | "reviewer" | "judge" | "refiner" | "root-cause analyst"
+export type Role = "ForgeQE's agent" | "browser agent" | "desktop agent" | "mobile agent" | "Scribe" | "reviewer" | "judge" | "refiner" | "root-cause analyst"
 
 type Entry = { usage: Usage; cost?: Cost; priced: boolean }