agent-work-layer 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.5.0 — 2026-10-17
+
+Both packages: `agent-work-layer` 0.5.0 and `agent-work-layer-mcp` 0.5.0. Spec v0.3: Work Orders are now written as `awl/work-order@0.3`; Work Reports stay `@0.2`.
+
+### Added
+
+- `continues` on the Work Order (#19), SPEC.md §4.5: the id of the finished order a new one picks up from, so a chain of reissued orders is the full history of one job.
+  - It is not `parent_id`: no narrowing applies, and the new order may have a different worker, budget and tools.
+  - The desk rejects a `continues` that names an unknown order (`NOT_FOUND`), one that is not `approved`, `declined`, `expired` or `cancelled` (`INVALID_TRANSITION`; cancel a failed or blocked order first), another manager's order (`FORBIDDEN`), or one that is already continued (`ALREADY_EXISTS`).
+  - `desk.list({ continues })` and `list_work_orders` follow the chain; summaries include `continues`. `create_work_order` takes it.
+- Delegation Pass (#17), SPEC.md §10.2: an order's authority as a signed JWT (`typ` `awl-pass+jwt`, ES256 or EdDSA) with `iss`, `sub`, `awl_order`, `awl_parent`, `awl_tools`, `awl_budget`, `awl_deadline`, `awl_attempt`, `iat`, `exp` and `jti`.
+  - `agent-work-layer`: `signPass(order, key, options)` and `verifyPass(token, keys, options)`, with WebCrypto only, so they are also in `agent-work-layer/validate`. `verifyPass` checks signature, type, lifetime (allowing 60 seconds of clock skew on `iat`) and, when asked, issuer, worker and order; with `parent` it rejects a pass that is wider than its parent's (C1–C3) or names another parent. Keys are JWKs or WebCrypto keys from the caller. `decodePass` reads claims without checking them.
+  - `WorkDesk({ passes: { key, issuer } })` signs a pass (15 minutes, never past the deadline) each time an order enters `working`, keeps it on `record.pass`, and drops it when the order leaves `working`. `desk.issuePass(id, worker)` renews it.
+  - `agent-work-layer-mcp`: `awl-desk serve --pass-key <file> --issuer <iss>`. `start_work_order` and `get_work_order` return the pass to the order's worker only, and `renew_work_pass` renews it.
+  - Gateway: `--pass-keys <file>` (`passKeys` in code) enforces a pass instead of reading the desk's store. Each call needs a valid pass for the order and worker, from `--pass-file`, `AWL_PASS` or the call's `_meta["awl/pass"]`, and is refused with `PASS_INVALID` otherwise. Tools and `tool_calls` come from the pass.
+  - Gateway call records and result `_meta` carry the authority each call ran under: `order_id`, `attempt` and the pass's `jti`.
+- Authenticated actor (#16): `awl-desk serve --keys <file>` runs one shared desk over MCP Streamable HTTP. Every request needs `Authorization: Bearer <key>`; the key decides the actor, and an `actor` argument naming anyone else gets `FORBIDDEN`. Requests without a valid key get 401. In code: `createDeskHttpHandler({ desk, authenticate })`, where `authenticate(request)` returns the agent ref or throws an `AuthError` (401, or 403). Two example authenticators: `apiKeyAuth` (a static key → agent map) and `bearerAuth` (OAuth 2.1 access tokens: checks `exp` and `aud`, maps `sub` to an agent ref, advertises `resource_metadata` in 401 challenges). The handler can serve Protected Resource Metadata (RFC 9728). Stdio mode is unchanged.
+- SPEC.md §10.1: what binding `actor` to an authenticated identity means, and how an MCP desk does it.
+
+### Changed
+
+- `agent-work-layer` writes Work Orders as `awl/work-order@0.3` and reads `@0.1`–`@0.3`. Readers on 0.4 or earlier reject `@0.3` orders; upgrade readers first. Reports are unchanged.
+- `agent-work-layer-mcp` now depends on `agent-work-layer` ^0.5.0.
+
+### Fixed
+
+- `agent-work-layer`: `FileStore` runs writes to one order one at a time within a process, so concurrent transitions get `CONFLICT` instead of overwriting each other's state and events, and temporary files get unique names. Across processes the check stays best-effort; use `SqliteStore` for an atomic one.
+
+## python 0.2.0 — 2026-10-17
+
+### Added
+
+- Spec v0.3: `WorkOrder.continues`, and the validator reads Work Orders marked `@0.1`–`@0.3`. New orders are written as `@0.3`.
+
+## 0.4.1 — 2026-10-14
+
+`agent-work-layer-mcp` alone (`agent-work-layer` stays at 0.4.0).
+
+### Added
+
+- Every desk tool and the gateway's `awl_usage` tool declare `readOnlyHint`, `destructiveHint`, `idempotentHint` and `openWorldHint`, so hosts can warn before a tool runs and directories that require the hints accept the server.
+
+## python 0.1.0 — 2026-10-14
+
+First release of the Python package `agent-work-layer` on PyPI (`pip install agent-work-layer`).
+
+### Added
+
+- Pydantic models for Work Orders and Work Reports, and `validate_order`, `validate_report` and `validate_child_order` with the same rule ids, kinds and paths as the TypeScript SDK (#5).
+
 ## 0.4.0 — 2026-10-11
 
 Both packages: `agent-work-layer` 0.4.0 and `agent-work-layer-mcp` 0.4.0.

package/README.md

@@ -4,6 +4,7 @@
 
 [![npm](https://img.shields.io/npm/v/agent-work-layer.svg)](https://www.npmjs.com/package/agent-work-layer)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![M8ven Score](https://m8ven.ai/badge/mcp/probita-ai-agent-work-layer-0vyqyi?v=1b5d39882e3a71ebeecc28d9d2f02ec3)](https://m8ven.ai/mcp/probita-ai-agent-work-layer-0vyqyi?s=readme)
 
 - **Work Order** (manager → worker): the goal, how "done" is judged, budget, deadline, allowed tools.
 - **Work Report** (worker → manager): the result, evidence for each criterion, actual cost, tools used.
@@ -21,7 +22,7 @@ Agent Cards say who an agent is. A2A carries messages between agents. MCP connec
 
 <p align="center"><img src="docs/fields.svg" alt="Each Work Report field answers a Work Order field: evidence proves criteria, cost stays within budget, tools used stay within allowed tools" width="760"></p>
 
-More diagrams: [message sequence](docs/sequence.svg) · [lifecycle](docs/lifecycle.svg) · [delegation](docs/delegation.svg) · [handoff](docs/handoff.svg)
+More diagrams: [message sequence](docs/sequence.svg) · [lifecycle](docs/lifecycle.svg) · [delegation](docs/delegation.svg) · [handoff](docs/handoff.svg) · [authenticated actor](docs/authenticated-actor.svg) · [Delegation Pass](docs/delegation-pass.svg)
 
 ## Install
 
@@ -31,9 +32,11 @@ Install only the part you use:
 |---|---|---|
 | Validate orders and reports, or run a desk in your code | `npm install agent-work-layer` | 7 |
 | Validate in a browser, Deno or Bun | `npm install agent-work-layer`, then import `agent-work-layer/validate` | 7 |
+| Validate orders and reports in Python | `pip install agent-work-layer` ([python/](python/)) | 11 |
 | Connect agent sessions (e.g. Claude Code) through MCP | `npx -y agent-work-layer-mcp` ([setup](#run-as-an-mcp-server)) | ~100 |
+| Sign or verify Delegation Passes | `npm install agent-work-layer` ([how](#delegation-pass)) | 7 |
 
-Node.js 20.11 or later. ESM only. Types included.
+Node.js 20.11 or later. ESM only. Types included. The Python package needs Python 3.9 or later.
 
 ## Quick start
 
@@ -79,6 +82,8 @@ const { record } = await desk.submitReport(
 await desk.review(order.id, "agent:manager", "approve");
 ```
 
+For a runnable version, clone the repo, run `npm install`, then run `node examples/two-agents.ts` (Node 22.18+). [examples/two-agents.ts](examples/two-agents.ts) walks one job through a rejected report, a rework request and approval, printing each event as it happens.
+
 The desk enforces the spec as you go:
 
 - Who may do what: only the worker reports, and only the manager approves.
@@ -87,12 +92,15 @@ The desk enforces the spec as you go:
 - Only allowed tools.
 - Cost within budget and finishing before the deadline. Going over either expires the order.
 - Sub-orders can only narrow their parent's authority.
+- A reissued order can only continue a finished one, so one job never has two live orders.
+
+Optionally, it also signs the worker's authority into a [Delegation Pass](#delegation-pass) that gateways and other systems can check without the desk.
 
 ### Hand off unfinished work
 
 When a worker fails, gets blocked or is cancelled, it can say what the next worker should know. The manager passes that along in the next order:
 
-<p align="center"><img src="docs/handoff.svg" alt="Worker A reports failed with a handoff; the manager reissues the job to Worker B with the same handoff: summary, decisions, what was tried, open questions and next step" width="760"></p>
+<p align="center"><img src="docs/handoff.svg" alt="Worker A reports failed with a handoff; the manager cancels that order and reissues the job to Worker B with continues pointing at it and the same handoff: summary, decisions, what was tried, open questions and next step" width="760"></p>
 
 ```ts
 await desk.submitReport(order.id, {
@@ -107,10 +115,13 @@ await desk.submitReport(order.id, {
 }, "agent:researcher");
 
 const { handoff } = (await desk.get(order.id)).reports.at(-1)!;
-await desk.create({ ...nextJob, to: "agent:other-worker", handoff }, "agent:manager");
+await desk.cancel(order.id, "agent:manager", "reissuing");   // a continued order must be finished
+await desk.create({ ...nextJob, to: "agent:other-worker", handoff, continues: order.id }, "agent:manager");
+
+await desk.list({ continues: order.id });   // the orders that pick up from this one
 ```
 
-`context` lists what to read; `handoff` says what was decided and already tried. See [SPEC.md §4.4](SPEC.md#44-handoff).
+`context` lists what to read; `handoff` says what was decided and already tried; `continues` links the new order to the one it replaces, so the chain of orders is the job's full history. Unlike `parent_id`, it doesn't narrow anything: the new order can have a different worker, budget and tools. See [SPEC.md §4.4](SPEC.md#44-handoff) and [§4.5](SPEC.md#45-continuation).
 
 ## Validate documents
 
@@ -132,7 +143,7 @@ The JSON Schemas are exported too: `workOrderSchema`, `workReportSchema`, or `ag
 
 The server lives in its own package, [`agent-work-layer-mcp`](packages/mcp/), so people who only validate documents don't download the MCP SDK.
 
-Each agent session runs its own desk process. Sessions share one folder, and each is locked to one identity, so a worker cannot approve its own work.
+**For development, over stdio.** Each agent session runs its own desk process. Sessions share one folder, and each is locked to the identity it is started with.
 
 ```sh
 # Claude Code: a manager session and a worker session, each added in its own project folder
@@ -140,7 +151,14 @@ claude mcp add awl -e AWL_STORE="$HOME/.awl" -e AWL_ACTOR=agent:manager -- npx -
 claude mcp add awl -e AWL_STORE="$HOME/.awl" -e AWL_ACTOR=agent:worker  -- npx -y agent-work-layer-mcp
 ```
 
-Tools: `create_work_order`, `list_work_orders`, `get_work_order`, `accept_work_order`, `decline_work_order`, `start_work_order`, `submit_work_report`, `answer_question`, `review_work_report`, `cancel_work_order`, `wait_for_update`.
+**For shared use, over HTTP.** One desk serves every agent, and each request's credential decides who it acts as, so a worker cannot approve its own work ([details](#authenticated-actor)):
+
+```sh
+npx -y agent-work-layer-mcp serve --keys keys.json        # { "keys": { "<key>": "agent:manager", ... } }
+claude mcp add --transport http awl http://127.0.0.1:8787/mcp --header "Authorization: Bearer $AWL_KEY"
+```
+
+Tools: `create_work_order`, `list_work_orders`, `get_work_order`, `accept_work_order`, `decline_work_order`, `start_work_order`, `submit_work_report`, `answer_question`, `review_work_report`, `cancel_work_order`, `wait_for_update`, and `renew_work_pass` when the desk issues [Delegation Passes](#delegation-pass).
 
 To embed the server in your own process or transport (`npm install agent-work-layer agent-work-layer-mcp`):
 
@@ -161,7 +179,9 @@ npx agent-work-layer validate order.json report.json      # exit 1 on invalid, p
 npx agent-work-layer validate child.json --parent order.json
 npx agent-work-layer validate order.json report.json --json
 npx agent-work-layer schema order
-npx -y agent-work-layer-mcp --store ./.awl --actor agent:worker   # the MCP desk (was "awl desk" before 0.2)
+npx -y agent-work-layer-mcp --store ./.awl --actor agent:worker   # the MCP desk on stdio (was "awl desk" before 0.2)
+npx -y agent-work-layer-mcp serve --keys keys.json                 # one shared desk over HTTP; add --pass-key/--issuer to sign passes
+npx -y agent-work-layer-mcp gateway --order <id> --config <file>   # enforce an order at every tool call; add --pass-keys to use passes
 ```
 
 `new order` starts with one criterion, a USD 1 budget, no allowed tools and a
@@ -193,22 +213,27 @@ Any active state ──cancel──▶ cancelled   ·   deadline or budget excee
 
 | Export | Purpose |
 |---|---|
-| `WorkDesk` | Runs the lifecycle: `create`, `accept`, `decline`, `start`, `submitReport`, `answer`, `review`, `cancel`, `get`, `list`, `waitForChange` |
+| `WorkDesk` | Runs the lifecycle: `create`, `accept`, `decline`, `start`, `submitReport`, `answer`, `review`, `cancel`, `get`, `list`, `waitForChange`, and `issuePass` when it issues passes |
 | `MemoryStore`, `FileStore`, `SqliteStore`, `DeskStore` | Storage. Implement `DeskStore` (4 methods) to use a database |
 | `validateOrder`, `validateReport`, `validateChildOrder`, `hasInvalid` | Spec checks, returning `Finding[]` |
 | `isWorkOrder`, `isWorkReport` | Type guards |
 | `toolAllowed`, `patternCovered` | Tool pattern matching |
 | `nextState`, `allowedActions`, `STATES`, `ROLE_FOR`, `isTerminal` | The state machine |
 | `AwlError`, `isAwlError` | Typed errors with `code` and `findings` |
+| `signPass`, `verifyPass`, `decodePass`, `PassError` | [Delegation Passes](#delegation-pass): sign, verify (including narrowing against a parent), read |
 | `ORDER_SPEC`, `REPORT_SPEC`, `ORDER_SPECS`, `REPORT_SPECS` | The spec version written, and every version read |
 | `createDeskServer` (from `agent-work-layer-mcp`) | MCP server for a desk |
+| `createDeskHttpHandler`, `apiKeyAuth`, `bearerAuth`, `AuthError` (from `agent-work-layer-mcp`) | The desk over HTTP, with the actor from each request's credential |
+| `createGateway` (from `agent-work-layer-mcp`) | MCP gateway enforcing an order, or a Delegation Pass, at every tool call |
 
-`WorkDesk` options: `store`, `clock` (for tests), `newId`, `onEvent(event, record)` (webhooks, logging, metrics).
+`WorkDesk` options: `store`, `clock` (for tests), `newId`, `onEvent(event, record)` (webhooks, logging, metrics), `passes: { key, issuer, ttlSeconds? }` (sign Delegation Passes).
 
 ### Error codes
 
 `NOT_FOUND`, `ALREADY_EXISTS`, `FORBIDDEN`, `INVALID_TRANSITION`, `VALIDATION_FAILED` (with `findings`), `CONFLICT` (a concurrent writer got there first; re-read and retry), `BAD_REQUEST`.
 
+`PassError` codes: `MALFORMED`, `UNSUPPORTED`, `BAD_SIGNATURE`, `EXPIRED`, `NOT_YET_VALID`, `WRONG_ISSUER`, `WRONG_WORKER`, `WRONG_ORDER`, `WRONG_PARENT`, `WIDER_THAN_PARENT` (with `findings` from C1–C3).
+
 ### Custom storage
 
 `MemoryStore` keeps records in memory, `FileStore` writes one JSON file per order, and `SqliteStore` keeps them in a SQLite database using Node's built-in `node:sqlite` (Node 22.13+, no extra dependency):
@@ -234,7 +259,45 @@ class PostgresStore implements DeskStore {
 
 ## Production notes
 
-The desk trusts the `actor` it is given. In production, derive the actor from authentication, not from tool arguments. For real-time enforcement, run the MCP gateway (`npx -y agent-work-layer-mcp gateway`), which checks `tools` and `budget` at each tool call, not only when the report arrives. See [SPEC.md §9.1](SPEC.md#91-mcp-gateway) and [§10](SPEC.md#10-security).
+A stdio desk trusts the `actor` it is started with. In production, run one desk over HTTP that takes the actor from each request's credential: `npx -y agent-work-layer-mcp serve --keys keys.json`, or `createDeskHttpHandler` with your own `authenticate` hook (OAuth 2.1 bearer tokens, API keys, mTLS). See the [MCP package README](packages/mcp/README.md#shared-desk-over-http). For real-time enforcement, run the MCP gateway (`npx -y agent-work-layer-mcp gateway`), which checks `tools` and `budget` at each tool call, not only when the report arrives. When the gateway or another team's system can't read the desk, give it [Delegation Passes](#delegation-pass) instead. See [SPEC.md §9.1](SPEC.md#91-mcp-gateway) and [§10](SPEC.md#10-security).
+
+## Authenticated actor
+
+With stdio, each agent runs its own desk and declares its own `actor`, so a worker could start one as its manager. Over HTTP, every agent connects to one desk, which takes the actor from the request's credential through a pluggable `authenticate(request)` hook. Teams plug in what they already use: OAuth 2.1 bearer tokens, API keys or mTLS. An `actor` argument naming anyone else is refused ([#16](https://github.com/probita-ai/agent-work-layer/issues/16), [SPEC.md §10.1](SPEC.md#101-authenticated-actor)).
+
+<p align="center"><img src="docs/authenticated-actor.svg" alt="With stdio, a worker can start its own desk with --actor agent:manager and approve its own report. Over HTTP, agents send a credential to one desk, authenticate(request) maps it to an agent ref before the role check, and a spoofed actor argument is refused" width="760"></p>
+
+## Delegation Pass
+
+When a worker starts, the desk signs a short-lived pass (a JWS) carrying the order's tools, budget and deadline. The worker presents it with each tool call, and a gateway or another team's system verifies it on its own, without calling the desk. A sub-order gets a narrower pass that names its parent, so the delegation rules (C1–C3) can be checked offline ([#17](https://github.com/probita-ai/agent-work-layer/issues/17), [SPEC.md §10.2](SPEC.md#102-delegation-pass)).
+
+<p align="center"><img src="docs/delegation-pass.svg" alt="The desk signs a pass when the worker starts; the gateway verifies it on each tool call, allowing filings/search and refusing web/browse; a sub-order gets a narrower pass naming its parent. Below, the claims in a pass: iss, sub, awl_order, awl_tools, awl_budget, awl_parent, awl_deadline, awl_attempt, iat, exp, jti, and the typ awl-pass+jwt" width="760"></p>
+
+- A pass lasts 15 minutes by default, never past the deadline. The desk issues a new one each time the order enters `working`, and the worker renews it while it works.
+- It carries the order's whole budget; the gateway tracks what has been spent.
+- Cancelling or expiring the order stops new passes. There is no other revocation, which is why passes are short.
+
+```ts
+import { WorkDesk, verifyPass } from "agent-work-layer";
+
+const desk = new WorkDesk({ passes: { key: privateJwk, issuer: "https://desk.example.com" } });
+// ...create, accept...
+const { pass } = await desk.start(id, "agent:worker");   // renew with desk.issuePass(id, "agent:worker")
+
+// Anywhere else, with only the desk's public key:
+const verified = await verifyPass(pass, publicJwk, { issuer: "https://desk.example.com", worker: "agent:worker", order: id });
+verified.allows("filings/search");   // true
+const child = await verifyPass(childPass, publicJwk, { parent: verified });   // throws WIDER_THAN_PARENT if it breaks C1–C3
+```
+
+Keys are P-256 or Ed25519 JWKs (or WebCrypto keys) that you supply; the SDK does no key management. `signPass` and `verifyPass` use WebCrypto only, so they are also in `agent-work-layer/validate` for browsers, Deno and Bun. To make a key pair in Node:
+
+```js
+const { privateKey, publicKey } = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);
+console.log(JSON.stringify(await crypto.subtle.exportKey("jwk", privateKey)), JSON.stringify(await crypto.subtle.exportKey("jwk", publicKey)));
+```
+
+Over MCP, `awl-desk serve --pass-key priv.json --issuer <url>` issues passes, and `awl-desk gateway --pass-keys pub.json` enforces them; see the [MCP package README](packages/mcp/README.md#delegation-passes).
 
 ## Development
 
@@ -250,6 +313,14 @@ npm run check          # all of the above; runs automatically before npm publish
 npm run generate       # after editing schemas/*.json: refreshes packages/core/src/generated.ts
 ```
 
+The Python package in [`python/`](python/) is separate from the npm workspace:
+
+```sh
+cd python
+python -m venv .venv && .venv/bin/pip install -e ".[test]"
+.venv/bin/pytest
+```
+
 ## Contributing
 
 Issues, ideas and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and the [roadmap](ROADMAP.md). Spec changes start as a **Spec proposal** issue.

package/SPEC.md

@@ -1,4 +1,4 @@
-# Agent Work Layer (AWL) — Specification v0.2 (draft)
+# Agent Work Layer (AWL) — Specification v0.3 (draft)
 
 Status: draft · Date: 2026-10-09 · Changes from v0.1: the optional `handoff` field (§4.4); MCP gateway (§9.1); readers accept both versions (§11); related work (§13).
 
@@ -39,7 +39,7 @@ The key words MUST, SHOULD and MAY are used as in RFC 2119.
 
 | Field          | Req | Type                | Meaning |
 |----------------|-----|---------------------|---------|
-| `spec`         | yes | `"awl/work-order@0.2"` | Format and version. Readers also accept `@0.1` (§11). |
+| `spec`         | yes | `"awl/work-order@0.3"` | Format and version. Readers also accept `@0.1` and `@0.2` (§11). |
 | `id`           | yes | string              | Unique job id, set by the desk or manager. |
 | `created_at`   | yes | timestamp           | When the order was issued. |
 | `from`         | yes | agent ref           | The manager. |
@@ -55,6 +55,7 @@ The key words MUST, SHOULD and MAY are used as in RFC 2119.
 | `handoff`      | no  | Handoff (§4.4)      | What earlier work on this job established. |
 | `output_schema`| no  | JSON Schema         | Shape that `result.output` MUST match when done. |
 | `parent_id`    | no  | string              | Set when this order was split from a larger one (§8). |
+| `continues`    | no  | string              | The id of the finished order this one picks up from (§4.5). |
 | `metadata`     | no  | object              | Free-form; ignored by checks. |
 
 ### 4.1 Criterion
@@ -100,7 +101,21 @@ When a job moves from one worker to another (after a failure, a cancellation or
 | `open_questions` | array of string               | Questions still unanswered. |
 | `next_step`      | string                        | The most useful thing to do next. |
 
-Every field is optional, but a handoff MUST NOT be empty. A Work Report MAY carry a handoff (§5); a worker SHOULD include one when it reports `failed` or `blocked`. A manager reissuing the job MAY copy it, edited or not, into the new order. Handoff content is the previous worker's account, not verified fact; it is not checked against evidence.
+Every field is optional, but a handoff MUST NOT be empty. A Work Report MAY carry a handoff (§5); a worker SHOULD include one when it reports `failed` or `blocked`. A manager reissuing the job MAY copy it, edited or not, into the new order, and SHOULD link the two with `continues` (§4.5). Handoff content is the previous worker's account, not verified fact; it is not checked against evidence.
+
+### 4.5 Continuation
+
+When a job moves to another worker after it stopped, the new order names the order it picks up from in `continues`. A chain of orders linked this way is the full history of one job: who worked on it, and under which order, and so which authority, each earlier action ran.
+
+`continues` is not `parent_id`. A sub-order (§8) is part of a live order and may only narrow it; a continuation replaces a finished one. No narrowing rules apply: the new order may have a different worker, budget, tools and deadline. An order MAY have both, e.g. a sub-order reissued under the same parent.
+
+A desk MUST reject an order whose `continues`:
+
+- names no order it knows;
+- names an order that is not in a terminal state (`approved`, `declined`, `expired` or `cancelled`), so two orders are never live for the same job. A `failed` or `blocked` report leaves the order `submitted` or `blocked`; the manager cancels it first;
+- names an order that another order already continues, so the chain stays a single line.
+
+A desk SHOULD also accept continuations only from the earlier order's manager (`from`). Each order in a chain keeps its own budget and cost; nothing is carried over unless the manager puts it in the new order, usually as `handoff`.
 
 ## 5. Work Report
 
@@ -224,6 +239,9 @@ A gateway is an MCP server that sits between one worker and its real MCP servers
 5. It numbers the calls that reach a tool 1, 2, 3… per order, across reworks, and names each `<server>/<tool>#<n>`. That name is the `ref` of `tool_call` evidence (§5.1), and the gateway SHOULD return it with the call's result.
 6. It SHOULD keep a log of every call, refused ones included, that survives a restart, so restarting the gateway does not reset the budget.
 7. The report's `tools_used` and its `cost.tool_calls` and `cost.seconds` SHOULD be taken from the gateway's log.
+8. Each logged call SHOULD record the authority it ran under: the order id, the report attempt in progress (`reports` + 1) and, when there is one, the `jti` of the Delegation Pass (§10.2). A resumed or reissued job can then tell which grant applied to every earlier call.
+
+A gateway MAY work from **Delegation Passes** instead of the desk's order state (§10.2). It then requires a valid pass for its order and worker on every call, and enforces the pass's `awl_tools` and `awl_budget.tool_calls` in place of rules 1–3. A pass does not say when the order was started, so `budget.seconds` is left to the report checks.
 
 A gateway MAY instead run in **observe** mode, for deployments whose own gateway or policy engine already controls access. It then applies rules 4–7 but not 1–3: it refuses nothing, and it SHOULD mark each logged call that rules 1–3 would have refused. Calls over budget or to tools the order does not allow still show up in the report, where checks R5 and R7 catch them.
 
@@ -231,19 +249,64 @@ The gateway cannot measure `usd` or `tokens`; those are still checked when the r
 
 ## 10. Security
 
-- A desk MUST bind `actor` to an authenticated identity in production. The reference desk trusts the `actor` argument and is for development only.
+- A desk MUST bind `actor` to an authenticated identity in production (§10.1). The reference stdio desk trusts the identity it is started with and is for development only.
 - A worker's MCP gateway SHOULD enforce `tools` and `budget` at call time, not only after the report arrives (§9.1).
 - Evidence `ref` values can point at sensitive data. Desks SHOULD apply the same access rules to evidence as to the data it points at.
 
+### 10.1 Authenticated actor
+
+`actor` is bound to an authenticated identity when the desk, not the caller, decides it:
+
+- The desk derives the actor from a credential it has verified on the same request (an OAuth 2.1 access token, an API key, a client certificate), through a hook `authenticate(request) → AgentRef`. The desk does not define how credentials are issued or stored.
+- A request whose credential is missing or invalid MUST be refused before any operation runs (HTTP 401). A valid credential that maps to no agent MUST be refused too (HTTP 403).
+- The authenticated actor is the only actor for that request. An `actor` argument naming anyone else MUST be refused with `FORBIDDEN`; naming the same agent is allowed. The role checks of §6 then run against that actor.
+- A desk SHOULD authenticate every request, not only the first one of a session, so a session never outlives its credential.
+
+For an MCP desk over Streamable HTTP, the desk is an OAuth resource server as the MCP authorization spec describes. When it accepts bearer tokens it MUST check that a token is unexpired and was issued for the desk (`aud`), SHOULD answer 401 with a `WWW-Authenticate` header naming its Protected Resource Metadata (RFC 9728), and maps the token's subject to an agent reference, either as is or through a configured map. A desk over stdio is not bound: whoever starts the process chooses its identity.
+
+### 10.2 Delegation Pass
+
+A Delegation Pass is an order's authority as a signed token: which tools, how much budget, until when, for which job and which worker. A gateway, a tool server or a sub-worker in another system can check a worker's authority with it, without calling the desk.
+
+A pass is a JWS in compact form (a JWT) with header `typ` `awl-pass+jwt` and `alg` `ES256` (P-256) or `EdDSA` (Ed25519). Its claims:
+
+| Claim | Value |
+|---|---|
+| `iss` | The desk that issued it |
+| `sub` | The worker: the order's `to` |
+| `awl_order` | The order's `id` |
+| `awl_parent` | The parent order's `id`, for sub-orders |
+| `awl_tools` | The order's `tools` |
+| `awl_budget` | The order's whole `budget`, not what is left of it |
+| `awl_deadline` | The order's `deadline` |
+| `awl_attempt` | The report attempt the pass was issued for: `reports` + 1 |
+| `iat`, `exp` | Issue and expiry time, in seconds since the epoch |
+| `jti` | A unique id for this pass |
+
+**Issuing.** A desk that issues passes signs one for the worker each time the order enters `working`, and on request while it stays `working`. A pass's `exp` MUST NOT be later than `awl_deadline`, and SHOULD be short (the reference desk uses 15 minutes); the worker renews it while it works. Short lifetimes are the only revocation: when an order is cancelled, expires or leaves `working`, the desk stops issuing passes for it. The desk SHOULD give a pass only to the authenticated worker (§10.1); a pass is only as trustworthy as the identity it was issued to.
+
+**Verifying.** A verifier MUST reject a pass whose signature does not verify with one of the issuer's keys, whose `typ` or `alg` is not one of the above, that has expired (at `exp` or `awl_deadline`, whichever is sooner), or whose `iat` is in the future by more than an allowance for clock skew (the reference verifier allows 60 seconds). It SHOULD check `iss`, and that `sub` and `awl_order` are the worker and order it expects. A tool call is allowed when a pattern in `awl_tools` allows it (§4.3).
+
+**Narrowing.** A sub-order's pass names its parent in `awl_parent`. A verifier holding a pass and its parent's pass checks C1–C3 (§8) between their `awl_budget`, `awl_tools` and `awl_deadline`, and MUST reject a pass wider than its parent's or naming a different parent. A chain is verified from the top down.
+
+Key distribution, rotation and JWKS hosting are out of scope. The reference implementation is `signPass` and `verifyPass` in `agent-work-layer`, which use WebCrypto only.
+
 ## 11. Versioning
 
 `spec` carries the version. Minor versions (0.x) may add optional fields only. Readers MUST reject a major version they do not know.
 
-A v0.2 reader MUST accept documents marked `@0.1` and `@0.2`, and MUST reject any other version. A v0.2 writer marks new documents `@0.2`. Every v0.1 document is a valid v0.2 document once its version is accepted.
+Each document type has its own version. v0.3 adds `continues` to the Work Order and leaves the Work Report unchanged:
+
+| Spec | Work Order | Work Report |
+|---|---|---|
+| v0.1 | `@0.1` | `@0.1` |
+| v0.2 | `@0.2` (adds `handoff`) | `@0.2` (adds `handoff`) |
+| v0.3 | `@0.3` (adds `continues`) | `@0.2` |
+
+A v0.3 reader MUST accept Work Orders marked `@0.1`, `@0.2` and `@0.3`, and Work Reports marked `@0.1` and `@0.2`, and MUST reject any other version. A v0.3 writer marks new orders `@0.3` and new reports `@0.2`. Every earlier document is a valid v0.3 document once its version is accepted.
 
 ## 12. Planned for later versions
 
-- Delegation Pass: a signed, standalone grant of budget, tools and time.
 - Track record: an aggregate of approved reports per worker.
 - Streaming progress events while `working`.
 

package/dist/desk.d.ts

@@ -1,3 +1,4 @@
+import type { PassKey } from "./pass.ts";
 import type { DeskStore } from "./store.ts";
 import type { AgentRef, Finding, OrderRecord, OrderSummary, State, WorkEvent, WorkOrderInput, WorkReportInput } from "./types.ts";
 export interface DeskOptions {
@@ -9,12 +10,28 @@ export interface DeskOptions {
     newId?: () => string;
     /** Called after every recorded event, once it is stored. */
     onEvent?: (event: WorkEvent, record: OrderRecord) => void;
+    /**
+     * Issue Delegation Passes (SPEC.md §10.2): the desk signs a pass for the worker each time an
+     * order enters `working`, and `issuePass` renews it. Without this, the desk issues none.
+     */
+    passes?: PassOptions;
+}
+export interface PassOptions {
+    /** Private signing key (P-256 or Ed25519). */
+    key: PassKey;
+    /** Goes in each pass's `iss`. */
+    issuer: string;
+    /** Lifetime in seconds, capped at the order's deadline. Default 900. */
+    ttlSeconds?: number;
+    kid?: string;
 }
 export interface ListFilter {
     to?: AgentRef;
     from?: AgentRef;
     state?: State;
     parent_id?: string;
+    /** Orders that continue this order id. */
+    continues?: string;
 }
 export interface WaitOptions {
     timeoutMs?: number;
@@ -32,13 +49,18 @@ export declare class WorkDesk {
     #private;
     readonly store: DeskStore;
     constructor(options?: DeskOptions);
+    /** True when this desk signs Delegation Passes. */
+    get issuesPasses(): boolean;
     /** The full record for an order. Throws NOT_FOUND. */
     get(id: string): Promise<OrderRecord>;
     /** Summaries of orders matching every given filter field. */
     list(filter?: ListFilter): Promise<OrderSummary[]>;
     /** Resolves once the order has an event newer than `sinceSeq`, or when the timeout passes. */
     waitForChange(id: string, sinceSeq: number, options?: WaitOptions): Promise<OrderRecord>;
-    /** Issues a new order. With `parent_id`, only the parent's worker may create it, and only narrower (§8). */
+    /**
+     * Issues a new order. With `parent_id`, only the parent's worker may create it, and only narrower (§8).
+     * With `continues`, the earlier order must be finished, be the same manager's, and not be continued yet (§4.5).
+     */
     create(input: WorkOrderInput, actor: AgentRef): Promise<OrderRecord>;
     answer(id: string, actor: AgentRef, answer: string): Promise<OrderRecord>;
     review(id: string, actor: AgentRef, decision: "approve" | "rework", reason?: string): Promise<OrderRecord>;
@@ -46,6 +68,11 @@ export declare class WorkDesk {
     accept(id: string, actor: AgentRef): Promise<OrderRecord>;
     decline(id: string, actor: AgentRef, reason?: string): Promise<OrderRecord>;
     start(id: string, actor: AgentRef): Promise<OrderRecord>;
+    /**
+     * Signs a fresh Delegation Pass for the order's worker while the order is `working`, replacing
+     * the current one. Workers call it before the current pass expires. Records no event.
+     */
+    issuePass(id: string, actor: AgentRef): Promise<string>;
     /**
      * Records a report. Invalid reports throw VALIDATION_FAILED and change nothing.
      * Reports over budget or past the deadline are kept and move the order to `expired`.

package/dist/desk.js

@@ -2,24 +2,34 @@
 import { randomUUID } from "node:crypto";
 import { AwlError } from "./errors.js";
 import { isTerminal, nextState, ROLE_FOR } from "./lifecycle.js";
+import { signPass } from "./pass.js";
 import { MemoryStore } from "./store.js";
 import { hasInvalid, validateChildOrder, validateOrder, validateReport } from "./validate.js";
 import { ORDER_SPEC, REPORT_SPEC } from "./types.js";
 export const lastSeq = (record) => record.events.at(-1)?.seq ?? 0;
 export function summarize(record) {
-    const { id, from, to, goal, deadline, parent_id } = record.order;
-    return { id, state: record.state, from, to, goal, deadline, ...(parent_id ? { parent_id } : {}), last_seq: lastSeq(record) };
+    const { id, from, to, goal, deadline, parent_id, continues } = record.order;
+    return {
+        id, state: record.state, from, to, goal, deadline,
+        ...(parent_id ? { parent_id } : {}), ...(continues ? { continues } : {}), last_seq: lastSeq(record),
+    };
 }
 export class WorkDesk {
     store;
     #clock;
     #newId;
     #onEvent;
+    #passes;
     constructor(options = {}) {
         this.store = options.store ?? new MemoryStore();
         this.#clock = options.clock ?? (() => new Date());
         this.#newId = options.newId ?? (() => `wo_${randomUUID().replace(/-/g, "").slice(0, 16)}`);
         this.#onEvent = options.onEvent;
+        this.#passes = options.passes;
+    }
+    /** True when this desk signs Delegation Passes. */
+    get issuesPasses() {
+        return this.#passes !== undefined;
     }
     // ---- reads ----------------------------------------------------------------
     /** The full record for an order. Throws NOT_FOUND. */
@@ -36,7 +46,8 @@ export class WorkDesk {
             .filter((r) => (!filter.to || r.order.to === filter.to) &&
             (!filter.from || r.order.from === filter.from) &&
             (!filter.state || r.state === filter.state) &&
-            (!filter.parent_id || r.order.parent_id === filter.parent_id))
+            (!filter.parent_id || r.order.parent_id === filter.parent_id) &&
+            (!filter.continues || r.order.continues === filter.continues))
             .sort((a, b) => a.order.created_at.localeCompare(b.order.created_at))
             .map(summarize);
     }
@@ -52,7 +63,10 @@ export class WorkDesk {
         }
     }
     // ---- manager actions ------------------------------------------------------
-    /** Issues a new order. With `parent_id`, only the parent's worker may create it, and only narrower (§8). */
+    /**
+     * Issues a new order. With `parent_id`, only the parent's worker may create it, and only narrower (§8).
+     * With `continues`, the earlier order must be finished, be the same manager's, and not be continued yet (§4.5).
+     */
     async create(input, actor) {
         requireActor(actor);
         const order = {
@@ -75,6 +89,17 @@ export class WorkDesk {
             if (childFindings.length)
                 throw new AwlError("VALIDATION_FAILED", "sub-order exceeds its parent's authority", childFindings);
         }
+        if (order.continues) {
+            const earlier = await this.get(order.continues);
+            if (!isTerminal(earlier.state)) {
+                throw new AwlError("INVALID_TRANSITION", `order "${order.continues}" is ${earlier.state}; only a finished order can be continued`);
+            }
+            if (actor !== earlier.order.from)
+                throw new AwlError("FORBIDDEN", `only the manager of "${order.continues}" can continue it`);
+            const next = (await this.store.list()).find((r) => r.order.continues === order.continues);
+            if (next)
+                throw new AwlError("ALREADY_EXISTS", `order "${order.continues}" is already continued by "${next.order.id}"`);
+        }
         const record = { order, state: "offered", reports: [], events: [], findings: [] };
         const event = this.#record(record, actor, "create", "offered");
         await this.store.insert(record);
@@ -106,6 +131,23 @@ export class WorkDesk {
     async start(id, actor) {
         return this.#act(id, "start", actor);
     }
+    /**
+     * Signs a fresh Delegation Pass for the order's worker while the order is `working`, replacing
+     * the current one. Workers call it before the current pass expires. Records no event.
+     */
+    async issuePass(id, actor) {
+        requireActor(actor);
+        if (!this.#passes)
+            throw new AwlError("BAD_REQUEST", "this desk does not issue passes");
+        const record = await this.#mutate(id, async (rec) => {
+            if (actor !== rec.order.to)
+                throw new AwlError("FORBIDDEN", `only the order's worker can get its pass`);
+            if (rec.state !== "working")
+                throw new AwlError("INVALID_TRANSITION", `no pass for an order that is ${rec.state}`);
+            rec.pass = await this.#sign(rec);
+        });
+        return record.pass;
+    }
     /**
      * Records a report. Invalid reports throw VALIDATION_FAILED and change nothing.
      * Reports over budget or past the deadline are kept and move the order to `expired`.
@@ -147,6 +189,17 @@ export class WorkDesk {
     #now() {
         return this.#clock().toISOString();
     }
+    #sign(record) {
+        const { key, issuer, ttlSeconds, kid } = this.#passes;
+        return signPass(record.order, key, { issuer, ttlSeconds, kid, attempt: record.reports.length + 1, now: this.#clock() });
+    }
+    /** A pass is issued on entering `working` and dropped on leaving it; cancel or expiry just stops new ones. */
+    async #syncPass(record, before) {
+        if (record.state !== "working")
+            delete record.pass;
+        else if (this.#passes && before !== "working")
+            record.pass = await this.#sign(record);
+    }
     #emit(event, record) {
         this.#onEvent?.(event, structuredClone(record));
     }
@@ -190,7 +243,9 @@ export class WorkDesk {
     async #mutate(id, change) {
         const record = await this.get(id);
         const expected = lastSeq(record);
-        change(record);
+        const before = record.state;
+        await change(record);
+        await this.#syncPass(record, before);
         await this.store.update(record, expected);
         return record;
     }
@@ -200,6 +255,7 @@ export class WorkDesk {
             return record;
         const expected = lastSeq(record);
         const event = this.#record(record, "desk", "expire", "expired", "deadline passed");
+        delete record.pass;
         try {
             await this.store.update(record, expected);
         }

package/dist/generated.js

@@ -1,11 +1,11 @@
 // Generated by scripts/generate.ts from package.json and schemas/*.json. Do not edit.
 /** This package's version. */
-export const VERSION = "0.4.0";
+export const VERSION = "0.5.0";
 /** The Work Order JSON Schema (schemas/work-order.schema.json). */
 export const workOrderSchema = {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://awl.dev/schemas/work-order-0.2.json",
-    "title": "AWL Work Order v0.2",
+    "$id": "https://awl.dev/schemas/work-order-0.3.json",
+    "title": "AWL Work Order v0.3",
     "type": "object",
     "required": [
         "spec",
@@ -23,7 +23,8 @@ export const workOrderSchema = {
         "spec": {
             "enum": [
                 "awl/work-order@0.1",
-                "awl/work-order@0.2"
+                "awl/work-order@0.2",
+                "awl/work-order@0.3"
             ]
         },
         "id": {
@@ -117,6 +118,10 @@ export const workOrderSchema = {
             "type": "string",
             "minLength": 1
         },
+        "continues": {
+            "type": "string",
+            "minLength": 1
+        },
         "metadata": {
             "type": "object"
         }

package/dist/index.d.ts

@@ -7,10 +7,12 @@ export * from "./types.ts";
 export { AwlError, isAwlError } from "./errors.ts";
 export type { AwlErrorCode } from "./errors.ts";
 export { validateOrder, validateReport, validateChildOrder, hasInvalid, isWorkOrder, isWorkReport, toolAllowed, patternCovered, workOrderSchema, workReportSchema, } from "./validate.ts";
+export { signPass, verifyPass, decodePass, PassError, PASS_TYP, PASS_TTL_SECONDS } from "./pass.ts";
+export type { PassClaims, PassKey, PassKeys, PassJwk, PassCryptoKey, PassErrorCode, SignPassOptions, VerifyPassOptions, VerifiedPass } from "./pass.ts";
 export { STATES, TERMINAL_STATES, ROLE_FOR, isTerminal, nextState, allowedActions } from "./lifecycle.ts";
 export type { Role } from "./lifecycle.ts";
 export { WorkDesk, summarize, lastSeq } from "./desk.ts";
-export type { DeskOptions, ListFilter, WaitOptions, SubmitResult } from "./desk.ts";
+export type { DeskOptions, PassOptions, ListFilter, WaitOptions, SubmitResult } from "./desk.ts";
 export { MemoryStore, FileStore, SqliteStore } from "./store.ts";
 export type { DeskStore } from "./store.ts";
 export { VERSION } from "./version.ts";

package/dist/index.js

@@ -6,6 +6,7 @@
 export * from "./types.js";
 export { AwlError, isAwlError } from "./errors.js";
 export { validateOrder, validateReport, validateChildOrder, hasInvalid, isWorkOrder, isWorkReport, toolAllowed, patternCovered, workOrderSchema, workReportSchema, } from "./validate.js";
+export { signPass, verifyPass, decodePass, PassError, PASS_TYP, PASS_TTL_SECONDS } from "./pass.js";
 export { STATES, TERMINAL_STATES, ROLE_FOR, isTerminal, nextState, allowedActions } from "./lifecycle.js";
 export { WorkDesk, summarize, lastSeq } from "./desk.js";
 export { MemoryStore, FileStore, SqliteStore } from "./store.js";

package/dist/pass.d.ts

@@ -0,0 +1,114 @@
+import type { AgentRef, Amounts, Finding, WorkOrder } from "./types.ts";
+/** The JWS `typ` of every pass, so a pass is never mistaken for another kind of token. */
+export declare const PASS_TYP = "awl-pass+jwt";
+/** Default lifetime: 15 minutes, and never past the order's deadline. */
+export declare const PASS_TTL_SECONDS = 900;
+export interface PassClaims {
+    /** The desk that issued the pass. */
+    iss: string;
+    /** The worker the pass was issued to: the order's `to`. */
+    sub: AgentRef;
+    awl_order: string;
+    /** The parent order's id, for sub-orders. */
+    awl_parent?: string;
+    /** The order's tool patterns. */
+    awl_tools: string[];
+    /** The order's whole budget, not what is left of it. */
+    awl_budget: Amounts;
+    /** The order's deadline (RFC 3339). `exp` is never later. */
+    awl_deadline: string;
+    /** The report attempt the pass was issued for: 1, then +1 per report. */
+    awl_attempt?: number;
+    /** Issue and expiry times, in seconds since the epoch. */
+    iat: number;
+    exp: number;
+    /** Unique id of this pass. */
+    jti: string;
+}
+/** A JWK: a P-256 EC key (ES256) or an Ed25519 OKP key (EdDSA). */
+export interface PassJwk {
+    kty: string;
+    crv: string;
+    x: string;
+    y?: string;
+    /** The private part; needed to sign. */
+    d?: string;
+    kid?: string;
+    [member: string]: unknown;
+}
+/** A WebCrypto `CryptoKey`, described by shape so this module needs no DOM or Node types. */
+export interface PassCryptoKey {
+    readonly type: string;
+    readonly algorithm: {
+        name: string;
+        namedCurve?: string;
+    };
+    readonly usages: readonly string[];
+}
+/** A JWK or a WebCrypto key. Private to sign, public to verify. */
+export type PassKey = PassJwk | PassCryptoKey;
+/** One key, several, or a JWK Set. */
+export type PassKeys = PassKey | readonly PassKey[] | {
+    keys: readonly PassJwk[];
+};
+export type PassErrorCode = "MALFORMED" | "UNSUPPORTED" | "BAD_SIGNATURE" | "EXPIRED" | "NOT_YET_VALID" | "WRONG_ISSUER" | "WRONG_WORKER" | "WRONG_ORDER" | "WRONG_PARENT" | "WIDER_THAN_PARENT";
+/** Why a pass could not be signed or was rejected. `findings` is set for WIDER_THAN_PARENT (rules C1–C3). */
+export declare class PassError extends Error {
+    readonly code: PassErrorCode;
+    readonly findings: Finding[];
+    constructor(code: PassErrorCode, message: string, findings?: Finding[]);
+    toJSON(): {
+        code: PassErrorCode;
+        message: string;
+        findings: Finding[];
+    };
+}
+export interface SignPassOptions {
+    /** Goes in `iss`; verifiers check it. */
+    issuer: string;
+    /** The report attempt the pass is for. */
+    attempt?: number;
+    /** Lifetime in seconds, capped at the order's deadline. Default 900. */
+    ttlSeconds?: number;
+    /** Key id for the JWS header. Default: the JWK's `kid`. */
+    kid?: string;
+    now?: Date;
+    jti?: string;
+}
+export interface VerifyPassOptions {
+    /** Required `iss`. */
+    issuer?: string;
+    /** Required `sub`: the worker presenting the pass. */
+    worker?: AgentRef;
+    /** Required `awl_order`. */
+    order?: string;
+    /**
+     * The parent order's verified pass. The pass must then name it in `awl_parent` and be no
+     * wider than it (C1–C3). Verify a chain from the top down, passing each result to the next.
+     */
+    parent?: VerifiedPass;
+    /** Seconds of clock skew to allow on `exp` (default 0) and on `iat` (at least 60, since issuer and verifier clocks differ). */
+    clockToleranceSeconds?: number;
+    now?: Date;
+}
+export interface VerifiedPass {
+    claims: PassClaims;
+    header: {
+        alg: string;
+        typ: string;
+        kid?: string;
+    };
+    /** When the pass stops being valid: `exp`, or the deadline if sooner. */
+    expiresAt: Date;
+    /** Does the pass allow this concrete tool (`server/tool`)? */
+    allows(tool: string): boolean;
+}
+/** Signs a pass for an order's worker. */
+export declare function signPass(order: WorkOrder, key: PassKey, options: SignPassOptions): Promise<string>;
+/** Reads a pass's claims without checking anything. For display and routing only; use verifyPass to trust it. */
+export declare function decodePass(token: string): PassClaims;
+/**
+ * Verifies a pass: its signature against `keys`, its type and lifetime, and, when asked,
+ * its issuer, worker, order and narrowing against the parent's pass. Throws a PassError.
+ */
+export declare function verifyPass(token: string, keys: PassKeys, options?: VerifyPassOptions): Promise<VerifiedPass>;

package/dist/pass.js

@@ -0,0 +1,200 @@
+// Delegation Pass (SPEC.md §10.2): an order's authority as a signed JWT anyone can verify.
+// WebCrypto only, no Node built-ins: this also runs in browsers, Deno and Bun (see src/validator.ts).
+import { toolAllowed, validateChildOrder } from "./validate.js";
+import { UNITS } from "./types.js";
+/** The JWS `typ` of every pass, so a pass is never mistaken for another kind of token. */
+export const PASS_TYP = "awl-pass+jwt";
+/** Default lifetime: 15 minutes, and never past the order's deadline. */
+export const PASS_TTL_SECONDS = 900;
+/** How far in the future `iat` may be: the issuer's clock may run ahead of the verifier's. */
+const IAT_SKEW_SECONDS = 60;
+/** Why a pass could not be signed or was rejected. `findings` is set for WIDER_THAN_PARENT (rules C1–C3). */
+export class PassError extends Error {
+    code;
+    findings;
+    constructor(code, message, findings = []) {
+        super(message);
+        this.name = "PassError";
+        this.code = code;
+        this.findings = findings;
+    }
+    toJSON() {
+        return { code: this.code, message: this.message, findings: this.findings };
+    }
+}
+const webcrypto = () => globalThis.crypto;
+const ALGS = {
+    ES256: { key: { name: "ECDSA", namedCurve: "P-256" }, sign: { name: "ECDSA", hash: "SHA-256" } },
+    EdDSA: { key: { name: "Ed25519" }, sign: { name: "Ed25519" } },
+};
+const utf8 = new TextEncoder();
+function b64url(bytes) {
+    let s = "";
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function unb64url(s) {
+    if (!/^[A-Za-z0-9_-]*$/.test(s) || s.length % 4 === 1)
+        throw new PassError("MALFORMED", "not base64url");
+    const bin = atob(s.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((s.length + 3) % 4));
+    return Uint8Array.from(bin, (c) => c.charCodeAt(0));
+}
+const isCryptoKey = (key) => "algorithm" in key && "usages" in key;
+function algOf(key) {
+    if (isCryptoKey(key)) {
+        const a = key.algorithm;
+        if (a.name === "ECDSA" && a.namedCurve === "P-256")
+            return "ES256";
+        if (a.name === "Ed25519")
+            return "EdDSA";
+    }
+    else {
+        if (key.kty === "EC" && key.crv === "P-256")
+            return "ES256";
+        if (key.kty === "OKP" && key.crv === "Ed25519")
+            return "EdDSA";
+    }
+    throw new PassError("UNSUPPORTED", "pass keys must be P-256 (ES256) or Ed25519 (EdDSA)");
+}
+async function cryptoKey(key, alg, use) {
+    if (isCryptoKey(key))
+        return key;
+    // Verifying only needs the public part; dropping the rest also drops key_ops that would forbid it.
+    const { kty, crv, x, y, d } = key;
+    const jwk = { kty, crv, x, ...(y ? { y } : {}), ...(use === "sign" ? { d } : {}) };
+    if (use === "sign" && !d)
+        throw new PassError("UNSUPPORTED", "signing needs a private key");
+    return webcrypto().subtle.importKey("jwk", jwk, ALGS[alg].key, false, [use]);
+}
+function keyList(keys) {
+    if (Array.isArray(keys))
+        return keys;
+    if ("keys" in keys && Array.isArray(keys.keys))
+        return keys.keys;
+    return [keys];
+}
+/** Signs a pass for an order's worker. */
+export async function signPass(order, key, options) {
+    const { issuer, attempt, ttlSeconds = PASS_TTL_SECONDS, now = new Date(), jti = webcrypto().randomUUID() } = options;
+    if (!issuer)
+        throw new PassError("MALFORMED", "a pass needs an issuer");
+    const alg = algOf(key);
+    const kid = options.kid ?? (isCryptoKey(key) ? undefined : key.kid);
+    const iat = Math.floor(now.getTime() / 1000);
+    const exp = Math.floor(Math.min(now.getTime() + ttlSeconds * 1000, Date.parse(order.deadline)) / 1000);
+    if (exp <= iat)
+        throw new PassError("EXPIRED", `order "${order.id}" is past its deadline`);
+    const claims = {
+        iss: issuer,
+        sub: order.to,
+        awl_order: order.id,
+        ...(order.parent_id ? { awl_parent: order.parent_id } : {}),
+        awl_tools: [...order.tools],
+        awl_budget: { ...order.budget },
+        awl_deadline: order.deadline,
+        ...(attempt !== undefined ? { awl_attempt: attempt } : {}),
+        iat,
+        exp,
+        jti,
+    };
+    const header = { alg, typ: PASS_TYP, ...(kid ? { kid } : {}) };
+    const input = `${b64url(utf8.encode(JSON.stringify(header)))}.${b64url(utf8.encode(JSON.stringify(claims)))}`;
+    const signature = await webcrypto().subtle.sign(ALGS[alg].sign, await cryptoKey(key, alg, "sign"), utf8.encode(input));
+    return `${input}.${b64url(new Uint8Array(signature))}`;
+}
+/** Reads a pass's claims without checking anything. For display and routing only; use verifyPass to trust it. */
+export function decodePass(token) {
+    const parts = typeof token === "string" ? token.split(".") : [];
+    if (parts.length !== 3)
+        throw new PassError("MALFORMED", "a pass is three base64url parts joined by dots");
+    try {
+        return JSON.parse(new TextDecoder().decode(unb64url(parts[1])));
+    }
+    catch (e) {
+        throw e instanceof PassError ? e : new PassError("MALFORMED", "the claims are not JSON");
+    }
+}
+const isString = (v) => typeof v === "string" && v.length > 0;
+const isTime = (v) => typeof v === "number" && Number.isFinite(v);
+function checkShape(c) {
+    const budget = c.awl_budget;
+    const ok = isString(c.iss) && isString(c.sub) && isString(c.awl_order) && isString(c.jti) &&
+        (c.awl_parent === undefined || isString(c.awl_parent)) &&
+        Array.isArray(c.awl_tools) && c.awl_tools.every(isString) &&
+        !!budget && typeof budget === "object" && !Array.isArray(budget) &&
+        Object.entries(budget).every(([unit, v]) => UNITS.includes(unit) && typeof v === "number" && v >= 0) &&
+        isString(c.awl_deadline) && !Number.isNaN(Date.parse(c.awl_deadline)) &&
+        (c.awl_attempt === undefined || (Number.isInteger(c.awl_attempt) && c.awl_attempt >= 1)) &&
+        isTime(c.iat) && isTime(c.exp);
+    if (!ok)
+        throw new PassError("MALFORMED", "the claims do not match the pass format");
+}
+/**
+ * Verifies a pass: its signature against `keys`, its type and lifetime, and, when asked,
+ * its issuer, worker, order and narrowing against the parent's pass. Throws a PassError.
+ */
+export async function verifyPass(token, keys, options = {}) {
+    const { issuer, worker, order, parent, clockToleranceSeconds = 0, now = new Date() } = options;
+    const parts = typeof token === "string" ? token.split(".") : [];
+    if (parts.length !== 3)
+        throw new PassError("MALFORMED", "a pass is three base64url parts joined by dots");
+    let header;
+    let claims;
+    try {
+        header = JSON.parse(new TextDecoder().decode(unb64url(parts[0])));
+        claims = JSON.parse(new TextDecoder().decode(unb64url(parts[1])));
+    }
+    catch {
+        throw new PassError("MALFORMED", "the header or claims are not base64url JSON");
+    }
+    if (!header || typeof header !== "object" || header.typ !== PASS_TYP)
+        throw new PassError("MALFORMED", `typ must be "${PASS_TYP}"`);
+    if (!Object.hasOwn(ALGS, header.alg))
+        throw new PassError("UNSUPPORTED", `unsupported alg "${String(header.alg)}"`);
+    const alg = header.alg;
+    const candidates = keyList(keys).filter((k) => {
+        try {
+            return algOf(k) === alg && (!header.kid || isCryptoKey(k) || !k.kid || k.kid === header.kid);
+        }
+        catch {
+            return false;
+        }
+    });
+    const signature = unb64url(parts[2]);
+    const data = utf8.encode(`${parts[0]}.${parts[1]}`);
+    let valid = false;
+    for (const k of candidates) {
+        if (await webcrypto().subtle.verify(ALGS[alg].sign, await cryptoKey(k, alg, "verify"), signature, data)) {
+            valid = true;
+            break;
+        }
+    }
+    if (!valid)
+        throw new PassError("BAD_SIGNATURE", "no key verifies this pass");
+    if (!claims || typeof claims !== "object" || Array.isArray(claims))
+        throw new PassError("MALFORMED", "the claims are not an object");
+    checkShape(claims);
+    const c = claims;
+    if (issuer !== undefined && c.iss !== issuer)
+        throw new PassError("WRONG_ISSUER", `issued by "${c.iss}", not "${issuer}"`);
+    const t = now.getTime();
+    const expiresAt = new Date(Math.min(c.exp * 1000, Date.parse(c.awl_deadline)));
+    if (expiresAt.getTime() + clockToleranceSeconds * 1000 <= t)
+        throw new PassError("EXPIRED", `pass "${c.jti}" expired at ${expiresAt.toISOString()}`);
+    if ((c.iat - Math.max(clockToleranceSeconds, IAT_SKEW_SECONDS)) * 1000 > t)
+        throw new PassError("NOT_YET_VALID", `pass "${c.jti}" is issued in the future`);
+    if (worker !== undefined && c.sub !== worker)
+        throw new PassError("WRONG_WORKER", `issued to "${c.sub}", not "${worker}"`);
+    if (order !== undefined && c.awl_order !== order)
+        throw new PassError("WRONG_ORDER", `for order "${c.awl_order}", not "${order}"`);
+    if (parent) {
+        if (c.awl_parent !== parent.claims.awl_order) {
+            throw new PassError("WRONG_PARENT", `pass names parent "${c.awl_parent ?? "(none)"}", not "${parent.claims.awl_order}"`);
+        }
+        const findings = validateChildOrder({ budget: c.awl_budget, tools: c.awl_tools, deadline: c.awl_deadline }, { budget: parent.claims.awl_budget, tools: parent.claims.awl_tools, deadline: parent.claims.awl_deadline });
+        if (findings.length)
+            throw new PassError("WIDER_THAN_PARENT", `pass for "${c.awl_order}" is wider than its parent's`, findings);
+    }
+    return { claims: c, header, expiresAt, allows: (tool) => toolAllowed(tool, c.awl_tools) };
+}

package/dist/store.d.ts

@@ -23,7 +23,8 @@ export declare class MemoryStore implements DeskStore {
 }
 /**
  * One JSON file per order in `<dir>/orders`. Several processes may share a folder.
- * Writes are atomic (write then rename); the CONFLICT check is best-effort across processes.
+ * Writes are atomic (write then rename). Within one process, writes to an order run one at a
+ * time, so the CONFLICT check is exact; across processes it is best-effort.
  */
 export declare class FileStore implements DeskStore {
     #private;

package/dist/store.js

@@ -1,4 +1,5 @@
 // Storage for desks. Implement DeskStore to back a desk with a database.
+import { randomUUID } from "node:crypto";
 import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { join } from "node:path";
@@ -32,11 +33,14 @@ export class MemoryStore {
 const SAFE_ID = /^[A-Za-z0-9_.-]{1,128}$/;
 /**
  * One JSON file per order in `<dir>/orders`. Several processes may share a folder.
- * Writes are atomic (write then rename); the CONFLICT check is best-effort across processes.
+ * Writes are atomic (write then rename). Within one process, writes to an order run one at a
+ * time, so the CONFLICT check is exact; across processes it is best-effort.
  */
 export class FileStore {
     dir;
     #ready;
+    /** Tail of each order's queue of pending writes. */
+    #queues = new Map();
     constructor(dir) {
         this.dir = join(dir, "orders");
         this.#ready = mkdir(this.dir, { recursive: true });
@@ -48,7 +52,7 @@ export class FileStore {
     }
     async #write(record) {
         const file = this.#path(record.order.id);
-        const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+        const tmp = `${file}.${randomUUID()}.tmp`;
         await writeFile(tmp, JSON.stringify(record, null, 2));
         await rename(tmp, file);
     }
@@ -63,18 +67,35 @@ export class FileStore {
             throw e;
         }
     }
+    /** Runs `fn` after every earlier write to order `id` in this process has finished. */
+    async #serial(id, fn) {
+        const run = (this.#queues.get(id) ?? Promise.resolve()).then(fn);
+        const tail = run.catch(() => { });
+        this.#queues.set(id, tail);
+        try {
+            return await run;
+        }
+        finally {
+            if (this.#queues.get(id) === tail)
+                this.#queues.delete(id);
+        }
+    }
     async insert(record) {
-        if (await this.read(record.order.id))
-            throw new AwlError("ALREADY_EXISTS", `order "${record.order.id}" already exists`);
-        await this.#write(record);
+        await this.#serial(record.order.id, async () => {
+            if (await this.read(record.order.id))
+                throw new AwlError("ALREADY_EXISTS", `order "${record.order.id}" already exists`);
+            await this.#write(record);
+        });
     }
     async update(record, expectedSeq) {
-        const current = await this.read(record.order.id);
-        if (!current)
-            throw new AwlError("NOT_FOUND", `no order "${record.order.id}"`);
-        if (lastSeq(current) !== expectedSeq)
-            throw new AwlError("CONFLICT", `order "${record.order.id}" changed since it was read`);
-        await this.#write(record);
+        await this.#serial(record.order.id, async () => {
+            const current = await this.read(record.order.id);
+            if (!current)
+                throw new AwlError("NOT_FOUND", `no order "${record.order.id}"`);
+            if (lastSeq(current) !== expectedSeq)
+                throw new AwlError("CONFLICT", `order "${record.order.id}" changed since it was read`);
+            await this.#write(record);
+        });
     }
     async list() {
         await this.#ready;

package/dist/types.d.ts

@@ -1,9 +1,9 @@
-/** Document types for AWL v0.2. Field meanings are defined in SPEC.md §4 and §5. */
+/** Document types for AWL v0.3. Field meanings are defined in SPEC.md §4 and §5. */
 /** The spec version this package writes. */
-export declare const ORDER_SPEC = "awl/work-order@0.2";
+export declare const ORDER_SPEC = "awl/work-order@0.3";
 export declare const REPORT_SPEC = "awl/work-report@0.2";
 /** Every spec version this package reads (SPEC.md §11). */
-export declare const ORDER_SPECS: readonly ["awl/work-order@0.1", "awl/work-order@0.2"];
+export declare const ORDER_SPECS: readonly ["awl/work-order@0.1", "awl/work-order@0.2", "awl/work-order@0.3"];
 export declare const REPORT_SPECS: readonly ["awl/work-report@0.1", "awl/work-report@0.2"];
 /** An Agent Card URL, an agent name, or `human:<id>`. */
 export type AgentRef = string;
@@ -51,6 +51,8 @@ export interface WorkOrder {
     handoff?: Handoff;
     output_schema?: Record<string, unknown>;
     parent_id?: string;
+    /** The order this one picks up from, after it stopped (§4.5). Not a sub-order: no narrowing applies. */
+    continues?: string;
     metadata?: Record<string, unknown>;
     [extension: `x-${string}`]: unknown;
 }
@@ -124,6 +126,8 @@ export interface OrderRecord {
     reports: WorkReport[];
     events: WorkEvent[];
     findings: Finding[];
+    /** The worker's current Delegation Pass (SPEC.md §10.2), while the order is `working` on a desk that issues passes. */
+    pass?: string;
 }
 export interface OrderSummary {
     id: string;
@@ -133,5 +137,6 @@ export interface OrderSummary {
     goal: string;
     deadline: string;
     parent_id?: string;
+    continues?: string;
     last_seq: number;
 }

package/dist/types.js

@@ -1,9 +1,9 @@
-/** Document types for AWL v0.2. Field meanings are defined in SPEC.md §4 and §5. */
+/** Document types for AWL v0.3. Field meanings are defined in SPEC.md §4 and §5. */
 /** The spec version this package writes. */
-export const ORDER_SPEC = "awl/work-order@0.2";
+export const ORDER_SPEC = "awl/work-order@0.3";
 export const REPORT_SPEC = "awl/work-report@0.2";
 /** Every spec version this package reads (SPEC.md §11). */
-export const ORDER_SPECS = ["awl/work-order@0.1", ORDER_SPEC];
+export const ORDER_SPECS = ["awl/work-order@0.1", "awl/work-order@0.2", ORDER_SPEC];
 export const REPORT_SPECS = ["awl/work-report@0.1", REPORT_SPEC];
 /** Budget and cost units (SPEC.md §4.2). */
 export const UNITS = ["usd", "tokens", "tool_calls", "seconds"];

package/dist/validate.d.ts

@@ -14,7 +14,9 @@ export declare const isWorkReport: (value: unknown) => value is WorkReport;
 export declare function validateOrder(order: unknown): Finding[];
 /** Runs report checks R1–R12 against the order it answers. The order is assumed valid. */
 export declare function validateReport(report: unknown, order: WorkOrder): Finding[];
+/** The parts of an order (or a Delegation Pass) that carry authority. */
+type Authority = Pick<WorkOrder, "budget" | "tools" | "deadline">;
 /** Runs sub-order checks C1–C3: a child order may only narrow its parent's authority. */
-export declare function validateChildOrder(child: WorkOrder, parent: WorkOrder): Finding[];
+export declare function validateChildOrder(child: Authority, parent: Authority): Finding[];
 /** True when any finding rejects the document. */
 export declare const hasInvalid: (findings: readonly Finding[]) => boolean;

package/dist/validator.d.ts

@@ -1,7 +1,10 @@
 /**
- * Validation only: document types, JSON Schemas and every check in SPEC.md §7–§8.
+ * Validation only: document types, JSON Schemas, every check in SPEC.md §7–§8, and Delegation Pass
+ * signing and verification (§10.2, WebCrypto).
  * Imports no Node built-ins, so it runs in browsers, Deno and Bun.
  * @packageDocumentation
  */
 export * from "./types.ts";
 export { validateOrder, validateReport, validateChildOrder, hasInvalid, isWorkOrder, isWorkReport, toolAllowed, patternCovered, workOrderSchema, workReportSchema, } from "./validate.ts";
+export { signPass, verifyPass, decodePass, PassError, PASS_TYP, PASS_TTL_SECONDS } from "./pass.ts";
+export type { PassClaims, PassKey, PassKeys, PassJwk, PassCryptoKey, PassErrorCode, SignPassOptions, VerifyPassOptions, VerifiedPass } from "./pass.ts";

package/dist/validator.js

@@ -1,7 +1,9 @@
 /**
- * Validation only: document types, JSON Schemas and every check in SPEC.md §7–§8.
+ * Validation only: document types, JSON Schemas, every check in SPEC.md §7–§8, and Delegation Pass
+ * signing and verification (§10.2, WebCrypto).
  * Imports no Node built-ins, so it runs in browsers, Deno and Bun.
  * @packageDocumentation
  */
 export * from "./types.js";
 export { validateOrder, validateReport, validateChildOrder, hasInvalid, isWorkOrder, isWorkReport, toolAllowed, patternCovered, workOrderSchema, workReportSchema, } from "./validate.js";
+export { signPass, verifyPass, decodePass, PassError, PASS_TYP, PASS_TTL_SECONDS } from "./pass.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-work-layer",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Work Orders and Work Reports for AI agents: a typed SDK, validator and lifecycle desk. The MCP server is in agent-work-layer-mcp.",
   "keywords": [
     "ai",

package/schemas/work-order.schema.json

@@ -1,11 +1,11 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://awl.dev/schemas/work-order-0.2.json",
-  "title": "AWL Work Order v0.2",
+  "$id": "https://awl.dev/schemas/work-order-0.3.json",
+  "title": "AWL Work Order v0.3",
   "type": "object",
   "required": ["spec", "id", "created_at", "from", "to", "goal", "criteria", "budget", "deadline", "tools"],
   "properties": {
-    "spec": { "enum": ["awl/work-order@0.1", "awl/work-order@0.2"] },
+    "spec": { "enum": ["awl/work-order@0.1", "awl/work-order@0.2", "awl/work-order@0.3"] },
     "id": { "type": "string", "minLength": 1, "maxLength": 128 },
     "created_at": { "type": "string", "format": "date-time" },
     "from": { "$ref": "#/$defs/agentRef" },
@@ -41,6 +41,7 @@
     "handoff": { "$ref": "#/$defs/handoff" },
     "output_schema": { "type": "object" },
     "parent_id": { "type": "string", "minLength": 1 },
+    "continues": { "type": "string", "minLength": 1 },
     "metadata": { "type": "object" }
   },
   "patternProperties": { "^x-": {} },