@hachej/boring-agent 0.4.25 → 0.4.27

package/dist/skills.js

@@ -50,36 +50,48 @@ async function readSkillFile(fs, path, name, context) {
         return { path, name, message: reason(error) };
     }
 }
-/** Every `<directory>/<name>/SKILL.md`; a missing directory holds no skills. Other files are read only with `companionFiles`. */
-export function directorySkillSource(fs, directory) {
+/**
+ * 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 function directorySkillSource(fs, directory, options = {}) {
     const root = directory.replace(/\/+$/, '');
-    async function folders(context) {
+    if (options.versioned)
+        return versionedSource(fs, root, options.flat === true);
+    /** The skill files the directory holds, each with the name it is reported under. */
+    async function candidates(context) {
         const listed = await fs.listDir(root, context);
         if (!listed.ok)
-            return listed.error.code === 'not_found' ? { names: [] } : { names: [], error: { path: root, message: listed.error.message } };
-        return { names: listed.value.filter(entry => entry.kind === 'directory').map(entry => entry.name).sort() };
+            return listed.error.code === 'not_found' ? { files: [] } : { files: [], error: { path: root, message: listed.error.message } };
+        const folders = listed.value.filter(entry => entry.kind === 'directory').map(entry => ({ path: `${root}/${entry.name}/SKILL.md`, name: entry.name }));
+        const flat = options.flat ? listed.value.filter(entry => entry.kind === 'file' && entry.name.endsWith('.md'))
+            .map(entry => ({ path: `${root}/${entry.name}`, name: entry.name.slice(0, -'.md'.length) })) : [];
+        return { files: [...folders, ...flat].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) };
     }
-    const info = (name, context) => fs.fileInfo(`${root}/${name}/SKILL.md`, context);
     return {
         fs,
         version: async (context) => {
-            const { names, error } = await folders(context);
+            const { files, error } = await candidates(context);
             if (error)
                 return `error:${error.message}`;
-            const stamps = await Promise.all(names.map(async (name) => {
-                const found = await info(name, context);
-                return `${name}=${found.ok ? stamp(found.value) : found.error.code}`;
+            const stamps = await Promise.all(files.map(async (file) => {
+                const found = await fs.fileInfo(file.path, context);
+                return `${file.path}=${found.ok ? stamp(found.value) : found.error.code}`;
             }));
             return stamps.join('|');
         },
         list: async (context) => {
-            const { names, error } = await folders(context);
+            const { files, error } = await candidates(context);
             const skills = [], errors = error ? [error] : [];
-            for (const name of names) {
-                const found = await info(name, context);
+            for (const file of files) {
+                const found = await fs.fileInfo(file.path, context);
                 if (!found.ok && found.error.code === 'not_found')
                     continue;
-                const read = await readSkillFile(fs, `${root}/${name}/SKILL.md`, name, context);
+                const read = await readSkillFile(fs, file.path, file.name, context);
                 if ('body' in read)
                     skills.push(read);
                 else
@@ -89,6 +101,39 @@ export function directorySkillSource(fs, directory) {
         },
     };
 }
+/** A version is one folder name: no separator, no control character, not `.` or `..`. */
+const VERSION = /^(?!\.\.?$)[^/\\\u0000-\u001f]{1,128}$/;
+function versionedSource(fs, root, flat) {
+    const pointer = `${root}/current`;
+    let good;
+    const folder = (version) => directorySkillSource(fs, `${root}/${version}`, { flat });
+    const versions = {
+        current: async (context) => {
+            const kept = (message) => ({ ...(good === undefined ? {} : { version: good }), error: { path: pointer, message } });
+            const text = await fs.readTextFile(pointer, context);
+            if (!text.ok)
+                return kept(`Skill version pointer could not be read: ${text.error.message}`);
+            const version = text.value.trim();
+            if (!VERSION.test(version))
+                return kept(`Skill version pointer names no version folder: ${JSON.stringify(version.slice(0, 80))}`);
+            const info = await fs.fileInfo(`${root}/${version}`, context);
+            if (!info.ok || info.value.kind !== 'directory')
+                return kept(`Skill version ${version} has no folder ${root}/${version}${info.ok ? '' : `: ${info.error.message}`}`);
+            good = version;
+            return { version };
+        },
+        list: (version, context) => folder(version).list(context),
+    };
+    return {
+        fs, versions,
+        version: async (context) => { const read = await versions.current(context); return `${read.version ?? ''}|${read.error?.message ?? ''}`; },
+        list: async (context) => {
+            const read = await versions.current(context);
+            const listing = read.version === undefined ? { skills: [], errors: [] } : await versions.list(read.version, context);
+            return read.error ? { skills: listing.skills, errors: [...listing.errors, read.error] } : listing;
+        },
+    };
+}
 /** One skill file (`SKILL.md` front matter); a missing file holds no skill. Its folder is the file's directory. */
 export function fileSkillSource(fs, path) {
     const name = path.slice(path.lastIndexOf('/') + 1).replace(/\.md$/i, '');
@@ -144,7 +189,7 @@ function only(name, next, current) {
  * The current copy of a source: read again once it is older than `maxAgeMs` and `version()` changed, or when `refresh` asks.
  * Reads run one at a time; concurrent callers of `current` share one.
  */
-function liveSkills(source, options) {
+function copyOf(source, options) {
     const maxAgeMs = options.maxAgeMs ?? 5000, fs = options.companionFiles ? source.fs : undefined;
     let state = { known: new Map(), errors: [] };
     let version, checkedAt = -Infinity, pending, missing;
@@ -201,6 +246,85 @@ function liveSkills(source, options) {
         }),
     };
 }
+/**
+ * A versioned source: each conversation is pinned to the version it first read and keeps it until `reload` or `refresh` moves
+ * it. The pointer is read again once older than `maxAgeMs`; each version is read once (a reload reads its version again).
+ * Pins live in this process: after a restart a conversation starts on the version current then.
+ */
+function versionsOf(versions, sourceFs, options) {
+    const maxAgeMs = options.maxAgeMs ?? 5000, fs = options.companionFiles ? sourceFs : undefined;
+    const empty = { known: new Map(), errors: [] };
+    const read = new Map(), pins = new Map();
+    let latest, checkedAt = -Infinity, reported, pending;
+    function load(version, context) {
+        let found = read.get(version);
+        if (!found) {
+            const next = (async () => { const listing = loaded(await versions.list(version, context)); return fs ? withCompanions(fs, listing, context) : listing; })();
+            read.set(version, next);
+            next.catch(() => { if (read.get(version) === next)
+                read.delete(version); });
+            found = next;
+        }
+        return found;
+    }
+    /** Read the pointer now; `again` reads its version's folder again too. Reports diagnostics when what was read changed. */
+    async function check(context, again = false) {
+        const pointed = await versions.current(context);
+        if (again && pointed.version !== undefined)
+            read.delete(pointed.version);
+        latest = pointed.version;
+        checkedAt = Date.now();
+        const state = latest === undefined ? empty : await load(latest, context);
+        const errors = pointed.error ? [...state.errors, pointed.error] : state.errors;
+        const token = JSON.stringify([latest, errors]);
+        if (token !== reported) {
+            reported = token;
+            options.onDiagnostics?.(errors);
+        }
+        return { ...pointed, state };
+    }
+    async function newest(context) {
+        if (Date.now() - checkedAt >= maxAgeMs)
+            await (pending ??= check(context).finally(() => { pending = undefined; }));
+        return latest;
+    }
+    async function move(context, conversationId) {
+        const pointed = await check(context, true);
+        if (pointed.version !== undefined && pointed.error === undefined) {
+            if (conversationId !== undefined)
+                pins.set(conversationId, pointed.version);
+            else
+                for (const id of pins.keys())
+                    pins.set(id, pointed.version);
+        }
+        return pointed;
+    }
+    return {
+        current: async (context, conversationId) => {
+            let version = conversationId === undefined ? undefined : pins.get(conversationId);
+            if (version === undefined) {
+                version = await newest(context);
+                if (version !== undefined && conversationId !== undefined)
+                    pins.set(conversationId, version);
+            }
+            return version === undefined ? empty : load(version, context);
+        },
+        reload: async (context, conversationId) => {
+            const pointed = await move(context, conversationId);
+            if (pointed.error) {
+                const kept = conversationId === undefined ? pointed.version : pins.get(conversationId) ?? pointed.version;
+                return `${kept === undefined ? 'No skill version is in use' : `Skills stay on version ${kept}`}: ${pointed.error.message}`;
+            }
+            const names = [...pointed.state.known.keys()];
+            return `Skills reloaded: version ${pointed.version} (${names.length ? names.join(', ') : 'no skills'}).`;
+        },
+        refresh: async (context, name, conversationId) => {
+            if (name !== undefined)
+                throw new TypeError('A versioned skill source moves whole versions: refresh takes no skill name');
+            return (await move(context, conversationId)).error === undefined;
+        },
+    };
+}
 const INTRO_TEXT = 'Before starting a task that matches a skill, call load_skill with its name and follow the returned instructions. A user message that starts with /<skill-name> naming one of these skills is an explicit request: call load_skill for that skill first and follow it for the rest of the message.';
 const COMPANION_LIMIT = 200;
 /** Each skill's companion files, checked when its listing was read. */
@@ -279,7 +403,7 @@ async function withCompanions(fs, listing, context) {
     return { known: listing.known, errors };
 }
 /** The listing section and `load_skill` over `live`, filtered per conversation by `visible`. */
-function skillsExtension(name, live, options, fs) {
+function skillsExtension(live, options, fs) {
     const { visible } = options, intro = options.intro ?? INTRO_TEXT;
     // `at` is read only with a filter, so direct callers of render/execute without Pi's input or api keep working.
     async function seen(known, at) {
@@ -293,10 +417,11 @@ function skillsExtension(name, live, options, fs) {
         ? Type.Object({ name: Type.String(), path: Type.Optional(Type.String({ description: 'A companion file of the skill, relative to its folder.' })) }, { additionalProperties: false })
         : Type.Object({ name: Type.String() }, { additionalProperties: false });
     return defineExtension({
-        name,
+        name: options.name,
         sections: [{ key: 'skills', render: async (input, context) => {
-                    const skills = await seen((await live.current(context)).known, () => input.conversationId);
-                    return skills.length ? `${intro}\n${skills.map(skill => `- ${skill.name}: ${skill.description}`).join('\n')}` : undefined;
+                    const skills = await seen((await live.current(context, input?.conversationId)).known, () => input.conversationId);
+                    const lines = [...skills.length ? [intro] : [], ...live.reload ? [RELOAD_TEXT] : [], ...skills.map(skill => `- ${skill.name}: ${skill.description}`)];
+                    return lines.length ? lines.join('\n') : undefined;
                 } }],
         tools: [defineTool({
                 name: 'load_skill',
@@ -305,7 +430,7 @@ function skillsExtension(name, live, options, fs) {
                 replay: 'safe',
                 execute: async (args, api, context) => {
                     const text = (value) => ({ output: [{ type: 'text', text: value }] });
-                    let { known, errors } = await live.current(context);
+                    let { known, errors } = await live.current(context, api?.conversationId);
                     let shown = await seen(known, () => api.conversationId);
                     if (!shown.some(candidate => candidate.name === args.name) && live.miss) {
                         // Not in this conversation's listing: the skill may have been added since, so check the source once now.
@@ -338,20 +463,25 @@ function skillsExtension(name, live, options, fs) {
                     const listed = companions.length ? `\n\nCompanion files of this skill (read one with load_skill and its path):\n${companions.map(path => `- ${path}`).join('\n')}` : '';
                     return text(skill.body + location + listed);
                 },
-            })],
+            }), ...live.reload ? [reloadTool(live.reload)] : []],
+    });
+}
+const RELOAD_TEXT = 'A user message that is /reload-skill asks to move this conversation to the latest published skills: call reload_skill and tell the person its answer.';
+/** The `reload_skill` tool of a versioned source: the person's `/reload-skill`, for the calling conversation only. */
+function reloadTool(reload) {
+    return defineTool({
+        name: 'reload_skill',
+        description: 'Move this conversation to the latest published version of the skills. Call it only when the person sends /reload-skill.',
+        parameters: Type.Object({}, { additionalProperties: false }),
+        replay: 'safe',
+        execute: async (_args, api, context) => ({ output: [{ type: 'text', text: await reload(context, api?.conversationId) }] }),
     });
 }
 /**
- * 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 function createSkillsExtension(name, skills, options = {}) {
-    if (!isSkillArray(skills))
-        return createSkillsController(name, skills, options).extension;
-    if (options.companionFiles)
-        throw new TypeError('Skills extension: companionFiles need a SkillSource with fs, not an array');
+export function staticSkills(skills, options) {
     const known = new Map();
     for (const skill of skills.map(validSkill)) {
         if (known.has(skill.name))
@@ -359,13 +489,21 @@ export function createSkillsExtension(name, skills, options = {}) {
         known.set(skill.name, skill);
     }
     const fixed = { known, errors: [] };
-    return skillsExtension(name, { current: async () => fixed }, options, undefined);
+    return { extension: skillsExtension({ current: async () => fixed }, options, undefined) };
 }
-/** `createSkillsExtension` on a source, plus `refresh(context, name?)` to re-read it now instead of after `maxAgeMs`. */
-export function createSkillsController(name, source, options = {}) {
+/**
+ * `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 function liveSkills(source, options) {
     if (options.companionFiles && !source.fs)
         throw new TypeError('Skills extension: companionFiles need a SkillSource with fs');
-    const live = liveSkills(source, options);
-    return { extension: skillsExtension(name, live, options, options.companionFiles ? source.fs : undefined), refresh: live.refresh };
+    if (source.versions && options.onPublish)
+        throw new TypeError('Skills extension: onPublish does not apply to a versioned source');
+    const live = source.versions ? versionsOf(source.versions, source.fs, options) : copyOf(source, options);
+    return { extension: skillsExtension(live, options, options.companionFiles ? source.fs : undefined), refresh: live.refresh };
 }
-const isSkillArray = (skills) => Array.isArray(skills);
+export const isSkillArray = (skills) => Array.isArray(skills);
+/** The file a built-in source read this skill from, if any: self-evolution reports a skill it refuses at that path. */
+export const skillFile = (skill) => skillFiles.get(skill);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-agent",
-  "version": "0.4.25",
+  "version": "0.4.27",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -148,6 +148,26 @@
     "./room": {
       "types": "./dist/room.d.ts",
       "import": "./dist/room.js"
+    },
+    "./run-result": {
+      "types": "./dist/run-result.d.ts",
+      "import": "./dist/run-result.js"
+    },
+    "./runs": {
+      "types": "./dist/runs.d.ts",
+      "import": "./dist/runs.js"
+    },
+    "./run-ledger": {
+      "types": "./dist/run-ledger.d.ts",
+      "import": "./dist/run-ledger.js"
+    },
+    "./run-outbox": {
+      "types": "./dist/run-outbox.d.ts",
+      "import": "./dist/run-outbox.js"
+    },
+    "./actions": {
+      "types": "./dist/actions.d.ts",
+      "import": "./dist/actions.js"
     }
   },
   "dependencies": {
@@ -160,8 +180,9 @@
     "@earendil-works/pi-durable": "~1.2.0",
     "@earendil-works/pi-ai": "~1.2.0",
     "@earendil-works/chord": "~1.2.0",
-    "@hachej/boring-files": "^0.4.25",
-    "@hachej/boring-ui-kit": "^0.4.25",
+    "@hachej/boring-files": "^0.4.27",
+    "@hachej/boring-ui-kit": "^0.4.27",
+    "typebox": "1.3.27",
     "xlsx": "^0.20.3"
   },
   "peerDependenciesMeta": {