@hachej/boring-agent 0.4.21 → 0.4.23

package/README.md

@@ -353,11 +353,44 @@ Each evidence entry must link to a completed native ToolTask, its original assis
 
 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`):
+
+- `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. `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.
 
-**Delegate.** `createDelegateTool({ agent, name?, description? })` from `@hachej/boring-agent/agents` is Pi's documented subagent pattern (pi-durable README, "Abort and Subagents"; pi-durable ships it as an example, not an export) as a tool factory. `delegate({ task })` creates a child conversation owned by the calling tool task (`ownership: { kind: 'task', taskId }`), configured as the child agent alone (its extensions, model and instructions; the inherited tool filters reset), submits the task with request id `<name>:<taskId>` and returns only the child's final text, with `details` (`DelegateDetails`, below) naming the child. It is replay-safe: a rerun after a crash or eviction finds its child through Pi's ownership index (`scanConversations({ ownerTaskId })`) and its submission through the request id, so it never starts a second child or turn. Aborting the call aborts the child. With `defineAgent`, declare `delegates: [{ agent: researcher }]`: each becomes a tool of the agent and `install(registry)` installs the child's extensions as well. A raw-Pi host installs the child agent's extensions itself.
+**Delegate.** `createDelegateTool({ agent, name?, description?, onChild?, limits?, meter?, childTools? })` from `@hachej/boring-agent/agents` is Pi's documented subagent pattern (pi-durable README, "Abort and Subagents"; pi-durable ships it as an example, not an export) as a tool factory. `delegate({ task })` creates a child conversation owned by the calling tool task (`ownership: { kind: 'task', taskId }`), configured as the child agent alone (its extensions, model and instructions; the inherited tool filters reset), submits the task with request id `<name>:<taskId>` and returns only the child's final text, with `details` (`DelegateDetails`, below) naming the child. It is replay-safe: a rerun after a crash or eviction finds its child through Pi's ownership index (`scanConversations({ ownerTaskId })`) and its submission through the request id, so it never starts a second child or turn. Aborting the call aborts the child. With `defineAgent`, declare `delegates: [{ agent: researcher }]`: each becomes a tool of the agent and `install(registry)` installs the child's extensions as well. A raw-Pi host installs the child agent's extensions itself.
 
 **Child identity.** The kit copies no identity onto a child; the host decides what a child carries. Pass `onChild(parent, child, tx)` in `DelegateOptions` (or a `delegates` entry): it runs inside the same native commit (`ToolExecutionApi.commit`, Pi's `Tx`) that creates and configures the child, so the child never exists without what it writes, and a throw aborts the commit and leaves no child (the delegate call returns an error). It runs once per child, not on a replay that finds the existing child. Read and write only through `tx`:
 
@@ -370,6 +403,30 @@ const delegates = [{ agent: researcher, onChild: async (parent, child, tx) => {
 
 **Sub-agent card data.** Every delegate call's `details` is a stable `DelegateDetails` (exported from `@hachej/boring-agent/agents`, with `DELEGATE_DETAILS_KIND` and `DelegateStatus`): `{ kind: 'boring.delegate', version: 1, agent, conversationId, status, startedAt, durationMs, toolCalls, tokens: { input, output }, error? }`. `status` is `running`, `done`, `failed` (with `error`, the same text as the result) or `cancelled`; `conversationId` is the child conversation, `toolCalls` counts the tool calls in the child's assistant messages and `tokens` sums the child's `UsageDoc` (input includes cache reads and writes). While the child runs, the tool publishes `running` values through Pi's `api.details`, so they appear in the call's `LiveDoc` tool slot: it watches the child's `LiveDoc` (`api.watchDoc`) and, when a step of the child's run changes, recounts (`tx.scanEntries` from the last counted entry, `api.snapshot(UsageDoc)`) and publishes only when the counts change; Pi paces the commits. The final result carries `done`, `failed` or `cancelled`. When the delegate call itself is stopped, Pi writes its aborted result from the slot, so its details keep the last `running` value: read `running` on a settled error result as `cancelled`. The `pi-chat` block's `SubagentCard` and `parseDelegateDetails(details, result?)` do this and render any call carrying these details.
 
+**Delegate limits, meter and child tools.** Host policy, all optional in `DelegateOptions` (or a `delegates` entry); Pi has no extension point for running-child limits, start rates or a host meter, so the tool enforces them itself (BORING-PI-4: host concern). With none set the tool behaves as above.
+
+| Option | Type | Effect |
+| --- | --- | --- |
+| `limits.maxRunningPerConversation` | `number` | Children running at once for one parent conversation. |
+| `limits.maxRunning` | `number` | Children running at once across every parent conversation, for the delegate tools sharing this `limits` object in this process. |
+| `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. |
+| `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.
+
+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.
+
+```ts
+const limits = { maxRunningPerConversation: 2, maxRunning: 8, maxStartsPerHour: 20, maxTaskChars: 4000, timeoutMs: 300_000 };
+const delegates = [
+  { agent: researcher, limits, childTools: ['search', 'read_file'], meter: (parent, child) => flightLog.open({ parent, child }) },
+  { agent: writer, limits }, // same object: shares the host-wide cap of 8
+];
+```
+
 **Schedule.** `@hachej/boring-agent/schedule` exports `createScheduleExtension({ now?, onDeadline?, maxDelaySeconds? })`, one native extension with `schedule({ instruction, delaySeconds | at, operationId? })`, `list_schedules()` and `cancel_schedule({ id })`, plus the delivery task `ScheduledDelivery`. A schedule is a native Pi task owned by the conversation as background work: it sleeps on the Harness clock (`runtime.sleep`) and then submits the instruction to its conversation as a follow-up input (entry kind `boring.schedule.delivery`, request id = schedule id, so a replayed delivery never submits twice). Pi's scheduler runs it and a restart resumes it; there is no second scheduler. Pending schedules live in the conversation document `ConversationSchedules`, so a conversation lists and cancels only its own; a cancelled schedule's task wakes and ends without delivering. `schedule` is idempotent on `operationId` (default: the tool task, so a replayed call returns the schedule it made). Hosts schedule outside a tool with `addSchedule(tx, conversationId, { operationId, instruction, runAt })`, `cancelSchedule(tx, conversationId, id)` and `listSchedules(harness, conversationId, context)`. Pass the Harness's own clock as `now`. A host with one wake-up timer (a Durable Object alarm) computes the earliest deadline from `harness.inspect()` with `scheduledDeadline(task)` and moves the timer earlier from `onDeadline`; its alarm handler only reopens or resumes the Harness, and Pi delivers what is due.
 
 **Storage conformance.** Boring ships no Pi `Storage` implementation. `test/packages/pi-storage-conformance.test.mjs` runs Pi's own suite (`createStorageConformance`, what `registerStorageConformance` registers with Vitest) on every storage the repository configures: `openPiStorage` (shared/pi-storage.mjs) on the local-disk and network-file-system presets, Pi's `SqliteStorage` over `openBrowserSqlite`, and Pi's `openDurableObjectSqliteStorage` on a SQLite-backed Durable Object in workerd through miniflare (the version the pinned wrangler resolves).

package/dist/agents.d.ts

@@ -5,12 +5,12 @@ 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, parseSkill } from './skills.js';
-export type { Skill } 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';
-export type { DelegateDetails, DelegateOptions, DelegateStatus } from './delegate.js';
+export type { DelegateDetails, DelegateEnd, DelegateLimits, DelegateMeter, DelegateModelEvent, DelegateOptions, DelegateStatus } from './delegate.js';
 /** One agent as plain data over native Pi pieces. It is a convenience, not another registry or lifecycle. */
 export interface AgentSpec {
     /** Stable name; it becomes the native extension name `agent.<id>`. */

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, 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/delegate.d.ts

@@ -1,4 +1,5 @@
-import type { AgentChange, ConversationId, ToolRegistration, Tx } from '@earendil-works/pi-durable';
+import type { AgentChange, ConversationId, EntryId, ToolRegistration, Tx } from '@earendil-works/pi-durable';
+import type { Usage } from '@earendil-works/pi-ai';
 export declare const DELEGATE_TOOL = "delegate";
 /** `DelegateDetails.kind`: how a UI recognises a sub-agent call's details, whatever the tool is named. */
 export declare const DELEGATE_DETAILS_KIND = "boring.delegate";
@@ -31,6 +32,50 @@ export type DelegateDetails = {
     /** Why the child failed (`failed` only). */
     readonly error?: string;
 };
+/**
+ * Host policy for delegate calls (host-owned, BORING-PI-4: Pi has no extension point for running-child limits, start rates, task
+ * size or a child deadline, so the tool enforces them). Every field is optional; an unset field is no limit. A call that hits a
+ * limit creates no child and returns an error result whose text says why (never a throw), for example
+ * `2 delegates already running for this conversation (limit 2).`. Only a call that would create a child is checked: a rerun that
+ * reattaches to its existing child (after a crash or eviction) is never refused and is counted once.
+ *
+ * The counts live in this process and belong to this object: every delegate tool given the same `limits` object shares them
+ * (pass one object to several `delegates` entries for one host-wide cap). A process restart starts them empty; reruns that
+ * reattach to their children count those again, and the hourly window forgets the starts before the restart.
+ */
+export interface DelegateLimits {
+    /** Children running at once for one parent conversation. */
+    readonly maxRunningPerConversation?: number;
+    /** Children started for one parent conversation in the last 60 minutes (a rolling window), whether or not they ended. */
+    readonly maxStartsPerHour?: number;
+    /** Children running at once across every parent conversation, for the tools sharing this object in this process. */
+    readonly maxRunning?: number;
+    /** Characters of `task`. */
+    readonly maxTaskChars?: number;
+    /**
+     * Wall-clock milliseconds a child may run, from the call's first start (kept across a rerun). On expiry the tool aborts the
+     * child conversation (Pi's `ConversationHandle.abort`) and the call fails with `The <agent> agent timed out after <ms> ms.`
+     */
+    readonly timeoutMs?: number;
+}
+/** How a metered child ended: `timeout` is a child `DelegateLimits.timeoutMs` cancelled. */
+export type DelegateEnd = 'done' | 'failed' | 'cancelled' | 'timeout';
+/** One response of the child's model, from its committed assistant entry. */
+export type DelegateModelEvent = {
+    /** The child's entry; a rerun after a crash sends the entries again, so a host dedupes by `entryId`. */
+    readonly entryId: EntryId;
+    readonly provider: string;
+    readonly model: string;
+    /** Pi's per-response `Usage` (tokens and cost), as recorded on the assistant message. */
+    readonly usage: Usage;
+};
+/** The host's handle for one child's spend (its own flight log); the kit only feeds and closes it. */
+export interface DelegateMeter {
+    /** One child model response, in entry order. A throw is ignored: the host's log owns its failures, not the child. */
+    readonly record: (event: DelegateModelEvent) => void | Promise<void>;
+    /** Called once, after the last `record`, when the call ends. A throw is ignored. */
+    readonly close: (end: DelegateEnd) => void | Promise<void>;
+}
 export interface DelegateOptions {
     /**
      * The child agent, usually a `defineAgent` result (its `id` and native `agent` change). The child conversation selects exactly its
@@ -49,6 +94,20 @@ export interface DelegateOptions {
      * It runs once per child (never on a replay that finds the existing child); a throw aborts the commit, so no child exists.
      */
     readonly onChild?: (parent: ConversationId, child: ConversationId, tx: Tx) => void | Promise<void>;
+    /** Concurrency, rate, task size and timeout limits (`DelegateLimits`). */
+    readonly limits?: DelegateLimits;
+    /**
+     * Host metering (host-owned, BORING-PI-4: Pi records spend in `pi.usage` but has no hook to a host's log). Called after the
+     * commit that creates the child, and again by a rerun in a new process that reattaches to it (the earlier handle is gone).
+     * The tool sends the handle each child model response (`DelegateModelEvent`) and closes it when the call ends. A throw fails
+     * the call. The kit keeps no log.
+     */
+    readonly meter?: (parent: ConversationId, child: ConversationId) => DelegateMeter | Promise<DelegateMeter>;
+    /**
+     * Names of the tools a child may have: its enabled tools become the intersection of this list with what it would otherwise
+     * get, written as Pi's own tool filter (`pi.agent` `tools`) in the commit that creates it. Unset: no restriction.
+     */
+    readonly childTools?: readonly string[];
 }
 /**
  * Pi's subagent pattern (pi-durable README "Abort and Subagents") as a tool factory: the child is a conversation owned by the
@@ -58,6 +117,10 @@ 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,
+ * 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.
  */
 export declare function createDelegateTool(options: DelegateOptions): ToolRegistration;
 //# sourceMappingURL=delegate.d.ts.map

package/dist/delegate.js

@@ -1,4 +1,4 @@
-import { AssistantEntry, LiveDoc, UsageDoc, configure, defineTool } from '@earendil-works/pi-durable';
+import { AgentDoc, AssistantEntry, LiveDoc, UsageDoc, configure, defineTool } from '@earendil-works/pi-durable';
 import { Type } from '@earendil-works/pi-ai';
 const GUARDS = (globalThis[Symbol.for('boring.agent.guards')] ??= new WeakSet()); // approval + sandbox extensions: a delegated child inherits them
 const isGuard = (extension) => GUARDS.has(extension);
@@ -13,12 +13,17 @@ 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,
+ * 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.
  */
 export function createDelegateTool(options) {
     const name = options.name ?? DELEGATE_TOOL;
     // A task-owned conversation starts as a copy of its owner's agent; reset the inherited filters so the child's own extensions are
     // its whole toolset, then apply the child agent. `cwd` stays inherited unless the child agent sets one.
     const child = { tools: null, modelTools: null, instructions: null, thinkingLevel: null, ...options.agent.agent };
+    const { limits } = options;
     return defineTool({
         name,
         description: options.description ?? `Delegate a self-contained task to the ${options.agent.id} agent and get its final answer back.`,
@@ -27,41 +32,82 @@ export function createDelegateTool(options) {
         execute: async (args, api, context) => {
             const inherited = (await api.agent(context)).extensions.filter(isGuard);
             const agent = withGuards(child, inherited);
-            const childId = await api.commit(async (tx) => {
-                const existing = (await tx.scanConversations({ ownerTaskId: api.taskId }, 1)).items[0];
-                if (existing !== undefined)
-                    return existing.id;
-                const created = await tx.createConversation({ ownership: { kind: 'task', taskId: api.taskId } });
-                await configure(tx, created.id, agent);
-                await options.onChild?.(api.conversationId, created.id, tx);
-                return created.id;
-            }, context);
-            const startedAt = await api.memo('delegate.startedAt', Date.now(), context);
-            const progress = childProgress(api, childId);
-            const details = (status, counts, error) => ({
-                kind: DELEGATE_DETAILS_KIND, version: 1, agent: options.agent.id, conversationId: childId, status, startedAt,
-                durationMs: Math.max(1, Date.now() - startedAt), ...counts, ...(error === undefined ? {} : { error })
-            });
-            const initial = await progress.read(context);
-            await api.details(details('running', initial), context);
-            const conversation = await api.conversation(childId, context);
-            if (conversation === undefined)
-                throw new Error(`Delegate conversation ${childId} is missing`);
-            const submission = await conversation.submit({ type: 'input', content: args.task, requestId: `${name}:${api.taskId}` }, context);
-            const live = await publishLive(api, childId, progress, initial, counts => api.details(details('running', counts), context), context);
-            // A stopped call ends here: Pi writes its aborted result from the slot, so its details stay the last `running` value.
-            const settled = await submission.wait(context).finally(() => live.stop());
-            const counts = await progress.read(context);
-            if (settled.status !== 'done' || settled.type !== 'input') {
-                const reason = settled.status === 'unanswered' ? settled.reason : settled.status;
-                const detail = settled.status === 'unanswered' && typeof settled.detail === 'string' && settled.detail ? settled.detail : undefined;
-                const error = `The ${options.agent.id} agent did not answer: ${reason}${detail ? ` (${detail})` : ''}`;
-                return { output: [{ type: 'text', text: error }], isError: true, details: reason === 'aborted' ? details('cancelled', counts) : details('failed', counts, error) };
+            const parent = api.conversationId, ledger = limits === undefined ? undefined : ledgerOf(limits);
+            let opened;
+            try {
+                opened = await api.commit(async (tx) => {
+                    const existing = (await tx.scanConversations({ ownerTaskId: api.taskId }, 1)).items[0];
+                    if (existing !== undefined) {
+                        ledger?.running.set(api.taskId, parent);
+                        return { id: existing.id };
+                    }
+                    const refused = ledger === undefined ? undefined : admit(limits, ledger, api.taskId, parent, args.task);
+                    if (refused !== undefined)
+                        return { refused };
+                    const created = await tx.createConversation({ ownership: { kind: 'task', taskId: api.taskId } });
+                    await configure(tx, created.id, agent);
+                    if (options.childTools !== undefined)
+                        await allowTools(tx, created.id, options.childTools, api);
+                    await options.onChild?.(parent, created.id, tx);
+                    return { id: created.id };
+                }, context);
+            }
+            catch (error) {
+                ledger?.running.delete(api.taskId);
+                ledger?.starts.delete(api.taskId);
+                throw error;
+            }
+            if ('refused' in opened)
+                return { output: [{ type: 'text', text: opened.refused }], isError: true };
+            const childId = opened.id;
+            let meter, end = 'cancelled', timer;
+            try {
+                meter = await options.meter?.(parent, childId);
+                const startedAt = await api.memo('delegate.startedAt', Date.now(), context);
+                const progress = childProgress(api, childId, meter);
+                const details = (status, counts, error) => ({
+                    kind: DELEGATE_DETAILS_KIND, version: 1, agent: options.agent.id, conversationId: childId, status, startedAt,
+                    durationMs: Math.max(1, Date.now() - startedAt), ...counts, ...(error === undefined ? {} : { error })
+                });
+                const initial = await progress.read(context);
+                await api.details(details('running', initial), context);
+                const conversation = await api.conversation(childId, context);
+                if (conversation === undefined)
+                    throw new Error(`Delegate conversation ${childId} is missing`);
+                const submission = await conversation.submit({ type: 'input', content: args.task, requestId: `${name}:${api.taskId}` }, context);
+                // The timeout reuses the cancel path: aborting the child settles its submission `aborted`, reported below as a timeout.
+                let timedOut = false;
+                if (limits?.timeoutMs !== undefined)
+                    timer = setTimeout(() => { timedOut = true; conversation.abort(context).catch(() => undefined); }, Math.max(0, startedAt + limits.timeoutMs - Date.now()));
+                const live = await publishLive(api, childId, progress, initial, counts => api.details(details('running', counts), context), context);
+                // A stopped call ends here: Pi writes its aborted result from the slot, so its details stay the last `running` value.
+                const settled = await submission.wait(context).finally(() => live.stop());
+                clearTimeout(timer);
+                const counts = await progress.read(context);
+                if (settled.status !== 'done' || settled.type !== 'input') {
+                    if (timedOut) {
+                        end = 'timeout';
+                        const error = `The ${options.agent.id} agent timed out after ${limits.timeoutMs} ms.`;
+                        return { output: [{ type: 'text', text: error }], isError: true, details: details('failed', counts, error) };
+                    }
+                    const reason = settled.status === 'unanswered' ? settled.reason : settled.status;
+                    const detail = settled.status === 'unanswered' && typeof settled.detail === 'string' && settled.detail ? settled.detail : undefined;
+                    const error = `The ${options.agent.id} agent did not answer: ${reason}${detail ? ` (${detail})` : ''}`;
+                    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);
+                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) };
+            }
+            finally {
+                clearTimeout(timer);
+                ledger?.running.delete(api.taskId);
+                if (meter !== undefined)
+                    await quietly(() => meter.close(end));
             }
-            const answer = await api.commit(tx => tx.entry(AssistantEntry, settled.answer), context);
-            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) };
         },
     });
 }
@@ -69,26 +115,33 @@ export function createDelegateTool(options) {
  * The child's counts from its native records: tool calls from its committed assistant entries (scanned once, incrementally,
  * through the invocation's commit), tokens from its `pi.usage` (Pi's `UsageDoc`, both buckets).
  */
-function childProgress(api, childId) {
+function childProgress(api, childId, meter) {
     let toolCalls = 0, after;
     return {
         async read(context) {
             const scanned = await api.commit(async (tx) => {
                 let found = 0, last = after, cursor;
+                const events = [];
                 do {
                     const page = await tx.scanEntries({ conversationId: childId, order: 'ascending', ...(last === undefined ? {} : { minEntryId: (last + 1) }) }, 100, cursor);
                     for (const entry of page.items) {
                         last = entry.id;
                         for (const message of entry.model ?? [])
-                            if (message.role === 'assistant')
+                            if (message.role === 'assistant') {
                                 found += message.content.filter(part => part.type === 'toolCall').length;
+                                events.push({ entryId: entry.id, provider: message.provider, model: message.model, usage: message.usage });
+                            }
                     }
                     cursor = page.next;
                 } while (cursor !== undefined);
-                return { found, last };
+                return { found, last, events };
             }, context);
             toolCalls += scanned.found;
             after = scanned.last;
+            // Outside the commit, which may run more than once; reads are sequential, so events arrive once each, in entry order.
+            if (meter !== undefined)
+                for (const event of scanned.events)
+                    await quietly(() => meter.record(event));
             const usage = await api.snapshot(UsageDoc, childId, context);
             const tokens = { input: 0, output: 0 };
             for (const bucket of [usage?.models, usage?.tools])
@@ -134,6 +187,55 @@ async function publishLive(api, childId, progress, initial, publish, context) {
     });
     return { async stop() { stopped = true; await watch.stop(); await reading; await committing; } };
 }
+const quietly = async (run) => { try {
+    await run();
+}
+catch { /* the host's meter owns its failures */ } };
+const LEDGERS = new WeakMap();
+const ledgerOf = (limits) => {
+    let ledger = LEDGERS.get(limits);
+    if (ledger === undefined)
+        LEDGERS.set(limits, ledger = { running: new Map(), starts: new Map() });
+    return ledger;
+};
+const HOUR_MS = 60 * 60 * 1000;
+const delegates = (count) => `${count} delegate${count === 1 ? '' : 's'}`;
+/**
+ * Why a new child may not start, or `undefined` after reserving its running slot and its start. Synchronous, so two calls in
+ * this process cannot both pass the same last slot; idempotent for one task, since a commit may run its change again.
+ */
+function admit(limits, ledger, taskId, parent, task) {
+    if (limits.maxTaskChars !== undefined && task.length > limits.maxTaskChars)
+        return `The task is ${task.length} characters; the limit is ${limits.maxTaskChars}.`;
+    const now = Date.now();
+    for (const [id, start] of ledger.starts)
+        if (now - start.at >= HOUR_MS)
+            ledger.starts.delete(id);
+    const others = [...ledger.running].filter(([id]) => id !== taskId);
+    const here = others.filter(([, owner]) => owner === parent).length;
+    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}).`;
+    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}).`;
+    ledger.running.set(taskId, parent);
+    ledger.starts.set(taskId, { parent, at: now });
+    return undefined;
+}
+/** Narrow the new child's tool filter (Pi's `pi.agent` `tools`, by name) to `allowed`: the intersection with what it would enable. */
+async function allowTools(tx, childId, allowed, api) {
+    const state = await tx.doc(AgentDoc, childId);
+    const allow = new Set(allowed), current = state.tools;
+    if (Array.isArray(current)) {
+        state.tools = current.filter(tool => allow.has(tool));
+        return;
+    }
+    // Unset or `{ remove }`: every enabled tool (minus the removed), in registry order, kept to the allowed names.
+    const removed = new Set(current?.remove ?? []);
+    state.tools = [...new Set(api.registry.tools().map(({ tool }) => tool.name))].filter(tool => allow.has(tool) && !removed.has(tool));
+}
 const runShape = (live) => JSON.stringify([live?.run?.taskId ?? null, live?.generation?.attempt ?? null, live?.generation?.message === undefined,
     (live?.tools ?? []).map(slot => `${slot.callId}:${slot.status}`)]);
 /** `change` with the parent's guard extensions appended to its extension selection (an array or `add`; an unset selection already inherits the parent's). */

package/dist/room.js

@@ -292,25 +292,38 @@ export function createRoomTurn(options) {
      * lands when the earlier run is done, so follow from the start and learn `from` the first time its entry exists.
      * Nothing is relayed before then, and never anything at or below the input's own entry (that is another wake's run).
      * Text is relayed as growth: per entry the text length and step count already sent are remembered, only the rest goes.
+     * The partial reply of the run in flight lives in the `pi.live` document, not in the entries: when that run is this
+     * wake's (its inputs hold our submission), its text grows through the same path under `live`, and the settled entry
+     * is seeded from it so nothing is sent twice.
      */
     async function follow(wakeId, known) {
         const watch = await conversation.watch(context);
         const sent = new Map();
         let from = known;
+        let submission;
+        let live = '';
         let queue = Promise.resolve();
         // Port calls are chained off the watch so a slow room never holds native frames.
         const relay = async (view) => {
             queue = queue.then(async () => {
-                if (from === undefined)
-                    from = (await conversation.commit(tx => tx.submissionByRequest(conversation.id, requestId(wakeId)), context))?.entry;
+                if (from === undefined || submission === undefined) {
+                    const record = await conversation.commit(tx => tx.submissionByRequest(conversation.id, requestId(wakeId)), context);
+                    submission = record?.id;
+                    from ??= record?.entry;
+                }
                 if (from === undefined)
                     return;
                 const own = view.entries.filter(entry => entry.id > from);
                 const frames = [];
                 for (const entry of own) {
-                    const before = sent.get(entry.id) ?? { text: 0, steps: 0 };
                     const all = framesOf([entry]);
                     const text = all.flatMap(frame => frame.type === 'text' ? [frame.text] : []).join('\n\n');
+                    // The first settled text of this run starts after what its live partial already sent.
+                    if (!sent.has(entry.id) && text) {
+                        sent.set(entry.id, { text: text.startsWith(live) ? live.length : 0, steps: 0 });
+                        live = '';
+                    }
+                    const before = sent.get(entry.id) ?? { text: 0, steps: 0 };
                     const steps = all.filter(frame => frame.type === 'step');
                     // Steps first: a tool call that began after the text belongs after it, but a lost order costs only polish.
                     frames.push(...steps.slice(before.steps));
@@ -318,6 +331,15 @@ export function createRoomTurn(options) {
                         frames.push({ type: 'text', text: text.slice(before.text) });
                     sent.set(entry.id, { text: Math.max(before.text, text.length), steps: Math.max(before.steps, steps.length) });
                 }
+                const partial = view.docs['pi.live'];
+                const message = partial?.generation?.message;
+                if (submission !== undefined && partial?.run?.inputs?.includes(submission) && message?.role === 'assistant') {
+                    const text = (message.content ?? []).flatMap(part => part.type === 'text' && part.text ? [part.text] : []).join('\n\n');
+                    if (text.length > live.length && text.startsWith(live)) {
+                        frames.push({ type: 'text', text: text.slice(live.length) });
+                        live = text;
+                    }
+                }
                 const questions = pendingQuestions(own);
                 if (frames.length && port.stream)
                     await port.stream(wakeId, frames);

package/dist/skills.d.ts

@@ -1,4 +1,6 @@
-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). */
 export declare const NAME: RegExp;
 /** Instructions the agent loads on demand: only name and description occupy the system prompt. */
@@ -11,6 +13,78 @@ export declare function skillInFolder(skill: Skill, folder: string): Skill;
 /** Parse a `SKILL.md`-style document: `---` front matter with `name` and `description`, then the body. */
 export declare function parseSkill(markdown: string): Skill;
 export declare function validSkill(skill: Skill): Skill;
-/** A prompt section listing the skills and a `load_skill` tool returning one body. Usable without `defineAgent`. */
-export declare function createSkillsExtension(name: string, skills: readonly Skill[]): Extension;
+/** A skill a live source left out, and why. `name` is the folder or file name when the skill itself could not be read. */
+export interface SkillError {
+    readonly path: string;
+    readonly name?: string;
+    readonly message: string;
+}
+/** What a source holds now: skills not yet validated, and the files it could not read. */
+export interface SkillListing {
+    readonly skills: readonly Skill[];
+    readonly errors: readonly SkillError[];
+}
+/**
+ * Skills that can change while the agent runs. `version()` is a cheap token that changes when the skills change; `list()`
+ * reads them. The built-in sources read through the workspace's Pi `FileSystem`; a host may write its own.
+ */
+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 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), 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

@@ -32,29 +32,311 @@ export function validSkill(skill) {
     const folder = skillFolders.get(skill);
     return folder === undefined ? valid : skillInFolder(valid, folder);
 }
-/** A prompt section listing the skills and a `load_skill` tool returning one body. Usable without `defineAgent`. */
-export function createSkillsExtension(name, skills) {
-    const known = new Map();
-    for (const skill of skills.map(validSkill)) {
-        if (known.has(skill.name))
-            throw new TypeError(`Duplicate skill: ${skill.name}`);
+const reason = (error) => error instanceof Error ? error.message : String(error);
+const parent = (path) => { const at = path.lastIndexOf('/'); return at < 0 ? '.' : path.slice(0, at); };
+const stamp = (info) => `${info.mtimeMs}:${info.size}`;
+/** The file a built-in source read each skill from, so a skill left out later is reported at its file. */
+const skillFiles = new WeakMap();
+async function readSkillFile(fs, path, name, context) {
+    const text = await fs.readTextFile(path, context);
+    if (!text.ok)
+        return { path, name, message: text.error.message };
+    try {
+        const skill = skillInFolder(parseSkill(text.value), parent(path));
+        skillFiles.set(skill, path);
+        return skill;
+    }
+    catch (error) {
+        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) {
+    const root = directory.replace(/\/+$/, '');
+    async function folders(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() };
+    }
+    const info = (name, context) => fs.fileInfo(`${root}/${name}/SKILL.md`, context);
+    return {
+        fs,
+        version: async (context) => {
+            const { names, error } = await folders(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}`;
+            }));
+            return stamps.join('|');
+        },
+        list: async (context) => {
+            const { names, error } = await folders(context);
+            const skills = [], errors = error ? [error] : [];
+            for (const name of names) {
+                const found = await info(name, context);
+                if (!found.ok && found.error.code === 'not_found')
+                    continue;
+                const read = await readSkillFile(fs, `${root}/${name}/SKILL.md`, name, context);
+                if ('body' in read)
+                    skills.push(read);
+                else
+                    errors.push(read);
+            }
+            return { skills, errors };
+        },
+    };
+}
+/** 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, '');
+    return {
+        fs,
+        version: async (context) => {
+            const found = await fs.fileInfo(path, context);
+            return found.ok ? stamp(found.value) : found.error.code;
+        },
+        list: async (context) => {
+            const read = await readSkillFile(fs, path, name, context);
+            if ('body' in read)
+                return { skills: [read], errors: [] };
+            const found = await fs.fileInfo(path, context);
+            return !found.ok && found.error.code === 'not_found' ? { skills: [], errors: [] } : { skills: [], errors: [read] };
+        },
+    };
+}
+/** Validate what a source returned with `validSkill` and the duplicate rule: what fails is left out and reported, never thrown. */
+function loaded(listing) {
+    const known = new Map(), errors = [...listing.errors];
+    for (const raw of listing.skills) {
+        const path = skillFiles.get(raw) ?? skillFolders.get(raw) ?? '';
+        let skill;
+        try {
+            skill = validSkill(raw);
+        }
+        catch (error) {
+            errors.push({ path, name: raw.name, message: reason(error) });
+            continue;
+        }
+        if (known.has(skill.name)) {
+            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);
     }
-    const listing = [...known.values()].map(skill => `- ${skill.name}: ${skill.description}`).join('\n');
+    return { known, errors };
+}
+/** `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, fs = options.companionFiles ? source.fs : undefined;
+    let state = { known: new Map(), errors: [] };
+    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) {
+            const listing = await read(context);
+            version = next;
+            await publish(listing);
+        }
+        checkedAt = Date.now();
+        return state;
+    }
+    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_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();
+/**
+ * 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.
+ */
+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('');
+    }
+    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: () => `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.\n${listing}` }],
+        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) => {
-                    const skill = known.get(args.name);
-                    const folder = skill && skillFolders.get(skill);
+                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 = 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 ? skill.body + location : `Unknown skill "${args.name}". Available: ${[...known.keys()].join(', ')}` }] };
+                    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.21",
+  "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.21",
-    "@hachej/boring-ui-kit": "^0.4.21",
+    "@hachej/boring-files": "^0.4.23",
+    "@hachej/boring-ui-kit": "^0.4.23",
     "xlsx": "^0.20.3"
   },
   "peerDependenciesMeta": {