@kindgi/api 0.1.2 → 0.1.4-rc.0

package/dist/routes/judged-suites.js

@@ -0,0 +1,272 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { Hono } from 'hono';
+import { ref, tuplesForCreate } from '@kindgi/authz';
+import { statusFor, toWireError } from '../errors.js';
+import { clampLimit } from './pagination.js';
+/** The most cases a test set built from judgments holds. */
+export const MAX_JUDGED_CASES = 1000;
+const PAGE = 100;
+const SEMVER_RE = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+/**
+ * Test sets built from judgments: `judged` eval suites.
+ *
+ * - `POST /v1/eval-suites/:suiteId/versions/from-judgments` builds and
+ *   publishes a version whose cases are copies of judged runs (input,
+ *   what the turn read, the judged output) with each item's judgments
+ *   summed up, weighted by judge class (an unclassified judgment counts
+ *   1). Needs `admin` on the project, as publishing a suite does.
+ * - `GET /v1/eval-suites/:suiteId/versions/:version/cases` lists them.
+ */
+export function judgedSuitesRouter(suites, judgments, cases, authorizer) {
+    const r = new Hono();
+    r.post('/:suiteId/versions/from-judgments', async (c) => {
+        const tenantId = c.get('tenantId');
+        const suiteId = c.req.param('suiteId');
+        const parsed = parseBuildBody(await c.req.json().catch(() => null));
+        if (parsed.kind === 'err')
+            return fail(c, 'bad-input', parsed.message);
+        const body = parsed.body;
+        if (authorizer !== undefined &&
+            !(await authorizer.can(c, 'admin', ref('project', body.projectId)))) {
+            return fail(c, 'permission-denied', 'Building a test set needs admin on the project.');
+        }
+        if (judgments.listJudgedRuns === undefined) {
+            return fail(c, 'test-sets-not-supported', 'This deployment cannot build test sets from judgments.');
+        }
+        const built = await buildCases(judgments, tenantId, body);
+        const principal = c.get('principal');
+        const creatorUserId = principal?.actor.kind === 'user' ? principal.actor.id : undefined;
+        const outcome = await suites.publish({
+            tenantId,
+            projectId: body.projectId,
+            suite: {
+                id: suiteId,
+                tenantId,
+                version: body.version,
+                kind: 'judged',
+                ...(body.description !== undefined && { description: body.description }),
+                spec: {
+                    source: 'judgments',
+                    // Where the judgments came from: a comparison's summary names it.
+                    projectId: body.projectId,
+                    query: body.query,
+                    caseCount: built.cases.length,
+                    truncated: built.truncated,
+                    builtAt: new Date().toISOString(),
+                },
+            },
+            enqueueTuples: (id) => tuplesForCreate({ kind: 'eval_suite', id, tenantId, projectId: body.projectId }, creatorUserId),
+        });
+        if (outcome.kind === 'already-registered') {
+            return fail(c, 'eval-suite-already-registered', `Eval suite "${suiteId}" version "${body.version}" is already registered.`);
+        }
+        if (outcome.kind === 'project-not-found') {
+            return fail(c, 'bad-input', `\`projectId\` "${body.projectId}" is not a project here.`);
+        }
+        await cases.putCases({ tenantId, suiteId, version: body.version, cases: built.cases });
+        c.status(201);
+        return c.json({
+            suiteId,
+            version: body.version,
+            kind: 'judged',
+            caseCount: built.cases.length,
+            truncated: built.truncated,
+        });
+    });
+    r.get('/:suiteId/versions/:version/cases', async (c) => {
+        const tenantId = c.get('tenantId');
+        const suiteId = c.req.param('suiteId');
+        const version = c.req.param('version');
+        if (authorizer !== undefined &&
+            !(await authorizer.can(c, 'read', ref('eval_suite', suiteId)))) {
+            return fail(c, 'eval-suite-not-found', `No eval suite "${suiteId}".`);
+        }
+        const cursor = c.req.query('cursor');
+        const page = await cases.listCases({
+            tenantId,
+            suiteId,
+            version,
+            limit: clampLimit(c.req.query('limit'), 25, 100),
+            ...(cursor !== undefined && cursor.length > 0 && { cursor: cursor }),
+        });
+        return c.json({
+            data: page.data,
+            hasMore: page.hasMore,
+            ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor }),
+        });
+    });
+    return r;
+}
+function fail(c, code, message) {
+    c.status(statusFor(code));
+    return c.json(toWireError({ code, message }, c.get('requestId')));
+}
+/** Each class's weight, read once (an unclassified judgment counts 1; a missing class too). */
+function classWeights(judgments, tenantId) {
+    const weights = new Map();
+    return async (judgeClassId) => {
+        if (judgeClassId === undefined)
+            return 1;
+        const known = weights.get(judgeClassId);
+        if (known !== undefined)
+            return known;
+        const k = await judgments.getClass({ tenantId, judgeClassId, includeUnregistered: true });
+        const w = k?.weight ?? 1;
+        weights.set(judgeClassId, w);
+        return w;
+    };
+}
+function judgedRunFilter(tenantId, body) {
+    const { judgeClassIds: _ids, minJudgments: _min, ...runFilter } = body.query;
+    return { tenantId, projectId: body.projectId, ...runFilter };
+}
+/** Pages judged runs (newest first, up to MAX_JUDGED_CASES) and turns each into a case. */
+async function buildCases(judgments, tenantId, body) {
+    const list = judgments.listJudgedRuns;
+    const weightOf = classWeights(judgments, tenantId);
+    const filter = judgedRunFilter(tenantId, body);
+    const cases = [];
+    let cursor;
+    for (;;) {
+        const page = await list({ ...filter, limit: PAGE, ...(cursor !== undefined && { cursor }) });
+        for (const judged of page.data) {
+            const built = await toCase(judged, body.query, weightOf);
+            if (built !== undefined)
+                cases.push(built);
+            if (cases.length >= MAX_JUDGED_CASES)
+                return { cases, truncated: true };
+        }
+        if (!page.hasMore || page.nextCursor === undefined)
+            return { cases, truncated: false };
+        cursor = page.nextCursor;
+    }
+}
+async function toCase(judged, q, weightOf) {
+    const kept = q.judgeClassIds === undefined
+        ? judged.judgments
+        : judged.judgments.filter((j) => j.judgeClassId !== undefined && q.judgeClassIds?.includes(j.judgeClassId));
+    if (kept.length === 0 || kept.length < (q.minJudgments ?? 1))
+        return undefined;
+    const byKey = new Map();
+    for (const j of kept)
+        byKey.set(j.item.key, [...(byKey.get(j.item.key) ?? []), j]);
+    const items = [];
+    for (const [key, list] of byKey)
+        items.push(await summarize(key, list, weightOf));
+    items.sort((a, b) => (a.rank ?? Number.MAX_SAFE_INTEGER) - (b.rank ?? Number.MAX_SAFE_INTEGER));
+    const run = judged.run;
+    return {
+        caseId: run.runId,
+        subject: run.subject,
+        input: run.input,
+        ...(run.context !== undefined && { context: run.context }),
+        output: run.output,
+        items,
+    };
+}
+async function summarize(key, judgments, weightOf) {
+    let yes = 0;
+    let no = 0;
+    let yesWeight = 0;
+    let totalWeight = 0;
+    for (const j of judgments) {
+        const w = await weightOf(j.judgeClassId);
+        totalWeight += w;
+        if (j.verdict === 'yes') {
+            yes += 1;
+            yesWeight += w;
+        }
+        else {
+            no += 1;
+        }
+    }
+    const first = judgments[0];
+    return {
+        key,
+        ...(first?.item.pointer !== undefined && { pointer: first.item.pointer }),
+        ...(first?.item.rank !== undefined && { rank: first.item.rank }),
+        yes,
+        no,
+        yesWeight,
+        totalWeight,
+        reasons: judgments.flatMap((j) => j.reason !== undefined ? [{ verdict: j.verdict, reason: j.reason }] : []),
+    };
+}
+const STRING_FILTERS = ['agentId', 'agentVersion', 'flowId', 'since', 'until'];
+/** The string filters (agent, version, flow, time window); a message when one is malformed. */
+function parseStringFilters(b) {
+    const query = {};
+    for (const field of STRING_FILTERS) {
+        const v = b[field];
+        if (v === undefined)
+            continue;
+        if (typeof v !== 'string' || v.length === 0)
+            return `${field} must be a non-empty string.`;
+        if ((field === 'since' || field === 'until') && Number.isNaN(Date.parse(v))) {
+            return `${field} must be an ISO 8601 time.`;
+        }
+        query[field] = v;
+    }
+    if (query.agentVersion !== undefined && query.agentId === undefined) {
+        return 'agentVersion needs agentId.';
+    }
+    return query;
+}
+/** Which judgments count: by class, and how many a run needs. */
+function parseJudgmentFilters(b) {
+    const ids = b.judgeClassIds;
+    if (ids !== undefined &&
+        (!Array.isArray(ids) || ids.some((i) => typeof i !== 'string' || i.length === 0))) {
+        return 'judgeClassIds must be a list of judge class ids.';
+    }
+    const min = b.minJudgments;
+    if (min !== undefined && !(Number.isInteger(min) && min >= 1)) {
+        return 'minJudgments must be a whole number ≥ 1.';
+    }
+    return {
+        ...(ids !== undefined && { judgeClassIds: ids }),
+        ...(min !== undefined && { minJudgments: min }),
+    };
+}
+/** The optional judged-run filters; a message when one is malformed. */
+function parseQuery(b) {
+    const strings = parseStringFilters(b);
+    if (typeof strings === 'string')
+        return strings;
+    const counted = parseJudgmentFilters(b);
+    if (typeof counted === 'string')
+        return counted;
+    return { ...strings, ...counted };
+}
+function parseBuildBody(raw) {
+    const err = (message) => ({ kind: 'err', message });
+    if (raw === null || typeof raw !== 'object')
+        return err('Send a JSON object.');
+    const b = raw;
+    if (typeof b.version !== 'string' || !SEMVER_RE.test(b.version)) {
+        return err('version is required: a semver such as "1.0.0".');
+    }
+    if (typeof b.projectId !== 'string' || b.projectId.length === 0) {
+        return err('projectId is required.');
+    }
+    if (b.agentId === undefined && b.flowId === undefined) {
+        return err('Name the agent (agentId) or the flow (flowId) whose judged runs to use.');
+    }
+    if (b.description !== undefined && typeof b.description !== 'string') {
+        return err('description must be a string.');
+    }
+    const query = parseQuery(b);
+    if (typeof query === 'string')
+        return err(query);
+    return {
+        kind: 'ok',
+        body: {
+            version: b.version,
+            projectId: b.projectId,
+            ...(typeof b.description === 'string' && { description: b.description }),
+            query,
+        },
+    };
+}
+//# sourceMappingURL=judged-suites.js.map

package/dist/routes/judged-suites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"judged-suites.js","sourceRoot":"","sources":["../../src/routes/judged-suites.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,OAAO,EAAgB,IAAI,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,EAAkB,GAAG,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGrE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAetD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,4DAA4D;AAC5D,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AACrC,MAAM,IAAI,GAAG,GAAG,CAAC;AACjB,MAAM,SAAS,GAAG,mCAAmC,CAAC;AAEtD;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAgC,EAChC,SAAkC,EAClC,KAA2B,EAC3B,UAAuB;IAEvB,MAAM,CAAC,GAAG,IAAI,IAAI,EAAU,CAAC;IAE7B,CAAC,CAAC,IAAI,CAAC,mCAAmC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QACtD,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,UAAU,CAAa,CAAC;QAC/C,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACvC,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;QACpE,IAAI,MAAM,CAAC,IAAI,KAAK,KAAK;YAAE,OAAO,IAAI,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QACvE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACzB,IACE,UAAU,KAAK,SAAS;YACxB,CAAC,CAAC,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EACnE,CAAC;YACD,OAAO,IAAI,CAAC,CAAC,EAAE,mBAAmB,EAAE,iDAAiD,CAAC,CAAC;QACzF,CAAC;QACD,IAAI,SAAS,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;YAC3C,OAAO,IAAI,CACT,CAAC,EACD,yBAAyB,EACzB,wDAAwD,CACzD,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,UAAU,CAAC,SAAS,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC1D,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,WAAW,CAA0B,CAAC;QAC9D,MAAM,aAAa,GACjB,SAAS,EAAE,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAE,SAAS,CAAC,KAAK,CAAC,EAAa,CAAC,CAAC,CAAC,SAAS,CAAC;QAChF,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC;YACnC,QAAQ;YACR,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,KAAK,EAAE;gBACL,EAAE,EAAE,OAAO;gBACX,QAAQ;gBACR,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,IAAI,EAAE,QAAQ;gBACd,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;gBACxE,IAAI,EAAE;oBACJ,MAAM,EAAE,WAAW;oBACnB,kEAAkE;oBAClE,SAAS,EAAE,IAAI,CAAC,SAAS;oBACzB,KAAK,EAAE,IAAI,CAAC,KAAK;oBACjB,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM;oBAC7B,SAAS,EAAE,KAAK,CAAC,SAAS;oBAC1B,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;iBAClC;aACF;YACD,aAAa,EAAE,CAAC,EAAE,EAAE,EAAE,CACpB,eAAe,CACb,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,EAC/D,aAAa,CACd;SACJ,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,IAAI,KAAK,oBAAoB,EAAE,CAAC;YAC1C,OAAO,IAAI,CACT,CAAC,EACD,+BAA+B,EAC/B,eAAe,OAAO,cAAc,IAAI,CAAC,OAAO,0BAA0B,CAC3E,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,KAAK,mBAAmB,EAAE,CAAC;YACzC,OAAO,IAAI,CAAC,CAAC,EAAE,WAAW,EAAE,kBAAkB,IAAI,CAAC,SAAS,0BAA0B,CAAC,CAAC;QAC1F,CAAC;QACD,MAAM,KAAK,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QACvF,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACd,OAAO,CAAC,CAAC,IAAI,CAAC;YACZ,OAAO;YACP,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM;YAC7B,SAAS,EAAE,KAAK,CAAC,SAAS;SAC3B,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,CAAC,CAAC,GAAG,CAAC,mCAAmC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QACrD,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,UAAU,CAAa,CAAC;QAC/C,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACvC,IACE,UAAU,KAAK,SAAS;YACxB,CAAC,CAAC,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,EAC9D,CAAC;YACD,OAAO,IAAI,CAAC,CAAC,EAAE,sBAAsB,EAAE,kBAAkB,OAAO,IAAI,CAAC,CAAC;QACxE,CAAC;QACD,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACrC,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC;YACjC,QAAQ;YACR,OAAO;YACP,OAAO;YACP,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC;YAChD,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAgB,EAAE,CAAC;SAC/E,CAAC,CAAC;QACH,OAAO,CAAC,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,GAAG,CAAC,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,UAA+B,EAAE,CAAC;SAC3F,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,IAAI,CAAC,CAAkB,EAAE,IAAY,EAAE,OAAe;IAC7D,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAU,CAAC,CAAC;IACnC,OAAO,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;AACpE,CAAC;AAoBD,+FAA+F;AAC/F,SAAS,YAAY,CACnB,SAAkC,EAClC,QAAkB;IAElB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,EAAE;QAC5B,IAAI,YAAY,KAAK,SAAS;YAAE,OAAO,CAAC,CAAC;QACzC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QACxC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QACtC,MAAM,CAAC,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,mBAAmB,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1F,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC;QACzB,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;QAC7B,OAAO,CAAC,CAAC;IACX,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CACtB,QAAkB,EAClB,IAAe;IAEf,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,GAAG,SAAS,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;IAC7E,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,GAAG,SAAS,EAAE,CAAC;AAC/D,CAAC;AAED,2FAA2F;AAC3F,KAAK,UAAU,UAAU,CACvB,SAAkC,EAClC,QAAkB,EAClB,IAAe;IAEf,MAAM,IAAI,GAAG,SAAS,CAAC,cAAwE,CAAC;IAChG,MAAM,QAAQ,GAAG,YAAY,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,IAAI,MAA0B,CAAC;IAC/B,SAAS,CAAC;QACR,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;QAC7F,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC/B,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YACzD,IAAI,KAAK,KAAK,SAAS;gBAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC3C,IAAI,KAAK,CAAC,MAAM,IAAI,gBAAgB;gBAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAC1E,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;YAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QACvF,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;IAC3B,CAAC;AACH,CAAC;AAED,KAAK,UAAU,MAAM,CACnB,MAA8B,EAC9B,CAAqB,EACrB,QAA+D;IAE/D,MAAM,IAAI,GACR,CAAC,CAAC,aAAa,KAAK,SAAS;QAC3B,CAAC,CAAC,MAAM,CAAC,SAAS;QAClB,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CACrB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,SAAS,IAAI,CAAC,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CACjF,CAAC;IACR,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/E,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACnF,MAAM,KAAK,GAAwB,EAAE,CAAC;IACtC,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,MAAM,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IAClF,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,MAAM,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAChG,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;IACvB,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,KAAK;QACjB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,GAAG,CAAC,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;QAC1D,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,KAAK;KACN,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,SAAS,CACtB,GAAW,EACX,SAA8B,EAC9B,QAA+D;IAE/D,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,EAAE,GAAG,CAAC,CAAC;IACX,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,MAAM,CAAC,GAAG,MAAM,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;QACzC,WAAW,IAAI,CAAC,CAAC;QACjB,IAAI,CAAC,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;YACxB,GAAG,IAAI,CAAC,CAAC;YACT,SAAS,IAAI,CAAC,CAAC;QACjB,CAAC;aAAM,CAAC;YACN,EAAE,IAAI,CAAC,CAAC;QACV,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAC3B,OAAO;QACL,GAAG;QACH,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QACzE,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAChE,GAAG;QACH,EAAE;QACF,SAAS;QACT,WAAW;QACX,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAC/B,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CACzE;KACF,CAAC;AACJ,CAAC;AAQD,MAAM,cAAc,GAAG,CAAC,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAU,CAAC;AAExF,+FAA+F;AAC/F,SAAS,kBAAkB,CAAC,CAA0B;IACpD,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,KAAK,MAAM,KAAK,IAAI,cAAc,EAAE,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QACnB,IAAI,CAAC,KAAK,SAAS;YAAE,SAAS;QAC9B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,GAAG,KAAK,8BAA8B,CAAC;QAC3F,IAAI,CAAC,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,OAAO,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5E,OAAO,GAAG,KAAK,4BAA4B,CAAC;QAC9C,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,CAAC;IACD,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACpE,OAAO,6BAA6B,CAAC;IACvC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,iEAAiE;AACjE,SAAS,oBAAoB,CAC3B,CAA0B;IAE1B,MAAM,GAAG,GAAG,CAAC,CAAC,aAAa,CAAC;IAC5B,IACE,GAAG,KAAK,SAAS;QACjB,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,EACjF,CAAC;QACD,OAAO,kDAAkD,CAAC;IAC5D,CAAC;IACD,MAAM,GAAG,GAAG,CAAC,CAAC,YAAY,CAAC;IAC3B,IAAI,GAAG,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAK,GAAc,IAAI,CAAC,CAAC,EAAE,CAAC;QAC1E,OAAO,0CAA0C,CAAC;IACpD,CAAC;IACD,OAAO;QACL,GAAG,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,aAAa,EAAE,GAAe,EAAE,CAAC;QAC5D,GAAG,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,YAAY,EAAE,GAAa,EAAE,CAAC;KAC1D,CAAC;AACJ,CAAC;AAED,wEAAwE;AACxE,SAAS,UAAU,CAAC,CAA0B;IAC5C,MAAM,OAAO,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAC;IACtC,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChD,MAAM,OAAO,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAAC;IACxC,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChD,OAAO,EAAE,GAAG,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;AACpC,CAAC;AAED,SAAS,cAAc,CAAC,GAAY;IAClC,MAAM,GAAG,GAAG,CAAC,OAAe,EAAqB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;IAC/E,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC,qBAAqB,CAAC,CAAC;IAC/E,MAAM,CAAC,GAAG,GAA8B,CAAC;IACzC,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;QAChE,OAAO,GAAG,CAAC,gDAAgD,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChE,OAAO,GAAG,CAAC,wBAAwB,CAAC,CAAC;IACvC,CAAC;IACD,IAAI,CAAC,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACtD,OAAO,GAAG,CAAC,yEAAyE,CAAC,CAAC;IACxF,CAAC;IACD,IAAI,CAAC,CAAC,WAAW,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC;QACrE,OAAO,GAAG,CAAC,+BAA+B,CAAC,CAAC;IAC9C,CAAC;IACD,MAAM,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;IACjD,OAAO;QACL,IAAI,EAAE,IAAI;QACV,IAAI,EAAE;YACJ,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,SAAS,EAAE,CAAC,CAAC,SAAsB;YACnC,GAAG,CAAC,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;YACxE,KAAK;SACN;KACF,CAAC;AACJ,CAAC"}

package/dist/routes/judgment-context.d.ts

@@ -0,0 +1,22 @@
+import { type ConversationBinding } from '@kindgi/agents';
+import type { RunBinding } from '@kindgi/runtime';
+import type { TenantId } from '@kindgi/types';
+import type { JudgedRunContext } from '../judgment-binding.js';
+/** The most messages of conversation history a judged turn keeps. */
+export declare const MAX_JUDGED_HISTORY = 200;
+/**
+ * What a judged agent turn read besides its input, so it can be replayed
+ * faithfully later: the conversation before the turn, what its
+ * retrievals returned, and the decision at its session approval gate. Best effort and read-only: a part that can't be
+ * read is left out (the judgment never fails over it). `undefined` for
+ * a flow run, or when nothing could be read.
+ */
+export declare function captureTurnContext(input: {
+    readonly tenantId: TenantId;
+    readonly runId: string;
+    readonly output: unknown;
+    readonly conversationId: string | undefined;
+    readonly runBinding: RunBinding;
+    readonly conversations: ConversationBinding | undefined;
+}): Promise<JudgedRunContext | undefined>;
+//# sourceMappingURL=judgment-context.d.ts.map

package/dist/routes/judgment-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"judgment-context.d.ts","sourceRoot":"","sources":["../../src/routes/judgment-context.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,mBAAmB,EAIzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAgB,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAyB,QAAQ,EAAE,MAAM,eAAe,CAAC;AAErE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,qEAAqE;AACrE,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAsFtC;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACzD,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAYxC"}

package/dist/routes/judgment-context.js

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { RUN_RETRIEVALS_NODE, SESSION_GATE_RECORD, readGateDecision, } from '@kindgi/agents';
+/** The most messages of conversation history a judged turn keeps. */
+export const MAX_JUDGED_HISTORY = 200;
+/** How many messages are read to find a turn's history. */
+const HISTORY_READ_LIMIT = 1000;
+function obj(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** The sequence of the first message the turn appended (its user message). */
+function firstAppendedSequence(output) {
+    const appended = obj(output)?.appended;
+    if (!Array.isArray(appended))
+        return undefined;
+    const sequences = appended
+        .map((m) => obj(m)?.sequence)
+        .filter((s) => typeof s === 'number');
+    return sequences.length > 0 ? Math.min(...sequences) : undefined;
+}
+async function readHistory(conversations, tenantId, conversationId, before) {
+    const read = await conversations.readMessages({
+        tenantId,
+        conversationId: conversationId,
+        limit: HISTORY_READ_LIMIT,
+    });
+    if (read.kind === 'err')
+        return {};
+    const earlier = read.value.filter((m) => m.sequence < before);
+    const kept = earlier.slice(-MAX_JUDGED_HISTORY);
+    return {
+        history: kept,
+        ...(kept.length < earlier.length && { historyTruncated: true }),
+    };
+}
+/** What the turn's journal says it retrieved, and how its session approval was decided. */
+async function readJournalParts(runBinding, tenantId, runId) {
+    const journal = await runBinding.readJournal(tenantId, runId);
+    if (journal.kind === 'err')
+        return {};
+    const entries = journal.value;
+    const step = entries.find((e) => e.kind === 'step.completed' &&
+        typeof e.nodeId === 'string' &&
+        (e.nodeId === RUN_RETRIEVALS_NODE || e.nodeId.endsWith(`/${RUN_RETRIEVALS_NODE}`)));
+    const retrieved = obj(obj(step?.payload)?.output)?.retrieved;
+    const sessionApproval = sessionApprovalOf(entries);
+    return {
+        ...(retrieved !== undefined && { retrieved }),
+        ...(sessionApproval !== undefined && { sessionApproval }),
+    };
+}
+/** The decision that resolved the turn's session approval gate, if it waited on one. */
+function sessionApprovalOf(entries) {
+    const gate = entries.find((e) => e.kind === 'value.recorded' && obj(e.payload)?.key === SESSION_GATE_RECORD);
+    const tokenId = obj(obj(gate?.payload)?.value)?.waitTokenId;
+    if (typeof tokenId !== 'string')
+        return undefined;
+    const resumed = entries.find((e) => e.kind === 'wait.resumed' && obj(e.payload)?.tokenId === tokenId);
+    if (resumed === undefined)
+        return undefined;
+    const decision = readGateDecision(obj(resumed.payload)?.value);
+    return {
+        approved: decision.approved,
+        ...(!decision.approved &&
+            decision.rationale !== undefined && { rationale: decision.rationale }),
+    };
+}
+/**
+ * What a judged agent turn read besides its input, so it can be replayed
+ * faithfully later: the conversation before the turn, what its
+ * retrievals returned, and the decision at its session approval gate. Best effort and read-only: a part that can't be
+ * read is left out (the judgment never fails over it). `undefined` for
+ * a flow run, or when nothing could be read.
+ */
+export async function captureTurnContext(input) {
+    const before = firstAppendedSequence(input.output);
+    const [history, journal] = await Promise.all([
+        input.conversations !== undefined && input.conversationId !== undefined && before !== undefined
+            ? readHistory(input.conversations, input.tenantId, input.conversationId, before).catch(() => ({}))
+            : Promise.resolve({}),
+        readJournalParts(input.runBinding, input.tenantId, input.runId).catch(() => ({})),
+    ]);
+    const context = { ...history, ...journal };
+    return Object.keys(context).length > 0 ? context : undefined;
+}
+//# sourceMappingURL=judgment-context.js.map

package/dist/routes/judgment-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"judgment-context.js","sourceRoot":"","sources":["../../src/routes/judgment-context.ts"],"names":[],"mappings":"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"}

package/dist/routes/judgment-flow-context.d.ts

@@ -0,0 +1,32 @@
+import type { RunBinding } from '@kindgi/runtime';
+import type { TenantId } from '@kindgi/types';
+import type { FlowRegistryBinding } from '../flow-binding.js';
+import type { JudgedRunContext } from '../judgment-binding.js';
+/** The most tool calls a judged flow run keeps. */
+export declare const MAX_JUDGED_FLOW_CALLS = 500;
+/**
+ * The tool calls an agent turn made, with their results, from its
+ * output's `appended` messages: each agent message's `toolCalls`, paired
+ * with the `tool` message that answered it.
+ */
+export declare function turnToolCalls(output: unknown): readonly {
+    readonly toolId: string;
+    readonly arguments: unknown;
+    readonly result: unknown;
+}[];
+/**
+ * What a judged flow run did (`context.flow`): its tool calls with their
+ * results, and its agent steps' turns. `undefined` when nothing could be
+ * read.
+ */
+export declare function captureFlowContext(input: {
+    readonly tenantId: TenantId;
+    readonly run: {
+        readonly runId: string;
+        readonly flowId: string;
+        readonly flowVersion: string;
+    };
+    readonly runBinding: RunBinding;
+    readonly flows: FlowRegistryBinding | undefined;
+}): Promise<JudgedRunContext | undefined>;
+//# sourceMappingURL=judgment-flow-context.d.ts.map

package/dist/routes/judgment-flow-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"judgment-flow-context.d.ts","sourceRoot":"","sources":["../../src/routes/judgment-flow-context.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAmB,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAiB,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAGV,gBAAgB,EAEjB,MAAM,wBAAwB,CAAC;AAEhC,mDAAmD;AACnD,eAAO,MAAM,qBAAqB,MAAM,CAAC;AA4BzC;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,OAAO,GACd,SAAS;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,EAAE,CAuB/F;AAmID;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAChG,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACjD,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAmBxC"}

package/dist/routes/judgment-flow-context.js

@@ -0,0 +1,195 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { isFanoutNode, isLoopNode } from '@kindgi/flow';
+/** The most tool calls a judged flow run keeps. */
+export const MAX_JUDGED_FLOW_CALLS = 500;
+/** How deep into sub-flows the capture goes. */
+const MAX_FLOW_DEPTH = 3;
+/** The most child runs read per run. */
+const MAX_CHILDREN = 100;
+function obj(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** The tool each tool node runs, by node id: in loop bodies and fanout branches too. */
+function toolNodes(flow) {
+    const tools = new Map();
+    const walk = (nodes) => {
+        for (const node of nodes) {
+            if (node.kind === 'tool')
+                tools.set(node.id, node.ref);
+            else if (isLoopNode(node))
+                walk(node.body.nodes);
+            else if (isFanoutNode(node)) {
+                for (const b of node.branches)
+                    tools.set(b.handler, b.handler);
+            }
+        }
+    };
+    if (flow !== null)
+        walk(flow.nodes);
+    return tools;
+}
+/**
+ * The tool calls an agent turn made, with their results, from its
+ * output's `appended` messages: each agent message's `toolCalls`, paired
+ * with the `tool` message that answered it.
+ */
+export function turnToolCalls(output) {
+    const appended = obj(output)?.appended;
+    if (!Array.isArray(appended))
+        return [];
+    const args = new Map();
+    for (const m of appended) {
+        const calls = obj(obj(m)?.content)?.toolCalls;
+        if (obj(m)?.role !== 'agent' || !Array.isArray(calls))
+            continue;
+        for (const call of calls) {
+            const id = obj(call)?.id;
+            if (typeof id === 'string')
+                args.set(id, obj(call)?.arguments);
+        }
+    }
+    return appended.flatMap((m) => {
+        const toolCall = obj(obj(m)?.toolCall);
+        const toolId = toolCall?.toolId;
+        const invocationId = toolCall?.invocationId;
+        if (obj(m)?.role !== 'tool' || typeof toolId !== 'string' || typeof invocationId !== 'string') {
+            return [];
+        }
+        return args.has(invocationId)
+            ? [{ toolId, arguments: args.get(invocationId), result: obj(m)?.content }]
+            : [];
+    });
+}
+/** Where a step sits: its loop iteration, when it's in a loop body. */
+function scopeOf(loopContext) {
+    return loopContext === undefined || loopContext === null
+        ? undefined
+        : JSON.stringify(loopContext);
+}
+class Collector {
+    calls = [];
+    steps = [];
+    truncated = false;
+    add(call) {
+        if (this.calls.length >= MAX_JUDGED_FLOW_CALLS) {
+            this.truncated = true;
+            return;
+        }
+        this.calls.push(call);
+    }
+}
+/** A flow run's tool nodes' calls: each `step.completed` of a tool node, with its `step.started` input. */
+async function nodeCalls(r, c, run) {
+    const [flow, journal] = await Promise.all([
+        r.flows?.getVersion({
+            tenantId: r.tenantId,
+            flowId: run.flowId,
+            version: run.flowVersion,
+        }) ?? Promise.resolve(null),
+        r.runBinding.readJournal(r.tenantId, run.runId),
+    ]);
+    const tools = toolNodes(flow);
+    if (journal.kind === 'err' || tools.size === 0)
+        return;
+    const inputs = new Map();
+    for (const e of journal.value) {
+        if (typeof e.nodeId !== 'string' || !tools.has(e.nodeId))
+            continue;
+        const payload = obj(e.payload) ?? {};
+        const scope = scopeOf(payload.loopContext);
+        const key = `${e.nodeId}\u0000${scope ?? ''}`;
+        if (e.kind === 'step.started')
+            inputs.set(key, payload.input);
+        if (e.kind === 'step.completed') {
+            c.add({
+                runId: run.runId,
+                nodeId: e.nodeId,
+                ...(scope !== undefined && { scope }),
+                toolId: tools.get(e.nodeId),
+                arguments: inputs.get(key),
+                result: payload.output,
+            });
+        }
+    }
+}
+/** An agent step's turn: its calls, and what it retrieved. */
+async function stepTurn(r, c, child) {
+    const agent = child.agent;
+    if (agent === undefined)
+        return;
+    const output = child.output ?? (await r.runBinding.getRun(r.tenantId, child.runId))?.output ?? undefined;
+    const nodeId = child.parentNodeId ?? undefined;
+    const scope = child.parentScope ?? undefined;
+    const retrieved = obj(output)?.retrieved;
+    c.steps.push({
+        runId: child.runId,
+        ...(nodeId !== undefined && { nodeId }),
+        ...(scope !== undefined && scope !== '' && { scope }),
+        agentId: agent.id,
+        agentVersion: agent.version,
+        ...(retrieved !== undefined && { retrieved }),
+    });
+    for (const call of turnToolCalls(output)) {
+        c.add({
+            runId: child.runId,
+            ...(nodeId !== undefined && { nodeId }),
+            ...(scope !== undefined && scope !== '' && { scope }),
+            ...call,
+        });
+    }
+}
+/** A run's child runs (agent steps' turns, sub-flows); none when they can't be read. */
+async function childrenOf(r, runId) {
+    try {
+        const page = await r.runBinding.listRuns({
+            tenantId: r.tenantId,
+            parent: { runId: runId },
+            limit: MAX_CHILDREN,
+        });
+        return page.data;
+    }
+    catch {
+        return [];
+    }
+}
+async function collectRun(r, c, run, depth) {
+    await nodeCalls(r, c, run).catch(() => undefined);
+    for (const child of await childrenOf(r, run.runId)) {
+        if (child.agent !== undefined) {
+            await stepTurn(r, c, child).catch(() => undefined);
+        }
+        else if (depth < MAX_FLOW_DEPTH) {
+            await collectRun(r, c, {
+                runId: child.runId,
+                flowId: child.flowId,
+                flowVersion: child.flowVersion,
+            }, depth + 1);
+        }
+    }
+}
+/**
+ * What a judged flow run did (`context.flow`): its tool calls with their
+ * results, and its agent steps' turns. `undefined` when nothing could be
+ * read.
+ */
+export async function captureFlowContext(input) {
+    const c = new Collector();
+    try {
+        await collectRun({ tenantId: input.tenantId, runBinding: input.runBinding, flows: input.flows }, c, input.run, 0);
+    }
+    catch {
+        // Best effort: keep what was read.
+    }
+    if (c.calls.length === 0 && c.steps.length === 0)
+        return undefined;
+    const flow = {
+        calls: c.calls,
+        steps: c.steps,
+        ...(c.truncated && { truncated: true }),
+    };
+    return { flow };
+}
+//# sourceMappingURL=judgment-flow-context.js.map