@zenera/neo 1.1.0 → 1.1.2

package/dist/project/config.d.ts

@@ -112,8 +112,24 @@ declare const embeddingSpec: z.ZodObject<{
     baseURL: z.ZodOptional<z.ZodString>;
     baseURLEnv: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
+/**
+ * A Dockerfile to build instead of an image to pull, for the ordinary case the
+ * `image:` key cannot serve: a project that needs two runtimes, or a pinned
+ * toolchain, and would otherwise have its agents reinstall it on every run.
+ *
+ * Building is a host concern, so nothing in this library does it — the front
+ * end resolves this to an image reference before a container is ever named.
+ */
+declare const build: z.ZodObject<{
+    dockerfile: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 declare const sandbox: z.ZodObject<{
     image: z.ZodOptional<z.ZodString>;
+    build: z.ZodOptional<z.ZodObject<{
+        dockerfile: z.ZodString;
+        context: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     cpus: z.ZodOptional<z.ZodNumber>;
     memory: z.ZodOptional<z.ZodInt>;
     network: z.ZodOptional<z.ZodEnum<{
@@ -230,8 +246,13 @@ export declare const projectSchema: z.ZodObject<{
     }, z.core.$strict>]>>>;
     embedding: z.ZodOptional<z.ZodString>;
     skills: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    assets: z.ZodOptional<z.ZodString>;
     sandbox: z.ZodOptional<z.ZodObject<{
         image: z.ZodOptional<z.ZodString>;
+        build: z.ZodOptional<z.ZodObject<{
+            dockerfile: z.ZodString;
+            context: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         cpus: z.ZodOptional<z.ZodNumber>;
         memory: z.ZodOptional<z.ZodInt>;
         network: z.ZodOptional<z.ZodEnum<{
@@ -269,6 +290,10 @@ export declare const projectSchema: z.ZodObject<{
         }, z.core.$strict>]>>;
         sandbox: z.ZodOptional<z.ZodObject<{
             image: z.ZodOptional<z.ZodString>;
+            build: z.ZodOptional<z.ZodObject<{
+                dockerfile: z.ZodString;
+                context: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
             cpus: z.ZodOptional<z.ZodNumber>;
             memory: z.ZodOptional<z.ZodInt>;
             network: z.ZodOptional<z.ZodEnum<{
@@ -291,6 +316,7 @@ export type ProviderConfig = z.infer<typeof provider>;
 export type ModelConfig = z.infer<typeof modelSpec>;
 export type EmbeddingConfig = z.infer<typeof embeddingSpec>;
 export type SandboxConfig = z.infer<typeof sandbox>;
+export type SandboxBuildConfig = z.infer<typeof build>;
 /**
  * Re-renders a zod failure as `agents.yaml: agents[1].skills.discovery — …`.
  *

package/dist/project/config.js

@@ -170,10 +170,28 @@ const forkBinding = z
  * hand every model key to whatever the agent decided to run.
  */
 const SECRETISH = /(KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL)/i;
+/**
+ * A Dockerfile to build instead of an image to pull, for the ordinary case the
+ * `image:` key cannot serve: a project that needs two runtimes, or a pinned
+ * toolchain, and would otherwise have its agents reinstall it on every run.
+ *
+ * Building is a host concern, so nothing in this library does it — the front
+ * end resolves this to an image reference before a container is ever named.
+ */
+const build = z
+    .object({
+    /** path to the Dockerfile, relative to the project root */
+    dockerfile: z.string().min(1),
+    /** what the build may COPY from; the Dockerfile's own directory by default */
+    context: z.string().min(1).optional(),
+})
+    .strict();
 const sandbox = z
     .object({
     /** the base image, e.g. `docker.io/library/python:3.13-slim` */
     image: z.string().min(1).optional(),
+    /** a Dockerfile to build, instead of an image to pull */
+    build: build.optional(),
     /** fractional cores the container may use */
     cpus: z.number().positive().optional(),
     /** MiB the container may use */
@@ -192,6 +210,14 @@ const sandbox = z
 })
     .strict()
     .superRefine((value, ctx) => {
+    if (value.image !== undefined && value.build !== undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['build'],
+            message: 'image and build cannot both be set — a Dockerfile names its own base ' +
+                'in its FROM line, so one of the two would be silently ignored',
+        });
+    }
     for (const [i, name] of (value.env ?? []).entries()) {
         if (SECRETISH.test(name)) {
             ctx.addIssue({
@@ -255,6 +281,12 @@ export const projectSchema = z
     embedding: modelRef.optional(),
     /** one directory, or several merged into one catalog */
     skills: z.union([z.string().min(1), z.array(z.string().min(1))]).optional(),
+    /**
+     * Reference material every agent can read and none can write, mounted
+     * at /assets. One directory, project-wide: an agent that may only see
+     * some of it is a different project, not a different key.
+     */
+    assets: z.string().min(1).optional(),
     /** the container `run_command` and friends execute in */
     sandbox: sandbox.optional(),
     agents: z.array(agent).min(1),

package/dist/project/index.d.ts

@@ -1,4 +1,4 @@
-export { parseConfig, projectSchema, type AgentConfig, type EmbeddingConfig, type ModelConfig, type ProjectConfig, type ProviderConfig, type SandboxConfig, } from './config.ts';
-export { AgentProject, loadProject, projectRegistry, readProjectConfig, type ProjectOptions, type ProjectSource, } from './load.ts';
+export { parseConfig, projectSchema, type AgentConfig, type EmbeddingConfig, type ModelConfig, type ProjectConfig, type ProviderConfig, type SandboxBuildConfig, type SandboxConfig, } from './config.ts';
+export { AgentProject, assetsDir, loadProject, projectRegistry, readProjectConfig, skillDirs, skillMounts, type ProjectOptions, type ProjectSource, } from './load.ts';
 export { projectDir, projectFile, projectPath, projectRoot } from './refs.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/project/index.js

@@ -1,4 +1,4 @@
 export { parseConfig, projectSchema, } from "./config.js";
-export { AgentProject, loadProject, projectRegistry, readProjectConfig, } from "./load.js";
+export { AgentProject, assetsDir, loadProject, projectRegistry, readProjectConfig, skillDirs, skillMounts, } from "./load.js";
 export { projectDir, projectFile, projectPath, projectRoot } from "./refs.js";
 //# sourceMappingURL=index.js.map

package/dist/project/load.d.ts

@@ -5,6 +5,7 @@ import type { MemoryStore } from '../memory.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 { type SkillDir } from '../skill-providers/file.ts';
 import type { SkillProvider } from '../skills.ts';
 import { type AnyTool, type Input } from '../types.ts';
 import { type ProjectConfig } from './config.ts';
@@ -16,6 +17,7 @@ import { type ProjectConfig } from './config.ts';
  * agents.yaml                   who exists, what they may reach for
  * agents/prompts/<role>.md      one agent's own instructions
  * agents/skills/<name>/SKILL.md
+ * assets/                       reference material, mounted read-only at /assets
  * ```
  *
  * The loader turns that into the objects an author would otherwise write by
@@ -56,6 +58,16 @@ export interface ProjectOptions<TCtx = unknown> {
     payloads?: PayloadStore;
     /** extra providers merged with the ones the project declares */
     skills?: SkillProvider[];
+    /**
+     * Where the host has mounted the skill catalog for the agent to reach —
+     * `/skills` from the CLI, which bind-mounts it into the container.
+     *
+     * Set it and a loaded skill carries the path of its own folder, so one that
+     * ships a script can say where the script is. Left unset, a skill is text
+     * and nothing claims otherwise: a promise of a directory that is not there
+     * is worse than no directory.
+     */
+    skillsAt?: string;
 }
 /** A project's declaration, before anything is assembled from it. */
 export interface ProjectSource {
@@ -85,6 +97,7 @@ interface ProjectParts<TCtx> {
     entry: string;
     registry: AgentRegistry<TCtx>;
     skillProviders: SkillProvider[];
+    assets: string | undefined;
     models: ModelRegistry;
     embedders: (ref: string | undefined, where: string) => Embedder | undefined;
     options: ProjectOptions<TCtx>;
@@ -112,6 +125,8 @@ export declare class AgentProject<TCtx = unknown> {
     readonly entry: string;
     readonly registry: AgentRegistry<TCtx>;
     readonly skillProviders: readonly SkillProvider[];
+    /** reference material to mount read-only, if the project has any */
+    readonly assets: string | undefined;
     /** the providers this project declared, and the clients behind them */
     readonly models: ModelRegistry;
     constructor(parts: ProjectParts<TCtx>);
@@ -138,5 +153,30 @@ export declare class AgentProject<TCtx = unknown> {
  * for, and only pay for it if an agent actually reaches for it.
  */
 export declare function projectRegistry<TCtx>(config: ProjectConfig, opts?: ProjectOptions<TCtx>): ModelRegistry;
+/**
+ * Where each skill directory appears in the agent's namespace.
+ *
+ * One catalog is the whole of `/skills`, which is what a project normally has.
+ * Several cannot all be it, so each takes its own last segment underneath — and
+ * two directories ending in the same name would mean one hid the other, which
+ * is a load error rather than a catalog that silently went missing.
+ */
+export declare function skillMounts(dirs: readonly string[], at: string): SkillDir[];
+/**
+ * The directories the skill catalog is built from, resolved. `skills:` if it is
+ * there, otherwise the conventional folder if it exists, otherwise none — a
+ * project without skills is a project, not an error.
+ */
+export declare function skillDirs(root: string, config: ProjectConfig): string[];
+/**
+ * The project's reference material, resolved, or undefined if it has none.
+ *
+ * Convention first — `assets/` next to `agents.yaml` is enough, and a project
+ * that only wants somewhere to put a handbook writes no config at all. The key
+ * exists for the project that keeps its material elsewhere in the tree; a key
+ * naming a directory that is not there is a mistake in the file and fails at
+ * load, where the conventional folder merely being absent does not.
+ */
+export declare function assetsDir(root: string, config: ProjectConfig): string | undefined;
 export {};
 //# sourceMappingURL=load.d.ts.map

package/dist/project/load.js

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
 import { Agent, AgentRegistry } from "../agent.js";
 import { RunStream } from "../events.js";
 import { ModelRegistry, } from "../models/factory.js";
@@ -11,6 +11,8 @@ import { parseConfig } from "./config.js";
 import { projectDir, projectFile, projectRoot } from "./refs.js";
 const PROMPTS_DIR = 'agents/prompts';
 const SKILLS_DIR = 'agents/skills';
+/** Reference material, by convention, when `assets:` says nothing. */
+const ASSETS_DIR = 'assets';
 const CONFIG_NAMES = ['agents.yaml', 'agents.yml', 'agents/agents.yaml', 'agents/agents.yml'];
 // 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
@@ -42,6 +44,9 @@ export async function loadProject(dir, opts = {}) {
     const providers = [...skillProviders(root, config, opts), ...(opts.skills ?? [])];
     const catalogs = await indexOf(providers);
     const models = projectRegistry(config, opts);
+    // Resolved here rather than where it is mounted, so an `assets:` naming a
+    // directory that is not there fails at load like every other bad path.
+    const assets = assetsDir(root, config);
     const registry = new AgentRegistry();
     const resolve = modelResolver(config, opts, models);
     for (const spec of config.agents) {
@@ -68,6 +73,7 @@ export async function loadProject(dir, opts = {}) {
         entry: entrypoint(config),
         registry,
         skillProviders: providers,
+        assets,
         models,
         embedders,
         options: opts,
@@ -95,6 +101,8 @@ export class AgentProject {
     entry;
     registry;
     skillProviders;
+    /** reference material to mount read-only, if the project has any */
+    assets;
     /** the providers this project declared, and the clients behind them */
     models;
     #embedders;
@@ -107,6 +115,7 @@ export class AgentProject {
         this.entry = parts.entry;
         this.registry = parts.registry;
         this.skillProviders = parts.skillProviders;
+        this.assets = parts.assets;
         this.models = parts.models;
         this.#embedders = parts.embedders;
         this.#options = parts.options;
@@ -307,13 +316,7 @@ function forkFor(spec) {
     return spec.fork === true ? {} : spec.fork;
 }
 function skillProviders(root, config, opts) {
-    const declared = config.skills
-        ? Array.isArray(config.skills)
-            ? config.skills
-            : [config.skills]
-        : existsSync(join(root, SKILLS_DIR))
-            ? [SKILLS_DIR]
-            : [];
+    const declared = skillDirs(root, config);
     if (!declared.length) {
         return [];
     }
@@ -323,11 +326,65 @@ function skillProviders(root, config, opts) {
     return [
         new FileSkillProvider({
             id: 'project',
-            dir: declared.map((d, i) => projectDir(root, d, `skills[${i}]`)),
+            dir: opts.skillsAt ? skillMounts(declared, opts.skillsAt) : declared,
             tools: opts.tools,
         }),
     ];
 }
+/**
+ * Where each skill directory appears in the agent's namespace.
+ *
+ * One catalog is the whole of `/skills`, which is what a project normally has.
+ * Several cannot all be it, so each takes its own last segment underneath — and
+ * two directories ending in the same name would mean one hid the other, which
+ * is a load error rather than a catalog that silently went missing.
+ */
+export function skillMounts(dirs, at) {
+    if (dirs.length === 1) {
+        return [{ path: dirs[0], at }];
+    }
+    const taken = new Map();
+    return dirs.map((dir) => {
+        const name = basename(dir);
+        const clash = taken.get(name);
+        if (clash) {
+            throw new Error(`skills: ${dir} and ${clash} would both be mounted at ${at}/${name}`);
+        }
+        taken.set(name, dir);
+        return { path: dir, at: `${at}/${name}` };
+    });
+}
+/**
+ * The directories the skill catalog is built from, resolved. `skills:` if it is
+ * there, otherwise the conventional folder if it exists, otherwise none — a
+ * project without skills is a project, not an error.
+ */
+export function skillDirs(root, config) {
+    const declared = config.skills
+        ? Array.isArray(config.skills)
+            ? config.skills
+            : [config.skills]
+        : existsSync(join(root, SKILLS_DIR))
+            ? [SKILLS_DIR]
+            : [];
+    return declared.map((d, i) => projectDir(root, d, `skills[${i}]`));
+}
+/**
+ * The project's reference material, resolved, or undefined if it has none.
+ *
+ * Convention first — `assets/` next to `agents.yaml` is enough, and a project
+ * that only wants somewhere to put a handbook writes no config at all. The key
+ * exists for the project that keeps its material elsewhere in the tree; a key
+ * naming a directory that is not there is a mistake in the file and fails at
+ * load, where the conventional folder merely being absent does not.
+ */
+export function assetsDir(root, config) {
+    if (config.assets) {
+        return projectDir(root, config.assets, 'assets');
+    }
+    const at = join(root, ASSETS_DIR);
+    return existsSync(at) && statSync(at).isDirectory() ? at : undefined;
+}
 // ---------------------------------------------------------------------------
 // Validation
 // ---------------------------------------------------------------------------

package/dist/skill-providers/file.d.ts

@@ -1,8 +1,18 @@
 import type { Skill, SkillProvider, SkillSummary } from '../skills.ts';
 import { type AnyTool } from '../types.ts';
+/**
+ * A directory of skills, and the name the *agent* reaches it by — which is not
+ * the host path when the folder is bind-mounted into a container. Give the
+ * plain string and a skill is text; give the pair and a skill that ships a
+ * script can say where the script is.
+ */
+export interface SkillDir {
+    path: string;
+    at: string;
+}
 export interface FileSkillProviderOptions {
-    /** one or more root directories holding `<name>.md` files and/or `<name>/SKILL.md` folders */
-    dir: string | string[];
+    /** one or more root directories holding `<name>/SKILL.md` folders, or bare `<name>.md` files */
+    dir: string | SkillDir | (string | SkillDir)[];
     /** logical provider id agents bind to; defaults to `file` */
     id?: string;
     /**
@@ -14,13 +24,18 @@ export interface FileSkillProviderOptions {
     tools?: AnyTool<any>[];
 }
 /**
- * Reads skills from disk. Two layouts, both discovered in one scan:
+ * Reads skills from disk. A skill is a directory holding `SKILL.md`, and the
+ * directory is what lets it ship a rate table or a script beside its text:
  *
  * ```
- * <dir>/budget_travel.md          flat: frontmatter + body
- * <dir>/budget_travel/SKILL.md    folder: sibling files become `resources`
+ * <dir>/budget_travel/SKILL.md    the instructions
+ * <dir>/budget_travel/cities.md   whatever they refer to
  * ```
  *
+ * A bare `<dir>/budget_travel.md` is indexed too, for a host with nothing but
+ * prose to offer. `zen check` refuses it in a project, since a skill with no
+ * directory of its own can never grow one.
+ *
  * Frontmatter is a small subset of YAML — `key: value`, plus `[a, b]` lists
  * for `tags` and `tools`. `name` defaults to the file or folder name and
  * `description` to the first line of the body, so the minimum viable skill is

package/dist/skill-providers/file.js

@@ -1,18 +1,23 @@
 import { readFile, readdir } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
+import { basename, join, resolve } from 'node:path';
 import { selectTools } from "../types.js";
 // ---------------------------------------------------------------------------
 // Filesystem-backed skill provider
 // ---------------------------------------------------------------------------
 const SKILL_FILE = 'SKILL.md';
 /**
- * Reads skills from disk. Two layouts, both discovered in one scan:
+ * Reads skills from disk. A skill is a directory holding `SKILL.md`, and the
+ * directory is what lets it ship a rate table or a script beside its text:
  *
  * ```
- * <dir>/budget_travel.md          flat: frontmatter + body
- * <dir>/budget_travel/SKILL.md    folder: sibling files become `resources`
+ * <dir>/budget_travel/SKILL.md    the instructions
+ * <dir>/budget_travel/cities.md   whatever they refer to
  * ```
  *
+ * A bare `<dir>/budget_travel.md` is indexed too, for a host with nothing but
+ * prose to offer. `zen check` refuses it in a project, since a skill with no
+ * directory of its own can never grow one.
+ *
  * Frontmatter is a small subset of YAML — `key: value`, plus `[a, b]` lists
  * for `tags` and `tools`. `name` defaults to the file or folder name and
  * `description` to the first line of the body, so the minimum viable skill is
@@ -26,7 +31,9 @@ export class FileSkillProvider {
     constructor(opts) {
         const o = typeof opts === 'string' ? { dir: opts } : opts;
         const raw = Array.isArray(o.dir) ? o.dir : [o.dir];
-        this.#dirs = raw.map((d) => resolve(d));
+        this.#dirs = raw.map((d) => typeof d === 'string'
+            ? { path: resolve(d), at: '' }
+            : { path: resolve(d.path), at: d.at });
         this.id = o.id ?? 'file';
         for (const t of o.tools ?? []) {
             this.#tools.set(t.name, t);
@@ -34,11 +41,11 @@ export class FileSkillProvider {
     }
     /** The first configured directory (kept for backwards compatibility). */
     get dir() {
-        return this.#dirs[0];
+        return this.#dirs[0].path;
     }
     /** All configured directories. */
     get dirs() {
-        return [...this.#dirs];
+        return this.#dirs.map((d) => d.path);
     }
     /** Drops the cached scan; call after editing skills on disk. */
     refresh() {
@@ -77,7 +84,7 @@ export class FileSkillProvider {
             content: entry.content,
             file: entry.file,
             ...(tools.length ? { tools } : {}),
-            ...(entry.folder ? { resources: await readResources(entry.folder) } : {}),
+            ...(entry.at ? { path: entry.at } : {}),
         };
     }
     tool(name) {
@@ -93,7 +100,7 @@ export class FileSkillProvider {
         for (const dir of this.#dirs) {
             let items;
             try {
-                items = await readdir(dir, { withFileTypes: true });
+                items = await readdir(dir.path, { withFileTypes: true });
             }
             catch (err) {
                 if (err.code === 'ENOENT') {
@@ -102,8 +109,8 @@ export class FileSkillProvider {
                 throw err;
             }
             for (const item of items) {
-                const folder = item.isDirectory() ? join(dir, item.name) : undefined;
-                const file = folder ? join(folder, SKILL_FILE) : join(dir, item.name);
+                const folder = item.isDirectory() ? join(dir.path, item.name) : undefined;
+                const file = folder ? join(folder, SKILL_FILE) : join(dir.path, item.name);
                 if (!folder && !(item.isFile() && item.name.endsWith('.md'))) {
                     continue;
                 }
@@ -112,20 +119,24 @@ export class FileSkillProvider {
                     continue;
                 }
                 const base = folder ? item.name : item.name.slice(0, -'.md'.length);
-                const entry = parse(raw, base, file, folder);
+                // 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);
                 index.set(entry.summary.name, entry);
             }
         }
         return index;
     }
 }
-function parse(raw, base, file, folder) {
+function parse(raw, base, file, folder, at) {
     const { data, body } = frontmatter(raw);
     const tags = toList(data.tags);
     const tools = toList(data.tools);
     return {
         file,
         folder,
+        ...(at ? { at } : {}),
         content: body,
         summary: {
             name: data.name || base,
@@ -136,20 +147,6 @@ function parse(raw, base, file, folder) {
         },
     };
 }
-/** Sibling files of a `SKILL.md`, top level only, keyed by filename. */
-async function readResources(folder) {
-    const out = {};
-    for (const item of await readdir(folder, { withFileTypes: true })) {
-        if (!item.isFile() || item.name === SKILL_FILE) {
-            continue;
-        }
-        const value = await readOptional(join(folder, item.name));
-        if (value !== undefined) {
-            out[item.name] = value;
-        }
-    }
-    return out;
-}
 async function readOptional(path) {
     try {
         return await readFile(path, 'utf8');

package/dist/skills.d.ts

@@ -23,7 +23,14 @@ export interface Skill extends SkillSummary {
     content: string;
     /** tools unlocked while the skill is active; the context type is the host agent's */
     tools?: AnyTool<any>[];
-    resources?: Record<string, string>;
+    /**
+     * Where the skill's own files are, *under a name the agent can use* — not a
+     * host path. A skill that ships a script is instructions plus that script,
+     * and its text says "run scripts/fill.py" without saying where `scripts/`
+     * is; this is the answer, and it is only set when the host has actually put
+     * the folder somewhere the agent can reach.
+     */
+    path?: string;
     /** absolute path of the source file, if known (set by file-backed providers) */
     file?: string;
 }

package/dist/skills.js

@@ -6,7 +6,17 @@ export function skillContentHash(s) {
 }
 export function renderSkills(skills) {
     return skills
-        .map((s) => `## Skill: ${s.name}${s.version ? ` (${s.version})` : ''}\n${s.content}`)
+        .map((s) => {
+        const head = `## Skill: ${s.name}${s.version ? ` (${s.version})` : ''}`;
+        // 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'
+            : '';
+        return `${head}${where}\n${s.content}`;
+    })
         .join('\n\n');
 }
 export function renderSkillIndex(summaries, max) {

package/dist/tools/workspace.d.ts

@@ -1,4 +1,22 @@
 import { type AnyTool } from '../types.ts';
+/** Where a project's `assets/` directory appears in the agent's namespace. */
+export declare const ASSETS_MOUNT = "/assets";
+/** ...and where its skill catalog does, so a skill's scripts can be run. */
+export declare const SKILLS_MOUNT = "/skills";
+/**
+ * A second tree the agent can reach, under a name of its own. Structurally the
+ * same as a `SandboxMount` on purpose: one directory is one mount, and the host
+ * hands the identical array to the file tools and to the container so that both
+ * call it by the same name.
+ */
+export interface WorkspaceMount {
+    /** absolute host path; must already exist */
+    host: string;
+    /** absolute path the agent names it by, e.g. `/assets` */
+    at: string;
+    /** defaults to true — an extra tree is reference material unless said otherwise */
+    readOnly?: boolean;
+}
 export interface WorkspaceOptions {
     root: string;
     /** refuse every mutating tool; `zen run --read-only` */
@@ -11,22 +29,28 @@ export interface WorkspaceOptions {
      * it and both spellings reach the same file.
      */
     mount?: string;
+    /** further trees, each under its own name; read-only unless one says otherwise */
+    mounts?: readonly WorkspaceMount[];
 }
 export declare class Workspace {
     #private;
     readonly root: string;
     readonly readOnly: boolean;
     readonly mount: string | undefined;
+    /** the extra trees, resolved — the primary root is not among them */
+    readonly mounts: readonly Required<WorkspaceMount>[];
     constructor(opts: WorkspaceOptions);
     /**
-     * The one gate. Returns an absolute path inside the workspace, or throws.
+     * The one gate. Returns an absolute path inside one of the roots, or throws.
      *
      * A path that does not exist yet cannot be realpath'd, so the nearest
      * existing ancestor is resolved instead and the remainder appended — which
      * is exactly what a create needs and closes the same hole a create opens.
      */
-    within(input: string): string;
-    /** Where a path sits under the root, in posix form. `.` is the root. */
+    within(input: string, opts?: {
+        write?: boolean;
+    }): string;
+    /** Where a path sits under its own root, in posix form. `.` is that root. */
     rel(path: string): string;
     /**
      * How a path is written back to the model, and the reason `mount` is not
@@ -39,6 +63,8 @@ export declare class Workspace {
      * is exact. Without one, everything stays relative as before.
      */
     show(path: string): string;
+    /** Whether a resolved path *is* one of the roots. Nothing may move or delete one. */
+    isRoot(path: string): boolean;
     mutable(): void;
 }
 export type FileFormat = 'text' | 'binary' | 'image' | 'audio' | 'video' | 'pdf' | 'archive';

package/dist/tools/workspace.js

@@ -1,4 +1,4 @@
-import { realpathSync } from 'node:fs';
+import { realpathSync, statSync } from 'node:fs';
 import { mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, extname, join, relative, resolve, sep } from 'node:path';
 import { tool } from "../types.js";
@@ -28,68 +28,117 @@ const SNIFF_BYTES = 8 * 1024;
 const MAX_SCAN = 1024 * 1024;
 /** ...and one listing only spends this much on line counting in total. */
 const LIST_SCAN_BUDGET = 8 * 1024 * 1024;
+/** Where a project's `assets/` directory appears in the agent's namespace. */
+export const ASSETS_MOUNT = '/assets';
+/** ...and where its skill catalog does, so a skill's scripts can be run. */
+export const SKILLS_MOUNT = '/skills';
 export class Workspace {
     root;
     readOnly;
     mount;
+    /** the extra trees, resolved — the primary root is not among them */
+    mounts;
+    /** primary first */
+    #roots;
+    /** the ones with a name, longest name first */
+    #named;
+    /** every root, deepest host path first, for attributing a resolved path to one */
+    #deep;
     constructor(opts) {
         // Resolve the root's own symlinks once, so a workspace that *is* a
         // symlink does not fail every containment check against itself.
         this.root = realpathSync(resolve(opts.root));
         this.readOnly = opts.readOnly ?? false;
-        // A trailing slash — or a mount of `/`, which would make everything on
-        // the machine look like it was inside — is not a mount point.
-        const mount = opts.mount?.replace(/\/+$/, '');
-        this.mount = mount ? mount : undefined;
+        this.mount = mountPoint(opts.mount);
+        const roots = [{ path: this.root, at: this.mount, readOnly: this.readOnly }];
+        const mounts = [];
+        for (const m of opts.mounts ?? []) {
+            const at = mountPoint(m.at);
+            if (at === undefined) {
+                throw new Error(`a workspace mount needs an absolute name of its own: ${m.at}`);
+            }
+            // Overlapping names would make one path mean two directories, and
+            // which one won would depend on the order they were passed in.
+            for (const taken of roots) {
+                if (taken.at && (at === taken.at || under(at, taken.at) || under(taken.at, at))) {
+                    throw new Error(`workspace mounts overlap: ${at} and ${taken.at}`);
+                }
+            }
+            const host = directory(m.host, at);
+            const readOnly = m.readOnly ?? true;
+            roots.push({ path: host, at, readOnly });
+            mounts.push({ host, at, readOnly });
+        }
+        this.mounts = mounts;
+        this.#roots = roots;
+        this.#named = roots
+            .filter((r) => r.at !== undefined)
+            .sort((a, b) => b.at.length - a.at.length);
+        // A mount may sit inside the workspace root; the deeper one owns the path.
+        this.#deep = [...roots].sort((a, b) => b.path.length - a.path.length);
     }
     /**
-     * The one gate. Returns an absolute path inside the workspace, or throws.
+     * The one gate. Returns an absolute path inside one of the roots, or throws.
      *
      * A path that does not exist yet cannot be realpath'd, so the nearest
      * existing ancestor is resolved instead and the remainder appended — which
      * is exactly what a create needs and closes the same hole a create opens.
      */
-    within(input) {
+    within(input, opts = {}) {
         if (typeof input !== 'string' || input.length === 0) {
             throw new Error('path is required');
         }
         if (input.includes('\0')) {
             throw new Error('path contains a null byte');
         }
-        // A lone `/` is the model's other name for "the top of what I can see".
-        // There is nothing above the root for it to mean, so it means the root
-        // — refusing it teaches nothing and costs a turn. This is the only
-        // absolute path treated as rooted: `/etc/passwd` still names the
-        // machine's file and still fails containment below.
-        const wanted = resolve(this.root, /^[\\/]+$/.test(input) ? '.' : this.#unmount(input));
-        const real = this.#realish(wanted);
-        if (real !== this.root && !real.startsWith(this.root + sep)) {
+        const { root, rest } = this.#locate(input);
+        const real = this.#realish(resolve(root.path, rest));
+        if (real !== root.path && !real.startsWith(root.path + sep)) {
             throw new Error(`outside the workspace: ${input}`);
         }
+        if (opts.write && root.readOnly) {
+            throw new Error(root.path === this.root
+                ? 'the workspace is read-only for this run'
+                : `${root.at} is read-only`);
+        }
         return real;
     }
     /**
-     * `/workspace/src/a.ts` and `src/a.ts` are one file under two names, and
-     * only the second resolves against the root, so the mounted spelling is
-     * rewritten before anything else looks at it.
+     * Which tree a path names, and where in it. `/workspace/src/a.ts` and
+     * `src/a.ts` are one file under two names, and only the second resolves
+     * against the root, so the mounted spelling is rewritten before anything
+     * else looks at it.
      *
-     * This is renaming, not permission. What comes out is still relative, still
-     * resolved, still symlink-followed and still checked against the root
-     * above: `/workspace/../etc/passwd` loses its prefix and then fails
-     * containment exactly as `../etc/passwd` does.
+     * This is renaming, not permission. What comes out is still resolved, still
+     * symlink-followed and still checked against its root by the caller:
+     * `/workspace/../etc/passwd` loses its prefix and then fails containment
+     * exactly as `../etc/passwd` does.
      */
-    #unmount(input) {
-        if (this.mount === undefined) {
-            return input;
+    #locate(input) {
+        const primary = this.#roots[0];
+        // A lone `/` is the model's other name for "the top of what I can see".
+        // There is nothing above the root for it to mean, so it means the root
+        // — refusing it teaches nothing and costs a turn. This is the only
+        // absolute path treated as rooted: `/etc/passwd` still names the
+        // machine's file and still fails containment.
+        if (/^[\\/]+$/.test(input)) {
+            return { root: primary, rest: '.' };
         }
         const at = input.replace(/\\/g, '/');
-        if (at === this.mount) {
-            return '.';
-        }
-        if (!at.startsWith(this.mount + '/')) {
-            return input;
+        for (const root of this.#named) {
+            if (at === root.at) {
+                return { root, rest: '.' };
+            }
+            if (at.startsWith(root.at + '/')) {
+                return { root, rest: at.slice(root.at.length + 1).replace(/^\/+/, '') || '.' };
+            }
         }
-        return at.slice(this.mount.length).replace(/^\/+/, '') || '.';
+        return { root: primary, rest: input };
+    }
+    /** The root a resolved path belongs to; the primary when nothing else claims it. */
+    #owner(path) {
+        return (this.#deep.find((r) => path === r.path || path.startsWith(r.path + sep)) ??
+            this.#roots[0]);
     }
     #realish(path) {
         const missing = [];
@@ -113,9 +162,9 @@ export class Workspace {
             }
         }
     }
-    /** Where a path sits under the root, in posix form. `.` is the root. */
+    /** Where a path sits under its own root, in posix form. `.` is that root. */
     rel(path) {
-        return relative(this.root, path).split(sep).join('/') || '.';
+        return relative(this.#owner(path).path, path).split(sep).join('/') || '.';
     }
     /**
      * How a path is written back to the model, and the reason `mount` is not
@@ -128,11 +177,16 @@ export class Workspace {
      * is exact. Without one, everything stays relative as before.
      */
     show(path) {
-        const rel = this.rel(path);
-        if (this.mount === undefined) {
+        const root = this.#owner(path);
+        const rel = relative(root.path, path).split(sep).join('/') || '.';
+        if (root.at === undefined) {
             return rel;
         }
-        return rel === '.' ? this.mount : `${this.mount}/${rel}`;
+        return rel === '.' ? root.at : `${root.at}/${rel}`;
+    }
+    /** Whether a resolved path *is* one of the roots. Nothing may move or delete one. */
+    isRoot(path) {
+        return this.#roots.some((r) => r.path === path);
     }
     mutable() {
         if (this.readOnly) {
@@ -140,6 +194,39 @@ export class Workspace {
         }
     }
 }
+/**
+ * An absolute name a tree is known by, with any trailing slash removed. A mount
+ * of `/` would make everything on the machine look like it was inside, so it is
+ * not a mount point; nor is a relative one, which would resolve against nothing.
+ */
+function mountPoint(at) {
+    const clean = at?.replace(/\\/g, '/').replace(/\/+$/, '');
+    return clean && clean.startsWith('/') ? clean : undefined;
+}
+function under(inner, outer) {
+    return inner.startsWith(outer + '/');
+}
+/** The host side of a mount, resolved. It has to exist: a mount of nothing is a typo. */
+function directory(host, at) {
+    let path;
+    try {
+        path = realpathSync(resolve(host));
+    }
+    catch {
+        throw new Error(`workspace mount ${at}: no such directory: ${host}`);
+    }
+    if (!statSync(path).isDirectory()) {
+        throw new Error(`workspace mount ${at}: not a directory: ${host}`);
+    }
+    return path;
+}
+/** `a`, `a and b`, `a, b and c` — these end up in sentences the model reads. */
+function nameList(items) {
+    if (items.length < 2) {
+        return items[0] ?? '';
+    }
+    return `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
+}
 /**
  * Formats that are decided by name alone. Everything absent from here is
  * sniffed, so an unknown extension still lands on text or binary correctly.
@@ -531,18 +618,29 @@ export function workspaceTools(opts) {
     // `read_file`, which is the first of these any model reaches for; the short
     // one is repeated on every `path` argument, which is where the value is
     // actually written and where a wrong guess costs a turn.
-    const scope = ws.mount
-        ? `The workspace is mounted at ${ws.mount}, which is the name commands running in the ` +
-            `sandbox print and the name these tools answer with, so a path from a command's ` +
-            `output can be used here unchanged. A path relative to the workspace root names the ` +
-            `same file: ${ws.mount}/src/a.ts and src/a.ts are one file. That directory is the ` +
-            'whole of what can be reached: nothing outside it can be read or written.'
-        : 'Paths are relative to the workspace root, and that directory is the whole of what ' +
-            'can be reached: nothing outside it can be read or written.';
-    const inside = ws.mount
-        ? `Path in the workspace: ${ws.mount}/src/a.ts, or src/a.ts relative to the root — the ` +
-            `same file either way. The root itself is "${ws.mount}", "/" or ".".`
-        : 'Path in the workspace, relative to its root: src/a.ts. The root itself is "." or "/".';
+    //
+    // This is also the only place an extra tree is named. Nothing else in the
+    // prompt mentions one, and a directory the model has not been told about is
+    // a directory it never opens.
+    const extras = ws.mounts.map((m) => m.at);
+    const bounds = extras.length === 0
+        ? ' That directory is the whole of what can be reached: nothing outside it can be ' +
+            'read or written.'
+        : ` ${nameList(extras)} ${extras.length > 1 ? 'are' : 'is'} mounted alongside it: ` +
+            `read, list and search ${extras.length > 1 ? 'them' : 'it'} like anything else, ` +
+            'but nothing there can be written, moved or deleted. Nothing outside those ' +
+            'directories can be reached at all.';
+    const scope = (ws.mount
+        ? `The workspace is mounted at ${ws.mount}, which is the name commands running in ` +
+            `the sandbox print and the name these tools answer with, so a path from a ` +
+            `command's output can be used here unchanged. A path relative to the workspace ` +
+            `root names the same file: ${ws.mount}/src/a.ts and src/a.ts are one file.`
+        : 'Paths are relative to the workspace root.') + bounds;
+    const inside = (ws.mount
+        ? `Path in the workspace: ${ws.mount}/src/a.ts, or src/a.ts relative to the root — ` +
+            `the same file either way. The root itself is "${ws.mount}", "/" or ".".`
+        : 'Path in the workspace, relative to its root: src/a.ts. The root itself is "." ' +
+            'or "/".') + (extras.length === 0 ? '' : ` Read-only: ${nameList(extras)}.`);
     /**
      * `.`, `/`, the mount and nothing at all are four spellings of the root, and
      * a tool whose path is optional takes all four. A model that means "the top"
@@ -687,7 +785,7 @@ export function workspaceTools(opts) {
             if (content.length > MAX_WRITE) {
                 return { error: `content exceeds ${MAX_WRITE} bytes` };
             }
-            const at = ws.within(path);
+            const at = ws.within(path, { write: true });
             await mkdir(dirname(at), { recursive: true });
             await writeFile(at, content, 'utf8');
             return {
@@ -770,12 +868,12 @@ export function workspaceTools(opts) {
         },
         execute: async ({ from, to, overwrite }) => {
             ws.mutable();
-            const source = ws.within(from);
-            const target = ws.within(to);
-            if (source === ws.root) {
+            const source = ws.within(from, { write: true });
+            const target = ws.within(to, { write: true });
+            if (ws.isRoot(source)) {
                 return { error: 'refusing to move the workspace root' };
             }
-            if (target === ws.root) {
+            if (ws.isRoot(target)) {
                 return { error: 'refusing to overwrite the workspace root' };
             }
             if (source === target) {
@@ -819,8 +917,8 @@ export function workspaceTools(opts) {
         },
         execute: async ({ path, recursive }) => {
             ws.mutable();
-            const at = ws.within(path);
-            if (at === ws.root) {
+            const at = ws.within(path, { write: true });
+            if (ws.isRoot(at)) {
                 return { error: 'refusing to delete the workspace root' };
             }
             const info = await stat(at);
@@ -857,19 +955,35 @@ export function workspaceTools(opts) {
             additionalProperties: false,
         },
         execute: async ({ pattern, path }) => {
-            const at = root(path);
+            // Omitting the path means "everywhere I can see", and what the
+            // model can see now includes the mounted trees. Searching only the
+            // workspace would leave them behind a path it has to know to ask
+            // for. A tree nested inside the workspace is walked twice, so the
+            // hits are a set: `show` gives one file one name either way.
+            const where = path?.trim()
+                ? [ws.within(path)]
+                : [ws.root, ...ws.mounts.map((m) => m.host)];
             const needle = pattern.toLowerCase();
-            const hits = [];
-            await walk(at, ws, (file) => {
-                // Matched on the path within the workspace, reported under the
-                // name the model uses: a mount prefix is on every candidate, so
-                // matching it would mean nothing.
-                if (ws.rel(file).toLowerCase().includes(needle)) {
-                    hits.push(ws.show(file));
+            const hits = new Set();
+            for (const dir of where) {
+                const room = await walk(dir, ws, (file) => {
+                    // Matched on the path within its own tree, reported under
+                    // the name the model uses: a mount prefix is on every
+                    // candidate, so matching it would mean nothing.
+                    if (ws.rel(file).toLowerCase().includes(needle)) {
+                        hits.add(ws.show(file));
+                    }
+                    return hits.size < MAX_ENTRIES;
+                });
+                if (!room) {
+                    break;
                 }
-                return hits.length < MAX_ENTRIES;
-            });
-            return { pattern, matches: hits, truncated: hits.length >= MAX_ENTRIES };
+            }
+            return {
+                pattern,
+                matches: [...hits],
+                truncated: hits.size >= MAX_ENTRIES,
+            };
         },
     });
     return opts.readOnly
@@ -883,8 +997,8 @@ async function runPatch(ws, patch) {
     const seen = new Set();
     let fuzz = 0;
     for (const op of ops) {
-        const at = ws.within(op.path);
-        if (at === ws.root) {
+        const at = patchPath(ws, op.path);
+        if (ws.isRoot(at)) {
             throw new PatchError(`${op.path} is the workspace root`);
         }
         if (seen.has(at)) {
@@ -953,8 +1067,8 @@ async function runPatch(ws, patch) {
             lines: patched.lines.length,
         };
         if (op.moveTo) {
-            const to = ws.within(op.moveTo);
-            if (to === ws.root) {
+            const to = patchPath(ws, op.moveTo);
+            if (ws.isRoot(to)) {
                 throw new PatchError('cannot move a file onto the workspace root');
             }
             if (to !== at) {
@@ -1000,6 +1114,21 @@ async function statOrNull(at) {
         return null;
     }
 }
+/**
+ * A path in a patch, checked for containment and for write permission before
+ * the first byte is written. Both refusals become patch errors, because the
+ * promise apply_patch makes is that a patch it will not finish leaves nothing
+ * behind — a read-only file named halfway down is a reason to reject the whole
+ * patch, not to write the files above it and then throw.
+ */
+function patchPath(ws, path) {
+    try {
+        return ws.within(path, { write: true });
+    }
+    catch (err) {
+        throw new PatchError(err instanceof Error ? err.message : String(err));
+    }
+}
 /** Depth-first, skipping the noise nobody means to search. */
 const SKIP = new Set(['.git', 'node_modules', '.data', 'dist', '.venv', '__pycache__']);
 async function walk(dir, ws, visit) {

package/package.json

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