open-multi-agent-kit 0.90.5 → 0.90.7

package/examples/extensions/correctness-wall/README.md

@@ -0,0 +1,111 @@
+# Correctness Wall extension
+
+B2C patch safety gate for `edit` and `write` tool calls, plus an explicit `correctness_wall_evaluate` tool. Policy checks come from `omk-adaptorch-wpl` via a **relative import** (no workspace `package.json` dependency).
+
+## Usage
+
+From the `packages/coding-agent` directory (or repo root with a valid path):
+
+```bash
+omk --extension examples/extensions/correctness-wall/index.ts
+```
+
+Copy into user extensions for auto-discovery:
+
+```bash
+cp -r examples/extensions/correctness-wall ~/.omk/agent/extensions/correctness-wall/
+```
+
+## Claim boundaries
+
+- **In scope**: unified-diff preview for pending `edit`/`write`, fast policy wall (write scope, flags), optional OA adjudication when `correctness_wall_evaluate` is called with `runIds`, `previewOnly: false`, and an OA fixture file (env or tool param).
+- **Out of scope**: Replacing core hooks, modifying `packages/adaptorch-wpl` from this lane, or adding npm workspace dependencies. The extension only **imports** `evaluateCorrectnessWall` and `AdaptOrchClient` from `../../../../adaptorch-wpl/src/index.ts`.
+
+## Environment variables
+
+| Variable | Default | Meaning |
+|----------|---------|---------|
+| `OMK_PATCH_SAFETY_WALL_MODE` | `shadow` | `shadow` — log/notify only, never block. `soft` — block `BLOCKED` unless override. `hard` — block `BLOCKED` and `INCONCLUSIVE`. |
+| `OMK_WALL_SCOPE` | *(empty)* | Comma-separated glob/path prefixes allowed in the diff. Empty means scope checks do not approve any path (out-of-scope diffs can trigger blocking flags when paths are present). |
+| `OMK_WALL_OVERRIDE` | unset | When `1` / `true` / `yes`, `soft` mode does not block `BLOCKED` verdicts (human override). |
+| `OMK_WALL_REPAIR_BUDGET` | `1` | Capped regenerate budget: max **blocked attempts** per packet (keyed by `packetId` or SHA-256 of `kind` + sorted `OMK_WALL_SCOPE`) before repair hints are treated as exhausted. Also caps hint string count in UI/JSON. Persisted in `.omk/wall-cache/repair-budget.json`. Hints only — no auto-regenerate. |
+| `OMK_WALL_RUN_IDS` | *(empty)* | Comma-separated AdaptOrch run ids. On `edit`/`write` hooks, when non-empty **and** `OMK_WALL_OA_FIXTURE_PATH` (or per-tool `adjudicationFixturePath`) is set, evaluation uses `previewOnly: false` and OA adjudication via `resolveOaClientForEvaluation`. Otherwise hooks stay preview-only. |
+| `OMK_WALL_OA_FIXTURE_PATH` | unset | Path to OA adjudication fixture JSON. Used when `correctness_wall_evaluate` runs with `previewOnly: false` and non-empty `runIds`, and on edit/write hooks when combined with `OMK_WALL_RUN_IDS`. Overridden per call by `adjudicationFixturePath`. |
+| `OMK_WALL_AUTO_REGENERATE` | unset | When `1` / `true` / `yes`, `correctness_wall_evaluate` JSON may include a `regeneratePacket` (capped hints only; no automatic patch apply). |
+| `OMK_WALL_RECEIPT_SIGNING_SECRET` | unset | When set, verification receipts include `signedReceipt` (HMAC-SHA256 over digest composite). Never log or commit this value. |
+| `OMK_WALL_DEEP_PHASE` | `stub` | `docker` records deep-wall intent; hermetic runner still unavailable (batch-2). |
+| `OMK_WALL_OA_TRANSPORT` | `fixture` | `mcp` or `live` uses session-injected MCP `callTool` via `setWallAdaptOrchCallTool` (see `adjudication-fixture.ts`). Fixture path optional for receipt metadata when using `mcp`. |
+
+## OA adjudication fixture format
+
+Fixture file (JSON object). Each `run_id` must define the three AdaptOrch introspection payloads the in-memory client serves:
+
+```json
+{
+  "wall_version": "1",
+  "dispatchRecordId": "local-dev-dispatch",
+  "runsById": {
+    "run-oa-1": {
+      "run": { "run_id": "run-oa-1", "status": "completed" },
+      "artifacts": [{ "path": "out.md", "size_bytes": 42 }],
+      "traces": [{ "kind": "write", "level": "info" }]
+    }
+  }
+}
+```
+
+- **`wall_version`**: optional string copied onto the verification **receipt** returned by `correctness_wall_evaluate` (defaults to extension version `1`).
+- **`dispatchRecordId`**: optional; passed to OA adjudication when not set elsewhere.
+- **`runsById`**: required map; keys must match `runIds` in the tool call.
+
+`createInMemoryAdaptOrchClient` (in `adjudication-fixture.ts`) wraps these entries with the same transport pattern as `packages/adaptorch-wpl/test/b2c-wall-oa.test.ts`.
+
+## Tools
+
+### `correctness_wall_evaluate`
+
+Parameters:
+
+- `kind` (string, required)
+- `approvedWriteScope` (optional string array)
+- `previewOnly` (optional boolean, default `true`)
+- `diffPath` (optional string) — if omitted, returns an `INCONCLUSIVE` verdict card JSON
+- `runIds` (optional string array)
+- `packetId` (optional string)
+- `adjudicationFixturePath` (optional string) — OA fixture file; falls back to `OMK_WALL_OA_FIXTURE_PATH`
+
+Returns JSON text: `{ verdictCard, receipt }`, and `repairHints` when `verdictCard.verdict` is `BLOCKED`.
+
+The **`receipt`** includes standard `VerificationReceipt` fields from adaptorch-wpl plus **`wall_version`** (from the fixture or default).
+
+Example receipt fragment:
+
+```json
+{
+  "schemaVersion": 1,
+  "evaluatedAt": "2026-07-08T12:00:00.000Z",
+  "kind": "code-edit",
+  "runIds": ["run-oa-1"],
+  "previewOnly": false,
+  "wall_version": "1",
+  "adjudicationVerdict": "CONFIRMED",
+  "policyFlags": []
+}
+```
+
+## Edit/write gate
+
+On each `edit` or `write` `tool_call` hook:
+
+1. Build a unified diff preview from `event.input` (edits or write content).
+2. Call `evaluateCorrectnessWall` with scope from `OMK_WALL_SCOPE`. Default `previewOnly: true`; when `OMK_WALL_RUN_IDS` is non-empty and an OA fixture path is set (`OMK_WALL_OA_FIXTURE_PATH`), hooks use `previewOnly: false`, pass `runIds`, and supply the OA client from `resolveOaClientForEvaluation`.
+3. Apply `OMK_PATCH_SAFETY_WALL_MODE` blocking rules; blocked calls return `{ block: true, reason: "<short user message>" }`.
+4. Write a summary snapshot to `.omk/wall-cache/latest.json` (mode, verdict, `wouldBlock`, compact card summary, timestamp — no full diff or secrets).
+5. In `shadow` mode, append one NDJSON line per gated tool call to **`.omk/wall-cache/shadow-telemetry.ndjson`** (`event`, `wall_version`, `mode`, `verdict`, `wouldBlock`, `kind`, `tool`, `previewOnly`, `usedOaFixture`, `timestamp` — no diff or secrets).
+6. On `BLOCKED`, increment per-packet attempts in `.omk/wall-cache/repair-budget.json`. In `shadow` mode, append capped repair hints to the UI notification; when `attempts >= OMK_WALL_REPAIR_BUDGET`, append a repair-budget-exhausted message.
+
+## Limitations
+
+- Edit preview reads the target file from disk relative to session `cwd`; if the file is missing or paths are wrong, the hook may return `INCONCLUSIVE` (and block in `hard` mode).
+- Hook OA requires both `OMK_WALL_RUN_IDS` and a fixture path; if either is missing, hooks remain preview-only. Explicit `correctness_wall_evaluate` can still pass `runIds`, `previewOnly: false`, and `adjudicationFixturePath` per call.
+- Relative imports require loading this extension from the monorepo layout (or an equivalent path to `adaptorch-wpl` and `coding-agent` sources).

package/examples/extensions/correctness-wall/adjudication-fixture.ts

@@ -0,0 +1,151 @@
+/**
+ * OA adjudication fixture loader and in-memory AdaptOrch client for local/dev evaluation.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { AdaptOrchCallToolFn, AdaptOrchClient } from "../../../../adaptorch-wpl/src/index.ts";
+import {
+	createLiveAdaptOrchClient,
+	createInMemoryAdaptOrchClient as createWplInMemoryClient,
+	parseOaTransportModeFromEnv,
+} from "../../../../adaptorch-wpl/src/index.ts";
+
+/** Optional session-injected MCP `callTool` when `OMK_WALL_OA_TRANSPORT=mcp`. */
+let wallAdaptOrchCallTool: AdaptOrchCallToolFn | undefined;
+
+export function setWallAdaptOrchCallTool(fn: AdaptOrchCallToolFn | undefined): void {
+	wallAdaptOrchCallTool = fn;
+}
+
+/** Minimal capability surface an extension host may expose for live MCP transport. */
+export interface McpCallToolCapable {
+	callMcpTool?(server: string, name: string, args: Record<string, unknown>): Promise<unknown>;
+}
+
+/** Default MCP server name used by the live adaptorch transport. */
+export const ADAPTORCH_MCP_SERVER = "adaptorch";
+
+/**
+ * Build an {@link AdaptOrchCallToolFn} that forwards to a session MCP capability,
+ * or return `undefined` when the host does not expose `callMcpTool`. The adaptorch
+ * server name is used as the MCP target by default. Pure: does not touch module state.
+ */
+export function buildLiveCallToolFromCapability(
+	api: McpCallToolCapable,
+	server: string = ADAPTORCH_MCP_SERVER,
+): AdaptOrchCallToolFn | undefined {
+	if (typeof api.callMcpTool !== "function") return undefined;
+	return (name, args) => api.callMcpTool!(server, name, args);
+}
+
+/**
+ * Auto-wire live adaptorch MCP transport when the host exposes `callMcpTool`.
+ * Called once from the extension entry. Idempotent and a no-op when the capability
+ * is absent (fixture transport remains the default). Using the live client is still
+ * gated by `OMK_WALL_OA_TRANSPORT=mcp` (explicit operator opt-in).
+ */
+export function autoWireLiveAdaptOrch(api: McpCallToolCapable): void {
+	setWallAdaptOrchCallTool(buildLiveCallToolFromCapability(api));
+}
+
+export const CORRECTNESS_WALL_EXTENSION_VERSION = "1" as const;
+
+/** Per-run payloads returned by fake adaptorch_get_run / _get_artifacts / _get_traces. */
+export interface OaRunFixture {
+	run: unknown;
+	artifacts: unknown;
+	traces: unknown;
+}
+
+export interface AdjudicationFixtureFile {
+	/** Extension / fixture schema version (surfaced on verification receipts as wall_version). */
+	wall_version?: string;
+	/** Optional default dispatch record id for adjudication requests. */
+	dispatchRecordId?: string;
+	/** Map of AdaptOrch run_id → MCP tool payloads. */
+	runsById: Record<string, OaRunFixture>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseFixtureJson(raw: unknown): AdjudicationFixtureFile {
+	if (!isRecord(raw)) {
+		throw new Error("OA fixture root must be a JSON object");
+	}
+	const runsById = raw.runsById;
+	if (!isRecord(runsById)) {
+		throw new Error("OA fixture missing runsById object");
+	}
+	const normalized: Record<string, OaRunFixture> = {};
+	for (const [runId, entry] of Object.entries(runsById)) {
+		if (!isRecord(entry)) {
+			throw new Error(`OA fixture runsById.${runId} must be an object`);
+		}
+		if (!("run" in entry) || !("artifacts" in entry) || !("traces" in entry)) {
+			throw new Error(`OA fixture runsById.${runId} must include run, artifacts, and traces`);
+		}
+		normalized[runId] = {
+			run: entry.run,
+			artifacts: entry.artifacts,
+			traces: entry.traces,
+		};
+	}
+	return {
+		wall_version:
+			typeof raw.wall_version === "string" && raw.wall_version.length > 0
+				? raw.wall_version
+				: CORRECTNESS_WALL_EXTENSION_VERSION,
+		dispatchRecordId: typeof raw.dispatchRecordId === "string" ? raw.dispatchRecordId : undefined,
+		runsById: normalized,
+	};
+}
+
+export async function loadAdjudicationFixtureFile(filePath: string): Promise<AdjudicationFixtureFile> {
+	const text = await readFile(filePath, "utf-8");
+	const parsed: unknown = JSON.parse(text);
+	return parseFixtureJson(parsed);
+}
+
+/** In-memory {@link AdaptOrchClient} backed by fixture run payloads (delegates to omk-adaptorch-wpl). */
+export function createInMemoryAdaptOrchClient(fixture: AdjudicationFixtureFile): AdaptOrchClient {
+	return createWplInMemoryClient(fixture.runsById);
+}
+
+export function resolveAdjudicationFixturePath(toolParamPath?: string): string | undefined {
+	const fromTool = toolParamPath?.trim();
+	if (fromTool) return fromTool;
+	const fromEnv = process.env.OMK_WALL_OA_FIXTURE_PATH?.trim();
+	return fromEnv && fromEnv.length > 0 ? fromEnv : undefined;
+}
+
+export async function resolveOaClientForEvaluation(options: {
+	previewOnly: boolean;
+	runIds?: string[];
+	adjudicationFixturePath?: string;
+}): Promise<{ client?: AdaptOrchClient; fixture?: AdjudicationFixtureFile }> {
+	const runIds = options.runIds ?? [];
+	if (options.previewOnly || runIds.length === 0) {
+		return {};
+	}
+	const transportMode = parseOaTransportModeFromEnv();
+	if (transportMode === "mcp" && wallAdaptOrchCallTool !== undefined) {
+		const fixturePath = resolveAdjudicationFixturePath(options.adjudicationFixturePath);
+		const fixture = fixturePath !== undefined ? await loadAdjudicationFixtureFile(fixturePath) : undefined;
+		return {
+			client: createLiveAdaptOrchClient(wallAdaptOrchCallTool),
+			fixture,
+		};
+	}
+	const fixturePath = resolveAdjudicationFixturePath(options.adjudicationFixturePath);
+	if (!fixturePath) {
+		return {};
+	}
+	const fixture = await loadAdjudicationFixtureFile(fixturePath);
+	return { client: createInMemoryAdaptOrchClient(fixture), fixture };
+}
+
+export function wallVersionFromFixture(fixture?: AdjudicationFixtureFile): string {
+	return fixture?.wall_version ?? CORRECTNESS_WALL_EXTENSION_VERSION;
+}