@hachej/boring-agent 0.4.22 → 0.4.23

package/README.md

@@ -357,13 +357,35 @@ With self-evolution, workspace skills may be flat `.agent/skills/<name>.md` file
 
 `createSkillsExtension(name, skills, options?)` also takes a `SkillSource` instead of an array, so skills added, edited or removed after start reach the agent without rebuilding the extension. A source is `{ list(context), version(context) }`: `list` returns `{ skills, errors }`, `version` a cheap token that changes when the skills do. Two are built in, and both read through the workspace's Pi `FileSystem` (an `ExecutionEnv` is one; pass the workspace provider's instance, never `node:fs`):
 
-- `directorySkillSource(fs, 'skills')`: every `skills/<name>/SKILL.md`, its folder passed to `load_skill` as for self-evolution. A missing directory holds no skills; folders without `SKILL.md` and companion files are not read. Its version is the folder names with each `SKILL.md`'s `mtimeMs` and size (one `listDir` and one `fileInfo` per folder).
+- `directorySkillSource(fs, 'skills')`: every `skills/<name>/SKILL.md`, its folder passed to `load_skill` as for self-evolution. A missing directory holds no skills; folders without `SKILL.md` are skipped, and companion files are read only with `companionFiles` (below). Its version is the folder names with each `SKILL.md`'s `mtimeMs` and size (one `listDir` and one `fileInfo` per folder).
 - `fileSkillSource(fs, 'notes/triage.md')`: one skill file, its folder the file's directory; a missing file holds no skill. Its version is the file's `mtimeMs` and size.
 
-The source is read on first use. After that the listing section and `load_skill` use the cached copy until it is older than `options.maxAgeMs` (default 5000), then ask `version()` and read `list()` again only when it changed. There is no watcher or timer: the check happens on use, and concurrent uses share one read. What a source returns is checked with `validSkill` and the duplicate-name rule (the first skill of a name wins). A skill that fails, or a file that cannot be read or parsed, is left out instead of taking the extension down: `options.onDiagnostics(errors)` receives every `SkillError` (`{ path, name?, message }`) after each read (an empty array once all are fine), and `load_skill` asked for the left-out name answers `Skill "<name>" could not be loaded (<path>): <reason>`. A source whose `list`/`version` throws is a host bug: the section keeps the text already shown (Pi's `renderSections`) and `load_skill` fails. A fixed array works as before: validated once, an invalid or duplicate skill throws. With no skills, the section is omitted.
+The source is read on first use. After that the listing section and `load_skill` use the cached copy until it is older than `options.maxAgeMs` (default 5000), then ask `version()` and read `list()` again only when it changed. There is no watcher or timer: the check happens on use, and concurrent uses share one read. `load_skill` asked for a name the conversation's listing does not hold makes the same check at once, whatever `maxAgeMs` (see *refresh on miss* below). What a source returns is checked with `validSkill` and the duplicate-name rule (the first skill of a name wins). A skill that fails, or a file that cannot be read or parsed, is left out instead of taking the extension down: `options.onDiagnostics(errors)` receives every `SkillError` (`{ path, name?, message }`) after each read (an empty array once all are fine), and `load_skill` asked for the left-out name answers `Skill "<name>" could not be loaded (<path>): <reason>`. A source whose `list`/`version` throws is a host bug: the section keeps the text already shown (Pi's `renderSections`) and `load_skill` fails. A fixed array works as before: validated once, an invalid or duplicate skill throws. With no skills, the section is omitted.
 
 Pi renders every extension section before each model request (`PromptSection.render`), so a refreshed listing reaches the next request; Pi's `planSystemEntries` writes nothing when the text is unchanged and a minimal `pi.system` section patch when it changed. Prompt cache: on a model that accepts system messages mid-conversation the patch is appended and the cached prefix stays valid; on one that does not, Pi collapses the system messages into one leading prompt, so every listing change rewrites the start of the prompt and misses the provider's prompt cache once. Keep `maxAgeMs` coarse and edits to skill descriptions deliberate. Pi itself has no skills loader in the packages this one depends on (`pi-durable` and `pi-ai`), so this is a host concern built on its `FileSystem` and section seams.
 
+**Control (all optional; with none set, the extension behaves as above).**
+
+- `visible(conversationId, skills)`: which skills a conversation sees. It is called once per render and once per `load_skill` call (may be async) with the whole current list of valid skills, and returns the subset that conversation sees (matched by name). The id is Pi's own: the section gets it from `PromptInput.conversationId`, the tool from `ToolExecutionApi.conversationId`, so no host bookkeeping is needed. A hidden skill is left out of the listing, and `load_skill` answers for it exactly as for an unknown name (`Unknown skill "<name>". Available: <visible names>`). With a filter, a skill that could not be read also answers as unknown (it is never in the list); its reason still reaches `onDiagnostics`. Works for an array too.
+- `companionFiles: true`: `load_skill`'s answer ends with the files beside the skill's `SKILL.md` (the Agent Skills layout: `references/`, `scripts/`, `assets/`; any depth, name order, at most 200), and `load_skill({ name, path })` returns one of them as text. The files are checked when the listing is read, not when the model asks: each one must be a regular file inside the skill's folder that reads as UTF-8 text. A symbolic link, an unreadable or binary file (a NUL byte or invalid UTF-8) and files past the 200th are left out and reported to `onDiagnostics` (`{ path, name: <skill>, message: 'Companion file left out: …' }`). Only a listed path is read, so a path cannot leave the folder (`../`, absolute paths and links are refused with `Skill "<name>" has no companion file "<path>"`). The list is kept with the listing: a companion added or removed later shows up on the next read of the source (a `SKILL.md` change or `refresh()`); a listed file's content is read on demand through the source's `fs` (the same workspace `FileSystem`; both built-in sources set `SkillSource.fs`), never cached. A skill file not named `SKILL.md` (a `fileSkillSource` on `notes/triage.md`) has none. An array, or a source without `fs`, throws.
+- `intro`: the listing section's text before the `- name: description` lines, replacing the default (“Before starting a task that matches a skill, call load_skill …”, with the `/<skill-name>` rule). The skill lines still follow it.
+- `onPublish(next, previous)`: called with both listings' skills before a newly read listing of a source replaces the current one (may be async). Return a reason, or throw, to refuse it: the current listing stays and `onDiagnostics` gets `[{ path: '', message: 'Listing refused by onPublish: <reason>' }]`. A refused listing is not offered again until the source's version changes or `refresh()` runs. The first read is offered too (`previous` empty).
+- `createSkillsController(name, source, options?)` returns `{ extension, refresh }`, so `createSkillsExtension` keeps its return type (it is `createSkillsController(...).extension` for a source). `await refresh(context)` reads the source now, whatever `maxAgeMs`, and publishes it through `onPublish`; `refresh(context, name)` takes only that skill from the new read (added, replaced or removed) and keeps the others as they were. It resolves `true` when published, `false` when refused. Reads run one at a time, so a refresh never interleaves with a `maxAgeMs` check. Call it from the code that changed the skills (an editor save, a self-evolution keep); there is still no watcher.
+
+**Refresh on miss.** On a source, `load_skill` for a name not in the conversation's listing checks the source once before answering, whatever `maxAgeMs`: `version()` now, and `list()` plus `onPublish` only when the version changed, serialized with the other reads. So a skill written a moment ago loads on the first try, and the listing shows it from the next request on. A model guessing names costs one `version()` per miss (a `fileInfo` per skill folder for the built-in sources), never a re-read of an unchanged source, and concurrent misses share one check in flight, so there is no time floor. A miss of a refused listing's skill stays a miss until the version changes or `refresh()` runs, as above.
+
+```ts
+const skills = createSkillsController('workspace.skills', directorySkillSource(env, 'skills'), {
+  companionFiles: true,
+  visible: (conversationId, skills) => billingConversations.has(conversationId) ? skills : skills.filter(skill => !skill.name.startsWith('billing-')),
+  onDiagnostics: errors => errors.forEach(error => log.warn(`skill ${error.path}: ${error.message}`)),
+  intro: 'Clinic procedures. Load the matching one with load_skill before you answer:',
+  onPublish: next => next.some(skill => !skill.body.includes('Reviewed')) ? 'unreviewed skill' : undefined,
+});
+const agent = defineAgent({ id: 'clerk', model, extensions: [skills.extension] });
+await skills.refresh(context, 'letters'); // after the host saved skills/letters/SKILL.md
+```
+
 ## Sub-agents and schedules
 
 These follow [Pi Durable on Cloudflare](https://earendil.com/posts/pi-durable-on-cloudflare/) and stay host-agnostic: a Node process and a Durable Object mount the same tools.

package/dist/agents.d.ts

@@ -5,8 +5,8 @@ import type { SelfEvolutionReport } from './self-evolving.js';
 import type { DelegateOptions } from './delegate.js';
 import type { Skill } from './skills.js';
 export type { SelfEvolutionError, SelfEvolutionReport } from './self-evolving.js';
-export { createSkillsExtension, directorySkillSource, fileSkillSource, parseSkill } from './skills.js';
-export type { Skill, SkillError, SkillFileSystem, SkillListing, SkillSource, SkillsExtensionOptions } from './skills.js';
+export { createSkillsController, createSkillsExtension, directorySkillSource, fileSkillSource, parseSkill } from './skills.js';
+export type { Skill, SkillError, SkillFileSystem, SkillListing, SkillSource, SkillsController, SkillsExtensionOptions } from './skills.js';
 export { jsonSchemaTool } from './json-schema-tool.js';
 export type { JsonObjectSchema, JsonSchemaToolOptions } from './json-schema-tool.js';
 export { createDelegateTool, DELEGATE_DETAILS_KIND, DELEGATE_TOOL } from './delegate.js';

package/dist/agents.js

@@ -3,7 +3,7 @@ import { AgentDoc, defineExtension } from '@earendil-works/pi-durable';
 import { createSelfEvolution } from './self-evolving.js';
 import { NAME, createSkillsExtension, parseSkill, validSkill } from './skills.js';
 import { createDelegateTool } from './delegate.js';
-export { createSkillsExtension, directorySkillSource, fileSkillSource, parseSkill } from './skills.js';
+export { createSkillsController, createSkillsExtension, directorySkillSource, fileSkillSource, parseSkill } from './skills.js';
 export { jsonSchemaTool } from './json-schema-tool.js';
 export { createDelegateTool, DELEGATE_DETAILS_KIND, DELEGATE_TOOL } from './delegate.js';
 /** Turn an agent described as data into native extensions and a native agent configuration. */

package/dist/skills.d.ts

@@ -1,4 +1,4 @@
-import type { Extension } from '@earendil-works/pi-durable';
+import type { ConversationId, Extension } from '@earendil-works/pi-durable';
 import type { FileSystem } from '@earendil-works/pi-durable/env';
 import type { Context } from '@earendil-works/chord';
 /** Names of skills and agents: a lowercase letter or digit, then lowercase letters, digits, `.`, `_` or `-` (at most 64). */
@@ -31,23 +31,60 @@ export interface SkillListing {
 export interface SkillSource {
     readonly list: (context: Context) => Promise<SkillListing>;
     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;
 }
 /** 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 companions and are never read. */
+/** 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;
 /** 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). */
+    /** Called after each read of a source with every skill it left out (an empty array when none), or with the `onPublish` refusal. */
     readonly onDiagnostics?: (errors: readonly SkillError[]) => void;
+    /**
+     * 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).
+     * A hidden skill is left out of the listing and `load_skill` answers for it exactly as for an unknown name. With a filter,
+     * 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[]>;
+    /**
+     * 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`. Read through the
+     * source's `fs`; an array or 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 `Listing refused by onPublish: <reason>`.
+     * A refused listing is offered again only once the source's version changes or `refresh()` is called.
+     */
+    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 {
+    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. Resolves `true` when published,
+     * `false` when `onPublish` refused it.
+     */
+    readonly refresh: (context: Context, name?: string) => 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.
  */
 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;
 //# sourceMappingURL=skills.d.ts.map

package/dist/skills.js

@@ -50,7 +50,7 @@ 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 companions and are never read. */
+/** Every `<directory>/<name>/SKILL.md`; a missing directory holds no skills. Other files are read only with `companionFiles`. */
 export function directorySkillSource(fs, directory) {
     const root = directory.replace(/\/+$/, '');
     async function folders(context) {
@@ -61,6 +61,7 @@ export function directorySkillSource(fs, directory) {
     }
     const info = (name, context) => fs.fileInfo(`${root}/${name}/SKILL.md`, context);
     return {
+        fs,
         version: async (context) => {
             const { names, error } = await folders(context);
             if (error)
@@ -92,6 +93,7 @@ export function directorySkillSource(fs, directory) {
 export function fileSkillSource(fs, path) {
     const name = path.slice(path.lastIndexOf('/') + 1).replace(/\.md$/i, '');
     return {
+        fs,
         version: async (context) => {
             const found = await fs.fileInfo(path, context);
             return found.ok ? stamp(found.value) : found.error.code;
@@ -122,75 +124,219 @@ function loaded(listing) {
             errors.push({ path, name: skill.name, message: `Duplicate skill: ${skill.name}` });
             continue;
         }
+        const file = skillFiles.get(raw);
+        if (file !== undefined)
+            skillFiles.set(skill, file);
         known.set(skill.name, skill);
     }
     return { known, errors };
 }
-/** The current copy of a source: read again once it is older than `maxAgeMs` and `version()` changed. Concurrent callers share one read. */
+/** `next` with only `name` taken from it; the rest of `current` is kept. */
+function only(name, next, current) {
+    const known = new Map(current.known), skill = next.known.get(name);
+    if (skill)
+        known.set(name, skill);
+    else
+        known.delete(name);
+    return { known, errors: [...current.errors.filter(error => error.name !== name), ...next.errors.filter(error => error.name === name)] };
+}
+/**
+ * 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) {
-    const maxAgeMs = options.maxAgeMs ?? 5000;
+    const maxAgeMs = options.maxAgeMs ?? 5000, fs = options.companionFiles ? source.fs : undefined;
     let state = { known: new Map(), errors: [] };
-    let version, checkedAt = -Infinity, pending;
-    async function refresh(context) {
+    let version, checkedAt = -Infinity, pending, missing;
+    let queue = Promise.resolve();
+    const read = async (context) => { const next = loaded(await source.list(context)); return fs ? withCompanions(fs, next, context) : next; };
+    const serial = (run) => { const next = queue.then(run, run); queue = next.catch(() => { }); return next; };
+    async function refusal(next) {
+        if (!options.onPublish)
+            return undefined;
+        try {
+            return (await options.onPublish([...next.known.values()], [...state.known.values()])) ?? undefined;
+        }
+        catch (error) {
+            return reason(error);
+        }
+    }
+    async function publish(next) {
+        const refused = await refusal(next);
+        if (refused !== undefined) {
+            options.onDiagnostics?.([{ path: '', message: `Listing refused by onPublish: ${refused}` }]);
+            return false;
+        }
+        state = next;
+        options.onDiagnostics?.(state.errors);
+        return true;
+    }
+    async function check(context) {
         const next = await source.version(context);
         if (next !== version) {
-            state = loaded(await source.list(context));
+            const listing = await read(context);
             version = next;
-            options.onDiagnostics?.(state.errors);
+            await publish(listing);
         }
         checkedAt = Date.now();
         return state;
     }
-    return context => {
-        if (Date.now() - checkedAt < maxAgeMs)
-            return Promise.resolve(state);
-        return pending ??= refresh(context).finally(() => { pending = undefined; });
+    return {
+        current: (context) => {
+            if (Date.now() - checkedAt < maxAgeMs)
+                return Promise.resolve(state);
+            return pending ??= serial(() => check(context)).finally(() => { pending = undefined; });
+        },
+        // A load_skill miss: the maxAgeMs check now. One at a time, shared by concurrent misses; `list()` and `onPublish` run
+        // only when `version()` changed, so a model asking for names that do not exist costs one `version()` per miss.
+        miss: (context) => missing ??= serial(() => check(context)).finally(() => { missing = undefined; }),
+        refresh: (context, name) => serial(async () => {
+            const next = await source.version(context), listing = await read(context);
+            // One skill taken: the copy no longer matches any version, so the next check reads the whole source again.
+            version = name === undefined ? next : undefined;
+            checkedAt = Date.now();
+            return publish(name === undefined ? listing : only(name, listing, state));
+        }),
     };
 }
-const INTRO = '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 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. */
+const companionLists = new WeakMap();
 /**
- * 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.
+ * Walk the files beside each skill's `SKILL.md` (relative to its folder, depth first in name order, at most
+ * `COMPANION_LIMIT`) and keep those that read as UTF-8 text. A symbolic link, an unreadable or non-text file, and files past
+ * the limit are left out and reported with the skill's name. A skill file not named `SKILL.md` has none.
  */
-export function createSkillsExtension(name, skills, options = {}) {
-    let current;
-    if (isSkillArray(skills)) {
-        const known = new Map();
-        for (const skill of skills.map(validSkill)) {
-            if (known.has(skill.name))
-                throw new TypeError(`Duplicate skill: ${skill.name}`);
-            known.set(skill.name, skill);
-        }
-        const fixed = { known, errors: [] };
-        current = async () => fixed;
+async function withCompanions(fs, listing, context) {
+    const errors = [...listing.errors];
+    for (const skill of listing.known.values()) {
+        const folder = skillFolders.get(skill), file = skillFiles.get(skill), files = [];
+        companionLists.set(skill, files);
+        if (folder === undefined || (file !== undefined && !/(^|\/)SKILL\.md$/.test(file)))
+            continue;
+        const at = (relative) => relative === '' ? folder : folder === '.' ? relative : `${folder}/${relative}`;
+        const leftOut = (relative, message) => { errors.push({ path: at(relative), name: skill.name, message }); };
+        let over = false;
+        const walk = async (relative) => {
+            const listed = await fs.listDir(at(relative), context);
+            if (!listed.ok) {
+                leftOut(relative, `Companion files could not be listed: ${listed.error.message}`);
+                return;
+            }
+            for (const entry of [...listed.value].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+                if (over)
+                    return;
+                const path = relative === '' ? entry.name : `${relative}/${entry.name}`;
+                if (entry.kind === 'directory') {
+                    await walk(path);
+                    continue;
+                }
+                if (path === 'SKILL.md')
+                    continue;
+                if (entry.kind === 'symlink') {
+                    leftOut(path, 'Companion file left out: a symbolic link');
+                    continue;
+                }
+                if (files.length >= COMPANION_LIMIT) {
+                    over = true;
+                    leftOut('', `Companion files left out: more than ${COMPANION_LIMIT}`);
+                    return;
+                }
+                const text = await fs.readTextFile(at(path), context);
+                if (!text.ok)
+                    leftOut(path, `Companion file left out: ${text.error.message}`);
+                else if (/[\u0000\uFFFD]/.test(text.value))
+                    leftOut(path, 'Companion file left out: not UTF-8 text');
+                else
+                    files.push(path);
+            }
+        };
+        await walk('');
     }
-    else
-        current = liveSkills(skills, options);
+    return { known: listing.known, errors };
+}
+/** The listing section and `load_skill` over `live`, filtered per conversation by `visible`. */
+function skillsExtension(name, 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) {
+        const all = [...known.values()];
+        if (!visible)
+            return all;
+        const names = new Set((await visible(at(), all)).map(skill => skill.name));
+        return all.filter(skill => names.has(skill.name));
+    }
+    const parameters = 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,
-        sections: [{ key: 'skills', render: async (_input, context) => {
-                    const { known } = await current(context);
-                    return known.size ? `${INTRO}\n${[...known.values()].map(skill => `- ${skill.name}: ${skill.description}`).join('\n')}` : undefined;
+        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;
                 } }],
         tools: [defineTool({
                 name: 'load_skill',
-                description: 'Load the full instructions of one listed skill.',
-                parameters: Type.Object({ name: Type.String() }, { additionalProperties: false }),
+                description: fs ? 'Load the full instructions of one listed skill, or with `path` one of its companion files.' : 'Load the full instructions of one listed skill.',
+                parameters,
                 replay: 'safe',
-                execute: async (args, _api, context) => {
-                    const { known, errors } = await current(context);
-                    const skill = known.get(args.name);
+                execute: async (args, api, context) => {
+                    const text = (value) => ({ output: [{ type: 'text', text: value }] });
+                    let { known, errors } = await live.current(context);
+                    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.
+                        ({ known, errors } = await live.miss(context));
+                        shown = await seen(known, () => api.conversationId);
+                    }
+                    const skill = shown.find(candidate => candidate.name === args.name);
                     if (!skill) {
-                        const failed = errors.find(error => error.name === args.name);
-                        const text = failed ? `Skill "${args.name}" could not be loaded (${failed.path}): ${failed.message}` : `Unknown skill "${args.name}". Available: ${[...known.keys()].join(', ')}`;
-                        return { output: [{ type: 'text', text }] };
+                        const failed = visible ? undefined : errors.find(error => error.name === args.name);
+                        return text(failed ? `Skill "${args.name}" could not be loaded (${failed.path}): ${failed.message}` : `Unknown skill "${args.name}". Available: ${shown.map(entry => entry.name).join(', ')}`);
                     }
                     const folder = skillFolders.get(skill);
+                    const companions = fs ? companionLists.get(skill) ?? [] : [];
+                    if (fs && args.path !== undefined) {
+                        // Only a listed file is read, so the path cannot leave the folder or follow a symbolic link.
+                        const path = args.path.replace(/^(\.\/)+/, '');
+                        if (!companions.includes(path))
+                            return text(`Skill "${skill.name}" has no companion file "${args.path}". Companion files: ${companions.join(', ') || 'none'}`);
+                        const read = await fs.readTextFile(folder === '.' ? path : `${folder}/${path}`, context);
+                        return text(read.ok ? read.value : `Companion file "${path}" of skill "${skill.name}" could not be read: ${read.error.message}`);
+                    }
                     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.body + location }] };
+                    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);
                 },
             })],
     });
 }
+/**
+ * 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.
+ */
+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');
+    const known = new Map();
+    for (const skill of skills.map(validSkill)) {
+        if (known.has(skill.name))
+            throw new TypeError(`Duplicate skill: ${skill.name}`);
+        known.set(skill.name, skill);
+    }
+    const fixed = { known, errors: [] };
+    return skillsExtension(name, { 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 = {}) {
+    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 };
+}
 const isSkillArray = (skills) => Array.isArray(skills);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-agent",
-  "version": "0.4.22",
+  "version": "0.4.23",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -160,8 +160,8 @@
     "@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.22",
-    "@hachej/boring-ui-kit": "^0.4.22",
+    "@hachej/boring-files": "^0.4.23",
+    "@hachej/boring-ui-kit": "^0.4.23",
     "xlsx": "^0.20.3"
   },
   "peerDependenciesMeta": {