@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/variant/store.d.ts

@@ -0,0 +1,114 @@
+import { type SurfaceSpec, type Variant } from "./surface.js";
+import { type VariantCensus, type VariantDiff, type ValidateOptions } from "./variant.js";
+/** A stable digest of a variant: the same files with the same text give the same value. */
+export declare function fingerprint(variant: Variant): string;
+export type VersionSource = {
+    kind: 'seed';
+    note?: string;
+} | {
+    kind: 'edit';
+    note?: string;
+    components?: string[];
+} | {
+    kind: 'refinement';
+    refineId: string;
+    label: string;
+    note?: string;
+} | {
+    kind: 'import';
+    note?: string;
+} | {
+    kind: 'restore';
+    from: string;
+    note?: string;
+};
+export interface VersionRecord {
+    fingerprint: string;
+    parent: string | null;
+    source: VersionSource;
+    createdAt: string;
+    census: VariantCensus;
+    /** The model the executions ran on when a refinement produced this version. */
+    tunedFor?: {
+        model: string;
+    } | null;
+}
+/** A version as lineage reports it: its record and the tags that name it now. */
+export type LineageEntry = VersionRecord & {
+    tags: string[];
+};
+export interface Head {
+    fingerprint: string;
+    updatedAt: string;
+}
+export declare function variantsDir(root: string): string;
+export declare function scopes(root: string): string[];
+export declare function head(root: string, scope: string): Head | null;
+export declare function exists(root: string, scope: string, fp: string): boolean;
+export declare function readVersion(root: string, scope: string, fp: string, surface?: SurfaceSpec): Variant;
+export declare function versionRecord(root: string, scope: string, fp: string): VersionRecord | null;
+/** Where a version's files are on disk, for a run that loads them. */
+export declare function versionPath(root: string, scope: string, fp: string): string;
+/** The head variant, or null when the scope has none yet. */
+export declare function headVariant(root: string, scope: string, surface?: SurfaceSpec): {
+    fingerprint: string;
+    variant: Variant;
+} | null;
+/** Every version recorded for a scope, newest first. */
+export declare function lineage(root: string, scope: string): LineageEntry[];
+export interface CommitOptions {
+    /** Move the head to the new version (the default). */
+    moveHead?: boolean;
+    surface?: SurfaceSpec;
+    validate?: ValidateOptions;
+    /** Recorded on a new version only; an existing version is never edited. */
+    tunedFor?: {
+        model: string;
+    } | null;
+}
+/**
+ * Saves `variant` as a version of `scope`. An invalid variant is refused with every problem listed.
+ * Saving a variant that already exists records nothing new but can still move the head.
+ */
+export declare function commit(root: string, scope: string, variant: Variant, source: VersionSource, options?: CommitOptions): VersionRecord;
+/** Gives a scope its first version, unless it already has a head. */
+export declare function seed(root: string, scope: string, variant: Variant, note?: string, surface?: SurfaceSpec): Head;
+/** Points the head at an earlier version. The version must exist. */
+export declare function restore(root: string, scope: string, fp: string, note?: string): Head;
+export interface FileDiff {
+    path: string;
+    before: string | null;
+    after: string | null;
+}
+/** What changed between two versions, file by file. */
+export declare function compare(root: string, scope: string, from: string, to: string, surface?: SurfaceSpec): {
+    summary: VariantDiff;
+    files: FileDiff[];
+};
+/** Reads a variant folder made outside the harness, such as an export or a hand-written one. */
+export declare function importFolder(dir: string, surface?: SurfaceSpec): {
+    variant: Variant;
+    rejected: string[];
+};
+/** Reads one file of a variant on disk; used by callers that only need one component. */
+export declare function readComponentFile(root: string, scope: string, fp: string, rel: string): string | null;
+/** Every tag of a scope, name → fingerprint. */
+export declare function tags(root: string, scope: string): Record<string, string>;
+/** Refuses a name that cannot be a tag. */
+export declare function checkTagName(name: string): string;
+/** Names a version. A tag already in use moves to this version. */
+export declare function tag(root: string, scope: string, name: string, fp: string): Record<string, string>;
+export declare function untag(root: string, scope: string, name: string): Record<string, string>;
+/** A fingerprint, a tag, or `head`, as the fingerprint it names. */
+export declare function resolveRef(root: string, scope: string, ref: string): string;
+/**
+ * Whether a selector names a path. A selector is a component (`c4` or `toolGuidance`) or one item
+ * by its path prefix (`skills/review`, `sub_agents/reader`, `scripts/check.py`, `plugins/guard.ts`).
+ */
+export declare function selects(surface: SurfaceSpec, selector: string, rel: string): boolean;
+/**
+ * Makes a new version from the head with the selected components taken from version `from`:
+ * what the head has there is dropped, what `from` has there is copied. The result is validated
+ * like any other edit, and the head moves to it.
+ */
+export declare function revertComponents(root: string, scope: string, from: string, selectors: string[], note?: string, surface?: SurfaceSpec): VersionRecord;

package/dist/sdk/variant/store.js

@@ -0,0 +1,256 @@
+// Versioned variants. Each scope (an opaque id the application chooses, such as one per
+// agent) has content-addressed versions, a head, and a lineage that says where each version came
+// from. A run uses the head it started with; a change makes a new version and never edits one.
+//
+//   <data>/variants/<scope>/versions/<fingerprint>/variant/<rel>
+//   <data>/variants/<scope>/versions/<fingerprint>/version.json
+//   <data>/variants/<scope>/head.json
+//   <data>/variants/<scope>/lineage.jsonl
+//   <data>/variants/<scope>/tags.json        name → fingerprint; labels, never versions
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { HarnessError, invalid, notFound } from "../core/errors.js";
+import { appendLine, now, readJson, readText, safeId, writeJson } from "../core/fs.js";
+import { PI_SURFACE, componentOf } from "./surface.js";
+import { diffSummary, readVariant, validate, writeVariant } from "./variant.js";
+/** A stable digest of a variant: the same files with the same text give the same value. */
+export function fingerprint(variant) {
+    const hash = createHash('sha1');
+    for (const rel of Object.keys(variant).sort()) {
+        hash.update(rel);
+        hash.update('\0');
+        hash.update(variant[rel]);
+        hash.update('\0');
+    }
+    return hash.digest('hex').slice(0, 16);
+}
+export function variantsDir(root) {
+    return join(root, 'variants');
+}
+function scopeDir(root, scope) {
+    return join(variantsDir(root), safeId(scope));
+}
+function versionDir(root, scope, fp) {
+    if (!/^[0-9a-f]{16}$/.test(fp))
+        throw invalid('Invalid harness version.');
+    return join(scopeDir(root, scope), 'versions', fp);
+}
+export function scopes(root) {
+    try {
+        return readdirSync(variantsDir(root), { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+    }
+    catch {
+        return [];
+    }
+}
+export function head(root, scope) {
+    return readJson(join(scopeDir(root, scope), 'head.json'));
+}
+export function exists(root, scope, fp) {
+    return existsSync(join(versionDir(root, scope, fp), 'version.json'));
+}
+export function readVersion(root, scope, fp, surface = PI_SURFACE) {
+    const dir = join(versionDir(root, scope, fp), 'variant');
+    if (!existsSync(dir))
+        throw notFound('That harness version');
+    return readVariant(surface, dir);
+}
+export function versionRecord(root, scope, fp) {
+    return readJson(join(versionDir(root, scope, fp), 'version.json'));
+}
+/** Where a version's files are on disk, for a run that loads them. */
+export function versionPath(root, scope, fp) {
+    return join(versionDir(root, scope, fp), 'variant');
+}
+/** The head variant, or null when the scope has none yet. */
+export function headVariant(root, scope, surface = PI_SURFACE) {
+    const current = head(root, scope);
+    return current ? { fingerprint: current.fingerprint, variant: readVersion(root, scope, current.fingerprint, surface) } : null;
+}
+/** Every version recorded for a scope, newest first. */
+export function lineage(root, scope) {
+    const text = readText(join(scopeDir(root, scope), 'lineage.jsonl')) ?? '';
+    const named = tagsByVersion(root, scope);
+    const out = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const record = JSON.parse(line);
+            out.push({ ...record, tags: named.get(record.fingerprint) ?? [] });
+        }
+        catch {
+            // A torn final line is skipped; the version files are the record.
+        }
+    }
+    return out.reverse();
+}
+/**
+ * Saves `variant` as a version of `scope`. An invalid variant is refused with every problem listed.
+ * Saving a variant that already exists records nothing new but can still move the head.
+ */
+export function commit(root, scope, variant, source, options = {}) {
+    const surface = options.surface ?? PI_SURFACE;
+    let census;
+    try {
+        census = validate(surface, variant, options.validate);
+    }
+    catch (error) {
+        throw new HarnessError('variant_invalid', error instanceof Error ? error.message : String(error), 'Fix the listed problems and save again.');
+    }
+    const fp = fingerprint(variant);
+    const parent = head(root, scope)?.fingerprint ?? null;
+    let record = versionRecord(root, scope, fp);
+    if (!record) {
+        writeVariant(surface, variant, join(versionDir(root, scope, fp), 'variant'), { stubs: false });
+        record = { fingerprint: fp, parent, source, createdAt: now(), census, ...(options.tunedFor?.model ? { tunedFor: { model: options.tunedFor.model } } : {}) };
+        writeJson(join(versionDir(root, scope, fp), 'version.json'), record);
+        appendLine(join(scopeDir(root, scope), 'lineage.jsonl'), JSON.stringify(record));
+    }
+    if (options.moveHead !== false)
+        writeJson(join(scopeDir(root, scope), 'head.json'), { fingerprint: fp, updatedAt: now() });
+    return record;
+}
+/** Gives a scope its first version, unless it already has a head. */
+export function seed(root, scope, variant, note, surface = PI_SURFACE) {
+    const current = head(root, scope);
+    if (current)
+        return current;
+    commit(root, scope, variant, { kind: 'seed', note }, { surface });
+    return head(root, scope);
+}
+/** Points the head at an earlier version. The version must exist. */
+export function restore(root, scope, fp, note) {
+    if (!exists(root, scope, fp))
+        throw notFound('That harness version');
+    const from = head(root, scope)?.fingerprint ?? fp;
+    writeJson(join(scopeDir(root, scope), 'head.json'), { fingerprint: fp, updatedAt: now() });
+    appendLine(join(scopeDir(root, scope), 'restores.jsonl'), JSON.stringify({ to: fp, from, note: note ?? null, at: now() }));
+    return head(root, scope);
+}
+/** What changed between two versions, file by file. */
+export function compare(root, scope, from, to, surface = PI_SURFACE) {
+    const a = readVersion(root, scope, from, surface);
+    const b = readVersion(root, scope, to, surface);
+    const summary = diffSummary(surface, a, b);
+    const files = [...summary.added, ...summary.removed, ...summary.modified].sort().map((path) => ({ path, before: a[path] ?? null, after: b[path] ?? null }));
+    return { summary, files };
+}
+/** Reads a variant folder made outside the harness, such as an export or a hand-written one. */
+export function importFolder(dir, surface = PI_SURFACE) {
+    const rejected = [];
+    const variant = readVariant(surface, dir, rejected);
+    return { variant, rejected };
+}
+/** Reads one file of a variant on disk; used by callers that only need one component. */
+export function readComponentFile(root, scope, fp, rel) {
+    try {
+        return readFileSync(join(versionPath(root, scope, fp), rel), 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+// ---- Tags: names a person gives versions. A tag is a label that can move; a version never changes.
+const TAG = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+function tagsFile(root, scope) {
+    return join(scopeDir(root, scope), 'tags.json');
+}
+/** Every tag of a scope, name → fingerprint. */
+export function tags(root, scope) {
+    return readJson(tagsFile(root, scope)) ?? {};
+}
+function tagsByVersion(root, scope) {
+    const out = new Map();
+    for (const [name, fp] of Object.entries(tags(root, scope)).sort(([a], [b]) => a.localeCompare(b)))
+        out.set(fp, [...(out.get(fp) ?? []), name]);
+    return out;
+}
+/** Refuses a name that cannot be a tag. */
+export function checkTagName(name) {
+    if (!TAG.test(name))
+        throw invalid('A tag is 1-64 letters, digits, dots, dashes or underscores, starting with a letter or digit.');
+    if (/^[0-9a-f]{4,16}$/.test(name) || name === 'head')
+        throw invalid('A tag cannot look like a version fingerprint or be `head`.');
+    return name;
+}
+/** Names a version. A tag already in use moves to this version. */
+export function tag(root, scope, name, fp) {
+    checkTagName(name);
+    if (!exists(root, scope, fp))
+        throw notFound('That harness version');
+    const next = { ...tags(root, scope), [name]: fp };
+    writeJson(tagsFile(root, scope), next);
+    return next;
+}
+export function untag(root, scope, name) {
+    const next = { ...tags(root, scope) };
+    delete next[name];
+    writeJson(tagsFile(root, scope), next);
+    return next;
+}
+/** A fingerprint, a tag, or `head`, as the fingerprint it names. */
+export function resolveRef(root, scope, ref) {
+    if (ref === 'head') {
+        const current = head(root, scope);
+        if (!current)
+            throw invalid(`The variant '${scope}' has no version yet.`);
+        return current.fingerprint;
+    }
+    if (/^[0-9a-f]{16}$/.test(ref)) {
+        if (!exists(root, scope, ref))
+            throw notFound('That harness version');
+        return ref;
+    }
+    const named = tags(root, scope)[ref];
+    if (named)
+        return named;
+    const matches = /^[0-9a-f]{4,15}$/.test(ref) ? lineage(root, scope).filter((entry) => entry.fingerprint.startsWith(ref)) : [];
+    if (matches.length === 1)
+        return matches[0].fingerprint;
+    if (matches.length > 1)
+        throw invalid(`'${ref}' matches more than one version; give more characters.`);
+    throw notFound(`The version or tag '${ref}'`);
+}
+// ---- Reverting part of a variant
+const COMPONENT_ALIASES = {
+    c1: 'systemPrompt', c2: 'guardrails', c3: 'memory', c4: 'toolGuidance', c5: 'subagents', c6: 'skills', c7: 'scripts', c8: 'plugins'
+};
+/**
+ * Whether a selector names a path. A selector is a component (`c4` or `toolGuidance`) or one item
+ * by its path prefix (`skills/review`, `sub_agents/reader`, `scripts/check.py`, `plugins/guard.ts`).
+ */
+export function selects(surface, selector, rel) {
+    const component = COMPONENT_ALIASES[selector.toLowerCase()] ?? surface.components.find((entry) => entry.id === selector)?.id;
+    if (component)
+        return componentOf(surface, rel) === component;
+    const prefix = selector.replace(/\/+$/, '');
+    return rel === prefix || rel.startsWith(`${prefix}/`);
+}
+/**
+ * Makes a new version from the head with the selected components taken from version `from`:
+ * what the head has there is dropped, what `from` has there is copied. The result is validated
+ * like any other edit, and the head moves to it.
+ */
+export function revertComponents(root, scope, from, selectors, note, surface = PI_SURFACE) {
+    if (!selectors.length)
+        throw invalid('Name at least one component to revert, such as c4 or skills/review.');
+    const current = headVariant(root, scope, surface);
+    if (!current)
+        throw invalid(`The variant '${scope}' has no version yet.`);
+    const source = readVersion(root, scope, from, surface);
+    const matched = (selector) => [...Object.keys(current.variant), ...Object.keys(source)].some((rel) => selects(surface, selector, rel));
+    const unknown = selectors.filter((selector) => !matched(selector));
+    if (unknown.length)
+        throw invalid(`Nothing in either version matches: ${unknown.join(', ')}.`);
+    const picked = (rel) => selectors.some((selector) => selects(surface, selector, rel));
+    const next = {};
+    for (const [rel, body] of Object.entries(current.variant))
+        if (!picked(rel))
+            next[rel] = body;
+    for (const [rel, body] of Object.entries(source))
+        if (picked(rel))
+            next[rel] = body;
+    return commit(root, scope, next, { kind: 'edit', components: selectors, note: note ?? `revert ${selectors.join(', ')} from ${from}` }, { surface });
+}

package/dist/sdk/variant/surface.d.ts

@@ -0,0 +1,56 @@
+/** A harness: relative path → file text, for every file on the editable surface. */
+export type Variant = Record<string, string>;
+export type ComponentId = 'systemPrompt' | 'guardrails' | 'memory' | 'toolGuidance' | 'subagents' | 'skills' | 'scripts' | 'plugins';
+/** How a component reaches a run, grouped as the paper groups them. */
+export type ComponentGroup = 'context' | 'toolInterface' | 'orchestration' | 'middleware';
+export interface ComponentInfo {
+    id: ComponentId;
+    /** c1..c8, as numbered in the paper. */
+    index: number;
+    title: string;
+    group: ComponentGroup;
+    /** Where it lives: a file for an always-on component, a pattern for the others. */
+    path: string;
+    /** When it is in a run's context. */
+    reach: 'always' | 'onDemand' | 'ownContext' | 'toolLoop';
+    description: string;
+}
+export interface SurfaceSpec {
+    name: string;
+    /** Files whose whole text is in every run's prompt. */
+    alwaysOn: readonly string[];
+    /** The most always-on characters a variant may carry. */
+    alwaysOnMax: number;
+    alwaysOnCapReason: string;
+    skillDir: string;
+    /** Pi drops a skill whose frontmatter `name` differs from its folder. */
+    skillNameRule: 'must_match' | 'overrides_dir';
+    triggerHint: string;
+    autotriggerFile: string;
+    triggerLine: string;
+    subagentDir: string;
+    scriptDir: string;
+    /** Script file extensions the surface accepts. */
+    scriptExtensions: readonly string[];
+    pluginDir: string;
+    /** Short README files written beside each directory so an editor knows the form. */
+    stubs: readonly (readonly [string, string])[];
+    components: readonly ComponentInfo[];
+}
+export declare const SYSTEM_PROMPT = "systemprompt.md";
+export declare const GUARDRAILS = "guardrails.md";
+export declare const MEMORY = "memory.md";
+export declare const TOOL_GUIDANCE = "tool_guidance.md";
+/** The Pi surface: the one surface this harness runs. */
+export declare const PI_SURFACE: SurfaceSpec;
+export interface SurfacePatterns {
+    skill: RegExp;
+    skillScript: RegExp;
+    subagent: RegExp;
+    script: RegExp;
+    scriptRef: RegExp;
+    plugin: RegExp;
+}
+export declare function patterns(surface: SurfaceSpec): SurfacePatterns;
+/** Which component a path belongs to, or null when it is off the surface. */
+export declare function componentOf(surface: SurfaceSpec, rel: string): ComponentId | null;

package/dist/sdk/variant/surface.js

@@ -0,0 +1,81 @@
+// The editable surface of a harness: the eight components a person or an improver may change,
+// where each lives in the variant, and the rules that keep a variant loadable by Pi.
+//
+// Ported from Harness² (Apache-2.0, Google LLC; `harness2/core/variant.py`, `SurfaceSpec`). The
+// component numbering c1..c8 follows the paper: system prompt, guardrails, memory, tool
+// guidance, subagents, skills, scripts and plugins.
+export const SYSTEM_PROMPT = 'systemprompt.md';
+export const GUARDRAILS = 'guardrails.md';
+export const MEMORY = 'memory.md';
+export const TOOL_GUIDANCE = 'tool_guidance.md';
+/** The Pi surface: the one surface this harness runs. */
+export const PI_SURFACE = {
+    name: 'pi',
+    alwaysOn: [SYSTEM_PROMPT, GUARDRAILS, MEMORY, TOOL_GUIDANCE],
+    alwaysOnMax: 24_000,
+    alwaysOnCapReason: 'every token here competes with the agent\'s own output budget on every run',
+    skillDir: 'skills',
+    skillNameRule: 'must_match',
+    triggerHint: 'Fix it by adding a trigger line naming `{name}` to systemprompt.md or guardrails.md, e.g. "When <the situation this skill handles>, load the `{name}` skill."',
+    autotriggerFile: GUARDRAILS,
+    triggerLine: '- When {desc}, load the `{name}` skill.',
+    subagentDir: 'sub_agents',
+    scriptDir: 'scripts',
+    scriptExtensions: ['.py', '.mjs'],
+    pluginDir: 'plugins',
+    stubs: [
+        ['scripts/README.md', '<!-- c7: deterministic helpers. Add one as scripts/<name>.py or scripts/<name>.mjs; the prompt names the folder they are staged in. -->\n'],
+        ['sub_agents/README.md', '<!-- c5: delegated subagents, started with `spawn_subagent` and `agent: "<name>"`, each in its OWN context. Add one as sub_agents/<name>/AGENT.md with a `description:` in its frontmatter. -->\n'],
+        ['plugins/README.md', '<!-- c8: Pi extensions. They act INSIDE the tool loop -- the only lever that can enforce something the model cannot skip. Add one as plugins/<name>.ts with a default export. New or changed code waits for the person to trust it. -->\n'],
+        ['skills/README.md', '<!-- c6: reusable workflows loaded on demand. Add one as skills/<name>/SKILL.md with frontmatter `name:` matching the folder and a `description:`. -->\n']
+    ],
+    components: [
+        { id: 'systemPrompt', index: 1, title: 'System prompt', group: 'context', path: SYSTEM_PROMPT, reach: 'always', description: 'Role and procedure.' },
+        { id: 'guardrails', index: 2, title: 'Guardrails', group: 'context', path: GUARDRAILS, reach: 'always', description: 'Standing rules the agent keeps on every run.' },
+        { id: 'memory', index: 3, title: 'Memory', group: 'context', path: MEMORY, reach: 'always', description: 'Durable, general facts about this kind of work.' },
+        { id: 'toolGuidance', index: 4, title: 'Tool guidance', group: 'toolInterface', path: TOOL_GUIDANCE, reach: 'always', description: 'How to use the tools well.' },
+        { id: 'subagents', index: 5, title: 'Subagents', group: 'orchestration', path: 'sub_agents/<name>/AGENT.md', reach: 'ownContext', description: 'Bounded helpers that run in their own context and return text.' },
+        { id: 'skills', index: 6, title: 'Skills', group: 'context', path: 'skills/<name>/SKILL.md', reach: 'onDemand', description: 'Reusable workflows loaded when a situation matches.' },
+        { id: 'scripts', index: 7, title: 'Scripts', group: 'toolInterface', path: 'scripts/<name>.py', reach: 'onDemand', description: 'Deterministic helpers the agent runs.' },
+        { id: 'plugins', index: 8, title: 'Plugins', group: 'middleware', path: 'plugins/<name>.ts', reach: 'toolLoop', description: 'Pi extensions that act inside the tool loop.' }
+    ]
+};
+const NAME = '[a-z0-9][a-z0-9_\\-]*';
+const cache = new Map();
+function escape(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export function patterns(surface) {
+    const known = cache.get(surface.name);
+    if (known)
+        return known;
+    const skills = escape(surface.skillDir);
+    const scripts = escape(surface.scriptDir);
+    const extensions = surface.scriptExtensions.map((extension) => escape(extension.slice(1))).join('|');
+    const made = {
+        skill: new RegExp(`^${skills}/(${NAME})/SKILL\\.md$`),
+        skillScript: new RegExp(`^${skills}/${NAME}/scripts/[A-Za-z0-9_.\\-]+$`),
+        subagent: new RegExp(`^${escape(surface.subagentDir)}/(${NAME})/AGENT\\.md$`),
+        script: new RegExp(`^${scripts}/[a-z0-9_][a-z0-9_]*\\.(?:${extensions})$`),
+        scriptRef: new RegExp(`(?:python3?|node)\\s+((?:${skills}/[\\w\\-]+/)?${scripts}/[\\w.\\-]+\\.(?:${extensions}))`, 'g'),
+        plugin: new RegExp(`^${escape(surface.pluginDir)}/(${NAME})\\.ts$`)
+    };
+    cache.set(surface.name, made);
+    return made;
+}
+/** Which component a path belongs to, or null when it is off the surface. */
+export function componentOf(surface, rel) {
+    const found = surface.components.find((component) => component.path === rel);
+    if (found)
+        return found.id;
+    const r = patterns(surface);
+    if (r.skill.test(rel) || r.skillScript.test(rel))
+        return 'skills';
+    if (r.subagent.test(rel))
+        return 'subagents';
+    if (r.script.test(rel))
+        return 'scripts';
+    if (r.plugin.test(rel))
+        return 'plugins';
+    return null;
+}

package/dist/sdk/variant/trust.d.ts

@@ -0,0 +1,27 @@
+import { type Variant } from "./surface.js";
+export interface TrustedPlugin {
+    hash: string;
+    /** The file it was trusted as, for display. */
+    name: string;
+    scope: string | null;
+    trustedAt: string;
+}
+export declare function pluginHash(text: string): string;
+export declare class VariantTrust {
+    private readonly path;
+    constructor(stateDir: string);
+    private read;
+    private write;
+    list(): TrustedPlugin[];
+    has(hash: string): boolean;
+    grant(text: string, name: string, scope: string | null): TrustedPlugin;
+    revoke(hash: string): void;
+    probeCode(scope: string): boolean;
+    setProbeCode(scope: string, on: boolean): void;
+    /** The plugin files of a variant and whether each is trusted. */
+    review(variant: Variant): {
+        path: string;
+        hash: string;
+        trusted: boolean;
+    }[];
+}

package/dist/sdk/variant/trust.js

@@ -0,0 +1,64 @@
+// Plugin code in a variant (c8) runs inside every session's tool loop, so it loads only
+// after a person trusted that exact code: trust is a hash of the file, and a changed file asks
+// again. A person may also let refinement probes run the plugin code an improver wrote for one
+// scope; adopting such a variant still needs the code trusted.
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { now, readJsonOr, safeId, writeJson } from "../core/fs.js";
+import { migrateTrustFile } from "./migrate.js";
+import { patterns, PI_SURFACE } from "./surface.js";
+export function pluginHash(text) {
+    return createHash('sha256').update(text).digest('hex');
+}
+export class VariantTrust {
+    path;
+    constructor(stateDir) {
+        migrateTrustFile(stateDir);
+        this.path = join(stateDir, 'variant-plugin-trust.json');
+    }
+    read() {
+        return readJsonOr(this.path, {});
+    }
+    write(stored) {
+        writeJson(this.path, stored);
+        if (existsSync(this.path))
+            chmodSync(this.path, 0o600);
+    }
+    list() {
+        return (this.read().trusted ?? []).filter((entry) => typeof entry?.hash === 'string');
+    }
+    has(hash) {
+        return this.list().some((entry) => entry.hash === hash);
+    }
+    grant(text, name, scope) {
+        const entry = { hash: pluginHash(text), name, scope, trustedAt: now() };
+        const stored = this.read();
+        this.write({ ...stored, trusted: [...this.list().filter((known) => known.hash !== entry.hash), entry] });
+        return entry;
+    }
+    revoke(hash) {
+        const stored = this.read();
+        this.write({ ...stored, trusted: this.list().filter((entry) => entry.hash !== hash) });
+    }
+    probeCode(scope) {
+        return this.read().probeCode?.[safeId(scope)] === true;
+    }
+    setProbeCode(scope, on) {
+        const stored = this.read();
+        const probeCode = { ...(stored.probeCode ?? {}) };
+        if (on)
+            probeCode[safeId(scope)] = true;
+        else
+            delete probeCode[safeId(scope)];
+        this.write({ ...stored, probeCode });
+    }
+    /** The plugin files of a variant and whether each is trusted. */
+    review(variant) {
+        const rx = patterns(PI_SURFACE).plugin;
+        return Object.keys(variant).filter((rel) => rx.test(rel)).sort().map((path) => {
+            const hash = pluginHash(variant[path]);
+            return { path, hash, trusted: this.has(hash) };
+        });
+    }
+}

package/dist/sdk/variant/variant.d.ts

@@ -0,0 +1,71 @@
+import { type ComponentId, type SurfaceSpec, type Variant } from "./surface.js";
+/** Scripts the harness itself ships; a reference to one needs no file in the variant. */
+export declare const RESERVED_SCRIPTS: ReadonlySet<string>;
+/** Normalises a relative path and refuses one that escapes the variant. */
+export declare function normalizeRel(rel: string): string;
+/** Whether a path is on the editable surface. Never throws. */
+export declare function isAllowed(surface: SurfaceSpec, rel: string): boolean;
+export declare function skillNames(surface: SurfaceSpec, variant: Variant): string[];
+export declare function subagentNames(surface: SurfaceSpec, variant: Variant): string[];
+export declare function pluginNames(surface: SurfaceSpec, variant: Variant): string[];
+/**
+ * Every file on the editable surface under `dir`, README stubs excluded. Pass `rejected` to
+ * collect paths that exist but are off the surface.
+ */
+export declare function readVariant(surface: SurfaceSpec, dir: string, rejected?: string[]): Variant;
+/** Whether `dir` holds a variant: at least one always-on file. */
+export declare function isVariant(surface: SurfaceSpec, dir: string): boolean;
+/**
+ * Writes exactly `variant` to `dest`. Always-on files are present even when empty; files off the
+ * surface are kept, editable files already there are replaced.
+ */
+export declare function writeVariant(surface: SurfaceSpec, variant: Variant, dest: string, options?: {
+    stubs?: boolean;
+}): string;
+/** The always-on text, as the model sees it, joined in surface order. */
+export declare function alwaysOnText(surface: SurfaceSpec, variant: Variant): string;
+/**
+ * Gives every skill a trigger line in the always-on text, mutating `variant`. Returns the names
+ * repaired. A line that would push the text over the cap is skipped.
+ */
+export declare function autotrigger(surface: SurfaceSpec, variant: Variant, alwaysOnMax?: number): string[];
+export interface VariantCensus {
+    alwaysOnChars: number;
+    files: number;
+    skills: number;
+    subagents: number;
+    scripts: number;
+    plugins: number;
+}
+export interface ValidateOptions {
+    allowSubagents?: boolean;
+    alwaysOnMax?: number;
+    reservedScripts?: ReadonlySet<string>;
+    /** Check that scripts compile with the interpreters on this machine. On by default. */
+    compileScripts?: boolean;
+}
+/** A variant that does not validate. `problems` is written to be fed back to an editor as-is. */
+export declare class VariantError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+/** Throws a `VariantError` listing every problem; returns a census of a valid variant. */
+export declare function validate(surface: SurfaceSpec, variant: Variant, options?: ValidateOptions): VariantCensus;
+export interface VariantDiff {
+    added: string[];
+    removed: string[];
+    modified: string[];
+    alwaysOnCharDelta: number;
+}
+export declare function diffSummary(surface: SurfaceSpec, before: Variant, after: Variant): VariantDiff;
+export declare function isUnchanged(surface: SurfaceSpec, before: Variant, after: Variant): boolean;
+/** Which components a diff touches. */
+export declare function touchedComponents(surface: SurfaceSpec, diff: VariantDiff): ComponentId[];
+/** Pairwise line-Jaccard over variants, so a collapse to one body is visible. */
+export declare function diversity(variants: Record<string, Variant>): {
+    n: number;
+    distinct: number;
+    meanLineJaccard: number;
+};
+/** Applies an omitted-is-inherited edit: `null` removes a file. */
+export declare function applyEdit(base: Variant, edit: Record<string, string | null>): Variant;