ftown-bridge 0.9.3 → 0.9.5

package/dist/workflow-runner.js

@@ -0,0 +1,305 @@
+/**
+ * ftown-workflows engine.
+ *
+ * Brings Workflow-tool-style deterministic orchestration to REAL ftown sessions:
+ * each `agent()` call spawns a real ftown session via the bridge loopback API, the
+ * child writes its result to a file, the runner polls the filesystem for that file
+ * (race-free — no inbox / Stop-hook contention), removes the session and returns it.
+ *
+ * The engine is fully dependency-injected (BridgeClient / ResultStore / Clock /
+ * Logger) so it is unit-testable without a live bridge, real fs or real timers.
+ */
+const DEFAULT_SHELL = 'claude';
+const DEFAULT_TIMEOUT_MS = 1_800_000;
+const DEFAULT_MAX_CONCURRENT = 4;
+const DEFAULT_POLL_INTERVAL_MS = 2000;
+// A new session reports running:false for a short startup window; only after this grace
+// (with the child never observed running) do we treat it as failed-to-start.
+const DEFAULT_STARTUP_GRACE_MS = 30_000;
+// ---- Pure helpers (exported + individually unit-tested) ----
+/**
+ * Build the full child prompt: the user's `task`, then a clearly delimited protocol
+ * block instructing the child to write its final result as JSON to `resultFilePath`
+ * and then stop. When `schema` is provided, the block embeds the schema and says
+ * `result` must conform. The block always literally contains `resultFilePath`.
+ */
+export function buildAgentPrompt(task, resultFilePath, schema) {
+    const lines = [
+        task.trim(),
+        '',
+        '--- ftown-workflows RESULT PROTOCOL (read carefully) ---',
+        'You are a worker session in a deterministic workflow. When you have finished the',
+        'task above, you MUST write your FINAL result as a single JSON object to this file:',
+        '',
+        `  RESULT FILE: ${resultFilePath}`,
+        '',
+        'The JSON object must have this exact shape:',
+        '  { "ok": true, "result": <your result> }   on success',
+        '  { "ok": false, "error": "<why it failed>" } on failure',
+        '',
+    ];
+    if (schema) {
+        lines.push('On success, `result` MUST be valid JSON conforming to this JSON schema:', '', JSON.stringify(schema, null, 2), '');
+    }
+    else {
+        lines.push('On success, `result` may be a plain string or any JSON value. (Without a schema, a', 'non-string `result` is returned to the calling script as a JSON string.)', '');
+    }
+    lines.push('Write the file atomically (write fully, then save). Do NOT print the result to the', 'terminal instead of the file.', 'The result FILE is the ONLY accepted output channel. Do NOT report via ftown-harness mail, the terminal, or any other channel.', 'After the file is written, STOP — do no further work.', `Reminder: the result file path is ${resultFilePath}`, '--- end protocol ---');
+    return lines.join('\n');
+}
+/**
+ * Parse raw file text into RawResult. Returns null if text is empty or not valid
+ * JSON (partial write). Throws nothing. If JSON parses but lacks a boolean `ok`,
+ * treat as null (not yet complete).
+ */
+export function parseResultFile(text) {
+    if (!text || text.trim().length === 0)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    const obj = parsed;
+    if (typeof obj.ok !== 'boolean')
+        return null;
+    return obj;
+}
+// ---- Internal helpers ----
+/** Async counting semaphore: caps concurrently-running spawn+poll cycles. */
+class Semaphore {
+    permits;
+    waiters = [];
+    constructor(permits) {
+        this.permits = Number.isFinite(permits) ? Math.max(1, Math.floor(permits)) : 1;
+    }
+    async acquire() {
+        if (this.permits > 0) {
+            this.permits -= 1;
+            return;
+        }
+        await new Promise((resolve) => this.waiters.push(resolve));
+    }
+    release() {
+        const next = this.waiters.shift();
+        if (next) {
+            // Hand the permit directly to the next waiter (keeps the cap exact).
+            next();
+        }
+        else {
+            this.permits += 1;
+        }
+    }
+}
+/** Make a label filesystem-safe for use as a result-file stem. */
+function sanitizeStepKey(label) {
+    const cleaned = label.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+    return cleaned.length > 0 ? cleaned : 'step';
+}
+/** Map a successful RawResult to the value agent() returns. */
+function mapOk(raw, hasSchema) {
+    const value = raw.result;
+    if (hasSchema)
+        return value ?? null;
+    if (value === undefined || value === null)
+        return null;
+    // No schema: a string is returned as-is; a non-string structured value is
+    // JSON-stringified (NOT lossily String()-coerced to "[object Object]").
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+/** Build + run the context, execute the module, return its return value. */
+export async function runWorkflow(deps, mod, opts) {
+    const body = mod.default ?? mod.run;
+    if (typeof body !== 'function') {
+        throw new Error('workflow module has no default or `run` export');
+    }
+    const { bridge, store, clock, logger } = deps;
+    const defaultShell = opts.defaultShell ?? DEFAULT_SHELL;
+    // Resolve numerics defensively: `??` does NOT catch NaN, and a NaN cap would
+    // deadlock the semaphore / make every timeout comparison false. Coerce non-finite
+    // values to the documented defaults.
+    const maxConcurrent = Number.isFinite(opts.maxConcurrent)
+        ? Math.max(1, Math.floor(opts.maxConcurrent))
+        : DEFAULT_MAX_CONCURRENT;
+    const defaultTimeoutMs = Number.isFinite(opts.defaultTimeoutMs)
+        ? Math.max(0, opts.defaultTimeoutMs)
+        : DEFAULT_TIMEOUT_MS;
+    // Number.isFinite(null) === false, so both NaN and null collapse to null (unbounded).
+    const maxAgents = Number.isFinite(opts.maxAgents)
+        ? Math.max(0, Math.floor(opts.maxAgents))
+        : null;
+    const sem = new Semaphore(maxConcurrent);
+    // Per-run step-key state (drives resumability + dedup).
+    const usedKeys = new Set();
+    let agentSeq = 0;
+    // Budget accounting — only NON-cached spawns count.
+    let spentCount = 0;
+    function deriveStepKey(label) {
+        agentSeq += 1;
+        const base = sanitizeStepKey(label ?? `step-${agentSeq}`);
+        let key = base;
+        let n = 2;
+        while (usedKeys.has(key)) {
+            key = `${base}-${n}`;
+            n += 1;
+        }
+        usedKeys.add(key);
+        return key;
+    }
+    const budget = {
+        maxAgents,
+        spent: () => spentCount,
+        remaining: () => (maxAgents === null ? Infinity : maxAgents - spentCount),
+    };
+    /** Poll the result file until it appears, the session dies, or we hit the cap. */
+    async function pollForResult(sessionId, path, pollIntervalMs, timeoutMs, startupGraceMs) {
+        const start = clock.now();
+        // A freshly-created session reports `running: false` for a brief startup window
+        // (the PTY exists but the child process is not registered as running yet). If we
+        // treated that first `!running` as terminal we would kill the child before it ever
+        // booted. So `!running` is only terminal once the child has been observed running
+        // at least once (it ran, then exited), or once the startup grace has elapsed
+        // without it ever coming up (it failed to start).
+        let everRunning = false;
+        for (;;) {
+            const found = await store.readResult(path);
+            if (found)
+                return found;
+            const elapsed = clock.now() - start;
+            if (elapsed >= timeoutMs)
+                return null;
+            const running = await bridge.isRunning(sessionId);
+            if (running) {
+                everRunning = true;
+            }
+            else if (everRunning || elapsed >= startupGraceMs) {
+                // Ran-then-exited (do one final read for the wrote-then-exited race) or
+                // never started within the grace window.
+                return await store.readResult(path);
+            }
+            await clock.sleep(pollIntervalMs);
+        }
+    }
+    async function agent(prompt, agentOpts = {}) {
+        if (typeof prompt !== 'string' || prompt.length === 0) {
+            throw new Error('agent(): prompt must be a non-empty string');
+        }
+        const stepKey = deriveStepKey(agentOpts.label);
+        const label = agentOpts.label ?? stepKey;
+        const phase = agentOpts.phase;
+        const hasSchema = agentOpts.schema !== undefined;
+        const path = store.resultPath(opts.runId, stepKey);
+        // 1. Resume: a valid result already on disk → return without spawning.
+        //    A failing cache read is treated as a MISS (proceed to spawn) so agent()
+        //    honors its never-rejects contract; the poll read inside the try block
+        //    surfaces real store failures as null.
+        let cached = null;
+        try {
+            cached = await store.readResult(path);
+        }
+        catch {
+            cached = null;
+        }
+        if (cached) {
+            logger.event({ kind: 'agent-done', label, phase, ok: cached.ok, cached: true });
+            return cached.ok ? mapOk(cached, hasSchema) : null;
+        }
+        // 7. Budget: a set cap blocks further spawns once exhausted.
+        if (maxAgents !== null && spentCount >= maxAgents) {
+            logger.event({ kind: 'agent-error', label, phase, error: 'budget exhausted' });
+            return null;
+        }
+        spentCount += 1;
+        const spec = {
+            prompt: buildAgentPrompt(prompt, path, agentOpts.schema),
+            shellType: agentOpts.shell ?? defaultShell,
+            parentSessionId: opts.selfSessionId,
+        };
+        if (agentOpts.workdir ?? opts.workdir)
+            spec.workingDir = agentOpts.workdir ?? opts.workdir;
+        spec.name = agentOpts.name ?? label;
+        if (agentOpts.model)
+            spec.model = agentOpts.model;
+        // 6. Concurrency: only `maxConcurrent` spawn+poll cycles run at once.
+        await sem.acquire();
+        let sessionId;
+        try {
+            const session = await bridge.createSession(spec);
+            sessionId = session.id;
+            logger.event({ kind: 'agent-start', label, phase, sessionId });
+            const pollInterval = Number.isFinite(agentOpts.pollIntervalMs)
+                ? Math.max(50, agentOpts.pollIntervalMs)
+                : DEFAULT_POLL_INTERVAL_MS;
+            const startupGrace = Number.isFinite(agentOpts.startupGraceMs)
+                ? Math.max(0, agentOpts.startupGraceMs)
+                : DEFAULT_STARTUP_GRACE_MS;
+            const raw = await pollForResult(sessionId, path, pollInterval, agentOpts.timeoutMs ?? defaultTimeoutMs, startupGrace);
+            if (raw && raw.ok) {
+                logger.event({ kind: 'agent-done', label, phase, ok: true, cached: false });
+                return mapOk(raw, hasSchema);
+            }
+            const error = raw
+                ? (raw.error ?? 'agent reported failure')
+                : 'no result (session exited or timed out)';
+            logger.event({ kind: 'agent-error', label, phase, error });
+            return null;
+        }
+        catch (err) {
+            // Real bridge/store errors must not reject agent() — map to a failure.
+            const message = err instanceof Error ? err.message : String(err);
+            logger.event({ kind: 'agent-error', label, phase, error: message });
+            return null;
+        }
+        finally {
+            // 5. Cleanup: ALWAYS remove the session, swallowing 404s.
+            if (sessionId !== undefined) {
+                try {
+                    await bridge.removeSession(sessionId);
+                }
+                catch {
+                    /* removeSession must not throw on 404 — ignore. */
+                }
+            }
+            sem.release();
+        }
+    }
+    async function parallel(thunks) {
+        return Promise.all(thunks.map(async (thunk) => {
+            try {
+                return await thunk();
+            }
+            catch {
+                return null;
+            }
+        }));
+    }
+    async function pipeline(items, ...stages) {
+        return Promise.all(items.map(async (item, index) => {
+            let prev = item;
+            try {
+                for (const stage of stages) {
+                    prev = await stage(prev, item, index);
+                }
+                return prev;
+            }
+            catch {
+                return null;
+            }
+        }));
+    }
+    const ctx = {
+        agent,
+        parallel,
+        pipeline,
+        phase: (title) => logger.event({ kind: 'phase', title }),
+        log: (message) => logger.event({ kind: 'log', message }),
+        args: opts.args,
+        budget,
+    };
+    return await body(ctx);
+}
+//# sourceMappingURL=workflow-runner.js.map

package/dist/workflow-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-runner.js","sourceRoot":"","sources":["../src/workflow-runner.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "ftown-bridge",
-  "version": "0.9.3",
-  "description": "CLI bridge for ftown \u2014 generic PTY-over-Centrifugo relay",
+  "version": "0.9.5",
+  "description": "CLI bridge for ftown — generic PTY-over-Centrifugo relay",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
     "ftown-bridge": "dist/index.js",
     "ftown-harness": "dist/harness-cli.js",
-    "ftown-sessions": "bin/ftown-sessions"
+    "ftown-sessions": "bin/ftown-sessions",
+    "ftown-workflows": "dist/workflow-runner-cli.js"
   },
   "files": [
     "dist",
@@ -17,6 +18,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "node --import tsx --test \"src/**/*.test.ts\"",
     "prepublishOnly": "npm run build",
     "start": "tsx src/index.ts",
     "dev": "tsx watch src/index.ts",

package/skills/ftown-workflows/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: ftown-workflows
+description: >-
+  Run deterministic, scripted, resumable multi-session workflows across real
+  ftown agent sessions. Activates when the user wants to fan out ftown worker
+  sessions over a work list, run a pipeline or parallel batch across ftown
+  sessions, perform adversarial-verify (majority-vote) across sessions,
+  loop-until-dry over a dataset, or write a repeatable orchestration script
+  instead of doing it by hand.
+---
+
+# ftown-workflows
+
+`ftown-workflows` is a **scripted orchestration engine** for real ftown sessions.
+You write a `.mjs` script using a small API (`agent`, `parallel`, `pipeline`,
+`phase`, `log`, `args`, `budget`) and the runner spawns real ftown sessions (claude /
+cursor / codex), waits for each to write a result file, cleans up, and returns the
+value — all deterministically and repeatably.
+
+This complements the by-hand **ftown-orchestrator** skill (which is the ad-hoc,
+human-in-the-loop playbook). Use ftown-workflows when the work is scripted and
+repeatable; use ftown-orchestrator when you need to improvise or keep a human in
+the loop.
+
+## Running a workflow
+
+You must be **inside an ftown session** — `FTOWN_SESSION_ID` must be set.
+
+```bash
+~/.ftown/ftown-workflows run path/to/script.mjs
+```
+
+> **Caveat:** run ftown-workflows from a **top-level orchestrator session**. If the
+> session running it is itself a child, the bridge flattens the tree so spawned
+> workers become **siblings** of the orchestrator rather than its children. Results
+> are file-based, so this does not affect correctness — only the dashboard topology.
+
+Full options:
+
+```bash
+~/.ftown/ftown-workflows run <script.mjs> \
+  [--args <json>]          # parsed and available as ctx.args in the script
+  [--workdir <path>]       # default working dir for spawned child sessions
+  [--shell claude|cursor|codex|opencode|shell]
+  [--concurrency <n>]      # max simultaneous live sessions (default 4)
+  [--timeout <ms>]         # per-agent timeout (default 1 800 000 = 30 min)
+  [--max-agents <n>]       # hard budget cap on total spawns
+  [--run-id <id>]          # resume a previous run (skip completed steps)
+  [--json]                 # print final result as raw JSON
+```
+
+The runner prints the **run directory** (`~/.ftown/workflows/<run-id>/`) at start.
+For long runs, launch in the background and tail the run dir:
+
+```bash
+~/.ftown/ftown-workflows run script.mjs --args '{"pr":42}' &
+tail -f ~/.ftown/workflows/<run-id>/*.json
+```
+
+See the runnable template at `skills/ftown-workflows/scripts/example.flow.mjs`.
+
+## Script API
+
+A workflow script is an ES module. Its **default export** (or named `run` export)
+is an async function that receives a `WorkflowContext`:
+
+```js
+// my-workflow.mjs
+export default async function (ctx) {
+  ctx.phase('Gather');
+  ctx.log(`args: ${JSON.stringify(ctx.args)}`);
+
+  const summary = await ctx.agent('Summarise the repo README', {
+    label: 'summarise',
+    workdir: '/path/to/repo',
+  });
+
+  ctx.log(`summary: ${summary}`);
+  return summary;
+}
+```
+
+### `ctx.agent(prompt, opts?)`
+
+Spawns one real ftown session. Blocks until the session writes its result file,
+then removes the session and returns the result.
+
+- Without `schema`: returns a **string** (or `null` on failure/timeout). A string
+  `result` is returned as-is; a non-string `result` is returned as a JSON string.
+- With `schema`: returns the child's `result` JSON value **as-is** (parsed from the
+  result file), or `null` on failure. The engine does **not** validate `result`
+  against the schema — the schema is embedded in the child's prompt as guidance only.
+  Treat conformance as best-effort and validate it yourself if you depend on it.
+
+Returns `null` — never throws — for: timeout, session exits without a result,
+`ok: false` in the result, budget exhausted.
+
+Key options:
+
+| option | default | meaning |
+|---|---|---|
+| `label` | `step-<n>` | step key used for the result file and resume |
+| `phase` | — | progress grouping shown in logs |
+| `schema` | — | JSON Schema; forces JSON result |
+| `shell` | run-level default | `claude` / `cursor` / `codex` / `opencode` / `shell` |
+| `model` | — | model override passed to the session |
+| `workdir` | run-level default | working directory for the child session |
+| `timeoutMs` | 1 800 000 | wall-clock cap for this step |
+| `pollIntervalMs` | 2000 | how often to check for the result file |
+
+### `ctx.parallel(thunks)`
+
+Run an array of thunks concurrently (barrier: waits for all). Respects the
+run-level `--concurrency` cap. A thunk that errors → `null` entry; the call
+never rejects.
+
+```js
+const reviews = await ctx.parallel(
+  files.map(f => () => ctx.agent(`Review ${f}`, { label: `review-${f}` }))
+);
+```
+
+### `ctx.pipeline(items, ...stages)`
+
+Thread each item through a sequence of stages independently (no barrier between
+stages). A stage that throws drops that item to `null` and skips its remaining
+stages.
+
+```js
+const results = await ctx.pipeline(
+  files,
+  async (file) => ctx.agent(`lint ${file}`, { label: `lint-${file}` }),
+  async (lintResult, file) => ctx.agent(`fix issues in ${file}: ${lintResult}`, { label: `fix-${file}` }),
+);
+```
+
+### `ctx.phase(title)` / `ctx.log(message)`
+
+Emit progress events to stderr. Use `phase` for major milestones, `log` for
+detail lines.
+
+### `ctx.args`
+
+The value passed via `--args <json>` (parsed). `undefined` if not provided.
+
+### `ctx.budget`
+
+```js
+ctx.budget.maxAgents   // null = unbounded
+ctx.budget.spent()     // spawns so far (cached don't count)
+ctx.budget.remaining() // maxAgents - spent(), or Infinity
+```
+
+## Result-file contract
+
+Each child session receives a prompt that ends with a protocol block instructing
+it to write its final result as JSON to a specific file path and then stop:
+
+```json
+{ "ok": true, "result": "...anything..." }
+```
+
+or on failure:
+
+```json
+{ "ok": false, "error": "reason" }
+```
+
+The engine polls the file every `pollIntervalMs` ms. A partial write (incomplete
+JSON) is silently ignored until it is valid. The child session is removed (archived)
+once the result is read, or on timeout/exit.
+
+**You do not write this file yourself** — the child agent is instructed to do it.
+The prompt injected by the engine tells the child agent exactly what to write.
+
+## Patterns
+
+### Parallel fan-out
+
+```js
+export default async function (ctx) {
+  const items = ctx.args.items;  // e.g. ["auth.ts", "api.ts", "db.ts"]
+
+  ctx.phase('Review');
+  const reviews = await ctx.parallel(
+    items.map(f => () => ctx.agent(`Review ${f} for security issues`, {
+      label: `review-${f}`,
+    }))
+  );
+
+  ctx.phase('Synthesise');
+  const report = await ctx.agent(
+    `Synthesise these security reviews:\n${reviews.filter(Boolean).join('\n---\n')}`,
+    { label: 'synthesis' },
+  );
+
+  return report;
+}
+```
+
+### Pipeline (multi-stage per item)
+
+```js
+export default async function (ctx) {
+  return ctx.pipeline(
+    ctx.args.files,
+    (file) => ctx.agent(`Lint ${file}`, { label: `lint-${file}` }),
+    (lintOut, file) => ctx.agent(`Fix ${file} based on: ${lintOut}`, { label: `fix-${file}` }),
+    (fixOut, file) => ctx.agent(`Write tests for ${file}`, { label: `test-${file}` }),
+  );
+}
+```
+
+### Adversarial verify (majority vote)
+
+```js
+export default async function (ctx) {
+  const claim = ctx.args.claim;
+  const REVIEWERS = 3;
+
+  ctx.phase('Verify');
+  const verdicts = await ctx.parallel(
+    Array.from({ length: REVIEWERS }, (_, i) =>
+      () => ctx.agent(
+        `You are a skeptical reviewer. Is this claim correct? "${claim}" Reply with just "yes" or "no".`,
+        { label: `skeptic-${i}` },
+      )
+    )
+  );
+
+  const yes = verdicts.filter(v => v?.toLowerCase().startsWith('yes')).length;
+  return { claim, verdict: yes > REVIEWERS / 2 ? 'accepted' : 'rejected', votes: verdicts };
+}
+```
+
+### Loop-until-dry
+
+```js
+export default async function (ctx) {
+  let queue = [...ctx.args.items];
+  const done = [];
+
+  while (queue.length > 0 && ctx.budget.remaining() > 0) {
+    ctx.phase(`Batch (${queue.length} remaining)`);
+    const batch = queue.splice(0, 4);
+    const results = await ctx.parallel(
+      batch.map(item => () => ctx.agent(`Process: ${item}`, { label: `proc-${item}` }))
+    );
+    done.push(...results.filter(Boolean));
+  }
+
+  return done;
+}
+```
+
+## Resume
+
+Every step is keyed by its `label` (or `step-<n>`). If a result file already
+exists for a step, the engine returns the cached result without spawning a new
+session. To resume a partial run:
+
+```bash
+~/.ftown/ftown-workflows run script.mjs --run-id <the-previous-run-id>
+```
+
+The run id and run directory are printed at startup.
+
+## When to use this vs ftown-orchestrator
+
+| | ftown-orchestrator | ftown-workflows |
+|---|---|---|
+| **style** | ad-hoc, by hand | scripted, deterministic |
+| **human in loop** | yes — you direct workers via mail | no — script drives everything |
+| **repeatability** | each run is improvised | same script, same steps |
+| **resume** | manual | automatic via `--run-id` |
+| **best for** | exploratory tasks, escalations, debugging | batch jobs, CI-style pipelines, fan-out reviews |
+
+## If the CLI is missing
+
+Start or restart **ftown-bridge** on this machine. It installs
+`~/.ftown/ftown-workflows` and updates this skill under
+`~/.ftown/skills/ftown-workflows/` (linked into ~/.agents/skills and ~/.claude/skills).