@xingular/harness 0.1.7 → 1.0.0

package/dist/sdk/history/lessons.js

@@ -0,0 +1,173 @@
+// Lessons from finished runs. When the `lessons` plugin is on for a run's caller, a completed
+// top-level run is reflected on in the background: a file-tools-only session reads its record and
+// may keep one general lesson as a Wiki note under `library/lessons/`. The lesson shape and the
+// answer-free guards are refinement's (harness²); the caps follow OMP's memory budget.
+//
+// Lessons are reference notes (INV-MEM-1). They never enter the stable prefix and never change a
+// variant; something that should become an instruction goes through refinement and `adopt`.
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadRun as loadCapabilities } from "../capabilities/runSnapshot.js";
+import { log } from "../core/bus.js";
+import * as frontmatter from "../core/frontmatter.js";
+import { looksSecret } from "../core/secrets.js";
+import * as attachments from "../plugins/attachments.js";
+import { LESSONS, LESSONS_CODE, LESSONS_SETTINGS, settingValue } from "../plugins/firstParty.js";
+import { assertNoGraderVerdicts, assertVariantHasNoGraderVerdicts } from "../refine/evidence.js";
+import { hasExperience } from "../refine/library.js";
+import { PiImprover } from "../refine/pi.js";
+import { parseExperience } from "../refine/selection.js";
+import { renderEvents } from "../refine/trajectory.js";
+import { executionEvents, findRun, readEvents } from "../sessions/runStore.js";
+import * as notes from "../wiki/notes.js";
+import { lessonMission, REFLECTION_IDENTITY } from "./lessonPrompt.js";
+export const REFLECTION_TRIGGER = 'reflection';
+export const LESSONS_FOLDER = 'library/lessons';
+/** Runs that are themselves part of improving the harness are never reflected on. */
+const SKIPPED_TRIGGERS = new Set(['probe', 'improver', REFLECTION_TRIGGER]);
+const REFLECTION_TOOLS = ['read', 'grep', 'find', 'ls'];
+/** The same floor refinement keeps for a trajectory (INV-REF-8). */
+const OBS_TRUNC = 10_000;
+const slug = (text) => text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60).replace(/-+$/, '') || 'lesson';
+/** The lessons the Wiki keeps now. */
+export function keptLessons(root) {
+    return notes.paths(root).filter((path) => path.startsWith(`${LESSONS_FOLDER}/`)).flatMap((path) => {
+        try {
+            const text = readFileSync(join(notes.wikiDir(root), `${path}.md`), 'utf8');
+            const parsed = frontmatter.parse(text);
+            const front = parsed?.front ?? {};
+            const sources = Array.isArray(front.sources) ? front.sources.filter((id) => typeof id === 'string') : [];
+            return [{ path, cue: typeof front.cue === 'string' ? front.cue : '', sources, front, body: parsed?.body ?? text }];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+/** The model the run used, as Pi names it, from its last usage report. */
+function modelOf(root, runId) {
+    const usage = readEvents(root, runId).filter((event) => event.type === 'usage.updated').at(-1)?.payload;
+    return typeof usage?.model === 'string' && typeof usage.provider === 'string' ? `${usage.provider}/${usage.model}` : null;
+}
+function lessonNote(experience, sources) {
+    const title = experience.cue.length > 80 ? `${experience.cue.slice(0, 77).trimEnd()}…` : experience.cue;
+    const body = [`# ${title}`, '', `**When:** ${experience.cue}`, '', `**Do:** ${experience.lesson}`, '', `**Evidence:** ${experience.evidence}`].join('\n');
+    return frontmatter.serialize({ title, cue: experience.cue, confidence: experience.confidence ?? null, sources }, body);
+}
+export class Lessons {
+    options;
+    queue = [];
+    abort = new AbortController();
+    draining = null;
+    closed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Called when a run completes. Cheap: the work happens later, one run at a time. */
+    consider(run) {
+        if (this.closed || !run || run.status !== 'completed' || run.parentRunId || run.relation)
+            return;
+        if (run.trigger && SKIPPED_TRIGGERS.has(run.trigger))
+            return;
+        if (this.queue.includes(run.id))
+            return;
+        this.queue.push(run.id);
+        this.draining ??= this.drain().finally(() => {
+            this.draining = null;
+        });
+    }
+    /** Resolves when everything queued so far was reflected on. */
+    async idle() {
+        while (this.draining)
+            await this.draining;
+    }
+    async close() {
+        this.closed = true;
+        this.queue.length = 0;
+        this.abort.abort();
+        await this.draining?.catch(() => undefined);
+    }
+    async drain() {
+        while (this.queue.length && !this.closed) {
+            const runId = this.queue.shift();
+            try {
+                const outcome = await this.reflect(runId);
+                if (outcome.kind !== 'skipped')
+                    log(`lessons: run ${runId}: ${outcome.kind}${'path' in outcome ? ` ${outcome.path}` : ''}`);
+            }
+            catch (error) {
+                log(`lessons: run ${runId} was not reflected on`, error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    /** The plugin's settings for this run's caller, or null when it is off for them. */
+    limits(root, runId) {
+        const contribution = `${LESSONS}/code/${LESSONS_CODE}`;
+        if (!loadCapabilities(root, runId)?.contributions.includes(contribution))
+            return null;
+        const saved = attachments.load(root).settings[LESSONS];
+        const value = (key) => settingValue(LESSONS_SETTINGS.find((setting) => setting.key === key), saved);
+        return { minToolCalls: value('minToolCalls'), maxLessons: value('maxLessons'), maxChars: value('maxChars') };
+    }
+    /** Reflects on one finished run. Exposed for tests and for a host that wants to ask directly. */
+    async reflect(runId) {
+        const root = this.options.root();
+        const run = findRun(root, runId);
+        if (!run || run.status !== 'completed')
+            return { kind: 'skipped', reason: 'not completed' };
+        const limits = this.limits(root, runId);
+        if (!limits)
+            return { kind: 'skipped', reason: 'plugin off' };
+        const events = executionEvents(readEvents(root, runId));
+        if (events.filter((event) => event.type === 'tool.started').length < limits.minToolCalls)
+            return { kind: 'skipped', reason: 'too few tool calls' };
+        const kept = keptLessons(root);
+        if (kept.some((lesson) => lesson.sources.includes(runId)))
+            return { kind: 'skipped', reason: 'already reflected' };
+        if (kept.length >= limits.maxLessons)
+            return { kind: 'skipped', reason: 'lesson limit reached' };
+        const context = mkdtempSync(join(tmpdir(), 'harness-lesson-'));
+        try {
+            const goal = run.goal ? `# Request\n\n${run.goal}\n\n# Record\n\n` : '# Record\n\n';
+            writeFileSync(join(context, 'run.md'), `${goal}${renderEvents(events, { obsTrunc: OBS_TRUNC })}\n`);
+            writeFileSync(join(context, 'lessons.md'), kept.length ? `${kept.map((lesson) => `${lesson.path} -- ${lesson.cue}`).join('\n')}\n` : '(no lessons kept yet)\n');
+            assertNoGraderVerdicts(context);
+            const reflector = this.options.reflector?.(run, modelOf(root, runId), this.abort.signal)
+                ?? new PiImprover(this.options.runtime, join(root, 'reflection'), { accountId: run.accountId, model: modelOf(root, runId), effort: 'medium' }, this.abort.signal, { trigger: REFLECTION_TRIGGER, identity: REFLECTION_IDENTITY, tools: REFLECTION_TOOLS });
+            const reply = await reflector.call({ mission: lessonMission(), contextDir: context, label: `lesson-${runId}`, signal: this.abort.signal });
+            return this.keep(root, runId, reply.text, kept, limits);
+        }
+        finally {
+            rmSync(context, { recursive: true, force: true });
+        }
+    }
+    keep(root, runId, text, kept, limits) {
+        if (/^\s*NO_ENTRY\s*$/m.test(text) && !text.includes('<experience>'))
+            return { kind: 'no_entry' };
+        const same = /^\s*SAME\s+(\S+)\s*$/m.exec(text)?.[1]?.replace(/\.md$/, '');
+        if (same) {
+            const lesson = kept.find((entry) => entry.path === same);
+            if (!lesson)
+                return { kind: 'skipped', reason: `named an unknown lesson ${same}` };
+            notes.write(root, lesson.path, frontmatter.serialize({ ...lesson.front, sources: [...lesson.sources, runId] }, lesson.body), { actor: REFLECTION_TRIGGER, reason: `Seen again in run ${runId}` });
+            return { kind: 'same', path: lesson.path };
+        }
+        const experience = parseExperience(text);
+        if (!hasExperience(experience))
+            return { kind: 'no_entry' };
+        const body = lessonNote(experience, [runId]);
+        if (`${experience.cue}${experience.lesson}${experience.evidence}`.length > limits.maxChars)
+            return { kind: 'skipped', reason: 'lesson too long' };
+        if (looksSecret(body))
+            return { kind: 'skipped', reason: 'lesson looked like it held a credential' };
+        assertVariantHasNoGraderVerdicts({ 'lesson.md': body });
+        const taken = new Set(notes.paths(root));
+        const base = `${LESSONS_FOLDER}/${slug(experience.cue)}`;
+        let path = base;
+        for (let n = 2; taken.has(path); n++)
+            path = `${base}-${n}`;
+        notes.write(root, path, body, { actor: REFLECTION_TRIGGER, reason: `Lesson from run ${runId}` });
+        return { kind: 'written', path };
+    }
+}

package/dist/sdk/history/recall.d.ts

@@ -0,0 +1,68 @@
+import type { HarnessEnv } from "../core/env.js";
+import type { RunEvent, RunRecord } from "../sessions/contracts.js";
+import { type CallerContext } from "../core/caller.js";
+export interface Passage {
+    /** `user`, `event` (a turn the application started, not the user), `assistant`, or `tool`. */
+    role: 'user' | 'event' | 'assistant' | 'tool';
+    at: string;
+    text: string;
+}
+/** A run as recall sees it: what was asked, what the assistant said, and which tools it used. */
+export declare function passages(run: RunRecord, events: readonly RunEvent[]): Passage[];
+/** Indexes one run from its record and events. Index failures never block a run. */
+export declare function indexRun(root: string, runId: string): void;
+/**
+ * Indexes every run that is missing or whose status changed since it was indexed. Returns how
+ * many were (re)indexed. Called at startup, so earlier conversations are searchable.
+ */
+export declare function sync(root: string): number;
+/**
+ * What a caller may recall. An agent searches its own conversations by default and everything
+ * when it asks; a session only sees session runs in its own project (or its own session when
+ * it has none), never an agent's conversation.
+ */
+export interface Scope {
+    /** Only runs of this session. */
+    sessionId?: string | null;
+    /** Only runs of this mode (`code` for sessions). */
+    mode?: string | null;
+    projectId?: string | null;
+    /** ISO date or timestamp; only passages at or after it. */
+    since?: string | null;
+}
+export interface RecallHit {
+    runId: string;
+    seq: number;
+    role: string;
+    at: string;
+    mode: string;
+    sessionId: string;
+    projectId: string | null;
+    snippet: string;
+}
+export declare function search(root: string, query: string, scope: Scope, limit: number): RecallHit[];
+export interface RecallMessage {
+    seq: number;
+    role: string;
+    at: string;
+    text: string;
+}
+export declare function read(root: string, runId: string): RecallMessage[];
+type Params = Record<string, unknown> | null | undefined;
+/** Who a run belonged to, for a person or a model reading a hit. */
+export declare function sourceLabel(env: HarnessEnv, mode: string, sessionId: string, projectId: string | null): string;
+/** `recall.search` as text for a model. */
+export declare function searchTool(env: HarnessEnv, context: CallerContext, params: Params): string;
+/** `recall.read` as text for a model. */
+export declare function readTool(env: HarnessEnv, context: CallerContext, params: Params): string;
+export interface RecallFilter {
+    sessionId?: string | null;
+    projectId?: string | null;
+    since?: string | null;
+}
+export type RecallResult = RecallHit & {
+    source: string;
+};
+/** A person's search: every conversation and run, narrowed only by the filter. */
+export declare function searchAll(env: HarnessEnv, query: string, filter?: RecallFilter): RecallResult[];
+export {};

package/dist/sdk/history/recall.js

@@ -0,0 +1,199 @@
+import { logLine } from "../core/bus.js";
+import { invalid, notFound } from "../core/errors.js";
+import { all, run as execute, transaction, withIndex } from "../core/index.js";
+import { findProject, listProjects } from "../core/projects.js";
+import { charCount, takeChars } from "../core/text.js";
+import { readAllRuns } from "../sessions/runIndex.js";
+import { findRun, readEvents } from "../sessions/runStore.js";
+import { isSession, projectOf } from "../core/caller.js";
+const PASSAGE_LIMIT = 6000;
+const READ_LIMIT = 12_000;
+const SEARCH_DEFAULT = 8;
+const SEARCH_MAX = 30;
+/** A run as recall sees it: what was asked, what the assistant said, and which tools it used. */
+export function passages(run, events) {
+    const found = [];
+    const goal = run.goal?.trim();
+    if (goal)
+        found.push({ role: goal.startsWith('[App coordination event') ? 'event' : 'user', at: run.startedAt, text: takeChars(goal, PASSAGE_LIMIT) });
+    for (const event of events) {
+        const payload = event.payload;
+        if (event.type === 'message.completed' && payload.role === 'assistant') {
+            const text = typeof payload.text === 'string' ? payload.text.trim() : '';
+            if (text)
+                found.push({ role: 'assistant', at: event.timestamp, text: takeChars(text, PASSAGE_LIMIT) });
+        }
+        else if (event.type === 'tool.started') {
+            const summary = typeof payload.summary === 'string' ? payload.summary.trim() : '';
+            if (summary)
+                found.push({ role: 'tool', at: event.timestamp, text: takeChars(`${typeof payload.name === 'string' ? payload.name : 'tool'}: ${summary}`, PASSAGE_LIMIT) });
+        }
+    }
+    return found;
+}
+function writeRun(database, run, found) {
+    execute(database, 'DELETE FROM recall_fts WHERE run_id = ?1', run.id);
+    found.forEach((passage, seq) => {
+        execute(database, 'INSERT INTO recall_fts (run_id, seq, role, at, mode, session_id, project_id, text) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)', run.id, seq, passage.role, passage.at, run.mode, run.sessionId, run.projectId, passage.text);
+    });
+    execute(database, 'INSERT OR REPLACE INTO recall_runs (run_id, passages, status) VALUES (?1, ?2, ?3)', run.id, found.length, run.status);
+}
+function eventsOf(root, runId) {
+    try {
+        return readEvents(root, runId);
+    }
+    catch {
+        return [];
+    }
+}
+/** Indexes one run from its record and events. Index failures never block a run. */
+export function indexRun(root, runId) {
+    const run = findRun(root, runId);
+    if (!run)
+        return;
+    const found = passages(run, eventsOf(root, runId));
+    try {
+        withIndex(root, (database) => writeRun(database, run, found));
+    }
+    catch (error) {
+        logLine(`[recall] run ${runId} was not indexed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Indexes every run that is missing or whose status changed since it was indexed. Returns how
+ * many were (re)indexed. Called at startup, so earlier conversations are searchable.
+ */
+export function sync(root) {
+    const known = new Map();
+    withIndex(root, (database) => {
+        for (const row of all(database, 'SELECT run_id, status FROM recall_runs'))
+            known.set(row.run_id, row.status);
+    });
+    const pending = readAllRuns(root)
+        .filter((run) => known.get(run.id) !== run.status)
+        .map((run) => ({ run, found: passages(run, eventsOf(root, run.id)) }));
+    if (pending.length)
+        withIndex(root, (database) => transaction(database, () => pending.forEach(({ run, found }) => writeRun(database, run, found))));
+    return pending.length;
+}
+/** Any word may match; passages that match more of them, and rarer ones, rank first. */
+function ftsAny(query) {
+    const terms = [];
+    for (const word of query.split(/[^\p{Alphabetic}\p{N}]+/u)) {
+        if (charCount(word) <= 1)
+            continue;
+        const term = `"${word.toLowerCase()}"*`;
+        if (!terms.includes(term) && terms.length < 24)
+            terms.push(term);
+    }
+    return terms.length ? terms.join(' OR ') : null;
+}
+export function search(root, query, scope, limit) {
+    const fts = ftsAny(query);
+    if (!fts)
+        return [];
+    return withIndex(root, (database) => all(database, `SELECT run_id, seq, role, at, mode, session_id, project_id, snippet(recall_fts, 7, '', '', '…', 40) AS snippet
+       FROM recall_fts WHERE recall_fts MATCH ?1
+         AND (?2 IS NULL OR session_id = ?2) AND (?3 IS NULL OR mode = ?3)
+         AND (?4 IS NULL OR project_id = ?4) AND (?5 IS NULL OR at >= ?5)
+       ORDER BY bm25(recall_fts), at DESC LIMIT ?6`, fts, scope.sessionId ?? null, scope.mode ?? null, scope.projectId ?? null, scope.since ?? null, Math.min(Math.max(limit, 1), SEARCH_MAX)).map((row) => ({ runId: row.run_id, seq: Number(row.seq), role: row.role, at: row.at ?? '', mode: row.mode ?? '', sessionId: row.session_id ?? '', projectId: row.project_id, snippet: row.snippet })));
+}
+export function read(root, runId) {
+    return withIndex(root, (database) => all(database, 'SELECT seq, role, at, text FROM recall_fts WHERE run_id = ?1 ORDER BY CAST(seq AS INTEGER)', runId).map((row) => ({ seq: Number(row.seq), role: row.role, at: row.at ?? '', text: row.text })));
+}
+function textParam(params, key) {
+    const value = params?.[key];
+    return typeof value === 'string' ? value.trim() : '';
+}
+/** The widest scope a caller may use, narrowed by what it asked for. */
+function callerScope(root, context, params) {
+    const since = textParam(params, 'since') || null;
+    if (isSession(context)) {
+        // A session never reads an agent's conversations: only session runs of its project, or its own.
+        const projectId = projectOf(root, context)?.id ?? null;
+        if (!projectId && !context.sessionId)
+            throw invalid('Recall needs a session.');
+        return { sessionId: projectId ? null : context.sessionId, mode: 'code', projectId, since };
+    }
+    if (!context.agentId)
+        throw invalid('Recall needs an agent or a Harness session.');
+    const key = textParam(params, 'project');
+    let projectId = null;
+    if (key) {
+        const project = listProjects(root).find((entry) => entry.id === key || entry.slug === key || entry.name.toLowerCase() === key.toLowerCase());
+        if (!project)
+            throw invalid(`There is no project called ${key}.`);
+        projectId = project.id;
+    }
+    const everything = textParam(params, 'scope') === 'all' || projectId !== null;
+    return { sessionId: everything ? null : context.agentId, mode: null, projectId, since };
+}
+function mayRead(scope, run) {
+    if (!scope.mode)
+        return true;
+    return scope.mode === run.mode && (!scope.projectId || scope.projectId === run.projectId) && (!scope.sessionId || scope.sessionId === run.sessionId);
+}
+/** Who a run belonged to, for a person or a model reading a hit. */
+export function sourceLabel(env, mode, sessionId, projectId) {
+    if (mode === 'chat') {
+        // One of an agent's extra conversations has its own id.
+        const owner = env.directory.sessionAgent(sessionId);
+        const name = env.directory.agentName(sessionId) ?? (owner ? env.directory.agentName(owner) : null);
+        return name ? `chat with ${name}` : 'group or earlier chat';
+    }
+    try {
+        return projectId ? `Harness session in ${findProject(env.root, projectId).name}` : 'Harness session';
+    }
+    catch {
+        return 'Harness session';
+    }
+}
+/** Whether a conversation belongs to an agent the caller may not recall. */
+function excluded(env, context, sessionId) {
+    const hidden = context.recallExcludeAgents ?? [];
+    if (!hidden.length)
+        return false;
+    return hidden.includes(sessionId) || hidden.includes(env.directory.sessionAgent(sessionId) ?? '');
+}
+/** `recall.search` as text for a model. */
+export function searchTool(env, context, params) {
+    const query = textParam(params, 'query');
+    if (!query)
+        throw invalid('Give a query.');
+    const scope = callerScope(env.root, context, params);
+    const requested = params?.limit;
+    const limit = typeof requested === 'number' && Number.isInteger(requested) && requested >= 0 ? requested : SEARCH_DEFAULT;
+    // The caller's current run is what it is in the middle of, not something to recall.
+    const hits = search(env.root, query, scope, limit + 4 + (context.recallExcludeAgents?.length ? SEARCH_MAX : 0)).filter((hit) => hit.runId !== context.runId && !excluded(env, context, hit.sessionId)).slice(0, Math.min(Math.max(limit, 1), SEARCH_MAX));
+    if (!hits.length) {
+        return scope.sessionId && !isSession(context) ? 'Nothing in your own conversations matches. Pass scope "all" to search every conversation and Harness run.' : 'Nothing in the recorded history matches.';
+    }
+    return `${hits.map((hit) => `- [run ${hit.runId} · ${hit.at.slice(0, 10)} · ${sourceLabel(env, hit.mode, hit.sessionId, hit.projectId)}] ${hit.role}: ${hit.snippet.replaceAll('\n', ' ')}`).join('\n')}\n\nRead a whole run with history_read and its run id.`;
+}
+/** `recall.read` as text for a model. */
+export function readTool(env, context, params) {
+    const runId = textParam(params, 'run') || textParam(params, 'runId');
+    const run = findRun(env.root, runId);
+    if (!run)
+        throw notFound('Run');
+    // Reading is as wide as an "all" search for an agent, and as narrow as a search for a session.
+    if (!mayRead(callerScope(env.root, context, { scope: 'all' }), run) || excluded(env, context, run.sessionId))
+        throw notFound('Run');
+    const messages = read(env.root, run.id);
+    if (!messages.length)
+        return 'That run has no recorded messages.';
+    let text = `Run ${run.id} · ${run.startedAt.slice(0, 16)} · ${sourceLabel(env, run.mode, run.sessionId, run.projectId)} · ${run.status}\n`;
+    for (const message of messages) {
+        const line = `\n${message.role}: ${message.text}\n`;
+        if (charCount(text) + charCount(line) > READ_LIMIT) {
+            text += '\n(The rest of the run was left out.)\n';
+            break;
+        }
+        text += line;
+    }
+    return text;
+}
+/** A person's search: every conversation and run, narrowed only by the filter. */
+export function searchAll(env, query, filter = {}) {
+    return search(env.root, query, { sessionId: filter.sessionId, mode: null, projectId: filter.projectId, since: filter.since || null }, SEARCH_MAX).map((hit) => ({ ...hit, source: sourceLabel(env, hit.mode, hit.sessionId, hit.projectId) }));
+}

package/dist/sdk/history/trajectory.d.ts

@@ -0,0 +1,7 @@
+import type { HarnessEnv } from "../core/env.js";
+import type { CallerContext } from "../core/caller.js";
+export type Params = Record<string, unknown> | null | undefined;
+/** `trajectory.search`: structured list/search over the current Harness data root. */
+export declare function searchTool(env: HarnessEnv, context: CallerContext, params: Params): string;
+/** `trajectory.read`: a bounded page of the events that affected a run. */
+export declare function readTool(env: HarnessEnv, context: CallerContext, params: Params): string;

package/dist/sdk/history/trajectory.js

@@ -0,0 +1,216 @@
+import { invalid, notFound } from "../core/errors.js";
+import { listProjects } from "../core/projects.js";
+import { compareText } from "../core/text.js";
+import { scrub } from "../accounts/store.js";
+import { scrubSensitive } from "../mcp/connections.js";
+import { isActiveStatus, runStatusSchema } from "../sessions/contracts.js";
+import { readAllRuns } from "../sessions/runIndex.js";
+import { findRun, snapshot } from "../sessions/runStore.js";
+const SEARCH_DEFAULT = 10;
+const SEARCH_MAX = 30;
+const READ_DEFAULT = 8;
+const READ_MAX = 10;
+const EVENT_MAX_CHARS = 18_000;
+const PAGE_MAX_CHARS = 48_000;
+function textParam(params, key) {
+    const value = params?.[key];
+    return typeof value === 'string' ? value.trim() : '';
+}
+function boundedInteger(params, key, fallback, minimum, maximum) {
+    const value = params?.[key];
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < minimum || value > maximum) {
+        throw invalid(`${key} must be an integer from ${minimum} to ${maximum}.`);
+    }
+    return value;
+}
+function dateValue(params, key) {
+    const value = textParam(params, key);
+    if (!value)
+        return null;
+    if (!/^\d{4}-\d{2}-\d{2}(?:T.*)?$/.test(value))
+        throw invalid(`${key} must be a YYYY-MM-DD date or ISO timestamp.`);
+    const timestamp = Date.parse(/^\d{4}-\d{2}-\d{2}$/.test(value) ? `${value}${key === 'until' ? 'T23:59:59.999Z' : 'T00:00:00.000Z'}` : value);
+    if (!Number.isFinite(timestamp))
+        throw invalid(`${key} must be a valid date or ISO timestamp.`);
+    return { text: value, timestamp };
+}
+function decodeCursor(value) {
+    if (!value)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+        if (typeof parsed.startedAt !== 'string' || !parsed.startedAt || typeof parsed.id !== 'string' || !parsed.id)
+            throw new Error('invalid cursor');
+        return { startedAt: parsed.startedAt, id: parsed.id };
+    }
+    catch {
+        throw invalid('The trajectory cursor is invalid. Start a new search without it.');
+    }
+}
+function encodeCursor(run) {
+    return Buffer.from(JSON.stringify({ startedAt: run.startedAt, id: run.id })).toString('base64url');
+}
+function hidden(env, context, run) {
+    const excluded = context.recallExcludeAgents ?? [];
+    if (!excluded.length)
+        return false;
+    return excluded.includes(run.agentId ?? '') || excluded.includes(run.sessionId) || excluded.includes(env.directory.sessionAgent(run.sessionId) ?? '');
+}
+function afterCursor(run, cursor) {
+    return run.startedAt < cursor.startedAt || (run.startedAt === cursor.startedAt && run.id < cursor.id);
+}
+function summary(env, run, projects) {
+    const project = projects.find((entry) => entry.id === run.projectId);
+    const goal = run.goal?.trim() ?? '';
+    return {
+        id: run.id,
+        agentId: run.agentId,
+        agentName: run.agentId ? env.directory.agentName(run.agentId) : null,
+        project: project ? { id: project.id, name: project.name, slug: project.slug } : null,
+        mode: run.mode,
+        status: run.status,
+        goal: goal.length > 500 ? `${goal.slice(0, 497)}…` : goal || null,
+        startedAt: run.startedAt,
+        endedAt: run.endedAt,
+        parentRunId: run.parentRunId,
+        relation: run.relation
+    };
+}
+/** `trajectory.search`: structured list/search over the current Harness data root. */
+export function searchTool(env, context, params) {
+    const agent = textParam(params, 'agent');
+    const projectKey = textParam(params, 'project');
+    const mode = textParam(params, 'mode');
+    const status = textParam(params, 'status');
+    const since = dateValue(params, 'since');
+    const until = dateValue(params, 'until');
+    const limit = boundedInteger(params, 'limit', SEARCH_DEFAULT, 1, SEARCH_MAX);
+    const cursor = decodeCursor(textParam(params, 'cursor'));
+    if (status && !runStatusSchema.safeParse(status).success)
+        throw invalid(`Unknown run status ${status}.`);
+    const projects = listProjects(env.root);
+    const project = projectKey ? projects.find((entry) => entry.id === projectKey || entry.slug === projectKey || entry.name.toLowerCase() === projectKey.toLowerCase()) : null;
+    if (projectKey && !project)
+        throw invalid(`There is no project called ${projectKey}.`);
+    const matching = readAllRuns(env.root)
+        .filter((run) => !hidden(env, context, run))
+        .filter((run) => !agent || run.agentId === agent || (run.agentId !== null && env.directory.agentName(run.agentId)?.toLowerCase() === agent.toLowerCase()))
+        .filter((run) => !projectKey || run.projectId === project?.id)
+        .filter((run) => !mode || run.mode === mode)
+        .filter((run) => !status || run.status === status)
+        .filter((run) => !since || Date.parse(run.startedAt) >= since.timestamp)
+        .filter((run) => !until || Date.parse(run.startedAt) <= until.timestamp)
+        .filter((run) => !cursor || afterCursor(run, cursor))
+        .sort((left, right) => compareText(right.startedAt, left.startedAt) || compareText(right.id, left.id));
+    const page = matching.slice(0, limit);
+    const hasMore = matching.length > page.length;
+    return JSON.stringify({
+        runs: page.map((run) => summary(env, run, projects)),
+        hasMore,
+        nextCursor: hasMore && page.length ? encodeCursor(page[page.length - 1]) : null
+    });
+}
+function boundedValue(value, path, truncated, stringLimit, arrayLimit, depth = 0) {
+    if (typeof value === 'string') {
+        const fieldLimit = path.endsWith('.systemPrompt') || path.endsWith('.contextUpdate') ? Math.min(12_000, stringLimit) :
+            path.endsWith('.input') || path.endsWith('.output') || path.endsWith('.summary') ? Math.min(10_000, stringLimit) : stringLimit;
+        if (value.length <= fieldLimit)
+            return value;
+        truncated.push(path);
+        return `${value.slice(0, Math.max(0, fieldLimit - 16))}… [truncated]`;
+    }
+    if (Array.isArray(value)) {
+        const kept = value.slice(0, arrayLimit).map((item, index) => boundedValue(item, `${path}[${index}]`, truncated, stringLimit, arrayLimit, depth + 1));
+        if (value.length > arrayLimit)
+            truncated.push(path);
+        return kept;
+    }
+    if (!value || typeof value !== 'object' || depth >= 8)
+        return value;
+    const entries = Object.entries(value);
+    const kept = entries.slice(0, 40).map(([key, item]) => [key, boundedValue(item, `${path}.${key}`, truncated, stringLimit, arrayLimit, depth + 1)]);
+    if (entries.length > 40)
+        truncated.push(path);
+    return Object.fromEntries(kept);
+}
+function publicEvent(event) {
+    let stringLimit = 12_000;
+    let arrayLimit = 20;
+    while (true) {
+        const truncated = [];
+        const omitted = [];
+        let payload = scrubSensitive(event.payload);
+        if (event.type === 'account.status' && payload && typeof payload === 'object' && !Array.isArray(payload)) {
+            const account = payload;
+            if (Object.hasOwn(account, 'accountId')) {
+                delete account.accountId;
+                omitted.push('payload.accountId');
+            }
+            if (typeof account.message === 'string')
+                account.message = scrub(account.message);
+        }
+        if (event.type === 'usage.updated' && payload && typeof payload === 'object' && !Array.isArray(payload)) {
+            const request = payload.request;
+            if (request && typeof request === 'object' && !Array.isArray(request) && Object.hasOwn(request, 'reasoningSummary')) {
+                delete request.reasoningSummary;
+                omitted.push('payload.request.reasoningSummary');
+            }
+        }
+        const value = {
+            id: event.id,
+            sequence: event.sequence,
+            timestamp: event.timestamp,
+            type: event.type,
+            payload: boundedValue(payload, 'payload', truncated, stringLimit, arrayLimit)
+        };
+        if (event.coalescedFrom !== undefined)
+            value.coalescedFrom = event.coalescedFrom;
+        if (truncated.length)
+            value.truncatedFields = truncated.slice(0, 40);
+        if (omitted.length)
+            value.omittedFields = omitted;
+        if (JSON.stringify(value).length <= EVENT_MAX_CHARS || (stringLimit <= 500 && arrayLimit <= 1))
+            return value;
+        stringLimit = Math.max(500, Math.floor(stringLimit / 2));
+        arrayLimit = Math.max(1, Math.floor(arrayLimit / 2));
+    }
+}
+/** `trajectory.read`: a bounded page of the events that affected a run. */
+export function readTool(env, context, params) {
+    const requested = textParam(params, 'run');
+    if (!requested)
+        throw invalid('Give a run id or "current".');
+    const runId = requested === 'current' ? context.runId ?? '' : requested;
+    if (!runId)
+        throw invalid('This caller has no current run.');
+    const run = findRun(env.root, runId);
+    if (!run || hidden(env, context, run))
+        throw notFound('Run');
+    const afterSequence = boundedInteger(params, 'afterSequence', -1, -1, Number.MAX_SAFE_INTEGER);
+    const limit = boundedInteger(params, 'limit', READ_DEFAULT, 1, READ_MAX);
+    const captured = snapshot(env.root, run.id);
+    const candidates = captured.events.filter((event) => event.sequence > afterSequence);
+    const events = [];
+    let eventChars = 0;
+    for (const event of candidates.slice(0, limit)) {
+        const bounded = publicEvent(event);
+        const size = JSON.stringify(bounded).length;
+        if (events.length && eventChars + size > PAGE_MAX_CHARS)
+            break;
+        events.push(bounded);
+        eventChars += size;
+    }
+    const lastSequence = events.length ? Number(events[events.length - 1].sequence) : afterSequence;
+    const hasMore = candidates.some((event) => event.sequence > lastSequence);
+    const projects = listProjects(env.root);
+    const result = {
+        run: summary(env, captured.run, projects),
+        active: isActiveStatus(captured.run.status),
+        events,
+        hasMore,
+        nextAfterSequence: lastSequence
+    };
+    return JSON.stringify(result);
+}