@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/context/attribution.js

@@ -0,0 +1,295 @@
+// Builds one run's context attribution from what the run recorded. Read-only: it opens the run's
+// pack and its events, and never writes either.
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { load } from "../prompt/compile.js";
+import { readEvents } from "../sessions/runStore.js";
+import { materialise } from "../variant/materialise.js";
+/** The house constant: four characters per token, the ratio Pi's own estimator uses. */
+export const CHARS_PER_TOKEN = 4;
+/** Estimated tokens in a number of characters. */
+export function tokensOf(chars) {
+    return Math.max(0, Math.ceil(chars / CHARS_PER_TOKEN));
+}
+/** The harness's own tool groups: their schemas are the released half's cost, not the host's. */
+const HARNESS_TOOL_GROUPS = new Set(['History', 'Wiki', 'Native', 'World', 'Progress', 'Session', 'Annotations']);
+/** Sections the harness writes itself, when a pack was recorded without its delivery record. */
+const FOUNDATION_SECTIONS = new Set(['harness-identity', 'tools', 'reporting']);
+const DYNAMIC_SECTIONS = new Set(['wiki', 'session-state', 'references', 'required-skills']);
+const GROUP_ORDER = ['foundation', 'variant', 'application', 'conversation', 'reserved'];
+function lastEvent(events, type) {
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event?.type === type)
+            return event.payload;
+    }
+    return null;
+}
+function sectionGroup(section, dynamic) {
+    if (dynamic.has(section.id))
+        return 'conversation';
+    if (section.sources.some((source) => source.kind === 'variant'))
+        return 'variant';
+    return FOUNDATION_SECTIONS.has(section.id) ? 'foundation' : 'application';
+}
+/** Characters one recorded tool's schema occupies: its name, description and parameter schema. */
+function toolChars(tool) {
+    try {
+        return JSON.stringify({ name: tool.name, description: tool.description, parameters: tool.parameters }).length;
+    }
+    catch {
+        return tool.name.length + tool.description.length;
+    }
+}
+function shareOf(tokens, window) {
+    if (!window)
+        return null;
+    return Math.max(0, Math.min(100, (tokens / window) * 100));
+}
+/** How many skills a variant folder offers, and roughly what one costs to load. */
+function skillCost(paths) {
+    const sizes = [];
+    for (const path of paths) {
+        let entries;
+        try {
+            entries = readdirSync(path);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            try {
+                const stat = statSync(join(path, entry, 'SKILL.md'));
+                if (stat.isFile())
+                    sizes.push(stat.size);
+            }
+            catch {
+                // A skill without a readable SKILL.md is not counted.
+            }
+        }
+    }
+    if (!sizes.length)
+        return null;
+    const average = sizes.reduce((sum, size) => sum + size, 0) / sizes.length;
+    return { items: sizes.length, tokensEach: tokensOf(average) };
+}
+/** What one variant component costs when it is loaded, read from the variant the run actually used. */
+function onDemandOf(env, pack) {
+    const scope = pack.variant?.scope;
+    if (!scope)
+        return [];
+    let built;
+    try {
+        built = materialise(env.root, { scope });
+    }
+    catch {
+        return [];
+    }
+    const rows = [];
+    const skills = skillCost(built.skillPaths);
+    if (skills)
+        rows.push({ id: 'skills', title: 'Skills (c6)', items: skills.items, tokensEach: skills.tokensEach, note: 'loaded when a situation matches' });
+    if (built.subagents.length)
+        rows.push({ id: 'subagents', title: 'Subagents (c5)', items: built.subagents.length, tokensEach: null, note: 'each runs in its own context' });
+    const scripts = Object.keys(built.files).filter((path) => path.startsWith('scripts/') && !path.endsWith('README.md'));
+    if (scripts.length)
+        rows.push({ id: 'scripts', title: 'Scripts (c7)', items: scripts.length, tokensEach: null, note: 'run, not read into context' });
+    return rows;
+}
+/**
+ * One run's attribution, or null when the run recorded no pack. A run whose latest request the
+ * provider measured is `measured`: its conversation row is the remainder, so the rows add up to the
+ * figure the provider reported rather than to an estimate of their own.
+ */
+export function attribution(env, runId) {
+    const pack = load(env.root, runId);
+    if (!pack)
+        return null;
+    const events = readEvents(env.root, runId);
+    const snapshot = lastEvent(events, 'context.snapshot');
+    const usage = lastEvent(events, 'usage.updated');
+    const sizes = pack.delivery?.sizes;
+    const updatedIds = pack.delivery?.updatedSectionIds ?? [];
+    const dynamic = pack.delivery
+        ? new Set(updatedIds)
+        : new Set([...DYNAMIC_SECTIONS].filter((id) => pack.sections.some((section) => section.id === id)));
+    const stable = pack.sections.filter((section) => !dynamic.has(section.id));
+    const window = typeof usage?.contextWindow === 'number' && usage.contextWindow > 0 ? usage.contextWindow : null;
+    const measuredTokens = typeof usage?.contextTokens === 'number' && usage.contextTokens > 0 ? usage.contextTokens : null;
+    let approximate = !sizes;
+    if (snapshot?.systemPromptTruncated || snapshot?.contextUpdateTruncated || snapshot?.toolsTruncated)
+        approximate = true;
+    const rows = [];
+    for (const section of stable) {
+        const chars = sizes?.system[section.id] ?? section.size;
+        // The tools section ends with the variant's tool guidance: count that part as the variant's.
+        const variantChars = section.id === 'tools' ? Math.min(section.sources.find((source) => source.kind === 'variant')?.chars ?? 0, chars) : 0;
+        const own = Math.max(0, chars - variantChars);
+        if (own > 0) {
+            rows.push({
+                id: section.id,
+                title: section.title,
+                group: sectionGroup(section, dynamic),
+                tokens: tokensOf(own),
+                chars: own,
+                share: null,
+                always: true,
+                estimated: true,
+                budget: section.budget,
+                ...(section.cut ? { cut: true } : {}),
+                ...(section.sources.length ? { sources: section.sources.map((source) => ({ ...source })) } : {})
+            });
+        }
+        if (variantChars > 0) {
+            rows.push({ id: 'tool-guidance', title: 'Tool guidance (c4)', group: 'variant', tokens: tokensOf(variantChars), chars: variantChars, share: null, always: true, estimated: true });
+        }
+    }
+    const framing = sizes?.systemFraming ?? 0;
+    if (framing > 0) {
+        rows.push({ id: 'framing', title: 'Prompt framing', group: 'foundation', tokens: tokensOf(framing), chars: framing, share: null, always: true, estimated: true, note: 'headings and the context-update guidance' });
+    }
+    // Tool schemas, by the owner of the tools: the harness's own groups against the application's.
+    const groupOfTool = new Map();
+    for (const group of pack.toolGroups)
+        for (const name of group.tools)
+            groupOfTool.set(name, group.group);
+    for (const [group, harnessOwned] of [['foundation', true], ['application', false]]) {
+        const owned = (snapshot?.tools ?? []).filter((tool) => HARNESS_TOOL_GROUPS.has(groupOfTool.get(tool.name) ?? '') === harnessOwned);
+        if (!owned.length)
+            continue;
+        const chars = owned.reduce((sum, tool) => sum + toolChars(tool), 0);
+        const byGroup = new Map();
+        for (const tool of owned) {
+            const name = groupOfTool.get(tool.name) ?? 'Other tools';
+            byGroup.set(name, (byGroup.get(name) ?? 0) + 1);
+        }
+        rows.push({
+            id: harnessOwned ? 'tools-harness' : 'tools-application',
+            title: `Tool schemas · ${owned.length} ${owned.length === 1 ? 'tool' : 'tools'}`,
+            group,
+            tokens: tokensOf(chars),
+            chars,
+            share: null,
+            always: true,
+            estimated: true,
+            tools: [...byGroup].map(([name, count]) => ({ group: name, count }))
+        });
+    }
+    // What arrived as this request's context update, and the messages it joined.
+    for (const id of updatedIds) {
+        const section = pack.sections.find((entry) => entry.id === id);
+        if (!section)
+            continue;
+        const chars = sizes?.update[section.id] ?? section.size;
+        if (!chars)
+            continue;
+        rows.push({ id: section.id, title: section.title, group: 'conversation', tokens: tokensOf(chars), chars, share: null, always: false, estimated: true });
+    }
+    const updateFraming = updatedIds.length ? sizes?.updateFraming ?? 0 : 0;
+    if (updateFraming > 0) {
+        // The update message's own words, which carry the sections below into history.
+        rows.push({ id: 'context-update', title: 'Context update framing', group: 'conversation', tokens: tokensOf(updateFraming), chars: updateFraming, share: null, always: false, estimated: true, note: 'the message the sections arrived in' });
+    }
+    const prefix = rows.slice();
+    let prefixTokens = prefix.reduce((sum, row) => sum + row.tokens, 0);
+    let note = approximate
+        ? 'The pack was recorded without every per-section size, so the split is approximate.'
+        : 'Rows are estimated from recorded characters, four per token, and reconciled to the measured request.';
+    let messages = 0;
+    let source = 'estimate';
+    if (measuredTokens !== null) {
+        source = 'measured';
+        const remainder = measuredTokens - prefixTokens;
+        if (remainder >= 0)
+            messages = remainder;
+        else {
+            // The estimate overshot the provider's figure: scale the prefix down and say so, never go negative.
+            const scale = prefixTokens > 0 ? measuredTokens / prefixTokens : 0;
+            for (const row of prefix) {
+                row.tokens = Math.max(0, Math.floor(row.tokens * scale));
+                row.note = 'scaled to the measured total';
+            }
+            prefixTokens = prefix.reduce((sum, row) => sum + row.tokens, 0);
+            messages = 0;
+            note = 'The estimated prefix exceeded the measured request, so every row was scaled down to it.';
+        }
+        rows.push({ id: 'messages', title: 'Messages and tool results', group: 'conversation', tokens: messages, chars: null, share: null, always: false, estimated: false, note: 'measured by subtraction' });
+    }
+    else {
+        note = `${note} No request has been measured yet.`;
+    }
+    const reserve = snapshot?.compaction?.enabled === true ? Math.max(0, Math.round(snapshot.compaction.reserveTokens)) : null;
+    if (reserve !== null) {
+        rows.push({ id: 'compaction-reserve', title: 'Compaction reserve', group: 'reserved', tokens: reserve, chars: null, share: null, always: true, estimated: true, note: 'Pi, auto-compaction' });
+    }
+    for (const row of rows)
+        row.share = shareOf(row.tokens, window);
+    const used = measuredTokens ?? prefixTokens;
+    const free = window === null ? null : Math.max(0, window - used - (reserve ?? 0));
+    const totals = { foundation: 0, variant: 0, application: 0, conversation: 0, reserved: 0 };
+    for (const row of rows)
+        totals[row.group] += row.tokens;
+    // One point per measured request, and where each compaction cut the window back.
+    const history = [];
+    const compactions = [];
+    for (const event of events) {
+        if (event.type === 'usage.updated') {
+            const payload = event.payload;
+            const used = typeof payload.contextTokens === 'number' ? payload.contextTokens : null;
+            const request = typeof payload.request?.index === 'number' ? payload.request.index : null;
+            // A provider that reports totals only still advances a request count.
+            const index = request ?? (typeof payload.request === 'number' ? payload.request : null);
+            if (used === null || index === null)
+                continue;
+            history.push({ request: index, used, share: shareOf(used, window), at: event.timestamp });
+        }
+        else if (event.type === 'compaction.ended') {
+            const payload = event.payload;
+            compactions.push({ at: event.timestamp, before: typeof payload.tokensBefore === 'number' ? payload.tokensBefore : null, after: typeof payload.tokensAfter === 'number' ? payload.tokensAfter : null });
+        }
+    }
+    return {
+        runId,
+        model: usage?.model ?? null,
+        provider: usage?.provider ?? null,
+        window,
+        used,
+        share: shareOf(used, window),
+        source,
+        request: typeof usage?.request?.index === 'number' ? usage.request.index : null,
+        compaction: reserve === null ? null : { enabled: true, reserveTokens: reserve },
+        free,
+        rows: rows.sort((left, right) => GROUP_ORDER.indexOf(left.group) - GROUP_ORDER.indexOf(right.group)),
+        history,
+        compactions,
+        onDemand: onDemandOf(env, pack),
+        totals,
+        recordedAt: pack.compiledAt ?? null,
+        note
+    };
+}
+/** One row's text, for a surface that shows what a row actually contributed. */
+export function rowText(env, runId, rowId) {
+    const pack = load(env.root, runId);
+    if (!pack)
+        return null;
+    if (rowId === 'tools-harness' || rowId === 'tools-application') {
+        const events = readEvents(env.root, runId);
+        const tools = lastEvent(events, 'context.snapshot')?.tools ?? [];
+        if (!tools.length)
+            return null;
+        const names = new Map();
+        for (const group of pack.toolGroups)
+            for (const name of group.tools)
+                names.set(name, group.group);
+        const harnessOwned = rowId === 'tools-harness';
+        const lines = tools
+            .filter((tool) => HARNESS_TOOL_GROUPS.has(names.get(tool.name) ?? '') === harnessOwned)
+            .map((tool) => `${names.get(tool.name) ?? 'Other tools'}: ${tool.name}`);
+        return { id: rowId, title: harnessOwned ? 'Harness tool schemas' : 'Application tool schemas', text: lines.join('\n') };
+    }
+    const section = pack.sections.find((entry) => entry.id === rowId);
+    if (!section)
+        return null;
+    return { id: section.id, title: section.title, text: section.body };
+}

package/dist/sdk/context/runDetails.d.ts

@@ -0,0 +1,16 @@
+/** Facts recorded for one run. Null means that the fact was not recorded. */
+export interface RunDetails {
+    runId: string;
+    status: string | null;
+    mode: string | null;
+    model: string | null;
+    effort: string | null;
+    variantScope: string | null;
+    variantVersion: string | null;
+    workspaceRoot: string | null;
+    tools: string[] | null;
+    connectors: string[] | null;
+    skills: string[] | null;
+    plugins: string[] | null;
+}
+export declare function runDetails(root: string, runId: string): RunDetails;

package/dist/sdk/context/runDetails.js

@@ -0,0 +1,22 @@
+import { loadRun as loadCapabilities } from "../capabilities/runSnapshot.js";
+import { loadRun, readEvents } from "../sessions/runStore.js";
+export function runDetails(root, runId) {
+    const run = loadRun(root, runId);
+    const capabilities = loadCapabilities(root, runId);
+    const snapshot = readEvents(root, runId).filter((event) => event.type === 'context.snapshot').at(-1);
+    const payload = snapshot?.payload;
+    return {
+        runId: run.id,
+        status: run.status ?? null,
+        mode: run.effectiveMode ?? null,
+        model: run.model ?? null,
+        effort: run.effort ?? null,
+        variantScope: run.variantScope ?? null,
+        variantVersion: run.variantVersion ?? null,
+        workspaceRoot: run.workspaceRoot ?? null,
+        tools: payload && !payload.toolsTruncated && Array.isArray(payload.tools) ? payload.tools.map((tool) => tool.name) : null,
+        connectors: capabilities?.connectors ?? null,
+        skills: run.loadedSkills ?? null,
+        plugins: run.activatedPlugins ?? null
+    };
+}

package/dist/sdk/context/types.d.ts

@@ -0,0 +1,94 @@
+/** Who owns the text: the released half, the mutably half, the host, or the conversation itself. */
+export type ContextGroup = 'foundation' | 'variant' | 'application' | 'conversation' | 'reserved';
+/** Where a row's characters came from, when the compiler recorded it. */
+export interface ContextRowSource {
+    id: string;
+    kind: string;
+    revision?: string | null;
+    chars?: number;
+}
+/** One contributor to the context window. */
+export interface ContextRow {
+    id: string;
+    title: string;
+    group: ContextGroup;
+    /** Estimated tokens this row occupied in the described request. */
+    tokens: number;
+    /** Characters the estimate came from; null for a remainder or a reservation. */
+    chars: number | null;
+    /** Share of the model's window, 0–100; null when the window is unknown. */
+    share: number | null;
+    /** True when it is part of the stable prefix of every request. */
+    always: boolean;
+    /** False only for a figure the provider reported rather than one this module derived. */
+    estimated: boolean;
+    /** Its character budget, when it has one. */
+    budget?: number;
+    /** The compiler shortened this section to meet its budget. */
+    cut?: boolean;
+    sources?: ContextRowSource[];
+    /** For a tool-schema row: the groups it counts, and how many tools each holds. */
+    tools?: {
+        group: string;
+        count: number;
+    }[];
+    /** Why this figure is not exact, when it is not. */
+    note?: string;
+}
+/** Context that is not in this request but arrives when it is used. */
+export interface ContextOnDemand {
+    id: string;
+    title: string;
+    /** How many items of this kind the variant offers. */
+    items: number;
+    /** Estimated tokens one item costs when it is loaded; null when it loads in its own context. */
+    tokensEach: number | null;
+    note?: string;
+}
+/** One measured request in the run, as the window filled. */
+export interface ContextPoint {
+    /** 1-based model request, as `usage.updated` numbers it. */
+    request: number;
+    used: number;
+    share: number | null;
+    at: string;
+}
+/** A compaction the run went through, and the window it started and ended with. */
+export interface ContextCompaction {
+    at: string;
+    before: number | null;
+    after: number | null;
+}
+/** One run's attribution: the rows, their totals, and how much of the window they account for. */
+export interface ContextAttribution {
+    runId: string;
+    model: string | null;
+    provider: string | null;
+    /** The model's context window; null when nothing reported one. */
+    window: number | null;
+    /** The provider-measured size of the latest request, or the estimate when it measured none. */
+    used: number;
+    /** Used as a share of the window, 0–100; null when the window is unknown. */
+    share: number | null;
+    source: 'measured' | 'estimate';
+    /** Which request the measured total describes (1-based), when the run reported one. */
+    request: number | null;
+    /** Pi's compaction headroom for this run, when the session exposed it. */
+    compaction: {
+        enabled: boolean;
+        reserveTokens: number;
+    } | null;
+    /** The window the request may still grow into, excluding the reserve; null when unknown. */
+    free: number | null;
+    rows: ContextRow[];
+    /** The window at each measured request, oldest first: what grew, which one snapshot cannot show. */
+    history: ContextPoint[];
+    /** Compactions the run went through, oldest first. */
+    compactions: ContextCompaction[];
+    onDemand: ContextOnDemand[];
+    totals: Record<ContextGroup, number>;
+    /** When the run's pack was compiled. */
+    recordedAt: string | null;
+    /** Why the split is approximate, when it is. */
+    note: string | null;
+}

package/dist/sdk/context/types.js

@@ -0,0 +1,10 @@
+// What a request's context window was made of: one figure per contributor, in tokens, reconciled to
+// the size the provider reported for that request. Nothing here formats text: every surface draws
+// these rows its own way.
+//
+// The split is measured where it can be and estimated where it must be. `context.snapshot` records
+// the prompt, the update and every tool schema the run sent; `context.json` records what each
+// section contributed; `usage.updated` records the provider's own figure for the request. Rows are
+// estimated at four characters per token — the ratio Pi, opencode and DeepSeek Harness all use — so
+// the page and the session's own status line cannot disagree by more than rounding.
+export {};

package/dist/sdk/core/bus.d.ts

@@ -0,0 +1,23 @@
+export interface Notice {
+    /** `accounts.changed`, `accounts.login`, `accounts.loginEvent`, `wiki.changed`, `wiki.maintenance`, … */
+    type: string;
+    [key: string]: unknown;
+}
+export type NoticeListener = (notice: Notice) => void;
+export declare class Bus {
+    private readonly listeners;
+    on(listener: NoticeListener): () => void;
+    emit(notice: Notice): void;
+}
+/**
+ * Sends diagnostics somewhere other than stderr, or back to stderr with `null`. A host whose stderr is
+ * the terminal a frontend is drawing on must not write into it, so it sets a sink.
+ */
+export declare function setLogSink(sink: ((text: string) => void) | null): void;
+/** One line of diagnostics. Diagnostics go to stderr by default; stdout may be carrying a protocol. */
+export declare function logLine(text: string): void;
+/** Redacts common credentials and URL query values before diagnostic text is persisted or shown. */
+export declare function redactLogText(text: string): string;
+/** Records useful failure detail without persisting credentials or response bodies. */
+export declare function logDiagnostic(scope: string, error: unknown, metadata?: Record<string, unknown>): void;
+export declare function log(...parts: unknown[]): void;

package/dist/sdk/core/bus.js

@@ -0,0 +1,76 @@
+// Notices: what the harness tells whoever embeds it. Run events travel separately, through the
+// run tracker; a notice says that some state changed and should be read again.
+export class Bus {
+    listeners = new Set();
+    on(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    emit(notice) {
+        for (const listener of this.listeners) {
+            try {
+                listener(notice);
+            }
+            catch (error) {
+                log('a notice listener failed', error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+}
+let logSink = null;
+/**
+ * Sends diagnostics somewhere other than stderr, or back to stderr with `null`. A host whose stderr is
+ * the terminal a frontend is drawing on must not write into it, so it sets a sink.
+ */
+export function setLogSink(sink) {
+    logSink = sink;
+}
+/** One line of diagnostics. Diagnostics go to stderr by default; stdout may be carrying a protocol. */
+export function logLine(text) {
+    if (logSink)
+        logSink(text);
+    else
+        process.stderr.write(`${text}\n`);
+}
+/** Redacts common credentials and URL query values before diagnostic text is persisted or shown. */
+export function redactLogText(text) {
+    return text
+        .replace(/\bBearer\s+\S+/gi, 'Bearer [redacted]')
+        .replace(/(["']?(?:authorization|proxy-authorization|cookie|set-cookie|x-[\w-]{0,64}(?:token|key)|[\w-]{0,64}(?:api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|token|secret|password|client[_-]?secret))["']?\s*[:=]\s*["']?)[^"'\s,;]+/gi, '$1[redacted]')
+        .replace(/\b(?:sk|sess)-[A-Za-z0-9_-]{16,}\b/gi, '[redacted]')
+        .replace(/\bhttps?:\/\/[^\s"'<>]+/gi, (raw) => {
+        const punctuation = /[),.;!?]+$/.exec(raw)?.[0] ?? '';
+        const address = punctuation ? raw.slice(0, -punctuation.length) : raw;
+        try {
+            const url = new URL(address);
+            url.username = '';
+            url.password = '';
+            url.search = '';
+            url.hash = '';
+            return `${url.href}${punctuation}`;
+        }
+        catch {
+            return raw;
+        }
+    });
+}
+/** Records useful failure detail without persisting credentials or response bodies. */
+export function logDiagnostic(scope, error, metadata = {}) {
+    const failure = error instanceof Error ? error : new Error(String(error));
+    const details = {
+        ...metadata,
+        message: failure.message,
+        ...(failure.stack ? { stack: failure.stack } : {})
+    };
+    let serialized;
+    try {
+        serialized = JSON.stringify(details);
+    }
+    catch {
+        serialized = JSON.stringify({ message: failure.message, stack: failure.stack });
+    }
+    logLine(`[harness] ${redactLogText(scope)} ${redactLogText(serialized)}`);
+}
+export function log(...parts) {
+    logLine(`[harness] ${parts.map((part) => (typeof part === 'string' ? part : JSON.stringify(part))).join(' ')}`);
+}

package/dist/sdk/core/caller.d.ts

@@ -0,0 +1,22 @@
+import { type Project } from "./projects.js";
+export interface CallerContext {
+    /** Opaque, host-owned policy data frozen when this session starts. The harness only forwards it to the embedding app's tool policy. */
+    policyContext?: unknown;
+    runId?: string | null;
+    sessionId?: string | null;
+    projectId?: string | null;
+    /** The caller: decides which plugins and connectors reach it, and whose history it recalls. */
+    agentId?: string | null;
+    /** Callers whose conversations this one may not recall (opaque ids from the embedding host). */
+    recallExcludeAgents?: string[] | null;
+    /** The caller's name, recorded on what it writes. */
+    agentName?: string | null;
+    /** `Chat` for an agent's own conversation, `Code` for a session in a project. */
+    actor?: string | null;
+    /** `cli` when the caller reaches the harness through a terminal command. */
+    surface?: string | null;
+}
+export declare const isSession: (context: CallerContext) => boolean;
+export declare const actorOf: (context: CallerContext) => string;
+export declare const usesCli: (context: CallerContext) => boolean;
+export declare function projectOf(root: string, context: CallerContext): Project | null;

package/dist/sdk/core/caller.js

@@ -0,0 +1,16 @@
+// Who a session works as. The embedding application supplies this when a session starts; the
+// harness never looks an agent up by itself. The ids are opaque to the harness.
+import { findProject } from "./projects.js";
+export const isSession = (context) => context.actor === 'Code';
+export const actorOf = (context) => (isSession(context) ? 'Code' : 'Chat');
+export const usesCli = (context) => context.surface === 'cli';
+export function projectOf(root, context) {
+    if (!context.projectId)
+        return null;
+    try {
+        return findProject(root, context.projectId);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/sdk/core/changes.d.ts

@@ -0,0 +1,15 @@
+export interface Change {
+    /** The Wiki folder the entry is in. */
+    wiki: string;
+    id: string;
+    /** The file that was written. */
+    path: string;
+    /** Its new contents, front matter included. */
+    text: string;
+    actor: string;
+    reason: string;
+}
+type Listener = (change: Change) => void;
+export declare function noteChange(change: Change): void;
+export declare function onChange(listener: Listener): () => void;
+export {};

package/dist/sdk/core/changes.js

@@ -0,0 +1,15 @@
+const listeners = new Set();
+export function noteChange(change) {
+    for (const listener of listeners) {
+        try {
+            listener(change);
+        }
+        catch {
+            // A listener must never break the write it is told about.
+        }
+    }
+}
+export function onChange(listener) {
+    listeners.add(listener);
+    return () => void listeners.delete(listener);
+}

package/dist/sdk/core/commandBudget.d.ts

@@ -0,0 +1,23 @@
+/** What a command gets when the caller says nothing. */
+export declare const DEFAULT_COMMAND_TIMEOUT_SECONDS = 120;
+/** Past this, a call must say why it needs longer. */
+export declare const COMMAND_TIMEOUT_CEILING_SECONDS = 300;
+/** The longest a single command may run at all. */
+export declare const COMMAND_TIMEOUT_MAX_SECONDS = 900;
+export type CommandTimeout = {
+    ok: true;
+    timeout: number;
+} | {
+    ok: false;
+    message: string;
+};
+/** Resolves a requested timeout against the default, the ceiling and the maximum. */
+export declare function resolveCommandTimeout(requested: unknown, reason: unknown): CommandTimeout;
+/** A command's result when it was stopped by the budget rather than finishing. */
+export declare function commandTimeoutText(seconds: number, output: string): string;
+/**
+ * Runs a command with a wall-clock budget. The abort reaches the live shell, so the promise
+ * settles instead of leaving the reply blocked; a timeout is reported as a rejection the caller
+ * turns into a tool result.
+ */
+export declare function withCommandBudget<T>(run: () => Promise<T>, abort: (() => void) | undefined, seconds: number): Promise<T>;