agent-work-layer 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 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).
+
+- README: diagram of a handoff moving a job from one worker to the next.
+
 ## 0.2.0 — 2026-10-09
 
 ### Breaking

package/README.md

@@ -21,7 +21,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)
+More diagrams: [message sequence](docs/sequence.svg) · [lifecycle](docs/lifecycle.svg) · [delegation](docs/delegation.svg) · [handoff](docs/handoff.svg)
 
 ## Install
 
@@ -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(
@@ -92,6 +92,8 @@ The desk enforces the spec as you go:
 
 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>
+
 ```ts
 await desk.submitReport(order.id, {
   status: "failed",
@@ -192,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 |
@@ -209,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";
 

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.0";
+export const VERSION = "0.3.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.0",
+  "version": "0.3.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",