@staix/agent-hub 0.12.33 → 0.12.34

package/src/adapters/definitions/native-cli-entry-claude.ts

@@ -0,0 +1,52 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import type { ClaudeLaunchRecord } from "../../cli/launch.ts";
+import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
+
+export async function runClaudeEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const { args, cwd, stateDir, cliDir, unattendedEnv, projectConfig, fail } = ctx;
+  const { launcherPreview, readControl, recordTerminalLaunch, claudeObservationHooks, buildLaunch, runClaudeLaunch, processSignature, recordClaudeLaunch, cleanupStaleClaudeSettings, nativeLaunchEnv, childEnv, cleanupClaudeSettings } = ctx.helpers;
+  if (args.includes("--print-command") || args.includes("--dry-run")) {
+    try { return console.log(JSON.stringify(launcherPreview("claude", args, cwd, stateDir, unattendedEnv), null, 2)); }
+    catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
+  }
+  const control = readControl(stateDir);
+  if (control?.instanceId) {
+    process.env.AGENTHUB_INSTANCE_ID = control.instanceId;
+    const terminal = await recordTerminalLaunch("claude", cwd, stateDir, control.instanceId);
+    if (!terminal) process.env.AGENTHUB_LAUNCH_ID = randomUUID();
+  }
+  // `--settings` outranks project and user settings, so the tee has to wrap whichever status line would have won:
+  // project local, then project, then user.
+  let original: { command?: string; refreshInterval?: number; padding?: number } | undefined;
+  for (const file of [join(cwd, ".claude", "settings.local.json"), join(cwd, ".claude", "settings.json"), join(process.env.HOME ?? "", ".claude", "settings.json")]) {
+    try {
+      original ??= JSON.parse(readFileSync(file, "utf8")).statusLine;
+    } catch {
+      // no such file, or no status line in it
+    }
+  }
+  // Turn-free facts and opted-in task sweeps share native PreToolUse/PostToolUse/Stop observations.
+  const facts = claudeObservationHooks(projectConfig(), { script: join(cliDir, "facts-hook.ts"), stateDir });
+  let previousLaunch: unknown;
+  try { previousLaunch = JSON.parse(readFileSync(join(stateDir, "claude-launch.json"), "utf8")); } catch { /* no previous managed launch */ }
+  const launch = buildLaunch("claude", args, { unattended: unattendedEnv, statusLine: { script: join(cliDir, "statusline-tee.ts"), stateDir, ...(original ? { original } : {}) }, ...(facts ? { facts } : {}) });
+  let result: Awaited<ReturnType<typeof runClaudeLaunch>>;
+  try {
+    let launchRecord: ClaudeLaunchRecord | undefined;
+    if (control?.instanceId) {
+      // Publish only the final launch's installed hook and effective permission flags.
+      launchRecord = { instanceId: control.instanceId, launchId: process.env.AGENTHUB_LAUNCH_ID!, permissionHook: launch.permissionHook === true, hookPurpose: launch.hookPurpose, settingsFile: launch.settingsFile, launcherPid: process.pid, launcherSignature: processSignature(process.pid), unattended: launch.unattended === true };
+      recordClaudeLaunch(stateDir, launchRecord);
+      cleanupStaleClaudeSettings(stateDir, previousLaunch);
+    }
+    if (launch.warning) console.error(launch.warning);
+    const env = nativeLaunchEnv("claude", childEnv());
+    result = await runClaudeLaunch(launch, { cwd, stateDir, env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd }, ...(launchRecord ? { record: launchRecord } : {}) });
+  } finally {
+    cleanupClaudeSettings(stateDir, launch.settingsFile);
+  }
+  if (result.error) fail(`cannot run ${launch.cmd}: ${result.error.message}`);
+  process.exit(result.status ?? 1);
+}

package/src/adapters/definitions/native-cli-entry-codex.ts

@@ -0,0 +1,26 @@
+import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
+
+export async function runCodexEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const { args, cwd, stateDir, unattendedEnv, projectConfig, connect, fail, exec } = ctx;
+  const { launcherPreview, buildLaunch, recoveryLock, readControl, recordTerminalLaunch } = ctx.helpers;
+  if (args.includes("--print-command") || args.includes("--dry-run")) {
+    try { return console.log(JSON.stringify(launcherPreview("codex", args, cwd, stateDir, unattendedEnv), null, 2)); }
+    catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
+  }
+  const launch0 = buildLaunch("codex", args, { unattended: unattendedEnv, proxyUrl: "pending" }); // refuse bad flags before starting anything
+  // #215: a launch by a recovery operation records itself before the hub round trip, so the coordinator never takes
+  // a launcher still starting for one that never ran. An ordinary launch records only once the hub accepted it: a
+  // refused start must not replace the record of a Codex already running here (one row per peer and instance).
+  const recovering = !!process.env.AGENTHUB_RECOVERY_OPERATION && process.env.AGENTHUB_RECOVERY_OPERATION === recoveryLock(); // not an id a restored session inherited
+  const before = readControl(stateDir);
+  if (recovering && before?.instanceId) await recordTerminalLaunch("codex", cwd, stateDir, before.instanceId);
+  const hub = await connect();
+  const res = await hub.request({ t: "start", peer: "codex", args: { unattended: launch0.unattended === true }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+  hub.close();
+  if (!res.ok) fail(res.error);
+  const control = readControl(stateDir);
+  if (!recovering && control?.instanceId) await recordTerminalLaunch("codex", cwd, stateDir, control.instanceId);
+  const launch = buildLaunch("codex", args, { unattended: unattendedEnv, proxyUrl: res.proxyUrl, codexBin: projectConfig().codex_bin });
+  if (launch0.warning) console.error(launch0.warning);
+  exec(launch.cmd, launch.args, "codex");
+}

package/src/adapters/definitions/native-cli-entry-jcode.ts

@@ -0,0 +1,24 @@
+import { resolve } from "node:path";
+import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
+
+export async function runJcodeEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const { args, cwd, stateDir, cliDir, unattendedEnv, connect, fail, takeFlags } = ctx;
+  const { launcherPreview, qwenSessionId, configureJcodeMcp } = ctx.helpers;
+  if (args.includes("--print-command") || args.includes("--dry-run")) {
+    try { return console.log(JSON.stringify(launcherPreview("jcode", args, cwd, stateDir, unattendedEnv), null, 2)); }
+    catch { fail("cannot preview Jcode launch: invalid arguments or configuration (details withheld)"); }
+  }
+  const { one, rest } = takeFlags(args, ["--mode", "--model", "--provider-profile", "--session-id"], []);
+  if (rest.length || (one["--mode"] !== undefined && one["--mode"] !== "headless")) fail("usage: ahub jcode [--mode headless] [--model <alias>] [--provider-profile <name>] [--session-id <id>]");
+  if (one["--session-id"] !== undefined && !qwenSessionId(one["--session-id"])) fail("invalid Jcode session identity");
+  const hub = await connect();
+  try {
+    const snapshot = (await hub.request({ t: "status" })).status;
+    if (snapshot?.roster?.find((row: any) => row.peer === "jcode")?.on !== true) fail("jcode is off roster; add it with ahub roster add jcode");
+    const written = configureJcodeMcp(cwd, stateDir, resolve(cliDir, "../../plugins/agent-hub/server.js"));
+    if (written.tracked) console.error(".jcode/mcp.json is tracked; review this local machine-path change before committing it");
+    const reply = await hub.request({ t: "start", peer: "jcode", args: { mode: "headless", model: one["--model"], providerProfile: one["--provider-profile"], sessionId: one["--session-id"] }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 65_000);
+    if (!reply.ok) fail(reply.error);
+    console.log(reply.already ? "jcode is already attached" : "jcode attached (headless); native policy unmanaged, NO hub sandbox");
+  } finally { hub.close(); }
+}

package/src/adapters/definitions/native-cli-entry-kimi.ts

@@ -0,0 +1,52 @@
+import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
+
+export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const { args, cwd, stateDir, cliDir, unattendedEnv, projectConfig, connect, fail, takeFlags } = ctx;
+  const { launcherPreview, startModeOf, buildKimiTuiLaunch, configureKimiMcp, nativeLaunchEnv, childEnv } = ctx.helpers;
+  if (args.includes("--print-command") || args.includes("--dry-run")) {
+    try { return console.log(JSON.stringify(launcherPreview("kimi", args, cwd, stateDir, unattendedEnv), null, 2)); }
+    catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
+  }
+  const { one, rest } = takeFlags(args, ["--mode", "--model"], []);
+  const mode = one["--mode"] ?? startModeOf(projectConfig().peers, "kimi"), model = one["--model"];
+  if (rest.length || !["tui", "headless"].includes(mode)) fail("usage: ahub kimi [--mode tui|headless] [--model <alias>]");
+  if (mode === "tui" && one["--mode"] === undefined && !(process.stdin.isTTY && process.stdout.isTTY)) {
+    if (model) fail("Kimi's TUI needs a terminal for these options; run in a terminal or add --mode headless");
+    const hub = await connect();
+    try {
+      const reply = await hub.request({ t: "peer_start", peer: "kimi" }, 35_000);
+      if (!reply.ok) fail(reply.error);
+      return console.log(reply.already ? "kimi is already attached" : `kimi: opened a terminal running ${reply.command}; it attaches pull-only when its TUI is ready`);
+    } finally { hub.close(); }
+  }
+  const hub = await connect();
+  try {
+    if (mode === "tui") {
+      const launch = buildKimiTuiLaunch(projectConfig().kimi_cmd, model);
+      const snapshot = (await hub.request({ t: "status" })).status;
+      if (snapshot?.roster?.find((row: any) => row.peer === "kimi")?.on === false) fail("kimi is off roster; add it with ahub roster add kimi");
+      const peer = snapshot?.peers?.kimi;
+      if (peer && !["offline"].includes(peer.state) && !peer.pullOnly) fail("Kimi is running headless; run ahub stop kimi before starting its TUI");
+      const admission = await hub.request({ t: "start", peer: "kimi", args: { mode: "tui" }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+      if (!admission.ok) fail(admission.error);
+      let result: ReturnType<typeof spawnSync>;
+      try {
+        const written = configureKimiMcp(cwd, stateDir, resolve(cliDir, "../../plugins/agent-hub/server.js"), "tui");
+        if (written.tracked) console.error(".kimi-code/mcp.json is tracked; the agent-hub entry contains machine paths. Review this local change before committing it.");
+        result = spawnSync(launch.cmd, launch.args, { cwd, stdio: "inherit", env: { ...nativeLaunchEnv("kimi", childEnv()), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
+      } finally {
+        if (admission.admissionId) await hub.request({ t: "kimi_launch_end", admissionId: admission.admissionId }).catch(() => {});
+      }
+      if (result.error) fail(`cannot run ${launch.cmd}: ${result.error.message}`);
+      process.exit(result.status ?? 1);
+    }
+    const peer = (await hub.request({ t: "status" })).status?.peers?.kimi;
+    if (peer?.pullOnly && peer.state !== "offline") fail("Kimi runs in a terminal; end it there before starting a headless one");
+    configureKimiMcp(cwd, stateDir, resolve(cliDir, "../../plugins/agent-hub/server.js"), "headless");
+    const res = await hub.request({ t: "start", peer: "kimi", args: { mode: "headless", model }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+    if (!res.ok) fail(res.error);
+    console.log(res.already ? "kimi is already attached" : 'kimi attached (headless). Talk to it with: ahub say @kimi "..."');
+  } finally { hub.close(); }
+}

package/src/adapters/definitions/native-cli-entry-local.ts

@@ -0,0 +1,14 @@
+import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
+
+export async function runLocalEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const { args, connect, fail } = ctx;
+  const opt = (flag: string) => (args.includes(flag) ? args[args.indexOf(flag) + 1] ?? fail(`${flag} needs a value`) : undefined);
+  for (const flag of ["--route", "--model"]) if (args.includes(flag) && (!opt(flag) || opt(flag)!.startsWith("--"))) fail(`${flag} needs a value`);
+  if (args.includes("--route") && args.includes("--model")) fail("use --route or --model, not both");
+  if (args.some((a, i) => i % 2 === 0 && !["--route", "--model"].includes(a))) fail("usage: ahub local [--route <id> | --model <id>]");
+  const hub = await connect();
+  const res = await hub.request({ t: "start", peer: "local", args: { route: opt("--route"), model: opt("--model") }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+  hub.close();
+  if (!res.ok) fail(res.error);
+  console.log(res.already ? "local is already attached" : `local attached on ${res.model}. Give it work with: ahub say @local "..."`);
+}

package/src/adapters/definitions/native-cli-entry-pi.ts

@@ -0,0 +1,51 @@
+import { parsePiFlags } from "./native-cli-pi.ts";
+import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
+
+export async function runPiEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const { args, cwd, stateDir, unattendedEnv, projectConfig, connect, fail, execWithEnv } = ctx;
+  const { launcherPreview, startModeOf, recoveryLock, readControl, recordTerminalLaunch } = ctx.helpers;
+  // --headless is --mode headless everywhere this command goes: the preview, the hub and the conductor path.
+  if (args.includes("--headless") && !args.includes("--mode")) args.splice(args.indexOf("--headless"), 1, "--mode", "headless");
+  if (args.includes("--print-command") || args.includes("--dry-run")) {
+    try { return console.log(JSON.stringify(launcherPreview("pi", args, cwd, stateDir, unattendedEnv), null, 2)); }
+    catch { fail("cannot preview launch: invalid arguments or configuration (details withheld to protect credentials)"); }
+  }
+  const flags = parsePiFlags(args, fail);
+  // #269: with no flag, Pi's start mode decides, and that is its TUI unless a person set headless.
+  const options = { ...flags, mode: flags.mode ?? startModeOf(projectConfig().peers, "pi") };
+  if (flags.mode === undefined && options.mode === "tui" && !(process.stdin.isTTY && process.stdout.isTTY)) {
+    // The default asked for the TUI and there is no terminal here (the console's command line, a script): the hub
+    // opens one, or says how to. It is never downgraded to headless. The fixed command carries no option, so one
+    // that was given needs a terminal of its own. An explicit --mode tui is taken at its word, as before.
+    if (Object.keys(flags).length) fail("Pi's TUI needs a terminal, and these options are not passed to one the hub opens: run this in a terminal, or add --mode headless");
+    const hub = await connect();
+    try {
+      const reply = await hub.request({ t: "peer_start", peer: "pi" }, 35_000);
+      if (reply.ok !== true) {
+        const error = String(reply.error ?? "pi start refused");
+        fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "peer_start"/i.test(error) ? `${error}; upgrade the running hub, or run ahub pi --mode headless` : error);
+      }
+      return console.log(reply.already ? "pi is already attached" : reply.opened ? `pi: opened a terminal running ${reply.command}; it attaches when its TUI is ready` : 'pi attached (headless). Talk to it with: ahub say @pi "..."');
+    } finally { hub.close(); }
+  }
+  // #215: as for Codex, a TUI launch by the recovery operation holding the lock records itself before the hub round
+  // trip, so a resume in that window never reads it as gone; an ordinary launch records only after the hub accepted it.
+  const recovering = options.mode === "tui" && !!process.env.AGENTHUB_RECOVERY_OPERATION && process.env.AGENTHUB_RECOVERY_OPERATION === recoveryLock();
+  const before = readControl(stateDir);
+  if (recovering && before?.instanceId) await recordTerminalLaunch("pi", cwd, stateDir, before.instanceId);
+  const hub = await connect();
+  const res = await hub.request({ t: "start", peer: "pi", args: options, operationId: process.env.AGENTHUB_RECOVERY_OPERATION });
+  hub.close();
+  if (!res.ok) fail(res.error);
+  if (options.mode === "tui") {
+    const launch = res.launch;
+    if (!launch || typeof launch.cmd !== "string" || !Array.isArray(launch.args) || !launch.args.every((a: unknown) => typeof a === "string") || !launch.env || typeof launch.env !== "object") fail("Pi TUI launch metadata was not verified");
+    const launchEnv = { ...(launch.env as NodeJS.ProcessEnv) };
+    delete launchEnv.AGENTHUB_RECOVERY_OPERATION;
+    delete launchEnv.AGENTHUB_UNATTENDED;
+    const control = readControl(stateDir);
+    if (!recovering && control?.instanceId) await recordTerminalLaunch("pi", cwd, stateDir, control.instanceId);
+    return execWithEnv(launch.cmd, launch.args, launchEnv);
+  }
+  console.log(res.already ? "pi is already attached" : 'pi attached (headless). Talk to it with: ahub say @pi "..."');
+}

package/src/adapters/definitions/native-cli-entry-qwen.ts

@@ -0,0 +1,20 @@
+import type { NativeCliEntryContext } from "./native-cli-entry-types.ts";
+
+export async function runQwenEntry(ctx: NativeCliEntryContext): Promise<void> {
+  const { args, cwd, stateDir, unattendedEnv, connect, fail, takeFlags } = ctx;
+  const { launcherPreview } = ctx.helpers;
+  if (args.includes("--print-command") || args.includes("--dry-run")) {
+    try { return console.log(JSON.stringify(launcherPreview("qwen", args, cwd, stateDir, unattendedEnv), null, 2)); }
+    catch { fail("cannot preview Qwen launch: invalid arguments or configuration (details withheld)"); }
+  }
+  const { one, rest } = takeFlags(args, ["--mode", "--model", "--session-id"], []);
+  const adapter = ctx.definition;
+  if (one["--session-id"] !== undefined && !adapter.session.crashIdentity?.({ sessionId: one["--session-id"] }).sessionId) fail("invalid Qwen session identity");
+  if (rest.length || (one["--mode"] !== undefined && !(adapter.start.forms as readonly string[]).includes(one["--mode"]))) fail("Qwen TUI is not offered before verification; usage: ahub qwen [--mode headless] [--model <alias>] [--session-id <id>]");
+  const hub = await connect();
+  try {
+    const reply = await hub.request({ t: "start", peer: "qwen", args: { mode: "headless", ...(one["--model"] ? { model: one["--model"] } : {}), ...(one["--session-id"] ? { sessionId: one["--session-id"] } : {}) }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 35_000);
+    if (!reply.ok) fail(reply.error);
+    console.log(reply.already ? "qwen is already attached" : "qwen attached (headless); use ahub say @qwen and the console for approvals");
+  } finally { hub.close(); }
+}

package/src/adapters/definitions/native-cli-entry-types.ts

@@ -0,0 +1,40 @@
+import type { HubConfig } from "../../hub/daemon.ts";
+import type { ControlClient } from "../../hub/control-client.ts";
+import type { AdapterDefinition } from "../registry-types.ts";
+
+/** Private static builtin relocation ports. The CLI binds identity, project and authority before invocation. */
+export interface NativeCliEntryContext {
+  args: string[]; cwd: string; stateDir: string; cliDir: string; unattendedEnv: boolean; definition: AdapterDefinition;
+  projectConfig(): HubConfig;
+  connect(): Promise<ControlClient>;
+  fail(message: string): never;
+  exec(bin: string, argv: string[], tool?: "claude" | "codex" | "kimi"): never;
+  execWithEnv(bin: string, argv: string[], extra: NodeJS.ProcessEnv): never;
+  takeFlags(argv: string[], single: string[], repeated: string[]): { one: Record<string, string>; many: Record<string, string[]>; rest: string[] };
+  helpers: {
+    launcherPreview: typeof import("../../cli/preview.ts").launcherPreview;
+    readControl: typeof import("../../hub/control-client.ts").readControl;
+    recordTerminalLaunch: typeof import("../../cli/terminal-recovery.ts").recordTerminalLaunch;
+    recoveryLock: typeof import("../../hub/recovery-store.ts").recoveryLock;
+    processSignature: typeof import("../../pi/process-signature.ts").processSignature;
+    buildLaunch: typeof import("../../cli/launch.ts").buildLaunch;
+    claudeObservationHooks: typeof import("../../cli/launch.ts").claudeObservationHooks;
+    recordClaudeLaunch: typeof import("../../cli/launch.ts").recordClaudeLaunch;
+    cleanupStaleClaudeSettings: typeof import("../../cli/launch.ts").cleanupStaleClaudeSettings;
+    cleanupClaudeSettings: typeof import("../../cli/launch.ts").cleanupClaudeSettings;
+    nativeLaunchEnv: typeof import("../../cli/launch.ts").nativeLaunchEnv;
+    runClaudeLaunch: typeof import("../../cli/launch.ts").runClaudeLaunch;
+    childEnv: typeof import("../../hub/child-process.ts").childEnv;
+    qwenSessionId: typeof import("../../hub/crash.ts").qwenSessionId;
+    configureJcodeMcp: typeof import("../../cli/jcode-mcp.ts").configureJcodeMcp;
+    configureKimiMcp: typeof import("../../cli/kimi-mcp.ts").configureKimiMcp;
+    buildKimiTuiLaunch: typeof import("../../cli/launch.ts").buildKimiTuiLaunch;
+    startModeOf: typeof import("../../hub/start-mode.ts").startModeOf;
+  };
+}
+export interface BuiltinCliEntry {
+  command: string;
+  /** Original CLI guard timing: previews precede it; Pi/local retain their daemon-enforced start admission. */
+  lifecycleAdmission: boolean;
+  execute(context: NativeCliEntryContext): Promise<void>;
+}

package/src/adapters/definitions/native-cli-entry.ts

@@ -0,0 +1,19 @@
+import type { BuiltinCliEntry } from "./native-cli-entry-types.ts";
+import { runClaudeEntry } from "./native-cli-entry-claude.ts";
+import { runCodexEntry } from "./native-cli-entry-codex.ts";
+import { runJcodeEntry } from "./native-cli-entry-jcode.ts";
+import { runQwenEntry } from "./native-cli-entry-qwen.ts";
+import { runKimiEntry } from "./native-cli-entry-kimi.ts";
+import { runPiEntry } from "./native-cli-entry-pi.ts";
+import { runLocalEntry } from "./native-cli-entry-local.ts";
+
+// Fixed trusted builtins only. No project configuration, caller payload or external module can register an entry.
+export const builtinCliEntries: readonly BuiltinCliEntry[] = Object.freeze([
+  { command: "claude", lifecycleAdmission: true, execute: runClaudeEntry },
+  { command: "codex", lifecycleAdmission: true, execute: runCodexEntry },
+  { command: "jcode", lifecycleAdmission: true, execute: runJcodeEntry },
+  { command: "qwen", lifecycleAdmission: true, execute: runQwenEntry },
+  { command: "kimi", lifecycleAdmission: true, execute: runKimiEntry },
+  { command: "pi", lifecycleAdmission: false, execute: runPiEntry },
+  { command: "local", lifecycleAdmission: false, execute: runLocalEntry },
+]);

package/src/adapters/definitions/native-cli-jcode-mcp.ts

@@ -0,0 +1,58 @@
+import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { hubGitSync } from "../../hub/git.ts";
+
+export const JCODE_MCP_FILE = ".jcode/mcp.json", JCODE_MCP_NAME = "agent-hub-jcode";
+type Document = Record<string, unknown>;
+const object = (value: unknown): value is Document => !!value && typeof value === "object" && !Array.isArray(value);
+
+function document(file: string): Document {
+  const stat = lstatSync(file, { throwIfNoEntry: false });
+  if (!stat) return {};
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 256 * 1024) throw new Error("Jcode MCP configuration must be a bounded regular file, not a link");
+  let value: unknown; try { value = JSON.parse(readFileSync(file, "utf8")); } catch { throw new Error("Jcode MCP configuration is invalid JSON"); }
+  if (!object(value)) throw new Error("Jcode MCP configuration must be an object");
+  if (value.servers !== undefined && value.mcpServers !== undefined) throw new Error("Jcode MCP configuration has ambiguous server maps");
+  for (const key of ["servers", "mcpServers"]) if (value[key] !== undefined && !object(value[key])) throw new Error("Jcode MCP server map must be an object");
+  return value;
+}
+const map = (doc: Document): Document => (doc.mcpServers ?? doc.servers ?? {}) as Document;
+const owned = (entry: unknown, cwd: string): entry is Document => object(entry) && object(entry.env) && entry.env.AGENTHUB_MODE === "tools" && entry.env.AGENTHUB_PEER_ID === "jcode" && entry.env.AGENTHUB_PROJECT_DIR === cwd;
+
+export function jcodeMcpEntry(cwd: string, stateDir: string, bundle: string) {
+  return { command: "bun", args: ["run", bundle], shared: false, env: { AGENTHUB_MODE: "tools", AGENTHUB_DELIVERY_ONLY: "true", AGENTHUB_PEER_ID: "jcode", AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } };
+}
+/** The native loader reads later project files last. Never shadow a foreign definition. */
+function inspect(cwd: string): Document {
+  const directory = lstatSync(join(cwd, ".jcode"), { throwIfNoEntry: false });
+  if (directory && (!directory.isDirectory() || directory.isSymbolicLink())) throw new Error(".jcode must be a project directory, not a link");
+  for (const relative of [".mcp.json", ".claude/mcp.json"]) {
+    const parent = relative.startsWith(".claude/") ? lstatSync(join(cwd, ".claude"), { throwIfNoEntry: false }) : undefined;
+    if (parent?.isSymbolicLink()) throw new Error("Jcode MCP override layer is a link; inspect it before launching");
+    if (Object.hasOwn(map(document(join(cwd, relative))), JCODE_MCP_NAME)) throw new Error("a later project MCP layer overrides agent-hub-jcode; resolve it in your editor");
+  }
+  return document(join(cwd, JCODE_MCP_FILE));
+}
+export function jcodeMcpReady(cwd: string, stateDir: string, bundle: string): boolean {
+  const entry = map(inspect(cwd))[JCODE_MCP_NAME];
+  return JSON.stringify(entry) === JSON.stringify(jcodeMcpEntry(cwd, stateDir, bundle));
+}
+/** Only the console launcher calls this; daemon starts use jcodeMcpReady read-only. */
+export function configureJcodeMcp(cwd: string, stateDir: string, bundle: string, remove = false): { changed: boolean; tracked: boolean } {
+  const current = inspect(cwd), servers = { ...map(current) }, existing = servers[JCODE_MCP_NAME];
+  if (existing !== undefined && !owned(existing, cwd)) throw new Error("agent-hub-jcode is a foreign MCP entry; it was not changed");
+  if (remove) delete servers[JCODE_MCP_NAME]; else servers[JCODE_MCP_NAME] = jcodeMcpEntry(cwd, stateDir, bundle);
+  const key = current.servers !== undefined ? "servers" : "mcpServers";
+  const next = { ...current, ...(current[key] !== undefined || !remove ? { [key]: servers } : {}) };
+  const tracked = hubGitSync(["ls-files", "--error-unmatch", "--", JCODE_MCP_FILE], { cwd, encoding: "utf8", timeout: 3000 }).status === 0;
+  if (JSON.stringify(next) === JSON.stringify(current)) return { changed: false, tracked };
+  mkdirSync(join(cwd, ".jcode"), { recursive: true });
+  const file = join(cwd, JCODE_MCP_FILE), temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    const fd = openSync(temporary, "wx", 0o600);
+    try { writeFileSync(fd, `${JSON.stringify(next, null, 2)}\n`); } finally { closeSync(fd); }
+    renameSync(temporary, file);
+  } finally { if (existsSync(temporary)) unlinkSync(temporary); }
+  return { changed: true, tracked };
+}

package/src/adapters/definitions/native-cli-launch-common.ts

@@ -0,0 +1,17 @@
+import type { LaunchContext, LaunchPlan } from "../registry-types.ts";
+import type { Launch } from "../../cli/launch.ts";
+import { UNATTENDED_WARNING } from "../../cli/launch.ts";
+import { shellQuote } from "../../cli/shell-quote.ts";
+
+export interface NativeLaunchPolicy { hubSwitches: readonly string[]; ownedFlags: readonly string[] }
+export function nativeLaunchArguments(tool: string, ctx: LaunchContext, policy: NativeLaunchPolicy) {
+  const passthrough = ctx.userArgs.filter(arg => !policy.hubSwitches.includes(arg));
+  const dup = passthrough.find(arg => policy.ownedFlags.some(flag => arg === flag || arg.startsWith(`${flag}=`)));
+  if (dup) throw new Error(`${dup} is managed by the hub; use "hub ${tool} --unattended" or drop the flag`);
+  const unattended = ctx.unattended || ctx.userArgs.includes("--unattended");
+  return { passthrough, unattended, warning: unattended ? { warning: UNATTENDED_WARNING } : {} };
+}
+export function nativeLaunchPlan(launch: Launch, ctx: LaunchContext): LaunchPlan {
+  const argv = [launch.cmd, ...launch.args];
+  return { ...launch, metadata: { packageEntrypoint: ctx.entrypoint, argv, env: {}, command: argv.map(shellQuote).join(" ") } };
+}

package/src/adapters/definitions/native-cli-pi.ts

@@ -0,0 +1,33 @@
+export function parsePiFlags(args: string[], fail: (message: string) => never): { mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; model?: string; sessionId?: string; sessionFile?: string; replaceSession?: boolean } {
+  const usage = "usage: ahub pi [--mode headless|tui | --headless] [--backend auto|dgx|mlx] [--model <alias>] [--session-id <id> | --session-file <path>] [--replace-session --session-file <path>]";
+  if (args.includes("--headless")) {
+    if (args.includes("--mode")) fail(usage);
+    args.splice(args.indexOf("--headless"), 1, "--mode", "headless");
+  }
+  for (const flag of ["--mode", "--backend", "--model", "--session-id", "--session-file"]) {
+    const index = args.indexOf(flag);
+    if (index >= 0 && (!args[index + 1] || args[index + 1]!.startsWith("--"))) fail(`${flag} needs a value`);
+  }
+  const mode = (args.includes("--mode") ? args[args.indexOf("--mode") + 1] : undefined) as string | undefined;
+  const backend = (args.includes("--backend") ? args[args.indexOf("--backend") + 1] : undefined) as string | undefined;
+  const model = args.includes("--model") ? args[args.indexOf("--model") + 1] : undefined;
+  const sessionId = args.includes("--session-id") ? args[args.indexOf("--session-id") + 1] : undefined;
+  const sessionFile = args.includes("--session-file") ? args[args.indexOf("--session-file") + 1] : undefined;
+  const replaceSession = args.includes("--replace-session");
+  if (replaceSession && (!sessionFile || sessionId)) fail("--replace-session requires --session-file, without --session-id");
+  const valueFlags = new Set(["--mode", "--backend", "--model", "--session-id", "--session-file"]);
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--replace-session") continue;
+    if (!valueFlags.has(args[i]!)) fail(`unknown Pi option: ${args[i]}`);
+    i++;
+  }
+  if ((mode !== undefined && !["headless", "tui"].includes(mode)) || (backend !== undefined && !["auto", "dgx", "mlx"].includes(backend)) || (sessionId && sessionFile)) fail(usage);
+  return { ...(replaceSession ? { replaceSession: true } : {}), ...(mode ? { mode: mode as "headless" | "tui" } : {}), ...(backend ? { backend: backend as "auto" | "dgx" | "mlx" } : {}), ...(model ? { model } : {}), ...(sessionId ? { sessionId } : {}), ...(sessionFile ? { sessionFile } : {}) };
+}
+
+/** The conductor can repeat only the selected form; native startup options remain person-only. */
+export function piConductorStartArgs(args: string[]): { mode?: "headless" | "tui" } | Error {
+  if (args.length === 1 && args[0] === "--headless") args.splice(0, 1, "--mode", "headless");
+  if (args.length && !(args.length === 2 && args[0] === "--mode" && ["headless", "tui"].includes(args[1] ?? ""))) return new Error("conductor starts accept no launch overrides; use ahub pi [--mode headless|tui]");
+  return args[1] ? { mode: args[1] as "headless" | "tui" } : {};
+}

package/src/adapters/definitions/native-cli-preview-claude.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Launch } from "../../cli/launch.ts";
+import { REDACTED, publicArg, previewState, finishPreview, type NativePreviewContext } from "./native-cli-preview-common.ts";
+
+export function previewClaude(ctx: NativePreviewContext) {
+  const { args, cwd, stateDir, cliDir, unattended, config } = ctx;
+  const { buildLaunch, claudeObservationHooks } = ctx.helpers;
+  const state = previewState(args, ctx.baseEnvNames), { unresolved } = state;
+  let envNames = state.envNames;
+  let launch: Launch;
+  let original: { command?: string; refreshInterval?: number; padding?: number } | undefined;
+  for (const file of [join(cwd, ".claude/settings.local.json"), join(cwd, ".claude/settings.json"), join(process.env.HOME ?? "", ".claude/settings.json")]) {
+    try { original ??= JSON.parse(readFileSync(file, "utf8")).statusLine; } catch { /* optional */ }
+  }
+  // Build with original inputs so channel selection and owned-flag validation match normal launch.
+  const facts = claudeObservationHooks(config, { script: join(cliDir, "facts-hook.ts"), stateDir });
+  launch = buildLaunch("claude", args, { preview: true, unattended, statusLine: { script: join(cliDir, "statusline-tee.ts"), stateDir, ...(original ? { original: { command: original.command ? REDACTED : "", ...(typeof original.refreshInterval === "number" && Number.isFinite(original.refreshInterval) ? { refreshInterval: original.refreshInterval } : {}), ...(typeof original.padding === "number" && Number.isFinite(original.padding) ? { padding: original.padding } : {}) } } : {}) }, ...(facts ? { facts } : {}) });
+  // Merged caller settings change the native argument count. Rebuild a redacted preview,
+  // retaining the managed hooks but never serializing caller settings or their file path.
+  const safeArgs = args.map((arg, i) => {
+    if (args[i - 1] === "--settings") return "{}";
+    if (arg.startsWith("--settings=")) return "--settings={}";
+    if (["--unattended", "--safe", "--new"].includes(arg)) return arg;
+    return publicArg(arg);
+  });
+  const publicLaunch = buildLaunch("claude", safeArgs, { preview: true, unattended, statusLine: { script: join(cliDir, "statusline-tee.ts"), stateDir,
+    ...(original ? { original: { command: original.command ? REDACTED : "", ...(typeof original.refreshInterval === "number" && Number.isFinite(original.refreshInterval) ? { refreshInterval: original.refreshInterval } : {}), ...(typeof original.padding === "number" && Number.isFinite(original.padding) ? { padding: original.padding } : {}) } } : {}) }, facts });
+  publicLaunch.args.splice(0, 2, ...launch.args.slice(0, 2)); // channel selection was verified against the original MCP config
+  launch = publicLaunch;
+
+  envNames.push("AGENTHUB_CHANNEL");
+  envNames.push("AGENTHUB_INSTANCE_ID", "AGENTHUB_LAUNCH_ID");
+  unresolved.push({ field: "env.AGENTHUB_INSTANCE_ID", reason: "injected when an existing daemon instance is read at launch; preview does not read runtime state" });
+  unresolved.push({ field: "env.AGENTHUB_LAUNCH_ID", reason: "allocated only for a verified Orca terminal launch; preview does not query Orca, allocate identity or write launch records" });
+  return finishPreview(ctx, launch, envNames, unresolved, undefined, launch.args.includes("--settings") ? launch.args[launch.args.indexOf("--settings") + 1] : undefined);
+}

package/src/adapters/definitions/native-cli-preview-codex.ts

@@ -0,0 +1,20 @@
+import type { Launch } from "../../cli/launch.ts";
+import { REDACTED, UNRESOLVED, publicArg, previewState, finishPreview, type NativePreviewContext } from "./native-cli-preview-common.ts";
+
+export function previewCodex(ctx: NativePreviewContext) {
+  const { args, unattended, config } = ctx;
+  const { buildLaunch } = ctx.helpers;
+  const state = previewState(args, ctx.baseEnvNames), { unresolved } = state;
+  let envNames = state.envNames;
+  let launch: Launch;
+  // A fresh native proxy is assigned by start, never guessed from an old status file.
+  launch = buildLaunch("codex", args, { unattended, proxyUrl: UNRESOLVED, codexBin: config.codex_bin === "codex" ? "codex" : REDACTED });
+  const passthrough = args.filter(arg => !["--unattended", "--safe", "--new"].includes(arg));
+  launch.args = launch.args.slice(0, launch.args.length - passthrough.length).concat(passthrough.map(publicArg));
+  unresolved.push({ field: "proxyUrl", reason: "assigned when the native adapter starts; preview does not start it" });
+
+  envNames.push("AGENTHUB_INSTANCE_ID", "AGENTHUB_LAUNCH_ID");
+  unresolved.push({ field: "env.AGENTHUB_INSTANCE_ID", reason: "injected when a verified Orca terminal launch is recorded against the daemon; preview does not record it" });
+  unresolved.push({ field: "env.AGENTHUB_LAUNCH_ID", reason: "allocated only for a verified Orca terminal launch; preview does not query Orca, allocate identity or write launch records" });
+  return finishPreview(ctx, launch, envNames, unresolved, undefined);
+}

package/src/adapters/definitions/native-cli-preview-common.ts

@@ -0,0 +1,57 @@
+import type { loadConfig } from "../../hub/daemon.ts";
+import type { AdapterDefinition } from "../registry-types.ts";
+import type { Launch } from "../../cli/launch.ts";
+
+export const REDACTED = "[redacted]";
+export const UNRESOLVED = "[unresolved]";
+/** Fixed, pure/read-only CLI planning helpers. No command executor, control client or writer enters this port. */
+export interface NativePreviewHelpers {
+  buildLaunch: typeof import("../../cli/launch.ts").buildLaunch;
+  claudeObservationHooks: typeof import("../../cli/launch.ts").claudeObservationHooks;
+  buildKimiLaunch: typeof import("../../cli/launch.ts").buildKimiLaunch;
+  buildKimiTuiLaunch: typeof import("../../cli/launch.ts").buildKimiTuiLaunch;
+  nativeLaunchEnv: typeof import("../../cli/launch.ts").nativeLaunchEnv;
+  childEnv: typeof import("../../hub/child-process.ts").childEnv;
+  startModeOf: typeof import("../../hub/start-mode.ts").startModeOf;
+  kimiMcpPlan: typeof import("../../cli/kimi-mcp.ts").kimiMcpPlan;
+  jcodeCommand: typeof import("../jcode.ts").jcodeCommand;
+  qwenSessionId: typeof import("../../hub/crash.ts").qwenSessionId;
+  relayModelIds: typeof import("../../models/relay.ts").relayModelIds;
+  buildPiLaunch: typeof import("../../pi/launch.ts").buildPiLaunch;
+}
+export interface NativePreviewContext {
+  tool: string; args: string[]; cwd: string; stateDir: string; cliDir: string; unattended: boolean;
+  config: ReturnType<typeof loadConfig>; definition: AdapterDefinition; baseEnvNames: string[]; helpers: NativePreviewHelpers;
+}
+export interface NativePreviewMetadata { mode: "tui" | "headless"; mcp: { file: string; action: string; changed: boolean; tracked: boolean } }
+export type NativePreviewBuilder = (ctx: NativePreviewContext) => NativePreview;
+export interface NativePreview {
+  tool: string; mode?: "tui" | "headless"; mcp?: NativePreviewMetadata["mcp"];
+  cmd: string; args: string[]; settings: string | undefined; envNames: string[]; warning?: string;
+  unresolved: { field: string; reason: string }[]; redaction: string; needs: string[];
+}
+/** Arbitrary native arguments can contain secrets even without a credential-looking key. */
+export function publicArg(arg: string): string {
+  const flags = new Set(["--settings", "--model", "--mcp-config", "--session-id", "--session-file", "--resume", "--continue", "--print", "--safe", "--new"]);
+  const key = arg.split("=", 1)[0]!;
+  return flags.has(key) ? (arg.includes("=") ? key + "=" + REDACTED : key) : REDACTED;
+}
+export function nativeCommand(command: string[], trusted: string[]): string[] {
+  return command.map((value, i) => value === trusted[i] ? value : REDACTED);
+}
+
+export function previewState(args: readonly string[], baseEnvNames: readonly string[]) {
+  const unresolved: { field: string; reason: string }[] = [];
+  const envNames = [...baseEnvNames];
+  const value = (flag: string) => {
+    const at = args.indexOf(flag);
+    if (at < 0) return undefined;
+    const next = args[at + 1];
+    if (!next || next.startsWith("--")) throw new Error("missing option value");
+    return next;
+  };
+  return { unresolved, envNames, value };
+}
+export function finishPreview(ctx: NativePreviewContext, launch: Launch, envNames: string[], unresolved: NativePreview["unresolved"], metadata?: NativePreviewMetadata, settings?: string): NativePreview {
+  return { tool: ctx.tool, ...(metadata ?? {}), cmd: launch.cmd, args: launch.args, settings, envNames: [...new Set(envNames)].sort(), ...(launch.warning ? { warning: launch.warning } : {}), unresolved, redaction: "Arbitrary user arguments, settings, commands and configured executable overrides are redacted. Environment values are never displayed.", needs: ["Native executable, accounts and runtime readiness are not checked."] };
+}

package/src/adapters/definitions/native-cli-preview-jcode.ts

@@ -0,0 +1,20 @@
+import type { Launch } from "../../cli/launch.ts";
+import { REDACTED, UNRESOLVED, nativeCommand, previewState, finishPreview, type NativePreviewContext } from "./native-cli-preview-common.ts";
+
+export function previewJcode(ctx: NativePreviewContext) {
+  const { args, config } = ctx;
+  const { jcodeCommand, qwenSessionId } = ctx.helpers;
+  const state = previewState(args, ctx.baseEnvNames), { unresolved, value } = state;
+  let envNames = state.envNames;
+  let launch: Launch;
+  const mode = value("--mode") ?? "headless", model = value("--model"), profile = value("--provider-profile"), session = value("--session-id");
+  if (mode !== "headless") throw new Error("Jcode TUI driving is unverified");
+  for (let i = 0; i < args.length; i += 2) if (!["--model", "--mode", "--provider-profile", "--session-id"].includes(args[i]!) || !args[i + 1]) throw new Error("unknown Jcode option");
+  if (session !== undefined && !qwenSessionId(session)) throw new Error("invalid Jcode session identity");
+  const cmd = jcodeCommand(nativeCommand(config.jcode_cmd, ["jcode"]), "acp", UNRESOLVED, UNRESOLVED, model ? REDACTED : undefined, profile || config.jcode_provider_profile ? REDACTED : undefined);
+  launch = { cmd: cmd[0]!, args: cmd.slice(1) };
+  unresolved.push({ field: "ownedDaemon", reason: "private daemon/socket and source-pinned native identity verified at start; preview starts nothing" });
+  unresolved.push({ field: "hubTools", reason: "project MCP bridge required; native tool-call receipt remains unverified" });
+
+  return finishPreview(ctx, launch, envNames, unresolved, undefined);
+}

package/src/adapters/definitions/native-cli-preview-kimi.ts

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+import type { Launch } from "../../cli/launch.ts";
+import { REDACTED, nativeCommand, previewState, finishPreview, type NativePreviewContext, type NativePreviewMetadata } from "./native-cli-preview-common.ts";
+
+export function previewKimi(ctx: NativePreviewContext) {
+  const { args, cwd, stateDir, cliDir, config } = ctx;
+  const { childEnv, startModeOf, buildKimiLaunch, buildKimiTuiLaunch, nativeLaunchEnv, kimiMcpPlan } = ctx.helpers;
+  const state = previewState(args, ctx.baseEnvNames), { unresolved, value } = state;
+  let envNames = state.envNames;
+  let launch: Launch;
+  let kimiMetadata: NativePreviewMetadata | undefined;
+  const model = value("--model");
+  const mode = value("--mode") ?? startModeOf(config.peers, "kimi");
+  if (mode !== "tui" && mode !== "headless") throw new Error("invalid Kimi mode");
+  for (let i = 0; i < args.length; i += 2) if (!["--model", "--mode"].includes(args[i]!) || !args[i + 1]) throw new Error("unknown Kimi option");
+  if (mode === "headless") {
+    launch = buildKimiLaunch(nativeCommand(config.kimi_cmd, ["kimi", "acp"]), model ? REDACTED : undefined);
+    unresolved.push({ field: "sessionId", reason: "ACP session identity is available only after native initialization" });
+  } else {
+    const native = buildKimiTuiLaunch(config.kimi_cmd, model ? REDACTED : undefined);
+    launch = { ...native, cmd: native.cmd === "kimi" ? "kimi" : REDACTED, args: native.args.map(arg => arg === "--model" || arg === REDACTED ? arg : REDACTED) };
+    envNames = Object.keys(nativeLaunchEnv("kimi", childEnv())).concat(["AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR"]);
+  }
+  const { file, action, changed, tracked } = kimiMcpPlan(cwd, stateDir, join(cliDir, "../../plugins/agent-hub/server.js"), mode);
+  kimiMetadata = { mode, mcp: { file, action, changed, tracked } };
+
+  return finishPreview(ctx, launch, envNames, unresolved, kimiMetadata);
+}