@smthrs/harness 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/Relevance.js

@@ -0,0 +1,254 @@
+/**
+ * What a run is shown of the human-provided items it could be shown.
+ *
+ * Memory rows, catalog flows and skills, and chunks of instruction files such
+ * as `AGENTS.md` are items. {@link judge} asks Jev one question about each:
+ * is it unnecessary for the task as stated? An item is withheld only when Jev
+ * says so with probability at or above {@link withholdAt}; everything else is
+ * kept. An item longer than {@link itemBytes} is sent head-kept and always
+ * kept: Jev cannot be confident about text it was not shown. A reading that
+ * cannot be judged keeps everything, and the caller
+ * journals `decision-unjudged` for it: keeping is the rule, withholding is
+ * the exception Jev must be confident of.
+ *
+ * Nothing here journals or filters a live catalog. {@link settled} is the row
+ * a caller writes for a reading, and {@link render} the instruction block a
+ * caller builds from what was kept.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Digest from "@smthrs/core/Digest";
+import * as Classifier from "@smthrs/model/Classifier";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as AgentEvent from "./AgentEvent.js";
+import * as bytes from "./internal/bytes.js";
+import * as elide from "./internal/elide.js";
+import { untrustedData } from "./internal/untrustedData.js";
+import * as Judgement from "./Judgement.js";
+/**
+ * What an item is.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export const Kind = AgentEvent.RelevanceKind;
+/**
+ * One human-provided item a run could be shown.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const Item = Schema.Struct({ kind: Kind, id: Schema.String, text: Schema.String });
+/**
+ * What every reading is told beside its items.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const Context = Schema.Struct({
+    task: Schema.String,
+    query: Schema.optionalKey(Schema.String),
+    recent: Schema.optionalKey(Schema.String)
+});
+/**
+ * The probability of "unnecessary" at or above which an item is withheld.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const withholdAt = 0.9;
+/**
+ * The `Classifier.confident` floor that is {@link withholdAt} for a boolean:
+ * its confidence is its distance from even odds, doubled.
+ */
+const confidentAt = (withholdAt - 0.5) * 2;
+/**
+ * The most of one item's text a reading carries, in UTF-8 bytes; the head
+ * kept.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const itemBytes = 1024;
+/** The most of a flow's description an item carries, in UTF-8 bytes. */
+const descriptionBytes = 512;
+const recall = "the rest is not shown";
+/** `text` within `limit` bytes, its head kept and the cut stated. */
+const headKept = (text, limit) => {
+    const whole = bytes.size(text);
+    if (whole <= limit)
+        return text;
+    // The notice names at most `whole` dropped bytes.
+    return elide.head(text, limit - bytes.size(`… [+${whole}b, ${recall}]`), recall);
+};
+/**
+ * The reading: one question per item, `unnecessary_${index}`.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const reader = Judgement.perItem({
+    id: "relevance/unnecessary",
+    description: "Decide which provided items an agent run does not need",
+    context: Context,
+    item: Item,
+    questions: {
+        unnecessary: (i) => Classifier.boolean({
+            instructions: `Is items[${i}] unnecessary for the task as stated? Read context.task, and context.query or context.recent when present.`,
+            criteria: {
+                true: "nothing the task, context.query, or a step they plainly imply uses it, needs it, or must follow it",
+                false: "the task, context.query, or a step they plainly imply may use it, need it, or must follow it"
+            }
+        })
+    }
+});
+/**
+ * Asks Jev which of `items` the run does not need. Each item's text is sent
+ * head-kept to {@link itemBytes}, and an item that was cut is never withheld.
+ * No items ask nothing.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const judge = (context, items) => Effect.gen(function* () {
+    const sent = items.map((item) => ({ ...item, text: headKept(item.text, itemBytes) }));
+    const [elapsed, read] = yield* reader.read(context, sent).pipe(Effect.timed);
+    const verdicts = items.map((item, index) => {
+        const answer = read.answers[index].unnecessary;
+        return {
+            item,
+            digest: Digest.digest(item.text),
+            p: answer.probability,
+            withheld: bytes.size(item.text) <= itemBytes &&
+                Option.getOrElse(Classifier.confident(answer, confidentAt), () => false)
+        };
+    });
+    const usages = read.asked.flatMap((asked) => asked.usage === undefined ? [] : [asked.usage]);
+    return {
+        verdicts,
+        asked: read.asked,
+        latencyMs: Math.round(Duration.toMillis(elapsed)),
+        ...(usages.length === 0 ? {} : {
+            usage: {
+                inputTokens: usages.reduce((sum, usage) => sum + usage.inputTokens, 0),
+                outputTokens: usages.reduce((sum, usage) => sum + usage.outputTokens, 0)
+            }
+        })
+    };
+});
+/**
+ * The `relevance-settled` row for a reading: ids and digests, never text.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export const settled = (reading, at) => {
+    const row = (verdict) => ({
+        kind: verdict.item.kind,
+        id: verdict.item.id,
+        digest: verdict.digest,
+        p: verdict.p
+    });
+    return new AgentEvent.RelevanceSettled({
+        eventType: AgentEvent.eventType.relevanceSettled,
+        scope: at.scope,
+        frame: at.frame,
+        source: at.source,
+        withholdAt,
+        kept: reading.verdicts.filter((verdict) => !verdict.withheld).map(row),
+        withheld: reading.verdicts.filter((verdict) => verdict.withheld).map(row),
+        latencyMs: reading.latencyMs,
+        ...(reading.usage === undefined ? {} : { usage: reading.usage })
+    });
+};
+/**
+ * A catalog entry as an item: a `skill` when its body is markdown, else a
+ * `flow`. Its description is untrusted data.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const flowItem = (descriptor) => {
+    const description = untrustedData(headKept(descriptor.description, descriptionBytes), `description of ${descriptor.name}`);
+    const capabilities = descriptor.capabilities.length === 0
+        ? ""
+        : `\ncapabilities: ${[...descriptor.capabilities].sort().join(",")}`;
+    return {
+        kind: descriptor.body._tag === "Markdown" ? "skill" : "flow",
+        id: descriptor.name,
+        text: `${descriptor.name}\n${description}${capabilities}`
+    };
+};
+/**
+ * One human-provided instruction file.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const Document = Schema.Struct({ path: Schema.String, text: Schema.String });
+const heading = /^#{1,6}(?:[ \t]|$)/;
+const listItem = /^(?:[-*+] |\d+\. )/;
+const fence = /^[ \t]*```/;
+const blank = /^[ \t]*\r?$/;
+const indented = /^[ \t]/;
+const split = (document) => {
+    const pieces = [];
+    let fenced = false;
+    // A list item's chunk runs over its indented and wrapped lines, and ends at
+    // the first unindented line after a blank one.
+    let item = false;
+    let afterBlank = false;
+    for (const line of document.text.match(/[^\n]*\n|[^\n]+$/g) ?? []) {
+        const bare = line.endsWith("\n") ? line.slice(0, -1) : line;
+        const starts = !fenced && pieces.length > 0 && (heading.test(bare) || listItem.test(bare) ||
+            (item && afterBlank && !blank.test(bare) && !indented.test(bare)));
+        if (!fenced && (heading.test(bare) || listItem.test(bare)))
+            item = listItem.test(bare);
+        else if (starts)
+            item = false;
+        if (starts || pieces.length === 0)
+            pieces.push(line);
+        else
+            pieces[pieces.length - 1] += line;
+        if (fence.test(bare))
+            fenced = !fenced;
+        afterBlank = !fenced && blank.test(bare);
+    }
+    return pieces.map((text, n) => ({ id: `${document.path}#${n}`, path: document.path, text }));
+};
+/**
+ * Splits instruction files into the chunks a reading judges, in order.
+ *
+ * A chunk starts at each markdown heading and at each top-level list item,
+ * whose indented and wrapped lines are its own. Every other line, blank lines
+ * included, joins the chunk before it, and nothing inside a fence is split.
+ * A file's chunks concatenate back to the file.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const chunks = (documents) => documents.flatMap(split);
+/**
+ * The project-instructions block of every chunk not in `withheld`, in order.
+ * A file whose every chunk is withheld is left out, and `""` is returned when
+ * nothing is left.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export const render = (documents, withheld) => {
+    const blocks = documents.flatMap((document) => {
+        const all = split(document);
+        const kept = all.filter((chunk) => !withheld.has(chunk.id));
+        if (all.length > 0 && kept.length === 0)
+            return [];
+        return [
+            `<project_instructions path="${document.path}">\n${kept.map((chunk) => chunk.text).join("")}\n</project_instructions>`
+        ];
+    });
+    return blocks.length === 0 ? "" : "Project-specific instructions and guidelines:\n\n" + blocks.join("\n\n");
+};
+//# sourceMappingURL=Relevance.js.map

package/dist/esm/Relevance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Relevance.js","sourceRoot":"","sources":["../../src/Relevance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,MAAM,MAAM,qBAAqB,CAAA;AAC7C,OAAO,KAAK,UAAU,MAAM,0BAA0B,CAAA;AAGtD,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,KAAK,MAAM,qBAAqB,CAAA;AAC5C,OAAO,KAAK,KAAK,MAAM,qBAAqB,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAC3D,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAE3C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,UAAU,CAAC,aAAa,CAAA;AAU5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAA;AAUzF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC;IACnC,IAAI,EAAE,MAAM,CAAC,MAAM;IACnB,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC;IACxC,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC;CAC1C,CAAC,CAAA;AAUF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,CAAA;AAE7B;;;GAGG;AACH,MAAM,WAAW,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC,GAAG,CAAC,CAAA;AAE1C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAA;AAE7B,wEAAwE;AACxE,MAAM,gBAAgB,GAAG,GAAG,CAAA;AAE5B,MAAM,MAAM,GAAG,uBAAuB,CAAA;AAEtC,qEAAqE;AACrE,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAE,KAAa,EAAU,EAAE;IACvD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC9B,IAAI,KAAK,IAAI,KAAK;QAAE,OAAO,IAAI,CAAA;IAC/B,kDAAkD;IAClD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,KAAK,MAAM,MAAM,GAAG,CAAC,EAAE,MAAM,CAAC,CAAA;AAClF,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC;IACtC,EAAE,EAAE,uBAAuB;IAC3B,WAAW,EAAE,wDAAwD;IACrE,OAAO,EAAE,OAAO;IAChB,IAAI,EAAE,IAAI;IACV,SAAS,EAAE;QACT,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,CACjB,UAAU,CAAC,OAAO,CAAC;YACjB,YAAY,EACV,YAAY,CAAC,4GAA4G;YAC3H,QAAQ,EAAE;gBACR,IAAI,EAAE,oGAAoG;gBAC1G,KAAK,EAAE,8FAA8F;aACtG;SACF,CAAC;KACL;CACF,CAAC,CAAA;AA+BF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,OAAgB,EAAE,KAA0B,EAA8C,EAAE,CAChH,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC,CAAA;IACrF,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAC5E,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAW,EAAE;QAClD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAE,CAAC,WAAW,CAAA;QAC/C,OAAO;YACL,IAAI;YACJ,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;YAChC,CAAC,EAAE,MAAM,CAAC,WAAW;YACrB,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS;gBAC1C,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,SAAS,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC;SAC3E,CAAA;IACH,CAAC,CAAC,CAAA;IACF,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAA;IAC5F,OAAO;QACL,QAAQ;QACR,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACjD,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAC7B,KAAK,EAAE;gBACL,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;gBACtE,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC;aACzE;SACF,CAAC;KACH,CAAA;AACH,CAAC,CAAC,CAAA;AAEJ;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CACrB,OAAgB,EAChB,EAA8G,EACjF,EAAE;IAC/B,MAAM,GAAG,GAAG,CAAC,OAAgB,EAAE,EAAE,CAAC,CAAC;QACjC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI;QACvB,EAAE,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE;QACnB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,CAAC,EAAE,OAAO,CAAC,CAAC;KACb,CAAC,CAAA;IACF,OAAO,IAAI,UAAU,CAAC,gBAAgB,CAAC;QACrC,SAAS,EAAE,UAAU,CAAC,SAAS,CAAC,gBAAgB;QAChD,KAAK,EAAE,EAAE,CAAC,KAAK;QACf,KAAK,EAAE,EAAE,CAAC,KAAK;QACf,MAAM,EAAE,EAAE,CAAC,MAAM;QACjB,UAAU;QACV,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;QACtE,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;QACzE,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;KACjE,CAAC,CAAA;AACJ,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,UAAqC,EAAQ,EAAE;IACtE,MAAM,WAAW,GAAG,aAAa,CAC/B,QAAQ,CAAC,UAAU,CAAC,WAAW,EAAE,gBAAgB,CAAC,EAClD,kBAAkB,UAAU,CAAC,IAAI,EAAE,CACpC,CAAA;IACD,MAAM,YAAY,GAAG,UAAU,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC;QACvD,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,mBAAmB,CAAC,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAA;IACtE,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;QAC5D,EAAE,EAAE,UAAU,CAAC,IAAI;QACnB,IAAI,EAAE,GAAG,UAAU,CAAC,IAAI,KAAK,WAAW,GAAG,YAAY,EAAE;KAC1D,CAAA;AACH,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAA;AAuBnF,MAAM,OAAO,GAAG,oBAAoB,CAAA;AACpC,MAAM,QAAQ,GAAG,oBAAoB,CAAA;AACrC,MAAM,KAAK,GAAG,YAAY,CAAA;AAC1B,MAAM,KAAK,GAAG,aAAa,CAAA;AAC3B,MAAM,QAAQ,GAAG,QAAQ,CAAA;AAEzB,MAAM,KAAK,GAAG,CAAC,QAAkB,EAAwB,EAAE;IACzD,MAAM,MAAM,GAAkB,EAAE,CAAA;IAChC,IAAI,MAAM,GAAG,KAAK,CAAA;IAClB,4EAA4E;IAC5E,+CAA+C;IAC/C,IAAI,IAAI,GAAG,KAAK,CAAA;IAChB,IAAI,UAAU,GAAG,KAAK,CAAA;IACtB,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,mBAAmB,CAAC,IAAI,EAAE,EAAE,CAAC;QAClE,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;QAC3D,MAAM,MAAM,GAAG,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;YACvF,CAAC,IAAI,IAAI,UAAU,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACpE,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAAE,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;aACjF,IAAI,MAAM;YAAE,IAAI,GAAG,KAAK,CAAA;QAC7B,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;;YAC/C,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,IAAI,CAAA;QACtC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,MAAM,GAAG,CAAC,MAAM,CAAA;QACtC,UAAU,GAAG,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC1C,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,QAAQ,CAAC,IAAI,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;AAC9F,CAAC,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,SAAkC,EAAwB,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAE5G;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,SAAkC,EAAE,QAA6B,EAAU,EAAE;IAClG,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE;QAC5C,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAA;QAC3B,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;QAC3D,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAA;QAClD,OAAO;YACL,+BAA+B,QAAQ,CAAC,IAAI,OAC1C,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CACzC,2BAA2B;SAC5B,CAAA;IACH,CAAC,CAAC,CAAA;IACF,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,mDAAmD,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;AAC7G,CAAC,CAAA","sourcesContent":["/**\n * What a run is shown of the human-provided items it could be shown.\n *\n * Memory rows, catalog flows and skills, and chunks of instruction files such\n * as `AGENTS.md` are items. {@link judge} asks Jev one question about each:\n * is it unnecessary for the task as stated? An item is withheld only when Jev\n * says so with probability at or above {@link withholdAt}; everything else is\n * kept. An item longer than {@link itemBytes} is sent head-kept and always\n * kept: Jev cannot be confident about text it was not shown. A reading that\n * cannot be judged keeps everything, and the caller\n * journals `decision-unjudged` for it: keeping is the rule, withholding is\n * the exception Jev must be confident of.\n *\n * Nothing here journals or filters a live catalog. {@link settled} is the row\n * a caller writes for a reading, and {@link render} the instruction block a\n * caller builds from what was kept.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Digest from \"@smthrs/core/Digest\"\nimport * as Classifier from \"@smthrs/model/Classifier\"\nimport type * as Evaluator from \"@smthrs/model/Evaluator\"\nimport type * as Descriptor from \"@smthrs/registry/Descriptor\"\nimport * as Duration from \"effect/Duration\"\nimport * as Effect from \"effect/Effect\"\nimport * as Option from \"effect/Option\"\nimport * as Schema from \"effect/Schema\"\nimport * as AgentEvent from \"./AgentEvent.ts\"\nimport * as bytes from \"./internal/bytes.ts\"\nimport * as elide from \"./internal/elide.ts\"\nimport { untrustedData } from \"./internal/untrustedData.ts\"\nimport * as Judgement from \"./Judgement.ts\"\n\n/**\n * What an item is.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport const Kind = AgentEvent.RelevanceKind\n\n/**\n * The decoded form of {@link Kind}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Kind = typeof Kind.Type\n\n/**\n * One human-provided item a run could be shown.\n *\n * @category schemas\n * @since 1.0.0-rc.0\n */\nexport const Item = Schema.Struct({ kind: Kind, id: Schema.String, text: Schema.String })\n\n/**\n * The decoded form of {@link Item}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Item = typeof Item.Type\n\n/**\n * What every reading is told beside its items.\n *\n * @category schemas\n * @since 1.0.0-rc.0\n */\nexport const Context = Schema.Struct({\n  task: Schema.String,\n  query: Schema.optionalKey(Schema.String),\n  recent: Schema.optionalKey(Schema.String)\n})\n\n/**\n * The decoded form of {@link Context}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Context = typeof Context.Type\n\n/**\n * The probability of \"unnecessary\" at or above which an item is withheld.\n *\n * @category constants\n * @since 1.0.0-rc.0\n */\nexport const withholdAt = 0.9\n\n/**\n * The `Classifier.confident` floor that is {@link withholdAt} for a boolean:\n * its confidence is its distance from even odds, doubled.\n */\nconst confidentAt = (withholdAt - 0.5) * 2\n\n/**\n * The most of one item's text a reading carries, in UTF-8 bytes; the head\n * kept.\n *\n * @category constants\n * @since 1.0.0-rc.0\n */\nexport const itemBytes = 1024\n\n/** The most of a flow's description an item carries, in UTF-8 bytes. */\nconst descriptionBytes = 512\n\nconst recall = \"the rest is not shown\"\n\n/** `text` within `limit` bytes, its head kept and the cut stated. */\nconst headKept = (text: string, limit: number): string => {\n  const whole = bytes.size(text)\n  if (whole <= limit) return text\n  // The notice names at most `whole` dropped bytes.\n  return elide.head(text, limit - bytes.size(`… [+${whole}b, ${recall}]`), recall)\n}\n\n/**\n * The reading: one question per item, `unnecessary_${index}`.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const reader = Judgement.perItem({\n  id: \"relevance/unnecessary\",\n  description: \"Decide which provided items an agent run does not need\",\n  context: Context,\n  item: Item,\n  questions: {\n    unnecessary: (i) =>\n      Classifier.boolean({\n        instructions:\n          `Is items[${i}] unnecessary for the task as stated? Read context.task, and context.query or context.recent when present.`,\n        criteria: {\n          true: \"nothing the task, context.query, or a step they plainly imply uses it, needs it, or must follow it\",\n          false: \"the task, context.query, or a step they plainly imply may use it, need it, or must follow it\"\n        }\n      })\n  }\n})\n\n/**\n * Jev's verdict on one item. `p` is the probability it is unnecessary.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Verdict {\n  readonly item: Item\n  /** `Digest.digest` of the item's whole text. */\n  readonly digest: string\n  readonly p: number\n  readonly withheld: boolean\n}\n\n/**\n * One reading: a verdict per item in input order, and the record of asking.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Reading {\n  readonly verdicts: ReadonlyArray<Verdict>\n  readonly asked: ReadonlyArray<Judgement.Asked>\n  /** Wall-clock milliseconds the reading took. */\n  readonly latencyMs: number\n  /** Token usage summed over every request, absent when none reported any. */\n  readonly usage?: Evaluator.Usage | undefined\n}\n\n/**\n * Asks Jev which of `items` the run does not need. Each item's text is sent\n * head-kept to {@link itemBytes}, and an item that was cut is never withheld.\n * No items ask nothing.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const judge = (context: Context, items: ReadonlyArray<Item>): Effect.Effect<Reading, Judgement.Unjudged> =>\n  Effect.gen(function*() {\n    const sent = items.map((item) => ({ ...item, text: headKept(item.text, itemBytes) }))\n    const [elapsed, read] = yield* reader.read(context, sent).pipe(Effect.timed)\n    const verdicts = items.map((item, index): Verdict => {\n      const answer = read.answers[index]!.unnecessary\n      return {\n        item,\n        digest: Digest.digest(item.text),\n        p: answer.probability,\n        withheld: bytes.size(item.text) <= itemBytes &&\n          Option.getOrElse(Classifier.confident(answer, confidentAt), () => false)\n      }\n    })\n    const usages = read.asked.flatMap((asked) => asked.usage === undefined ? [] : [asked.usage])\n    return {\n      verdicts,\n      asked: read.asked,\n      latencyMs: Math.round(Duration.toMillis(elapsed)),\n      ...(usages.length === 0 ? {} : {\n        usage: {\n          inputTokens: usages.reduce((sum, usage) => sum + usage.inputTokens, 0),\n          outputTokens: usages.reduce((sum, usage) => sum + usage.outputTokens, 0)\n        }\n      })\n    }\n  })\n\n/**\n * The `relevance-settled` row for a reading: ids and digests, never text.\n *\n * @category conversions\n * @since 1.0.0-rc.0\n */\nexport const settled = (\n  reading: Reading,\n  at: { readonly scope: string; readonly frame: number; readonly source: AgentEvent.RelevanceSettled[\"source\"] }\n): AgentEvent.RelevanceSettled => {\n  const row = (verdict: Verdict) => ({\n    kind: verdict.item.kind,\n    id: verdict.item.id,\n    digest: verdict.digest,\n    p: verdict.p\n  })\n  return new AgentEvent.RelevanceSettled({\n    eventType: AgentEvent.eventType.relevanceSettled,\n    scope: at.scope,\n    frame: at.frame,\n    source: at.source,\n    withholdAt,\n    kept: reading.verdicts.filter((verdict) => !verdict.withheld).map(row),\n    withheld: reading.verdicts.filter((verdict) => verdict.withheld).map(row),\n    latencyMs: reading.latencyMs,\n    ...(reading.usage === undefined ? {} : { usage: reading.usage })\n  })\n}\n\n/**\n * A catalog entry as an item: a `skill` when its body is markdown, else a\n * `flow`. Its description is untrusted data.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const flowItem = (descriptor: Descriptor.FlowDescriptor): Item => {\n  const description = untrustedData(\n    headKept(descriptor.description, descriptionBytes),\n    `description of ${descriptor.name}`\n  )\n  const capabilities = descriptor.capabilities.length === 0\n    ? \"\"\n    : `\\ncapabilities: ${[...descriptor.capabilities].sort().join(\",\")}`\n  return {\n    kind: descriptor.body._tag === \"Markdown\" ? \"skill\" : \"flow\",\n    id: descriptor.name,\n    text: `${descriptor.name}\\n${description}${capabilities}`\n  }\n}\n\n/**\n * One human-provided instruction file.\n *\n * @category schemas\n * @since 1.0.0-rc.0\n */\nexport const Document = Schema.Struct({ path: Schema.String, text: Schema.String })\n\n/**\n * The decoded form of {@link Document}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Document = typeof Document.Type\n\n/**\n * One piece of an instruction file, as {@link chunks} splits it.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Chunk {\n  /** `${path}#${n}`, `n` counting from 0 within the file. */\n  readonly id: string\n  readonly path: string\n  readonly text: string\n}\n\nconst heading = /^#{1,6}(?:[ \\t]|$)/\nconst listItem = /^(?:[-*+] |\\d+\\. )/\nconst fence = /^[ \\t]*```/\nconst blank = /^[ \\t]*\\r?$/\nconst indented = /^[ \\t]/\n\nconst split = (document: Document): ReadonlyArray<Chunk> => {\n  const pieces: Array<string> = []\n  let fenced = false\n  // A list item's chunk runs over its indented and wrapped lines, and ends at\n  // the first unindented line after a blank one.\n  let item = false\n  let afterBlank = false\n  for (const line of document.text.match(/[^\\n]*\\n|[^\\n]+$/g) ?? []) {\n    const bare = line.endsWith(\"\\n\") ? line.slice(0, -1) : line\n    const starts = !fenced && pieces.length > 0 && (heading.test(bare) || listItem.test(bare) ||\n      (item && afterBlank && !blank.test(bare) && !indented.test(bare)))\n    if (!fenced && (heading.test(bare) || listItem.test(bare))) item = listItem.test(bare)\n    else if (starts) item = false\n    if (starts || pieces.length === 0) pieces.push(line)\n    else pieces[pieces.length - 1] += line\n    if (fence.test(bare)) fenced = !fenced\n    afterBlank = !fenced && blank.test(bare)\n  }\n  return pieces.map((text, n) => ({ id: `${document.path}#${n}`, path: document.path, text }))\n}\n\n/**\n * Splits instruction files into the chunks a reading judges, in order.\n *\n * A chunk starts at each markdown heading and at each top-level list item,\n * whose indented and wrapped lines are its own. Every other line, blank lines\n * included, joins the chunk before it, and nothing inside a fence is split.\n * A file's chunks concatenate back to the file.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const chunks = (documents: ReadonlyArray<Document>): ReadonlyArray<Chunk> => documents.flatMap(split)\n\n/**\n * The project-instructions block of every chunk not in `withheld`, in order.\n * A file whose every chunk is withheld is left out, and `\"\"` is returned when\n * nothing is left.\n *\n * @category conversions\n * @since 1.0.0-rc.0\n */\nexport const render = (documents: ReadonlyArray<Document>, withheld: ReadonlySet<string>): string => {\n  const blocks = documents.flatMap((document) => {\n    const all = split(document)\n    const kept = all.filter((chunk) => !withheld.has(chunk.id))\n    if (all.length > 0 && kept.length === 0) return []\n    return [\n      `<project_instructions path=\"${document.path}\">\\n${\n        kept.map((chunk) => chunk.text).join(\"\")\n      }\\n</project_instructions>`\n    ]\n  })\n  return blocks.length === 0 ? \"\" : \"Project-specific instructions and guidelines:\\n\\n\" + blocks.join(\"\\n\\n\")\n}\n"]}