@dalmasonto/taskflow-mcp 1.0.35 → 2.1.0

package/dist/config.d.ts

@@ -1,21 +1,140 @@
-export interface TaskFlowConfig {
-    port: number;
-    host: string;
-    databasePath: string;
-    logLevel: 'debug' | 'info' | 'warn' | 'error';
-    agentLivenessInterval: number;
-    maxPortAttempts: number;
-    relayUrl: string;
-    relayPushToken: string;
+/**
+ * Load and validate `.taskflow.json`, then resolve one profile into a flat,
+ * ready-to-use identity for the HTTP client.
+ *
+ * The file is the stable per-repo credential a human creates via the dashboard's
+ * **API Base** page:
+ *
+ * ```json
+ * { "server": "http://localhost:8000", "project": 1, "default_profile": "main",
+ *   "profiles": {
+ *     "main":     { "agent_id": 12, "key": "tfk_…", "display_name": "Builder" },
+ *     "reviewer": { "agent_id": 13, "key": "tfk_…", "display_name": "Reviewer" }
+ *   } }
+ * ```
+ *
+ * File resolution: an explicit path (or `TASKFLOW_CONFIG`) wins; otherwise we
+ * walk up from a start directory to the first `.taskflow.json`.
+ *
+ * Profile resolution (highest priority first):
+ *   1. an explicit `profile` argument (a per-tool-call override),
+ *   2. the `TASKFLOW_PROFILE` env var,
+ *   3. the file's `default_profile`,
+ *   4. the literal `"main"`.
+ *
+ * Every function that reads the environment or filesystem takes those as
+ * explicit, defaultable options so the whole module is unit-testable without
+ * touching real `process.env` or `process.cwd()`.
+ */
+import { z } from "zod";
+export declare const CONFIG_FILENAME = ".taskflow.json";
+export declare const DEFAULT_PROFILE_NAME = "main";
+/** One profile block as it appears in the file. */
+export declare const profileSchema: z.ZodObject<{
+    agent_id: z.ZodNumber;
+    key: z.ZodString;
+    display_name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** The whole `.taskflow.json` file. */
+export declare const taskflowConfigSchema: z.ZodObject<{
+    server: z.ZodString;
+    project: z.ZodNumber;
+    default_profile: z.ZodOptional<z.ZodString>;
+    profiles: z.ZodRecord<z.ZodString, z.ZodObject<{
+        agent_id: z.ZodNumber;
+        key: z.ZodString;
+        display_name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RawProfile = z.infer<typeof profileSchema>;
+export type TaskflowConfig = z.infer<typeof taskflowConfigSchema>;
+/** A profile flattened with its file-level context — everything the client needs. */
+export interface ResolvedProfile {
+    server: string;
+    project: number;
+    profileName: string;
+    agentId: number;
+    key: string;
+    displayName: string;
+    /** Absolute path the config was read from (empty when parsed from a string). */
+    configPath: string;
+}
+/** A clear, user-facing configuration error (never a raw stack). */
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export interface FindConfigOptions {
+    /** An explicit path to the file; skips the walk-up entirely. */
+    configPath?: string | undefined;
+    /** Where to start the upward walk (defaults to `process.cwd()`). */
+    startDir?: string | undefined;
+    /** Environment source (defaults to `process.env`). */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolve the absolute path of the `.taskflow.json` to use. Precedence:
+ * explicit `configPath` > `TASKFLOW_CONFIG` env > walk up from `startDir`.
+ * Throws {@link ConfigError} when nothing is found.
+ */
+export declare function findConfigPath(options?: FindConfigOptions): string;
+/** Validate an already-parsed object (or JSON text) into a {@link TaskflowConfig}. */
+export declare function parseConfig(input: string | unknown, sourceLabel?: string): TaskflowConfig;
+/** Read + validate the config file at an absolute path. */
+export declare function loadConfigFile(configPath: string): TaskflowConfig;
+export interface ResolveProfileOptions {
+    /** An explicit per-call profile override (highest precedence). */
+    profile?: string | undefined;
+    /** Environment source (defaults to `process.env`); reads `TASKFLOW_PROFILE`. */
+    env?: NodeJS.ProcessEnv;
+    /** Path the config came from, for error messages and the resolved result. */
+    configPath?: string;
+}
+/**
+ * Pick the effective profile name using the documented precedence:
+ * argument > `TASKFLOW_PROFILE` > `default_profile` > `"main"`.
+ */
+export declare function chooseProfileName(config: TaskflowConfig, options?: ResolveProfileOptions): string;
+/**
+ * Resolve `config` + options into a flat {@link ResolvedProfile}. Throws
+ * {@link ConfigError} if the chosen profile is not present in the file.
+ */
+export declare function resolveProfile(config: TaskflowConfig, options?: ResolveProfileOptions): ResolvedProfile;
+/** One selectable identity, as offered to the human choosing among them. */
+export interface ProfileChoice {
+    name: string;
+    display_name: string;
+    /** True for the file's `default_profile` — a hint, never a decision. */
+    recommended: boolean;
+    /** Filled in by the caller from live session data; omitted if unknown. */
+    in_use?: boolean;
+}
+export type ProfileResolution = {
+    kind: "resolved";
+    profile: ResolvedProfile;
+} | {
+    kind: "ambiguous";
+    profiles: ProfileChoice[];
+};
+export interface AskProfileOptions extends ResolveProfileOptions {
+    /** This terminal's remembered pick, if any (see `sessions-store.ts`). */
+    sticky?: string | undefined;
+}
+/**
+ * Resolve a profile, or report that a human has to choose.
+ *
+ * Ambiguous means: several profiles defined, and nothing said which one this
+ * terminal is. `default_profile` deliberately does NOT settle it — `--mint`
+ * adds profiles without moving it, so honouring it would mean the prompt never
+ * fires and two terminals silently share one identity, which is the bug.
+ *
+ * `resolveProfile` keeps its throwing contract for callers that already have a
+ * name (`--tmux --profile=x`, `--mint`, a per-tool `profile` argument).
+ */
+export declare function resolveProfileOrAsk(config: TaskflowConfig, options?: AskProfileOptions): ProfileResolution;
+export interface LoadProfileOptions extends FindConfigOptions, ResolveProfileOptions {
 }
-/** Keys that live in the config file (not SQLite) */
-export declare const SERVER_CONFIG_KEYS: Set<string>;
-export declare function getConfig(): TaskFlowConfig;
-/** Check if a setting key is a server-level config key */
-export declare function isServerConfigKey(key: string): boolean;
 /**
- * Update a single key in ~/.taskflow_config.json.
- * Re-reads the file first to avoid clobbering other keys.
- * Returns the updated config value.
+ * The one-call convenience the bin entry and hooks use: find the file, load +
+ * validate it, and resolve the chosen profile into a {@link ResolvedProfile}.
  */
-export declare function writeConfigKey(key: string, value: unknown): void;
+export declare function loadProfile(options?: LoadProfileOptions): ResolvedProfile;

package/dist/config.js

@@ -1,125 +1,206 @@
-import { readFileSync, writeFileSync, mkdirSync } from 'fs';
-import { resolve, dirname } from 'path';
-import { homedir } from 'os';
-/** Keys that live in the config file (not SQLite) */
-export const SERVER_CONFIG_KEYS = new Set([
-    'port',
-    'host',
-    'databasePath',
-    'logLevel',
-    'agentLivenessInterval',
-    'maxPortAttempts',
-    'relayUrl',
-    'relayPushToken',
-]);
-// ─── defaults ────────────────────────────────────────────────────────
-const DEFAULTS = {
-    port: 3456,
-    host: '127.0.0.1',
-    databasePath: '~/.taskflow/taskflow.db',
-    logLevel: 'info',
-    agentLivenessInterval: 30_000,
-    maxPortAttempts: 10,
-    relayUrl: '',
-    relayPushToken: '',
-};
-// ─── config file path ────────────────────────────────────────────────
-// Config lives alongside the database in ~/.taskflow/
-// Falls back to legacy ~/.taskflow_config.json for backward compat
-import { existsSync } from 'fs';
-const NEW_CONFIG_PATH = resolve(homedir(), '.taskflow', 'config.json');
-const LEGACY_CONFIG_PATH = resolve(homedir(), '.taskflow_config.json');
-const CONFIG_PATH = existsSync(NEW_CONFIG_PATH) ? NEW_CONFIG_PATH
-    : existsSync(LEGACY_CONFIG_PATH) ? LEGACY_CONFIG_PATH
-        : NEW_CONFIG_PATH; // default to new path for fresh installs
-// ─── loader ──────────────────────────────────────────────────────────
-function loadFromFile() {
-    try {
-        const raw = readFileSync(CONFIG_PATH, 'utf-8');
-        const parsed = JSON.parse(raw);
-        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-            console.error(`[config] Warning: ${CONFIG_PATH} is not a JSON object — using defaults`);
-            return {};
+/**
+ * Load and validate `.taskflow.json`, then resolve one profile into a flat,
+ * ready-to-use identity for the HTTP client.
+ *
+ * The file is the stable per-repo credential a human creates via the dashboard's
+ * **API Base** page:
+ *
+ * ```json
+ * { "server": "http://localhost:8000", "project": 1, "default_profile": "main",
+ *   "profiles": {
+ *     "main":     { "agent_id": 12, "key": "tfk_…", "display_name": "Builder" },
+ *     "reviewer": { "agent_id": 13, "key": "tfk_…", "display_name": "Reviewer" }
+ *   } }
+ * ```
+ *
+ * File resolution: an explicit path (or `TASKFLOW_CONFIG`) wins; otherwise we
+ * walk up from a start directory to the first `.taskflow.json`.
+ *
+ * Profile resolution (highest priority first):
+ *   1. an explicit `profile` argument (a per-tool-call override),
+ *   2. the `TASKFLOW_PROFILE` env var,
+ *   3. the file's `default_profile`,
+ *   4. the literal `"main"`.
+ *
+ * Every function that reads the environment or filesystem takes those as
+ * explicit, defaultable options so the whole module is unit-testable without
+ * touching real `process.env` or `process.cwd()`.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { z } from "zod";
+export const CONFIG_FILENAME = ".taskflow.json";
+export const DEFAULT_PROFILE_NAME = "main";
+/** One profile block as it appears in the file. */
+export const profileSchema = z.object({
+    agent_id: z.number().int(),
+    key: z.string().min(1, "profile key must not be empty"),
+    display_name: z.string().optional(),
+});
+/** The whole `.taskflow.json` file. */
+export const taskflowConfigSchema = z.object({
+    server: z.string().min(1, "server must not be empty"),
+    project: z.number().int(),
+    default_profile: z.string().optional(),
+    profiles: z
+        .record(z.string(), profileSchema)
+        .refine((p) => Object.keys(p).length > 0, {
+        message: "profiles must contain at least one profile",
+    }),
+});
+/** A clear, user-facing configuration error (never a raw stack). */
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+/**
+ * Resolve the absolute path of the `.taskflow.json` to use. Precedence:
+ * explicit `configPath` > `TASKFLOW_CONFIG` env > walk up from `startDir`.
+ * Throws {@link ConfigError} when nothing is found.
+ */
+export function findConfigPath(options = {}) {
+    const env = options.env ?? process.env;
+    const explicit = options.configPath ?? env.TASKFLOW_CONFIG;
+    if (explicit) {
+        const abs = resolve(explicit);
+        if (!existsSync(abs)) {
+            throw new ConfigError(`TaskFlow config not found at ${abs}`);
         }
-        return parsed;
+        return abs;
     }
-    catch (err) {
-        if (err.code === 'ENOENT') {
-            // File doesn't exist — that's fine, use defaults
-            return {};
+    let dir = resolve(options.startDir ?? process.cwd());
+    // Walk up to the filesystem root looking for the file.
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const candidate = join(dir, CONFIG_FILENAME);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            break;
         }
-        console.error(`[config] Warning: failed to read ${CONFIG_PATH} — ${err.message}`);
-        return {};
+        dir = parent;
     }
+    throw new ConfigError(`Could not find ${CONFIG_FILENAME} in ${resolve(options.startDir ?? process.cwd())} or any parent directory. ` +
+        `Create one (link an agent in the dashboard's API Base page) or set TASKFLOW_CONFIG.`);
 }
-function applyCliAndEnvOverrides(config) {
-    // Env vars override config file
-    if (process.env.TASKFLOW_SSE_PORT) {
-        const p = parseInt(process.env.TASKFLOW_SSE_PORT, 10);
-        if (!isNaN(p))
-            config.port = p;
-    }
-    if (process.env.TASKFLOW_DB_PATH) {
-        config.databasePath = process.env.TASKFLOW_DB_PATH;
-    }
-    if (process.env.TASKFLOW_HOST) {
-        config.host = process.env.TASKFLOW_HOST;
-    }
-    if (process.env.TASKFLOW_LOG_LEVEL) {
-        config.logLevel = process.env.TASKFLOW_LOG_LEVEL;
+/** Validate an already-parsed object (or JSON text) into a {@link TaskflowConfig}. */
+export function parseConfig(input, sourceLabel = "<string>") {
+    let data;
+    if (typeof input === "string") {
+        try {
+            data = JSON.parse(input);
+        }
+        catch (err) {
+            throw new ConfigError(`Failed to parse ${sourceLabel} as JSON: ${err.message}`);
+        }
     }
-    if (process.env.TASKFLOW_RELAY_URL) {
-        config.relayUrl = process.env.TASKFLOW_RELAY_URL;
+    else {
+        data = input;
     }
-    if (process.env.TASKFLOW_RELAY_PUSH_TOKEN) {
-        config.relayPushToken = process.env.TASKFLOW_RELAY_PUSH_TOKEN;
+    const result = taskflowConfigSchema.safeParse(data);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`)
+            .join("\n");
+        throw new ConfigError(`Invalid ${sourceLabel}:\n${issues}`);
     }
-    // CLI args take highest priority
-    const portArgIdx = process.argv.indexOf('--port');
-    if (portArgIdx !== -1 && process.argv[portArgIdx + 1]) {
-        const p = parseInt(process.argv[portArgIdx + 1], 10);
-        if (!isNaN(p))
-            config.port = p;
+    return result.data;
+}
+/** Read + validate the config file at an absolute path. */
+export function loadConfigFile(configPath) {
+    let text;
+    try {
+        text = readFileSync(configPath, "utf8");
     }
-    const hostArgIdx = process.argv.indexOf('--host');
-    if (hostArgIdx !== -1 && process.argv[hostArgIdx + 1]) {
-        config.host = process.argv[hostArgIdx + 1];
+    catch (err) {
+        throw new ConfigError(`Failed to read ${configPath}: ${err.message}`);
     }
-    return config;
+    return parseConfig(text, configPath);
 }
-// ─── singleton ───────────────────────────────────────────────────────
-let _config = null;
-export function getConfig() {
-    if (_config)
-        return _config;
-    const fileValues = loadFromFile();
-    _config = applyCliAndEnvOverrides({ ...DEFAULTS, ...fileValues });
-    return _config;
+/**
+ * Pick the effective profile name using the documented precedence:
+ * argument > `TASKFLOW_PROFILE` > `default_profile` > `"main"`.
+ */
+export function chooseProfileName(config, options = {}) {
+    const env = options.env ?? process.env;
+    const fromArg = options.profile?.trim();
+    const fromEnv = env.TASKFLOW_PROFILE?.trim();
+    return ((fromArg && fromArg.length > 0 ? fromArg : undefined) ??
+        (fromEnv && fromEnv.length > 0 ? fromEnv : undefined) ??
+        config.default_profile ??
+        DEFAULT_PROFILE_NAME);
 }
-/** Check if a setting key is a server-level config key */
-export function isServerConfigKey(key) {
-    return SERVER_CONFIG_KEYS.has(key);
+/**
+ * Resolve `config` + options into a flat {@link ResolvedProfile}. Throws
+ * {@link ConfigError} if the chosen profile is not present in the file.
+ */
+export function resolveProfile(config, options = {}) {
+    const profileName = chooseProfileName(config, options);
+    const profile = config.profiles[profileName];
+    if (!profile) {
+        const available = Object.keys(config.profiles).join(", ") || "(none)";
+        throw new ConfigError(`Profile "${profileName}" is not defined in ${options.configPath ?? CONFIG_FILENAME}. Available profiles: ${available}.`);
+    }
+    return {
+        server: config.server.replace(/\/+$/, ""),
+        project: config.project,
+        profileName,
+        agentId: profile.agent_id,
+        key: profile.key,
+        displayName: profile.display_name ?? profileName,
+        configPath: options.configPath ?? "",
+    };
 }
-// ─── write-back ──────────────────────────────────────────────────────
 /**
- * Update a single key in ~/.taskflow_config.json.
- * Re-reads the file first to avoid clobbering other keys.
- * Returns the updated config value.
+ * Resolve a profile, or report that a human has to choose.
+ *
+ * Ambiguous means: several profiles defined, and nothing said which one this
+ * terminal is. `default_profile` deliberately does NOT settle it — `--mint`
+ * adds profiles without moving it, so honouring it would mean the prompt never
+ * fires and two terminals silently share one identity, which is the bug.
+ *
+ * `resolveProfile` keeps its throwing contract for callers that already have a
+ * name (`--tmux --profile=x`, `--mint`, a per-tool `profile` argument).
  */
-export function writeConfigKey(key, value) {
-    let existing = {};
-    try {
-        const raw = readFileSync(CONFIG_PATH, 'utf-8');
-        existing = JSON.parse(raw);
+export function resolveProfileOrAsk(config, options = {}) {
+    const env = options.env ?? process.env;
+    const explicit = options.profile?.trim() || env.TASKFLOW_PROFILE?.trim();
+    if (explicit) {
+        // Unknown name is a real error, not an invitation to ask: the caller
+        // asserted an identity and got it wrong.
+        return { kind: "resolved", profile: resolveProfile(config, { ...options, profile: explicit }) };
     }
-    catch {
-        // File doesn't exist or is malformed — start fresh
+    const names = Object.keys(config.profiles);
+    // A stale sticky pick (profile since removed from the file) falls through to
+    // asking rather than throwing — the human never typed that name today.
+    const sticky = options.sticky?.trim();
+    if (sticky && config.profiles[sticky]) {
+        return { kind: "resolved", profile: resolveProfile(config, { ...options, profile: sticky }) };
     }
-    existing[key] = value;
-    mkdirSync(dirname(CONFIG_PATH), { recursive: true });
-    writeFileSync(CONFIG_PATH, JSON.stringify(existing, null, 2) + '\n', 'utf-8');
-    // Update the in-memory singleton so get_setting reflects the change immediately
-    if (_config && key in DEFAULTS) {
-        _config[key] = value;
+    if (names.length === 1) {
+        return { kind: "resolved", profile: resolveProfile(config, { ...options, profile: names[0] }) };
     }
+    const recommended = config.default_profile ?? DEFAULT_PROFILE_NAME;
+    return {
+        kind: "ambiguous",
+        profiles: names.map((name) => ({
+            name,
+            display_name: config.profiles[name]?.display_name ?? name,
+            recommended: name === recommended,
+        })),
+    };
+}
+/**
+ * The one-call convenience the bin entry and hooks use: find the file, load +
+ * validate it, and resolve the chosen profile into a {@link ResolvedProfile}.
+ */
+export function loadProfile(options = {}) {
+    const configPath = findConfigPath(options);
+    const config = loadConfigFile(configPath);
+    return resolveProfile(config, { ...options, configPath });
 }
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/connect.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 { TaskflowClient } from "./client.js";
+import type { ResolvedProfile } from "./config.js";
+export type ConnectionState = "starting" | "active" | "retrying" | "needs_profile" | "stopped";
+export interface ConnectionStatus {
+    state: ConnectionState;
+    /** Why, in the caller's words — always set for `retrying` and `needs_profile`. */
+    detail?: string;
+    attempts: number;
+    /** The live session row id, once registered. */
+    session?: number;
+    /**
+     * WHICH profile this connection is for. Absent before a connection exists
+     * (`starting` / `needs_profile` after a reset).
+     *
+     * A session id on its own is not enough for a caller to reuse: a tool called
+     * with an explicit `profile:` other than the connected one would send another
+     * agent's session under this profile's credential, which the backend rejects.
+     */
+    profile?: string;
+}
+export interface ConnectedContext {
+    client: TaskflowClient;
+    session: number;
+    profile: ResolvedProfile;
+    pane: string | null;
+}
+export interface ConnectOptions {
+    profile: ResolvedProfile;
+    /** The tmux pane, or null outside tmux. Null is a normal, connectable state. */
+    pane: string | null;
+    /** Fired ONCE, on the first successful registration. */
+    onSession?: (ctx: ConnectedContext) => void | Promise<void>;
+    /** Test seam. */
+    createClient?: (profile: ResolvedProfile) => TaskflowClient;
+    log?: (line: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+    heartbeatMs?: number;
+    /** Test seam. False drives heartbeats by hand via `handle.beat()`, so a
+     *  background tick cannot race an assertion. Always true in production. */
+    autoHeartbeat?: boolean;
+}
+export interface ConnectionHandle {
+    stop: () => void;
+    /**
+     * Resolves when the initial registration settles — and NEVER rejects.
+     *
+     * "Settles" means registered, or stopped, or the injected sleep gave up. It
+     * does NOT mean "resolves eventually": retries are unbounded, so while the
+     * backend is down this stays PENDING forever. Callers on the startup path
+     * (Task 6) must therefore not `await` it — doing so would keep the MCP
+     * server from serving a single tool call until the backend came up. Start
+     * the connection, keep the handle, carry on; only tests await it, and they
+     * inject a `sleep` with a finite budget.
+     */
+    settled: Promise<void>;
+    /** Run one heartbeat tick now. Tests use it; production uses the loop. */
+    beat: () => Promise<void>;
+}
+/** The current connection status, for `whoami` to report. */
+export declare function getConnectionStatus(): ConnectionStatus;
+/** Record that we are deliberately NOT connecting until a human picks. */
+export declare function setNeedsProfile(detail: string): void;
+/** Test seam — reset module-level status between cases. */
+export declare function resetConnectionStatus(): void;
+/**
+ * Connect and stay connected. Never throws and never rejects: the agent must
+ * keep working whether or not the dashboard is reachable.
+ */
+export declare function startConnection(options: ConnectOptions): ConnectionHandle;