@staix/agent-hub 0.12.33 → 0.12.35

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);
+}

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

@@ -0,0 +1,36 @@
+import { join, resolve } from "node:path";
+import type { Launch } from "../../cli/launch.ts";
+import { REDACTED, UNRESOLVED, nativeCommand, previewState, finishPreview, type NativePreviewContext } from "./native-cli-preview-common.ts";
+
+export function previewPi(ctx: NativePreviewContext) {
+  const { args, stateDir, cliDir, config } = ctx;
+  const { relayModelIds, buildPiLaunch, startModeOf } = ctx.helpers;
+  const state = previewState(args, ctx.baseEnvNames), { unresolved, value } = state;
+  let envNames = state.envNames;
+  let launch: Launch;
+  const mode = value("--mode") ?? startModeOf(config.peers, "pi"); // #269: the same default `ahub pi` takes
+  const backend = value("--backend") ?? config.pi.backend;
+  if (!["headless", "tui"].includes(mode) || !["auto", "dgx", "mlx"].includes(backend) || (value("--session-id") && value("--session-file"))) throw new Error("invalid Pi options");
+  if (args.includes("--replace-session") && (!value("--session-file") || value("--session-id"))) throw new Error("--replace-session requires --session-file, without --session-id");
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--replace-session") continue;
+    if (!["--mode", "--backend", "--model", "--session-id", "--session-file"].includes(args[i]!) || !value(args[i]!)) throw new Error("unknown Pi option");
+    i++;
+  }
+  if (args.includes("--replace-session")) unresolved.push({ field: "session replacement", reason: "requires a person, a validated managed file and an offline settled owner at runtime; preview changes nothing" });
+  const models = relayModelIds({ enableHubAuto: true, mlx: config.mlx.enabled === false ? undefined : config.mlx, mlxAlias: "mlx/fast", allowedDGXmodels: { "dgx/coding": config.pi.dgx_coding, "dgx/fast": config.pi.dgx_fast } });
+  const pi = buildPiLaunch({
+    stateDir, cmd: nativeCommand(config.pi.cmd, ["pi"]), mode: mode as "headless" | "tui", backend: backend as "auto" | "dgx" | "mlx",
+    ...(value("--model") ? { model: REDACTED } : {}),
+    ...(value("--session-id") ? { sessionId: REDACTED } : {}),
+    ...(value("--session-file") ? { sessionFile: REDACTED } : {}),
+    relay: { url: UNRESOLVED, token: UNRESOLVED, models: models.map(id => ({ id })) },
+    tools: [], preamble: REDACTED, maxSteps: config.pi.max_steps,
+  }, {}, resolve(join(cliDir, "../pi/extension.ts")), UNRESOLVED, UNRESOLVED);
+  launch = pi;
+  envNames = Object.keys(pi.env).concat(["PATH", "HOME", "USER", "SHELL", "TMPDIR", "TERM", "TERM_PROGRAM", "LANG", "LC_ALL", "LC_CTYPE", "NO_COLOR", "CODEX_HOME"].filter(key => process.env[key] !== undefined));
+  if (mode === "tui") envNames.push("AGENTHUB_STATE_DIR", "AGENTHUB_PROJECT_DIR");
+  unresolved.push({ field: "bridge/relay endpoints and owner credentials", reason: "assigned at runtime; preview does not bind a server or start a model" });
+  if (!value("--session-id") && !value("--session-file")) unresolved.push({ field: "sessionId", reason: "new native session identity is not allocated by preview" });
+  return finishPreview(ctx, launch, envNames, unresolved, undefined);
+}

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

@@ -0,0 +1,22 @@
+import { join } from "node:path";
+import type { Launch } from "../../cli/launch.ts";
+import { REDACTED, UNRESOLVED, nativeCommand, previewState, finishPreview, type NativePreviewContext } from "./native-cli-preview-common.ts";
+
+export function previewQwen(ctx: NativePreviewContext) {
+  const { tool, args, cwd, stateDir, cliDir, config } = ctx;
+  const state = previewState(args, ctx.baseEnvNames), { unresolved, value } = state;
+  let envNames = state.envNames;
+  let launch: Launch;
+  const mode = value("--mode") ?? "headless", model = value("--model");
+  const adapter = ctx.definition;
+  if (!(adapter.start.forms as readonly string[]).includes(mode)) throw new Error("Qwen TUI is not offered before verification");
+  for (let i = 0; i < args.length; i += 2) if (!["--model", "--mode", "--session-id"].includes(args[i]!) || !args[i + 1]) throw new Error("unknown Qwen option");
+  const sessionId = value("--session-id");
+  if (sessionId !== undefined && !adapter.session.crashIdentity?.({ sessionId }).sessionId) throw new Error("invalid Qwen session identity");
+  if (sessionId) unresolved.push({ field: "sessionId", reason: "requested through ACP session/load at start; preview does not load or expose it" });
+  launch = adapter.start.launch({ instance: tool, form: "headless", projectRoot: cwd, stateDir, entrypoint: join(cliDir, "main.js"),
+    userArgs: [], unattended: false, env: {}, preview: true, nativeCommand: nativeCommand(config.qwen_cmd, ["qwen", "--acp"]), model: model ? REDACTED : undefined });
+  unresolved.push({ field: "nativeIdentity", reason: "Qwen Code 0.25.0 identity and permission modes are checked at ACP initialization; preview starts nothing" });
+
+  return finishPreview(ctx, launch, envNames, unresolved, undefined);
+}

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

@@ -0,0 +1,16 @@
+import type { AdapterDefinition } from "../registry-types.ts";
+import type { NativePreviewBuilder } from "./native-cli-preview-common.ts";
+import { previewClaude } from "./native-cli-preview-claude.ts";
+import { previewCodex } from "./native-cli-preview-codex.ts";
+import { previewKimi } from "./native-cli-preview-kimi.ts";
+import { previewPi } from "./native-cli-preview-pi.ts";
+import { previewQwen } from "./native-cli-preview-qwen.ts";
+import { previewJcode } from "./native-cli-preview-jcode.ts";
+
+// Private implementations of the fixed builtin set; neither config nor an external definition can add callbacks.
+const previews: Readonly<Record<string, NativePreviewBuilder>> = Object.freeze({
+  claude: previewClaude, codex: previewCodex, kimi: previewKimi, pi: previewPi, qwen: previewQwen, jcode: previewJcode,
+});
+export function builtinPreview(definition: AdapterDefinition): NativePreviewBuilder | undefined {
+  return Object.hasOwn(previews, definition.kind) ? previews[definition.kind] : undefined;
+}

package/src/adapters/definitions/native-config-defaults.ts

@@ -0,0 +1,19 @@
+import { join } from "node:path";
+import type { HubConfig } from "../../hub/daemon.ts";
+import type { Routing } from "../../hub/routing.ts";
+
+/** Preserve the legacy config block order and shallow native merges. */
+export const NATIVE_CONFIG_BLOCKS = ["local", "pi"] as const;
+export function nativeConfigurationDefaults(ctx: { home: string; env: Readonly<Record<string, string | undefined>>; networkAllow: string[] }) {
+  return {
+    commands: { kimi_cmd: ["kimi", "acp"], qwen_cmd: ["qwen", "--acp"], jcode_cmd: ["jcode"], jcode_home: ctx.env.JCODE_HOME ?? join(ctx.home, ".jcode"), jcode_provider_profile: "" },
+    proxy: { codex_bin: "codex" },
+    rpc: { pi: { enabled: false, auto_start: false, cmd: ["pi"], backend: "auto" as const, dgx_coding: "coding", dgx_fast: "fast", max_steps: 30 } },
+    sandbox: { local: { deny: [] as string[], bash_network: false, network_allow: ctx.networkAllow, max_steps: 30, read_allow: [] as string[] } },
+  };
+}
+export function mergeNativeConfiguration(file: Record<string, any>, defaults: HubConfig): Pick<HubConfig, "local" | "pi"> {
+  return { local: { ...defaults.local, ...file.local }, pi: { ...defaults.pi, ...file.pi } };
+}
+/** The published RPC relay stays bound while other routing leaves are reloaded. */
+export function retainNativeRouting(running: Routing): Pick<Routing, "pi"> { return { pi: running.pi }; }

package/src/adapters/definitions/native-config-policy.ts

@@ -0,0 +1,35 @@
+import type { NativeConfigCheck, NativeConfigValidators } from "../registry-types.ts";
+import type { SettingDef } from "../../hub/settings.ts";
+
+/** Native config uses the host's checked schema vocabulary, retaining its shape/path introspection. */
+export function piConfigSchema(v: NativeConfigValidators): Record<string, NativeConfigCheck> {
+  return { pi: v.block({ enabled: v.bool, auto_start: v.bool, cmd: v.argv, backend: v.words(["auto", "dgx", "mlx"]), dgx_coding: v.text, dgx_fast: v.text, max_steps: v.number(1, 1_000_000, true) }) };
+}
+export function localConfigSchema(v: NativeConfigValidators): Record<string, NativeConfigCheck> {
+  return { local: v.block({ deny: v.strings, bash_network: (value, key) => { if (value !== "direct") v.bool(value, key); }, network_allow: v.strings, max_steps: v.number(1, 1_000_000, true), read_allow: v.strings }) };
+}
+export function piRoutingSchema(v: NativeConfigValidators): Record<string, NativeConfigCheck> {
+  return { pi: v.block({ dgx_max_context_tokens: v.number(), mlx_max_context_tokens: v.number(), efficient_wait_ms: v.number(0, 119999) }) };
+}
+export function localRoutingSchema(v: NativeConfigValidators): Record<string, NativeConfigCheck> {
+  return { local: v.block({ route: v.text, fixed_model: v.text }) };
+}
+export const PI_SETTINGS: readonly SettingDef[] = [
+  { key: "pi.auto_start", group: "Start", label: "Start Pi with the hub", type: "boolean", store: "config", applies: "next use", risk: "raises", floor: false, path: ["pi", "auto_start"] },
+];
+export const PI_RESTART_REASONS: Readonly<Record<string, string>> = {
+  "pi.dgx_coding": "Published Pi relay model catalogue requires a new daemon relay",
+  "pi.dgx_fast": "Published Pi relay model catalogue requires a new daemon relay",
+  "routing.pi": "Pi relay context and model publication are bound to the running relay",
+};
+export const LOCAL_RESTART_REASONS: Readonly<Record<string, string>> = {
+  "local.deny": "Existing native sessions retain their sandbox deny policy", "local.read_allow": "Existing native sessions retain their sandbox read grants",
+  "local.bash_network": "Existing sandbox and egress proxy contracts require a new instance", "local.network_allow": "Existing egress proxy ownership requires a new instance",
+};
+export function piEffectiveConfig(raw: Record<string, unknown>, fail: (key: string, reason: string) => never): void {
+  const object = (value: unknown, key: string): Record<string, unknown> => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return fail(key, "must be an object");
+    return value as Record<string, unknown>;
+  };
+  if (object(raw.mlx, "mlx").enabled === false && object(raw.pi, "pi").backend === "mlx") fail("pi.backend", "conflicts with disabled mlx");
+}

package/src/adapters/definitions/native-context.ts

@@ -0,0 +1,35 @@
+import type { ContextReading } from "../../hub/context-window.ts";
+
+export const nonnegative = (n: unknown): n is number => typeof n === "number" && Number.isFinite(n) && n >= 0;
+export const positive = (n: unknown): n is number => nonnegative(n) && n > 0;
+const record = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v);
+const object = (v: unknown): Record<string, unknown> => record(v) ? v : {};
+export function claudeContext(value: unknown, sessionId: string, measuredAt: number): ContextReading {
+  const c = object(value);
+  const current = object(c.current_usage);
+  const parts = [current.input_tokens, current.cache_creation_input_tokens, current.cache_read_input_tokens];
+  const window = positive(c.context_window_size) ? c.context_window_size : null;
+  const sum = c.current_usage != null && parts.every(nonnegative) ? parts.reduce<number>((sum, n) => sum + (n as number), 0) : null;
+  const tokens = nonnegative(sum) ? sum : null;
+  const used = record(c.current_usage) && tokens !== null && nonnegative(c.used_percentage) && c.used_percentage <= 100 && window !== null ? c.used_percentage / 100 : null;
+  return { source: "claude_statusline", sessionId, measuredAt, tokens, window, used };
+}
+export function codexContext(value: unknown, sessionId: string, measuredAt: number): ContextReading {
+  const c = object(value), last = object(c.last);
+  const window = positive(c.modelContextWindow) ? c.modelContextWindow : null;
+  const tokens = nonnegative(last.totalTokens) ? last.totalTokens : null;
+  return { source: "codex_token_usage", sessionId, measuredAt, tokens, window, used: tokens !== null && window !== null ? Math.min(1, tokens / window) : null };
+}
+/** An ACP `usage_update` of the `{ used, size }` shape (Kimi 2.x): context occupancy, not consumption (#167, #285). */
+export function acpContext(usage: { used: number; size: number }, sessionId: string, measuredAt: number): ContextReading {
+  const window = positive(usage.size) ? usage.size : null;
+  const tokens = nonnegative(usage.used) ? usage.used : null;
+  // If a report ever shows used > size, the fraction clamps so a bar renders; tokens keeps the reported number.
+  return { source: "acp_usage_update", sessionId, measuredAt, tokens, window, used: tokens !== null && window !== null ? Math.min(1, tokens / window) : null };
+}
+
+/** The coordinator supplies validated occupancy; malformed public input remains unknown. */
+export function acpContextValue(value: unknown, sessionId: string, measuredAt: number): ContextReading {
+  const raw = object(value);
+  return acpContext({ used: raw.used as number, size: raw.size as number }, sessionId, measuredAt);
+}

package/src/adapters/definitions/native-daemon-kimi.ts

@@ -0,0 +1,5 @@
+/** Kimi puts its optional model switch before the configured ACP subcommand. */
+export function kimiAcpCommand(command: readonly string[], model?: string): string[] {
+  const [cmd, ...args] = command;
+  return [cmd!, ...(model ? ["--model", model, ...args] : args)];
+}

package/src/adapters/definitions/native-daemon-policy.ts

@@ -0,0 +1,18 @@
+import type { StartForm, StartRequest, VersionContext } from "../registry-types.ts";
+
+/** Native serialization and person-facing guidance only; the daemon retains every ownership decision. */
+export const claudeRecoveryLaunch = (instance: string): Record<string, unknown> => ({ kind: "claude-channel", peer: instance });
+export const kimiRecoveryLaunch = (instance: string): Record<string, unknown> => ({ kind: "kimi-tui", peer: instance, mode: "tui" });
+export const claudeRetainedTerminalNotice = (instance: string): string =>
+  `Stop ${instance}'s existing work in its retained terminal; removal detaches the hub connection and does not stop that terminal's work.`;
+export const piRetainedTerminalNotice = (instance: string, form: StartForm | undefined): string | undefined =>
+  form === "tui" ? claudeRetainedTerminalNotice(instance) : undefined;
+export const codexRetainedTerminalNotice = (_instance: string, _form: StartForm | undefined, resumeCommand: string): string =>
+  `Check codex's existing terminal and stop any remaining work. Its app-server and proxy stay available, but Codex 0.146.0 exits its TUI on disconnect and does not reconnect automatically; after ahub roster add codex, resume the previous session with ${resumeCommand}.`;
+export const codexRosterReturnNotice = (resumeCommand: string): string =>
+  `Codex 0.146.0 needs a manual return: resume the previous native session with ${resumeCommand}.`;
+export const jcodeStartPreflight = (request: StartRequest): string | undefined =>
+  request.form !== undefined && request.form !== "headless" ? "Jcode native TUI driving is unverified; use headless" : undefined;
+export const claudeObservedVersion = (context: VersionContext): string | undefined => context.observedVersion;
+export const codexObservedVersion = (context: VersionContext): string | undefined =>
+  (context.peer as { version?: string } | undefined)?.version ?? context.observedVersion;

package/src/adapters/definitions/native-display.ts

@@ -0,0 +1,18 @@
+/** Existing native identity swatches; hub and unknown-peer styling stays in the UI. */
+export const CLAUDE_DISPLAY = { palette: { fg: "#6495ed", bg: "transparent", tone: "peerClaude", ansi: "\x1b[94m" } } as const;
+export const CODEX_DISPLAY = { palette: { fg: "#22b8cf", bg: "transparent", tone: "peerCodex", ansi: "\x1b[96m" } } as const;
+export const KIMI_DISPLAY = { palette: { fg: "#bc73ca", bg: "transparent", tone: "taskKeyword", ansi: "\x1b[35m" } } as const;
+export const PI_DISPLAY = { palette: { fg: "#c79936", bg: "transparent", tone: "attention", ansi: "\x1b[33m" } } as const;
+export const LOCAL_DISPLAY = { palette: { fg: "#4caa77", bg: "transparent", tone: "success", ansi: "\x1b[32m" } } as const;
+// These two kinds deliberately retain the existing 'other' fallback, not new public swatches.
+export const QWEN_DISPLAY = { palette: { fg: "#8a8f99", bg: "transparent", tone: "muted", ansi: "\x1b[90m" } } as const;
+export const JCODE_DISPLAY = { palette: { fg: "#8a8f99", bg: "transparent", tone: "muted", ansi: "\x1b[90m" } } as const;
+
+/** Kinds with a public named swatch; keep their exact literal types in compatibility projections. */
+export const NATIVE_DISPLAYS = { claude: CLAUDE_DISPLAY, codex: CODEX_DISPLAY, kimi: KIMI_DISPLAY, pi: PI_DISPLAY, local: LOCAL_DISPLAY } as const;
+
+const STREAM_TONES = { claude: "peerClaude", codex: "peerCodex" } as const;
+/** Stream headers historically color only these speakers, independently of their board palette. */
+export function nativeStreamTone(peer: string): (typeof STREAM_TONES)[keyof typeof STREAM_TONES] | undefined {
+  return Object.hasOwn(STREAM_TONES, peer) ? STREAM_TONES[peer as keyof typeof STREAM_TONES] : undefined;
+}

package/src/adapters/definitions/native-factories.ts

@@ -0,0 +1,48 @@
+import type { CreateContext, DaemonEngine, DaemonPorts } from "../registry-types.ts";
+import type { PeerAdapter } from "../../hub/peers.ts";
+
+// Load only fixed builtin modules after the pre-effect guards. A top-level LocalPeer import would
+// cycle through hub-tools and the registry while its definitions are still being initialized.
+export function createCodex(ctx: CreateContext): PeerAdapter {
+  if (!("codex" in ctx.daemon)) throw new Error("Codex requires its Codex transport options");
+  if (ctx.permission === "read-only") throw new Error("Codex has no verified read-only permission mapping");
+  const { CodexPeer } = require("../codex-appserver.ts") as typeof import("../codex-appserver.ts");
+  return new CodexPeer(ctx.instance, ctx.daemon.codex);
+}
+
+export function createKimi(ctx: CreateContext): PeerAdapter {
+  if (!("acp" in ctx.daemon)) throw new Error("Kimi requires its ACP transport options");
+  if (ctx.permission === "read-only") throw new Error("Kimi has no verified read-only permission mapping");
+  const { AcpPeer } = require("../acp.ts") as typeof import("../acp.ts");
+  return new AcpPeer(ctx.instance, ctx.daemon.acp);
+}
+
+export function createJcode(ctx: CreateContext): PeerAdapter {
+  if (!("jcode" in ctx.daemon)) throw new Error("Jcode requires its Jcode transport options");
+  if (ctx.permission === "read-only") throw new Error("Jcode has no verified read-only permission mapping");
+  const { JcodePeer } = require("../jcode.ts") as typeof import("../jcode.ts");
+  return new JcodePeer(ctx.daemon.jcode);
+}
+
+export function createPi(ctx: CreateContext): PeerAdapter {
+  if (!("pi" in ctx.daemon)) throw new Error("Pi requires its Pi transport options");
+  if (ctx.permission === "read-only") throw new Error("Pi has no verified read-only permission mapping");
+  const { PiPeer } = require("../pi.ts") as typeof import("../pi.ts");
+  return new PiPeer(ctx.instance, ctx.daemon.pi);
+}
+
+export function createLocal(ctx: CreateContext): PeerAdapter {
+  if (!("local" in ctx.daemon)) throw new Error("Local worker requires its local transport options");
+  if (ctx.permission === "read-only") throw new Error("Local worker has no verified read-only permission mapping");
+  const { LocalPeer } = require("../local-worker.ts") as typeof import("../local-worker.ts");
+  return new LocalPeer(ctx.instance, ctx.daemon.local);
+}
+
+/** Preserve existing transport option types and object identity; selection stays host-owned. */
+export const DAEMON_PORTS = {
+  "codex-appserver": (options: Extract<DaemonPorts, { codex: unknown }>["codex"]) => ({ codex: options }),
+  acp: (options: Extract<DaemonPorts, { acp: unknown }>["acp"]) => ({ acp: options }),
+  "owned-acp": (options: Extract<DaemonPorts, { jcode: unknown }>["jcode"]) => ({ jcode: options }),
+  "pi-rpc": (options: Extract<DaemonPorts, { pi: unknown }>["pi"]) => ({ pi: options }),
+  "local-worker": (options: Extract<DaemonPorts, { local: unknown }>["local"]) => ({ local: options }),
+} satisfies Record<DaemonEngine, unknown>;