@staix/agent-hub 0.12.44 → 0.12.45

package/src/adapters/conformance/kit.ts

@@ -0,0 +1,50 @@
+import { expect, test } from "bun:test";
+import type { Envelope } from "../../hub/envelope.ts";
+import { newEnvelope } from "../../hub/envelope.ts";
+import type { PeerAdapter } from "../../hub/peers.ts";
+
+export async function until(condition: () => boolean, label: string): Promise<void> {
+  const deadline = Date.now() + 5000;
+  while (!condition() && Date.now() < deadline) await Bun.sleep(10);
+  expect(condition(), label).toBe(true);
+}
+export interface ConformanceFixture {
+  peer: PeerAdapter;
+  messages: string[];
+  /** Claude's native hooks own busy; channel insertion itself has no native acceptance evidence. */
+  busyOnDeliver: boolean;
+  settle?(): Promise<void>;
+  verifyTransport(): void | Promise<void>;
+  close(): Promise<void>;
+}
+export interface AdapterConformance {
+  kind: string;
+  create(): Promise<ConformanceFixture>;
+}
+
+/** Shared observable contract; every invocation uses the real adapter and its fake native transport. */
+export function registerConformance(adapter: AdapterConformance): void {
+  test(`P4 ${adapter.kind}: transport delivery, synchronous occupancy and owned teardown`, async () => {
+    const f = await adapter.create();
+    try {
+      expect(f.peer.id).toBe(adapter.kind);
+      expect(f.peer.state).toBe("idle");
+      const envelope: Envelope = newEnvelope("user", "conformance ping", { to: [adapter.kind] });
+      const delivering = f.peer.deliver([envelope]);
+      // Attach the rejection observer before teardown, even if an assertion fails while delivery is pending.
+      const outcome = delivering.then(() => undefined, error => error as Error);
+      expect(f.peer.state).toBe(f.busyOnDeliver ? "busy" : "idle");
+      expect(await outcome).toBeUndefined();
+      await f.settle?.();
+      await until(() => f.messages.length === 1 && f.peer.state === "idle", `${adapter.kind} one settled reply`);
+      expect(f.messages[0]).not.toBeEmpty();
+      await f.verifyTransport();
+      const metadata = f.peer.recoveryMetadata?.();
+      expect(JSON.stringify(metadata ?? {})).not.toContain("conformance ping");
+    } finally { await f.close(); }
+    await until(() => f.peer.state === "offline", `${adapter.kind} stop observed offline`);
+  }, 20_000);
+}
+
+/** Host-owned authenticated channel fixtures share the observable delivery contract, not a driven native factory. */
+export function registerExternalChannelConformance(adapter: AdapterConformance): void { registerConformance(adapter); }

package/src/adapters/conformance/local-pi.ts

@@ -0,0 +1,100 @@
+import { expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { LocalPeer } from "../local-worker.ts";
+import type { PiPeer } from "../pi.ts";
+import { OmniRoute } from "../../omniroute/client.ts";
+import { newEnvelope } from "../../hub/envelope.ts";
+import { startFakeModelServer, toolCall } from "./fakes/model-server.ts";
+import { until } from "./kit.ts";
+import { fakePaths } from "./fake-paths.ts";
+import type { AdapterDefinition } from "../registry-types.ts";
+import { createFromDefinition, expire } from "./factories.ts";
+
+
+export function registerLocalConformance(definition: AdapterDefinition, { label = definition.displayName }: { label?: string } = {}): void {
+  if (definition.start.daemonPort !== "local-worker") throw new Error(definition.kind + ": conformance requires local-worker transport factory");
+  test(`P4 ${label}: a consumed model result from an expired generation cannot publish into the next turn`, async () => {
+    const dir = mkdtempSync(join(tmpdir(), "conformance-local-late-"));
+    let release = () => {}, observed = false, parsed = () => {};
+    const parsedLate = new Promise<void>(resolve => { parsed = resolve; });
+    const server = startFakeModelServer({ key: "conformance-key", script: async body => {
+      const text = String(body.messages.at(-1)?.content);
+      if (text.includes("OLD_GENERATION")) await new Promise<void>(resolve => { release = resolve; observed = true; });
+      return { content: text.includes("OLD_GENERATION") ? "stale answer" : "current answer" };
+    } });
+    const oldUrl = process.env.AGENTHUB_OMNIROUTE_URL, oldKey = process.env.OMNIROUTE_API_KEY;
+    process.env.AGENTHUB_OMNIROUTE_URL = server.url; process.env.OMNIROUTE_API_KEY = "conformance-key";
+    const omni = new OmniRoute({ urls: [server.url], access_hosts: [] }), chat = omni.chat.bind(omni);
+    omni.chat = async (body, options = {}) => {
+      const old = String(body.messages.at(-1)?.content).includes("OLD_GENERATION");
+      const result = await chat(body, old ? { ...options, signal: undefined } : options);
+      if (old) parsed(); return result;
+    };
+    const messages: string[] = [];
+    const peer = createFromDefinition<LocalPeer>(definition, { local: { cwd: dir, omni, fixedModel: "vllm/fixed", tools: { deny: [], permit: async () => false } } });
+    peer.onMessage = text => { messages.push(text); };
+    let oldTurn: Promise<void> | undefined;
+    try {
+      await peer.start(); oldTurn = peer.deliver([newEnvelope("user", "OLD_GENERATION")]); oldTurn.catch(() => {});
+      await until(() => observed, "old gateway call held"); expire(peer);
+      expect(peer.state).toBe("idle");
+      await peer.deliver([newEnvelope("user", "CURRENT_GENERATION")]);
+      await until(() => messages.length === 1, "new generation publishes");
+      release(); await parsedLate; await oldTurn; await new Promise<void>(resolve => setImmediate(resolve));
+      expect(messages).toEqual(["current answer"]); expect(peer.state).toBe("idle");
+    } finally { release(); await peer.stop(); await oldTurn?.catch(() => {}); server.stop();
+      if (oldUrl === undefined) delete process.env.AGENTHUB_OMNIROUTE_URL; else process.env.AGENTHUB_OMNIROUTE_URL = oldUrl;
+      if (oldKey === undefined) delete process.env.OMNIROUTE_API_KEY; else process.env.OMNIROUTE_API_KEY = oldKey;
+      rmSync(dir, { recursive: true, force: true }); }
+  });
+
+  test(`P4 ${label}: tool approval refusal prevents the write and hub tools use the host callback`, async () => {
+    const dir = mkdtempSync(join(tmpdir(), "conformance-local-approval-")), path = join(dir, "a.txt"); writeFileSync(path, "before");
+    const asked: string[] = [], called: string[] = [];
+    const server = startFakeModelServer({ key: "conformance-key", script: body => {
+      const tools = body.messages.filter(message => message.role === "tool").length;
+      return tools === 0 ? { tool_calls: [toolCall("write", { path: "a.txt", content: "after" })] }
+        : tools === 1 ? { tool_calls: [toolCall("hub_task_list", {})] } : { content: "done" };
+    } });
+    const oldUrl = process.env.AGENTHUB_OMNIROUTE_URL, oldKey = process.env.OMNIROUTE_API_KEY;
+    process.env.AGENTHUB_OMNIROUTE_URL = server.url; process.env.OMNIROUTE_API_KEY = "conformance-key";
+    const peer = createFromDefinition<LocalPeer>(definition, { local: { cwd: dir, omni: new OmniRoute({ urls: [server.url], access_hosts: [] }), fixedModel: "vllm/fixed",
+      tools: { deny: [], permit: async title => { asked.push(title); return false; } }, taskTool: async name => { called.push(name); return "[]"; } } });
+    try {
+      await peer.start(); await peer.deliver([newEnvelope("user", "edit and list tasks")]);
+      await until(() => peer.state === "idle", "local tools settled");
+      expect(readFileSync(path, "utf8")).toBe("before"); expect(asked).toHaveLength(1); expect(called).toEqual(["hub_task_list"]);
+    } finally { await peer.stop(); server.stop(); if (oldUrl === undefined) delete process.env.AGENTHUB_OMNIROUTE_URL; else process.env.AGENTHUB_OMNIROUTE_URL = oldUrl;
+      if (oldKey === undefined) delete process.env.OMNIROUTE_API_KEY; else process.env.OMNIROUTE_API_KEY = oldKey;
+      rmSync(dir, { recursive: true, force: true }); }
+  });
+
+}
+
+export function registerPiConformance(definition: AdapterDefinition, { label = definition.displayName }: { label?: string } = {}): void {
+  if (definition.start.daemonPort !== "pi-rpc") throw new Error(definition.kind + ": conformance requires pi-rpc transport factory");
+  test(`P4 ${label}: recovery resumes its exact persisted session and rejects a stale bridge generation`, async () => {
+    const dir = mkdtempSync(join(tmpdir(), "conformance-pi-resume-")), stateDir = join(dir, "state"), sessions = join(stateDir, "pi-sessions");
+    mkdirSync(sessions, { recursive: true });
+    const sessionFile = join(sessions, "saved-session.jsonl"); writeFileSync(sessionFile, JSON.stringify({ type: "session", id: "saved-session", cwd: dir }) + "\n");
+    const peer = createFromDefinition<PiPeer>(definition, { pi: { cwd: dir, stateDir, sessionFile, mode: "headless", backend: "dgx", cmd: [process.execPath, fakePaths.piRpc],
+      relay: { url: "http://127.0.0.1:9/v1", token: "fixture", models: [{ id: "dgx/coding" }] }, tools: [], executeTool: async () => "fixture" } });
+    const messages: string[] = []; peer.onMessage = text => { messages.push(text); };
+    try {
+      await peer.start(); expect(peer.recoveryMetadata()).toMatchObject({ sessionId: "saved-session", sessionFile });
+      const launch = peer.tuiLaunch!;
+      const event = async (body: unknown) => fetch(`${launch.env.AGENTHUB_PI_BRIDGE_URL}/event`, { method: "POST", headers: { authorization: `Bearer ${launch.env.AGENTHUB_PI_BRIDGE_TOKEN}`, "content-type": "application/json" }, body: JSON.stringify(body) });
+      await peer.deliver([newEnvelope("user", "resumed turn")]);
+      expect((await event({ type: "agent_start", generation: 3, sessionId: "saved-session" })).status).toBe(200);
+      await event({ type: "agent_end", generation: 2, text: "stale answer" });
+      await event({ type: "agent_settled", generation: 2 });
+      expect(peer.state).toBe("busy"); expect(messages).toEqual([]);
+      await event({ type: "agent_end", generation: 3, text: "current answer" });
+      await event({ type: "agent_settled", generation: 3 });
+      expect(peer.state).toBe("idle"); expect(messages).toEqual(["current answer"]);
+    } finally { await peer.stop(); rmSync(dir, { recursive: true, force: true }); }
+  });
+
+}

package/src/adapters/conformance/owned-acp.ts

@@ -0,0 +1,44 @@
+import { expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { JcodePeer } from "../jcode.ts";
+import { newEnvelope } from "../../hub/envelope.ts";
+import { fakePaths } from "./fake-paths.ts";
+import type { AdapterDefinition } from "../registry-types.ts";
+import { createFromDefinition, expire } from "./factories.ts";
+import { until } from "./kit.ts";
+
+
+/** The owned-ACP protocol flavor and its unmanaged mode ceiling are supplied explicitly. */
+export function registerOwnedAcpConformance(definition: AdapterDefinition, { label = definition.displayName, unmanagedReason }: { label?: string; unmanagedReason?: string } = {}): void {
+  if (definition.start.daemonPort !== "owned-acp") throw new Error(definition.kind + ": conformance requires owned-acp transport factory");
+  if (!unmanagedReason?.trim()) throw new Error(definition.kind + ": owned-ACP unmanaged mode reason must be explicit");
+  test(`P4 ${label}: watchdog waits for the consumed late native result without publishing it into a successor`, async () => {
+    const dir = mkdtempSync(join(tmpdir(), "conformance-jcode-watchdog-")), home = join(dir, "home"), release = join(dir, "release");
+    mkdirSync(home); writeFileSync(join(home, "mcp.json"), "{}");
+    const messages: string[] = [], failed: unknown[] = [];
+    const peer = createFromDefinition<JcodePeer>(definition, { jcode: { cwd: dir, home,
+      command: [process.execPath, fakePaths.jcodeAgent, "--steer-file", release],
+    } });
+    peer.onMessage = text => { messages.push(text); }; peer.onFailed = envelopes => { failed.push(envelopes); };
+    try {
+      await peer.start();
+      expect(unmanagedReason).toContain("no verified native permission-mode mapping");
+      expect(peer.permissionModeState).toBe("unmanaged");
+      await expect(peer.setPermissionMode("ask")).rejects.toThrow("no verified mode mapping");
+      await peer.deliver([newEnvelope("user", "old Jcode turn")]);
+      await until(() => existsSync(`${release}.busy`), "native Jcode consumed the held prompt");
+      expire(peer);
+      expect(peer.state).toBe("busy"); expect(messages).toEqual([]);
+      writeFileSync(release, "release");
+      // Returning idle proves the old prompt settled, not merely that a cancel notification was written.
+      await until(() => peer.state === "idle", "Jcode late prompt result consumed after watchdog cancellation");
+      expect(messages).toEqual([]); expect(failed).toEqual([]);
+      await peer.deliver([newEnvelope("user", "successor Jcode turn")]);
+      await until(() => messages.length === 1 && peer.state === "idle", "only the successor Jcode answer publishes");
+      expect(messages).toEqual(["JCODE_REPLY"]);
+    } finally { writeFileSync(release, "release"); await peer.stop(); rmSync(dir, { recursive: true, force: true }); }
+  }, 20_000);
+
+}

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,9 +152,10 @@ 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: [] },
@@ -147,7 +164,7 @@ export const NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition
       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-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-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.ts

@@ -1,3 +1,5 @@
+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 +11,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 +67,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 0.25.0 ACP (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(); }
+}