agent-work-layer 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.4.0 — 2026-10-11
+
+Both packages: `agent-work-layer` 0.4.0 and `agent-work-layer-mcp` 0.4.0.
+
+### Added
+
+- MCP gateway (#6): `awl-desk gateway --order <id> --config <file>` sits between a worker and its real MCP servers and enforces the order at every tool call. It lists only the tools the order allows, refuses the rest, refuses calls once `tool_calls` or `seconds` is spent or while the order is not `working`, and logs each call to `<store>/calls/<id>.jsonl` with an evidence ref `<server>/<tool>#<n>`. Its `awl_usage` tool returns `tools_used` and `cost` for the report. In code: `createGateway` from `agent-work-layer-mcp`. Enforcement is optional: `--observe` (`enforce: false`) refuses nothing and logs what the order would have refused, for setups whose own gateway already controls access.
+- SPEC.md §9.1: what an MCP gateway must enforce.
+
+### Changed
+
+- `agent-work-layer-mcp` now depends on `agent-work-layer` ^0.4.0.
+
+## 0.3.0 — 2026-10-10
+
+Both packages: `agent-work-layer` 0.3.0 and `agent-work-layer-mcp` 0.3.0.
+
+### Added
+
+- `SqliteStore`: a `DeskStore` backed by SQLite through Node's built-in `node:sqlite` (Node 22.13+), with an atomic CONFLICT check (#1).
+
+### Changed
+
+- `agent-work-layer-mcp` now depends on `agent-work-layer` ^0.3.0.
+
 ## 0.2.1 — 2026-10-09
 
 Documentation only; `agent-work-layer` alone (`agent-work-layer-mcp` stays at 0.2.0).

package/README.md

@@ -40,7 +40,7 @@ Node.js 20.11 or later. ESM only. Types included.
 ```ts
 import { WorkDesk } from "agent-work-layer";
 
-const desk = new WorkDesk(); // in-memory; use FileStore or your own DeskStore to persist
+const desk = new WorkDesk(); // in-memory; use FileStore, SqliteStore or your own DeskStore to persist
 
 // Manager issues a job
 const { order } = await desk.create(
@@ -194,7 +194,7 @@ 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` |
-| `MemoryStore`, `FileStore`, `DeskStore` | Storage. Implement `DeskStore` (4 methods) to use a database |
+| `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 |
@@ -211,6 +211,16 @@ Any active state ──cancel──▶ cancelled   ·   deadline or budget excee
 
 ### 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):
+
+```ts
+import { WorkDesk, SqliteStore } from "agent-work-layer";
+
+const desk = new WorkDesk({ store: new SqliteStore("./awl.db") }); // or ":memory:"
+```
+
+To use another database, implement `DeskStore`:
+
 ```ts
 import type { DeskStore, OrderRecord } from "agent-work-layer";
 
@@ -224,7 +234,7 @@ 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, check `tools` and `budget` at each tool call in an MCP gateway, not only when the report arrives. See [SPEC.md §10](SPEC.md#10-security).
+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).
 
 ## Development
 

package/SPEC.md

@@ -1,6 +1,6 @@
 # Agent Work Layer (AWL) — Specification v0.2 (draft)
 
-Status: draft · Date: 2026-10-09 · Changes from v0.1: the optional `handoff` field (§4.4); readers accept both versions (§11); related work (§13).
+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).
 
 ## 1. Purpose
 
@@ -213,10 +213,26 @@ How AWL documents travel. A desk MAY support several.
 - **MCP**: a desk exposed as an MCP server with tools such as `create_work_order`, `submit_work_report` and `review_work_report`. The reference implementation is the `agent-work-layer-mcp` package in this repo.
 - **A2A**: the document travels as a data part of an A2A message with the AWL media type. The A2A task id SHOULD be stored in `metadata.a2a_task_id`.
 
+### 9.1 MCP gateway
+
+A gateway is an MCP server that sits between one worker and its real MCP servers, for one order. It enforces the order while the worker works, instead of only checking the report afterwards (§10).
+
+1. It MUST refuse a call to a tool that no pattern in `tools` allows (§4.3), and SHOULD NOT list such tools.
+2. It MUST refuse calls once `budget.tool_calls` calls have reached a tool, and once `budget.seconds` have passed since the order was first started. It SHOULD stop a running call when the seconds run out.
+3. It MUST refuse calls while the order is not `working`. It MAY start an `accepted` order on its first call.
+4. Refused calls do not reach the tool and do not count against the budget. A call that reached the tool counts even if the tool returned an error.
+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.
+
+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.
+
+The gateway cannot measure `usd` or `tokens`; those are still checked when the report arrives (R7). The reference implementation is `awl-desk gateway` in `agent-work-layer-mcp`.
+
 ## 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 worker's MCP gateway SHOULD enforce `tools` and `budget` at call time, not only after the report arrives.
+- 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.
 
 ## 11. Versioning

package/dist/generated.js

@@ -1,6 +1,6 @@
 // Generated by scripts/generate.ts from package.json and schemas/*.json. Do not edit.
 /** This package's version. */
-export const VERSION = "0.2.1";
+export const VERSION = "0.4.0";
 /** The Work Order JSON Schema (schemas/work-order.schema.json). */
 export const workOrderSchema = {
     "$schema": "https://json-schema.org/draft/2020-12/schema",

package/dist/index.d.ts

@@ -11,6 +11,6 @@ export { STATES, TERMINAL_STATES, ROLE_FOR, isTerminal, nextState, allowedAction
 export type { Role } from "./lifecycle.ts";
 export { WorkDesk, summarize, lastSeq } from "./desk.ts";
 export type { DeskOptions, ListFilter, WaitOptions, SubmitResult } from "./desk.ts";
-export { MemoryStore, FileStore } from "./store.ts";
+export { MemoryStore, FileStore, SqliteStore } from "./store.ts";
 export type { DeskStore } from "./store.ts";
 export { VERSION } from "./version.ts";

package/dist/index.js

@@ -8,5 +8,5 @@ export { AwlError, isAwlError } from "./errors.js";
 export { validateOrder, validateReport, validateChildOrder, hasInvalid, isWorkOrder, isWorkReport, toolAllowed, patternCovered, workOrderSchema, workReportSchema, } from "./validate.js";
 export { STATES, TERMINAL_STATES, ROLE_FOR, isTerminal, nextState, allowedActions } from "./lifecycle.js";
 export { WorkDesk, summarize, lastSeq } from "./desk.js";
-export { MemoryStore, FileStore } from "./store.js";
+export { MemoryStore, FileStore, SqliteStore } from "./store.js";
 export { VERSION } from "./version.js";

package/dist/store.d.ts

@@ -1,4 +1,5 @@
 import type { OrderRecord } from "./types.ts";
+import type { DatabaseSync } from "node:sqlite";
 export interface DeskStore {
     /** Returns the record, or null when there is none. */
     read(id: string): Promise<OrderRecord | null>;
@@ -33,3 +34,18 @@ export declare class FileStore implements DeskStore {
     update(record: OrderRecord, expectedSeq: number): Promise<void>;
     list(): Promise<OrderRecord[]>;
 }
+/**
+ * One SQLite database, using Node's built-in `node:sqlite` (Node 22.13+). Pass a file path,
+ * or ":memory:" for a throwaway database. Several processes may share a file; the CONFLICT
+ * check is atomic (`UPDATE ... WHERE last_seq = ?`).
+ */
+export declare class SqliteStore implements DeskStore {
+    readonly db: DatabaseSync;
+    constructor(path?: string);
+    read(id: string): Promise<OrderRecord | null>;
+    insert(record: OrderRecord): Promise<void>;
+    update(record: OrderRecord, expectedSeq: number): Promise<void>;
+    list(): Promise<OrderRecord[]>;
+    /** Closes the database. */
+    close(): void;
+}

package/dist/store.js

@@ -1,5 +1,6 @@
 // Storage for desks. Implement DeskStore to back a desk with a database.
 import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
 import { join } from "node:path";
 import { AwlError } from "./errors.js";
 const lastSeq = (r) => r.events.at(-1)?.seq ?? 0;
@@ -82,3 +83,53 @@ export class FileStore {
         return records.filter((r) => r !== null);
     }
 }
+/**
+ * One SQLite database, using Node's built-in `node:sqlite` (Node 22.13+). Pass a file path,
+ * or ":memory:" for a throwaway database. Several processes may share a file; the CONFLICT
+ * check is atomic (`UPDATE ... WHERE last_seq = ?`).
+ */
+export class SqliteStore {
+    db;
+    constructor(path = ":memory:") {
+        // Loaded here so importing the package does not need node:sqlite.
+        const { DatabaseSync } = createRequire(import.meta.url)("node:sqlite");
+        this.db = new DatabaseSync(path);
+        this.db.exec(`
+      PRAGMA busy_timeout = 5000;
+      CREATE TABLE IF NOT EXISTS orders (
+        id TEXT PRIMARY KEY,
+        last_seq INTEGER NOT NULL,
+        record TEXT NOT NULL
+      ) STRICT;
+    `);
+    }
+    async read(id) {
+        const row = this.db.prepare("SELECT record FROM orders WHERE id = ?").get(id);
+        return row ? JSON.parse(row.record) : null;
+    }
+    async insert(record) {
+        const { changes } = this.db
+            .prepare("INSERT INTO orders (id, last_seq, record) VALUES (?, ?, ?) ON CONFLICT (id) DO NOTHING")
+            .run(record.order.id, lastSeq(record), JSON.stringify(record));
+        if (!changes)
+            throw new AwlError("ALREADY_EXISTS", `order "${record.order.id}" already exists`);
+    }
+    async update(record, expectedSeq) {
+        const { changes } = this.db
+            .prepare("UPDATE orders SET last_seq = ?, record = ? WHERE id = ? AND last_seq = ?")
+            .run(lastSeq(record), JSON.stringify(record), record.order.id, expectedSeq);
+        if (changes)
+            return;
+        if (!(await this.read(record.order.id)))
+            throw new AwlError("NOT_FOUND", `no order "${record.order.id}"`);
+        throw new AwlError("CONFLICT", `order "${record.order.id}" changed since it was read`);
+    }
+    async list() {
+        const rows = this.db.prepare("SELECT record FROM orders ORDER BY id").all();
+        return rows.map((r) => JSON.parse(r.record));
+    }
+    /** Closes the database. */
+    close() {
+        this.db.close();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-work-layer",
-  "version": "0.2.1",
+  "version": "0.4.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",