ftown-bridge 0.19.39 → 0.19.40

package/dist/workflow-runner.js

@@ -1,307 +0,0 @@
-/**
- * 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_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(/\.{2,}/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;
-    // 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

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

package/skills/fticket/SKILL.md

@@ -1,166 +0,0 @@
----
-name: fticket
-description: >-
-  Operate fticket (FTS, the Factory Ticket System) through its `fts` CLI: tickets,
-  atomic claims, dependencies, resource leases with FIFO waitlists, scheduler sweeps,
-  status/history/events, and stuck-work diagnosis. Use whenever work mentions FTS,
-  factory.db, factory tickets, worker claims, resource leases, or factory pipelines.
----
-
-# fticket — transactional coordination for agent teams
-
-FTS is the durable control plane for concurrent agents. It owns task status, atomic
-claims, dependencies, resource leases, and an immutable history/event stream in one
-SQLite database (WAL mode with race-free write transactions). Ticket folders hold
-durable artifacts; FTS holds who owns work, what is blocked, and what happens next.
-
-Prefer FTS over direct agent messages whenever an existing database/ticket is available:
-
-- use the ticket and artifact folder for shared context;
-- use claims, lifecycle transitions, notes, board/history/events for status;
-- use dependencies for ordering;
-- use resource leases for shared mutable surfaces;
-- use direct messages only when FTS is unavailable/fenced or for urgent escalation.
-
-## Runtime
-
-- CLI: `fts` (also `python -m fticket`)
-- Python: 3.13+
-- Install: `uv tool install fticket` or `uv tool upgrade fticket`
-- Without installing: `uvx --python 3.13 fticket ...`
-- Database: `--db PATH`, default `factory.db`; the flag may precede or follow a subcommand.
-- Configuration lives in the database; there are no fticket environment variables.
-
-Never open or edit the SQLite file directly. Use the CLI/API so fencing, leases, events,
-and invariants remain transactional.
-
-## Ticket lifecycle
-
-Statuses are `queued`, `claimed`, `in_progress`, `done`, `rejected`, `blocked`, and
-`dead_letter`.
-
-```bash
-fts init --db factory.db --stages code,review,qa,deploy
-fts create --db factory.db --title "build parser" --stage code --folder tasks/0001
-fts claim --db factory.db --stage code --worker coder-1
-fts start --db factory.db --ticket 1 --worker coder-1 --epoch 2
-fts renew --db factory.db --ticket 1 --worker coder-1 --epoch 2
-fts complete --db factory.db --ticket 1 --worker coder-1 --epoch 2 \
-  --note "implementation-notes.md written; checks green"
-fts advance --db factory.db --ticket 1 --worker coder-1 --to-stage review \
-  --note "ready for review"
-```
-
-Claims expire unless renewed (default five minutes). Always pass the epoch returned by
-`claim` when the command offers `--epoch`; it fences stale workers after reassignment.
-Run `fts scheduler` continuously, or `fts tick` periodically, so expired claims/leases
-are swept and waitlists/dependencies are promoted.
-
-Legal flow:
-
-- `queued` → `claimed` only via `claim`
-- `claimed` → `in_progress` via `start`
-- `in_progress` → `done` via `complete`
-- `done` → `queued` at a different stage via `advance`
-- `reject` bounces work according to the pipeline; repeated bounces dead-letter
-- operator escape hatches: `transition`, `dead-letter`, and `revive`
-
-Dependencies are durable ordering, not messages:
-
-```bash
-fts add-dep --db factory.db --ticket 8 --depends-on 7 --until review
-fts dag --db factory.db --format ascii
-```
-
-## Resources (leases with FIFO waitlists)
-
-Register stable names once, then acquire before touching the shared surface:
-
-```bash
-fts register-resource --db factory.db --name staging --policy exclusive_only
-fts register-resource --db factory.db --name test-db --policy both
-
-fts acquire --db factory.db --resource staging --ticket 8 --worker coder-1 \
-  --mode exclusive
-fts resources --db factory.db --json
-fts release --db factory.db --ticket 8 --resource staging
-```
-
-Policies: `both`, `exclusive_only`, `shared_only`. Modes: `exclusive`, `shared`.
-If acquisition is waitlisted, the ticket becomes blocked on that resource. Do not touch
-the resource until the scheduler grants the lease. Waitlists are FIFO, and leases expire
-after their TTL (default ten minutes), so long operations must renew their ticket claim
-and finish/release the resource promptly.
-
-Acquire multiple resources in alphabetical order to avoid team-level deadlock patterns.
-Plan a release for every acquired lease and run it even when later work fails.
-
-`fts release` is overloaded and accepts exactly one release target:
-
-```bash
-# Release a ticket claim back to the queue
-fts release --db factory.db --ticket 8 --worker coder-1 --epoch 2 --note "reason"
-
-# Release a resource lease
-fts release --db factory.db --ticket 8 --resource staging
-```
-
-Never combine `--worker` and `--resource` in one release command.
-
-## Shared context and status
-
-Use `fts show --json` first, then read the ticket's artifact folder. Artifacts accrete:
-do not delete or rewrite another stage's handoff. Name the artifact in concise completion,
-advance, or rejection notes so later workers can locate it from immutable history.
-
-```bash
-fts show --db factory.db 8 --json
-fts board --db factory.db
-fts queues --db factory.db
-fts events --db factory.db --after 120
-fts why --db factory.db 8
-```
-
-FTS does not provide free-form chat. That is deliberate: substantive context belongs in
-artifacts and status belongs in lifecycle/history. Use ftown mail only for urgent
-questions or escalation that cannot be represented durably, and summarize the answer in
-the ticket artifact before continuing.
-
-## Scheduler
-
-```bash
-fts tick --db factory.db --verbose
-fts scheduler --db factory.db --interval-ms 1000
-```
-
-Nothing else expires claims/leases or promotes resource waitlists. A factory dispatcher
-may call `tick` itself; otherwise run one scheduler process per database.
-
-## Diagnosis and observability
-
-```bash
-fts board --db factory.db --json
-fts show --db factory.db 8 --json
-fts why --db factory.db 8
-fts resources --db factory.db --json
-fts dag --db factory.db --format ascii
-fts triage --db factory.db --json
-fts doctor --db factory.db
-fts events --db factory.db --after 0 --follow
-fts serve --db factory.db --port 8787
-```
-
-For a stuck ticket: run `why`, then `show`, then `resources`; use `triage` for
-dead-letters/orphans and `doctor` for systemic invariant failures. The events cursor is
-the integration hook for orchestrators—persist the last cursor and poll after it.
-
-## Operational gotchas
-
-- `claimed` is reachable only via `claim`; `transition --to claimed` is invalid.
-- `advance` must change stage.
-- `blocked` is driven by resource/dependency mechanics, not an arbitrary worker status.
-- Ticket folders are immutable identities and never move.
-- History, events, and reached stages are append-only.
-- Read commands are safe for observers; write commands require the correct worker/epoch.
-- One FTS object/CLI process uses one connection; SQLite serializes concurrent writers.
-- If `uvx fticket` is shadowed by a 0.1.0 installed tool, run `uv tool upgrade fticket`.