ftown-bridge 0.9.2 → 0.9.4

package/dist/workflow-runner-cli.js

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+/**
+ * ftown-workflows CLI.
+ *
+ * Wires the real dependencies (HTTP loopback BridgeClient, node:fs ResultStore,
+ * Date.now/setTimeout Clock, stderr Logger), loads a workflow script, and runs it
+ * through the engine in `workflow-runner.ts`.
+ *
+ * Installed to ~/.ftown/ftown-workflows-cli.js by ftown-bridge. Must run INSIDE an
+ * ftown session: spawned children need a parent, so FTOWN_SESSION_ID is required.
+ */
+import { mkdirSync, readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { parseResultFile, runWorkflow, } from './workflow-runner.js';
+function loadBridge() {
+    const path = join(homedir(), '.ftown', 'bridge.json');
+    const raw = readFileSync(path, 'utf8');
+    const data = JSON.parse(raw);
+    if (!data.port || !data.token) {
+        throw new Error('Invalid bridge.json (missing port or token)');
+    }
+    return data;
+}
+// ---- Real BridgeClient: HTTP to the local bridge loopback API ----
+class HttpBridgeClient {
+    selfSessionId;
+    constructor(selfSessionId) {
+        this.selfSessionId = selfSessionId;
+    }
+    async api(method, path, body, extraHeaders) {
+        const { port, token } = loadBridge();
+        const headers = {
+            Authorization: `Bearer ${token}`,
+            ...extraHeaders,
+        };
+        let payload;
+        if (body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            payload = JSON.stringify(body);
+        }
+        const res = await fetch(`http://127.0.0.1:${port}${path}`, {
+            method,
+            headers,
+            body: payload,
+        });
+        const text = await res.text();
+        let data = null;
+        if (text) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = { raw: text };
+            }
+        }
+        if (!res.ok) {
+            const err = data;
+            throw new Error(err?.error ?? `HTTP ${res.status}`);
+        }
+        return { status: res.status, data };
+    }
+    async createSession(opts) {
+        const body = {
+            prompt: opts.prompt,
+            shellType: opts.shellType,
+            parentSessionId: opts.parentSessionId,
+            // Workflow children report via the result FILE, never via the mail briefing.
+            suppressBriefing: true,
+        };
+        if (opts.workingDir)
+            body.workingDir = opts.workingDir;
+        if (opts.name)
+            body.name = opts.name;
+        if (opts.model)
+            body.model = opts.model;
+        const { data } = await this.api('POST', '/api/sessions', body, {
+            'X-Ftown-Session-Id': this.selfSessionId,
+        });
+        const session = data.session;
+        if (!session?.id) {
+            throw new Error('createSession: bridge did not return a session id');
+        }
+        return { id: session.id };
+    }
+    async removeSession(id) {
+        try {
+            await this.api('DELETE', `/api/sessions/${id}`);
+        }
+        catch {
+            // Swallow 404 / already-removed — cleanup must never throw.
+        }
+    }
+    async isRunning(id) {
+        try {
+            const { data } = await this.api('GET', `/api/sessions/${id}/running`);
+            return data.running === true;
+        }
+        catch {
+            // If we cannot reach the session, treat it as no longer running.
+            return false;
+        }
+    }
+}
+// ---- Real ResultStore: result files under ~/.ftown/workflows/<runId>/<stepKey>.json ----
+class FsResultStore {
+    resultPath(runId, stepKey) {
+        return join(homedir(), '.ftown', 'workflows', runId, `${stepKey}.json`);
+    }
+    async readResult(path) {
+        let text;
+        try {
+            text = await readFile(path, 'utf8');
+        }
+        catch (err) {
+            // ENOENT (file not written yet) and any read error → not ready.
+            if (err.code === 'ENOENT')
+                return null;
+            return null;
+        }
+        return parseResultFile(text);
+    }
+}
+// ---- Real Clock ----
+class RealClock {
+    now() {
+        return Date.now();
+    }
+    sleep(ms) {
+        return new Promise((r) => setTimeout(r, ms));
+    }
+}
+// ---- Real Logger: concise lines to stderr ----
+class StderrLogger {
+    event(ev) {
+        switch (ev.kind) {
+            case 'phase':
+                process.stderr.write(`\n[phase] ${ev.title}\n`);
+                break;
+            case 'log':
+                process.stderr.write(`  ${ev.message}\n`);
+                break;
+            case 'agent-start':
+                process.stderr.write(`  → start ${ev.label} (${ev.sessionId})\n`);
+                break;
+            case 'agent-done':
+                process.stderr.write(`  ${ev.cached ? '⟳' : '✓'} ${ev.label}\n`);
+                break;
+            case 'agent-error':
+                process.stderr.write(`  ✗ ${ev.label}: ${ev.error}\n`);
+                break;
+        }
+    }
+}
+// ---- argv parsing ----
+const SHELLS = ['claude', 'cursor', 'codex', 'opencode', 'shell'];
+function flag(args, name) {
+    const i = args.indexOf(name);
+    if (i === -1 || i + 1 >= args.length)
+        return undefined;
+    return args[i + 1];
+}
+function hasFlag(args, name) {
+    return args.includes(name);
+}
+/** Strict integer flag parser: rejects NaN / non-integer / below-min values. */
+function parseIntFlag(raw, name, min) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n < min) {
+        throw new Error(`${name} must be an integer >= ${min} (got "${raw}")`);
+    }
+    return n;
+}
+// Flags that consume the following argv token as their value — so positional
+// detection must skip that token (otherwise a flag value looks like the script).
+const VALUE_FLAGS = [
+    '--args',
+    '--workdir',
+    '--shell',
+    '--concurrency',
+    '--timeout',
+    '--max-agents',
+    '--run-id',
+];
+function positionals(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith('--')) {
+            if (VALUE_FLAGS.includes(a))
+                i++;
+            continue;
+        }
+        out.push(a);
+    }
+    return out;
+}
+function usage() {
+    console.error(`Usage: ftown-workflows run <script.mjs> [options]
+
+Runs a deterministic multi-session workflow. Must run INSIDE an ftown session
+(FTOWN_SESSION_ID must be set — spawned children need a parent).
+
+Options:
+  --args <json>        JSON passed to the script as ctx.args
+  --workdir <path>     Default working dir for spawned child sessions
+  --shell <type>       Default child shell: ${SHELLS.join(' | ')} (default: claude)
+  --concurrency <n>    Max concurrently-running child sessions (default: 4)
+  --timeout <ms>       Default per-agent timeout in ms (default: 1800000)
+  --max-agents <n>     Cap total agent() spawns this run (default: unbounded)
+  --run-id <id>        Reuse a run id to RESUME (skips already-completed steps)
+  --json               Print the workflow return value as compact JSON
+
+Reads ~/.ftown/bridge.json (ftown-bridge must be running).`);
+}
+function parseShell(value) {
+    if (value === undefined)
+        return undefined;
+    if (SHELLS.includes(value))
+        return value;
+    throw new Error(`Invalid --shell "${value}" — use one of: ${SHELLS.join(', ')}`);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+        usage();
+        process.exit(argv.length === 0 ? 1 : 0);
+    }
+    if (argv[0] !== 'run') {
+        usage();
+        process.exit(1);
+    }
+    const rest = argv.slice(1);
+    const scriptArg = positionals(rest)[0];
+    if (!scriptArg) {
+        throw new Error('Missing <script.mjs> — usage: ftown-workflows run <script.mjs> [options]');
+    }
+    const selfSessionId = process.env.FTOWN_SESSION_ID?.trim();
+    if (!selfSessionId) {
+        throw new Error('FTOWN_SESSION_ID is not set. ftown-workflows must run inside an ftown session ' +
+            'so spawned child sessions have a parent.');
+    }
+    // Fail fast if the bridge is down/misconfigured, instead of running a whole
+    // workflow that returns nothing but null results.
+    try {
+        loadBridge();
+    }
+    catch (e) {
+        throw new Error('ftown-bridge is not running or ~/.ftown/bridge.json is invalid: ' +
+            (e instanceof Error ? e.message : String(e)));
+    }
+    const jsonOut = hasFlag(rest, '--json');
+    const runId = flag(rest, '--run-id') ?? randomUUID().slice(0, 8);
+    const concurrencyRaw = flag(rest, '--concurrency');
+    const timeoutRaw = flag(rest, '--timeout');
+    const maxAgentsRaw = flag(rest, '--max-agents');
+    const argsRaw = flag(rest, '--args');
+    let parsedArgs;
+    if (argsRaw !== undefined) {
+        try {
+            parsedArgs = JSON.parse(argsRaw);
+        }
+        catch {
+            throw new Error('--args must be valid JSON');
+        }
+    }
+    const opts = {
+        runId,
+        selfSessionId,
+        args: parsedArgs,
+        defaultShell: parseShell(flag(rest, '--shell')) ?? 'claude',
+    };
+    const workdir = flag(rest, '--workdir');
+    if (workdir)
+        opts.workdir = resolve(workdir);
+    const concurrency = parseIntFlag(concurrencyRaw, '--concurrency', 1);
+    if (concurrency !== undefined)
+        opts.maxConcurrent = concurrency;
+    const timeout = parseIntFlag(timeoutRaw, '--timeout', 0);
+    if (timeout !== undefined)
+        opts.defaultTimeoutMs = timeout;
+    const maxAgents = parseIntFlag(maxAgentsRaw, '--max-agents', 0);
+    if (maxAgents !== undefined)
+        opts.maxAgents = maxAgents;
+    // Run dir holds every step's result file — print it so the user can resume.
+    const store = new FsResultStore();
+    const runDir = join(homedir(), '.ftown', 'workflows', runId);
+    mkdirSync(runDir, { recursive: true });
+    process.stderr.write(`[ftown-workflows] run ${runId}\n`);
+    process.stderr.write(`[ftown-workflows] run dir: ${runDir}\n`);
+    process.stderr.write(`[ftown-workflows] resume with: --run-id ${runId}\n`);
+    const scriptUrl = pathToFileURL(resolve(scriptArg)).href;
+    const mod = (await import(scriptUrl));
+    const deps = {
+        bridge: new HttpBridgeClient(selfSessionId),
+        store,
+        clock: new RealClock(),
+        logger: new StderrLogger(),
+    };
+    const out = await runWorkflow(deps, mod, opts);
+    if (out !== undefined) {
+        console.log(jsonOut ? JSON.stringify(out) : JSON.stringify(out, null, 2));
+    }
+}
+main().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`ftown-workflows: ${msg}`);
+    process.exit(1);
+});
+//# sourceMappingURL=workflow-runner-cli.js.map

package/dist/workflow-runner-cli.js.map

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

package/dist/workflow-runner.d.ts

@@ -0,0 +1,162 @@
+/**
+ * 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.
+ */
+/** Minimal session-control surface the engine needs. Real impl = HTTP loopback API. */
+export interface BridgeClient {
+    /** Create a session; returns its id. Mirrors POST /api/sessions. */
+    createSession(opts: SpawnSpec): Promise<{
+        id: string;
+    }>;
+    /** Remove (tombstone) a session. Mirrors DELETE /api/sessions/:id. Must not throw on 404. */
+    removeSession(id: string): Promise<void>;
+    /** True if the session PTY is alive. Mirrors GET /api/sessions/:id/running. */
+    isRunning(id: string): Promise<boolean>;
+}
+/** Reads result files written by child sessions. Real impl = node:fs. */
+export interface ResultStore {
+    /** Absolute path where step `stepKey` of `runId` writes its result. */
+    resultPath(runId: string, stepKey: string): string;
+    /**
+     * Returns the parsed RawResult if the file exists AND is valid JSON matching
+     * RawResult; returns null if the file is absent OR not yet valid JSON (partial
+     * write). MUST NOT throw for absent/partial files.
+     */
+    readResult(path: string): Promise<RawResult | null>;
+}
+/** Time abstraction so tests run instantly (fake clock). */
+export interface Clock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+export interface Logger {
+    /** Emitted for phase()/log() and lifecycle events. */
+    event(ev: WorkflowEvent): void;
+}
+export type WorkflowEvent = {
+    kind: 'phase';
+    title: string;
+} | {
+    kind: 'log';
+    message: string;
+} | {
+    kind: 'agent-start';
+    label: string;
+    phase?: string;
+    sessionId: string;
+} | {
+    kind: 'agent-done';
+    label: string;
+    phase?: string;
+    ok: boolean;
+    cached: boolean;
+} | {
+    kind: 'agent-error';
+    label: string;
+    phase?: string;
+    error: string;
+};
+export type WorkflowShell = 'claude' | 'cursor' | 'codex' | 'opencode' | 'shell';
+/** What the engine asks BridgeClient to create. */
+export interface SpawnSpec {
+    prompt: string;
+    shellType: WorkflowShell;
+    workingDir?: string;
+    name?: string;
+    model?: string;
+    parentSessionId: string;
+}
+/** Shape the child writes into its result file. */
+export interface RawResult {
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+}
+export interface AgentOptions {
+    label?: string;
+    phase?: string;
+    schema?: object;
+    shell?: WorkflowShell;
+    model?: string;
+    workdir?: string;
+    name?: string;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    startupGraceMs?: number;
+}
+export interface Budget {
+    /** Max total agent() spawns allowed this run (null = unbounded). */
+    maxAgents: number | null;
+    /** Count of agent() spawns started so far (cached results do NOT count). */
+    spent(): number;
+    /** maxAgents - spent(), or Infinity if maxAgents is null. */
+    remaining(): number;
+}
+export interface WorkflowContext {
+    /**
+     * Spawn a real ftown session for `prompt`, block until its result file appears,
+     * remove the session, and return the result.
+     *  - without schema: returns the result as a string. A string `result` is returned
+     *    as-is; a non-string `result` is returned as a JSON string (JSON.stringify).
+     *  - with schema: returns the parsed RawResult.result (validated as JSON; on parse
+     *    failure the agent is treated as failed).
+     * Returns null if: the session exits without writing a valid result, the timeout
+     * elapses, ok===false, or the budget is exhausted. NEVER rejects for these — only
+     * programming errors (bad args) throw.
+     */
+    agent(prompt: string, opts?: AgentOptions): Promise<string | unknown | null>;
+    /** Run thunks concurrently (BARRIER, respects maxConcurrent). A thunk that throws
+     *  or whose agent errors resolves to null in the result array; the call never rejects. */
+    parallel<T>(thunks: Array<() => Promise<T>>): Promise<Array<T | null>>;
+    /** Run each item through all stages independently, NO barrier between stages.
+     *  Stage callback signature: (prev, originalItem, index). A stage that throws drops
+     *  that item to null and skips its remaining stages. */
+    pipeline(items: unknown[], ...stages: Array<(prev: unknown, item: unknown, index: number) => Promise<unknown>>): Promise<unknown[]>;
+    phase(title: string): void;
+    log(message: string): void;
+    readonly args: unknown;
+    readonly budget: Budget;
+}
+export interface RunOptions {
+    runId: string;
+    selfSessionId: string;
+    args?: unknown;
+    workdir?: string;
+    defaultShell?: WorkflowShell;
+    defaultTimeoutMs?: number;
+    maxConcurrent?: number;
+    maxAgents?: number | null;
+}
+export interface RunnerDeps {
+    bridge: BridgeClient;
+    store: ResultStore;
+    clock: Clock;
+    logger: Logger;
+}
+/** A loaded workflow module: default export is the script body fn, or a `run` export. */
+export type WorkflowModule = {
+    default?: (ctx: WorkflowContext) => Promise<unknown> | unknown;
+    run?: (ctx: WorkflowContext) => Promise<unknown> | unknown;
+};
+/**
+ * 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 declare function buildAgentPrompt(task: string, resultFilePath: string, schema?: object): string;
+/**
+ * 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 declare function parseResultFile(text: string): RawResult | null;
+/** Build + run the context, execute the module, return its return value. */
+export declare function runWorkflow(deps: RunnerDeps, mod: WorkflowModule, opts: RunOptions): Promise<unknown>;