@dalmasonto/taskflow-mcp 1.0.33 → 2.0.0

package/dist/mint.js

@@ -0,0 +1,135 @@
+/**
+ * `taskflow-mcp --mint <name>` — create a NEW agent identity and record it as
+ * a profile in `.taskflow.json`.
+ *
+ * ## Why this is a CLI and not an MCP tool
+ *
+ * `POST /api/taskflow/agents/link` is gated on `RequireAuth` plus an active
+ * project membership, and it stamps the linking human onto the agent. An agent
+ * authenticates with `Authorization: Agent <key>` and would simply be refused.
+ *
+ * That gate is correct and this command deliberately does not work around it:
+ * an agent able to mint sibling agents could grow an unbounded roster that no
+ * human vouched for. Creating an identity is a human act, so a human runs this.
+ *
+ * ## What it is for
+ *
+ * Identity is `project + profile`. Two terminals sharing the `main` profile are
+ * ONE agent — same roster entry, and, more importantly, one shared DM inbox and
+ * one shared read cursor. Giving the second terminal its own profile is what
+ * makes them distinguishable.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { findConfigPath, taskflowConfigSchema } from "./config.js";
+/** A clear, user-facing failure (never a raw stack). */
+export class MintError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MintError";
+    }
+}
+/**
+ * Parse `--mint <name> [--display-name <s>] [--token <t>]`.
+ *
+ * The token falls back to `TASKFLOW_USER_TOKEN`, but an explicit `--token`
+ * wins — a one-off mint against another account must not silently pick up
+ * whatever is exported in the shell.
+ */
+export function parseMintArgs(argv, env = process.env) {
+    const valueFor = (flag) => {
+        const i = argv.indexOf(flag);
+        if (i === -1)
+            return undefined;
+        const next = argv[i + 1];
+        // A flag consuming the next flag as its value is how `--mint --token t`
+        // would otherwise mint a profile literally named "--token".
+        return next && !next.startsWith("--") ? next : undefined;
+    };
+    const name = valueFor("--mint");
+    if (!name) {
+        throw new MintError("--mint needs a profile name, e.g. `--mint bear`.");
+    }
+    return {
+        name,
+        displayName: valueFor("--display-name") ?? `Claude (${name})`,
+        token: valueFor("--token") ?? env.TASKFLOW_USER_TOKEN,
+    };
+}
+/**
+ * Return a copy of `config` with `profile` recorded under `name`.
+ *
+ * Pure, and deliberately non-destructive in three ways:
+ * - an existing profile is never overwritten (its key is unrecoverable, and it
+ *   is what a running terminal authenticates with)
+ * - `default_profile` never moves, so existing terminals keep their identity
+ * - every other field is carried through untouched
+ */
+export function addProfile(config, name, profile) {
+    const key = name.trim();
+    if (!key) {
+        throw new MintError("A profile name must not be blank.");
+    }
+    if (config.profiles[key]) {
+        throw new MintError(`Profile "${key}" already exists in .taskflow.json. ` +
+            `Pick another name — overwriting it would discard a key that cannot be recovered.`);
+    }
+    return { ...config, profiles: { ...config.profiles, [key]: profile } };
+}
+/** The line the operator runs to start the other terminal as the new identity. */
+export function exportHint(name) {
+    return `export TASKFLOW_PROFILE=${name}`;
+}
+/** Mint against the server and return the profile block it hands back. */
+export async function requestMint(server, project, args, token, doFetch = fetch) {
+    const res = await doFetch(`${server.replace(/\/$/, "")}/api/taskflow/agents/link`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ project, display_name: args.displayName, profile: args.name }),
+    });
+    if (res.status === 401) {
+        throw new MintError("The server rejected that token (401). It must be a USER token, not an agent key.");
+    }
+    if (res.status === 403) {
+        throw new MintError(`That account is not an active member of project ${project} (403).`);
+    }
+    if (!res.ok) {
+        throw new MintError(`Mint failed: ${res.status} ${res.statusText}`);
+    }
+    const body = (await res.json());
+    // The raw key exists in this response and nowhere else — the server stores
+    // only a hash. A malformed body here means the key is already lost, so say so
+    // rather than writing a profile that cannot authenticate.
+    if (!body.taskflow_profile?.key) {
+        throw new MintError("The server's response carried no key; the minted agent is unusable. Nothing was written.");
+    }
+    return body.taskflow_profile;
+}
+/**
+ * Run the command. Returns the lines to print.
+ *
+ * The write is last: a failed mint must not leave a half-edited config, and a
+ * successful mint must not lose its key to a formatting error.
+ */
+export async function runMint(argv, env = process.env) {
+    const args = parseMintArgs(argv, env);
+    if (!args.token) {
+        throw new MintError("No user token. Pass --token <t> or set TASKFLOW_USER_TOKEN.\n" +
+            "Minting an agent is a human action, so this needs YOUR login token, not an agent key.");
+    }
+    const configPath = findConfigPath({ env });
+    const config = taskflowConfigSchema.parse(JSON.parse(readFileSync(configPath, "utf8")));
+    // Fail on a duplicate name BEFORE minting, so a mistyped command cannot leave
+    // an orphan agent on the server that nothing references.
+    addProfile(config, args.name, { agent_id: 0, key: "probe" });
+    const profile = await requestMint(config.server, config.project, args, args.token);
+    const next = addProfile(config, args.name, profile);
+    writeFileSync(configPath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    return [
+        `minted agent ${profile.agent_id} — ${profile.display_name ?? args.displayName}`,
+        `wrote profile "${args.name}" to ${configPath}`,
+        "",
+        "run the other terminal with:",
+        `  ${exportHint(args.name)}`,
+    ];
+}
+//# sourceMappingURL=mint.js.map

package/dist/mint.js.map

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

package/dist/mirror.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Mirror lifecycle: start the terminal mirror, keep trying if the backend is not
+ * ready yet, and remember what happened so a human can ask.
+ *
+ * This module exists because of a real failure. The mirror's *running* loop is
+ * carefully resilient — `startMirrorLoop` swallows transient errors and
+ * reconnects the event stream — but its *startup* had no such protection. Setup
+ * calls `registerSession`, so a backend that was still booting when the MCP
+ * spawned threw once, was caught, logged to stderr, and mirroring was dead for
+ * the entire life of the process. The dashboard then showed a stale terminal
+ * with nothing anywhere saying why.
+ *
+ * Restarting the backend and reconnecting the MCP together is the normal way to
+ * pick up a change, which is exactly when the race is most likely.
+ */
+export type MirrorState = 
+/** Not attempted yet. */
+"starting"
+/** Deliberately not mirroring — no tmux pane to mirror. Not an error. */
+ | "off"
+/** Streaming. */
+ | "active"
+/** Gave up after exhausting retries; `detail` carries the last reason. */
+ | "failed";
+export interface MirrorStatus {
+    state: MirrorState;
+    /** Why, in the caller's words — always set for `off` and `failed`. */
+    detail?: string;
+    /** The tmux pane being mirrored, once known. */
+    pane?: string;
+    /** How many start attempts have been made. */
+    attempts: number;
+}
+/** The current mirror status, for `whoami` to report. */
+export declare function getMirrorStatus(): MirrorStatus;
+/**
+ * Publish the mirror's state from whoever is driving it — since Task 5 that is
+ * `runtime.ts`, not `startMirrorWithRetry`.
+ *
+ * Without this, every writer of `status` lived inside `startMirrorWithRetry`,
+ * which the startup path no longer calls: `whoami` reported a streaming mirror
+ * as `{state: "starting"}` forever, inverting the very problem this field
+ * exists to solve.
+ */
+export declare function reportMirror(next: MirrorStatus): void;
+/** Test seam — reset the module-level status between cases. */
+export declare function resetMirrorStatus(): void;
+export interface StartMirrorOptions {
+    /** Resolve the pane to mirror, or null when not running under tmux. */
+    detectPane: () => Promise<string | null>;
+    /** Do the actual setup (register, stream, loop). Throws if it cannot. */
+    start: (pane: string) => Promise<void>;
+    maxAttempts?: number;
+    baseMs?: number;
+    maxMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    log?: (line: string) => void;
+}
+/**
+ * Start the mirror, retrying with backoff until it takes or the attempts run
+ * out. Never throws: a mirror is a nice-to-have and must not be able to take
+ * the tool server down with it.
+ *
+ * No pane means no tmux, which is a permanent and legitimate condition — that
+ * returns immediately rather than retrying, so a non-tmux agent does not spend
+ * eight backoff rounds discovering the same thing.
+ */
+export declare function startMirrorWithRetry(options: StartMirrorOptions): Promise<void>;

package/dist/mirror.js

@@ -0,0 +1,103 @@
+/**
+ * Mirror lifecycle: start the terminal mirror, keep trying if the backend is not
+ * ready yet, and remember what happened so a human can ask.
+ *
+ * This module exists because of a real failure. The mirror's *running* loop is
+ * carefully resilient — `startMirrorLoop` swallows transient errors and
+ * reconnects the event stream — but its *startup* had no such protection. Setup
+ * calls `registerSession`, so a backend that was still booting when the MCP
+ * spawned threw once, was caught, logged to stderr, and mirroring was dead for
+ * the entire life of the process. The dashboard then showed a stale terminal
+ * with nothing anywhere saying why.
+ *
+ * Restarting the backend and reconnecting the MCP together is the normal way to
+ * pick up a change, which is exactly when the race is most likely.
+ */
+/** Backoff between startup attempts. Mirrors `events.ts`'s reconnect policy. */
+const START_BASE_MS = 1_000;
+const START_MAX_MS = 30_000;
+const START_MAX_ATTEMPTS = 8;
+let status = { state: "starting", attempts: 0 };
+/** The current mirror status, for `whoami` to report. */
+export function getMirrorStatus() {
+    return { ...status };
+}
+/**
+ * Publish the mirror's state from whoever is driving it — since Task 5 that is
+ * `runtime.ts`, not `startMirrorWithRetry`.
+ *
+ * Without this, every writer of `status` lived inside `startMirrorWithRetry`,
+ * which the startup path no longer calls: `whoami` reported a streaming mirror
+ * as `{state: "starting"}` forever, inverting the very problem this field
+ * exists to solve.
+ */
+export function reportMirror(next) {
+    status = next;
+}
+/** Test seam — reset the module-level status between cases. */
+export function resetMirrorStatus() {
+    status = { state: "starting", attempts: 0 };
+}
+const wait = (ms) => new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    // Never hold the process open for a retry.
+    t.unref?.();
+});
+/**
+ * Start the mirror, retrying with backoff until it takes or the attempts run
+ * out. Never throws: a mirror is a nice-to-have and must not be able to take
+ * the tool server down with it.
+ *
+ * No pane means no tmux, which is a permanent and legitimate condition — that
+ * returns immediately rather than retrying, so a non-tmux agent does not spend
+ * eight backoff rounds discovering the same thing.
+ */
+export async function startMirrorWithRetry(options) {
+    const { detectPane, start, maxAttempts = START_MAX_ATTEMPTS, baseMs = START_BASE_MS, maxMs = START_MAX_MS, sleep = wait, log, } = options;
+    let pane;
+    try {
+        pane = await detectPane();
+    }
+    catch (err) {
+        status = {
+            state: "failed",
+            detail: err.message,
+            attempts: 0,
+        };
+        log?.(`terminal mirror unavailable (${err.message})`);
+        return;
+    }
+    if (!pane) {
+        status = {
+            state: "off",
+            detail: "not running inside tmux — nothing to mirror",
+            attempts: 0,
+        };
+        return;
+    }
+    let lastError = "";
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+            await start(pane);
+            status = { state: "active", pane, attempts: attempt };
+            if (attempt > 1)
+                log?.(`terminal mirror started after ${attempt} attempts`);
+            return;
+        }
+        catch (err) {
+            lastError = err.message.split("\n")[0] ?? String(err);
+            status = { state: "starting", pane, attempts: attempt, detail: lastError };
+            if (attempt === maxAttempts)
+                break;
+            // Same shape as the event stream's reconnect: grow, cap, and jitter so a
+            // backend coming back up is not hit by every client at once.
+            const ceiling = Math.min(baseMs * 2 ** (attempt - 1), maxMs);
+            const delay = Math.round(ceiling / 2 + Math.random() * (ceiling / 2));
+            log?.(`terminal mirror not up yet (${lastError}) — retrying in ${delay}ms`);
+            await sleep(delay);
+        }
+    }
+    status = { state: "failed", pane, detail: lastError, attempts: maxAttempts };
+    log?.(`terminal mirror gave up after ${maxAttempts} attempts (${lastError})`);
+}
+//# sourceMappingURL=mirror.js.map

package/dist/mirror.js.map

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

package/dist/pane-queue.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A serial queue for pane writes.
+ *
+ * ## Why this exists
+ *
+ * Every write to the agent's tmux pane — delivering a message, replaying a
+ * prompt answer, sending a terminal key — is a MULTI-STEP tmux sequence
+ * (`send-keys -l <text>` then `send-keys Enter`, or a paced run of keys). The
+ * event stream dispatches handlers fire-and-forget (`void onMessage(...)`), so
+ * two writes that land close together used to interleave: `typeA, typeB,
+ * EnterA, EnterB` — and the first Enter submits BOTH texts as one line while the
+ * second submits nothing. That is the "a message meant for someone else was
+ * typed into my pane and the next message's Enter submitted it" race.
+ *
+ * Routing every pane write through one serial queue makes each sequence
+ * atomic with respect to the others: a write runs to completion before the next
+ * begins, so type/Enter pairs can never cross.
+ */
+/** Runs enqueued tasks one at a time, in call order. */
+export interface SerialQueue {
+    /** Enqueue a task; resolves/rejects with the task's own result. */
+    (task: () => Promise<void>): Promise<void>;
+}
+/**
+ * Create a serial queue. Each task waits for the previous one to settle (success
+ * OR failure) before it starts, so a single failing write never wedges or
+ * reorders the queue. The caller still sees its own task's rejection.
+ */
+export declare function createSerialQueue(): SerialQueue;

package/dist/pane-queue.js

@@ -0,0 +1,35 @@
+/**
+ * A serial queue for pane writes.
+ *
+ * ## Why this exists
+ *
+ * Every write to the agent's tmux pane — delivering a message, replaying a
+ * prompt answer, sending a terminal key — is a MULTI-STEP tmux sequence
+ * (`send-keys -l <text>` then `send-keys Enter`, or a paced run of keys). The
+ * event stream dispatches handlers fire-and-forget (`void onMessage(...)`), so
+ * two writes that land close together used to interleave: `typeA, typeB,
+ * EnterA, EnterB` — and the first Enter submits BOTH texts as one line while the
+ * second submits nothing. That is the "a message meant for someone else was
+ * typed into my pane and the next message's Enter submitted it" race.
+ *
+ * Routing every pane write through one serial queue makes each sequence
+ * atomic with respect to the others: a write runs to completion before the next
+ * begins, so type/Enter pairs can never cross.
+ */
+/**
+ * Create a serial queue. Each task waits for the previous one to settle (success
+ * OR failure) before it starts, so a single failing write never wedges or
+ * reorders the queue. The caller still sees its own task's rejection.
+ */
+export function createSerialQueue() {
+    // The tail is a promise that settles when the last-enqueued task is done. It
+    // is kept deliberately error-swallowed so one rejection cannot break the chain
+    // for everything queued after it.
+    let tail = Promise.resolve();
+    return (task) => {
+        const run = tail.then(task, task);
+        tail = run.then(() => { }, () => { });
+        return run;
+    };
+}
+//# sourceMappingURL=pane-queue.js.map

package/dist/pane-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pane-queue.js","sourceRoot":"","sources":["../src/pane-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAQH;;;;GAIG;AACH,MAAM,UAAU,iBAAiB;IAC/B,6EAA6E;IAC7E,+EAA+E;IAC/E,kCAAkC;IAClC,IAAI,IAAI,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5C,OAAO,CAAC,IAAI,EAAE,EAAE;QACd,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAClC,IAAI,GAAG,GAAG,CAAC,IAAI,CACb,GAAG,EAAE,GAAE,CAAC,EACR,GAAG,EAAE,GAAE,CAAC,CACT,CAAC;QACF,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;AACJ,CAAC"}

package/dist/prompts.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Reading a dashboard-answered prompt back into keystrokes.
+ *
+ * `AskUserQuestion` accepts SEVERAL questions in one call. The agent's terminal
+ * presents them one at a time — question 2's screen only exists once question 1
+ * is answered — so a whole set is stored as ONE prompt row and replayed in order
+ * only when every question has an answer. Replaying half a set would send the
+ * remaining digits at whatever screen the agent had moved on to.
+ *
+ * Two on-the-wire shapes are supported, because rows written before
+ * multi-question support are still in the table:
+ *
+ *   legacy  options_json = [{number, label}, ...]        one question
+ *           answer_json  = [1, 3]                        one flat set
+ *
+ *   set     options_json = [{question, kind, options}]   N questions
+ *           answer_json  = [[1], [2, 3]]                 one set per question
+ *
+ * A prompt that cannot be read yields NO keystrokes. An agent left waiting is
+ * recoverable; digits fired into the wrong screen are not.
+ */
+export interface PromptOption {
+    number: number;
+    label: string;
+    description?: string;
+    isOther?: boolean;
+}
+export type KeyStep = {
+    key: string;
+} | {
+    text: string;
+};
+export interface PromptQuestion {
+    question: string;
+    kind: string;
+    options: PromptOption[];
+}
+/**
+ * The questions a prompt is asking.
+ *
+ * `fallbackKind` and `fallbackQuestion` come from the row's own columns and are
+ * used only for the legacy shape, which stored the question text and kind there
+ * rather than inside the JSON.
+ */
+export declare function parseQuestions(optionsJson: string, fallbackKind: string, fallbackQuestion: string): PromptQuestion[];
+/**
+ * The chosen numbers, one set per question.
+ *
+ * `answer` is the row's single-answer column, kept as a fallback for rows
+ * answered before `answer_json` existed.
+ */
+export declare function parseAnswerSets(answerJson: string | null, answer: number | null): number[][];
+/** Whether every question in the set has at least one choice. */
+export declare function isFullyAnswered(sets: number[][], questionCount: number): boolean;
+/** What the human chose to do with an answered prompt. */
+export type PromptIntent = "submit" | "cancel";
+/**
+ * The full keystroke sequence for an answered prompt, or `[]` when it must not
+ * be replayed.
+ *
+ * Each question contributes its own sequence and they run back to back, in the
+ * order the questions were asked — the terminal advances to the next question as
+ * each is submitted. A set then confirms at the review screen.
+ *
+ * A single SINGLE-select question has no review screen (it submits as soon as it
+ * is answered), so nothing is appended and there is no safe "cancel" key. A
+ * single MULTI-select question DOES reach the review screen, so it gets the
+ * submit/cancel like a set does.
+ */
+export declare function keystrokesForPrompt(optionsJson: string, kind: string, question: string, answerJson: string | null, answer: number | null, intent?: PromptIntent): string[];
+/** The Other free-text value per question, parallel to the answer sets. */
+export declare function parseAnswerTexts(answerTextJson: string | null, count: number): (string | null)[];
+/**
+ * The full ordered steps for an answered prompt. Without any Other text this is
+ * `keystrokesForPrompt` wrapped as `{key}` steps. With Other text on a single
+ * multi-select question, it walks the arrow-based flow the new TUI uses (see the
+ * hypothesis in the test — verified live before this ships).
+ */
+export declare function stepsForPrompt(optionsJson: string, kind: string, question: string, answerJson: string | null, answer: number | null, answerTextJson: string | null, intent?: PromptIntent): KeyStep[];