v2.2.0

Stable · 2026-08-29 · Previous stable v2.1.0

The runtime release

2.1.0 made a round of team collaboration a governable Team Run. 2.2.0 moves down a layer and rebuilds the foundation beneath it: an employee is no longer synonymous with one built-in reasoning loop, and a long task is no longer synonymous with one uninterrupted request.

This release advances the runtime mainline:

• Employee runtimes become an explicit extension point. A shared runtime contract, provider registry, session factory, capability model, and lifecycle surface let an employee select a native or external runtime while reusing MateClaw conversations, permissions, workspaces, message persistence, and UI projection.
• DeepSeek Harness (DSH) enters the mainline. DSH runs as a managed external Agent runtime over an authenticated JSON-RPC process bridge, streaming thinking, text, tool calls, and lifecycle events. The console owns installation, configuration, verification, connection testing, and enable/disable controls.
• Long work becomes durable execution. Goals run as bounded segments scheduled by a database-backed supervisor. Queues, cooldowns, retries, attempts, accepted user input, and leases can recover after a backend restart.
• Agents can interoperate across systems. New A2A JSON-RPC / SSE ingress, Agent Cards, and the call_a2a_agent outbound tool let external agents call MateClaw employees and let MateClaw call peers within explicit network boundaries.
• Runtime boundaries get tighter. DSH tools still pass through host Tool Guard and workspace policy. Live administration, shared conversations, generated files, file mutation, and Wiki failure records now enforce workspace ownership more consistently.
• Long collaboration and delivery are hardened. Team checkpoints, board recovery, deliverable completion gates, worker attachments, retries, and synthesis are more reliable; long-form output and input arriving during approvals, stopping, or recovery are preserved.

Also included: an optional OfficeCLI document engine, configurable ACP prompt timeout, plugin tools in the employee picker, a WeChat execution-trace switch, restored custom model providers, and faster Live status loading.

---

1. Runtime Contract: decoupling employees from reasoning engines

2.2.0 introduces the AgentRuntimeProvider extension layer. A runtime starts an employee turn and emits a normalized event stream; MateClaw continues to own:

• employee identity, model binding, conversations, and message persistence;
• workspace resolution, tool catalogs, Tool Guard, and approvals;
• normalized projection into Chat and Agents Live;
• stop, cancel, completion, and failure lifecycle semantics.

Providers are selected by type through a registry. Sessions validate workspace, configuration, and capabilities before startup, so unknown or unavailable runtimes fail early instead of silently degrading halfway through a turn. The employee editor exposes runtime selection, while message and usage records retain the actual runtime provider for operational comparison.

Two paths ship today:

Runtime	Best for	Governance
Native	MateClaw ReAct / Plan-Execute, Goals, and Team Runs	Entirely inside MateClaw
DSH	DeepSeek Harness Agent loop and Cordis composition	DSH runs the loop; MateClaw owns sessions, policy, tools, and projection

---

2. DeepSeek Harness: external loop, host governance

DSH is not an MCP tool or a model provider. It is an employee-level runtime: MateClaw launches and manages dsh-jsonrpc-agent over authenticated JSON-RPC on stdin/stdout, then adapts its runtime events into the existing chat stream.

This release includes:

• DSH process/session management, per-conversation isolation, cancellation, and complete stream lifecycle;
• an authenticated bridge protocol plus text / thinking / tool / lifecycle event mapping;
• host tool descriptor projection, with every tool call returning to MateClaw for workspace policy and Tool Guard enforcement;
• DeepSeek provider credential injection without placing secrets in employee runtimeConfig;
• console installation, configuration, verification, connection testing, enable/disable controls, and redacted diagnostics;
• child-process environment isolation that forwards only controlled runtime values.

See DeepSeek Harness Integration for setup.

---

3. Persistent Goals: from “continue this turn” to “continue after restart”

New goals enable persistentExecution by default. Long work is split into bounded execution segments; ending one segment no longer ends the goal, because a supervisor schedules the next segment from persisted state.

The runtime now provides:

• a database-backed continuation queue, cooldowns, retries, and expired-lease recovery;
• goal attempts, single-goal run coordination, and startup recovery;
• a durable per-conversation input queue: messages arriving during execution wait and drain in order after an approval or segment boundary;
• transient-provider backoff and instance-wide pacing to avoid recovery request storms;
• explicit pauses for Stop, essential missing input, approval denial, and exhausted budgets, all requiring an explicit resume;
• a final persisted-checklist read before completion, requiring every criterion to pass with nonblank evidence.

GET /api/v1/goals/{id}/execution returns the latest scheduling state, reason, and due time; SSE broadcasts changes through goal_continuation. The current implementation targets a single backend instance using the native runtime. External tool effects are not guaranteed exactly once; recovery checks existing artifacts and asynchronous handles first.

See Persistent Goals.

---

4. A2A: making MateClaw a node in an agent network

2.2.0 ships both inbound and outbound A2A support:

• ingress for message/send, message/stream, tasks/get, and tasks/cancel;
• SSE task-status and artifact events with heartbeat comments;
• anonymous Agent Cards expose only minimal metadata, while enabled-employee skills remain Bearer-protected;
• idempotency snapshots, duplicate-task rejection, terminal TTL cleanup, and capacity limits bound task storage;
• call_a2a_agent discovers the peer Agent Card, sends work, and polls or parses SSE;
• redirects and private-network egress are rejected by default, with response-size and timeout limits guarding SSRF and resource exhaustion.

A2A is disabled by default. See A2A Protocol for deployment settings and endpoints.

---

5. Team Run and delivery reliability

The runtime work also hardens team execution:

• checkpoint loops and board recovery are idempotent, preventing duplicate evidence on long collaborations;
• required deliverables must be registered before a task or run can cross its completion gate;
• lead attachments reach workers, and generated files in worker replies become registered deliverables;
• clarification-only worker replies are not accepted as final results, and retry paths preserve required context;
• admins may inspect completed worker runs while normal conversation and workspace boundaries remain enforced;
• tool returnDirect, long-form final answers, and Team Run projection settle more reliably.

See Team Runs.

---

6. Tools, documents, and runtime details

• OfficeCLI (optional): inspect, validate, batch-edit, merge, and preview .docx, .xlsx, and .pptx. Inputs are copied into an isolated scratch directory and outputs are capped at 20 MB; its absence does not affect the built-in document tools.
• ACP prompt timeout: custom endpoints may allow longer prompt waits for coding runtimes that need extended startup or human confirmation.
• Tool discovery and execution: plugin tools appear in the employee picker, repeated plan-skill loading is suppressed, and input validation, returnDirect, and failure degradation are more consistent.
• Channels and UI: WeChat can expose execution traces; resumed conversations restore chat state; running/stopped labels are clearer; and Live queries are workspace-scoped with less loading overhead.

---

Upgrade notes

Existing 2.1.0 data remains compatible. Flyway applies V185–V189 for each supported dialect: OfficeCLI registration, employee runtime provider, ACP prompt timeout, goal continuation, and goal attempt / conversation input queue.

Before upgrading:

• New goals are durable by default. When turnBudget / llmCallBudget are omitted, 0 means no cumulative limit. Production deployments should set explicit budgets, concurrency, and provider-failure backoff. Existing goals retain their previous mode and do not auto-start after upgrade.
• DSH is optional. Native employees work without it. Before enabling DSH, use a dedicated working directory, a minimal tool set, and the console verify / connection test.
• A2A is off by default. Configure a stable public base URL, Bearer authentication, and outbound network policy before exposure. Do not enable private-network egress unless required.
• Recovery is not exactly once. Restart recovery resumes unfinished execution, but external APIs, shells, and third-party tools still need idempotency keys, artifact checks, or human confirmation.
• OfficeCLI is optional. The migration registers the capability; when officecli is absent from the server PATH it returns an explicit unavailable result without replacing the JVM-native tools.

---

What this means for you

If you operate different kinds of digital employees, 2.2.0 separates the employee from its reasoning engine for the first time: choose native or DSH without giving up one governance, tool, message, and observation plane.

If you run long tasks, the objective no longer loses its thread when one request ends, a user message arrives mid-run, or the service restarts. It continues with its checklist, attempts, input queue, and recovery state intact.

If you collaborate across systems, A2A lets MateClaw expose governed employee capabilities and bring external agents into a controlled run.

2.1 made collaboration a run; 2.2 makes the runtime replaceable, recoverable, and interoperable.