@xingular/harness 0.1.7 → 1.1.1

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 = ?', run.id);
+    found.forEach((passage, seq) => {
+        execute(database, 'INSERT INTO recall_fts (run_id, seq, role, at, mode, session_id, project_id, text) VALUES (?, ?, ?, ?, ?, ?, ?, ?)', 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 (?, ?, ?)', 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 ?
+         AND (? IS NULL OR session_id = ?) AND (? IS NULL OR mode = ?)
+         AND (? IS NULL OR project_id = ?) AND (? IS NULL OR at >= ?)
+       ORDER BY bm25(recall_fts), at DESC LIMIT ?`, fts, scope.sessionId ?? null, scope.sessionId ?? null, scope.mode ?? null, scope.mode ?? null, scope.projectId ?? null, scope.projectId ?? null, scope.since ?? 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 = ? 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/serverMethods.d.ts

@@ -0,0 +1,3 @@
+import type { Harness } from "../harness.js";
+import type { Handler } from "../server/rpc.js";
+export declare function historyServerMethods(harness: Harness): Record<string, Handler>;

package/dist/sdk/history/serverMethods.js

@@ -0,0 +1,8 @@
+import * as recall from "./recall.js";
+import { text } from "../server/params.js";
+export function historyServerMethods(harness) {
+    return {
+        'recall.search': (params) => recall.searchAll(harness.env, typeof params.query === 'string' ? params.query : '', params.filter ?? {}),
+        'recall.read': (params) => recall.read(harness.env.root, text(params, 'runId'))
+    };
+}

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;