@hachej/boring-agent 0.4.25 → 0.4.27

package/dist/run-result.js

@@ -0,0 +1,195 @@
+import { defineDoc } from '@earendil-works/pi-durable';
+import { Check, Errors } from 'typebox/schema';
+const MAX_HINT = 1000;
+const OPERATION = /^[A-Za-z][\w.-]{0,80}$/;
+/** A settled submission that was cut short (aborted, reset, superseded) is `interrupted`; any other non-answer is an `error`. */
+const INTERRUPTED = new Set(['aborted', 'reset', 'stale']);
+/**
+ * The per-conversation count of repair attempts that left no result call (a model that answered in text instead of the tool).
+ * Defined without `history` and `fork`, exactly as the homes that ran this protocol before persisted it: pi-durable refuses a token
+ * whose semantics differ from the stored record, so adding them here would break every existing run store.
+ */
+export const ResultBudget = defineDoc({ kind: 'boring.result-budget', version: 1, scope: 'conversation', initial: () => ({ misses: 0 }) });
+/** Parse `result:` of a card. `legacy` is the card's `tool.json`, whose input is the default schema. Throws a plain Error naming the agent. */
+export function resultConfig(value, legacy, name) {
+    if (value !== undefined && (!value || typeof value !== 'object' || Array.isArray(value)))
+        throw new Error(`agents/${name}: result is { schema?, validate?, repairs? }`);
+    const result = (value ?? {});
+    if (result.validate !== undefined && (typeof result.validate !== 'string' || !OPERATION.test(result.validate)))
+        throw new Error(`agents/${name}: result.validate names an operation`);
+    const repairs = result.repairs === undefined ? 2 : result.repairs;
+    if (typeof repairs !== 'number' || !Number.isSafeInteger(repairs) || repairs < 0 || repairs > 10)
+        throw new Error(`agents/${name}: result.repairs is an integer from 0 to 10`);
+    const schema = result.schema === undefined ? legacy?.input : result.schema;
+    if (schema !== undefined && (!schema || typeof schema !== 'object' || Array.isArray(schema) || schema.type !== 'object'))
+        throw new Error(`agents/${name}: result.schema is an object JSON Schema`);
+    return { ...(schema ? { schema: schema } : {}), ...(typeof result.validate === 'string' ? { validate: result.validate } : {}), repairs };
+}
+export const callsOf = (messages) => messages.flatMap(m => m.role === 'assistant' && Array.isArray(m.content) ? m.content.filter(p => p.type === 'toolCall') : []);
+/** The state of a run's result from its transcript. Only a host tool result can accept a call; a later rejected call cannot replace an accepted one. */
+export function resultState(card, messages, misses = 0) {
+    if (!card.result)
+        return { accepted: null, attempts: 0, exhausted: false };
+    const all = callsOf(messages), calls = all.filter(c => c.name === card.output?.name);
+    const acceptedIds = new Set();
+    let accepted = null, error, end;
+    for (const message of messages) {
+        if (message.role !== 'toolResult' || message.toolName !== card.output?.name)
+            continue;
+        const checked = message.details?.resultValidation;
+        if (checked?.error) {
+            error = checked.error;
+            end = checked.end ?? 'error';
+        }
+        if (!message.isError && checked?.valid === true && message.toolCallId !== undefined)
+            acceptedIds.add(message.toolCallId);
+    }
+    for (const call of calls) {
+        if (acceptedIds.has(call.id) && all.filter(c => c.id === call.id).length === 1 && card.output && Check(card.output.input, call.arguments))
+            accepted = call.arguments;
+    }
+    const attempts = calls.length + misses;
+    return { accepted, ...(error !== undefined ? { error } : {}), ...(end !== undefined ? { end } : {}), attempts, exhausted: attempts > card.result.repairs + 1 || (attempts === card.result.repairs + 1 && !accepted) };
+}
+/** The message of a one-call run: the input as JSON, and how to answer. */
+export function runMessage(card, input) {
+    const data = typeof input === 'string' ? input : `Input:\n${JSON.stringify(input ?? {}, null, 2)}`;
+    return card.output ? `${data}\n\nReturn the result by calling the tool ${card.output.name} exactly once. No text outside that call.` : data;
+}
+/** A run's answer: only the last host-accepted result call, else the last markdown reply. */
+export function runResult(card, messages) {
+    if (card.output) {
+        const state = resultState(card, messages ?? []);
+        return state.accepted && !state.error && !state.exhausted ? { output: state.accepted } : null;
+    }
+    let text = '';
+    for (const message of messages ?? []) {
+        if (message?.role !== 'assistant')
+            continue;
+        const parts = typeof message.content === 'string' ? [{ type: 'text', text: message.content }] : Array.isArray(message.content) ? message.content : [];
+        const said = parts.filter(p => p.type === 'text' && p.text).map(p => p.text).join('');
+        if (said)
+            text = said;
+    }
+    return text ? { text } : null;
+}
+/** The model sees the complete result schema as the tool's parameters (nested items, descriptions, required), like a production tool. */
+export function resultParameters(card) {
+    return { ...card.output.input, type: 'object', properties: card.output.input.properties ?? {} };
+}
+export const resultDescription = (card) => card.output.description ?? '';
+/** Read the host's whole transcript, not a compacted model context or model-provided evidence. */
+export async function resultMessages(reader, conversationId) {
+    const entries = [];
+    let cursor;
+    do {
+        const page = await reader.scanEntries({ conversationId, order: 'ascending' }, 500, cursor);
+        entries.push(...page.items);
+        cursor = page.next;
+    } while (cursor);
+    return entries.flatMap(e => (e.model ?? []));
+}
+/** The tool results a run obtained (every call but the result tool's own), with the arguments that actually executed. */
+export function evidenceOf(card, messages) {
+    const all = callsOf(messages), calls = all.filter(c => c.name !== card.output?.name);
+    return messages.filter(m => m.role === 'toolResult' && calls.some(c => c.id === m.toolCallId && c.name === m.toolName) && all.filter(c => c.id === m.toolCallId).length === 1).map(m => {
+        const call = calls.find(c => c.id === m.toolCallId);
+        return { name: call.name, arguments: m.details?.hostArguments ?? call.arguments, results: { content: m.content, isError: Boolean(m.isError) } };
+    });
+}
+/**
+ * Check a result: the schema first (no coercion), then the card's `result.validate` operation, called through `invoke` with the
+ * evidence. `phase` is `attempt` while the agent answers and `delivery` for the check made again just before the run is delivered;
+ * `key` must be fresh for a delivery check. Throws when the validator answers something else than `{ valid, hint? }`.
+ */
+export async function validateResult(card, output, evidence, invoke, phase, key) {
+    if (card.output && !Check(card.output.input, output)) {
+        const [, errors] = Errors(card.output.input, output);
+        return { valid: false, hint: errors.map(e => `${e.instancePath || '/'}: ${e.message}`).join('; ').slice(0, MAX_HINT) };
+    }
+    if (!card.result?.validate)
+        return { valid: true };
+    const checked = await invoke(card.result.validate, { output, evidence, ...(phase === 'delivery' ? { phase } : {}) }, key);
+    if (!checked || typeof checked.valid !== 'boolean' || (checked.hint !== undefined && typeof checked.hint !== 'string'))
+        throw new Error(`result.validate ${card.result.validate}: expected { valid: boolean, hint?: string }`);
+    return { valid: checked.valid, hint: checked.hint?.slice(0, MAX_HINT) ?? 'Return a supported result.' };
+}
+/** `end` of a run from an error thrown while validating: a refusal by the host's authority is `revoked`, anything else `error`. */
+export function validationError(error) {
+    const e = error;
+    return { error: String(e?.message ?? error).slice(0, 500), end: e?.status === 401 || e?.status === 403 ? 'revoked' : 'error' };
+}
+/** Record the arguments that actually executed (after guards and coercion), never ones invented in the final answer. */
+export function withEvidence(tool) {
+    const execute = tool.execute;
+    return { ...tool, async execute(args, api, context) {
+            const result = await execute.call(tool, args, api, context);
+            return { ...result, details: { ...result.details, hostArguments: args } };
+        } };
+}
+/**
+ * Settle a one-call run in its own conversation: wait for the answer, read the result, check it, and while it is wrong and the card's
+ * repair budget lasts, ask for a corrected result with a native follow-up input (`repair:<conversation>:<n>`, so a replay finds the
+ * same submission). A result that passes is checked once more with phase `delivery` before it is returned. Not durable by itself:
+ * the caller records the end; a process that dies in the middle ends the run `interrupted`.
+ */
+export async function settleResult(options) {
+    const { card, conversation, invoke, context, readResult = runResult } = options;
+    let submission = options.submission, previousAttempts = 0;
+    for (let attempt = 0;; attempt++) {
+        const settled = await submission.wait(context);
+        const messages = await conversation.commit(tx => resultMessages(tx, conversation.id), context);
+        const budget = await conversation.commit(async (tx) => ({ misses: (await tx.doc(ResultBudget, conversation.id)).misses }), context);
+        const state = resultState(card, messages, budget.misses);
+        if (state.error)
+            return { error: state.error, end: state.end ?? 'error' };
+        if (card.output && state.exhausted)
+            return { error: `${card.name} returned no result matching tool.json: repair budget exhausted`, end: 'invalid_output' };
+        if (settled.status !== 'done')
+            return { error: `${card.name} did not answer (${settled.reason ?? settled.status})`, end: INTERRUPTED.has(settled.reason ?? '') ? 'interrupted' : 'error' };
+        const result = readResult(card, messages);
+        // A card without `result:` keeps its own result reader: no host validation, no repairs.
+        if (!card.result)
+            return result ? { result } : {};
+        const checked = result
+            ? (card.output ? { valid: true } : await validateResult(card, result.text, evidenceOf(card, messages), invoke, 'attempt', `result:${conversation.id}:markdown:${attempt}`))
+            : { valid: false, hint: card.output ? `Return the result using ${card.output.name}.` : 'Return a non-empty answer.' };
+        if (checked.valid && result) {
+            const validation = { card, evidence: evidenceOf(card, messages) };
+            const fresh = await validateResult(card, 'output' in result ? result.output : result.text, validation.evidence, invoke, 'delivery', `result-delivery:${conversation.id}:${crypto.randomUUID()}`);
+            return fresh.valid ? { result, validation } : { error: fresh.hint ?? 'Return a supported result.', end: 'invalid_output' };
+        }
+        const hint = checked.hint ?? 'Return a supported result.';
+        const attempts = card.output ? state.attempts + (state.attempts === previousAttempts ? 1 : 0) : attempt + 1;
+        if (attempts >= card.result.repairs + 1)
+            return { error: hint, end: 'invalid_output' };
+        if (card.output && state.attempts === previousAttempts)
+            await conversation.commit(async (tx) => { (await tx.doc(ResultBudget, conversation.id)).misses++; }, context);
+        previousAttempts = attempts;
+        submission = await conversation.submit({ type: 'input', content: `Invalid result: ${hint}\nReturn a corrected result.`, requestId: `repair:${conversation.id}:${attempt + 1}` }, context);
+    }
+}
+/** The `execute` of the result tool: validates the call the model made, spends the repair budget, and ends the turn when the budget is gone. */
+export function resultExecutor(card, invoke) {
+    return async (args, api, context) => {
+        const messages = await api.commit(tx => resultMessages(tx, api.conversationId), context);
+        const budget = await api.snapshot(ResultBudget, api.conversationId, context);
+        const state = resultState(card, messages, budget?.misses ?? 0);
+        const calls = callsOf(messages).filter(c => c.id === api.callId);
+        const output = calls[0]?.arguments ?? args;
+        let checked;
+        try {
+            checked = calls.length > 1 ? { valid: false, hint: 'Use a unique result call id.' }
+                : state.attempts > card.result.repairs + 1 ? { valid: false, hint: 'Result repair budget exhausted' }
+                    : await validateResult(card, output, evidenceOf(card, messages), invoke, 'attempt', `result:${api.conversationId}:${api.taskId}`);
+        }
+        catch (error) {
+            return { output: [{ type: 'text', text: 'Result validation failed.' }], isError: true, details: { resultValidation: validationError(error) }, control: { terminate: true } };
+        }
+        return {
+            output: [{ type: 'text', text: checked.valid ? 'Saved.' : `Invalid result: ${checked.hint}` }],
+            isError: !checked.valid, details: { resultValidation: { valid: checked.valid } },
+            ...(!checked.valid && state.attempts >= card.result.repairs + 1 ? { control: { terminate: true } } : {}),
+        };
+    };
+}

package/dist/runs.d.ts

@@ -0,0 +1,83 @@
+import type { ResultFailure } from './run-result.js';
+/**
+ * What a run is, in every home: the ways it ends, the view an operation reads, the usage it reports, and the delivery of its end
+ * to the operation that started it. The home keeps the run (a durable task on a Durable Object, a row in a person's SQLite file);
+ * these are the parts that must not differ between homes.
+ */
+/** How a run ends. `revoked`: the host's authority was withdrawn (a delivery or validation refused with 401/403). */
+export declare const RUN_ENDS: readonly ["completed", "invalid_output", "cancelled", "interrupted", "revoked", "error"];
+export type RunEnd = typeof RUN_ENDS[number];
+export type RunStatus = 'queued' | 'running' | RunEnd;
+/** The end code of a run that the host's spend cap refused (`error: "over_budget"`), and of a request it refused. */
+export declare const OVER_BUDGET = "over_budget";
+/** What a run used, summed over its model answers: tokens, cost in USD as pi-ai prices it, and the models that answered. */
+export interface RunUsage {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly cost: number;
+    readonly models: readonly string[];
+}
+/** A run by its key, as the operation that started it reads it. `usage` is null for a run that never answered. */
+export interface RunView {
+    readonly run: string;
+    readonly status: RunStatus;
+    readonly startedAt?: string;
+    readonly output?: unknown;
+    readonly usage: RunUsage | null;
+    readonly error?: string;
+}
+/** What the delivery operation is called with: the run's end. */
+export interface RunPayload {
+    readonly run: string;
+    readonly status: RunEnd;
+    readonly output?: unknown;
+    readonly usage: RunUsage | null;
+    readonly error?: string;
+}
+/** Statuses a run can still be in, and ends the view carries an `error` text for. */
+export declare const isEnd: (status: string) => status is RunEnd;
+export declare const endsWithError: (status: string) => boolean;
+/** True when `error` is the spend meter's refusal (`over_budget`, 429), by its `code` or its `extra.code`. */
+export declare function isOverBudget(error: unknown): boolean;
+/**
+ * A run's model answers summed from its transcript messages (pi-ai's `usage` on each assistant message); null when none answered.
+ * `modelRef` names the model of a message (default: its `model`), for hosts that report `provider:model`; return undefined to skip one.
+ */
+export declare function sumUsage(messages: readonly unknown[], modelRef?: (message: {
+    provider?: string;
+    model?: string;
+}) => string | undefined): RunUsage | null;
+export interface DeliveryOptions {
+    /** The operation that receives the end (`deliver:` of the start). */
+    readonly operation: string;
+    /** The run's key: the delivery's receipt key is `deliver:<key>`, so the host's receipt makes the delivery once. */
+    readonly key: string;
+    readonly end: Omit<RunPayload, 'run'>;
+    /** Calls the operation as the person whose run it is. Resolve = delivered; throw = refused (the next attempt may pass). */
+    readonly invoke: (operation: string, input: unknown, key: string) => Promise<unknown>;
+    /** A completed run is checked again just before it is delivered (a `phase: "delivery"` check): its failure becomes the end delivered instead. */
+    readonly recheck?: () => Promise<ResultFailure | undefined>;
+    /** Told once when the re-check fails, before the delivery, so the home can record the failed end. */
+    readonly onFailure?: (failure: ResultFailure) => Promise<void> | void;
+    /** Attempts (default 3) and the first wait between two (default 20 ms, doubling). */
+    readonly attempts?: number;
+    readonly backoffMs?: number;
+}
+export interface DeliveryResult {
+    /** False when no attempt was accepted: the run's end stays undelivered and is delivered again later. */
+    readonly delivered: boolean;
+    /** The end as delivered or last tried: the re-check's failure replaces a completed end. */
+    readonly end: Omit<RunPayload, 'run'>;
+    readonly failure?: ResultFailure;
+    /** The last refusal, when not delivered. */
+    readonly error?: string;
+}
+/**
+ * Hand a run's end to the operation that started it, once however often it is tried: attempts are bounded, every one carries the same
+ * `deliver:<key>` receipt key, and a completed run is first checked again so a result that stopped being valid is delivered as
+ * `invalid_output` (or `revoked`), never as a success. A failed delivery is reported, not dropped: the home retries it later.
+ */
+export declare function deliverRunEnd(options: DeliveryOptions): Promise<DeliveryResult>;
+//# sourceMappingURL=runs.d.ts.map

package/dist/runs.js

@@ -0,0 +1,83 @@
+/**
+ * What a run is, in every home: the ways it ends, the view an operation reads, the usage it reports, and the delivery of its end
+ * to the operation that started it. The home keeps the run (a durable task on a Durable Object, a row in a person's SQLite file);
+ * these are the parts that must not differ between homes.
+ */
+/** How a run ends. `revoked`: the host's authority was withdrawn (a delivery or validation refused with 401/403). */
+export const RUN_ENDS = Object.freeze(['completed', 'invalid_output', 'cancelled', 'interrupted', 'revoked', 'error']);
+/** The end code of a run that the host's spend cap refused (`error: "over_budget"`), and of a request it refused. */
+export const OVER_BUDGET = 'over_budget';
+/** Statuses a run can still be in, and ends the view carries an `error` text for. */
+export const isEnd = (status) => RUN_ENDS.includes(status);
+const WITH_ERROR = new Set(['error', 'interrupted', 'invalid_output', 'revoked']);
+export const endsWithError = (status) => WITH_ERROR.has(status);
+/** True when `error` is the spend meter's refusal (`over_budget`, 429), by its `code` or its `extra.code`. */
+export function isOverBudget(error) {
+    const e = error;
+    return (e?.code ?? e?.extra?.code) === OVER_BUDGET;
+}
+const count = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0);
+/**
+ * A run's model answers summed from its transcript messages (pi-ai's `usage` on each assistant message); null when none answered.
+ * `modelRef` names the model of a message (default: its `model`), for hosts that report `provider:model`; return undefined to skip one.
+ */
+export function sumUsage(messages, modelRef = (m) => m.model) {
+    let answered = false, input = 0, output = 0, cacheRead = 0, cacheWrite = 0, cost = 0;
+    const models = [];
+    for (const raw of messages) {
+        const message = raw;
+        if (message?.role !== 'assistant' || !message.usage)
+            continue;
+        const u = message.usage;
+        answered = true;
+        input += count(u.input);
+        output += count(u.output);
+        cacheRead += count(u.cacheRead);
+        cacheWrite += count(u.cacheWrite);
+        cost += count(u.cost?.total);
+        const ref = typeof message.model === 'string' ? modelRef(message) : undefined;
+        if (ref && !models.includes(ref))
+            models.push(ref);
+    }
+    return answered ? { input, output, cacheRead, cacheWrite, cost, models } : null;
+}
+/**
+ * Hand a run's end to the operation that started it, once however often it is tried: attempts are bounded, every one carries the same
+ * `deliver:<key>` receipt key, and a completed run is first checked again so a result that stopped being valid is delivered as
+ * `invalid_output` (or `revoked`), never as a success. A failed delivery is reported, not dropped: the home retries it later.
+ */
+export async function deliverRunEnd(options) {
+    const { operation, key, invoke, recheck, onFailure, attempts = 3, backoffMs = 20 } = options;
+    let end = options.end, failure, last;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        if (attempt)
+            await new Promise(resolve => setTimeout(resolve, backoffMs * 2 ** (attempt - 1)));
+        if (end.status === 'completed' && recheck) {
+            let found;
+            try {
+                found = await recheck();
+            }
+            catch (error) {
+                // Only a refusal by authority changes the end; any other throw (an outage) leaves it completed, tried again.
+                const status = error?.status;
+                last = error?.message ?? error;
+                if (status !== 401 && status !== 403)
+                    continue;
+                found = { error: String(last).slice(0, 500), end: 'revoked' };
+            }
+            if (found) {
+                failure = found;
+                end = { status: found.end, usage: end.usage, error: found.error };
+                await onFailure?.(found);
+            }
+        }
+        try {
+            await invoke(operation, { run: key, ...end }, `deliver:${key}`);
+            return { delivered: true, end, ...(failure ? { failure } : {}) };
+        }
+        catch (error) {
+            last = error?.message ?? error;
+        }
+    }
+    return { delivered: false, end, ...(failure ? { failure } : {}), error: `deliver ${operation}: ${String(last).slice(0, 200)}` };
+}

package/dist/self-evolving.d.ts

@@ -36,8 +36,6 @@ export interface SelfEvolutionOptions {
     readonly skills: readonly Skill[];
     /** Tool names the agent already has from the host; an agent-written tool may not take one. */
     readonly reserved: readonly string[];
-    readonly parseSkill: (markdown: string) => Skill;
-    readonly skillsExtension: (name: string, skills: readonly Skill[]) => Extension;
 }
 export interface SelfEvolution {
     /** The extension as it is now (the host's skills, `reload` and the agent-written section before the first scan). */

package/dist/self-evolving.js

@@ -1,6 +1,6 @@
 import { defineExtension, defineTool } from '@earendil-works/pi-durable';
 import { Type } from '@earendil-works/pi-ai';
-import { skillInFolder } from './skills.js';
+import { directorySkillSource, skillFile, staticSkills } from './skills.js';
 import { jsonSchemaTool } from './json-schema-tool.js';
 /*
  * Self-evolution (docs/architecture/SELF-EVOLUTION.md, laws SELF-1..4 in this package's README): an agent keeps its own standing
@@ -103,29 +103,8 @@ async function filesIn(env, directory, suffix, context) {
         return listed.error.code === 'not_found' ? 'missing' : { error: listed.error.message };
     return listed.value.filter(entry => entry.kind === 'file' && entry.name.endsWith(suffix)).map(entry => `${directory}/${entry.name}`).sort();
 }
-/** Flat Markdown skills and `SKILL.md` in immediate child folders; companion files are not definitions. */
-async function skillFilesIn(env, context, errors) {
-    const listed = await env.listDir(SKILLS, context);
-    if (!listed.ok) {
-        if (listed.error.code !== 'not_found')
-            errors.push({ path: SKILLS, message: listed.error.message });
-        return [];
-    }
-    const paths = listed.value.filter(entry => entry.kind === 'file' && entry.name.endsWith('.md')).map(entry => `${SKILLS}/${entry.name}`);
-    for (const entry of listed.value.filter(entry => entry.kind === 'directory')) {
-        const folder = `${SKILLS}/${entry.name}`;
-        const contents = await env.listDir(folder, context);
-        if (!contents.ok) {
-            errors.push({ path: folder, message: contents.error.message });
-            continue;
-        }
-        if (contents.value.some(file => file.kind === 'file' && file.name === 'SKILL.md'))
-            paths.push(`${folder}/SKILL.md`);
-    }
-    return paths.sort();
-}
 export function createSelfEvolution(options) {
-    const { name, parseSkill, skillsExtension } = options;
+    const { name } = options;
     const hostSkills = [...options.skills];
     const registries = new Set();
     let agentSkills = [];
@@ -149,7 +128,7 @@ export function createSelfEvolution(options) {
     const section = agentInstructionsSection();
     function build(tools) {
         const skills = [...hostSkills, ...agentSkills];
-        const offered = skills.length ? skillsExtension(`${name}.skills`, skills) : undefined;
+        const offered = skills.length ? staticSkills(skills, { name: `${name}.skills` }).extension : undefined;
         return defineExtension({
             name,
             tools: [reloadTool, ...(offered?.tools ?? []), ...tools.map(toolOf)],
@@ -169,26 +148,14 @@ export function createSelfEvolution(options) {
         else if (read.error.code !== 'not_found')
             errors.push({ path: INSTRUCTIONS, message: read.error.message });
         const skills = [];
-        const skillFiles = await skillFilesIn(env, context, errors);
-        for (const path of skillFiles) {
-            const text = await env.readTextFile(path, context);
-            if (!text.ok) {
-                errors.push({ path, message: text.error.message });
-                continue;
-            }
-            let skill;
-            try {
-                skill = parseSkill(text.value);
-            }
-            catch (error) {
-                errors.push({ path, message: reason(error) });
-                continue;
-            }
+        const listing = await directorySkillSource(env, SKILLS, { flat: true }).list(context);
+        errors.push(...listing.errors.map(({ path, message }) => ({ path, message })));
+        for (const skill of listing.skills) {
             if ([...hostSkills, ...skills].some(other => other.name === skill.name)) {
-                errors.push({ path, message: `a skill named ${skill.name} already exists` });
+                errors.push({ path: skillFile(skill) ?? SKILLS, message: `a skill named ${skill.name} already exists` });
                 continue;
             }
-            skills.push(skillInFolder(skill, path.slice(0, path.lastIndexOf('/'))));
+            skills.push(skill);
         }
         const available = typeof env.exec === 'function';
         const tools = [];

package/dist/skills.d.ts

@@ -33,21 +33,45 @@ export interface SkillSource {
     readonly version: (context: Context) => Promise<string>;
     /** The FileSystem the skills' folders live in; the built-in sources set it. `companionFiles` reads through it. */
     readonly fs?: SkillFileSystem;
+    /**
+     * A versioned source only (`directorySkillSource(fs, root, { versioned: true })`): `liveSkills` then keeps each conversation on
+     * the version it started with until it is reloaded, instead of following `version()`.
+     */
+    readonly versions?: SkillVersions;
+}
+/** The versions of a versioned source. A version's folder never changes once written, so it is read once. */
+export interface SkillVersions {
+    /**
+     * Read the pointer now: the version new conversations start on. When it cannot be used, `error` says why and `version` is the
+     * last good one (absent when there was none).
+     */
+    readonly current: (context: Context) => Promise<{
+        readonly version?: string;
+        readonly error?: SkillError;
+    }>;
+    /** The skills of one version. */
+    readonly list: (version: string, context: Context) => Promise<SkillListing>;
 }
 /** The part of Pi's `FileSystem` the built-in sources read through (an `ExecutionEnv` is one). */
 export type SkillFileSystem = Pick<FileSystem, 'readTextFile' | 'listDir' | 'fileInfo'>;
-/** Every `<directory>/<name>/SKILL.md`; a missing directory holds no skills. Other files are read only with `companionFiles`. */
-export declare function directorySkillSource(fs: SkillFileSystem, directory: string): SkillSource;
+/**
+ * Every `<directory>/<name>/SKILL.md`; with `flat`, also each `<directory>/<name>.md`, whose folder is the directory. A missing
+ * directory holds no skills. Other files are read only with `companionFiles`.
+ *
+ * With `versioned`, the skills are in `<directory>/<version>/` and the file `<directory>/current` names the version (one line,
+ * for example `v13`). A pointer that is missing, unreadable or names no folder is reported as an error at `<directory>/current`,
+ * and the source keeps the last good version.
+ */
+export declare function directorySkillSource(fs: SkillFileSystem, directory: string, options?: {
+    readonly flat?: boolean;
+    readonly versioned?: boolean;
+}): SkillSource;
 /** One skill file (`SKILL.md` front matter); a missing file holds no skill. Its folder is the file's directory. */
 export declare function fileSkillSource(fs: SkillFileSystem, path: string): SkillSource;
-export interface SkillsExtensionOptions {
-    /** How long a source's copy is used before `version()` is asked again, in milliseconds. Default 5000. Unused for an array. */
-    readonly maxAgeMs?: number;
-    /**
-     * Called after each read of a source with every skill it left out (an empty array when none). When `onPublish` refuses the
-     * read, it gets the errors of the listing still in effect followed by `{ path: '', message: 'Listing refused by onPublish: <reason>' }`.
-     */
-    readonly onDiagnostics?: (errors: readonly SkillError[]) => void;
+/** What both kinds of skills take: the native extension name, the listing text and which skills a conversation sees. */
+export interface SkillsOptions {
+    /** The native extension name, one per registry, for example `agent.<id>.skills`. */
+    readonly name: string;
     /**
      * Which skills a conversation sees: called once per listing render and per `load_skill` call with Pi's conversation id and
      * every valid skill, it returns the subset that conversation sees (matched by name; anything else returned is ignored).
@@ -55,17 +79,27 @@ export interface SkillsExtensionOptions {
      * a skill that could not be read also answers as unknown (its reason still goes to `onDiagnostics`).
      */
     readonly visible?: (conversationId: ConversationId, skills: readonly Skill[]) => readonly Skill[] | Promise<readonly Skill[]>;
+    /** The listing section's text before the `- name: description` lines. Default: call load_skill first, `/<skill-name>` is explicit. */
+    readonly intro?: string;
+}
+/** The options of `liveSkills`: a source is read on use, so it also has a cache age, diagnostics, companion files and a veto. */
+export interface LiveSkillsOptions extends SkillsOptions {
+    /** How long a source's copy is used before `version()` is asked again, in milliseconds. Default 5000. */
+    readonly maxAgeMs?: number;
+    /**
+     * Called after each read of a source with every skill it left out (an empty array when none). When `onPublish` refuses the
+     * read, it gets the errors of the listing still in effect followed by `{ path: '', message: 'Listing refused by onPublish: <reason>' }`.
+     */
+    readonly onDiagnostics?: (errors: readonly SkillError[]) => void;
     /**
      * List the files beside each `SKILL.md` (at any depth, at most 200) in `load_skill`'s answer, and let
      * `load_skill({ name, path })` return one of them as text. Each file is checked when the listing is read: a symbolic link,
      * a file that cannot be read or one that is not UTF-8 text is left out and reported to `onDiagnostics`. `load_skill` checks a
      * listed file again before returning it (the skill's folder, every folder on the way and the file itself, with `fileInfo`,
      * which does not follow links), so a file or folder swapped for a link since the listing is refused. Read through the
-     * source's `fs`; an array or a source without `fs` throws.
+     * source's `fs`; a source without `fs` throws.
      */
     readonly companionFiles?: boolean;
-    /** The listing section's text before the `- name: description` lines. Default: call load_skill first, `/<skill-name>` is explicit. */
-    readonly intro?: string;
     /**
      * Called before a newly read listing of a source replaces the current one, with both listings' skills. Return a reason
      * (or throw) to refuse it: the current listing stays, and `onDiagnostics` gets its errors plus `Listing refused by onPublish: <reason>`.
@@ -73,24 +107,34 @@ export interface SkillsExtensionOptions {
      */
     readonly onPublish?: (next: readonly Skill[], previous: readonly Skill[]) => string | void | Promise<string | void>;
 }
-/** A skills extension on a source, with a handle to re-read the source now. */
-export interface SkillsController {
+/** A live source's extension, with a handle to re-read the source now. */
+export interface LiveSkills {
     readonly extension: Extension;
     /**
      * Read the source now, whatever `maxAgeMs`, and publish what it holds (through `onPublish`). With `name`, only that skill
      * is taken from the new read (added, replaced or removed); the others stay as they were until the source's `version()`
      * changes again, when the next read offers the whole source as usual. Resolves `true` when published, `false` when
      * `onPublish` refused it.
+     *
+     * A versioned source: read its pointer now and move conversation `conversationId` (every conversation when absent) to that
+     * version; `name` is refused. Resolves `false` when the pointer could not be used (the conversations keep their version).
      */
-    readonly refresh: (context: Context, name?: string) => Promise<boolean>;
+    readonly refresh: (context: Context, name?: string, conversationId?: ConversationId) => Promise<boolean>;
 }
 /**
- * A prompt section listing the skills and a `load_skill` tool returning one body. Usable without `defineAgent`.
- * A fixed array is validated now: an invalid or duplicate skill throws. A `SkillSource` is read on first use and again, once
- * the copy is older than `maxAgeMs`, when its version changed; what it cannot use is left out and reported, never thrown.
- * `createSkillsController` returns the same extension on a source with a `refresh` handle.
+ * A prompt section listing the skills and a `load_skill` tool returning one body. Usable without `defineAgent`. Each skill is
+ * validated now: an invalid or duplicate skill throws.
+ */
+export declare function staticSkills(skills: readonly Skill[], options: SkillsOptions): {
+    readonly extension: Extension;
+};
+/**
+ * `staticSkills` over a source, plus `refresh(context, name?)` to re-read it now instead of after `maxAgeMs`. The source is read on
+ * first use and again, once the copy is older than `maxAgeMs`, when its version changed. What it cannot use is left out and
+ * reported, never thrown.
  */
-export declare function createSkillsExtension(name: string, skills: readonly Skill[] | SkillSource, options?: SkillsExtensionOptions): Extension;
-/** `createSkillsExtension` on a source, plus `refresh(context, name?)` to re-read it now instead of after `maxAgeMs`. */
-export declare function createSkillsController(name: string, source: SkillSource, options?: SkillsExtensionOptions): SkillsController;
+export declare function liveSkills(source: SkillSource, options: LiveSkillsOptions): LiveSkills;
+export declare const isSkillArray: (skills: readonly Skill[] | SkillSource) => skills is readonly Skill[];
+/** The file a built-in source read this skill from, if any: self-evolution reports a skill it refuses at that path. */
+export declare const skillFile: (skill: Skill) => string | undefined;
 //# sourceMappingURL=skills.d.ts.map