@chopin-ai/core 0.2.0 → 0.3.0

package/dist/evidence/classify.d.ts

@@ -0,0 +1,31 @@
+import type { TranscriptEntry } from "../transcript.js";
+import type { Signal } from "./signals.js";
+/** Asks a model for a reply to one prompt; the caller picks the model and pays for it. */
+export type Complete = (prompt: string) => Promise<string>;
+/** Why the failure happened. */
+export declare const CAUSES: readonly ["tool_error", "wrong_command", "skipped_verification", "misread_request", "missing_context", "environment", "user_preference", "gave_up_early", "other"];
+/** What the agent did that led to it. */
+export declare const BEHAVIORS: readonly ["read", "edit", "run_command", "answer", "plan", "ask", "other"];
+/** A failure written as three fields; two failures are the same kind only when all three are equal. */
+export interface FailureSignature {
+    cause: (typeof CAUSES)[number];
+    behavior: (typeof BEHAVIORS)[number];
+    /** A short kebab-case name for the mechanism, such as `stops-at-truncated-output`. */
+    mechanism: string;
+}
+/**
+ * The rules failures are named by; a failure is counted only with failures named under the same rules, so changing
+ * them starts the count afresh instead of mixing two ways of naming.
+ */
+export declare const CLASSIFIER_VERSION = 3;
+/** What a model makes of a signal: a named failure, or not a failure at all, such as a search that found nothing. */
+export type Classified = FailureSignature | "not_a_failure";
+/**
+ * The signature of the failure `signal` marks in `entries`. Signatures already seen, the most common first, are
+ * offered whole, so one kind of failure keeps one name; a reply that does not fit gives `undefined` rather than a
+ * guess. A session of another agent, `foreign`, may hold refusals by its host's own rules, which are not the agent's.
+ */
+export declare function classify(entries: readonly TranscriptEntry[], signal: Signal, known: readonly FailureSignature[], complete: Complete, foreign?: boolean): Promise<Classified | undefined>;
+export declare function parseSignature(reply: string): Classified | undefined;
+/** The key failures of one kind share. */
+export declare function signatureKey(signature: FailureSignature): string;

package/dist/evidence/classify.js

@@ -0,0 +1,87 @@
+import { isUserWritten } from "./points.js";
+/** Why the failure happened. */
+export const CAUSES = [
+    "tool_error", "wrong_command", "skipped_verification", "misread_request", "missing_context", "environment",
+    "user_preference", "gave_up_early", "other",
+];
+/** What the agent did that led to it. */
+export const BEHAVIORS = ["read", "edit", "run_command", "answer", "plan", "ask", "other"];
+const MECHANISM = /^[a-z0-9]+(-[a-z0-9]+){0,7}$/;
+/**
+ * What the model is shown of a session: lines before the failure, and after it up to the user's next message, which
+ * tell a failure the agent had to recover from apart from a result it used; each line cut to a length.
+ */
+const BEFORE = 20;
+const AFTER = 8;
+const ENTRY_CHARS = 1500;
+/** How many named failures are offered, the most common first, so the prompt does not grow with the catalog. */
+const KNOWN_SHOWN = 30;
+/**
+ * The rules failures are named by; a failure is counted only with failures named under the same rules, so changing
+ * them starts the count afresh instead of mixing two ways of naming.
+ */
+export const CLASSIFIER_VERSION = 3;
+/**
+ * The signature of the failure `signal` marks in `entries`. Signatures already seen, the most common first, are
+ * offered whole, so one kind of failure keeps one name; a reply that does not fit gives `undefined` rather than a
+ * guess. A session of another agent, `foreign`, may hold refusals by its host's own rules, which are not the agent's.
+ */
+export async function classify(entries, signal, known, complete, foreign = false) {
+    const next = entries.findIndex((entry, line) => line > signal.line && isUserWritten(entry));
+    const end = Math.min(next === -1 ? entries.length : next + 1, signal.line + 1 + AFTER);
+    const window = entries.slice(Math.max(0, signal.line - BEFORE), end);
+    const reply = await complete(prompt(window, signal.line - Math.max(0, signal.line - BEFORE), signal, known.slice(0, KNOWN_SHOWN), foreign));
+    return parseSignature(reply);
+}
+export function parseSignature(reply) {
+    const json = reply.slice(reply.indexOf("{"), reply.lastIndexOf("}") + 1);
+    let value;
+    try {
+        value = JSON.parse(json);
+    }
+    catch {
+        return undefined;
+    }
+    if (value.failure === false)
+        return "not_a_failure";
+    const { cause, behavior, mechanism } = value;
+    if (!CAUSES.includes(cause) || !BEHAVIORS.includes(behavior))
+        return undefined;
+    if (typeof mechanism !== "string" || !MECHANISM.test(mechanism))
+        return undefined;
+    return { cause, behavior, mechanism };
+}
+/** The key failures of one kind share. */
+export function signatureKey(signature) {
+    return `${signature.cause}/${signature.behavior}/${signature.mechanism}`;
+}
+function prompt(window, at, signal, known, foreign) {
+    return [
+        "An agent's session may have gone wrong at the line marked >>> below. If it did, name the failure with three",
+        "fields, as one JSON object.",
+        `- cause: one of ${CAUSES.join(", ")}`,
+        `- behavior: what the agent did that led to it, one of ${BEHAVIORS.join(", ")}`,
+        "- mechanism: a kebab-case name for how it failed, of at most 8 words, general enough to recur in other sessions",
+        ...(known.length === 0 ? [] : [
+            "When it is the same failure as one already named, reply with that one exactly, all three fields as they are;",
+            "name a new one when they only sound alike:",
+            ...known.map((signature) => JSON.stringify(signature)),
+        ]),
+        'Reply {"failure":false} when it is no failure of the agent\'s own making:',
+        "- the agent got what it needed and carried on, as the lines after it show, such as when a search rightly found",
+        "  nothing or one part of a longer command exited non-zero",
+        "- the outside world failed, such as the network or a service, and no other step would have fared better",
+        ...(foreign ? [
+            "- the agent's host refused it by a rule of its own, such as a blocked command, a permission check or a sandbox",
+            "  limit; this session comes from another agent, and its host's rules are not this agent's",
+        ] : []),
+        `The signal: ${JSON.stringify(signal)}`,
+        "The session around it, one ACP entry per line:",
+        ...window.map((entry, line) => {
+            const text = JSON.stringify(entry);
+            return `${line === at ? ">>> " : ""}${text.length <= ENTRY_CHARS ? text : `${text.slice(0, ENTRY_CHARS)}…`}`;
+        }),
+        'Reply with only the JSON object, such as {"cause":"…","behavior":"…","mechanism":"…"} or {"failure":false}.',
+    ].join("\n");
+}
+//# sourceMappingURL=classify.js.map

package/dist/evidence/classify.js.map

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

package/dist/evidence/corrections.d.ts

@@ -0,0 +1,14 @@
+import type { TranscriptEntry } from "../transcript.js";
+import type { Complete } from "./classify.js";
+/** A user message that may correct the agent; it counts as a failure only once the user confirms it. */
+export interface CorrectionCandidate {
+    /** The transcript line of the user's message. */
+    line: number;
+    /** What the user corrected, in a few words. */
+    summary: string;
+}
+/**
+ * Lines from `from` on where the user pushed back on what the agent did. A model proposes them, since no event marks
+ * a correction; a long session is asked about in batches, and lines the user did not write are dropped.
+ */
+export declare function proposeCorrections(entries: readonly TranscriptEntry[], complete: Complete, from?: number): Promise<CorrectionCandidate[]>;

package/dist/evidence/corrections.js

@@ -0,0 +1,61 @@
+import { correctedStep, isUserWritten } from "./points.js";
+/** How much of each message the model is shown, and how much one request carries, so a long session stays cheap. */
+const USER_CHARS = 1200;
+const AGENT_CHARS = 600;
+const BATCH_CHARS = 60_000;
+/**
+ * Lines from `from` on where the user pushed back on what the agent did. A model proposes them, since no event marks
+ * a correction; a long session is asked about in batches, and lines the user did not write are dropped.
+ */
+export async function proposeCorrections(entries, complete, from = 0) {
+    const users = entries.flatMap((entry, line) => (line >= from && isUserWritten(entry) ? [line] : []));
+    const found = [];
+    for (const batch of batches(users.map((line) => excerpt(entries, line)))) {
+        const reply = await complete([
+            "Below are the user's messages from an agent session, each with the agent step just before it. Find the user",
+            "messages that correct the agent: rejecting what it did, pointing out a mistake, or restating a rule it broke.",
+            "Questions and new requests are not corrections, nor are praise, agreement, or frustration that names nothing to",
+            "do differently. Summarize each as what the agent should do instead, in a few words. Reply with only a JSON",
+            'array such as [{"line":12,"summary":"use pnpm, not npm"}], or [] for none.',
+            ...batch,
+        ].join("\n"));
+        found.push(...parseCandidates(reply, users));
+    }
+    return found;
+}
+function excerpt(entries, line) {
+    const before = correctedStep(entries, line);
+    const agent = before === undefined ? "" : `agent before ${line}: ${clip(JSON.stringify(entries[before]), AGENT_CHARS)}\n`;
+    return `${agent}user ${line}: ${clip(JSON.stringify(entries[line]), USER_CHARS)}`;
+}
+function batches(excerpts) {
+    const all = [];
+    let size = Infinity;
+    for (const text of excerpts) {
+        if (size + text.length > BATCH_CHARS) {
+            all.push([]);
+            size = 0;
+        }
+        all.at(-1).push(text);
+        size += text.length;
+    }
+    return all;
+}
+function parseCandidates(reply, users) {
+    let found;
+    try {
+        found = JSON.parse(reply.slice(reply.indexOf("["), reply.lastIndexOf("]") + 1));
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(found))
+        return [];
+    return found.flatMap((item) => typeof item.line === "number" && users.includes(item.line) && typeof item.summary === "string" && item.summary !== ""
+        ? [{ line: item.line, summary: item.summary }]
+        : []);
+}
+function clip(text, limit) {
+    return text.length <= limit ? text : `${text.slice(0, limit)}…`;
+}
+//# sourceMappingURL=corrections.js.map

package/dist/evidence/corrections.js.map

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

package/dist/evidence/failures.d.ts

@@ -0,0 +1,44 @@
+import { type Complete, type FailureSignature } from "./classify.js";
+/** One failure in one session, with its signature. */
+export interface Failure {
+    session: string;
+    /** The transcript line where it happened. */
+    line: number;
+    signature: FailureSignature;
+    /** The version of the rules it was named by. */
+    classifier?: number;
+}
+/** Failures of one kind, and the distinct sessions they came from. */
+export interface FailureClass {
+    key: string;
+    /** The signature most of its failures were named with. */
+    signature: FailureSignature;
+    failures: Failure[];
+    sessions: string[];
+}
+/** How many distinct sessions a kind of failure must appear in before it starts a round. */
+export declare const TRIGGER_SESSIONS = 2;
+/**
+ * The key failures of one kind share: what the agent did and how it failed. The cause is a judgement that differs
+ * between sessions for the same mechanism, so it describes a kind without splitting it.
+ */
+export declare function kindKey(signature: FailureSignature): string;
+/**
+ * Failures grouped by kind, the kinds seen in the most sessions first. `aliases` maps a kind's key to the key of the
+ * kind it is another name for, whose name the merged kind carries.
+ */
+export declare function groupFailures(failures: readonly Failure[], aliases?: ReadonlyMap<string, string>): FailureClass[];
+/** The kinds looked at for other names before, and the aliases found among them. */
+export interface KindNaming {
+    reviewed: readonly string[];
+    aliases: ReadonlyMap<string, string>;
+}
+/**
+ * Which kinds are other names for one mechanism. Each behavior with a kind not looked at before is asked about once,
+ * with every name given within it; a new kind joins the kind of an earlier name it is grouped with, or else the first
+ * new name of its group, while kinds looked at before keep the names they were given, so grouping only ever settles.
+ * A reply naming a kind that is not there, or one kind twice, is not taken.
+ */
+export declare function kindAliases(kinds: readonly string[], complete: Complete, before?: KindNaming): Promise<Map<string, string>>;
+/** The kinds of failure that have recurred often enough to start a round. */
+export declare function triggered(classes: readonly FailureClass[], sessions?: number): FailureClass[];

package/dist/evidence/failures.js

@@ -0,0 +1,91 @@
+import { signatureKey } from "./classify.js";
+/** How many distinct sessions a kind of failure must appear in before it starts a round. */
+export const TRIGGER_SESSIONS = 2;
+/**
+ * The key failures of one kind share: what the agent did and how it failed. The cause is a judgement that differs
+ * between sessions for the same mechanism, so it describes a kind without splitting it.
+ */
+export function kindKey(signature) {
+    return `${signature.behavior}/${signature.mechanism}`;
+}
+/**
+ * Failures grouped by kind, the kinds seen in the most sessions first. `aliases` maps a kind's key to the key of the
+ * kind it is another name for, whose name the merged kind carries.
+ */
+export function groupFailures(failures, aliases = new Map()) {
+    const classes = new Map();
+    for (const failure of failures) {
+        const own = kindKey(failure.signature);
+        const key = aliases.get(own) ?? own;
+        const found = classes.get(key) ?? { key, signature: failure.signature, failures: [], sessions: [] };
+        found.failures.push(failure);
+        if (!found.sessions.includes(failure.session))
+            found.sessions.push(failure.session);
+        classes.set(key, found);
+    }
+    for (const found of classes.values()) {
+        const signature = mostCommon(found.failures.map((failure) => failure.signature));
+        found.signature = { ...signature, mechanism: found.key.slice(found.key.indexOf("/") + 1) };
+    }
+    return [...classes.values()].sort((a, b) => b.sessions.length - a.sessions.length);
+}
+/**
+ * Which kinds are other names for one mechanism. Each behavior with a kind not looked at before is asked about once,
+ * with every name given within it; a new kind joins the kind of an earlier name it is grouped with, or else the first
+ * new name of its group, while kinds looked at before keep the names they were given, so grouping only ever settles.
+ * A reply naming a kind that is not there, or one kind twice, is not taken.
+ */
+export async function kindAliases(kinds, complete, before = { reviewed: [], aliases: new Map() }) {
+    const aliases = new Map(before.aliases);
+    const reviewed = new Set(before.reviewed);
+    for (const [behavior, keys] of Map.groupBy(kinds, (key) => key.slice(0, key.indexOf("/")))) {
+        if (keys.length < 2 || keys.every((key) => reviewed.has(key)))
+            continue;
+        const names = keys.map((key) => key.slice(behavior.length + 1));
+        const reply = await complete([
+            `Below are names an agent's failures were given, all from the behavior "${behavior}". Group the names that name`,
+            "the same mechanism in other words, so a fix for one is a fix for all; names that are only related stay apart.",
+            'Reply with only a JSON array of groups, each with the name to keep first, such as [["a-b","a-b-c"]], or [] for',
+            "none.",
+            ...names,
+        ].join("\n"));
+        const seen = new Set();
+        for (const group of parseGroups(reply)) {
+            if (group.length < 2 || group.some((name) => !names.includes(name) || seen.has(name)))
+                continue;
+            for (const name of group)
+                seen.add(name);
+            const members = group.map((name) => `${behavior}/${name}`);
+            const anchor = members.find((key) => reviewed.has(key)) ?? members[0];
+            const target = aliases.get(anchor) ?? anchor;
+            for (const key of members)
+                if (!reviewed.has(key) && key !== target)
+                    aliases.set(key, target);
+        }
+    }
+    return aliases;
+}
+function parseGroups(reply) {
+    try {
+        const value = JSON.parse(reply.slice(reply.indexOf("["), reply.lastIndexOf("]") + 1));
+        if (!Array.isArray(value))
+            return [];
+        return value.filter((group) => Array.isArray(group) && group.every((name) => typeof name === "string"));
+    }
+    catch {
+        return [];
+    }
+}
+function mostCommon(signatures) {
+    const counts = new Map();
+    for (const signature of signatures) {
+        const key = signatureKey(signature);
+        counts.set(key, { signature, count: (counts.get(key)?.count ?? 0) + 1 });
+    }
+    return [...counts.values()].reduce((best, next) => (next.count > best.count ? next : best)).signature;
+}
+/** The kinds of failure that have recurred often enough to start a round. */
+export function triggered(classes, sessions = TRIGGER_SESSIONS) {
+    return classes.filter((found) => found.sessions.length >= sessions);
+}
+//# sourceMappingURL=failures.js.map

package/dist/evidence/failures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failures.js","sourceRoot":"","sources":["../../src/evidence/failures.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAwC,MAAM,eAAe,CAAC;AAqBnF,4FAA4F;AAC5F,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAElC;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,SAA2B;IACjD,OAAO,GAAG,SAAS,CAAC,QAAQ,IAAI,SAAS,CAAC,SAAS,EAAE,CAAC;AACxD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,QAA4B,EAAE,OAAO,GAAgC,IAAI,GAAG,EAAE;IAC1G,MAAM,OAAO,GAAG,IAAI,GAAG,EAAwB,CAAC;IAChD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACvC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC;QACpC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QACpG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7B,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC;YAAE,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACpF,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC1B,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACrC,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;QACjF,KAAK,CAAC,SAAS,GAAG,EAAE,GAAG,SAAS,EAAE,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;IAC7F,CAAC;IACD,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACrF,CAAC;AAQD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAwB,EACxB,QAAkB,EAClB,MAAM,GAAe,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE;IAEzD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC1C,KAAK,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3F,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAAE,SAAS;QACxE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;QAChE,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC;YAC3B,0EAA0E,QAAQ,8BAA8B;YAChH,+GAA+G;YAC/G,gHAAgH;YAChH,OAAO;YACP,GAAG,KAAK;SACT,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACd,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;YACvC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBAAE,SAAS;YAChG,KAAK,MAAM,IAAI,IAAI,KAAK;gBAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACzC,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,QAAQ,IAAI,IAAI,EAAE,CAAC,CAAC;YAC3D,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAE,CAAC;YACvE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC;YAC7C,KAAK,MAAM,GAAG,IAAI,OAAO;gBAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,KAAK,MAAM;oBAAE,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAChG,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,WAAW,CAAC,KAAa;IAChC,IAAI,CAAC;QACH,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC/F,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACrC,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAqB,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC;IAC7H,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,UAAuC;IACzD,MAAM,MAAM,GAAG,IAAI,GAAG,EAA0D,CAAC;IACjF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;QACpC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACxG,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,SAAS,CAAC,OAAgC,EAAE,QAAQ,GAAG,gBAAgB;IACrF,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,CAAC;AACtE,CAAC"}

package/dist/evidence/messages-jsonl.d.ts

@@ -0,0 +1,7 @@
+import type { TranscriptEntry } from "../transcript.js";
+/**
+ * A transcript from session logs written one JSON object per line, each a user or assistant message whose content is
+ * text, thinking, tool-use and tool-result blocks. Side threads and bookkeeping lines are left out; user-role text the
+ * user did not write stays in, since the model saw it, marked as injected.
+ */
+export declare function fromMessagesJsonl(text: string): TranscriptEntry[];

package/dist/evidence/messages-jsonl.js

@@ -0,0 +1,97 @@
+import { withChopinMeta } from "../meta.js";
+/**
+ * Tool names other agents use, as the tools chopin has. A call with no counterpart keeps its own name, and a
+ * continuation skips the steps it cannot offer.
+ */
+const TOOLS = { Read: "read", Write: "write", Edit: "edit", MultiEdit: "edit", Bash: "bash" };
+const INTERRUPTED = "[Request interrupted by user";
+/** How these logs record a tool call the user declined to let run. */
+const REJECTED = "User rejected tool use";
+/**
+ * A transcript from session logs written one JSON object per line, each a user or assistant message whose content is
+ * text, thinking, tool-use and tool-result blocks. Side threads and bookkeeping lines are left out; user-role text the
+ * user did not write stays in, since the model saw it, marked as injected.
+ */
+export function fromMessagesJsonl(text) {
+    const entries = [];
+    const kinds = new Map();
+    for (const raw of text.split("\n")) {
+        if (raw.trim() === "")
+            continue;
+        let line;
+        try {
+            line = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        const message = line.message;
+        if ((line.type !== "user" && line.type !== "assistant") || line.isSidechain === true || message === undefined)
+            continue;
+        const sessionId = line.sessionId ?? "";
+        const at = line.timestamp ?? "";
+        const blocks = typeof message.content === "string" ? [{ type: "text", text: message.content }] : message.content ?? [];
+        if (message.role === "user") {
+            for (const block of blocks) {
+                if (block.type === "text" && "text" in block && block.text.startsWith(INTERRUPTED)) {
+                    entries.push({ at, sessionId, turnEnd: { stopReason: "cancelled" } });
+                }
+                else {
+                    const update = userUpdate(block, kinds, line.toolUseResult === REJECTED);
+                    const injected = update?.sessionUpdate === "user_message_chunk" && line.promptSource !== "typed";
+                    if (update !== undefined) {
+                        entries.push({ at, notification: { sessionId, update: injected ? withChopinMeta(update, { injected }) : update } });
+                    }
+                }
+            }
+            continue;
+        }
+        for (const block of blocks) {
+            const update = assistantUpdate(block, kinds);
+            if (update !== undefined)
+                entries.push({ at, notification: { sessionId, update } });
+        }
+        if (message.stop_reason === "end_turn") {
+            const model = message.model === undefined ? {} : { model: { provider: "", id: message.model } };
+            entries.push({ at, sessionId, turnEnd: withChopinMeta({ stopReason: "end_turn" }, model) });
+        }
+    }
+    return entries;
+}
+function userUpdate(block, kinds, rejected) {
+    if (block.type === "text" && "text" in block)
+        return { sessionUpdate: "user_message_chunk", content: { type: "text", text: block.text } };
+    if (block.type !== "tool_result" || !("tool_use_id" in block))
+        return undefined;
+    const text = typeof block.content === "string"
+        ? block.content
+        : (block.content ?? []).flatMap((item) => (item.type === "text" && item.text !== undefined ? [item.text] : [])).join("\n");
+    const update = {
+        sessionUpdate: "tool_call_update", toolCallId: block.tool_use_id, status: block.is_error === true ? "failed" : "completed",
+        kind: kinds.get(block.tool_use_id) ?? "other", content: [{ type: "content", content: { type: "text", text } }],
+    };
+    return rejected ? withChopinMeta(update, { diagnostics: ["rejected"] }) : update;
+}
+function assistantUpdate(block, kinds) {
+    if (block.type === "text" && "text" in block)
+        return { sessionUpdate: "agent_message_chunk", content: { type: "text", text: block.text } };
+    if (block.type === "thinking" && "thinking" in block) {
+        return { sessionUpdate: "agent_thought_chunk", content: { type: "text", text: block.thinking } };
+    }
+    if (block.type !== "tool_use" || !("id" in block))
+        return undefined;
+    const title = TOOLS[block.name] ?? block.name;
+    const kind = toolKind(title);
+    kinds.set(block.id, kind);
+    return { sessionUpdate: "tool_call", toolCallId: block.id, title, kind, status: "pending", rawInput: block.input };
+}
+function toolKind(name) {
+    if (name === "read")
+        return "read";
+    if (name === "write" || name === "edit")
+        return "edit";
+    if (name === "bash")
+        return "execute";
+    return "other";
+}
+//# sourceMappingURL=messages-jsonl.js.map

package/dist/evidence/messages-jsonl.js.map

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

package/dist/evidence/points.d.ts

@@ -0,0 +1,26 @@
+import type { TranscriptEntry } from "../transcript.js";
+import type { Signal } from "./signals.js";
+/** Whether the entry is something the user wrote, not text the harness added in the user's role. */
+export declare function isUserWritten(entry: TranscriptEntry): boolean;
+/**
+ * A place to continue a session from: the agent step at `line`, with every line before it as the context. Continuing
+ * there shows what another version of the agent would have done instead.
+ */
+export interface DecisionPoint {
+    session: string;
+    line: number;
+}
+/**
+ * The session before `line` to continue from: the last `size` lines or so, begun at a message in the user's role,
+ * as a conversation must be; one is looked for up to `size` lines further back, and without one there is none.
+ */
+export declare function continuationPrefix(entries: readonly TranscriptEntry[], line: number, size: number): TranscriptEntry[] | undefined;
+/** The agent step a failure goes back to: the failed call itself, or the last step before the user stepped in. */
+export declare function failureStep(entries: readonly TranscriptEntry[], signal: Signal): number | undefined;
+/** The agent step a user's correction answers: the last one before the user spoke. */
+export declare function correctedStep(entries: readonly TranscriptEntry[], line: number): number | undefined;
+/**
+ * Agent steps that went right: tool calls that completed, in turns where nothing went wrong afterwards before the user
+ * spoke again. `wrong` holds the lines of the session's signals and corrections.
+ */
+export declare function goodSteps(entries: readonly TranscriptEntry[], wrong: readonly number[]): number[];

package/dist/evidence/points.js

@@ -0,0 +1,72 @@
+import { chopinMeta } from "../meta.js";
+/** Whether the entry is something the user wrote, not text the harness added in the user's role. */
+export function isUserWritten(entry) {
+    if (!("notification" in entry))
+        return false;
+    const update = entry.notification.update;
+    return update.sessionUpdate === "user_message_chunk" && chopinMeta(update)?.injected !== true;
+}
+/**
+ * The session before `line` to continue from: the last `size` lines or so, begun at a message in the user's role,
+ * as a conversation must be; one is looked for up to `size` lines further back, and without one there is none.
+ */
+export function continuationPrefix(entries, line, size) {
+    const cut = Math.max(0, line - size);
+    const userTurn = (at) => {
+        const entry = entries[at];
+        return "notification" in entry && entry.notification.update.sessionUpdate === "user_message_chunk";
+    };
+    for (let start = cut; start < line; start += 1)
+        if (userTurn(start))
+            return entries.slice(start, line);
+    for (let start = cut - 1; start >= Math.max(0, cut - size); start -= 1)
+        if (userTurn(start))
+            return entries.slice(start, line);
+    return undefined;
+}
+/** The agent step a failure goes back to: the failed call itself, or the last step before the user stepped in. */
+export function failureStep(entries, signal) {
+    if (signal.kind === "tool_failed") {
+        return entries.findIndex((entry) => "notification" in entry && entry.notification.update.sessionUpdate === "tool_call" &&
+            entry.notification.update.toolCallId === signal.toolCallId);
+    }
+    return lastAgentStep(entries, signal.line);
+}
+/** The agent step a user's correction answers: the last one before the user spoke. */
+export function correctedStep(entries, line) {
+    return lastAgentStep(entries, line);
+}
+/**
+ * Agent steps that went right: tool calls that completed, in turns where nothing went wrong afterwards before the user
+ * spoke again. `wrong` holds the lines of the session's signals and corrections.
+ */
+export function goodSteps(entries, wrong) {
+    const completed = new Set(entries.flatMap((entry) => "notification" in entry && entry.notification.update.sessionUpdate === "tool_call_update" &&
+        entry.notification.update.status === "completed" ? [entry.notification.update.toolCallId] : []));
+    return entries.flatMap((entry, line) => {
+        if (!("notification" in entry))
+            return [];
+        const update = entry.notification.update;
+        if (update.sessionUpdate !== "tool_call" || !completed.has(update.toolCallId))
+            return [];
+        const end = nextUserLine(entries, line);
+        return wrong.some((bad) => bad > line && bad <= end) ? [] : [line];
+    });
+}
+function isAgentStep(entry) {
+    if (!("notification" in entry))
+        return false;
+    const kind = entry.notification.update.sessionUpdate;
+    return kind === "tool_call" || kind === "agent_message_chunk";
+}
+function lastAgentStep(entries, before) {
+    for (let line = before - 1; line >= 0; line -= 1)
+        if (isAgentStep(entries[line]))
+            return line;
+    return undefined;
+}
+function nextUserLine(entries, after) {
+    const next = entries.findIndex((entry, line) => line > after && isUserWritten(entry));
+    return next === -1 ? entries.length : next;
+}
+//# sourceMappingURL=points.js.map

package/dist/evidence/points.js.map

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

package/dist/evidence/sanitize.d.ts

@@ -0,0 +1,16 @@
+import type { McpServer } from "../layer/mcp.js";
+import type { TranscriptEntry } from "../transcript.js";
+/** The values of environment variables named like secrets. */
+export declare function secretValues(env: Readonly<Record<string, string | undefined>>): string[];
+/**
+ * The secrets MCP servers are configured with, from headers and environment named like secrets: each whole value and
+ * each long word of it, so a token is masked with or without the scheme before it.
+ */
+export declare function mcpSecrets(servers: Readonly<Record<string, McpServer>>): string[];
+/** `text` with every known secret value and every common secret format masked. */
+export declare function redactText(text: string, values: readonly string[]): string;
+/**
+ * A transcript fit to leave the session: secrets masked in every string, and the output of any tool call that touched
+ * a secret file replaced by the fact that it did.
+ */
+export declare function redactTranscript(entries: readonly TranscriptEntry[], values: readonly string[]): TranscriptEntry[];