@zenera/neo 1.1.16 → 1.1.18

package/README.md

@@ -166,7 +166,7 @@ of surfacing three turns into a run as a confused model.
 [docs/projects.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/projects.md) ·
 [docs/agents-yaml.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/agents-yaml.md)
 · and
-[`examples/`](https://github.com/andreyryabov/ZeneraNeo/tree/main/examples) for
+[`examples/sdk/`](https://github.com/andreyryabov/ZeneraNeo/tree/main/examples/sdk) for
 eight worked demos, from a single agent to a project loaded entirely from a
 folder.
 

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/memory/store.js

@@ -51,7 +51,7 @@ export class MemoryStore {
             const b = opts.embedding;
             if (a.model !== b.model || a.dimensions !== b.dimensions) {
                 throw new MemoryError(`this memory was embedded with ${a.model} (${a.dimensions}d), ` +
-                    `but ${b.model} (${b.dimensions}d) is configured`, 're-embed it with `zen memory reembed`, or restore the original model');
+                    `but ${b.model} (${b.dimensions}d) is configured`, 'restore the original model, or start a new memory');
             }
         }
         const graph = manifest
@@ -79,7 +79,7 @@ export class MemoryStore {
         if (held) {
             if (held.model !== embedding.model || held.dimensions !== embedding.dimensions) {
                 throw new MemoryError(`this memory was embedded with ${held.model} (${held.dimensions}d), ` +
-                    `but ${embedding.model} (${embedding.dimensions}d) is configured`, 're-embed it with `zen memory reembed`, or restore the original model');
+                    `but ${embedding.model} (${embedding.dimensions}d) is configured`, 'restore the original model, or start a new memory');
             }
             return;
         }

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
@@ -55,6 +56,13 @@ export interface ProjectOptions<TCtx = unknown> {
      */
     registry?: ModelRegistry;
     memory?: MemoryIndex;
+    /**
+     * Another directory to keep the memory graph in, relative to the project
+     * root when it is not absolute. Whoever sets it must mount that directory
+     * as `/memory` too, or the agent reads its remembered files from one graph
+     * and writes to another.
+     */
+    memoryDir?: string;
     /** turns an agent-visible path into a host path, so files can be remembered */
     resolveFile?: (path: string) => string;
     payloads?: PayloadStore;
@@ -165,8 +173,13 @@ export declare function projectRegistry<TCtx>(config: ProjectConfig, opts?: Proj
  * with the front end, which has to mount the same directory into the sandbox:
  * two answers to this question would mean `/memory` pointing somewhere the
  * graph is not.
+ *
+ * `override` is the host pointing the run at another graph — `zen run
+ * --memory`. It answers for a project that declares no memory at all, because
+ * naming a directory is the declaration; the agents bound to it are still the
+ * ones that said `memory: true`.
  */
-export declare function memoryDir(root: string, config: ProjectConfig): string | undefined;
+export declare function memoryDir(root: string, config: ProjectConfig, override?: string): string | undefined;
 /**
  * Where each skill directory appears in the agent's namespace.
  *

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, resolve, 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 ?? [])];
@@ -69,7 +74,7 @@ export async function loadProject(dir, opts = {}) {
     // The default is resolved here rather than on first use, so a broken
     // `embedding:` fails at load like a broken `model:` does.
     embedders(config.embedding, 'embedding');
-    const memory = opts.memory ?? (await openMemory(root, config, embedders));
+    const memory = opts.memory ?? (await openMemory(root, config, embedders, opts.memoryDir));
     return new AgentProject({
         root,
         source,
@@ -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;
 }
@@ -354,8 +392,16 @@ function memoryFor(spec) {
  * with the front end, which has to mount the same directory into the sandbox:
  * two answers to this question would mean `/memory` pointing somewhere the
  * graph is not.
+ *
+ * `override` is the host pointing the run at another graph — `zen run
+ * --memory`. It answers for a project that declares no memory at all, because
+ * naming a directory is the declaration; the agents bound to it are still the
+ * ones that said `memory: true`.
  */
-export function memoryDir(root, config) {
+export function memoryDir(root, config, override) {
+    if (override) {
+        return resolve(root, override);
+    }
     if (!config.memory && !config.agents.some((a) => a.memory)) {
         return undefined;
     }
@@ -367,8 +413,8 @@ export function memoryDir(root, config) {
  * to it still counts: it is how a project declares the graph `zen memory`
  * inspects between runs.
  */
-async function openMemory(root, config, embedders) {
-    const dir = memoryDir(root, config);
+async function openMemory(root, config, embedders, override) {
+    const dir = memoryDir(root, config, override);
     if (!dir) {
         return undefined;
     }

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;
@@ -51,6 +58,8 @@ export interface ComposedPrompt {
     /** the editable contributors, in the order they were rendered */
     sources: PromptSource[];
 }
+/** `&`, `<` and `"` are the three that would end the attribute or the tag. */
+export declare function attribute(value: string): string;
 /**
  * Renders the authored parts, then the kernel's derived text, into one string —
  * and reports which documents went into it.

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. */
+export 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/dist/skill-providers/file.js

@@ -1,5 +1,5 @@
 import { readFile, readdir } from 'node:fs/promises';
-import { basename, join, resolve } from 'node:path';
+import { basename, join, relative, resolve } from 'node:path';
 import { selectTools } from "../types.js";
 // ---------------------------------------------------------------------------
 // Filesystem-backed skill provider
@@ -83,6 +83,7 @@ export class FileSkillProvider {
             ...entry.summary,
             content: entry.content,
             file: entry.file,
+            src: entry.src,
             ...(tools.length ? { tools } : {}),
             ...(entry.at ? { path: entry.at } : {}),
         };
@@ -122,19 +123,20 @@ export class FileSkillProvider {
                 // Only a folder skill has files of its own to point at, and
                 // only when the host said where the directory can be reached.
                 const at = folder && dir.at ? `${dir.at}/${basename(folder)}` : undefined;
-                const entry = parse(raw, base, file, folder, at);
+                const entry = parse(raw, base, file, relative(dir.path, file), folder, at);
                 index.set(entry.summary.name, entry);
             }
         }
         return index;
     }
 }
-function parse(raw, base, file, folder, at) {
+function parse(raw, base, file, src, folder, at) {
     const { data, body } = frontmatter(raw);
     const tags = toList(data.tags);
     const tools = toList(data.tools);
     return {
         file,
+        src,
         folder,
         ...(at ? { at } : {}),
         content: body,

package/dist/skills.d.ts

@@ -33,6 +33,13 @@ export interface Skill extends SkillSummary {
     path?: string;
     /** absolute path of the source file, if known (set by file-backed providers) */
     file?: string;
+    /**
+     * The source document *as the model is told it*, written onto the block as
+     * `src`. Deliberately not `file`: 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 catalog.
+     */
+    src?: string;
 }
 export interface SkillProvider {
     readonly id: string;

package/dist/skills.js

@@ -1,4 +1,5 @@
 import { hash } from "./payload.js";
+import { attribute } from "./prompt.js";
 import { projected } from "./trajectory.js";
 import { SKILL_LOAD_TOOL, SKILL_SEARCH_TOOL, tool, withEffects, } from "./types.js";
 export function skillContentHash(s) {
@@ -7,15 +8,21 @@ export function skillContentHash(s) {
 export function renderSkills(skills) {
     return skills
         .map((s) => {
-        const head = `## Skill: ${s.name}${s.version ? ` (${s.version})` : ''}`;
+        const attrs = [
+            ` name="${attribute(s.name)}"`,
+            s.version ? ` version="${attribute(s.version)}"` : '',
+            // Same contract as a prompt block's `src`: the document to edit,
+            // under a name that is the same on every machine.
+            s.src ? ` src="${attribute(s.src)}"` : '',
+        ].join('');
         // One line, and only when the files are reachable. Without it the
         // model has the instructions and no way to act on the half of them
         // that names a file.
         const where = s.path
-            ? `\nThis skill's files are at ${s.path}, read-only. Paths written in it are ` +
-                'relative to that directory.\n'
+            ? `This skill's files are at ${s.path}, read-only. Paths written in it are ` +
+                'relative to that directory.\n\n'
             : '';
-        return `${head}${where}\n${s.content}`;
+        return `<skill${attrs}>\n${where}${s.content}\n</skill>`;
     })
         .join('\n\n');
 }

package/package.json

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