@nylorun/agents 0.27.0-beta → 0.28.0-beta

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @nylorun/agents
 
+## 0.28.0-beta
+
+### Minor Changes
+
+- 498d972: `@nylorun/agents` exports `harnessSectionOf` and `sectionGaps` from its main entry, as its README documents: the harness section `agentManifests.save` makes from a built agent or flow, and the gaps the Runtime refuses between a manifest's two sections. Both were only in `@nylorun/agents/define` and `@nylorun/core/define`.
+
+  `nylo` no longer says nylorun 0.19 removes it, which 0.19 does not: its message ends "A later nylorun release removes nylo."
+
+- b3dad06: Agent folders convert both ways (track T7, D80). `folderOfManifest(manifest)` in `@nylorun/core/folder` (also exported by `@nylorun/agents`) writes the agent folder that compiles back to the same manifest: name, description, metadata, harness, memory, loop and server and skill settings in `AGENT.md`, the first instruction as its body and the rest as `instructions/NN-*.md`, HTTP tools as `tools/<name>.json`, subagents as `agents/<name>/`, a flow as `flow.json` (v3's node tree, naming agents by id and tools by file name) with one flat `agents/<id>/` for its agents and its sub-flows' (a sub-flow is an `agents/<id>/` with its own `flow.json`, and a tool stage or HTTP verifier a `tools/<name>.json` beside the `flow.json` that names it), MCP servers in `mcp.json` with `Bearer ${SLOT}` or `${SLOT}` for a credential, triggers as `triggers/<id>.md`, and `runtime.json` without the slots the compiler derives the same way. It checks itself by compiling the folder, says whether the hash is the same (`exact`), and notes what it writes differently. Skills are written from their bytes when given them, else as a placeholder with the files to copy in. An embedded agent's display `name` is left out with a note, since a folder names an agent by its id.
+
+  `nylorun export --folder <name>[@<version>]` writes the folder of a saved manifest, from JSON or TypeScript; `nylorun migrate folder <dir>` writes the folder of a three-file folder, offline, with its skills; `nylorun pull <name>[@<version>]` writes back the folder a version was saved from, byte for byte, and says to use `export --folder` for a version saved as JSON. None writes over a file with other bytes.
+
+  Deprecated, still read: the three-file format (`agent.manifest.json`), whose `composeManifest` and `nylorun apply` now warn and name `nylorun migrate folder`, and `secrets` in a `SKILL.md`, which the skills loader warns about (a `DeprecationWarning` from `.skills()`): an agent folder lists a skill's secrets in `AGENT.md`.
+
+- b3dad06: Both ends of the agent folder loop (track T7).
+
+  - `nylorun init <path>` names the agent after the path's last segment (`init agents/hello`). `--example` adds `tools/get_order.json`, `mcp.json` (a `Bearer ${ORDERS_MCP_TOKEN}` header) and `triggers/new-order.md`, explained in the folder's README.md, and the result passes `nylorun check`. The first run in a project (the nearest directory with `.git`) writes `.gitattributes` (`* text=auto eol=lf`), ignores `.nylorun/credentials.json` in `.gitignore`, and maps the folder files to their JSON Schemas in `.vscode/settings.json`, merged into an existing file. Its hint names `apply --agent` and `chat`.
+  - `nylorun apply --agent [<id>]` makes the Agent from the manifest after a save (or on an unchanged one), or moves it, as `nylorun agents put` does, and prints what it needs a person for.
+  - `nylorun apply --watch [--save]` checks and plans again on each change to the folders (and the files their `runtime.json` extends); it saves only with `--save`.
+  - A plan's change to the instructions prints their text diff, `-` and `+` lines.
+  - `nylorun chat <agent> [--session <id>] [--message <text>]` opens or reuses a session, sends `--message` or each line of standard input, and prints the reply as it comes.
+  - `nylorun check --json` prints `{ folders: [{ path, ok, manifest?, diagnostics }] }` for CI, with the same exit codes. `check` says "1 file", and `nylorun --version` prints the version.
+  - `packFolder` (`@nylorun/agents`) leaves out what the folder's `.nyloignore` names (gitignore rules), and resolves `extends` in `runtime.json`: the packed file is the merge, the folder's own keys winning, with `.nylorun/origin.json` naming the files it came from; a missing file or a cycle is a `FolderError`. `ignoreMatcher` is exported.
+  - `session.approve(id, approved)` and `session.respond(id, value)` take no options: each makes its own idempotency key.
+  - The Runtime's Agent view names each required secret of the version it runs that has no value, as an attention item (`secret_unset: required secret ORDERS_TOKEN unset`, state `input_required`), until it is set.
+  - The compiler's refusal of an unresolved `extends` says to resolve it before uploading.
+
+- b3dad06: Compare two versions' agent folders, and set what a folder may hold per Tenant (track T7).
+
+  - **`GET /v1/agent-manifests/{name}/source/diff?from=<v>&to=<v>`** answers the files added, removed and changed (by SHA-256) from one version's source to another's, each list sorted by path, and how many stayed the same (`AgentManifestSourceDiff` in `@nylorun/core/contracts`). A version saved as JSON has no source (`404`); a `from` or `to` that is not a version number is `400`. `client.agentManifests.sourceDiff(name, from, to)` in `@nylorun/agents` calls it.
+  - **Folder limits are Tenant settings**: the Runtime limits `folderFiles` (2,000), `folderBytes` (50 MiB) and `folderTextFileBytes` (1 MiB), T6's fixed values, set with `PUT /v1/tenant/limits` like the others. A folder save with more files or bytes is `413 limit_exceeded` (`details.limit` names the limit), and the compiler holds each Markdown or JSON file to `folderTextFileBytes` (`422 folder_invalid`).
+  - `compileAgentFolder({ entries, files, name, limits })` takes the limits as an optional input (`AgentFolderLimits`); each left out is `AGENT_FOLDER_LIMITS`'.
+  - `@nylorun/agents` also exports the types `AgentManifestSource`, `AgentManifestSourceDiff`, `AgentManifestSourceSummary` and `AgentFolderDiagnostic`, and `AGENT_FOLDER_MEDIA_TYPE`.
+
+### Patch Changes
+
+- 7bcdc85: `composeManifest` reads the `mcp.json` a `harness.manifest.json` names in a folder reached through a symlink, such as macOS's temporary directory (`/var` → `/private/var`). The package boundary is now resolved through `realpath` like the file, so it is no longer refused as "not a file inside the package".
+- Pin core to the tested release.
+- Updated dependencies [498d972]
+- Updated dependencies [d23304e]
+- Updated dependencies [b3dad06]
+- Updated dependencies [b3dad06]
+- Updated dependencies [b3dad06]
+- Updated dependencies [498d972]
+- Updated dependencies [b3dad06]
+  - @nylorun/core@0.28.0-beta
+
 ## 0.27.0-beta
 
 ### Minor Changes

package/README.md

@@ -150,6 +150,8 @@ management key (`PUT /v1/tenant/tool-policy`, `admin.toolPolicy.put()` in
 journals the call, before anything is sent, and its Tool Gate runs only a call
 the journal holds running, so a harness cannot skip it.
 
+<!-- doc-test: tool-policy -->
+<!-- doc-test: typescript -->
 ```ts
 import { createAdmin } from "@nylorun/admin";
 
@@ -157,23 +159,27 @@ await createAdmin().toolPolicy.put({
   rules: [
     { effect: "ask", tool: "refund_order", reason: "Refunds need a person" },
     { effect: "deny", tool: "refund_order", when: { amount: { gt: 10_000 } } },
-    { effect: "ask", server: "github", tool: "github__delete_*" },
+    { effect: "ask", server: "github", tool: "delete_*" },
   ],
 });
 ```
 
-A rule matches a call when every selector it sets matches: `tool` (the name the
-model calls it by; `*` matches any run of characters), `server` (an MCP
+A rule matches a call when every selector it sets matches: `tool` (the tool's
+own name: an MCP tool's name on its server, such as `delete_file`, or an HTTP
+tool's declared name; `*` matches any run of characters), `server` (an MCP
 server's name), `kind` (`mcp` or `http`), `agent` (the agent that calls it) and
 `when` (fields of the call's input by dotted path, each tested with `equals`,
 `in`, `gt`, `gte`, `lt`, `lte` or `matches`). The strictest matching rule
-decides, and a call no rule matches runs:
+decides, and a call no rule matches runs. Name an MCP tool by `server` and
+`tool`, never by the name the model calls it by (`github__delete_file`): a
+harness chooses that name, and a `tool` with `__` in it is refused (`400`).
 
 - `deny`: the call is never sent; the model gets `tool.denied` with the rule's
   `reason`.
 - `ask`: the turn pauses (`turn.paused`, with the tool, its input and the
   reason). `session.approve(interactionId, true)` sends that exact call;
-  `false` fails it to the model as `tool.denied`, unsent. Nothing holds a
+  `false` fails it to the model as `tool.denied`, unsent (pass
+  `{ idempotencyKey }` as a third argument to retry an answer safely). Nothing holds a
   process while it waits, so an approval can wait a day, or a Runtime restart.
   Studio shows an approval card; AG-UI ends the run with a `tool_approval`
   interrupt.
@@ -252,7 +258,7 @@ const assistant = Agent({ id: "assistant", name: "Order assistant" })
   .skills("./assistant-skills");
 ```
 
-Each subdirectory under the catalog must contain a `SKILL.md` with YAML frontmatter (`name`, `description`) per [Agent Skills](https://agentskills.io/home). Its `secrets` (`secrets: [GH_TOKEN]`, environment variable names) are the skill's `secrets` in the harness section: the `runtime.secrets` slots its scripts read, of type `environment_secret` or `environment_variable`; a skill whose `secrets` is not such a list is skipped with a warning. Every file of a skill's folder, binary included (not `.git/`, `node_modules/`, OS files like `.DS_Store`, or `.env` and `.env.*` files, which hold secrets), is part of the definition: the manifest names each one by path and SHA-256 (`skills.<name>.files`). A skill's files may hold together at most the Tenant's skill limit (`PUT /v1/tenant/skills`, default 2 GiB); no file and no count of files has a limit of its own, and a manifest's runtime section may set a lower limit for its Agents' sessions (`runtime.limits.skills.totalBytes`). Skills need a sandbox: the runtime section's kind is `virtual` or `pod`, which the Runtime checks when the manifest is saved. `agentManifests.save` uploads the files the Runtime does not hold (`client.files`, `PUT /v1/files/sha256:<hex>`) before it saves the manifest, which the Runtime refuses while it names a file it lacks (`400 definition_files_missing`) or a skill past the Tenant's limit (`413 limit_exceeded`). `read_skill_resource` reads files of up to 10 MiB into the model's context; a larger one is used in the sandbox.
+Each subdirectory under the catalog must contain a `SKILL.md` with YAML frontmatter (`name`, `description`) per [Agent Skills](https://agentskills.io/home). Its `secrets` (`secrets: [GH_TOKEN]`, environment variable names) are the skill's `secrets` in the harness section: the `runtime.secrets` slots its scripts read, of type `environment_secret` or `environment_variable`; a skill whose `secrets` is not such a list is skipped with a warning. `secrets` is not an Agent Skills key, so it is deprecated in `SKILL.md` (still read, with a `DeprecationWarning`): an agent folder lists a skill's secrets in `AGENT.md`'s skills block (`skills: { <name>: { secrets: [GH_TOKEN] } }`). Every file of a skill's folder, binary included (not `.git/`, `node_modules/`, OS files like `.DS_Store`, or `.env` and `.env.*` files, which hold secrets), is part of the definition: the manifest names each one by path and SHA-256 (`skills.<name>.files`). A skill's files may hold together at most the Tenant's skill limit (`PUT /v1/tenant/skills`, default 2 GiB); no file and no count of files has a limit of its own, and a manifest's runtime section may set a lower limit for its Agents' sessions (`runtime.limits.skills.totalBytes`). Skills need a sandbox: the runtime section's kind is `virtual` or `pod`, which the Runtime checks when the manifest is saved. `agentManifests.save` uploads the files the Runtime does not hold (`client.files`, `PUT /v1/files/sha256:<hex>`) before it saves the manifest, which the Runtime refuses while it names a file it lacks (`400 definition_files_missing`) or a skill past the Tenant's limit (`413 limit_exceeded`). `read_skill_resource` reads files of up to 10 MiB into the model's context; a larger one is used in the sandbox.
 
 The Runtime serves the skills itself, with no call to your process. When our harness runs a turn, it adds the skill catalog to the instructions and two tools: `load_skill` returns a skill's `SKILL.md` body and the paths of its other files, and `read_skill_resource` returns a text file. A session with a sandbox also has each skill's files read-only under `/skills/<name>@<hash>/`, so the model can run a skill's scripts with `bash`.
 
@@ -301,12 +307,13 @@ await client.agents.secrets.put("users/alice/analyst", "GH_TOKEN", { value: proc
 const session = await client.createSession({ id: "alice-q3", agent: "users/alice/analyst", ownerUserId: "alice" });
 ```
 
-`agentManifests.save(input, { ifMatch, requestId })` and `plan(input, { ifMatch })` (a dry run that saves nothing) take a v8 document, what `composeManifest` read, or `{ agent, runtime?, harness?, loop?, memory?, name?, description?, metadata? }`: the SDK makes the harness section from the built agent or flow (`harnessSectionOf`, with its skills' `secrets`; `harness` is the harness's id; `memory`, `{ access?, instructions? }`, turns on an agent's memory, not a flow's) and names the manifest after the agent's id. First it uploads every file the manifest names by hash that the Runtime does not hold: the agent's skills, a flow's agents' skills, and the runtime's files (`runtimeFiles(path, contents)` hashes a `files` entry; pass its `bytes` as `files`). `If-Match` is the version you read (`0` for a new manifest). A save that changes nothing answers the latest version, `unchanged`. `get(name, version?)`, `list()`, `versions(name)` (with the Agents made from each) and `delete(name)` (refused while an Agent was made from it: `409 manifest_in_use`) read and remove them.
+`agentManifests.save(input, { ifMatch, requestId })` and `plan(input, { ifMatch })` (a dry run that saves nothing) take a v8 document, what `composeManifest` read, or `{ agent, runtime?, harness?, loop?, memory?, name?, description?, metadata? }`: the SDK makes the harness section from the built agent or flow (`harnessSectionOf`, exported for code that builds a manifest itself, with its skills' `secrets`; `harness` is the harness's id; `memory`, `{ access?, instructions? }`, turns on an agent's memory, not a flow's) and names the manifest after the agent's id. First it uploads every file the manifest names by hash that the Runtime does not hold: the agent's skills, a flow's agents' skills, and the runtime's files (`runtimeFiles(path, contents)` hashes a `files` entry; pass its `bytes` as `files`). `If-Match` is the version you read (`0` for a new manifest). A save that changes nothing answers the latest version, `unchanged`. `get(name, version?)`, `list()`, `versions(name)` (with the Agents made from each) and `delete(name)` (refused while an Agent was made from it: `409 manifest_in_use`) read and remove them.
 
 ### Agent folders: `packFolder`, `checkFolder`, `saveFolder`
 
-An agent can be a folder of Markdown and JSON (track T6): `AGENT.md` with `name`, `description` and the instructions, and beside it `mcp.json`, `runtime.json`, `skills/`, `tools/`, `triggers/` and `files/` as it needs them. `packFolder(dir)` (Node only) lists every file with its size and SHA-256, skipping `.git` and `node_modules`; `checkFolder(folder)` compiles it offline with the Runtime's compiler (`@nylorun/core/folder`) and returns `{ manifest?, diagnostics, compiler }`, each diagnostic with its file, line and column (`diagnosticLine` formats one). `agentManifests.saveFolder(folder, { ifMatch })` and `planFolder` compile it first, refuse one that does not compile (`FolderInvalidError`), upload the files the Runtime lacks and send the folder by hash; the Runtime keeps it as the version's source, which `source(name, version)` and `sourceFile(name, version, path)` read back.
+An agent is best written as a folder of Markdown and JSON (tracks T6 and T7): `AGENT.md` with `name`, `description` and the instructions, and beside it `mcp.json`, `runtime.json`, `skills/`, `tools/`, `triggers/` and `files/` as it needs them. `agents/<id>/` holds subagents (each offered to the agent as a tool), `flow.json` makes the folder a flow whose stages name those agents by id, and `plugins/<name>/` vendors an Agent Plugin; [the CLI's README](../../cli/nylorun/README.md#agent-manifests-apply) shows each. `packFolder(dir)` (Node only) lists every file with its size and SHA-256, skipping `.git`, `node_modules` and what the folder's `.nyloignore` names (gitignore rules, `ignoreMatcher`), and resolves `"extends"` in `runtime.json` (the packed file is the merge, the folder's own keys winning); `checkFolder(folder)` compiles it offline with the Runtime's compiler (`@nylorun/core/folder`) and returns `{ manifest?, diagnostics, compiler }`, each diagnostic with its file, line and column (`diagnosticLine` formats one). `agentManifests.saveFolder(folder, { ifMatch })` and `planFolder` compile it first, refuse one that does not compile (`FolderInvalidError`), upload the files the Runtime lacks and send the folder by hash; the Runtime keeps it as the version's source, which `source(name, version)` and `sourceFile(name, version, path)` read back, and `sourceDiff(name, from, to)` compares two versions' sources: the files added, removed and changed, by hash. `folderOfManifest(manifest)` goes the other way: the folder that compiles back to a saved manifest (what `nylorun export --folder` writes).
 
+<!-- doc-test: typescript -->
 ```ts
 import { createClient, packFolder } from "@nylorun/agents";
 
@@ -316,9 +323,11 @@ console.log(plan.manifest, plan.diagnostics); // the compiled manifest, and e.g.
 await client.agentManifests.saveFolder(await packFolder("agents/triage"), { ifMatch: plan.from ?? 0 });
 ```
 
-### Three files: `composeManifest`
+### Three files: `composeManifest` (deprecated)
 
-A manifest can also be authored as files, so a runtime is shared by many agents and skills stay folders. `composeManifest(dir)` (Node only) reads `<dir>/agent.manifest.json` and the files it names, each path relative to the file that names it, and returns `{ manifest, files, gaps, warnings }`; `agentManifests.save` takes it as it is and uploads `files`. `npx nylorun apply <dir>` does the same from the command line.
+The three-file form is deprecated in favour of agent folders: `composeManifest` and `nylorun apply` still read it, and warn, and `npx nylorun migrate folder <dir>` writes the agent folder of a three-file folder, with its skills, offline. A folder's `runtime.json` shares a runtime between agents with `"extends"`.
+
+A manifest can be authored as three files, so a runtime is shared by many agents and skills stay folders. `composeManifest(dir)` (Node only) reads `<dir>/agent.manifest.json` and the files it names, each path relative to the file that names it, and returns `{ manifest, files, gaps, warnings }`; `agentManifests.save` takes it as it is and uploads `files`. `npx nylorun apply <dir>` does the same from the command line.
 
 ```jsonc
 // agents/triage/agent.manifest.json
@@ -413,7 +422,12 @@ the manifest, then `createSession({ agent })` and `session.input(value)`. `input
 `content` and other JSON as `data`. On the wire a flow agent is a workflow manifest v3
 (`kind: "workflow"`, `workflowSchemaVersion: 3`) that embeds the agents it runs, so one
 document and one manifest hash cover the whole flow; its agents are not listed on their own.
-In an agent manifest it is the harness section, `harness.kind: "workflow"`.
+In an agent manifest it is the harness section, `harness.kind: "workflow"`. A flow can also
+be an [agent folder](#agent-folders-packfolder-checkfolder-savefolder): `flow.json` holds the
+same node tree, naming its agents (each an `agents/<id>/` folder) by id, and the compiler
+embeds each agent where the manifest needs it
+([`examples/agents/repo-brief-folder/`](../../examples/agents/repo-brief-folder/) is the Repo
+brief flow as a folder).
 
 A flow passes data between its stages itself: the first stage gets the flow's input, and
 every later stage gets the previous stage's output. So each agent returns, through its
@@ -542,7 +556,7 @@ default release registry). Host contract:
 [HOST_CONTRACT.md](../../runtime/harness/HOST_CONTRACT.md). Vocabulary (turn loop vs
 workflow Loop): [runtime/harness/src/CONTEXT.md](../../runtime/harness/src/CONTEXT.md).
 
-Use `session.observe({ cursor, signal })` for resumable canonical events, `session.inspect()` for waiting/uncertain state, and `approve`, `respond`, or `cancel` with an explicit stable idempotency key. Retry the same semantic command with the same key. `ownerUserId` must come from trusted server authentication. Application credentials are not browser credentials; browser applications need an authorized backend. Definition authoring is browser-bundleable.
+Use `session.observe({ cursor, signal })` for resumable canonical events, `session.inspect()` for waiting/uncertain state, and `approve`, `respond` or `cancel` to answer or stop a turn. `cancel` takes an idempotency key; `approve(interactionId, approved)` and `respond(interactionId, value)` make one of their own when given none, so give them a stable one (`{ idempotencyKey }`) when you may retry. Retry the same semantic command with the same key. `ownerUserId` must come from trusted server authentication. Application credentials are not browser credentials; browser applications need an authorized backend. Definition authoring is browser-bundleable.
 
 Connection defaults follow `resolveConnection` (options → environment → Project
 link). Agents do not hash the manifest; a session pins the manifest version its Agent runs

package/dist/agent-manifests.d.ts

@@ -19,7 +19,7 @@
  * upload its files by hash, and send the folder, which the Runtime compiles again and keeps as the
  * version's source.
  */
-import { AGENT_MANIFEST_V8_SCHEMA_VERSION, type AgentManifestPlan, type AgentManifestSource, type AgentManifestV8, type AgentMemorySettings, type AgentManifestVersions, type AgentManifestView, type DeleteAgentManifestResponse, type RuntimeSection, type SaveAgentManifestResponse } from "@nylorun/core/contracts";
+import { AGENT_MANIFEST_V8_SCHEMA_VERSION, type AgentManifestPlan, type AgentManifestSource, type AgentManifestSourceDiff, type AgentManifestV8, type AgentMemorySettings, type AgentManifestVersions, type AgentManifestView, type DeleteAgentManifestResponse, type RuntimeSection, type SaveAgentManifestResponse } from "@nylorun/core/contracts";
 import { type AgentManifest, type BuiltAgent, type BuiltWorkflow, type JsonObject, type SkillFileSource, type WorkflowManifest } from "@nylorun/core/define";
 import { type PackedFolder } from "./folder.js";
 import { type Transport } from "./http.js";
@@ -136,6 +136,13 @@ export declare class AgentManifestsClient {
     sourceFile(name: string, version: number, path: string, options?: {
         signal?: AbortSignal;
     }): Promise<Uint8Array>;
+    /**
+     * What changed from version `from`'s source to version `to`'s: the files added, removed and
+     * changed by path and hash. A version saved as JSON has no source (`404`).
+     */
+    sourceDiff(name: string, from: number, to: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentManifestSourceDiff>;
     /** The latest version of manifest `name`, or version `version`. */
     get(name: string, version?: number, options?: {
         signal?: AbortSignal;

package/dist/agent-manifests.js

@@ -262,6 +262,14 @@ export class AgentManifestsClient {
         });
         return new Uint8Array(await response.arrayBuffer());
     }
+    /**
+     * What changed from version `from`'s source to version `to`'s: the files added, removed and
+     * changed by path and hash. A version saved as JSON has no source (`404`).
+     */
+    async sourceDiff(name, from, to, options = {}) {
+        const query = new URLSearchParams({ from: String(from), to: String(to) });
+        return this.transport.json(`${this.path(name)}/source/diff?${query}`, "GET", undefined, options.signal);
+    }
     /** The latest version of manifest `name`, or version `version`. */
     async get(name, version, options = {}) {
         return this.transport.json(`${this.path(name)}${version === undefined ? "" : `/versions/${version}`}`, "GET", undefined, options.signal);

package/dist/compose.d.ts

@@ -6,6 +6,11 @@ export declare class ComposeError extends Error {
     readonly path: string;
     constructor(path: string, message: string);
 }
+/**
+ * The warning every three-file folder gets (D80): agent folders replace it. It is still read, and
+ * removed in a later release.
+ */
+export declare function threeFileDeprecation(dir: string): string;
 /**
  * Composes the agent manifest in `dir` (its `agent.manifest.json`, or `options.file`): the v8
  * document to save, the bytes of every file it names by hash (skills, plugins' skills, runtime

package/dist/compose.js

@@ -16,10 +16,13 @@
  *   `{ path, files }`.
  *
  * Each path is relative to the file that names it. Node only: it reads the files.
+ *
+ * Deprecated (D80): agent folders (`AGENT.md`) replace the three files, and every composed
+ * manifest carries a warning naming `nylorun migrate folder`. It is still read.
  */
 import { existsSync, statSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
-import { dirname, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { AGENT_MANIFEST_V8_SCHEMA_VERSION, AgentManifestFileSchema, AgentManifestV8Schema, HarnessManifestFileSchema, RuntimeManifestFileSchema, WorkflowHarnessSectionSchema, } from "@nylorun/core/contracts";
 import { sectionGaps } from "@nylorun/core/define";
 import { requirementGaps } from "./agent-manifests.js";
@@ -198,6 +201,15 @@ function agentHarness(file, base, where, files, warnings) {
         ...(file.memory === undefined ? {} : { memory: file.memory }),
     };
 }
+/**
+ * The warning every three-file folder gets (D80): agent folders replace it. It is still read, and
+ * removed in a later release.
+ */
+export function threeFileDeprecation(dir) {
+    const inside = relative(process.cwd(), dir);
+    const where = inside === "" ? "." : inside.startsWith("..") || isAbsolute(inside) ? dir : inside;
+    return `${AGENT_MANIFEST_FILE} (the three-file format) is deprecated: nylorun migrate folder ${where} writes it as an agent folder (AGENT.md), which saves the same manifest. It is still read until a later release.`;
+}
 /**
  * Composes the agent manifest in `dir` (its `agent.manifest.json`, or `options.file`): the v8
  * document to save, the bytes of every file it names by hash (skills, plugins' skills, runtime
@@ -210,7 +222,7 @@ export async function composeManifest(dir, options = {}) {
     const base = dirname(agentFile);
     const authored = await readFileAs(agentFile, AgentManifestFileSchema, relativeTo(agentFile));
     const files = new Map();
-    const warnings = [];
+    const warnings = [threeFileDeprecation(base)];
     const runtime = authored.runtime === undefined ? undefined : await runtimeSection(authored.runtime, base, agentFile, files, warnings);
     let harness;
     let requires;

package/dist/folder-check.d.ts

@@ -5,6 +5,8 @@
  */
 import { type CompiledAgentFolder } from "@nylorun/core/folder";
 import type { PackedFolder } from "./folder.js";
+/** The agent folder of a manifest (track T7): what `nylorun export --folder` writes. */
+export { folderOfManifest, type FolderOfManifest, type FolderOfManifestOptions } from "@nylorun/core/folder";
 /**
  * Compiles a packed folder offline, as the Runtime will: the manifest when it compiles, and every
  * diagnostic either way. With `name`, the name it will be saved as, `AGENT.md`'s must match.

package/dist/folder-check.js

@@ -4,6 +4,8 @@
  * module only when a folder is sent.
  */
 import { AGENT_FOLDER_LIMITS, compileAgentFolder, folderTextPaths, } from "@nylorun/core/folder";
+/** The agent folder of a manifest (track T7): what `nylorun export --folder` writes. */
+export { folderOfManifest } from "@nylorun/core/folder";
 /**
  * Compiles a packed folder offline, as the Runtime will: the manifest when it compiles, and every
  * diagnostic either way. With `name`, the name it will be saved as, `AGENT.md`'s must match.

package/dist/folder-ignore.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `.nyloignore` (track T7): the files `packFolder` leaves out of an agent folder, in gitignore
+ * syntax. Blank lines and `#` comments are skipped; `!` re-includes what an earlier line left out;
+ * a trailing `/` matches directories only; a pattern with a `/` before its end is anchored at the
+ * folder, and one without matches a name at any depth; `*`, `?`, `[…]` and `**` glob as in git.
+ * The last line that matches decides, and nothing below a directory left out comes back, as in
+ * git. Pure: no Node module, so it also reads a project's `.gitignore`.
+ */
+/**
+ * A matcher for an ignore file's text: whether `path` (relative, `/` between segments) is left
+ * out, a directory when `directory` is true. A path below a directory left out is left out too.
+ */
+export declare function ignoreMatcher(text: string): (path: string, directory?: boolean) => boolean;

package/dist/folder-ignore.js

@@ -0,0 +1,113 @@
+/**
+ * `.nyloignore` (track T7): the files `packFolder` leaves out of an agent folder, in gitignore
+ * syntax. Blank lines and `#` comments are skipped; `!` re-includes what an earlier line left out;
+ * a trailing `/` matches directories only; a pattern with a `/` before its end is anchored at the
+ * folder, and one without matches a name at any depth; `*`, `?`, `[…]` and `**` glob as in git.
+ * The last line that matches decides, and nothing below a directory left out comes back, as in
+ * git. Pure: no Node module, so it also reads a project's `.gitignore`.
+ */
+/** A glob's body as a regular expression's source: `*` and `?` stop at `/`, `**` crosses it. */
+function globSource(glob) {
+    let source = "";
+    for (let index = 0; index < glob.length; index += 1) {
+        const char = glob[index];
+        if (char === "\\" && index + 1 < glob.length) {
+            source += escapeChar(glob[++index]);
+            continue;
+        }
+        if (char === "*") {
+            if (glob[index + 1] === "*") {
+                const before = index === 0 || glob[index - 1] === "/";
+                const after = index + 2 === glob.length || glob[index + 2] === "/";
+                if (before && after) {
+                    if (index + 2 === glob.length)
+                        source += ".*"; // `a/**`: everything inside
+                    else {
+                        source += "(?:.*/)?"; // `**/` and `/**/`: zero or more directories
+                        index += 1; // the `/` after `**`
+                    }
+                    index += 1;
+                    continue;
+                }
+            }
+            source += "[^/]*";
+            continue;
+        }
+        if (char === "?") {
+            source += "[^/]";
+            continue;
+        }
+        if (char === "[") {
+            const end = glob.indexOf("]", index + 2);
+            if (end > 0) {
+                let body = glob.slice(index + 1, end);
+                if (body.startsWith("!"))
+                    body = `^${body.slice(1)}`;
+                source += `[${body.replace(/\\/g, "\\\\")}]`;
+                index = end;
+                continue;
+            }
+        }
+        source += escapeChar(char);
+    }
+    return source;
+}
+const escapeChar = (char) => char.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+/** The rules of an ignore file's text. */
+function parseIgnore(text) {
+    const rules = [];
+    for (const raw of text.split(/\r?\n/)) {
+        // Trailing spaces go, unless the last is escaped.
+        let line = raw.replace(/(?<!\\)\s+$/, "");
+        if (line === "" || line.startsWith("#"))
+            continue;
+        let negate = false;
+        if (line.startsWith("!")) {
+            negate = true;
+            line = line.slice(1);
+        }
+        else if (line.startsWith("\\!") || line.startsWith("\\#"))
+            line = line.slice(1);
+        const directoryOnly = line.endsWith("/");
+        if (directoryOnly)
+            line = line.slice(0, -1);
+        if (line === "")
+            continue;
+        const anchored = line.includes("/");
+        if (line.startsWith("/"))
+            line = line.slice(1);
+        const body = globSource(line);
+        rules.push({
+            negate,
+            directoryOnly,
+            pattern: new RegExp(anchored ? `^${body}$` : `(?:^|/)${body}$`),
+        });
+    }
+    return rules;
+}
+/**
+ * A matcher for an ignore file's text: whether `path` (relative, `/` between segments) is left
+ * out, a directory when `directory` is true. A path below a directory left out is left out too.
+ */
+export function ignoreMatcher(text) {
+    const rules = parseIgnore(text);
+    const decide = (path, directory) => {
+        let ignored = false;
+        for (const rule of rules) {
+            if (rule.directoryOnly && !directory)
+                continue;
+            if (rule.negate === ignored && rule.pattern.test(path))
+                ignored = !rule.negate;
+        }
+        return ignored;
+    };
+    return (path, directory = false) => {
+        if (rules.length === 0)
+            return false;
+        const segments = path.split("/");
+        for (let depth = 1; depth < segments.length; depth += 1)
+            if (decide(segments.slice(0, depth).join("/"), true))
+                return true;
+        return decide(path, directory);
+    };
+}

package/dist/folder-pack.d.ts

@@ -1,4 +1,6 @@
 import { type PackedFolder } from "./folder.js";
+/** The file, at a folder's top, that names what packing leaves out (gitignore syntax). */
+export declare const FOLDER_IGNORE_FILE = ".nyloignore";
 /** Whether `dir` holds an `AGENT.md`. */
 export declare function isAgentFolder(dir: string): Promise<boolean>;
 /** Lists the agent folder at `dir` with each file's size and SHA-256. */

package/dist/folder-pack.js

@@ -1,24 +1,110 @@
 /**
  * Packing an agent folder (track T6): `packFolder(dir)` lists every file with its size and SHA-256
- * and reads its bytes on demand. It skips `.git`, `.hg`, `.svn` and `node_modules` and follows no
- * symbolic link. Node only: it reads the folder.
+ * and reads its bytes on demand. It skips `.git`, `.hg`, `.svn` and `node_modules`, what the
+ * folder's `.nyloignore` names (gitignore rules, `folder-ignore.ts`; track T7), and follows no
+ * symbolic link.
+ *
+ * `extends` in `runtime.json` (track T7, design §3.9) names a shared JSON file, inside the folder
+ * or outside it, by a path relative to the file that names it. The packed `runtime.json` is the
+ * merge, the folder's own keys winning (objects merge, arrays replace), so every saved version is
+ * self-contained and its source is what was sent; `.nylorun/origin.json` in the pack names the
+ * files it was merged from. A chain of `extends` resolves in turn; a cycle, a missing file or
+ * one that is not a JSON object is a `FolderError`. Node only: it reads the folder.
  */
 import { createHash } from "node:crypto";
 import { readdir, readFile, stat } from "node:fs/promises";
-import { join, relative, resolve, sep } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { AGENT_FOLDER_LIMITS } from "@nylorun/core/folder";
 import { AGENT_FOLDER_FILE, FolderError } from "./folder.js";
+import { ignoreMatcher } from "./folder-ignore.js";
 const SKIPPED_DIRECTORIES = new Set([".git", ".hg", ".svn", "node_modules"]);
+/** The file, at a folder's top, that names what packing leaves out (gitignore syntax). */
+export const FOLDER_IGNORE_FILE = ".nyloignore";
+const RUNTIME_FILE = "runtime.json";
+const ORIGIN_FILE = ".nylorun/origin.json";
 /** Whether `dir` holds an `AGENT.md`. */
 export async function isAgentFolder(dir) {
     return stat(join(dir, AGENT_FOLDER_FILE)).then((found) => found.isFile(), () => false);
 }
+const sha256 = (data) => createHash("sha256").update(data).digest("hex");
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+/** `over` merged onto `under`: `over`'s keys win, objects merge, arrays and the rest replace. */
+function merge(under, over) {
+    const merged = { ...under };
+    for (const [key, value] of Object.entries(over)) {
+        const below = merged[key];
+        merged[key] = isObject(below) && isObject(value) ? merge(below, value) : value;
+    }
+    return merged;
+}
+/**
+ * `runtime.json` with its `extends` resolved, and each file it was merged from (absolute paths,
+ * nearest first); undefined when it says no `extends`, or is not a JSON object (the compiler
+ * reports that with its position).
+ */
+async function resolveExtends(root, text) {
+    let local;
+    try {
+        local = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isObject(local) || !("extends" in local))
+        return undefined;
+    const shown = (file) => relative(root, file).split(sep).join("/");
+    const chain = [join(root, RUNTIME_FILE)];
+    const layers = [];
+    let current = local;
+    for (;;) {
+        const { extends: target, ...own } = current;
+        // The extended file's `$schema` names that file's kind; the folder's own file has none.
+        if (layers.length > 0)
+            delete own.$schema;
+        layers.push(own);
+        if (target === undefined)
+            break;
+        const from = chain.at(-1);
+        if (typeof target !== "string" || target.trim() === "")
+            throw new FolderError(root, `${shown(from)}: extends is the path of a JSON file, such as "../../platform/pod.runtime.json"`);
+        const file = resolve(dirname(from), target);
+        if (chain.includes(file))
+            throw new FolderError(root, `${RUNTIME_FILE}: extends makes a cycle: ${[...chain, file].map(shown).join(" → ")}`);
+        let body;
+        try {
+            body = await readFile(file, "utf8");
+        }
+        catch (error) {
+            const code = error.code;
+            throw new FolderError(root, code === "ENOENT"
+                ? `${shown(from)}: extends ${target}, which does not exist (${file})`
+                : `${shown(from)}: cannot read ${target}, which it extends: ${code ?? error}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch (error) {
+            throw new FolderError(root, `${shown(file)}, which ${shown(from)} extends, is not JSON: ${error.message}`);
+        }
+        if (!isObject(parsed))
+            throw new FolderError(root, `${shown(file)}, which ${shown(from)} extends, is not a JSON object`);
+        chain.push(file);
+        current = parsed;
+    }
+    // The farthest file first, each nearer one over it.
+    const value = layers.reduceRight((under, layer) => merge(under, layer), {});
+    return { value, from: chain.slice(1) };
+}
 /** Lists the agent folder at `dir` with each file's size and SHA-256. */
 export async function packFolder(dir) {
     const root = resolve(dir);
     const entries = [];
     const files = new Map();
     const skipped = [];
+    const ignoreText = await readFile(join(root, FOLDER_IGNORE_FILE), "utf8").catch(() => undefined);
+    const ignored = ignoreText === undefined ? () => false : ignoreMatcher(ignoreText);
     let bytes = 0;
     const walk = async (at) => {
         const children = await readdir(at, { withFileTypes: true }).catch((error) => {
@@ -28,10 +114,12 @@ export async function packFolder(dir) {
             const full = join(at, child.name);
             const path = relative(root, full).split(sep).join("/");
             if (child.isDirectory()) {
-                if (!SKIPPED_DIRECTORIES.has(child.name))
+                if (!SKIPPED_DIRECTORIES.has(child.name) && !ignored(path, true))
                     await walk(full);
                 continue;
             }
+            if (ignored(path))
+                continue;
             if (child.isSymbolicLink()) {
                 skipped.push(`${path}: a symbolic link, not followed`);
                 continue;
@@ -44,11 +132,33 @@ export async function packFolder(dir) {
             bytes += data.byteLength;
             if (bytes > AGENT_FOLDER_LIMITS.totalBytes)
                 throw new FolderError(root, `${dir} holds more than ${AGENT_FOLDER_LIMITS.totalBytes} bytes, an agent folder's limit`);
-            entries.push({ path, size: data.byteLength, sha256: createHash("sha256").update(data).digest("hex") });
+            entries.push({ path, size: data.byteLength, sha256: sha256(data) });
             files.set(path, { size: data.byteLength, read: () => readFile(full) });
         }
     };
     await walk(root);
-    entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
-    return { dir: root, entries, files, skipped };
+    // `extends`: the packed runtime.json is the merge, and origin.json names what it came from.
+    let extended;
+    const runtime = files.get(RUNTIME_FILE);
+    if (runtime && runtime.size <= AGENT_FOLDER_LIMITS.textFileBytes) {
+        const resolved = await resolveExtends(root, new TextDecoder().decode(await runtime.read()));
+        if (resolved) {
+            extended = resolved.from;
+            const put = (path, text) => {
+                const data = new TextEncoder().encode(text);
+                const at = entries.findIndex((entry) => entry.path === path);
+                const entry = { path, size: data.byteLength, sha256: sha256(data) };
+                if (at < 0)
+                    entries.push(entry);
+                else
+                    entries[at] = entry;
+                files.set(path, { size: data.byteLength, read: async () => data });
+            };
+            put(RUNTIME_FILE, `${JSON.stringify(resolved.value, null, 2)}\n`);
+            const relativeTo = (file) => relative(root, file).split(sep).join("/");
+            put(ORIGIN_FILE, `${JSON.stringify({ [RUNTIME_FILE]: { extends: resolved.from.map(relativeTo) } }, null, 2)}\n`);
+        }
+    }
+    entries.sort(byPath);
+    return { dir: root, entries, files, skipped, ...(extended ? { extended } : {}) };
 }

package/dist/folder.d.ts

@@ -22,8 +22,16 @@ export interface PackedFolder {
     readonly files: ReadonlyMap<string, SkillFileSource>;
     /** What packing left out, and why (a symbolic link). */
     readonly skipped: readonly string[];
+    /**
+     * The files `runtime.json` was merged from (its `extends`, nearest first), as absolute paths;
+     * absent when it extends none.
+     */
+    readonly extended?: readonly string[];
 }
-/** A folder that cannot be packed: too many files, or more bytes than an agent folder holds. */
+/**
+ * A folder that cannot be packed: too many files, more bytes than an agent folder holds, or an
+ * `extends` in `runtime.json` that does not resolve.
+ */
 export declare class FolderError extends Error {
     readonly dir: string;
     constructor(dir: string, message: string);

package/dist/folder.js

@@ -1,6 +1,9 @@
 /** The file that makes a folder an agent folder. */
 export const AGENT_FOLDER_FILE = "AGENT.md";
-/** A folder that cannot be packed: too many files, or more bytes than an agent folder holds. */
+/**
+ * A folder that cannot be packed: too many files, more bytes than an agent folder holds, or an
+ * `extends` in `runtime.json` that does not resolve.
+ */
 export class FolderError extends Error {
     dir;
     constructor(dir, message) {

package/dist/index.d.ts

@@ -3,11 +3,11 @@ export type { ProtocolFeature, ProtocolRange, Compatibility, ErrorCode, } from "
 export { checkHealth, describeIncompatibility, parseProtocolRange, } from "@nylorun/core/transport";
 export type { HealthCheck, Incompatibility } from "@nylorun/core/transport";
 export { Agent, AgentBuilder } from "./builder.js";
-export { AgentBuildError, AgentLifecycleError, VerdictSchema, isVerdict, WorkflowBuildError, isBuiltWorkflow, flow, tool, http, defineSchema, ToolError, } from "@nylorun/core/define";
+export { AgentBuildError, AgentLifecycleError, VerdictSchema, isVerdict, WorkflowBuildError, isBuiltWorkflow, flow, tool, http, defineSchema, ToolError, harnessSectionOf, sectionGaps, } from "@nylorun/core/define";
 export type { FlowAgentBuilder, Flow, Named, LoopOptions, StageOptions, HttpTarget, } from "@nylorun/core/define";
 export type { AgentOptions, AgentManifest, BuiltAgent, BuiltWorkflow, Verdict, WorkflowBinding, WorkflowManifest, ToolDefinition, ToolExecutionContext, ToolOutcome, JsonValue, JsonObject, } from "@nylorun/core/define";
-export type { SessionPage, SessionListItem, SessionManifestView, HistoryPage, SessionUsageTotals, CostSplit, ModelCall, ModelCallsPage, AgentPage, ToolCall, ToolCallsPage, LiveEvent, SessionEvent, SessionEventOf, EventType, SessionCommand, SubjectScope, AgentView, AgentState, AgentAttention, AgentEvent, AgentEventType, EgressRunningTurn, EnvironmentKind, EnvironmentRecipe, EnvironmentSecretSlot, AgentSecretView, AgentSnapshot, AgentRestore, AgentDiskVersions, RestoreAgentRequest, AgentForkPlan, AgentMovePlan, RestartAgentRequest, ForkAgentRequest, ForkAgentResponse, DeleteAgentResponse, PutAgentRequest, PutAgentSecretRequest, AgentManifestV8, AgentManifestFile, HarnessManifestFile, RuntimeManifestFile, RuntimeSection, AgentManifestChange, AgentManifestWarning, AgentManifestPlan, AgentManifestView, AgentManifestVersions, SaveAgentManifestResponse, DeleteAgentManifestResponse, MessagePart, ArtifactView, ArtifactKind, ArtifactListItem, ArtifactPage, ArtifactVersionView, ArtifactLink, UploadArtifactResponse, DefinitionFileView, ArtifactTree, ArtifactDiff, FolderEntry, } from "@nylorun/core/contracts";
-export { AGENT_EVENT_TYPES, AGENT_STATES, COMPUTE_STATES, RUNTIME_LIMIT_DEFAULTS, SUBJECT_SCOPES, } from "@nylorun/core/contracts";
+export type { SessionPage, SessionListItem, SessionManifestView, HistoryPage, SessionUsageTotals, CostSplit, ModelCall, ModelCallsPage, AgentPage, ToolCall, ToolCallsPage, LiveEvent, SessionEvent, SessionEventOf, EventType, SessionCommand, SubjectScope, AgentView, AgentState, AgentAttention, AgentEvent, AgentEventType, EgressRunningTurn, EnvironmentKind, EnvironmentRecipe, EnvironmentSecretSlot, AgentSecretView, AgentSnapshot, AgentRestore, AgentDiskVersions, RestoreAgentRequest, AgentForkPlan, AgentMovePlan, RestartAgentRequest, ForkAgentRequest, ForkAgentResponse, DeleteAgentResponse, PutAgentRequest, PutAgentSecretRequest, AgentManifestV8, AgentManifestFile, HarnessManifestFile, RuntimeManifestFile, RuntimeSection, AgentManifestChange, AgentManifestWarning, AgentManifestPlan, AgentManifestSource, AgentManifestSourceDiff, AgentManifestSourceSummary, AgentFolderDiagnostic, AgentManifestView, AgentManifestVersions, SaveAgentManifestResponse, DeleteAgentManifestResponse, MessagePart, ArtifactView, ArtifactKind, ArtifactListItem, ArtifactPage, ArtifactVersionView, ArtifactLink, UploadArtifactResponse, DefinitionFileView, ArtifactTree, ArtifactDiff, FolderEntry, } from "@nylorun/core/contracts";
+export { AGENT_EVENT_TYPES, AGENT_FOLDER_MEDIA_TYPE, AGENT_STATES, COMPUTE_STATES, RUNTIME_LIMIT_DEFAULTS, SUBJECT_SCOPES, } from "@nylorun/core/contracts";
 export type { AgentHarnessSection, HarnessSection, HarnessSkill, HarnessMcpServer, WorkflowHarnessSection, } from "@nylorun/core";
 export { AgentsClient, SessionClient, createClient } from "./client.js";
 export { ArtifactsClient } from "./artifacts.js";
@@ -17,9 +17,10 @@ export type { ActAsOptions, AgentSource, SessionView, CommandOptions, CreateSess
 export { AgentInstancesClient, AgentManifestsClient, AgentMemoriesClient, AgentSecretsClient, ManifestGapsError, agentManifest, requirementGaps, runtimeFiles, } from "./client.js";
 export { composeManifest, manifestFolders, ComposeError, AGENT_MANIFEST_FILE } from "./compose.js";
 export { AGENT_FOLDER_FILE, FolderError, FolderInvalidError, diagnosticLine } from "./folder.js";
-export { checkFolder } from "./folder-check.js";
+export { checkFolder, folderOfManifest, type FolderOfManifest, type FolderOfManifestOptions } from "./folder-check.js";
 export type { PackedFolder } from "./folder.js";
-export { packFolder, isAgentFolder } from "./folder-pack.js";
+export { packFolder, isAgentFolder, FOLDER_IGNORE_FILE } from "./folder-pack.js";
+export { ignoreMatcher } from "./folder-ignore.js";
 export { AccessClient } from "./access.js";
 export { resolveConnection, ConnectionError } from "./connection.js";
 export type { ResolvedConnection } from "./connection.js";

package/dist/index.js

@@ -3,16 +3,20 @@ export { hashManifest, PROTOCOL_VERSION, PROTOCOL_FEATURES, HOST_PROTOCOL, DEFIN
 // The `/health` compatibility probe every Runtime client shares (Studio's server uses it).
 export { checkHealth, describeIncompatibility, parseProtocolRange, } from "@nylorun/core/transport";
 export { Agent, AgentBuilder } from "./builder.js";
-export { AgentBuildError, AgentLifecycleError, VerdictSchema, isVerdict, WorkflowBuildError, isBuiltWorkflow, flow, tool, http, defineSchema, ToolError, } from "@nylorun/core/define";
-export { AGENT_EVENT_TYPES, AGENT_STATES, COMPUTE_STATES, RUNTIME_LIMIT_DEFAULTS, SUBJECT_SCOPES, } from "@nylorun/core/contracts";
+export { AgentBuildError, AgentLifecycleError, VerdictSchema, isVerdict, WorkflowBuildError, isBuiltWorkflow, flow, tool, http, defineSchema, ToolError, 
+// The harness section `agentManifests.save` makes from a built agent or flow, and the gaps the
+// Runtime refuses between a manifest's two sections, for code that builds a manifest itself.
+harnessSectionOf, sectionGaps, } from "@nylorun/core/define";
+export { AGENT_EVENT_TYPES, AGENT_FOLDER_MEDIA_TYPE, AGENT_STATES, COMPUTE_STATES, RUNTIME_LIMIT_DEFAULTS, SUBJECT_SCOPES, } from "@nylorun/core/contracts";
 export { AgentsClient, SessionClient, createClient } from "./client.js";
 export { ArtifactsClient } from "./artifacts.js";
 export { FilesClient, definitionFileHash } from "./files.js";
 export { AgentInstancesClient, AgentManifestsClient, AgentMemoriesClient, AgentSecretsClient, ManifestGapsError, agentManifest, requirementGaps, runtimeFiles, } from "./client.js";
 export { composeManifest, manifestFolders, ComposeError, AGENT_MANIFEST_FILE } from "./compose.js";
 export { AGENT_FOLDER_FILE, FolderError, FolderInvalidError, diagnosticLine } from "./folder.js";
-export { checkFolder } from "./folder-check.js";
-export { packFolder, isAgentFolder } from "./folder-pack.js";
+export { checkFolder, folderOfManifest } from "./folder-check.js";
+export { packFolder, isAgentFolder, FOLDER_IGNORE_FILE } from "./folder-pack.js";
+export { ignoreMatcher } from "./folder-ignore.js";
 export { AccessClient } from "./access.js";
 export { resolveConnection, ConnectionError } from "./connection.js";
 export { RuntimeError, IncompatibleRuntimeError } from "./http.js";

package/dist/plugins/load.js

@@ -291,7 +291,8 @@ function realInside(root, candidate) {
         return undefined;
     try {
         const real = realpathSync(candidate);
-        return isInside(root, real) ? real : undefined;
+        // Both sides real: a package under a symlinked directory (macOS's /var → /private/var) is inside itself.
+        return isInside(realpathSync(root), real) ? real : undefined;
     }
     catch {
         return undefined;

package/dist/session-client.d.ts

@@ -152,7 +152,8 @@ export declare class SessionClient {
         cursor: string | null;
         requestId: string;
     }>;
-    approve(interactionId: string, approved: boolean, options: CommandOptions): Promise<{
+    /** Approve (or deny) a held tool call. Without an idempotency key, a new one is made. */
+    approve(interactionId: string, approved: boolean, options?: Partial<CommandOptions>): Promise<{
         status: "accepted";
         turnId: string | null;
         cursor: string | null;
@@ -164,7 +165,8 @@ export declare class SessionClient {
         cursor: string | null;
         requestId: string;
     }>;
-    respond(interactionId: string, value: JsonValue, options: CommandOptions): Promise<{
+    /** Answer a question the agent asked. Without an idempotency key, a new one is made. */
+    respond(interactionId: string, value: JsonValue, options?: Partial<CommandOptions>): Promise<{
         status: "accepted";
         turnId: string | null;
         cursor: string | null;

package/dist/session-client.js

@@ -168,22 +168,24 @@ export class SessionClient {
             ...(options.delivery ? { delivery: options.delivery } : {}),
         }, options.signal);
     }
-    approve(interactionId, approved, options) {
+    /** Approve (or deny) a held tool call. Without an idempotency key, a new one is made. */
+    approve(interactionId, approved, options = {}) {
         return this.command({
             type: "approve",
             interactionId,
             approved,
             requestId: options.requestId ?? id(),
-            idempotencyKey: options.idempotencyKey,
+            idempotencyKey: options.idempotencyKey ?? id(),
         }, options.signal);
     }
-    respond(interactionId, value, options) {
+    /** Answer a question the agent asked. Without an idempotency key, a new one is made. */
+    respond(interactionId, value, options = {}) {
         return this.command({
             type: "respond",
             interactionId,
             value,
             requestId: options.requestId ?? id(),
-            idempotencyKey: options.idempotencyKey,
+            idempotencyKey: options.idempotencyKey ?? id(),
         }, options.signal);
     }
     cancel(options) {

package/dist/skills/load.js

@@ -91,6 +91,13 @@ export function loadSkillsFromDirectory(directory, diagnostics, options = {}) {
             });
             continue;
         }
+        if (parsed.secrets !== undefined)
+            diagnostics.push({
+                severity: "warning",
+                code: `${prefix}.skill-secrets`,
+                message: `Skill '${parsed.name}': secrets in SKILL.md is deprecated (D80), since it is not an Agent Skills key: an agent folder lists a skill's secrets in AGENT.md's skills block, where nylorun migrate folder moves them. It is still read until a later release.`,
+                path: skillFile,
+            });
         skills[parsed.name] = {
             name: parsed.name,
             description: parsed.description,

package/dist/skills/skills.d.ts

@@ -19,9 +19,10 @@ export interface SkillsPart extends PartDeclaration {
  *
  * Sets `skills`: each skill's name, description and files (every file of its folder, binary
  * included, by content hash). A SKILL.md's frontmatter `secrets` (environment variable names)
- * become the skill's `secrets` in the harness section when the agent's manifest is saved. The
- * client uploads the files the Runtime lacks when it saves the agent's manifest; the Runtime adds
- * the skill catalog and serves `load_skill` / `read_skill_resource` from them.
+ * become the skill's `secrets` in the harness section when the agent's manifest is saved; that key
+ * is deprecated (D80), so it also emits a `DeprecationWarning`. The client uploads the files the
+ * Runtime lacks when it saves the agent's manifest; the Runtime adds the skill catalog and serves
+ * `load_skill` / `read_skill_resource` from them.
  */
 export declare function skills(directory: string): SkillsPart;
 /**

package/dist/skills/skills.js

@@ -14,14 +14,23 @@ import { loadSkillsFromDirectory, resolveSkillsRoot, } from "./load.js";
  *
  * Sets `skills`: each skill's name, description and files (every file of its folder, binary
  * included, by content hash). A SKILL.md's frontmatter `secrets` (environment variable names)
- * become the skill's `secrets` in the harness section when the agent's manifest is saved. The
- * client uploads the files the Runtime lacks when it saves the agent's manifest; the Runtime adds
- * the skill catalog and serves `load_skill` / `read_skill_resource` from them.
+ * become the skill's `secrets` in the harness section when the agent's manifest is saved; that key
+ * is deprecated (D80), so it also emits a `DeprecationWarning`. The client uploads the files the
+ * Runtime lacks when it saves the agent's manifest; the Runtime adds the skill catalog and serves
+ * `load_skill` / `read_skill_resource` from them.
  */
 export function skills(directory) {
     const root = resolveSkillsRoot(directory);
     const diagnostics = [];
     const loaded = loadSkillsFromDirectory(root, diagnostics);
+    // `secrets` in SKILL.md is deprecated (D80): building or saving the agent says so.
+    for (const diagnostic of diagnostics)
+        if (diagnostic.code === "skills.skill-secrets")
+            process.emitWarning(diagnostic.message, {
+                type: "DeprecationWarning",
+                code: diagnostic.code,
+                ...(diagnostic.path === undefined ? {} : { detail: diagnostic.path }),
+            });
     const listed = Object.values(loaded);
     const id = `skills:${basename(root)}`;
     if (listed.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/agents",
-  "version": "0.27.0-beta",
+  "version": "0.28.0-beta",
   "description": "Nylorun agent definitions and session client",
   "type": "module",
   "license": "Apache-2.0",
@@ -43,7 +43,7 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@nylorun/core": "0.27.0-beta",
+    "@nylorun/core": "0.28.0-beta",
     "gray-matter": "^4.0.3"
   },
   "peerDependencies": {