jev-agent-tools 0.1.4 → 0.2.0

package/dist/tools/ask-files.js

@@ -0,0 +1,217 @@
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { Type } from "@sinclair/typebox";
+import { collectAskFiles } from "../adapters/ask-files.js";
+import { canonicalPath } from "../adapters/canonical-path.js";
+import { shareGitInventory } from "../adapters/git-inventory.js";
+import { hostUsage } from "../adapters/usage.js";
+import { compileAsks, readAsks, reverseQuestions } from "../core/asks.js";
+import { checkIntegrity } from "../core/integrity.js";
+import { buildEnvelope } from "../core/output.js";
+import { interpolate } from "../describe.js";
+import { renderEnvelope } from "../render.js";
+import { ASK_FILES_DESCRIPTION } from "../texts/ask-files.js";
+import { NOT_CONFIGURED } from "../texts/configuration.js";
+import { asksParameter } from "./ask-schema.js";
+export const askFilesParameters = Type.Object({
+    paths: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+    asks: asksParameter("files"),
+    max_calls: Type.Optional(Type.Integer({ minimum: 0 })),
+}, { additionalProperties: false });
+export function createAskFilesTool(dependencies) {
+    const { host, runtime, exec: execute } = dependencies;
+    return {
+        name: "jev_ask_files",
+        label: "Jev ask files",
+        description: interpolate(ASK_FILES_DESCRIPTION, host.names),
+        parameters: askFilesParameters,
+        ...(host.isOmp
+            ? { approval: "read", loadMode: "essential" }
+            : {
+                promptSnippet: "Typed answers about many files from intents you declare, without reading them",
+                promptGuidelines: [
+                    "jev_ask_files: put every ask in one call; declare intents (verify, classify, rate, decide), never raw questions",
+                    "jev_ask_files: use it to decide what to read, then read only the files that matter",
+                ],
+            }),
+        async execute(_id, args, signal, _update, ctx) {
+            const client = dependencies.client;
+            const cwd = await canonicalPath(ctx.cwd);
+            const started = performance.now();
+            const exec = shareGitInventory(execute);
+            const totals = {
+                calls: 0,
+                questions: 0,
+                cacheHits: 0,
+                cacheRequests: 0,
+                inputTokens: 0,
+                costUsd: 0,
+            };
+            const records = [];
+            let skipped = [];
+            const finish = (input) => {
+                const envelope = buildEnvelope({
+                    ...input,
+                    yield: { ...totals, elapsedMs: performance.now() - started },
+                });
+                runtime.session.record(envelope);
+                runtime.guide.deliver(ctx);
+                const usage = hostUsage(host.isOmp, {
+                    inputTokens: totals.inputTokens,
+                    costUsd: totals.costUsd,
+                });
+                return {
+                    content: [{ type: "text", text: renderEnvelope(envelope) }],
+                    details: { files: records, skipped, envelope },
+                    ...usage,
+                };
+            };
+            if (!client)
+                return finish({ refusal: NOT_CONFIGURED });
+            const plan = compileAsks(args.asks, { surface: "files" });
+            if (!plan.ok)
+                return finish({ refusal: plan.error });
+            const collected = await collectAskFiles(cwd, args.paths, signal, exec);
+            if (!collected.ok)
+                return finish({ refusal: collected.error });
+            skipped = collected.skipped;
+            if (!collected.files.length && skipped.length)
+                return finish({
+                    refusal: `No readable evidence: ${skipped.join("; ")}`,
+                });
+            let sent = 0;
+            let budget;
+            const options = {
+                signal,
+                ...runtime.session.requestGate(),
+                beforeRequest: (count) => {
+                    if (args.max_calls !== undefined && sent >= args.max_calls) {
+                        budget = {
+                            kind: "max_calls",
+                            message: `max_calls=${args.max_calls} reached`,
+                        };
+                        return { ok: false, error: budget.message };
+                    }
+                    const admission = runtime.session.admit(count);
+                    if (!admission.ok) {
+                        budget = { kind: "session", message: admission.error };
+                        return admission;
+                    }
+                    sent++;
+                    return admission;
+                },
+                onUsage: (usage) => runtime.session.recordUsage(usage),
+            };
+            const accumulate = (result) => {
+                totals.calls += result.calls ?? 0;
+                totals.questions += result.questions ?? 0;
+                totals.cacheHits += result.cacheHits ?? 0;
+                totals.cacheRequests += result.cacheRequests ?? 0;
+                totals.inputTokens += result.usage?.inputTokens ?? 0;
+                totals.costUsd += result.usage?.costUsd ?? 0;
+            };
+            const rows = await Promise.all(collected.files.map(async (file) => {
+                const state = { path: file.path, content: file.content };
+                const integrity = checkIntegrity(state, plan.asks, [
+                    {
+                        ...file.identity,
+                        insertedPath: resolve(cwd, state.path),
+                        content: state.content,
+                        insertedSha256: createHash("sha256")
+                            .update(state.content)
+                            .digest("hex"),
+                    },
+                ]);
+                const initial = await client.judge(state, plan.questions, {
+                    ...options,
+                    groups: plan.groups,
+                });
+                accumulate(initial);
+                let reversed;
+                let reverseAnswers;
+                if (initial.ok) {
+                    const questions = reverseQuestions(plan, initial.answers);
+                    if (Object.keys(questions).length) {
+                        reversed = await client.judge(state, questions, options);
+                        accumulate(reversed);
+                        reverseAnswers = reversed.ok
+                            ? reversed.answers
+                            : Object.fromEntries(Object.keys(questions).map((id) => [
+                                id,
+                                {
+                                    type: "unjudged",
+                                    reason: reversed && !reversed.ok
+                                        ? reversed.error
+                                        : "reverse control failed",
+                                },
+                            ]));
+                    }
+                }
+                const answers = initial.ok
+                    ? readAsks(plan, initial.answers, reverseAnswers)
+                    : [];
+                return { file, initial, reversed, integrity, answers };
+            }));
+            const answers = [];
+            const unchecked = [];
+            const unjudged = [];
+            for (const row of rows) {
+                records.push({
+                    path: row.file.path,
+                    initial: row.initial,
+                    ...(row.reversed ? { reversed: row.reversed } : {}),
+                });
+                if (!row.initial.ok) {
+                    unchecked.push(row.file.path);
+                    unjudged.push({
+                        label: row.file.path,
+                        reason: row.initial.error,
+                        next: "read the file or retry",
+                    });
+                    continue;
+                }
+                if (Object.values(row.initial.answers).some((answer) => answer.type === "unjudged") ||
+                    (row.reversed &&
+                        (!row.reversed.ok ||
+                            Object.values(row.reversed.answers).some((answer) => answer.type === "unjudged"))))
+                    unchecked.push(row.file.path);
+                for (const answer of row.answers)
+                    answers.push({
+                        ...answer,
+                        label: `${row.file.path}  ${answer.label}`,
+                        ...(row.integrity.controls.length
+                            ? {
+                                band: "unsure",
+                                reason: row.integrity.controls
+                                    .map((control) => control.fact)
+                                    .join("; "),
+                            }
+                            : {}),
+                    });
+            }
+            return finish({
+                state: {
+                    files: collected.files.length,
+                    integrity: rows.some((row) => row.integrity.controls.length)
+                        ? "failed"
+                        : "ok",
+                    warnings: plan.warnings.map((warning) => warning.fact),
+                },
+                answers,
+                unjudged,
+                unchecked,
+                budget,
+                lines: skipped.length
+                    ? [{ type: "list", title: "skipped", items: skipped }]
+                    : [],
+                limitations: [
+                    ...plan.warnings,
+                    ...rows.flatMap((row) => [
+                        ...row.integrity.controls,
+                        ...row.integrity.notes,
+                    ]),
+                ],
+            });
+        },
+    };
+}

package/dist/tools/ask-schema.js

@@ -0,0 +1,70 @@
+import { Type } from "@sinclair/typebox";
+import { CHOICE_MAX_OPTIONS, SCORE_MAX_LEVELS, SCORE_MIN_LEVELS, } from "../constants.js";
+const criteria = Type.Record(Type.String(), Type.String(), {
+    minProperties: 1,
+    maxProperties: CHOICE_MAX_OPTIONS,
+});
+const question = Type.Union([
+    Type.Object({
+        type: Type.Literal("bool"),
+        instructions: Type.String({ minLength: 1 }),
+        criteria: Type.Optional(Type.Object({
+            true: Type.Optional(Type.String()),
+            false: Type.Optional(Type.String()),
+        }, { additionalProperties: false })),
+    }, { additionalProperties: false }),
+    Type.Object({
+        type: Type.Literal("choice"),
+        instructions: Type.String({ minLength: 1 }),
+        criteria,
+    }, { additionalProperties: false }),
+    Type.Object({
+        type: Type.Literal("score"),
+        instructions: Type.String({ minLength: 1 }),
+        criteria: Type.Array(Type.String(), {
+            minItems: SCORE_MIN_LEVELS,
+            maxItems: SCORE_MAX_LEVELS,
+        }),
+    }, { additionalProperties: false }),
+]);
+const fullAskSchema = Type.Union(createAskVariants({ about: Type.Optional(Type.String({ minLength: 1 })) }));
+const filesAskSchema = Type.Union(createAskVariants({}).slice(0, -1));
+export function askSchema(surface) {
+    return surface === "ask" ? fullAskSchema : filesAskSchema;
+}
+function createAskVariants(about) {
+    const variants = [
+        Type.Object({ intent: Type.Literal("free"), ...about, question }, { additionalProperties: false }),
+        Type.Object({ intent: Type.Literal("verify"), ...about, claims: criteria }, { additionalProperties: false }),
+        Type.Object({
+            intent: Type.Literal("classify"),
+            ...about,
+            categories: criteria,
+            pick: Type.Optional(Type.Union([Type.Literal("one"), Type.Literal("many")])),
+            by: Type.Optional(Type.String()),
+        }, { additionalProperties: false }),
+        Type.Object({ intent: Type.Literal("decide"), ...about, hypotheses: criteria }, { additionalProperties: false }),
+        Type.Object({
+            intent: Type.Literal("rate"),
+            ...about,
+            dimension: Type.String(),
+            levels: Type.Array(Type.String(), {
+                minItems: SCORE_MIN_LEVELS,
+                maxItems: SCORE_MAX_LEVELS,
+            }),
+        }, { additionalProperties: false }),
+        Type.Object({
+            intent: Type.Literal("locate"),
+            ...about,
+            target: Type.String(),
+            among: Type.Array(Type.String(), { minItems: 1 }),
+            count: Type.Optional(Type.Union([Type.Literal("one"), Type.Literal("many")])),
+            attribution: Type.Optional(Type.Boolean()),
+        }, { additionalProperties: false }),
+    ];
+    return variants;
+}
+export function asksParameter(surface) {
+    const ask = askSchema(surface);
+    return Type.Union([ask, Type.Array(ask, { minItems: 1 }), Type.String()]);
+}