@onyx-robotics/agent 0.1.0

package/src/lib/git.ts

@@ -0,0 +1,57 @@
+import { commandOutput, runProcess } from "./process"
+
+export async function git(args: string[], cwd?: string) {
+  return commandOutput("git", args, cwd)
+}
+
+export async function gitResult(args: string[], cwd?: string) {
+  return runProcess("git", args, { cwd })
+}
+
+export async function repoRoot(cwd = process.cwd()) {
+  return git(["rev-parse", "--show-toplevel"], cwd)
+}
+
+/** Absolute path to the repo's git directory (handles worktrees). */
+export async function gitDir(root: string) {
+  return git(["rev-parse", "--absolute-git-dir"], root)
+}
+
+export async function currentBranch(cwd: string) {
+  return git(["branch", "--show-current"], cwd)
+}
+
+export async function currentCommit(cwd: string) {
+  return git(["rev-parse", "HEAD"], cwd)
+}
+
+export function gitBranchForName(name: string) {
+  return `onyx/${name}`
+}
+
+export function nameFromGitBranch(gitBranchName: string) {
+  return gitBranchName.startsWith("onyx/")
+    ? gitBranchName.slice("onyx/".length)
+    : null
+}
+
+/** Pushes a branch to origin, setting upstream. Throws on failure. */
+export async function pushBranch(root: string, branchName: string) {
+  await git(["push", "-u", "origin", branchName], root)
+}
+
+export function normalizeRepositoryUrl(value: string) {
+  const ssh = value.match(/^git@github\.com:(.+?)\/(.+?)(?:\.git)?$/)
+  if (ssh)
+    return `https://github.com/${ssh[1]}/${ssh[2]!.replace(/\.git$/, "")}`
+  return value.replace(/\.git$/, "")
+}
+
+export async function repositoryUrl(
+  root: string,
+  explicitUrl?: string
+): Promise<string> {
+  if (explicitUrl) return normalizeRepositoryUrl(explicitUrl)
+  const origin = await git(["remote", "get-url", "origin"], root)
+  return normalizeRepositoryUrl(origin)
+}

package/src/lib/history.ts

@@ -0,0 +1,272 @@
+import { readFile, rename, writeFile } from "node:fs/promises"
+import { join } from "node:path"
+
+import {
+  localResearchHistoryRecordSchema,
+  type LocalResearchExperimentLoggedRecord,
+  type LocalResearchHistoryRecord,
+} from "../protocol"
+
+import {
+  getProjectTree,
+  resolveProject,
+  type ApiTreeBranch,
+  type ApiTreeExperiment,
+} from "./api"
+import type { Args } from "./args"
+import { onyxStateDir, readOutbox, readState } from "./outbox"
+
+export async function historyPath(root: string) {
+  return join(await onyxStateDir(root), "history.jsonl")
+}
+
+export async function appendHistory(
+  root: string,
+  record: LocalResearchHistoryRecord
+) {
+  const validated = localResearchHistoryRecordSchema.parse(record)
+  await writeFile(await historyPath(root), `${JSON.stringify(validated)}\n`, {
+    encoding: "utf8",
+    flag: "a",
+  })
+}
+
+/**
+ * Reads the local history cache. Corrupt or partially-written lines are
+ * skipped and counted rather than thrown, mirroring the outbox.
+ */
+export async function readHistory(
+  root: string
+): Promise<{ records: LocalResearchHistoryRecord[]; corrupt: number }> {
+  let text = ""
+  try {
+    text = await readFile(await historyPath(root), "utf8")
+  } catch {
+    return { records: [], corrupt: 0 }
+  }
+
+  const records: LocalResearchHistoryRecord[] = []
+  let corrupt = 0
+
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(trimmed)
+    } catch {
+      corrupt += 1
+      continue
+    }
+    const result = localResearchHistoryRecordSchema.safeParse(parsed)
+    if (result.success) {
+      records.push(result.data)
+    } else {
+      corrupt += 1
+    }
+  }
+
+  return { records, corrupt }
+}
+
+/** Atomically replaces the history cache. */
+export async function rewriteHistory(
+  root: string,
+  records: LocalResearchHistoryRecord[]
+) {
+  const path = await historyPath(root)
+  const body = records.map((record) => JSON.stringify(record)).join("\n")
+  const tmp = `${path}.tmp`
+  await writeFile(tmp, body ? `${body}\n` : "", "utf8")
+  await rename(tmp, path)
+}
+
+/** Provisional history record for a just-logged experiment. */
+export function experimentRecordToHistory(
+  record: LocalResearchExperimentLoggedRecord
+): LocalResearchHistoryRecord {
+  return {
+    schemaVersion: 1,
+    source: "local",
+    branchName: record.branchName,
+    gitBranchName: record.gitBranchName,
+    runRef: record.runRef,
+    commitSha: record.commitSha,
+    status: record.status,
+    name: record.name,
+    description: record.description ?? null,
+    primaryMetricName: record.primaryMetricName,
+    primaryMetricValue: record.primaryMetricValue,
+    metrics: record.metrics,
+    agentNotes: record.agentNotes,
+    checks: record.checks ?? null,
+    durationMs: record.durationMs ?? null,
+    outputSummary: record.outputSummary ?? null,
+    startedAt: record.startedAt ?? null,
+    completedAt: record.completedAt ?? null,
+    createdAt: record.createdAt,
+  }
+}
+
+/** Canonical history record from a tree-endpoint experiment DTO. */
+export function apiExperimentToHistory(
+  branch: ApiTreeBranch,
+  experiment: ApiTreeExperiment
+): LocalResearchHistoryRecord | null {
+  const metrics: Record<string, number> = {}
+  for (const [key, value] of Object.entries(experiment.secondaryMetrics)) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      metrics[key] = value
+    }
+  }
+  if (experiment.primaryMetricValue !== null) {
+    metrics[experiment.primaryMetricName] = experiment.primaryMetricValue
+  }
+
+  const result = localResearchHistoryRecordSchema.safeParse({
+    schemaVersion: 1,
+    source: "api",
+    branchName: branch.name,
+    gitBranchName: branch.gitBranchName ?? undefined,
+    runRef: experiment.runRef,
+    commitSha: experiment.commitSha,
+    status: experiment.status,
+    name: experiment.name.slice(0, 160),
+    description: experiment.description?.slice(0, 2000) ?? null,
+    primaryMetricName: experiment.primaryMetricName,
+    primaryMetricValue: experiment.primaryMetricValue,
+    metrics,
+    agentNotes: experiment.agentNotes,
+    checks: experiment.checks
+      ? {
+          status: experiment.checks.status,
+          durationMs: experiment.checks.durationMs,
+          outputSummary: experiment.checks.outputSummary?.slice(0, 4000),
+        }
+      : null,
+    durationMs: experiment.durationMs,
+    outputSummary: experiment.outputSummary?.slice(0, 4000) ?? null,
+    startedAt: experiment.startedAt,
+    completedAt: experiment.completedAt,
+    createdAt: experiment.createdAt,
+    experimentId: experiment.id,
+    branchId: experiment.branchId,
+    sequenceNumber: experiment.sequenceNumber,
+  })
+  return result.success ? result.data : null
+}
+
+/**
+ * Merges canonical API records with still-pending local records. Keyed by
+ * runRef (globally unique: `local/{branch}/{uuid}`); canonical wins so
+ * server-updated statuses (accepted/rejected) replace provisional rows.
+ */
+export function mergeHistory(
+  canonical: LocalResearchHistoryRecord[],
+  localCandidates: LocalResearchHistoryRecord[]
+): LocalResearchHistoryRecord[] {
+  const byRunRef = new Map<string, LocalResearchHistoryRecord>()
+  for (const record of localCandidates) byRunRef.set(record.runRef, record)
+  for (const record of canonical) byRunRef.set(record.runRef, record)
+
+  return [...byRunRef.values()].sort((a, b) => {
+    if (a.branchName !== b.branchName) {
+      return a.branchName < b.branchName ? -1 : 1
+    }
+    // Server-sequenced records first in order; pending local records after.
+    if (a.sequenceNumber !== undefined && b.sequenceNumber !== undefined) {
+      return a.sequenceNumber - b.sequenceNumber
+    }
+    if (a.sequenceNumber !== undefined) return -1
+    if (b.sequenceNumber !== undefined) return 1
+    return a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0
+  })
+}
+
+export type HistorySyncUpdate = {
+  sequenceNumber: number
+  experimentId: string
+  branchId: string
+}
+
+/**
+ * Stamps server-assigned fields onto matching history records right after a
+ * flush, so `onyx listen` and `exp list` show sequence numbers immediately
+ * instead of waiting for the next full hydrate. Matched records become
+ * canonical (`source: "api"`).
+ */
+export async function applyHistorySyncUpdates(
+  root: string,
+  updates: Map<string, HistorySyncUpdate>
+) {
+  if (updates.size === 0) return
+  const { records } = await readHistory(root)
+  let changed = false
+  const next = records.map((record) => {
+    const update = updates.get(record.runRef)
+    if (!update) return record
+    changed = true
+    return {
+      ...record,
+      source: "api" as const,
+      sequenceNumber: update.sequenceNumber,
+      experimentId: update.experimentId,
+      branchId: update.branchId,
+    }
+  })
+  if (changed) await rewriteHistory(root, next)
+}
+
+export type HydrateResult = {
+  experiments: number
+  branches: number
+  pendingLocal: number
+}
+
+/**
+ * Rewrites `.git/onyx/history.jsonl` to the canonical API state, keeping
+ * local records the server doesn't know yet (offline-logged, unflushed).
+ * Throws on network/auth failure; callers treat hydration as best-effort.
+ */
+export async function hydrateHistoryFromApi(
+  root: string,
+  args: Args
+): Promise<HydrateResult> {
+  const state = await readState(root)
+  const projectId = state.projectId ?? (await resolveProject(root, args)).id
+  const tree = await getProjectTree(projectId, args)
+
+  const canonical: LocalResearchHistoryRecord[] = []
+  for (const branch of tree.branches) {
+    for (const experiment of branch.experiments) {
+      const record = apiExperimentToHistory(branch, experiment)
+      if (record) canonical.push(record)
+    }
+  }
+  const canonicalRunRefs = new Set(canonical.map((record) => record.runRef))
+
+  // Local records the server doesn't have yet: provisional history rows plus
+  // anything still queued in the outbox (covers a failed earlier append).
+  const { records: existing } = await readHistory(root)
+  const localCandidates = existing.filter(
+    (record) =>
+      record.source === "local" && !canonicalRunRefs.has(record.runRef)
+  )
+  const seen = new Set(localCandidates.map((record) => record.runRef))
+  const { records: outbox } = await readOutbox(root)
+  for (const record of outbox) {
+    if (record.type !== "experiment_logged") continue
+    if (canonicalRunRefs.has(record.runRef) || seen.has(record.runRef)) continue
+    localCandidates.push(experimentRecordToHistory(record))
+    seen.add(record.runRef)
+  }
+
+  const merged = mergeHistory(canonical, localCandidates)
+  await rewriteHistory(root, merged)
+
+  return {
+    experiments: merged.length,
+    branches: new Set(merged.map((record) => record.branchName)).size,
+    pendingLocal: localCandidates.length,
+  }
+}

package/src/lib/login.ts

@@ -0,0 +1,233 @@
+import { createServer, type Server } from "node:http"
+
+import { runProcess } from "./process"
+
+export async function openBrowser(url: string) {
+  const command =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "cmd"
+        : "xdg-open"
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url]
+  try {
+    const result = await runProcess(command, args)
+    if (result.code === 0) return
+  } catch {
+    // Fall through to printing the URL for headless or minimal systems.
+  }
+  console.log(`Open this URL to log in:\n${url}`)
+}
+
+export type CliLoginResult = {
+  apiKey?: string
+  apiKeyId?: string
+  apiUrl?: string
+  teamId: string
+  teamName: string
+  profileName?: string
+  alreadyConfigured: boolean
+}
+
+const LOGIN_COMPLETE_MESSAGE =
+  "Onyx CLI login complete. You can close this tab."
+
+const ONYX_MARK_SVG = `<svg width="381" height="509" viewBox="0 0 381 509" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"><path d="M381 382.14L233 508.018V424.447L298.75 368.525L190.501 151.379L82.25 368.526L149 425.297V508.867L0 382.14L190.501 0L381 382.14Z" fill="currentColor"/></svg>`
+
+export function cliLoginCompleteHtml() {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Onyx CLI login complete</title>
+  <style>
+    :root {
+      color-scheme: light dark;
+      --background: oklch(0.96 0 0);
+      --foreground: oklch(0.145 0 0);
+      --card: oklch(0.96 0 0);
+      --card-foreground: oklch(0.145 0 0);
+      --muted-foreground: oklch(0.556 0 0);
+      --border: oklch(0.922 0 0);
+    }
+
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --background: oklch(0.145 0 0);
+        --foreground: oklch(0.985 0 0);
+        --card: oklch(0.205 0 0);
+        --card-foreground: oklch(0.985 0 0);
+        --muted-foreground: oklch(0.708 0 0);
+        --border: oklch(1 0 0 / 10%);
+      }
+    }
+
+    * {
+      box-sizing: border-box;
+    }
+
+    body {
+      margin: 0;
+      min-height: 100vh;
+      display: grid;
+      place-items: center;
+      padding: 24px;
+      background: var(--background);
+      color: var(--foreground);
+      font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    }
+
+    main {
+      width: min(100%, 448px);
+    }
+
+    .brand {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      gap: 32px;
+      margin-bottom: 32px;
+      font-size: 48px;
+      line-height: 1;
+      font-weight: 600;
+      letter-spacing: 0;
+    }
+
+    .brand svg {
+      width: 60px;
+      height: 80px;
+      flex: none;
+    }
+
+    .card {
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      background: var(--card);
+      color: var(--card-foreground);
+      padding: 24px;
+      text-align: center;
+      box-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+    }
+
+    h1 {
+      margin: 0;
+      font-size: 16px;
+      line-height: 24px;
+      font-weight: 600;
+      letter-spacing: 0;
+    }
+
+    p {
+      margin: 8px 0 0;
+      color: var(--muted-foreground);
+      font-size: 14px;
+      line-height: 22px;
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <div class="brand">${ONYX_MARK_SVG}<span>Onyx</span></div>
+    <section class="card" aria-labelledby="title">
+      <h1 id="title">${LOGIN_COMPLETE_MESSAGE}</h1>
+      <p>Your CLI profile is ready to use.</p>
+    </section>
+  </main>
+</body>
+</html>`
+}
+
+function closeServer(server: Server) {
+  return new Promise<void>((resolveClose) => {
+    const forceClose = setTimeout(() => {
+      server.closeAllConnections()
+      resolveClose()
+    }, 1_000)
+    forceClose.unref()
+
+    server.close(() => {
+      clearTimeout(forceClose)
+      resolveClose()
+    })
+    server.closeIdleConnections()
+  })
+}
+
+export async function waitForCliLogin({
+  port,
+  state,
+  timeoutMs,
+}: {
+  port: number
+  state: string
+  timeoutMs: number
+}): Promise<CliLoginResult> {
+  let server: Server | null = null
+  let timeout: ReturnType<typeof setTimeout> | null = null
+  const login = new Promise<CliLoginResult>((resolveLogin, reject) => {
+    server = createServer((request, response) => {
+      response.setHeader("connection", "close")
+      response.on("finish", () => request.socket.destroy())
+
+      const url = new URL(request.url ?? "/", `http://127.0.0.1:${port}`)
+      if (url.pathname !== "/callback") {
+        response.writeHead(404).end("Not found")
+        return
+      }
+
+      if (url.searchParams.get("state") !== state) {
+        response.writeHead(400).end("Invalid state")
+        reject(new Error("Login callback returned an invalid state."))
+        return
+      }
+
+      const teamId = url.searchParams.get("team_id")
+      const teamName = url.searchParams.get("team_name")
+      if (!teamId || !teamName) {
+        response.writeHead(400).end("Missing team")
+        reject(new Error("Login callback did not include a team."))
+        return
+      }
+
+      const alreadyConfigured =
+        url.searchParams.get("already_configured") === "true"
+      const key = url.searchParams.get("api_key")
+      if (!alreadyConfigured && !key) {
+        response.writeHead(400).end("Missing API key")
+        reject(new Error("Login callback did not include an API key."))
+        return
+      }
+
+      response
+        .writeHead(200, { "content-type": "text/html; charset=utf-8" })
+        .end(cliLoginCompleteHtml())
+      resolveLogin({
+        apiKey: key ?? undefined,
+        apiKeyId: url.searchParams.get("api_key_id") ?? undefined,
+        apiUrl: url.searchParams.get("api_url") ?? undefined,
+        teamId,
+        teamName,
+        profileName: url.searchParams.get("profile_name") ?? undefined,
+        alreadyConfigured,
+      })
+    })
+    server.listen(port, "127.0.0.1")
+  })
+
+  try {
+    return await Promise.race([
+      login,
+      new Promise<never>((_, reject) => {
+        timeout = setTimeout(
+          () => reject(new Error("Timed out waiting for browser login.")),
+          timeoutMs
+        )
+        timeout.unref()
+      }),
+    ])
+  } finally {
+    if (timeout) clearTimeout(timeout)
+    if (server) await closeServer(server)
+  }
+}

package/src/lib/markdown.ts

@@ -0,0 +1,148 @@
+import { readFile, writeFile } from "node:fs/promises"
+
+import { currentBranch, nameFromGitBranch } from "./git"
+import { readState } from "./outbox"
+import { branchStateKey, onyxPath } from "./project"
+
+export type MetricDirection = "maximize" | "minimize"
+
+export type BranchMetadata = {
+  name: string
+  description: string | null
+  gitBranchName: string
+  baseCommitSha: string | null
+  metricName: string
+  metricUnit: string | null
+  metricDirection: MetricDirection
+}
+
+export async function resolveBranchName(root: string, branchOption?: string) {
+  if (branchOption) return branchOption
+
+  const gitBranchName = await currentBranch(root)
+  const name = nameFromGitBranch(gitBranchName)
+  if (name) return name
+
+  throw new Error("Missing --branch and no local onyx/* branch is checked out.")
+}
+
+function markdownField(section: string, name: string) {
+  return section.match(new RegExp(`^${name}:\\s*(.*)$`, "m"))?.[1]?.trim()
+}
+
+async function branchFromMarkdown({
+  root,
+  projectPath,
+  name,
+  gitBranchName,
+}: {
+  root: string
+  projectPath: string
+  name: string
+  gitBranchName: string
+}): Promise<BranchMetadata | null> {
+  let text = ""
+  try {
+    text = await readFile(onyxPath(root, projectPath, "onyx.md"), "utf8")
+  } catch {
+    return null
+  }
+
+  const start = text.indexOf(`### ${name}`)
+  if (start === -1) return null
+  const rest = text.slice(start)
+  const next = rest.slice(1).search(/\n###\s+/)
+  const section = next === -1 ? rest : rest.slice(0, next + 1)
+  const metricName = markdownField(section, "Metric") || "score"
+  const unit = markdownField(section, "Unit")
+  const direction = markdownField(section, "Direction")
+  const baseCommitSha = markdownField(section, "Base commit")
+
+  return {
+    name,
+    description: markdownField(section, "Description") || null,
+    gitBranchName,
+    baseCommitSha: baseCommitSha || null,
+    metricName,
+    metricUnit: unit || null,
+    metricDirection: direction === "minimize" ? "minimize" : "maximize",
+  }
+}
+
+export async function branchMetadata({
+  root,
+  projectPath,
+  branchName,
+  gitBranchName,
+}: {
+  root: string
+  projectPath: string
+  branchName: string
+  gitBranchName: string
+}): Promise<BranchMetadata> {
+  const state = await readState(root)
+  const stored = state.branches[branchStateKey(projectPath, branchName)]
+  if (stored?.metricName) {
+    return {
+      name: branchName,
+      description: stored.description ?? null,
+      gitBranchName: stored.gitBranchName ?? gitBranchName,
+      baseCommitSha: stored.baseCommitSha ?? null,
+      metricName: stored.metricName,
+      metricUnit: stored.metricUnit ?? null,
+      metricDirection:
+        stored.metricDirection === "minimize" ? "minimize" : "maximize",
+    }
+  }
+
+  return (
+    (await branchFromMarkdown({
+      root,
+      projectPath,
+      name: branchName,
+      gitBranchName,
+    })) ?? {
+      name: branchName,
+      description: null,
+      gitBranchName,
+      baseCommitSha: null,
+      metricName: "score",
+      metricUnit: null,
+      metricDirection: "maximize",
+    }
+  )
+}
+
+export async function appendBranchToMarkdown({
+  root,
+  projectPath,
+  name,
+  description,
+  baseCommitSha,
+  metricName,
+  metricUnit,
+  metricDirection,
+}: {
+  root: string
+  projectPath: string
+  name: string
+  description?: string | null
+  baseCommitSha?: string | null
+  metricName: string
+  metricUnit?: string | null
+  metricDirection: MetricDirection
+}) {
+  const file = onyxPath(root, projectPath, "onyx.md")
+  const marker = `### ${name}`
+  let text = ""
+  try {
+    text = await readFile(file, "utf8")
+  } catch {
+    return
+  }
+
+  if (text.includes(marker)) return
+
+  const addition = `\n### ${name}\n\nDescription: ${description ?? ""}\n\nMetric: ${metricName}\nUnit: ${metricUnit ?? ""}\nDirection: ${metricDirection}\nBase commit: ${baseCommitSha ?? ""}\n\nPlan:\n\nSuccess criteria:\n\nNext to try:\n\n- Add hypotheses here as a queue. Each iteration pops one and appends a row to Attempts.\n\nAttempts:\n\n| commit | hypothesis | metric | status | learning |\n| ------ | ---------- | ------ | ------ | -------- |\n`
+  await writeFile(file, `${text.trimEnd()}\n${addition}`, "utf8")
+}