@vauban-org/agent-sdk 1.0.0 → 1.2.0

package/src/container/runtime.ts

@@ -0,0 +1,424 @@
+/**
+ * ContainerRuntime — execute automations as local binaries or as containers,
+ * speaking the {@link ./protocol.ts | Container Execution Protocol}.
+ *
+ * Two modes:
+ *
+ *   - **Binary**: spawn a local executable directly (Rust/Go/Python binary).
+ *     The runtime uses `node:child_process.spawn` by default; tests inject a
+ *     `SpawnFn` to avoid actually running anything.
+ *
+ *   - **Container**: delegate to a host-provided {@link SandboxExecutor}.
+ *     This is structurally compatible with Command Center's `DockerExecutor`
+ *     (hardened isolation), so the SDK stays decoupled from any specific
+ *     sandbox implementation.
+ *
+ * @public @since 1.2.0
+ */
+
+import { randomUUID } from "node:crypto";
+import { type ChildProcess, spawn as nodeSpawn } from "node:child_process";
+
+import {
+  buildProtocolEnv,
+  type ExecutionResult,
+  parseProtocolOutput,
+  parseStderrLogs,
+  ProtocolParseError,
+} from "./protocol.js";
+
+/**
+ * Description of a sandboxed job — structurally identical to Command Center's
+ * `SandboxJob`. Defined here so the SDK has no dependency on a specific
+ * sandbox implementation.
+ *
+ * @public
+ */
+export interface SandboxJob {
+  image: string;
+  command: string[];
+  stdin?: string;
+  env?: Record<string, string>;
+  cwd?: string;
+  timeoutMs: number;
+  networkMode?: "none" | "outbound" | "bridge";
+  readOnlyRoot?: boolean;
+  memoryMb?: number;
+  cpuQuota?: number;
+}
+
+/**
+ * Outcome of a sandbox run — structurally identical to Command Center's
+ * `SandboxResult`.
+ *
+ * @public
+ */
+export interface SandboxResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  durationMs: number;
+}
+
+/**
+ * Port for a process sandbox (Docker, Firecracker, etc.). The host injects an
+ * implementation at runtime; the SDK never depends on a concrete sandbox.
+ *
+ * @public
+ */
+export interface SandboxExecutor {
+  run(job: SandboxJob): Promise<SandboxResult>;
+}
+
+/**
+ * Spawn function signature, mirrors `node:child_process.spawn`. Injectable so
+ * tests can avoid spawning real subprocesses.
+ *
+ * @public
+ */
+export type SpawnFn = (
+  cmd: string,
+  args: string[],
+  opts: {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    stdio: ["pipe", "pipe", "pipe"];
+    signal?: AbortSignal;
+  }
+) => ChildProcess;
+
+/**
+ * Options for {@link ContainerRuntime.executeContainer}.
+ *
+ * @public
+ */
+export interface ContainerExecutionOptions {
+  executionId?: string;
+  timeoutSeconds?: number;
+  extraEnv?: Record<string, string>;
+  mode?: string;
+  networkMode?: "none" | "outbound" | "bridge";
+  readOnlyRoot?: boolean;
+  memoryMb?: number;
+  cpuQuota?: number;
+}
+
+/**
+ * Options for {@link ContainerRuntime.executeBinary}.
+ *
+ * @public
+ */
+export interface BinaryExecutionOptions {
+  executionId?: string;
+  timeoutSeconds?: number;
+  extraEnv?: Record<string, string>;
+  cwd?: string;
+  mode?: string;
+}
+
+/**
+ * Construct a {@link ContainerRuntime} bound to a {@link SandboxExecutor}
+ * (for container mode) and optionally a custom {@link SpawnFn} (for binary
+ * mode tests).
+ *
+ * @public
+ */
+export interface ContainerRuntimeOptions {
+  /** Sandbox executor for container mode. Required if executeContainer() is called. */
+  sandbox?: SandboxExecutor;
+  /** Spawn function for binary mode. Defaults to node:child_process.spawn. */
+  spawnFn?: SpawnFn;
+  /** Default timeout when callers don't specify one. */
+  defaultTimeoutSeconds?: number;
+}
+
+const DEFAULT_TIMEOUT_SECONDS = 300;
+const MAX_OUTPUT_BYTES = 1_048_576; // 1 MB
+const TRUNCATION_MARKER = "\n[TRUNCATED — output exceeded 1 MB]";
+
+/**
+ * Run automations via either a sandboxed container (host-injected) or a local
+ * binary subprocess. Both paths produce a uniform {@link ExecutionResult}.
+ *
+ * @public
+ */
+export class ContainerRuntime {
+  private readonly sandbox: SandboxExecutor | undefined;
+  private readonly spawnFn: SpawnFn;
+  private readonly defaultTimeoutSeconds: number;
+
+  constructor(opts: ContainerRuntimeOptions = {}) {
+    this.sandbox = opts.sandbox;
+    this.spawnFn = opts.spawnFn ?? (nodeSpawn as unknown as SpawnFn);
+    this.defaultTimeoutSeconds =
+      opts.defaultTimeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
+  }
+
+  /**
+   * Execute an automation packaged as a container image. Delegates to the
+   * injected {@link SandboxExecutor} so isolation policy (caps, network,
+   * read-only FS) lives in the host implementation.
+   */
+  async executeContainer<T = unknown>(
+    image: string,
+    automationName: string,
+    input: unknown,
+    options: ContainerExecutionOptions = {}
+  ): Promise<ExecutionResult<T>> {
+    if (!this.sandbox) {
+      throw new Error(
+        "ContainerRuntime.executeContainer: no SandboxExecutor injected"
+      );
+    }
+    const executionId = options.executionId ?? randomUUID();
+    const timeoutSeconds = options.timeoutSeconds ?? this.defaultTimeoutSeconds;
+    const startedAt = new Date();
+
+    const env = buildProtocolEnv({
+      executionId,
+      automationName,
+      input,
+      timeoutSeconds,
+      mode: options.mode,
+      extraEnv: options.extraEnv,
+    });
+
+    const job: SandboxJob = {
+      image,
+      command: [],
+      env,
+      timeoutMs: timeoutSeconds * 1000,
+      networkMode: options.networkMode ?? "none",
+      readOnlyRoot: options.readOnlyRoot ?? true,
+      memoryMb: options.memoryMb ?? 256,
+      cpuQuota: options.cpuQuota ?? 0.5,
+    };
+
+    const result = await this.sandbox.run(job);
+    return this.toExecutionResult<T>({
+      executionId,
+      automationName,
+      input,
+      startedAt,
+      sandboxResult: result,
+    });
+  }
+
+  /**
+   * Execute an automation packaged as a local binary (Rust release, Python
+   * wrapper, shell script). No container — just a hardened subprocess.
+   */
+  async executeBinary<T = unknown>(
+    command: string[],
+    automationName: string,
+    input: unknown,
+    options: BinaryExecutionOptions = {}
+  ): Promise<ExecutionResult<T>> {
+    if (!Array.isArray(command) || command.length === 0) {
+      throw new Error(
+        "ContainerRuntime.executeBinary: command must be a non-empty array"
+      );
+    }
+    const executionId = options.executionId ?? randomUUID();
+    const timeoutSeconds = options.timeoutSeconds ?? this.defaultTimeoutSeconds;
+    const startedAt = new Date();
+
+    const protocolEnv = buildProtocolEnv({
+      executionId,
+      automationName,
+      input,
+      timeoutSeconds,
+      mode: options.mode,
+      extraEnv: options.extraEnv,
+    });
+    const env: NodeJS.ProcessEnv = { ...process.env, ...protocolEnv };
+
+    const result = await this.runSubprocess({
+      cmd: command[0]!,
+      args: command.slice(1),
+      env,
+      cwd: options.cwd,
+      timeoutMs: timeoutSeconds * 1000,
+    });
+
+    return this.toExecutionResult<T>({
+      executionId,
+      automationName,
+      input,
+      startedAt,
+      sandboxResult: result,
+    });
+  }
+
+  // ─── Internals ────────────────────────────────────────────────────────
+
+  private async runSubprocess(args: {
+    cmd: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    cwd: string | undefined;
+    timeoutMs: number;
+  }): Promise<SandboxResult> {
+    const startedAt = Date.now();
+    const abortController = new AbortController();
+    const timeoutHandle = setTimeout(
+      () => abortController.abort(),
+      args.timeoutMs
+    );
+
+    let stdoutBuf = "";
+    let stderrBuf = "";
+    let timedOut = false;
+
+    const spawnOpts: {
+      env?: NodeJS.ProcessEnv;
+      cwd?: string;
+      stdio: ["pipe", "pipe", "pipe"];
+      signal?: AbortSignal;
+    } = {
+      env: args.env,
+      stdio: ["pipe", "pipe", "pipe"],
+      signal: abortController.signal,
+    };
+    if (args.cwd !== undefined) spawnOpts.cwd = args.cwd;
+
+    const child = this.spawnFn(args.cmd, args.args, spawnOpts);
+
+    if (child.stdin) child.stdin.end();
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      const remaining = MAX_OUTPUT_BYTES - Buffer.byteLength(stdoutBuf, "utf8");
+      if (remaining <= 0) return;
+      const piece = chunk.toString("utf8");
+      if (Buffer.byteLength(piece, "utf8") <= remaining) {
+        stdoutBuf += piece;
+      } else {
+        stdoutBuf += piece.slice(0, remaining) + TRUNCATION_MARKER;
+      }
+    });
+
+    child.stderr?.on("data", (chunk: Buffer) => {
+      const remaining = MAX_OUTPUT_BYTES - Buffer.byteLength(stderrBuf, "utf8");
+      if (remaining <= 0) return;
+      const piece = chunk.toString("utf8");
+      if (Buffer.byteLength(piece, "utf8") <= remaining) {
+        stderrBuf += piece;
+      } else {
+        stderrBuf += piece.slice(0, remaining) + TRUNCATION_MARKER;
+      }
+    });
+
+    const exitCode = await new Promise<number>((resolve) => {
+      child.on("close", (code) => resolve(code ?? 1));
+      child.on("error", (err: NodeJS.ErrnoException) => {
+        if (err.name === "AbortError" || abortController.signal.aborted) {
+          timedOut = true;
+          resolve(137);
+        } else {
+          resolve(1);
+        }
+      });
+    });
+
+    clearTimeout(timeoutHandle);
+
+    return {
+      exitCode,
+      stdout: stdoutBuf,
+      stderr: stderrBuf,
+      timedOut,
+      durationMs: Date.now() - startedAt,
+    };
+  }
+
+  private toExecutionResult<T>(args: {
+    executionId: string;
+    automationName: string;
+    input: unknown;
+    startedAt: Date;
+    sandboxResult: SandboxResult;
+  }): ExecutionResult<T> {
+    const completedAt = new Date(
+      args.startedAt.getTime() + args.sandboxResult.durationMs
+    );
+    const logs = parseStderrLogs(args.sandboxResult.stderr);
+
+    if (args.sandboxResult.timedOut) {
+      return {
+        executionId: args.executionId,
+        automationName: args.automationName,
+        status: "timeout",
+        input: args.input,
+        error: {
+          code: "TIMEOUT",
+          message: `execution timed out after ${args.sandboxResult.durationMs}ms`,
+        },
+        startedAt: args.startedAt,
+        completedAt,
+        durationMs: args.sandboxResult.durationMs,
+        logs,
+      };
+    }
+
+    // Try to parse the protocol result FIRST — a non-zero exit with a valid
+    // protocol "failed" payload is a business failure, not a container crash.
+    try {
+      const protocol = parseProtocolOutput<T>(args.sandboxResult.stdout);
+      if (protocol.status === "completed") {
+        return {
+          executionId: args.executionId,
+          automationName: args.automationName,
+          status: "completed",
+          input: args.input,
+          output: protocol.output,
+          startedAt: args.startedAt,
+          completedAt,
+          durationMs: args.sandboxResult.durationMs,
+          logs,
+        };
+      }
+      return {
+        executionId: args.executionId,
+        automationName: args.automationName,
+        status: "failed",
+        input: args.input,
+        error: { ...protocol.error },
+        startedAt: args.startedAt,
+        completedAt,
+        durationMs: args.sandboxResult.durationMs,
+        logs,
+      };
+    } catch (err) {
+      // No parseable protocol output. If the process exited non-zero, surface
+      // it as a container crash; otherwise the binary returned 0 but said
+      // nothing useful — also a protocol violation.
+      const code =
+        args.sandboxResult.exitCode === 0
+          ? "INVALID_OUTPUT"
+          : "CONTAINER_EXIT_ERROR";
+      const message =
+        args.sandboxResult.exitCode === 0
+          ? "process exited 0 but produced no protocol result"
+          : `process exited with code ${args.sandboxResult.exitCode}`;
+      const stderrTail = args.sandboxResult.stderr.slice(-2000);
+      const stdoutTail = args.sandboxResult.stdout.slice(-2000);
+      const rawTail = err instanceof ProtocolParseError ? err.rawTail : "";
+      return {
+        executionId: args.executionId,
+        automationName: args.automationName,
+        status: "failed",
+        input: args.input,
+        error: {
+          code,
+          message,
+          details: { stderr: stderrTail, stdout: stdoutTail, rawTail },
+        },
+        startedAt: args.startedAt,
+        completedAt,
+        durationMs: args.sandboxResult.durationMs,
+        logs,
+      };
+    }
+  }
+}

package/src/db/migrations/026_formal_verify_results.sql

@@ -0,0 +1,30 @@
+-- 026_formal_verify_results.sql
+--
+-- Sprint-587 — Persistence for Z3 formal verification outcomes.
+--
+-- One row per (cycle_id, axiom) verification attempt. UNKNOWN and SKIPPED
+-- are first-class states (NOT folded into SAFE/UNSAFE). The `mode` and
+-- `context` columns preserve enough metadata to reproduce the decision
+-- under a different policy without re-running the solver.
+
+CREATE TABLE IF NOT EXISTS formal_verify_results (
+  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  cycle_id        TEXT NOT NULL,
+  axiom           TEXT NOT NULL,
+  state           TEXT NOT NULL CHECK (state IN ('SAFE','UNSAFE','UNKNOWN','SKIPPED')),
+  rationale       TEXT,
+  witness         TEXT,
+  counterexample  TEXT,
+  time_ms         INT,
+  mode            TEXT NOT NULL DEFAULT 'permissive'
+                  CHECK (mode IN ('strict','permissive','audit_only')),
+  context         TEXT NOT NULL DEFAULT 'runtime'
+                  CHECK (context IN ('runtime','skill_ingestion')),
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_formal_verify_cycle
+  ON formal_verify_results (cycle_id);
+
+CREATE INDEX IF NOT EXISTS idx_formal_verify_state
+  ON formal_verify_results (state, created_at DESC);

package/src/identity/agent-persona.ts

@@ -0,0 +1,203 @@
+/**
+ * AgentPersona — load, save, and resolve a per-agent persona.
+ *
+ * Pipeline:
+ *   1. Resolve persona for agent X
+ *   2. base = DEFAULT_PERSONA
+ *   3. brain = loadFromBrain(X) (Tier 3 semantic memory query)
+ *   4. local = loadFromFile(`.cc/persona.yaml`) — optional
+ *   5. effective = merge(base, brain, local)
+ *
+ * Brain entries use category `agent-persona`, tags `["persona", agentId]`.
+ * The latest entry per agent wins (Brain query returns entries sorted by
+ * recency).
+ *
+ * @see ./persona-schema.ts
+ * @public
+ */
+
+import { readFile, writeFile } from "node:fs/promises";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import type { SemanticMemoryPort } from "../ports/brain.js";
+import {
+  DEFAULT_PERSONA,
+  mergePersona,
+  PersonaSchema,
+  validatePersona,
+  type AgentPersona,
+} from "./persona-schema.js";
+
+export const PERSONA_BRAIN_CATEGORY = "agent-persona";
+
+/** Tags used to query/archive a persona for a given agent. */
+export function personaTags(agentId: string): string[] {
+  return ["persona", agentId];
+}
+
+// ─── Brain layer ────────────────────────────────────────────────────────────
+
+/**
+ * Save (archive) a persona for an agent in Brain Tier 3 (semantic).
+ *
+ * The persona is serialized as JSON in the `content` field — keep this
+ * structured so future queries can parse it deterministically. Tags include
+ * the agent id so per-agent retrieval is precise.
+ *
+ * Returns the archived entry id, or null when the brain port returns null
+ * (e.g. replay mode, no brain configured).
+ */
+export async function savePersonaToBrain(
+  brain: SemanticMemoryPort,
+  agentId: string,
+  persona: AgentPersona
+): Promise<string | null> {
+  validatePersona(persona);
+  // Wrap the JSON body with a discoverable header line — FTS-backed Brain
+  // backends use the query string as a keyword filter, so the content MUST
+  // contain the literal "persona" + agent id for `query("persona ...")` hits.
+  const content = `persona for agent ${agentId}\n${JSON.stringify(persona)}`;
+  const entry = await brain.archive({
+    content,
+    content_type: "persona",
+    category: PERSONA_BRAIN_CATEGORY,
+    tags: personaTags(agentId),
+    metadata: { agent_id: agentId, schema_version: 1 },
+  });
+  return entry?.id ?? null;
+}
+
+/**
+ * Extract the JSON body from a persona Brain entry (strips the header line).
+ * Returns null if the content doesn't follow the wrapper format.
+ */
+function extractPersonaJson(content: string): string | null {
+  const nl = content.indexOf("\n");
+  if (nl === -1) {
+    // Backward-compat: legacy entries stored raw JSON.
+    return content;
+  }
+  return content.slice(nl + 1);
+}
+
+/**
+ * Query Brain for the latest persona for an agent.
+ *
+ * Returns the parsed persona or `null` if no entry is found (or if the
+ * latest entry's content does not parse).
+ */
+export async function loadPersonaFromBrain(
+  brain: SemanticMemoryPort,
+  agentId: string
+): Promise<AgentPersona | null> {
+  const results = await brain.query("persona", {
+    category: PERSONA_BRAIN_CATEGORY,
+    tags: personaTags(agentId),
+    limit: 5,
+  });
+  if (results.length === 0) return null;
+  // Prefer the most recent entry by created_at if available.
+  const sorted = [...results].sort((a, b) => {
+    const ta = a.created_at ? Date.parse(a.created_at) : 0;
+    const tb = b.created_at ? Date.parse(b.created_at) : 0;
+    return tb - ta;
+  });
+  for (const entry of sorted) {
+    const json = extractPersonaJson(entry.content);
+    if (!json) continue;
+    try {
+      const parsed = JSON.parse(json) as unknown;
+      const validated = PersonaSchema.safeParse(parsed);
+      if (validated.success) return validated.data;
+    } catch {
+      // skip malformed entry, try next
+    }
+  }
+  return null;
+}
+
+// ─── File layer ─────────────────────────────────────────────────────────────
+
+/**
+ * Load a persona from a YAML file. Returns null if the file is missing or
+ * the content does not validate. Throws only on filesystem errors other
+ * than ENOENT.
+ */
+export async function loadPersonaFromFile(
+  path: string
+): Promise<AgentPersona | null> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf-8");
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return null;
+    throw err;
+  }
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(raw);
+  } catch {
+    return null;
+  }
+  const result = PersonaSchema.safeParse(parsed);
+  return result.success ? result.data : null;
+}
+
+/**
+ * Persist a persona to a YAML file (overwrites). Validates first.
+ */
+export async function savePersonaToFile(
+  path: string,
+  persona: AgentPersona
+): Promise<void> {
+  const validated = validatePersona(persona);
+  const yaml = stringifyYaml(validated, { indent: 2 });
+  await writeFile(path, yaml, "utf-8");
+}
+
+// ─── Resolution ─────────────────────────────────────────────────────────────
+
+export interface ResolvePersonaOptions {
+  agentId: string;
+  brain?: SemanticMemoryPort;
+  localPath?: string;
+}
+
+export interface ResolvedPersona {
+  effective: AgentPersona;
+  /** Layers actually applied, in order (latest wins). */
+  layers: Array<"defaults" | "brain" | "local">;
+}
+
+/**
+ * Resolve the effective persona for an agent.
+ *
+ * Composition order (each layer overrides the previous):
+ *   1. DEFAULT_PERSONA
+ *   2. Brain entry (Tier 3 semantic, optional)
+ *   3. Local `.cc/persona.yaml` (optional)
+ *
+ * The returned `layers` array documents which sources contributed, useful
+ * for diagnostics (e.g. `cc persona show --explain`).
+ */
+export async function resolvePersona(
+  opts: ResolvePersonaOptions
+): Promise<ResolvedPersona> {
+  const layers: ResolvedPersona["layers"] = ["defaults"];
+  let effective: AgentPersona = DEFAULT_PERSONA;
+  if (opts.brain) {
+    const fromBrain = await loadPersonaFromBrain(opts.brain, opts.agentId);
+    if (fromBrain) {
+      effective = mergePersona(effective, fromBrain);
+      layers.push("brain");
+    }
+  }
+  if (opts.localPath) {
+    const fromFile = await loadPersonaFromFile(opts.localPath);
+    if (fromFile) {
+      effective = mergePersona(effective, fromFile);
+      layers.push("local");
+    }
+  }
+  return { effective, layers };
+}