@nylorun/agents 0.27.0-beta → 0.29.0-beta

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @nylorun/agents
 
+## 0.29.0-beta
+
+### Minor Changes
+
+- d99b3ac: A session can have its own model (optional Host feature `session-model`). `PUT /v1/sessions/{id}/model` chooses one of a connected provider's models for that session's turns, `DELETE` clears it, and `GET` answers the model the next turn uses (`source: "session"` or `"tenant"`). The Tenant's model and every other session's stay as they are. The Model Gate calls the session's model on its provider's credential (a refreshed OAuth credential is written back to that provider), `turn.start.model` describes it, and the usage ledger records it. A choice names a connected provider and a model its catalog lists, is set by the application only (a trusted issuer's token can read it, not change it), and is refused while a turn runs or waits (`409 session_busy`); while its provider is disconnected the session uses the Tenant's model. The SDK adds `session.model()`, `setModel({ provider, model })` and `clearModel()`.
+
+  Studio's model picker under the message box now sets the model of that session only, instead of the Tenant's: "Tenant model" clears the session's choice, the picker is locked while a turn runs, it groups models by provider, and its search keeps what is typed. A Runtime without `session-model` shows no picker.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [95f98f1]
+- Updated dependencies [d99b3ac]
+  - @nylorun/core@0.29.0-beta
+
+## 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, SessionModelChoice, SessionModelView, 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

@@ -3,7 +3,7 @@
  * which resolves the connection from the environment or the Project link.
  */
 import type { JsonValue, SandboxToolName } from "@nylorun/core/define";
-import { type SessionItemsResponse, type SessionSummary, type SubjectScope, type MessageDelivery, type MessagePart, type SessionCommand } from "@nylorun/core/contracts";
+import { type SessionModelChoice, type SessionItemsResponse, type SessionSummary, type SubjectScope, type MessageDelivery, type MessagePart, type SessionCommand } from "@nylorun/core/contracts";
 import { SessionsReadClient } from "./reads.js";
 import { AccessClient } from "./access.js";
 import { AgentInstancesClient } from "./agents.js";
@@ -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;
@@ -202,6 +204,72 @@ export declare class SessionClient {
         manifestHash: string;
         manifest: Record<string, unknown>;
     }>;
+    /**
+     * The model the session's next turn uses (Host feature `session-model`): its own while its
+     * provider is connected, else the Tenant's.
+     */
+    model(options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        configured: false;
+        choice?: {
+            provider: string;
+            model: string;
+        } | undefined;
+    } | {
+        configured: true;
+        source: "session" | "tenant";
+        provider: string;
+        model: string;
+        baseUrl?: string | undefined;
+        choice?: {
+            provider: string;
+            model: string;
+        } | undefined;
+    }>;
+    /**
+     * Chooses one of a connected provider's models for this session's turns; the Tenant's model and
+     * other sessions' stay as they are. Refused while a turn runs or waits (`409 session_busy`).
+     */
+    setModel(choice: SessionModelChoice, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        configured: false;
+        choice?: {
+            provider: string;
+            model: string;
+        } | undefined;
+    } | {
+        configured: true;
+        source: "session" | "tenant";
+        provider: string;
+        model: string;
+        baseUrl?: string | undefined;
+        choice?: {
+            provider: string;
+            model: string;
+        } | undefined;
+    }>;
+    /** Clears the session's own model: its next turns use the Tenant's. */
+    clearModel(options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        configured: false;
+        choice?: {
+            provider: string;
+            model: string;
+        } | undefined;
+    } | {
+        configured: true;
+        source: "session" | "tenant";
+        provider: string;
+        model: string;
+        baseUrl?: string | undefined;
+        choice?: {
+            provider: string;
+            model: string;
+        } | undefined;
+    }>;
     usage(options?: {
         turnId?: string;
         signal?: AbortSignal;

package/dist/session-client.js

@@ -1,7 +1,7 @@
 import { SANDBOX_TOOL_NAMES, isSandboxToolName } from "@nylorun/core/define";
 import { z } from "zod";
 import { SCOPES_HEADER, SUBJECT_HEADER } from "@nylorun/core/compatibility";
-import { SessionManifestViewSchema, SessionUsageTotalsSchema, ModelCallsPageSchema, ToolCallsPageSchema, TurnTraceSchema, parseSessionEvent, parseSubjectHeaders, } from "@nylorun/core/contracts";
+import { SessionManifestViewSchema, SessionModelViewSchema, SessionUsageTotalsSchema, ModelCallsPageSchema, ToolCallsPageSchema, TurnTraceSchema, parseSessionEvent, parseSubjectHeaders, } from "@nylorun/core/contracts";
 import { SessionsReadClient } from "./reads.js";
 import { AccessClient } from "./access.js";
 import { AgentInstancesClient } from "./agents.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) {
@@ -198,6 +200,27 @@ export class SessionClient {
         await this.transport.requireFeature("session-reads", options.signal);
         return SessionManifestViewSchema.parse(await this.transport.json(`${this.path}/manifest`, "GET", undefined, options.signal));
     }
+    /**
+     * The model the session's next turn uses (Host feature `session-model`): its own while its
+     * provider is connected, else the Tenant's.
+     */
+    async model(options = {}) {
+        await this.transport.requireFeature("session-model", options.signal);
+        return SessionModelViewSchema.parse(await this.transport.json(`${this.path}/model`, "GET", undefined, options.signal));
+    }
+    /**
+     * Chooses one of a connected provider's models for this session's turns; the Tenant's model and
+     * other sessions' stay as they are. Refused while a turn runs or waits (`409 session_busy`).
+     */
+    async setModel(choice, options = {}) {
+        await this.transport.requireFeature("session-model", options.signal);
+        return SessionModelViewSchema.parse(await this.transport.json(`${this.path}/model`, "PUT", { provider: choice.provider, model: choice.model }, options.signal));
+    }
+    /** Clears the session's own model: its next turns use the Tenant's. */
+    async clearModel(options = {}) {
+        await this.transport.requireFeature("session-model", options.signal);
+        return SessionModelViewSchema.parse(await this.transport.json(`${this.path}/model`, "DELETE", undefined, options.signal));
+    }
     async usage(options = {}) {
         await this.transport.requireFeature("session-reads", options.signal);
         const query = new URLSearchParams();

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.29.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.29.0-beta",
     "gray-matter": "^4.0.3"
   },
   "peerDependencies": {