forgeos 0.1.0-alpha.12 → 0.1.0-alpha.13

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

@@ -0,0 +1,249 @@
+import { normalizePath } from "../compiler/primitives/paths.ts";
+import { readDeltaGitSnapshot } from "../delta/git-observer.ts";
+import { redactAgentPayload } from "./redaction.ts";
+import {
+  AGENT_EVENT_SCHEMA,
+  type AgentEventEnvelope,
+  type AgentMemoryIntegrationKind,
+  type AgentMemorySourceName,
+  type AgentMemoryTrustLevel,
+} from "./types.ts";
+
+export interface NormalizeAgentEventInput {
+  workspaceRoot: string;
+  source: AgentMemorySourceName | string;
+  eventName?: string;
+  integration?: AgentMemoryIntegrationKind | string;
+  raw: Record<string, unknown>;
+  now?: string;
+}
+
+export function normalizeAgentEvent(input: NormalizeAgentEventInput): AgentEventEnvelope {
+  const source = normalizeSource(input.source);
+  const rawEventName = input.eventName ?? stringField(input.raw, "hook_event_name") ?? stringField(input.raw, "event") ?? "unknown";
+  const normalizedKind = normalizeEventKind(source, rawEventName, input.raw);
+  const redacted = redactAgentPayload(input.raw);
+  const git = readDeltaGitSnapshot(input.workspaceRoot);
+  const actorName = source === "claude-code"
+    ? "Claude Code"
+    : source === "codex"
+      ? "Codex"
+      : source === "cursor"
+        ? "Cursor"
+        : "External Agent";
+  return {
+    schema: AGENT_EVENT_SCHEMA,
+    source: {
+      agent: source,
+      integration: input.integration ?? defaultIntegrationForSource(source),
+      version: stringField(input.raw, "version") ?? "unknown",
+    },
+    workspace: {
+      root: normalizePath(input.workspaceRoot),
+      gitBranch: git.branch,
+      gitHead: git.head,
+    },
+    session: {
+      externalSessionId: stringField(input.raw, "session_id") ?? stringField(input.raw, "sessionId") ?? stringField(input.raw, "conversation_id"),
+      forgeSessionId: stringField(input.raw, "forgeSessionId"),
+      turnId: stringField(input.raw, "turn_id") ?? stringField(input.raw, "turnId"),
+    },
+    event: {
+      kind: normalizedKind,
+      timestamp: stringField(input.raw, "timestamp") ?? input.now ?? new Date().toISOString(),
+    },
+    actor: {
+      kind: "agent",
+      name: stringField(input.raw, "actor") ?? actorName,
+      model: stringField(input.raw, "model"),
+    },
+    payload: redacted.value,
+    privacy: {
+      rawPromptStored: false,
+      rawCompletionStored: false,
+      rawToolArgsStored: false,
+      transcriptImported: false,
+      redacted: true,
+      sensitiveFieldsRemoved: redacted.sensitiveFieldsRemoved,
+    },
+    capture: {
+      trustLevel: trustLevelForIntegration(input.integration ?? defaultIntegrationForSource(source)),
+      confidence: confidenceForSource(source, input.integration ?? defaultIntegrationForSource(source)),
+    },
+  };
+}
+
+export function summarizeAgentEvent(envelope: AgentEventEnvelope): string {
+  const tool = stringField(envelope.payload, "toolName") ??
+    stringField(envelope.payload, "tool_name") ??
+    stringField(envelope.payload, "tool");
+  const command = stringField(envelope.payload, "command");
+  const promptSummary = stringField(envelope.payload, "promptSummary") ?? stringField(envelope.payload, "userPromptSummary");
+  if (envelope.event.kind === "agent.prompt.submitted" && promptSummary) {
+    return promptSummary;
+  }
+  if (tool) {
+    return `${envelope.source.agent} ${tool} ${statusFromKind(envelope.event.kind)}`;
+  }
+  if (command) {
+    return `${envelope.source.agent} ran ${command}`;
+  }
+  return `${envelope.source.agent} ${envelope.event.kind}`;
+}
+
+export function extractAgentEventBindings(envelope: AgentEventEnvelope): {
+  toolName?: string;
+  command?: string;
+  exitCode?: number;
+  files: string[];
+  entries: string[];
+  proofs: string[];
+  status?: string;
+} {
+  const payload = envelope.payload;
+  return {
+    toolName: stringField(payload, "toolName") ?? stringField(payload, "tool_name") ?? stringField(payload, "tool"),
+    command: stringField(payload, "command"),
+    exitCode: numberField(payload, "exitCode") ?? numberField(payload, "exit_code"),
+    files: uniqueStrings([
+      ...arrayOfStrings(payload.files),
+      ...arrayOfStrings(payload.paths),
+      stringField(payload, "file_path"),
+      stringField(payload, "filePath"),
+      stringField(payload, "path"),
+    ].map((value) => value ? normalizePath(value) : value)),
+    entries: uniqueStrings([
+      ...arrayOfStrings(payload.entries),
+      stringField(payload, "entryName"),
+      stringField(payload, "entry_name"),
+      stringField(payload, "runtimeEntry"),
+    ]),
+    proofs: uniqueStrings([
+      ...arrayOfStrings(payload.proofs),
+      stringField(payload, "proofKind"),
+      stringField(payload, "proof_kind"),
+    ]),
+    status: statusFromKind(envelope.event.kind),
+  };
+}
+
+function normalizeSource(source: string): AgentMemorySourceName | string {
+  if (source === "claude" || source === "claude-code") {
+    return "claude-code";
+  }
+  if (source === "codex" || source === "cursor") {
+    return source;
+  }
+  return source || "generic";
+}
+
+function defaultIntegrationForSource(source: string): AgentMemoryIntegrationKind {
+  return source === "cursor" ? "mcp" : "native-hook";
+}
+
+function trustLevelForIntegration(integration: string): AgentMemoryTrustLevel {
+  if (integration === "native-hook") {
+    return "direct-hook";
+  }
+  if (integration === "mcp") {
+    return "mcp-tool";
+  }
+  if (integration === "cli-wrapper") {
+    return "forge-command";
+  }
+  if (integration === "file-watcher") {
+    return "file-watcher";
+  }
+  if (integration === "git-hook") {
+    return "git-observer";
+  }
+  return "manual-import";
+}
+
+function confidenceForSource(source: string, integration: string): number {
+  if (integration === "native-hook") {
+    return source === "generic" ? 0.78 : 0.94;
+  }
+  if (integration === "mcp") {
+    return 0.9;
+  }
+  if (integration === "cli-wrapper") {
+    return 0.84;
+  }
+  return 0.68;
+}
+
+function normalizeEventKind(source: string, eventName: string, raw: Record<string, unknown>): string {
+  const canonical = eventName.replace(/\s+/g, "");
+  switch (canonical) {
+    case "SessionStart":
+      return "agent.session.started";
+    case "SessionEnd":
+      return "agent.session.ended";
+    case "UserPromptSubmit":
+      return "agent.prompt.submitted";
+    case "PreToolUse":
+      return "agent.tool.requested";
+    case "PermissionRequest":
+      return "approval.requested";
+    case "PermissionDenied":
+      return "approval.denied";
+    case "PostToolUseFailure":
+      return "agent.tool.failed";
+    case "PostToolUse":
+      return "agent.tool.completed";
+    case "SubagentStart":
+      return "agent.subagent.started";
+    case "SubagentStop":
+      return "agent.subagent.ended";
+    case "PreCompact":
+      return "agent.memory.compaction.requested";
+    case "PostCompact":
+      return "agent.memory.compaction.completed";
+    case "FileChanged":
+      return "agent.file.changed";
+    case "Stop":
+      return source === "codex" ? "agent.turn.stopped" : "agent.turn.completed";
+    default: {
+      const tool = stringField(raw, "toolName") ?? stringField(raw, "tool_name");
+      if (tool && (canonical === "tool.call" || canonical === "tool_call" || canonical === "unknown")) {
+        return "agent.tool.called";
+      }
+      return canonical.includes(".") ? canonical : `agent.${canonical || "event"}`;
+    }
+  }
+}
+
+function statusFromKind(kind: string): string | undefined {
+  if (kind.endsWith(".completed") || kind === "agent.tool.called") {
+    return "completed";
+  }
+  if (kind.endsWith(".failed")) {
+    return "failed";
+  }
+  if (kind.endsWith(".requested")) {
+    return "requested";
+  }
+  if (kind.endsWith(".denied")) {
+    return "denied";
+  }
+  return undefined;
+}
+
+function stringField(value: Record<string, unknown>, key: string): string | undefined {
+  const field = value[key];
+  return typeof field === "string" && field.length > 0 ? field : undefined;
+}
+
+function numberField(value: Record<string, unknown>, key: string): number | undefined {
+  const field = value[key];
+  return typeof field === "number" && Number.isFinite(field) ? field : undefined;
+}
+
+function arrayOfStrings(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item.length > 0) : [];
+}
+
+function uniqueStrings(values: Array<string | undefined>): string[] {
+  return [...new Set(values.filter((value): value is string => typeof value === "string" && value.length > 0))];
+}

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

@@ -0,0 +1,94 @@
+import { hashStable } from "../compiler/primitives/hash.ts";
+import { redactDeltaPayload } from "../delta/redaction.ts";
+
+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", "input"]);
+
+export interface AgentPayloadRedaction {
+  value: Record<string, unknown>;
+  sensitiveFieldsRemoved: string[];
+}
+
+export function redactAgentPayload(payload: Record<string, unknown>): AgentPayloadRedaction {
+  const removed: string[] = [];
+  const coarse = stripRawPayload(payload, [], removed) as Record<string, unknown>;
+  const redacted = redactDeltaPayload(coarse);
+  return {
+    value: redacted.value,
+    sensitiveFieldsRemoved: [...new Set([...removed, ...redacted.redaction.diagnostics])],
+  };
+}
+
+function stripRawPayload(value: unknown, path: string[], removed: string[]): unknown {
+  if (Array.isArray(value)) {
+    return value.slice(0, 50).map((item, index) => stripRawPayload(item, [...path, String(index)], removed));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const output: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    const nextPath = [...path, key];
+    if (RAW_TEXT_KEYS.has(key)) {
+      removed.push(nextPath.join("."));
+      output[`${key}Hash`] = typeof child === "string" ? hashStable(child) : hashStable(JSON.stringify(child ?? null));
+      output[`${key}Stored`] = false;
+      if (typeof child === "string" && !isPromptLikeKey(key)) {
+        const summary = summarizeText(child);
+        if (summary) {
+          output[`${key}Summary`] = redactDeltaPayload({ summary }).value.summary;
+        }
+      }
+      continue;
+    }
+    if (RAW_ARGS_KEYS.has(key)) {
+      removed.push(nextPath.join("."));
+      output[`${key}Hash`] = hashStable(JSON.stringify(child ?? null));
+      output[`${key}Stored`] = false;
+      output[`${key}Shape`] = describeShape(child);
+      continue;
+    }
+    output[key] = stripRawPayload(child, nextPath, removed);
+  }
+  return output;
+}
+
+function isPromptLikeKey(key: string): boolean {
+  return key.toLowerCase().includes("prompt") || key.toLowerCase().includes("completion") || key.toLowerCase().includes("message");
+}
+
+function summarizeText(value: string): string | undefined {
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (!normalized) {
+    return undefined;
+  }
+  return normalized.length > 160 ? `${normalized.slice(0, 157)}...` : normalized;
+}
+
+function describeShape(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return { kind: "array", length: value.length };
+  }
+  if (value && typeof value === "object") {
+    return {
+      kind: "object",
+      keys: Object.keys(value as Record<string, unknown>).slice(0, 20).sort(),
+    };
+  }
+  return { kind: typeof value };
+}

package/src/forge/agent-memory/sources/claude-code.ts

@@ -0,0 +1,51 @@
+import type { AgentInstallResult } from "../types.ts";
+import { privacyDefaults } from "./codex.ts";
+
+const CLAUDE_EVENTS = [
+  "SessionStart",
+  "UserPromptSubmit",
+  "PreToolUse",
+  "PermissionRequest",
+  "PostToolUse",
+  "PostToolUseFailure",
+  "PermissionDenied",
+  "FileChanged",
+  "SubagentStart",
+  "SubagentStop",
+  "Stop",
+  "SessionEnd",
+];
+
+export function claudeCodeInstallFiles(): Array<{ path: string; content: string }> {
+  const settings = {
+    hooks: Object.fromEntries(CLAUDE_EVENTS.map((event) => [
+      event,
+      [
+        {
+          matcher: "*",
+          hooks: [
+            {
+              type: "command",
+              command: `forge agent ingest claude-code --event ${event}`,
+            },
+          ],
+        },
+      ],
+    ])),
+  };
+  return [
+    { path: ".claude/settings.json", content: `${JSON.stringify(settings, null, 2)}\n` },
+  ];
+}
+
+export function claudeCodeInstallResult(filesWritten: string[], filesPlanned: string[]): AgentInstallResult {
+  return {
+    ok: true,
+    target: "claude-code",
+    filesWritten,
+    filesPlanned,
+    privacy: privacyDefaults(),
+    warnings: ["Claude transcript imports are opt-in only; hooks store redacted project memory."],
+    exitCode: 0,
+  };
+}

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

@@ -0,0 +1,58 @@
+import type { AgentInstallResult } from "../types.ts";
+
+const CODEX_EVENTS = [
+  "SessionStart",
+  "UserPromptSubmit",
+  "PreToolUse",
+  "PermissionRequest",
+  "PostToolUse",
+  "SubagentStart",
+  "SubagentStop",
+  "PreCompact",
+  "PostCompact",
+  "Stop",
+];
+
+export function codexInstallFiles(): Array<{ path: string; content: string }> {
+  const hook = {
+    hooks: Object.fromEntries(CODEX_EVENTS.map((event) => [
+      event,
+      [
+        {
+          matcher: "*",
+          hooks: [
+            {
+              type: "command",
+              command: `forge agent ingest codex --event ${event}`,
+            },
+          ],
+        },
+      ],
+    ])),
+  };
+  return [
+    { path: ".codex/hooks.json", content: `${JSON.stringify(hook, null, 2)}\n` },
+  ];
+}
+
+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."],
+    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,112 @@
+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 AgentMemoryContextPack {
+  ok: true;
+  scope: "current" | "entry";
+  entry?: string;
+  currentState: Record<string, unknown>;
+  agentMemory: {
+    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: AgentMemoryEventRecord[];
+    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;
+  exitCode: 0 | 1;
+  error?: string;
+}

package/src/forge/cli/build.ts

@@ -46,6 +46,22 @@ async function runOptionalScript(
   return { skipped: false, exitCode };
 }
 
+function readPackageScripts(workspaceRoot: string): Record<string, string> {
+  const packageJsonPath = join(workspaceRoot, "package.json");
+  if (!nodeFileSystem.exists(packageJsonPath)) {
+    return {};
+  }
+  const pkg = JSON.parse(nodeFileSystem.readText(packageJsonPath) ?? "{}") as {
+    scripts?: Record<string, string>;
+  };
+  return pkg.scripts ?? {};
+}
+
+function shouldTypecheckBuild(workspaceRoot: string): boolean {
+  const scripts = readPackageScripts(workspaceRoot);
+  return Boolean(scripts.typecheck || nodeFileSystem.exists(join(workspaceRoot, "tsconfig.json")));
+}
+
 export async function runBuildCommand(options: BuildCommandOptions): Promise<BuildCommandResult> {
   const steps: BuildCommandResult["steps"] = [];
   const generate = await runGenerateCommand({
@@ -63,9 +79,9 @@ export async function runBuildCommand(options: BuildCommandOptions): Promise<Bui
   const verify = await runVerifyCommand({
     workspaceRoot: options.workspaceRoot,
     json: false,
-    skipTests: false,
-    skipTypecheck: false,
-    skipEslint: false,
+    skipTests: true,
+    skipTypecheck: !shouldTypecheckBuild(options.workspaceRoot),
+    skipEslint: true,
     strict: false,
   });
   steps.push({ name: "verify", ok: verify.exitCode === 0, exitCode: verify.exitCode });

package/src/forge/cli/commands.ts

@@ -165,6 +165,7 @@ import {
   formatAgentJson,
   runAgentCommand,
 } from "../agent-adapters/index.ts";
+import { runMcpServe } from "../agent-memory/mcp.ts";
 import {
   formatReviewHuman,
   formatReviewJson,
@@ -909,6 +910,9 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
       }
       return result.exitCode;
     }
+    case "mcp": {
+      return runMcpServe(command.workspaceRoot);
+    }
     case "review": {
       const result = runReviewCommand(command.options);
       if (command.options.json) {

package/src/forge/cli/main.ts

@@ -15,6 +15,8 @@ function formatHelp(): string {
     "  forge dev --once --json   One-shot health/diagnostic loop for agents and CI",
     "  forge do \"fix\" --json     Ask ForgeOS for the right workflow and commands",
     "  forge inspect all --json  Read the generated machine contract",
+    "  forge mcp serve          Serve ForgeOS Agent Memory tools over MCP stdio",
+    "  forge agent context --current --json  Read the Agent Memory context pack",
     "  forge doctor windows --json  Diagnose native Windows setup and Bun shims",
     "  forge bench compiler --json  Measure public compiler phase timings",
     "  forge manifest validate ./forge.manifest.json --json  Validate an external runtime manifest",