@hachej/boring-agent 0.4.3 → 0.4.5

package/dist/memory/optchat.js

@@ -1,3 +1,5 @@
+// Adapted from VictorTaelin/uniichat, Copyright 2026 Higher Order Company, Apache-2.0.
+// Changed: Pi-native tasks, documents, message adaptation and host memory controls. See ../../NOTICE and ../../licenses/Apache-2.0.txt.
 // OptChat memory as one native pi-durable extension, opt-in per conversation.
 // The Pi transcript is the append-only log and is never rewritten. While the extension is selected, `beforeRequest` shows
 // the model one view of everything before the current turn: a tiling of the log by summary-tree nodes, one `id+n|text`
@@ -15,7 +17,17 @@ export { OptChatLog, OptChatTree, advanceFold, emptyFold, leavesOf, renderView,
 export const OptChatNodes = defineDocFamily({
     kind: 'boring.memory.optchat.nodes', version: 1, family: true, scope: 'conversation', history: 'latest', fork: 'current', initial: () => ({ nodes: {} }),
 });
-/** Compactor bookkeeping of one conversation: the summarizer's calls and spend, and the last failure of each node (the retry spacing reads it; no timer does). */
+/** Seed memories, stored once per conversation and inherited by forks. They precede the Pi transcript in the memory only. */
+export const OptChatNotes = defineDoc({
+    kind: 'boring.memory.optchat.notes', version: 1, scope: 'conversation', history: 'latest', fork: 'current',
+    initial: () => ({ seeded: false, notes: [] }),
+});
+/** Memory-only tombstones. Values are leaf counts, never the forgotten content. Pi's transcript is unchanged. */
+export const OptChatEdits = defineDoc({
+    kind: 'boring.memory.optchat.edits', version: 1, scope: 'conversation', history: 'latest', fork: 'current',
+    initial: () => ({ revision: 0, forgotten: {} }),
+});
+/** Compactor bookkeeping of one conversation: calls, spend and the last failure of each node, including its retry streak. */
 export const OptChatState = defineDoc({
     kind: 'boring.memory.optchat.state', version: 1, scope: 'conversation', history: 'latest', fork: 'initial',
     initial: () => ({ calls: 0, usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 }, failures: {} }),
@@ -28,6 +40,7 @@ class Session {
     stored = new Map();
     tree;
     fold = emptyFold();
+    compactFold = emptyFold();
     /** Summary tasks may be created for leaves below this; the current turn's steps are held back while a request runs. */
     upTo = 0;
     lastRequest;
@@ -41,11 +54,33 @@ class Session {
         if (this.log.set(leaves) < before) {
             this.tree.reset();
             this.fold = emptyFold();
+            this.compactFold = emptyFold();
         }
     }
 }
 const message = (text) => ({ role: 'user', content: text.map(part => ({ type: 'text', text: part })), timestamp: Date.now() });
 const LIVE = ['pending', 'running', 'waiting'];
+function redacted(item) {
+    if (item.role === 'system')
+        return item;
+    if (item.role === 'assistant')
+        return { ...item, content: item.content.flatMap((part) => part.type === 'toolCall'
+                ? [{ type: 'toolCall', id: part.id, name: 'forgotten', arguments: {} }]
+                : part.type === 'text' ? [{ type: 'text', text: '(forgotten)' }] : []) };
+    if (item.role === 'toolResult')
+        return { ...item, toolName: 'forgotten', content: [{ type: 'text', text: '(forgotten)' }] };
+    return { ...item, content: '(forgotten)' };
+}
+/** Pi's TextContent has no per-block cache marker. Keep the reference's four-line blocks without inventing one. */
+function chatBlocks(lines) {
+    const rows = lines ? lines.split('\n') : [];
+    const blocks = ['<chat>\n'];
+    let i = 0;
+    for (; i + 4 <= rows.length; i += 4)
+        blocks.push(`${rows.slice(i, i + 4).join('\n')}\n`);
+    blocks.push(`${rows.slice(i).map(line => `${line}\n`).join('')}</chat>\n`);
+    return blocks;
+}
 const addUsage = (sum, usage) => {
     if (!sum)
         return structuredClone(usage);
@@ -68,12 +103,17 @@ const addUsage = (sum, usage) => {
 export function createOptChatMemory(options) {
     const nodeBytes = options.nodeBytes ?? DEFAULTS.nodeBytes, viewBytes = options.viewBytes ?? DEFAULTS.viewBytes, jobs = options.jobs ?? DEFAULTS.jobs;
     const tries = options.tries ?? DEFAULTS.tries, cap = options.cap ?? DEFAULTS.cap, retryMs = options.retryMs ?? DEFAULTS.retryMs, settleMs = options.settleTimeoutMs ?? DEFAULTS.settleTimeoutMs;
+    const compactBytes = options.compactBytes ?? DEFAULTS.compactBytes;
     const agentName = options.agentName ?? 'OptChat';
     const extensionName = options.name ?? 'boring.memory.optchat';
     const taskKind = `${extensionName}.node`;
     const system = compactPrompt(agentName);
     const scale = scaleLine(nodeBytes);
+    const notes = [...(options.notes ?? [])];
+    const logOptions = (seed, edits) => ({ notes: seed, forgotten: edits.forgotten, ...(options.workOf ? { workOf: options.workOf } : {}) });
     const sessions = new Map();
+    const naps = new Map();
+    const retryDelay = (failure) => Math.min(60_000, retryMs * 2 ** Math.min(30, (failure.attempts ?? 1) - 1));
     const aborter = new AbortController();
     const hostContext = withAbortSignal(aborter.signal, options.context);
     const session = (id) => {
@@ -85,6 +125,8 @@ export function createOptChatMemory(options) {
     /** Read the stored summaries. Tasks write them (in this process or another, before or after a restart), so every read goes to the documents. */
     async function loadStored(s, reader, context) {
         const total = s.log.leaves.length;
+        s.stored.clear();
+        s.tree.reset();
         for (let level = 0; span(level) <= total; level++) {
             const nodes = Math.floor(total / span(level));
             for (let shard = 0; shard * SHARD < nodes; shard++) {
@@ -100,14 +142,38 @@ export function createOptChatMemory(options) {
             throw new Error(`No conversation ${String(id)}`);
         return found;
     }
+    /** The compactor has an independent fold. Copy before advancing: native tasks and requests can overlap. */
+    function compactView(s, to) {
+        const cached = session(s.id).compactFold;
+        const fold = cached.T > to ? emptyFold() : { T: cached.T, size: cached.size, parts: cached.parts.map(part => ({ ...part })) };
+        return advanceFold(fold, s.tree, to, compactBytes);
+    }
     /** Bring a session up to date with the committed context and its stored summaries. */
     async function refresh(id) {
         const s = session(id);
         const view = await (await conversationOf(id)).context(options.context);
-        s.sync(leavesOf(view.messages, cap).leaves);
+        const seed = await seedNotes(id);
+        const edits = await memoryEdits(id);
+        s.sync(leavesOf(view.messages, cap, logOptions(seed, edits)).leaves);
         await loadStored(s, options.harness(), options.context);
         return s;
     }
+    async function memoryEdits(id) {
+        return await options.harness().snapshot(OptChatEdits, id, options.context) ?? { revision: 0, forgotten: {} };
+    }
+    async function seedNotes(id) {
+        const stored = await options.harness().snapshot(OptChatNotes, id, options.context);
+        if (stored?.seeded)
+            return stored.notes;
+        return (await conversationOf(id)).commit(async (tx) => {
+            const doc = await tx.doc(OptChatNotes, id);
+            if (!doc.seeded) {
+                doc.notes = [...notes];
+                doc.seeded = true;
+            }
+            return [...doc.notes];
+        }, options.context);
+    }
     // ---- The summarizer (runs inside the native task) ----------------------------------------------------------------------
     /** One node by the reference protocol (§4.2, §4.3): context first, then the step; over-long lines are resubmitted cut at the limit; the shortest wins. */
     async function askModel(job, runtimeModels, signal) {
@@ -131,7 +197,7 @@ export function createOptChatMemory(options) {
         const step = `For scale, this line is exactly ${scale.bytes} bytes:\n${scale.text}\n\n` + (job.level === 0
             ? `Compress this message into one line, in at most ${nodeBytes} bytes:\n${job.source[0]}`
             : `Merge these two lines into one, in at most ${nodeBytes} bytes:\n${lines.join('\n')}`);
-        const conversation = [message([`<chat>\n${job.context}\n</chat>`, step])];
+        const conversation = [message([...chatBlocks(job.context), step])];
         const attempts = [];
         let usage, calls = 0, spender;
         try {
@@ -186,29 +252,48 @@ export function createOptChatMemory(options) {
                 // A private view of this conversation: a request may be folding and rendering the shared session right now.
                 const s = new Session(id, nodeBytes);
                 const load = async () => {
-                    s.sync(leavesOf((await runtime.context(id, context)).messages, cap).leaves);
+                    const seed = (await runtime.snapshot(OptChatNotes, id, context))?.notes ?? [];
+                    const edits = await runtime.snapshot(OptChatEdits, id, context) ?? { revision: 0, forgotten: {} };
+                    s.sync(leavesOf((await runtime.context(id, context)).messages, cap, logOptions(seed, edits)).leaves);
                     await loadStored(s, runtime, context);
+                    return edits.revision;
                 };
-                await load();
+                const revision = await load();
                 const ready = () => s.log.fp(level, index) === of && (level === 0 || (s.tree.text(level - 1, 2 * index) !== undefined && s.tree.text(level - 1, 2 * index + 1) !== undefined));
                 if (!ready() || s.tree.text(level, index) !== undefined)
                     return stale(); // the history changed, a child is missing, or the node needs no summary
-                const to = Math.min(upTo, s.log.leaves.length);
-                if (s.fold.T > to)
-                    s.fold = emptyFold();
-                advanceFold(s.fold, s.tree, to, viewBytes);
+                const to = Math.min(upTo, index * span(level));
+                const shared = session(id);
+                shared.sync(s.log.leaves);
+                const fold = compactView(s, to);
+                if (fold.size > compactBytes)
+                    return stale(); // admission will build preceding parents before trying this node again
+                if (fold.T >= shared.compactFold.T)
+                    shared.compactFold = fold;
                 const source = level === 0 ? [s.log.leaves[index].line] : [s.tree.text(level - 1, 2 * index), s.tree.text(level - 1, 2 * index + 1)];
-                const job = { conversationId: id, level, index, range: [index * span(level), (index + 1) * span(level) - 1], source, context: bareLines(s.fold, s.tree, level === 0 ? index : (index + 1) * span(level)), nodeBytes };
-                const summary = await askModel(job, runtime.models, runtime.signal);
+                const job = { conversationId: id, level, index, range: [index * span(level), (index + 1) * span(level) - 1], source, context: bareLines(fold, s.tree, to), nodeBytes };
+                let summary;
+                try {
+                    summary = await askModel(job, runtime.models, runtime.signal);
+                }
+                catch (error) {
+                    if (runtime.signal.aborted)
+                        throw error;
+                    summary = { error, calls: 0 }; // model resolution can fail before any request is sent
+                }
                 await load();
                 if (!ready())
                     return stale(summary); // the history changed while the model ran: its line is dropped, its spend is kept
                 let firstFailure = false;
                 await runtime.commit(async (tx) => {
                     const state = await bookkeeping(tx, id, summary);
+                    const edits = await tx.doc(OptChatEdits, id);
+                    if (edits.revision !== revision)
+                        return { status: 'terminal', outcome: { status: 'completed', result: { built: false } } };
                     if (summary.text === undefined) {
-                        firstFailure = state.failures[`${level}:${index}`]?.of !== of;
-                        state.failures[`${level}:${index}`] = { at: Date.now(), of, error: String(summary.error?.message ?? summary.error) };
+                        const previous = state.failures[`${level}:${index}`];
+                        firstFailure = previous?.of !== of;
+                        state.failures[`${level}:${index}`] = { at: Date.now(), of, attempts: firstFailure ? 1 : (previous?.attempts ?? 1) + 1, error: String(summary.error?.message ?? summary.error) };
                         return { status: 'terminal', outcome: { status: 'failed', error: { message: state.failures[`${level}:${index}`].error } } };
                     }
                     const doc = await tx.doc(OptChatNodes, id, shardKey(level, index), 0);
@@ -242,6 +327,8 @@ export function createOptChatMemory(options) {
                     continue;
                 if (level > 0 && (s.tree.text(level - 1, 2 * index) === undefined || s.tree.text(level - 1, 2 * index + 1) === undefined))
                     continue;
+                if (compactView(s, index * span(level)).size > compactBytes)
+                    break;
                 found.push({ level, index });
             }
         }
@@ -250,7 +337,7 @@ export function createOptChatMemory(options) {
     /**
      * Make sure every node that can be built has one live background task, up to `jobs` live tasks of the conversation. Host
      * admission only: Pi schedules and runs the tasks. One live task per node key (found by scanning native tasks in the same
-     * commit that creates them); a node whose last failure is inside `retryMs` is left for the next trigger.
+     * commit that creates them); a node inside its backoff window waits for the idle admission loop.
      */
     async function admit(s, skip) {
         const wanted = candidates(s).map(({ level, index }) => ({ level, index, of: s.log.fp(level, index) }));
@@ -276,7 +363,7 @@ export function createOptChatMemory(options) {
                 if (found.has(key) || skip.has(key))
                     continue;
                 const failure = failures[nodeKey(node.level, node.index)];
-                if (failure && failure.of === node.of && now - failure.at < retryMs) {
+                if (failure && failure.of === node.of && now - failure.at < retryDelay(failure)) {
                     waiting++;
                     continue;
                 }
@@ -301,22 +388,45 @@ export function createOptChatMemory(options) {
             cancel();
         }
     }
-    async function nap(id) {
-        const s = await refresh(id);
-        s.upTo = s.log.leaves.length;
-        const skip = new Set();
-        for (;;) {
-            const { live } = await admit(s, skip);
-            if (live.size === 0)
+    /** Abortable host wait between admission attempts. Pi still owns each node task and its recovery. */
+    async function pause(ms) {
+        if (aborter.signal.aborted)
+            return;
+        await new Promise(resolve => {
+            const done = () => { clearTimeout(timer); aborter.signal.removeEventListener('abort', done); resolve(); };
+            const timer = setTimeout(done, Math.max(1, ms));
+            aborter.signal.addEventListener('abort', done, { once: true });
+        });
+    }
+    async function drain(id) {
+        while (!aborter.signal.aborted) {
+            const s = await refresh(id);
+            s.upTo = s.log.leaves.length;
+            const { live } = await admit(s, new Set());
+            if (live.size > 0) {
+                if (!await settleAny([...live.values()], undefined, hostContext))
+                    return;
+                continue;
+            }
+            const failures = (await options.harness().snapshot(OptChatState, id, options.context))?.failures ?? {};
+            const delays = candidates(s).flatMap(({ level, index }) => {
+                const failure = failures[nodeKey(level, index)];
+                return failure && failure.of === s.log.fp(level, index) ? [failure.at + retryDelay(failure) - Date.now()] : [];
+            });
+            if (delays.length === 0)
                 return;
-            const done = await settleAny([...live.values()], undefined, hostContext);
-            if (!done)
-                return; // disposed
-            if (!done.built)
-                skip.add(done.key);
-            await loadStored(s, options.harness(), options.context);
+            await pause(Math.min(...delays));
         }
     }
+    function nap(id) {
+        const key = String(id);
+        const existing = naps.get(key);
+        if (existing)
+            return existing;
+        const running = drain(id).finally(() => { naps.delete(key); });
+        naps.set(key, running);
+        return running;
+    }
     /** Wait until every line of the view is a summary (§6). Never shows cut text: on timeout the rest shows the placeholder. */
     async function settle(s, covered, context) {
         const deadline = Date.now() + settleMs, skip = new Set();
@@ -339,6 +449,45 @@ export function createOptChatMemory(options) {
                 skip.add(done.key);
         }
     }
+    /** Context can copy an earlier fact into a later summary. Invalidate those too, atomically with the tombstone. */
+    async function forgetMessage(id, messageIndex) {
+        if (!Number.isInteger(messageIndex) || messageIndex < 0)
+            throw new Error('Invalid message index');
+        const conversation = await conversationOf(id);
+        const seed = await seedNotes(id);
+        for (;;) {
+            const edits = await memoryEdits(id);
+            const messages = (await conversation.context(options.context)).messages;
+            if (messageIndex >= messages.length || messages[messageIndex].role === 'system')
+                throw new Error('No forgettable message at that index');
+            const ordinal = messages.slice(0, messageIndex).filter(item => item.role !== 'system').length;
+            if (edits.forgotten[String(ordinal)] !== undefined)
+                return;
+            const { leaves, before } = leavesOf(messages, cap, logOptions(seed, edits));
+            const start = before[messageIndex], end = before[messageIndex + 1];
+            const changed = await conversation.commit(async (tx) => {
+                const doc = await tx.doc(OptChatEdits, id);
+                if (doc.revision !== edits.revision)
+                    return false;
+                doc.forgotten[String(ordinal)] = end - start;
+                doc.revision++;
+                const state = await tx.doc(OptChatState, id);
+                for (let level = 0; span(level) <= leaves.length; level++) {
+                    for (let index = Math.floor(start / span(level)); (index + 1) * span(level) <= leaves.length; index++) {
+                        const shard = await tx.doc(OptChatNodes, id, shardKey(level, index), 0);
+                        delete shard.nodes[String(index)];
+                        delete state.failures[nodeKey(level, index)];
+                    }
+                }
+                return true;
+            }, options.context);
+            if (!changed)
+                continue;
+            sessions.delete(String(id));
+            void nap(id).catch(() => { });
+            return;
+        }
+    }
     // ---- The extension -----------------------------------------------------------------------------------------------------
     const text = (value) => ({ output: [{ type: 'text', text: value }] });
     const zoomTool = defineTool({
@@ -363,30 +512,53 @@ export function createOptChatMemory(options) {
         hooks: [
             hook(GenerationTask, {
                 beforeRequest: async (request, api, context) => {
-                    const { leaves, before } = leavesOf(request.messages, cap);
-                    const last = request.messages.findLastIndex(item => item.role === 'user');
-                    const covered = last < 0 ? 0 : before[last];
-                    if (covered === 0)
-                        return undefined; // nothing came before this turn
-                    const s = session(api.conversationId);
-                    s.sync(leaves);
-                    s.upTo = covered;
-                    if (s.fold.T > covered)
-                        s.fold = emptyFold();
-                    const started = Date.now();
-                    const settled = await settle(s, covered, context);
-                    const view = renderView(s.fold, s.tree);
-                    const messages = request.messages.flatMap((item, index) => {
-                        if (index < last)
-                            return item.role === 'system' ? [item] : [];
-                        if (index > last)
-                            return [item];
-                        const user = item;
-                        const body = typeof user.content === 'string' ? [{ type: 'text', text: user.content }] : user.content;
-                        return [{ ...user, content: [{ type: 'text', text: view }, ...body] }];
-                    });
-                    s.lastRequest = { at: new Date().toISOString(), covered, requestMessages: messages.length, logMessages: request.messages.length, viewBytes: byteLength(view), waitedMs: Date.now() - started, settled };
-                    return { messages };
+                    for (;;) {
+                        const seed = await seedNotes(api.conversationId);
+                        const edits = await memoryEdits(api.conversationId);
+                        const { leaves, before } = leavesOf(request.messages, cap, logOptions(seed, edits));
+                        const last = request.messages.findLastIndex(item => item.role === 'user' || (item.role !== 'system' && options.workOf?.(item)));
+                        const covered = last < 0 ? 0 : before[last];
+                        if (covered === 0 && Object.keys(edits.forgotten).length === 0 && !request.messages.some(item => options.workOf?.(item)))
+                            return undefined;
+                        const cached = session(api.conversationId);
+                        cached.sync(leaves);
+                        const s = new Session(api.conversationId, nodeBytes);
+                        s.sync(leaves);
+                        s.upTo = covered;
+                        if (cached.fold.T <= covered)
+                            s.fold = { T: cached.fold.T, size: cached.fold.size, parts: cached.fold.parts.map(part => ({ ...part })) };
+                        const started = Date.now();
+                        const settled = await settle(s, covered, context);
+                        if ((await memoryEdits(api.conversationId)).revision !== edits.revision)
+                            continue;
+                        const view = renderView(s.fold, s.tree);
+                        const blocks = chatBlocks(view.split('\n').slice(1, -1).join('\n')).map(text => ({ type: 'text', text }));
+                        let ordinal = 0;
+                        const calls = new Set();
+                        const messages = request.messages.flatMap((item, index) => {
+                            const forgotten = item.role !== 'system' && edits.forgotten[String(ordinal++)] !== undefined;
+                            if (index < last)
+                                return item.role === 'system' ? [item] : [];
+                            const retained = forgotten ? redacted(item) : item;
+                            const work = item.role !== 'system' && options.workOf?.(item);
+                            // A report can start midway through a tool batch. Never send results without their calls.
+                            const normalize = (index === last && work && retained.role !== 'user') || (retained.role === 'toolResult' && !calls.has(retained.toolCallId));
+                            const current = normalize ? message([leavesOf([retained], Infinity, { workOf: () => !!work }).leaves[0].line]) : retained;
+                            if (current.role === 'assistant')
+                                for (const part of current.content)
+                                    if (part.type === 'toolCall')
+                                        calls.add(part.id);
+                            if (index > last || current.role === 'system')
+                                return [current];
+                            if (current.role === 'assistant')
+                                return [{ ...current, content: [...blocks, ...current.content] }];
+                            const body = typeof current.content === 'string' ? [{ type: 'text', text: current.content }] : current.content;
+                            return [{ ...current, content: [...blocks, ...body] }];
+                        });
+                        cached.lastRequest = { at: new Date().toISOString(), covered, requestMessages: messages.length, logMessages: request.messages.length, viewBytes: byteLength(view), waitedMs: Date.now() - started, settled };
+                        cached.fold = s.fold;
+                        return { messages };
+                    }
                 },
                 // A finished answer: once the run has committed it, create its summary tasks (background, so they never hold the run) so the next request finds its view ready.
                 onYield: (_answer, api) => {
@@ -414,7 +586,7 @@ export function createOptChatMemory(options) {
             const state = await options.harness().snapshot(OptChatState, id, options.context);
             const failures = Object.entries(state?.failures ?? {}).filter(([key, failure]) => { const [level, index] = key.split(':').map(Number); return failure.of === s.log.fp(level, index); }).map(([, failure]) => failure);
             const busy = (await options.harness().inspect(options.context)).tasks.filter(task => task.record.kind === taskKind && task.record.conversationId === id).length;
-            const retrying = failures.filter(failure => Date.now() - failure.at < retryMs).length;
+            const retrying = failures.filter(failure => Date.now() - failure.at < retryDelay(failure)).length;
             const latest = failures.reduce((best, failure) => !best || failure.at > best.at ? failure : best, undefined);
             return {
                 leaves: s.log.leaves.length, summaries,
@@ -426,7 +598,8 @@ export function createOptChatMemory(options) {
         },
         async zoom(id, nth, n) { return zoomText((await refresh(id)).tree, nth, n); },
         async date(id, nth) { return dateText((await refresh(id)).log, nth); },
+        forgetMessage,
         forget(id) { sessions.delete(String(id)); },
-        async dispose() { aborter.abort(); },
+        async dispose() { aborter.abort(); await Promise.allSettled(naps.values()); },
     };
 }

package/dist/self-evolving.js

@@ -1,5 +1,6 @@
 import { defineExtension, defineTool } from '@earendil-works/pi-durable';
 import { Type } from '@earendil-works/pi-ai';
+import { skillInFolder } 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
@@ -102,6 +103,27 @@ 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 hostSkills = [...options.skills];
@@ -113,7 +135,7 @@ export function createSelfEvolution(options) {
         name: 'reload',
         description: `Apply the changes you made to your own ${AGENT_FOLDER}/ folder in the workspace, then return what was added, changed and removed and every load error. `
             + `${INSTRUCTIONS}: standing instructions for yourself, shown after the host's instructions on every request. `
-            + `${SKILLS}/<name>.md: skills (front matter with name and description between --- lines, then the instructions), loaded with load_skill. `
+            + `${SKILLS}/<name>.md or ${SKILLS}/<name>/SKILL.md: skills (front matter with name and description between --- lines, then the instructions), loaded with load_skill; paths in a skill are relative to its folder and read with read. `
             + `${TOOLS}/<name>.json: your own tools, {"name": "snake_case", "description": "...", "parameters": {a JSON Schema with "type": "object"}, "run": "a command run in the workspace, for example sh ${TOOLS}/<name>.sh"}; `
             + 'the arguments arrive as one line of JSON on standard input and the command output is the result. Restore or delete the files and reload to undo a change.',
         parameters: Type.Object({}, { additionalProperties: false }),
@@ -147,10 +169,8 @@ export function createSelfEvolution(options) {
         else if (read.error.code !== 'not_found')
             errors.push({ path: INSTRUCTIONS, message: read.error.message });
         const skills = [];
-        const skillFiles = await filesIn(env, SKILLS, '.md', context);
-        if (typeof skillFiles === 'object' && !Array.isArray(skillFiles))
-            errors.push({ path: SKILLS, message: skillFiles.error });
-        for (const path of Array.isArray(skillFiles) ? skillFiles : []) {
+        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 });
@@ -168,7 +188,7 @@ export function createSelfEvolution(options) {
                 errors.push({ path, message: `a skill named ${skill.name} already exists` });
                 continue;
             }
-            skills.push(skill);
+            skills.push(skillInFolder(skill, path.slice(0, path.lastIndexOf('/'))));
         }
         const available = typeof env.exec === 'function';
         const tools = [];

package/dist/skills.d.ts

@@ -7,6 +7,7 @@ export interface Skill {
     readonly description: string;
     readonly body: string;
 }
+export declare function skillInFolder(skill: Skill, folder: string): Skill;
 /** Parse a `SKILL.md`-style document: `---` front matter with `name` and `description`, then the body. */
 export declare function parseSkill(markdown: string): Skill;
 export declare function validSkill(skill: Skill): Skill;

package/dist/skills.js

@@ -2,6 +2,11 @@ import { defineExtension, defineTool } from '@earendil-works/pi-durable';
 import { Type } from '@earendil-works/pi-ai';
 /** Names of skills and agents: a lowercase letter or digit, then lowercase letters, digits, `.`, `_` or `-` (at most 64). */
 export const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const skillFolders = new WeakMap();
+export function skillInFolder(skill, folder) {
+    skillFolders.set(skill, folder);
+    return skill;
+}
 /** Parse a `SKILL.md`-style document: `---` front matter with `name` and `description`, then the body. */
 export function parseSkill(markdown) {
     const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(markdown);
@@ -23,7 +28,9 @@ export function validSkill(skill) {
         throw new TypeError(`Invalid skill name: ${skill.name}`);
     if (!skill.description.trim() || !skill.body.trim())
         throw new TypeError(`Skill ${skill.name} needs a description and a body`);
-    return Object.freeze({ name: skill.name, description: skill.description.trim(), body: skill.body });
+    const valid = Object.freeze({ name: skill.name, description: skill.description.trim(), body: skill.body });
+    const folder = skillFolders.get(skill);
+    return folder === undefined ? valid : skillInFolder(valid, folder);
 }
 /** A prompt section listing the skills and a `load_skill` tool returning one body. Usable without `defineAgent`. */
 export function createSkillsExtension(name, skills) {
@@ -44,7 +51,9 @@ export function createSkillsExtension(name, skills) {
                 replay: 'safe',
                 execute: async (args) => {
                     const skill = known.get(args.name);
-                    return { output: [{ type: 'text', text: skill ? skill.body : `Unknown skill "${args.name}". Available: ${[...known.keys()].join(', ')}` }] };
+                    const folder = skill && skillFolders.get(skill);
+                    const location = folder === undefined ? '' : `\n\nThis skill's folder is \`${folder}\`; paths in it are relative to that folder.`;
+                    return { output: [{ type: 'text', text: skill ? skill.body + location : `Unknown skill "${args.name}". Available: ${[...known.keys()].join(', ')}` }] };
                 },
             })],
     });