@jitsusama/agentic-harness.core 0.1.0

package/dist/result/listing.js

@@ -0,0 +1,72 @@
+/**
+ * A rendered listing, bounded for reading and stored for querying.
+ *
+ * Families render their own listings, and they should: a renderer
+ * that silently dropped rows would be lying in its own way.
+ * Bounding belongs here instead, at the point where the records
+ * are still to hand and can be kept.
+ *
+ * The counts in the citation are lines, because lines are what a
+ * reader can see and count for themselves. How many records those
+ * lines covered is not knowable from the text, and a citation
+ * nobody can check is a citation nobody should trust. What the
+ * payload actually holds is named separately, since a caller
+ * writing their first expression against lines when the payload
+ * holds records gets nothing back and no clue why.
+ */
+import { cite } from "./cite.js";
+import { count } from "./counts.js";
+import { withinLineBudget } from "./view.js";
+/** What a rendered listing spends before the rest is stored. */
+export const LISTING_BUDGET_BYTES = 8_192;
+/**
+ * Bound a listing and cite its records when the view was cut.
+ *
+ * A listing that fits is returned untouched, with no citation and
+ * no advice: the view is the whole truth and saying more would be
+ * noise.
+ */
+export function citeListing(store, listing) {
+    const budget = listing.budget ?? LISTING_BUDGET_BYTES;
+    const bounded = withinLineBudget(listing.view, budget);
+    const trailer = listing.trailer ? `\n\n${listing.trailer}` : "";
+    if (bounded.cut === 0 && !listing.elided) {
+        return `${bounded.text}${trailer}`;
+    }
+    if (listing.records.length === 0) {
+        // A caller whose view was cut needs the rest of it, and an empty
+        // array is not the rest of it. "All 0 findings are stored under
+        // handle X" invites a query that can only come back empty, and
+        // reads as though the answer were empty rather than the payload
+        // being the wrong thing to have kept.
+        return cite(store, {
+            payload: listing.view,
+            view: `${bounded.text}${trailer}\n\n` +
+                `Cut ${count(bounded.cut)} of ${count(bounded.total)} lines ` +
+                `to fit the ${count(budget)} byte budget. ${listing.narrowing}`,
+            shown: bounded.shown,
+            total: bounded.total,
+            unit: "lines",
+            stored: { unit: "rendered answer" },
+        }).text;
+    }
+    const cited = cite(store, {
+        payload: listing.records,
+        view: `${bounded.text}${trailer}\n\n` +
+            (bounded.cut === 0
+                ? `This view lists only some of what was found. ${listing.narrowing}`
+                : `Cut ${count(bounded.cut)} of ` +
+                    `${count(bounded.total)} lines to fit the ` +
+                    `${count(budget)} byte budget. ${listing.narrowing}`),
+        shown: bounded.shown,
+        total: bounded.total,
+        unit: "lines",
+        ...(listing.elided ? { elided: true } : {}),
+        // Lines are what the reader can count; records are what is on
+        // disk. Naming both in one sentence replaced a correction
+        // appended after the fact, which contradicted the sentence above
+        // it and made the reader decide which to believe.
+        stored: { count: listing.records.length, unit: listing.unit },
+    });
+    return cited.text;
+}

package/dist/result/location.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Where a session's stored payloads live, and when they stop
+ * living there.
+ *
+ * Keyed by process id, because that is the one identifier that is
+ * both available everywhere without being passed around and
+ * checkable from outside: a directory named for a process that no
+ * longer exists is abandoned, and no bookkeeping had to survive
+ * the crash to tell us so. Sessions that end cleanly delete their
+ * own directory; sessions that are killed leave one behind, and
+ * the next session to start reaps it.
+ *
+ * The alternative, reaping by age, cannot tell a dead session's
+ * payloads from a live session's, so it either deletes payloads
+ * somebody is still querying or keeps payloads nobody can.
+ */
+import { type ResultStore } from "./store.js";
+/** Where every session's stored payloads are rooted. */
+export declare const RESULT_ROOT: string;
+/**
+ * How much disk one session's payloads may hold.
+ *
+ * Generous, because the point of storing is that the caller can
+ * come back for detail later in a long session, and a quota that
+ * evicts a page outline before it has been queried has cost the
+ * context it was meant to save.
+ */
+export declare const SESSION_QUOTA_BYTES: number;
+/** This process's own payload directory. */
+export declare function sessionResultDir(): string;
+/**
+ * A store over this session's directory.
+ *
+ * Every family opens its own, because the store is its directory:
+ * two instances over one directory see the same payloads and
+ * enforce one quota between them. That is what lets one family
+ * cite a handle another can read without either importing the
+ * other, or a mutable instance being passed around a package that
+ * has no place to keep one.
+ *
+ * Not memoized here on purpose. Session lifetime belongs to the
+ * adapter, and an instance holds nothing worth reusing beyond
+ * the directory it names.
+ *
+ * Names the directory without creating it. Creating it here made
+ * opening a store a disk operation, and every family opens one
+ * before handing it to the code that knows how to survive a
+ * failed write: an unwritable temp directory threw straight out
+ * of nine call sites and took the whole tool call with it, past
+ * the one place that catches exactly this and answers anyway.
+ * The write itself still creates what it needs.
+ */
+export declare function openSessionStore(): ResultStore;
+/** Whether a process is still running. */
+export declare function isPidAlive(pid: number): boolean;
+/**
+ * Remove payload directories no live process owns.
+ *
+ * The collaborators are parameters so a destructive sweep can be
+ * tested against a throwaway root rather than the real one.
+ */
+export declare function reapAbandonedResults(opts: {
+    root: string;
+    isPidAlive: (pid: number) => boolean;
+}): void;
+/** Remove this session's payload directory. */
+export declare function cleanupSessionResults(): void;

package/dist/result/location.js

@@ -0,0 +1,125 @@
+/**
+ * Where a session's stored payloads live, and when they stop
+ * living there.
+ *
+ * Keyed by process id, because that is the one identifier that is
+ * both available everywhere without being passed around and
+ * checkable from outside: a directory named for a process that no
+ * longer exists is abandoned, and no bookkeeping had to survive
+ * the crash to tell us so. Sessions that end cleanly delete their
+ * own directory; sessions that are killed leave one behind, and
+ * the next session to start reaps it.
+ *
+ * The alternative, reaping by age, cannot tell a dead session's
+ * payloads from a live session's, so it either deletes payloads
+ * somebody is still querying or keeps payloads nobody can.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createResultStore } from "./store.js";
+/** Where every session's stored payloads are rooted. */
+export const RESULT_ROOT = path.join(os.tmpdir(), "pi-tool-results");
+// The directory's mode lives with the code that creates it, in
+// spill.ts. Nothing here makes a directory any more.
+/**
+ * How much disk one session's payloads may hold.
+ *
+ * Generous, because the point of storing is that the caller can
+ * come back for detail later in a long session, and a quota that
+ * evicts a page outline before it has been queried has cost the
+ * context it was meant to save.
+ */
+export const SESSION_QUOTA_BYTES = 256 * 1024 * 1024;
+/** This process's own payload directory. */
+export function sessionResultDir() {
+    return path.join(RESULT_ROOT, String(process.pid));
+}
+/**
+ * A store over this session's directory.
+ *
+ * Every family opens its own, because the store is its directory:
+ * two instances over one directory see the same payloads and
+ * enforce one quota between them. That is what lets one family
+ * cite a handle another can read without either importing the
+ * other, or a mutable instance being passed around a package that
+ * has no place to keep one.
+ *
+ * Not memoized here on purpose. Session lifetime belongs to the
+ * adapter, and an instance holds nothing worth reusing beyond
+ * the directory it names.
+ *
+ * Names the directory without creating it. Creating it here made
+ * opening a store a disk operation, and every family opens one
+ * before handing it to the code that knows how to survive a
+ * failed write: an unwritable temp directory threw straight out
+ * of nine call sites and took the whole tool call with it, past
+ * the one place that catches exactly this and answers anyway.
+ * The write itself still creates what it needs.
+ */
+export function openSessionStore() {
+    return createResultStore({
+        dir: sessionResultDir(),
+        maxBytes: SESSION_QUOTA_BYTES,
+    });
+}
+/** Whether a process is still running. */
+export function isPidAlive(pid) {
+    try {
+        // Signal 0 tests for the process without touching it.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means it exists and belongs to somebody else, which is
+        // still alive as far as reaping is concerned.
+        return err.code === "EPERM";
+    }
+}
+/**
+ * Remove payload directories no live process owns.
+ *
+ * The collaborators are parameters so a destructive sweep can be
+ * tested against a throwaway root rather than the real one.
+ */
+export function reapAbandonedResults(opts) {
+    let entries;
+    try {
+        entries = fs.readdirSync(opts.root, { withFileTypes: true });
+    }
+    catch {
+        // No root yet, so nothing was ever abandoned.
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const pid = Number(entry.name);
+        // Anything not named for a pid was not made by us; leaving it
+        // alone is cheaper than being wrong about whose it is.
+        if (!Number.isInteger(pid) || pid <= 0)
+            continue;
+        if (opts.isPidAlive(pid))
+            continue;
+        try {
+            fs.rmSync(path.join(opts.root, entry.name), {
+                recursive: true,
+                force: true,
+            });
+        }
+        catch {
+            // It vanished under us or will not delete; either way the next
+            // session will try again.
+        }
+    }
+}
+/** Remove this session's payload directory. */
+export function cleanupSessionResults() {
+    try {
+        fs.rmSync(sessionResultDir(), { recursive: true, force: true });
+    }
+    catch {
+        // Nothing more can be done at shutdown, and the pid-keyed name
+        // means the next session's reaper will collect it.
+    }
+}

package/dist/result/query.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Asking a stored payload a question.
+ *
+ * One query language for every tool that stores anything, because
+ * the cost of a query language is learning it, and that cost is
+ * paid once only if the language does not change per family.
+ * JSONPath is the choice: a language model already knows it, and
+ * filters mean a caller can find the records they want rather
+ * than paging through records they do not.
+ *
+ * Every answer is bounded twice. At most a fixed number of
+ * matches are serialized, and the serialized text passes back
+ * through the same size rule that sent the payload to disk in the
+ * first place, so a query broad enough to select everything
+ * cannot undo the storing. The total match count is always
+ * reported before that truncation, which means a deliberately
+ * broad expression is the cheapest way to answer "how many"
+ * without pulling a single whole record.
+ *
+ * The second of those bounds was documented here and never
+ * written, which is the worst of both: `$.rows[*]` over a stored
+ * listing came back larger than the payload the store had just
+ * taken out of context, and the sentence above said it could not.
+ *
+ * Nothing here throws. A handle that has expired, a payload that
+ * no longer parses and an expression with a typo are all ordinary
+ * events in a conversation, and each comes back as a note that
+ * says what to do differently.
+ */
+import { type ResultStore } from "./store.js";
+/** A block of text an answer is made of. */
+export interface TextBlock {
+    readonly type: "text";
+    readonly text: string;
+}
+/** Bounds on a query's answer. */
+export interface QueryOptions {
+    /** Cap on the serialized answer, above which it is stored instead. */
+    limitBytes?: number;
+    /** Cap on how many matches are serialized. */
+    maxMatches?: number;
+}
+/** How many matches an answer carries when the caller says nothing. */
+export declare const DEFAULT_MAX_MATCHES = 100;
+/**
+ * How many bytes an answer spends before it is stored instead.
+ *
+ * The same figure a rendered listing spends, because it is the
+ * same question: how much of a collection goes in front of the
+ * model before the rest is put where it can be asked about.
+ */
+export declare const DEFAULT_ANSWER_BYTES = 8192;
+/** What a query did, for a caller that wants to store the answer. */
+export interface QueryAnswer {
+    readonly blocks: readonly TextBlock[];
+    /** Total matches before any cap, when the expression ran at all. */
+    readonly matches?: number;
+    /** The serialized matches, whatever their size. */
+    readonly json?: string;
+}
+/**
+ * Run a JSONPath expression against a stored payload.
+ *
+ * The answer opens with the total match count, so the number is
+ * never a casualty of the cap that follows it.
+ */
+export declare function queryStored(store: ResultStore, handle: string, expression: string, opts?: QueryOptions): QueryAnswer;

package/dist/result/query.js

@@ -0,0 +1,144 @@
+/**
+ * Asking a stored payload a question.
+ *
+ * One query language for every tool that stores anything, because
+ * the cost of a query language is learning it, and that cost is
+ * paid once only if the language does not change per family.
+ * JSONPath is the choice: a language model already knows it, and
+ * filters mean a caller can find the records they want rather
+ * than paging through records they do not.
+ *
+ * Every answer is bounded twice. At most a fixed number of
+ * matches are serialized, and the serialized text passes back
+ * through the same size rule that sent the payload to disk in the
+ * first place, so a query broad enough to select everything
+ * cannot undo the storing. The total match count is always
+ * reported before that truncation, which means a deliberately
+ * broad expression is the cheapest way to answer "how many"
+ * without pulling a single whole record.
+ *
+ * The second of those bounds was documented here and never
+ * written, which is the worst of both: `$.rows[*]` over a stored
+ * listing came back larger than the payload the store had just
+ * taken out of context, and the sentence above said it could not.
+ *
+ * Nothing here throws. A handle that has expired, a payload that
+ * no longer parses and an expression with a typo are all ordinary
+ * events in a conversation, and each comes back as a note that
+ * says what to do differently.
+ */
+import { JSONPath } from "jsonpath-plus";
+import { cite } from "./cite.js";
+import { count } from "./counts.js";
+import { LISTING_BUDGET_BYTES } from "./listing.js";
+import { HandleExpiredError } from "./store.js";
+import { withinLineBudget } from "./view.js";
+/** How many matches an answer carries when the caller says nothing. */
+export const DEFAULT_MAX_MATCHES = 100;
+/**
+ * How many bytes an answer spends before it is stored instead.
+ *
+ * The same figure a rendered listing spends, because it is the
+ * same question: how much of a collection goes in front of the
+ * model before the rest is put where it can be asked about.
+ */
+export const DEFAULT_ANSWER_BYTES = LISTING_BUDGET_BYTES;
+/** How much of a caller's own string is echoed back in a note. */
+const MAX_EXPRESSION_ECHO = 200;
+/**
+ * Run a JSONPath expression against a stored payload.
+ *
+ * The answer opens with the total match count, so the number is
+ * never a casualty of the cap that follows it.
+ */
+export function queryStored(store, handle, expression, opts = {}) {
+    let rawText;
+    try {
+        rawText = store.read(handle);
+    }
+    catch (err) {
+        if (err instanceof HandleExpiredError)
+            return note(err.message);
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch {
+        return note(`stored result for handle ${handle} is not valid JSON`);
+    }
+    let matches;
+    try {
+        matches = JSONPath({
+            path: expression,
+            json: parsed,
+            wrap: true,
+            // Filter expressions are the most useful verb in the language,
+            // so evaluation stays on. The expression comes from a model
+            // that can already run anything through bash, so this grants no
+            // capability it lacked; the catch below is about a typo, not a
+            // boundary.
+            eval: true,
+        });
+    }
+    catch (err) {
+        return note(`invalid JSONPath expression: ${err instanceof Error ? err.message : String(err)}. ` +
+            "If a field name contains dots it is a single literal key, so match " +
+            "it with bracket notation like @['a.b.c'] rather than dot access.");
+    }
+    if (matches.length === 0)
+        return note(`no matches for expression ${echo(expression)}. Field names are ` +
+            "case-sensitive; check the result summary for the exact names, and " +
+            "match a dotted key with bracket notation like @['a.b.c'].");
+    const maxMatches = Math.max(0, opts.maxMatches ?? DEFAULT_MAX_MATCHES);
+    const limited = matches.slice(0, maxMatches);
+    const header = limited.length < matches.length
+        ? `${matches.length} matches; showing the first ${limited.length}.`
+        : `${matches.length} matches.`;
+    const json = JSON.stringify(limited, null, 2);
+    return {
+        blocks: [
+            { type: "text", text: header },
+            { type: "text", text: answerWithin(store, limited, json, opts) },
+        ],
+        matches: matches.length,
+        json,
+    };
+}
+/**
+ * The serialized matches, cut to a budget and citable beyond it.
+ *
+ * The cut answer is stored under its own handle rather than
+ * pointing back at the original, because what the caller wants
+ * next is a narrower question about these matches, not about the
+ * payload they came from. Following a handle should move forward.
+ */
+function answerWithin(store, matches, json, opts) {
+    const budget = opts.limitBytes ?? DEFAULT_ANSWER_BYTES;
+    const bounded = withinLineBudget(json, budget);
+    if (bounded.cut === 0)
+        return bounded.text;
+    return cite(store, {
+        payload: matches,
+        view: `${bounded.text}\n\n` +
+            `Cut ${count(bounded.cut)} of ` +
+            `${count(bounded.total)} lines to fit the ` +
+            `${count(budget)} byte budget. Project fewer fields, ` +
+            "or filter before selecting.",
+        shown: bounded.shown,
+        total: bounded.total,
+        unit: "lines",
+        stored: { count: matches.length, unit: "matches" },
+    }).text;
+}
+/** A note about a query that could not run, itself bounded. */
+function note(message) {
+    return { blocks: [{ type: "text", text: `[${echo(message)}]` }] };
+}
+/** Bound a caller's own string before echoing it back. */
+function echo(text) {
+    return text.length > MAX_EXPRESSION_ECHO
+        ? `${text.slice(0, MAX_EXPRESSION_ECHO)}...`
+        : text;
+}

package/dist/result/spill.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Putting a payload on disk so an answer does not have to carry
+ * it.
+ *
+ * A payload is named after its own content, which makes storing it
+ * twice free. That is not a micro-optimization: a caller who
+ * navigates, reads the page, clicks something and reads it again
+ * generates the same outline several times over, and the first
+ * version of this stored a separate megabyte for each of them
+ * under a separate handle. Naming by content means one file, one
+ * handle, and a handle that stays valid however many answers cite
+ * it.
+ *
+ * The write is exclusive rather than checked-then-created, because
+ * two tools answering at once is ordinary. With content
+ * addressing a collision is not a conflict: whoever lost the race
+ * wrote the same bytes, so the existing file is the correct answer.
+ */
+/** A stored payload, and whether it was already there. */
+export interface SpilledPayload {
+    readonly path: string;
+    /** True when an identical payload was already stored. */
+    readonly reused: boolean;
+}
+/**
+ * Write text into a directory under a name derived from its
+ * content, and return where it went.
+ *
+ * The directory is created when missing and resolved through its
+ * real path, so a handle never depends on a symlink that later
+ * changes where it points.
+ *
+ * The bytes land under a temporary name and are moved into place,
+ * so the content-addressed name only ever holds a complete
+ * payload. Writing straight to it meant an interrupted write left
+ * the right name over the wrong bytes, and since the name is
+ * derived from the content, every later attempt to store the same
+ * thing took the name's existence as proof the content matched and
+ * handed back a handle to a truncated payload.
+ */
+export declare function spillText(text: string, dir: string): SpilledPayload;

package/dist/result/spill.js

@@ -0,0 +1,121 @@
+/**
+ * Putting a payload on disk so an answer does not have to carry
+ * it.
+ *
+ * A payload is named after its own content, which makes storing it
+ * twice free. That is not a micro-optimization: a caller who
+ * navigates, reads the page, clicks something and reads it again
+ * generates the same outline several times over, and the first
+ * version of this stored a separate megabyte for each of them
+ * under a separate handle. Naming by content means one file, one
+ * handle, and a handle that stays valid however many answers cite
+ * it.
+ *
+ * The write is exclusive rather than checked-then-created, because
+ * two tools answering at once is ordinary. With content
+ * addressing a collision is not a conflict: whoever lost the race
+ * wrote the same bytes, so the existing file is the correct answer.
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** Owner only, since a payload can hold anything the tool saw. */
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+/**
+ * How much of the digest names the file.
+ *
+ * Sixty-four bits, which for the number of payloads one session
+ * can produce makes an accidental collision far less likely than
+ * the disk lying about the write that stored it.
+ */
+const NAME_HEX_LENGTH = 16;
+/**
+ * Write text into a directory under a name derived from its
+ * content, and return where it went.
+ *
+ * The directory is created when missing and resolved through its
+ * real path, so a handle never depends on a symlink that later
+ * changes where it points.
+ *
+ * The bytes land under a temporary name and are moved into place,
+ * so the content-addressed name only ever holds a complete
+ * payload. Writing straight to it meant an interrupted write left
+ * the right name over the wrong bytes, and since the name is
+ * derived from the content, every later attempt to store the same
+ * thing took the name's existence as proof the content matched and
+ * handed back a handle to a truncated payload.
+ */
+export function spillText(text, dir) {
+    fs.mkdirSync(dir, { recursive: true, mode: DIR_MODE });
+    const realDir = fs.realpathSync(dir);
+    const digest = crypto
+        .createHash("sha256")
+        .update(text, "utf-8")
+        .digest("hex")
+        .slice(0, NAME_HEX_LENGTH);
+    const target = path.join(realDir, `result-${digest}.json`);
+    const bytes = Buffer.from(text, "utf-8");
+    if (alreadyWhole(target, bytes.length)) {
+        // Touch it so the quota's oldest-first eviction treats it as
+        // freshly used rather than as the stalest payload in the
+        // directory, which is how a handle being cited again would
+        // otherwise get itself evicted.
+        try {
+            const now = new Date();
+            fs.utimesSync(target, now, now);
+        }
+        catch {
+            // The timestamp is a hint for eviction order, not correctness.
+        }
+        return { path: target, reused: true };
+    }
+    // A name nothing else will choose: the process, the moment and a
+    // counter, so two concurrent spills of the same payload cannot
+    // land on one temporary file.
+    const staging = path.join(realDir, `.${digest}.${process.pid}.${nextStagingId()}.part`);
+    try {
+        fs.writeFileSync(staging, bytes, { mode: FILE_MODE });
+        // Atomic within a directory, and it overwrites: a partial file
+        // left by an earlier crash is replaced by the complete one
+        // rather than being trusted forever.
+        fs.renameSync(staging, target);
+    }
+    catch (err) {
+        try {
+            fs.rmSync(staging, { force: true });
+        }
+        catch {
+            // Nothing more to do about it. The caller is about to be told
+            // the payload could not be stored, and debris in a temporary
+            // directory is the lesser problem.
+        }
+        throw err;
+    }
+    return { path: target, reused: false };
+}
+/**
+ * Whether the payload is already there in full.
+ *
+ * Judged by length, because the name is a digest of the content:
+ * anything of the right length under the right name differs only
+ * by a hash collision, which content addressing already treats as
+ * less likely than the disk lying. A short file is the failure
+ * this catches, and truncation is what a torn write produces.
+ */
+function alreadyWhole(target, expected) {
+    try {
+        return fs.statSync(target).size === expected;
+    }
+    catch {
+        // Not there, or not readable. Either way it is about to be
+        // written.
+        return false;
+    }
+}
+/** Distinguishes two staging files written in the same millisecond. */
+let stagingCounter = 0;
+function nextStagingId() {
+    stagingCounter += 1;
+    return `${Date.now().toString(36)}${stagingCounter.toString(36)}`;
+}