@dalmasonto/taskflow-mcp 2.5.1 → 2.7.0

package/README.md

@@ -1,42 +1,174 @@
-# @dalmasonto/taskflow-mcp — TaskFlow MCP server + Claude Code hooks
+# @dalmasonto/taskflow-mcp — TaskFlow for AI coding agents
 
-An **agent client** for the TaskFlow backend. It lets a coding agent (e.g. Claude
-Code) connect to your TaskFlow project using a stable, per-repo credential
-(`.taskflow.json`) and drive the whole agent API: identity, tasks, chat, reviews,
-live sessions, streamed terminal output, and real activity logging.
+**TaskFlow** is a multi-agent task board with realtime chat. This package is its
+**MCP server**: it connects a coding agent — **Claude Code, Codex CLI, Gemini CLI,
+Cursor, opencode**, or any other MCP client that can launch a stdio server — to your
+TaskFlow project, so the agent can confirm its identity, work the task board, chat
+with humans and other agents, request and record reviews, stream its terminal, log
+activity, and edit the project's design pages.
 
-> **2.0.0** is a ground-up rewrite. Where the 1.x server kept its own local SQLite
-> and inferred an agent's identity from `cwd + ppid`, this package holds **no state**
-> and **no local DB**: it talks to a TaskFlow backend over HTTP, and its identity is
-> exactly the `key` in `.taskflow.json`, so an agent linked yesterday keeps the same
-> identity today. Multi-agent collaboration — channels, reviews, terminal streaming,
-> `.taskflow.json` profiles — is new in 2.x.
+It holds **no state and no local DB**: it talks to a TaskFlow backend over HTTP,
+and its identity is exactly the `key` in `.taskflow.json`, so an agent linked
+yesterday keeps the same identity today.
+
+> **2.x** is a ground-up rewrite. The 1.x server kept its own local SQLite and
+> inferred an agent's identity from `cwd + ppid`. Multi-agent collaboration —
+> channels, reviews, terminal streaming, `.taskflow.json` profiles — is new in 2.x.
+
+## Quick start
 
 ```bash
 npm install -g @dalmasonto/taskflow-mcp
+taskflow init
+```
+
+Or, on Linux/macOS, the install script does both (checks Node ≥ 20, installs the
+package, then starts `taskflow init`; arguments are passed through to it):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/dalmasonto/task_flow/main/scripts/install.sh | sh
+```
+
+On **Windows** (PowerShell):
+
+```powershell
+npm i -g @dalmasonto/taskflow-mcp; taskflow init
 ```
 
-This puts two commands on your PATH:
+The install puts three commands on your PATH:
 
-- **`taskflow-mcp`** — the MCP server an MCP client (Claude Code, Cursor, …) runs.
-- **`taskflow-hook`** — the Claude Code lifecycle hook (see [Hooks](#hooks)).
+| Command | What it is |
+| --- | --- |
+| `taskflow` | The setup CLI you run: `taskflow init`, `taskflow doctor`, `taskflow mint`. |
+| `taskflow-mcp` | The MCP server your coding agent launches over stdio. You don't run it by hand (except `--doctor`, `--mint`, `--tmux`). |
+| `taskflow-hook` | The Claude Code lifecycle hook (see [Hooks](#hooks-claude-code-only)). |
+
+## `taskflow init`
+
+`taskflow init` (also spelled `taskflow-mcp init`) walks you through the setup:
+
+1. **Pick your coding agent(s)** — Claude Code, Codex CLI, Gemini CLI, Cursor,
+   opencode. Ones found on this machine are pre-selected.
+2. **Pick a scope** — `user` (global: every project on this machine) or `project`
+   (only the current repo, in files you can commit).
+3. **Register the `taskflow` MCP server** with each agent — through the agent's own
+   CLI when it is on your PATH, otherwise by merging its config file.
+4. **Claude Code only:** offer the [hooks](#hooks-claude-code-only).
+5. **Credentials** — find `.taskflow.json`, or create it by linking an agent when
+   you pass `--project` and your user `--token`; otherwise it tells you how.
+6. **Check** the connection (the same check as `taskflow-mcp --doctor`).
+7. **Next steps**, ending with signing up / logging in to the TaskFlow web app —
+   <https://taskflow.supercodehive.com>, or your own frontend if you self-host.
+
+It is safe to re-run: nothing that is already registered is added twice, an
+existing `taskflow` entry is never overwritten (even if you customised it), other
+servers and settings are left untouched, and every file it edits is first backed
+up to `<file>.bak`. A file it cannot parse safely (for example JSON with comments)
+is not touched — you get the exact lines to add by hand instead.
 
-## How it works
+**Non-interactive** (scripts, CI, dotfiles):
 
-- **`.taskflow.json`** (per repo, gitignored) holds the server URL, project id, a
-  `default_profile`, and one or more named `profiles`. Each profile has an
-  `agent_id`, a `key` (the `tfk_…` credential), and a `display_name`.
+```bash
+taskflow init --harness claude --scope user --yes
+taskflow init --harness claude,codex --scope project --dry-run   # show the plan + diffs, change nothing
+taskflow init --harness all --yes --project 3 --token "$TASKFLOW_USER_TOKEN"
+```
+
+| Option | Meaning |
+| --- | --- |
+| `--harness <names>` | `claude`, `codex`, `gemini`, `cursor`, `opencode` — comma-separated, repeatable, or `all`. Required with `--yes`. |
+| `--scope user\|project` | Global, or this repo only (default `user`). |
+| `--dir <path>` | Project root for `--scope project` and `.taskflow.json` (default: cwd). |
+| `--hooks` / `--no-hooks` | Install the Claude Code hooks (default: yes). |
+| `--project <id>` + `--token <t>` | Link a new agent and write `.taskflow.json`. The token is **your user token** (or `TASKFLOW_USER_TOKEN`), not an agent key. |
+| `--server <url>` | API for the new `.taskflow.json` (default `https://api.taskflow.supercodehive.com`). |
+| `--profile <name>`, `--display-name <s>` | Name the linked agent (default profile `main`). |
+| `--app-url <url>` | Your web app, when self-hosting (printed in the next steps). |
+| `--dry-run` | Print what would be run/written, with diffs. Changes nothing. |
+| `--no-doctor` | Skip the connection check. |
+| `-y`, `--yes` | Never prompt; accept defaults. |
+
+### What it does per agent
+
+| Agent | `user` scope | `project` scope | How |
+| --- | --- | --- | --- |
+| Claude Code | Claude's user config | `.mcp.json` | `claude mcp add --scope <scope> taskflow -- taskflow-mcp`. Without the `claude` CLI: project scope writes `.mcp.json`; user scope prints the command (it never edits `~/.claude.json` directly). |
+| Codex CLI | `~/.codex/config.toml` (`$CODEX_HOME`) | same — Codex reads MCP servers from its user config | `codex mcp add taskflow -- taskflow-mcp`, else appends a `[mcp_servers.taskflow]` table. |
+| Gemini CLI | `~/.gemini/settings.json` | `.gemini/settings.json` | Merges `mcpServers.taskflow`. |
+| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` | Merges `mcpServers.taskflow`. |
+| opencode | `~/.config/opencode/opencode.json` | `opencode.json` | Merges `mcp.taskflow` (opencode's own schema). An `opencode.jsonc` is left alone. |
+
+## Manual setup (any MCP client)
+
+If you would rather do it by hand, or use another client: register a stdio server
+named `taskflow` whose command is `taskflow-mcp` (no arguments), then create
+`.taskflow.json` (below). The server must start in your repo (or set
+`TASKFLOW_CONFIG=/abs/path/.taskflow.json` in its environment), because that is
+where it looks for credentials.
+
+**Claude Code**
+
+```bash
+claude mcp add --scope user taskflow -- taskflow-mcp      # or --scope project (writes .mcp.json)
+```
+
+```json
+// .mcp.json (project scope)
+{ "mcpServers": { "taskflow": { "command": "taskflow-mcp", "args": [] } } }
+```
+
+**Codex CLI**
+
+```bash
+codex mcp add taskflow -- taskflow-mcp
+```
+
+```toml
+# ~/.codex/config.toml
+[mcp_servers.taskflow]
+command = "taskflow-mcp"
+args = []
+```
+
+**Gemini CLI** — `~/.gemini/settings.json` or `.gemini/settings.json`; **Cursor** —
+`~/.cursor/mcp.json` or `.cursor/mcp.json`:
+
+```json
+{ "mcpServers": { "taskflow": { "command": "taskflow-mcp", "args": [] } } }
+```
+
+**opencode** — `~/.config/opencode/opencode.json` or `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": { "taskflow": { "type": "local", "command": ["taskflow-mcp"], "enabled": true } }
+}
+```
+
+**Other clients** (Windsurf, Cline, Zed, …): the same stdio server — command
+`taskflow-mcp`, no arguments — in whatever format the client uses.
+
+## Credentials: `.taskflow.json` and profiles
+
+- **`.taskflow.json`** (per repo, **gitignored** — it holds secret keys) has the
+  server URL, project id, a `default_profile`, and one or more named `profiles`.
+  Each profile has an `agent_id`, a `key` (the `tfk_…` credential), and a
+  `display_name`.
 - Every backend call sends `Authorization: Agent <key>`. The chosen profile's key
   is the whole identity — the server derives the agent, project, and display name
   from it.
-- **Profile selection** (highest priority first): a tool's `profile` argument →
-  `TASKFLOW_PROFILE` env → the file's `default_profile` → `"main"`.
-
-## `.taskflow.json` format
+- **Profile selection** for the MCP server (highest priority first): a tool's
+  `profile` argument → `TASKFLOW_PROFILE` env → this terminal's remembered pick
+  (from `select_profile`, kept in `.taskflow/sessions.json`) → the only profile, if
+  there is just one. With several profiles and nothing choosing one, the agent asks
+  you which identity this terminal is (`default_profile` is shown as the
+  recommended pick). The hook and the CLI modes use `TASKFLOW_PROFILE` →
+  `default_profile` → `"main"`.
 
 ```json
 {
-  "server": "http://localhost:8000",
+  "server": "https://api.taskflow.supercodehive.com",
   "project": 1,
   "default_profile": "main",
   "profiles": {
@@ -46,43 +178,42 @@ This puts two commands on your PATH:
 }
 ```
 
-Resolution: the file is read from `TASKFLOW_CONFIG` if set, otherwise found by
-walking up from the working directory. See `.taskflow.json.example`.
-
-## Setup
-
-1. **Install the package** globally so `taskflow-mcp` and `taskflow-hook` are on
-   your PATH:
-   ```bash
-   npm install -g @dalmasonto/taskflow-mcp
-   ```
-2. **Link an agent.** In the TaskFlow dashboard open your project's **API Base**
-   page and link an agent (profile `main`, and optionally `reviewer`). It returns
-   a block containing the `agent_id`, raw `key`, and `display_name` — shown once.
-3. **Create `.taskflow.json`** at your repo root and paste the returned profile
-   block(s) under `profiles` (see the format above and `.taskflow.json.example`).
-   **Do not commit it** — add `.taskflow.json` to your `.gitignore`.
-4. **Register the MCP server** with Claude Code — copy `.mcp.json.example` to
-   `.mcp.json` at your repo root:
-   ```json
-   {
-     "mcpServers": {
-       "taskflow": { "command": "taskflow-mcp", "args": [] }
-     }
-   }
-   ```
-5. **Add the hooks** (optional but recommended) — see [Hooks](#hooks) below.
-
-**From a local checkout** (contributing, or running an unpublished build) instead
-of the global install: `cd mcp && npm install && npm run build`, then point the
-MCP `command` at `node` with `args: ["./mcp/dist/index.js"]`, and the hook at
-`node ABS_PATH/mcp/hooks/taskflow-hook.mjs`.
-
-## Hooks
-
-The Claude Code hook (`taskflow-hook`) turns the agent's own lifecycle into real,
-attributable activity on the TaskFlow board — no prompting required. On each event
-it resolves your `.taskflow.json` + profile and POSTs to the backend:
+`server` is the **backend** origin — the hosted API above, or e.g.
+`http://localhost:8000` for a local backend — never a frontend dev server.
+The file is read from `TASKFLOW_CONFIG` if set, otherwise found by walking up from
+the working directory. See `.taskflow.example.json` in the repo.
+
+**Getting one:**
+
+1. Sign up / log in at <https://taskflow.supercodehive.com> (or your self-hosted
+   frontend) and create or open a project.
+2. Open the project's **API Base** page and link an agent (profile `main`, and
+   optionally `reviewer`). It shows a block with the `agent_id`, raw `key`, and
+   `display_name` — **once**.
+3. Save it as `.taskflow.json` at your repo root and add `.taskflow.json` to
+   `.gitignore`.
+
+Or let `taskflow init --project <id> --token <your user token>` link the agent
+and write the file (and the `.gitignore` entry) for you.
+
+**A second identity** for another terminal (two terminals sharing `main` are ONE
+agent — one roster row, one DM inbox, one read cursor):
+
+```bash
+taskflow mint bear --display-name "Claude (bear)"   # = taskflow-mcp --mint bear ...
+export TASKFLOW_PROFILE=bear                        # then start that terminal's agent
+```
+
+It needs your user token (`--token` or `TASKFLOW_USER_TOKEN`). An existing profile
+is never overwritten and `default_profile` never moves.
+
+## Hooks (Claude Code only)
+
+Hooks are a **Claude Code** feature; other agents get the same tools through MCP,
+just without this automatic lifecycle reporting. The hook (`taskflow-hook`) turns
+the agent's own lifecycle into real, attributable activity on the TaskFlow board —
+no prompting required. On each event it resolves your `.taskflow.json` + profile
+and POSTs to the backend:
 
 - **SessionStart** → registers/reconnects your live session (you show "online").
 - **PreToolUse / PostToolUse** → logs meaningful tool calls as activity. Read-only
@@ -91,13 +222,13 @@ it resolves your `.taskflow.json` + profile and POSTs to the backend:
 - **Stop** → closes the session cleanly.
 - **Notification** → surfaces permission prompts so a human can answer from the UI.
 
-It is **best-effort and never blocks or crashes the agent**: with no `.taskflow.json`,
-or with the backend unreachable, every invocation swallows the error and exits `0`
-in well under its short timeout.
+It is **best-effort and never blocks or crashes the agent**: with no
+`.taskflow.json`, or with the backend unreachable, every invocation swallows the
+error and exits `0` in well under its short timeout.
 
-**Wire it up** — copy the `hooks` block from `.claude/settings.example.json` into
-your project's `.claude/settings.json`. With the global install the command is just
-`taskflow-hook`:
+`taskflow init` adds them for you (to `~/.claude/settings.json` for `user` scope,
+`.claude/settings.json` for `project`), appending after any hooks you already
+have. By hand:
 
 ```json
 {
@@ -115,36 +246,85 @@ The hook reads `TASKFLOW_PROFILE` (else `default_profile`, else `main`) and find
 `.taskflow.json` by walking up from the working directory (or `TASKFLOW_CONFIG`).
 Set `TASKFLOW_HOOK_DEBUG=1` to see why a hook no-oped on stderr.
 
+## Terminal mirroring
+
+When the agent runs inside **tmux**, the server finds its own pane and streams it
+to the dashboard automatically. Set `TASKFLOW_MIRROR=off` to disable it. Without
+tmux the agent still connects and appears online; only the streamed terminal needs
+a pane. `taskflow-mcp --tmux [target]` mirrors a pane the agent is *not* running
+in (see `taskflow-mcp --help`).
+
 ## MCP tools
 
+The tools are called by the **model** through the MCP client, not typed as
+commands. Every tool accepts an optional `profile` argument to act as a different
+profile for that one call (e.g. `reviewer` for `report_review`).
+
 | Tool | What it does |
 | --- | --- |
-| `whoami` | Confirm the agent identity + project behind the credential. |
+| `whoami` | Confirm the agent identity, project, connection and terminal-mirror state. |
+| `select_profile(profile)` | Choose which identity this terminal is, when the repo defines several (after asking the human). |
 | `list_tasks(status?, assigned?)` | List project tasks; `assigned='me'` for claimed. |
 | `create_task(title, description?, priority?, claim?)` | Create (optionally claim) a task. |
+| `update_task(task, …)` | Edit a task's title, description, notes, priority, attachments. |
 | `update_task_status(task, status)` | Advance a task's status. |
 | `claim_task(task)` | Self-assign a task. |
 | `report_review(task, decision, body?)` | Record a review (`approved`/`changes_requested`). |
 | `list_channels` | Channels this agent can see. |
 | `list_agents` | Other agents in the project. |
 | `send_message(channel, body, priority?)` | Post a chat message as this agent. |
-| `check_messages(channel, since?)` | Read a channel's messages + read cursor. |
+| `check_messages(…)` | Read unread messages addressed to this agent. |
 | `mark_read(channel, last_read_message)` | Advance this agent's read cursor. |
-| `register_session(session_identifier?, cwd?)` | Register/reconnect a live session. |
-| `heartbeat(status?)` | Bump session liveness (`idle`/`busy`). |
+| `download_attachment(url)` | Save a message attachment to disk; returns its path. |
+| `register_session(session_identifier?, cwd?)` | Register/reconnect a live session (automatic; rarely needed). |
+| `heartbeat(status?)` | Bump session liveness (automatic; rarely needed). |
 | `capture_terminal(content, stream?)` | Stream terminal output into the session. |
 | `log_activity(action, body?, task?)` | Log a real activity event. |
 | `get_activity(task?, limit?)` | Read recent project activity. |
+| `design_get_tokens`, `design_write_tokens` | Read / replace the design token scale. |
+| `design_list_components`, `design_read_component`, `design_write_component`, `design_delete_component` | The design component registry. |
+| `design_read_page`, `design_write_page`, `design_delete_page` | Design pages (delete moves to the trash). |
+| `design_read_layout`, `design_create_group`, `design_update_group`, `design_reorder_group`, `design_reorder_page`, `design_delete_group`, `design_arrange` | How design pages are grouped and ordered. |
+| `design_write_asset` | Write an image or other non-page asset. |
+| `design_screenshot` | Render a route in headless Chromium and return a PNG. |
+| `design_list_comments`, `design_resolve_comment` | Operator comments on the rendered design. |
+
+## Troubleshooting
+
+```bash
+taskflow-mcp --doctor     # or: taskflow doctor / taskflow-mcp --check
+```
+
+It finds `.taskflow.json`, validates it, authenticates every profile against the
+backend, and prints the fix for each failure (missing file, wrong/revoked key,
+nothing listening at `server`, a frontend URL where the backend belongs). It exits
+non-zero when the default profile cannot authenticate.
+
+- **The agent doesn't see the `taskflow` tools** — restart the agent after
+  `taskflow init`; check the registration with its own tooling (e.g. `claude mcp
+  list`, `codex mcp list`, `/mcp` in Gemini CLI or opencode).
+- **`taskflow-mcp: command not found`** — npm's global bin is not on PATH
+  (`npm prefix -g` shows where it is; add its `bin` to PATH).
+- **Config not found** although the file exists — the agent started the server
+  outside your repo. Set `TASKFLOW_CONFIG` to the file's absolute path in the MCP
+  server's `env`.
+- **`profile_ambiguous`** — the repo has several profiles; answer the agent's
+  question, or set `TASKFLOW_PROFILE`.
+
+## From a local checkout
 
-Every tool also accepts an optional `profile` argument to act as a different
-profile for that one call (e.g. use `reviewer` for `report_review`).
+Contributing, or running an unpublished build, instead of the global install:
+`cd mcp && npm install && npm run build`, then point the MCP `command` at `node`
+with `args: ["./mcp/dist/index.js"]`, the hook at
+`node ABS_PATH/mcp/hooks/taskflow-hook.mjs`, and run the walkthrough with
+`node mcp/dist/cli.js init`.
 
 ## Development
 
 ```bash
 npm run typecheck   # tsc --noEmit
 npm run build       # compile to dist/
-npm test            # vitest (config resolution unit tests)
+npm test            # vitest
 ```
 
 ## Smoke test (against a real backend)

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * The `taskflow` command — the human-facing CLI that ships next to the
+ * `taskflow-mcp` server bin. It never serves MCP; harnesses run `taskflow-mcp`.
+ *
+ *   taskflow init      Post-install walkthrough (also: taskflow-mcp init).
+ *   taskflow doctor    Same as taskflow-mcp --doctor.
+ *   taskflow mint ...  Same as taskflow-mcp --mint ...
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * The `taskflow` command — the human-facing CLI that ships next to the
+ * `taskflow-mcp` server bin. It never serves MCP; harnesses run `taskflow-mcp`.
+ *
+ *   taskflow init      Post-install walkthrough (also: taskflow-mcp init).
+ *   taskflow doctor    Same as taskflow-mcp --doctor.
+ *   taskflow mint ...  Same as taskflow-mcp --mint ...
+ */
+import { createRequire } from "node:module";
+import { runInitCommand } from "./init.js";
+import { runDoctor } from "./doctor.js";
+import { runMint } from "./mint.js";
+const USAGE = `taskflow — set up and check TaskFlow for your coding agents
+
+  taskflow init [options]        Connect Claude Code, Codex, Gemini CLI, Cursor or
+                                 opencode to TaskFlow (see: taskflow init --help).
+  taskflow doctor                Verify .taskflow.json + backend auth.
+  taskflow mint <name> [--display-name <s>] [--token <t>]
+                                 Create another agent identity in .taskflow.json.
+  taskflow --version             Print the package version.
+
+The MCP server itself is the taskflow-mcp command, which your agent runs.`;
+function version() {
+    const require = createRequire(import.meta.url);
+    return require("../package.json").version;
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    switch (cmd) {
+        case "init":
+            return runInitCommand(rest);
+        case "doctor":
+        case "check":
+            return runDoctor();
+        case "mint":
+            for (const line of await runMint(["--mint", ...rest]))
+                process.stdout.write(`${line}\n`);
+            return 0;
+        case "-v":
+        case "--version":
+            process.stdout.write(`${version()}\n`);
+            return 0;
+        case undefined:
+        case "help":
+        case "-h":
+        case "--help":
+            process.stdout.write(`${USAGE}\n`);
+            return 0;
+        default:
+            process.stderr.write(`taskflow: unknown command "${cmd}"\n\n${USAGE}\n`);
+            return 1;
+    }
+}
+main().then((code) => process.exit(code), (err) => {
+    process.stderr.write(`taskflow: ${err.message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,KAAK,GAAG;;;;;;;;;0EAS4D,CAAC;AAE3E,SAAS,OAAO;IACd,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/C,OAAQ,OAAO,CAAC,iBAAiB,CAAyB,CAAC,OAAO,CAAC;AACrE,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7C,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,MAAM;YACT,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;QAC9B,KAAK,QAAQ,CAAC;QACd,KAAK,OAAO;YACV,OAAO,SAAS,EAAE,CAAC;QACrB,KAAK,MAAM;YACT,KAAK,MAAM,IAAI,IAAI,MAAM,OAAO,CAAC,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,CAAC;gBAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;YACzF,OAAO,CAAC,CAAC;QACX,KAAK,IAAI,CAAC;QACV,KAAK,WAAW;YACd,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,EAAE,IAAI,CAAC,CAAC;YACvC,OAAO,CAAC,CAAC;QACX,KAAK,SAAS,CAAC;QACf,KAAK,MAAM,CAAC;QACZ,KAAK,IAAI,CAAC;QACV,KAAK,QAAQ;YACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC;YACnC,OAAO,CAAC,CAAC;QACX;YACE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8BAA8B,GAAG,QAAQ,KAAK,IAAI,CAAC,CAAC;YACzE,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,IAAI,CACT,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAC5B,CAAC,GAAU,EAAE,EAAE;IACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC;IACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CACF,CAAC"}

package/dist/client.d.ts

@@ -32,6 +32,15 @@ export interface TaskflowClientOptions {
     timeoutMs?: number;
 }
 /** An error carrying the backend's status + parsed detail. */
+/** Optional `design_screenshot` controls; see the tool's description. */
+export type DesignScreenshotOptions = {
+    width?: number;
+    height?: number;
+    dpr?: number;
+    mobile?: boolean;
+    full_page?: boolean;
+    frame?: "none" | "classic" | "device";
+};
 export declare class TaskflowApiError extends Error {
     readonly status: number;
     readonly detail: string;
@@ -84,6 +93,8 @@ export interface SendMessageInput {
         filename: string;
         bytes: Buffer;
     }[];
+    /** #317: the id of the message this one replies to (same channel). */
+    reply_to?: number;
 }
 export interface CreateTaskInput {
     title: string;
@@ -156,6 +167,34 @@ export type DesignLayoutOp = {
         group_id?: string;
         position?: number;
     };
+} | {
+    delete_group: {
+        group_id: string;
+    };
+} | {
+    link_pages: {
+        from: string;
+        to: string;
+        label?: string;
+    };
+} | {
+    unlink_pages: {
+        edge_id: string;
+    } | {
+        from: string;
+        to: string;
+    };
+} | {
+    update_link: {
+        edge_id: string;
+        label?: string;
+    };
+} | {
+    place_page: {
+        route: string;
+        x: number;
+        y: number;
+    };
 };
 export declare class TaskflowClient {
     private readonly server;
@@ -253,9 +292,12 @@ export declare class TaskflowClient {
      * — omitted, the server works from whatever it currently holds. */
     writeLayoutOp(input: {
         project: number;
-        op: DesignLayoutOp;
         base_version?: number;
-    }): Promise<unknown>;
+    } & ({
+        op: DesignLayoutOp;
+    } | {
+        ops: DesignLayoutOp[];
+    })): Promise<unknown>;
     /** `GET /agents/design/page?route=` — one page fragment + version. */
     readDesignPage(project: number, route: string): Promise<unknown>;
     /** `GET /agents/design/component?name=` — source + blast radius. */
@@ -269,6 +311,9 @@ export declare class TaskflowClient {
      *  names the routes, so this throws a `component_in_use` detail rather than
      *  deleting and stranding a page. */
     deleteDesignComponent(project: number, name: string, reason: string): Promise<unknown>;
+    /** `DELETE /agents/design/page` — #501: move a page to the trash. The
+     *  operator can restore it; it is not a hard delete. */
+    trashDesignPage(project: number, route: string, reason: string): Promise<unknown>;
     /** `PUT /agents/design/asset` — one image under `assets/`, or the external
      *  resources document `styles/resources.json`. Content is text; raster bytes
      *  are `data:<mime>;base64,<payload>`. */
@@ -279,10 +324,19 @@ export declare class TaskflowClient {
         tokens?: unknown;
         css?: string;
     }): Promise<unknown>;
-    /** `GET /agents/design/screenshot` — render a route; `{png_base64}`. */
-    designScreenshot(project: number, route: string, viewport: string, state?: string): Promise<{
+    /** `GET /agents/design/screenshot` — render a route; `{png_base64, warnings}`. */
+    designScreenshot(project: number, route: string, viewport: string, state?: string, opts?: DesignScreenshotOptions): Promise<{
         route: string;
         viewport: string;
+        size?: {
+            width: number;
+            height: number;
+            dpr: number;
+            mobile: boolean;
+        };
+        frame?: string;
+        full_page?: boolean;
+        warnings?: string[];
         mime: string;
         png_base64: string;
     }>;

package/dist/client.js

@@ -10,7 +10,6 @@
  * `fetchImpl` is injectable so the client can be unit-tested against a stub
  * without a live backend.
  */
-/** An error carrying the backend's status + parsed detail. */
 export class TaskflowApiError extends Error {
     status;
     detail;
@@ -187,6 +186,8 @@ export class TaskflowClient {
             form.set("client_nonce", fields.client_nonce);
         if (fields.is_design)
             form.set("is_design", "true");
+        if (fields.reply_to !== undefined)
+            form.set("reply_to", String(fields.reply_to));
         for (const file of attachments) {
             // The server treats a part as a file only when it carries a non-empty
             // filename (views.rs:180-186), so the basename must be preserved.
@@ -328,7 +329,7 @@ export class TaskflowClient {
                 // Absent, not `null`: the route reads this as `Option<i64>`, and "not
                 // supplied" is a different thing from "supplied as nothing".
                 ...(input.base_version === undefined ? {} : { base_version: input.base_version }),
-                op: input.op,
+                ...("ops" in input ? { ops: input.ops } : { op: input.op }),
             },
         });
     }
@@ -378,6 +379,13 @@ export class TaskflowClient {
             body: { project, name, reason },
         });
     }
+    /** `DELETE /agents/design/page` — #501: move a page to the trash. The
+     *  operator can restore it; it is not a hard delete. */
+    trashDesignPage(project, route, reason) {
+        return this.request("DELETE", `${API_PREFIX}/agents/design/page`, {
+            body: { project, route, reason },
+        });
+    }
     /** `PUT /agents/design/asset` — one image under `assets/`, or the external
      *  resources document `styles/resources.json`. Content is text; raster bytes
      *  are `data:<mime>;base64,<payload>`. */
@@ -403,10 +411,14 @@ export class TaskflowClient {
             },
         });
     }
-    /** `GET /agents/design/screenshot` — render a route; `{png_base64}`. */
-    designScreenshot(project, route, viewport, state) {
+    /** `GET /agents/design/screenshot` — render a route; `{png_base64, warnings}`. */
+    designScreenshot(project, route, viewport, state, opts = {}) {
+        const extra = {};
+        for (const [key, value] of Object.entries(opts))
+            if (value !== undefined)
+                extra[key] = value;
         return this.request("GET", `${API_PREFIX}/agents/design/screenshot`, {
-            query: { project, route, viewport, ...(state ? { state } : {}) },
+            query: { project, route, viewport, ...(state ? { state } : {}), ...extra },
             timeoutMs: 45_000,
         });
     }