@dalmasonto/taskflow-mcp 1.0.33 → 2.0.0

package/dist/connect.js

@@ -0,0 +1,269 @@
+/**
+ * The agent's connection to TaskFlow: register a session, prove liveness, and
+ * keep doing both for as long as the process lives.
+ *
+ * ## Why this is its own module
+ *
+ * This ran as step one of `startMirrorForThisAgent`'s `start(pane)` callback,
+ * behind `mirror.ts`'s "no tmux pane, nothing to mirror" early return. A
+ * capability (presence) was smuggled inside a feature (terminal mirroring), so
+ * the feature's precondition became the capability's: an agent outside tmux
+ * never registered, never heartbeat, and never appeared in the dashboard.
+ *
+ * Mirroring is now layered on top of this — `onSession` hands the caller a live
+ * session to attach the event stream and the pane mirror to.
+ *
+ * Retries are UNBOUNDED. The old startup gave up after 8 attempts (~2 minutes)
+ * and stayed dead for the life of the process, which is indistinguishable from
+ * the bug this module fixes: starting the MCP before the backend is a normal
+ * ordering, not an error.
+ */
+import { TaskflowApiError, TaskflowClient } from "./client.js";
+import { sessionIdentifier } from "./session-identifier.js";
+import { hostname } from "node:os";
+/** Backoff, matching `events.ts`'s reconnect policy exactly. */
+const RETRY_BASE_MS = 1_000;
+const RETRY_MAX_MS = 30_000;
+/** 30s beats inside a 90s liveness window — a three-way contract with the
+ *  backend's AGENT_HEARTBEAT_WINDOW_SECS and the frontend's ..._MS. */
+const HEARTBEAT_MS = 30_000;
+let status = { state: "starting", attempts: 0 };
+/**
+ * Which connection the module-level `status` describes.
+ *
+ * There can be more than one live connection in a process — `select_profile`
+ * starts a second one after a human picks a profile — and a single shared
+ * variable let them cross-talk: the superseded connection's `stop()` would
+ * flip the LIVE connection's row to `stopped`, so `whoami` reported an offline
+ * agent that was in fact heartbeating. The newest connection owns the status;
+ * every write from an older one is dropped.
+ */
+let statusOwner;
+/** The current connection status, for `whoami` to report. */
+export function getConnectionStatus() {
+    return { ...status };
+}
+/** Record that we are deliberately NOT connecting until a human picks. */
+export function setNeedsProfile(detail) {
+    statusOwner = undefined;
+    status = { state: "needs_profile", detail, attempts: 0 };
+}
+/** Test seam — reset module-level status between cases. */
+export function resetConnectionStatus() {
+    statusOwner = undefined;
+    status = { state: "starting", attempts: 0 };
+}
+/**
+ * The first line of why something failed, for ANY thrown value.
+ *
+ * Nothing guarantees a rejection carries an `Error`: `fetch` internals reject
+ * with `{code:"ECONNRESET"}`, libraries throw strings, and a bare
+ * `Promise.reject()` carries `undefined`. `(err as Error).message.split(...)`
+ * on those throws a TypeError from INSIDE the catch block, which escapes the
+ * handler that was supposed to contain it — the one thing this module must
+ * never do.
+ */
+function reason(err) {
+    try {
+        const raw = err instanceof Error && typeof err.message === "string" ? err.message : String(err);
+        return raw.split("\n")[0] || "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+const defaultSleep = (ms) => new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    // Never hold the process open for a retry.
+    t.unref?.();
+});
+/**
+ * Connect and stay connected. Never throws and never rejects: the agent must
+ * keep working whether or not the dashboard is reachable.
+ */
+export function startConnection(options) {
+    const { profile, pane, log: rawLog = () => { }, sleep = defaultSleep, heartbeatMs = HEARTBEAT_MS, autoHeartbeat = true, createClient = (p) => new TaskflowClient({ server: p.server, key: p.key }), } = options;
+    /** Diagnostics are never worth the connection: an injected `log` that throws
+     *  (a closed stream, a broken transport) must not unwind a catch block. */
+    const log = (line) => {
+        try {
+            rawLog(line);
+        }
+        catch {
+            // Nowhere left to report it — stdout belongs to the MCP transport.
+        }
+    };
+    let stopped = false;
+    let session;
+    // Starting a connection makes it the one `whoami` describes; the previous
+    // one keeps running but can no longer write to the shared status.
+    const token = {};
+    statusOwner = token;
+    status = { state: "starting", attempts: 0, profile: profile.profileName };
+    /**
+     * Write the shared status — a no-op once this connection is superseded.
+     *
+     * The profile is stamped HERE rather than at each call site: every published
+     * status describes this connection, so there is no state in which the field
+     * could correctly be omitted, and a new publish site cannot forget it.
+     */
+    const publish = (next) => {
+        if (statusOwner !== token)
+            return;
+        status = { ...next, profile: profile.profileName };
+    };
+    /**
+     * Built on first use, INSIDE the retry loop's try — never in the function
+     * body. `new TaskflowClient(...)` throws on a profile with no `server` and
+     * on a runtime with no `fetch`, and a throw out here would escape
+     * `startConnection` itself: the caller would get no handle, no `settled` to
+     * catch on, and — since Task 6 calls this on the startup path — a dead MCP
+     * server at boot. Built once and reused so a retry does not leak clients.
+     */
+    let client;
+    let identifier;
+    const clientOf = () => (client ??= createClient(profile));
+    const identifierOf = () => (identifier ??= sessionIdentifier({
+        pane,
+        profileName: profile.profileName,
+        project: profile.project,
+        agentId: profile.agentId,
+        configPath: profile.configPath,
+    }));
+    const register = async () => {
+        const row = await clientOf().registerSession({
+            session_identifier: identifierOf(),
+            host: hostname(),
+            pid: process.pid,
+            cwd: process.cwd(),
+            transport: pane ? "tmux" : "mcp",
+        });
+        return row.id;
+    };
+    /** One heartbeat tick. A dead session is re-registered; anything else waits. */
+    const beat = async () => {
+        if (stopped || session === undefined)
+            return;
+        try {
+            await clientOf().heartbeat(session);
+        }
+        catch (err) {
+            // 404: the row is gone (backend restarted with a fresh DB, or it was
+            // swept). 401: the credential was rejected mid-flight. Both are fixed by
+            // registering again — it is idempotent per identifier and re-adopts the
+            // SAME row id, so the mirror's session number stays valid.
+            const status_ = err instanceof TaskflowApiError ? err.status : 0;
+            if (status_ === 404 || status_ === 401) {
+                try {
+                    session = await register();
+                    // `stop()` may have landed while the re-register request was in
+                    // flight — mirrors the same check in `run()`. Without it, a
+                    // torn-down connection's `beat()` can resolve after `stop()` and
+                    // flip a correctly-`stopped` status back to a lying `active`.
+                    if (stopped)
+                        return;
+                    // Built fresh, not spread from `status`: a spread-plus-`detail:
+                    // undefined` creates an OWN `detail` key whose value is
+                    // `undefined`, so `"detail" in status` reads true even though
+                    // there is nothing to report.
+                    publish({ state: "active", attempts: status.attempts, session });
+                    log(`session re-registered as ${session}`);
+                }
+                catch (reErr) {
+                    // The next tick tries again; a backend mid-restart is expected. But
+                    // do NOT keep reporting a confident `active` against a session id
+                    // the backend just 404'd — that lie would stand for a full 30s beat.
+                    const detail = `session ${session} is gone; re-register failed (${reason(reErr)})`;
+                    publish({ ...status, state: "retrying", detail });
+                    log(detail);
+                }
+                return;
+            }
+            // Transient (network, 5xx): the next tick retries. Re-registering here
+            // would hammer a struggling backend with writes instead of cheap beats.
+            log(`heartbeat failed (${reason(err)})`);
+        }
+    };
+    const heartbeatLoop = async () => {
+        while (!stopped) {
+            try {
+                await sleep(heartbeatMs);
+            }
+            catch {
+                return; // test sleep budget exhausted, or the timer was torn down
+            }
+            try {
+                await beat();
+            }
+            catch (err) {
+                // `beat` contains its own failures, but a defect in that containment
+                // must cost one tick, not the whole loop: an escape here lands on an
+                // unhandled rejection and the agent goes silently offline forever.
+                // Logged (via the guarded `log`, never the raw callback) so a
+                // regression in that containment leaves a trace instead of vanishing.
+                log(`heartbeat loop caught an escape from beat() (${reason(err)})`);
+            }
+        }
+    };
+    const run = async () => {
+        for (let attempt = 1; !stopped; attempt += 1) {
+            let live;
+            try {
+                live = await register();
+            }
+            catch (err) {
+                const detail = reason(err);
+                publish({ state: "retrying", attempts: attempt, detail });
+                // Grow, cap, jitter — so a backend coming back up is not hit by every
+                // client at once.
+                const ceiling = Math.min(RETRY_BASE_MS * 2 ** (attempt - 1), RETRY_MAX_MS);
+                const delay = Math.round(ceiling / 2 + Math.random() * (ceiling / 2));
+                log(`not connected yet (${detail}) — retrying in ${delay}ms`);
+                try {
+                    await sleep(delay);
+                }
+                catch {
+                    return; // test sleep budget exhausted
+                }
+                continue;
+            }
+            // `stop()` may have landed while the register request was in flight.
+            // Without this, a torn-down connection reports itself active and hands
+            // the caller a session to attach a mirror and an event stream to.
+            if (stopped)
+                return;
+            session = live;
+            publish({ state: "active", attempts: attempt, session });
+            if (attempt > 1)
+                log(`connected after ${attempt} attempts`);
+            if (autoHeartbeat)
+                void heartbeatLoop();
+            // Deliberately OUTSIDE the retry loop and in its own try/catch. The
+            // caller attaches the pane mirror and the SSE stream here, and attaching
+            // genuinely fails in practice. That is a failed mirror, not a failed
+            // connection: the session IS registered and IS heartbeating, so it stays
+            // `active` and must never be re-registered — inside the loop, one
+            // rejection became an unbounded register storm against the backend.
+            try {
+                await options.onSession?.({ client: clientOf(), session, profile, pane });
+            }
+            catch (err) {
+                log(`session attach failed (${reason(err)}) — connection stays active`);
+            }
+            return;
+        }
+    };
+    // Last-resort net. Every failure path inside `run` is already contained; this
+    // exists so that a future one that is not cannot become an unhandled
+    // rejection in the MCP process, which is what this module's contract forbids.
+    const settled = run().catch(() => { });
+    return {
+        settled,
+        beat,
+        stop: () => {
+            stopped = true;
+            publish({ ...status, state: "stopped" });
+        },
+    };
+}
+//# sourceMappingURL=connect.js.map

package/dist/connect.js.map

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

package/dist/doctor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `taskflow-mcp --check` — verify the whole agent chain from a terminal.
+ *
+ * The MCP tools can only be called by a model through an MCP client, so there is
+ * otherwise no way for a human to answer "is this thing actually wired up?"
+ * without hand-rolling curl. This walks the same path the server does — find the
+ * config, resolve each profile, authenticate against the backend — and reports
+ * where it breaks, with the fix.
+ *
+ * Writes to stdout (this mode is not the MCP transport) and exits non-zero on
+ * failure so it can gate a script.
+ */
+export interface DoctorOptions {
+    configPath?: string | undefined;
+    startDir?: string | undefined;
+    env?: NodeJS.ProcessEnv;
+    /** Injected in tests; defaults to writing a line to stdout. */
+    log?: (line: string) => void;
+}
+/**
+ * Run every check. Returns a process exit code: 0 when the agent can
+ * authenticate as at least one profile, 1 otherwise.
+ */
+export declare function runDoctor(options?: DoctorOptions): Promise<number>;

package/dist/doctor.js

@@ -0,0 +1,120 @@
+/**
+ * `taskflow-mcp --check` — verify the whole agent chain from a terminal.
+ *
+ * The MCP tools can only be called by a model through an MCP client, so there is
+ * otherwise no way for a human to answer "is this thing actually wired up?"
+ * without hand-rolling curl. This walks the same path the server does — find the
+ * config, resolve each profile, authenticate against the backend — and reports
+ * where it breaks, with the fix.
+ *
+ * Writes to stdout (this mode is not the MCP transport) and exits non-zero on
+ * failure so it can gate a script.
+ */
+import { TaskflowClient, TaskflowApiError } from "./client.js";
+import { findConfigPath, loadConfigFile, resolveProfile, } from "./config.js";
+const PASS = "PASS";
+const FAIL = "FAIL";
+/**
+ * Run every check. Returns a process exit code: 0 when the agent can
+ * authenticate as at least one profile, 1 otherwise.
+ */
+export async function runDoctor(options = {}) {
+    const log = options.log ?? ((line) => process.stdout.write(`${line}\n`));
+    // 1. Locate the credential file.
+    let configPath;
+    try {
+        configPath = findConfigPath({
+            configPath: options.configPath,
+            startDir: options.startDir,
+            env: options.env,
+        });
+    }
+    catch (err) {
+        log(`${FAIL}  .taskflow.json not found`);
+        log(`      ${err.message}`);
+        log("");
+        log("      Fix: link an agent on the dashboard's API Base page, then save the");
+        log("      snippet as .taskflow.json in your repo root.");
+        return 1;
+    }
+    log(`${PASS}  config found — ${configPath}`);
+    // 2. Parse + validate it.
+    let config;
+    try {
+        config = loadConfigFile(configPath);
+    }
+    catch (err) {
+        log(`${FAIL}  config is not valid`);
+        log(`      ${err.message}`);
+        return 1;
+    }
+    const profileNames = Object.keys(config.profiles);
+    log(`${PASS}  config valid — server ${config.server}, project ${config.project}`);
+    log(`      profiles: ${profileNames.join(", ")} (default: ${config.default_profile ?? "main"})`);
+    // A frontend origin here is the classic misconfiguration: the dev server
+    // proxies /api to the backend, so it appears to work until the frontend is
+    // stopped, at which point the agent dies for no obvious reason.
+    if (/:(517[0-9]|300[0-9]|808[0-9])$/.test(config.server) && !/:8000$/.test(config.server)) {
+        log(`      note: ${config.server} looks like a frontend dev server. It must be the`);
+        log("      BACKEND origin — an agent runs headless and must not depend on the UI.");
+    }
+    // 3. Authenticate each profile against the live backend. Readiness hinges on
+    // the DEFAULT profile — that is the one tools use when no profile is named, so
+    // a working "reviewer" next to a broken "main" is not a ready setup.
+    const defaultName = config.default_profile ?? "main";
+    const failed = [];
+    let defaultOk = false;
+    for (const name of profileNames) {
+        let resolved;
+        try {
+            resolved = resolveProfile(config, { profile: name, env: options.env, configPath });
+        }
+        catch (err) {
+            log(`${FAIL}  profile "${name}" — ${err.message}`);
+            failed.push(name);
+            continue;
+        }
+        const client = new TaskflowClient({ server: resolved.server, key: resolved.key });
+        try {
+            const who = await client.whoami();
+            if (name === defaultName)
+                defaultOk = true;
+            log(`${PASS}  profile "${name}" authenticated — agent #${who.agent_id} ` +
+                `"${who.display_name}", project ${who.project}, status ${who.status}`);
+        }
+        catch (err) {
+            log(`${FAIL}  profile "${name}" could not authenticate`);
+            failed.push(name);
+            const message = err.message;
+            log(`      ${message}`);
+            // The client wraps a network failure as a TaskflowApiError with status 0,
+            // so "could not connect" must be matched on the message, not by falling
+            // through to a non-API error branch — there isn't one.
+            const status = err instanceof TaskflowApiError ? err.status : -1;
+            if (status === 401 || status === 403) {
+                log("      The key is wrong, revoked, or belongs to another project.");
+                log("      Fix: re-link the agent on the API Base page for a fresh key.");
+            }
+            else if (status === 0 || /ECONNREFUSED|fetch failed|ENOTFOUND|network/i.test(message)) {
+                log(`      Nothing is listening at ${resolved.server}.`);
+                log('      Fix: start the backend, or correct the "server" field.');
+            }
+        }
+    }
+    log("");
+    if (defaultOk && failed.length === 0) {
+        log("Ready. The agent can authenticate — MCP tools will work in Claude Code.");
+    }
+    else if (defaultOk) {
+        log(`Mostly ready. The default profile "${defaultName}" works, so tools will run, ` +
+            `but ${failed.length === 1 ? "profile" : "profiles"} ${failed
+                .map((f) => `"${f}"`)
+                .join(", ")} failed and cannot be used.`);
+    }
+    else {
+        log(`Not ready. The default profile "${defaultName}" could not authenticate; ` +
+            "see the failures above.");
+    }
+    return defaultOk ? 0 : 1;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAEL,cAAc,EACd,cAAc,EACd,cAAc,GAEf,MAAM,aAAa,CAAC;AAErB,MAAM,IAAI,GAAG,MAAM,CAAC;AACpB,MAAM,IAAI,GAAG,MAAM,CAAC;AAUpB;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,UAAyB,EAAE;IACzD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC;IAEjF,iCAAiC;IACjC,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,cAAc,CAAC;YAC1B,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,GAAG,EAAE,OAAO,CAAC,GAAG;SACjB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,GAAG,IAAI,4BAA4B,CAAC,CAAC;QACzC,GAAG,CAAC,SAAU,GAAmB,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7C,GAAG,CAAC,EAAE,CAAC,CAAC;QACR,GAAG,CAAC,0EAA0E,CAAC,CAAC;QAChF,GAAG,CAAC,oDAAoD,CAAC,CAAC;QAC1D,OAAO,CAAC,CAAC;IACX,CAAC;IACD,GAAG,CAAC,GAAG,IAAI,oBAAoB,UAAU,EAAE,CAAC,CAAC;IAE7C,0BAA0B;IAC1B,IAAI,MAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,GAAG,IAAI,uBAAuB,CAAC,CAAC;QACpC,GAAG,CAAC,SAAU,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACvC,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAClD,GAAG,CAAC,GAAG,IAAI,2BAA2B,MAAM,CAAC,MAAM,aAAa,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IAClF,GAAG,CACD,mBAAmB,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,cACxC,MAAM,CAAC,eAAe,IAAI,MAC5B,GAAG,CACJ,CAAC;IAEF,yEAAyE;IACzE,2EAA2E;IAC3E,gEAAgE;IAChE,IAAI,gCAAgC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1F,GAAG,CACD,eAAe,MAAM,CAAC,MAAM,mDAAmD,CAChF,CAAC;QACF,GAAG,CAAC,8EAA8E,CAAC,CAAC;IACtF,CAAC;IAED,6EAA6E;IAC7E,+EAA+E;IAC/E,qEAAqE;IACrE,MAAM,WAAW,GAAG,MAAM,CAAC,eAAe,IAAI,MAAM,CAAC;IACrD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,IAAI,QAAQ,CAAC;QACb,IAAI,CAAC;YACH,QAAQ,GAAG,cAAc,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,UAAU,EAAE,CAAC,CAAC;QACrF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,GAAG,IAAI,cAAc,IAAI,OAAQ,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;YAC9D,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClB,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;QAClF,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;YAClC,IAAI,IAAI,KAAK,WAAW;gBAAE,SAAS,GAAG,IAAI,CAAC;YAC3C,GAAG,CACD,GAAG,IAAI,cAAc,IAAI,4BAA4B,GAAG,CAAC,QAAQ,GAAG;gBAClE,IAAI,GAAG,CAAC,YAAY,cAAc,GAAG,CAAC,OAAO,YAAY,GAAG,CAAC,MAAM,EAAE,CACxE,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,GAAG,IAAI,cAAc,IAAI,0BAA0B,CAAC,CAAC;YACzD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClB,MAAM,OAAO,GAAI,GAAa,CAAC,OAAO,CAAC;YACvC,GAAG,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;YAExB,0EAA0E;YAC1E,wEAAwE;YACxE,uDAAuD;YACvD,MAAM,MAAM,GAAG,GAAG,YAAY,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACjE,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;gBACrC,GAAG,CAAC,iEAAiE,CAAC,CAAC;gBACvE,GAAG,CAAC,oEAAoE,CAAC,CAAC;YAC5E,CAAC;iBAAM,IAAI,MAAM,KAAK,CAAC,IAAI,8CAA8C,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;gBACxF,GAAG,CAAC,iCAAiC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;gBACzD,GAAG,CAAC,8DAA8D,CAAC,CAAC;YACtE,CAAC;QACH,CAAC;IACH,CAAC;IAED,GAAG,CAAC,EAAE,CAAC,CAAC;IACR,IAAI,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrC,GAAG,CAAC,yEAAyE,CAAC,CAAC;IACjF,CAAC;SAAM,IAAI,SAAS,EAAE,CAAC;QACrB,GAAG,CACD,sCAAsC,WAAW,8BAA8B;YAC7E,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,IAAI,MAAM;iBAC1D,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;iBACpB,IAAI,CAAC,IAAI,CAAC,6BAA6B,CAC7C,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,GAAG,CACD,mCAAmC,WAAW,4BAA4B;YACxE,yBAAyB,CAC5B,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3B,CAAC"}

package/dist/events.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Listen to the agent's server-sent event stream so messages reach the terminal
+ * the instant they are sent.
+ *
+ * This is v1's tmux-bridge idea (`task_flow/mcp-server/src/tmux-bridge.ts`):
+ * hold a stream open for the life of the session and inject on arrival, instead
+ * of polling. Polling made delivery as slow as the interval and cost a request
+ * per tick even in silence.
+ *
+ * It cannot use `EventSource`: agents authenticate with `Authorization: Agent
+ * <key>`, and EventSource cannot set headers. Node's fetch can, so the SSE frame
+ * parsing is done here — it is a small, well-specified format.
+ */
+import { TaskflowClient } from "./client.js";
+export interface AgentMessageEvent {
+    id: number;
+    channel: number;
+    sender_kind: string;
+    sender_label: string;
+    body_markdown: string;
+    sender_agent: number | null;
+    /** Context ids carried on the resolved read row (absent on the id-only wire
+     *  event). Surfaced in the pane notice so the agent can query/act on the
+     *  right project/task/person without a round trip — see `formatIncoming`. */
+    project?: number | null;
+    task?: number | null;
+    sender_user?: number | null;
+    /** #29: a directed group message names the one agent whose pane should get it;
+     *  null broadcasts to every agent on the channel (the default). Kept for
+     *  back-compat with rows written before `targets`; `targets` is authoritative
+     *  when present. */
+    target_agent?: number | null;
+    /** #29: the full directed-target set — agents (pane delivery) and users
+     *  (mention only). Empty/absent broadcasts to every agent, like a null
+     *  `target_agent`. Supersedes `target_agent` when present. */
+    targets?: MessageTarget[] | null;
+}
+/** #29: one directed target of a message. `kind` is "agent" or "user"; only
+ *  agent targets gate pane delivery (users are mention/attribution). */
+export interface MessageTarget {
+    kind: string;
+    id: number;
+}
+/** A terminal key the dashboard sent, projected on the realtime event. `agent`
+ *  is the target pane's agent; `keys` is one tmux key name. */
+export interface TerminalKeyEvent {
+    agent: number;
+    keys: string;
+}
+export interface EventStreamOptions {
+    server: string;
+    key: string;
+    /** Called for each message created — or edited (#107) — in this agent's
+     *  project. `action` says which; absent means "created" (older callers). */
+    onMessage: (message: AgentMessageEvent, action?: "created" | "updated") => void | Promise<void>;
+    /** Called when a human answers a question this agent is blocked on. */
+    onPromptAnswered?: (prompt: PromptEvent) => void | Promise<void>;
+    /** Called when a human sends a terminal key from the dashboard. Broadcast to
+     *  the whole project, so `agent` says which pane it is for — the handler must
+     *  ignore keys addressed to other agents. */
+    onTerminalKey?: (input: TerminalKeyEvent) => void | Promise<void>;
+    /** Called each time the stream RE-connects (not the first connect). The live
+     *  push is at-most-once, so the handler catches up on messages that arrived
+     *  while the stream was down. */
+    onReconnect?: () => void | Promise<void>;
+    log?: (line: string) => void;
+    /** Injected in tests. */
+    fetchImpl?: typeof fetch;
+}
+export interface EventStreamHandle {
+    stop: () => void;
+    /**
+     * Drop the current connection and reconnect now.
+     *
+     * The idle watchdog is a backstop measured in tens of seconds; when something
+     * else in this process has just proven the backend is unreachable (a failed
+     * heartbeat, say), there is no reason to wait for it.
+     */
+    reconnectNow: () => void;
+}
+/**
+ * Hold the stream open, reconnecting with backoff.
+ *
+ * Never rejects: a stream that cannot connect retries quietly forever, because
+ * the agent must keep working whether or not the dashboard is reachable.
+ */
+export declare function startAgentEventStream(options: EventStreamOptions): EventStreamHandle;
+/** Pull the `data:` lines out of one SSE frame and dispatch a message event. */
+export declare function handleFrame(frame: string, options: Pick<EventStreamOptions, "onMessage" | "onPromptAnswered" | "onTerminalKey">): void;
+/**
+ * Whether a message should be delivered to THIS agent's terminal.
+ *
+ * Every message the agent can see is delivered EXCEPT its own — an agent must
+ * stay aware of all channel traffic so it can chat / add information (#40 review).
+ * Whether it may ACT on the message is a SEPARATE signal (`canActOnMessage`)
+ * surfaced as guidance in the notice, NOT a delivery gate. Its own messages are
+ * still skipped: echoing them back reads as a new instruction and could loop the
+ * agent against itself.
+ */
+export declare function shouldDeliver(message: AgentMessageEvent, selfAgentId: number): boolean;
+/**
+ * Whether THIS agent is a TARGET of the message and may act on it — build,
+ * execute, take ownership. A non-target still RECEIVES the message (to reply or
+ * add information) but must not act; `formatIncoming` says so.
+ *
+ * - An empty/absent target set is a broadcast: everyone may act.
+ * - Otherwise the agent may act only if it is one of the AGENT targets. A
+ *   message tagged only at users leaves every agent a non-target.
+ */
+export declare function canActOnMessage(message: AgentMessageEvent, selfAgentId: number): boolean;
+/** Format a delivered message the way v1 did: who it is from, then the text. */
+/** The attachment fields a notice needs. Matches the agent read projection. */
+export interface NoticeAttachment {
+    name: string;
+    size_bytes: number;
+    url: string;
+}
+export declare function formatIncoming(message: AgentMessageEvent, attachments?: NoticeAttachment[], selfAgentId?: number, edited?: boolean): string;
+export type { TaskflowClient };
+/**
+ * The keystrokes that answer a prompt, as verified against a live Claude Code
+ * session — not inferred from the UI's appearance.
+ *
+ * SINGLE-select: the number HIGHLIGHTS the option; Enter submits it.
+ *     press "2"      -> option 2 highlighted, still waiting
+ *     press Enter    -> "You selected: Green"
+ *
+ * This one was wrong here until 2026-07-21. The comment claimed the number both
+ * selected and submitted, so the agent was left sitting on a prompt the
+ * dashboard already showed as answered — the worst shape of failure, because
+ * the human sees a completed action and the agent sees nothing.
+ *
+ * MULTI-select: numbers TOGGLE checkboxes, then Right opens the review screen
+ * ("Ready to submit your answers?" — 1. Submit / 2. Cancel). This function only
+ * REACHES that screen; the submit key is appended once by keystrokesForPrompt,
+ * because a multi-question set lands on the identical screen. Verified live
+ * 2026-07-21: a single multi-select question sat on that review screen because
+ * nothing pressed the final key.
+ *     press "1" -> [✔] Lint
+ *     press "3" -> [✔] Tests
+ *     press Right -> review screen (submit handled by the caller)
+ *
+ * Getting this wrong is not a cosmetic bug: sending a single digit to a
+ * multi-select ticks one box and leaves the agent still waiting, and sending
+ * Enter instead of Right submits an empty answer.
+ */
+export declare function answerKeystrokes(choices: number[], kind: string): string[];
+export interface PromptEvent {
+    id: number;
+    session: number;
+    question: string;
+    kind: string;
+    status: string;
+    answer: number | null;
+    answer_json: string | null;
+    /** Set when a HUMAN answered or cancelled it; null when the agent cleared it. */
+    answered_by?: number | null;
+    /**
+     * The options, as the hook wrote them. Carried on the realtime projection
+     * (`PROMPT_FIELDS` in backend/src/realtime.rs) because a multi-question prompt
+     * cannot be turned into keystrokes without knowing each question's kind — a
+     * set can mix single and multi.
+     */
+    options_json?: string;
+    /**
+     * Free-text "Other" answers as JSON, one entry per question (`null` where the
+     * question has no Other pick). Carried on the realtime projection so the MCP
+     * can type the value into the terminal's "Type something" field.
+     */
+    answer_text_json?: string | null;
+}
+/** The numbers a human chose, from whichever field carries them. */
+export declare function chosenNumbers(prompt: PromptEvent): number[];
+/**
+ * Whether this event is a human decision this agent should act on.
+ *
+ * `answered` and `cancelled` are BOTH actionable: cancel is the other button on
+ * the review screen, and reaching it means replaying every answer first, so it
+ * is just as much a keystroke sequence as submit.
+ *
+ * `answered_by` is what separates a human cancel from the agent clearing its own
+ * prompt — it times out, or someone answers in the terminal directly, and the
+ * row is marked cancelled with nobody attributed. Firing keys for that would
+ * type digits at a screen the agent has already left.
+ */
+export declare function isAnsweredPrompt(row: unknown): row is PromptEvent;