@xingular/harness 0.1.7 → 1.1.1

package/dist/sdk/variant/seed.js

@@ -0,0 +1,116 @@
+// A first variant for a caller that had none, built from what shaped it before harness
+// variants existed: its instructions (c1), the rules switched on for it (c2), its memory blocks and
+// the person's own block (c3), and the skills switched on for it (c6). Read straight from the
+// files an earlier harness left in the data root; nothing there is changed.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import * as frontmatter from "../core/frontmatter.js";
+import * as attachments from "../plugins/attachments.js";
+import { GUARDRAILS, MEMORY, PI_SURFACE, SYSTEM_PROMPT, TOOL_GUIDANCE } from "./surface.js";
+import { alwaysOnText, autotrigger, validate } from "./variant.js";
+function body(text) {
+    return (frontmatter.parse(text)?.body ?? text).trim();
+}
+function read(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function folders(dir) {
+    try {
+        return readdirSync(dir).filter((name) => !name.startsWith('.')).sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Where an earlier Wiki kept memory blocks: in place, or where they were moved aside. */
+function blocksDir(root) {
+    if (existsSync(join(root, 'wiki', 'blocks')))
+        return join(root, 'wiki', 'blocks');
+    const moved = folders(join(root, 'legacy')).filter((name) => name.startsWith('wiki-')).reverse();
+    for (const name of moved)
+        if (existsSync(join(root, 'legacy', name, 'blocks')))
+            return join(root, 'legacy', name, 'blocks');
+    return null;
+}
+function skillName(stem) {
+    return stem.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^[-_]+|-+$/g, '').slice(0, 64) || 'skill';
+}
+/** The legacy pieces for a caller, before they are put together. */
+export function legacyPieces(root, input) {
+    const choices = attachments.load(root);
+    const scope = { agentId: input.agentId ?? null, projectId: input.projectId ?? null };
+    const on = (id) => attachments.attached(choices, [id], scope, false);
+    const rules = [];
+    const rulesDir = join(root, 'registry', 'rules');
+    for (const name of folders(rulesDir)) {
+        const stem = name.replace(/\.md$/, '');
+        const path = name.endsWith('.md') ? join(rulesDir, name) : join(rulesDir, name, 'SKILL.md');
+        const text = read(path);
+        if (text && on(`rules/${stem}`))
+            rules.push(body(text));
+    }
+    const skills = {};
+    const skillsDir = join(root, 'registry', 'skills');
+    for (const name of folders(skillsDir)) {
+        const stem = name.replace(/\.md$/, '');
+        let path = join(skillsDir, name);
+        try {
+            if (statSync(path).isDirectory())
+                path = join(path, 'SKILL.md');
+        }
+        catch {
+            continue;
+        }
+        const text = read(path);
+        if (!text || !on(`skills/${stem}`))
+            continue;
+        const slug = skillName(stem);
+        const parsed = frontmatter.parse(text);
+        const description = typeof parsed?.front.description === 'string' && parsed.front.description.trim() ? parsed.front.description.trim() : `the ${slug} workflow applies`;
+        skills[`skills/${slug}/SKILL.md`] = `---\nname: ${slug}\ndescription: ${description.replace(/\n/g, ' ')}\n---\n${body(text)}\n`;
+    }
+    const memory = [];
+    const blocks = blocksDir(root);
+    if (blocks) {
+        const user = read(join(blocks, 'shared', 'user.md'));
+        if (user && body(user))
+            memory.push(`## About the person\n\n${body(user)}`);
+        if (input.agentId && /^[A-Za-z0-9_-]+$/.test(input.agentId)) {
+            for (const [file, title] of [['persona.md', 'Persona'], ['notes.md', 'Notes']]) {
+                const text = read(join(blocks, 'agents', input.agentId, file));
+                if (text && body(text))
+                    memory.push(`## ${title}\n\n${body(text)}`);
+            }
+        }
+    }
+    return { rules, skills, memory };
+}
+/**
+ * Builds a valid seed variant. Rules become guardrails, blocks become memory, and every skill gets a
+ * trigger line. When the always-on text would be over the cap, memory is shortened first, then
+ * guardrails; nothing else is dropped.
+ */
+export function seedVariant(root, input) {
+    const pieces = legacyPieces(root, input);
+    const variant = {
+        [SYSTEM_PROMPT]: (input.instructions ?? '').trim() ? `${input.instructions.trim()}\n` : '',
+        [GUARDRAILS]: pieces.rules.length ? `${pieces.rules.join('\n\n')}\n` : '',
+        [MEMORY]: pieces.memory.length ? `${pieces.memory.join('\n\n')}\n` : '',
+        [TOOL_GUIDANCE]: '',
+        ...pieces.skills
+    };
+    const cap = PI_SURFACE.alwaysOnMax - 2_000;
+    for (const rel of [MEMORY, GUARDRAILS, SYSTEM_PROMPT]) {
+        const over = alwaysOnText(PI_SURFACE, variant).length - cap;
+        if (over > 0)
+            variant[rel] = `${variant[rel].slice(0, Math.max(0, variant[rel].length - over - 40)).trimEnd()}\n\n(Shortened when this harness was created.)\n`;
+    }
+    autotrigger(PI_SURFACE, variant);
+    validate(PI_SURFACE, variant, { compileScripts: false });
+    return variant;
+}

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

@@ -0,0 +1,82 @@
+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;
+}
+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): VersionRecord[];
+export interface CommitOptions {
+    /** Move the head to the new version (the default). */
+    moveHead?: boolean;
+    surface?: SurfaceSpec;
+    validate?: ValidateOptions;
+}
+/**
+ * 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;

package/dist/sdk/variant/store.js

@@ -0,0 +1,151 @@
+// 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
+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 } 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 out = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        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 };
+        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;
+    }
+}

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;