@bobobowis/jev-kit 0.0.0-stage → 0.1.0

package/dist/core/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * TypeSafe System One API types — the exact wire contract for Jev.
+ *
+ * One endpoint: POST https://api.typesafe.ai/v1/systemone
+ * You send a `state` and a map of typed `questions`; you get back one typed
+ * `answer` per question, keyed by the IDs you chose.
+ */
+/** The content being evaluated. A plain string, or structured data. */
+export type State = string | Record<string, unknown> | unknown[];
+/**
+ * What to ask about the state. Can be a plain string, or a structured object
+ * that puts the question in one field and the data it refers to in others.
+ */
+export type Instructions = string | Record<string, unknown>;
+/** Optional clarification of what yes and no mean. */
+export interface NoulCriteria {
+    true?: string;
+    false?: string;
+}
+/** A map of option -> rubric description. Use null when an option needs no detail. Max 255 options. */
+export type ChoiceCriteria = Record<string, string | null>;
+/** An ordered array of level descriptions, low to high. 2-10 levels. */
+export type ScoreCriteria = string[];
+export interface NoulQuestion {
+    type: "noul";
+    instructions: Instructions;
+    criteria?: NoulCriteria;
+}
+export interface ChoiceQuestion {
+    type: "choice";
+    instructions: Instructions;
+    criteria: ChoiceCriteria;
+}
+export interface ScoreQuestion {
+    type: "score";
+    instructions: Instructions;
+    criteria: ScoreCriteria;
+}
+export type Question = NoulQuestion | ChoiceQuestion | ScoreQuestion;
+/** Question IDs are for your code. They are not sent to the model and are not used in inference. */
+export type Questions = Record<string, Question>;
+export interface NoulAnswer {
+    type: "noul";
+    /** The probability the answer is yes. 0 = strong no, 1 = strong yes, 0.5 = uncertain. */
+    noul: number;
+}
+export interface ChoiceAnswer {
+    type: "choice";
+    /** The highest-probability option. Always one you defined. */
+    choice: string;
+    /** Every option mapped to its probability. Floats that sum to 1. */
+    probabilities: Record<string, number>;
+    /** How certain the model is, derived from the shape of the distribution. */
+    confidence: number;
+}
+export interface ScoreAnswer {
+    type: "score";
+    /** Probability-weighted position along the levels. Can land between levels. */
+    score: number;
+    /** Each level number mapped back to its description. */
+    legend: Record<string, string>;
+    /** Each level mapped to its probability. Floats that sum to 1. */
+    probabilities: Record<string, number>;
+    confidence: number;
+}
+export type Answer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
+export interface SystemOneRequest {
+    /** Defaults to "jev-latest". */
+    model?: string;
+    state: State;
+    questions: Questions;
+}
+export interface SystemOneUsage {
+    input_tokens: number;
+    output_tokens: number;
+    /** Provider-reported USD cost. Only finite, nonnegative numbers are trusted. */
+    cost?: unknown;
+    [key: string]: unknown;
+}
+export interface SystemOneResponse {
+    /** The versioned model that answered. Log it. */
+    model: string;
+    answers: Record<string, Answer>;
+    usage: SystemOneUsage;
+    /** Provider extensions are retained, not stripped during validation. */
+    [key: string]: unknown;
+}
+/** Client-side validation limits, mirrored from the published API. */
+export declare const LIMITS: {
+    readonly MAX_CHOICE_OPTIONS: 255;
+    readonly MIN_SCORE_LEVELS: 2;
+    readonly MAX_SCORE_LEVELS: 10;
+    /** Approximate shared token budget for state + all questions. */
+    readonly TOTAL_TOKEN_BUDGET: 64000;
+};
+export declare class QuestionValidationError extends Error {
+    constructor(message: string);
+}
+/** Validate runtime input as well as TypeScript callers, before any transport. */
+export declare function validateRequest(request: unknown): asserts request is SystemOneRequest;
+/** Validate a request's question shapes before it is ever sent. */
+export declare function validateQuestions(questions: unknown): asserts questions is Questions;

package/dist/core/types.js

@@ -0,0 +1,82 @@
+/**
+ * TypeSafe System One API types — the exact wire contract for Jev.
+ *
+ * One endpoint: POST https://api.typesafe.ai/v1/systemone
+ * You send a `state` and a map of typed `questions`; you get back one typed
+ * `answer` per question, keyed by the IDs you chose.
+ */
+/** Client-side validation limits, mirrored from the published API. */
+export const LIMITS = {
+    MAX_CHOICE_OPTIONS: 255,
+    MIN_SCORE_LEVELS: 2,
+    MAX_SCORE_LEVELS: 10,
+    /** Approximate shared token budget for state + all questions. */
+    TOTAL_TOKEN_BUDGET: 64_000,
+};
+export class QuestionValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "QuestionValidationError";
+    }
+}
+const isRecord = (value) => value !== null && typeof value === "object" &&
+    (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+/** Validate runtime input as well as TypeScript callers, before any transport. */
+export function validateRequest(request) {
+    if (!isRecord(request))
+        throw new QuestionValidationError("Expected a request object.");
+    if (typeof request.state !== "string" && !isRecord(request.state) && !Array.isArray(request.state)) {
+        throw new QuestionValidationError("State must be a string, object, or array.");
+    }
+    if (request.model !== undefined && (typeof request.model !== "string" || !request.model.trim())) {
+        throw new QuestionValidationError("Model must be a nonblank string.");
+    }
+    validateQuestions(request.questions);
+}
+/** Validate a request's question shapes before it is ever sent. */
+export function validateQuestions(questions) {
+    if (!isRecord(questions) || Object.keys(questions).length === 0) {
+        throw new QuestionValidationError("Questions must be a nonempty object.");
+    }
+    for (const [id, q] of Object.entries(questions)) {
+        if (!isRecord(q))
+            throw new QuestionValidationError(`Question "${id}" must be an object.`);
+        if (q.type !== "noul" && q.type !== "choice" && q.type !== "score") {
+            throw new QuestionValidationError(`Question "${id}" has a missing or unknown type.`);
+        }
+        if (typeof q.instructions === "string" ? !q.instructions.trim() : !isRecord(q.instructions)) {
+            throw new QuestionValidationError(`Question "${id}" needs nonblank string or object instructions.`);
+        }
+        if (q.type === "noul" && q.criteria !== undefined) {
+            if (!isRecord(q.criteria) || Object.entries(q.criteria).some(([key, value]) => !["true", "false"].includes(key) || (value !== undefined && typeof value !== "string"))) {
+                throw new QuestionValidationError(`Noul "${id}" criteria must map true/false to descriptions.`);
+            }
+        }
+        if (q.type === "choice") {
+            if (!isRecord(q.criteria)) {
+                throw new QuestionValidationError(`Choice "${id}" criteria must be an object.`);
+            }
+            const options = Object.keys(q.criteria);
+            if (options.length === 0) {
+                throw new QuestionValidationError(`Choice "${id}" has no options.`);
+            }
+            if (options.length > LIMITS.MAX_CHOICE_OPTIONS) {
+                throw new QuestionValidationError(`Choice "${id}" has ${options.length} options; the maximum is ${LIMITS.MAX_CHOICE_OPTIONS}.`);
+            }
+            if (Object.values(q.criteria).some((value) => value !== null && typeof value !== "string")) {
+                throw new QuestionValidationError(`Choice "${id}" descriptions must be strings or null.`);
+            }
+        }
+        if (q.type === "score") {
+            if (!Array.isArray(q.criteria)) {
+                throw new QuestionValidationError(`Score "${id}" criteria must be an array.`);
+            }
+            if (q.criteria.length < LIMITS.MIN_SCORE_LEVELS || q.criteria.length > LIMITS.MAX_SCORE_LEVELS) {
+                throw new QuestionValidationError(`Score "${id}" must have between ${LIMITS.MIN_SCORE_LEVELS} and ${LIMITS.MAX_SCORE_LEVELS} levels; got ${q.criteria.length}.`);
+            }
+            if (q.criteria.some((level) => typeof level !== "string" || !level.trim())) {
+                throw new QuestionValidationError(`Score "${id}" levels must be nonblank strings.`);
+            }
+        }
+    }
+}

package/dist/events/index.d.ts

@@ -0,0 +1,44 @@
+import { type JevClient } from "../core/client.ts";
+import { type Answer, type Questions, type State, type SystemOneUsage } from "../core/types.ts";
+export declare const EVENT_PREFIX = "JEV_EVENT ";
+export interface JevEventLine {
+    kind: string;
+    at: number;
+    harness: string;
+    [field: string]: unknown;
+}
+export interface Reporter {
+    readonly harness: string;
+    /** Where events go: the file path, "stderr", or "off". */
+    readonly target: string;
+    report(kind: string, payload?: Record<string, unknown>): void;
+}
+export interface ReporterOptions {
+    /** Names who produced the events: pi, claude, codex, mcp, cli, ... */
+    harness: string;
+    /** Defaults to JEV_EVENT_DIR. */
+    dir?: string;
+    /** No event directory means no events, instead of stderr lines. */
+    quiet?: boolean;
+    /** Also called with every event, for a harness's own record (pi session entries). Errors are ignored. */
+    onEvent?: (kind: string, payload: Record<string, unknown>) => void;
+    stderr?: {
+        write(chunk: string): unknown;
+    };
+}
+export declare function createReporter(opts: ReporterOptions): Reporter;
+export interface Decision {
+    answers: Record<string, Answer>;
+    usage: SystemOneUsage;
+    model: string;
+    ms: number;
+}
+/** One Jev call that validates, calls, times, and reports. `source` names who asked, a hook or a tool. */
+export type Decider = (source: string, state: State, questions: Questions, extra?: Record<string, unknown>) => Promise<Decision>;
+/**
+ * `extra` must not use the keys the report already sets: source, state, questions, answers, usage, model, ms.
+ * The client defaults to the shared, auto-selected one.
+ */
+export declare function createDecider(reporter: Reporter, client?: () => Pick<JevClient, "systemOne">): Decider;
+/** Parse one `JEV_EVENT ` stderr line, or null when the line is something else. */
+export declare function parseEventLine(line: string): JevEventLine | null;

package/dist/events/index.js

@@ -0,0 +1,77 @@
+/**
+ * The event channel every tool, hook, and CLI run reports on.
+ *
+ * With JEV_EVENT_DIR set, each process appends JSON lines to its own file, `<dir>/<harness>-<pid>.jsonl`,
+ * so no two processes share a file and large events never tear. Without it, events go to stderr as
+ * `JEV_EVENT {json}` lines, unless the reporter is quiet (the general CLI keeps stderr readable).
+ * A failed write falls back to stderr and never fails the caller.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { sharedJev } from "../core/client.js";
+import { validateQuestions } from "../core/types.js";
+export const EVENT_PREFIX = "JEV_EVENT ";
+export function createReporter(opts) {
+    const stderr = opts.stderr ?? process.stderr;
+    const dir = opts.dir ?? process.env.JEV_EVENT_DIR?.trim() ?? "";
+    let file = dir ? join(dir, `${opts.harness}-${process.pid}.jsonl`) : "";
+    let ready = false;
+    const toStderr = (line) => {
+        try {
+            stderr.write(EVENT_PREFIX + line + "\n");
+        }
+        catch { /* nowhere left to report */ }
+    };
+    return {
+        harness: opts.harness,
+        get target() { return file || (opts.quiet ? "off" : "stderr"); },
+        report(kind, payload = {}) {
+            const line = JSON.stringify({ kind, at: Date.now(), harness: opts.harness, ...payload });
+            try {
+                opts.onEvent?.(kind, payload);
+            }
+            catch { /* optional record */ }
+            if (file) {
+                try {
+                    if (!ready) {
+                        mkdirSync(dir, { recursive: true });
+                        ready = true;
+                    }
+                    appendFileSync(file, line + "\n");
+                    return;
+                }
+                catch (err) {
+                    file = "";
+                    toStderr(JSON.stringify({ kind: "error", at: Date.now(), harness: opts.harness, hook: "events", message: `cannot write ${dir}: ${err.message}; reporting on stderr` }));
+                }
+            }
+            if (!opts.quiet)
+                toStderr(line);
+        },
+    };
+}
+/**
+ * `extra` must not use the keys the report already sets: source, state, questions, answers, usage, model, ms.
+ * The client defaults to the shared, auto-selected one.
+ */
+export function createDecider(reporter, client = sharedJev) {
+    return async (source, state, questions, extra = {}) => {
+        validateQuestions(questions);
+        const started = performance.now();
+        const result = await client().systemOne(state, questions);
+        const out = { answers: result.answers, usage: result.usage, model: result.model, ms: Math.round(performance.now() - started) };
+        reporter.report("jev", { source, state, questions, answers: out.answers, usage: out.usage, model: out.model, ms: out.ms, ...extra });
+        return out;
+    };
+}
+/** Parse one `JEV_EVENT ` stderr line, or null when the line is something else. */
+export function parseEventLine(line) {
+    if (!line.startsWith(EVENT_PREFIX))
+        return null;
+    try {
+        return JSON.parse(line.slice(EVENT_PREFIX.length));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/files/ask-file-bool.d.ts

@@ -0,0 +1,12 @@
+import type { Decide } from "./decide.ts";
+export interface FileBool {
+    path: string;
+    answer: boolean;
+    noul: number;
+    usage?: unknown;
+}
+/** A: the question is written against `content`; the tool description says so. */
+export declare function askFileBool(path: string, question: string, cwd: string, criteria?: {
+    yes?: string;
+    no?: string;
+}, decide?: Decide): Promise<FileBool>;

package/dist/files/ask-file-bool.js

@@ -0,0 +1,15 @@
+/**
+ * Level 8, option A: ask_jev_file_bool.
+ * One file, one yes or no question, flat parameters. The agent asks "does src/auth/session.ts validate tokens?" and gets a Noul back without the file ever entering its context.
+ */
+import { jev } from "../core/client.js";
+import { noul } from "../core/helpers.js";
+import { readFileState } from "./read-state.js";
+/** A: the question is written against `content`; the tool description says so. */
+export async function askFileBool(path, question, cwd, criteria = {}, decide = (s, q) => jev.systemOne(s, q)) {
+    const state = await readFileState(path, cwd);
+    const questions = { answer: noul(question, criteria.yes || criteria.no ? { true: criteria.yes, false: criteria.no } : undefined) };
+    const { answers, usage } = await decide(state, questions);
+    const a = answers.answer;
+    return { path, answer: a.noul > 0.5, noul: a.noul, usage };
+}

package/dist/files/ask-file-choice.d.ts

@@ -0,0 +1,10 @@
+import type { Decide } from "./decide.ts";
+export interface FileChoice {
+    path: string;
+    choice: string;
+    confidence: number;
+    probabilities: Record<string, number>;
+    usage?: unknown;
+}
+/** B: options are name to description. An `other` entry is added when the agent leaves none, so the model has an exit. */
+export declare function askFileChoice(path: string, question: string, options: Record<string, string>, cwd: string, decide?: Decide): Promise<FileChoice>;

package/dist/files/ask-file-choice.js

@@ -0,0 +1,17 @@
+/**
+ * Level 8, option B: ask_jev_file_choice.
+ * One file, one pick from options the agent names. "Which layer is this file?" comes back as one of the agent's own keys, with the whole distribution.
+ */
+import { jev } from "../core/client.js";
+import { choice } from "../core/helpers.js";
+import { readFileState } from "./read-state.js";
+/** B: options are name to description. An `other` entry is added when the agent leaves none, so the model has an exit. */
+export async function askFileChoice(path, question, options, cwd, decide = (s, q) => jev.systemOne(s, q)) {
+    const state = await readFileState(path, cwd);
+    const criteria = { ...options };
+    if (!("other" in criteria) && !("none" in criteria) && !("none_of_the_above" in criteria))
+        criteria.other = "None of the above";
+    const { answers, usage } = await decide(state, { answer: choice(question, criteria) });
+    const a = answers.answer;
+    return { path, choice: a.choice, confidence: a.confidence, probabilities: a.probabilities, usage };
+}

package/dist/files/ask-file-score.d.ts

@@ -0,0 +1,12 @@
+import type { Decide } from "./decide.ts";
+export interface FileScore {
+    path: string;
+    score: number;
+    top: number;
+    nearest: string;
+    confidence: number;
+    legend: Record<string, string>;
+    usage?: unknown;
+}
+/** C: levels are situations, not degrees. The nearest level's text comes back so the agent can quote it. */
+export declare function askFileScore(path: string, question: string, levels: string[], cwd: string, decide?: Decide): Promise<FileScore>;

package/dist/files/ask-file-score.js

@@ -0,0 +1,15 @@
+/**
+ * Level 8, option C: ask_jev_file_score.
+ * One file, one scale the agent writes, low to high. "How risky is a refactor of this file?" comes back as a position on the agent's own levels.
+ */
+import { jev } from "../core/client.js";
+import { score } from "../core/helpers.js";
+import { readFileState } from "./read-state.js";
+/** C: levels are situations, not degrees. The nearest level's text comes back so the agent can quote it. */
+export async function askFileScore(path, question, levels, cwd, decide = (s, q) => jev.systemOne(s, q)) {
+    const state = await readFileState(path, cwd);
+    const { answers, usage } = await decide(state, { answer: score(question, levels) });
+    const a = answers.answer;
+    const top = levels.length - 1;
+    return { path, score: a.score, top, nearest: a.legend[String(Math.round(a.score))] ?? "", confidence: a.confidence, legend: a.legend, usage };
+}

package/dist/files/ask-files.d.ts

@@ -0,0 +1,23 @@
+import { type Answer, type Questions } from "../core/types.ts";
+import type { Decide } from "./decide.ts";
+import { type Skipped } from "./prune.ts";
+export interface FileAnswers {
+    path: string;
+    answers: Record<string, Answer>;
+    usage?: unknown;
+}
+export interface AskFilesResult {
+    results: FileAnswers[];
+    skipped: Skipped[];
+    calls: number;
+}
+/** The agent writes Jev's question shape as JSON. Malformed blocks fail here, with the reason, before any file is read. */
+export declare function parseQuestions(questionsJson: string): Questions;
+/** Run `fn` over `items` with at most `limit` in flight. Results keep the input order. */
+export declare function parallel<T, R>(items: T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]>;
+export declare function askFiles(patterns: string[], questionsJson: string, cwd: string, opts?: {
+    recursive?: boolean;
+    concurrency?: number;
+    decide?: Decide;
+    onResult?: (r: FileAnswers) => void;
+}): Promise<AskFilesResult>;

package/dist/files/ask-files.js

@@ -0,0 +1,56 @@
+/**
+ * Level 9, option A: ask_jev_files.
+ * The same questions, raw Jev question JSON, over many files. One call per file, every question in each, all in parallel with a cap. Answers come back per path. No file enters the agent's context.
+ */
+import { jev } from "../core/client.js";
+import { validateQuestions } from "../core/types.js";
+import { FileStateError, readFileState } from "./read-state.js";
+import { expandPatterns, pruneFiles } from "./prune.js";
+/** The agent writes Jev's question shape as JSON. Malformed blocks fail here, with the reason, before any file is read. */
+export function parseQuestions(questionsJson) {
+    let parsed;
+    try {
+        parsed = JSON.parse(questionsJson);
+    }
+    catch (err) {
+        throw new Error(`questions_json is not valid JSON: ${err.message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("questions_json must be an object keyed by question id");
+    validateQuestions(parsed);
+    return parsed;
+}
+/** Run `fn` over `items` with at most `limit` in flight. Results keep the input order. */
+export async function parallel(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await fn(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return out;
+}
+export async function askFiles(patterns, questionsJson, cwd, opts = {}) {
+    const questions = parseQuestions(questionsJson);
+    const decide = opts.decide ?? ((s, q) => jev.systemOne(s, q));
+    const expanded = await expandPatterns(patterns, cwd, opts.recursive ?? false);
+    const { files, skipped } = await pruneFiles(expanded, cwd);
+    const results = [];
+    await parallel(files, opts.concurrency ?? 16, async (path) => {
+        try {
+            const state = await readFileState(path, cwd);
+            const { answers, usage } = await decide(state, questions);
+            const r = { path, answers, usage };
+            results.push(r);
+            opts.onResult?.(r);
+        }
+        catch (err) {
+            skipped.push({ path, reason: err instanceof FileStateError ? err.message : `call failed: ${err?.message ?? err}` });
+        }
+    });
+    results.sort((a, b) => a.path.localeCompare(b.path));
+    return { results, skipped, calls: results.length };
+}

package/dist/files/ask.d.ts

@@ -0,0 +1,12 @@
+import type { Answer, State } from "../core/types.ts";
+import type { Decide } from "./decide.ts";
+export interface AskResult {
+    answers: Record<string, Answer>;
+    usage?: unknown;
+    model?: string;
+    state_summary?: unknown;
+}
+/** A JSON string becomes structured state; anything else is sent as the string it is. */
+export declare function parseState(raw: string | Record<string, unknown>): State;
+/** A: any state, any questions, one call. Empty state is refused; Jev cannot judge nothing. */
+export declare function askJev(rawState: string | Record<string, unknown>, questionsJson: string, decide?: Decide): Promise<AskResult>;

package/dist/files/ask.js

@@ -0,0 +1,28 @@
+/**
+ * Level 10, option A: ask_jev on any content.
+ * The general form. The agent passes its own state, paths for code to read, a command for code to run, and its question block. Code assembles one state, validates, and makes one call. The agent never receives the files or the output, only the answers.
+ */
+import { jev } from "../core/client.js";
+import { parseQuestions } from "./ask-files.js";
+/** A JSON string becomes structured state; anything else is sent as the string it is. */
+export function parseState(raw) {
+    if (typeof raw !== "string")
+        return raw;
+    const t = raw.trim();
+    if ((t.startsWith("{") && t.endsWith("}")) || (t.startsWith("[") && t.endsWith("]"))) {
+        try {
+            return JSON.parse(t);
+        }
+        catch { /* not JSON after all, send the text */ }
+    }
+    return raw;
+}
+/** A: any state, any questions, one call. Empty state is refused; Jev cannot judge nothing. */
+export async function askJev(rawState, questionsJson, decide = (s, q) => jev.systemOne(s, q)) {
+    const state = parseState(rawState);
+    if (typeof state === "string" ? !state.trim() : !state || Object.keys(state).length === 0)
+        throw new Error("state is empty");
+    const questions = parseQuestions(questionsJson);
+    const { answers, usage, model } = await decide(state, questions);
+    return { answers, usage, model };
+}

package/dist/files/assemble.d.ts

@@ -0,0 +1,52 @@
+import { type Skipped } from "./prune.ts";
+/** Roughly four characters per token, the same estimate the file reader uses. */
+export declare const tokensOf: (text: string) => number;
+/** Leave room for the questions inside Jev's shared budget. */
+export declare const STATE_TOKEN_BUDGET: number;
+/** A single situation, not a corpus. Many files belong to ask_jev_files. */
+export declare const MAX_FILES_PER_CALL = 20;
+/** The agent's own note is for context, not for pasting content that code could fetch. */
+export declare const MAX_OWN_STATE_CHARS = 8000;
+export interface CommandOutput {
+    command: string;
+    exit_code: number | null;
+    stdout: string;
+    stderr: string;
+}
+export type RunCommand = (command: string, cwd: string) => Promise<CommandOutput>;
+export interface AssembleInput {
+    state?: string | Record<string, unknown>;
+    paths?: string[];
+    command?: string;
+}
+export interface Assembled {
+    state: Record<string, unknown>;
+    summary: {
+        own_fields: string[];
+        files: string[];
+        output: string | null;
+        skipped: Skipped[];
+        tokens: number;
+    };
+}
+interface Part {
+    name: string;
+    tokens: number;
+    kind: "own" | "file" | "output";
+}
+export declare class AskStateError extends Error {
+    constructor(message: string);
+}
+/**
+ * Greedy first fit, largest first. Returns groups whose token sums fit the budget, so the error
+ * can say "call 1: these, call 2: those" instead of "too big".
+ */
+export declare function suggestSplit(parts: Part[], budget: number): Part[][];
+/** The message the agent reads when one call cannot hold the situation. */
+export declare function overflowMessage(parts: Part[], budget: number): string;
+/**
+ * Build the state. Own state first, then files, then the command's output. Nothing is truncated:
+ * over the file cap or the token budget, the call is refused with a message that says how to split.
+ */
+export declare function assembleState(input: AssembleInput, cwd: string, run: RunCommand): Promise<Assembled>;
+export {};