@garygentry/system1-core 0.1.0

package/dist/prepare.d.ts

@@ -0,0 +1,39 @@
+import { type ScrubCounts } from "./egress/scrub.js";
+import type { ModelProfile } from "./model/profiles.js";
+import type { QuestionSet } from "./model/types.js";
+import { type Projection } from "./run/budget.js";
+import type { Item, Skipped, SourceSpec } from "./sources/types.js";
+import { type SplitSpec } from "./split/split.js";
+export interface PrepareInput {
+    sources: readonly SourceSpec[];
+    split: SplitSpec;
+    questions: QuestionSet;
+    profile: ModelProfile;
+    cwd: string;
+    /** Extra exclude patterns from config. */
+    exclude?: readonly string[];
+    maxFileBytes?: number;
+    /** Allow content from outside the repo (off by default). */
+    allowOutside?: boolean;
+}
+export interface Prepared {
+    /** Ready to send: excluded, scrubbed and size-checked. */
+    items: Item[];
+    /** Everything withheld, with the reason. Always reported, never silent. */
+    skipped: Skipped[];
+    /** `items`: how many documents or items had at least one redaction. */
+    redactions: {
+        total: number;
+        byKind: ScrubCounts;
+        items: number;
+    };
+    projection: Projection;
+}
+/**
+ * sources → split → exclude → scrub → size check → projection.
+ *
+ * Nothing here touches the network. The caller then checks the budget and
+ * consent before any call is made.
+ */
+export declare function prepare(input: PrepareInput): Promise<Prepared>;
+//# sourceMappingURL=prepare.d.ts.map

package/dist/prepare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../src/prepare.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,WAAW,EAAyB,MAAM,mBAAmB,CAAA;AAG3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAE,WAAW,EAAS,MAAM,kBAAkB,CAAA;AAE1D,OAAO,EAAE,KAAK,UAAU,EAAW,MAAM,iBAAiB,CAAA;AAE1D,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACnE,OAAO,EAAa,KAAK,SAAS,EAAS,MAAM,kBAAkB,CAAA;AAEnE,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,SAAS,UAAU,EAAE,CAAA;IAC9B,KAAK,EAAE,SAAS,CAAA;IAChB,SAAS,EAAE,WAAW,CAAA;IACtB,OAAO,EAAE,YAAY,CAAA;IACrB,GAAG,EAAE,MAAM,CAAA;IACX,0CAA0C;IAC1C,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,0DAA0D;IAC1D,KAAK,EAAE,IAAI,EAAE,CAAA;IACb,2EAA2E;IAC3E,OAAO,EAAE,OAAO,EAAE,CAAA;IAClB,uEAAuE;IACvE,UAAU,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IACjE,UAAU,EAAE,UAAU,CAAA;CACvB;AAED;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CA4DpE"}

package/dist/prepare.js

@@ -0,0 +1,84 @@
+import { applyExcludes } from "./egress/exclude.js";
+import { scrubState, scrubText } from "./egress/scrub.js";
+import { assertStateFits } from "./egress/size.js";
+import { DecisionsError } from "./errors.js";
+import { assertQuestionSet } from "./model/validate.js";
+import { project } from "./run/budget.js";
+import { readSources } from "./sources/read.js";
+import { joinItems, split } from "./split/split.js";
+/**
+ * sources → split → exclude → scrub → size check → projection.
+ *
+ * Nothing here touches the network. The caller then checks the budget and
+ * consent before any call is made.
+ */
+export async function prepare(input) {
+    assertQuestionSet(input.questions);
+    assertChoicesFit(input.questions, input.profile);
+    const read = await readSources(input.sources, {
+        cwd: input.cwd,
+        ...(input.maxFileBytes ? { maxFileBytes: input.maxFileBytes } : {}),
+        ...(input.allowOutside ? { allowOutside: true } : {}),
+    });
+    const byKind = {};
+    /** How many documents or items had at least one redaction. */
+    let redactedSources = 0;
+    const count = (counts) => {
+        const found = Object.values(counts).reduce((a, b) => a + b, 0);
+        for (const [kind, n] of Object.entries(counts))
+            byKind[kind] = (byKind[kind] ?? 0) + n;
+        return found;
+    };
+    // Excluded files are dropped before anything else touches them, so a
+    // withheld file is never reported as scrubbed.
+    const allowed = applyExcludes(read.documents, input.exclude);
+    // Then scrub whole documents: a private key cut across two line windows
+    // would otherwise lose the markers that identify it.
+    const documents = allowed.items.map((doc) => {
+        const counts = {};
+        const scrubbed = {
+            ...doc,
+            ...(doc.text !== undefined ? { text: scrubText(doc.text, counts) } : {}),
+            ...(doc.data !== undefined ? { data: scrubState(doc.data, counts) } : {}),
+        };
+        if (count(counts) > 0)
+            redactedSources += 1;
+        return scrubbed;
+    });
+    // Again after splitting, in case a split produced a path we hadn't seen.
+    const filtered = applyExcludes(split(documents, input.split), input.exclude);
+    const kept = input.split.kind === "join" ? joinItems(filtered.items) : filtered.items;
+    // Then each item again, so anything the split produced (a join, a row read
+    // as a value) is covered too.
+    const tokens = [];
+    const items = kept.map((item) => {
+        const counts = {};
+        const state = scrubState(item.state, counts);
+        if (count(counts) > 0)
+            redactedSources += 1;
+        tokens.push(assertStateFits(item.id, state, input.questions, input.profile));
+        return { ...item, state };
+    });
+    return {
+        items,
+        skipped: [...read.skipped, ...allowed.excluded, ...filtered.excluded],
+        redactions: {
+            total: Object.values(byKind).reduce((a, b) => a + b, 0),
+            byKind,
+            items: redactedSources,
+        },
+        projection: project(input.profile, tokens),
+    };
+}
+/** Refused before any call, so a fan-out never fails N times on the same limit. */
+function assertChoicesFit(questions, profile) {
+    for (const [name, q] of Object.entries(questions)) {
+        if (q.type !== "choice")
+            continue;
+        const n = Object.keys(q.criteria).length;
+        if (n > profile.maxChoices) {
+            throw new DecisionsError("invalid-request", `Question "${name}" has ${n} options; ${profile.id} accepts at most ${profile.maxChoices}. Narrow the candidates first (e.g. screen them with a noul), then pick among the survivors.`, { question: name, options: n, maxChoices: profile.maxChoices });
+        }
+    }
+}
+//# sourceMappingURL=prepare.js.map

package/dist/prepare.js.map

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

package/dist/project/project.d.ts

@@ -0,0 +1,64 @@
+import type { Answers, QuestionSet } from "../model/types.js";
+/**
+ * Projection: the engine returns only what the agent will act on (charter
+ * principle 2). Filters, sort and field selection are parsed from a small
+ * string syntax so they fit on a command line and in a spec file.
+ */
+export type Op = ">=" | ">" | "<=" | "<" | "=" | "!=" | "in";
+export interface Filter {
+    question: string;
+    /** Dotted path into the answer, e.g. `noul`, `choice`, `probabilities.fix`. */
+    field: string;
+    op: Op;
+    value: number | string | string[];
+    /** The original text, for error messages and echoing back. */
+    source: string;
+}
+export interface SortKey {
+    question: string;
+    field: string;
+    direction: "asc" | "desc";
+}
+/** Parse `relevant>=0.7`, `kind=fix`, `kind in fix,feature`, `kind.probabilities.fix>=0.5`. */
+export declare function parseFilter(text: string, questions?: QuestionSet): Filter;
+/** Parse `relevant`, `relevant.noul:asc`, `risk.score:desc`. Defaults to descending. */
+export declare function parseSort(text: string, questions?: QuestionSet): SortKey;
+export declare function matches(answers: Answers, filter: Filter): boolean;
+export interface ProjectInput<T extends {
+    answers: Answers;
+}> {
+    rows: readonly T[];
+    keep?: readonly Filter[];
+    sort?: SortKey;
+    limit?: number;
+    fields?: readonly string[];
+    /** Names of each row's undecided answers. */
+    undecidedOf: (row: T) => readonly string[];
+}
+export interface Projected<T> {
+    kept: T[];
+    /** Kept before `limit` cut it down. */
+    keptTotal: number;
+    /** Rows whose relevant answers are too flat to judge: for the agent or a human. */
+    undecided: Array<{
+        row: T;
+        questions: string[];
+    }>;
+    dropped: number;
+}
+/**
+ * Split rows into kept / undecided / dropped.
+ *
+ * Undecided is decided first and is never subject to a threshold. A flat
+ * answer rounded into "kept" or "dropped" would be acting on noise (charter
+ * principle 4).
+ *
+ * Every question the projection *acts on* counts: those `keep` filters on and
+ * the one `sort` ranks by. (Sorting was missed before: an item ranked first by
+ * an undecided score was kept, and reported as decided.) With neither, every
+ * question counts.
+ */
+export declare function project<T extends {
+    answers: Answers;
+}>(input: ProjectInput<T>): Projected<T>;
+//# sourceMappingURL=project.d.ts.map

package/dist/project/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/project/project.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAU,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAErE;;;;GAIG;AAEH,MAAM,MAAM,EAAE,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAA;AAE5D,MAAM,WAAW,MAAM;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAA;IACb,EAAE,EAAE,EAAE,CAAA;IACN,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAA;IACjC,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,KAAK,GAAG,MAAM,CAAA;CAC1B;AAID,+FAA+F;AAC/F,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,WAAW,GAAG,MAAM,CA2BzE;AAED,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,WAAW,GAAG,OAAO,CAWxE;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAqBjE;AAED,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE;IAC1D,IAAI,EAAE,SAAS,CAAC,EAAE,CAAA;IAClB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B,6CAA6C;IAC7C,WAAW,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,SAAS,MAAM,EAAE,CAAA;CAC3C;AAED,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,EAAE,CAAA;IACT,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAA;IACjB,mFAAmF;IACnF,SAAS,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,CAAC,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAA;IACjD,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CA2B5F"}

package/dist/project/project.js

@@ -0,0 +1,144 @@
+import { DecisionsError } from "../errors.js";
+import { confidenceOf } from "../model/answers.js";
+const FILTER = /^\s*([A-Za-z_][\w-]*)((?:\.[\w-]+)*)\s*(>=|<=|!=|>|<|=|\s+in\s+)\s*(.+?)\s*$/;
+/** Parse `relevant>=0.7`, `kind=fix`, `kind in fix,feature`, `kind.probabilities.fix>=0.5`. */
+export function parseFilter(text, questions) {
+    const m = FILTER.exec(text);
+    if (!m?.[1] || !m[3] || m[4] === undefined) {
+        throw new DecisionsError("invalid-request", `Cannot parse --keep "${text}". Use <question>[.<field>]<op><value>, e.g. relevant>=0.7 or kind in fix,feature`);
+    }
+    const question = m[1];
+    const op = m[3].trim();
+    const field = m[2] ? m[2].slice(1) : defaultField(question, questions);
+    const raw = m[4];
+    const value = op === "in"
+        ? raw
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : isNumeric(raw)
+            ? Number(raw)
+            : raw;
+    const filter = { question, field, op, value, source: text };
+    if (questions)
+        assertKnown(question, questions, text);
+    if ((op === ">" || op === ">=" || op === "<" || op === "<=") && typeof value !== "number") {
+        throw new DecisionsError("invalid-request", `--keep "${text}": ${op} needs a number`);
+    }
+    return filter;
+}
+/** Parse `relevant`, `relevant.noul:asc`, `risk.score:desc`. Defaults to descending. */
+export function parseSort(text, questions) {
+    const m = /^\s*([A-Za-z_][\w-]*)((?:\.[\w-]+)*)(?::(asc|desc))?\s*$/.exec(text);
+    if (!m?.[1]) {
+        throw new DecisionsError("invalid-request", `Cannot parse --sort "${text}". Use <question>[.<field>][:asc|desc]`);
+    }
+    if (questions)
+        assertKnown(m[1], questions, text);
+    const field = m[2] ? m[2].slice(1) : sortField(m[1], questions);
+    return { question: m[1], field, direction: m[3] ?? "desc" };
+}
+export function matches(answers, filter) {
+    const actual = read(answers[filter.question], filter.field);
+    switch (filter.op) {
+        case "in":
+            return filter.value.includes(String(actual));
+        case "=":
+            return String(actual) === String(filter.value);
+        case "!=":
+            return String(actual) !== String(filter.value);
+        default: {
+            if (typeof actual !== "number")
+                return false;
+            const v = filter.value;
+            return filter.op === ">="
+                ? actual >= v
+                : filter.op === ">"
+                    ? actual > v
+                    : filter.op === "<="
+                        ? actual <= v
+                        : actual < v;
+        }
+    }
+}
+/**
+ * Split rows into kept / undecided / dropped.
+ *
+ * Undecided is decided first and is never subject to a threshold. A flat
+ * answer rounded into "kept" or "dropped" would be acting on noise (charter
+ * principle 4).
+ *
+ * Every question the projection *acts on* counts: those `keep` filters on and
+ * the one `sort` ranks by. (Sorting was missed before: an item ranked first by
+ * an undecided score was kept, and reported as decided.) With neither, every
+ * question counts.
+ */
+export function project(input) {
+    const keep = input.keep ?? [];
+    const acted = [...keep.map((f) => f.question), ...(input.sort ? [input.sort.question] : [])];
+    const relevant = acted.length > 0 ? new Set(acted) : undefined;
+    const kept = [];
+    const undecided = [];
+    let dropped = 0;
+    for (const row of input.rows) {
+        const flat = input.undecidedOf(row).filter((q) => !relevant || relevant.has(q));
+        if (flat.length > 0)
+            undecided.push({ row, questions: [...flat] });
+        else if (keep.every((f) => matches(row.answers, f)))
+            kept.push(row);
+        else
+            dropped += 1;
+    }
+    if (input.sort) {
+        const { question, field, direction } = input.sort;
+        const sign = direction === "asc" ? 1 : -1;
+        kept.sort((a, b) => sign * (num(read(a.answers[question], field)) - num(read(b.answers[question], field))));
+    }
+    const keptTotal = kept.length;
+    const limited = input.limit !== undefined ? kept.slice(0, input.limit) : kept;
+    const withFields = input.fields
+        ? limited.map((row) => pickAnswers(row, input.fields))
+        : limited;
+    return { kept: withFields, keptTotal, undecided, dropped };
+}
+function pickAnswers(row, fields) {
+    return {
+        ...row,
+        answers: Object.fromEntries(Object.entries(row.answers).filter(([k]) => fields.includes(k))),
+    };
+}
+function read(answer, field) {
+    if (!answer)
+        return undefined;
+    if (field === "confidence")
+        return confidenceOf(answer);
+    let value = answer;
+    for (const part of field.split(".")) {
+        value =
+            typeof value === "object" && value !== null
+                ? value[part]
+                : undefined;
+    }
+    return value;
+}
+function defaultField(question, questions) {
+    const type = questions?.[question]?.type;
+    return type ?? "noul";
+}
+/** Choices sort by confidence (their winner is a label, not a number). */
+function sortField(question, questions) {
+    const type = questions?.[question]?.type;
+    return type === "choice" ? "confidence" : (type ?? "noul");
+}
+function assertKnown(question, questions, text) {
+    if (!(question in questions)) {
+        throw new DecisionsError("invalid-request", `"${text}" names question "${question}", which is not in the question set (${Object.keys(questions).join(", ")})`);
+    }
+}
+function isNumeric(text) {
+    return /^-?\d+(\.\d+)?$/.test(text);
+}
+function num(value) {
+    return typeof value === "number" ? value : Number.NEGATIVE_INFINITY;
+}
+//# sourceMappingURL=project.js.map

package/dist/project/project.js.map

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

package/dist/run/budget.d.ts

@@ -0,0 +1,20 @@
+import type { Budget } from "../config/load.js";
+import type { ModelProfile } from "../model/profiles.js";
+/** A cost figure computed before running. Always labelled; never shown as measured. */
+export interface Projection {
+    basis: "projected";
+    calls: number;
+    estimatedInputTokens: number;
+    projectedUsd: number;
+    /** Listed-price date the projection used. */
+    priceAsOf: string;
+}
+export declare function project(profile: ModelProfile, tokensPerCall: readonly number[]): Projection;
+/**
+ * The spend guard (decision 0011): above either limit, stop and hand back the
+ * projection unless the caller explicitly confirmed.
+ *
+ * @throws DecisionsError `budget-exceeded`, with the projection in `details`.
+ */
+export declare function checkBudget(projection: Projection, budget: Budget, confirmed: boolean): void;
+//# sourceMappingURL=budget.d.ts.map

package/dist/run/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/run/budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAExD,uFAAuF;AACvF,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,WAAW,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,oBAAoB,EAAE,MAAM,CAAA;IAC5B,YAAY,EAAE,MAAM,CAAA;IACpB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CAS3F;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,CAc5F"}

package/dist/run/budget.js

@@ -0,0 +1,31 @@
+import { DecisionsError } from "../errors.js";
+export function project(profile, tokensPerCall) {
+    const estimatedInputTokens = tokensPerCall.reduce((a, b) => a + b, 0);
+    return {
+        basis: "projected",
+        calls: tokensPerCall.length,
+        estimatedInputTokens,
+        projectedUsd: estimatedInputTokens * profile.usdPerInputToken,
+        priceAsOf: profile.priceAsOf,
+    };
+}
+/**
+ * The spend guard (decision 0011): above either limit, stop and hand back the
+ * projection unless the caller explicitly confirmed.
+ *
+ * @throws DecisionsError `budget-exceeded`, with the projection in `details`.
+ */
+export function checkBudget(projection, budget, confirmed) {
+    if (confirmed)
+        return;
+    const over = [];
+    if (projection.calls > budget.maxCalls)
+        over.push(`${projection.calls} calls > ${budget.maxCalls}`);
+    if (projection.projectedUsd > budget.maxUsd) {
+        over.push(`projected $${projection.projectedUsd.toFixed(4)} > $${budget.maxUsd}`);
+    }
+    if (over.length === 0)
+        return;
+    throw new DecisionsError("budget-exceeded", `Over the spend guard (${over.join("; ")}). Narrow the source, or re-run with --confirm to proceed.`, { projection, budget });
+}
+//# sourceMappingURL=budget.js.map

package/dist/run/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/run/budget.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAa7C,MAAM,UAAU,OAAO,CAAC,OAAqB,EAAE,aAAgC;IAC7E,MAAM,oBAAoB,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;IACrE,OAAO;QACL,KAAK,EAAE,WAAW;QAClB,KAAK,EAAE,aAAa,CAAC,MAAM;QAC3B,oBAAoB;QACpB,YAAY,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB;QAC7D,SAAS,EAAE,OAAO,CAAC,SAAS;KAC7B,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,UAAsB,EAAE,MAAc,EAAE,SAAkB;IACpF,IAAI,SAAS;QAAE,OAAM;IACrB,MAAM,IAAI,GAAa,EAAE,CAAA;IACzB,IAAI,UAAU,CAAC,KAAK,GAAG,MAAM,CAAC,QAAQ;QACpC,IAAI,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,KAAK,YAAY,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAA;IAC7D,IAAI,UAAU,CAAC,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QAC5C,IAAI,CAAC,IAAI,CAAC,cAAc,UAAU,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,MAAM,CAAC,MAAM,EAAE,CAAC,CAAA;IACnF,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAM;IAC7B,MAAM,IAAI,cAAc,CACtB,iBAAiB,EACjB,yBAAyB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,4DAA4D,EACpG,EAAE,UAAU,EAAE,MAAM,EAAE,CACvB,CAAA;AACH,CAAC"}

package/dist/run/pool.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Run `worker` over every item, never more than `limit` at once.
+ *
+ * Results come back in input order whatever the completion order, so callers
+ * can zip them against their inputs by index.
+ *
+ * A rejected worker never aborts the run: in a wide fan-out, one transient
+ * upstream error would otherwise throw away every sibling result that was
+ * already paid for. Failures are captured per item instead.
+ */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, worker: (item: T, index: number) => Promise<R>, onProgress?: (completed: number, total: number) => void): Promise<Array<{
+    value: R;
+} | {
+    error: Error;
+}>>;
+//# sourceMappingURL=pool.d.ts.map

package/dist/run/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/run/pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAC3C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9C,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GACtD,OAAO,CAAC,KAAK,CAAC;IAAE,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC,CAuBjD"}

package/dist/run/pool.js

@@ -0,0 +1,35 @@
+/**
+ * Run `worker` over every item, never more than `limit` at once.
+ *
+ * Results come back in input order whatever the completion order, so callers
+ * can zip them against their inputs by index.
+ *
+ * A rejected worker never aborts the run: in a wide fan-out, one transient
+ * upstream error would otherwise throw away every sibling result that was
+ * already paid for. Failures are captured per item instead.
+ */
+export async function mapWithConcurrency(items, limit, worker, onProgress) {
+    const width = Math.max(1, Math.min(limit, items.length || 1));
+    const results = new Array(items.length);
+    let next = 0;
+    let completed = 0;
+    async function run() {
+        while (true) {
+            const index = next;
+            next += 1;
+            if (index >= items.length)
+                return;
+            try {
+                results[index] = { value: await worker(items[index], index) };
+            }
+            catch (error) {
+                results[index] = { error: error instanceof Error ? error : new Error(String(error)) };
+            }
+            completed += 1;
+            onProgress?.(completed, items.length);
+        }
+    }
+    await Promise.all(Array.from({ length: width }, run));
+    return results;
+}
+//# sourceMappingURL=pool.js.map

package/dist/run/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../../src/run/pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAmB,EACnB,KAAa,EACb,MAA8C,EAC9C,UAAuD;IAEvD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAA;IAC7D,MAAM,OAAO,GAAG,IAAI,KAAK,CAAkC,KAAK,CAAC,MAAM,CAAC,CAAA;IACxE,IAAI,IAAI,GAAG,CAAC,CAAA;IACZ,IAAI,SAAS,GAAG,CAAC,CAAA;IAEjB,KAAK,UAAU,GAAG;QAChB,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,KAAK,GAAG,IAAI,CAAA;YAClB,IAAI,IAAI,CAAC,CAAA;YACT,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM;gBAAE,OAAM;YACjC,IAAI,CAAC;gBACH,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,CAAM,EAAE,KAAK,CAAC,EAAE,CAAA;YACpE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAA;YACvF,CAAC;YACD,SAAS,IAAI,CAAC,CAAA;YACd,UAAU,EAAE,CAAC,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;QACvC,CAAC;IACH,CAAC;IAED,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,GAAG,CAAC,CAAC,CAAA;IACrD,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/run/spend.d.ts

@@ -0,0 +1,34 @@
+import type { Usage } from "../model/types.js";
+export type AnswerSource = "live" | "replay";
+/** One ledger line. Every figure comes from an upstream `usage` block; nothing is estimated. */
+export interface SpendEntry extends Usage {
+    ts: string;
+    session?: string;
+    model: string;
+    source: AnswerSource;
+    calls: number;
+}
+export interface SpendSummary extends Usage {
+    calls: number;
+    liveCalls: number;
+    replayCalls: number;
+}
+export declare function sumUsage(usages: ReadonlyArray<Usage | undefined>): Usage;
+/**
+ * Measured spend, persisted as append-only JSONL (default `.system1/usage.jsonl`).
+ *
+ * A file rather than process memory because the CLI is a fresh process per call:
+ * "what has this session cost" has to survive between invocations. Replayed
+ * calls are logged at zero cost so the call count stays honest.
+ */
+export declare class SpendLedger {
+    readonly file: string;
+    constructor(file: string);
+    append(entry: SpendEntry): void;
+    entries(): SpendEntry[];
+    summary(filter?: {
+        session?: string;
+        since?: Date;
+    }): SpendSummary;
+}
+//# sourceMappingURL=spend.d.ts.map

package/dist/run/spend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend.d.ts","sourceRoot":"","sources":["../../src/run/spend.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAE9C,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAA;AAE5C,gGAAgG;AAChG,MAAM,WAAW,UAAW,SAAQ,KAAK;IACvC,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,YAAY,CAAA;IACpB,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,YAAa,SAAQ,KAAK;IACzC,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,GAAG,SAAS,CAAC,GAAG,KAAK,CAWxE;AAED;;;;;;GAMG;AACH,qBAAa,WAAW;IACV,QAAQ,CAAC,IAAI,EAAE,MAAM;IAAjC,YAAqB,IAAI,EAAE,MAAM,EAAI;IAErC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAG9B;IAED,OAAO,IAAI,UAAU,EAAE,CAYtB;IAED,OAAO,CAAC,MAAM,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,IAAI,CAAA;KAAO,GAAG,YAAY,CAcrE;CACF"}

package/dist/run/spend.js

@@ -0,0 +1,55 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+export function sumUsage(usages) {
+    const total = usages.reduce((sum, u) => ({
+        input_tokens: sum.input_tokens + (u?.input_tokens ?? 0),
+        output_tokens: sum.output_tokens + (u?.output_tokens ?? 0),
+        cost: sum.cost + (u?.cost ?? 0),
+    }), { input_tokens: 0, output_tokens: 0, cost: 0 });
+    // One unreported call makes the total a lower bound, so say so.
+    return usages.some((u) => u?.reported === false) ? { ...total, reported: false } : total;
+}
+/**
+ * Measured spend, persisted as append-only JSONL (default `.system1/usage.jsonl`).
+ *
+ * A file rather than process memory because the CLI is a fresh process per call:
+ * "what has this session cost" has to survive between invocations. Replayed
+ * calls are logged at zero cost so the call count stays honest.
+ */
+export class SpendLedger {
+    file;
+    constructor(file) {
+        this.file = file;
+    }
+    append(entry) {
+        mkdirSync(dirname(this.file), { recursive: true });
+        appendFileSync(this.file, `${JSON.stringify(entry)}\n`);
+    }
+    entries() {
+        if (!existsSync(this.file))
+            return [];
+        return readFileSync(this.file, "utf8")
+            .split("\n")
+            .filter((line) => line.trim() !== "")
+            .flatMap((line) => {
+            try {
+                return [JSON.parse(line)];
+            }
+            catch {
+                return []; // a torn last line from a crash is skipped, not fatal
+            }
+        });
+    }
+    summary(filter = {}) {
+        const rows = this.entries().filter((e) => (filter.session === undefined || e.session === filter.session) &&
+            (filter.since === undefined || new Date(e.ts) >= filter.since));
+        const count = (source) => rows.filter((e) => e.source === source).reduce((n, e) => n + e.calls, 0);
+        return {
+            ...sumUsage(rows),
+            calls: rows.reduce((n, e) => n + e.calls, 0),
+            liveCalls: count("live"),
+            replayCalls: count("replay"),
+        };
+    }
+}
+//# sourceMappingURL=spend.js.map

package/dist/run/spend.js.map

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

package/dist/sources/read.d.ts

@@ -0,0 +1,40 @@
+import type { Document, LineRange, Skipped, SourceSpec } from "./types.js";
+export interface ReadOptions {
+    /** Paths resolve against this directory (normally the repo root). */
+    cwd: string;
+    /** Files larger than this are skipped as `too-large` without being read. */
+    maxFileBytes?: number;
+    /**
+     * Allow content from outside `cwd`. Off by default: consent is given per
+     * repo, so a path (or a symlink) that resolves elsewhere is withheld.
+     */
+    allowOutside?: boolean;
+}
+export interface ReadResult {
+    documents: Document[];
+    skipped: Skipped[];
+}
+export declare function readSources(specs: readonly SourceSpec[], options: ReadOptions): Promise<ReadResult>;
+/**
+ * Parse `path`, `path:12` or `path:12-40` (1-based, inclusive). A bare `:`
+ * suffix that isn't a line spec stays part of the path.
+ */
+export declare function parseFileRef(ref: string): {
+    path: string;
+    range?: LineRange;
+};
+/**
+ * The subset of `paths` git would ignore, when `cwd` is inside a work tree.
+ * Outside one, nothing is filtered (and `node_modules`/`.git` are still skipped).
+ */
+export declare function gitIgnored(cwd: string, paths: readonly string[]): string[];
+export declare function splitDiffByFile(diff: string): {
+    documents: Document[];
+    skipped: Skipped[];
+};
+/**
+ * Git quotes paths with unusual bytes (`"secrets/\303\251.txt"`). Left quoted,
+ * the path never matches an exclude, so it is decoded here.
+ */
+export declare function unquoteGitPath(path: string): string | undefined;
+//# sourceMappingURL=read.d.ts.map

package/dist/sources/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/sources/read.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE1E,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAA;IACX,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAgCD,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,QAAQ,EAAE,CAAA;IACrB,OAAO,EAAE,OAAO,EAAE,CAAA;CACnB;AAQD,wBAAsB,WAAW,CAC/B,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC,CASrB;AAmBD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,CAY7E;AAwED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAwB1E;AAyED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,EAAE,CAAA;CAAE,CAsB3F;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAyB/D"}