ennodia 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +2 -19
- package/README.md +4 -6
- package/docs/comparisons/agent-frameworks.md +5 -5
- package/docs/comparisons/autogen.md +4 -4
- package/docs/comparisons/chathub.md +4 -4
- package/docs/comparisons/index.md +4 -4
- package/docs/comparisons/langgraph.md +4 -4
- package/docs/comparisons/mixture-of-agents.md +5 -5
- package/docs/comparisons/model-merging.md +5 -5
- package/docs/comparisons/openrouter.md +4 -4
- package/docs/concepts/compositional-audits.md +8 -6
- package/docs/concepts/data-governance.md +5 -9
- package/docs/concepts/how-ennodia-works.md +2 -2
- package/docs/concepts/interfaces-and-core.md +1 -1
- package/docs/concepts/second-opinions.md +5 -5
- package/docs/evidence/index.md +6 -13
- package/docs/evidence/measurement.md +6 -5
- package/docs/getting-started.md +9 -6
- package/docs/guides/agent-skills.md +6 -5
- package/docs/guides/budgets-and-limits.md +8 -6
- package/docs/guides/pragmatic-mode.md +2 -0
- package/docs/guides/recipes.md +1 -4
- package/docs/guides/running-better-audits.md +7 -7
- package/docs/guides/troubleshooting.md +0 -2
- package/docs/guides/understand-results.md +0 -2
- package/docs/index.md +2 -4
- package/docs/install.md +11 -9
- package/docs/reference/controlled-english.md +1 -3
- package/docs/reference/ennodia-io.md +7 -7
- package/docs/reference/mcp-tools.md +69 -15
- package/docs/reference/supported-harnesses.md +9 -4
- package/docs/roadmap.md +0 -2
- package/package.json +3 -10
- package/skills/pragmatic/SKILL.md +2 -0
- package/src/cli.ts +31 -15
- package/src/compare.ts +37 -1
- package/src/core.ts +2 -4
- package/src/diagnosis.ts +48 -1
- package/src/harnesses.ts +54 -25
- package/src/index.ts +4 -0
- package/src/runs.ts +17 -8
- package/src/server.ts +55 -2
- package/src/tasks.ts +145 -37
- package/src/version.ts +1 -1
- package/bench/README.md +0 -34
- package/bench/bug-recall/run.ts +0 -339
- package/bench/bug-recall/scorer.ts +0 -424
- package/bench/fixtures/bug-recall/001-missing-await/input.ts +0 -33
- package/bench/fixtures/bug-recall/001-missing-await/oracle.json +0 -28
- package/bench/fixtures/bug-recall/001-missing-await/responses/claude-code-solo.md +0 -1
- package/bench/fixtures/bug-recall/001-missing-await/responses/codex-solo.md +0 -1
- package/bench/fixtures/bug-recall/001-missing-await/responses/ennodia-parallel-compare.md +0 -1
- package/bench/fixtures/bug-recall/002-timeout-drain/input.ts +0 -40
- package/bench/fixtures/bug-recall/002-timeout-drain/oracle.json +0 -28
- package/bench/fixtures/bug-recall/002-timeout-drain/responses/claude-code-solo.md +0 -1
- package/bench/fixtures/bug-recall/002-timeout-drain/responses/codex-solo.md +0 -1
- package/bench/fixtures/bug-recall/002-timeout-drain/responses/ennodia-parallel-compare.md +0 -1
- package/bench/fixtures/bug-recall/003-schema-contract/input.ts +0 -22
- package/bench/fixtures/bug-recall/003-schema-contract/oracle.json +0 -28
- package/bench/fixtures/bug-recall/003-schema-contract/responses/claude-code-solo.md +0 -1
- package/bench/fixtures/bug-recall/003-schema-contract/responses/codex-solo.md +0 -1
- package/bench/fixtures/bug-recall/003-schema-contract/responses/ennodia-parallel-compare.md +0 -1
- package/bench/fixtures/bug-recall/004-cancel-propagation/input.ts +0 -28
- package/bench/fixtures/bug-recall/004-cancel-propagation/oracle.json +0 -28
- package/bench/fixtures/bug-recall/004-cancel-propagation/responses/claude-code-solo.md +0 -1
- package/bench/fixtures/bug-recall/004-cancel-propagation/responses/codex-solo.md +0 -1
- package/bench/fixtures/bug-recall/004-cancel-propagation/responses/ennodia-parallel-compare.md +0 -1
- package/bench/results/.gitkeep +0 -1
- package/docs/evidence/building-ennodia.md +0 -66
- package/docs/evidence/docs-drift.md +0 -73
- package/docs/evidence/skill-trial.md +0 -68
- package/docs/reference/benchmarks.md +0 -64
- package/examples/docs-drift/README.md +0 -8
- package/examples/docs-drift/archive/migration.md +0 -4
- package/examples/docs-drift/check.ts +0 -7
- package/examples/docs-drift/config.ts +0 -8
- package/examples/docs-drift/demo.ts +0 -54
- package/examples/docs-drift/recorded-run.json +0 -16
- package/examples/skill-trial/README.md +0 -8
- package/examples/skill-trial/check.ts +0 -15
- package/examples/skill-trial/contract.md +0 -7
- package/examples/skill-trial/recorded-trial.json +0 -42
- package/examples/skill-trial/retry.ts +0 -4
package/bench/bug-recall/run.ts
DELETED
|
@@ -1,339 +0,0 @@
|
|
|
1
|
-
import { mkdir, readdir, writeFile } from "node:fs/promises";
|
|
2
|
-
import { basename, join } from "node:path";
|
|
3
|
-
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
|
4
|
-
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
|
|
5
|
-
import {
|
|
6
|
-
buildPrompt,
|
|
7
|
-
DEFAULT_FIXTURES_ROOT,
|
|
8
|
-
formatConditionTable,
|
|
9
|
-
loadCases,
|
|
10
|
-
scoreBenchmark,
|
|
11
|
-
type BenchmarkCase,
|
|
12
|
-
type BenchmarkSummary,
|
|
13
|
-
type OutputRecord,
|
|
14
|
-
} from "./scorer";
|
|
15
|
-
import { ENNODIA_VERSION } from "../../src/version";
|
|
16
|
-
|
|
17
|
-
type CliOptions = {
|
|
18
|
-
live: boolean;
|
|
19
|
-
fixtureIds: string[];
|
|
20
|
-
harnessIds: string[];
|
|
21
|
-
timeoutMs: number;
|
|
22
|
-
outDir?: string;
|
|
23
|
-
judgeHarnessId?: string;
|
|
24
|
-
advisorHarnessId?: string;
|
|
25
|
-
};
|
|
26
|
-
|
|
27
|
-
type McpTextContent = {
|
|
28
|
-
type: "text";
|
|
29
|
-
text: string;
|
|
30
|
-
};
|
|
31
|
-
|
|
32
|
-
type RunView = {
|
|
33
|
-
id: string;
|
|
34
|
-
status: "executing" | "comparing" | "succeeded" | "failed" | "cancelled";
|
|
35
|
-
finalAnswer?: string;
|
|
36
|
-
selectedHarnessIds?: string[];
|
|
37
|
-
taskIds?: string[];
|
|
38
|
-
compareId?: string;
|
|
39
|
-
elapsedMs?: number;
|
|
40
|
-
error?: string;
|
|
41
|
-
};
|
|
42
|
-
|
|
43
|
-
const DEFAULT_LIVE_HARNESSES = ["codex", "claude-code"];
|
|
44
|
-
|
|
45
|
-
const options = parseArgs(Bun.argv.slice(2));
|
|
46
|
-
const cases = await selectCases(await loadCases(), options.fixtureIds);
|
|
47
|
-
const outputs = options.live
|
|
48
|
-
? await runLiveBenchmark(cases, options)
|
|
49
|
-
: await loadFixtureOutputs(cases);
|
|
50
|
-
const summary = await scoreBenchmark({
|
|
51
|
-
cases,
|
|
52
|
-
outputs,
|
|
53
|
-
mode: options.live ? "live" : "fixture",
|
|
54
|
-
});
|
|
55
|
-
const outDir = await resolveOutDir(options, summary);
|
|
56
|
-
|
|
57
|
-
await writeSummary(outDir, summary, outputs);
|
|
58
|
-
|
|
59
|
-
console.log(formatConditionTable(summary));
|
|
60
|
-
console.log("");
|
|
61
|
-
console.log(`Wrote benchmark results to ${outDir}`);
|
|
62
|
-
|
|
63
|
-
async function loadFixtureOutputs(cases: BenchmarkCase[]): Promise<OutputRecord[]> {
|
|
64
|
-
const outputs: OutputRecord[] = [];
|
|
65
|
-
|
|
66
|
-
for (const benchmarkCase of cases) {
|
|
67
|
-
const responseDir = new URL(
|
|
68
|
-
`${benchmarkCase.id}/responses/`,
|
|
69
|
-
DEFAULT_FIXTURES_ROOT,
|
|
70
|
-
);
|
|
71
|
-
const entries = await readdir(responseDir, { withFileTypes: true });
|
|
72
|
-
const files = entries
|
|
73
|
-
.filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
|
|
74
|
-
.map((entry) => entry.name)
|
|
75
|
-
.sort();
|
|
76
|
-
|
|
77
|
-
for (const file of files) {
|
|
78
|
-
outputs.push({
|
|
79
|
-
caseId: benchmarkCase.id,
|
|
80
|
-
condition: basename(file, ".md"),
|
|
81
|
-
text: await Bun.file(new URL(file, responseDir)).text(),
|
|
82
|
-
metadata: { mode: "fixture", source: file },
|
|
83
|
-
});
|
|
84
|
-
}
|
|
85
|
-
}
|
|
86
|
-
|
|
87
|
-
return outputs;
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
async function runLiveBenchmark(
|
|
91
|
-
cases: BenchmarkCase[],
|
|
92
|
-
options: CliOptions,
|
|
93
|
-
): Promise<OutputRecord[]> {
|
|
94
|
-
const client = new Client({
|
|
95
|
-
name: "ennodia-benchmark",
|
|
96
|
-
version: ENNODIA_VERSION,
|
|
97
|
-
});
|
|
98
|
-
const transport = new StdioClientTransport({
|
|
99
|
-
command: "bun",
|
|
100
|
-
args: ["run", "src/cli.ts"],
|
|
101
|
-
cwd: new URL("../../", import.meta.url).pathname,
|
|
102
|
-
stderr: "pipe",
|
|
103
|
-
});
|
|
104
|
-
await client.connect(transport);
|
|
105
|
-
|
|
106
|
-
try {
|
|
107
|
-
const outputs: OutputRecord[] = [];
|
|
108
|
-
const harnessIds = options.harnessIds.length > 0
|
|
109
|
-
? options.harnessIds
|
|
110
|
-
: DEFAULT_LIVE_HARNESSES;
|
|
111
|
-
|
|
112
|
-
for (const benchmarkCase of cases) {
|
|
113
|
-
const prompt = buildPrompt(benchmarkCase);
|
|
114
|
-
|
|
115
|
-
for (const harnessId of harnessIds) {
|
|
116
|
-
const run = await startAndWaitForRun(client, {
|
|
117
|
-
prompt,
|
|
118
|
-
harnessId,
|
|
119
|
-
mode: "single",
|
|
120
|
-
compare: false,
|
|
121
|
-
timeoutMs: options.timeoutMs,
|
|
122
|
-
});
|
|
123
|
-
outputs.push(runToOutput(benchmarkCase.id, `${harnessId}-solo`, run));
|
|
124
|
-
}
|
|
125
|
-
|
|
126
|
-
const parallelRun = await startAndWaitForRun(client, {
|
|
127
|
-
prompt,
|
|
128
|
-
mode: "parallel",
|
|
129
|
-
compare: true,
|
|
130
|
-
timeoutMs: options.timeoutMs,
|
|
131
|
-
judgeHarnessId: options.judgeHarnessId,
|
|
132
|
-
advisorHarnessId: options.advisorHarnessId,
|
|
133
|
-
maxOutputChars: 16_000,
|
|
134
|
-
});
|
|
135
|
-
outputs.push(runToOutput(
|
|
136
|
-
benchmarkCase.id,
|
|
137
|
-
"ennodia-parallel-compare",
|
|
138
|
-
parallelRun,
|
|
139
|
-
));
|
|
140
|
-
}
|
|
141
|
-
|
|
142
|
-
return outputs;
|
|
143
|
-
} finally {
|
|
144
|
-
await client.close();
|
|
145
|
-
}
|
|
146
|
-
}
|
|
147
|
-
|
|
148
|
-
async function startAndWaitForRun(
|
|
149
|
-
client: Client,
|
|
150
|
-
args: Record<string, unknown>,
|
|
151
|
-
): Promise<RunView> {
|
|
152
|
-
const started = parseTextResult(await client.callTool({
|
|
153
|
-
name: "ennodia_run",
|
|
154
|
-
arguments: args,
|
|
155
|
-
})) as RunView;
|
|
156
|
-
|
|
157
|
-
let run = started;
|
|
158
|
-
while (run.status === "executing" || run.status === "comparing") {
|
|
159
|
-
await Bun.sleep(1_000);
|
|
160
|
-
run = parseTextResult(await client.callTool({
|
|
161
|
-
name: "ennodia_get_run",
|
|
162
|
-
arguments: {
|
|
163
|
-
runId: started.id,
|
|
164
|
-
includeEvents: true,
|
|
165
|
-
maxEvents: 80,
|
|
166
|
-
maxAnswerChars: 120_000,
|
|
167
|
-
},
|
|
168
|
-
})) as RunView;
|
|
169
|
-
}
|
|
170
|
-
|
|
171
|
-
if (run.status !== "succeeded") {
|
|
172
|
-
throw new Error(`Run ${started.id} ended as ${run.status}: ${run.error ?? ""}`);
|
|
173
|
-
}
|
|
174
|
-
|
|
175
|
-
return run;
|
|
176
|
-
}
|
|
177
|
-
|
|
178
|
-
function runToOutput(
|
|
179
|
-
caseId: string,
|
|
180
|
-
condition: string,
|
|
181
|
-
run: RunView,
|
|
182
|
-
): OutputRecord {
|
|
183
|
-
return {
|
|
184
|
-
caseId,
|
|
185
|
-
condition,
|
|
186
|
-
text: run.finalAnswer ?? "",
|
|
187
|
-
metadata: {
|
|
188
|
-
mode: "live",
|
|
189
|
-
runId: run.id,
|
|
190
|
-
elapsedMs: run.elapsedMs,
|
|
191
|
-
selectedHarnessIds: run.selectedHarnessIds,
|
|
192
|
-
taskIds: run.taskIds,
|
|
193
|
-
compareId: run.compareId,
|
|
194
|
-
},
|
|
195
|
-
};
|
|
196
|
-
}
|
|
197
|
-
|
|
198
|
-
async function writeSummary(
|
|
199
|
-
outDir: string,
|
|
200
|
-
summary: BenchmarkSummary,
|
|
201
|
-
outputs: OutputRecord[],
|
|
202
|
-
): Promise<void> {
|
|
203
|
-
await mkdir(outDir, { recursive: true });
|
|
204
|
-
await writeFile(
|
|
205
|
-
join(outDir, "summary.json"),
|
|
206
|
-
`${JSON.stringify({ ...summary, outputs }, null, 2)}\n`,
|
|
207
|
-
);
|
|
208
|
-
await writeFile(
|
|
209
|
-
join(outDir, "summary.md"),
|
|
210
|
-
[
|
|
211
|
-
`# ${summary.benchmark}`,
|
|
212
|
-
"",
|
|
213
|
-
`Mode: ${summary.mode}`,
|
|
214
|
-
"",
|
|
215
|
-
formatConditionTable(summary),
|
|
216
|
-
"",
|
|
217
|
-
"## Wins",
|
|
218
|
-
"",
|
|
219
|
-
...summary.wins.map((win) =>
|
|
220
|
-
`- ${win.condition}: ${win.fixtures} fixture(s)`
|
|
221
|
-
),
|
|
222
|
-
"",
|
|
223
|
-
].join("\n"),
|
|
224
|
-
);
|
|
225
|
-
}
|
|
226
|
-
|
|
227
|
-
async function resolveOutDir(
|
|
228
|
-
options: CliOptions,
|
|
229
|
-
summary: BenchmarkSummary,
|
|
230
|
-
): Promise<string> {
|
|
231
|
-
if (options.outDir) {
|
|
232
|
-
return options.outDir;
|
|
233
|
-
}
|
|
234
|
-
|
|
235
|
-
const stamp = summary.createdAt.replace(/[:.]/g, "-");
|
|
236
|
-
return join(
|
|
237
|
-
new URL("../results/bug-recall/", import.meta.url).pathname,
|
|
238
|
-
`${summary.mode}-${stamp}`,
|
|
239
|
-
);
|
|
240
|
-
}
|
|
241
|
-
|
|
242
|
-
async function selectCases(
|
|
243
|
-
cases: BenchmarkCase[],
|
|
244
|
-
fixtureIds: string[],
|
|
245
|
-
): Promise<BenchmarkCase[]> {
|
|
246
|
-
if (fixtureIds.length === 0) {
|
|
247
|
-
return cases;
|
|
248
|
-
}
|
|
249
|
-
|
|
250
|
-
const selected = cases.filter((benchmarkCase) =>
|
|
251
|
-
fixtureIds.includes(benchmarkCase.id)
|
|
252
|
-
);
|
|
253
|
-
const missing = fixtureIds.filter((fixtureId) =>
|
|
254
|
-
!selected.some((benchmarkCase) => benchmarkCase.id === fixtureId)
|
|
255
|
-
);
|
|
256
|
-
|
|
257
|
-
if (missing.length > 0) {
|
|
258
|
-
throw new Error(`Unknown fixture id(s): ${missing.join(", ")}`);
|
|
259
|
-
}
|
|
260
|
-
|
|
261
|
-
return selected;
|
|
262
|
-
}
|
|
263
|
-
|
|
264
|
-
function parseArgs(args: string[]): CliOptions {
|
|
265
|
-
const options: CliOptions = {
|
|
266
|
-
live: false,
|
|
267
|
-
fixtureIds: [],
|
|
268
|
-
harnessIds: [],
|
|
269
|
-
timeoutMs: 300_000,
|
|
270
|
-
};
|
|
271
|
-
|
|
272
|
-
for (let index = 0; index < args.length; index += 1) {
|
|
273
|
-
const arg = args[index];
|
|
274
|
-
|
|
275
|
-
if (arg === "--live") {
|
|
276
|
-
options.live = true;
|
|
277
|
-
} else if (arg === "--fixture") {
|
|
278
|
-
options.fixtureIds.push(requireValue(args, ++index, arg));
|
|
279
|
-
} else if (arg === "--harness") {
|
|
280
|
-
options.harnessIds.push(requireValue(args, ++index, arg));
|
|
281
|
-
} else if (arg === "--timeout-ms") {
|
|
282
|
-
options.timeoutMs = Number(requireValue(args, ++index, arg));
|
|
283
|
-
} else if (arg === "--out") {
|
|
284
|
-
options.outDir = requireValue(args, ++index, arg);
|
|
285
|
-
} else if (arg === "--judge-harness") {
|
|
286
|
-
options.judgeHarnessId = requireValue(args, ++index, arg);
|
|
287
|
-
} else if (
|
|
288
|
-
arg === "--advisor-harness" || arg === "--synthesizer-harness"
|
|
289
|
-
) {
|
|
290
|
-
const value = requireValue(args, ++index, arg);
|
|
291
|
-
if (options.advisorHarnessId && options.advisorHarnessId !== value) {
|
|
292
|
-
throw new Error(
|
|
293
|
-
"--advisor-harness and --synthesizer-harness must match.",
|
|
294
|
-
);
|
|
295
|
-
}
|
|
296
|
-
options.advisorHarnessId = value;
|
|
297
|
-
} else {
|
|
298
|
-
throw new Error(`Unknown option: ${arg}`);
|
|
299
|
-
}
|
|
300
|
-
}
|
|
301
|
-
|
|
302
|
-
if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
|
|
303
|
-
throw new Error("--timeout-ms must be a positive number.");
|
|
304
|
-
}
|
|
305
|
-
|
|
306
|
-
return options;
|
|
307
|
-
}
|
|
308
|
-
|
|
309
|
-
function requireValue(args: string[], index: number, flag: string): string {
|
|
310
|
-
const value = args[index];
|
|
311
|
-
if (!value) {
|
|
312
|
-
throw new Error(`${flag} requires a value.`);
|
|
313
|
-
}
|
|
314
|
-
|
|
315
|
-
return value;
|
|
316
|
-
}
|
|
317
|
-
|
|
318
|
-
function parseTextResult(result: unknown): unknown {
|
|
319
|
-
const content = (result as { content?: unknown }).content;
|
|
320
|
-
if (!Array.isArray(content)) {
|
|
321
|
-
throw new Error("MCP response did not include content.");
|
|
322
|
-
}
|
|
323
|
-
|
|
324
|
-
const text = content
|
|
325
|
-
.filter(isMcpTextContent)
|
|
326
|
-
.map((item) => item.text)
|
|
327
|
-
.join("\n");
|
|
328
|
-
|
|
329
|
-
return JSON.parse(text);
|
|
330
|
-
}
|
|
331
|
-
|
|
332
|
-
function isMcpTextContent(value: unknown): value is McpTextContent {
|
|
333
|
-
return (
|
|
334
|
-
value !== null &&
|
|
335
|
-
typeof value === "object" &&
|
|
336
|
-
(value as { type?: unknown }).type === "text" &&
|
|
337
|
-
typeof (value as { text?: unknown }).text === "string"
|
|
338
|
-
);
|
|
339
|
-
}
|