@onyx-robotics/agent 0.1.0

package/src/commands/sync.ts

@@ -0,0 +1,88 @@
+import type { Args } from "../lib/args"
+import { requestProjectSync, resolveProject } from "../lib/api"
+import { emitEvent } from "../lib/events"
+import { currentBranch, pushBranch, repoRoot } from "../lib/git"
+import { hydrateHistoryFromApi } from "../lib/history"
+import { readLastRun, readOutbox } from "../lib/outbox"
+import { resolveProjectPath } from "../lib/project"
+import { flushOutbox } from "../lib/sync"
+
+export async function commandPush(args: Args) {
+  const root = await repoRoot()
+  const branchName = await currentBranch(root)
+  if (!branchName) throw new Error("Cannot push from a detached HEAD.")
+  await pushBranch(root, branchName)
+  await emitEvent(root, { type: "pushed", message: branchName })
+  console.log(`Pushed ${branchName}`)
+  await flushOutbox(root, args)
+}
+
+export async function commandSync(args: Args) {
+  const root = await repoRoot()
+  const result = await flushOutbox(root, args)
+  if (result.offline) return
+
+  // Refresh the local history cache to the canonical API state. Runs even
+  // when the outbox was empty so fresh clones pick up cross-branch history.
+  try {
+    const hydrated = await hydrateHistoryFromApi(root, args)
+    console.log(
+      `history: ${hydrated.experiments} experiment(s) across ${hydrated.branches} branch(es)${
+        hydrated.pendingLocal ? `, ${hydrated.pendingLocal} pending local` : ""
+      }`
+    )
+  } catch (error) {
+    console.warn(
+      `History refresh skipped: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    )
+  }
+
+  // Warm the server mirror so file/diff views stay fast.
+  try {
+    const project = await resolveProject(root, args)
+    await requestProjectSync(project.id, args)
+    console.log(`Requested mirror refresh for project ${project.id}`)
+  } catch (error) {
+    console.warn(
+      `Mirror refresh skipped: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    )
+  }
+}
+
+export async function commandStatus(args: Args) {
+  const root = await repoRoot()
+  const projectPath = await resolveProjectPath(root, args)
+  const branchName = await currentBranch(root)
+  const { records, corrupt } = await readOutbox(root)
+  const lastRun = await readLastRun(root)
+  const experiments = records.filter(
+    (record) => record.type === "experiment_logged"
+  ).length
+  const branches = records.filter(
+    (record) => record.type === "branch_started"
+  ).length
+
+  console.log(`branch: ${branchName || "(detached)"}`)
+  console.log(`projectPath: ${projectPath || "(repo root)"}`)
+  console.log(
+    `outbox: ${experiments} experiment(s), ${branches} branch(es) pending${
+      corrupt ? `, ${corrupt} unreadable` : ""
+    }`
+  )
+  if (lastRun) {
+    console.log(
+      `last run: ${lastRun.commitSha.slice(0, 7)} (${lastRun.status}, ${lastRun.primaryMetricName}=${lastRun.primaryMetricValue ?? "null"})`
+    )
+  }
+
+  try {
+    const project = await resolveProject(root, args)
+    console.log(`project: ${project.name} (${project.id})`)
+  } catch {
+    console.log("project: not linked / offline")
+  }
+}

package/src/install.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test"
+
+async function dryRun(os: string, arch: string) {
+  const process = Bun.spawn(["sh", "scripts/install.sh"], {
+    cwd: import.meta.dir + "/..",
+    env: {
+      ...Bun.env,
+      ONYX_INSTALL_DRY_RUN: "1",
+      ONYX_INSTALL_OS: os,
+      ONYX_INSTALL_ARCH: arch,
+    },
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  const stdout = await new Response(process.stdout).text()
+  const stderr = await new Response(process.stderr).text()
+  const code = await process.exited
+  if (code !== 0) {
+    throw new Error(stderr || stdout)
+  }
+  return stdout
+}
+
+describe("install script", () => {
+  test("maps macOS arm64 to the darwin arm64 asset", async () => {
+    const output = await dryRun("Darwin", "arm64")
+
+    expect(output).toContain("target=darwin-arm64")
+    expect(output).toContain("asset=onyx-darwin-arm64")
+  })
+
+  test("maps Linux x64 to the baseline asset", async () => {
+    const output = await dryRun("Linux", "x86_64")
+
+    expect(output).toContain("target=linux-x64-baseline")
+    expect(output).toContain("asset=onyx-linux-x64-baseline")
+  })
+})

package/src/lib/api.ts

@@ -0,0 +1,227 @@
+import type {
+  CreateResearchExperimentRequest,
+  CreateResearchBranchRequest,
+} from "../protocol"
+
+import type { Args } from "./args"
+import { apiBaseUrl, apiKey } from "./config"
+import { normalizeRepositoryUrl, repositoryUrl } from "./git"
+import { resolveProjectPath } from "./project"
+
+export type ApiProject = {
+  id: string
+  name: string
+  repositoryUrl: string
+  repositoryFullName: string | null
+  defaultBranch: string
+  projectPath: string
+}
+
+export type ApiBranch = {
+  id: string
+  name: string
+  gitBranchName: string | null
+}
+
+export type ApiExperiment = {
+  id: string
+  sequenceNumber: number
+  runRef: string
+  commitSha: string
+  status: string
+  primaryMetricName: string
+  primaryMetricValue: number | null
+}
+
+export type ApiTreeExperiment = ApiExperiment & {
+  branchId: string
+  name: string
+  description: string | null
+  secondaryMetrics: Record<string, unknown>
+  agentNotes: Record<string, unknown>
+  checks: {
+    status: "passed" | "failed" | "timed_out"
+    durationMs: number | null
+    outputSummary: string | null
+  } | null
+  durationMs: number | null
+  outputSummary: string | null
+  startedAt: string | null
+  completedAt: string | null
+  createdAt: string
+}
+
+export type ApiTreeBranch = ApiBranch & {
+  experiments: ApiTreeExperiment[]
+}
+
+export type ApiProjectTree = {
+  project: ApiProject
+  branches: ApiTreeBranch[]
+}
+
+export async function callApi(
+  method: string,
+  path: string,
+  body?: unknown,
+  args?: Args
+) {
+  const response = await fetch(`${await apiBaseUrl(args)}${path}`, {
+    method,
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${await apiKey(args)}`,
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  })
+
+  const text = await response.text()
+  let payload: unknown = null
+  try {
+    payload = text ? JSON.parse(text) : null
+  } catch {
+    payload = text
+  }
+
+  if (!response.ok) {
+    throw new ApiError(method, path, response.status, payload)
+  }
+
+  return payload
+}
+
+export class ApiError extends Error {
+  status: number
+
+  constructor(method: string, path: string, status: number, payload: unknown) {
+    super(
+      `${method} ${path} failed (${status}): ${
+        typeof payload === "string" ? payload : JSON.stringify(payload)
+      }`
+    )
+    this.name = "ApiError"
+    this.status = status
+  }
+}
+
+export function apiData<T>(payload: unknown): T {
+  if (!payload || typeof payload !== "object" || !("data" in payload)) {
+    throw new Error(`Unexpected API response: ${JSON.stringify(payload)}`)
+  }
+  return (payload as { data: T }).data
+}
+
+/**
+ * Resolves the linked Onyx project for this repository by matching the origin
+ * URL + projectPath against the team's projects (or an explicit --project id).
+ * Throws when nothing matches so callers can keep work queued in the outbox.
+ */
+export async function resolveProject(
+  root: string,
+  args: Args
+): Promise<ApiProject> {
+  const projectPath = await resolveProjectPath(root, args)
+  const projects = apiData<ApiProject[]>(
+    await callApi("GET", "/api/v1/research/projects", undefined, args)
+  )
+
+  if (args.options.project) {
+    const byId = projects.find(
+      (candidate) => candidate.id === args.options.project
+    )
+    if (byId) return byId
+    return {
+      id: args.options.project,
+      name: args.options.project,
+      repositoryUrl: "",
+      repositoryFullName: null,
+      defaultBranch: "main",
+      projectPath,
+    }
+  }
+
+  const url = normalizeRepositoryUrl(
+    await repositoryUrl(root, args.options["repository-url"])
+  )
+  const project = projects.find(
+    (candidate) =>
+      normalizeRepositoryUrl(candidate.repositoryUrl) === url &&
+      candidate.projectPath === projectPath
+  )
+
+  if (!project) {
+    throw new Error(
+      "No linked Onyx project matched this repository. Link the repo in Onyx first."
+    )
+  }
+
+  return project
+}
+
+export async function listProjectBranches(
+  projectId: string,
+  args?: Args
+): Promise<ApiBranch[]> {
+  return apiData<ApiBranch[]>(
+    await callApi(
+      "GET",
+      `/api/v1/research/projects/${projectId}/branches`,
+      undefined,
+      args
+    )
+  )
+}
+
+/** Full project hierarchy (branches + experiments) for history hydration. */
+export async function getProjectTree(
+  projectId: string,
+  args?: Args
+): Promise<ApiProjectTree> {
+  return apiData<ApiProjectTree>(
+    await callApi(
+      "GET",
+      `/api/v1/research/projects/${projectId}/tree`,
+      undefined,
+      args
+    )
+  )
+}
+
+export async function upsertBranch(
+  projectId: string,
+  body: CreateResearchBranchRequest,
+  args?: Args
+): Promise<ApiBranch> {
+  return apiData<ApiBranch>(
+    await callApi(
+      "POST",
+      `/api/v1/research/projects/${projectId}/branches`,
+      body,
+      args
+    )
+  )
+}
+
+export async function reportExperiment(
+  branchId: string,
+  body: CreateResearchExperimentRequest,
+  args?: Args
+): Promise<ApiExperiment> {
+  return apiData<ApiExperiment>(
+    await callApi(
+      "POST",
+      `/api/v1/research/branches/${branchId}/experiments`,
+      body,
+      args
+    )
+  )
+}
+
+export async function requestProjectSync(projectId: string, args?: Args) {
+  await callApi(
+    "POST",
+    `/api/v1/research/projects/${projectId}/sync`,
+    undefined,
+    args
+  )
+}

package/src/lib/args.ts

@@ -0,0 +1,68 @@
+export type Args = {
+  positional: string[]
+  options: Record<string, string>
+}
+
+export function parseArgs(argv: string[]): Args {
+  const positional: string[] = []
+  const options: Record<string, string> = {}
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i]!
+    if (!token.startsWith("--")) {
+      positional.push(token)
+      continue
+    }
+
+    const key = token.slice(2)
+    const eq = key.indexOf("=")
+
+    if (eq !== -1) {
+      options[key.slice(0, eq)] = key.slice(eq + 1)
+      continue
+    }
+
+    const next = argv[i + 1]
+    if (next === undefined || next.startsWith("--")) {
+      options[key] = "true"
+    } else {
+      options[key] = next
+      i += 1
+    }
+  }
+
+  return { positional, options }
+}
+
+export function requireOption(args: Args, name: string): string {
+  const value = args.options[name]
+  if (!value) {
+    throw new Error(`Missing required --${name}`)
+  }
+  return value
+}
+
+export function optionalFlag(args: Args, name: string) {
+  return args.options[name] === "true"
+}
+
+export function normalizeName(value: string) {
+  return value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}
+
+export function nameOption(args: Args) {
+  const value = args.options.name
+  if (!value) throw new Error("Missing required --name")
+  const name = normalizeName(value)
+  if (!name)
+    throw new Error("--name must contain at least one letter or number")
+  return name
+}
+
+export function descriptionOption(args: Args): string | null {
+  return args.options.description ?? null
+}

package/src/lib/config.ts

@@ -0,0 +1,148 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+import type { Args } from "./args"
+
+const CONFIG_FILE = "config.json"
+export const DEFAULT_API_URL = "https://app.onyxresearch.ai"
+
+export type CliProfile = {
+  apiUrl: string
+  apiKey?: string
+  apiKeyId?: string
+  apiKeyEnv?: string
+  teamId: string
+  teamName: string
+  updatedAt: string
+}
+
+export type Config = {
+  profiles: Record<string, CliProfile>
+  currentProfile: string
+}
+
+export function emptyConfig(): Config {
+  return {
+    profiles: {},
+    currentProfile: "",
+  }
+}
+
+export function configDir() {
+  return process.env.XDG_CONFIG_HOME
+    ? join(process.env.XDG_CONFIG_HOME, "onyx")
+    : join(homedir(), ".config", "onyx")
+}
+
+export function configPath() {
+  return join(configDir(), CONFIG_FILE)
+}
+
+export async function readConfig(): Promise<Config> {
+  try {
+    const parsed = JSON.parse(
+      await readFile(configPath(), "utf8")
+    ) as Partial<Config>
+
+    return {
+      profiles: parsed.profiles ?? {},
+      currentProfile: parsed.currentProfile ?? "",
+    }
+  } catch {
+    return emptyConfig()
+  }
+}
+
+export async function writeConfig(config: Config) {
+  await mkdir(configDir(), { recursive: true })
+  await writeFile(configPath(), `${JSON.stringify(config, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  })
+}
+
+export function normalizeProfileName(value: string) {
+  return value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}
+
+function profileNameFromArgs(args: Args | undefined, config: Config) {
+  return args?.options.profile ?? config.currentProfile
+}
+
+async function selectedProfileEntry(args?: Args): Promise<{
+  name: string
+  profile: CliProfile
+}> {
+  const config = await readConfig()
+  const profileName = profileNameFromArgs(args, config)
+
+  if (!profileName) {
+    throw new Error(
+      "No Onyx CLI profile selected. Run `onyx login` or set ONYX_API_KEY."
+    )
+  }
+
+  const profile = config.profiles[profileName]
+  if (!profile) {
+    throw new Error(
+      `Unknown Onyx CLI profile "${profileName}". Run \`onyx profile list\`.`
+    )
+  }
+
+  return { name: profileName, profile }
+}
+
+export async function selectedProfile(args?: Args): Promise<CliProfile> {
+  return (await selectedProfileEntry(args)).profile
+}
+
+export async function apiBaseUrl(
+  args?: Args,
+  options?: { allowDefault?: boolean }
+) {
+  if (args?.options["api-url"]) return args.options["api-url"]
+  if (process.env.ONYX_API_URL) return process.env.ONYX_API_URL
+
+  const config = await readConfig()
+  const profileName = profileNameFromArgs(args, config)
+  const profile = profileName ? config.profiles[profileName] : undefined
+
+  if (profile) return profile.apiUrl
+  if (process.env.ONYX_API_KEY) return DEFAULT_API_URL
+  if (options?.allowDefault) return DEFAULT_API_URL
+
+  if (profileName) {
+    throw new Error(
+      `Unknown Onyx CLI profile "${profileName}". Run \`onyx profile list\`.`
+    )
+  }
+
+  throw new Error(
+    "No Onyx CLI profile selected. Run `onyx login` or set ONYX_API_URL."
+  )
+}
+
+export async function apiKey(args?: Args) {
+  if (process.env.ONYX_API_KEY) return process.env.ONYX_API_KEY
+
+  const { name, profile } = await selectedProfileEntry(args)
+  if (profile.apiKeyEnv) {
+    const value = process.env[profile.apiKeyEnv]
+    if (value?.trim()) return value
+
+    throw new Error(
+      `Profile "${name}" expects API key in ${profile.apiKeyEnv}, but that environment variable is not set or empty.`
+    )
+  }
+
+  if (profile.apiKey) return profile.apiKey
+
+  throw new Error(
+    `Profile "${name}" has no API key. Run \`onyx login --refresh\` or \`onyx profile set-api-key-env ${name} <ENV_VAR>\`.`
+  )
+}

package/src/lib/events.ts

@@ -0,0 +1,97 @@
+import { readFile, rename, stat, writeFile } from "node:fs/promises"
+import { join } from "node:path"
+
+import {
+  localResearchEventSchema,
+  type LocalResearchEvent,
+  type LocalResearchEventType,
+} from "../protocol"
+
+import { onyxStateDir } from "./outbox"
+
+const TRUNCATE_BYTES = 256 * 1024
+const TRUNCATE_KEEP = 500
+
+export async function eventsPath(root: string) {
+  return join(await onyxStateDir(root), "events.jsonl")
+}
+
+/**
+ * Appends a local activity event for `onyx listen`. Strictly best-effort:
+ * never throws, so a broken feed can never fail a command.
+ */
+export async function emitEvent(
+  root: string,
+  event: {
+    type: LocalResearchEventType
+    branchName?: string
+    commitSha?: string
+    message?: string
+  }
+): Promise<void> {
+  try {
+    const validated = localResearchEventSchema.parse({
+      schemaVersion: 1,
+      ts: new Date().toISOString(),
+      ...event,
+    })
+    const path = await eventsPath(root)
+    await writeFile(path, `${JSON.stringify(validated)}\n`, {
+      encoding: "utf8",
+      flag: "a",
+    })
+    await truncateEvents(root)
+  } catch {
+    // Activity feed is observational only.
+  }
+}
+
+/**
+ * Reads activity events, skipping corrupt lines. `tail` limits parsing to the
+ * last N lines so the listener stays cheap as the feed grows.
+ */
+export async function readEvents(
+  root: string,
+  options: { tail?: number } = {}
+): Promise<LocalResearchEvent[]> {
+  let text = ""
+  try {
+    text = await readFile(await eventsPath(root), "utf8")
+  } catch {
+    return []
+  }
+
+  let lines = text.split("\n")
+  if (options.tail !== undefined) lines = lines.slice(-options.tail - 1)
+
+  const events: LocalResearchEvent[] = []
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    try {
+      const result = localResearchEventSchema.safeParse(JSON.parse(trimmed))
+      if (result.success) events.push(result.data)
+    } catch {
+      // skip corrupt line
+    }
+  }
+  return events
+}
+
+/** Atomically trims the feed to the most recent events once it grows large. */
+export async function truncateEvents(root: string, keep = TRUNCATE_KEEP) {
+  const path = await eventsPath(root)
+  try {
+    const { size } = await stat(path)
+    if (size <= TRUNCATE_BYTES) return
+    const lines = (await readFile(path, "utf8"))
+      .split("\n")
+      .filter((line) => line.trim())
+    if (lines.length <= keep) return
+    const tmp = `${path}.tmp`
+    await writeFile(tmp, `${lines.slice(-keep).join("\n")}\n`, "utf8")
+    await rename(tmp, path)
+  } catch {
+    // best-effort
+  }
+}