@xingular/harness 2.0.0 → 2.0.1-unstable

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;

package/dist/sdk/history/trajectory.js

@@ -0,0 +1,218 @@
+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,
+        terminalReason: run.terminalReason ?? null,
+        terminalCode: run.terminalCode ?? null,
+        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);
+}

package/dist/sdk/hub/catalog.json

@@ -0,0 +1,123 @@
+{
+    "schemaVersion": 1,
+    "entries": [
+        {
+            "id": "xingular/evidence-first",
+            "title": "Evidence first",
+            "description": "Keep observations, inferences, and unknowns distinct.",
+            "publisher": "Xingular",
+            "license": "MIT",
+            "version": "1.0.0",
+            "category": "rule",
+            "channel": "official",
+            "tags": [
+                "rule"
+            ],
+            "requires": {
+                "harness": "0.1.6"
+            },
+            "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/evidence-first/1.0.0",
+            "delivery": {
+                "kind": "registry",
+                "registryKind": "rules",
+                "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/evidence-first/1.0.0/payload.json",
+                "sha256": "0f77661ea41e27bcb51aad982d15d493b893c5c1ba1eb6046a21315ddac07c5b",
+                "bundled": "{\n  \"items\": [\n    {\n      \"name\": \"hub-evidence-first\",\n      \"files\": [\n        {\n          \"path\": \"CONTENT.md\",\n          \"encoding\": \"utf8\",\n          \"content\": \"---\\nname: Evidence first\\ndescription: Distinguish observations, inferences, and unknowns.\\n---\\n\\nSupport factual claims with inspectable evidence. Label inferences and uncertainties. Correct a claim when better evidence changes it.\\n\"\n        }\n      ]\n    }\n  ]\n}\n"
+            }
+        },
+        {
+            "id": "xingular/github-connector",
+            "title": "GitHub connector",
+            "description": "A setup recipe for the GitHub MCP server; provide your own credentials.",
+            "publisher": "Xingular",
+            "license": "MIT",
+            "version": "1.0.0",
+            "category": "connector",
+            "channel": "official",
+            "tags": [
+                "connector"
+            ],
+            "requires": {
+                "harness": "0.1.6"
+            },
+            "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/github-connector/1.0.0",
+            "delivery": {
+                "kind": "document",
+                "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/github-connector/1.0.0/payload.json",
+                "sha256": "ec5bd9675e2977b9d880cf81732d84ac72b04af271048499415eaa6288896223",
+                "bundled": "{\n  \"id\": \"github-hub\",\n  \"name\": \"GitHub\",\n  \"description\": \"Repositories, issues, and pull requests\",\n  \"kind\": \"remote\",\n  \"docsUrl\": \"https://github.com/github/github-mcp-server\",\n  \"url\": \"https://api.githubcopilot.com/mcp/\",\n  \"auth\": \"headers\",\n  \"oauth\": null,\n  \"fields\": [\n    {\n      \"header\": \"Authorization\",\n      \"label\": \"Personal access token\",\n      \"prefix\": \"Bearer \",\n      \"help\": \"Provide a token for only the repositories and permissions you need.\"\n    }\n  ],\n  \"setup\": [\n    \"Create a personal access token in GitHub with the access you want to grant.\",\n    \"Review the connection before enabling it.\"\n  ],\n  \"notice\": null,\n  \"provenance\": null,\n  \"suggestedReadTools\": []\n}\n"
+            }
+        },
+        {
+            "id": "xingular/research-starter",
+            "title": "Research starter",
+            "description": "A starting agent for comparing sources and writing supported answers.",
+            "publisher": "Xingular",
+            "license": "MIT",
+            "version": "1.0.0",
+            "category": "agent-template",
+            "channel": "official",
+            "tags": [
+                "agent-template"
+            ],
+            "requires": {
+                "harness": "0.1.6"
+            },
+            "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/research-starter/1.0.0",
+            "delivery": {
+                "kind": "document",
+                "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/research-starter/1.0.0/payload.json",
+                "sha256": "a2f672583df6f4049cc153ba1e173192301220e5f8817f9ad5a4fe87af25f52b",
+                "bundled": "{\n  \"schemaVersion\": 1,\n  \"id\": \"research-starter\",\n  \"title\": \"Research starter\",\n  \"description\": \"Compare sources and explain the evidence behind an answer.\",\n  \"version\": \"1.0.0\",\n  \"author\": \"Xingular\",\n  \"license\": \"MIT\",\n  \"agent\": {\n    \"name\": \"Research starter\",\n    \"icon\": {\n      \"kind\": \"mascot\",\n      \"shape\": \"prism\",\n      \"color\": \"violet\",\n      \"material\": \"glass\"\n    },\n    \"description\": \"Investigates questions with sources.\",\n    \"instructions\": \"Help the user investigate a question. Start with reliable sources, explain what the evidence supports, cite the sources, and state unresolved questions. Ask the user when their goal is unclear.\",\n    \"model\": null,\n    \"effort\": \"high\",\n    \"tools\": [\n      \"read\",\n      \"grep\",\n      \"find\",\n      \"ls\",\n      \"web_search\",\n      \"web_fetch\"\n    ]\n  },\n  \"skills\": [],\n  \"connections\": []\n}\n"
+            }
+        },
+        {
+            "id": "xingular/source-review",
+            "title": "Review a source",
+            "description": "Check who wrote a source, what it supports, and what remains uncertain.",
+            "publisher": "Xingular",
+            "license": "MIT",
+            "version": "1.0.0",
+            "category": "skill",
+            "channel": "official",
+            "tags": [
+                "skill"
+            ],
+            "requires": {
+                "harness": "0.1.6"
+            },
+            "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/source-review/1.0.0",
+            "delivery": {
+                "kind": "registry",
+                "registryKind": "skills",
+                "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/source-review/1.0.0/payload.json",
+                "sha256": "bb0617889ee1ca39611a10952bec3086fa3986e9ce10a809c473c57acf47bc07",
+                "bundled": "{\n  \"items\": [\n    {\n      \"name\": \"hub-source-review\",\n      \"files\": [\n        {\n          \"path\": \"SKILL.md\",\n          \"encoding\": \"utf8\",\n          \"content\": \"---\\nname: hub-source-review\\ndescription: Review the evidence behind a source before using its claims.\\n---\\n\\n# Review a source\\n\\nRecord its author and date. Identify the original evidence. Write what the source supports and which uncertainties remain. Cite the source so the reader can inspect it.\\n\"\n        }\n      ]\n    }\n  ]\n}\n"
+            }
+        },
+        {
+            "id": "xingular/summarize-source",
+            "title": "Summarize a source",
+            "description": "Summarize a provided source and explain its limitations.",
+            "publisher": "Xingular",
+            "license": "MIT",
+            "version": "1.0.0",
+            "category": "prompt",
+            "channel": "official",
+            "tags": [
+                "prompt"
+            ],
+            "requires": {
+                "harness": "0.1.6"
+            },
+            "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/summarize-source/1.0.0",
+            "delivery": {
+                "kind": "registry",
+                "registryKind": "prompts",
+                "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/summarize-source/1.0.0/payload.json",
+                "sha256": "12a646d474fe3cd822970869c972d1d9400c7f6350388dc735dce5c31a22680a",
+                "bundled": "{\n  \"items\": [\n    {\n      \"name\": \"hub-summarize-source\",\n      \"files\": [\n        {\n          \"path\": \"CONTENT.md\",\n          \"encoding\": \"utf8\",\n          \"content\": \"---\\nname: summarize-source\\ndescription: Summarize the supplied source and its limits.\\n---\\n\\nSummarize the source below. Include its main claims, supporting evidence, limitations, and questions it leaves unanswered.\\n\\n$@\\n\"\n        }\n      ]\n    }\n  ]\n}\n"
+            }
+        }
+    ]
+}

package/dist/sdk/hub/cli.d.ts

@@ -0,0 +1,7 @@
+import { Harness, type HarnessOptions } from "../harness.js";
+export declare const HUB_USAGE = "Usage: xagent hub <list | show | install> [id@version] [options]\n\n  list [--refresh]             Browse the curated catalog and locally installed versions\n  show <id@version>            Show publisher, license, source, and delivery details\n  install <id@version>         Install the exact reviewed version, disabled and untrusted\n\n  --data <dir>                 Target data library (default: ~/.xingular-harness/data)\n  --state <dir>                Target device state (default: ~/.xingular-harness/state)\n  --refresh                    Refresh the public catalog; cached items remain usable offline\n";
+export declare function runHubCli(argv: string[], dependencies?: {
+    home?: string;
+    write?: (text: string) => void;
+    createHarness?: (options: HarnessOptions) => Harness;
+}): Promise<number>;