workplane 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +127 -34
  2. package/package.json +5 -6
package/README.md CHANGED
@@ -1,15 +1,15 @@
1
1
  # workplane
2
2
 
3
- [![website](https://img.shields.io/badge/website-mindstaq.github.io%2Fworkplane-3dd6c6)](https://mindstaq.github.io/workplane/)
3
+ [![website](https://img.shields.io/badge/website-workplane.dev-3dd6c6)](https://mindstaq.github.io/workplane/)
4
4
  [![npm version](https://img.shields.io/npm/v/workplane)](https://www.npmjs.com/package/workplane)
5
- [![status](https://img.shields.io/badge/status-beta-orange)](https://github.com/MindStaq/workplane)
5
+ [![status](https://img.shields.io/badge/status-alpha-orange)](https://github.com/MindStaq/workplane)
6
6
  [![license](https://img.shields.io/npm/l/workplane)](https://github.com/MindStaq/workplane/blob/main/packages/workplane/LICENSE)
7
7
 
8
- > **Beta** — Workplane v0.1.x is under active development. APIs, CLI commands, and deployment expectations may change. Not recommended for production workloads yet.
8
+ > **Alpha software.** APIs and data models are unstable and will change between releases. Not recommended for production use.
9
9
 
10
- Route durable work—shell commands, local inference (Ollama), and batch agent harness jobs (Aider, Codex, Claude Code)—to capable machines on your private network.
10
+ Route durable work to capable nodes on your private network. Compose multi-step AI workplans that mix local Ollama with frontier APIs. Supports shell commands, local inference, and AI coding agents (Codex, Claude Code, Aider) — both **batch** (one-shot) and **interactive** (multi-turn PTY/stdin sessions mediated through the control plane with no direct client-to-node connection).
11
11
 
12
- Workplane is a control plane + polling node runtime backed by Postgres and [DBOS](https://www.dbos.dev/). You submit tasks from a CLI; nodes pull work, run it in isolated workspaces, and report logs and artifacts.
12
+ Workplane is a control plane + polling node runtime backed by Postgres. You submit tasks from a CLI; nodes pull work, run it in isolated workspaces, and stream logs and artifacts back.
13
13
 
14
14
  **Requires Node.js 20+** and **Postgres**.
15
15
 
@@ -54,7 +54,7 @@ workplane-node
54
54
  **4. Submit a task** (fourth terminal):
55
55
 
56
56
  ```bash
57
- export WORKPLANE_OPERATOR_TOKEN=your-operator-secret # if auth enabled on server
57
+ export WORKPLANE_OPERATOR_TOKEN=your-operator-secret
58
58
 
59
59
  workplane task submit shell --command "echo hello"
60
60
  workplane tasks
@@ -64,18 +64,18 @@ workplane logs <runId>
64
64
 
65
65
  ## Authentication
66
66
 
67
- When `WORKPLANE_NODE_TOKEN` is set on the **server**, every node must use the same value. When `WORKPLANE_OPERATOR_TOKEN` is set, the CLI must send it for `task submit`, `retry`, and `cancel`.
68
-
69
67
  | Variable | Used by |
70
68
  |----------|---------|
71
- | `WORKPLANE_NODE_TOKEN` | `workplane-node` |
72
- | `WORKPLANE_OPERATOR_TOKEN` | `workplane` CLI (mutating commands) |
69
+ | `WORKPLANE_NODE_TOKEN` | `workplane-node` (register, poll, report) |
70
+ | `WORKPLANE_OPERATOR_TOKEN` | `workplane` CLI (task submit / retry / cancel / send input) |
73
71
 
74
- Read-only CLI commands (`tasks`, `logs`, `runs`, …) work without the operator token unless you add stricter rules in your deployment.
72
+ Read-only CLI commands (`tasks`, `logs`, `runs`, …) work without the operator token.
75
73
 
76
74
  ## CLI examples
77
75
 
78
76
  ```bash
77
+ export WORKPLANE_OPERATOR_TOKEN=...
78
+
79
79
  # Shell
80
80
  workplane task submit shell --command "npm test" \
81
81
  --repo https://github.com/you/your-repo.git
@@ -83,19 +83,33 @@ workplane task submit shell --command "npm test" \
83
83
  # Local inference (node must advertise ollama capability)
84
84
  workplane task submit inference --model llama3.2 --prompt "Say hello"
85
85
 
86
- # Agent harness (node must have codex or claude-code installed)
87
- workplane task submit harness --harness codex \
88
- --repo git@github.com:you/app.git \
89
- --prompt "Fix failing tests"
90
-
91
- workplane task submit aider \
92
- --repo git@github.com:you/app.git \
93
- --prompt "Fix the bug" \
94
- --test-command "npm test"
95
-
96
- workplane task retry <taskId>
97
- workplane task cancel <taskId>
86
+ # Batch harness (one-shot)
87
+ workplane task submit harness --harness claude-code \
88
+ --repo git@github.com:you/app.git --prompt "Refactor auth middleware" \
89
+ --requires claude-code,git
90
+
91
+ # Interactive harness (multi-turn PTY/stdin session)
92
+ workplane task submit harness --harness claude-code \
93
+ --repo git@github.com:you/app.git --prompt "Start exploring the codebase" \
94
+ --interactive --requires claude-code,git
95
+
96
+ # Send input to a running interactive session
97
+ workplane run input <runId> --stdin "Focus on the auth module"
98
+ workplane run input <runId> --signal SIGINT
99
+ workplane run input <runId> --resize 220x50
100
+
101
+ # Skills (v0.3.0)
102
+ workplane skill list
103
+ workplane skill run code-review --repo . --model claude-haiku-4-5-20251001
104
+
105
+ # Inspect
106
+ workplane tasks [--status running]
107
+ workplane runs --task-id <taskId>
108
+ workplane run show <runId>
109
+ workplane logs <runId>
98
110
  workplane artifacts <runId>
111
+ workplane task cancel <taskId>
112
+ workplane task retry <taskId>
99
113
  ```
100
114
 
101
115
  ## Node capabilities
@@ -109,27 +123,106 @@ workplane-node
109
123
 
110
124
  Tasks declare `requires`; the control plane assigns work to a node whose capabilities are a superset.
111
125
 
112
- | Adapter | Typical capabilities |
113
- |---------|----------------------|
114
- | Shell | `shell` |
115
- | Ollama | `ollama` |
116
- | Aider | `git`, `aider` |
117
- | Codex | `git`, `codex` |
118
- | Claude Code | `git`, `claude-code` |
126
+ | Adapter | Capability tags | Modes |
127
+ |---------|----------------|-------|
128
+ | Shell | `shell` | batch |
129
+ | Ollama | `ollama` | batch |
130
+ | Aider | `aider`, `git` | batch |
131
+ | Codex | `codex`, `git` | batch, interactive (stdio) |
132
+ | Claude Code | `claude-code`, `git` | batch, interactive (PTY) |
119
133
 
120
134
  Override harness binaries: `WORKPLANE_CODEX_BIN`, `WORKPLANE_CLAUDE_CODE_BIN`.
121
135
 
136
+ ## Workplans (v0.3.0)
137
+
138
+ Compose multi-step AI pipelines with the `@workplane/workplans` DSL:
139
+
140
+ ```ts
141
+ import { SequentialWorkplanRunner, LocalWorkplanContext } from "@workplane/workplans";
142
+
143
+ const plan = {
144
+ id: "review", name: "Code Review",
145
+ steps: [
146
+ {
147
+ id: "diff", adapter: "shell", provider: "shell",
148
+ payload: { command: "git diff HEAD~1", cwd: "./my-repo" },
149
+ output: { dest: "next" },
150
+ },
151
+ {
152
+ id: "summarize", adapter: "ollama", provider: "ollama", model: "llama3",
153
+ payload: { prompt: "Summarize these changes:\n{{prevOutput}}" },
154
+ output: { dest: "next" },
155
+ },
156
+ {
157
+ id: "critique", adapter: "anthropic", provider: "anthropic",
158
+ model: "claude-haiku-4-5-20251001",
159
+ payload: { prompt: "Review for correctness and security:\n{{prevOutput}}" },
160
+ },
161
+ ],
162
+ };
163
+
164
+ await new SequentialWorkplanRunner().run(plan, new LocalWorkplanContext());
165
+ ```
166
+
167
+ Inline providers (`anthropic`, `openai`, `ollama`, `shell`, `file`) run without dispatching to a fleet node.
168
+
169
+ ## Agent skills (v0.3.0)
170
+
171
+ Pre-built workplans via `@workplane/agent-skills`:
172
+
173
+ ```ts
174
+ import { createDefaultRegistry } from "@workplane/agent-skills";
175
+ import { SequentialWorkplanRunner, LocalWorkplanContext } from "@workplane/workplans";
176
+
177
+ const skill = createDefaultRegistry().get("code-review");
178
+ const plan = skill.buildPlan({ repo: ".", model: "claude-haiku-4-5-20251001" });
179
+ await new SequentialWorkplanRunner().run(plan, new LocalWorkplanContext());
180
+ ```
181
+
182
+ Or via CLI: `workplane skill run code-review --repo . --model claude-haiku-4-5-20251001`
183
+
184
+ ## Library packages
185
+
186
+ All packages are published under `@workplane/` and can be imported independently:
187
+
188
+ | Package | Purpose |
189
+ |---------|---------|
190
+ | `@workplane/workplans` | Workplan DSL, sequential runner, inline providers |
191
+ | `@workplane/agent-skills` | Pre-built skills, SkillRegistry, CanonicalSkillWorkflow |
192
+ | `@workplane/adapter-sdk` | Build custom adapters — WorkAdapter, WorkContext, cancellable exec |
193
+ | `@workplane/types` | Shared TypeScript types |
194
+ | `@workplane/core` | Config, HTTP client, auth, git utilities |
195
+ | `@workplane/adapter-shell` | Shell command adapter |
196
+ | `@workplane/adapter-ollama` | Ollama inference adapter |
197
+ | `@workplane/adapter-aider` | Aider coding agent adapter |
198
+ | `@workplane/adapter-harness` | Base harness adapter (extended by codex/claude-code) |
199
+ | `@workplane/adapter-claude-code` | Claude Code adapter (PTY interactive) |
200
+ | `@workplane/adapter-codex` | Codex adapter (stdio interactive) |
201
+ | `@workplane/dbos` | Optional DBOS durability layer (step checkpointing + replay) |
202
+
203
+ ## DBOS (optional)
204
+
205
+ DBOS durability is opt-in. The server boots without it by default:
206
+
207
+ ```bash
208
+ # Default — no DBOS
209
+ workplane-server
210
+
211
+ # With DBOS durability
212
+ WORKPLANE_USE_DBOS=true workplane-server
213
+ ```
214
+
122
215
  ## Personal fleet (home + office)
123
216
 
124
- Run the control plane on an always-on host (VPS, NAS, or home server). Run nodes on each machine where tools or GPUs live. Connect machines with Tailscale, WireGuard, or a trusted LAN.
217
+ Run the control plane on an always-on host (VPS, NAS, or home server). Run nodes on each machine where tools or GPUs live. Nodes poll outbound — no inbound ports required. Use Tailscale, WireGuard, or a trusted LAN.
125
218
 
126
- Set `WORKPLANE_SERVER_URL` to the control plane’s reachable URL on every node and CLI client.
219
+ Set `WORKPLANE_SERVER_URL` to the control plane's reachable address on every node and CLI client.
127
220
 
128
- Full deployment guide: [github.com/MindStaq/workplane/blob/main/docs/deployment/FLEET.md](https://github.com/MindStaq/workplane/blob/main/docs/deployment/FLEET.md)
221
+ Full deployment guide: [docs/deployment/FLEET.md](https://github.com/MindStaq/workplane/blob/main/docs/deployment/FLEET.md)
129
222
 
130
223
  ## Documentation
131
224
 
132
- - [v0.1.0 specification](https://github.com/MindStaq/workplane/blob/main/docs/specs/v0.1.0/WORKPLANE_SPEC.md)
225
+ - [v0.3.0 specification](https://github.com/MindStaq/workplane/blob/main/docs/specs/v0.3.0/WORKPLANE_SPEC.md)
133
226
  - [Source repository](https://github.com/MindStaq/workplane)
134
227
  - [Issues](https://github.com/MindStaq/workplane/issues)
135
228
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "workplane",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "Durable execution plane for routing work across trusted nodes",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -33,10 +33,6 @@
33
33
  "README.md",
34
34
  "LICENSE"
35
35
  ],
36
- "scripts": {
37
- "build": "tsup --config tsup.config.ts",
38
- "prepublishOnly": "pnpm run build"
39
- },
40
36
  "devDependencies": {
41
37
  "tsup": "^8.5.0",
42
38
  "typescript": "^5.8.3"
@@ -51,5 +47,8 @@
51
47
  "publishConfig": {
52
48
  "access": "public",
53
49
  "registry": "https://registry.npmjs.org/"
50
+ },
51
+ "scripts": {
52
+ "build": "tsup --config tsup.config.ts"
54
53
  }
55
- }
54
+ }