Enables AI agents to exchange structured work orders and reports with verifiable evidence, budgets, and tool usage tracking.
Also known as probita-ai/agent-work-layer, agent-work-layer-mcp
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- Apache-2.0
What is agent-work-layer MCP?
agent-work-layer enables AI agents to exchange structured work orders and reports with verifiable evidence, budgets, and tool usage tracking.
Summary generated from the project's README
About agent-work-layer MCP server
Managing complex tasks between different AI agents is what agent-work-layer enables through a structured lifecycle of work orders and reports. It provides a framework where a manager agent can define a specific goal, budget, deadline, and allowed tools, while a worker agent returns a report containing verifiable evidence and actual costs. This ensures that every task completed by an agent is checkable against the original requirements.
Developers can use this system locally via stdio for individual agent sessions or remotely over HTTP for shared use across multiple agents. The MCP server implementation allows connecting agent sessions like Claude Code to this layer using specific environment variables for the actor identity and store location. It is particularly useful for workflows requiring high accountability, as it supports staged tools that hold write actions like sending emails until a manager approves the final report.
What you can do with it
- 1Verifying task completionAn AI client can check if a worker's results match the requested criteria using provided evidence.
- 2Preventing unauthorized actionsDevelopers can use staged tools to ensure that write operations are only executed after a human or manager reviews the report.
- 3Handing off failed jobsWhen an agent fails a task, it can pass its decisions and attempted steps to a new worker to continue the job.
Written from the project's README. Every use case is checked against a quote from it.
How to install agent-work-layer MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall agent-work-layer MCP in Claude Code
$ claude mcp add agent-work-layer -- npx -y agent-work-layerInstall agent-work-layer MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"agent-work-layer": {
"command": "npx",
"args": [
"-y",
"agent-work-layer"
]
}
}
}Install agent-work-layer MCP in VS Code
.vscode/mcp.json
{
"servers": {
"agent-work-layer": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"agent-work-layer"
]
}
}
}Install agent-work-layer MCP in VS Code CLI
$ code --add-mcp '{"name":"agent-work-layer","type":"stdio","command":"npx","args":["-y","agent-work-layer"]}'Install agent-work-layer MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"agent-work-layer": {
"command": "npx",
"args": [
"-y",
"agent-work-layer"
]
}
}
}Install agent-work-layer MCP in Codex
$ codex mcp add agent-work-layer -- npx -y agent-work-layerInstall agent-work-layer MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.agent-work-layer] command = "npx" args = ["-y", "agent-work-layer"]
Install agent-work-layer MCP in Gemini CLI
$ gemini mcp add -s user agent-work-layer npx -- -y agent-work-layerInstall agent-work-layer MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"agent-work-layer": {
"command": "npx",
"args": [
"-y",
"agent-work-layer"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableprobita-ai/agent-work-layer is public and reachablegithub.com/probita-ai/agent-work-layer ↗Pass
- Package names this repository as its sourceagent-work-layer, agent-work-layer-mcp name probita-ai/agent-work-layer as sourcenpmjs.com/package/agent-work-layer ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for agent-work-layer, agent-work-layer-mcpnpmjs.com/package/agent-work-layer/v/0.10.0#provenance ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/probita-ai/agent-work-layer ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from agent-work-layer, agent-work-layer-mcpPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubagent-work-layer
Work Orders and Work Reports for AI agents. A typed SDK, validator and lifecycle engine for handing work from one agent to another, with checkable results. The MCP server is a separate package, agent-work-layer-mcp.
- 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.
Agent Cards say who an agent is. A2A carries messages between agents. MCP connects agents to tools. AWL describes the job itself, so any manager can hand work to any worker and check what came back. The format is defined in SPEC.md.
How it works
- A manager issues a Work Order: goal, criteria, budget, deadline, allowed tools.
- A worker accepts it and does the job with its tools.
- The worker returns a Work Report with evidence for every criterion and what it spent.
- The desk checks the report against the order. The manager approves it or sends it back.
More diagrams: message sequence · lifecycle · delegation · handoff · staged tools · authenticated actor · Delegation Pass · JWS vs JWT
Install
Install only the part you use:
| You want to… | Install | Packages |
|---|---|---|
| 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/) |
11 |
| Connect agent sessions (e.g. Claude Code) through MCP | npx -y agent-work-layer-mcp (setup) |
~100 |
| Hand work to another agent over A2A | npm install agent-work-layer, then import agent-work-layer/a2a (how) |
7 |
| Sign or verify Delegation Passes | npm install agent-work-layer (how) |
7 |
Node.js 20.11 or later. ESM only. Types included. The Python package needs Python 3.9 or later.
Quick start
import { WorkDesk } from "agent-work-layer";
const desk = new WorkDesk(); // in-memory; use FileStore, SqliteStore or your own DeskStore to persist
// Manager issues a job
const { order } = await desk.create(
{
to: "agent:researcher",
goal: "Summarize the main risk factors in the latest annual report",
criteria: [
{ id: "c1", text: "Lists three risk factors, each quoted from the filing" },
{ id: "c2", text: "States total debt and its fiscal year" },
],
budget: { usd: 2, tool_calls: 20 },
deadline: new Date(Date.now() + 3_600_000).toISOString(),
tools: ["filings/*"],
},
"agent:manager",
);
// Worker accepts, does the work, reports with evidence
await desk.accept(order.id, "agent:researcher");
const { record } = await desk.submitReport(
order.id,
{
status: "done",
result: { summary: "Refinancing, customer concentration and FX risk. Debt 1.2B USD (FY2025)." },
evidence: [
{ criterion: "c1", type: "tool_call", ref: "filings/get_section#3" },
{ criterion: "c2", type: "citation", ref: "filings/get_section#5" },
],
cost: { usd: 0.84, tool_calls: 7 },
tools_used: ["filings/search", "filings/get_section"],
},
"agent:researcher",
);
// Manager approves, or sends it back with a reason
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 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.
- Which state changes are legal.
- Evidence for every criterion.
- Only allowed tools.
- Cost within budget and finishing before the deadline. Going over either expires the order.
- Behind the MCP gateway, a report can't claim less than the gateway measured: evidence must cite calls it logged, and cost and tools used must cover what it counted.
- Sub-orders can only narrow their parent's authority. Their budgets come out of the parent's, so a whole tree of sub-orders never spends more than the order at its root.
- 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 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:
await desk.submitReport(order.id, {
status: "failed",
error: "Export runs out of memory on files over 2 GB",
handoff: {
decisions: [{ text: "Stream rows instead of buffering", why: "Memory limit" }],
tried: [{ text: "xlsx library", result: "Too slow on large files" }],
next_step: "Add tests for null cells",
},
/* result, evidence, cost, tools_used */
}, "agent:researcher");
const { handoff } = (await desk.get(order.id)).reports.at(-1)!;
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; 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 and §4.5.
Hold writes until the report is approved
Rejecting a report doesn't unsend an email. For tools whose effects you want to review first, list them in staged:
await desk.create({ ...job, tools: ["filings/*", "gmail/*"], staged: ["gmail/send"] }, "agent:manager");
The worker's MCP gateway then holds back calls to gmail/send: it counts and logs each one and returns a placeholder (pending:gmail/send#4). The worker lists them in its report's effects, which the manager reviews with the rest of the report. Approving lets the gateway run them; rework drops them, and since they never ran, there is nothing to undo. Reads still run normally. A sub-order can't allow a tool its parent stages (C5).
A staged call can use an earlier one's result: pass { "$ref": "github/create_issue#3", "pointer": "/structuredContent/number" } as an argument, and the gateway fills it in when it runs the effects. The manager can also approve only some effects:
await desk.review(order.id, "agent:manager", "approve", "Send the CFO copy only", { effects: ["gmail/send#4"] });
See SPEC.md §4.6.
Follow progress and track records
await desk.progress(order.id, "agent:researcher", "Risk section read; checking the debt note", 60);
await desk.trackRecord("agent:researcher");
// { orders: 12, approved: 9, approved_first_time: 7, reworks: 3, expired: 1, ..., spent: { usd: 8.4 }, budget: { usd: 24 } }
Progress notes are progress events: they change no state, but waitForChange and wait_for_update wake on them. A track record counts what happened to the orders a desk holds for one worker. See SPEC.md §6.2 and §6.3.
Validate documents
import { validateOrder, validateReport, hasInvalid } from "agent-work-layer";
const findings = validateReport(report, order);
// [{ rule: "R4", kind: "invalid", path: "/evidence", message: 'no evidence for criterion "c2"' }, ...]
if (hasInvalid(findings)) reject(findings);
To check a report against what the order's gateway measured (R17–R19), pass it: validateReport(report, order, { usage }). The desk does this itself when the gateway records its measurement (SPEC.md §7.3).
Every finding carries the rule id from SPEC.md §7. invalid findings reject a document. limit findings (over budget, past deadline) are recorded and expire the order.
Writing a validator in another language? Run it against the JSON test vectors in conformance/: documents with the findings each rule must report.
The JSON Schemas are exported too: workOrderSchema, workReportSchema, or agent-work-layer/schemas/work-order.schema.json.
agent-work-layer/validate has the same checks, types and schemas without the desk. It imports nothing from Node, so it runs in browsers, Deno and Bun. (Cloudflare Workers are not supported: the validator compiles schemas to code at runtime, which Workers block.)
Run as an MCP server
The server lives in its own package, agent-work-layer-mcp, so people who only validate documents don't download the MCP SDK.
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.
# Claude Code: a manager session and a worker session, each added in its own project folder
claude mcp add awl -e AWL_STORE="$HOME/.awl" -e AWL_ACTOR=agent:manager -- npx -y agent-work-layer-mcp
claude mcp add awl -e AWL_STORE="$HOME/.awl" -e AWL_ACTOR=agent:worker -- npx -y agent-work-layer-mcp
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):
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, report_progress, submit_work_report, answer_question, review_work_report, allow_effect_retry, cancel_work_order, wait_for_update, get_track_record, and renew_work_pass when the desk issues Delegation Passes.
To enforce an order while the worker works, and to hold its staged writes until you approve, connect the worker to its real MCP servers through the gateway: npx -y agent-work-layer-mcp gateway --order <id> --config upstream.json. After approval, --commit runs the approved writes. See the gateway docs.
To embed the server in your own process or transport (npm install agent-work-layer agent-work-layer-mcp):
import { WorkDesk, FileStore } from "agent-work-layer";
import { createDeskServer } from "agent-work-layer-mcp";
const server = createDeskServer({ desk: new WorkDesk({ store: new FileStore("./.awl") }), actor: "agent:manager" });
await server.connect(transport);
Hand work over A2A
Agents that talk A2A can hand Work Orders to each other without sharing a desk. One order is one A2A task. The manager keeps the desk and sends the order as a data part; the worker answers with its reports as task artifacts. agent-work-layer/a2a has the parts and the state mapping, and doesn't depend on any A2A SDK:
import { agentCardExtension, orderPart, recordTask, reviewPart } from "agent-work-layer/a2a";
// Worker: list the extension in its Agent Card, under capabilities.extensions.
const extension = agentCardExtension();
// Manager, with any A2A client: send the order, then let the desk record what the worker's task says.
const task = await a2aClient.sendMessage({ message: { kind: "message", role: "user", messageId, parts: [orderPart(order)] } });
const { record } = await recordTask(desk, order.id, task, "agent:researcher"); // authenticate the peer first
// Reviews go back on the same task.
await a2aClient.sendMessage({ message: { kind: "message", role: "user", messageId, taskId: task.id, parts: [reviewPart({ order_id: order.id, decision: "approve" })] } });
blocked and submitted orders are both input-required tasks, with the AWL state in metadata["awl/state"]. For a runnable version, run node examples/a2a.ts (Node 22.18+): a manager and a worker over A2A JSON-RPC, through a rework to approval. See SPEC.md §9.2.
CLI
npx agent-work-layer new order > order.json
npx agent-work-layer new report > report.json
npx agent-work-layer validate order.json report.json # exit 1 on invalid, prints rule ids
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 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
deadline one hour after creation. new report starts as blocked, with a question
and no evidence of completed work. Both templates validate together as printed.
Replace the placeholder goal, identities, criterion and report contents before
using them; keep the report's order_id equal to the order's id.
Lifecycle
offered ──accept──▶ accepted ──start──▶ working ──report done/failed──▶ submitted ──approve──▶ approved
│ │ ▲ │
decline blocked │ │ answer │ rework (with reason)
▼ ▼ │ ▼
declined blocked working
Any active state ──cancel──▶ cancelled · deadline or budget exceeded ──▶ expired
While working, the worker can post progress notes. They are recorded as events but don't change the state (SPEC.md §6.2).
| Action | Who |
|---|---|
| accept, decline, start, submit report, post progress | the worker (order.to) |
| record or settle effect outcomes, after approval | the worker |
| approve, rework, cancel, allow an effect retry | the manager (order.from) |
| answer a blocked worker | the manager or order.escalate_to |
| expire | the desk |
API
| Export | Purpose |
|---|---|
WorkDesk |
Runs the lifecycle: create, accept, decline, start, progress, recordUsage (from the gateway), submitReport, answer, review, cancel, get, list, subOrders, held, trackRecord, waitForChange, and issuePass when it issues passes. After approval: recordCommit, settle (worker) and allowRetry (manager) |
MemoryStore, FileStore, SqliteStore, DeskStore |
Storage. Implement DeskStore (4 methods) to use a database |
validateOrder, validateReport, validateChildOrder, validateChildBudgets, validateOwnCost, validateUsage, hasInvalid |
Spec checks, returning Finding[] |
heldBySubOrders |
The budget an order's sub-orders hold, which it may not spend itself |
isWorkOrder, isWorkReport |
Type guards |
toolAllowed, patternCovered |
Tool pattern matching |
effectReferences |
The references to earlier effects' results in an effect's arguments |
approvedEffects, effectOutcomes |
The effects an approval lets run, and what is known of each from the order's commit and settle events |
nextState, allowedActions, STATES, ROLE_FOR, isTerminal |
The state machine |
AwlError, isAwlError |
Typed errors with code and findings |
signPass, verifyPass, decodePass, PassError |
Delegation Passes: sign, verify (including narrowing against a parent), read |
orderSpecFor, reportSpecFor |
The lowest version that has every field a document uses, as the desk writes it |
ORDER_SPEC, REPORT_SPEC, ORDER_SPECS, REPORT_SPECS |
The newest spec version, and every version read |
orderPart, reportPart, reviewPart, readParts, taskState, taskStatus, agentCardExtension, recordTask (from agent-work-layer/a2a) |
The A2A binding |
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), 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 and C5).
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):
import { WorkDesk, SqliteStore } from "agent-work-layer";
const desk = new WorkDesk({ store: new SqliteStore("./awl.db") }); // or ":memory:"
To use another database, implement DeskStore:
import type { DeskStore, OrderRecord } from "agent-work-layer";
class PostgresStore implements DeskStore {
async read(id: string): Promise<OrderRecord | null> { /* SELECT */ }
async insert(record: OrderRecord) { /* INSERT, throw AwlError("ALREADY_EXISTS") on conflict */ }
async update(record: OrderRecord, expectedSeq: number, expectedRev?: number) {
/* UPDATE ... WHERE last_seq = expectedSeq AND rev = expectedRev, else AwlError("CONFLICT") */
}
async list() { /* SELECT */ }
}
Production notes
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. 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 instead. See SPEC.md §9.1 and §10.
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, SPEC.md §10.1).
agent-work-layer MCP questions
How do I add agent-work-layer MCP to Claude Code?
Run claude mcp add agent-work-layer -- npx -y agent-work-layer in your terminal. Add --scope user to make it available in every project.
How do I add agent-work-layer MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What is the purpose of agent-work-layer?
It provides a typed SDK, validator, and lifecycle engine for handing work from one agent to another with checkable results.
How does the system handle tool usage and budgets?
The system tracks tool calls and costs, ensuring they stay within the defined budget and deadline; exceeding these limits expires the order.