@indigoai-us/hq-cloud 6.11.15 → 6.11.17

package/src/agent-codex-instructions.ts

@@ -0,0 +1,309 @@
+/**
+ * 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/bin/sync-runner-planning.ts

@@ -1,5 +1,8 @@
 import type { Membership } from "../index.js";
-import { pickCanonicalPersonEntity } from "../vault-client.js";
+import {
+  pickCanonicalPersonEntity,
+  pickAgentSelfEntity,
+} from "../vault-client.js";
 import { PERSONAL_VAULT_JOURNAL_SLUG } from "../journal.js";
 import type { RunnerEvent, VaultClientSurface } from "./sync-runner.js";
 
@@ -9,6 +12,16 @@ interface IdentityClaims {
   name?: string;
   given_name?: string;
   family_name?: string;
+  /**
+   * Entity-bound machine-identity claims (US-013, unblocks US-004). A headless
+   * agent box authenticates with machine creds; its idToken carries the agent's
+   * own entity binding here. The `--personal` target resolver reads these to
+   * resolve the agent AS itself: when `custom:entityType === "agent"`, the
+   * personal slot resolves to the agent's OWN entity (`custom:entityUid`,
+   * `agt_*`) instead of the person-only canonical pick.
+   */
+  "custom:entityType"?: string;
+  "custom:entityUid"?: string;
 }
 
 export interface RunnerTarget {
@@ -72,6 +85,7 @@ export async function buildFanoutPlan(options: {
   personal: boolean;
   skipPersonal: boolean;
   client: VaultClientSurface;
+  claims: IdentityClaims | null;
   resolveSkipPersonal: (flag: boolean) => boolean;
 }): Promise<
   | { status: "setup-needed" }
@@ -95,8 +109,26 @@ export async function buildFanoutPlan(options: {
     (options.companies || options.personal) &&
     !options.resolveSkipPersonal(options.skipPersonal)
   ) {
+    // Self-entity listing. For a person identity this returns the caller's
+    // person entit(ies); for an agent machine identity (idToken
+    // `custom:entityType=agent`) the server scopes it to the agent's OWN
+    // entity (type: "agent"). `listByType("person")` is the same orphan-safe
+    // self-listing call in both cases — the server resolves the caller from
+    // the JWT, so an agent box gets back its own agt_ entity here.
     const persons = await options.client.entity.listByType("person");
-    const pick = pickCanonicalPersonEntity(persons);
+
+    // Agent-aware target selection (US-013, unblocks US-004): when the runner
+    // is an agent machine identity, the person-only canonical pick drops the
+    // agent's own `type: "agent"` entity — so resolve the agent's OWN entity
+    // by its claimed self-uid instead. Falls back to the person-only pick for
+    // a person identity (or an agent whose self-entity didn't list), so the
+    // prs_* `--personal` path is unchanged.
+    const isAgentIdentity = options.claims?.["custom:entityType"] === "agent";
+    const agentSelfUid = options.claims?.["custom:entityUid"] ?? "";
+    const pick = isAgentIdentity
+      ? (pickAgentSelfEntity(persons, agentSelfUid) ??
+          pickCanonicalPersonEntity(persons))
+      : pickCanonicalPersonEntity(persons);
     if (pick?.bucketName) {
       plan.push({
         slug: "personal",