@xingular/harness 2.0.0 → 2.0.1-unstable

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

@@ -0,0 +1,60 @@
+/** Whose usage is counted. The terminal resolves the ids, never the client. */
+export type UsageScope = 'session' | 'account' | 'project' | 'all';
+export type UsagePeriod = 'today' | '7d' | '30d' | 'all';
+export interface UsageTotals {
+    requests: number;
+    inputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    /** Reported and estimated cost; null when nothing could be priced. */
+    costUsd: number | null;
+    /** The part of `costUsd` that came from list rates, not from the provider. */
+    estimatedCostUsd: number;
+    /** Requests no provider priced and no catalogue rate could price. */
+    unpricedRequests: number;
+    avgTtftMs: number | null;
+    avgDurationMs: number | null;
+    /** Cache reads as a share of all input tokens; null without input. */
+    cacheHitPercent: number | null;
+}
+export interface UsageRow extends UsageTotals {
+    key: string;
+    label: string;
+    detail: string | null;
+}
+export interface UsageDay {
+    day: string;
+    requests: number;
+    inputTokens: number;
+    cacheReadTokens: number;
+    outputTokens: number;
+    costUsd: number | null;
+}
+export interface UsageSummary {
+    scope: UsageScope;
+    period: UsagePeriod;
+    /** The first instant counted, or null when everything is. */
+    from: string | null;
+    to: string;
+    timezoneOffsetMinutes: number;
+    generatedAt: string;
+    totals: UsageTotals;
+    byDay: UsageDay[];
+    byModel: UsageRow[];
+    byProvider: UsageRow[];
+    byAccount: UsageRow[];
+    bySession: UsageRow[];
+    /** At least one breakdown stopped at its row cap. */
+    truncated: boolean;
+    lastIndexedAt: string | null;
+}
+/** The filter a scope resolves to, after the service looks up the ids it was asked for. */
+export interface UsageFilter {
+    session: string | null;
+    account: string | null;
+    project: string | null;
+}
+export declare const USAGE_PERIODS: readonly UsagePeriod[];
+export declare const USAGE_SCOPES: readonly UsageScope[];

package/dist/sdk/usage/types.js

@@ -0,0 +1,4 @@
+// What `/usage:analysis` shows: token, cost and latency totals read from the derived usage ledger.
+// One record answers one question about one scope and period; no raw run events reach a surface.
+export const USAGE_PERIODS = ['today', '7d', '30d', 'all'];
+export const USAGE_SCOPES = ['session', 'account', 'project', 'all'];

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

@@ -0,0 +1,34 @@
+import { type Variant } from "./surface.js";
+export declare const KINDS: readonly ["skills", "prompts", "rules"];
+export type ComponentKind = (typeof KINDS)[number];
+export interface ComponentItem {
+    /** `<kind>/<name>`, stable across edits. */
+    id: string;
+    kind: string;
+    name: string;
+    description: string;
+    path: string;
+    /** Set on an item that ships with the application. */
+    builtin?: true;
+}
+export interface SkillBundleInput {
+    name: string;
+    files: {
+        path: string;
+        content: string;
+        encoding: 'utf8' | 'base64';
+    }[];
+}
+/** The folders built-in items are read from, each laid out like `registry/`. Later folders win. */
+export declare function configureBuiltins(directories: readonly string[]): void;
+/** The name and description of a skill or prompt file anywhere on disk, read the way a registry item is. */
+export declare function describeFile(file: string): {
+    name: string;
+    description: string;
+} | null;
+export declare function list(root: string): ComponentItem[];
+/** Whether a library skill or rule already has a corresponding entry in a variant. */
+export declare function isInVariant(root: string, variant: Variant, id: string): boolean;
+export declare function addToVariant(root: string, variant: Variant, id: string): Variant;
+/** Imports inert registry resources. Prompts and rules are single UTF-8 Markdown documents. */
+export declare function importItems(root: string, kind: ComponentKind, bundles: SkillBundleInput[]): ComponentItem[];

package/dist/sdk/variant/components.js

@@ -0,0 +1,230 @@
+// The component library: skills, rules and prompts kept as files under `<data>/registry/`, and
+// any built-in ones an application ships in folders laid out the same way. Nothing here reaches
+// a session by itself: a person adds an item to a variant, where it becomes a skill (c6) or
+// guardrail text (c2). The Hub installs into this library.
+import { lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { invalid, notFound } from "../core/errors.js";
+import * as frontmatter from "../core/frontmatter.js";
+import { isDir, safeRelative } from "../core/fs.js";
+import { compareText, lines, takeChars } from "../core/text.js";
+import { GUARDRAILS, PI_SURFACE } from "./surface.js";
+import { autotrigger } from "./variant.js";
+export const KINDS = ['skills', 'prompts', 'rules'];
+const MAX_SKILL_BUNDLES = 20;
+const MAX_SKILL_FILES = 100;
+const MAX_SKILL_IMPORT_BYTES = 10 * 1024 * 1024;
+let builtinDirs = [];
+/** The folders built-in items are read from, each laid out like `registry/`. Later folders win. */
+export function configureBuiltins(directories) {
+    builtinDirs = [...directories];
+}
+const kindDir = (root, kind) => join(root, 'registry', kind);
+function itemFrom(kind, stem, file) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const parsed = frontmatter.parse(text);
+    const name = parsed?.front.name;
+    const description = parsed?.front.description;
+    // A frontmatter block whose name or description is not text is treated as no frontmatter.
+    const usable = parsed !== null && (name === undefined || name === null || typeof name === 'string') && (description === undefined || description === null || typeof description === 'string');
+    const body = usable ? parsed.body : text;
+    return {
+        id: `${kind}/${stem}`,
+        kind,
+        name: usable && typeof name === 'string' ? name : stem.replace(/[-_]/g, ' '),
+        description: usable && typeof description === 'string' ? description : takeChars(lines(body).find((line) => line.trim() && !line.startsWith('#')) ?? '', 160),
+        path: file
+    };
+}
+const stemOf = (name) => (name.lastIndexOf('.') > 0 ? name.slice(0, name.lastIndexOf('.')) : name);
+/** The name and description of a skill or prompt file anywhere on disk, read the way a registry item is. */
+export function describeFile(file) {
+    const stem = basename(file) === 'SKILL.md' ? basename(dirname(file)) : stemOf(basename(file));
+    const item = itemFrom('', stem, file);
+    return item && { name: item.name, description: item.description };
+}
+function itemsIn(directory) {
+    const items = [];
+    for (const kind of KINDS) {
+        let names;
+        try {
+            names = readdirSync(join(directory, kind));
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            const path = join(directory, kind, name);
+            const stem = stemOf(name);
+            if (stem.startsWith('.'))
+                continue;
+            const file = isDir(path) ? join(path, 'SKILL.md') : name.endsWith('.md') ? path : null;
+            const item = file && itemFrom(kind, stem, file);
+            if (item)
+                items.push(item);
+        }
+    }
+    return items;
+}
+export function list(root) {
+    const items = new Map();
+    for (const directory of builtinDirs)
+        for (const item of itemsIn(directory))
+            items.set(item.id, { ...item, builtin: true });
+    for (const item of itemsIn(join(root, 'registry')))
+        items.set(item.id, item);
+    return [...items.values()].sort((left, right) => compareText(left.id, right.id));
+}
+/** A variant with one library item added: a skill as `skills/<name>/` with its files, a rule as guardrail text. */
+function skillName(item) {
+    const slug = basename(item.path) === 'SKILL.md' ? basename(dirname(item.path)) : basename(item.path).replace(/\.md$/, '');
+    return slug.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^[-_]+|-+$/g, '') || 'skill';
+}
+/** Whether a library skill or rule already has a corresponding entry in a variant. */
+export function isInVariant(root, variant, id) {
+    const item = list(root).find((candidate) => candidate.id === id);
+    if (!item)
+        return false;
+    if (item.kind === 'skills')
+        return variant['skills/' + skillName(item) + '/SKILL.md'] !== undefined;
+    if (item.kind === 'rules') {
+        const text = readFileSync(item.path, 'utf8');
+        const body = (frontmatter.parse(text)?.body ?? text).trim();
+        return Boolean(body) && (variant[GUARDRAILS] ?? '').includes(body);
+    }
+    return false;
+}
+export function addToVariant(root, variant, id) {
+    const item = list(root).find((candidate) => candidate.id === id);
+    if (!item)
+        throw notFound('That library item');
+    const next = { ...variant };
+    const text = readFileSync(item.path, 'utf8');
+    const body = (frontmatter.parse(text)?.body ?? text).trim();
+    if (item.kind === 'rules') {
+        const current = (next[GUARDRAILS] ?? '').trimEnd();
+        next[GUARDRAILS] = `${current ? `${current}\n\n` : ''}${body}\n`;
+        return next;
+    }
+    if (item.kind !== 'skills')
+        throw invalid('Only skills and rules can be added to a harness; prompts stay in the library.');
+    const name = skillName(item);
+    next[`skills/${name}/SKILL.md`] = `---\nname: ${name}\ndescription: ${(item.description || `the ${name} workflow applies`).replace(/\n/g, ' ')}\n---\n${body}\n`;
+    // A folder skill's helpers travel with it.
+    const folder = dirname(item.path);
+    if (basename(item.path) === 'SKILL.md' && isDir(join(folder, 'scripts'))) {
+        for (const file of readdirSync(join(folder, 'scripts')))
+            next[`skills/${name}/scripts/${file}`] = readFileSync(join(folder, 'scripts', file), 'utf8');
+    }
+    autotrigger(PI_SURFACE, next);
+    return next;
+}
+/** Imports inert registry resources. Prompts and rules are single UTF-8 Markdown documents. */
+export function importItems(root, kind, bundles) {
+    if (!Array.isArray(bundles) || bundles.length === 0 || bundles.length > MAX_SKILL_BUNDLES) {
+        throw invalid(`Import between 1 and ${MAX_SKILL_BUNDLES} skills at a time.`);
+    }
+    const directory = kindDir(root, kind);
+    mkdirSync(directory, { recursive: true });
+    const existing = new Set(list(root).map((item) => item.id));
+    const seen = new Set();
+    let totalBytes = 0;
+    const prepared = bundles.map((bundle) => {
+        if (!bundle || typeof bundle.name !== 'string' || !Array.isArray(bundle.files) || bundle.files.length === 0 || bundle.files.length > MAX_SKILL_FILES) {
+            throw invalid('Each skill needs a name and a bounded list of files.');
+        }
+        const name = bundle.name.trim();
+        if (name.length > 64)
+            throw invalid('Use a skill name with at most 64 letters or numbers.');
+        const slug = Array.from(name.toLowerCase(), (character) => (/^[a-z0-9]$/.test(character) ? character : '-')).join('').split('-').filter(Boolean).join('-');
+        if (!slug || slug.length > 64)
+            throw invalid('Use a skill name with at most 64 letters or numbers.');
+        const id = `${kind}/${slug}`;
+        if (existing.has(id) || seen.has(id))
+            throw invalid(`The skill “${name}” already exists.`);
+        try {
+            lstatSync(join(directory, kind === 'skills' ? slug : `${slug}.md`));
+            throw invalid(`The skill “${name}” already exists.`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        seen.add(id);
+        const files = new Map();
+        for (const file of bundle.files) {
+            if (!file || typeof file.path !== 'string' || file.path.length > 240 || typeof file.content !== 'string' || !['utf8', 'base64'].includes(file.encoding)) {
+                throw invalid(`The skill “${name}” contains an invalid file.`);
+            }
+            let relative;
+            try {
+                relative = safeRelative(file.path);
+            }
+            catch {
+                throw invalid(`The skill “${name}” contains a path outside its folder.`);
+            }
+            if (relative.includes('\0') || relative.split('/').some((part) => part.startsWith('.') || part.includes(':'))) {
+                throw invalid(`The skill “${name}” contains an unsupported file path.`);
+            }
+            const portablePath = relative.normalize('NFC').toLowerCase();
+            if ([...files.keys()].some((path) => path.normalize('NFC').toLowerCase() === portablePath))
+                throw invalid(`The skill “${name}” contains a duplicate file path.`);
+            let byteLength;
+            if (file.encoding === 'base64') {
+                if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(file.content)) {
+                    throw invalid(`The file “${relative}” is not valid base64.`);
+                }
+                if (file.content.length > Math.ceil(MAX_SKILL_IMPORT_BYTES / 3) * 4)
+                    throw invalid('The skill import is larger than 10 MiB.');
+                byteLength = Math.floor(file.content.length * 3 / 4) - (file.content.endsWith('==') ? 2 : file.content.endsWith('=') ? 1 : 0);
+            }
+            else {
+                byteLength = Buffer.byteLength(file.content, 'utf8');
+            }
+            totalBytes += byteLength;
+            if (totalBytes > MAX_SKILL_IMPORT_BYTES)
+                throw invalid('The skill import is larger than 10 MiB.');
+            const bytes = file.encoding === 'base64' ? Buffer.from(file.content, 'base64') : Buffer.from(file.content, 'utf8');
+            if (file.encoding === 'base64' && bytes.toString('base64') !== file.content)
+                throw invalid(`The file “${relative}” is not valid base64.`);
+            files.set(relative, bytes);
+        }
+        if (kind === 'skills' && !files.has('SKILL.md'))
+            throw invalid(`The skill “${name}” must include SKILL.md at its root.`);
+        if (kind !== 'skills' && (bundle.files.length !== 1 || bundle.files[0].encoding !== 'utf8' || bundle.files[0].path !== 'CONTENT.md'))
+            throw invalid('A prompt or rule must contain one UTF-8 CONTENT.md file.');
+        return { name, slug, files };
+    });
+    const staging = mkdtempSync(join(directory, '.agent-template-import-'));
+    const installed = [];
+    try {
+        for (const bundle of prepared) {
+            const target = join(staging, bundle.slug);
+            for (const [relative, bytes] of bundle.files) {
+                const path = join(target, ...relative.split('/'));
+                mkdirSync(dirname(path), { recursive: true });
+                writeFileSync(path, bytes, { flag: 'wx' });
+            }
+        }
+        for (const bundle of prepared) {
+            const target = join(directory, kind === 'skills' ? bundle.slug : `${bundle.slug}.md`);
+            renameSync(kind === 'skills' ? join(staging, bundle.slug) : join(staging, bundle.slug, 'CONTENT.md'), target);
+            installed.push(target);
+        }
+    }
+    catch (error) {
+        for (const target of installed)
+            rmSync(target, { recursive: true, force: true });
+        throw error;
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+    return list(root);
+}

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

@@ -0,0 +1,66 @@
+import { type Variant } from "./surface.js";
+import type { VariantTrust } from "./trust.js";
+/** Where the variant's own sections sit among the application's (identity 10, role 20). */
+export declare const VARIANT_SECTION_ORDER: {
+    readonly system: 25;
+    readonly guardrails: 40;
+    readonly memory: 45;
+    readonly subagents: 64;
+    readonly scripts: 66;
+};
+/** Which variant a session runs. */
+export type VariantChoice = 
+/** A scope's head, or one of its versions. */
+{
+    scope: string;
+    version?: string | null;
+}
+/** A variant on disk, such as a refinement candidate. It is read, never written. */
+ | {
+    dir: string;
+    scope?: string | null;
+};
+export interface SubagentDefinition {
+    name: string;
+    description: string;
+    instructions: string;
+}
+export interface Materialised {
+    scope: string | null;
+    /** The fingerprint of the variant that ran. */
+    fingerprint: string;
+    /** The variant's folder; scripts and skills are read from it in place. */
+    dir: string;
+    /** The variant's files, path → text. */
+    files: Variant;
+    sections: {
+        id: string;
+        title: string;
+        body: string;
+        order: number;
+    }[];
+    /** The tool guidance, added after the tool groups. */
+    toolGuidance: string;
+    skillPaths: string[];
+    extensionPaths: string[];
+    /** Plugin files that did not load because their code is not trusted. */
+    untrustedPlugins: string[];
+    subagents: SubagentDefinition[];
+}
+/** Finds the variant a choice names. */
+export declare function resolve(root: string, choice: VariantChoice): {
+    scope: string | null;
+    dir: string;
+    fingerprint: string;
+    variant: Variant;
+};
+export interface MaterialiseOptions {
+    trust?: VariantTrust | null;
+    /** Load improver-written plugin code without trust (refinement probes, when the person allowed it). */
+    probeCode?: boolean;
+    /** Whether the session can start subagents; when it cannot, c5 is not described. */
+    subagents?: boolean;
+}
+export declare function materialise(root: string, choice: VariantChoice, options?: MaterialiseOptions): Materialised;
+/** One subagent's definition from the variant a run used. */
+export declare function subagentOf(dir: string, name: string): SubagentDefinition | null;

package/dist/sdk/variant/materialise.js

@@ -0,0 +1,81 @@
+// Turning a variant into what a Pi session receives: always-on prompt sections (c1–c4),
+// the skills folder Pi advertises natively (c6), the scripts folder named in the prompt (c7),
+// subagent definitions (c5), and plugin extensions that are trusted (c8).
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { invalid } from "../core/errors.js";
+import * as store from "./store.js";
+import { GUARDRAILS, MEMORY, PI_SURFACE, SYSTEM_PROMPT, TOOL_GUIDANCE, patterns } from "./surface.js";
+import { readVariant } from "./variant.js";
+/** Where the variant's own sections sit among the application's (identity 10, role 20). */
+export const VARIANT_SECTION_ORDER = { system: 25, guardrails: 40, memory: 45, subagents: 64, scripts: 66 };
+function frontmatter(text, field) {
+    const m = new RegExp(`^${field}:\\s*(.+)$`, 'm').exec(text.slice(0, 600));
+    return m?.[1]?.trim() ?? null;
+}
+function bodyAfterFrontmatter(text) {
+    const m = /^---\n[\s\S]*?\n---\n?/.exec(text);
+    return (m ? text.slice(m[0].length) : text).trim();
+}
+/** Finds the variant a choice names. */
+export function resolve(root, choice) {
+    if ('dir' in choice) {
+        if (!existsSync(choice.dir))
+            throw invalid('That variant folder does not exist.');
+        const variant = readVariant(PI_SURFACE, choice.dir);
+        return { scope: choice.scope ?? null, dir: choice.dir, fingerprint: store.fingerprint(variant), variant };
+    }
+    const fp = choice.version ?? store.head(root, choice.scope)?.fingerprint;
+    if (!fp)
+        throw invalid(`The variant '${choice.scope}' has no version yet.`);
+    const dir = store.versionPath(root, choice.scope, fp);
+    return { scope: choice.scope, dir, fingerprint: fp, variant: store.readVersion(root, choice.scope, fp) };
+}
+export function materialise(root, choice, options = {}) {
+    const { scope, dir, fingerprint, variant } = resolve(root, choice);
+    const r = patterns(PI_SURFACE);
+    const sections = [];
+    const add = (id, title, body, order) => {
+        if (body?.trim())
+            sections.push({ id, title, body: body.trim(), order });
+    };
+    add('system', 'Instructions', variant[SYSTEM_PROMPT], VARIANT_SECTION_ORDER.system);
+    add('guardrails', 'Guardrails', variant[GUARDRAILS], VARIANT_SECTION_ORDER.guardrails);
+    add('memory', 'Memory', variant[MEMORY], VARIANT_SECTION_ORDER.memory);
+    const subagents = [];
+    for (const rel of Object.keys(variant).sort()) {
+        const m = r.subagent.exec(rel);
+        if (!m)
+            continue;
+        const text = variant[rel];
+        subagents.push({ name: m[1], description: frontmatter(text, 'description') ?? '', instructions: bodyAfterFrontmatter(text) });
+    }
+    if (subagents.length && options.subagents !== false) {
+        add('subagents', 'Subagents', `Start one with spawn_subagent and agent set to its name. Each works in its own context and returns text.\n${subagents.map((agent) => `- ${agent.name} — ${agent.description}`).join('\n')}`, VARIANT_SECTION_ORDER.subagents);
+    }
+    const scripts = Object.keys(variant).filter((rel) => r.script.test(rel)).map((rel) => rel.slice('scripts/'.length)).sort();
+    if (scripts.length) {
+        add('scripts', 'Scripts', `Your helper scripts are in ${join(dir, 'scripts')}: ${scripts.join(', ')}. Run a .py one with python3 and a .mjs one with node, giving its full path. When instructions say \`scripts/<name>\`, they mean this folder.`, VARIANT_SECTION_ORDER.scripts);
+    }
+    const skillPaths = existsSync(join(dir, 'skills')) && readdirSync(join(dir, 'skills')).length ? [join(dir, 'skills')] : [];
+    const extensionPaths = [];
+    const untrustedPlugins = [];
+    for (const rel of Object.keys(variant).filter((path) => r.plugin.test(path)).sort()) {
+        const trusted = options.trust?.has((options.trust.review({ [rel]: variant[rel] })[0]?.hash) ?? '') ?? false;
+        if (trusted || options.probeCode)
+            extensionPaths.push(join(dir, rel));
+        else
+            untrustedPlugins.push(rel);
+    }
+    return { scope, fingerprint, dir, files: variant, sections, toolGuidance: (variant[TOOL_GUIDANCE] ?? '').trim(), skillPaths, extensionPaths, untrustedPlugins, subagents };
+}
+/** One subagent's definition from the variant a run used. */
+export function subagentOf(dir, name) {
+    if (!/^[a-z0-9][a-z0-9_-]*$/.test(name))
+        return null;
+    const path = join(dir, 'sub_agents', name, 'AGENT.md');
+    if (!existsSync(path))
+        return null;
+    const text = readFileSync(path, 'utf8');
+    return { name, description: frontmatter(text, 'description') ?? '', instructions: bodyAfterFrontmatter(text) };
+}

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

@@ -0,0 +1,4 @@
+/** `harnesses/<scope>/versions/<fp>/tree/` and `library/<scope>/<area>/harnesses/<task>/harness/`. */
+export declare function migrateVariantLayout(root: string): string[];
+/** The device-local file of trusted plugin code. */
+export declare function migrateTrustFile(stateDir: string): void;

package/dist/sdk/variant/migrate.js

@@ -0,0 +1,41 @@
+// Moves state written before the foundation/variant naming (PROP-0009) to its new names. Every
+// step renames and never overwrites, so running it again, or beside new data, changes nothing.
+import { existsSync, readdirSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+function move(from, to, moved) {
+    if (!existsSync(from) || existsSync(to))
+        return;
+    renameSync(from, to);
+    moved.push(to);
+}
+function folders(path) {
+    try {
+        return readdirSync(path, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+/** `harnesses/<scope>/versions/<fp>/tree/` and `library/<scope>/<area>/harnesses/<task>/harness/`. */
+export function migrateVariantLayout(root) {
+    const moved = [];
+    move(join(root, 'harnesses'), join(root, 'variants'), moved);
+    for (const scope of folders(join(root, 'variants'))) {
+        const versions = join(root, 'variants', scope, 'versions');
+        for (const fingerprint of folders(versions))
+            move(join(versions, fingerprint, 'tree'), join(versions, fingerprint, 'variant'), moved);
+    }
+    for (const scope of folders(join(root, 'library'))) {
+        for (const area of folders(join(root, 'library', scope))) {
+            const base = join(root, 'library', scope, area);
+            move(join(base, 'harnesses'), join(base, 'variants'), moved);
+            for (const task of folders(join(base, 'variants')))
+                move(join(base, 'variants', task, 'harness'), join(base, 'variants', task, 'variant'), moved);
+        }
+    }
+    return moved;
+}
+/** The device-local file of trusted plugin code. */
+export function migrateTrustFile(stateDir) {
+    move(join(stateDir, 'tree-plugin-trust.json'), join(stateDir, 'variant-plugin-trust.json'), []);
+}

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

@@ -0,0 +1,20 @@
+import { type Variant } from "./surface.js";
+export interface SeedInput {
+    /** The caller whose rules, skills and memory blocks to carry over. */
+    agentId?: string | null;
+    projectId?: string | null;
+    /** The caller's own instructions. */
+    instructions?: string;
+}
+/** The legacy pieces for a caller, before they are put together. */
+export declare function legacyPieces(root: string, input: SeedInput): {
+    rules: string[];
+    skills: Record<string, string>;
+    memory: string[];
+};
+/**
+ * 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 declare function seedVariant(root: string, input: SeedInput): Variant;

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;
+}