forgeos 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/forge/agent-memory/sources/codex-hook-runner.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+/**
+ * Lightweight Codex hook runner — no Forge CLI, no DeltaDB.
+ * Reads stdin with a short timeout, enqueues a redacted event to .forge/agent/events.ndjson, exits.
+ */
+import { createHash } from "node:crypto";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+const STDIN_TIMEOUT_MS = 750;
+const eventName = process.argv[2];
+
+if (!eventName) {
+  process.stderr.write("usage: codex-hook.mjs <CodexHookEvent>\n");
+  process.exit(2);
+}
+
+const workspaceRoot = resolve(process.cwd());
+const eventsFile = join(workspaceRoot, ".forge", "agent", "events.ndjson");
+
+const RAW_TEXT_KEYS = new Set([
+  "prompt",
+  "userPrompt",
+  "last_assistant_message",
+  "lastAssistantMessage",
+  "completion",
+  "message",
+  "transcript",
+  "transcript_path",
+  "transcriptPath",
+  "output",
+  "stdout",
+  "stderr",
+  "result",
+]);
+
+const RAW_ARGS_KEYS = new Set(["args", "arguments", "tool_input", "toolInput", "tool_response", "toolResponse", "input"]);
+
+function readStdin(timeoutMs) {
+  return new Promise((resolveRead) => {
+    if (process.stdin.isTTY) {
+      resolveRead("");
+      return;
+    }
+    const chunks = [];
+    let settled = false;
+    const finish = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      resolveRead(Buffer.concat(chunks).toString("utf8"));
+    };
+    const timer = setTimeout(() => {
+      process.stdin.destroy();
+      finish();
+    }, timeoutMs);
+    process.stdin.on("data", (chunk) => {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    });
+    process.stdin.on("end", finish);
+    process.stdin.on("close", finish);
+    process.stdin.on("error", finish);
+    process.stdin.resume();
+  });
+}
+
+async function main() {
+  const stdin = await readStdin(STDIN_TIMEOUT_MS);
+  const trimmed = stdin.trim();
+  let raw = {};
+  if (trimmed) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      raw = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : { _invalidPayload: true };
+    } catch {
+      raw = { _parseError: true, _rawLength: trimmed.length };
+    }
+  }
+  if (!raw.hook_event_name) {
+    raw.hook_event_name = eventName;
+  }
+  if (!raw.cwd) {
+    raw.cwd = workspaceRoot;
+  }
+
+  const entry = {
+    forgeHookQueueV1: true,
+    source: "codex",
+    eventName,
+    workspaceRoot,
+    enqueuedAt: new Date().toISOString(),
+    rawStored: false,
+    payloadRedacted: true,
+    payload: sanitizePayload(raw, eventName),
+  };
+
+  mkdirSync(dirname(eventsFile), { recursive: true });
+  appendFileSync(eventsFile, `${JSON.stringify(entry)}\n`, "utf8");
+}
+
+function sanitizePayload(raw, hookEventName) {
+  const payload = stripRawPayload(raw);
+  if (!payload.hook_event_name) {
+    payload.hook_event_name = hookEventName;
+  }
+  if (!payload.cwd) {
+    payload.cwd = workspaceRoot;
+  }
+
+  const toolInput = objectField(raw, "tool_input") ?? objectField(raw, "toolInput");
+  const toolResponse = objectField(raw, "tool_response") ?? objectField(raw, "toolResponse");
+  const command = stringField(toolInput, "command") ?? stringField(raw, "command");
+  if (command) {
+    payload.commandHash = hashStable(command);
+    payload.commandStored = false;
+    payload.commandSummary = summarizeCommand(command);
+    payload.commandKind = classifyCommand(stringField(raw, "tool_name") ?? stringField(raw, "toolName"), command);
+  }
+
+  const description = stringField(toolInput, "description");
+  if (description) {
+    payload.approvalDescriptionSummary = safeSummary(description, 180);
+  }
+
+  const exitCode = numberField(toolResponse, "exitCode") ?? numberField(toolResponse, "exit_code") ??
+    numberField(raw, "exitCode") ?? numberField(raw, "exit_code");
+  if (exitCode !== undefined) {
+    payload.exitCode = exitCode;
+    payload.resultStatus = exitCode === 0 ? "success" : "failed";
+  } else {
+    const status = stringField(toolResponse, "status") ?? stringField(raw, "status");
+    if (status) {
+      payload.resultStatus = status;
+    }
+  }
+
+  const responseSummary = summarizeToolResponse(toolResponse);
+  if (responseSummary) {
+    payload.responseSummary = responseSummary;
+  }
+  if (toolResponse) {
+    payload.responseHash = hashStable(JSON.stringify(toolResponse));
+    payload.responseStored = false;
+  }
+
+  return payload;
+}
+
+function stripRawPayload(value) {
+  if (Array.isArray(value)) {
+    return value.slice(0, 50).map((item) => stripRawPayload(item));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const output = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (RAW_TEXT_KEYS.has(key)) {
+      output[`${key}Hash`] = hashStable(typeof child === "string" ? child : JSON.stringify(child ?? null));
+      output[`${key}Stored`] = false;
+      if (typeof child === "string" && !isPromptLikeKey(key)) {
+        const summary = safeSummary(child, 160);
+        if (summary) {
+          output[`${key}Summary`] = summary;
+        }
+      }
+      continue;
+    }
+    if (RAW_ARGS_KEYS.has(key)) {
+      output[`${key}Hash`] = hashStable(JSON.stringify(child ?? null));
+      output[`${key}Stored`] = false;
+      output[`${key}Shape`] = describeShape(child);
+      continue;
+    }
+    output[key] = stripRawPayload(child);
+  }
+  return output;
+}
+
+function objectField(value, key) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const child = value[key];
+  return child && typeof child === "object" && !Array.isArray(child) ? child : undefined;
+}
+
+function stringField(value, key) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const child = value[key];
+  return typeof child === "string" && child.length > 0 ? child : undefined;
+}
+
+function numberField(value, key) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const child = value[key];
+  return typeof child === "number" && Number.isFinite(child) ? child : undefined;
+}
+
+function describeShape(value) {
+  if (Array.isArray(value)) {
+    return { kind: "array", length: value.length };
+  }
+  if (value && typeof value === "object") {
+    return {
+      kind: "object",
+      keys: Object.keys(value).slice(0, 20).sort(),
+    };
+  }
+  return { kind: typeof value };
+}
+
+function summarizeCommand(command) {
+  return safeSummary(
+    command
+      .replace(/--(token|api-key|apikey|password|secret)\s+[^\s]+/giu, "--$1 [REDACTED]")
+      .replace(/(["']?)(token|apiKey|api_key|password|secret)(["']?)\s*:\s*(["'])(.*?)\4/giu, "$1$2$3: \"[REDACTED]\""),
+    220,
+  ) ?? "[command redacted]";
+}
+
+function summarizeToolResponse(response) {
+  if (!response || typeof response !== "object" || Array.isArray(response)) {
+    return undefined;
+  }
+  const text = stringField(response, "stdout") ?? stringField(response, "stderr") ??
+    stringField(response, "output") ?? stringField(response, "result");
+  return text ? safeSummary(text, 180) : undefined;
+}
+
+function safeSummary(value, maxLength) {
+  const normalized = scrubSecretTokens(value).replace(/\s+/gu, " ").trim();
+  if (!normalized) {
+    return undefined;
+  }
+  return normalized.length > maxLength ? `${normalized.slice(0, maxLength - 3)}...` : normalized;
+}
+
+function classifyCommand(toolName, command) {
+  if (toolName === "apply_patch" || command.includes("*** Begin Patch")) {
+    return "patch";
+  }
+  if (/^\s*(?:node|npm|bun|pnpm|yarn|forge|git)\b/u.test(command)) {
+    return "shell";
+  }
+  return "unknown";
+}
+
+function isPromptLikeKey(key) {
+  return key.toLowerCase().includes("prompt") || key.toLowerCase().includes("completion") || key.toLowerCase().includes("message");
+}
+
+function scrubSecretTokens(value) {
+  return value
+    .replace(/\bsk[-_][A-Za-z0-9_\-.]{8,}\b/gu, "[REDACTED]")
+    .replace(/\bnpm_[A-Za-z0-9]{16,}\b/gu, "[REDACTED]")
+    .replace(/\bgh[pousr]_[A-Za-z0-9_]{16,}\b/gu, "[REDACTED]")
+    .replace(/\b(?:xox[baprs]-)[A-Za-z0-9-]{16,}\b/gu, "[REDACTED]");
+}
+
+function hashStable(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch(() => process.exit(1));

package/src/forge/agent-memory/sources/codex.ts

@@ -0,0 +1,119 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { releaseManifest } from "../../_generated/releaseManifest.ts";
+import type { AgentInstallResult } from "../types.ts";
+
+const CODEX_EVENTS = [
+  "SessionStart",
+  "UserPromptSubmit",
+  "PreToolUse",
+  "PermissionRequest",
+  "PostToolUse",
+  "SubagentStart",
+  "SubagentStop",
+  "PreCompact",
+  "PostCompact",
+  "Stop",
+];
+
+const CODEX_EVENT_STATUS: Record<string, string> = {
+  SessionStart: "Recording Codex session start",
+  UserPromptSubmit: "Recording Codex prompt metadata",
+  PreToolUse: "Recording Codex tool request",
+  PermissionRequest: "Recording Codex approval request",
+  PostToolUse: "Recording Codex tool result",
+  SubagentStart: "Recording Codex subagent start",
+  SubagentStop: "Recording Codex subagent stop",
+  PreCompact: "Recording Codex compaction start",
+  PostCompact: "Recording Codex compaction result",
+  Stop: "Recording Codex turn stop",
+};
+
+export const CODEX_HOOK_RUNNER_RELATIVE = ".forge/agent/codex-hook.mjs";
+export const CODEX_HOOK_META_RELATIVE = ".forge/agent/codex-hook.meta.json";
+export const CODEX_HOOK_QUEUE_RELATIVE = ".forge/agent/events.ndjson";
+
+const FAST_HOOK_EVENTS = new Set(["PreToolUse", "PostToolUse"]);
+
+function codexHookTimeout(event: string): number {
+  return FAST_HOOK_EVENTS.has(event) ? 2 : 3;
+}
+
+function codexHookCommand(event: string): string {
+  return `node ${CODEX_HOOK_RUNNER_RELATIVE} ${event}`;
+}
+
+function readCodexHookRunnerSource(): string {
+  const path = join(dirname(fileURLToPath(import.meta.url)), "codex-hook-runner.mjs");
+  return readFileSync(path, "utf8");
+}
+
+export function codexHookMetaContent(workspaceRoot: string): string {
+  const meta = {
+    schema: "forge.codex-hook.meta.v1",
+    forgeVersion: releaseManifest.packageVersion,
+    installedAt: new Date().toISOString(),
+    commandResolvedFrom: "workspace",
+    workspaceRoot,
+    runner: CODEX_HOOK_RUNNER_RELATIVE,
+    queueFile: CODEX_HOOK_QUEUE_RELATIVE,
+    stdinTimeoutMs: 750,
+    hookTimeouts: Object.fromEntries(CODEX_EVENTS.map((event) => [event, codexHookTimeout(event)])),
+  };
+  return `${JSON.stringify(meta, null, 2)}\n`;
+}
+
+export function codexInstallFiles(workspaceRoot?: string): Array<{ path: string; content: string }> {
+  const hook = {
+    hooks: Object.fromEntries(CODEX_EVENTS.map((event) => [
+      event,
+      [
+        {
+          matcher: "*",
+          hooks: [
+            {
+              type: "command",
+              command: codexHookCommand(event),
+              timeout: codexHookTimeout(event),
+              statusMessage: CODEX_EVENT_STATUS[event] ?? "Recording Codex event",
+            },
+          ],
+        },
+      ],
+    ])),
+  };
+  const files: Array<{ path: string; content: string }> = [
+    { path: ".codex/hooks.json", content: `${JSON.stringify(hook, null, 2)}\n` },
+    { path: CODEX_HOOK_RUNNER_RELATIVE, content: readCodexHookRunnerSource() },
+  ];
+  if (workspaceRoot) {
+    files.push({ path: CODEX_HOOK_META_RELATIVE, content: codexHookMetaContent(workspaceRoot) });
+  }
+  return files;
+}
+
+export function codexInstallResult(filesWritten: string[], filesPlanned: string[]): AgentInstallResult {
+  return {
+    ok: true,
+    target: "codex",
+    filesWritten,
+    filesPlanned,
+    privacy: privacyDefaults(),
+    warnings: [
+      "Codex memories and transcripts are not imported automatically.",
+      "Hooks enqueue to .forge/agent/events.ndjson; run forge agent ingest codex --watch to drain into Agent Memory.",
+    ],
+    exitCode: 0,
+  };
+}
+
+export function privacyDefaults(): AgentInstallResult["privacy"] {
+  return {
+    rawPrompts: "off",
+    rawCompletions: "off",
+    rawToolArgs: "off",
+    transcriptImport: "off",
+    cloudSync: "off",
+  };
+}

package/src/forge/agent-memory/sources/cursor.ts

@@ -0,0 +1,35 @@
+import type { AgentInstallResult } from "../types.ts";
+import { privacyDefaults } from "./codex.ts";
+
+export function cursorInstallFiles(): Array<{ path: string; content: string }> {
+  return [
+    {
+      path: ".cursor/mcp.json",
+      content: `${JSON.stringify({
+        mcpServers: {
+          forgeos: {
+            type: "stdio",
+            command: "forge",
+            args: ["mcp", "serve"],
+          },
+        },
+      }, null, 2)}\n`,
+    },
+    {
+      path: ".cursor/rules/forgeos-agent-memory.mdc",
+      content: `---\ndescription: ForgeOS Agent Memory Bridge context and MCP workflow.\nalwaysApply: true\n---\n\n# ForgeOS Agent Memory\n\n- Before modifying runtime entries, call the ForgeOS MCP tool \`agent_context\` or run \`forge agent context --current --json\`.\n- Prefer ForgeOS MCP tools for inspect, timeline, check, verify, and agent context.\n- Do not edit \`src/forge/_generated/**\` directly.\n- Do not expose destructive or write tools without approval metadata.\n- After changes, run \`forge check --json\`; use \`forge verify --strict\` before handoff.\n- Do not ask ForgeOS to read Cursor internal chats, checkpoints, or editor databases.\n`,
+    },
+  ];
+}
+
+export function cursorInstallResult(filesWritten: string[], filesPlanned: string[]): AgentInstallResult {
+  return {
+    ok: true,
+    target: "cursor",
+    filesWritten,
+    filesPlanned,
+    privacy: privacyDefaults(),
+    warnings: ["Cursor internal chats, checkpoints, and databases are not read by ForgeOS."],
+    exitCode: 0,
+  };
+}

package/src/forge/agent-memory/types.ts

@@ -0,0 +1,191 @@
+import type { Diagnostic } from "../compiler/types/diagnostic.ts";
+
+export const AGENT_EVENT_SCHEMA = "forge.agent-event.v1" as const;
+
+export type AgentMemorySourceName = "claude-code" | "codex" | "cursor" | "generic";
+export type AgentMemoryIntegrationKind = "native-hook" | "mcp" | "cli-wrapper" | "file-watcher" | "git-hook" | "manual-import";
+export type AgentMemoryTrustLevel =
+  | "direct-hook"
+  | "mcp-tool"
+  | "forge-command"
+  | "file-watcher"
+  | "git-observer"
+  | "manual-import"
+  | "inferred";
+
+export interface AgentEventEnvelope {
+  schema: typeof AGENT_EVENT_SCHEMA;
+  source: {
+    agent: AgentMemorySourceName | string;
+    integration: AgentMemoryIntegrationKind | string;
+    version: string;
+  };
+  workspace: {
+    root: string;
+    gitBranch?: string;
+    gitHead?: string;
+  };
+  session: {
+    externalSessionId?: string;
+    forgeSessionId?: string;
+    turnId?: string;
+  };
+  event: {
+    kind: string;
+    timestamp: string;
+  };
+  actor: {
+    kind: "agent" | "human" | "forge" | "unknown";
+    name: string;
+    model?: string;
+  };
+  payload: Record<string, unknown>;
+  privacy: {
+    rawPromptStored: false;
+    rawCompletionStored: false;
+    rawToolArgsStored: false;
+    transcriptImported: false;
+    redacted: true;
+    sensitiveFieldsRemoved: string[];
+  };
+  capture: {
+    trustLevel: AgentMemoryTrustLevel;
+    confidence: number;
+  };
+}
+
+export interface AgentMemoryEventRecord {
+  id: string;
+  externalEventId: string;
+  sourceName: string;
+  integrationKind: string;
+  trustLevel: string;
+  externalSessionId?: string;
+  externalTurnId?: string;
+  eventKind: string;
+  normalizedKind: string;
+  summary?: string;
+  confidence: number;
+  capturedAt: string;
+  operationId?: string;
+  data: Record<string, unknown>;
+}
+
+export interface AgentMemoryContextEvent {
+  id: string;
+  source: string;
+  integration: string;
+  trustLevel: string;
+  kind: string;
+  capturedAt: string;
+  summary?: string;
+  sessionId?: string;
+  turnId?: string;
+  tool?: string;
+  command?: string;
+  status?: string;
+  files: string[];
+  entries: string[];
+  proofs: string[];
+  confidence: number;
+}
+
+export interface AgentMemoryContextPack {
+  ok: true;
+  scope: "current" | "entry";
+  entry?: string;
+  currentState: Record<string, unknown>;
+  agentMemory: {
+    summary: {
+      events: number;
+      goals: number;
+      toolCalls: number;
+      files: number;
+      entries: number;
+      approvals: number;
+      proofs: number;
+      openQuestions: number;
+      sources: string[];
+      tools: string[];
+      latestEventAt?: string;
+    };
+    goals: Array<{ source: string; summary: string; confidence: number }>;
+    toolCalls: Array<{ source: string; tool: string; status?: string; summary?: string }>;
+    files: string[];
+    entries: string[];
+    approvals: Array<{ source: string; status: string; summary?: string }>;
+    proofs: Array<{ kind: string; result?: string }>;
+    events: AgentMemoryContextEvent[];
+    openQuestions: string[];
+  };
+  exitCode: 0;
+}
+
+export interface AgentInstallResult {
+  ok: boolean;
+  target: string;
+  filesWritten: string[];
+  filesPlanned: string[];
+  privacy: {
+    rawPrompts: "off";
+    rawCompletions: "off";
+    rawToolArgs: "off";
+    transcriptImport: "off";
+    cloudSync: "off";
+  };
+  warnings: string[];
+  exitCode: 0 | 1;
+}
+
+export interface AgentIngestResult {
+  ok: boolean;
+  event?: AgentMemoryEventRecord;
+  envelope?: AgentEventEnvelope;
+  fallback?: {
+    kind: "agent-events-ndjson";
+    path: string;
+    reason: "pglite-active";
+  };
+  exitCode: 0 | 1;
+  error?: string;
+  diagnostics?: Diagnostic[];
+  nextActions?: string[];
+}
+
+export interface AgentIngestWatchResult {
+  ok: boolean;
+  watch: boolean;
+  source: string;
+  file?: string;
+  dryRun?: boolean;
+  eventsIngested: number;
+  errors: string[];
+  bytesRead?: number;
+  pendingBytes?: number;
+  checkpointFile?: string;
+  compacted?: boolean;
+  historyFile?: string;
+  nextActions: string[];
+  exitCode: 0 | 1;
+}
+
+export interface AgentMemoryUnavailableResult {
+  ok: false;
+  error: string;
+  events?: AgentMemoryEventRecord[];
+  busy?: {
+    code: "FORGE_DELTA_BUSY";
+    lockPath: string;
+    relativeLockPath: string;
+    pid?: number;
+    processAlive: boolean;
+    createdAt?: string;
+    ageMs?: number;
+    cwd?: string;
+    command?: string;
+    holderKnown: boolean;
+  };
+  diagnostics: Diagnostic[];
+  nextActions: string[];
+  exitCode: 1;
+}