@nylorun/agents 0.21.0-beta → 0.22.0-beta

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @nylorun/agents
 
+## 0.22.0-beta
+
+### Minor Changes
+
+- a0cf8b2: **HTTP tools take `GET` and `DELETE`, and URL path parameters.**
+
+  - `method` is `GET`, `POST` (default), `PUT`, `PATCH` or `DELETE`. `POST`, `PUT` and `PATCH` send the input as the JSON body, as before. `GET` and `DELETE` send no body: the input becomes the query string, after any query string written in the URL. An array repeats its name (`tag=a&tag=b`) and a `null` is left out.
+  - The URL's path may name input fields as `{field}`, as in `https://api.example.com/orders/{orderId}`. Each value is percent-encoded into the path and is not sent again in the body or query string. A value that is empty, `.` or `..`, or not a string, number or boolean is refused before the call is sent (`tool.invalid-input`).
+  - `http()` and the manifest contract check a tool against its input schema. Each `{field}` must be a required scalar property. For `GET` and `DELETE`, a property must not be an object and must not repeat a query parameter the URL already sets.
+  - An HTTP verifier still takes only `POST`, `PUT` or `PATCH` and a URL without `{field}` parameters, because it is sent `{ input, output, iteration }` as a body. A credential with `via` cannot serve a tool with `{field}` parameters (`http.credential`).
+  - core exports `httpToolRequest`, which maps a call's input to the request, and `httpPathParameters`. The Runtime's outbound `post()` is now `send()`, which can send a request without a body.
+
+### Patch Changes
+
+- 620072d: **Docs and schemas match what the CLI and the Runtime do.**
+
+  - `@nylorun/core`: the environment manifest's JSON Schema (`@nylorun/core/schemas/environment-manifest.json`) takes the CLI's `{ path, from }` `files` entry, so an editor no longer flags a manifest that `nylorun environments manifests save` accepts. The Runtime's own schema is unchanged: the CLI turns the folder into `{ path, files }` before saving. `manifest_changed` says to save without `If-Match` (`--if-match`, `ifMatch`); no command takes `--force`.
+  - Tool names, skill names and MCP server names are each unique within their kind, as the builder and the Runtime check; a tool, a skill and a server may share a name. The docs said they were unique across kinds.
+  - `harness_mismatch` is described as what it is since protocol 14: an Environment's harness is fixed for its life (fork onto a manifest version to run another), and a session's turn is refused when its Environment id was deleted and made again with another harness, or an Environment changed in place before protocol 14 applies that change.
+  - `@nylorun/agents`: the README names `nylorun environments list | delete`, not `nylorun local sandbox ls | rm`.
+  - MIGRATION.md no longer offers a tool's `approval`, removed in protocol 11, as a replacement for step middleware.
+
+- 000ff75: **READMEs and help text match protocol 14.**
+
+  - `nylorun --help` lists `environments fork`, `manifests` and `delete-version`. The package description no longer offers `nylo` as the Runtime client, and the README says nylorun depends on `@nylorun/agents` too.
+  - The READMEs name the current commands: `nylorun tenant keys`, `nylorun tenant mcp inspect`, `nylorun local logs` and `nylorun local reset`. `@nylorun/admin` says it speaks protocol 14.
+  - `@nylorun/agents`: a lost MCP or HTTP tool call is sent again with its key, then fails to the model as `tool.interrupted` (it is not left `uncertain`). Every manifest is v7. A2A takes `raw` files. A delegated agent cannot pause.
+  - `@nylorun/runtime`: the README describes protocol 14, `PUT /v1/sessions/{id}` says it answers an identical session (vaults are no longer attached), and the database-layout error names `nylorun local reset`.
+  - `@nylorun/create-agent`: `nylorun start` writes the project's keys (no key is derived any more).
+
+- Pin core to the tested release.
+- Updated dependencies [620072d]
+- Updated dependencies [a0cf8b2]
+  - @nylorun/core@0.22.0-beta
+
 ## 0.21.0-beta
 
 ### Minor Changes

package/README.md

@@ -46,7 +46,7 @@ const refundOrder = http({
   input: z.object({ orderId: z.string(), amount: z.number() }), // or a JSON Schema object
   output: z.object({ refundId: z.string() }), // optional
   url: "https://billing.example.com/refunds",
-  method: "POST", // default; or PUT, PATCH
+  method: "POST", // default; or GET, PUT, PATCH, DELETE
   credential: "billing", // optional: the session's Environment holds a credential for this URL
   timeoutMs: 20_000, // default 60000, at most 300000
 });
@@ -54,9 +54,51 @@ const refundOrder = http({
 export const support = Agent({ id: "support" }).tools(refundOrder);
 ```
 
-The tool goes into the manifest as `http`, and the Runtime's
-Tool Gate sends the model's input as the JSON body, under the Host's address
-policy (`NYLORUN_ENDPOINT_*`), with `content-type: application/json`,
+The method decides where the input goes:
+
+| Method                           | Request                                                        |
+| -------------------------------- | -------------------------------------------------------------- |
+| `POST` (default), `PUT`, `PATCH` | The input as the JSON body (`content-type: application/json`) |
+| `GET`, `DELETE`                  | No body: the input as the query string                         |
+
+The URL's path may name input fields as `{field}`. Each one must be a required string,
+number or boolean field of `input`. Its value goes into the path percent-encoded (so `/`,
+`?` and `#` cannot change the request), and it is not sent again in the body or query
+string. A query string written in the URL is kept, and the input's fields come after it.
+In the query string an array repeats its name (`tag=a&tag=b`) and a `null` is left out.
+
+`http()`, and the Runtime when it saves a manifest, refuse a tool whose URL names a field
+the input does not require. For `GET` and `DELETE` they also refuse a field that is an object (a query string cannot hold one), and a
+field that repeats a query parameter the URL already sets. A call is refused before it is
+sent (`tool.invalid-input`) when a URL value is empty, `.` or `..`, or not a string, number
+or boolean.
+
+```ts
+// GET https://api.open-meteo.com/v1/forecast?current=…&latitude=22.57&longitude=88.36
+const forecast = http({
+  name: "get_forecast",
+  description: "Current weather at a latitude and longitude.",
+  input: z.object({
+    latitude: z.number(),
+    longitude: z.number(),
+    temperature_unit: z.enum(["celsius", "fahrenheit"]).optional(),
+  }),
+  url: "https://api.open-meteo.com/v1/forecast?current=temperature_2m,relative_humidity_2m,wind_speed_10m&timezone=auto",
+  method: "GET",
+});
+
+// DELETE https://billing.example.com/orders/A-17?reason=duplicate
+const cancelOrder = http({
+  name: "cancel_order",
+  input: z.object({ orderId: z.string(), reason: z.string() }),
+  url: "https://billing.example.com/orders/{orderId}",
+  method: "DELETE",
+  credential: "billing",
+});
+```
+
+The tool goes into the manifest as `http`, and the Runtime's Tool Gate sends
+the request under the Host's address policy (`NYLORUN_ENDPOINT_*`), with
 `Nylorun-Session-Id`, `Nylorun-Turn-Id`, `Nylorun-Agent-Id` and an
 `Idempotency-Key` that is the same when the Runtime re-sends the call after a
 restart, so your service can drop duplicates. A `2xx` JSON answer is the output
@@ -81,10 +123,11 @@ turn say, that is a new call with a new key: put a business key (an order or
 charge id) in the tool's input schema to refuse it too.
 
 `credential` works as for a remote MCP server: the vault of the session's
-Environment must hold a credential bound to the tool's exact URL, else the call
-fails before it is sent (`http.credential`). A credential with `via`
-sends the call there instead, such as a gateway, with the session owner in its
-identity header, and a `401` is `credential_rejected` to the model, not retried.
+Environment must hold a credential bound to the tool's exact URL (as written,
+`{field}` parameters included), else the call fails before it is sent
+(`http.credential`). A credential with `via` sends the call there instead, such
+as a gateway, with the session owner in its identity header (a gateway has one
+URL, so a tool with `{field}` parameters fails with `http.credential`), and a `401` is `credential_rejected` to the model, not retried.
 Whether a call waits for a person is not the tool's to say: it is the Tenant's
 [tool policy](#tool-policy). An HTTP tool is also a flow stage (see [Flow agents](#flow-agents)), and runs
 only on the Runtime (a local `run()` reports `http.runtime-only`).
@@ -215,11 +258,11 @@ const assistant = Agent({ id: "assistant", name: "Assistant" })
   });
 ```
 
-Each key names a server; its `name` defaults to the key and, when given, must equal it. Repeated `.mcp()` calls add servers to the manifest's `mcpServers`. Nylorun accepts remote servers only: `streamable-http` and `sse` ([Agent Plugins MCP servers](https://agent-plugins.org/plugin-authors/mcp-servers)); a `stdio` server is refused, so run it behind an HTTP transport and declare its URL. Attach an Agent Plugin package with `.plugin(path)`: its skills and remote MCP servers join the agent's `skills` and `mcpServers`, each labelled `plugin: { name, version }` from its `plugin.json`, and a stdio server in its `mcp.json` throws. Names are unique across the agent's tools, skills and servers.
+Each key names a server; its `name` defaults to the key and, when given, must equal it. Repeated `.mcp()` calls add servers to the manifest's `mcpServers`. Nylorun accepts remote servers only: `streamable-http` and `sse` ([Agent Plugins MCP servers](https://agent-plugins.org/plugin-authors/mcp-servers)); a `stdio` server is refused, so run it behind an HTTP transport and declare its URL. Attach an Agent Plugin package with `.plugin(path)`: its skills and remote MCP servers join the agent's `skills` and `mcpServers`, each labelled `plugin: { name, version }` from its `plugin.json`, and a stdio server in its `mcp.json` throws. Tool names, skill names and server names are each unique within their kind; a tool, a skill and a server may share a name, since a server's tools are called `<server>__<tool>`.
 
-Set a server's tools one by one with `tools`, keyed by the server's own tool names, `"*"` for the rest: `{ "*": { enabled: false }, search_issues: { enabled: true }, create_issue: { enabled: true } }` is an allowlist (whether a call waits for a person is the [tool policy](#tool-policy)). When an agent's MCP tools would fill more than a tenth of the model's context window, the Runtime defers them: the model finds them with `tool_search` and runs them with `tool_call`. `deferred: true` or `false`, on a tool or on the server, decides instead. Either setting makes the manifest v6 (see MIGRATION.md).
+Set a server's tools one by one with `tools`, keyed by the server's own tool names, `"*"` for the rest: `{ "*": { enabled: false }, search_issues: { enabled: true }, create_issue: { enabled: true } }` is an allowlist (whether a call waits for a person is the [tool policy](#tool-policy)). When an agent's MCP tools would fill more than a tenth of the model's context window, the Runtime defers them: the model finds them with `tool_search` and runs them with `tool_call`. `deferred: true` or `false`, on a tool or on the server, decides instead.
 
-A manifest never carries a server's credential, and its `headers` hold no secret. You write a credential for the server's URL into an Environment (a token or a header map, or a gateway's key with `via` and an identity header for servers that need each person's sign-in, with `client.environments.secrets.put`), and sessions that name the Environment use it: [DEPLOYMENT.md](../../guides/DEPLOYMENT.md#mcp-servers-and-http-tools), which also shows `nylorun mcp inspect` for listing a server's tools first. After `saveAgent`, `admin.coverage({ agentId, environmentId })` in `@nylorun/admin` says which credential each server and HTTP tool would get in that Environment ([Checking an agent's credentials](../../guides/DEPLOYMENT.md#checking-an-agents-credentials)). The model knows each tool as `server__tool`, with characters outside `[A-Za-z0-9_-]` replaced by `_`; a failed call reaches it with a code (`credential_rejected` on a `401`, `mcp.unreachable`, …), and a result past 32 KiB, or an image, becomes an artifact of the session that it reads with `read_artifact`.
+A manifest never carries a server's credential, and its `headers` hold no secret. You write a credential for the server's URL into an Environment (a token or a header map, or a gateway's key with `via` and an identity header for servers that need each person's sign-in, with `client.environments.secrets.put`), and sessions that name the Environment use it: [DEPLOYMENT.md](../../guides/DEPLOYMENT.md#mcp-servers-and-http-tools), which also shows `nylorun tenant mcp inspect` for listing a server's tools first. After `saveAgent`, `admin.coverage({ agentId, environmentId })` in `@nylorun/admin` says which credential each server and HTTP tool would get in that Environment ([Checking an agent's credentials](../../guides/DEPLOYMENT.md#checking-an-agents-credentials)). The model knows each tool as `server__tool`, with characters outside `[A-Za-z0-9_-]` replaced by `_`; a failed call reaches it with a code (`credential_rejected` on a `401`, `mcp.unreachable`, …), and a result past 32 KiB, or an image, becomes an artifact of the session that it reads with `read_artifact`.
 
 A session runs in an **Environment**: one sandbox and one vault, with an id you choose, which outlives the sessions that name it (protocol 11). It is made from one version of an **environment manifest** or from inline fields, and never changes what it runs after that (protocol 14). The agent names no Environment, so the same agent runs in any Tenant; it may state what it needs (`.requires()`). Whether an Environment serves one session, one person or a project is your app's choice:
 
@@ -271,7 +314,7 @@ An Environment never changes what it runs (protocol 14, its view's `manifest`):
 
 Secrets are write-only: `client.environments.secrets.put(id, name, secret)` creates or replaces one, and `list`, `get` and `delete` never return a value. An `environment_secret` (`{ value, allowedHosts, inject? }`) shows its name to commands as the sentinel `nylorun-managed`, and egress-gate sets its header on HTTPS requests to `allowedHosts` (pods only); an `environment_variable` (`{ value }`) is a plain variable; `bearer` (`{ url, value, via?, identity? }`) and `headers` (`{ url, headers, via?, identity? }`) are credentials for the MCP servers and HTTP tools at `url`. A second secret for one host, or a second credential for one URL, is `409 credential_conflict` at the write ([DEPLOYMENT.md](../../guides/DEPLOYMENT.md#credentials)). When what an Environment runs declares a secret's slot (a manifest's `secrets`), send only `{ value }` (or `{ headers }`): the type and binding come from the slot, and a name it does not declare is `409 secret_not_in_manifest`. An agent built with `.requires({ sandbox: "pod", secrets: ["GH_TOKEN"] })` opens a session only on an Environment that has them (`409 environment_unsuitable`). `saveAgent(agent, { dryRun: true })` checks a definition and saves nothing.
 
-Sessions on one Environment share its `/workspace` and run their turns at the same time (one turn per session); which sessions work on one disk, and when, is your app's call. Stop, reset, snapshot and restore wait until no turn runs (`409 environment_busy`). Deleting a session only detaches it. With `ownerUserId` set, a session of another owner is `403 environment_owner_mismatch` (a caller acting for a person gets the `404` of a missing Environment), checked when it opens and at every turn start. `client.environments.list({ labels })`, `page`, `get(id)`, `events(id, { types, since, until })` (its lifecycle, and `environment.egress` for every connection its sandbox opens, naming the turns that were running), `stop(id)`, `reset(id)` and `delete(id)` manage them, and `npx nylorun local sandbox ls | rm` does the same on a local Tenant. Acting for a person (`app.as(...)`), changing an Environment or its secrets needs `environments:write`. A trusted issuer's token reaches only the Environments its issuer grants (the identity file's `environments` templates, exact ids or prefixes ending in `/*`), checked at every turn start. The Tenant holds at most `limits.environments` of them (`PUT /v1/tenant/sandbox`, default 100).
+Sessions on one Environment share its `/workspace` and run their turns at the same time (one turn per session); which sessions work on one disk, and when, is your app's call. Stop, reset, snapshot and restore wait until no turn runs (`409 environment_busy`). Deleting a session only detaches it. With `ownerUserId` set, a session of another owner is `403 environment_owner_mismatch` (a caller acting for a person gets the `404` of a missing Environment), checked when it opens and at every turn start. `client.environments.list({ labels })`, `page`, `get(id)`, `events(id, { types, since, until })` (its lifecycle, and `environment.egress` for every connection its sandbox opens, naming the turns that were running), `stop(id)`, `reset(id)` and `delete(id)` manage them, and `npx nylorun environments list | delete` does the same from the command line. Acting for a person (`app.as(...)`), changing an Environment or its secrets needs `environments:write`. A trusted issuer's token reaches only the Environments its issuer grants (the identity file's `environments` templates, exact ids or prefixes ending in `/*`), checked at every turn start. The Tenant holds at most `limits.environments` of them (`PUT /v1/tenant/sandbox`, default 100).
 
 A pod's disk can start prepared: `files` copies versions of Tenant-wide artifacts in, then `setup` runs its commands, once per new disk and before its first turn (a failed command fails the pod, and the next turn start runs the setup again). Between turns, `client.environments.snapshot(id)` keeps a version of the disk, `restore(id, version)` puts one back (a pod on a new volume seeded before its next turn), `put(newId, { from: { environment: id, version: "latest" } })` starts a new Environment from it, and `versions(id)` and `deleteVersion(id, n)` manage them ([DEPLOYMENT.md](../../guides/DEPLOYMENT.md#environments)):
 
@@ -312,7 +355,7 @@ The tool is named after the agent's `id` and takes `{ task: string }`; the agent
 
 A flow agent can be a subagent too: `.subagents(researchFlow)` with a `description` like any other. Its manifest is inlined in the parent's, so it is saved with the parent. When the model calls it, the flow runs on the Runtime in its own linked session (a fresh one per call, linked from the parent's with a `node.agent` event at `support/<flow id>`), its agents in theirs, and the flow's output comes back as the tool result; a failed flow is a failed tool result. Cancelling the parent cancels the flow. Flow agents as subagents run on the Runtime only, not in a local `run()`. An approval asked for inside the flow waits on the flow's own session.
 
-Delegate when the parent should keep the answer. When a specialist should own the rest of the conversation, send the next message with a turn manifest that has the specialist's instructions instead. This version is one level deep and non-interactive: a delegated agent cannot use agents as tools, and its tools cannot declare `approval` (keep those on the parent). In the local engine (`@nylorun/harness/run`), a delegated agent's `tool({ run })` tools start with empty `ctx.state`, can read `ctx.agent` (`{ id, path, delegationId }`), and fail with `delegation.interaction-unsupported` on `ctx.ask`, `ctx.approve`, `ctx.sleep` or `ctx.waitFor`. Delegation is not an approval boundary; approvals live on tools.
+Delegate when the parent should keep the answer. When a specialist should own the rest of the conversation, send the next message with a turn manifest that has the specialist's instructions instead. This version is one level deep and non-interactive: a delegated agent cannot use agents as tools, and cannot pause for input, an approval or a wait (keep those on the parent). In the local engine (`@nylorun/harness/run`), a delegated agent's `tool({ run })` tools start with empty `ctx.state`, can read `ctx.agent` (`{ id, path, delegationId }`), and fail with `delegation.interaction-unsupported` on `ctx.ask`, `ctx.approve`, `ctx.sleep` or `ctx.waitFor`. Delegation is not an approval boundary.
 
 ## Flow agents
 
@@ -398,7 +441,8 @@ an answer that does not match `output` fails the stage with its code (`http.stat
 is retried with the Loop's input, not the feedback.
 
 A Loop may be judged by your service instead of an agent: `http({ url, method?,
-credential?, timeoutMs? })`, with no name or input, is an HTTP verifier. The Runtime
+credential?, timeoutMs? })`, with no name or input, is an HTTP verifier. Its method is
+`POST`, `PUT` or `PATCH` and its URL has no `{field}` parameters, because the Runtime
 sends `{ input, output, iteration }` (the Loop's input, the attempt's output, its
 number) and reads a verdict, `{ pass, feedback? }`, from the answer; anything else, or a
 failed request, fails the Loop (`loop.verify-failed`). Its verdicts are recorded as
@@ -459,7 +503,8 @@ then `dev`. Agents do not hash the manifest; the Runtime pins the digest of the
 definition a session opens with. Model selection and model credentials belong to
 the Tenant.
 
-The Runtime makes a lost HTTP tool call `uncertain` instead of repeating its external effect.
+The Runtime sends a lost MCP or HTTP tool call again with the same key, then fails it to the
+model as `tool.interrupted` (see **How tool calls are delivered**).
 In the local engine (`@nylorun/harness/run`), `tool({ run })` tools receive state, info,
 identity, resume, signal, approval/response helpers and memoized `step`. Agent definitions
 have no `.run()`; explicit
@@ -590,8 +635,10 @@ What the Runtime answers (Host feature `a2a-endpoint`):
   on the same `taskId`.
 - The `messageId` is the idempotency key: a retried message returns the same
   task.
-- Text parts, or a single data part, in; the turn's output as the artifact
-  `output` (text, or JSON as a data part). Files are
+- Text parts, a single data part, or text and `raw` file parts in (at most
+  20 MiB each, stored as artifacts of the context's session); the turn's
+  output as the artifact `output` (text, or JSON as a data part). A file by
+  `url`, or one the Tenant's model does not read, is
   `ContentTypeNotSupportedError`.
 - Clients must send `A2A-Version: 1.0` (header or `?A2A-Version=`).
 - Not yet: `ListTasks`, streaming and `SubscribeToTask`

package/dist/client.d.ts

@@ -2,7 +2,7 @@ export * from "./session-client.js";
 import { AgentsClient } from "./session-client.js";
 import type { Destination } from "./http.js";
 /**
- * Build a Tenant API client.
+ * Build a Runtime API client.
  * Explicit connection fields keep today's sync Transport resolution (including
  * environment fill-ins). With no connection fields, resolves via
  * `resolveConnection` (environment → project link), which reads the Project's files: it is

package/dist/connection.d.ts

@@ -9,7 +9,7 @@ export declare class ConnectionError extends Error {
     constructor(message: string);
 }
 /**
- * Resolve Tenant API connection: options → environment → project link (D§7.1). A connection is a
+ * Resolve a Runtime API connection: options → environment → project link (D§7.1). A connection is a
  * Runtime URL and a key: the Runtime serves one Tenant, so nothing names it.
  */
 export declare function resolveConnection(options?: {

package/dist/connection.js

@@ -42,7 +42,7 @@ function readProjectLink(cwd) {
     };
 }
 /**
- * Resolve Tenant API connection: options → environment → project link (D§7.1). A connection is a
+ * Resolve a Runtime API connection: options → environment → project link (D§7.1). A connection is a
  * Runtime URL and a key: the Runtime serves one Tenant, so nothing names it.
  */
 export async function resolveConnection(options) {

package/dist/session-client.d.ts

@@ -1,5 +1,5 @@
 /**
- * The Tenant API client classes, with no Node-only imports. `client.ts` adds `createClient`,
+ * The Runtime API client classes, with no Node-only imports. `client.ts` adds `createClient`,
  * which resolves the connection from the environment or the Project link.
  */
 import type { AgentManifest, BuiltAgent, BuiltWorkflow, JsonValue, SandboxToolName, WorkflowManifest } from "@nylorun/core/define";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/agents",
-  "version": "0.21.0-beta",
+  "version": "0.22.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.21.0-beta",
+    "@nylorun/core": "0.22.0-beta",
     "gray-matter": "^4.0.3"
   },
   "peerDependencies": {