@zenera/neo 1.1.15 → 1.1.17

package/README.md

@@ -16,7 +16,7 @@
 an append-only trajectory.**
 
 > Part of [ZeneraNeo](https://github.com/andreyryabov/ZeneraNeo). This is an
-> open-source side project for experimentation and chore work — **not** the
+> open-source side project for experimentation and chore work - **not** the
 > official Zenera AI Platform. It carries no support or stability promises.
 
 ## Install
@@ -41,7 +41,7 @@ or load them from a folder.
 ### In code
 
 An agent is an instruction, a model, some tools, and who it may hand work to.
-That is the whole list — there is no orchestration layer underneath.
+That is the whole list - there is no orchestration layer underneath.
 
 ```ts
 import { AgentRunner, createModel, tool } from '@zenera/neo';
@@ -72,7 +72,7 @@ console.log(result.output);
 ```
 
 `run()` returns a handle: `await` it for the answer, or iterate it for the
-stream — token deltas plus a checkpoint for every model call, tool call,
+stream - token deltas plus a checkpoint for every model call, tool call,
 handoff, fork and join.
 
 ```ts
@@ -88,7 +88,7 @@ them.
 
 ### From a folder
 
-An agentic project is a folder — prompts, agent wiring, skills and tool
+An agentic project is a folder - prompts, agent wiring, skills and tool
 selections are Markdown and YAML files, not code buried inside an application.
 Load one and run it:
 
@@ -127,29 +127,29 @@ agents:
 ```
 
 It is validated strictly at load: an unknown tool, a handoff to nobody, a
-missing prompt file — each fails immediately, naming the offending key, instead
+missing prompt file - each fails immediately, naming the offending key, instead
 of surfacing three turns into a run as a confused model.
 
 ## What it gives you
 
-- **Agents** — an instruction, a model, tools, skills, who it may hand the work
+- **Agents** - an instruction, a model, tools, skills, who it may hand the work
   to, and how it splits into parallel branches. There is no hidden orchestration
   layer.
-- **Models** — OpenAI, Anthropic, Google/Vertex and OpenRouter behind one
+- **Models** - OpenAI, Anthropic, Google/Vertex and OpenRouter behind one
   interface, each through its own SDK, plus any OpenAI-compatible endpoint.
   Named providers and model aliases resolve from config or from the host.
-- **Tools** — plain typed functions, selectable per agent by name, group or
+- **Tools** - plain typed functions, selectable per agent by name, group or
   wildcard. Workspace file tools and a Podman sandbox ship with the library.
-- **Skills** — instruction bundles discovered and loaded on demand instead of
+- **Skills** - instruction bundles discovered and loaded on demand instead of
   permanently occupying the prompt, optionally owning their own tools.
-- **Memory** — a timed, masked knowledge graph that outlives a run: recall
+- **Memory** - a timed, masked knowledge graph that outlives a run: recall
   returns a stitched subgraph rather than a ranked list, remembered files are
   mounted at `/memory`, and standing preferences go into the system prompt.
-- **Trajectory** — an append-only log of everything that happened. What is sent
+- **Trajectory** - an append-only log of everything that happened. What is sent
   to a provider is derived from it, and compaction _covers_ nodes rather than
   deleting them, so the full record survives even when older turns have to be
   pushed out of the context window.
-- **Inspection** — `renderReportHtml` turns any run into one self-contained HTML
+- **Inspection** - `renderReportHtml` turns any run into one self-contained HTML
   file: the graph, every request, every token.
 
 ## Entry points
@@ -174,14 +174,14 @@ folder.
 
 | Package                                                                                         | What it is                                                    |
 | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| [`@zenera/cli`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/cli/README.md)     | `zen` — this runtime on the command line, with a TUI          |
-| [`@zenera/faker`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/faker/README.md) | `zen faker` — a mock API from an openapi/swagger document     |
-| [`@zenera/rag`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/rag/README.md)     | `zen rag` — an API description as a searchable graph, + tools |
+| [`@zenera/cli`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/cli/README.md)     | `zen` - this runtime on the command line, with a TUI          |
+| [`@zenera/faker`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/faker/README.md) | `zen faker` - a mock API from an openapi/swagger document     |
+| [`@zenera/rag`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/rag/README.md)     | `zen rag` - an API description as a searchable graph, + tools |
 
 `@zenera/rag` also exports tools you can hand straight to `loadProject`, so an
 agent can search an API it has never read.
 
 ## License
 
-Early days and moving fast — issues, questions and pull requests are welcome.
+Early days and moving fast - issues, questions and pull requests are welcome.
 [MIT](LICENSE).

package/dist/embeddings/limiter.js

@@ -99,10 +99,12 @@ export class RateLimiter {
                 if (at >= 0) {
                     this.#waiting.splice(at, 1);
                 }
+                this.#hold();
                 reject(signal?.reason);
             };
             signal?.addEventListener('abort', abort, { once: true });
             this.#waiting.push(waiter);
+            this.#hold();
         });
     }
     #free() {
@@ -121,6 +123,7 @@ export class RateLimiter {
             this.#active++;
             this.#waiting.shift().grant(this.#epoch);
         }
+        this.#hold();
     }
     #succeeded() {
         this.#penalty = this.#initial;
@@ -168,7 +171,23 @@ export class RateLimiter {
             return;
         }
         this.#timer = setTimeout(() => this.#arm(), remaining);
-        this.#timer.unref?.();
+        this.#hold();
+    }
+    /**
+     * A parked task is a bare promise, which keeps nothing alive, and while the
+     * pause is in force this timer is the only thing that can ever wake it — so
+     * it has to hold the event loop open, or the last in-flight request settling
+     * empties the loop and Node exits 13 with the whole queue unsettled. With
+     * nobody waiting it must NOT hold it, or a run that ended on a refusal sits
+     * out the rest of the backoff before the process can exit.
+     */
+    #hold() {
+        if (this.#waiting.length > 0) {
+            this.#timer?.ref?.();
+        }
+        else {
+            this.#timer?.unref?.();
+        }
     }
 }
 const clamp = (n, low, high) => Math.min(high, Math.max(low, n));

package/dist/fork.d.ts

@@ -0,0 +1,24 @@
+import type { JsonSchema } from './types.ts';
+/**
+ * Deliberately not a function of the agent list or the branch cap: both are
+ * already on the tool schema, where the provider enforces them during decoding,
+ * and naming them twice buys nothing but two places to drift.
+ */
+export declare function forkInstructions(): string;
+/**
+ * Mechanics only — the policy above is in the system prompt of every agent that
+ * can call this, so repeating it here would cost tokens in two places at once.
+ */
+export declare const FORK_DESCRIPTION: string;
+/**
+ * Derived from the registry rather than a constant, because the one thing a
+ * weak model reliably gets wrong here is inventing an agent name. An `enum` of
+ * the agents that actually exist is a constraint the provider enforces during
+ * decoding, which no amount of prose in the description can match.
+ *
+ * `minItems`/`maxItems` are stated too, but they are advisory — most providers
+ * ignore them under strict decoding — so `parseForkArgs` and `forkProblem`
+ * still check both, and their messages are written to be read by the model.
+ */
+export declare function forkParameters(agents: string[], self: string, maxBranches?: number): JsonSchema;
+//# sourceMappingURL=fork.d.ts.map

package/dist/fork.js

@@ -0,0 +1,137 @@
+// ---------------------------------------------------------------------------
+// Teaching the model to fan out and to delegate
+//
+// The tool schema says what the arguments are; none of it says what survives a
+// join, that a branch cannot be corrected once it starts, or which `context`
+// mode fits which shape of work. That is policy, it is the same for every
+// agent, and it belongs in the system prompt — the only place it can be stated
+// once per run instead of once per call.
+//
+// It goes in through `composePrompt`'s `derived` array, so it sits in the
+// cacheable prefix and is recorded on the `system_prompt` node like every other
+// part of what the model read. The text is gated on the agent holding a fork
+// binding *and* being below the depth cap — the same condition that decides
+// whether the tool is offered at all, because a rule about a tool the model
+// does not have is a rule it can only be confused by.
+// ---------------------------------------------------------------------------
+/**
+ * Deliberately not a function of the agent list or the branch cap: both are
+ * already on the tool schema, where the provider enforces them during decoding,
+ * and naming them twice buys nothing but two places to drift.
+ */
+export function forkInstructions() {
+    return FORKING;
+}
+const FORKING = `Forking runs work in separate conversations and brings back only the answers.
+
+A branch is a run of its own: its own conversation, its own tool calls, its own
+reasoning. None of that returns. What returns is each branch's final answer, as
+the result of your \`fork\` call — so whatever you will need afterwards has to be
+*in* that answer, and the branch only knows it if your instructions say so. Work
+whose value is the trace rather than the conclusion should not be forked at all.
+
+The instructions you write are the entire assignment. A branch cannot ask you a
+question, cannot see what its siblings are doing, and cannot be corrected once
+it starts. Say what it must do, what it must leave alone, and the exact shape of
+what it must hand back.
+
+**One branch is delegation**: the work happens elsewhere and you get the
+conclusion instead of the transcript. Use it when another agent is better suited
+to the job, or when the job would otherwise fill this conversation with material
+you have no use for afterwards — a long file survey, a noisy build loop, an
+exploration down a path that may go nowhere. **Several branches are a fan-out**:
+independent parts of one task, worked at the same time, merged by you. It is the
+same call either way; the number of branches is the only difference.
+
+Do not fork a sequence. Branches run at once and can exchange nothing, so a step
+that needs the step before it has to stay in this conversation.
+
+\`context\` decides what each branch starts from, and you choose it per call:
+- \`inherit\` — everything said here so far. For work that only makes sense
+  against the case as it stands.
+- \`compact\` — the same, without the tool traffic: what was decided, not how it
+  was found out. The usual choice for a wide fan-out.
+- \`none\` — nothing but its own instructions. The cheapest, and the honest one
+  when the assignment is self-contained.
+
+A branch can fail, or answer badly. Its row says which, and what the final
+answer is remains your decision, not the join's.`;
+/**
+ * Mechanics only — the policy above is in the system prompt of every agent that
+ * can call this, so repeating it here would cost tokens in two places at once.
+ */
+export const FORK_DESCRIPTION = [
+    'Run work in separate conversations and get back only the answers.',
+    '',
+    'Each branch needs a unique name and complete, self-contained instructions: it runs on ' +
+        'its own, cannot ask questions, and cannot see the other branches. One branch delegates ' +
+        'a job; several run in parallel and rejoin together.',
+    '',
+    'The branches\u2019 answers come back as the result of this call, and what the final answer ' +
+        'is remains yours to decide.',
+].join('\n');
+/**
+ * Derived from the registry rather than a constant, because the one thing a
+ * weak model reliably gets wrong here is inventing an agent name. An `enum` of
+ * the agents that actually exist is a constraint the provider enforces during
+ * decoding, which no amount of prose in the description can match.
+ *
+ * `minItems`/`maxItems` are stated too, but they are advisory — most providers
+ * ignore them under strict decoding — so `parseForkArgs` and `forkProblem`
+ * still check both, and their messages are written to be read by the model.
+ */
+export function forkParameters(agents, self, maxBranches) {
+    const max = maxBranches ?? 0;
+    // When the author's list excludes the current agent there is no sane
+    // default, so the model has to name one.
+    const selfAllowed = agents.includes(self);
+    return {
+        type: 'object',
+        properties: {
+            branches: {
+                type: 'array',
+                minItems: 1,
+                ...(max >= 1 ? { maxItems: max } : {}),
+                description: `One branch per job that can be carried out on its own${max >= 1 ? `, at most ${max}` : ''}. ` +
+                    'One delegates that job elsewhere; several work independent parts of the ' +
+                    'task at the same time.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        name: {
+                            type: 'string',
+                            description: 'Short, unique label for this branch, e.g. "eu-tariffs".',
+                        },
+                        instructions: {
+                            type: 'string',
+                            description: 'The complete assignment for this branch. It runs in a separate ' +
+                                'conversation and cannot ask questions, so state everything it ' +
+                                'needs and exactly what it must return.',
+                        },
+                        agent: {
+                            type: 'string',
+                            enum: agents,
+                            description: 'Which agent runs this branch. Must be one of: ' +
+                                agents.join(', ') +
+                                (selfAllowed ? `. Omit to use "${self}".` : '.'),
+                        },
+                    },
+                    required: selfAllowed
+                        ? ['name', 'instructions']
+                        : ['name', 'instructions', 'agent'],
+                    additionalProperties: false,
+                },
+            },
+            context: {
+                type: 'string',
+                enum: ['inherit', 'compact', 'none'],
+                description: 'How much of this conversation each branch starts with: "inherit" (all of ' +
+                    'it, the default), "compact" (messages only, no tool traffic), "none" ' +
+                    '(nothing but its own instructions).',
+            },
+        },
+        required: ['branches'],
+        additionalProperties: false,
+    };
+}
+//# sourceMappingURL=fork.js.map

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './embedding.ts';
 export * from './embeddings/index.ts';
 export * from './events.ts';
 export * from './failure.ts';
+export * from './fork.ts';
 export * from './ids.ts';
 export * from './inspect/index.ts';
 export * as Kernel from './kernel.ts';

package/dist/index.js

@@ -4,6 +4,7 @@ export * from "./embedding.js";
 export * from "./embeddings/index.js";
 export * from "./events.js";
 export * from "./failure.js";
+export * from "./fork.js";
 export * from "./ids.js";
 export * from "./inspect/index.js";
 export * as Kernel from "./kernel.js";

package/dist/kernel.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { Agent, AgentRegistry, handoffTarget, handoffTool } from "./agent.js";
+import { FORK_DESCRIPTION, forkInstructions, forkParameters } from "./fork.js";
 import { systemClock } from "./ids.js";
 import { memoryInstructions, renderPreferences } from "./memory/instructions.js";
 import { memoryTools } from "./memory/tools.js";
@@ -193,82 +194,10 @@ function forkAgents(state, reg) {
     const known = allowed.filter((n) => reg.find(n));
     return known.length ? known : [state.agentName];
 }
-/**
- * Derived from the state rather than a constant, because the one thing a weak
- * model reliably gets wrong here is inventing an agent name. An `enum` of the
- * agents that actually exist is a constraint the provider enforces during
- * decoding, which no amount of prose in the description can match.
- *
- * `minItems`/`maxItems` are stated too, but they are advisory — most providers
- * ignore them under strict decoding — so `parseForkArgs` and `forkProblem`
- * still check both, and their messages are written to be read by the model.
- */
-function forkParameters(agents, self, maxBranches) {
-    const max = maxBranches ?? 0;
-    // When the author's list excludes the current agent there is no sane
-    // default, so the model has to name one.
-    const selfAllowed = agents.includes(self);
-    return {
-        type: 'object',
-        properties: {
-            branches: {
-                type: 'array',
-                minItems: 2,
-                ...(max >= 2 ? { maxItems: max } : {}),
-                description: `At least two branches${max >= 2 ? `, at most ${max}` : ''}. ` +
-                    'One branch is never valid: if the work does not split, do it yourself ' +
-                    'instead of calling this tool.',
-                items: {
-                    type: 'object',
-                    properties: {
-                        name: {
-                            type: 'string',
-                            description: 'Short, unique label for this branch, e.g. "eu-tariffs".',
-                        },
-                        instructions: {
-                            type: 'string',
-                            description: 'The complete assignment for this branch. It runs in a separate ' +
-                                'conversation and cannot ask questions, so state everything it ' +
-                                'needs and exactly what it must return.',
-                        },
-                        agent: {
-                            type: 'string',
-                            enum: agents,
-                            description: 'Which agent runs this branch. Must be one of: ' +
-                                agents.join(', ') +
-                                (selfAllowed ? `. Omit to use "${self}".` : '.'),
-                        },
-                    },
-                    required: selfAllowed
-                        ? ['name', 'instructions']
-                        : ['name', 'instructions', 'agent'],
-                    additionalProperties: false,
-                },
-            },
-            context: {
-                type: 'string',
-                enum: ['inherit', 'compact', 'none'],
-                description: 'How much of this conversation each branch starts with: "inherit" (all of ' +
-                    'it, the default), "compact" (messages only, no tool traffic), "none" ' +
-                    '(nothing but its own instructions).',
-            },
-        },
-        required: ['branches'],
-        additionalProperties: false,
-    };
+/** One condition for the tool and for the prompt block that explains it. */
+function canFork(agent, state) {
+    return Boolean(agent.fork) && state.spec.forkDepth < state.spec.maxForkDepth;
 }
-const FORK_DESCRIPTION = [
-    'Split the work into independent branches that run in parallel and rejoin into one result.',
-    '',
-    'Call it when two or more parts of the task can be worked on without seeing each ' +
-        "other's findings — separate documents, regions, candidates, hypotheses. Do not call it " +
-        'to break one line of reasoning into steps: branches cannot talk to each other, and a ' +
-        "step that needs the previous step's answer must stay in this conversation.",
-    '',
-    'Every call needs at least two branches, each with a unique name and self-contained ' +
-        'instructions. Their answers come back to you as the result of this call, and you ' +
-        'decide what the final answer is.',
-].join('\n');
 /**
  * tools(state) = agent tools + handoffs + memory + skills + fork +
  * final_output. Computed from the state so a rehydrated run offers exactly the
@@ -298,11 +227,11 @@ export async function resolveTools(state, reg, env) {
         const own = new Set(agent.tools.map((t) => t.name));
         tools.push(...(await lockedSkillTools(binding, provider, own)));
     }
-    if (agent.fork && state.spec.forkDepth < state.spec.maxForkDepth) {
+    if (canFork(agent, state)) {
         tools.push({
             name: FORK_TOOL,
             description: FORK_DESCRIPTION,
-            parameters: forkParameters(forkAgents(state, reg), state.agentName, agent.fork.maxBranches),
+            parameters: forkParameters(forkAgents(state, reg), state.agentName, agent.fork?.maxBranches),
             // Never executed as a tool: the runner drives branches and the join
             // becomes the tool result.
             execute: () => 'fork scheduled',
@@ -355,6 +284,9 @@ async function derivedPrompt(agent, state, env) {
             out.push(rendered);
         }
     }
+    if (canFork(agent, state)) {
+        out.push(forkInstructions());
+    }
     if (state.spec.outputSchema) {
         out.push(FINAL_OUTPUT_INSTRUCTIONS);
     }
@@ -444,12 +376,7 @@ function parseForkArgs(raw) {
     // the model as the tool result, and it is the only chance it gets to work
     // out what to do differently.
     if (!Array.isArray(branches) || branches.length === 0) {
-        return 'the "branches" argument is missing or empty; it must be an array of at least two branches';
-    }
-    if (branches.length < 2) {
-        return ('a fork needs at least two branches, and this call has one. Either add the other ' +
-            'independent branches, or do not fork at all and carry out the work in this ' +
-            'conversation.');
+        return 'the "branches" argument is missing or empty; it must be an array of at least one branch';
     }
     const parsed = [];
     for (const b of branches) {
@@ -847,6 +774,9 @@ export async function createChildState(state, forkId, branch, env) {
  * what happens to what it produces, exist nowhere else. Without them a branch
  * re-derives work a sibling already owns and writes an answer shaped for a user
  * rather than for a merge.
+ *
+ * A lone branch has no siblings to be told about, and the thing it does need to
+ * know is the opposite one: nobody else is working on any of this.
  */
 function branchBrief(fork, plan, instructions) {
     const siblings = fork.branches.filter((b) => b.name !== plan.name).map((b) => `"${b.name}"`);
@@ -855,11 +785,16 @@ function branchBrief(fork, plan, instructions) {
         '',
         instructions,
         '',
-        `Running in parallel, on the assignments the call above gave them: ${siblings.join(', ')}. ` +
-            'You cannot see their work and they cannot see yours, so anything you do on their ' +
-            'part is duplicated effort, and anything you leave to them will be there. This branch ' +
-            'ends with your final answer; that answer alone rejoins the conversation above, ' +
-            'merged with theirs.',
+        siblings.length
+            ? `Running in parallel, on the assignments the call above gave them: ${siblings.join(', ')}. ` +
+                'You cannot see their work and they cannot see yours, so anything you do on their ' +
+                'part is duplicated effort, and anything you leave to them will be there. This branch ' +
+                'ends with your final answer; that answer alone rejoins the conversation above, ' +
+                'merged with theirs.'
+            : 'No other branch was opened, so the whole assignment is yours and nothing you ' +
+                'leave undone will be picked up elsewhere. This branch ends with your final ' +
+                'answer; that answer alone rejoins the conversation above, and none of the steps ' +
+                'you take to reach it go with it.',
     ].join('\n');
 }
 /** The parent history a branch starts from, as decided by `contextMode`. */

package/dist/project/config.js

@@ -157,15 +157,17 @@ const skillsBinding = z
  * `fork:` is never offered the tool.
  *
  * Both limits are stated as errors rather than as values that get clamped
- * later: `maxBranches: 1` would make every call the model could write fail, and
+ * later: `maxBranches: 0` would make every call the model could write fail, and
  * `agents: []` reads as "no agents" while actually meaning "only itself".
+ * `maxBranches: 1` is not a contradiction — it says this agent may delegate a
+ * job but may not fan out.
  */
 const forkBinding = z
     .object({
     /** agents a branch may run; absent means any registered agent */
     agents: z.array(name).min(1).optional(),
-    /** a fork is never valid with one branch, so a cap below two is a contradiction */
-    maxBranches: z.int().min(2).optional(),
+    /** a cap of 1 allows delegation only; 0 would refuse every possible call */
+    maxBranches: z.int().min(1).optional(),
 })
     .strict();
 /**

package/dist/project/load.d.ts

@@ -4,7 +4,7 @@ import { RunStream } from '../events.ts';
 import { MemoryIndex } from '../memory/index.ts';
 import { ModelRegistry, type EmbeddingRef, type ModelRef, type ProviderSpec } from '../models/factory.ts';
 import type { PayloadStore } from '../payload.ts';
-import { AgentRunner, type RunOptions, type RunnerOptions } from '../runner.ts';
+import { AgentRunner, type RunnerOptions, type RunOptions } from '../runner.ts';
 import { type SkillDir } from '../skill-providers/file.ts';
 import type { SkillProvider } from '../skills.ts';
 import { type AnyTool, type Input } from '../types.ts';
@@ -13,8 +13,9 @@ import { type ProjectConfig } from './config.ts';
  * A folder is an agentic system:
  *
  * ```
- * INSTRUCTIONS.md               house rules, prepended to every agent
  * agents.yaml                   who exists, what they may reach for
+ * agents/instructions.md        house rules, prepended to every agent
+ * agents/<topic>-instructions.md   more of them, added as the project grows
  * agents/prompts/<role>.md      one agent's own instructions
  * agents/skills/<name>/SKILL.md
  * assets/                       reference material, mounted read-only at /assets

package/dist/project/load.js

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync, statSync } from 'node:fs';
-import { basename, join } from 'node:path';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, join, relative, sep } from 'node:path';
 import { Agent, AgentRegistry } from "../agent.js";
 import { RunStream } from "../events.js";
 import { MemoryIndex } from "../memory/index.js";
@@ -11,6 +11,7 @@ import { FileSkillProvider } from "../skill-providers/file.js";
 import { selectTools } from "../types.js";
 import { parseConfig } from "./config.js";
 import { projectDir, projectFile, projectRoot } from "./refs.js";
+const AGENTS_DIR = 'agents';
 const PROMPTS_DIR = 'agents/prompts';
 const SKILLS_DIR = 'agents/skills';
 /** Reference material, by convention, when `assets:` says nothing. */
@@ -19,7 +20,11 @@ const CONFIG_NAMES = ['agents.yaml', 'agents.yml', 'agents/agents.yaml', 'agents
 // Deliberately not `AGENTS.md`: every coding assistant now reads that name out
 // of an open folder, and `zen open` opens exactly this directory. The house
 // rules here address *this project's* agents, not the editor's.
-const HOUSE_RULES = 'INSTRUCTIONS.md';
+const HOUSE_RULES = 'agents/instructions.md';
+/** Every other `agents/<topic>-instructions.md`, in filename order. */
+const INSTRUCTIONS_SUFFIX = '-instructions.md';
+/** Where the house rules used to live. Still read, so an old project still runs. */
+const LEGACY_HOUSE_RULES = 'INSTRUCTIONS.md';
 /**
  * Finds and validates `agents.yaml`, and stops there. Loading a project builds
  * its model clients, which needs credentials — so anything that wants to *look*
@@ -39,8 +44,8 @@ export function readProjectConfig(dir) {
  */
 export async function loadProject(dir, opts = {}) {
     const { root, source, config } = readProjectConfig(dir);
-    // Read once and share the object: every agent's prompt then reports the
-    // same path and the same content hash, so the report says "one document,
+    // Read once and share the objects: every agent's prompt then reports the
+    // same paths and the same content hashes, so the report says "one document,
     // five prompts" instead of showing five identical blobs.
     const houseRules = readHouseRules(root);
     const providers = [...skillProviders(root, config, opts), ...(opts.skills ?? [])];
@@ -184,30 +189,63 @@ function findConfig(root) {
     }
     throw new Error(`no project configuration in ${root} (looked for ${CONFIG_NAMES.join(', ')})`);
 }
+/** The project-relative name of a file, which is the name the model is given. */
+function within(root, path) {
+    return relative(root, path).split(sep).join('/');
+}
+/**
+ * Every house-rules document, in the order they are prepended.
+ *
+ * The set is a glob rather than a list in `agents.yaml` because these are read
+ * by every agent without exception — there is nothing to decide, so there is
+ * nothing to declare. Order is the filename's, which is the only ordering that
+ * is the same on every machine and is visible without opening another file.
+ *
+ * All of it is optional: a one-agent project whose whole prompt is its role
+ * file should not need a second, empty document.
+ */
 function readHouseRules(root) {
-    const path = join(root, HOUSE_RULES);
-    // Optional on purpose: a one-agent project whose whole prompt is its role
-    // file should not need a second, empty document.
-    return existsSync(path) ? promptFile(path, 'house_rules') : undefined;
+    const rules = [];
+    const take = (rel) => {
+        const path = join(root, rel);
+        if (existsSync(path)) {
+            rules.push(promptFile(path, 'house_rules', rel));
+        }
+    };
+    // First, because it is the oldest and most general thing the project says:
+    // anything added under `agents/` during a migration layers on top of it.
+    take(LEGACY_HOUSE_RULES);
+    take(HOUSE_RULES);
+    for (const name of topics(root)) {
+        take(`${AGENTS_DIR}/${name}`);
+    }
+    return rules;
+}
+/** `agents/<topic>-instructions.md`, sorted. Subdirectories are not searched. */
+function topics(root) {
+    const dir = join(root, AGENTS_DIR);
+    if (!existsSync(dir)) {
+        return [];
+    }
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(INSTRUCTIONS_SUFFIX))
+        .map((entry) => entry.name)
+        .sort((a, b) => a.localeCompare(b));
 }
 /**
- * `INSTRUCTIONS.md` first, the agent's own file second — shared context before
+ * The house rules first, the agent's own file second — shared context before
  * the specific job, and the stable half of the prompt in front where a cache
  * can reuse it.
  */
 function instructionsFor(root, spec, houseRules) {
-    const parts = [];
-    if (houseRules) {
-        parts.push(houseRules);
-    }
-    if (spec.system) {
-        parts.push(promptFile(projectFile(root, spec.system, `agents.${spec.name}.system`), 'role'));
-    }
-    else {
-        const conventional = join(root, PROMPTS_DIR, `${spec.name}.md`);
-        if (existsSync(conventional)) {
-            parts.push(promptFile(conventional, 'role'));
-        }
+    const parts = [...houseRules];
+    const role = spec.system
+        ? projectFile(root, spec.system, `agents.${spec.name}.system`)
+        : join(root, PROMPTS_DIR, `${spec.name}.md`);
+    // A named prompt that is missing is `projectFile`'s to refuse; a
+    // conventional one that is missing is simply an agent without a role file.
+    if (spec.system || existsSync(role)) {
+        parts.push(promptFile(role, 'role', within(root, role)));
     }
     return parts;
 }

package/dist/prompt.d.ts

@@ -13,6 +13,13 @@ export interface PromptText {
     path?: string;
     /** opt-in wrapper tag, e.g. `intent` → `<intent>…</intent>` */
     section?: string;
+    /**
+     * The name of that document *as the model is told it*, written onto the
+     * wrapper tag as `src`. Deliberately not `path`: that one is absolute, so
+     * it would put a home directory in the prompt and give two machines two
+     * different cache prefixes for the same project.
+     */
+    src?: string;
 }
 /**
  * One contributor to a system prompt: literal text, text computed from the run
@@ -39,7 +46,7 @@ export type Instructions<TCtx = unknown> = string | ((ctx: TCtx, spec: RunSpec)
  * A prompt that must change without a restart is a different feature: rebuild
  * the agent, or use the function form.
  */
-export declare function promptFile(path: string, section?: string): PromptText;
+export declare function promptFile(path: string, section?: string, src?: string): PromptText;
 /** A document that fed a prompt, with the exact bytes it contributed. */
 export interface PromptSource {
     path: string;

package/dist/prompt.js

@@ -11,17 +11,34 @@ import { readFileSync } from 'node:fs';
  * A prompt that must change without a restart is a different feature: rebuild
  * the agent, or use the function form.
  */
-export function promptFile(path, section) {
+export function promptFile(path, section, src) {
     const text = readFileSync(path, 'utf8');
-    return section === undefined ? { text, path } : { text, path, section };
+    return {
+        text,
+        path,
+        ...(section === undefined ? {} : { section }),
+        ...(src === undefined ? {} : { src }),
+    };
 }
 const SEPARATOR = '\n\n';
+/** `&`, `<` and `"` are the three that would end the attribute or the tag. */
+function attribute(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/"/g, '&quot;');
+}
 /**
  * Markers are opt-in because they are tokens the model reads: a wrapper that
  * "does not influence the content" does not exist for an LLM.
+ *
+ * `src` rides on the marker rather than being a line of prose above it for the
+ * same reason the marker exists at all — it is structure, and a model that can
+ * see where a block ends can see where it came from.
  */
 function wrap(part) {
-    return part.section ? `<${part.section}>\n${part.text}\n</${part.section}>` : part.text;
+    if (!part.section) {
+        return part.text;
+    }
+    const src = part.src ? ` src="${attribute(part.src)}"` : '';
+    return `<${part.section}${src}>\n${part.text}\n</${part.section}>`;
 }
 /**
  * Renders the authored parts, then the kernel's derived text, into one string —

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/neo",
-    "version": "1.1.15",
+    "version": "1.1.17",
     "description": "A multi-agent runtime for Node.js: agents, models, tools, skills, memory and an append-only trajectory.",
     "keywords": [
         "agents",