@xingular/harness 0.1.7 → 1.1.1

package/dist/sdk/tools/sessionName.d.ts

@@ -0,0 +1,7 @@
+import type { ToolSpec } from "./types.js";
+export declare const SESSION_NAME = "session_name";
+export interface NamedSession {
+    readonly sessionName?: string;
+    setSessionName(name: string): void;
+}
+export declare function sessionNameTool(current: () => NamedSession | undefined): ToolSpec;

package/dist/sdk/tools/sessionName.js

@@ -0,0 +1,31 @@
+// Pi owns session names and their history. Both execution paths bind this tool to
+// the current native session; it never receives a target session id from the model.
+import { invalid } from "../core/errors.js";
+export const SESSION_NAME = 'session_name';
+export function sessionNameTool(current) {
+    return {
+        name: SESSION_NAME,
+        label: 'Name the session',
+        description: 'Set or revise this session’s name. Name meaningful work early, then revise the name when the overall objective changes; greetings alone need no name. ' +
+            'Use one short imperative sentence describing the objective, at most six words, such as "Add web browser integrations". ' +
+            'You may revise a manually assigned name. Keep a useful current name when the objective is unchanged. This only names your own session.',
+        parameters: Type => Type.Object({ name: Type.String({ description: 'One short sentence describing the objective, at most six words' }) }),
+        planModeSafe: () => true,
+        execute: async (input) => {
+            if (typeof input.name !== 'string')
+                throw invalid('Send name as a short sentence of at most six words.');
+            if (/[\x00-\x08\x0e-\x1f\x7f-\x9f]/u.test(input.name)) {
+                throw invalid('Session names cannot contain terminal escapes or control characters.');
+            }
+            const name = input.name.replace(/\s+/gu, ' ').trim();
+            if (!name || name.split(' ').length > 6)
+                throw invalid('Use a non-empty session name of at most six words.');
+            const session = current();
+            if (!session)
+                throw invalid('The native session is unavailable; try naming it again once it is ready.');
+            if (session.sessionName !== name)
+                session.setSessionName(name);
+            return `Session name: ${name}`;
+        }
+    };
+}

package/dist/sdk/tools/spawnSubagent.d.ts

@@ -0,0 +1,4 @@
+import type { Subagents } from "../sessions/subagentService.js";
+import type { ToolSpec } from "./types.js";
+export { SPAWN_SUBAGENT, SUBAGENT_RELATION, DEFAULT_SUBAGENT_DEPTH, MAX_SUBAGENT_DEPTH, subagentDepth, subagentReport, type SubagentOptions } from "../sessions/subagents.js";
+export declare function subagentTools(service: Subagents, parentRunId: string): ToolSpec[];

package/dist/sdk/tools/spawnSubagent.js

@@ -0,0 +1,58 @@
+import { HarnessError, invalid } from "../core/errors.js";
+import { SPAWN_SUBAGENT, WAIT_SUBAGENTS, SUBAGENT_RECEIPT, MAX_SUBAGENT_TITLE_WORDS, subagentTitle } from "../sessions/subagents.js";
+export { SPAWN_SUBAGENT, SUBAGENT_RELATION, DEFAULT_SUBAGENT_DEPTH, MAX_SUBAGENT_DEPTH, subagentDepth, subagentReport } from "../sessions/subagents.js";
+function reported(parentRunId, results, spawned) {
+    const included = [];
+    let length = 0;
+    for (const result of results) {
+        if (length + result.text.length > 24_000 && included.length)
+            break;
+        included.push(result);
+        length += result.text.length + 300;
+    }
+    const receipt = { version: 1, ownerRunId: parentRunId, ...(spawned ? { spawned } : {}), delivered: included.map((result) => result.runId) };
+    return { text: JSON.stringify({ results: included, ...(results.length > included.length ? { remaining: results.slice(included.length).map((result) => result.runId) } : {}) }), details: { [SUBAGENT_RECEIPT]: receipt } };
+}
+export function subagentTools(service, parentRunId) {
+    const execute = (fn) => async (input) => {
+        try {
+            return await fn(input);
+        }
+        catch (error) {
+            if (error instanceof HarnessError)
+                return error.message;
+            throw error;
+        }
+    };
+    return [{
+            name: SPAWN_SUBAGENT,
+            label: 'Start a subagent',
+            description: 'Start a fresh child run for independent work: a copy of yourself, or an agent profile from your Subagents list when you name it in agent (for example worker to make changes, explorer to find and explain). Give a short title, which the user sees in the roster, and a complete brief: the child has no conversation history and no more capabilities than you. Returns its run ID immediately by default so you can continue working. Results arrive automatically before you finish. Use wait_subagents to join selected children, or wait: true for an inline result. Stopping you stops your children.',
+            parameters: (Type) => Type.Object({
+                title: Type.String({ description: `A short imperative title for the roster, at most ${MAX_SUBAGENT_TITLE_WORDS} words, such as "Map the auth flow"` }),
+                brief: Type.String(),
+                agent: Type.Optional(Type.String({ description: 'The name of an agent profile from your Subagents list; omit for a copy of yourself' })),
+                tools: Type.Optional(Type.Array(Type.String())),
+                wait: Type.Optional(Type.Boolean({ description: 'Wait for the child and return its result; default false' }))
+            }),
+            execute: execute(async (input) => {
+                const title = subagentTitle(input.title);
+                if (!title)
+                    throw invalid(`Give the subagent a title of at most ${MAX_SUBAGENT_TITLE_WORDS} words, with no control characters.`);
+                const child = await service.spawn({ parentRunId, brief: input.brief, title, agent: input.agent, tools: input.tools, wait: input.wait });
+                if (input.wait === true)
+                    return reported(parentRunId, service.results({ parentRunId, runIds: [child.runId] }), [child.runId]);
+                return { text: JSON.stringify(child), details: { [SUBAGENT_RECEIPT]: { version: 1, ownerRunId: parentRunId, spawned: [child.runId] } } };
+            })
+        }, {
+            name: WAIT_SUBAGENTS,
+            label: 'Wait for subagents',
+            description: 'Wait for all selected direct subagents to settle and return their results, including failures. Omit runIds to select your current children. Do useful independent work before waiting; results also arrive automatically before your final reply.',
+            parameters: (Type) => Type.Object({ runIds: Type.Optional(Type.Array(Type.String())) }),
+            execute: execute(async (input) => {
+                if (input.runIds !== undefined && !Array.isArray(input.runIds))
+                    throw invalid('runIds must be an array of child run IDs.');
+                return reported(parentRunId, await service.wait({ parentRunId, runIds: input.runIds }));
+            })
+        }];
+}

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

@@ -0,0 +1,48 @@
+import type { CallerContext } from "../core/caller.js";
+import type { CapabilitySet } from "../capabilities/types.js";
+import type { ActiveRun } from "../sessions/registry.js";
+import type { ToolAttachmentRef } from "../sessions/contracts.js";
+import type { ProviderDiagnostics } from "../doctor/types.js";
+export interface ToolResult {
+    text: string;
+    /** Native-history metadata; never interpreted as model instructions. */
+    details?: Record<string, unknown>;
+    image?: {
+        data: string;
+        mimeType: string;
+    };
+    /** Further images, after `image`. A screenshot tool returns one; a comparison may return several. */
+    images?: {
+        data: string;
+        mimeType: string;
+    }[];
+    /** References to content stored by the provider; bytes never enter the run-event stream. */
+    attachments?: ToolAttachmentRef[];
+}
+export interface ToolSpec {
+    name: string;
+    label: string;
+    description: string;
+    /** Builds the TypeBox parameter schema. */
+    parameters: (type: typeof import('typebox').Type) => unknown;
+    /** Only reads or asks; such a tool stays callable in plan mode. */
+    readOnly?: boolean;
+    /** Whether this particular call is safe for plan-mode research. Refusals happen before approvals. */
+    planModeSafe?: (input: Record<string, unknown>) => boolean;
+    execute: (input: Record<string, unknown>) => Promise<string | ToolResult>;
+}
+/** What a tool provider is told about the session it is building tools for. */
+export interface ToolSession {
+    run: ActiveRun;
+    caller: CallerContext;
+    /** The tool names switched on for this session. */
+    allow: readonly string[];
+    /** Hops from the user to this session (0 when the user started it). */
+    depth: number;
+    /** The session's working folder. */
+    cwd: string;
+    /** The capability set frozen when this run started. */
+    capabilities: CapabilitySet;
+}
+/** Builds the tools a session may be given. Only those named in `allow` are registered. */
+export type ToolProvider = ((session: ToolSession) => ToolSpec[] | Promise<ToolSpec[]>) & ProviderDiagnostics;

package/dist/sdk/tools/types.js

@@ -0,0 +1 @@
+export {};

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;