@kashscript/hudhud 0.1.0

package/src/ledger/writer.ts

@@ -0,0 +1,249 @@
+// ============================================================================
+// @kashscript/hudhud/ledger — ForensicLedgerService (the write side)
+// ----------------------------------------------------------------------------
+// The single append entry point: acquire the per-session mutex, resolve the
+// chain tip, verify the caller stepIndex, compute the canonical block hash,
+// verify the Ed25519 signature, and atomically insert. The self-signing path
+// (`appendActorTransition`) resolves + signs INSIDE the mutex so two concurrent
+// appends can never sign over a stale (prev, stepIndex). The chain-hash,
+// signature sign/verify, and forensic scan are attest's (M1 seed); this module
+// is the write-side orchestration. Ported from oreoasis-core-host/services/
+// ledger-writer (M5); errors neutralized (append → LedgerAppendError, tamper →
+// attest TamperError).
+// ============================================================================
+
+import {
+  KASH_DID_PATTERN,
+  LedgerSignatureError,
+  chainBlockHash,
+  forensicConsistencyScan,
+  signLedgerBlock,
+  verifyLedgerSignature,
+} from "@kashscript/attest";
+import type { DidRegistry, ForensicScanReport, LedgerBlockRecord, LedgerSignaturePayload } from "@kashscript/attest";
+
+import { LedgerAppendError } from "../errors";
+import { SessionMutex } from "./mutex";
+import { resolvePreviousBlockHash } from "./store";
+import type { LedgerStore } from "./store";
+
+export const ACTOR_CLASSES = ["AGENT", "SYSTEM_KERNEL", "OPERATOR_ADMIN", "COMPLIANCE_AUDITOR"] as const;
+export type ActorClass = (typeof ACTOR_CLASSES)[number];
+
+/** An in-process signing identity the host controls (the runtime key that signs
+ *  autonomous agent actions). The private key stays captured behind `sign()`. */
+export interface HostActorSigner {
+  readonly actorDid: string;
+  readonly actorClass: ActorClass;
+  sign(payload: LedgerSignaturePayload): Promise<string>;
+}
+
+/** Build a HostActorSigner from a raw Ed25519 private key. `actorDid` must be a
+ *  did:kash and be registered in the DidRegistry the service verifies against. */
+export function createEd25519HostSigner(opts: {
+  readonly actorDid: string;
+  readonly actorClass: ActorClass;
+  readonly privateKey: Uint8Array;
+}): HostActorSigner {
+  if (!KASH_DID_PATTERN.test(opts.actorDid)) {
+    throw new LedgerAppendError("host signer actorDid is not a valid did:kash:… identifier");
+  }
+  return {
+    actorDid: opts.actorDid,
+    actorClass: opts.actorClass,
+    sign: (payload) => signLedgerBlock(payload, opts.privateKey),
+  };
+}
+
+export interface AppendTransitionLogInput {
+  readonly sessionId: string;
+  readonly stepIndex: number;
+  readonly actorDid: string;
+  readonly actorClass: ActorClass;
+  readonly payloadMutation: Readonly<Record<string, unknown>>;
+  /** `ed25519:<128-hex>` wire form — verified inside the service. */
+  readonly signature: string;
+}
+
+export interface AppendedLedgerBlock {
+  readonly sessionId: string;
+  readonly stepIndex: number;
+  readonly actorDid: string;
+  readonly actorClass: ActorClass;
+  readonly previousBlockHash: string;
+  readonly currentTransactionBlockHash: string;
+  readonly signature: string;
+  readonly emittedAt: string;
+  readonly localLedgerId: number;
+}
+
+export interface ForensicLedgerServiceDeps {
+  readonly ledger: LedgerStore;
+  readonly sessionMutex: SessionMutex;
+  readonly didRegistry: DidRegistry;
+  /** Required only for `appendActorTransition` (the self-signing path). */
+  readonly hostSigner?: HostActorSigner;
+}
+
+export class ForensicLedgerService {
+  constructor(private readonly deps: ForensicLedgerServiceDeps) {}
+
+  /** Append a caller-pre-signed transition. @throws LedgerAppendError on any
+   *  validation / signature / store failure. */
+  async appendTransitionLog(input: AppendTransitionLogInput): Promise<AppendedLedgerBlock> {
+    if (typeof input.sessionId !== "string" || input.sessionId.length === 0) {
+      throw new LedgerAppendError("sessionId is required");
+    }
+    if (typeof input.actorDid !== "string" || !KASH_DID_PATTERN.test(input.actorDid)) {
+      throw new LedgerAppendError("actorDid must be a valid did:kash:… identifier");
+    }
+    if (typeof input.signature !== "string" || input.signature.length === 0) {
+      throw new LedgerAppendError("signature is required");
+    }
+    if (!ACTOR_CLASSES.includes(input.actorClass)) {
+      throw new LedgerAppendError(`actorClass must be one of [${ACTOR_CLASSES.join(", ")}]`);
+    }
+    if (!Number.isInteger(input.stepIndex) || input.stepIndex < 0) {
+      throw new LedgerAppendError("stepIndex must be a non-negative integer");
+    }
+
+    return this.deps.sessionMutex.run(input.sessionId, async () => {
+      const { previousBlockHash: resolvedPrev, nextStepIndex } = await resolvePreviousBlockHash(
+        this.deps.ledger,
+        input.sessionId,
+      );
+      if (input.stepIndex !== nextStepIndex) {
+        throw new LedgerAppendError(
+          `stepIndex ${input.stepIndex} does not match next expected ${nextStepIndex} for session ${input.sessionId}`,
+        );
+      }
+      return this.commitResolvedBlock({
+        sessionId: input.sessionId,
+        stepIndex: input.stepIndex,
+        actorDid: input.actorDid,
+        actorClass: input.actorClass,
+        payloadMutation: input.payloadMutation,
+        signature: input.signature,
+        resolvedPrev,
+      });
+    });
+  }
+
+  /** Self-signing append for the in-host autonomous actor: resolves + signs +
+   *  verifies + inserts atomically inside the per-session mutex. Requires
+   *  `deps.hostSigner`. */
+  async appendActorTransition(input: {
+    readonly sessionId: string;
+    readonly payloadMutation: Readonly<Record<string, unknown>>;
+  }): Promise<AppendedLedgerBlock> {
+    const signer = this.deps.hostSigner;
+    if (signer === undefined) {
+      throw new LedgerAppendError("appendActorTransition requires a configured hostSigner");
+    }
+    if (typeof input.sessionId !== "string" || input.sessionId.length === 0) {
+      throw new LedgerAppendError("sessionId is required");
+    }
+    if (input.payloadMutation === null || typeof input.payloadMutation !== "object" || Array.isArray(input.payloadMutation)) {
+      throw new LedgerAppendError("payloadMutation must be a plain object");
+    }
+
+    return this.deps.sessionMutex.run(input.sessionId, async () => {
+      const { previousBlockHash: resolvedPrev, nextStepIndex } = await resolvePreviousBlockHash(
+        this.deps.ledger,
+        input.sessionId,
+      );
+      const signature = await signer.sign({
+        sessionId: input.sessionId,
+        stepIndex: nextStepIndex,
+        actorDid: signer.actorDid,
+        previousBlockHash: resolvedPrev,
+        payloadMutation: input.payloadMutation,
+      });
+      return this.commitResolvedBlock({
+        sessionId: input.sessionId,
+        stepIndex: nextStepIndex,
+        actorDid: signer.actorDid,
+        actorClass: signer.actorClass,
+        payloadMutation: input.payloadMutation,
+        signature,
+        resolvedPrev,
+      });
+    });
+  }
+
+  /** MUST be called inside the session mutex — computes the canonical block
+   *  hash, verifies the signature, and inserts. */
+  private async commitResolvedBlock(args: {
+    readonly sessionId: string;
+    readonly stepIndex: number;
+    readonly actorDid: string;
+    readonly actorClass: ActorClass;
+    readonly payloadMutation: Readonly<Record<string, unknown>>;
+    readonly signature: string;
+    readonly resolvedPrev: string;
+  }): Promise<AppendedLedgerBlock> {
+    const currentTransactionBlockHash = await chainBlockHash(
+      {
+        sessionId: args.sessionId,
+        stepIndex: args.stepIndex,
+        actorDid: args.actorDid,
+        payloadMutation: args.payloadMutation,
+        signature: args.signature,
+      },
+      args.resolvedPrev,
+    );
+
+    try {
+      await verifyLedgerSignature({
+        signatureWire: args.signature,
+        payload: {
+          sessionId: args.sessionId,
+          stepIndex: args.stepIndex,
+          actorDid: args.actorDid,
+          previousBlockHash: args.resolvedPrev,
+          payloadMutation: args.payloadMutation,
+        },
+        didRegistry: this.deps.didRegistry,
+      });
+    } catch (cause) {
+      const reason = cause instanceof LedgerSignatureError ? cause.reason : "UNKNOWN";
+      throw new LedgerAppendError(`Ed25519 signature verification failed (${reason})`);
+    }
+
+    let record: LedgerBlockRecord;
+    try {
+      record = await this.deps.ledger.appendBlock({
+        sessionId: args.sessionId,
+        stepIndex: args.stepIndex,
+        previousBlockHash: args.resolvedPrev,
+        currentTransactionBlockHash,
+        actorDid: args.actorDid,
+        payloadMutation: args.payloadMutation,
+        signature: args.signature,
+      });
+    } catch (cause) {
+      throw new LedgerAppendError(`Ledger store write failed — ${cause instanceof Error ? cause.message : "unknown"}`);
+    }
+
+    return {
+      sessionId: record.sessionId,
+      stepIndex: record.stepIndex,
+      actorDid: record.actorDid,
+      actorClass: args.actorClass,
+      previousBlockHash: record.previousBlockHash,
+      currentTransactionBlockHash: record.currentTransactionBlockHash,
+      signature: record.signature,
+      emittedAt: record.emittedAt,
+      localLedgerId: record.localId,
+    };
+  }
+
+  /** Walk the whole chain for `sessionId` and re-verify hashes + signatures.
+   *  Delegates to attest's `forensicConsistencyScan` (throws `TamperError` on
+   *  the first variance: STEP_INDEX_GAP / PREVIOUS_HASH_MISMATCH /
+   *  PAYLOAD_HASH_VARIANCE / SIGNATURE_VERIFY_FAILED). */
+  async forensicConsistencyScan(sessionId: string): Promise<ForensicScanReport> {
+    const rows = await this.deps.ledger.listBlocksForSession(sessionId);
+    return forensicConsistencyScan(sessionId, rows, this.deps.didRegistry);
+  }
+}

package/src/mcp/allowlist.ts

@@ -0,0 +1,102 @@
+// ============================================================================
+// @kashscript/hudhud/mcp — MCP tool allowlist + per-tool argument governance
+// ----------------------------------------------------------------------------
+// Tracks which fully-qualified `<server>.<tool>` names each (institutionDid,
+// serverName) pair may dispatch, plus optional per-tool argument allow/require
+// key sets. Fully-qualified names route deterministically (no first-match-wins
+// hijack). Ported verbatim from the oreoasis-core-host engine (M5, ADR-0016).
+// ============================================================================
+
+export interface ToolArgSpec {
+  /** Whitelisted argument keys. Absent/empty ⇒ no restriction. */
+  readonly allowedKeys?: ReadonlyArray<string>;
+  /** Argument keys that MUST be present. */
+  readonly requiredKeys?: ReadonlyArray<string>;
+}
+
+export interface AllowlistEntry {
+  readonly institutionDid: string;
+  readonly serverName: string;
+  readonly transportProtocol: "HTTP_SSE" | "STDIO_STUB";
+  readonly endpointUrl: string;
+  /** Tool names WITHOUT the `<server>.` prefix. */
+  readonly allowlistTools: ReadonlyArray<string>;
+  readonly toolArgSpecs?: Readonly<Record<string, ToolArgSpec>>;
+  readonly isCircuitBroken: boolean;
+}
+
+export type ToolArgValidationResult =
+  | { ok: true }
+  | { ok: false; reason: "EXTRA_KEYS"; extraKeys: ReadonlyArray<string> }
+  | { ok: false; reason: "MISSING_REQUIRED"; missingKeys: ReadonlyArray<string> };
+
+/** Validate arguments against a per-tool spec (no spec ⇒ ok). */
+export function validateToolArgs(
+  args: Readonly<Record<string, unknown>>,
+  spec: ToolArgSpec | undefined,
+): ToolArgValidationResult {
+  if (spec === undefined) return { ok: true };
+  const argKeys = Object.keys(args);
+
+  if (spec.allowedKeys !== undefined && spec.allowedKeys.length > 0) {
+    const allowed = new Set(spec.allowedKeys);
+    const extras = argKeys.filter((k) => !allowed.has(k));
+    if (extras.length > 0) return { ok: false, reason: "EXTRA_KEYS", extraKeys: extras };
+  }
+  if (spec.requiredKeys !== undefined && spec.requiredKeys.length > 0) {
+    const present = new Set(argKeys);
+    const missing = spec.requiredKeys.filter((k) => !present.has(k));
+    if (missing.length > 0) return { ok: false, reason: "MISSING_REQUIRED", missingKeys: missing };
+  }
+  return { ok: true };
+}
+
+/** `<server>.<tool>`: lowercase alnum/_/- segments, mandatory dot. */
+export const FULLY_QUALIFIED_TOOL_PATTERN = /^[a-z0-9][a-z0-9_-]*\.[a-z0-9][a-z0-9._-]*$/;
+/** Tool-name length cap. */
+export const MAX_TOOL_NAME_LENGTH = 256;
+
+export interface ToolNameDecomposition {
+  readonly serverName: string;
+  readonly toolLocalName: string;
+}
+
+/** Decompose a fully-qualified tool name → (server, localName), or null if malformed. */
+export function decomposeToolName(fullyQualified: string): ToolNameDecomposition | null {
+  if (fullyQualified.length === 0 || fullyQualified.length > MAX_TOOL_NAME_LENGTH) return null;
+  if (!FULLY_QUALIFIED_TOOL_PATTERN.test(fullyQualified)) return null;
+  const dot = fullyQualified.indexOf(".");
+  return { serverName: fullyQualified.slice(0, dot), toolLocalName: fullyQualified.slice(dot + 1) };
+}
+
+export interface McpAllowlistStore {
+  /** Resolve a fully-qualified tool for a tenant; null if the server row is
+   *  unknown OR the local tool isn't on that server's allowlist. */
+  resolveForAction(institutionDid: string, fullyQualifiedTool: string): Promise<AllowlistEntry | null>;
+  upsert(entry: AllowlistEntry): Promise<void>;
+}
+
+/** In-memory store keyed by (institutionDid, serverName). O(1) resolve. */
+export class InMemoryMcpAllowlistStore implements McpAllowlistStore {
+  private readonly byKey = new Map<string, AllowlistEntry>();
+
+  private static key(institutionDid: string, serverName: string): string {
+    return `${institutionDid}::${serverName}`;
+  }
+
+  async upsert(entry: AllowlistEntry): Promise<void> {
+    this.byKey.set(InMemoryMcpAllowlistStore.key(entry.institutionDid, entry.serverName), {
+      ...entry,
+      allowlistTools: [...entry.allowlistTools],
+    });
+  }
+
+  async resolveForAction(institutionDid: string, fullyQualifiedTool: string): Promise<AllowlistEntry | null> {
+    const parts = decomposeToolName(fullyQualifiedTool);
+    if (parts === null) return null;
+    const entry = this.byKey.get(InMemoryMcpAllowlistStore.key(institutionDid, parts.serverName));
+    if (entry === undefined) return null;
+    if (!entry.allowlistTools.includes(parts.toolLocalName)) return null;
+    return entry;
+  }
+}

package/src/mcp/client.ts

@@ -0,0 +1,284 @@
+// ============================================================================
+// @kashscript/hudhud/mcp — McpClientPoolManager (JSON-RPC 2.0 + circuit breaker)
+// ----------------------------------------------------------------------------
+// Stateful HTTP/SSE JSON-RPC client pool. Owns:
+//   1. a per-serverUrl circuit breaker — FAIL-CLOSED on the first transport
+//      failure so a wedged endpoint can't stall the agent loop (manual reset);
+//   2. a hard timeout (default 5000ms) via AbortController, covering the body
+//      drain;
+//   3. JSON-RPC 2.0 outbound framing + inbound structural conformance — a
+//      non-conformant response is a protocol failure and trips the breaker;
+//   4. an injectable `fetchImpl` for tests.
+// Application-level JSON-RPC `{error}` blocks do NOT trip the breaker.
+//
+// Ported from the oreoasis-core-host engine (M5); `McpTimeoutException` →
+// neutral `McpTimeoutError`, telemetry made injectable (no node `process` dep).
+// ============================================================================
+
+import { McpTimeoutError } from "../errors";
+
+export const MCP_HARD_TIMEOUT_MS = 5000 as const;
+
+export interface McpClientPoolOptions {
+  readonly fetchImpl?: typeof fetch;
+  readonly timeoutMs?: number;
+  readonly nowMs?: () => number;
+  readonly defaultHeaders?: Readonly<Record<string, string>>;
+  /** Optional structured audit sink (default no-op — a library must not spam). */
+  readonly onTelemetry?: (payload: Record<string, unknown>) => void;
+}
+
+export interface McpJsonRpcErrorBlock {
+  readonly code: number;
+  readonly message: string;
+  readonly data?: unknown;
+}
+export interface McpJsonRpcSuccess {
+  readonly jsonrpc: "2.0";
+  readonly id: string;
+  readonly result: unknown;
+}
+export interface McpJsonRpcError {
+  readonly jsonrpc: "2.0";
+  readonly id: string;
+  readonly error: McpJsonRpcErrorBlock;
+}
+export type McpJsonRpcResponse = McpJsonRpcSuccess | McpJsonRpcError;
+
+export type McpToolCallResult =
+  | {
+      readonly ok: true;
+      readonly result: unknown;
+      readonly jsonRpcId: string;
+      readonly latencyMs: number;
+      readonly transportProtocol: "HTTP_SSE" | "STDIO_STUB";
+      readonly forwardedArguments: Readonly<Record<string, unknown>>;
+    }
+  | {
+      readonly ok: false;
+      readonly error: McpJsonRpcErrorBlock;
+      readonly jsonRpcId: string;
+      readonly latencyMs: number;
+      readonly transportProtocol: "HTTP_SSE" | "STDIO_STUB";
+      readonly forwardedArguments: Readonly<Record<string, unknown>>;
+    };
+
+export interface CircuitBreakerSnapshot {
+  readonly serverUrl: string;
+  readonly open: boolean;
+  readonly trippedAtMs: number | null;
+  readonly lastFailureReason: string | null;
+  readonly consecutiveFailures: number;
+}
+
+interface BreakerState {
+  open: boolean;
+  trippedAtMs: number | null;
+  lastFailureReason: string | null;
+  consecutiveFailures: number;
+}
+
+function emptyBreaker(): BreakerState {
+  return { open: false, trippedAtMs: null, lastFailureReason: null, consecutiveFailures: 0 };
+}
+
+export class McpClientPoolManager {
+  private readonly breakers = new Map<string, BreakerState>();
+  private readonly fetchImpl: typeof fetch;
+  private readonly timeoutMs: number;
+  private readonly now: () => number;
+  private readonly defaultHeaders: Readonly<Record<string, string>>;
+  private readonly onTelemetry: (payload: Record<string, unknown>) => void;
+  private rpcIdCounter = 0;
+
+  constructor(options: McpClientPoolOptions = {}) {
+    this.fetchImpl = options.fetchImpl ?? (globalThis.fetch as typeof fetch);
+    if (typeof this.fetchImpl !== "function") {
+      throw new Error("McpClientPoolManager: no global fetch available — pass fetchImpl in options");
+    }
+    this.timeoutMs = options.timeoutMs ?? MCP_HARD_TIMEOUT_MS;
+    if (this.timeoutMs <= 0 || this.timeoutMs > 60_000) {
+      throw new Error(`McpClientPoolManager: timeoutMs must be (0, 60000] — got ${this.timeoutMs}`);
+    }
+    this.now = options.nowMs ?? (() => Date.now());
+    this.defaultHeaders = Object.freeze({ ...(options.defaultHeaders ?? {}) });
+    this.onTelemetry = options.onTelemetry ?? (() => {});
+  }
+
+  getFetchImpl(): typeof fetch {
+    return this.fetchImpl;
+  }
+
+  private mintRpcId(): string {
+    this.rpcIdCounter += 1;
+    return `mcp-${this.now().toString(36)}-${this.rpcIdCounter.toString(36)}`;
+  }
+
+  private getBreaker(serverUrl: string): BreakerState {
+    let b = this.breakers.get(serverUrl);
+    if (b === undefined) {
+      b = emptyBreaker();
+      this.breakers.set(serverUrl, b);
+    }
+    return b;
+  }
+
+  snapshot(serverUrl: string): CircuitBreakerSnapshot {
+    const b = this.getBreaker(serverUrl);
+    return {
+      serverUrl,
+      open: b.open,
+      trippedAtMs: b.trippedAtMs,
+      lastFailureReason: b.lastFailureReason,
+      consecutiveFailures: b.consecutiveFailures,
+    };
+  }
+
+  resetCircuit(serverUrl: string): void {
+    this.breakers.set(serverUrl, emptyBreaker());
+    this.onTelemetry({ action: "circuit-reset", serverUrl, timestamp: this.now() });
+  }
+
+  isCircuitBroken(serverUrl: string): boolean {
+    return this.getBreaker(serverUrl).open;
+  }
+
+  /** Execute a JSON-RPC `tools/call`. Transport failures trip the breaker +
+   *  throw `McpTimeoutError`; JSON-RPC `{error}` blocks bubble as `{ok:false}`. */
+  async executeMcpToolCall(
+    serverUrl: string,
+    toolName: string,
+    argumentsBlock: Record<string, unknown>,
+  ): Promise<McpToolCallResult> {
+    if (typeof serverUrl !== "string" || serverUrl.length === 0) {
+      throw new McpTimeoutError(this.timeoutMs, "executeMcpToolCall: serverUrl is required");
+    }
+    if (typeof toolName !== "string" || toolName.length === 0) {
+      throw new McpTimeoutError(this.timeoutMs, "executeMcpToolCall: toolName is required");
+    }
+    if (argumentsBlock === null || typeof argumentsBlock !== "object") {
+      throw new McpTimeoutError(this.timeoutMs, "executeMcpToolCall: argumentsBlock must be a non-null object");
+    }
+
+    const breaker = this.getBreaker(serverUrl);
+    if (breaker.open) {
+      this.onTelemetry({ action: "dispatch-refused", reason: "CIRCUIT_OPEN", serverUrl, toolName });
+      throw new McpTimeoutError(
+        this.timeoutMs,
+        `MCP server '${serverUrl}' circuit is open (last failure: ${breaker.lastFailureReason ?? "<unknown>"})`,
+      );
+    }
+
+    const jsonRpcId = this.mintRpcId();
+    const requestEnvelope = {
+      jsonrpc: "2.0" as const,
+      id: jsonRpcId,
+      method: "tools/call",
+      params: { name: toolName, arguments: argumentsBlock },
+    };
+
+    const controller = new AbortController();
+    const startMs = this.now();
+    const timeoutHandle = setTimeout(() => controller.abort(new Error(`MCP_HARD_TIMEOUT_${this.timeoutMs}MS`)), this.timeoutMs);
+
+    let response: Response;
+    try {
+      response = await this.fetchImpl(serverUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json, text/event-stream",
+          "X-Json-Rpc-Id": jsonRpcId,
+          ...this.defaultHeaders,
+        },
+        body: JSON.stringify(requestEnvelope),
+        signal: controller.signal,
+      });
+    } catch (cause) {
+      clearTimeout(timeoutHandle);
+      return this.tripAndRaise(
+        serverUrl,
+        toolName,
+        jsonRpcId,
+        startMs,
+        cause instanceof Error && cause.name === "AbortError" ? "TRANSPORT_TIMEOUT" : "TRANSPORT_NETWORK_FAILURE",
+        cause,
+      );
+    }
+
+    if (!response.ok) {
+      clearTimeout(timeoutHandle);
+      return this.tripAndRaise(serverUrl, toolName, jsonRpcId, startMs, `TRANSPORT_HTTP_${response.status}`, new Error(`HTTP ${response.status}`));
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = await response.json();
+    } catch (cause) {
+      clearTimeout(timeoutHandle);
+      return this.tripAndRaise(serverUrl, toolName, jsonRpcId, startMs, "TRANSPORT_JSON_PARSE_FAILED", cause);
+    }
+    clearTimeout(timeoutHandle);
+
+    const validated = validateJsonRpcResponse(parsed, jsonRpcId);
+    if (validated === null) {
+      return this.tripAndRaise(serverUrl, toolName, jsonRpcId, startMs, "TRANSPORT_JSON_RPC_SHAPE_INVALID", new Error("bad JSON-RPC shape"));
+    }
+
+    breaker.consecutiveFailures = 0;
+    breaker.lastFailureReason = null;
+
+    const latencyMs = this.now() - startMs;
+    const transportProtocol = response.headers.get("Content-Type")?.toLowerCase().includes("text/event-stream")
+      ? ("HTTP_SSE" as const)
+      : ("STDIO_STUB" as const);
+
+    if ("error" in validated) {
+      return { ok: false, error: validated.error, jsonRpcId, latencyMs, transportProtocol, forwardedArguments: Object.freeze({ ...argumentsBlock }) };
+    }
+    return { ok: true, result: validated.result, jsonRpcId, latencyMs, transportProtocol, forwardedArguments: Object.freeze({ ...argumentsBlock }) };
+  }
+
+  private tripAndRaise(serverUrl: string, toolName: string, jsonRpcId: string, startMs: number, reason: string, cause: unknown): never {
+    const breaker = this.getBreaker(serverUrl);
+    breaker.open = true;
+    breaker.trippedAtMs = this.now();
+    breaker.lastFailureReason = reason;
+    breaker.consecutiveFailures += 1;
+    const latencyMs = this.now() - startMs;
+    this.onTelemetry({
+      action: "circuit-trip",
+      reason,
+      serverUrl,
+      toolName,
+      jsonRpcId,
+      latencyMs,
+      causeMessage: cause instanceof Error ? cause.message : String(cause),
+    });
+    throw new McpTimeoutError(this.timeoutMs, `MCP transport failure for '${serverUrl}' (${reason}); breaker tripped`);
+  }
+}
+
+/** Structural JSON-RPC 2.0 response conformance (exactly one of result|error). */
+function validateJsonRpcResponse(candidate: unknown, expectedId: string): McpJsonRpcResponse | null {
+  if (candidate === null || typeof candidate !== "object") return null;
+  const c = candidate as Record<string, unknown>;
+  if (c.jsonrpc !== "2.0") return null;
+  if (typeof c.id !== "string" && typeof c.id !== "number") return null;
+  const responseIdStr = typeof c.id === "string" ? c.id : String(c.id);
+  if (responseIdStr !== expectedId) return null;
+  const hasResult = Object.prototype.hasOwnProperty.call(c, "result");
+  const hasError = Object.prototype.hasOwnProperty.call(c, "error");
+  if (hasResult === hasError) return null;
+  if (hasResult) return { jsonrpc: "2.0", id: responseIdStr, result: c.result };
+  const e = c.error;
+  if (e === null || typeof e !== "object") return null;
+  const eo = e as Record<string, unknown>;
+  if (typeof eo.code !== "number" || typeof eo.message !== "string") return null;
+  const errorBlock: McpJsonRpcErrorBlock = {
+    code: eo.code,
+    message: eo.message,
+    ...(Object.prototype.hasOwnProperty.call(eo, "data") ? { data: eo.data } : {}),
+  };
+  return { jsonrpc: "2.0", id: responseIdStr, error: errorBlock };
+}

package/src/mcp/index.ts

@@ -0,0 +1,4 @@
+// @kashscript/hudhud/mcp — MCP tool governance: allowlist + per-tool argument
+// validation, and a JSON-RPC 2.0 client pool with a fail-closed circuit breaker.
+export * from "./allowlist";
+export * from "./client";