@vauban-org/agent-sdk 0.16.0

package/src/tools/types.ts

@@ -0,0 +1,114 @@
+/**
+ * Tool registry contract — shared types used by AgentLoop and SdkAgentLoop.
+ *
+ * This is the single source of truth for the tool surface. Concrete
+ * registries (in-memory, CC-traced, remote-proxy) all implement
+ * `ToolRegistry` defined here.
+ */
+
+import type { z } from "zod";
+import type { SdkCapability } from "../permissions/sdk-permissions.js";
+
+// ─── AgentTool ─────────────────────────────────────────────────────────────
+
+/**
+ * An agent tool: named capability with typed parameters and async handler.
+ * The Zod schema doubles as runtime validator AND MCP inputSchema generator.
+ *
+ * Capability annotations (`capability`, `mcpScopes`, `dangerous`) are read
+ * by SdkAgentLoop for permission enforcement and HITL gating. They are
+ * ignored by the minimal AgentLoop (which only looks at `dangerous`).
+ */
+export interface AgentTool<TParams extends z.ZodTypeAny = z.ZodTypeAny> {
+  /** Unique tool name (snake_case, e.g. "query_knowledge"). */
+  readonly name: string;
+  /** Human-readable description for LLM tool-use. */
+  readonly description: string;
+  /** Zod schema for parameter validation. */
+  readonly parameters: TParams;
+  /** Async handler — receives validated params, returns unknown result. */
+  readonly execute: (params: z.infer<TParams>) => Promise<unknown>;
+  /** Capability surface required. Defaults to "mcp" in SdkAgentLoop. */
+  readonly capability?: SdkCapability;
+  /** Required MCP sub-scopes (e.g. ["brain:write"]). Only honoured when capability === "mcp". */
+  readonly mcpScopes?: readonly string[];
+  /** If true, HITL approval required before each call. */
+  readonly dangerous?: boolean;
+}
+
+// ─── Tool execution result ─────────────────────────────────────────────────
+
+export type ToolResult<T = unknown> =
+  | { ok: true; data: T }
+  | { ok: false; error: ToolError };
+
+export interface ToolError {
+  code: ToolErrorCode;
+  message: string;
+  toolName: string;
+}
+
+export type ToolErrorCode =
+  | "not_found"
+  | "validation_failed"
+  | "execution_failed"
+  | "duplicate_name";
+
+// ─── MCP-compatible tool definition (JSON Schema output) ───────────────────
+
+export interface MCPToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+// ─── Tool name validation ──────────────────────────────────────────────────
+
+const TOOL_NAME_REGEX = /^[a-z][a-z0-9_]{0,62}$/;
+
+export function isValidToolName(name: string): boolean {
+  return TOOL_NAME_REGEX.test(name);
+}
+
+// ─── ToolRegistry contract ─────────────────────────────────────────────────
+
+/**
+ * Unified tool registry contract consumed by both AgentLoop (minimal) and
+ * SdkAgentLoop (Anthropic-direct). Concrete implementations (CC, test doubles)
+ * must implement every method.
+ */
+export interface ToolRegistry {
+  /** Register a tool. Returns ok or a structured error. */
+  register<T extends z.ZodTypeAny>(tool: AgentTool<T>): ToolResult<void>;
+
+  /** Unregister a tool by name. Returns false if not found. */
+  unregister(name: string): boolean;
+
+  /** Get a registered tool by name. */
+  get(name: string): AgentTool | undefined;
+
+  /** Check if a tool is registered. */
+  has(name: string): boolean;
+
+  /** List all registered tool names. */
+  listNames(): string[];
+
+  /** List all tools as MCP-compatible definitions (JSON Schema). */
+  listMCPDefinitions(): MCPToolDefinition[];
+
+  /** Number of registered tools. */
+  readonly size: number;
+
+  /** Remove all registered tools. */
+  clear(): void;
+
+  /**
+   * Execute a tool by name with raw (unvalidated) arguments.
+   * Validates against the tool's Zod schema before invoking execute().
+   */
+  execute(name: string, args: unknown): Promise<ToolResult>;
+}

package/src/tools/zod-to-json-schema.ts

@@ -0,0 +1,112 @@
+import { z } from "zod";
+import type { MCPToolDefinition } from "./types.js";
+
+/**
+ * Minimal Zod-to-JSON-Schema converter for MCP tool definitions.
+ * Handles the subset of Zod types used in agent tool parameters:
+ * z.object, z.string, z.number, z.boolean, z.array, z.enum, z.optional, z.default.
+ *
+ * No external dependency — avoids adding zod-to-json-schema to direct deps.
+ */
+export function zodToJsonSchema(
+  schema: z.ZodTypeAny,
+): MCPToolDefinition["inputSchema"] {
+  const jsonSchema = convertZodType(schema);
+  if (jsonSchema.type === "object") {
+    return jsonSchema as MCPToolDefinition["inputSchema"];
+  }
+  return { type: "object", properties: { value: jsonSchema } };
+}
+
+function convertZodType(schema: z.ZodTypeAny): Record<string, unknown> {
+  if (schema instanceof z.ZodOptional) {
+    const inner = convertZodType(schema.unwrap());
+    return withDescription(schema, inner);
+  }
+
+  if (schema instanceof z.ZodDefault) {
+    const inner = convertZodType(schema._def.innerType);
+    inner.default = schema._def.defaultValue();
+    return withDescription(schema, inner);
+  }
+
+  if (schema instanceof z.ZodObject) {
+    const shape = schema.shape as Record<string, z.ZodTypeAny>;
+    const properties: Record<string, unknown> = {};
+    const required: string[] = [];
+
+    for (const [key, value] of Object.entries(shape)) {
+      properties[key] = convertZodType(value);
+      if (!isOptionalType(value)) {
+        required.push(key);
+      }
+    }
+
+    const result: Record<string, unknown> = { type: "object", properties };
+    if (required.length > 0) {
+      result.required = required;
+    }
+    return withDescription(schema, result);
+  }
+
+  if (schema instanceof z.ZodString) {
+    return withDescription(schema, { type: "string" });
+  }
+
+  if (schema instanceof z.ZodNumber) {
+    return withDescription(schema, { type: "number" });
+  }
+
+  if (schema instanceof z.ZodBoolean) {
+    return withDescription(schema, { type: "boolean" });
+  }
+
+  if (schema instanceof z.ZodArray) {
+    return withDescription(schema, {
+      type: "array",
+      items: convertZodType(schema.element),
+    });
+  }
+
+  if (schema instanceof z.ZodEnum) {
+    return withDescription(schema, {
+      type: "string",
+      enum: schema.options as string[],
+    });
+  }
+
+  if (schema instanceof z.ZodLiteral) {
+    const jsonType = schema.value === null ? "null" : typeof schema.value;
+    return withDescription(schema, { type: jsonType, const: schema.value });
+  }
+
+  if (schema instanceof z.ZodRecord) {
+    return withDescription(schema, {
+      type: "object",
+      additionalProperties: convertZodType(schema._def.valueType),
+    });
+  }
+
+  if (schema instanceof z.ZodUnion) {
+    const options = (schema._def.options as z.ZodTypeAny[]).map(convertZodType);
+    return withDescription(schema, { oneOf: options });
+  }
+
+  return {};
+}
+
+function withDescription(
+  schema: z.ZodTypeAny,
+  result: Record<string, unknown>,
+): Record<string, unknown> {
+  if (schema.description) {
+    result.description = schema.description;
+  }
+  return result;
+}
+
+function isOptionalType(schema: z.ZodTypeAny): boolean {
+  if (schema instanceof z.ZodOptional) return true;
+  if (schema instanceof z.ZodDefault) return true;
+  return false;
+}

package/src/trace/canonical.ts

@@ -0,0 +1,158 @@
+/**
+ * canonical — RFC 8785 JSON canonicalization with deterministic pre-processing.
+ *
+ * Pre-processing contract (applied depth-first before canonicalize):
+ *   - Buffer / Uint8Array   → base64 string (RFC 4648 §4, no padding stripping)
+ *   - undefined             → key is omitted (JSON.stringify-compatible semantics)
+ *   - Date                  → ISO-8601 string via .toISOString()
+ *   - BigInt                → { __bigint: string } (decimal representation)
+ *   - NaN / Infinity / -0   → throws NonSerializablePayloadError
+ *   - Circular references   → throws NonSerializablePayloadError
+ *   - Everything else       → left unchanged (strings, booleans, null, plain numbers)
+ *
+ * Usage:
+ *   import { canonicalize, NonSerializablePayloadError } from './canonical.js';
+ *   const json = canonicalize({ b: 2, a: 1 }); // '{"a":1,"b":2}'
+ *
+ * @module trace/canonical
+ */
+
+import { canonicalize as _rfcCanonicalize } from "json-canonicalize";
+
+/**
+ * Thrown when the value graph contains a non-serializable primitive
+ * (NaN, Infinity, -0) or a circular reference.
+ */
+export class NonSerializablePayloadError extends Error {
+  constructor(reason: string, public readonly path: string[]) {
+    super(`NonSerializablePayloadError: ${reason} at path /${path.join("/")}`);
+    this.name = "NonSerializablePayloadError";
+  }
+}
+
+/**
+ * Convert a Uint8Array (or Node Buffer) to a base64 string.
+ * Uses globalThis.btoa when available (browser/edge), falls back to
+ * Buffer.from().toString('base64') on Node.js.
+ */
+function uint8ToBase64(bytes: Uint8Array): string {
+  if (typeof globalThis.btoa === "function") {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    return globalThis.btoa(binary);
+  }
+  // Node.js fallback
+  return Buffer.from(bytes).toString("base64");
+}
+
+/**
+ * Recursively pre-process a value so that it is safe to pass to the
+ * RFC 8785 canonicalizer.  Returns a new value — never mutates input.
+ *
+ * @param value  Input to preprocess.
+ * @param path   Breadcrumb path for error messages (internal use).
+ * @param seen   Cycle detection set (internal use).
+ */
+function preprocess(
+  value: unknown,
+  path: string[],
+  seen: Set<object>,
+): unknown {
+  // Null / primitives (boolean, string, number — checked below for special floats)
+  if (value === null) return null;
+  if (value === undefined) return undefined; // caller omits the key
+
+  // Special float values that cannot be represented in JSON
+  if (typeof value === "number") {
+    if (Number.isNaN(value)) {
+      throw new NonSerializablePayloadError("NaN is not serializable", path);
+    }
+    if (!Number.isFinite(value)) {
+      throw new NonSerializablePayloadError(
+        `${value > 0 ? "Infinity" : "-Infinity"} is not serializable`,
+        path,
+      );
+    }
+    // -0: Object.is(-0, -0) → true but JSON.stringify(-0) === '0'.
+    // We normalise -0 → 0 would silently change data.  Throw instead.
+    if (Object.is(value, -0)) {
+      throw new NonSerializablePayloadError("-0 is not serializable", path);
+    }
+    return value;
+  }
+
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") return value;
+
+  // BigInt — JSON-serialisable wrapper
+  if (typeof value === "bigint") {
+    return { __bigint: value.toString(10) };
+  }
+
+  // Date → ISO-8601 string
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+
+  // Uint8Array / Buffer → base64 string
+  if (value instanceof Uint8Array) {
+    return uint8ToBase64(value);
+  }
+
+  // Objects and Arrays — cycle detection + recursive descent
+  if (typeof value === "object") {
+    if (seen.has(value as object)) {
+      throw new NonSerializablePayloadError("circular reference detected", path);
+    }
+    seen.add(value as object);
+
+    let result: unknown;
+    if (Array.isArray(value)) {
+      result = (value as unknown[]).map((item, i) =>
+        preprocess(item, [...path, String(i)], seen),
+      );
+    } else {
+      const obj: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+        const processed = preprocess(v, [...path, k], seen);
+        if (processed !== undefined) {
+          obj[k] = processed;
+        }
+        // undefined values → key omitted (consistent with JSON.stringify behaviour)
+      }
+      result = obj;
+    }
+
+    seen.delete(value as object); // allow same object to appear in sibling branches
+    return result;
+  }
+
+  // Functions, symbols, etc. — omit like JSON.stringify
+  if (typeof value === "function" || typeof value === "symbol") {
+    return undefined;
+  }
+
+  // Unreachable in TypeScript but guards against unknown runtime types
+  throw new NonSerializablePayloadError(
+    `unhandled type: ${typeof value}`,
+    path,
+  );
+}
+
+/**
+ * Produce the RFC 8785 canonical JSON string of any value.
+ *
+ * Pre-processes the value graph (Buffer→base64, Date→ISO-8601,
+ * BigInt→{__bigint}, undefined→omit, cycles/NaN/Inf/-0→throw)
+ * then applies `json-canonicalize` for deterministic key ordering.
+ *
+ * @throws {NonSerializablePayloadError} for NaN, Infinity, -0, or cycles.
+ */
+export function canonicalize(value: unknown): string {
+  const preprocessed = preprocess(value, [], new Set());
+  // json-canonicalize already handles key sorting per RFC 8785.
+  // We pass the pre-processed value (all types are now JSON-safe).
+  return _rfcCanonicalize(preprocessed);
+}

package/src/trace/policy.ts

@@ -0,0 +1,242 @@
+/**
+ * PayloadPolicy — 4-axis payload handling policy for trace steps.
+ *
+ * Axes:
+ *   include    — store the full (optionally PII-redacted) payload
+ *   redact     — remove PII fields before storing; hash the original
+ *   hmac       — hash + HMAC(original, out-of-band key); no plaintext stored
+ *   hash-only  — SHA-256 of canonical payload; no plaintext, no HMAC
+ *
+ * defaultPolicy(env, piiFields?) — fail-closed in production:
+ *   - prod without piiFields → throws PRODUCTION_PII_FIELDS_REQUIRED
+ *   - prod with piiFields    → { kind: 'redact', piiFields } (no detector by default, R8-I3)
+ *   - dev                    → { kind: 'include' } (full payloads for debugging)
+ *
+ * STRICT_PII_DETECTOR is opt-in only — never activated by defaultPolicy.
+ *
+ * @module trace/policy
+ */
+
+import { canonicalize } from "./canonical.js";
+
+// ─── PIIDetector port ────────────────────────────────────────────────────────
+
+/**
+ * A function that returns true when the given field value is suspected
+ * to contain PII. Used to extend structural redaction (piiFields) with
+ * heuristic scanning.
+ *
+ * NOTE: defaultPolicy does NOT activate a PIIDetector by default (R8-I3).
+ * Opt in explicitly: { kind: 'redact', piiFields: [...], piiDetector: STRICT_PII_DETECTOR }
+ */
+export type PIIDetector = (value: unknown) => boolean;
+
+// ─── PayloadPolicy discriminated union ───────────────────────────────────────
+
+/** Store the full payload (PII fields removed if present). Dev-safe. */
+export interface IncludePolicy {
+  kind: "include";
+}
+
+/** Remove piiFields from the stored payload. HMAC the original for auditability. */
+export interface RedactPolicy {
+  kind: "redact";
+  /** Field names to remove from the payload before storage. */
+  piiFields: readonly string[];
+  /**
+   * Optional detector run on every value in the payload. When it fires,
+   * the owning key is redacted even if not in piiFields.
+   * Intentionally absent by default (R8-I3 — false-positive risk).
+   */
+  piiDetector?: PIIDetector;
+}
+
+/** HMAC-SHA-256(canonical(original), key) + SHA-256 hash. No plaintext stored. */
+export interface HmacPolicy {
+  kind: "hmac";
+  /** Key provider for HMAC operations. */
+  keyProvider: import("../ports/key-provider.js").KeyProvider;
+  /** Key identifier passed to keyProvider.getKey(). */
+  keyId: string;
+}
+
+/** SHA-256(canonical(payload)) only. No plaintext, no HMAC. */
+export interface HashOnlyPolicy {
+  kind: "hash-only";
+}
+
+/** Discriminated union of all supported payload policies. */
+export type PayloadPolicy =
+  | IncludePolicy
+  | RedactPolicy
+  | HmacPolicy
+  | HashOnlyPolicy;
+
+// ─── SHA-256 via Web Crypto (zero external deps) ─────────────────────────────
+
+/**
+ * Compute SHA-256 of a UTF-8 string using Web Crypto API.
+ * Requires Node >= 20 (globalThis.crypto.subtle available).
+ */
+async function sha256(input: string): Promise<string> {
+  const encoded = new TextEncoder().encode(input);
+  const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", encoded);
+  return bufferToHex(hashBuffer);
+}
+
+/**
+ * Compute HMAC-SHA-256 of a UTF-8 string using Web Crypto API.
+ * @param input   The message to sign.
+ * @param key     Raw key bytes.
+ */
+async function hmacSha256(input: string, key: Uint8Array): Promise<string> {
+  // Ensure we have a plain ArrayBuffer (SharedArrayBuffer is not accepted by importKey)
+  const keyBuffer = key.buffer instanceof ArrayBuffer
+    ? key.buffer.slice(key.byteOffset, key.byteOffset + key.byteLength)
+    : new Uint8Array(key).buffer;
+  const cryptoKey = await globalThis.crypto.subtle.importKey(
+    "raw",
+    keyBuffer,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const encoded = new TextEncoder().encode(input);
+  const sigBuffer = await globalThis.crypto.subtle.sign("HMAC", cryptoKey, encoded);
+  return bufferToHex(sigBuffer);
+}
+
+function bufferToHex(buffer: ArrayBuffer): string {
+  return Array.from(new Uint8Array(buffer))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+// ─── Redaction helpers ────────────────────────────────────────────────────────
+
+/**
+ * Deep-redact piiFields and optionally piiDetector from an object.
+ * Returns a new object — never mutates input.
+ */
+function deepRedact(
+  value: unknown,
+  piiFields: ReadonlySet<string>,
+  piiDetector: PIIDetector | undefined,
+): unknown {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) {
+    return (value as unknown[]).map((item) =>
+      deepRedact(item, piiFields, piiDetector),
+    );
+  }
+  const result: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    if (piiFields.has(k)) {
+      result[k] = "[REDACTED]";
+    } else if (piiDetector !== undefined && piiDetector(v)) {
+      result[k] = "[REDACTED]";
+    } else {
+      result[k] = deepRedact(v, piiFields, piiDetector);
+    }
+  }
+  return result;
+}
+
+// ─── payloadHash ─────────────────────────────────────────────────────────────
+
+/**
+ * Result of applying a PayloadPolicy to a value.
+ */
+export interface PayloadHashResult {
+  /** Hex-encoded SHA-256 of canonical(processed_value). */
+  hash: string;
+  /** The effective policy kind that was applied. */
+  policy: PayloadPolicy["kind"];
+  /**
+   * The processed payload to store inline in the trace step.
+   * undefined for 'hmac' and 'hash-only' policies.
+   */
+  storedValue?: unknown;
+  /**
+   * HMAC-SHA-256(canonical(original), key).
+   * Present only when policy is 'hmac'.
+   */
+  hmac?: string;
+}
+
+/**
+ * Compute SHA-256(canonical(processed_value)) according to a PayloadPolicy.
+ *
+ * - include:   stores the full value; hash = SHA-256(canonical(value))
+ * - redact:    stores redacted value; hash = SHA-256(canonical(redacted))
+ * - hmac:      stores nothing; hash = SHA-256(canonical(value)); hmac = HMAC(canonical(value), key)
+ * - hash-only: stores nothing; hash = SHA-256(canonical(value))
+ */
+export async function payloadHash(
+  value: unknown,
+  policy: PayloadPolicy,
+): Promise<PayloadHashResult> {
+  const canonical = canonicalize(value);
+
+  switch (policy.kind) {
+    case "include": {
+      const hash = await sha256(canonical);
+      return { hash, policy: "include", storedValue: value };
+    }
+
+    case "redact": {
+      const piiSet = new Set(policy.piiFields);
+      const redacted = deepRedact(value, piiSet, policy.piiDetector);
+      const redactedCanonical = canonicalize(redacted);
+      const hash = await sha256(redactedCanonical);
+      return { hash, policy: "redact", storedValue: redacted };
+    }
+
+    case "hmac": {
+      const hash = await sha256(canonical);
+      const key = await policy.keyProvider.getKey(policy.keyId);
+      const hmac = await hmacSha256(canonical, key);
+      return { hash, policy: "hmac", hmac };
+    }
+
+    case "hash-only": {
+      const hash = await sha256(canonical);
+      return { hash, policy: "hash-only" };
+    }
+  }
+}
+
+// ─── defaultPolicy ───────────────────────────────────────────────────────────
+
+/**
+ * Factory for sensible default PayloadPolicies.
+ *
+ * Fail-closed production contract (CH2):
+ *   - Calling defaultPolicy('prod') without piiFields throws immediately.
+ *     This forces the caller to declare what PII exists — silence is not
+ *     consent in a production compliance context.
+ *   - To explicitly opt out of redaction in prod, use { kind: 'include' }
+ *     directly and accept the WARNING that will be logged at boot.
+ *
+ * STRICT_PII_DETECTOR is NOT activated by this function (R8-I3).
+ * Activate it explicitly: { kind: 'redact', piiFields: [...], piiDetector: STRICT_PII_DETECTOR }
+ *
+ * @param env        'dev' or 'prod'
+ * @param piiFields  Required in prod. Field names to structurally redact.
+ */
+export function defaultPolicy(
+  env: "dev" | "prod",
+  piiFields?: readonly string[],
+): PayloadPolicy {
+  if (env === "prod") {
+    if (!piiFields || piiFields.length === 0) {
+      throw new Error(
+        "PRODUCTION_PII_FIELDS_REQUIRED: production policy requires non-empty piiFields. " +
+          "Use { kind: 'include' } explicitly to opt out (will log a WARNING at boot).",
+      );
+    }
+    // piiDetector intentionally absent by default (R8-I3)
+    return { kind: "redact", piiFields };
+  }
+  return { kind: "include" };
+}