@capagents/forgeqe 1.3.2 → 2.0.1

package/src/copilot.ts

@@ -0,0 +1,155 @@
+import { readFileSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+import type { LlmProfile } from "./llm.ts"
+
+/**
+ * GitHub Copilot seats as the model (`provider: github_copilot` in llms.json). ForgeQE's agent and Scribe run on the
+ * agent runtime's own GitHub Copilot provider, which GitHub supports for Copilot Pro, Pro+, Business and Enterprise;
+ * `forgeqe auth login copilot` signs in through it and keeps the sign-in in ForgeQE's credential store. The browser
+ * engine calls the model itself, which Copilot does not offer other tools, so it uses GitHub Models (an OpenAI-style
+ * API) with the GitHub CLI's sign-in or GITHUB_TOKEN.
+ */
+
+/** The agent runtime's provider id. */
+export const COPILOT_PROVIDER_ID = "github-copilot"
+/** The saved Copilot sign-in (JSON), in ForgeQE's credential store; never in a file the agent can read. */
+export const COPILOT_AUTH_ENV = "FORGEQE_COPILOT_AUTH"
+/** The agent runtime reads its sign-ins from this variable instead of its auth.json. */
+export const RUNTIME_AUTH_ENV = "OPENCODE_AUTH_CONTENT"
+/** The GitHub Models token, set only in the engine's own environment. */
+export const MODELS_TOKEN_ENV = "FORGEQE_GITHUB_MODELS_TOKEN"
+export const MODELS_URL = "https://models.github.ai"
+/** The engine's model when the profile names none: GitHub Models' id, which takes screenshots. */
+export const DEFAULT_ENGINE_MODEL = "openai/gpt-4.1"
+
+/** A GitHub organization login. */
+const ORG = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/
+/** A GitHub Models id: publisher/model. */
+const MODELS_ID = /^[A-Za-z0-9][\w.-]*\/[A-Za-z0-9][\w.:-]*$/
+/** A Copilot model id as the agent runtime lists it (claude-sonnet-4.6, gpt-5.4). */
+const COPILOT_MODEL = /^[A-Za-z0-9][\w.:-]*$/
+/** A GitHub Enterprise Cloud host with data residency (acme.ghe.com) or a GitHub Enterprise Server host. */
+const HOST = /^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/
+
+export type CopilotAuth = { type: "oauth"; refresh: string; access: string; expires: number; enterpriseUrl?: string }
+
+const TOKEN = /^[A-Za-z0-9_.-]{20,512}$/
+
+/** A sign-in as the agent runtime writes it, or null when `value` is not one. */
+export function parseCopilotAuth(value: unknown): CopilotAuth | null {
+  let v = value
+  if (typeof v === "string") {
+    try {
+      v = JSON.parse(v)
+    } catch {
+      return null
+    }
+  }
+  if (!v || typeof v !== "object") return null
+  const r = v as Record<string, unknown>
+  if (r.type !== "oauth" || typeof r.refresh !== "string" || !TOKEN.test(r.refresh)) return null
+  const access = typeof r.access === "string" && TOKEN.test(r.access) ? r.access : r.refresh
+  const expires = typeof r.expires === "number" && Number.isFinite(r.expires) ? r.expires : 0
+  let enterpriseUrl: string | undefined
+  if (r.enterpriseUrl !== undefined) {
+    enterpriseUrl = enterpriseHost(String(r.enterpriseUrl)) || undefined
+    if (!enterpriseUrl) return null
+  }
+  return { type: "oauth", refresh: r.refresh, access, expires, ...(enterpriseUrl ? { enterpriseUrl } : {}) }
+}
+
+/** "acme.ghe.com" or "https://acme.ghe.com/" → "acme.ghe.com"; null for anything that is not a plain host. */
+export function enterpriseHost(raw: string): string | null {
+  const t = raw.trim().toLowerCase()
+  let host = t
+  if (/^[a-z][a-z0-9+.-]*:/.test(t)) {
+    let u: URL
+    try {
+      u = new URL(t)
+    } catch {
+      return null
+    }
+    if (u.protocol !== "https:" || u.username || u.password || u.port || (u.pathname !== "/" && u.pathname !== "") || u.search || u.hash) return null
+    host = u.hostname
+  } else host = t.replace(/\/+$/, "")
+  if (!HOST.test(host) || host === "github.com") return null
+  return host
+}
+
+/** The agent runtime's sign-ins for this run: the saved Copilot one, as RUNTIME_AUTH_ENV takes them; null when none is saved. */
+export function runtimeAuthContent(saved: string | undefined = process.env[COPILOT_AUTH_ENV]): string | null {
+  const auth = parseCopilotAuth(saved)
+  return auth ? JSON.stringify({ [COPILOT_PROVIDER_ID]: auth }) : null
+}
+
+/** Where the agent runtime keeps the sign-ins of `opencode auth login`. */
+export function runtimeAuthFile(env: Record<string, string | undefined> = process.env): string {
+  const base = env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share")
+  return path.join(base, "opencode", "auth.json")
+}
+
+/** Whether the agent runtime itself has a Copilot sign-in (`opencode auth login`); only the entry's presence is checked. */
+export function runtimeHasCopilot(file = runtimeAuthFile()): boolean {
+  try {
+    const data = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>
+    return Boolean(data && typeof data === "object" && data[COPILOT_PROVIDER_ID])
+  } catch {
+    return false
+  }
+}
+
+/** GitHub Models' OpenAI-style base URL; with `org`, requests are billed to and governed by that organization. */
+export function modelsEndpoint(org?: string): string {
+  if (!org) return `${MODELS_URL}/inference`
+  if (!ORG.test(org)) throw new Error(`github_org must be a GitHub organization name, got "${org}".`)
+  return `${MODELS_URL}/orgs/${org}/inference`
+}
+
+export function engineModel(p: Pick<LlmProfile, "engineModel">): string {
+  return p.engineModel || DEFAULT_ENGINE_MODEL
+}
+
+export const NO_MODELS_TOKEN =
+  "The browser engine reaches GitHub Models with a GitHub sign-in, and there is none: run forgeqe auth login github " +
+  "(the GitHub CLI), or set GITHUB_TOKEN to a token with the models:read permission."
+
+/** The GitHub Models token: the profile's api_key_env, else GITHUB_TOKEN, else the GitHub CLI's sign-in. */
+export function modelsToken(p: Pick<LlmProfile, "apiKeyEnv">, gh: () => string | null, env: Record<string, string | undefined> = process.env): string | null {
+  const name = p.apiKeyEnv || "GITHUB_TOKEN"
+  return env[name]?.trim() || gh()
+}
+
+/** Why the profile's fields cannot work, or null. */
+export function copilotProfileError(p: LlmProfile): string | null {
+  if (!COPILOT_MODEL.test(p.model)) return `The github_copilot profile's model must be a Copilot model id such as claude-sonnet-4.6, got "${p.model}".`
+  if (p.engineModel && !MODELS_ID.test(p.engineModel)) return `engine_model must be a GitHub Models id such as ${DEFAULT_ENGINE_MODEL}, got "${p.engineModel}".`
+  if (p.githubOrg && !ORG.test(p.githubOrg)) return `github_org must be a GitHub organization name, got "${p.githubOrg}".`
+  if (p.auth === "entra") return "auth: entra does not apply to github_copilot, which signs in with GitHub."
+  return null
+}
+
+/** Why the agent runtime cannot use Copilot here, or null. */
+export function missingCopilotSignIn(p: LlmProfile, hasRuntimeSignIn: () => boolean = runtimeHasCopilot): string | null {
+  const bad = copilotProfileError(p)
+  if (bad) return bad
+  if (runtimeAuthContent() || hasRuntimeSignIn()) return null
+  return `The github_copilot profile for ${p.model} needs a GitHub Copilot sign-in: run forgeqe auth login copilot (or /auth copilot in the shell).`
+}
+
+/**
+ * The profile the engine runs for a github_copilot one: GitHub Models' OpenAI-compatible API, with the token only in
+ * the engine's environment. Other profiles come back as they are.
+ */
+export function engineRoute(p: LlmProfile, gh: () => string | null): { profile: LlmProfile; env: Record<string, string> } {
+  if (p.provider !== "github_copilot") return { profile: p, env: {} }
+  const bad = copilotProfileError(p)
+  if (bad) throw new Error(bad)
+  const token = modelsToken(p, gh)
+  if (!token) throw new Error(NO_MODELS_TOKEN)
+  return {
+    profile: { ...p, provider: "openai_compatible", model: engineModel(p), endpoint: modelsEndpoint(p.githubOrg), auth: "key", apiKey: undefined, apiKeyEnv: MODELS_TOKEN_ENV },
+    env: { [MODELS_TOKEN_ENV]: token },
+  }
+}

package/src/desktop/bridge.ts

@@ -0,0 +1,229 @@
+import { spawn } from "node:child_process"
+import { createInterface } from "node:readline"
+import path from "node:path"
+
+import type { DesktopConfig } from "../config.ts"
+import { ghAuthToken } from "../cases/github.ts"
+import { engineRoute } from "../copilot.ts"
+import { AZURE_IDENTITY_ENV } from "../entra.ts"
+import { llmPayload } from "../engine/bridge.ts"
+import { engineEnv } from "../engine/setup.ts"
+import type { LlmProfile } from "../llm.ts"
+import { logEvent } from "../sessionLog.ts"
+import { recordCall, withUsageScope } from "../tokenomics/ledger.ts"
+import type { Usage } from "../types.ts"
+import type { Role } from "../usage.ts"
+
+/** One request to `python -m forgeqe_desktop serve`: a replay of a workflow, an explore of a goal, or a recording by hand. */
+export type DesktopRequest = {
+  mode: "replay" | "explore" | "record"
+  outDir: string
+  llm: LlmProfile
+  profileName: string
+  desktop: DesktopConfig
+  /** The pinned UFO checkout (explore). */
+  ufoDir?: string
+  workflow?: string
+  variables?: Record<string, string>
+  heal?: boolean
+  /** expect_image: replace the baselines with what is captured now. */
+  updateBaselines?: boolean
+  goal?: string
+  app?: string
+  name?: string
+}
+
+export type DesktopStep = {
+  index: number
+  op: string
+  ok: boolean
+  ms: number
+  error?: string
+  healed_target?: Record<string, unknown> | null
+  screenshot?: string | null
+  target?: Record<string, unknown> | null
+  /** How many tries the step took, when more than one. */
+  attempts?: number
+  /** Dialogs closed (by the workflow's dismiss list) while the step ran. */
+  dismissed?: string[]
+  /** expect_image: the run's copies of the baseline, what was captured, and the difference. */
+  images?: { name?: string; baseline?: string; actual?: string; diff?: string; differs?: number; baseline_saved?: boolean }
+  note?: string
+}
+
+/** run.json of a desktop run, as the engine writes it. */
+export type DesktopResult = {
+  mode?: "replay" | "explore" | "record" | "maestro"
+  /** mobile: the driver a replay ran on (appium or maestro), the Maestro flow written for it. */
+  driver?: string
+  flow?: string
+  /** mobile maestro mode: each team flow's result, and the flow files checked before they ran. */
+  flows?: { name: string; ok: boolean; error?: string }[]
+  checked?: string[]
+  ok: boolean
+  error?: string
+  stopped?: boolean
+  name?: string
+  app?: string
+  workflow?: string | null
+  total?: number
+  steps?: DesktopStep[]
+  heals?: { index: number; old: Record<string, unknown> | null; new: Record<string, unknown> }[]
+  goal?: string
+  recorded?: number
+  /** expect steps explore added from what the app showed when UFO had finished. */
+  checks?: number
+  /** Values the app showed at the end of an explore (an order number), each exactly as on screen, by name. */
+  values?: Record<string, string>
+  skipped?: { index: number; action: string; reason: string }[]
+  refused?: { action: string; args?: Record<string, unknown> }[]
+  ufo_complete?: boolean | null
+  seconds?: number
+  /** record: why the recording ended (hotkey, app closed, stopped). */
+  stopped_by?: string | null
+  /** record: the secrets the workflow types (password fields), which must be in desktop.secrets. */
+  secrets?: string[]
+}
+
+export type DesktopEvent =
+  | { type: "log"; level?: string; text?: string }
+  | ({ type: "step" } & DesktopStep)
+  | { type: "recorded"; index: number; op: string; target?: Record<string, unknown>; keys?: string; value?: string }
+  | { type: "call"; ms?: number; ok?: boolean; input?: number; output?: number; cached?: number }
+  | { type: "done"; result?: DesktopResult }
+
+export function desktopPayload(req: DesktopRequest): Record<string, unknown> {
+  return {
+    mode: req.mode,
+    out_dir: req.outDir,
+    llm: llmPayload(req.llm),
+    profile_name: req.profileName,
+    desktop: { apps: req.desktop.apps, secrets: req.desktop.secrets, ...(req.ufoDir ? { ufo_dir: req.ufoDir } : {}) },
+    ...(req.mode === "replay"
+      ? { workflow: req.workflow, variables: req.variables || {}, heal: Boolean(req.heal), screenshots: req.desktop.screenshots, update_baselines: Boolean(req.updateBaselines) }
+      : req.mode === "record"
+        ? { app: req.app, ...(req.name ? { name: req.name } : {}) }
+        : { goal: req.goal, app: req.app, name: req.name || req.goal }),
+  }
+}
+
+/** What the engine process may see: system settings, the model's key (or Entra variables), and desktop.secrets only. */
+export function desktopEnvNames(req: Pick<DesktopRequest, "llm" | "desktop">): string[] {
+  return [...(req.llm.auth === "entra" ? AZURE_IDENTITY_ENV : req.llm.apiKeyEnv ? [req.llm.apiKeyEnv] : []), ...req.desktop.secrets]
+}
+
+/**
+ * Run one desktop request in the engine and pass its events on. A stop (the signal) asks the engine to stop between
+ * steps; one that has not exited `graceMs` later is killed.
+ */
+export async function runDesktop(opts: {
+  python: string
+  /** The engine command; default `<python> -m forgeqe_desktop serve`. */
+  command?: string[]
+  request: DesktopRequest
+  signal?: AbortSignal
+  onEvent?: (event: DesktopEvent) => void
+  graceMs?: number
+}): Promise<DesktopResult> {
+  const req = opts.request
+  return runEngine({
+    command: opts.command || [opts.python, "-m", "forgeqe_desktop", "serve"],
+    payload: desktopPayload(req),
+    logged: { ...desktopPayload(req), desktop: { apps: Object.keys(req.desktop.apps), secrets: req.desktop.secrets } },
+    envNames: desktopEnvNames(req),
+    outDir: req.outDir,
+    llm: req.llm,
+    agent: "desktop agent",
+    log: "desktop",
+    signal: opts.signal,
+    onEvent: opts.onEvent,
+    graceMs: opts.graceMs,
+  })
+}
+
+/** One request to an engine that speaks the JSON-lines protocol (`serve`): the desktop engine or the mobile engine. */
+export async function runEngine(opts: {
+  command: string[]
+  payload: Record<string, unknown>
+  /** What the session log records of the request (no secrets). */
+  logged: Record<string, unknown>
+  /** The environment variables the engine may see, besides system settings. */
+  envNames: string[]
+  outDir: string
+  llm: LlmProfile
+  /** The usage ledger's name for the engine's model calls. */
+  agent: Role
+  log: "desktop" | "mobile"
+  signal?: AbortSignal
+  onEvent?: (event: DesktopEvent) => void
+  graceMs?: number
+}): Promise<DesktopResult> {
+  const { onEvent } = opts
+  // A github_copilot profile's desktop and mobile agents run on GitHub Models, like the browser engine: the engine gets
+  // that profile, and the token only in its environment.
+  const route = engineRoute(opts.llm, ghAuthToken)
+  const req = { llm: route.profile }
+  const payload = opts.payload.llm ? { ...opts.payload, llm: llmPayload(route.profile) } : opts.payload
+  const scope = { runId: path.basename(opts.outDir) }
+  const model = req.llm.deployment || req.llm.model
+  const [bin, ...args] = opts.command
+  const child = spawn(bin!, args, { env: engineEnv(route.env, [...opts.envNames, ...Object.keys(route.env)]), stdio: ["pipe", "pipe", "pipe"] })
+
+  const stderrTail: string[] = []
+  child.stderr.setEncoding("utf8")
+  child.stderr.on("data", (chunk: string) => {
+    for (const line of chunk.split(/\r?\n/)) {
+      if (!line.trim()) continue
+      logEvent(`${opts.log}.log`, line)
+      stderrTail.push(line)
+      if (stderrTail.length > 40) stderrTail.shift()
+    }
+  })
+
+  child.stdin.write(JSON.stringify(payload) + "\n")
+  logEvent(`${opts.log}.request`, opts.logged)
+
+  let killTimer: ReturnType<typeof setTimeout> | undefined
+  const onAbort = () => {
+    if (child.stdin.writable) child.stdin.write("stop\n")
+    killTimer = setTimeout(() => child.exitCode === null && child.kill(), opts.graceMs ?? 30_000)
+  }
+  if (opts.signal?.aborted) onAbort()
+  opts.signal?.addEventListener("abort", onAbort, { once: true })
+
+  let done: DesktopResult | null = null
+  const lines = createInterface({ input: child.stdout })
+  lines.on("line", (line) => {
+    if (!line.trim()) return
+    let ev: DesktopEvent
+    try {
+      ev = JSON.parse(line) as DesktopEvent
+    } catch {
+      onEvent?.({ type: "log", level: "info", text: line })
+      return
+    }
+    logEvent(`${opts.log}.event`, ev)
+    if (ev.type === "call") {
+      const usage: Usage = { input: Number(ev.input || 0), output: Number(ev.output || 0), ...(ev.cached ? { cached: Number(ev.cached) } : {}) }
+      withUsageScope(scope, () =>
+        recordCall({ agent: opts.agent, usage, price: req.llm.price, provider: opts.llm.provider, model, purpose: opts.log, ms: Number(ev.ms || 0), outcome: ev.ok === false ? "error" : "ok" }),
+      )
+    }
+    if (ev.type === "done") done = ev.result || { ok: false, error: "the engine sent no result" }
+    onEvent?.(ev)
+  })
+
+  const code = await new Promise<number>((resolve, reject) => {
+    child.on("error", reject)
+    child.on("close", (c) => resolve(c ?? 1))
+  }).finally(() => {
+    if (killTimer) clearTimeout(killTimer)
+    opts.signal?.removeEventListener("abort", onAbort)
+  })
+  logEvent(`${opts.log}.exit`, { code, finished: Boolean(done) })
+  if (!done) {
+    const detail = stderrTail.slice(-12).join("\n")
+    throw new Error(`The ${opts.log} engine exited (${code}) without a result.${detail ? `\n${detail}` : ""}`)
+  }
+  return done
+}