@quantod/qq 1.0.0 → 1.0.2

package/dist/resources/guide.md

@@ -50,7 +50,7 @@ push Q/pending "url-3" payload: "url: https://c.com"
 ```
 
 Spawn subagents with instructions like:
-> Claim an item from pipeline `0529_a3f9c2` stage `pending`. Open the URL. Extract name, price, availability. Release to `done` appending the fields. If the page fails, release to `failed` appending `error: <reason>`. Repeat until "No items to claim". Report back.
+> Claim an item from pipeline `0529_a3f9c2` stage `pending`. Open the URL. Extract name, price, availability. Release to `done` appending the fields. If the page fails, release to `failed` appending `error: <reason>`. Repeat until claim returns `error: no items to claim`. Report back.
 
 Monitor with `status` — done when `pending: [0, 0]` and nothing claimed.
 
@@ -58,6 +58,14 @@ Monitor with `status` — done when `pending: [0, 0]` and nothing claimed.
 
 ## MCP Tools — Full Reference
 
+Errors are returned uniformly — tools never throw:
+- **MCP**: YAML text `error: <message>`
+- **SDK**: JSON object `{ "error": "<message>" }`
+
+The message is identical in both cases. Each command lists its specific errors below.
+
+---
+
 ### make_pipeline
 
 Creates a pipeline. Returns its name.
@@ -71,6 +79,9 @@ Returns:
 pipeline: 0529_a3f9c2
 ```
 
+Errors:
+- `error: pipeline <name> already exists` — custom name is already taken
+
 ---
 
 ### push
@@ -92,6 +103,11 @@ id: url-1
 
 **ID strategy**: use the item's natural stable identity from its origin system — URL, database row id, API object id. Omit id only when items have no upstream identity.
 
+Errors:
+- `error: item <id> already in the pipeline` — duplicate id; item already exists
+- `error: payload is not valid YAML: <detail>` — `payloadFormat` is `yaml` (default) and payload fails YAML parse
+- `error: payload is not valid JSON: <detail>` — `payloadFormat` is `json` and payload fails JSON parse
+
 ---
 
 ### claim
@@ -117,10 +133,8 @@ payload: |
   url: https://example.com/product/42
 ```
 
-Returns `error: no items to claim` when nothing is available. **Stop and report back when this happens** — do not retry.
-
-Errors (MCP YAML / SDK JSON):
-- `error: no items to claim` — stage is empty or all items are already claimed. Stop and report back.
+Errors:
+- `error: no items to claim` — stage is empty or all items are already claimed. **Stop and report back — do not retry.**
 - `error: item <id> not found` — only when claiming by specific `id`
 - `error: item <id> already claimed` — only when claiming by specific `id`
 
@@ -146,7 +160,11 @@ Returns:
 ok: true
 ```
 
-Fails if the claim expired (item was unstuck while you worked) or item is not claimed.
+Errors:
+- `error: claim on seq <n> expired` — seq no longer exists; item was unstuck while you held the claim
+- `error: item seq <n> not claimed` — seq exists but the item is not currently claimed
+- `error: payload is not valid YAML: <detail>` — `payloadFormat` is `yaml` (default) and payload fails YAML parse
+- `error: payload is not valid JSON: <detail>` — `payloadFormat` is `json` and payload fails JSON parse
 
 **Payload is append-only history by default.** Each stage appends its output — resulting duplicate YAML fields are intentional. Use `replace: true` only when treating payload as a structured object you own.
 
@@ -171,6 +189,9 @@ stats:
 
 Each value is `[total, claimed]` — total item count and how many are currently claimed (being processed). `*` is the pipeline-level aggregate across all stages. For nested stages (`enriched/shortlisted`), intermediate paths are included as aggregates of their children. `description` is `null` if none was set.
 
+Errors:
+- `error: pipeline <name> not found`
+
 ---
 
 ### batch_read
@@ -262,9 +283,7 @@ QQ.status(pipeline)                                  → Promise<{ description:
 - `release` opts: `target` (string), `payload` (string), `replace` (boolean), `priority` (number), `payloadFormat`
 - `batch_read` opts: `includePayload` (boolean), `claimed` (boolean), `ids` (string, comma-separated), `createdAfter`, `createdBefore`, `modifiedAfter` (epoch ms), `limit`, `offset` (number)
 
-All functions return `{ error: string }` on failure — never throw (except `BridgeError` for network connection failures). Check `result.error` before using the result.
-
-`claim` returns `{ error: "no items to claim" }` when nothing is available.
+All functions return `{ error: string }` on failure — never throw (except `BridgeError` for network connection failures).
 
 Item shape (returned by `claim` and `batch_read`):
 ```
@@ -283,7 +302,7 @@ qq_batch_read(pipeline, stage, **opts)                   → list[dict] | { 'err
 qq_status(pipeline)                                      → { 'description': str|None, 'stats': dict } | { 'error': str }
 ```
 
-All Python functions return `{ 'error': str }` on failure — never raise (except `BridgeError` for connection failures).
+All Python functions return `{ 'error': str }` on failure — never raise (except `BridgeError` for connection failures). Error messages are identical to those in the MCP tool reference above.
 
 ---
 
@@ -320,7 +339,10 @@ item-2: duplicate
 item-3: error: <message>
 ```
 
-File-level parse errors (bad JSON, malformed CSV, etc.) abort the entire operation. Per-record push failures are reported individually without aborting remaining records.
+Per-record push failures are reported inline (`item-1: error: <message>`) without aborting remaining records.
+
+Errors:
+- `error: <message>` — file-level failure (file not found, unsupported extension, malformed file). Entire operation aborted; no records are pushed.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quantod/qq",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Persistent queue for multi-stage Claude agent pipelines",
   "license": "UNLICENSED",
   "engines": {

package/src/mcp.ts

@@ -120,7 +120,7 @@ export async function startMcp(fixedPort?: number): Promise<void> {
     description: 'Get pipeline description and item counts per stage. Read guide before using.',
     inputSchema: { pipeline: z.string() },
   }, ({ pipeline }) => {
-    try { return ok(dump(status(pipeline), { lineWidth: -1 })); }
+    try { return ok(dump(status(pipeline), { lineWidth: -1, flowLevel: 2 })); }
     catch (e) { return err(e); }
   });
 

package/src/resources/guide.md

@@ -50,7 +50,7 @@ push Q/pending "url-3" payload: "url: https://c.com"
 ```
 
 Spawn subagents with instructions like:
-> Claim an item from pipeline `0529_a3f9c2` stage `pending`. Open the URL. Extract name, price, availability. Release to `done` appending the fields. If the page fails, release to `failed` appending `error: <reason>`. Repeat until "No items to claim". Report back.
+> Claim an item from pipeline `0529_a3f9c2` stage `pending`. Open the URL. Extract name, price, availability. Release to `done` appending the fields. If the page fails, release to `failed` appending `error: <reason>`. Repeat until claim returns `error: no items to claim`. Report back.
 
 Monitor with `status` — done when `pending: [0, 0]` and nothing claimed.
 
@@ -58,6 +58,14 @@ Monitor with `status` — done when `pending: [0, 0]` and nothing claimed.
 
 ## MCP Tools — Full Reference
 
+Errors are returned uniformly — tools never throw:
+- **MCP**: YAML text `error: <message>`
+- **SDK**: JSON object `{ "error": "<message>" }`
+
+The message is identical in both cases. Each command lists its specific errors below.
+
+---
+
 ### make_pipeline
 
 Creates a pipeline. Returns its name.
@@ -71,6 +79,9 @@ Returns:
 pipeline: 0529_a3f9c2
 ```
 
+Errors:
+- `error: pipeline <name> already exists` — custom name is already taken
+
 ---
 
 ### push
@@ -92,6 +103,11 @@ id: url-1
 
 **ID strategy**: use the item's natural stable identity from its origin system — URL, database row id, API object id. Omit id only when items have no upstream identity.
 
+Errors:
+- `error: item <id> already in the pipeline` — duplicate id; item already exists
+- `error: payload is not valid YAML: <detail>` — `payloadFormat` is `yaml` (default) and payload fails YAML parse
+- `error: payload is not valid JSON: <detail>` — `payloadFormat` is `json` and payload fails JSON parse
+
 ---
 
 ### claim
@@ -117,10 +133,8 @@ payload: |
   url: https://example.com/product/42
 ```
 
-Returns `error: no items to claim` when nothing is available. **Stop and report back when this happens** — do not retry.
-
-Errors (MCP YAML / SDK JSON):
-- `error: no items to claim` — stage is empty or all items are already claimed. Stop and report back.
+Errors:
+- `error: no items to claim` — stage is empty or all items are already claimed. **Stop and report back — do not retry.**
 - `error: item <id> not found` — only when claiming by specific `id`
 - `error: item <id> already claimed` — only when claiming by specific `id`
 
@@ -146,7 +160,11 @@ Returns:
 ok: true
 ```
 
-Fails if the claim expired (item was unstuck while you worked) or item is not claimed.
+Errors:
+- `error: claim on seq <n> expired` — seq no longer exists; discard your work
+- `error: item seq <n> not claimed` — items should be claimed before releasing - likely bug
+- `error: payload is not valid YAML: <detail>` — `payloadFormat` is `yaml` (default) and payload fails YAML parse
+- `error: payload is not valid JSON: <detail>` — `payloadFormat` is `json` and payload fails JSON parse
 
 **Payload is append-only history by default.** Each stage appends its output — resulting duplicate YAML fields are intentional. Use `replace: true` only when treating payload as a structured object you own.
 
@@ -171,6 +189,9 @@ stats:
 
 Each value is `[total, claimed]` — total item count and how many are currently claimed (being processed). `*` is the pipeline-level aggregate across all stages. For nested stages (`enriched/shortlisted`), intermediate paths are included as aggregates of their children. `description` is `null` if none was set.
 
+Errors:
+- `error: pipeline <name> not found`
+
 ---
 
 ### batch_read
@@ -262,9 +283,7 @@ QQ.status(pipeline)                                  → Promise<{ description:
 - `release` opts: `target` (string), `payload` (string), `replace` (boolean), `priority` (number), `payloadFormat`
 - `batch_read` opts: `includePayload` (boolean), `claimed` (boolean), `ids` (string, comma-separated), `createdAfter`, `createdBefore`, `modifiedAfter` (epoch ms), `limit`, `offset` (number)
 
-All functions return `{ error: string }` on failure — never throw (except `BridgeError` for network connection failures). Check `result.error` before using the result.
-
-`claim` returns `{ error: "no items to claim" }` when nothing is available.
+All functions return `{ error: string }` on failure — never throw (except `BridgeError` for network connection failures).
 
 Item shape (returned by `claim` and `batch_read`):
 ```
@@ -283,7 +302,7 @@ qq_batch_read(pipeline, stage, **opts)                   → list[dict] | { 'err
 qq_status(pipeline)                                      → { 'description': str|None, 'stats': dict } | { 'error': str }
 ```
 
-All Python functions return `{ 'error': str }` on failure — never raise (except `BridgeError` for connection failures).
+All Python functions return `{ 'error': str }` on failure — never raise (except `BridgeError` for connection failures). Error messages are identical to those in the MCP tool reference above.
 
 ---
 
@@ -320,7 +339,10 @@ item-2: duplicate
 item-3: error: <message>
 ```
 
-File-level parse errors (bad JSON, malformed CSV, etc.) abort the entire operation. Per-record push failures are reported individually without aborting remaining records.
+Per-record push failures are reported inline (`item-1: error: <message>`) without aborting remaining records.
+
+Errors:
+- `error: <message>` — file-level failure (file not found, unsupported extension, malformed file). Entire operation aborted; no records are pushed.
 
 ---