jev-agent-tools 0.1.4 → 0.3.0

package/dist/tools/ask-files.js

@@ -0,0 +1,450 @@
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { Type } from "@sinclair/typebox";
+import { collectAskFiles } from "../adapters/ask-files.js";
+import { resolveEvidenceContext, withEvidenceContext, } from "../adapters/evidence-context.js";
+import { shareGitInventory } from "../adapters/git-inventory.js";
+import { hostUsage } from "../adapters/usage.js";
+import { STATE_MAX_CHARS } from "../constants.js";
+import { compileAsks, readAsks, reverseQuestions } from "../core/asks.js";
+import { checkIntegrity } from "../core/integrity.js";
+import { buildEnvelope } from "../core/output.js";
+import { answerItemFromInput, buildResultReport, contextFromEvidence, known, unknown, } from "../core/result-report.js";
+import { interpolate } from "../describe.js";
+import { renderResultReport } 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({
+    root: Type.Optional(Type.String()),
+    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 evidence = await resolveEvidenceContext(ctx.cwd, args.root, {
+                exec: execute,
+                signal,
+                origin: dependencies.evidenceOrigin,
+            });
+            const evidenceContext = evidence.context;
+            const cwd = evidence.ok ? evidence.cwd : evidenceContext.authority.path;
+            const started = performance.now();
+            const exec = shareGitInventory(execute);
+            const plan = compileAsks(args.asks, { surface: "files" });
+            let refusalCause = "invalid_arguments";
+            let collectedPaths;
+            let costKnown = true;
+            const reportItems = [];
+            const diagnostics = [];
+            const actions = [];
+            const auxiliary = {
+                controls: { fresh: 0, cache: 0, notJudged: 0, static: 0 },
+                passages: { fresh: 0, cache: 0, notJudged: 0 },
+            };
+            const diagnose = (cause, fact, scope, target) => {
+                const id = `diagnostic:${diagnostics.length}`, actionId = `action:${actions.length}`;
+                actions.push({
+                    id: actionId,
+                    code: cause === "invalid_root"
+                        ? "correct_context"
+                        : cause === "not_configured"
+                            ? "configure_client"
+                            : "inspect_native",
+                    target: target === undefined
+                        ? unknown("target not established")
+                        : known(target),
+                    scope,
+                    condition: "Only after correcting context or supplying materially new evidence",
+                    instruction: "Read the admitted files natively; do not repeat the unchanged Jev call.",
+                    repeatUnchanged: false,
+                });
+                diagnostics.push({
+                    id,
+                    cause,
+                    fact,
+                    target: target === undefined
+                        ? unknown("target not established")
+                        : known(target),
+                    origin: cause === "call_budget" || cause === "session_budget"
+                        ? "budget"
+                        : "collection",
+                    scope,
+                    effect: "blocking",
+                    material: true,
+                    omittedMembers: [],
+                    memberCount: known(0),
+                    actionIds: [actionId],
+                });
+                return { diagnosticIds: [id], actionIds: [actionId] };
+            };
+            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);
+                if (!reportItems.length && !diagnostics.length)
+                    diagnose(input.refusal ? refusalCause : "collection_empty", input.refusal ?? "No file-question results collected", { kind: "call" });
+                if (!reportItems.length && collectedPaths && plan.ok)
+                    for (const path of collectedPaths)
+                        for (const reading of plan.readings)
+                            reportItems.push({
+                                id: `${path}:${reading.id}`,
+                                kind: "file_question",
+                                label: `${path}  ${reading.label}`,
+                                groupId: `${path}:group:${plan.groups.findIndex((group) => group.includes(reading.id))}`,
+                                evidence: [
+                                    {
+                                        target: path,
+                                        canonicalPath: known(resolve(cwd, path)),
+                                        aliases: [],
+                                        side: "current",
+                                        revision: unknown("working tree evidence"),
+                                    },
+                                ],
+                                diagnosticIds: diagnostics.map((diagnostic) => diagnostic.id),
+                                actionIds: actions.map((action) => action.id),
+                                treatment: "not_judged",
+                                source: "none",
+                            });
+                for (const limitation of input.limitations ?? []) {
+                    diagnose("evidence_limit", limitation.fact, { kind: "call" }, limitation.path);
+                    const diagnostic = diagnostics.at(-1);
+                    if (diagnostic)
+                        diagnostic.effect = "reservation";
+                }
+                const report = buildResultReport({
+                    tool: "jev_ask_files",
+                    context: contextFromEvidence(evidenceContext, {
+                        inventories: collectedPaths
+                            ? [
+                                {
+                                    id: "files",
+                                    kind: "repository",
+                                    rules: [
+                                        "Requested paths expanded with admission and pruning",
+                                    ],
+                                    restrictions: args.paths,
+                                    discovered: unknown("collector does not expose pre-pruning candidate count"),
+                                    considered: known(collectedPaths.length),
+                                    scopeRestricted: true,
+                                    criteria: [],
+                                },
+                            ]
+                            : [],
+                    }),
+                    items: reportItems,
+                    diagnostics,
+                    actions,
+                    metrics: {
+                        ...totals,
+                        costUsd: costKnown && collectedPaths ? totals.costUsd : undefined,
+                        elapsedMs: performance.now() - started,
+                    },
+                    auxiliary,
+                    total: collectedPaths && plan.ok
+                        ? known(collectedPaths.length * plan.readings.length)
+                        : unknown("file-question inventory not collected"),
+                    refused: !!input.refusal && refusalCause !== "not_configured",
+                });
+                const usage = hostUsage(host.isOmp, {
+                    inputTokens: totals.inputTokens,
+                    costUsd: totals.costUsd,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: renderResultReport(report, { details: envelope }),
+                        },
+                    ],
+                    details: {
+                        files: records,
+                        skipped,
+                        envelope,
+                        evidenceContext,
+                        result: report,
+                    },
+                    ...usage,
+                };
+            };
+            if (!evidence.ok) {
+                refusalCause = evidence.cause ?? "invalid_root";
+                return finish({ refusal: evidence.error });
+            }
+            if (!plan.ok)
+                return finish({ refusal: plan.error });
+            if (!client) {
+                refusalCause = "not_configured";
+                return finish({ refusal: NOT_CONFIGURED });
+            }
+            const collected = await collectAskFiles(cwd, args.paths, signal, exec);
+            if (!collected.ok) {
+                refusalCause = collected.cause ?? "file_unavailable";
+                return finish({ refusal: collected.error });
+            }
+            collectedPaths = collected.files.map((file) => file.path);
+            skipped = collected.skipped;
+            for (const skippedPath of skipped)
+                diagnose(collected.secret.includes(skippedPath)
+                    ? "secret_pattern"
+                    : "collection_omitted", skippedPath, { kind: "inventory", inventoryIds: ["files"] });
+            if (!collected.files.length && skipped.length)
+                return finish({
+                    refusal: `No readable evidence: ${skipped.join("; ")}`,
+                });
+            const states = collected.files.map((file) => ({
+                file,
+                state: withEvidenceContext({ path: file.path, content: file.content }, evidenceContext),
+            }));
+            if (states.some(({ state }) => JSON.stringify(state).length > STATE_MAX_CHARS)) {
+                refusalCause = "evidence_too_large";
+                return finish({
+                    refusal: `required evidence exceeds STATE_MAX_CHARS=${STATE_MAX_CHARS}`,
+                });
+            }
+            let sent = 0;
+            let budget;
+            const options = {
+                signal,
+                ...runtime.session.requestGate(),
+                admissionCause: () => budget?.kind === "session"
+                    ? "session_budget"
+                    : "call_budget",
+                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;
+                if (!result.usage && result.calls !== 0)
+                    costKnown = false;
+            };
+            const rows = await Promise.all(states.map(async ({ file, state }) => {
+                const integrity = checkIntegrity(state, plan.asks, [
+                    {
+                        ...file.identity,
+                        insertedPath: resolve(cwd, file.path),
+                        content: file.content,
+                        insertedSha256: createHash("sha256")
+                            .update(file.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) {
+                const readings = plan.readings;
+                for (const [index, reading] of readings.entries()) {
+                    const groupId = `${row.file.path}:group:${plan.groups.findIndex((group) => group.includes(reading.id))}`;
+                    const common = {
+                        id: `${row.file.path}:${reading.id}`,
+                        kind: "file_question",
+                        label: `${row.file.path}  ${reading.label}`,
+                        groupId,
+                        evidence: [
+                            {
+                                target: row.file.path,
+                                canonicalPath: known(resolve(cwd, row.file.path)),
+                                aliases: [],
+                                side: "current",
+                                revision: unknown("working tree evidence"),
+                            },
+                        ],
+                        diagnosticIds: [],
+                        actionIds: [],
+                    };
+                    const answer = row.answers[index];
+                    if (answer &&
+                        !answer.unjudged &&
+                        (answer.source || answer.answer?.source))
+                        reportItems.push(answerItemFromInput(common, row.integrity.controls.length
+                            ? {
+                                ...answer,
+                                band: "unsure",
+                                reason: row.integrity.controls
+                                    .map((control) => control.fact)
+                                    .join("; "),
+                            }
+                            : answer));
+                    else {
+                        const raw = row.initial.ok
+                            ? row.initial.answers[reading.id]
+                            : undefined;
+                        const cause = raw?.type === "unjudged" ? raw.cause : row.initial.failureCause;
+                        const links = diagnose(cause ??
+                            (budget
+                                ? budget.kind === "session"
+                                    ? "session_budget"
+                                    : "call_budget"
+                                : "control_failure"), answer?.reason ??
+                            (row.initial.ok
+                                ? "Required group incomplete or response provenance not established"
+                                : row.initial.error), { kind: "group", groupIds: [groupId] }, row.file.path);
+                        reportItems.push({
+                            ...common,
+                            ...links,
+                            treatment: "not_judged",
+                            source: "none",
+                        });
+                    }
+                    for (const id of [
+                        reading.twin,
+                        ...Object.values(reading.controls ?? {}),
+                    ].filter((id) => !!id)) {
+                        const control = row.initial.ok
+                            ? row.initial.answers[id]
+                            : undefined;
+                        if (control && control.type !== "unjudged" && control.source)
+                            auxiliary.controls[control.source]++;
+                        else
+                            auxiliary.controls.notJudged++;
+                    }
+                    const reverse = row.reversed?.ok
+                        ? row.reversed.answers[reading.id]
+                        : undefined;
+                    if (row.reversed) {
+                        if (reverse && reverse.type !== "unjudged" && reverse.source)
+                            auxiliary.controls[reverse.source]++;
+                        else
+                            auxiliary.controls.notJudged++;
+                    }
+                }
+                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 supplied file natively; a new Jev call needs materially changed evidence or recovered service",
+                    });
+                    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()]);
+}