@nylorun/agents 0.16.0-beta → 0.17.0-beta

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @nylorun/agents
 
+## 0.17.0-beta
+
+### Major Changes
+
+- cf5eb9c: **Protocol 9: the Runtime API is an OAuth 2.1 resource server for your identity provider's tokens.** Nylorun is still never the authorization server. Upgrade every package together; MIGRATION.md has the details.
+
+  - **Breaking (`@nylorun/runtime`): a refused credential is `401`, not the opaque `404`.** No `Authorization` is `401 credential_required`; an unknown key, or a token no trusted issuer signed or that fails a check, is `401 credential_invalid`. Each carries `WWW-Authenticate: Bearer` (OAuth 2.1 §5.3), naming the protected resource metadata (`resource_metadata`) on the Runtime API when the Runtime has trusted issuers; the Management API's challenge is a bare `Bearer`. `token_expired` and `issuer_unavailable` gain the challenge too. Another Tenant named, a Tenant that could not open and an unsigned capability link stay the opaque `404`.
+  - **Breaking (`@nylorun/runtime`): a request with neither `Nylorun-Protocol` nor `Authorization`** on an API route gets that route's `401` challenge instead of `426`, so a generic OAuth client learns where to sign in.
+  - `@nylorun/runtime`: a token without a route's scope still gets `403 scope_required`, now with `WWW-Authenticate: Bearer error="insufficient_scope", scope="…"`. The `Bearer` scheme is matched in any case (RFC 9110).
+  - `@nylorun/runtime`: `GET /.well-known/oauth-protected-resource` (RFC 9728) serves the resource (`NYLORUN_PUBLIC_URL`, else the request's origin), the identity file's issuers in order and their scopes, with no key or protocol; `404` without an identity file.
+  - **Breaking (`@nylorun/runtime`): the identity file drops `maxLifetime`.** The issuer sets its tokens' lifetimes; `exp` is required, `iat` no longer is. A key the file does not define, `maxLifetime` included, is ignored and logged (`identity_file_key_ignored`) instead of stopping the boot. `subject` defaults to `{sub}`, `scopes` to `{ claim: scope }` and `allowedScopes` to every token scope but `studio`.
+  - `@nylorun/core`: `PROTOCOL_VERSION` is 9 and `HOST_PROTOCOL` 4–9, with the required feature `resource-server`; `ERROR_CODES` adds `credential_required` and `credential_invalid`. `@nylorun/agents`, `@nylorun/admin` and `@nylorun/cli` send protocol 9.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [cf5eb9c]
+- Updated dependencies [2ed5fe0]
+  - @nylorun/core@0.16.0-beta
+
+## 0.16.1-beta
+
+### Patch Changes
+
+- cb29dea: **READMEs for manifest-only agents.** Documentation only; no code changes.
+
+  - `@nylorun/agents`: the Flow agents example opens the PR with an `http()` tool stage instead of a code tool, and shows how to keep a person's approval: a flow stage cannot take `approval` yet (`flow.approval-unsupported`), so the HTTP tool goes to an agent stage with `approval: "always"`. Requests set `Nylorun-Protocol` 8. The subagents section says `ctx.state`, `ctx.agent` and `ctx.ask`/`ctx.approve` apply only to `tool({ run })` in the local engine.
+  - `@nylorun/cli`: no longer says `nylo endpoints` uses the Runtime API or replaces `nylo tenant endpoints`; it was removed with Action endpoints and exits 2.
+
 ## 0.16.0-beta
 
 ### Major Changes

package/README.md

@@ -127,7 +127,7 @@ eval "$(npx @nylorun/cli env)"
 # → NYLORUN_RUNTIME_URL, NYLORUN_SERVER_KEY
 ```
 
-Every request sets `Nylorun-Protocol` (6) and no `Nylorun-Tenant`: the Runtime
+Every request sets `Nylorun-Protocol` (8) and no `Nylorun-Tenant`: the Runtime
 serves one Tenant. Before the first authenticated
 request, `Transport` fetches `/health` once, checks protocol compatibility, and
 throws `IncompatibleRuntimeError` / `incompatible_host` when the Host range or
@@ -218,11 +218,11 @@ const support = Agent({ id: "support" })
   .subagents(researcher);
 ```
 
-The tool is named after the agent's `id` and takes `{ task: string }`; the agent's `description` (required) is what the parent's model reads to decide when to delegate. The child starts with a fresh context: it sees its own instructions and the task, nothing of the parent's conversation, and only its final text (or `outputSchema` result) comes back. It keeps its own tools, skills and MCP servers, saved with the parent, shares the session's sandbox, and starts with empty `ctx.state`. Tools can read `ctx.agent` (`{ id, path, delegationId }`). Several delegation calls in one model response run in parallel. An empty answer, a failure (with the child's last text marked as evidence) or a cancelled child reaches the parent's model as a failed tool result, never as success. The Runtime emits `delegation.started` and `delegation.completed`; `session.history({ agent })` filters by `delegationId` (one child invocation) or by path such as `support/researcher` (every concurrent child that shares that path).
+The tool is named after the agent's `id` and takes `{ task: string }`; the agent's `description` (required) is what the parent's model reads to decide when to delegate. The child starts with a fresh context: it sees its own instructions and the task, nothing of the parent's conversation, and only its final text (or `outputSchema` result) comes back. It keeps its own tools, skills and MCP servers, saved with the parent, and shares the session's sandbox. Several delegation calls in one model response run in parallel. An empty answer, a failure (with the child's last text marked as evidence) or a cancelled child reaches the parent's model as a failed tool result, never as success. The Runtime emits `delegation.started` and `delegation.completed`; `session.history({ agent })` filters by `delegationId` (one child invocation) or by path such as `support/researcher` (every concurrent child that shares that path).
 
 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, its tools cannot declare `approval` (keep those on the parent), and `ctx.ask`, `ctx.approve`, `ctx.sleep` or `ctx.waitFor` inside it fail with `delegation.interaction-unsupported`. 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 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.
 
 ## Flow agents
 
@@ -239,7 +239,7 @@ gets the previous stage's output. So each agent returns, through its `.output()`
 what the next stage needs.
 
 ```ts
-import { Agent, VerdictSchema, tool } from "@nylorun/agents";
+import { Agent, VerdictSchema, http } from "@nylorun/agents";
 import { z } from "zod";
 
 const planner = Agent({ id: "planner" })
@@ -258,13 +258,13 @@ const prWriter = Agent({ id: "pr-writer" })
   .instructions("Return the summaries you are given as { summaries }.")
   .output(z.object({ summaries: z.array(z.string()) }));
 
-const openPr = tool({
-  name: "open-pr",
+// Your service serves POST /pull-requests and answers { url }.
+const openPr = http({
+  name: "open_pr",
   input: z.object({ summaries: z.array(z.string()) }),
-  async run({ summaries }, ctx) {
-    if (!(await ctx.approve("Open the PR?"))) throw new Error("Rejected");
-    return { opened: true, count: summaries.length };
-  },
+  output: z.object({ url: z.string() }),
+  url: "https://ci.example.com/pull-requests",
+  credential: "github",
 });
 
 export const shipFeature = Agent({ id: "ship-feature" })
@@ -275,6 +275,29 @@ export const shipFeature = Agent({ id: "ship-feature" })
 export const agents = [shipFeature];
 ```
 
+A flow stage cannot take `approval` yet (`flow.approval-unsupported`). To have a person
+approve opening the PR, give the HTTP tool to an agent as the last stage instead: that
+agent's turn pauses until the call is approved, and the flow session's `pending()` lists
+the wait:
+
+```ts
+const prOpener = Agent({ id: "pr-opener" })
+  .instructions("Open one pull request with open_pr from the summaries you are given.")
+  .tools(
+    http({
+      name: "open_pr",
+      description: "Open a pull request with the given summaries.",
+      input: z.object({ summaries: z.array(z.string()) }),
+      url: "https://ci.example.com/pull-requests",
+      credential: "github",
+      approval: "always",
+    }),
+  );
+
+// …
+  .pipe(prWriter, prOpener);
+```
+
 | Stage | Role |
 | --- | --- |
 | **`.pipe(a, b, …)`** | Run agents, tools or `flow()`s in order; each one's output is the next one's input |

package/dist/session-client.d.ts

@@ -261,7 +261,7 @@ export declare class SessionClient {
         time: string;
         schemaVersion: number;
         source: {
-            kind: "api" | "controller" | "edge" | "egress-gate" | "evidence" | "harness" | "human" | "init" | "loop" | "model-gate" | "operator" | "sandboxd" | "supervisor" | "tool-gate";
+            kind: "api" | "controller" | "edge" | "egress-gate" | "evidence" | "harness" | "human" | "init" | "loop" | "model-gate" | "operator" | "sandboxes" | "supervisor" | "tool-gate";
             id: string;
         };
         evidence: "asserted" | "attested" | "claimed" | "measured" | "observed";

package/package.json

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