@staix/agent-hub 0.12.33 → 0.12.35

package/src/adapters/registry.ts

@@ -1,10 +1,23 @@
-import { BUILTIN_DEFINITIONS_WITHOUT_QWEN } from "./definitions/builtin-metadata.ts";
+import { builtinCliEntries } from "./definitions/native-cli-entry.ts";
+import { builtinPreview } from "./definitions/native-cli-preview.ts";
+import { DAEMON_PORTS } from "./definitions/native-factories.ts";
+export { DAEMON_PORTS };
+import { NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN } from "./definitions/builtin-metadata.ts";
 import { QWEN_DEFINITION } from "./definitions/qwen.ts";
-import type { AdapterDefinition } from "./registry-types.ts";
+import type { AdapterDefinition, KindMap } from "./registry-types.ts";
+import { types } from "node:util";
 
 export type * from "./registry-types.ts";
 export const ADAPTER_API = 1;
 
+/** Ordered compatibility projections stay typed independently of definition implementation inference. */
+export const KNOWN_PEERS = ["claude", "codex", "kimi", "pi", "local"] as const;
+export const OPTIONAL_PEERS = ["qwen", "jcode"] as const;
+export const SUPPORTED_PEERS = [...KNOWN_PEERS, ...OPTIONAL_PEERS] as const;
+export const START_MODE_PEERS = ["pi", "codex", "kimi"] as const;
+export const OFFICE_PEER_ORDER: readonly string[] = KNOWN_PEERS;
+
+
 function immutable<T>(value: T, seen = new WeakSet<object>()): T {
   if (!value || typeof value !== "object" || seen.has(value)) return value;
   seen.add(value);
@@ -12,25 +25,128 @@ function immutable<T>(value: T, seen = new WeakSet<object>()): T {
   return Object.freeze(value);
 }
 
+const fixedBuiltinDefinitions = new Set<AdapterDefinition>([...NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN, QWEN_DEFINITION]);
+
 /** Keep the native catalog's order, independently of the legacy default-role object order. */
 export const ADAPTERS: readonly AdapterDefinition[] = immutable([
-  ...BUILTIN_DEFINITIONS_WITHOUT_QWEN.filter(definition => definition.kind !== "jcode"),
+  ...NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN.filter(definition => definition.kind !== "jcode"),
   QWEN_DEFINITION,
-  ...BUILTIN_DEFINITIONS_WITHOUT_QWEN.filter(definition => definition.kind === "jcode"),
+  ...NATIVE_BUILTIN_DEFINITIONS_WITHOUT_QWEN.filter(definition => definition.kind === "jcode"),
 ]);
 const definitions = new Map<string, AdapterDefinition>();
 for (const definition of ADAPTERS) {
+  assertDaemonEngine(definition);
+  assertNativeCapabilityScope(definition);
   if (definition.api !== ADAPTER_API || definitions.has(definition.kind)) throw new Error("invalid builtin adapter registry");
   definitions.set(definition.kind, definition);
 }
 
-/** A1 registers kinds only. Undeclared suffixes never acquire a native kind or admission. */
-export function kindOf(id: string): string | undefined {
-  return definitions.has(id) ? id : undefined;
+/** Native quota handoff platform names, distinct from per-delivery recall injection policy. */
+export const QUOTA_HANDOFF_PLATFORMS: Readonly<Record<string, string>> = Object.freeze(Object.fromEntries(
+  ADAPTERS.flatMap(adapter => adapter.hooks?.recallPlatform ? [[adapter.kind, adapter.hooks.recallPlatform]] : []),
+));
+
+/** Declaration reads never execute caller accessors or inherit another project's mapping. */
+function declaredKind(id: string, instances: KindMap | undefined): string | undefined {
+  if (!instances || typeof instances !== "object" || types.isProxy(instances) || Array.isArray(instances)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(instances))) return undefined;
+  const field = Object.getOwnPropertyDescriptor(instances, id);
+  if (!field || !Object.hasOwn(field, "value") || !field.enumerable) return undefined;
+  const entry: unknown = field.value;
+  if (!entry || typeof entry !== "object" || types.isProxy(entry) || Array.isArray(entry)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(entry))) return undefined;
+  const kind = Object.getOwnPropertyDescriptor(entry, "kind");
+  if (!kind || !Object.hasOwn(kind, "value") || !kind.enumerable || typeof kind.value !== "string" || !definitions.has(kind.value)) return undefined;
+  const prefix = `${kind.value}-`;
+  return /^[a-z][a-z0-9-]{0,31}$/.test(id) && id.startsWith(prefix) && /^[a-z0-9][a-z0-9-]*$/.test(id.slice(prefix.length)) ? kind.value : undefined;
+}
+/** Legacy ids retain their identity. Extra instances resolve only through the explicit project map. */
+export function kindOf(id: string, instances?: KindMap): string | undefined {
+  return definitions.has(id) ? id : typeof id === "string" ? declaredKind(id, instances) : undefined;
+}
+export function definitionOf(id: string, instances?: KindMap): AdapterDefinition | undefined {
+  const kind = kindOf(id, instances);
+  return kind === undefined ? undefined : definitions.get(kind);
 }
-export function definitionOf(id: string): AdapterDefinition | undefined {
-  return definitions.get(id);
+export function familyOf(id: string, instances?: KindMap): string | undefined {
+  return definitionOf(id, instances)?.family;
 }
-export function familyOf(id: string): string | undefined {
-  return definitionOf(id)?.family;
+
+/** Compatibility projection order is observable in default role maps and planner selection. */
+const ROLE_ORDER = ["claude", "codex", "kimi", "local", "pi", "qwen", "jcode"] as const;
+export const PLANNER_PEERS = ["claude", "codex", "kimi", "qwen", "jcode"] as const;
+
+/** Callers own their role arrays, independent of immutable native policy. */
+export function defaultPeerRoles(includeOptional = false): Record<string, string[]> {
+  return Object.fromEntries(ROLE_ORDER.filter(peer => includeOptional || !definitionOf(peer)!.optional)
+    .map(peer => [peer, [...definitionOf(peer)!.roles]]));
+}
+
+/** Preserve the tool schema's legacy preferred order without spreading native names into tools. */
+const CONDUCTOR_START_PRIORITY = ["local", "kimi", "pi"] as const;
+export const CONDUCTOR_START_PEERS = [
+  ...CONDUCTOR_START_PRIORITY,
+  ...ADAPTERS.filter(adapter => !(CONDUCTOR_START_PRIORITY as readonly string[]).includes(adapter.kind)).map(adapter => adapter.kind),
+];
+
+/** A missing definition retains external-id admission; Pi's legacy enabled switch controls its default only. */
+export function defaultRosterEnabled(peer: string, piEnabled: boolean): boolean {
+  const definition = definitionOf(peer);
+  if (!definition) return true;
+  return definition.kind === "pi" ? piEnabled : definition.defaultOnRoster ?? false;
 }
+
+/** A factory must name one existing engine; metadata never creates a caller-controlled port. */
+export function assertDaemonEngine(definition: Pick<AdapterDefinition, "start">): void {
+  const engine = definition.start.daemonPort;
+  if (definition.start.create && engine === undefined || engine !== undefined && !Object.hasOwn(DAEMON_PORTS, engine)) throw new Error("invalid adapter daemon engine");
+}
+
+/** Host-global native quirks are not capabilities a config-only or external definition may opt into. */
+export function assertNativeCapabilityScope(definition: AdapterDefinition): void {
+  if (fixedBuiltinDefinitions.has(definition)) return;
+  const declared = (block: object | undefined, key: string): boolean => block !== undefined && key in block;
+  const restricted: [string, boolean][] = [
+    ["start.acpCommand", declared(definition.start, "acpCommand")],
+    ["attach.admission", declared(definition.attach, "admission")],
+    ["budget.resetSoftTokensOnResume", declared(definition.budget, "resetSoftTokensOnResume")],
+    ["session.crashIdentity", declared(definition.session, "crashIdentity")],
+    ["start.daemonPort pi-rpc", definition.start.daemonPort === "pi-rpc"],
+    ["routing", definition.routing !== undefined],
+  ];
+  const field = restricted.find(([, present]) => present)?.[0];
+  if (field) throw new Error(`${field} is restricted to fixed builtin adapter definitions`);
+}
+
+/** Ordered catalog projections consumed by generic core hosts. */
+export const STARTABLE_PEERS = SUPPORTED_PEERS;
+export type SupportedPeer = typeof SUPPORTED_PEERS[number];
+export function isSupportedPeer(peer: unknown): peer is SupportedPeer { return typeof peer === "string" && definitionOf(peer) !== undefined; }
+export function isStartablePeer(peer: unknown): peer is SupportedPeer { return typeof peer === "string" && definitionOf(peer)?.start.conductorStartable === true; }
+
+/** Body-free browser metadata, derived from the same native participation and managed-tool contracts. */
+export const ADAPTER_DISPLAY = Object.fromEntries(ADAPTERS.map(adapter => [adapter.kind, {
+  pullOnlyRead: adapter.attach?.pullOnlyForms?.includes("tui") === true,
+  terminalApproval: adapter.trust.hubSandboxed,
+}]));
+
+export { NATIVE_CONFIG_BLOCKS, nativeConfigurationDefaults, mergeNativeConfiguration, retainNativeRouting } from "./definitions/native-config-defaults.ts";
+
+/** Private fixed-builtin preview implementation; not an adapter extension or configurable callback. */
+export function builtinPreviewOf(id: string) {
+  const definition = definitionOf(id);
+  return definition ? builtinPreview(definition) : undefined;
+}
+
+/** Fixed builtin doctor metadata and pure observed-value projections; the CLI retains all probe effects. */
+export { DOCTOR_TOOL_PROBES, DOCTOR_MEMORY_CAPTURE_PEERS, DOCTOR_PLUGIN_PROBE, nativeDoctorCheck, nativeDoctorRecoveryIdentity, nativeDoctorOptionalProbes } from "./definitions/native-cli-doctor.ts";
+
+/** Internal fixed builtin CLI entries; public AdapterDefinition and NativeHooks expose no execution extension. */
+export const BUILTIN_CLI_ENTRIES = Object.freeze(builtinCliEntries.map(entry => {
+  const definition = definitionOf(entry.command);
+  if (!definition) throw new Error("builtin CLI entry has no adapter definition");
+  return Object.freeze({ ...entry, definition });
+}));
+
+/** Private fixed-builtin stream presentation; does not widen the public palette object. */
+export { nativeStreamTone } from "./definitions/native-display.ts";

package/src/cli/console-state.ts

@@ -2,7 +2,7 @@ import { consoleNeeds, characterAttentionLine, attentionCommand } from "./attent
 import { CHARACTERS, petFrame, petSize, petFooterRows, type CharacterId, type PetSize, type PetPose } from "../pet/frame.ts";
 import { PEER_PALETTE } from "../ui/peer-palette.ts";
 import { PERMISSION_MODES, permissionBoundary } from "../hub/permission-mode.ts";
-import { PLANNER_PEERS } from "../hub/peer-catalog.ts";
+import { PLANNER_PEERS, definitionOf, nativeStreamTone } from "../adapters/registry.ts";
 import { taskProgress } from "../ui/task-progress.ts";
 import type { ProgressStage } from "../ui/task-progress.ts";
 import { sanitize } from "../hub/envelope.ts";
@@ -114,7 +114,6 @@ export function paint(line: Span[], color: boolean): string {
 export function streamTokens(value: string, eventTone?: Tone, kind?: string): Span[] {
   const text = terminalText(value);
   if (kind === "command" || kind === "console") return [{ text }];
-  const peers: Readonly<Record<string, Tone>> = { claude: "peerClaude", codex: "peerCodex" };
   // Hub-written peer slots only; words such as local/pi/hub in a title do not identify a speaker.
   const peerSlots = new Set<number>();
   const leading = text.match(/^\s*(?:[.?*!]\s+)?([A-Za-z_][A-Za-z_0-9-]*)(?=:| is | asks permission:| permission )/);
@@ -143,6 +142,7 @@ export function streamTokens(value: string, eventTone?: Tone, kind?: string): Sp
     const gap = text.slice(end, start);
     if (gap) out.push({ text: gap });
     let tone: Tone | undefined;
+    const peerTone = nativeStreamTone(token);
     // ponytail: legacy notices have no typed reference ranges. Classify task/review prefixes textually;
     // assign/which #N remains an issue reference until notices carry structured reference spans.
     if (token.startsWith("#")) {
@@ -152,7 +152,7 @@ export function streamTokens(value: string, eventTone?: Tone, kind?: string): Sp
     }
     else if (start === taskKeywordAt) tone = "taskKeyword";
     else if (/^[0-9]/.test(token) && !permissionIds.has(start)) tone = "number";
-    else if (peerSlots.has(start) && Object.hasOwn(peers, token)) tone = peers[token];
+    else if (peerSlots.has(start) && peerTone) tone = peerTone;
     else if (start === markerAt || start === stateAt || (route && token === "->" && start < route[0].length)) tone = eventTone;
     out.push({ text: token, ...(tone ? { tone } : {}) });
     previousToken = token; previousStart = start; end = start + token.length;
@@ -749,7 +749,7 @@ export function cells(s: ConsoleState, row: any, selected: boolean, now: number,
       : row.paused === "manual" ? "user" : row.paused ? String(row.paused).split(":")[0] : "-";
     return [id(row.planner ? `${row.id} (planner)` : row.id, row.state === "offline" ? undefined : "info"), span(row.rostered === false ? `${row.state} off roster` : row.state, stateTone(row.state)),
       ...(showPermissionModes(s) ? [span(row.permissionMode && row.permissionMode !== "ask" ? row.permissionMode : "-", row.permissionMode === "never-ask" ? "attention" : undefined)] : []),
-      span(row.pullOnly && row.id === "kimi" ? "pull-only" : row.toolsOnly ? "tools-only" : row.attached === false ? "detached" : "attached", row.toolsOnly ? "attention" : undefined),
+      span(row.pullOnly && definitionOf(row.id)?.attach?.pullOnlyForms?.includes("tui") ? "pull-only" : row.toolsOnly ? "tools-only" : row.attached === false ? "detached" : "attached", row.toolsOnly ? "attention" : undefined),
       span(count(row.queued)), span(count(row.queuedImportant), row.queuedImportant ? "attention" : undefined),
       span(count(row.needsReview), row.needsReview ? "failure" : undefined), span(paused, paused === "-" ? undefined : "attention"),
       span(b?.windows?.length ? b.windows.map((w: any) => `${w.id} ${Math.round(w.used * 100)}%${typeof w.resetsAt === "number" ? ` ${relative(w.resetsAt, now)}` : ""}`).join(", ") : "-"),
@@ -890,7 +890,7 @@ export function renderConsoleLines(s: ConsoleState, columns: number, rows = 24,
     if (p.permissionMode && p.permissionMode !== "ask") summary.push(span(` ${p.permissionMode}`, "attention"));
     if (p.needsReview) summary.push(span(` review${p.needsReview}`, "failure"));
     if (p.paused) summary.push(span(" paused", "attention"));
-    if (p.toolsOnly) summary.push(span(id === "kimi" ? ` pull-only, read ${typeof p.lastInboxAt === "number" ? relative(p.lastInboxAt, now) : "never"}` : " tools-only: ahub claude", "attention"));
+    if (p.toolsOnly) summary.push(span(definitionOf(id)?.attach?.pullOnlyForms?.includes("tui") ? ` pull-only, read ${typeof p.lastInboxAt === "number" ? relative(p.lastInboxAt, now) : "never"}` : " tools-only: ahub claude", "attention"));
   }
   if (s.pendingRestart?.length) summary.push(span(`${summary.length ? " | " : ""}restart pending: ${s.pendingRestart.map(row => row.key).join(", ")}`, "attention"));
   const quotas = Object.entries(s.budget).map(([id, b]) => `${id}:${b.windows?.map((w: any) => `${w.id} ${Math.round(w.used * 100)}%`).join("/") ?? "?"}`).join(" ");

package/src/cli/identity.ts

@@ -1,5 +1,5 @@
 import { recoveryPresentationFlag } from "./recovery-presentation-options.ts";
-import { isSupportedPeer } from "../hub/peer-catalog.ts";
+import { definitionOf, kindOf, type KindMap } from "../adapters/registry.ts";
 
 /** Recovery reads this declaration before delegating to another package's CLI. */
 export const LIVE_TEST_SUPPORTED = true;
@@ -29,7 +29,7 @@ export type CliIdentity =
   | { role: "invalid"; reason: string };
 
 /** Honest defaults for native shells, not authentication against an agent that can edit its environment. */
-export function detectCliIdentity(env: Readonly<Record<string, string | undefined>>): CliIdentity {
+export function detectCliIdentity(env: Readonly<Record<string, string | undefined>>, instances?: KindMap): CliIdentity {
   const hub = env.AGENTHUB_PEER_ID;
   const claude = env.CLAUDECODE;
   const session = env.CLAUDE_CODE_SESSION_ID;
@@ -42,7 +42,7 @@ export function detectCliIdentity(env: Readonly<Record<string, string | undefine
   if (session !== undefined && claude === undefined) return invalid("CLAUDE_CODE_SESSION_ID without CLAUDECODE marker");
   if (claude !== undefined && codex !== undefined) return invalid("conflicting native agent markers");
   const native = claude !== undefined ? "claude" : codex !== undefined ? "codex" : undefined;
-  if (hub !== undefined && native !== undefined && hub !== native) return invalid("AGENTHUB_PEER_ID conflicts with native agent marker");
+  if (hub !== undefined && native !== undefined && (kindOf(hub, instances) ?? hub) !== native) return invalid("AGENTHUB_PEER_ID conflicts with native agent marker");
   const peer = hub ?? native;
   return peer === undefined ? { role: "console" } : { role: "tools", peer };
 }
@@ -52,7 +52,8 @@ export type PeerCommandAccess = "allowed" | "conductor" | "console";
 /** A closed list: unknown commands cannot acquire console authority through an agent shell. */
 export function classifyPeerCommand(command: string, args: readonly string[]): PeerCommandAccess {
   if (command === "recovery" && recoveryAction(args) === "reattach") return "console";
-  if (command === "pi" && args.includes("--replace-session")) return "console";
+  const native = definitionOf(command);
+  if (native?.cli.personOnlyFlags?.some(flag => args.includes(flag))) return "console";
   if (command === "pet" && args.includes("--window")) return "console";
   if (command === "permission" || command === "stop" || command === "watch") return "console";
   if (args.some((arg) => arg === "--as-user" || arg.startsWith("--as-user="))) return "console";
@@ -72,8 +73,8 @@ export function classifyPeerCommand(command: string, args: readonly string[]): P
   // The subcommand is the first argument that is not --json, which the command accepts anywhere.
   if (command === "bench") return args.find((arg) => arg !== "--json") === "run" ? "console" : "allowed";
   if (command === "budget") return !args.length || args.every((arg) => arg === "--json" || arg === "--full" || arg.startsWith("--color=")) ? "allowed" : "console";
-  if (command === "jcode") return "console"; // the person launcher alone writes its project MCP entry
-  if (isSupportedPeer(command) || ["pause", "resume"].includes(command)) return "conductor";
+  if (native?.cli.authority === "person") return "console";
+  if (native || ["pause", "resume"].includes(command)) return "conductor";
   if (command === "board" && args[0] === "import") return "console";
   if (["help", "version", "--version", "say", "status", "pet", "board", "report", "turns", "review", "remember", "facts", "check-path"].includes(command)) return "allowed";
   return "console";
@@ -84,7 +85,7 @@ export function cliCommandLabel(command: string, args: readonly string[]): strin
   if (command === "backlog") return ["list", "add", "pull", "pull-ready", "split", "return", "plan", "pin", "undo"].includes(args[0] ?? "") ? `backlog ${args[0]}` : "backlog";
   if (command === "board" && args[0] === "import") return "board import";
   if (command === "release") return ["new", "list", "show", "plan", "activate", "freeze", "ship", "drop"].includes(args[0] ?? "") ? `release ${args[0]}` : "release";
-  if (!["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "claude", "codex", "kimi", "qwen", "jcode", "pi", "local", "stop", "models", "say", "queue", "tail", "watch", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "settings", "roster", "status", "pet", "logs", "export", "report", "research", "memory", "goal", "bench", "sdlc", "role", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor"].includes(command)) return "unknown";
+  if (!definitionOf(command) && !["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "stop", "models", "say", "queue", "tail", "watch", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "settings", "roster", "status", "pet", "logs", "export", "report", "research", "memory", "goal", "bench", "sdlc", "role", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor"].includes(command)) return "unknown";
   if (["task", "queue", "budget", "route", "recovery", "models", "projects", "research", "memory", "goal", "bench"].includes(command)) {
     const sub = command === "bench" || command === "memory" || command === "goal" ? args.find((arg) => arg !== "--json") : args[0];
     if (sub && ["propose", "show", "assign", "unassign", "escalate", "label", "list", "resolve", "resume", "set", "execution", "explain", "status", "abort", "dispose", "reattach", "setup", "start", "stop", "remove", "export", "backfill", "addons", "run", "report", "compare", "search", "graph", "promote", "demote", "forget", "supersede", "dedupe", "decay", "rebuild", "sync", "machine", "import", "suggestions", "confirm", "reject", "new", "link", "state", "done", "take"].includes(sub)) return `${command} ${sub}`;

package/src/cli/jcode-mcp.ts

@@ -1,58 +1,2 @@
-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 };
-}
+/** Compatibility exports; the project MCP layer is native adapter policy. */
+export { JCODE_MCP_FILE, JCODE_MCP_NAME, jcodeMcpEntry, jcodeMcpReady, configureJcodeMcp } from "../adapters/definitions/native-cli-jcode-mcp.ts";

package/src/cli/launch.ts

@@ -6,38 +6,46 @@ import { resolve, join, basename, dirname, isAbsolute } from "node:path";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
 import { realPath } from "../hub/project.ts";
 import { peerChildEnv, processTable } from "../hub/child-process.ts";
+import { definitionOf } from "../adapters/registry.ts";
+import type { InstancesConfig } from "../hub/instances.ts";
+import { kimiAcpCommand } from "../adapters/definitions/native-daemon-kimi.ts";
 export const CLAUDE_CHANNEL = "plugin:agent-hub@agent-hub";
 
+/** Consume only ahub's selector, never native arguments after the passthrough delimiter. */
+export function instanceLaunchArguments(command: string, raw: readonly string[], instances?: InstancesConfig): { instance?: string; args: string[] } {
+  if (!definitionOf(command)) return { args: [...raw] };
+  const args: string[] = [];
+  let instance: string | undefined;
+  for (let index = 0; index < raw.length; index++) {
+    const arg = raw[index]!;
+    if (arg === "--") { args.push(...raw.slice(index)); break; }
+    if (arg !== "--as" && !arg.startsWith("--as=")) { args.push(arg); continue; }
+    if (instance !== undefined) throw new Error("--as may appear only once");
+    const id = arg === "--as" ? raw[++index] : arg.slice("--as=".length);
+    if (!id || id.startsWith("--")) throw new Error("--as needs a declared instance id");
+    const declaration = instances && Object.hasOwn(instances, id) ? instances[id] : undefined;
+    if (!declaration || declaration.kind !== command || !definitionOf(id, instances)) throw new Error("--as must name a declared instance of this command's native kind");
+    instance = id;
+  }
+  return { ...(instance ? { instance } : {}), args };
+}
+
+/** Only an authenticated daemon hello can authorize extra-instance effects. */
+export function requirePeerInstances(features: unknown): void {
+  if (!Array.isArray(features) || !features.includes("peer_instances")) throw new Error("running hub lacks peer_instances; upgrade it before starting an extra instance");
+}
+
 /** Launch identity belongs to the native child, never to the agent that invoked the wrapper. */
-export function nativeLaunchEnv(tool: "claude" | "codex" | "pi" | "kimi", source: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+export function nativeLaunchEnv(tool: string, source: NodeJS.ProcessEnv, instances?: InstancesConfig): NodeJS.ProcessEnv {
   const env = peerChildEnv(tool, source);
   delete env.AGENTHUB_UNATTENDED;
   // Channel evidence for the plugin (issue #205): set beside the development-channel flag `buildLaunch` always passes.
-  if (tool === "claude") env.AGENTHUB_CHANNEL = "1";
-  if (tool === "kimi") delete env.AGENTHUB_MODE; // its MCP child must attach pull-only, never as a tools socket
+  const definition = definitionOf(tool, instances);
+  if (definition?.identity.mcp === "channel-plugin") env.AGENTHUB_CHANNEL = "1";
+  if (definition?.attach?.pullOnlyForms?.includes("tui")) delete env.AGENTHUB_MODE; // its MCP child must attach pull-only, never as a tools socket
   return env;
 }
 
-/** A scoped candidate MCP server can be selected without promoting the installed plugin. */
-function claudeChannel(userArgs: string[]): string {
-  const bundle = resolve(import.meta.dir, "../../plugins/agent-hub/server.js");
-  for (let i = 0; i < userArgs.length; i++) {
-    const arg = userArgs[i]!;
-    const path = arg === "--mcp-config" ? userArgs[i + 1] : arg.startsWith("--mcp-config=") ? arg.slice("--mcp-config=".length) : undefined;
-    if (!path) continue;
-    try {
-      const server = JSON.parse(readFileSync(resolve(path), "utf8")).mcpServers?.["agent-hub"];
-      if (server?.command === "bun" && Array.isArray(server.args) && server.args.some((value: unknown) => typeof value === "string" && resolve(value) === bundle)) return "server:agent-hub";
-    } catch { /* The native CLI reports invalid user-supplied MCP configuration. */ }
-  }
-  return CLAUDE_CHANNEL;
-}
-
-const OWNED: Record<"claude" | "codex", string[]> = {
-  claude: ["--dangerously-load-development-channels", "--dangerously-skip-permissions"],
-  codex: ["--remote", "--yolo", "--dangerously-bypass-approvals-and-sandbox"],
-};
-
 export const UNATTENDED_WARNING =
   "WARNING: --unattended disables permission prompts. Other agents' messages are untrusted input and this agent will act on its own judgment without asking you.";
 
@@ -306,91 +314,22 @@ export function sessionSettings(tee?: StatusLineTee, facts?: FactsHook): string
 export function buildLaunch(
   tool: "claude" | "codex",
   userArgs: string[],
-  ctx: { unattended: boolean; proxyUrl?: string; codexBin?: string; statusLine?: StatusLineTee; facts?: FactsHook; preview?: boolean },
+  ctx: { instance?: string; unattended: boolean; proxyUrl?: string; codexBin?: string; statusLine?: StatusLineTee; facts?: FactsHook; preview?: boolean },
 ): Launch {
-  // Hub-level switches are consumed here; everything else passes through to the tool.
-  const passthrough = userArgs.filter((a) => !["--unattended", "--safe", "--new"].includes(a));
-  const dup = passthrough.find((a) => OWNED[tool].some((flag) => a === flag || a.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 || userArgs.includes("--unattended");
-  const warning = unattended ? { warning: UNATTENDED_WARNING } : {};
-  if (tool === "claude") {
-    // `--settings` takes one value, so a user-supplied one wins and Claude has no quota source for that session.
-    const own = passthrough.some((a) => a === "--settings" || a.startsWith("--settings="));
-    let settingsArgs = ctx.statusLine && !own ? ["--settings", sessionSettings(ctx.statusLine, ctx.facts)] : [];
-    let nativeArgs = passthrough;
-    let settingsFile: string | undefined;
-    if (own) {
-      if (passthrough.filter(a => a === "--settings" || a.startsWith("--settings=")).length > 1) throw new Error("pass --settings only once so the hub permission hook stays installed");
-      const index = passthrough.findIndex(a => a === "--settings" || a.startsWith("--settings="));
-      const arg = passthrough[index]!;
-      const value = arg === "--settings" ? passthrough[index + 1] : arg.slice("--settings=".length);
-      if (!value) throw new Error("--settings requires a JSON object or readable file so the hub permission hook can be installed");
-      let caller: Record<string, unknown>;
-      try {
-        caller = JSON.parse(value.trim().startsWith("{") ? value : readFileSync(resolve(value), "utf8"));
-        if (!caller || typeof caller !== "object" || Array.isArray(caller)) throw new Error("not an object");
-      } catch { throw new Error("cannot read --settings as a JSON object; the hub permission hook must be installed"); }
-      if (ctx.facts && caller.disableAllHooks === true) throw new Error("--settings disableAllHooks prevents the required hub permission hook; enable hooks to launch");
-      const injected = JSON.parse(sessionSettings(undefined, ctx.facts));
-      const callerHooks = caller.hooks;
-      if (callerHooks !== undefined && (!callerHooks || typeof callerHooks !== "object" || Array.isArray(callerHooks))) throw new Error("--settings hooks must be an object");
-      const hooks = { ...(callerHooks as Record<string, unknown> | undefined) };
-      for (const [event, entries] of Object.entries(injected.hooks ?? {})) {
-        const existing = hooks[event];
-        if (existing !== undefined && !Array.isArray(existing)) throw new Error(`--settings ${event} hooks must be an array`);
-        hooks[event] = [...(existing as unknown[] | undefined ?? []), ...(entries as unknown[])];
-      }
-      settingsArgs = ["--settings", JSON.stringify({ ...caller, ...(ctx.facts ? { hooks } : {}) })];
-      nativeArgs = passthrough.filter((_, i) => i !== index && (arg !== "--settings" || i !== index + 1));
-    } else if (ctx.facts && !ctx.statusLine) {
-      const injected = JSON.parse(sessionSettings(undefined, ctx.facts));
-      settingsArgs = ["--settings", JSON.stringify({ hooks: injected.hooks })];
-    }
-    if (settingsArgs.length && !ctx.preview) {
-      const stateDir = ctx.facts?.stateDir ?? ctx.statusLine?.stateDir;
-      if (!stateDir) throw new Error("Claude session settings require the hub state directory");
-      const file = join(stateDir, `claude-settings-${randomUUID()}.json`);
-      try {
-        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
-        writeFileSync(`${file}.tmp`, settingsArgs[1]!, { mode: 0o600, flag: "wx" });
-        renameSync(`${file}.tmp`, file);
-      } catch {
-        try { unlinkSync(`${file}.tmp`); } catch { /* no temp file was written */ }
-        throw new Error("cannot write private Claude session settings in the hub state directory");
-      }
-      settingsArgs[1] = file;
-      settingsFile = file;
-    }
-    const notes = [
-      unattended ? UNATTENDED_WARNING : "",
-      ctx.statusLine && own ? "note: you passed --settings, so the hub's status line tee is off and the budget coordinator cannot see Claude's quota (ahub budget set claude <0..1> still works)." : "",
-    ].filter(Boolean);
-    return {
-      cmd: "claude",
-      args: ["--dangerously-load-development-channels", claudeChannel(passthrough), ...(unattended ? ["--dangerously-skip-permissions"] : []), ...settingsArgs, ...nativeArgs],
-      ...(settingsFile ? { settingsFile } : {}),
-      permissionHook: !!ctx.facts,
-      ...(ctx.facts ? { hookPurpose: ctx.facts.purpose ?? "facts" } : {}),
-      unattended,
-      ...(notes.length ? { warning: notes.join("\n") } : {}),
-    };
-  }
-  if (!ctx.proxyUrl) throw new Error("codex proxy url is missing");
-  return {
-    cmd: ctx.codexBin ?? "codex",
-    args: ["--enable", "tui_app_server", "--remote", ctx.proxyUrl, ...(unattended ? ["--dangerously-bypass-approvals-and-sandbox"] : []), ...passthrough],
-    unattended,
-    ...warning,
-  };
+  const adapter = definitionOf(tool);
+  if (!adapter) throw new Error("native launch definition unavailable");
+  const { metadata: _metadata, ...launch } = adapter.start.launch({
+    instance: ctx.instance ?? tool, form: "tui", projectRoot: process.cwd(), stateDir: ctx.facts?.stateDir ?? ctx.statusLine?.stateDir ?? "",
+    entrypoint: resolve(import.meta.dir, "main.js"), userArgs, env: {}, ...ctx,
+  });
+  return launch;
 }
 
 
 /** The daemon and preview use exactly the same ACP command insertion. */
 export function buildKimiLaunch(command: string[], model?: string): Launch {
-  const [cmd, ...args] = command;
-  return { cmd: cmd!, args: model ? ["--model", model, ...args] : args };
+  const [cmd, ...args] = kimiAcpCommand(command, model);
+  return { cmd: cmd!, args };
 }
 
 export { buildQwenLaunch } from "../adapters/definitions/qwen-native.ts";