@oh-my-matrix/autopilot 2.1.1 → 3.0.0

package/README.md

@@ -14,23 +14,118 @@ npm install @oh-my-matrix/autopilot
 npm install openclaw@">=2026.5.28" @oh-my-matrix/permission-policy
 ```
 
-## Use
-
-Registers as an OpenClaw plugin (`openclaw.plugin.json`) with hooks including
-`before_tool_call`, `after_tool_call`, `before_compaction`, `agent_turn_prepare`,
-`before_agent_run`, and `llm_output`. Enable it in your OpenClaw runtime and configure
-behaviour via `WORKFLOW.md` (destructive-git policy, retry, evidence gates).
-
 ## What it does
 
-- **Continuation engine** — resumes long tasks across turns with a retry queue.
+- **Continuation engine** — resumes long tasks across turns with exponential-backoff retry.
 - **Stall / completion detection** — surfaces when a run is stuck or genuinely done.
-- **Evidence gate** — blocks completion until success criteria are verified.
+- **Evidence gate** — blocks completion until validation commands pass (opt-in via `trustWorkspace`).
+- **Orchestrator reducer** — pure-function state machine (7 states, immutable transitions).
 - **Projection + goal manager** — preserves run state and goal across compaction.
+- **Model routing** — cost-aware tier selection per execution phase (budget/standard/premium).
 - **Permission-policy integration** — coordinates the run-scoped policy with
   [`@oh-my-matrix/permission-policy`](../permission-policy).
 
+## Plugin config
+
+Set via `openclaw.plugin.json` or host `pluginConfig`:
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `maxAttemptsPerTurn` | number | `5` | Max revise attempts within a single turn |
+| `maxTotalContinuations` | number | `50` | Max total continuations across all turns |
+| `toolErrorThreshold` | number | `3` | Consecutive identical tool errors before pause |
+| `excludedAgents` | string[] | `[]` | Agent IDs to skip (no autopilot hooks) |
+| `highRiskTools` | string[] | — | Additional tools to block for subagents |
+| `tokenBudget` | number | — | Total token budget; pauses when exceeded |
+| `maxConcurrentAutopilot` | number | `5` | Max simultaneous autopilot runs |
+| `thinkingIntensity` | `'low'\|'medium'\|'high'` | `'high'` | Graduated thinking effort injection |
+| `trustWorkspace` | boolean | `false` | Enable workspace-sourced validation commands |
+| `modelRouting` | object | — | Tier→model mapping (see Model routing below) |
+
+## Gateway methods
+
+| Method | Params | Description |
+|--------|--------|-------------|
+| `autopilot.activate` | `{ sessionKey, goal?, maxTotalContinuations?, tokenBudget?, trustWorkspace? }` | Start or re-activate a run. Returns `{ ok, runId, projection }` |
+| `autopilot.stop` | `{ sessionKey }` | Stop a running session (sets `blockedReason: 'user_stopped'`) |
+| `autopilot.resume` | `{ sessionKey }` | Resume from `paused` status (resumable blocked reasons only) |
+| `autopilot.status` | `{ sessionKey }` | Query current projection for a session |
+| `autopilot.setGoal` | `{ sessionKey, goal }` | Update the run goal mid-flight |
+| `autopilot.cleanup` | — | Clear all internal state (all runs, maps, intervals) |
+
+## WORKFLOW.md format
+
+Place a `WORKFLOW.md` with YAML front matter in the workspace root to configure per-workspace behavior:
+
+```yaml
+---
+autopilot:
+  version: 1
+  permission_mode: guarded_yolo
+  max_concurrent: 3
+  max_retries: 5
+  stall_timeout_ms: 60000
+  max_retry_backoff_ms: 120000
+  workspace:
+    root: .matrix/worktrees
+    cleanup: delete_on_done
+    branch_prefix: auto
+  validation:
+    commands:
+      - id: test
+        command: pnpm test
+        timeout_ms: 30000
+        required: true
+  destructive_git:
+    allow: false
+  model_routing:
+    default_tier: standard
+    initial_turn_tier: premium
+    validation_tier: budget
+    model_ids:
+      budget: claude-haiku-4-5-20251001
+      standard: claude-sonnet-4-6
+      premium: claude-opus-4-6
+---
+```
+
+Validation command binaries are allowlisted (npm, pnpm, node, vitest, tsc, go, cargo, python, etc.); disallowed binaries (curl, wget, bash, sh) are dropped with a warning.
+
+## AutopilotProjection fields
+
+The `autopilot.status` gateway returns a projection object:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | `'idle'\|'running'\|'paused'\|'done'` | Current run status |
+| `orchestrationState` | `'unclaimed'\|'claimed'\|'running'\|'retry_queued'\|'released'\|'blocked'\|'done'` | Orchestrator state |
+| `enabled` | boolean | Whether autopilot is active |
+| `turnAttempts` / `totalContinuations` | number | Current turn / total counters |
+| `pauseReason` | string? | Why the run paused |
+| `blockedReason` | string? | Why the run is blocked |
+| `canStop` | boolean | Whether stop is meaningful |
+| `lastGoal` | string? | Truncated goal text |
+| `totalTokensUsed` / `inputTokensUsed` / `outputTokensUsed` | number | Token accounting |
+| `estimatedCostUsd` | number | Estimated API cost (Claude Sonnet pricing) |
+| `evidenceStatus` | string? | Evidence gate status |
+| `workspacePath` / `workspaceBranch` | string? | Workspace info |
+| `thinkingIntensity` / `modelTier` / `recommendedModelId` | string? | Current routing |
+
+## Environment variables
+
+No environment variables are required. The plugin reads all configuration from `pluginConfig` and `WORKFLOW.md`.
+
+## Troubleshooting
+
+**Run stuck at `claimed`?** — The host must emit `agent_turn_prepare` before `before_agent_finalize` for the orchestrator to advance through `running` → `released` → `done`.
+
+**Evidence gate always skipped?** — Set `trustWorkspace: true` in the activate payload or plugin config. Without it, workspace-sourced validation commands are not executed (security: untrusted workspaces cannot reach RCE).
+
+**"audit plugin not loaded" warning?** — Normal if `@openclaw/matrixassistant-audit` is not installed. Autopilot works without it (degraded but safe).
+
+**Token budget not enforcing?** — Budget enforcement happens at the `before_agent_finalize` turn boundary (`continuation-engine.ts`). Subagent tokens are counted toward the parent run's budget.
+
 ## Status
 
-v2.1.1. Tested with `vitest` (500+ tests). See the project
+v3.0.0. Tested with `vitest` (677 tests, 91%+ statement coverage). See the project
 [changelog](https://github.com/TeFuirnever/oh-my-matrix/blob/master/CHANGELOG.md).

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import type { AutopilotState } from './src/types';
 import type { OpenClawPluginApi } from 'openclaw/dist/plugin-sdk/plugin-runtime';
+export type { AutopilotProjection } from './src/projection';
 export declare const id = "autopilot";
 export declare const name = "Autopilot Continuous Mode";
-export declare const version = "2.0.0";
+export declare const version = "3.0.0";
 export declare function _resetForTest(): void;
 /** Test-only: inject a mock audit_setMode so the closed-over _auditSetMode reference is replaceable. */
 export declare function _setAuditSetModeForTest(fn: ((mode: 'active' | 'monitor' | 'passive') => void) | null): void;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,cAAc,EAA+B,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAE,iBAAiB,EAAmB,MAAM,yCAAyC,CAAC;AA+BlG,eAAO,MAAM,EAAE,cAAc,CAAC;AAC9B,eAAO,MAAM,IAAI,8BAA8B,CAAC;AAChD,eAAO,MAAM,OAAO,UAAU,CAAC;AAgD/B,wBAAgB,aAAa,IAAI,IAAI,CASpC;AAED,wGAAwG;AACxG,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAK3G;AAED,wBAAgB,wBAAwB;;;;;EAOvC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,cAAc,CAAC,oBAAoB,CAAC,CAAC;IACzD,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;CACjC,GAAG,cAAc,GAAG,SAAS,CAiD7B;AAyDD,+EAA+E;AAC/E,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAMD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAwyBrD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,cAAc,EAA+B,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAE,iBAAiB,EAAuZ,MAAM,yCAAyC,CAAC;AActe,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAsB5D,eAAO,MAAM,EAAE,cAAc,CAAC;AAC9B,eAAO,MAAM,IAAI,8BAA8B,CAAC;AAGhD,eAAO,MAAM,OAAO,UAAU,CAAC;AA4G/B,wBAAgB,aAAa,IAAI,IAAI,CAWpC;AAED,wGAAwG;AACxG,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAK3G;AAED,wBAAgB,wBAAwB;;;;;EAOvC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,cAAc,CAAC,oBAAoB,CAAC,CAAC;IACzD,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;CACjC,GAAG,cAAc,GAAG,SAAS,CAmD7B;AA6FD,+EAA+E;AAC/E,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAMD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAo7BrD"}