@hachej/boring-agent 0.4.4 → 0.4.5

package/README.md

@@ -305,6 +305,8 @@ Each evidence entry must link to a completed native ToolTask, its original assis
 
 `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.
 
+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.
+
 ## 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.
@@ -323,7 +325,7 @@ These follow [Pi Durable on Cloudflare](https://earendil.com/posts/pi-durable-on
 
 `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` 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` 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.
 - `.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/self-evolving.js

@@ -1,5 +1,6 @@
 import { defineExtension, defineTool } from '@earendil-works/pi-durable';
 import { Type } from '@earendil-works/pi-ai';
+import { skillInFolder } from './skills.js';
 import { jsonSchemaTool } from './json-schema-tool.js';
 /*
  * Self-evolution (docs/architecture/SELF-EVOLUTION.md, laws SELF-1..4 in this package's README): an agent keeps its own standing
@@ -102,6 +103,27 @@ async function filesIn(env, directory, suffix, context) {
         return listed.error.code === 'not_found' ? 'missing' : { error: listed.error.message };
     return listed.value.filter(entry => entry.kind === 'file' && entry.name.endsWith(suffix)).map(entry => `${directory}/${entry.name}`).sort();
 }
+/** Flat Markdown skills and `SKILL.md` in immediate child folders; companion files are not definitions. */
+async function skillFilesIn(env, context, errors) {
+    const listed = await env.listDir(SKILLS, context);
+    if (!listed.ok) {
+        if (listed.error.code !== 'not_found')
+            errors.push({ path: SKILLS, message: listed.error.message });
+        return [];
+    }
+    const paths = listed.value.filter(entry => entry.kind === 'file' && entry.name.endsWith('.md')).map(entry => `${SKILLS}/${entry.name}`);
+    for (const entry of listed.value.filter(entry => entry.kind === 'directory')) {
+        const folder = `${SKILLS}/${entry.name}`;
+        const contents = await env.listDir(folder, context);
+        if (!contents.ok) {
+            errors.push({ path: folder, message: contents.error.message });
+            continue;
+        }
+        if (contents.value.some(file => file.kind === 'file' && file.name === 'SKILL.md'))
+            paths.push(`${folder}/SKILL.md`);
+    }
+    return paths.sort();
+}
 export function createSelfEvolution(options) {
     const { name, parseSkill, skillsExtension } = options;
     const hostSkills = [...options.skills];
@@ -113,7 +135,7 @@ export function createSelfEvolution(options) {
         name: 'reload',
         description: `Apply the changes you made to your own ${AGENT_FOLDER}/ folder in the workspace, then return what was added, changed and removed and every load error. `
             + `${INSTRUCTIONS}: standing instructions for yourself, shown after the host's instructions on every request. `
-            + `${SKILLS}/<name>.md: skills (front matter with name and description between --- lines, then the instructions), loaded with load_skill. `
+            + `${SKILLS}/<name>.md or ${SKILLS}/<name>/SKILL.md: skills (front matter with name and description between --- lines, then the instructions), loaded with load_skill; paths in a skill are relative to its folder and read with read. `
             + `${TOOLS}/<name>.json: your own tools, {"name": "snake_case", "description": "...", "parameters": {a JSON Schema with "type": "object"}, "run": "a command run in the workspace, for example sh ${TOOLS}/<name>.sh"}; `
             + 'the arguments arrive as one line of JSON on standard input and the command output is the result. Restore or delete the files and reload to undo a change.',
         parameters: Type.Object({}, { additionalProperties: false }),
@@ -147,10 +169,8 @@ export function createSelfEvolution(options) {
         else if (read.error.code !== 'not_found')
             errors.push({ path: INSTRUCTIONS, message: read.error.message });
         const skills = [];
-        const skillFiles = await filesIn(env, SKILLS, '.md', context);
-        if (typeof skillFiles === 'object' && !Array.isArray(skillFiles))
-            errors.push({ path: SKILLS, message: skillFiles.error });
-        for (const path of Array.isArray(skillFiles) ? skillFiles : []) {
+        const skillFiles = await skillFilesIn(env, context, errors);
+        for (const path of skillFiles) {
             const text = await env.readTextFile(path, context);
             if (!text.ok) {
                 errors.push({ path, message: text.error.message });
@@ -168,7 +188,7 @@ export function createSelfEvolution(options) {
                 errors.push({ path, message: `a skill named ${skill.name} already exists` });
                 continue;
             }
-            skills.push(skill);
+            skills.push(skillInFolder(skill, path.slice(0, path.lastIndexOf('/'))));
         }
         const available = typeof env.exec === 'function';
         const tools = [];

package/dist/skills.d.ts

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

package/dist/skills.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-agent",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -154,8 +154,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.4",
-    "@hachej/boring-ui-kit": "^0.4.4"
+    "@hachej/boring-files": "^0.4.5",
+    "@hachej/boring-ui-kit": "^0.4.5"
   },
   "peerDependenciesMeta": {
     "@hachej/boring-files": {