@tpsdev-ai/flair 0.14.0 → 0.16.0

package/dist/fabric-upgrade.js

@@ -0,0 +1,367 @@
+/**
+ * fabric-upgrade.ts — `flair upgrade --target <fabric-url>`
+ *
+ * One-command upgrade of a Flair instance already DEPLOYED to a Harper Fabric
+ * cluster (as opposed to a local `flair upgrade`, which upgrades the globally
+ * installed npm packages on the current host).
+ *
+ * Why this exists — the manual dance it replaces:
+ *   Upgrading a deployed Fabric Flair used to require, by hand:
+ *     1. mkdir a fresh temp dir
+ *     2. write a package.json that depends on @tpsdev-ai/flair@<version> AND
+ *        carries an `overrides` block pinning @harperfast/harper to a fixed
+ *        version — because the PUBLISHED flair declares an OLD Harper
+ *        (@harperfast/harper@5.0.21 as of flair@0.14.0) whose component
+ *        packager (`packageComponent`) emits an EMPTY tarball when the package
+ *        root lives under node_modules (the real npm-install scenario).
+ *        See flair#513 — fixed in Harper >= 5.1.13.
+ *     3. npm install
+ *     4. run `flair deploy --target <url>` from that temp dir
+ *   This module bakes the Harper pin in so the whole thing is one command.
+ *
+ * `deploy()` (src/deploy.ts) is REUSED verbatim for the packaging + spawn of
+ * the bundled Harper's `harper deploy` — this module never reimplements deploy.
+ * It only: resolves the target version, prepares a clean temp deployable with
+ * the Harper override baked in, confirms the resolved Harper bin is the fix
+ * version, then hands the temp package root to deploy() via `packageRoot`.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createRequire } from "node:module";
+/**
+ * Minimum @harperfast/harper version whose component packager works when the
+ * package root is under node_modules (flair#513 — the empty-tarball fix landed
+ * in 5.1.13). Anything below this MUST be overridden before a Fabric deploy.
+ */
+export const MIN_HARPER_VERSION = "5.1.13";
+/**
+ * Version we pin Harper to when an override is needed and `--harper-version`
+ * isn't given and we can't resolve the registry's latest. Known-good, ships the
+ * packageComponent fix. 5.1.14 is the latest published as of this writing.
+ */
+export const DEFAULT_HARPER_PIN = "5.1.14";
+const FLAIR_PKG = "@tpsdev-ai/flair";
+const HARPER_PKG = "@harperfast/harper";
+/**
+ * Parse "5.1.14" / "5.1.14-rc.1" / "v0.14.0" into [major, minor, patch],
+ * ignoring any pre-release / build suffix for comparison. Returns null when the
+ * core can't be parsed as three numeric segments.
+ */
+export function parseSemverCore(v) {
+    if (!v)
+        return null;
+    const core = v.trim().replace(/^v/, "").split("-")[0].split("+")[0];
+    const parts = core.split(".");
+    if (parts.length < 3)
+        return null;
+    const nums = parts.slice(0, 3).map((p) => Number(p));
+    if (nums.some((n) => !Number.isFinite(n)))
+        return null;
+    return [nums[0], nums[1], nums[2]];
+}
+/** True when `a` >= `b` by numeric major.minor.patch (pre-release ignored). */
+export function semverGte(a, b) {
+    const pa = parseSemverCore(a);
+    const pb = parseSemverCore(b);
+    if (!pa || !pb)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] > pb[i])
+            return true;
+        if (pa[i] < pb[i])
+            return false;
+    }
+    return true; // equal
+}
+/**
+ * Decide what (if any) @harperfast/harper override to bake into the temp
+ * deployable's package.json.
+ *
+ *   - If flair already declares Harper >= MIN_HARPER_VERSION → no override
+ *     needed; keep what it ships (pin = declared).
+ *   - Otherwise (declared is older, absent, or unparseable) → override to
+ *     `preferredPin` (caller passes --harper-version, else registry latest,
+ *     else DEFAULT_HARPER_PIN). We still require the chosen pin to satisfy
+ *     MIN_HARPER_VERSION, falling back to DEFAULT_HARPER_PIN if the caller
+ *     passed something too old.
+ *
+ * Pure — no I/O. The LOAD-BEARING bit is `overridden`: when true, the temp
+ * package.json gets `overrides: { "@harperfast/harper": pin }`.
+ */
+export function resolveHarperPin(declared, preferredPin) {
+    if (declared && semverGte(declared, MIN_HARPER_VERSION)) {
+        return {
+            pin: declared,
+            overridden: false,
+            declared,
+            reason: `flair declares ${HARPER_PKG}@${declared} (>= ${MIN_HARPER_VERSION}); no override needed`,
+        };
+    }
+    // Need an override. Choose the pin: prefer the caller's, but never below the
+    // fix floor — a stale --harper-version would silently reintroduce flair#513.
+    let pin = preferredPin && semverGte(preferredPin, MIN_HARPER_VERSION)
+        ? preferredPin
+        : DEFAULT_HARPER_PIN;
+    const declaredLabel = declared ? `${declared}` : "none";
+    const tooOldHint = preferredPin && !semverGte(preferredPin, MIN_HARPER_VERSION)
+        ? ` (requested ${preferredPin} is below the ${MIN_HARPER_VERSION} fix floor — using ${pin} instead)`
+        : "";
+    return {
+        pin,
+        overridden: true,
+        declared,
+        reason: `flair declares ${HARPER_PKG}@${declaredLabel} (< ${MIN_HARPER_VERSION}, flair#513 empty-tarball) — pinning to ${pin}${tooOldHint}`,
+    };
+}
+/**
+ * Build the package.json contents for the temp deployable. Depends on
+ * @tpsdev-ai/flair@<version> and, when the Harper pin is an override, carries
+ * the `overrides` block that forces npm to install the fix Harper under the
+ * flair package's node_modules.
+ */
+export function buildDeployablePackageJson(flairVersion, pin) {
+    const pkg = {
+        name: "flair-fabric-upgrade-stage",
+        version: "0.0.0",
+        private: true,
+        dependencies: {
+            [FLAIR_PKG]: flairVersion,
+        },
+    };
+    if (pin.overridden) {
+        pkg.overrides = { [HARPER_PKG]: pin.pin };
+    }
+    return pkg;
+}
+// ─── Default (real) dependency implementations ──────────────────────────────
+const REGISTRY = "https://registry.npmjs.org";
+async function defaultFetchLatestFlairVersion() {
+    const res = await fetch(`${REGISTRY}/${FLAIR_PKG}/latest`, {
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+        throw new Error(`npm registry returned ${res.status} for ${FLAIR_PKG}/latest`);
+    }
+    const data = (await res.json());
+    if (!data.version)
+        throw new Error(`No version in registry response for ${FLAIR_PKG}`);
+    return data.version;
+}
+async function defaultFetchDeclaredHarperVersion(flairVersion) {
+    const res = await fetch(`${REGISTRY}/${FLAIR_PKG}/${flairVersion}`, {
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok)
+        return null;
+    const data = (await res.json());
+    return data.dependencies?.[HARPER_PKG] ?? null;
+}
+function defaultNpmInstall(dir) {
+    // No package spec on argv — npm reads dependencies + overrides from the
+    // package.json we wrote into `dir`. --omit=dev keeps the stage lean;
+    // --no-audit/--no-fund cut noise. Output streamed for operator visibility.
+    const r = spawnSync("npm", ["install", "--omit=dev", "--no-audit", "--no-fund"], { cwd: dir, stdio: "inherit" });
+    if (r.error)
+        throw r.error;
+    if (r.status !== 0) {
+        throw new Error(`npm install failed in staging dir (exit ${r.status})`);
+    }
+}
+/**
+ * Query the Fabric for the deployed Flair component version. Best-effort: the
+ * public REST surface exposes `/Health`, which echoes the running Flair version
+ * in newer builds; if the shape isn't recognized we return null (verification
+ * downgrades to a soft notice, never a hard failure).
+ */
+async function defaultFetchDeployedVersion(opts) {
+    const base = opts.url.replace(/\/$/, "");
+    const headers = {};
+    if (opts.fabricUser && opts.fabricPassword) {
+        const auth = Buffer.from(`${opts.fabricUser}:${opts.fabricPassword}`).toString("base64");
+        headers.Authorization = `Basic ${auth}`;
+    }
+    try {
+        const res = await fetch(`${base}/Health`, {
+            headers,
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok)
+            return null;
+        const text = await res.text();
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+        // Tolerate a few shapes: { version }, { flair: { version } }, { flairVersion }.
+        const v = body?.version ?? body?.flairVersion ?? body?.flair?.version ?? null;
+        return typeof v === "string" ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve the @harperfast/harper bin that npm installed under the staged flair. */
+export function resolveStagedHarperVersion(stagingDir) {
+    const harperPkgJson = join(stagingDir, "node_modules", FLAIR_PKG, "node_modules", HARPER_PKG, "package.json");
+    // npm dedupes: with an override the fixed Harper may hoist to the staging
+    // root rather than nest under flair. Check both.
+    const hoisted = join(stagingDir, "node_modules", HARPER_PKG, "package.json");
+    for (const candidate of [harperPkgJson, hoisted]) {
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, "utf8"));
+                if (typeof pkg.version === "string")
+                    return pkg.version;
+            }
+            catch {
+                /* try next */
+            }
+        }
+    }
+    // Last resort: resolve through the staged flair's module graph.
+    try {
+        const flairPkg = join(stagingDir, "node_modules", FLAIR_PKG, "package.json");
+        const req = createRequire(flairPkg);
+        const resolved = req.resolve(`${HARPER_PKG}/package.json`);
+        const pkg = JSON.parse(readFileSync(resolved, "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Locate the staged @tpsdev-ai/flair package root (the deploy() packageRoot). */
+export function resolveStagedFlairRoot(stagingDir) {
+    const root = join(stagingDir, "node_modules", FLAIR_PKG);
+    if (!existsSync(join(root, "package.json"))) {
+        throw new Error(`Staged flair not found at ${root} — npm install may have failed`);
+    }
+    return root;
+}
+function defaultDeps() {
+    // deploy is imported lazily so unit tests can fully mock without pulling the
+    // real Harper-spawning module into their graph.
+    return {
+        fetchLatestFlairVersion: defaultFetchLatestFlairVersion,
+        fetchDeclaredHarperVersion: defaultFetchDeclaredHarperVersion,
+        npmInstall: defaultNpmInstall,
+        fetchDeployedVersion: defaultFetchDeployedVersion,
+        deploy: async (opts) => {
+            const { deploy } = await import("./deploy.js");
+            return deploy(opts);
+        },
+        log: (m) => console.log(m),
+    };
+}
+// ─── Orchestrator ───────────────────────────────────────────────────────────
+/**
+ * Build the upgrade plan (steps 1 + version diff). Pure-ish: only the two
+ * read-only registry lookups, no install, no deploy. `--check` stops here.
+ */
+export async function planFabricUpgrade(opts, deps) {
+    const project = opts.project ?? "flair";
+    const targetVersion = opts.version ?? (await deps.fetchLatestFlairVersion());
+    const declaredHarper = await deps.fetchDeclaredHarperVersion(targetVersion);
+    const harper = resolveHarperPin(declaredHarper, opts.harperVersion);
+    const currentVersion = await deps.fetchDeployedVersion({
+        url: opts.target,
+        project,
+        fabricUser: opts.fabricUser,
+        fabricPassword: opts.fabricPassword,
+    });
+    const upToDate = currentVersion != null &&
+        parseSemverCore(currentVersion) != null &&
+        parseSemverCore(targetVersion) != null &&
+        semverGte(currentVersion, targetVersion) &&
+        semverGte(targetVersion, currentVersion);
+    return { target: opts.target, project, targetVersion, currentVersion, harper, upToDate };
+}
+/**
+ * Full Fabric upgrade. Reuses deploy() for the packaging/deploy — this function
+ * only prepares the clean temp deployable (with the Harper override baked in)
+ * and verifies afterward.
+ *
+ * SAFETY: never logs creds; always cleans up the staging dir (finally); never
+ * touches the running local Flair — all work happens in an isolated temp dir
+ * and the deploy targets the remote Fabric URL only.
+ */
+export async function fabricUpgrade(opts, injected) {
+    const deps = { ...defaultDeps(), ...injected };
+    const log = deps.log ?? (() => { });
+    // Step 1 + diff.
+    const plan = await planFabricUpgrade(opts, deps);
+    log(`Fabric:  ${plan.target}`);
+    log(`Project: ${plan.project}`);
+    log(`Version: ${plan.currentVersion ?? "(unknown)"} → ${plan.targetVersion}` +
+        (plan.upToDate ? "  (already up to date)" : ""));
+    log(`Harper:  ${plan.harper.reason}`);
+    if (opts.check) {
+        log("");
+        log("--check: plan only — not deploying.");
+        return { plan, deployed: false, verifiedVersion: null, stagingDir: "" };
+    }
+    // Step 2: prepare a clean deployable in an isolated temp dir.
+    const stagingDir = mkdtempSync(join(tmpdir(), "flair-fabric-upgrade-"));
+    try {
+        const pkgJson = buildDeployablePackageJson(plan.targetVersion, plan.harper);
+        writeFileSync(join(stagingDir, "package.json"), JSON.stringify(pkgJson, null, 2));
+        log(`\nStaging ${FLAIR_PKG}@${plan.targetVersion} in ${stagingDir} ...`);
+        deps.npmInstall(stagingDir);
+        // CONFIRM the resolved Harper bin is the fix version before deploying.
+        const stagedHarper = resolveStagedHarperVersion(stagingDir);
+        if (!stagedHarper) {
+            throw new Error(`Could not resolve the staged ${HARPER_PKG} version — refusing to deploy ` +
+                `(packageComponent may emit an empty tarball, flair#513).`);
+        }
+        if (!semverGte(stagedHarper, MIN_HARPER_VERSION)) {
+            throw new Error(`Staged ${HARPER_PKG}@${stagedHarper} is below the ${MIN_HARPER_VERSION} ` +
+                `fix floor — the override did not take. Refusing to deploy (flair#513).`);
+        }
+        log(`✓ Staged ${HARPER_PKG}@${stagedHarper} (>= ${MIN_HARPER_VERSION})`);
+        const packageRoot = resolveStagedFlairRoot(stagingDir);
+        // Step 3: REUSE deploy() — do not reimplement packaging/spawn.
+        log(`Deploying ${plan.project} ${plan.targetVersion} to ${plan.target} ...`);
+        const result = await deps.deploy({
+            target: opts.target,
+            project: plan.project,
+            version: plan.targetVersion,
+            fabricUser: opts.fabricUser,
+            fabricPassword: opts.fabricPassword,
+            restart: opts.restart,
+            replicated: opts.replicated,
+            packageRoot,
+        });
+        // Step 4: verify the deployed version (best-effort).
+        let verifiedVersion = null;
+        try {
+            verifiedVersion = await deps.fetchDeployedVersion({
+                url: opts.target,
+                project: plan.project,
+                fabricUser: opts.fabricUser,
+                fabricPassword: opts.fabricPassword,
+            });
+        }
+        catch {
+            verifiedVersion = null;
+        }
+        if (verifiedVersion) {
+            const ok = semverGte(verifiedVersion, plan.targetVersion);
+            log(ok
+                ? `✓ Fabric now reports Flair ${verifiedVersion}`
+                : `⚠ Fabric reports ${verifiedVersion} (expected ${plan.targetVersion}) — may still be restarting`);
+        }
+        else {
+            log(`✓ Deployed ${result.version} (Fabric did not report a version to verify against)`);
+        }
+        return { plan, deployed: true, verifiedVersion, stagingDir };
+    }
+    finally {
+        // SAFETY: always clean up the temp dir.
+        rmSync(stagingDir, { recursive: true, force: true });
+    }
+}

package/dist/install/clients.js

@@ -5,9 +5,28 @@
 //   - detect(): boolean - returns true if client is installed
 //   - wire(options: { agentId: string; flairUrl: string }): { ok: boolean; message: string }
 //
+// Wiring contract (FIX 4 — onboarding dogfood round 1):
+//   "wired" MUST mean a config file was actually written. A wire function returns
+//   { ok: true } ONLY when it merged the Flair MCP server into the client's real
+//   config file. If it cannot (unknown path, write error), it returns
+//   { ok: false } with the correct per-OS snippet to paste — never a vague
+//   "manual wiring required" while elsewhere the run claims the client is wired.
+//   All paths are resolved cross-platform (Linux included) via standard
+//   per-client locations under $HOME / $XDG_CONFIG_HOME.
 // ---- Detection helpers ----------------------------------------------------------
 import { spawnSync } from "node:child_process";
-import { accessSync, constants } from "node:fs";
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/**
+ * Resolve the user's home dir. Prefer the live HOME/USERPROFILE env over
+ * os.homedir(), which caches the value at process start and so ignores a
+ * runtime HOME override — same convention as src/cli.ts ("so tests can
+ * override"). Production behavior is unchanged (HOME is set on every OS).
+ */
+function resolveHome() {
+    return process.env.HOME || process.env.USERPROFILE || homedir();
+}
 /**
  * Check if a command exists in PATH (cross-platform alternative to `which`).
  * Does not spawn a child process — pure filesystem check.
@@ -85,94 +104,126 @@ function cursorDetect() {
         return false;
     }
 }
-// ---- Internal wiring functions --------------------------------------------------
-function _wireClaudeCode(env) {
+// ---- Shared config shapes -------------------------------------------------------
+/** The standard MCP stdio server entry every client (except Codex TOML) uses. */
+function flairMcpEntry(env) {
     return {
-        ok: false,
-        message: `Manual wiring required for Claude Code:\n` +
-            `1. Locate Claude Code's settings file (usually ~/Library/Application Support/Claude/settings.json on macOS or %APPDATA%/Claude/settings.json on Windows)\n` +
-            `2. Add or update the "mcpServers" section:\n` +
-            `   {\n` +
-            `     "mcpServers": {\n` +
-            `       "flair": {\n` +
-            `         "command": "npx",\n` +
-            `         "args": ["-y", "@tpsdev-ai/flair-mcp"],\n` +
-            `         "env": {\n` +
-            `           "FLAIR_AGENT_ID": "${env.FLAIR_AGENT_ID}",\n` +
-            `           "FLAIR_URL": "${env.FLAIR_URL}"\n` +
-            `         }\n` +
-            `       }\n` +
-            `     }\n` +
-            `   }\n` +
-            `3. Restart Claude Code\n` +
-            `Note: This is a manual step - the Flair CLI cannot automatically modify Claude Code's settings due to security restrictions.`,
+        command: "npx",
+        args: ["-y", "@tpsdev-ai/flair-mcp"],
+        env: { FLAIR_AGENT_ID: env.FLAIR_AGENT_ID, FLAIR_URL: env.FLAIR_URL },
     };
 }
+/** Pretty-printed JSON `mcpServers.flair` snippet for copy-paste fallbacks. */
+function jsonSnippet(env) {
+    return JSON.stringify({ mcpServers: { flair: flairMcpEntry(env) } }, null, 2);
+}
+/** TOML `[mcp_servers.flair]` snippet (Codex format). */
+function tomlSnippet(env) {
+    return [
+        `[mcp_servers.flair]`,
+        `command = "npx"`,
+        `args = ["-y", "@tpsdev-ai/flair-mcp"]`,
+        ``,
+        `[mcp_servers.flair.env]`,
+        `FLAIR_AGENT_ID = "${env.FLAIR_AGENT_ID}"`,
+        `FLAIR_URL = "${env.FLAIR_URL}"`,
+    ].join("\n");
+}
+/**
+ * Merge the Flair MCP server into a JSON config file with an `mcpServers` map.
+ * Creates the file (and parent dir) if absent; preserves existing servers and
+ * any other top-level keys. Returns ok:true only when the file was written.
+ */
+function wireJsonMcp(configPath, label, env) {
+    const home = resolveHome();
+    const display = configPath.startsWith(home) ? "~" + configPath.slice(home.length) : configPath;
+    try {
+        let config = {};
+        if (existsSync(configPath)) {
+            const raw = readFileSync(configPath, "utf-8").trim();
+            if (raw)
+                config = JSON.parse(raw);
+        }
+        config.mcpServers = config.mcpServers || {};
+        const existing = config.mcpServers.flair;
+        if (existing && existing.env?.FLAIR_URL === env.FLAIR_URL && existing.env?.FLAIR_AGENT_ID === env.FLAIR_AGENT_ID) {
+            return { ok: true, message: `${label}: already wired in ${display}` };
+        }
+        config.mcpServers.flair = flairMcpEntry(env);
+        mkdirSync(dirname(configPath), { recursive: true });
+        writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+        return { ok: true, message: `${label}: wired ${display} (restart ${label} to pick it up)` };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            message: `${label}: manual wiring needed (could not write ${display}: ${reason}).\n` +
+                `   Add this to ${display}:\n${indent(jsonSnippet(env))}`,
+        };
+    }
+}
+function indent(s) {
+    return s.split("\n").map((l) => `     ${l}`).join("\n");
+}
+// ---- Per-client config paths (cross-platform, Linux included) --------------------
+/** Cursor: ~/.cursor/mcp.json on every OS. */
+function cursorConfigPath() {
+    return join(resolveHome(), ".cursor", "mcp.json");
+}
+/** Gemini CLI: ~/.gemini/settings.json on every OS. */
+function geminiConfigPath() {
+    return join(resolveHome(), ".gemini", "settings.json");
+}
+/** Codex CLI: ~/.codex/config.toml on every OS. */
+function codexConfigPath() {
+    return join(resolveHome(), ".codex", "config.toml");
+}
+// ---- Internal wiring functions --------------------------------------------------
+//
+// Claude Code wiring lives inline in src/cli.ts (it writes ~/.claude.json, the
+// one client the CLI safely edits, cross-platform). _wireClaudeCode here is the
+// fallback used when something calls the array form; it returns the snippet for
+// ~/.claude.json so the message is unambiguous and correct on every OS.
+function _wireClaudeCode(env) {
+    // The real auto-wire is inline in cli.ts. If reached via the array, point at
+    // the correct cross-platform path (~/.claude.json — same on macOS/Linux/Win)
+    // and give the exact snippet. Never emit macOS-only paths here.
+    return wireJsonMcp(join(resolveHome(), ".claude.json"), "Claude Code", env);
+}
 function _wireCodex(env) {
-    return {
-        ok: false,
-        message: `Manual wiring required for Codex:\n` +
-            `1. Locate Codex's configuration (check ~/.codex/config or similar)\n` +
-            `2. Add the Flair MCP server configuration:\n` +
-            `   {\n` +
-            `     "mcpServers": {\n` +
-            `       "flair": {\n` +
-            `         "command": "npx",\n` +
-            `         "args": ["-y", "@tpsdev-ai/flair-mcp"],\n` +
-            `         "env": {\n` +
-            `           "FLAIR_AGENT_ID": "${env.FLAIR_AGENT_ID}",\n` +
-            `           "FLAIR_URL": "${env.FLAIR_URL}"\n` +
-            `         }\n` +
-            `       }\n` +
-            `     }\n` +
-            `   }\n` +
-            `3. Restart Codex\n` +
-            `Note: This is a manual step - the Flair CLI cannot automatically modify Codex's configuration due to security restrictions.`,
-    };
+    // Codex uses TOML with a [mcp_servers.flair] table. We don't carry a TOML
+    // parser, and blind text-appending risks corrupting/duplicating an existing
+    // table — so we only auto-write when the file does NOT yet exist (clean
+    // create), otherwise emit the exact TOML block to paste.
+    const path = codexConfigPath();
+    const display = "~/.codex/config.toml";
+    try {
+        if (existsSync(path)) {
+            return {
+                ok: false,
+                message: `Codex: manual wiring needed — ${display} already exists.\n` +
+                    `   Add this block to ${display}:\n${indent(tomlSnippet(env))}`,
+            };
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, tomlSnippet(env) + "\n");
+        return { ok: true, message: `Codex: wired ${display} (restart Codex to pick it up)` };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            message: `Codex: manual wiring needed (could not write ${display}: ${reason}).\n` +
+                `   Add this block to ${display}:\n${indent(tomlSnippet(env))}`,
+        };
+    }
 }
 function _wireGemini(env) {
-    return {
-        ok: false,
-        message: `Manual wiring required for Gemini:\n` +
-            `1. Locate Gemini's configuration (check ~/.gemini/config or similar)\n` +
-            `2. Add the Flair MCP server configuration:\n` +
-            `   {\n` +
-            `     "mcpServers": {\n` +
-            `       "flair": {\n` +
-            `         "command": "npx",\n` +
-            `         "args": ["-y", "@tpsdev-ai/flair-mcp"],\n` +
-            `         "env": {\n` +
-            `           "FLAIR_AGENT_ID": "${env.FLAIR_AGENT_ID}",\n` +
-            `           "FLAIR_URL": "${env.FLAIR_URL}"\n` +
-            `         }\n` +
-            `       }\n` +
-            `     }\n` +
-            `   }\n` +
-            `3. Restart Gemini\n` +
-            `Note: This is a manual step - the Flair CLI cannot automatically modify Gemini's configuration due to security restrictions.`,
-    };
+    return wireJsonMcp(geminiConfigPath(), "Gemini", env);
 }
 function _wireCursor(env) {
-    return {
-        ok: false,
-        message: `Manual wiring required for Cursor:\n` +
-            `1. Locate Cursor's settings file (usually ~/.cursor/settings.json)\n` +
-            `2. Add or update the "mcpServers" section:\n` +
-            `   {\n` +
-            `     "mcpServers": {\n` +
-            `       "flair": {\n` +
-            `         "command": "npx",\n` +
-            `         "args": ["-y", "@tpsdev-ai/flair-mcp"],\n` +
-            `         "env": {\n` +
-            `           "FLAIR_AGENT_ID": "${env.FLAIR_AGENT_ID}",\n` +
-            `           "FLAIR_URL": "${env.FLAIR_URL}"\n` +
-            `         }\n` +
-            `       }\n` +
-            `     }\n` +
-            `   }\n` +
-            `3. Restart Cursor\n` +
-            `Note: This is a manual step - the Flair CLI cannot automatically modify Cursor's settings due to security restrictions.`,
-    };
+    return wireJsonMcp(cursorConfigPath(), "Cursor", env);
 }
 // ---- Exported detection & wiring array ------------------------------------------
 export const ALL_CLIENTS = [

package/dist/resources/A2AAdapter.js

@@ -274,7 +274,10 @@ export class A2AAdapter extends Resource {
     // (GET /a2a passes through; POST /a2a must carry TPS-Ed25519 or admin
     // Basic). The post() handler below additionally enforces sender ==
     // params.agentId for message/send so an authenticated caller can only
-    // act AS themselves, not impersonate another agent.
+    // act AS themselves, not impersonate another agent. message/send routes
+    // a DIRECTED handoff to params.toAgentId (the recipient) by setting the
+    // OrgEvent's targetIds = [toAgentId]; OrgEventCatchup filters on that, so
+    // the recipient — not the sender — receives the message.
     allowRead() { return true; }
     allowCreate() { return true; }
     async get() {
@@ -439,22 +442,45 @@ export class A2AAdapter extends Resource {
                 // Without this check, an authenticated agent could forge OrgEvents
                 // attributed to any other agent — defeats the whole signed-envelopes
                 // model that delegationChain enforces for TPS mail.
+                // NOTE: agentId is the SENDER. The recipient is params.toAgentId.
                 if (!callerIsAdmin && callerAgent !== agentId) {
                     return rpcError(id, -32001, "Forbidden", {
                         detail: `caller ${callerAgent ?? "(anon)"} cannot send as ${agentId}`,
                     });
                 }
-                const agent = await databases.flair.Agent.get(agentId).catch(() => null);
-                if (!agent) {
+                const sender = await databases.flair.Agent.get(agentId).catch(() => null);
+                if (!sender) {
                     return rpcError(id, -32004, "Agent not found", { agentId });
                 }
+                // Directed handoff: params.toAgentId (the recipient) controls
+                // OrgEvent.targetIds, which is what OrgEventCatchup filters on
+                // (`targets.includes(participantId)`). The recipient must exist.
+                // Back-compat: if toAgentId is omitted, fall back to the legacy
+                // self-scoped broadcast (targetIds = [sender]) so existing callers
+                // that only set agentId keep working. The no-spoof guard above is
+                // unchanged — toAgentId only affects WHO receives the message, never
+                // who it is sent AS, so a sender can hand off to a peer without being
+                // able to impersonate anyone.
+                const toAgentId = cleanText(params.toAgentId);
+                let targetIds;
+                if (toAgentId) {
+                    const recipient = await databases.flair.Agent.get(toAgentId).catch(() => null);
+                    if (!recipient) {
+                        return rpcError(id, -32004, "Recipient agent not found", { toAgentId });
+                    }
+                    targetIds = [toAgentId];
+                }
+                else {
+                    targetIds = [agentId];
+                }
                 const summary = truncate(firstTextPart(message) || "A2A message received", 200);
                 await publishOrgEvent({
+                    authorId: agentId,
                     kind: "a2a.message",
                     scope: agentId,
                     summary,
-                    detail: JSON.stringify({ message }),
-                    targetIds: [agentId],
+                    detail: JSON.stringify({ message, toAgentId: toAgentId || null }),
+                    targetIds,
                 });
                 return rpcResult(id, {
                     type: "message",