@xingular/harness 1.2.0 → 1.3.1-unstable.1

package/dist/sdk/plugins/discover.d.ts

@@ -1,8 +1,9 @@
 /**
  * `context` is an instruction file Pi reads on its own: `AGENTS.md`, `SYSTEM.md` and their kin.
  * `hook` is a package's hooks file, which the harness runs itself; Pi never loads it.
+ * `agent` is a subagent profile a package brings; the harness reads it, Pi never does.
  */
-export type FoundKind = 'extension' | 'skill' | 'prompt' | 'theme' | 'context' | 'hook';
+export type FoundKind = 'extension' | 'skill' | 'prompt' | 'theme' | 'context' | 'hook' | 'agent';
 /** Where a found item comes from. `builtin` is one of the Pi command's own extensions. */
 export type FoundOrigin = 'shared' | 'package' | 'project' | 'home' | 'builtin';
 export interface Found {
@@ -33,6 +34,11 @@ export type Resolver = (input: ResolveInput) => Promise<Found[]>;
 /** The extensions built into the `pi` command. A terminal loads them; an SDK session has none. */
 export declare const PI_BUILTINS: readonly ["llama.cpp", "codemode", "tool-search", "mcp"];
 export declare const BUILTIN_PREFIX = "builtin:";
+/**
+ * The subagent profiles in a package's agents folder: Markdown files whose frontmatter has a
+ * `name` and a `description`. Anything else there (notes, a README) is not a profile.
+ */
+export declare function packageProfiles(root: string, folder: string): string[];
 /**
  * Runs an install with the package manager's install scripts switched off, so fetching a
  * package runs none of its code. A package that builds itself on install then fails to load,

package/dist/sdk/plugins/discover.js

@@ -1,14 +1,50 @@
 // What Pi would load for a session, found with Pi's own resolver so the list matches Pi's
 // rules. Resolving reads folders and manifests; it never runs an extension.
-import { existsSync } from 'node:fs';
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, sep } from 'node:path';
 import { log } from "../core/bus.js";
+import * as frontmatter from "../core/frontmatter.js";
 import { loadPi } from "../pi/runtime.js";
 import { packageManifest } from "./manifest.js";
 /** The extensions built into the `pi` command. A terminal loads them; an SDK session has none. */
 export const PI_BUILTINS = ['llama.cpp', 'codemode', 'tool-search', 'mcp'];
 export const BUILTIN_PREFIX = 'builtin:';
+/** At most this many profiles are read from one package. */
+const MAX_PACKAGE_PROFILES = 50;
+/**
+ * The subagent profiles in a package's agents folder: Markdown files whose frontmatter has a
+ * `name` and a `description`. Anything else there (notes, a README) is not a profile.
+ */
+export function packageProfiles(root, folder) {
+    const dir = join(root, folder);
+    let names;
+    try {
+        if (!lstatSync(dir).isDirectory())
+            return [];
+        names = readdirSync(dir).filter((name) => name.endsWith('.md') && !name.startsWith('.')).sort();
+    }
+    catch {
+        return [];
+    }
+    const profiles = [];
+    for (const name of names) {
+        const path = join(dir, name);
+        try {
+            if (!lstatSync(path).isFile())
+                continue;
+            const front = frontmatter.parse(readFileSync(path, 'utf8'))?.front;
+            if (typeof front?.name === 'string' && front.name.trim() && typeof front.description === 'string' && front.description.trim())
+                profiles.push(path);
+        }
+        catch {
+            continue;
+        }
+        if (profiles.length >= MAX_PACKAGE_PROFILES)
+            break;
+    }
+    return profiles;
+}
 const inside = (path, parent) => path === parent || path.startsWith(parent.endsWith(sep) ? parent : `${parent}${sep}`);
 function origin(path, metadata) {
     if (path.startsWith(BUILTIN_PREFIX))
@@ -92,7 +128,10 @@ export const piResolver = async ({ cwd, agentDir, install, packages }) => {
     for (const folder of packages ?? [])
         roots.set(folder, folder);
     for (const [root, source] of roots) {
-        const hooks = packageManifest(root).hooks;
+        const manifest = packageManifest(root);
+        for (const path of packageProfiles(root, manifest.agents))
+            found.push({ kind: 'agent', path, origin: 'package', project: false, packageRoot: root, source, enabled: true });
+        const hooks = manifest.hooks;
         if (!hooks || !existsSync(join(root, hooks)))
             continue;
         found.push({ kind: 'hook', path: join(root, hooks), origin: 'package', project: false, packageRoot: root, source, enabled: true });

package/dist/sdk/plugins/identity.js

@@ -6,7 +6,7 @@ import * as frontmatter from "../core/frontmatter.js";
 import { BUILTIN_PREFIX } from "./discover.js";
 import { packageManifest } from "./manifest.js";
 export { packageManifest } from "./manifest.js";
-export const FOUND_KINDS = { extension: 'code', hook: 'code', skill: 'skill', prompt: 'command', theme: 'theme', context: 'instruction' };
+export const FOUND_KINDS = { extension: 'code', hook: 'code', skill: 'skill', prompt: 'command', agent: 'agent', theme: 'theme', context: 'instruction' };
 /** The id of the plugin a found item is listed under. */
 export function pluginIdOf(item) {
     if (item.origin === 'builtin')

package/dist/sdk/plugins/install.d.ts

@@ -10,11 +10,15 @@ export declare function normalizeSource(input: string): string;
 export declare function install(harness: Harness, params: PluginScope & {
     source: string;
 }): Promise<Plugin[]>;
-/** Removes an installed package. One kept as a folder beside a person's data is moved to the trash there. */
+/** Removes an installed package without consulting Hub. Hub calls this while it owns the receipt transaction. */
+export declare function removeDirect(harness: Harness, params: PluginScope & {
+    pluginId: string;
+}): Promise<Plugin[]>;
+/** Removes an installed package, delegating Hub-owned packages to their receipt owner. */
 export declare function remove(harness: Harness, params: PluginScope & {
     pluginId: string;
 }): Promise<Plugin[]>;
-/** Fetches a newer version of one installed package, or of all of them. Changed code waits for trust again. */
+/** Fetches newer versions of local packages. Hub-owned packages remain pinned to catalog versions. */
 export declare function update(harness: Harness, params: PluginScope & {
     pluginId?: string | null;
 }): Promise<Plugin[]>;

package/dist/sdk/plugins/install.js

@@ -75,8 +75,8 @@ function installed(plugins, pluginId) {
         throw invalid(`${plugin.title} was not installed as a package, so it cannot be removed or updated here.`);
     return plugin;
 }
-/** Removes an installed package. One kept as a folder beside a person's data is moved to the trash there. */
-export async function remove(harness, params) {
+/** Removes an installed package without consulting Hub. Hub calls this while it owns the receipt transaction. */
+export async function removeDirect(harness, params) {
     const plugin = installed(await list(harness, params), params.pluginId);
     if (plugin.install.kind === 'folder') {
         const trash = join(harness.env.root, 'trash', 'plugins');
@@ -98,13 +98,37 @@ export async function remove(harness, params) {
     changed(harness);
     return list(harness, params);
 }
-/** Fetches a newer version of one installed package, or of all of them. Changed code waits for trust again. */
+async function hubReceiptForPackage(harness, pluginId) {
+    const receipts = (await harness.hub.list()).installed.filter((receipt) => receipt.entry.delivery.kind === 'pi-package' && receipt.resourceIds.includes(pluginId));
+    if (receipts.length > 1)
+        throw invalid('More than one Hub receipt owns this package. Review the Hub receipts before changing it.');
+    return receipts[0];
+}
+/** Removes an installed package, delegating Hub-owned packages to their receipt owner. */
+export async function remove(harness, params) {
+    const receipt = await hubReceiptForPackage(harness, params.pluginId);
+    if (receipt) {
+        await harness.hub.uninstall(receipt.entry.id, receipt.entry.version);
+        return list(harness, params);
+    }
+    return removeDirect(harness, params);
+}
+/** Fetches newer versions of local packages. Hub-owned packages remain pinned to catalog versions. */
 export async function update(harness, params) {
-    const plugin = params.pluginId ? installed(await list(harness, params), params.pluginId) : null;
+    const plugins = await list(harness, params);
+    const plugin = params.pluginId ? installed(plugins, params.pluginId) : null;
     if (plugin?.install.kind === 'folder')
         throw invalid(`${plugin.title} is a folder on this machine. Change its files to update it.`);
+    const receipts = (await harness.hub.list()).installed.filter((receipt) => receipt.entry.delivery.kind === 'pi-package');
+    const hubOwned = new Set(receipts.flatMap((receipt) => receipt.resourceIds));
+    if (plugin && hubOwned.has(plugin.id))
+        throw invalid(`${plugin.title} is managed by Hub. Uninstall its receipt before installing another exact catalog version.`);
+    const sources = plugin
+        ? [plugin.install.source]
+        : [...new Set(plugins.filter((candidate) => candidate.install && candidate.install.kind !== 'folder' && !hubOwned.has(candidate.id)).map((candidate) => candidate.install.source))];
     const { packages } = await manager(harness);
-    await withoutInstallScripts(() => packages.update(plugin?.install.source));
+    for (const source of sources)
+        await withoutInstallScripts(() => packages.update(source));
     changed(harness);
     return list(harness, params);
 }

package/dist/sdk/plugins/inventory.js

@@ -6,7 +6,7 @@ import { charCount } from "../core/text.js";
 import { allowed } from "../mcp/connections.js";
 import { BUILT_IN_DYNAMIC, compile, toolGroups } from "../prompt/compile.js";
 import { ASK_USER } from "../tools/askUser.js";
-import { CHECKLIST_WRITE } from "../tools/checklist.js";
+import { TODO_WRITE } from "../tools/todo.js";
 import { DEFAULT_TOOL_NAMES } from "../tools/definitions.js";
 import { VARIANT_PLUGIN } from "./builtin.js";
 const size = (path) => {
@@ -68,7 +68,7 @@ export function inventory(input) {
     }
     const names = [...input.tools];
     const extensionToolNames = new Set(input.plugins.filter((plugin) => ['project', 'package', 'shared', 'home'].includes(plugin.source)).flatMap((plugin) => plugin.contributions.filter((entry) => entry.kind === 'tool' && entry.state === 'on').map((entry) => entry.name)));
-    for (const name of [ASK_USER, CHECKLIST_WRITE, ...DEFAULT_TOOL_NAMES, ...(input.connections ? ['mcp_list_tools', 'mcp_call_tool'] : [])])
+    for (const name of [ASK_USER, TODO_WRITE, ...DEFAULT_TOOL_NAMES, ...(input.connections ? ['mcp_list_tools', 'mcp_call_tool'] : [])])
         if (!names.includes(name))
             names.push(name);
     for (const name of names) {
@@ -86,7 +86,7 @@ export function inventory(input) {
     }
     // What the harness found on disk and lets load. The pi command's own extensions load in no
     // Xingular session, so a terminal and a host have the same (PROP-0039).
-    const delivered = { code: 'code', skill: 'on-demand', command: 'on-demand', instruction: 'system', theme: 'code', tool: 'tool', connection: 'tool' };
+    const delivered = { code: 'code', skill: 'on-demand', command: 'on-demand', agent: 'on-demand', instruction: 'system', theme: 'code', tool: 'tool', connection: 'tool' };
     const terminal = context.surface === 'cli';
     for (const plugin of input.plugins) {
         if (!['project', 'package', 'shared', 'home'].includes(plugin.source))

package/dist/sdk/plugins/manifest.d.ts

@@ -9,6 +9,8 @@ export interface PackageManifest {
     commandPrefix: string | null;
     /** The hooks file, inside the package, or `null` when it has none. */
     hooks: string | null;
+    /** The folder of subagent profiles, inside the package. `agents` unless the manifest names another. */
+    agents: string;
     /** Data-only remote connector forms. Invalid templates are ignored; none can carry credentials. */
     connectorTemplates: ConnectorTemplate[];
 }

package/dist/sdk/plugins/manifest.js

@@ -1,5 +1,7 @@
 // What a package says about itself in its `package.json`: Pi's own fields, and under `harness`
-// which part of the harness it extends, its command namespace and the file of hooks it runs.
+// which part of the harness it extends, its command namespace, the file of hooks it runs and the
+// folder of subagent profiles it brings. A package written for other agent harnesses may have no
+// `package.json`; its `plugin.json` then names and describes it.
 import { basename, join } from 'node:path';
 import { z } from 'zod';
 import { readJsonOr, safeRelative } from "../core/fs.js";
@@ -39,16 +41,31 @@ function inside(path) {
         return null;
     }
 }
+/** The plugin manifests other agent harnesses read, in the order they are tried. */
+const PLUGIN_MANIFESTS = ['plugin.json', '.claude-plugin/plugin.json', '.codex-plugin/plugin.json'];
+const text = (value) => (typeof value === 'string' && value.trim() ? value.trim() : null);
+function pluginJson(packageRoot) {
+    for (const file of PLUGIN_MANIFESTS) {
+        const found = readJsonOr(join(packageRoot, file), null);
+        if (found && typeof found === 'object' && !Array.isArray(found))
+            return found;
+    }
+    return {};
+}
 export function packageManifest(packageRoot) {
     const manifest = readJsonOr(join(packageRoot, 'package.json'), {});
+    // Only a package without a name of its own is described by its plugin.json.
+    const plugin = text(manifest.name) ? {} : pluginJson(packageRoot);
     const own = (manifest.harness && typeof manifest.harness === 'object' && !Array.isArray(manifest.harness) ? manifest.harness : {});
+    const pluginName = text(plugin.name);
     return {
-        name: typeof manifest.name === 'string' && manifest.name ? manifest.name : basename(packageRoot),
-        description: typeof manifest.description === 'string' ? manifest.description : '',
-        version: typeof manifest.version === 'string' ? manifest.version : null,
+        name: text(manifest.name) ?? (pluginName && /^[a-z0-9][a-z0-9._-]*$/i.test(pluginName) ? pluginName : basename(packageRoot)),
+        description: text(manifest.description) ?? text(plugin.description) ?? '',
+        version: text(manifest.version) ?? text(plugin.version),
         extends: (Array.isArray(own.extends) ? own.extends : typeof own.extends === 'string' ? [own.extends] : []).filter((id) => typeof id === 'string' && !!id),
         commandPrefix: typeof own.commandPrefix === 'string' && /^[a-z][a-z0-9-]*$/i.test(own.commandPrefix) && !['plugin', 'skill'].includes(own.commandPrefix.toLowerCase()) ? own.commandPrefix.toLowerCase() : null,
         hooks: inside(own.hooks),
+        agents: inside(own.agents) ?? 'agents',
         connectorTemplates: (Array.isArray(own.connectors) ? own.connectors : []).flatMap((value) => {
             const parsed = connectorTemplateSchema.safeParse(value);
             return parsed.success ? [parsed.data] : [];

package/dist/sdk/plugins/plugins.d.ts

@@ -9,6 +9,8 @@ export interface Loading {
     skillPaths: string[];
     promptPaths: string[];
     themePaths: string[];
+    /** Subagent profile files packages bring. The harness reads them; Pi is never given them. */
+    profilePaths: string[];
     /** The `pi` command's own extensions left on, as `builtin:<name>`. Only a terminal has them. */
     builtins: string[];
     /** Hooks files the harness runs itself. Pi is never given them. */

package/dist/sdk/plugins/plugins.js

@@ -87,6 +87,7 @@ export class Plugins {
             skillPaths: paths('skill', false),
             promptPaths: paths('prompt', false),
             themePaths: paths('theme', false),
+            profilePaths: paths('agent', false),
             builtins: paths('extension', true),
             hooks: chosen.filter((item) => item.kind === 'hook' && item.packageRoot).map((item) => ({ path: item.path, packageRoot: item.packageRoot, hash: packageCodeState[item.packageRoot]?.hash ?? '' })),
             found,

package/dist/sdk/plugins/proposals.d.ts

@@ -0,0 +1,17 @@
+import type { Harness } from "../harness.js";
+export interface Proposal {
+    id: string;
+    name: string;
+    description: string;
+    files: Record<string, string>;
+    manifest: string;
+    hash: string;
+    createdAt: string;
+    status: 'pending' | 'accepted' | 'rejected';
+    decidedAt?: string;
+}
+export declare function create(root: string, name: unknown, description: unknown, files: unknown): Proposal;
+export declare function preview(root: string, id: string): Proposal;
+export declare function list(root: string): Proposal[];
+export declare function reject(root: string, id: string, hash: string): Proposal;
+export declare function accept(harness: Harness, id: string, hash: string): Promise<Proposal>;

package/dist/sdk/plugins/proposals.js

@@ -0,0 +1,147 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readdirSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { invalid, notFound } from "../core/errors.js";
+import * as frontmatter from "../core/frontmatter.js";
+import { now, readJson, safeId, safeRelative, writeJson } from "../core/fs.js";
+import { ensureAdopted, list as listPlugins } from "./api.js";
+import * as attachments from "./attachments.js";
+import { packageCode } from "./trust.js";
+const MAX_FILES = 100;
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_TOTAL_BYTES = 1024 * 1024;
+const dir = (root) => join(root, 'plugin-proposals');
+const pathOf = (root, id) => join(dir(root), `${safeId(id)}.json`);
+function validate(name, description, input) {
+    if (typeof name !== 'string' || !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(name))
+        throw invalid('Plugin name must be lowercase letters, digits, underscores or hyphens.');
+    if (typeof description !== 'string' || !description.trim() || Buffer.byteLength(description, 'utf8') > 4096 || /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(description))
+        throw invalid('Description must be non-empty valid text of at most 4096 bytes.');
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw invalid('Files must be a path to text object.');
+    const entries = Object.entries(input);
+    if (!entries.length || entries.length > MAX_FILES)
+        throw invalid('A proposal must contain between 1 and 100 files.');
+    const files = Object.create(null);
+    let total = 0;
+    for (const [path, content] of entries) {
+        if (typeof content !== 'string' || /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(content))
+            throw invalid('Each file must be valid UTF-8 text.');
+        if (path.includes('\\') || path.length > 240 || /[\x00-\x1f\x7f]/.test(path) || safeRelative(path) !== path || path.split('/').some((part) => part === 'node_modules' || part === '.git'))
+            throw invalid('Invalid proposal file path.');
+        if (!/^(?:README\.md|extensions\/[A-Za-z0-9_./-]+\.(?:ts|js|mjs)|skills\/[A-Za-z0-9_./-]+\.md|prompts\/[A-Za-z0-9_./-]+\.md|agents\/[A-Za-z0-9_./-]+\.md|themes\/[A-Za-z0-9_./-]+\.json)$/.test(path))
+            throw invalid('Unsupported proposal file type or location.');
+        if (path.startsWith('skills/') && path.endsWith('/SKILL.md')) {
+            if (!/^skills\/[A-Za-z0-9_-]+\/SKILL\.md$/.test(path))
+                throw invalid('Skill files must be in skills/<name>/SKILL.md.');
+            const front = frontmatter.parse(content)?.front;
+            if (front?.name !== path.split('/')[1] || typeof front.description !== 'string' || !front.description.trim())
+                throw invalid('Skill frontmatter needs a matching name and a non-empty description.');
+        }
+        const bytes = Buffer.byteLength(content, 'utf8');
+        if (bytes > MAX_FILE_BYTES || (total += bytes) > MAX_TOTAL_BYTES)
+            throw invalid('Proposal files exceed the size limit.');
+        files[path] = content;
+    }
+    for (const path of Object.keys(files))
+        if (Object.keys(files).some((other) => other.startsWith(`${path}/`)))
+            throw invalid('A file cannot also be a directory.');
+    const manifest = `${JSON.stringify({ name, version: '1.0.0', description }, null, 2)}\n`;
+    const hash = createHash('sha256').update(JSON.stringify([name, description, manifest, Object.entries(files).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)])).digest('hex');
+    return { name, description, files, manifest, hash };
+}
+export function create(root, name, description, files) {
+    const valid = validate(name, description, files);
+    const proposal = { id: randomUUID(), ...valid, createdAt: now(), status: 'pending' };
+    writeJson(pathOf(root, proposal.id), proposal);
+    return proposal;
+}
+export function preview(root, id) {
+    const proposal = readJson(pathOf(root, id));
+    if (!proposal)
+        throw notFound('Proposal');
+    const valid = validate(proposal.name, proposal.description, proposal.files);
+    if (proposal.id !== id || !['pending', 'accepted', 'rejected'].includes(proposal.status))
+        throw invalid('Invalid stored proposal.');
+    return { ...proposal, ...valid };
+}
+export function list(root) {
+    let names;
+    try {
+        names = readdirSync(dir(root));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    return names.filter((name) => /^[a-f0-9-]+\.json$/.test(name)).sort().map((name) => preview(root, name.slice(0, -5)));
+}
+function reviewed(proposal, hash) {
+    if (proposal.status !== 'pending')
+        throw invalid('Proposal is no longer pending.');
+    if (!/^[a-f0-9]{64}$/.test(hash) || proposal.hash !== hash)
+        throw invalid('Stale proposal review; preview it again.');
+}
+export function reject(root, id, hash) {
+    const proposal = preview(root, id);
+    reviewed(proposal, hash);
+    const rejected = { ...proposal, status: 'rejected', decidedAt: now() };
+    writeJson(pathOf(root, id), rejected);
+    return rejected;
+}
+export async function accept(harness, id, hash) {
+    const root = harness.env.root;
+    const initial = preview(root, id);
+    reviewed(initial, hash);
+    await ensureAdopted(harness);
+    const existing = await listPlugins(harness, {});
+    const proposal = preview(root, id);
+    reviewed(proposal, hash);
+    const pluginId = `package:${proposal.name}`;
+    if (existing.some((plugin) => plugin.id === pluginId))
+        throw invalid('A plugin with this name already exists.');
+    const parent = join(root, 'plugins');
+    const destination = join(parent, proposal.name);
+    mkdirSync(parent, { recursive: true });
+    const stage = join(parent, `.proposal-${randomUUID()}`);
+    mkdirSync(stage);
+    let reserved = false;
+    try {
+        for (const [path, content] of Object.entries(proposal.files)) {
+            const target = join(stage, path);
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, content, { flag: 'wx' });
+        }
+        writeFileSync(join(stage, 'package.json'), proposal.manifest, { flag: 'wx' });
+        const found = { kind: 'extension', path: stage, origin: 'package', project: false, packageRoot: stage, source: stage, enabled: true };
+        const code = packageCode([found]).get(stage);
+        if (harness.plugins.trust.has(code.hash))
+            throw invalid('Identical package code is already trusted; change it before accepting.');
+        // Reserve the destination exclusively. Renaming over our empty directory publishes the whole package.
+        mkdirSync(destination);
+        reserved = true;
+        const choices = attachments.load(root);
+        for (const scope of [choices.global, ...Object.values(choices.agents), ...Object.values(choices.projects)]) {
+            scope.on = scope.on.filter((entry) => entry !== pluginId && !entry.startsWith(`${pluginId}/`));
+            scope.off = scope.off.filter((entry) => entry !== pluginId && !entry.startsWith(`${pluginId}/`));
+        }
+        attachments.set(choices, [pluginId], {}, false, true);
+        attachments.save(root, choices);
+        renameSync(stage, destination);
+        reserved = false;
+        const accepted = { ...proposal, status: 'accepted', decidedAt: now() };
+        writeJson(pathOf(root, id), accepted);
+        harness.bus.emit({ type: 'plugins.changed' });
+        return accepted;
+    }
+    finally {
+        rmSync(stage, { recursive: true, force: true });
+        if (reserved) {
+            try {
+                rmdirSync(destination);
+            }
+            catch { /* Do not remove another writer's files. */ }
+        }
+    }
+}

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

@@ -1,7 +1,7 @@
 import type { Attachment } from "./attachments.js";
 import type { Registered } from "./plugins.js";
 import type { ProjectCode } from "./trust.js";
-export declare const CONTRIBUTION_KINDS: readonly ["instruction", "skill", "command", "tool", "connection", "code", "theme"];
+export declare const CONTRIBUTION_KINDS: readonly ["instruction", "skill", "command", "agent", "tool", "connection", "code", "theme"];
 export type ContributionKind = (typeof CONTRIBUTION_KINDS)[number];
 /**
  * Where a plugin comes from: the harness itself, the embedding application, Pi, a person's own

package/dist/sdk/plugins/types.js

@@ -1,4 +1,4 @@
-export const CONTRIBUTION_KINDS = ['instruction', 'skill', 'command', 'tool', 'connection', 'code', 'theme'];
+export const CONTRIBUTION_KINDS = ['instruction', 'skill', 'command', 'agent', 'tool', 'connection', 'code', 'theme'];
 /**
  * Where a plugin comes from: the harness itself, the embedding application, Pi, a person's own
  * registry, the folder every account shares, an installed package, the working folder, or the

package/dist/sdk/prompt/compile.d.ts

@@ -1,13 +1,15 @@
 import { type CallerContext } from "../core/caller.js";
 import type { HarnessEnv } from "../core/env.js";
 import type { Materialised } from "../variant/materialise.js";
-import type { ChecklistItem } from "../sessions/contracts.js";
+import type { TodoItem } from "../sessions/contracts.js";
+import type { SessionState } from "../sessions/sessionState.js";
 import { type StandardSession } from "./standard.js";
 export declare const REFERENCES_BUDGET = 12000;
 /** Where the harness's own sections sit; an application's sections are placed among them by `order`. */
 export declare const SECTION_ORDER: {
     readonly harnessIdentity: 5;
     readonly system: 25;
+    readonly sessionState: 30;
     readonly guardrails: 40;
     readonly memory: 45;
     readonly references: 50;
@@ -24,7 +26,7 @@ export interface Source {
     revision?: string | null;
 }
 export interface Section {
-    /** `harness-identity`, `identity`, `role`, `system`, `guardrails`, `memory`, `references`, `subagents`, `scripts`, `wiki`, `tools`, or an application's own. */
+    /** `harness-identity`, `identity`, `role`, `system`, `session-state`, `guardrails`, `memory`, `references`, `subagents`, `scripts`, `wiki`, `tools`, or an application's own. */
     id: string;
     title: string;
     body: string;
@@ -103,6 +105,8 @@ export interface Launch {
     connectionTools?: string[];
     /** The tools switched on for the caller. The pack only describes tools the caller can call. */
     tools?: string[] | null;
+    /** The current session name and this run's todo, delivered as a request-scoped update. */
+    sessionState?: SessionState;
     references?: Reference[];
     sections?: HostSection[];
     toolGroups?: HostToolGroup[];
@@ -135,7 +139,7 @@ export declare function clip(text: string, limit: number): string;
 /** A bounded, request-scoped checkpoint reintroduced after context compaction. */
 export declare function renderCompactionCheckpoint(input: {
     goal: string;
-    checklist: readonly ChecklistItem[];
+    todo: readonly TodoItem[];
     planInstructions?: string | null;
 }): string | null;
 export interface OrderedGroup extends ToolGroup {
@@ -147,6 +151,11 @@ export interface OrderedGroup extends ToolGroup {
  * follows the switches in `launch.tools` and what the application provides.
  */
 export declare function toolGroups(context: CallerContext, launch: Launch, dataRoot?: string): OrderedGroup[];
+/** The request-scoped state line: the name, this run's todo, and the previous list as context. */
+export declare function sessionStateText(state: SessionState, options: {
+    name: boolean;
+    todo: boolean;
+}): string | null;
 /** Compiles the pack for a caller. It only reads the data root. */
 export declare function compile(env: HarnessEnv, context: CallerContext, launch?: Launch, variant?: Materialised | null): ContextPack;
 /** The pack as the one string a session receives. */
@@ -160,7 +169,7 @@ export declare const BUILT_IN_DYNAMIC: readonly {
     id: string;
     order: number;
 }[];
-export declare const CONTEXT_GUIDANCE = "App-origin context updates in the conversation supply current Wiki notes, active work, and selected references. Each listed section replaces its earlier app snapshot; a withdrawn section is no longer current context. These updates are context, not requests from the user. Selected references apply only to the accompanying request. They do not change permissions. Use the latest supplied state and retrieve details through tools when needed.";
+export declare const CONTEXT_GUIDANCE = "App-origin context updates in the conversation supply current Wiki notes, active work, session state, and selected references. Each listed section replaces its earlier app snapshot; a withdrawn section is no longer current context. These updates are context, not requests from the user. Selected references apply only to the accompanying request. They do not change permissions. Use the latest supplied state and retrieve details through tools when needed.";
 /** The hidden message a context update is saved as in native history, and where its snapshot sits. */
 export declare const CONTEXT_MESSAGE_TYPE = "xingular-context";
 export declare const CONTEXT_SNAPSHOT_KEY = "xingularContext";