jev-lens 0.5.0

package/dist/presend.d.ts

@@ -0,0 +1,151 @@
+import type { TypeSafeClient } from "@typesafe-ai/sdk";
+import type { Config } from "./config.ts";
+import { type Block, type Candidates, type View, type ViewKind } from "./views.ts";
+export interface PresendState {
+    task: {
+        first_user_request: string;
+        latest_user_message: string;
+    };
+    agent: {
+        text_before_call: string;
+        tool: string;
+        args: string;
+    };
+    result: {
+        kind: string;
+        is_error: boolean;
+        total_lines: number;
+        total_chars: number;
+    };
+    views: Record<string, {
+        lines: number;
+        chars: number;
+        preview: string;
+    }>;
+}
+export interface PresendDecision {
+    view: ViewKind;
+    needsFull: number;
+    probabilities: Record<string, number>;
+    confidence: number;
+}
+export interface PresendClassifier {
+    choose(state: PresendState, kinds: ViewKind[], signal?: AbortSignal): Promise<{
+        choice: ViewKind;
+        probabilities: Record<string, number>;
+        confidence: number;
+        needsFull: number;
+    }>;
+    /** Second step: for each block, P(the agent will need its body). */
+    expand(state: ExpandState, signal?: AbortSignal): Promise<number[]>;
+}
+export interface ExpandState {
+    task: PresendState["task"];
+    agent: PresendState["agent"];
+    file: {
+        kind: string;
+        total_lines: number;
+    };
+    blocks: {
+        index: number;
+        signature: string;
+        lines: string;
+        preview: string;
+    }[];
+}
+export declare function buildExpandState(base: PresendState, blocks: Block[], text: string): ExpandState;
+export declare function expandQuestions(n: number, prompts?: PromptVariant, kind?: string): Record<string, {
+    type: "noul";
+    instructions: string;
+    criteria: {
+        true: string;
+        false: string;
+    };
+}>;
+export declare function buildPresendState(cfg: Pick<Config, "stateHeadChars">, input: {
+    firstUser: string;
+    latestUser: string;
+    agentText: string;
+    toolName: string;
+    args: unknown;
+    isError: boolean;
+    cands: Candidates;
+    totalLines: number;
+    totalChars: number;
+}): PresendState;
+/** Everything the autoresearch loop may vary: prompt texts and view descriptions. Defaults = current best. */
+export interface PromptVariant {
+    viewInstructions: string;
+    viewDescriptions: Partial<Record<ViewKind, string>>;
+    needsFullInstructions: string;
+    needsFullTrue: string;
+    needsFullFalse: string;
+    expandInstructions: string;
+    expandTrue: string;
+    expandFalse: string;
+    /** Second step for command output: per section, will the agent need its contents. */
+    sectionInstructions: string;
+    sectionTrue: string;
+    sectionFalse: string;
+}
+export declare const DEFAULT_PROMPTS: PromptVariant;
+export declare function presendQuestions(kinds: ViewKind[], prompts?: PromptVariant): {
+    view: {
+        type: "choice";
+        instructions: string;
+        criteria: Record<string, string>;
+    };
+    needs_full: {
+        type: "noul";
+        instructions: string;
+        criteria: {
+            true: string;
+            false: string;
+        };
+    };
+};
+export declare class JevPresend implements PresendClassifier {
+    private client;
+    private model;
+    private prompts;
+    constructor(client: TypeSafeClient, model: string, prompts?: PromptVariant);
+    expand(state: ExpandState, signal?: AbortSignal): Promise<number[]>;
+    choose(state: PresendState, kinds: ViewKind[], signal?: AbortSignal): Promise<{
+        choice: ViewKind;
+        probabilities: Record<string, number>;
+        confidence: number;
+        needsFull: number;
+    }>;
+}
+export declare class MockPresend implements PresendClassifier {
+    private pick;
+    expand(state: ExpandState): Promise<number[]>;
+    constructor(pick?: (state: PresendState, kinds: ViewKind[]) => ViewKind);
+    choose(state: PresendState, kinds: ViewKind[]): Promise<{
+        choice: ViewKind;
+        probabilities: Record<string, number>;
+        confidence: number;
+        needsFull: number;
+    }>;
+}
+/**
+ * Turn jev's answers into a view, erring on the side of sending more:
+ * full when needsFull is likely, when full itself carries real mass, or when the chosen view is not confident.
+ */
+export declare function decideView(answer: {
+    choice: ViewKind;
+    probabilities: Record<string, number>;
+    confidence: number;
+    needsFull: number;
+}, cands: Candidates, cfg: Pick<Config, "presendNeedsFullAbove" | "presendFullMassAbove" | "presendMinConfidence" | "presendCodeNeedsFullAbove" | "presendCommandNeedsFullAbove"> & Partial<Pick<Config, "presendCodePolicy" | "presendCommandPolicy">>): View;
+/**
+ * Second node of the pre-send graph: when a code file was reduced to its outline (or command output to its
+ * section headers), ask jev which block bodies the agent will need and put those back. Returns undefined when not applicable.
+ */
+export declare function expandRelevantBlocks(presend: PresendClassifier, base: PresendState, text: string, cands: Candidates, chosen: View, threshold: number, signal?: AbortSignal, precomputed?: Block[], 
+/** Command output only: send full when no section reaches this probability (0 = headers alone are allowed). */
+floor?: number): Promise<{
+    view: View;
+    blocks: Block[];
+    probs: number[];
+} | undefined>;

package/dist/presend.js

@@ -0,0 +1,172 @@
+import { truncate } from "./text.js";
+import { relevantView, splitBlocks, splitSections } from "./views.js";
+export function buildExpandState(base, blocks, text) {
+    const lines = text.split("\n");
+    return {
+        task: base.task,
+        agent: base.agent,
+        file: { kind: base.result.kind, total_lines: base.result.total_lines },
+        blocks: blocks.map((b, index) => ({ index, signature: b.name, lines: `${b.from}-${b.to}`, preview: truncate(lines.slice(b.from - 1, Math.min(b.to, b.from + 2)).join("\n"), 240) })),
+    };
+}
+export function expandQuestions(n, prompts = DEFAULT_PROMPTS, kind = "code") {
+    const q = {};
+    const [instructions, t, f] = kind === "command" ? [prompts.sectionInstructions, prompts.sectionTrue, prompts.sectionFalse] : [prompts.expandInstructions, prompts.expandTrue, prompts.expandFalse];
+    for (let i = 0; i < n; i++) {
+        q[`b${i}`] = { type: "noul", instructions: instructions.replaceAll("{i}", String(i)), criteria: { true: t, false: f } };
+    }
+    return q;
+}
+const VIEW_DESCRIPTIONS = {
+    full: "The complete, unmodified output. Needed when the agent will edit or quote exact text, when details anywhere in the output matter, or when nothing else clearly suffices.",
+    outline: "Structure only: imports, exports, signatures, class and function headers, headings, doc comments, with line numbers. Enough to understand what a file offers and where things are, not enough to edit a body verbatim.",
+    focus: "Only the lines that mention the identifiers from the task and the tool call, with a few lines of context, line-numbered. Enough when the agent is looking for specific names.",
+    signals: "Command output reduced to errors, warnings, failing tests and the final summary lines with context, line-numbered. Enough for reacting to a failed or passed run.",
+    sample: "Header plus a sample of rows and the total count, for tabular or log-like data. Enough to learn the shape of the data, not its contents.",
+    head_tail: "The first and last lines only. Enough to see what the output is and how it ends.",
+    relevant: "Outline plus the full bodies of the blocks the agent will need.",
+    matches: "Search output (grep, rg) reduced to the first matches of every file with the count of further matches per file, plus any non-match lines. Enough to see which files and lines are involved; not enough to read every match.",
+    log: "Script or server output with repeated lines collapsed: the first two and the last occurrence of every repeated line pattern, plus errors and the final lines. Enough to follow what happened; not enough to see every iteration.",
+    tree: "A directory listing reduced to the first few entries of every directory, with the number of omitted entries per directory. Enough to learn the project layout, not enough to find one specific file in a large directory.",
+    testlog: "A test run reduced to the failing tests with their assertion and traceback, the short summary and the final counts. Passing tests and decoration are dropped. Enough for reacting to a test run; not enough to see the output of passing tests.",
+    sections: "The first line of every section of the output (grep match groups, JSON objects, paragraphs, command markers), line-numbered. The bodies of the sections the agent needs are added in a second step. Enough when only some parts of a long mixed output matter.",
+};
+export function buildPresendState(cfg, input) {
+    const views = {};
+    for (const v of input.cands.views) {
+        views[v.kind] = { lines: v.lines, chars: v.chars, preview: truncate(v.text, v.kind === "full" ? Math.min(1500, cfg.stateHeadChars) : 900) };
+    }
+    return {
+        task: { first_user_request: truncate(input.firstUser, 600), latest_user_message: truncate(input.latestUser, 400) },
+        agent: { text_before_call: truncate(input.agentText, 600), tool: input.toolName, args: truncate(JSON.stringify(input.args ?? {}), 300) },
+        result: { kind: input.cands.kind, is_error: input.isError, total_lines: input.totalLines, total_chars: input.totalChars },
+        views,
+    };
+}
+export const DEFAULT_PROMPTS = {
+    viewInstructions: "A coding agent working on `task` just called `agent.tool` with `agent.args` (its reasoning right before the call is `agent.text_before_call`). The output is large. `views` lists candidate presentations of the same output with a preview of each. Which view is the smallest one that still gives the agent everything it needs for its next step? Prefer smaller views only when the agent's purpose is clearly served by them; when in doubt, choose full.",
+    viewDescriptions: {},
+    needsFullInstructions: "Will the agent's next step require the exact, complete text of this output, for example to make an edit whose old text must match, to copy code, or to check details that could be anywhere in it?",
+    needsFullTrue: "The agent asked for this to modify it, copy from it, or review it line by line; the task is about the contents of this specific output.",
+    needsFullFalse: "The agent is orienting itself, checking structure, looking for where something lives, confirming an outcome, or sampling data.",
+    expandInstructions: "The agent working on `task` just read this file (`agent.args`) for the reason in `agent.text_before_call`. Will it need the full body of block `blocks[{i}]` (not just its signature) for its next step?",
+    expandTrue: "The task or the agent's stated purpose concerns this block: it will edit it, call it in a specific way, explain its logic, or debug it.",
+    expandFalse: "The block is unrelated to the task, or knowing its signature and existence is enough.",
+    sectionInstructions: "The agent working on `task` just ran the command `agent.args` for the reason in `agent.text_before_call`. The output is split into sections listed in `blocks`. Will the agent need the contents of section `blocks[{i}]` (not just its first line) for its next step?",
+    sectionTrue: "The section holds the result, error, value or match the agent ran the command to see, or something it will quote, compare or act on.",
+    sectionFalse: "The section is boilerplate, an unrelated match, setup or progress output, or its first line already tells the agent what it needs.",
+};
+export function presendQuestions(kinds, prompts = DEFAULT_PROMPTS) {
+    const criteria = {};
+    for (const k of kinds)
+        criteria[k] = prompts.viewDescriptions[k] ?? VIEW_DESCRIPTIONS[k];
+    return {
+        view: { type: "choice", instructions: prompts.viewInstructions, criteria },
+        needs_full: { type: "noul", instructions: prompts.needsFullInstructions, criteria: { true: prompts.needsFullTrue, false: prompts.needsFullFalse } },
+    };
+}
+export class JevPresend {
+    client;
+    model;
+    prompts;
+    constructor(client, model, prompts = DEFAULT_PROMPTS) {
+        this.client = client;
+        this.model = model;
+        this.prompts = prompts;
+    }
+    async expand(state, signal) {
+        const r = await this.client.systemOne({ state: state, questions: expandQuestions(state.blocks.length, this.prompts, state.file.kind), model: this.model }, { signal, timeout: 15000 });
+        return state.blocks.map((_, i) => r.answers[`b${i}`].noul);
+    }
+    async choose(state, kinds, signal) {
+        const r = await this.client.systemOne({ state: state, questions: presendQuestions(kinds, this.prompts), model: this.model }, { signal, timeout: 15000 });
+        return { choice: r.answers.view.choice, probabilities: r.answers.view.probabilities, confidence: r.answers.view.confidence, needsFull: r.answers.needs_full.noul };
+    }
+}
+export class MockPresend {
+    pick;
+    async expand(state) {
+        // deterministic: blocks whose signature mentions a term from the task
+        const words = (state.task.first_user_request + " " + state.agent.args).toLowerCase();
+        return state.blocks.map((b) => (b.signature.toLowerCase().split(/[^a-z0-9_]+/).some((w) => w.length > 4 && words.includes(w)) ? 0.9 : 0.1));
+    }
+    constructor(pick = (s, kinds) => (s.result.kind === "data" && kinds.includes("sample") ? "sample" : kinds.includes("outline") ? "outline" : "full")) {
+        this.pick = pick;
+    }
+    async choose(state, kinds) {
+        const choice = this.pick(state, kinds);
+        const probabilities = {};
+        for (const k of kinds)
+            probabilities[k] = k === choice ? 0.9 : 0.1 / Math.max(1, kinds.length - 1);
+        return { choice, probabilities, confidence: 0.9, needsFull: choice === "full" ? 0.9 : 0.1 };
+    }
+}
+/**
+ * Turn jev's answers into a view, erring on the side of sending more:
+ * full when needsFull is likely, when full itself carries real mass, or when the chosen view is not confident.
+ */
+export function decideView(answer, cands, cfg) {
+    const full = cands.views[0];
+    if (cands.kind === "command" && cfg.presendCommandPolicy === "sections") {
+        // sections-first: when jev would send full but does not think exact full text is needed, send the
+        // section headers and let the second step put back the sections it needs (full if that reaches 90 %).
+        const sections = cands.views.find((v) => v.kind === "sections");
+        if (sections && answer.choice === "full" && answer.needsFull <= cfg.presendCommandNeedsFullAbove)
+            return sections;
+    }
+    if (cands.kind === "code" && cfg.presendCodePolicy === "outline") {
+        // outline-first: structure now, bodies via the expansion step, everything else via recall.
+        // Only when the expansion step can run (2+ blocks): an outline nobody can expand was edited from at once.
+        const outline = cands.views.find((v) => v.kind === "outline");
+        const blocks = cands.blocks;
+        if (outline && blocks && blocks.length >= 2)
+            return outline;
+        if (outline && !(blocks && blocks.length >= 2))
+            return full;
+    }
+    const needsFullAbove = cands.kind === "code" ? Math.min(cfg.presendNeedsFullAbove, cfg.presendCodeNeedsFullAbove) : cands.kind === "command" ? cfg.presendCommandNeedsFullAbove : cfg.presendNeedsFullAbove;
+    if (answer.needsFull > needsFullAbove)
+        return full;
+    // For code, "focus" alone is a locating aid; if it wins, upgrade to outline so structure comes along (the second step may expand bodies).
+    if (cands.kind === "code" && answer.choice === "focus") {
+        const outline = cands.views.find((v) => v.kind === "outline");
+        if (outline)
+            return outline;
+    }
+    if ((answer.probabilities.full ?? 0) > cfg.presendFullMassAbove)
+        return full;
+    if (answer.confidence < cfg.presendMinConfidence)
+        return full;
+    return cands.views.find((v) => v.kind === answer.choice) ?? full;
+}
+/**
+ * Second node of the pre-send graph: when a code file was reduced to its outline (or command output to its
+ * section headers), ask jev which block bodies the agent will need and put those back. Returns undefined when not applicable.
+ */
+export async function expandRelevantBlocks(presend, base, text, cands, chosen, threshold, signal, precomputed, 
+/** Command output only: send full when no section reaches this probability (0 = headers alone are allowed). */
+floor = 0) {
+    const isCode = cands.kind === "code" && (chosen.kind === "outline" || chosen.kind === "focus");
+    const isCommand = cands.kind === "command" && chosen.kind === "sections";
+    if (!isCode && !isCommand)
+        return undefined;
+    const blocks = precomputed && precomputed.length >= 2 ? precomputed : isCommand ? splitSections(text) : splitBlocks(text);
+    if (blocks.length < 2)
+        return undefined;
+    const probs = await presend.expand(buildExpandState(base, blocks, text), signal);
+    const expand = new Set();
+    probs.forEach((p, i) => { if (p > threshold)
+        expand.add(i); });
+    // the import/constants header is small and often edited (new imports): always keep it whole when short
+    if (isCode && blocks[0]?.name.startsWith("(header") && blocks[0].to - blocks[0].from < 20)
+        expand.add(0);
+    // Command output where every section scores low is "cannot tell", not "nothing needed" (docs read for
+    // orientation score flat and low): headers alone would drop what the agent came for, so send it all.
+    if (isCommand && Math.max(...probs) < floor)
+        return { view: cands.views[0], blocks, probs };
+    const outline = cands.views.find((v) => v.kind === (isCommand ? "sections" : "outline"));
+    const view = relevantView(text, cands.kind, blocks, expand, outline?.included);
+    if (view.chars >= cands.views[0].chars * 0.9)
+        return { view: cands.views[0], blocks, probs };
+    return { view, blocks, probs };
+}

package/dist/recall.d.ts

@@ -0,0 +1,31 @@
+export interface RecallParams {
+    /** Line range like "120-180" (1-based, inclusive). */
+    lines?: string;
+    /** Case-insensitive substring, or /regex/ with optional flags. */
+    pattern?: string;
+}
+export interface StoredOutput {
+    text: string;
+    toolName: string;
+    args: unknown;
+}
+export interface RecallSlice {
+    text: string;
+    /** Lines returned. */
+    count: number;
+    /** Lines in the stored output. */
+    total: number;
+    /** Set when the parameters were malformed; `text` then explains what was expected. */
+    error?: string;
+}
+/** Select the requested lines of a stored output. Returns the whole text unchanged when nothing restricts it. */
+export declare function sliceRecall(hit: StoredOutput, params?: RecallParams): RecallSlice;
+/** What the model gets when it recalls an id nothing was stored for. */
+export declare function recallMissText(id: string): string;
+/** The recall tool's description, identical in every host so the model's habits carry over. */
+export declare const RECALL_DESCRIPTION = "Return the full output of an earlier tool call that jev-lens showed in a reduced view. Pass the id from the [jev-lens: ...] note. Optionally restrict to a line range \"a-b\" or to lines matching a pattern (case-insensitive substring or /regex/).";
+export declare const RECALL_PARAM_DESCRIPTIONS: {
+    id: string;
+    lines: string;
+    pattern: string;
+};

package/dist/recall.js

@@ -0,0 +1,58 @@
+/**
+ * The recall tool's slicing, shared by every host: a stored full output, optionally restricted to a
+ * line range or to the lines matching a pattern (with two lines of context), rendered with line numbers.
+ */
+import { truncate } from "./text.js";
+/** Select the requested lines of a stored output. Returns the whole text unchanged when nothing restricts it. */
+export function sliceRecall(hit, params = {}) {
+    const all = hit.text.split("\n");
+    let idx = all.map((_, i) => i);
+    if (params.lines) {
+        const m = params.lines.match(/^(\d+)\s*-\s*(\d+)$/);
+        if (!m)
+            return { text: "lines must look like 120-180", count: 0, total: all.length, error: "bad-lines" };
+        const a = Math.max(1, Number(m[1])), b = Math.min(all.length, Number(m[2]));
+        idx = idx.filter((i) => i + 1 >= a && i + 1 <= b);
+    }
+    if (params.pattern) {
+        let test;
+        const rx = params.pattern.match(/^\/(.*)\/([a-z]*)$/);
+        if (rx) {
+            let re;
+            try {
+                re = new RegExp(rx[1], rx[2].includes("i") ? rx[2] : rx[2] + "i");
+            }
+            catch {
+                return { text: `pattern is not a valid regular expression: ${params.pattern}`, count: 0, total: all.length, error: "bad-pattern" };
+            }
+            test = (l) => re.test(l);
+        }
+        else {
+            const needle = params.pattern.toLowerCase();
+            test = (l) => l.toLowerCase().includes(needle);
+        }
+        const keep = new Set();
+        for (const i of idx)
+            if (test(all[i]))
+                for (let j = Math.max(0, i - 2); j <= Math.min(all.length - 1, i + 2); j++)
+                    keep.add(j);
+        idx = idx.filter((i) => keep.has(i));
+    }
+    if (idx.length === all.length)
+        return { text: hit.text, count: all.length, total: all.length };
+    const width = String(all.length).length;
+    const body = idx.map((i) => `${String(i + 1).padStart(width)}│ ${all[i]}`).join("\n");
+    const header = `[${idx.length} of ${all.length} lines from ${hit.toolName} ${truncate(JSON.stringify(hit.args ?? {}), 80)}]\n`;
+    return { text: header + body, count: idx.length, total: all.length };
+}
+/** What the model gets when it recalls an id nothing was stored for. */
+export function recallMissText(id) {
+    return `No stored output for id ${id}. Re-run the original tool instead.`;
+}
+/** The recall tool's description, identical in every host so the model's habits carry over. */
+export const RECALL_DESCRIPTION = "Return the full output of an earlier tool call that jev-lens showed in a reduced view. Pass the id from the [jev-lens: ...] note. Optionally restrict to a line range \"a-b\" or to lines matching a pattern (case-insensitive substring or /regex/).";
+export const RECALL_PARAM_DESCRIPTIONS = {
+    id: "id from the jev-lens note",
+    lines: "Line range like 120-180 (1-based, inclusive)",
+    pattern: "Only lines matching this substring or /regex/, with 2 lines of context",
+};

package/dist/shell-display.d.ts

@@ -0,0 +1,2 @@
+/** A deliberately small shell subset, not a general shell parser. Unknown syntax fails closed. */
+export declare function displayedFiles(command: string): string[] | undefined;

package/dist/shell-display.js

@@ -0,0 +1,135 @@
+/** A deliberately small shell subset, not a general shell parser. Unknown syntax fails closed. */
+export function displayedFiles(command) {
+    if (command.length > 16384 || /[<>`$\\()#\r]/.test(command))
+        return undefined;
+    const tokens = [];
+    for (let i = 0; i < command.length;) {
+        const c = command[i];
+        if (c === " " || c === "\t") {
+            i++;
+            continue;
+        }
+        if (";|&\n".includes(c)) {
+            let value = c;
+            if (command[i + 1] === c && (c === "&" || c === "|")) {
+                value += c;
+                i++;
+            }
+            if (value === "&" || value === "||")
+                return undefined;
+            tokens.push({ value, operator: true });
+            i++;
+            continue;
+        }
+        if (c === "'" || c === '"') {
+            const end = command.indexOf(c, i + 1);
+            if (end < 0 || (end + 1 < command.length && !/[\s;|&]/.test(command[end + 1])))
+                return undefined;
+            const value = command.slice(i + 1, end);
+            // Quoted wildcard/brace paths need literal matching, not shell expansion.
+            if (/[{}*?\[\]\n]/.test(value))
+                return undefined;
+            tokens.push({ value });
+            i = end + 1;
+            continue;
+        }
+        let end = i;
+        while (end < command.length && !/[\s;|&]/.test(command[end]))
+            end++;
+        const value = command.slice(i, end);
+        if (!value || /['"]/.test(value))
+            return undefined;
+        tokens.push({ value });
+        i = end;
+    }
+    const files = [];
+    let stage = [], filter = false;
+    const finish = () => {
+        const paths = displayStage(stage);
+        if (!paths || (filter ? paths.length !== 0 : paths.length === 0))
+            return false;
+        files.push(...paths);
+        stage = [];
+        return files.length <= 256;
+    };
+    for (const token of tokens) {
+        if (!token.operator) {
+            stage.push(token.value);
+            continue;
+        }
+        if (!stage.length) {
+            if (token.value === "\n" && !filter)
+                continue;
+            return undefined;
+        }
+        if (!finish())
+            return undefined;
+        filter = token.value === "|";
+    }
+    if (stage.length) {
+        if (!finish())
+            return undefined;
+    }
+    else if (filter || tokens.at(-1)?.value === "&&")
+        return undefined;
+    return files.length ? files : undefined;
+}
+/** Only content-preserving cat, line-limited head/tail, and sed -n range-p are recognized. */
+function displayStage(words) {
+    const [executable, ...args] = words;
+    if (!executable || !/^(?:(?:\/usr)?\/bin\/)?(?:cat|head|tail|sed)$/.test(executable))
+        return undefined;
+    const cmd = executable.split("/").pop();
+    let i = 0;
+    if (cmd === "sed") {
+        if (args[i++] !== "-n" || !/^\d+(?:,(?:\d+|\$))?p$/.test(args[i++] ?? ""))
+            return undefined;
+    }
+    else if (cmd === "head" || cmd === "tail") {
+        if (args[i] === "-n") {
+            i++;
+            if (!/^\d+$/.test(args[i++] ?? ""))
+                return undefined;
+        }
+        else if (/^-\d+$/.test(args[i] ?? ""))
+            i++;
+    }
+    if (args[i] === "--")
+        i++;
+    const paths = [];
+    for (const arg of args.slice(i)) {
+        if (!arg || arg.startsWith("-") || /[~!]/.test(arg))
+            return undefined;
+        const expanded = expandBraces(arg);
+        if (!expanded)
+            return undefined;
+        paths.push(...expanded);
+    }
+    return paths;
+}
+function expandBraces(word) {
+    let pending = [word];
+    for (;;) {
+        const next = [];
+        let expanded = false;
+        for (const item of pending) {
+            const m = /^(.*?)\{([^{}]+)\}(.*)$/.exec(item);
+            if (!m) {
+                if (/[{}]/.test(item))
+                    return undefined;
+                next.push(item);
+                continue;
+            }
+            if (!m[2].includes(","))
+                return undefined;
+            for (const alt of m[2].split(","))
+                next.push(m[1] + alt + m[3]);
+            expanded = true;
+            if (next.length > 256)
+                return undefined;
+        }
+        if (!expanded)
+            return next;
+        pending = next;
+    }
+}

package/dist/text.d.ts

@@ -0,0 +1,17 @@
+/** The shape of a message this module reads: pi's AgentMessage and Claude Code transcript messages both fit. */
+export interface MessageLike {
+    role: string;
+    content: unknown;
+}
+export declare function contentText(content: unknown): string;
+export declare function toolCallsOf(message: MessageLike): {
+    name: string;
+    arguments: unknown;
+}[];
+export declare function head(s: string, n: number): string;
+export declare function tail(s: string, n: number): string;
+export declare function truncate(s: string, n: number): string;
+/** Rough token estimate matching pi's heuristic (chars / 4). */
+export declare function estimateTokensOfText(s: string): number;
+/** Short, stable description of a tool call for stubs and memory pointers. */
+export declare function describeToolCall(toolName: string, args: unknown, outputChars: number, lines: number): string;

package/dist/text.js

@@ -0,0 +1,66 @@
+export function contentText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        const b = block;
+        if (b.type === "text" && typeof b.text === "string")
+            parts.push(b.text);
+    }
+    return parts.join("\n");
+}
+export function toolCallsOf(message) {
+    if (message.role !== "assistant" || !Array.isArray(message.content))
+        return [];
+    const out = [];
+    for (const block of message.content) {
+        if (block && block.type === "toolCall" && typeof block.name === "string")
+            out.push({ name: block.name, arguments: block.arguments });
+    }
+    return out;
+}
+export function head(s, n) {
+    return s.length <= n ? s : s.slice(0, n);
+}
+export function tail(s, n) {
+    return s.length <= n ? "" : s.slice(-n);
+}
+export function truncate(s, n) {
+    return s.length <= n ? s : `${s.slice(0, n)}…`;
+}
+/** Rough token estimate matching pi's heuristic (chars / 4). */
+export function estimateTokensOfText(s) {
+    return Math.ceil(s.length / 4);
+}
+/** Short, stable description of a tool call for stubs and memory pointers. */
+export function describeToolCall(toolName, args, outputChars, lines) {
+    const a = (args ?? {});
+    const pick = (k) => (typeof a[k] === "string" ? a[k] : undefined);
+    let what = "";
+    switch (toolName) {
+        case "read":
+            what = pick("path") ?? "";
+            break;
+        case "bash":
+            what = truncate((pick("command") ?? "").replace(/\s+/g, " "), 80);
+            break;
+        case "grep":
+            what = `${pick("pattern") ?? ""} in ${pick("path") ?? "."}`;
+            break;
+        case "find":
+        case "ls":
+            what = pick("path") ?? pick("pattern") ?? "";
+            break;
+        case "edit":
+        case "write":
+            what = pick("path") ?? "";
+            break;
+        default:
+            what = truncate(JSON.stringify(a), 80);
+    }
+    return `${toolName} ${what}`.trim() + ` (${lines} lines, ${outputChars} chars)`;
+}

package/dist/treesitter.d.ts

@@ -0,0 +1,10 @@
+import type { Block } from "./views.ts";
+export declare function languageForPath(path: string): string | undefined;
+/**
+ * Top-level blocks from the syntax tree: each named child of the root that is a declaration
+ * becomes a block spanning its full line range (including a directly preceding comment).
+ * Leading imports and other non-block statements are folded into a header block.
+ */
+export declare function treeSitterBlocks(path: string, text: string, maxBlocks?: number): Promise<Block[] | undefined>;
+/** Signature lines (block starts) as an outline index list, 0-based. */
+export declare function treeSitterOutline(path: string, text: string): Promise<number[] | undefined>;