@staix/agent-hub 0.12.44 → 0.13.0

package/src/adapters/definitions/builtin-metadata.ts

@@ -1,3 +1,14 @@
+import { runClaudeEntry } from "./native-cli-entry-claude.ts";
+import { runCodexEntry } from "./native-cli-entry-codex.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";
+import { runJcodeEntry } from "./native-cli-entry-jcode.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 { previewJcode } from "./native-cli-preview-jcode.ts";
 import type { PermissionMode } from "../../hub/permission-mode.ts";
 import { claudeReviewerBackend, CODEX_REVIEWER_VARIANT, KIMI_REVIEWER_VARIANT } from "./reviewer-variants.ts";
 import { kimiAcpCommand } from "./native-daemon-kimi.ts";
@@ -73,6 +84,7 @@ const CLAUDE_REVIEWER_VARIANT: AdapterDefinition = {
 // daemon.ts runtime mappings/stop policy, budget.ts exemptions, and ui/peer-palette.ts CSS foregrounds.
 export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition[] = Object.freeze([
   {
+    projection: { roleRank: 0, helpRank: 0, plannerEligible: true },
     api: 1, kind: "claude", displayName: "Claude Code", family: "claude", transport: "claude-channel",
     roles: Object.freeze(["planner", "reviewer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
     start: { forms: Object.freeze(["tui"] as const), defaultForm: "tui", launch: claudeNativeLaunch, version: claudeObservedVersion, ...CLAUDE_LAUNCH_POLICY, conductorStartable: true,
@@ -84,11 +96,12 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
       "never-ask": "every tool runs without asking" } },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), configDirEnv: "CLAUDE_CONFIG_DIR", zeroTurnFresh: true, launchKind: "claude-channel", launchRecord: true, ...CLAUDE_RECOVERY_SESSION, crashPlan: claudeCrashPlan, unrecordedTerminal: "always" },
     turnEnd: "native-hook", budget: { account: "claude", checkpoint: true, reader: { source: "claude status line", read: claudeWindows }, context: { source: "claude_statusline", read: claudeContext } },
-    cli: { command: "claude", retainedTerminalNotice: claudeRetainedTerminalNotice, stopNotice: () => "this peer belongs to a native terminal; end it in its terminal", startWords: () => ["claude"] }, display: CLAUDE_DISPLAY, hooks: { recallPlatform: "claude", recallSource: "claude", recallInjected: true, pluginInventory: claudePluginInventory },
+    cli: { command: "claude", entry: { lifecycleAdmission: true, execute: runClaudeEntry }, preview: previewClaude, usage: [["ahub claude [--print-command] [--unattended] [args...]", "launch Claude Code with the hub channel"]], retainedTerminalNotice: claudeRetainedTerminalNotice, stopNotice: () => "this peer belongs to a native terminal; end it in its terminal", startWords: () => ["claude"] }, display: CLAUDE_DISPLAY, hooks: { recallPlatform: "claude", recallSource: "claude", recallInjected: true, pluginInventory: claudePluginInventory },
     reviewerVariant: CLAUDE_REVIEWER_VARIANT,
   },
   {
     reviewerVariant: CODEX_REVIEWER_VARIANT,
+    projection: { roleRank: 1, startRank: 1, helpRank: 1, plannerEligible: true },
     api: 1, kind: "codex", displayName: "Codex", family: "codex", transport: "codex-appserver",
     roles: Object.freeze(["implementer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
     start: { create: createCodex, daemonPort: "codex-appserver", forms: dualForms, defaultForm: "tui", launch: codexNativeLaunch, version: codexObservedVersion, ...CODEX_LAUNCH_POLICY, conductorStartable: true,
@@ -97,10 +110,11 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     permission: { trackUnattended: true, grants: { ask: "the session's own approval policy applies again", "ask-when-needed": "approval policy on-request on every turn", "never-ask": "approval policy never on every turn: nothing asks" } },
     session: { nativeRevert: true, idField: "threadId", currentId: sessionId("threadId"), configDirEnv: "CODEX_HOME", zeroTurnFresh: true, launchKind: "codex", launchRecord: true, ...CODEX_RECOVERY_SESSION, crashPlan: codexCrashPlan, unrecordedTerminal: "always" },
     turnEnd: "adapter", budget: { account: "codex", checkpoint: true, reader: { source: "codex rateLimits", read: codexWindows }, context: { source: "codex_token_usage", read: codexContext } },
-    cli: { command: "codex", launchConfigKeys: ["codex_bin"], retainedTerminalNotice: codexRetainedTerminalNotice, rosterReturnNotice: codexRosterReturnNotice, stopNotice: () => "this peer belongs to a native terminal; end it in its terminal", startWords: () => ["codex"] }, display: CODEX_DISPLAY, hooks: { recallPlatform: "codex", recallSource: "codex", recallInjected: true, pluginInventory: codexPluginInventory, classifyTool: codexToolSemantic },
+    cli: { command: "codex", entry: { lifecycleAdmission: true, execute: runCodexEntry }, preview: previewCodex, usage: [["ahub codex [--print-command] [--unattended] [args...]", "start the Codex adapter and attach the TUI"]], launchConfigKeys: ["codex_bin"], retainedTerminalNotice: codexRetainedTerminalNotice, rosterReturnNotice: codexRosterReturnNotice, stopNotice: () => "this peer belongs to a native terminal; end it in its terminal", startWords: () => ["codex"] }, display: CODEX_DISPLAY, hooks: { recallPlatform: "codex", recallSource: "codex", recallInjected: true, pluginInventory: codexPluginInventory, classifyTool: codexToolSemantic },
   },
   {
     reviewerVariant: KIMI_REVIEWER_VARIANT,
+    projection: { roleRank: 2, startRank: 2, helpRank: 2, plannerEligible: true },
     api: 1, kind: "kimi", displayName: "Kimi Code", family: "kimi", transport: "acp",
     roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
     start: { create: createKimi, acpCommand: kimiAcpCommand, explicitHeadlessMode: true, planCommand: () => "ahub kimi", daemonPort: "acp", forms: dualForms, defaultForm: "tui", conductorStartable: true, hubSwitches: [], ownedFlags: [] },
@@ -112,9 +126,10 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
       unmanagedForms: Object.freeze(["tui"] as const), unmanagedStatusNote: "Kimi approves tools in its own TUI; no hub permission mode", unmanagedNote: "Kimi approves tools and selects its permission mode in its own TUI; no hub permission mode" },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: true, launchKind: "acp", ...KIMI_RECOVERY_SESSION, crashPlan: kimiCrashPlan },
     turnEnd: "adapter", budget: { account: "kimi", resetSoftTokensOnResume: true, context: { source: "acp_usage_update", read: acpContextValue } }, capabilities: { watch: true }, hooks: { recallPlatform: "kimi", recallSource: "kimi" },
-    cli: { command: "kimi", launchConfigKeys: ["kimi_cmd", "peers.kimi.start_mode"], stopNotice: form => form === "tui" ? "Kimi belongs to its own TUI terminal; end it in that terminal" : "", startWords: form => ["kimi", "--mode", form] }, display: KIMI_DISPLAY,
+    cli: { command: "kimi", entry: { lifecycleAdmission: true, execute: runKimiEntry }, preview: previewKimi, usage: [["ahub kimi [--print-command] [--mode tui|headless] [--model <alias>]", "default: Kimi's own TUI, pull-only via hub_inbox; no push, steer, watchdog, console approvals or automatic quota handoff. Select headless for ACP"]], launchConfigKeys: ["kimi_cmd", "peers.kimi.start_mode"], stopNotice: form => form === "tui" ? "Kimi belongs to its own TUI terminal; end it in that terminal" : "", startWords: form => ["kimi", "--mode", form] }, display: KIMI_DISPLAY,
   },
   {
+    projection: { roleRank: 4, startRank: 0, helpRank: 6, plannerEligible: false },
     api: 1, kind: "pi", enabledSwitchStartOnly: true, displayName: "Pi", family: "pi", transport: "hub-native",
     roles: implementerRoles, defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: true },
     start: { create: createPi, exclusiveStartRefusal: "Pi start is in progress; inspect status before retrying", refreshTools: true, explicitHeadlessMode: true, daemonPort: "pi-rpc", forms: dualForms, defaultForm: "tui", conductorStartable: true, autoStart: "pi.auto_start", conductorStartArgs: piConductorStartArgs, hubSwitches: [], ownedFlags: [] },
@@ -124,9 +139,10 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     session: { idField: "sessionId", currentId: sessionId("sessionId"), restoreOnStart: true, launchKind: "pi", launchRecord: true, ...PI_RECOVERY_SESSION, crashPlan: piCrashPlan, unrecordedTerminal: "tui", continuityBookmark: piRecoveryContinuity, continuity: { key: "pi", parse: parsePiContinuity } },
     turnEnd: "adapter", budget: { account: "pi", instrumented: true }, reporting: { tokensNotReported: true }, configuration: { schema: piConfigSchema, routingSchema: piRoutingSchema, settings: PI_SETTINGS, restartReasons: PI_RESTART_REASONS, validateEffective: piEffectiveConfig },
     routing: { localAllowedRefusal: "local_allowed = false also excludes pi for this class", longContext: "backend-limit", preferredTier: true, handoffPriority: 0, trace: "backend", backendLabel: "pi" },
-    cli: { command: "pi", launchConfigKeys: ["pi.cmd", "pi.backend", "pi.dgx_coding", "pi.dgx_fast", "pi.max_steps", "routing.pi", "peers.pi.start_mode"], previewArgs: ["--mode", "tui"], retainedTerminalNotice: piRetainedTerminalNotice, personOnlyFlags: ["--replace-session"], startWords: form => ["pi", "--mode", form] }, display: PI_DISPLAY,
+    cli: { command: "pi", entry: { lifecycleAdmission: false, execute: runPiEntry }, preview: previewPi, usage: [["ahub pi [--print-command] [--mode headless|tui | --headless] [--backend auto|dgx|mlx] [--model <alias>] [--session-id <id>] [--session-file <path>] [--replace-session]", "start Pi: its TUI in this terminal unless --headless or the start mode setting (peers.pi.start_mode) says headless; without a terminal the hub opens one or says how"]], launchConfigKeys: ["pi.cmd", "pi.backend", "pi.dgx_coding", "pi.dgx_fast", "pi.max_steps", "routing.pi", "peers.pi.start_mode"], previewArgs: ["--mode", "tui"], retainedTerminalNotice: piRetainedTerminalNotice, personOnlyFlags: ["--replace-session"], startWords: form => ["pi", "--mode", form] }, display: PI_DISPLAY,
   },
   {
+    projection: { roleRank: 3, helpRank: 7, plannerEligible: false },
     api: 1, kind: "local", displayName: "Local worker", family: "local", transport: "hub-native",
     roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: true, hubSandboxed: true },
     start: { create: createLocal, reconfigureWhileAttached: true, refreshTools: true, daemonPort: "local-worker", forms: headlessForms, defaultForm: "headless", conductorStartable: true, hubSwitches: [], ownedFlags: [] },
@@ -136,18 +152,20 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
     session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: true, launchKind: "local", ...LOCAL_RECOVERY_SESSION, crashPlan: localCrashPlan },
     turnEnd: "adapter", budget: { account: "local", quotaExempt: true, instrumented: true }, configuration: { schema: localConfigSchema, routingSchema: localRoutingSchema, restartReasons: LOCAL_RESTART_REASONS },
     routing: { localAllowedRefusal: "local_allowed = false for this class", longContext: "skip-owner", preferredTier: true, handoffPriority: 1, trace: "route" },
-    cli: { command: "local", launchConfigKeys: ["local.deny", "local.bash_network", "local.network_allow", "local.max_steps", "local.read_allow", "routing.local"], startWords: () => ["local"] }, display: LOCAL_DISPLAY,
+    cli: { command: "local", entry: { lifecycleAdmission: false, execute: runLocalEntry }, usage: [["ahub local [--route <id> | --model <id>]", "start the hub-native worker on the self-hosted models (routing.toml)"]], launchConfigKeys: ["local.deny", "local.bash_network", "local.network_allow", "local.max_steps", "local.read_allow", "routing.local"], startWords: () => ["local"] }, display: LOCAL_DISPLAY,
   },
   {
+    projection: { roleRank: 6, startRank: 3, helpRank: 3, plannerEligible: true },
     api: 1, kind: "jcode", displayName: "Jcode", family: "jcode", transport: "acp",
     roles: implementerRoles, optional: true, defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: false },
     start: { create: createJcode, preflight: jcodeStartPreflight, daemonPort: "owned-acp", forms: dualForms, defaultForm: "tui", explicitHeadlessMode: true, conductorStartable: true, hubSwitches: [], ownedFlags: [] },
-    identity: { mcp: "project-file" },
+    // #685: an extra Jcode is a headless instance with its own native home, socket and state (instances.<id>.jcode_home).
+    identity: { mcp: "project-file" }, instances: { mode: "headless", nativeHome: true },
     permission: { unmanaged: "Jcode native policy is unmanaged; no hub mode mapping", grants: {
       ask: "no verified hub mode mapping; native policy only", "ask-when-needed": "no verified hub mode mapping; native policy only", "never-ask": "no verified hub mode mapping; native policy only" } },
     session: { idField: "sessionId", currentId: sessionId("sessionId"), launchKind: "jcode", ...JCODE_RECOVERY_SESSION, crashPlan: jcodeCrashPlan }, turnEnd: "adapter", budget: { account: "jcode" },
     // Jcode has no dedicated CSS swatch today: retain peer-palette.ts's existing 'other' fallback.
-    cli: { command: "jcode", authority: "person", launchConfigKeys: ["jcode_cmd", "jcode_home", "jcode_provider_profile"], startWords: mode => ["jcode", "--mode", mode] }, display: JCODE_DISPLAY, hooks: { recallPlatform: "jcode" },
+    cli: { command: "jcode", entry: { lifecycleAdmission: true, execute: runJcodeEntry }, preview: previewJcode, usage: [["ahub jcode [--mode tui|headless] [--model <alias>] [--provider-profile <name>] [--session-id <id>] [--print-command]", "optional Jcode (roster.jcode, default off): its TUI on the hub-owned ACP session, opened once that session is saved; --mode headless for ACP only; native policy unmanaged, no hub sandbox"]], authority: "person", launchConfigKeys: ["jcode_cmd", "jcode_home", "jcode_provider_profile"], startWords: mode => ["jcode", "--mode", mode] }, display: JCODE_DISPLAY, hooks: { recallPlatform: "jcode" },
   },
 ] satisfies AdapterDefinition[]);
 

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

@@ -1,3 +1,4 @@
+import type { CompatId } from "../compat.ts";
 import type { DoctorCheck } from "../../cli/output.ts";
 
 // Fixed builtin doctor policy only. These projections neither execute probes nor extend AdapterDefinition.
@@ -33,17 +34,23 @@ export function nativeDoctorRecoveryIdentity(peer: { id: string; state: string;
 export type NativeDoctorOptionalProbe =
   | { kind: "source-identity"; name: string; command: string[]; detail: string }
   | { kind: "jcode-mcp"; name: string; home: string }
-  | { kind: "pinned-version"; name: string; command: string[]; expected: string; confirmed: string; unconfirmed: string };
+  | { kind: "pinned-version"; name: string; command: string[]; compat: CompatId; confirmed: string; unconfirmed: string };
 
 /** The host runs these existing checks in order; no process, filesystem or caller callback enters this planner. */
-export function nativeDoctorOptionalProbes(config: { roster: Readonly<Record<string, boolean | undefined>>; jcode_cmd: string[]; qwen_cmd: string[]; jcode_home?: string }): NativeDoctorOptionalProbe[] {
+export function nativeDoctorOptionalProbes(config: { roster: Readonly<Record<string, boolean | undefined>>; jcode_cmd: string[]; qwen_cmd: string[]; jcode_home?: string;
+  /** Declared extra instances (#685): a rostered Jcode instance's own home is inventoried like the base home. */
+  instances?: Readonly<Record<string, { kind: string; jcode_home?: string }>> }): NativeDoctorOptionalProbe[] {
   const probes: NativeDoctorOptionalProbe[] = [];
   if (config.roster.jcode === true) probes.push({ kind: "source-identity", name: "jcode", command: config.jcode_cmd,
     detail: "CLI/source identity only; provider, project MCP and native teardown require separate receipts; native policy unmanaged" });
   // #572 AC4: jcode cannot be told which MCP servers to load, so the host lists the ones its config files name.
   if (config.roster.jcode === true && config.jcode_home) probes.push({ kind: "jcode-mcp", name: "jcode MCP servers", home: config.jcode_home });
-  if (config.roster.qwen === true) probes.push({ kind: "pinned-version", name: "qwen", command: config.qwen_cmd, expected: "0.25.0",
-    confirmed: "CLI reports 0.25.0; native ACP identity/modes and provider access require a separate live check",
-    unconfirmed: "Qwen Code 0.25.0 executable not confirmed; provider and ACP readiness unknown" });
+  // #685: each extra instance has its own home, hence its own inventory. Names and homes only: no model source, URL or token.
+  for (const [id, declaration] of Object.entries(config.instances ?? {})) {
+    if (declaration.kind === "jcode" && declaration.jcode_home && config.roster[id] === true) probes.push({ kind: "jcode-mcp", name: `${id} MCP servers`, home: declaration.jcode_home });
+  }
+  if (config.roster.qwen === true) probes.push({ kind: "pinned-version", name: "qwen", command: config.qwen_cmd, compat: "qwen",
+    confirmed: "CLI version verified; native ACP identity/modes and provider access require a separate live check",
+    unconfirmed: "Qwen Code executable not confirmed; provider and ACP readiness unknown" });
   return probes;
 }

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

@@ -51,7 +51,10 @@ export async function runJcodeEntry(ctx: NativeCliEntryContext): Promise<void> {
   if (rest.length || (one["--mode"] !== undefined && !["headless", "tui"].includes(one["--mode"]))) fail("usage: ahub jcode [--mode tui|headless] [--model <alias>] [--provider-profile <name>] [--session-id <id>]");
   if (one["--session-id"] !== undefined && !qwenSessionId(one["--session-id"])) fail("invalid Jcode session identity");
   const control = readControl(stateDir);
+  // #685: `--as <id>` selects an extra Jcode instance; every request below names it, never the base peer.
+  const peer = ctx.instance ?? "jcode";
   const mode = one["--mode"] ?? (ctx.instance ? "headless" : control?.startModes?.jcode ?? startModeOf(ctx.projectConfig().peers, "jcode"));
+  if (ctx.instance && mode === "tui") fail(`${peer} is an extra Jcode instance: it runs headless on its own private server (ahub jcode --as ${peer}); the TUI belongs to the base jcode`);
   if (print && (mode === "headless" || !control?.features?.includes("native_tui_launch"))) {
     try { return console.log(JSON.stringify(launcherPreview("jcode", args, cwd, stateDir, unattendedEnv), null, 2)); }
     catch { return fail("cannot preview Jcode launch: invalid arguments or configuration (details withheld)"); }
@@ -66,10 +69,10 @@ export async function runJcodeEntry(ctx: NativeCliEntryContext): Promise<void> {
   hub.onClose = (code, reason) => { if (!abort.signal.aborted) abort.abort(); oldClose?.(code, reason); };
   try {
     const snapshot = (await hub.request({ t: "status" })).status;
-    const rostered = rosterInStatus(snapshot, "jcode");
-    if (rostered === undefined) fail("cannot read jcode's roster membership from the running hub; upgrade or restart it, then retry (nothing was started)");
-    if (!rostered) fail("jcode is off roster; add it with ahub roster add jcode");
-    const warning = retainedLaunchWarning(snapshot, "jcode", ctx.definition); if (warning) console.error(warning);
+    const rostered = rosterInStatus(snapshot, peer);
+    if (rostered === undefined) fail(`cannot read ${peer}'s roster membership from the running hub; upgrade or restart it, then retry (nothing was started)`);
+    if (!rostered) fail(`${peer} is off roster; add it with ahub roster add ${peer}`);
+    const warning = retainedLaunchWarning(snapshot, peer, ctx.definition); if (warning) console.error(warning);
     const options = { model: one["--model"], providerProfile: one["--provider-profile"], sessionId: one["--session-id"] };
     if (print) {
       if (!hub.features.includes("native_tui_launch") || mode !== "tui") return console.log(JSON.stringify(launcherPreview("jcode", args, cwd, stateDir, unattendedEnv), null, 2));
@@ -89,10 +92,10 @@ export async function runJcodeEntry(ctx: NativeCliEntryContext): Promise<void> {
     }
     const written = configureJcodeMcp(cwd, stateDir, bundleInStatus(snapshot) ?? 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, ...options }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 65_000);
+    const reply = await hub.request({ t: "start", peer, args: { mode, ...options }, operationId: process.env.AGENTHUB_RECOVERY_OPERATION }, 65_000);
     if (interruptedWait()) return;
     if (!reply.ok) fail(reply.error);
-    if (mode === "headless") { console.log(reply.already ? "jcode is already attached" : "jcode attached (headless); native policy unmanaged, NO hub sandbox"); return; }
+    if (mode === "headless") { console.log(reply.already ? `${peer} is already attached` : `${peer} attached (headless); native policy unmanaged, NO hub sandbox`); return; }
     const ready = await waitForJcodeTui(hub, fail, abort.signal, options);
     if (interruptedWait() || !ready) return;
     // No managed terminal record: Jcode's controlled recovery is refused at plan time, so, like Kimi's TUI, it has

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

@@ -45,7 +45,13 @@ export async function runKimiEntry(ctx: NativeCliEntryContext): Promise<void> {
       let result: ReturnType<typeof spawnSync>;
       try {
         // Inside the try: a kimi_cmd with no TUI form throws here, and the admission must still be released (#549).
-        launch = buildKimiTuiLaunch(Array.isArray(runningCommand) && runningCommand.every((arg: unknown) => typeof arg === "string") ? runningCommand : projectConfig().kimi_cmd, model);
+        // The running hub's value wins over the file's while a reload is retained (#654): when it has no TUI form, say whose it is, so the
+        // error is not read as a fault in the file. The words themselves are never echoed.
+        const running = Array.isArray(runningCommand) && runningCommand.every((arg: unknown) => typeof arg === "string");
+        try { launch = buildKimiTuiLaunch(running ? runningCommand : projectConfig().kimi_cmd, model); }
+        catch (error) {
+          throw running ? new Error(`${(error as Error).message} (the command is the running hub's kimi_cmd: the value in the config file is retained until ahub settings reload)`) : error;
+        }
         // The daemon's own bundle, so the MCP server matches the hub it talks to (#502); this CLI's copy only for an older hub.
         const written = configureKimiMcp(cwd, stateDir, bundleInStatus(snapshot) ?? 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.");

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

@@ -1,21 +1,9 @@
-import { runAgyEntry } from "../agy/entry.ts";
+import type { AdapterDefinition } from "../registry-types.ts";
 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: "agy", lifecycleAdmission: true, execute: runAgyEntry },
-  { 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 },
-]);
+/** Project only the trusted definitions supplied by the host, preserving their order. */
+export function builtinCliEntries(definitions: readonly AdapterDefinition[]): readonly BuiltinCliEntry[] {
+  return Object.freeze(definitions.flatMap(definition => definition.cli.entry
+    ? [Object.freeze({ ...definition.cli.entry, command: definition.cli.command })]
+    : []));
+}

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

@@ -18,10 +18,17 @@ function document(file: string): Document {
   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;
+/**
+ * The project's `.jcode/mcp.json` entry is shared by every Jcode in it, so it names no peer (#685): jcode gives an entry's own env
+ * precedence over the process env (probed on 0.99.0), so a hardcoded `AGENTHUB_PEER_ID: "jcode"` would make an extra instance's
+ * hub tools act as the base peer. Each owned launch path supplies its own id instead (peerChildEnv for serve and ACP, the TUI launch env).
+ * An entry written before this still hardcodes the id: `jcodeMcpReady` is false for it, and the launcher rewrites it.
+ */
+const owned = (entry: unknown, cwd: string): entry is Document => object(entry) && object(entry.env) && entry.env.AGENTHUB_MODE === "tools"
+  && (entry.env.AGENTHUB_PEER_ID === undefined || 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 } };
+  return { command: "bun", args: ["run", bundle], shared: false, env: { AGENTHUB_MODE: "tools", AGENTHUB_DELIVERY_ONLY: "true", 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 {

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

@@ -23,6 +23,8 @@ export interface NativePreviewHelpers {
 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;
+  /** The declared extra instance a `--as <id>` launch selected; its own model fields belong in the preview (#685). */
+  instance?: string;
 }
 export interface NativePreviewMetadata { mode: "tui" | "headless"; mcp: { file: string; action: string; changed: boolean; tracked: boolean } }
 export type NativePreviewBuilder = (ctx: NativePreviewContext) => NativePreview;

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

@@ -2,7 +2,7 @@ import type { Launch } from "../../cli/launch.ts";
 import { REDACTED, UNRESOLVED, nativeCommand, previewState, finishPreview, type NativePreviewContext, type NativePreview } from "./native-cli-preview-common.ts";
 
 export function previewJcode(ctx: NativePreviewContext): NativePreview {
-  const { args, config } = ctx;
+  const { args, config, instance } = ctx;
   const { jcodeCommand, jcodeTuiCommand, qwenSessionId, startModeOf } = ctx.helpers;
   const state = previewState(args, ctx.baseEnvNames), { unresolved, value } = state;
   let envNames = state.envNames;
@@ -11,7 +11,13 @@ export function previewJcode(ctx: NativePreviewContext): NativePreview {
   if (mode !== "headless" && mode !== "tui") throw new Error("invalid Jcode start mode");
   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 = mode === "tui" ? jcodeTuiCommand(nativeCommand(config.jcode_cmd, ["jcode"]), UNRESOLVED, UNRESOLVED, model ? REDACTED : undefined, profile || config.jcode_provider_profile ? REDACTED : undefined) : jcodeCommand(nativeCommand(config.jcode_cmd, ["jcode"]), "acp", UNRESOLVED, UNRESOLVED, model ? REDACTED : undefined, profile || config.jcode_provider_profile ? REDACTED : undefined);
+  // The daemon starts an instance with its own declared provider, model and profile (a launch flag still wins, as in the start branch):
+  // preview the same flags. Values stay redacted, as the base Jcode's model and profile already are.
+  const declared = instance ? config.instances?.[instance] : undefined;
+  const provider = declared?.provider ? REDACTED : undefined, modelWord = model || declared?.model ? REDACTED : undefined;
+  const profileWord = profile || declared?.provider_profile || config.jcode_provider_profile ? REDACTED : undefined;
+  const cmd = mode === "tui" ? jcodeTuiCommand(nativeCommand(config.jcode_cmd, ["jcode"]), UNRESOLVED, UNRESOLVED, modelWord, profileWord, provider)
+    : jcodeCommand(nativeCommand(config.jcode_cmd, ["jcode"]), "acp", UNRESOLVED, UNRESOLVED, modelWord, profileWord, provider, instance ?? "jcode");
   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" });

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

@@ -1,3 +1,4 @@
+import { describe } from "../compat.ts";
 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";
@@ -16,7 +17,7 @@ export function previewQwen(ctx: NativePreviewContext) {
   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" });
+  unresolved.push({ field: "nativeIdentity", reason: `Qwen Code (${describe("qwen")}) 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

@@ -1,16 +1,7 @@
 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,
-});
+/** The host admits builtin-only preview ports before calling this projection. */
 export function builtinPreview(definition: AdapterDefinition): NativePreviewBuilder | undefined {
-  return Object.hasOwn(previews, definition.kind) ? previews[definition.kind] : undefined;
+  return definition.cli.preview;
 }

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

@@ -1,16 +1,20 @@
+import { assessVersion } from "../compat.ts";
 import type { PermissionMode } from "../../hub/permission-mode.ts";
 import type { Launch } from "../../cli/launch.ts";
 
 export const QWEN_MODE_IDS: Readonly<Record<PermissionMode, string>> = { ask: "default", "ask-when-needed": "auto-edit", "never-ask": "yolo" };
 
 export class QwenIdentityError extends Error {
-  constructor() { super("Qwen Code 0.25.0 native identity is not verified; check the executable and its advertised ACP version"); }
+  constructor(reason?: string) { super(reason ? `Qwen Code native identity is not verified: ${reason}` : "Qwen Code native identity is not verified; check the executable and its advertised ACP version"); }
 }
 
 export function qwenNativeIdentity(instance: string, production: boolean | undefined, init: unknown, kind?: string): boolean {
   const native = init as { agentInfo?: { name?: unknown; version?: unknown } } | null | undefined;
-  const verified = production === true && (kind ?? instance) === "qwen" && native?.agentInfo?.name === "qwen-code" && native?.agentInfo?.version === "0.25.0";
-  if (production && !verified) throw new QwenIdentityError();
+  const identity = production === true && (kind ?? instance) === "qwen" && native?.agentInfo?.name === "qwen-code";
+  // #691: a version refusal carries the compat reason (observed and verified versions, the trust command).
+  const version = identity ? assessVersion("qwen", native?.agentInfo?.version) : undefined;
+  if (production && !version?.ok) throw new QwenIdentityError(version && !version.ok ? version.reason : undefined);
+  const verified = !!version?.ok;
   return verified;
 }
 

package/src/adapters/definitions/qwen.ts

@@ -1,3 +1,6 @@
+import { describe } from "../compat.ts";
+import { runQwenEntry } from "./native-cli-entry-qwen.ts";
+import { previewQwen } from "./native-cli-preview-qwen.ts";
 import { QWEN_DISPLAY } from "./native-display.ts";
 import { QWEN_RECOVERY_SESSION } from "./native-recovery.ts";
 import { AcpPeer } from "../acp.ts";
@@ -9,6 +12,7 @@ import { shellQuote } from "../../cli/shell-quote.ts";
 export const QWEN_DEFINITION: AdapterDefinition = {
   api: 1,
   kind: "qwen",
+  projection: { roleRank: 5, helpRank: 5, plannerEligible: true },
   displayName: "Qwen Code",
   family: "qwen",
   transport: "acp",
@@ -64,7 +68,7 @@ export const QWEN_DEFINITION: AdapterDefinition = {
   turnEnd: "adapter",
   budget: { account: "qwen" },
   capabilities: { watch: true },
-  cli: { command: "qwen", launchConfigKeys: ["qwen_cmd"], startWords: () => ["qwen"] },
+  cli: { command: "qwen", entry: { lifecycleAdmission: true, execute: runQwenEntry }, preview: previewQwen, usage: [["ahub qwen [--mode headless] [--model <alias>] [--session-id <id>] [--print-command]", `start optional Qwen Code ACP (${describe("qwen")}; roster.qwen, default off)`]], launchConfigKeys: ["qwen_cmd"], startWords: () => ["qwen"] },
   display: QWEN_DISPLAY,
   hooks: { recallPlatform: "qwen" },
 };

package/src/adapters/external-metadata.ts

@@ -0,0 +1,48 @@
+import { types } from "node:util";
+import { ADAPTER_API } from "./adapter-api.ts";
+import type { AdapterDefinition } from "./registry-types.ts";
+export interface ExternalAdapterMetadata { readonly kind: string; readonly displayName: string }
+const MAX_MODULES = 16;
+const fail = (reason: string): never => { throw new Error(`external adapter: ${reason}`); };
+export function moduleDataObject(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || types.isProxy(value) || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value)) || Object.getOwnPropertySymbols(value).length) return fail("plain own-data object required");
+  const fields: Record<string, PropertyDescriptor> = Object.assign(Object.create(null), Object.getOwnPropertyDescriptors(value));
+  if (Object.values(fields).some(field => !Object.hasOwn(field, "value") || !field.enumerable)) return fail("accessors and hidden fields are unsupported");
+  return Object.fromEntries(Object.entries(fields).map(([key, field]) => [key, field.value]));
+}
+export function moduleText(value: unknown, max: number): string {
+  if (typeof value !== "string" || !value.trim() || Buffer.byteLength(value) > max || /[\p{Cc}\p{Cf}]/u.test(value)) return fail("bounded control-free text required");
+  return value;
+}
+export function moduleArray(value: unknown, max: number): unknown[] {
+  if (!Array.isArray(value) || types.isProxy(value) || Object.getPrototypeOf(value) !== Array.prototype || value.length > max
+    || Object.getOwnPropertySymbols(value).length) return fail("bounded array required");
+  const fields: Record<string, PropertyDescriptor> = Object.assign(Object.create(null), Object.getOwnPropertyDescriptors(value));
+  if (Object.keys(fields).length !== value.length + 1) return fail("dense array required");
+  return Array.from({ length: value.length }, (_, index) => {
+    const field = fields[String(index)];
+    if (!field || !Object.hasOwn(field, "value") || !field.enumerable) return fail("array data fields required");
+    return field.value;
+  });
+}
+/** Bounded inert metadata, usable by CLI/config readers without executing module callbacks. */
+export function externalAdapterMetadata(raw: unknown): readonly ExternalAdapterMetadata[] {
+  if (raw === undefined) return Object.freeze([]);
+  const rows = moduleArray(raw, MAX_MODULES).map(value => {
+    const row = moduleDataObject(value), kind = row.kind;
+    if (Object.keys(row).some(key => !["kind", "displayName"].includes(key)) || typeof kind !== "string" || !/^[a-z][a-z0-9-]{0,31}$/.test(kind)) return fail("invalid external display metadata");
+    return Object.freeze({ kind, displayName: moduleText(row.displayName, 256) });
+  });
+  if (new Set(rows.map(row => row.kind)).size !== rows.length) return fail("duplicate external display metadata");
+  return Object.freeze(rows);
+}
+export function externalMetadataDefinitions(raw: unknown): readonly AdapterDefinition[] {
+  return Object.freeze(externalAdapterMetadata(raw).map(({ kind, displayName }): AdapterDefinition => ({
+    api: ADAPTER_API, kind, family: kind, displayName, transport: "acp", roles: [], optional: true, defaultOnRoster: false,
+    trust: { onPrem: false, hubSandboxed: false }, identity: { mcp: "acp-session" }, permission: { genericAcp: {}, unmanaged: "external adapter metadata; authority belongs to the running daemon" },
+    start: { forms: ["headless"], defaultForm: "headless", conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    session: { idField: "sessionId", currentId: () => undefined }, turnEnd: "adapter",
+    cli: { command: kind, startWords: () => [kind] }, display: { palette: { fg: "white", bg: "black" } },
+  })));
+}

package/src/adapters/external-module-scan.ts

@@ -0,0 +1,126 @@
+interface Token { kind: "word" | "string" | "punct"; value: string }
+const forbiddenNames = new Set(["require", "createRequire", "eval", "Function"]);
+const globalNames = new Set(["globalThis", "global", "self", "window"]);
+const regexAfterWords = new Set(["return", "throw", "case", "delete", "typeof", "void", "yield", "await", "in", "of", "else", "do"]);
+const regexAfterPunctuation = new Set(["=", "(", "[", "{", ":", ",", ";", "!", "?", "&&", "||", "??", "=>", "+", "-", "*", "%", "&", "|", "^", "~", "<", ">"]);
+const fail = (): never => { throw new Error("external adapter: module source scan refused (details withheld)"); };
+
+/** Lex normalized JS, retaining literal tokens only for direct computed global/member access. */
+function tokensOf(source: string): Token[] {
+  const tokens: Token[] = [];
+  let index = 0;
+  const controlParens: boolean[] = [];
+  let regexAllowed = true;
+  const push = (kind: Token["kind"], value: string) => {
+    const previous = tokens.at(-1);
+    if (kind === "punct" && value === "(") controlParens.push(previous?.kind === "word" && ["if", "while", "for", "with", "switch", "catch"].includes(previous.value));
+    const controlEnd = kind === "punct" && value === ")" ? controlParens.pop() === true : false;
+    tokens.push({ kind, value });
+    regexAllowed = controlEnd || (kind === "word" ? regexAfterWords.has(value) : kind === "punct" && regexAfterPunctuation.has(value));
+  };
+  const wordStart = (char: string) => /[$_\p{ID_Start}]/u.test(char);
+  const wordPart = (char: string) => /[$_\p{ID_Continue}]/u.test(char);
+  const quoted = (quote: string) => {
+    index++;
+    let value = "";
+    while (index < source.length) {
+      const char = source[index++]!;
+      if (char === quote) { push("string", value); return; }
+      if (char === "\\") {
+        const escaped = source[index++];
+        // Unknown escapes are not a proof of a statically named member. Transform normally canonicalizes them.
+        value += escaped === quote || escaped === "\\" ? escaped : "?";
+      } else value += char;
+    }
+    fail();
+  };
+  const regex = () => {
+    index++;
+    let characterClass = false;
+    while (index < source.length) {
+      const char = source[index++]!;
+      if (char === "\\") { index++; continue; }
+      if (char === "[") characterClass = true;
+      else if (char === "]") characterClass = false;
+      else if (char === "/" && !characterClass) {
+        while (index < source.length && /[a-z]/i.test(source[index]!)) index++;
+        push("string", "");
+        return;
+      }
+    }
+    fail();
+  };
+  const template = (depth: number) => {
+    if (depth > 128) fail();
+    index++;
+    let text = "";
+    while (index < source.length) {
+      const char = source[index]!;
+      if (source.charCodeAt(index) === 96) { index++; push("string", text); return; }
+      if (char === "\\") { index += 2; text += "?"; continue; }
+      if (char === "$" && source[index + 1] === "{") {
+        push("string", text); text = ""; index += 2;
+        push("punct", "(");
+        code(true, depth + 1);
+        push("punct", ")");
+      } else { text += char; index++; }
+    }
+    fail();
+  };
+  const code = (stopAtBrace: boolean, depth: number) => {
+    if (depth > 128) fail();
+    let braces = 0;
+    while (index < source.length) {
+      const char = source[index]!, next = source[index + 1];
+      if (/\s/u.test(char)) { index++; continue; }
+      if (char === "/" && next === "/") {
+        index += 2; while (index < source.length && source[index] !== "\n") index++;
+        continue;
+      }
+      if (char === "/" && next === "*") {
+        const end = source.indexOf("*/", index + 2);
+        if (end < 0) fail(); index = end + 2; continue;
+      }
+      if (char === "'" || char === '"') { quoted(char); continue; }
+      if (source.charCodeAt(index) === 96) { template(depth + 1); continue; }
+      if (char === "}" && stopAtBrace && braces === 0) { index++; return; }
+      if (char === "{") braces++;
+      if (char === "}") braces--;
+      if (char === "/" && regexAllowed) { regex(); continue; }
+      if (wordStart(char)) {
+        const start = index++;
+        while (index < source.length && wordPart(source[index]!)) index++;
+        push("word", source.slice(start, index)); continue;
+      }
+      const pair = char + (next ?? "");
+      if (["=>", "&&", "||", "??", "++", "--", "?."].includes(pair)) { push("punct", pair); index += 2; }
+      else { push("punct", char); index++; }
+    }
+    if (stopAtBrace) fail();
+  };
+  code(false, 0);
+  return tokens;
+}
+
+/**
+ * Conservative ESM dependency/code-loading inspection, not a sandbox or proof against obfuscated privileged code.
+ * Literal messages/comments are inert. Direct code-loading names are refused even when aliased or shadowed.
+ */
+export function scanModuleSource(source: string): readonly Bun.Import[] {
+  try {
+    const transpiler = new Bun.Transpiler({ loader: "js", minifyWhitespace: true });
+    const imports = transpiler.scanImports(source);
+    if (imports.some(record => ["dynamic-import", "require-call", "require-resolve"].includes(record.kind))) fail();
+    const tokens = tokensOf(transpiler.transformSync(source));
+    for (const [index, token] of tokens.entries()) {
+      if (token.kind === "word" && forbiddenNames.has(token.value)) fail();
+      if (token.kind === "word" && token.value === "import" && tokens[index + 1]?.value === "(") fail();
+      if (token.kind === "string" && forbiddenNames.has(token.value) && tokens[index - 1]?.value === "[" && tokens[index + 1]?.value === "]") {
+        const owner = tokens[index - 2];
+        const importMeta = owner?.value === "meta" && tokens[index - 3]?.value === "." && tokens[index - 4]?.value === "import";
+        if (owner?.kind === "word" && globalNames.has(owner.value) || importMeta) fail();
+      }
+    }
+    return Object.freeze(imports.map(record => Object.freeze({ ...record })));
+  } catch { return fail(); }
+}