ennodia 0.3.0 → 0.4.0

package/bench/fixtures/bug-recall/004-cancel-propagation/oracle.json

@@ -1,28 +0,0 @@
-{
-  "id": "004-cancel-propagation",
-  "title": "Run cancellation does not cancel child tasks",
-  "prompt": "Review the TypeScript fixture and list correctness bugs.",
-  "requiredFindings": [
-    {
-      "id": "missing-task-cancel-call",
-      "severity": "high",
-      "line": 20,
-      "description": "The loop finds running child tasks but never calls task.cancel(), leaving them running after the run is cancelled.",
-      "keywords": ["task.cancel", "running"]
-    },
-    {
-      "id": "mutates-run-in-place",
-      "severity": "medium",
-      "line": 17,
-      "description": "The function mutates the Run object in place before child task cancellation has succeeded, so callers can observe cancelled state while children continue running.",
-      "keywords": ["mutates", "cancelled", "children"]
-    }
-  ],
-  "knownFalsePositives": [
-    {
-      "id": "task-id-order",
-      "description": "Claims task ID order causes the cancellation bug.",
-      "terms": ["taskIds", "order"]
-    }
-  ]
-}

package/bench/fixtures/bug-recall/004-cancel-propagation/responses/claude-code-solo.md

@@ -1 +0,0 @@
-{"findings":[{"line":20,"summary":"The loop checks each running task but never calls task.cancel, so children keep running after cancellation."}]}

package/bench/fixtures/bug-recall/004-cancel-propagation/responses/codex-solo.md

@@ -1 +0,0 @@
-{"findings":[{"line":17,"summary":"The run is mutated to cancelled before children are cancelled, so callers can observe cancelled while children still run."}]}

package/bench/fixtures/bug-recall/004-cancel-propagation/responses/ennodia-parallel-compare.md

@@ -1 +0,0 @@
-{"findings":[{"line":20,"summary":"The loop finds running child tasks but never calls task.cancel, leaving running tasks alive."},{"line":17,"summary":"cancelRun mutates the run to cancelled before child cancellation succeeds, so children can continue running under a cancelled run."}]}

package/bench/results/.gitkeep

@@ -1 +0,0 @@
-

package/docs/evidence/building-ennodia.md

@@ -1,66 +0,0 @@
----
-title: Building Ennodia with Ennodia
-description: A real development case with a failed launch, a useful worker patch, and primary-agent review.
----
-
-# Building Ennodia with Ennodia
-
-Development record: September 6, 2026. These changes belong to the next release candidate.
-
-A local server could accept browser requests that started agent work without an intended origin check.
-The primary agent had a reproduced defect and a focused implementation task.
-It stayed in Codex and used Ennodia to dispatch the work.
-
-## What happened
-
-| Attempt | Observed result | Next action |
-| --- | --- | --- |
-| Claude Code with Sonnet | Authentication failed before the task ran. | Use another configured agent. |
-| OpenCode with its configured model | Reproduced the problem, edited four files, and added seven regression tests. | Review the patch in the primary conversation. |
-| Primary agent | Tightened malformed Host and Origin validation and preserved the native request size limit. | Run the combined verification suite. |
-
-The worker tested both the request handler and a real listening server.
-It also found that Bun can return an empty oversized-request error before the handler runs.
-Its proposed size-limit adjustment could not guarantee a structured response for every oversized request.
-The primary agent kept the hard limit and documented the actual behavior.
-
-The combined suite passed after integration.
-This demonstrates a useful contribution that still needed review and adaptation.
-It does not establish how long the primary agent alone would have taken.
-
-## What did not help
-
-A separate Compare review used a smaller GPT model with the rigorous-review skill.
-It reached the ten-minute task limit without returning a usable proposal.
-The primary agent completed those fixes locally.
-The record includes that failed attempt, rather than treating every delegation as a success.
-
-The Claude failure indicates an expired login, not model quality.
-The GPT attempt does not establish that the model or skill is generally unsuitable.
-Its observed result applies to this task, configuration, and time limit.
-
-A later broad documentation assignment through OpenCode also reached its ten-minute limit without producing edits.
-The primary agent completed those pages directly.
-This suggests testing smaller assignments and clearer execution controls. It does not establish a general provider limitation.
-
-## Inspect and reproduce
-
-The implementation and regressions are in the open repository:
-
-- [HTTP implementation](https://github.com/cherninlab/ennodia/blob/main/packages/ennodia-io/src/io.ts)
-- [HTTP regressions](https://github.com/cherninlab/ennodia/blob/main/packages/ennodia-io/src/io.test.ts)
-
-Use the release candidate checkout that contains this page.
-
-```sh
-bun install
-bun test packages/ennodia-io/src/io.test.ts
-bun run verify
-```
-
-The tests use local fixtures. They do not call model providers.
-A live repeat requires an authenticated supported agent.
-Save the worker output and the primary agent’s final diff when repeating the experiment.
-
-The practical benefit here was a reviewed contribution from another tool without moving the primary conversation.
-No token-saving or speed comparison was measured.

package/docs/evidence/docs-drift.md

@@ -1,73 +0,0 @@
----
-title: Find stale documentation
-description: Review current documentation without deleting useful historical records.
----
-
-# Find stale documentation
-
-A current guide can disagree with code while a historical document remains correct for its period.
-This exercise gives an additional agent a bounded review task.
-
-The fixture lives in `examples/docs-drift` in the Ennodia checkout.
-It contains deliberate documentation errors and a labeled migration record.
-
-## Try it
-
-The recording below shows an actual MCP run from the release candidate checkout.
-The final frame includes ten extra seconds for reading.
-
-<video controls preload="metadata" aria-label="Recorded Ennodia documentation review" style="width:100%; height:auto;" src="/demos/docs-drift.mp4"></video>
-
-The [terminal recording](/demos/docs-drift.cast) preserves the captured output and timing.
-The text below provides the same findings without video.
-
-1. Use a local checkout of Ennodia.
-2. Run the fixture’s behavior check.
-
-```sh
-bun examples/docs-drift/check.ts
-```
-
-3. Give this request to your primary agent.
-
-```text
-Use Ennodia MCP to review examples/docs-drift in a separate read-only task.
-Compare the current README with config.ts. Identify each conflicting claim.
-Distinguish current instructions from the labeled historical migration record.
-Return proposed corrections with file references. Bring the findings back here.
-```
-
-4. Review each proposed correction against the source.
-5. Update the current guide in your copy.
-6. Keep the historical migration record labeled as history.
-
-## Check the result
-
-The current implementation uses port `4545`, the variable `APP_PORT`, and the response `{ "ready": true }`.
-The README contains three conflicting current claims.
-The migration record describes the previous release and does not need the same changes.
-
-A useful review finds the three conflicts and preserves the historical distinction.
-A model can still miss a conflict or recommend deleting useful history.
-This exercise has known answers. It is not a general benchmark.
-
-## Recorded development trial
-
-On September 6, 2026, an Antigravity task through Ennodia found all three current documentation conflicts.
-It also identified the archive as a historical record that did not need changes.
-The primary agent checked each finding against the fixture source.
-This is one successful trial on a small known-answer example, not a general performance result.
-
-The fixture includes `recorded-run.json` with the answer, task IDs, timing, and verification notes.
-Local file URL prefixes were normalized for sharing.
-
-The video records a later successful repetition through the candidate's MCP server.
-It uses the configured default Antigravity model, with no model override.
-The opt-in script starts one real agent using your configured provider access:
-
-```sh
-bun examples/docs-drift/demo.ts --live antigravity
-```
-
-Replace `antigravity` with another installed, authenticated harness ID when needed.
-The recording uses the [asciicast format](https://docs.asciinema.org/manual/asciicast/v2/).

package/docs/evidence/skill-trial.md

@@ -1,68 +0,0 @@
----
-title: Try a skill separately
-description: Compare two reviews of one function while keeping the main conversation focused.
----
-
-# Try a skill separately
-
-A skill can improve a review, add irrelevant work, or make no difference.
-A small separate task gives you evidence before you use its recommendations.
-
-The fixture lives in `examples/skill-trial` in the Ennodia checkout.
-It contains a short function and a local contract with deliberate mismatches.
-
-## Prepare two comparable attempts
-
-1. Select one available agent and model.
-2. Check that the requested skill is installed for that agent.
-3. Give both attempts the same `retry.ts` and `contract.md` files.
-4. Keep the evaluator `check.ts` out of the review materials.
-5. Run the plain review and skill review as separate read-only tasks.
-
-```text
-Use Ennodia MCP for two separate read-only reviews of examples/skill-trial/retry.ts.
-Provide contract.md as the source of truth. Use the same agent and model.
-First run: request no additional skill.
-Second run: request the installed source-grounded-audit skill.
-Do not open check.ts until both reviews finish.
-Return each contract mismatch with a concrete failing input.
-Compare useful findings, unsupported claims, and time spent.
-```
-
-Your agent can use `ennodia_start_compositional` with one slice per attempt.
-Set `skillIds: []` on the plain slice and `skillIds: ["source-grounded-audit"]` on the skill slice.
-The [skill guide](/docs/guides/agent-skills/) describes installation and explicit selection.
-
-A native agent can self-select other available skills.
-An empty requested skill list does not guarantee a skill-free control.
-For strict measurement, use separate controlled skill inventories and record the skills actually loaded.
-
-## Validate the findings
-
-Run the evaluator after saving both reviews:
-
-```sh
-bun examples/skill-trial/check.ts
-```
-
-The supplied implementation deliberately fails some cases.
-Use each reported input to check a proposed fix in a disposable copy.
-A useful finding needs to explain a contract mismatch, not just suggest a stylistic change.
-Keep useful partial findings even if the skill adds other irrelevant advice.
-
-This fixture supports a repeatable workflow demonstration.
-No quality improvement is claimed for it.
-
-## Recorded development trial
-
-On September 6, 2026, two Antigravity tasks ran through Ennodia in separate temporary copies.
-The plain review found the six failing evaluator cases and an additional alternative-number-notation case.
-The requested-skill attempt produced no answer because native tool permissions blocked a required read.
-
-The agent command exited with code zero despite the permission denial.
-Ennodia initially labeled that task successful. This trial exposed a classification defect that the next release candidate fixes.
-The denied attempt cannot establish the quality of the skill.
-No permission bypass was used to force a successful result.
-
-The fixture includes `recorded-trial.json` with both observed outcomes and the diagnostic excerpt.
-Local paths were normalized, and CLI remediation instructions were omitted from the excerpt.

package/docs/reference/benchmarks.md

@@ -1,64 +0,0 @@
----
-title: Benchmarks
-description: Deterministic benchmark snapshots for Ennodia's multi-agent bug-recall suite.
----
-
-The first benchmark is `multi-model-bug-recall`: TypeScript review fixtures with
-committed bug oracles. It measures required-finding recall for a condition and
-checks for known false-positive traps.
-
-## Current Snapshot
-
-Snapshot date: `2026-07-06T14:49:00.060Z`
-
-Command:
-
-```sh
-bun run bench:bug-recall -- --out /tmp/ennodia-benchmark-snapshot
-```
-
-Mode: fixture, using committed reference outputs.
-
-The F1 score combines recall and precision. FP means false positive.
-
-| Condition | Cases | Recall | Precision | F1 | High recall | FP traps |
-| --- | ---: | ---: | ---: | ---: | ---: | ---: |
-| `claude-code-solo` | 4 | 87.5% | 100% | 93.3% | 100% | 0 |
-| `codex-solo` | 4 | 37.5% | 50% | 42.9% | 75% | 1 |
-| `ennodia-parallel-compare` | 4 | 100% | 100% | 100% | 100% | 0 |
-
-Fixture wins: `claude-code-solo` won 3 fixtures, and
-`ennodia-parallel-compare` won 1 fixture. Ennodia's value in this snapshot is
-recall consistency: it recovered every required finding without adding a
-false-positive trap.
-
-## How Scoring Works
-
-The scorer in `bench/bug-recall/scorer.ts` compares each output with committed
-case oracles:
-
-- recall: required findings matched
-- precision: claimed findings that were required
-- high recall: high-severity required findings matched
-- FP traps: known false positives claimed by the output
-
-The default benchmark is deterministic. It reads committed fixture responses and
-does not launch child agents:
-
-```sh
-bun run bench:bug-recall
-```
-
-Live mode starts real local harnesses and varies with installed command-line
-interface (CLI) versions, models, account state, and machine configuration:
-
-```sh
-bun run bench:bug-recall:live -- --fixture 001-missing-await
-```
-
-## Limitations
-
-This is a small TypeScript-focused fixture set. It is recall-oriented, not a
-general software-engineering leaderboard. Live runs are intentionally excluded
-from `bun run verify` because they consume real agent time and depend on local
-setup.

package/examples/docs-drift/README.md

@@ -1,8 +0,0 @@
-# Small Service
-
-This is an intentionally inconsistent documentation fixture for Ennodia.
-
-The current default port is 3000. Configure another port with `PORT`.
-The readiness response is `{ "status": "ok" }`.
-
-The [migration record](./archive/migration.md) describes the previous release.

package/examples/docs-drift/archive/migration.md

@@ -1,4 +0,0 @@
-# Migration record — previous release
-
-The previous release used port 3000, the `PORT` variable, and `{ "status": "ok" }`.
-This file is a historical record, not a current configuration guide.

package/examples/docs-drift/check.ts

@@ -1,7 +0,0 @@
-import assert from "node:assert/strict";
-import { DEFAULT_PORT, readPort, readiness } from "./config";
-assert.equal(DEFAULT_PORT, 4545);
-assert.equal(readPort({ APP_PORT: "5050" }), 5050);
-assert.equal(readPort({ PORT: "5050" }), 4545);
-assert.deepEqual(readiness(), { ready: true });
-console.log("Current behavior verified. Compare README claims with config.ts; preserve the labeled migration record.");

package/examples/docs-drift/config.ts

@@ -1,8 +0,0 @@
-export const DEFAULT_PORT = 4545;
-export function readPort(env: Record<string, string | undefined>): number {
-  const value = env.APP_PORT;
-  return value === undefined ? DEFAULT_PORT : Number(value);
-}
-export function readiness(): { ready: boolean } {
-  return { ready: true };
-}

package/examples/docs-drift/demo.ts

@@ -1,54 +0,0 @@
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { resolve } from "node:path";
-
-// Opt-in live example. This starts one real agent and uses its configured access.
-if (!process.argv.includes("--live")) {
-  console.log("Run: bun examples/docs-drift/demo.ts --live <harness-id>");
-  console.log("Example: bun examples/docs-drift/demo.ts --live antigravity");
-  process.exit(0);
-}
-const harnessId = process.argv[process.argv.indexOf("--live") + 1];
-if (!harnessId) throw new Error("Select an installed, authenticated harness ID.");
-const root = resolve(import.meta.dir, "../..");
-const client = new Client({ name: "ennodia-docs-demo", version: "1" });
-const transport = new StdioClientTransport({
-  command: "bun", args: ["run", "src/cli.ts"], cwd: root, stderr: "pipe",
-});
-async function call(name: string, args: Record<string, unknown>) {
-  const result = await client.callTool({ name, arguments: args });
-  const text = (result.content as { type: string; text?: string }[])
-    .filter((item) => item.type === "text").map((item) => item.text).join("\n");
-  if (result.isError) throw new Error(text);
-  return JSON.parse(text);
-}
-try {
-  console.log("Ennodia live example: find stale documentation");
-  console.log(`Agent: ${harnessId}; configured default model; no model override.`);
-  console.log("Read-only task: check README against config.ts; preserve labeled history.");
-  await client.connect(transport);
-  const run = await call("ennodia_run", {
-    harnessId, mode: "single", compare: false, cwd: import.meta.dir, timeoutMs: 120000,
-    prompt: "Read only README.md, config.ts, and archive/migration.md. Compare current README claims with config.ts. Return each conflict and its correction in plain text, with relative file names only. Explain if the labeled historical migration record needs changes. Do not read other files or edit anything. Keep the response under 180 words.",
-  });
-  console.log(`Run: ${run.id}\nStatus: ${run.status}`);
-  const deadline = Date.now() + 135000;
-  for (;;) {
-    await Bun.sleep(2000);
-    const result = await call("ennodia_get_run", { runId: run.id, includeEvents: false, maxAnswerChars: 5000 });
-    if (["succeeded", "failed", "cancelled"].includes(result.status)) {
-      console.log(`Status: ${result.status}\nElapsed: ${result.elapsedMs} ms`);
-      console.log(result.finalAnswer || JSON.stringify(result.diagnosis ?? "No answer returned."));
-      console.log("Check each finding against config.ts before using it.");
-      console.log("This is one live attempt, without a speed or cost comparison.");
-      if (result.status !== "succeeded") process.exitCode = 1;
-      break;
-    }
-    if (Date.now() > deadline) {
-      await call("ennodia_cancel_run", { runId: run.id });
-      throw new Error("The bounded demo wait expired.");
-    }
-  }
-} finally {
-  await client.close();
-}

package/examples/docs-drift/recorded-run.json

@@ -1,16 +0,0 @@
-{
-  "recordedAt": "2026-09-06",
-  "kind": "single development trial",
-  "harness": "antigravity",
-  "model": "Configured default; exact model not established",
-  "runId": "d3e36bf1-07dd-4912-af33-b5c904603b44",
-  "taskIds": [
-    "e822af92-4410-4ed8-9382-f62a6f36a505"
-  ],
-  "status": "succeeded",
-  "elapsedMs": 13272,
-  "output": "* **Default Port Conflict**: [README.md:L5](../docs-drift/README.md#L5) claims the default port is `3000`, but [config.ts:L1](../docs-drift/config.ts#L1) defines [`DEFAULT_PORT`](../docs-drift/config.ts#L1) as `4545`.\n* **Port Environment Variable Conflict**: [README.md:L5](../docs-drift/README.md#L5) instructs users to configure ports using `PORT`, whereas [`readPort`](../docs-drift/config.ts#L2-L5) in [config.ts:L3](../docs-drift/config.ts#L3) reads `APP_PORT`.\n* **Readiness Response Conflict**: [README.md:L6](../docs-drift/README.md#L6) states the readiness response is `{ \"status\": \"ok\" }`, but [`readiness`](../docs-drift/config.ts#L6-L8) in [config.ts:L6-L7](../docs-drift/config.ts#L6-L7) returns `{ ready: true }`.\n* **Archive Status**: [archive/migration.md](../docs-drift/archive/migration.md#L1-L5) does **not** need changes; as stated in [archive/migration.md:L3-L4](../docs-drift/archive/migration.md#L3-L4), it is explicitly labeled as a historical migration record of the previous release rather than active configuration documentation.",
-  "edits": "Local file URL prefixes normalized to fixture-relative paths.",
-  "verification": "Primary agent checked all three conflicts and the historical distinction against the fixture.",
-  "limitation": "Known-answer fixture. No control run or speed or cost advantage established."
-}

package/examples/skill-trial/README.md

@@ -1,8 +0,0 @@
-# Try a review skill on one small function
-
-Compare `retry.ts` with `contract.md`. The function has deliberate defects.
-Run a plain review and a review with a native installed skill in separate tasks.
-Use the same model, files, and request. Save both findings before opening `check.ts`.
-
-The evaluator contains the expected cases. Keep it out of the review material.
-This example demonstrates the workflow. It does not establish that a skill improves quality.

package/examples/skill-trial/check.ts

@@ -1,15 +0,0 @@
-import { retryDelaySeconds } from "./retry";
-const cases: [string | null, number][] = [
-  [null, 30], ["0", 0], ["12", 12], ["120", 120], ["", 30], [" ", 30],
-  ["1.5", 30], ["-1", 30], ["121", 30], ["1e2", 30], ["0x10", 30],
-];
-let failures = 0;
-for (const [input, expected] of cases) {
-  const actual = retryDelaySeconds(input);
-  if (actual !== expected) {
-    failures += 1;
-    console.log(`${JSON.stringify(input)}: expected ${expected}, received ${actual}`);
-  }
-}
-console.log(`${cases.length - failures}/${cases.length} contract cases passed.`);
-process.exitCode = failures ? 1 : 0;

package/examples/skill-trial/contract.md

@@ -1,7 +0,0 @@
-# Retry delay contract
-
-- A missing value uses 30 seconds.
-- A decimal integer from 0 through 120 specifies the delay in seconds.
-- Zero is valid and means retry immediately.
-- Empty values, whitespace, fractions, negative values, and values over 120 use 30 seconds.
-- The function must not accept numeric notation such as `1e2` or `0x10`.

package/examples/skill-trial/recorded-trial.json

@@ -1,42 +0,0 @@
-{
-  "recordedAt": "2026-09-06",
-  "kind": "inconclusive native skill trial",
-  "harness": "antigravity",
-  "model": "Configured default; exact model not established",
-  "plain": {
-    "taskId": "125ffd40-c224-4615-a441-f31154a26096",
-    "status": "succeeded",
-    "elapsedMs": 18023,
-    "requestedSkills": [],
-    "output": "Contract violations identified in [`retryDelaySeconds`](./retry.ts#L2) based on [contract.md](./contract.md):\n\n* **Zero input (`\"0\"`)**: Returns `30` instead of `0` because `Number(\"0\")` evaluates to `0`, which is falsy in `0 || 30`.\n* **Values exceeding upper bound (`\"121\"`)**: Returns `121` instead of `30` because there is no `> 120` boundary check.\n* **Negative values (`\"-1\"`)**: Returns `-1` instead of `30` because negative numbers are truthy and not checked against `< 0`.\n* **Fractions (`\"1.5\"`)**: Returns `1.5` instead of `30` because `Number(\"1.5\")` parses floats without integer validation.\n* **Scientific notation (`\"1e2\"`)**: Returns `100` instead of `30`, directly violating the rule disallowing numeric notation like `1e2`.\n* **Hexadecimal notation (`\"0x10\"`)**: Returns `16` instead of `30`, directly violating the rule disallowing numeric notation like `0x10`.\n* **Binary / octal notation (`\"0b10\"`)**: Returns `2` instead of `30` because `Number()` parses alternative radix notations instead of strictly decimal integers.\n"
-  },
-  "requestedSkill": {
-    "taskId": "233ba69d-b691-4e34-94db-c3fa03a759bb",
-    "reportedStatus": "succeeded",
-    "observedOutcome": "No answer; required read_file access denied",
-    "exitCode": 0,
-    "elapsedMs": 17290,
-    "requestedSkills": [
-      {
-        "id": "source-grounded-audit",
-        "name": "source-grounded-audit",
-        "version": "local",
-        "hash": "87366950aa303123d38f7d97cd6cc01a842ca7cc18ffc41f75653bec76fe9cfa",
-        "source": "project",
-        "harnessIds": [
-          "antigravity",
-          "claude-code",
-          "codex",
-          "installable",
-          "opencode"
-        ],
-        "native": true
-      }
-    ],
-    "stderrExcerpt": "jetski: no output produced — a tool required the \"read_file\" permission that headless mode cannot prompt for, so it was auto-denied.",
-    "output": ""
-  },
-  "edits": "Local file URL prefixes normalized; CLI remediation instructions omitted from the diagnostic excerpt.",
-  "verification": "Plain findings checked against the contract and evaluator. This denied attempt cannot measure skill effectiveness.",
-  "limitation": "Uncontrolled native skill inventory; loading not verified. The zero-exit false success is fixed in the release candidate."
-}

package/examples/skill-trial/retry.ts

@@ -1,4 +0,0 @@
-// Deliberately incomplete implementation for a review exercise.
-export function retryDelaySeconds(value: string | null): number {
-  return Number(value) || 30;
-}