@quantod/qq 0.3.6 → 1.0.0

package/dist/sdk-templates/javascript.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderJavaScriptSdk = renderJavaScriptSdk;
+function renderJavaScriptSdk(host, port, token) {
+    return `class BridgeError extends Error { constructor(m) { super(m); this.name = 'BridgeError'; } }
+const QQ = (() => {
+  const _u = 'http://${host}:${port}';
+  const _h = { 'Authorization': 'Bearer ${token}', 'Content-Type': 'application/json' };
+  async function _req(method, path, body) {
+    let r;
+    try { r = await fetch(_u + path, { method, headers: _h, body: body != null ? JSON.stringify(body) : undefined }); }
+    catch { throw new BridgeError('Connection failed — call get_sdk again to refresh credentials'); }
+    return r.status === 204 ? undefined : r.json();
+  }
+  return {
+    push:        (pipeline, stage, id, payload, opts = {}) => _req('POST', \`/pipelines/\${pipeline}/push\`, { stage, id, payload, ...opts }),
+    claim:       (pipeline, stage, opts = {})               => _req('POST', \`/pipelines/\${pipeline}/claim\`, { stage, ...opts }),
+    release:     (pipeline, seq, opts = {})                 => _req('POST', \`/pipelines/\${pipeline}/release/\${seq}\`, opts),
+    batch_read:  (pipeline, stage, opts = {})               => _req('GET',  \`/pipelines/\${pipeline}/items?\${new URLSearchParams({ stage, ...opts })}\`),
+    status:      (pipeline)                                 => _req('GET',  \`/pipelines/\${pipeline}/status\`),
+  };
+})();`;
+}
+//# sourceMappingURL=javascript.js.map

package/dist/sdk-templates/javascript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"javascript.js","sourceRoot":"","sources":["../../src/sdk-templates/javascript.ts"],"names":[],"mappings":";;AAAA,kDAmBC;AAnBD,SAAgB,mBAAmB,CAAC,IAAY,EAAE,IAAY,EAAE,KAAa;IAC3E,OAAO;;uBAEc,IAAI,IAAI,IAAI;0CACO,KAAK;;;;;;;;;;;;;;MAczC,CAAC;AACP,CAAC"}

package/dist/sdk-templates/python.d.ts

@@ -0,0 +1,2 @@
+export declare function renderPythonSdk(host: string, port: number, token: string): string;
+//# sourceMappingURL=python.d.ts.map

package/dist/sdk-templates/python.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python.d.ts","sourceRoot":"","sources":["../../src/sdk-templates/python.ts"],"names":[],"mappings":"AAAA,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CA0BjF"}

package/dist/sdk-templates/python.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderPythonSdk = renderPythonSdk;
+function renderPythonSdk(host, port, token) {
+    return `import urllib.request, json as _json, urllib.parse
+class BridgeError(Exception): pass
+_BRIDGE_URL = 'http://${host}:${port}'
+_BRIDGE_HEADERS = {'Authorization': 'Bearer ${token}', 'Content-Type': 'application/json'}
+def _bridge_req(method, path, body=None):
+    data = _json.dumps(body).encode() if body is not None else None
+    req = urllib.request.Request(_BRIDGE_URL + path, data=data, headers=_BRIDGE_HEADERS, method=method)
+    try:
+        with urllib.request.urlopen(req) as r:
+            return _json.loads(r.read()) if r.status != 204 else None
+    except urllib.error.HTTPError as e:
+        return _json.loads(e.read())
+    except Exception as e:
+        raise BridgeError('Connection failed — call get_sdk again to refresh credentials') from e
+def qq_push(pipeline, stage, id=None, payload=None, **opts):
+    return _bridge_req('POST', f'/pipelines/{pipeline}/push', {'stage': stage, 'id': id, 'payload': payload, **opts})
+def qq_claim(pipeline, stage, **opts):
+    return _bridge_req('POST', f'/pipelines/{pipeline}/claim', {'stage': stage, **opts})
+def qq_release(pipeline, seq, **opts):
+    return _bridge_req('POST', f'/pipelines/{pipeline}/release/{seq}', opts)
+def qq_batch_read(pipeline, stage, **opts):
+    qs = urllib.parse.urlencode({'stage': stage, **opts})
+    return _bridge_req('GET', f'/pipelines/{pipeline}/items?{qs}')
+def qq_status(pipeline):
+    return _bridge_req('GET', f'/pipelines/{pipeline}/status')`;
+}
+//# sourceMappingURL=python.js.map

package/dist/sdk-templates/python.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python.js","sourceRoot":"","sources":["../../src/sdk-templates/python.ts"],"names":[],"mappings":";;AAAA,0CA0BC;AA1BD,SAAgB,eAAe,CAAC,IAAY,EAAE,IAAY,EAAE,KAAa;IACvE,OAAO;;wBAEe,IAAI,IAAI,IAAI;8CACU,KAAK;;;;;;;;;;;;;;;;;;;;;+DAqBY,CAAC;AAChE,CAAC"}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@quantod/qq",
-  "version": "0.3.6",
+  "version": "1.0.0",
   "description": "Persistent queue for multi-stage Claude agent pipelines",
   "license": "UNLICENSED",
   "engines": {
-    "node": ">=22 <23"
+    "node": ">=22"
   },
   "main": "./dist/commands.js",
   "exports": {
@@ -19,19 +19,26 @@
     "src"
   ],
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
     "better-sqlite3": "^12.0.0",
+    "csv-parse": "^5.5.0",
     "commander": "^13.1.0",
-    "js-yaml": "^4.1.0"
+    "cors": "^2.8.5",
+    "express": "^4.21.0",
+    "js-yaml": "^4.1.0",
+    "zod": "^3.25.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.0"
   },
   "scripts": {
-    "build": "tsc --project tsconfig.build.json",
+    "build": "tsc --project tsconfig.build.json && mkdir -p dist/resources && cp src/resources/*.md dist/resources/",
     "test": "vitest run",
     "lint": "tsc --noEmit"
   }

package/src/commands.ts

@@ -1,16 +1,27 @@
 import { randomBytes } from 'node:crypto';
+import { readFileSync, unlinkSync } from 'node:fs';
+import { extname } from 'node:path';
 import type Database from 'better-sqlite3';
-import { load } from 'js-yaml';
+import { load, dump } from 'js-yaml';
+import { parse as parseCsv } from 'csv-parse/sync';
 import { openDb, inTransaction } from './db.js';
 
 export * as yaml from 'js-yaml';
 
-function validateYaml(payload: string | undefined, plainText: boolean): void {
-  if (!payload || plainText) return;
-  try {
-    load(payload);
-  } catch (e) {
-    throw new QQError(`payload is not valid YAML: ${e instanceof Error ? e.message : String(e)}`);
+export type PayloadFormat = 'yaml' | 'json' | 'text';
+
+function processPayload(payload: string | undefined, format: PayloadFormat = 'yaml'): string | undefined {
+  if (!payload) return payload;
+  switch (format) {
+    case 'yaml':
+      try { load(payload); }
+      catch (e) { throw new QQError(`payload is not valid YAML: ${e instanceof Error ? e.message : String(e)}`); }
+      return payload;
+    case 'json':
+      try { return JSON.stringify(JSON.parse(payload)); }
+      catch (e) { throw new QQError(`payload is not valid JSON: ${e instanceof Error ? e.message : String(e)}`); }
+    case 'text':
+      return payload;
   }
 }
 
@@ -73,7 +84,7 @@ function rowToItem(row: Record<string, unknown>, includePayload: boolean): Item
 
 // ── makePipeline ──────────────────────────────────────────────────────────────
 
-export function makePipeline(customName?: string): string {
+export function makePipeline(customName?: string, description?: string): string {
   if (!customName) {
     const now = new Date();
     const mm = String(now.getMonth() + 1).padStart(2, '0');
@@ -86,7 +97,7 @@ export function makePipeline(customName?: string): string {
     inTransaction(db, () => {
       const existing = db.prepare('SELECT id FROM pipelines WHERE id = ?').get(name);
       if (existing) throw new QQError(`pipeline ${name} already exists`);
-      db.prepare('INSERT INTO pipelines (id, created) VALUES (?, ?)').run(name, Date.now());
+      db.prepare('INSERT INTO pipelines (id, created, description) VALUES (?, ?, ?)').run(name, Date.now(), description ?? null);
     });
   } finally {
     db.close();
@@ -95,6 +106,18 @@ export function makePipeline(customName?: string): string {
 }
 
 
+// ── listPipelines ─────────────────────────────────────────────────────────────
+
+export function listPipelines(): string[] {
+  const db = openDb();
+  try {
+    const rows = db.prepare('SELECT id FROM pipelines ORDER BY id ASC').all() as { id: string }[];
+    return rows.map(r => r.id);
+  } finally {
+    db.close();
+  }
+}
+
 // ── deletePipeline ────────────────────────────────────────────────────────────
 
 export function deletePipeline(pipeline: string): void {
@@ -111,11 +134,11 @@ export function deletePipeline(pipeline: string): void {
 export interface PushOptions {
   payload?: string;
   priority?: number;
-  plainText?: boolean;
+  payloadFormat?: PayloadFormat;
 }
 
-export function push(pipeline: string, stage: string, id?: string, { payload, priority = 0.0, plainText = false }: PushOptions = {}): string {
-  validateYaml(payload, plainText);
+export function push(pipeline: string, stage = '', id?: string, { payload, priority = 0.0, payloadFormat = 'yaml' }: PushOptions = {}): string {
+  const processedPayload = processPayload(payload, payloadFormat);
   const db = openDb();
   try {
     return inTransaction(db, () => {
@@ -126,7 +149,7 @@ export function push(pipeline: string, stage: string, id?: string, { payload, pr
       const now = Date.now();
       db.prepare(
         'INSERT INTO messages (pipeline, id, subqueue, claimed, seq, payload, priority, created, last_modified) VALUES (?, ?, ?, 0, ?, ?, ?, ?, ?)'
-      ).run(pipeline, actualId, stage, seq, payload ?? null, priority, now, now);
+      ).run(pipeline, actualId, stage, seq, processedPayload ?? null, priority, now, now);
       return actualId;
     });
   } finally {
@@ -134,13 +157,97 @@ export function push(pipeline: string, stage: string, id?: string, { payload, pr
   }
 }
 
+// ── loadFile ──────────────────────────────────────────────────────────────────
+
+export interface LoadFileOptions {
+  stage?: string;
+  deleteAfter?: boolean;
+}
+
+export interface LoadFileResult {
+  id: string;
+  status: 'ok' | 'duplicate' | 'error';
+  message?: string;
+}
+
+function expandEnvVars(p: string): string {
+  return p.replace(/\$([A-Z_][A-Z0-9_]*)/gi, (_, name) => process.env[name] ?? '');
+}
+
+function parseFileRecords(filePath: string, content: string): Record<string, unknown>[] {
+  const ext = extname(filePath).toLowerCase();
+  switch (ext) {
+    case '.jsonl':
+    case '.ndjson':
+      return content.split('\n')
+        .map(l => l.trim()).filter(Boolean)
+        .map((l, i) => {
+          try { return JSON.parse(l) as Record<string, unknown>; }
+          catch (e) { throw new Error(`JSONL line ${i + 1}: ${e instanceof Error ? e.message : String(e)}`); }
+        });
+    case '.json': {
+      const parsed = JSON.parse(content) as unknown;
+      if (!Array.isArray(parsed)) throw new Error('JSON file must contain an array');
+      return parsed as Record<string, unknown>[];
+    }
+    case '.yaml':
+    case '.yml': {
+      const doc = load(content);
+      if (!Array.isArray(doc)) throw new Error('YAML file must contain a sequence');
+      return doc as Record<string, unknown>[];
+    }
+    case '.csv':
+      return parseCsv(content, { columns: true, skip_empty_lines: true }) as Record<string, unknown>[];
+    default:
+      throw new Error(`unsupported file extension: ${ext} — use .jsonl, .json, .yaml, .yml, or .csv`);
+  }
+}
+
+export function loadFile(
+  rawPath: string,
+  pipeline: string,
+  { stage: defaultStage = '', deleteAfter = false }: LoadFileOptions = {}
+): LoadFileResult[] {
+  const filePath = expandEnvVars(rawPath);
+  const content = readFileSync(filePath, 'utf8');
+  const records = parseFileRecords(filePath, content);
+
+  const results: LoadFileResult[] = [];
+
+  for (const rec of records) {
+    const recStage = typeof rec.stage === 'string' ? rec.stage : defaultStage;
+    const recId = rec.id !== undefined ? String(rec.id) : undefined;
+    const recPriority = rec.priority !== undefined ? Number(rec.priority) : undefined;
+    const recPayload = rec.payload !== undefined
+      ? (typeof rec.payload === 'string' ? rec.payload : dump(rec.payload))
+      : undefined;
+
+    try {
+      const id = push(pipeline, recStage, recId, { payload: recPayload, priority: recPriority, payloadFormat: 'text' });
+      results.push({ id, status: 'ok' });
+    } catch (e) {
+      if (e instanceof QQError && e.message.includes('already in the pipeline')) {
+        results.push({ id: recId ?? '(autogen)', status: 'duplicate' });
+      } else {
+        results.push({ id: recId ?? '(autogen)', status: 'error', message: e instanceof Error ? e.message : String(e) });
+      }
+    }
+  }
+
+  if (deleteAfter) {
+    try { unlinkSync(filePath); } catch { /* best-effort */ }
+  }
+
+  return results;
+}
+
 // ── claim ─────────────────────────────────────────────────────────────────────
 
 export interface ClaimOptions {
   random?: boolean;
 }
 
-export function claim(pipeline: string, stage: string, id?: string, { random = false }: ClaimOptions = {}): Item | null {
+export function claim(pipeline: string, stage: string, id?: string, { random = false }: ClaimOptions = {}): Item {
   const db = openDb();
   try {
     return inTransaction(db, () => {
@@ -157,7 +264,7 @@ export function claim(pipeline: string, stage: string, id?: string, { random = f
         row = db.prepare(
           `SELECT * FROM messages WHERE pipeline = ? AND subqueue LIKE ? AND claimed = 0 ORDER BY ${orderBy} LIMIT 1`
         ).get(pipeline, toGlob(stage)) as Record<string, unknown> | undefined;
-        if (!row) return null;
+        if (!row) throw new QQError('no items to claim');
       }
 
       const now = Date.now();
@@ -179,11 +286,11 @@ export interface ReleaseOptions {
   payload?: string;
   replace?: boolean;
   priority?: number;
-  plainText?: boolean;
+  payloadFormat?: PayloadFormat;
 }
 
-export function release(pipeline: string, seq: number, { target, payload, replace, priority, plainText = false }: ReleaseOptions = {}): void {
-  validateYaml(payload, plainText);
+export function release(pipeline: string, seq: number, { target, payload, replace, priority, payloadFormat = 'yaml' }: ReleaseOptions = {}): void {
+  const processedPayload = processPayload(payload, payloadFormat);
   const db = openDb();
   try {
     inTransaction(db, () => {
@@ -197,10 +304,10 @@ export function release(pipeline: string, seq: number, { target, payload, replac
       const newPriority = priority ?? (row.priority as number) ?? 0.0;
 
       let newPayload: string | null;
-      if (payload !== undefined) {
+      if (processedPayload !== undefined) {
         newPayload = replace
-          ? payload
-          : [row.payload as string | null, payload].filter(Boolean).join('\n');
+          ? processedPayload
+          : [(row.payload as string | null)?.trimEnd() ?? null, processedPayload].filter(Boolean).join('\n');
       } else {
         newPayload = (row.payload as string | null) ?? null;
       }
@@ -271,14 +378,22 @@ export function batchRead(pipeline: string, stage = '*', filters: FilterOptions
   }
 }
 
-// ── stats ─────────────────────────────────────────────────────────────────────
+// ── status ────────────────────────────────────────────────────────────────────
 
-export function stats(pipeline = '*'): Record<string, [number, number]> {
+export interface PipelineStatus {
+  description: string | null;
+  stats: Record<string, [number, number]>;
+}
+
+export function status(pipeline: string): PipelineStatus {
   const db = openDb();
   try {
+    const pRow = db.prepare('SELECT description FROM pipelines WHERE id = ?').get(pipeline) as { description: string | null } | undefined;
+    if (!pRow) throw new QQError(`pipeline ${pipeline} not found`);
+
     const rows = db.prepare(
-      'SELECT pipeline, subqueue, claimed, COUNT(*) as count FROM messages WHERE pipeline LIKE ? GROUP BY pipeline, subqueue, claimed'
-    ).all(toGlob(pipeline)) as { pipeline: string; subqueue: string; claimed: number; count: number }[];
+      'SELECT subqueue, claimed, COUNT(*) as count FROM messages WHERE pipeline = ? GROUP BY subqueue, claimed'
+    ).all(pipeline) as { subqueue: string; claimed: number; count: number }[];
 
     const agg = new Map<string, { total: number; claimed: number }>();
     const ensure = (key: string) => {
@@ -286,25 +401,29 @@ export function stats(pipeline = '*'): Record<string, [number, number]> {
       return agg.get(key)!;
     };
 
+    let pipelineTotal = 0;
+    let pipelineClaimed = 0;
+
     for (const row of rows) {
-      const pEntry = ensure(row.pipeline);
-      pEntry.total += row.count;
-      if (row.claimed) pEntry.claimed += row.count;
+      pipelineTotal += row.count;
+      if (row.claimed) pipelineClaimed += row.count;
 
+      if (row.subqueue === '') continue;
       const parts = row.subqueue.split('/');
       for (let i = 0; i < parts.length; i++) {
-        const key = row.pipeline + '/' + parts.slice(0, i + 1).join('/');
+        const key = parts.slice(0, i + 1).join('/');
         const entry = ensure(key);
         entry.total += row.count;
         if (row.claimed) entry.claimed += row.count;
       }
     }
 
-    const result: Record<string, [number, number]> = {};
+    const stats: Record<string, [number, number]> = { '*': [pipelineTotal, pipelineClaimed] };
     for (const [key, { total, claimed }] of [...agg.entries()].sort(([a], [b]) => a.localeCompare(b))) {
-      result[key] = [total, claimed];
+      stats[key] = [total, claimed];
     }
-    return result;
+
+    return { description: pRow.description, stats };
   } finally {
     db.close();
   }

package/src/db.ts

@@ -1,12 +1,14 @@
 import Database from 'better-sqlite3';
-import { mkdirSync, readFileSync } from 'node:fs';
+import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 
 const DDL = `
 CREATE TABLE IF NOT EXISTS pipelines (
-  id      TEXT PRIMARY KEY,
-  created INTEGER NOT NULL
+  id          TEXT PRIMARY KEY,
+  created     INTEGER NOT NULL,
+  description TEXT
 );
+
 CREATE TABLE IF NOT EXISTS messages (
   id            TEXT NOT NULL,
   pipeline      TEXT NOT NULL REFERENCES pipelines(id) ON DELETE CASCADE,
@@ -25,30 +27,22 @@ CREATE INDEX IF NOT EXISTS idx_claim_pri ON messages (pipeline, subqueue, claime
 `;
 
 function dbDir(): string {
-  const home = process.env.HOME;
-  if (home?.startsWith('/sessions')) {
-    try {
-      const workspace = readFileSync(join(home, '.cowork_workspace_location'), 'utf8').trim();
-      if (workspace) return join(workspace, '.claude', 'qq');
-    } catch { /* file absent */ }
-    throw new Error(
-      'Cowork sandboxed environment detected.\n' +
-      'Before using qq, write your sandbox workspace path to $HOME/.cowork_workspace_location:\n' +
-      '  echo "<sandbox workspace path>" > $HOME/.cowork_workspace_location\n' +
-      'Find the workspace path in your system prompt\'s shell access path mapping.'
-    );
-  }
-  return join(process.cwd(), '.claude', 'qq');
+  return join(process.env.HOME!, '.claude', 'qq');
 }
 
 export function openDb(): Database.Database {
   const dir = dbDir();
   mkdirSync(dir, { recursive: true });
   const db = new Database(join(dir, 'qq.db'));
-  db.pragma('journal_mode = MEMORY');
+  db.pragma('journal_mode = WAL');
   db.pragma('busy_timeout = 5000');
   db.pragma('foreign_keys = ON');
   db.exec(DDL);
+  // Migration: add description column if missing (existing DBs pre-date this column)
+  const cols = db.prepare("PRAGMA table_info(pipelines)").all() as { name: string }[];
+  if (!cols.some(c => c.name === 'description')) {
+    db.exec('ALTER TABLE pipelines ADD COLUMN description TEXT');
+  }
   return db;
 }
 

package/src/http.ts

@@ -0,0 +1,133 @@
+import express from 'express';
+import cors from 'cors';
+import { createServer } from 'node:net';
+import { randomBytes } from 'node:crypto';
+import {
+  makePipeline, deletePipeline, push, claim, release,
+  batchRead, status, unstick, loadFile, QQError,
+} from './commands.js';
+
+export interface HttpServer {
+  port: number;
+  token: string;
+  close(): void;
+}
+
+function pickPort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.listen(0, () => {
+      const addr = srv.address();
+      srv.close(() => {
+        if (addr && typeof addr === 'object') resolve(addr.port);
+        else reject(new Error('failed to get port'));
+      });
+    });
+  });
+}
+
+export async function startHttp(fixedPort?: number): Promise<HttpServer> {
+  const port = fixedPort ?? await pickPort();
+  const token = randomBytes(32).toString('hex');
+
+  const app = express();
+  app.use(cors());
+  app.use(express.json({ limit: '50mb' }));
+
+  // Auth middleware
+  app.use((req, res, next) => {
+    const auth = req.headers['authorization'];
+    if (auth !== `Bearer ${token}`) {
+      res.status(401).json({ error: 'Unauthorized' });
+      return;
+    }
+    next();
+  });
+
+  function wrap(res: express.Response, fn: () => unknown) {
+    try {
+      const result = fn();
+      res.json(result ?? { ok: true });
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      const status = e instanceof QQError ? 400 : 500;
+      res.status(status).json({ error: msg });
+    }
+  }
+
+  // Routes
+  app.post('/pipelines', (req, res) => {
+    wrap(res, () => ({ pipeline: makePipeline(req.body?.name, req.body?.description) }));
+  });
+
+  app.delete('/pipelines/:pipeline', (req, res) => {
+    wrap(res, () => { deletePipeline(req.params.pipeline); });
+  });
+
+  app.post('/pipelines/:pipeline/push', (req, res) => {
+    const { stage, id, payload, priority, payloadFormat } = req.body ?? {};
+    wrap(res, () => ({ id: push(req.params.pipeline, stage, id, { payload, priority, payloadFormat }) }));
+  });
+
+  app.post('/pipelines/:pipeline/claim', (req, res) => {
+    const { stage = '*', id, random } = req.body ?? {};
+    wrap(res, () => claim(req.params.pipeline, stage, id, { random }));
+  });
+
+  app.post('/pipelines/:pipeline/release/:seq', (req, res) => {
+    const seq = parseInt(req.params.seq, 10);
+    const { target, payload, replace, priority, payloadFormat } = req.body ?? {};
+    wrap(res, () => { release(req.params.pipeline, seq, { target, payload, replace, priority, payloadFormat }); });
+  });
+
+  app.get('/pipelines/:pipeline/status', (req, res) => {
+    wrap(res, () => status(req.params.pipeline));
+  });
+
+  app.get('/pipelines/:pipeline/items', (req, res) => {
+    const { stage = '*', includePayload, claimed, ids, createdAfter, createdBefore, modifiedAfter, limit, offset } = req.query;
+    wrap(res, () => batchRead(
+      req.params.pipeline,
+      String(stage),
+      {
+        claimed: claimed !== undefined ? String(claimed).toLowerCase() === 'true' : undefined,
+        ids: ids ? String(ids).split(',') : undefined,
+        created_after: createdAfter ? Number(createdAfter) : undefined,
+        created_before: createdBefore ? Number(createdBefore) : undefined,
+        modified_after: modifiedAfter ? Number(modifiedAfter) : undefined,
+        limit: limit ? Number(limit) : undefined,
+        offset: offset ? Number(offset) : undefined,
+      },
+      String(includePayload).toLowerCase() === 'true',
+    ));
+  });
+
+  app.post('/pipelines/:pipeline/load', (req, res) => {
+    const { path: filePath, stage, deleteAfter } = req.body ?? {};
+    wrap(res, () => {
+      const results = loadFile(filePath, req.params.pipeline, { stage, deleteAfter });
+      return results.map(r => r.message ? `${r.id}: ${r.status}: ${r.message}` : `${r.id}: ${r.status}`);
+    });
+  });
+
+  app.post('/pipelines/:pipeline/unstick', (req, res) => {
+    const { stage = '*', ids, createdAfter, createdBefore, modifiedAfter } = req.body ?? {};
+    wrap(res, () => ({
+      unstuck: unstick(req.params.pipeline, stage, {
+        ids: ids ?? undefined,
+        created_after: createdAfter ?? undefined,
+        created_before: createdBefore ?? undefined,
+        modified_after: modifiedAfter ?? undefined,
+      }),
+    }));
+  });
+
+  const server = app.listen(port, '0.0.0.0');
+  await new Promise<void>((resolve) => server.once('listening', resolve));
+
+  return {
+    port,
+    token,
+    close: () => server.close(),
+  };
+}