@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/agent-codex-instructions.ts

@@ -1,309 +0,0 @@
-/**
- * Agent codex-instructions materialization.
- *
- * Projects the synced HQ agent overlay into `~/.codex/AGENTS.md` — the codex
- * GLOBAL instruction file, which `codex exec` natively merges on every run
- * (alongside the project `AGENTS.md`, which on an HQ box symlinks to the
- * `.claude/CLAUDE.md` charter). This is the codex mirror of how Claude reads
- * `~/.claude/CLAUDE.md`: it carries the agent OPERATING CONTRACT (build your
- * own tools, resolve credentials via group grants, follow team policy, the
- * safety boundary) on top of the generic HQ charter.
- *
- * Why here (the sync runner), and why this file:
- *   - DURABLE: `~/.codex/AGENTS.md` lives OUTSIDE the hq-root, so `hq rescue`
- *     (`--hq-root`) and core upgrades never touch it. (In-tree `AGENTS.md` is
- *     classified regenerable and silently overwritten by rescue.)
- *   - SCALABLE: every agent box runs `@indigoai-us/hq-cloud@latest`
- *     `hq-sync-runner` each cycle, so shipping the projection here reaches the
- *     whole fleet — new and existing agents — with no reprovision or SSM push.
- *   - AGENT-ONLY: the caller gates on `custom:entityType === "agent"`, so a
- *     human running `hq sync` never materializes this file.
- *
- * Trust + isolation boundary (where it is actually enforced):
- *   - Tenant isolation is enforced UPSTREAM at the sync boundary: an agent's
- *     `--personal` sync resolves the agent's OWN vault (`pickAgentSelfEntity`,
- *     server-authorized by the agent's machine JWT). This function trusts that
- *     `hqRoot/personal/` was populated by that agent-scoped sync; it does not
- *     re-fetch entity membership (the gate claim is the SAME one the runner
- *     already trusts for `--personal` resolution; tampering it requires local
- *     compromise of the 0o600 token cache, i.e. the box is already owned).
- *   - DEFENCE-IN-DEPTH against a tampered local tree: every read is restricted
- *     to REGULAR files (symlinks/dirs are skipped), so a planted symlink in the
- *     overlay can't exfiltrate arbitrary files into `~/.codex/AGENTS.md`.
- *   - The projection NEVER reads release-shipped `core/` content — the charter
- *     reaches codex via the project `AGENTS.md` symlink, not this file.
- *
- * Deployment assumption: ONE agent identity per machine (the EC2 agent box
- * model). `~/.codex/AGENTS.md` is a single, non-namespaced path; multiple agent
- * identities sharing one OS home would last-write-wins. Not a concern in the
- * one-agent-per-box fleet; revisit (per-agent namespacing) if that changes.
- */
-import * as crypto from "crypto";
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-
-/** hq-root-relative location of the (locally-written) agent identity briefing. */
-export const AGENTS_PROFILE_REL = "personal/agents-profile.md";
-
-/** hq-root-relative dir holding the synced agent-capability overlay docs. */
-export const AGENT_CAPABILITIES_REL =
-  "personal/knowledge/public/agent-capabilities";
-
-/** The capability doc carrying the operating contract — ordered first. */
-export const AGENT_CONTRACT_FILE = "hq-agent-contract.md";
-
-/** Leading marker so the file is self-describing and recognizable as generated. */
-export const CODEX_AGENTS_MARKER =
-  "<!-- hq-agent: generated by hq-sync-runner";
-
-export interface CodexSection {
-  /** hq-root-relative source path (for diagnostics; not written to the file). */
-  name: string;
-  content: string;
-}
-
-/**
- * Pure: compose the codex global `AGENTS.md` body from ordered sections.
- * Trims and drops empty/whitespace-only sections. Returns "" when nothing
- * substantive remains, so the caller can SKIP the write (never emit an
- * empty/marker-only file, never wipe a previously-materialized one).
- *
- * Deliberately carries NO timestamp: the output is a deterministic projection
- * of its inputs, so a no-change sync rewrites byte-identical content (no churn;
- * the write/skip/error events are timestamped in the diagnostic log instead).
- */
-export function composeCodexAgentsMd(sections: CodexSection[]): string {
-  const body = sections
-    .map((s) => s.content.trim())
-    .filter((c) => c.length > 0)
-    .join("\n\n");
-  if (body.length === 0) return "";
-  const header =
-    `${CODEX_AGENTS_MARKER} from the synced HQ agent overlay. ` +
-    `Do not edit by hand — regenerated on every agent sync. ` +
-    `Source: ${AGENTS_PROFILE_REL} + ${AGENT_CAPABILITIES_REL}/*.md -->`;
-  return `${header}\n\n${body}\n`;
-}
-
-/**
- * Pure: order capability filenames — the operating contract first, then the
- * remaining `*.md` alphabetically. Non-markdown entries are dropped.
- */
-export function orderCapabilityFiles(files: string[]): string[] {
-  const md = files.filter((f) => f.endsWith(".md")).sort();
-  const contractFirst = md.filter((f) => f === AGENT_CONTRACT_FILE);
-  const rest = md.filter((f) => f !== AGENT_CONTRACT_FILE);
-  return [...contractFirst, ...rest];
-}
-
-/** True iff `p` exists and is a REGULAR file (symlinks/dirs/etc. → false). */
-function isRegularFile(p: string): boolean {
-  try {
-    return fs.lstatSync(p).isFile();
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Read `p` only when it is a regular file (best-effort, never throws). lstat
- * gates the read so a symlink is never followed — a planted symlink in the
- * overlay cannot exfiltrate an out-of-tree file into the materialized output.
- */
-function readRegularFileIfPresent(p: string): string | null {
-  if (!isRegularFile(p)) return null;
-  try {
-    const s = fs.readFileSync(p, "utf8");
-    return s.trim().length > 0 ? s : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * IO: gather the agent overlay sections present under `hqRoot`. Order:
- *   1. identity briefing (`personal/agents-profile.md`)
- *   2. the operating contract (`agent-capabilities/hq-agent-contract.md`)
- *   3. any other `agent-capabilities/*.md`, alphabetically
- * Each is included only when it is a regular file and non-whitespace-only.
- * Symlinks and directories are skipped (containment / no symlink-escape).
- */
-export function gatherCodexAgentSections(hqRoot: string): CodexSection[] {
-  const sections: CodexSection[] = [];
-
-  const profile = readRegularFileIfPresent(path.join(hqRoot, AGENTS_PROFILE_REL));
-  if (profile) sections.push({ name: AGENTS_PROFILE_REL, content: profile });
-
-  const capDir = path.join(hqRoot, AGENT_CAPABILITIES_REL);
-  // Reject a symlinked capability DIR (only descend into a real directory).
-  let capDirIsRealDir = false;
-  try {
-    capDirIsRealDir = fs.lstatSync(capDir).isDirectory();
-  } catch {
-    capDirIsRealDir = false;
-  }
-  if (capDirIsRealDir) {
-    let entries: string[] = [];
-    try {
-      entries = fs.readdirSync(capDir);
-    } catch {
-      entries = [];
-    }
-    for (const f of orderCapabilityFiles(entries)) {
-      const content = readRegularFileIfPresent(path.join(capDir, f));
-      if (content) {
-        sections.push({ name: `${AGENT_CAPABILITIES_REL}/${f}`, content });
-      }
-    }
-  }
-  return sections;
-}
-
-export interface MaterializeLog {
-  (e: {
-    event: string;
-    message: string;
-    err?: unknown;
-    context?: Record<string, unknown>;
-  }): void;
-}
-
-export interface MaterializeResult {
-  written: boolean;
-  path: string;
-  sectionCount: number;
-  skippedReason?: "empty-overlay" | "target-not-regular-file" | "error";
-}
-
-/**
- * Resolve the codex home dir. Honors `CODEX_HOME` only when it is an ABSOLUTE
- * path with no `..` traversal; otherwise falls back to `~/.codex` (an injected
- * relative/traversing value must not redirect the write off-target).
- */
-export function codexHomeDir(): string {
-  const env = process.env.CODEX_HOME?.trim();
-  if (env && path.isAbsolute(env) && !env.split(path.sep).includes("..")) {
-    return env;
-  }
-  return path.join(os.homedir(), ".codex");
-}
-
-/**
- * Best-effort: project the synced agent overlay into `~/.codex/AGENTS.md`.
- * Idempotent atomic rewrite (write entropy-named temp + rename). NEVER throws —
- * logs and returns a result.
- *
- * Non-destructive guarantees:
- *   - SKIPS (no write, no delete) when the overlay yields no content, so a
- *     transient empty/unsynced tree can never wipe a previously-materialized
- *     file. (Emits a distinct event when a prior file exists — a possible
- *     provisioning regression worth an operator's eye.)
- *   - SKIPS when the target already exists but is NOT a regular file (a symlink
- *     or directory), rather than silently clobbering an external config
- *     relationship (or failing opaquely with EISDIR).
- *   - On any write/rename failure, the entropy-named temp file is cleaned up so
- *     repeated failures can't accumulate `*.hq-tmp` orphans.
- *
- * First boot: before the first `--personal` sync lands, the overlay is absent
- * and this skips — the agent operates on the project `AGENTS.md` (charter)
- * alone until the first sync materializes the contract (~one cycle).
- */
-export function materializeCodexAgents(opts: {
-  hqRoot: string;
-  codexHome?: string;
-  log?: MaterializeLog;
-}): MaterializeResult {
-  const codexHome = opts.codexHome ?? codexHomeDir();
-  const target = path.join(codexHome, "AGENTS.md");
-  const log = opts.log ?? (() => {});
-  try {
-    const sections = gatherCodexAgentSections(opts.hqRoot);
-    const body = composeCodexAgentsMd(sections);
-
-    if (body.length === 0) {
-      const targetExists = (() => {
-        try {
-          fs.lstatSync(target);
-          return true;
-        } catch {
-          return false;
-        }
-      })();
-      log({
-        // A pre-existing target + now-empty overlay is a likely regression
-        // (broken provisioning / seed), distinct from a clean first-boot skip.
-        event: targetExists
-          ? "runner.agent_codex_instructions.skipped_empty_target_exists"
-          : "runner.agent_codex_instructions.skipped",
-        message:
-          "no agent overlay content found; leaving ~/.codex/AGENTS.md untouched",
-        context: { target, targetExists },
-      });
-      return {
-        written: false,
-        path: target,
-        sectionCount: 0,
-        skippedReason: "empty-overlay",
-      };
-    }
-
-    // Refuse to clobber a non-regular target (symlink / directory): preserve an
-    // external config relationship + surface EISDIR-class problems distinctly.
-    let targetStat: fs.Stats | null = null;
-    try {
-      targetStat = fs.lstatSync(target);
-    } catch {
-      targetStat = null; // absent — fine, we create it
-    }
-    if (targetStat && !targetStat.isFile()) {
-      log({
-        event: "runner.agent_codex_instructions.config_error",
-        message:
-          "~/.codex/AGENTS.md exists but is not a regular file (symlink or directory); refusing to overwrite",
-        context: {
-          target,
-          isSymbolicLink: targetStat.isSymbolicLink(),
-          isDirectory: targetStat.isDirectory(),
-        },
-      });
-      return {
-        written: false,
-        path: target,
-        sectionCount: sections.length,
-        skippedReason: "target-not-regular-file",
-      };
-    }
-
-    fs.mkdirSync(codexHome, { recursive: true, mode: 0o700 });
-    const tmp = `${target}.${process.pid}.${crypto
-      .randomBytes(6)
-      .toString("hex")}.hq-tmp`;
-    try {
-      fs.writeFileSync(tmp, body, { mode: 0o600 });
-      fs.renameSync(tmp, target);
-    } catch (writeErr) {
-      // Clean up the orphaned temp so repeated failures don't accumulate.
-      try {
-        fs.unlinkSync(tmp);
-      } catch {
-        /* best-effort */
-      }
-      throw writeErr;
-    }
-    log({
-      event: "runner.agent_codex_instructions.written",
-      message: `materialized codex global AGENTS.md from ${sections.length} overlay section(s)`,
-      context: { target, sectionCount: sections.length },
-    });
-    return { written: true, path: target, sectionCount: sections.length };
-  } catch (err) {
-    log({
-      event: "runner.agent_codex_instructions.error",
-      message: "failed to materialize codex global AGENTS.md",
-      err,
-      context: { target },
-    });
-    return { written: false, path: target, sectionCount: 0, skippedReason: "error" };
-  }
-}

package/src/auth.ts

@@ -1,146 +0,0 @@
-/**
- * Authentication — OAuth flow with IndigoAI
- * Opens browser for sign-in, receives tokens via localhost callback
- */
-
-import * as fs from "fs";
-import * as path from "path";
-import * as http from "http";
-import open from "open";
-import type { Credentials } from "./types.js";
-
-const AUTH_URL = "https://example.com/auth";
-const CALLBACK_PORT = 19847;
-const CREDS_DIR = path.join(
-  process.env.HOME || process.env.USERPROFILE || "~",
-  ".hq"
-);
-const CREDS_FILE = path.join(CREDS_DIR, "credentials.json");
-
-export function hasCredentials(): boolean {
-  return fs.existsSync(CREDS_FILE);
-}
-
-export function readCredentials(): Credentials | null {
-  if (!fs.existsSync(CREDS_FILE)) return null;
-  try {
-    const content = fs.readFileSync(CREDS_FILE, "utf-8");
-    return JSON.parse(content) as Credentials;
-  } catch {
-    return null;
-  }
-}
-
-export function writeCredentials(creds: Credentials): void {
-  if (!fs.existsSync(CREDS_DIR)) {
-    fs.mkdirSync(CREDS_DIR, { recursive: true });
-  }
-  fs.writeFileSync(CREDS_FILE, JSON.stringify(creds, null, 2), { mode: 0o600 });
-}
-
-export function clearCredentials(): void {
-  if (fs.existsSync(CREDS_FILE)) {
-    fs.unlinkSync(CREDS_FILE);
-  }
-}
-
-/**
- * Start OAuth flow:
- * 1. Open browser to AUTH_URL with callback port
- * 2. Start localhost server to receive tokens
- * 3. Store credentials
- */
-export async function authenticate(): Promise<Credentials> {
-  return new Promise((resolve, reject) => {
-    const server = http.createServer((req, res) => {
-      const url = new URL(req.url || "", `http://localhost:${CALLBACK_PORT}`);
-
-      if (url.pathname === "/callback") {
-        const token = url.searchParams.get("token");
-        const refreshToken = url.searchParams.get("refresh_token");
-        const userId = url.searchParams.get("user_id");
-        const bucket = url.searchParams.get("bucket");
-        const region = url.searchParams.get("region") || "us-east-1";
-        const teamId = url.searchParams.get("team_id");
-
-        if (!token || !refreshToken || !userId || !bucket) {
-          res.writeHead(400, { "Content-Type": "text/html" });
-          res.end("<h1>Authentication failed</h1><p>Missing required parameters. Please try again.</p>");
-          server.close();
-          reject(new Error("Authentication failed: missing parameters"));
-          return;
-        }
-
-        const creds: Credentials = {
-          accessKeyId: "", // Will be populated via STS
-          secretAccessKey: "",
-          refreshToken,
-          userId,
-          bucket,
-          region,
-          ...(teamId ? { teamId } : {}),
-        };
-
-        writeCredentials(creds);
-
-        res.writeHead(200, { "Content-Type": "text/html" });
-        res.end(
-          "<h1>Authenticated!</h1><p>You can close this window and return to your terminal.</p>"
-        );
-
-        server.close();
-        resolve(creds);
-      }
-    });
-
-    server.listen(CALLBACK_PORT, () => {
-      const authUrl = `${AUTH_URL}?callback=http://localhost:${CALLBACK_PORT}/callback`;
-      console.log(`  Opening browser for authentication...`);
-      console.log(`  If browser doesn't open, visit: ${authUrl}`);
-      open(authUrl).catch(() => {
-        // If open fails, user can manually visit the URL
-      });
-    });
-
-    // Timeout after 5 minutes
-    setTimeout(() => {
-      server.close();
-      reject(new Error("Authentication timed out after 5 minutes"));
-    }, 5 * 60 * 1000);
-  });
-}
-
-/**
- * Refresh temporary AWS credentials using refresh token
- */
-export async function refreshAwsCredentials(
-  creds: Credentials
-): Promise<Credentials> {
-  const response = await fetch("https://example.com/api/auth/refresh", {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ refreshToken: creds.refreshToken }),
-  });
-
-  if (!response.ok) {
-    throw new Error(`Failed to refresh credentials: ${response.statusText}`);
-  }
-
-  const data = (await response.json()) as {
-    accessKeyId: string;
-    secretAccessKey: string;
-    sessionToken: string;
-    expiration: string;
-  };
-
-  const updated: Credentials = {
-    ...creds,
-    accessKeyId: data.accessKeyId,
-    secretAccessKey: data.secretAccessKey,
-    sessionToken: data.sessionToken,
-    expiration: data.expiration,
-  };
-
-  writeCredentials(updated);
-  return updated;
-}

package/src/backup-prune.test.ts

@@ -1,98 +0,0 @@
-import { describe, expect, it } from "vitest";
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-import {
-  applyBackupPrune,
-  canonicalRootHash,
-  inventoryManagedSnapshots,
-  planBackupPrune,
-  type BackupEntry,
-  type SnapshotStatus,
-} from "./backup-prune.js";
-
-const DAY = 86_400_000;
-const now = Date.UTC(2026, 6, 15, 12);
-const rootA = "/tmp/hq-a";
-const rootB = "/tmp/hq-b";
-function entry(name: string, age: number, status: SnapshotStatus, root = rootA): BackupEntry {
-  const at = new Date(now - age * DAY).toISOString();
-  return { name, createdMs: now - age * DAY, completedMs: now - age * DAY, bytes: 1,
-    manifest: { schemaVersion: 1, status, canonicalHqRoot: root, rootHash: canonicalRootHash(root), runId: name,
-      creatorPid: 1, creatorStartedAt: at, source: "source", ref: "main", sourceSha: "sha", createdAt: at,
-      completedAt: at, includedRoots: ["core"], fileCount: 1, byteCount: 1 } };
-}
-const names = (x: ReturnType<typeof planBackupPrune>) => x.candidates.map((c) => c.entry.name).sort();
-const protectedNames = (x: ReturnType<typeof planBackupPrune>) => x.protected.map((p) => `${p.entry.name}:${p.reason}`).sort();
-
-describe("planBackupPrune", () => {
-  it("keeps the newest two known-good snapshots per canonical root", () => {
-    const p = planBackupPrune([entry("a1", 0, "completed-good"), entry("a2", 1, "completed-good"), entry("a3", 2, "completed-good"), entry("a4", 3, "completed-good"), entry("b1", 0, "completed-good", rootB)], now);
-    expect(names(p)).toEqual(["a3", "a4"]);
-    expect(protectedNames(p)).toContain("a1:newest-good");
-    expect(protectedNames(p)).toContain("b1:newest-good");
-  });
-
-  it("never selects the sole, old known-good snapshot", () => {
-    const p = planBackupPrune([entry("only", 30, "completed-good")], now);
-    expect(names(p)).toEqual([]);
-    expect(protectedNames(p)).toEqual(["only:newest-good"]);
-  });
-
-  it("retains copying and unsuperseded recovery evidence", () => {
-    const p = planBackupPrune([entry("copy", 40, "copying"), entry("recovery", 40, "recovery-required")], now);
-    expect(names(p)).toEqual([]);
-    expect(protectedNames(p)).toContain("copy:copying-not-superseded");
-    expect(protectedNames(p)).toContain("recovery:recovery-required-no-later-good");
-  });
-
-  it("requires a later good run before pruning recovery-required snapshots", () => {
-    const p = planBackupPrune([entry("recovery-old", 30, "recovery-required"), entry("recovery-new", 2, "recovery-required"), entry("good", 1, "completed-good")], now);
-    expect(names(p)).toEqual(["recovery-old"]);
-    expect(protectedNames(p)).toContain("recovery-new:newest-recovery-required-grace");
-  });
-
-  it("only prunes failed-pre-mutation snapshots after a newer ready/good snapshot", () => {
-    const noSuccess = planBackupPrune([entry("failure", 20, "failed-pre-mutation")], now);
-    expect(names(noSuccess)).toEqual([]);
-    const p = planBackupPrune([entry("failure-new", 1, "failed-pre-mutation"), entry("failure-old", 2, "failed-pre-mutation"), entry("ready", 0, "ready")], now);
-    expect(names(p)).toEqual(["failure-old"]);
-  });
-
-  it("clamps malformed retention so the newest good is still protected", () => {
-    const p = planBackupPrune([entry("one", 30, "completed-good"), entry("two", 31, "completed-good"), entry("three", 32, "completed-good")], now, { keepGood: 0, maxAgeDays: Number.NaN });
-    expect(names(p)).toEqual(["three"]);
-    expect(protectedNames(p)).toContain("one:newest-good");
-  });
-});
-
-describe("managed snapshot filesystem boundary", () => {
-  it("does not select prefix matches, mcp, symlinks, malformed metadata, or changed candidates", () => {
-    const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-prune-root-"));
-    const backup = fs.mkdtempSync(path.join(os.tmpdir(), "hq-prune-backup-"));
-    try {
-      const make = (name: string, age: number) => {
-        const dir = path.join(backup, name); fs.mkdirSync(dir);
-        const at = new Date(now - age * DAY).toISOString();
-        fs.writeFileSync(path.join(dir, "SNAPSHOT.json"), JSON.stringify({ ...entry(name, age, "completed-good", root).manifest, runId: name, createdAt: at, completedAt: at }));
-        return dir;
-      };
-      const good1 = make("pre-update-2026-07-15T12-00-00Z-" + canonicalRootHash(root) + "-one", 0);
-      const good2 = make("pre-update-2026-07-14T12-00-00Z-" + canonicalRootHash(root) + "-two", 1);
-      const old = make("pre-update-2026-07-13T12-00-00Z-" + canonicalRootHash(root) + "-three", 2);
-      fs.mkdirSync(path.join(backup, "mcp"));
-      fs.mkdirSync(path.join(backup, "pre-update-not-managed"));
-      fs.symlinkSync(good1, path.join(backup, "pre-update-2026-07-12T12-00-00Z-" + canonicalRootHash(root) + "-symlink"));
-      const inventory = inventoryManagedSnapshots(backup, root);
-      expect(inventory.candidates.map((x) => x.entry.name)).toEqual([path.basename(old)]);
-      expect(inventory.unmanaged.map((x) => x.name)).toEqual(expect.arrayContaining(["mcp", "pre-update-not-managed"]));
-      // A changed manifest invalidates the dry-run identity and cannot be removed.
-      fs.writeFileSync(path.join(old, "SNAPSHOT.json"), JSON.stringify({ ...entry("replacement", 2, "completed-good", root).manifest }));
-      const result = applyBackupPrune(backup, root, inventory);
-      expect(result.deleted).toEqual([]);
-      expect(fs.existsSync(old)).toBe(true);
-      expect(fs.existsSync(path.join(backup, "mcp"))).toBe(true);
-      expect(fs.existsSync(good2)).toBe(true);
-    } finally { fs.rmSync(root, { recursive: true, force: true }); fs.rmSync(backup, { recursive: true, force: true }); }
-  });
-});