@hachej/boring-agent 0.4.24 → 0.4.26

package/README.md

@@ -349,33 +349,34 @@ Each evidence entry must link to a completed native ToolTask, its original assis
 
 `?op=configure` (POST `{ model?: { provider, modelId }, thinkingLevel? }`) changes the conversation's native agent for a model or effort picker. It is gated by `allow('configure')` and delegated to `ChatTransportAccess.configure(change)`; without that function the op answers `not-supported`. The host function applies `conversation.configure(...)` and owns the allow-list: it validates the change against its own models and levels and returns a refusal such as `{ kind: 'refused', reason }` instead of applying it (the handler checks only the request shape). `createRemoteChat().configure(change)` returns whatever the host answered. A change applies from the next model request.
 
-`createSkillsExtension` tells the model that a user message starting with `/<skill-name>` is an explicit request to load that skill first, which is what the chat's `/` menu inserts. `defineAgent(...).skills` lists each skill's name and description for such a menu.
+The skills section (`staticSkills` and `liveSkills`) tells the model that a user message starting with `/<skill-name>` is an explicit request to load that skill first, which is what the chat's `/` menu inserts. `defineAgent(...).skills` lists each skill's name and description for such a menu when the skills are an array.
 
 With self-evolution, workspace skills may be flat `.agent/skills/<name>.md` files or `.agent/skills/<name>/SKILL.md` folders. Only `SKILL.md` defines a skill inside a folder; other Markdown and deeper files are companions, not skills. `load_skill` returns the body followed by “This skill's folder is `.agent/skills/<name>`; paths in it are relative to that folder.” (For flat files the folder is `.agent/skills`.) A skill can say `see portions.md` or `see tables/2026.csv`; the agent reads that path under the returned folder with Pi's native `read`, through the same workspace provider. Scanning and loading do not read the companions. No special companion folder, new file tool or additional access is granted. Host-given `Skill` data stays `{ name, description, body }`: with no source folder, `load_skill` returns its body unchanged.
 
 ## Live skills
 
-`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`):
+`staticSkills(skills, { name, intro?, visible? })` takes an array and returns `{ extension }`. `liveSkills(source, { name, maxAgeMs?, onDiagnostics?, companionFiles?, onPublish?, intro?, visible? })` takes a `SkillSource` instead, so skills added, edited or removed after start reach the agent without rebuilding the extension; `defineAgent({ skills })` takes either. 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` 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).
+- `directorySkillSource(fs, 'skills')`: every `skills/<name>/SKILL.md`, its folder passed to `load_skill` as for self-evolution; `{ flat: true }` adds every `skills/<name>.md` file (self-evolution's `.agent/skills` layout). A missing directory holds no skills; folders without `SKILL.md` are skipped, and companion files are read only with `companionFiles` (below). Its version is each skill file's path with its `mtimeMs` and size (one `listDir` and one `fileInfo` per skill file).
 - `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. `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.
+The source is read on first use. After that the listing section and `load_skill` use the cached copy until it is older than `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: `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.
+- `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 `staticSkills` 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, and a listed file is checked again 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>"`). Before returning a listed file, `load_skill` looks at the skill's folder, every folder on the way and the file with `fileInfo` (which does not follow links) and checks the text again: a file or folder swapped for a symbolic link since the listing (the agent may write its own skill folder) answers `Companion file "<path>" of skill "<name>" could not be read: <path> is a symbolic link` and is never followed. 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. 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.
+- `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 that listing's errors followed by `{ path: '', message: 'Listing refused by onPublish: <reason>' }` (the per-skill errors are kept; the entry with `path: ''` is the refusal). A refused listing is not offered again until the source's version changes or `refresh()` runs. The first read is offered too (`previous` empty).
+- `liveSkills(source, options)` returns `{ extension, refresh }`; `staticSkills` returns `{ extension }` only. `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 until the source's `version()` changes again: later `maxAgeMs` checks and `load_skill` misses do not re-read an unchanged source, and the first read after a change offers the whole source (through `onPublish`) as usual. A source only lists everything at once, so the others' pending edits are part of that next read. 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'), {
+const skills = liveSkills(directorySkillSource(env, 'skills'), {
+  name: 'workspace.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}`)),
@@ -386,6 +387,27 @@ const agent = defineAgent({ id: 'clerk', model, extensions: [skills.extension] }
 await skills.refresh(context, 'letters'); // after the host saved skills/letters/SKILL.md
 ```
 
+### Versioned skill folders
+
+`directorySkillSource(fs, root, { versioned: true })` reads skills published as whole versions, for example from a bucket mounted read-only into the agent runtime (the library only reads a folder through the workspace `FileSystem`; it does not know where the bytes live):
+
+```
+<root>/v12/<skill>/SKILL.md   (+ companion files)
+<root>/v13/<skill>/SKILL.md
+<root>/current                one line: v13
+```
+
+- **Publish**: write the new version folder completely, then overwrite `current` with its name. A version folder is never changed once written (the library reads each version once and keeps it).
+- **Rollback**: write the old version's name back into `current`.
+- **Which version a conversation sees**: a new conversation starts on the version `current` names (read again once older than `maxAgeMs`). A running conversation keeps the version it started on until the person sends `/reload-skill`, which moves that conversation only to the version `current` names now (reading that version's folder again). `{ flat: true }` applies inside each version folder.
+- **A bad pointer**: `current` missing or unreadable, a value that is not one folder name (`../v1`), or a version with no folder is reported to `onDiagnostics` as `{ path: '<root>/current', message }`; new conversations stay on the last good version, and `/reload-skill` answers `Skills stay on version <v>: <message>`. Before any good version, the agent has no skills.
+
+`/reload-skill` is the skills extension's native tool `reload_skill` (Pi extension point: a tool and the listing section of the extension, over the `SkillSource` on the workspace's `ExecutionEnv` `FileSystem`; no second loader). The listing tells the model that a message `/reload-skill` means calling it, as `/<skill-name>` means `load_skill`; the tool answers `Skills reloaded: version <v> (<names>).` A host command can do the same without the model: `refresh(context, undefined, conversationId)` moves one conversation, `refresh(context)` every conversation, and resolves `false` on a bad pointer. `refresh(context, name)` is refused (versions move whole), and so is `onPublish`. Limit: which version each conversation is on is kept in the process, so after a restart every conversation starts on the version `current` names then.
+
+```ts
+const agent = defineAgent({ id: 'clerk', model, skills: directorySkillSource(env, '/mnt/skills', { versioned: true }) });
+```
+
 ## 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.
@@ -412,12 +434,12 @@ const delegates = [{ agent: researcher, onChild: async (parent, child, tx) => {
 | `limits.maxStartsPerHour` | `number` | Children started for one parent conversation in the last 60 minutes (rolling), ended or not. |
 | `limits.maxTaskChars` | `number` | Characters of `task`. |
 | `limits.timeoutMs` | `number` | Wall-clock milliseconds from the call's first start (kept across a rerun). On expiry the tool aborts the child conversation (`ConversationHandle.abort`, the same cancel path as a stopped call) and the call fails: `details.status` `failed`, `error` `The <agent> agent timed out after <ms> ms.` |
-| `meter` | `(parent, child) => DelegateMeter \| Promise<DelegateMeter>` | The host's handle for the child's spend: the tool calls `record(event)` once per child model response (`DelegateModelEvent`: `entryId`, `provider`, `model`, Pi's per-response `usage`) and `close(end)` once at the end (`done`, `failed`, `cancelled` or `timeout`). The kit keeps no log. |
+| `meter` | `(parent, child) => DelegateMeter \| Promise<DelegateMeter>` | The host's handle for the child's spend: the tool calls `record(event)` once per child model response (`DelegateModelEvent`: `entryId`, `provider`, `model`, Pi's per-response `usage`) and `close(end)` once at the end (`done` once the child's answer is committed to the parent; `cancelled` only when the call or the child was aborted; `timeout`; `failed` for every other end, including a throw such as a failed commit). The kit keeps no log. |
 | `childTools` | `string[]` | Names of the tools a child may have: its enabled tools are the intersection with what it would otherwise get, written as Pi's own `pi.agent` `tools` filter in the creating commit. |
 
-A call over a limit is refused: it creates no child and returns an ordinary error result the model reads, for example `2 delegates already running for this conversation (limit 2).`, `1 delegate already running on this host (limit 1).`, `1 delegate already started for this conversation in the last hour (limit 1).` or `The task is 41 characters; the limit is 40.` It never throws and carries no `details`. Only a call that would create a child is checked: a rerun that finds its existing child (after a crash or eviction) is never refused, and a call counts once, by its tool task.
+A call over a limit is refused: it creates no child and returns an ordinary error result the model reads, for example `2 delegates already running for this conversation (limit 2).`, `1 delegate already running across the conversations sharing this limit (limit 1).`, `1 delegate already started for this conversation in the last hour (limit 1).` or `The task is 41 characters; the limit is 40.` It never throws and carries no `details`. Only a call that would create a child is checked: a rerun that finds its existing child (after a crash or eviction) is never refused, and a call counts once, by its tool task.
 
-The counts live in this process and belong to the `limits` object: every delegate tool given the same object shares them, so one object passed to several `delegates` entries is one host-wide cap. Separate processes do not share them, and a restart starts them empty (reruns that reattach count their children again; the hourly window forgets earlier starts). `meter` is called after the commit that creates the child and again by a rerun in a new process that reattaches to it, since the earlier handle is gone; such a rerun sends the child's earlier responses again, so dedupe by `entryId`. A throw from `meter` fails the call; a throw from `record` or `close` is ignored.
+The counts live in this process and belong to the `limits` object: every delegate tool given the same object shares them, so one object passed to several `delegates` entries is one host-wide cap, while two entries written with their own literals (`limits: { maxRunning: 2 }` each) get two separate budgets; the refusal text says “sharing this limit” for that reason. Separate processes do not share them, and a restart starts them empty (reruns that reattach count their children again; the hourly window forgets earlier starts). `meter` is called after the commit that creates the child and again by a rerun in a new process that reattaches to it, since the earlier handle is gone; such a rerun sends the child's earlier responses again, so dedupe by `entryId`. A throw from `meter` fails the call; a throw from `record` or `close` is ignored.
 
 ```ts
 const limits = { maxRunningPerConversation: 2, maxRunning: 8, maxStartsPerHour: 20, maxTaskChars: 4000, timeoutMs: 300_000 };
@@ -439,7 +461,7 @@ const delegates = [
 
 `defineAgent({ …, selfEvolving: true, workspace })` lets the agent keep its own standing instructions, skills and tools in the `.agent/` folder of its workspace and apply them with a `reload` tool; the plan and its reasons are in [SELF-EVOLUTION.md](../../docs/architecture/SELF-EVOLUTION.md). Off by default.
 
-- One native extension per workspace, named `self-evolving:<workspace>`, so two workspaces in one host never replace each other's tools. Without a fixed `workspace` the agent works in a workspace per conversation: `inWorkspace(name)` returns the agent of workspace `name` (made once, then the same), whose configuration selects only `self-evolving:<name>`; the host creates each conversation with the agent of its owner's workspace and installs and reloads that workspace's extension when the workspace opens, so one harness and one registry never offer one workspace's agent-written tools to another's. It carries the skills (the host's, then `.agent/skills/*.md` and `.agent/skills/<name>/SKILL.md` parsed with `parseSkill`, behind the usual `load_skill`), `reload`, the agent-written tools and the `agent-written` prompt section. It is selected last; the host's `instructions` become the first section (`host-instructions`) of `agent.<id>`, because Pi renders native `instructions` after every extension section.
+- One native extension per workspace, named `self-evolving:<workspace>`, so two workspaces in one host never replace each other's tools. Without a fixed `workspace` the agent works in a workspace per conversation: `inWorkspace(name)` returns the agent of workspace `name` (made once, then the same), whose configuration selects only `self-evolving:<name>`; the host creates each conversation with the agent of its owner's workspace and installs and reloads that workspace's extension when the workspace opens, so one harness and one registry never offer one workspace's agent-written tools to another's. It carries the skills (the host's, then `.agent/skills/*.md` and `.agent/skills/<name>/SKILL.md`, read with `directorySkillSource(env, '.agent/skills', { flat: true })`, behind the usual `load_skill`), `reload`, the agent-written tools and the `agent-written` prompt section. It is selected last; the host's `instructions` become the first section (`host-instructions`) of `agent.<id>`, because Pi renders native `instructions` after every extension section.
 - `.agent/AGENTS.md` is rendered by that section on every request through the request's environment, labelled as agent-written and capped at `MAX_AGENT_INSTRUCTIONS` (16,000) characters.
 - `.agent/tools/<name>.json` is `{ name, description, parameters, run }`: `name` snake_case and not one of the agent's other tools, `parameters` a JSON Schema with `"type": "object"`, `run` one command line; a path under `.agent/` that `run` names must exist. Each becomes a native `ToolRegistration` (through `jsonSchemaTool`, so Pi refuses arguments that do not match `parameters` before `run` starts) whose `execute` runs `run` through the call's own `ExecutionEnv.exec` (the same provider instance as the files it was read from), with the arguments as one line of JSON on standard input (a quoted here-document); the output is the result and a non-zero exit is an error.
 - `reload` (and `DefinedAgent.reload(env, context)`, which a host calls on open and for the person's `/reload`) reads `.agent/` through the given environment's `FileSystem`, rebuilds the extension and calls the native `registry.install()` in every registry `install` was given (same name: replaced in place). Reloads are serialised. The report (`SelfEvolutionReport`, its `text` is the tool result) names tools added, changed and removed, the agent's skills, the instructions and every load error (invalid JSON, schema, missing script, name conflict, unreadable file). A reload never imports or evaluates anything. Without `exec` the tools are reported unavailable and skipped; instructions and skills still load.

package/dist/agents.d.ts

@@ -3,10 +3,10 @@ import type { Context } from '@earendil-works/chord';
 import type { ExecutionEnv } from '@earendil-works/pi-durable/env';
 import type { SelfEvolutionReport } from './self-evolving.js';
 import type { DelegateOptions } from './delegate.js';
-import type { Skill } from './skills.js';
+import type { Skill, SkillSource } from './skills.js';
 export type { SelfEvolutionError, SelfEvolutionReport } from './self-evolving.js';
-export { createSkillsController, createSkillsExtension, directorySkillSource, fileSkillSource, parseSkill } from './skills.js';
-export type { Skill, SkillError, SkillFileSystem, SkillListing, SkillSource, SkillsController, SkillsExtensionOptions } from './skills.js';
+export { directorySkillSource, fileSkillSource, liveSkills, parseSkill, staticSkills } from './skills.js';
+export type { LiveSkills, LiveSkillsOptions, Skill, SkillError, SkillFileSystem, SkillListing, SkillSource, SkillsOptions, SkillVersions } 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';
@@ -22,7 +22,11 @@ export interface AgentSpec {
     readonly tools?: readonly ToolRegistration[];
     /** Additional native extensions this agent selects, for example Pi's `CodingTools`. */
     readonly extensions?: readonly Extension[];
-    readonly skills?: readonly Skill[];
+    /**
+     * The agent's skills: an array, or a `SkillSource` (`directorySkillSource`, `fileSkillSource` or a host's own) read on use with
+     * `liveSkills`. A source cannot be combined with `selfEvolving`.
+     */
+    readonly skills?: readonly Skill[] | SkillSource;
     /**
      * Sub-agents this agent may hand a task to: each becomes a `delegate` tool (`createDelegateTool`) among this agent's tools, and
      * `install` installs the child agent's extensions too. The child runs in a conversation owned by the tool call, with only its own tools.
@@ -47,7 +51,7 @@ export interface DefinedAgent {
     readonly id: string;
     /** Every native extension this agent selects, own extension first; with `selfEvolving` the per-workspace extension (as first defined) last. */
     readonly extensions: readonly Extension[];
-    /** Name and description of this agent's skills, for hosts that offer them in a `/` menu. */
+    /** Name and description of this agent's skills (an array given to `skills`), for hosts that offer them in a `/` menu. A source's skills are read at run time and not listed. */
     readonly skills: readonly Pick<Skill, 'name' | 'description'>[];
     /** Native per-conversation agent configuration. */
     readonly agent: AgentChange;

package/dist/agents.js

@@ -1,9 +1,9 @@
 import { createHash } from 'node:crypto';
 import { AgentDoc, defineExtension } from '@earendil-works/pi-durable';
 import { createSelfEvolution } from './self-evolving.js';
-import { NAME, createSkillsExtension, parseSkill, validSkill } from './skills.js';
+import { NAME, isSkillArray, liveSkills, staticSkills, validSkill } from './skills.js';
 import { createDelegateTool } from './delegate.js';
-export { createSkillsController, createSkillsExtension, directorySkillSource, fileSkillSource, parseSkill } from './skills.js';
+export { directorySkillSource, fileSkillSource, liveSkills, parseSkill, staticSkills } 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. */
@@ -23,7 +23,13 @@ export function defineAgent(spec) {
     // The skills of a self-evolving agent live in its per-workspace extension, so agent-written skills join them on reload. Without a
     // workspace (a self-evolving agent whose workspace is chosen per conversation, before `inWorkspace`) they stay the host's alone.
     const evolving = spec.selfEvolving === true && spec.workspace !== undefined;
-    const hostSkills = spec.skills?.length && !evolving ? [createSkillsExtension(`agent.${spec.id}.skills`, spec.skills)] : [];
+    if (spec.selfEvolving && spec.skills !== undefined && !isSkillArray(spec.skills))
+        throw new TypeError(`Agent ${spec.id}: selfEvolving takes an array of skills, not a SkillSource`);
+    const fixed = spec.skills === undefined ? [] : isSkillArray(spec.skills) ? spec.skills : [];
+    const skillsName = `agent.${spec.id}.skills`;
+    const hostSkills = spec.skills === undefined || evolving ? [] : isSkillArray(spec.skills)
+        ? (spec.skills.length ? [staticSkills(spec.skills, { name: skillsName }).extension] : [])
+        : [liveSkills(spec.skills, { name: skillsName }).extension];
     const listed = (skills) => Object.freeze(skills.map(skill => Object.freeze({ name: skill.name, description: skill.description.trim() })));
     const reserved = [...tools, ...(spec.extensions ?? []).flatMap(extension => extension.tools ?? [])].map(tool => tool.name);
     /** The agent as one native configuration: its own extensions, the host's, and with `evolution` the per-workspace one last. */
@@ -38,7 +44,7 @@ export function defineAgent(spec) {
             ...(spec.thinkingLevel === undefined ? {} : { thinkingLevel: spec.thinkingLevel }),
             ...(spec.cwd === undefined ? {} : { cwd: spec.cwd }),
         });
-        const fixedSkills = listed(spec.skills ?? []);
+        const fixedSkills = listed(fixed);
         return Object.freeze({
             id: spec.id, extensions, agent,
             get skills() { return evolution ? listed(evolution.skills()) : fixedSkills; },
@@ -58,7 +64,7 @@ export function defineAgent(spec) {
         });
     }
     const evolutionOf = (workspace) => createSelfEvolution({
-        name: `self-evolving:${workspace}`, skills: (spec.skills ?? []).map(validSkill), parseSkill, skillsExtension: createSkillsExtension, reserved,
+        name: `self-evolving:${workspace}`, skills: fixed.map(validSkill), reserved,
     });
     if (!spec.selfEvolving)
         return assemble([...own, ...hostSkills], undefined);

package/dist/delegate.d.ts

@@ -117,7 +117,8 @@ export interface DelegateOptions {
  * child's final text. The child inherits the parent's approval and sandbox extensions (appended after its own, in the parent's order, so a
  * sandbox stays last), so a delegate cannot escape the parent's gate; `details` is a `DelegateDetails` (live while the child runs) for a UI that shows it.
  * `onChild` lets the host write the parent's identity onto the child in the same commit that creates it.
- * Host policy, all optional (Pi has no extension point for these): `limits` (running children per conversation and per host,
+ * Host policy, all optional (Pi has no extension point for these): `limits` (running children per conversation and across
+ * the conversations sharing one `limits` object in this process,
  * starts per hour, task size, a child deadline; a refusal is an error result, never a throw, and creates no child), `meter`
  * (the host's flight-log handle, fed each child model response and closed when the call ends) and `childTools` (an allow list
  * applied through Pi's own tool filter). With none of them set the tool behaves as before.

package/dist/delegate.js

@@ -13,7 +13,8 @@ export const DELEGATE_DETAILS_KIND = 'boring.delegate';
  * child's final text. The child inherits the parent's approval and sandbox extensions (appended after its own, in the parent's order, so a
  * sandbox stays last), so a delegate cannot escape the parent's gate; `details` is a `DelegateDetails` (live while the child runs) for a UI that shows it.
  * `onChild` lets the host write the parent's identity onto the child in the same commit that creates it.
- * Host policy, all optional (Pi has no extension point for these): `limits` (running children per conversation and per host,
+ * Host policy, all optional (Pi has no extension point for these): `limits` (running children per conversation and across
+ * the conversations sharing one `limits` object in this process,
  * starts per hour, task size, a child deadline; a refusal is an error result, never a throw, and creates no child), `meter`
  * (the host's flight-log handle, fed each child model response and closed when the call ends) and `childTools` (an allow list
  * applied through Pi's own tool filter). With none of them set the tool behaves as before.
@@ -60,7 +61,8 @@ export function createDelegateTool(options) {
             if ('refused' in opened)
                 return { output: [{ type: 'text', text: opened.refused }], isError: true };
             const childId = opened.id;
-            let meter, end = 'cancelled', timer;
+            // `end` is set where the call's outcome is known; a throw ends `cancelled` only when the call itself was aborted.
+            let meter, end = 'failed', timer;
             try {
                 meter = await options.meter?.(parent, childId);
                 const startedAt = await api.memo('delegate.startedAt', Date.now(), context);
@@ -96,12 +98,16 @@ export function createDelegateTool(options) {
                     end = reason === 'aborted' ? 'cancelled' : 'failed';
                     return { output: [{ type: 'text', text: error }], isError: true, details: reason === 'aborted' ? details('cancelled', counts) : details('failed', counts, error) };
                 }
-                end = 'done';
                 const answer = await api.commit(tx => tx.entry(AssistantEntry, settled.answer), context);
+                end = 'done';
                 const message = answer?.model?.find(part => part.role === 'assistant');
                 const text = message?.role === 'assistant' ? message.content.flatMap(part => part.type === 'text' ? [part.text] : []).join('\n') : '';
                 return { output: [{ type: 'text', text }], details: details('done', counts) };
             }
+            catch (error) {
+                end = context.abortSignal?.aborted ? 'cancelled' : 'failed';
+                throw error;
+            }
             finally {
                 clearTimeout(timer);
                 ledger?.running.delete(api.taskId);
@@ -216,7 +222,7 @@ function admit(limits, ledger, taskId, parent, task) {
     if (limits.maxRunningPerConversation !== undefined && here >= limits.maxRunningPerConversation)
         return `${delegates(here)} already running for this conversation (limit ${limits.maxRunningPerConversation}).`;
     if (limits.maxRunning !== undefined && others.length >= limits.maxRunning)
-        return `${delegates(others.length)} already running on this host (limit ${limits.maxRunning}).`;
+        return `${delegates(others.length)} already running across the conversations sharing this limit (limit ${limits.maxRunning}).`;
     const started = [...ledger.starts].filter(([id, start]) => id !== taskId && start.parent === parent).length;
     if (limits.maxStartsPerHour !== undefined && started >= limits.maxStartsPerHour)
         return `${delegates(started)} already started for this conversation in the last hour (limit ${limits.maxStartsPerHour}).`;

package/dist/mentions.d.ts

@@ -33,8 +33,8 @@ export declare const MENTION_LIMITS: Readonly<{
 }>;
 /** Every part this module adds starts with this prefix, so a viewer can tell it from what the person typed. */
 export declare const MENTION_FILE_PREFIX = "<file path=\"";
-/** The `@path` tokens of a message: at the start or after whitespace; a bare path drops trailing punctuation, a quoted `@"a b.md"` (escapes `\"`, `\\`) is taken as written. The syntax pi-chat produces. The registry item `pi-chat` cannot import this, so it copies the
- * parser (`MENTION_TOKEN` and `pieces` in `registry/pi-chat/config.ts`); `test/contracts/pi-chat-source.test.mjs` keeps the two equal. */
+/** The `@path` tokens of a message: at the start or after whitespace; a bare path drops trailing punctuation, a quoted `@"a b.md"` (escapes `\"`, `\\`) is taken as written. The syntax the chat writes. The browser cannot import this, so the kit's `chat-text` holds the
+ * same parser (`mentionedPaths`, `MENTION_TOKEN` and `pieces` of `@hachej/boring-ui-kit/chat-text`); `test/packages/ui-chat-text.test.mjs` keeps the two equal. */
 export declare function mentionedPaths(text: string): string[];
 /** A workspace-relative path with no absolute prefix, no `..`, no backslash and no control characters. */
 export declare function safeMentionPath(path: string): boolean;

package/dist/mentions.js

@@ -3,8 +3,8 @@ import { SNIFF_BYTES, fileKind, nativeImageType } from './file-types.js';
 export const MENTION_LIMITS = Object.freeze({ fileBytes: 100_000, totalBytes: 300_000, files: 20 });
 /** Every part this module adds starts with this prefix, so a viewer can tell it from what the person typed. */
 export const MENTION_FILE_PREFIX = '<file path="';
-/** The `@path` tokens of a message: at the start or after whitespace; a bare path drops trailing punctuation, a quoted `@"a b.md"` (escapes `\"`, `\\`) is taken as written. The syntax pi-chat produces. The registry item `pi-chat` cannot import this, so it copies the
- * parser (`MENTION_TOKEN` and `pieces` in `registry/pi-chat/config.ts`); `test/contracts/pi-chat-source.test.mjs` keeps the two equal. */
+/** The `@path` tokens of a message: at the start or after whitespace; a bare path drops trailing punctuation, a quoted `@"a b.md"` (escapes `\"`, `\\`) is taken as written. The syntax the chat writes. The browser cannot import this, so the kit's `chat-text` holds the
+ * same parser (`mentionedPaths`, `MENTION_TOKEN` and `pieces` of `@hachej/boring-ui-kit/chat-text`); `test/packages/ui-chat-text.test.mjs` keeps the two equal. */
 export function mentionedPaths(text) {
     const found = new Set();
     for (const match of text.matchAll(/(^|\s)@(?:"((?:[^"\\]|\\.)*)"|([^\s]+))/g)) {

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,18 +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), or with the `onPublish` refusal. */
-    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).
@@ -52,39 +79,62 @@ 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`. Read through the
-     * source's `fs`; an array or a source without `fs` throws.
+     * 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`; 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>`.
+     * (or throw) to refuse it: the current listing stays, and `onDiagnostics` gets its errors plus `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 {
+/** 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. Resolves `true` when published,
-     * `false` when `onPublish` refused it.
+     * 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

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;
@@ -163,8 +208,9 @@ function liveSkills(source, options) {
     }
     async function publish(next) {
         const refused = await refusal(next);
+        // The listing in effect stays, so its errors stay too: the refusal is added to them, never replaces them.
         if (refused !== undefined) {
-            options.onDiagnostics?.([{ path: '', message: `Listing refused by onPublish: ${refused}` }]);
+            options.onDiagnostics?.([...state.errors, { path: '', message: `Listing refused by onPublish: ${refused}` }]);
             return false;
         }
         state = next;
@@ -192,17 +238,117 @@ function liveSkills(source, options) {
         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;
+            // The read is accounted for at this version, whether all of it or one skill was taken (or onPublish refused it): the
+            // others kept by a one-skill refresh are offered again only once the source changes, not at the next maxAgeMs check.
+            version = next;
             checkedAt = Date.now();
             return publish(name === undefined ? listing : only(name, listing, state));
         }),
     };
 }
+/**
+ * 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. */
 const companionLists = new WeakMap();
+const notText = (text) => /[\u0000\uFFFD]/.test(text);
+/**
+ * Why a listed companion may not be read now, or `undefined`: the skill's folder and every folder on the way must still be
+ * directories and the file a regular file (`fileInfo` does not follow links), so a link swapped in since the listing is refused.
+ */
+async function companionChanged(fs, folder, relative, context) {
+    const parts = relative.split('/'), base = folder === '.' ? '' : `${folder}/`;
+    const steps = [...(folder === '.' ? [] : [{ path: folder, kind: 'directory' }]),
+        ...parts.map((_, index) => ({ path: base + parts.slice(0, index + 1).join('/'), kind: index === parts.length - 1 ? 'file' : 'directory' }))];
+    for (const step of steps) {
+        const info = await fs.fileInfo(step.path, context);
+        if (!info.ok)
+            return info.error.message;
+        if (info.value.kind === 'symlink')
+            return `${step.path} is a symbolic link`;
+        if (info.value.kind !== step.kind)
+            return `${step.path} is not a ${step.kind === 'file' ? 'regular file' : 'directory'}`;
+    }
+    return undefined;
+}
 /**
  * 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
@@ -246,7 +392,7 @@ async function withCompanions(fs, listing, context) {
                 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))
+                else if (notText(text.value))
                     leftOut(path, 'Companion file left out: not UTF-8 text');
                 else
                     files.push(path);
@@ -257,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) {
@@ -271,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',
@@ -283,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.
@@ -298,31 +445,43 @@ function skillsExtension(name, live, options, fs) {
                     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.
+                        // Only a listed file is read, so the path cannot leave the folder; it is checked again now, so a link swapped in
+                        // since the listing (the agent may write its own skill folder) is refused rather than followed.
                         const path = args.path.replace(/^(\.\/)+/, '');
-                        if (!companions.includes(path))
+                        if (!companions.includes(path) || folder === undefined)
                             return text(`Skill "${skill.name}" has no companion file "${args.path}". Companion files: ${companions.join(', ') || 'none'}`);
+                        const failed = (why) => text(`Companion file "${path}" of skill "${skill.name}" could not be read: ${why}`);
+                        const changed = await companionChanged(fs, folder, path, context);
+                        if (changed !== undefined)
+                            return failed(changed);
                         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}`);
+                        if (!read.ok)
+                            return failed(read.error.message);
+                        return notText(read.value) ? failed('not UTF-8 text') : text(read.value);
                     }
                     const location = folder === undefined ? '' : `\n\nThis skill's folder is \`${folder}\`; paths in it are relative to that folder.`;
                     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))
@@ -330,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.24",
+  "version": "0.4.26",
   "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.24",
-    "@hachej/boring-ui-kit": "^0.4.24",
+    "@hachej/boring-files": "^0.4.26",
+    "@hachej/boring-ui-kit": "^0.4.26",
     "xlsx": "^0.20.3"
   },
   "peerDependenciesMeta": {