@staix/agent-hub 0.12.31 → 0.12.32

package/src/adapters/acp.ts

@@ -3,7 +3,10 @@ import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { createInterface } from "node:readline";
 import { renderDigest, replyAudience, replyParent, sanitize, type Envelope, type PeerId, type PeerState } from "../hub/envelope.ts";
 import { acpQuotaRefusal, type ACPQuotaRefusal } from "./acp-quota.ts";
-import { KIMI_MODE_IDS, QWEN_MODE_IDS, type PermissionMode } from "../hub/permission-mode.ts";
+import type { PermissionMode } from "../hub/permission-mode.ts";
+import { KIMI_MODE_IDS } from "./definitions/kimi-native.ts";
+import { QWEN_MODE_IDS, qwenNativeIdentity } from "./definitions/qwen-native.ts";
+export { QwenIdentityError } from "./definitions/qwen-native.ts";
 import { BasePeer } from "../hub/peers.ts";
 import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 
@@ -115,9 +118,6 @@ export function canonicalMcpToolName(announcedTitle: string | undefined, serverN
 }
 
 class RpcTimeoutError extends Error {}
-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"); }
-}
 
 type Pending = { resolve: (v: any) => void; reject: (e: Error) => void };
 
@@ -241,8 +241,7 @@ export class AcpPeer extends BasePeer {
       // Installed Kimi Code CLI's ACP initialize advertises this exact name.
       this.kimiAgent = init?.agentInfo?.name === "Kimi Code CLI";
       if (this.opts.expectedAgent && (init?.agentInfo?.name !== this.opts.expectedAgent.name || init?.agentInfo?.version !== this.opts.expectedAgent.version)) throw new Error("native ACP identity is not verified for this production adapter");
-      this.qwenAgent = this.opts.qwen025 === true && this.id === "qwen" && init?.agentInfo?.name === "qwen-code" && init?.agentInfo?.version === "0.25.0";
-      if (this.opts.qwen025 && !this.qwenAgent) throw new QwenIdentityError();
+      this.qwenAgent = qwenNativeIdentity(this.id, this.opts.qwen025, init);
       const resume = this.opts.resumeSessionId;
       if (!resume) return this.request("session/new", { cwd: this.opts.cwd, mcpServers: this.opts.mcpServers ?? [] });
       // The agent replays the session as updates while it loads; they arrive before the peer is idle, so none of

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

@@ -0,0 +1,121 @@
+import type { AdapterDefinition, LaunchContext, LaunchPlan, StartForm } from "../registry-types.ts";
+import type { PeerAdapter } from "../../hub/peers.ts";
+import { shellQuote } from "../../cli/terminal-recovery.ts";
+
+type CompatibilityKind = "claude" | "codex" | "kimi" | "pi" | "local" | "jcode";
+
+/**
+ * ponytail: A1 compatibility definitions delegate to the existing CLI; the existing daemon remains their runtime
+ * authority until A2 migrates each native path. These launch methods are not a second native launcher or factory.
+ */
+function compatibilityLaunch(kind: CompatibilityKind, ctx: LaunchContext): LaunchPlan {
+  const mode = kind === "kimi" || kind === "pi" ? ["--mode", ctx.form] : [];
+  const unattended = ctx.unattended && (kind === "claude" || kind === "codex") ? ["--unattended"] : [];
+  const args = [ctx.entrypoint, "--project", ctx.projectRoot, kind, ...mode, ...unattended,
+    ...(ctx.model && !ctx.userArgs.includes("--model") ? ["--model", ctx.model] : []), ...ctx.userArgs];
+  const argv = [process.execPath, ...args];
+  const env = {
+    ...(ctx.env.CODEX_HOME !== undefined ? { CODEX_HOME: ctx.env.CODEX_HOME } : {}),
+    ...(ctx.env.CLAUDE_CONFIG_DIR !== undefined ? { CLAUDE_CONFIG_DIR: ctx.env.CLAUDE_CONFIG_DIR } : {}),
+  };
+  const prefix = Object.entries(env).map(([name, value]) => `${name}=${shellQuote(value)}`);
+  return { cmd: process.execPath, args, ...(unattended.length ? { unattended: true } : {}),
+    metadata: { packageEntrypoint: ctx.entrypoint, argv, env, command: [...prefix, ...argv.map(shellQuote)].join(" ") } };
+}
+
+function sessionId(field: "sessionId" | "threadId"): (peer: PeerAdapter) => string | undefined {
+  return peer => {
+    const value = peer.recoveryMetadata?.()[field];
+    return typeof value === "string" && value ? value : undefined;
+  };
+}
+const terminal = (form: StartForm) => form === "tui";
+const headless = () => false;
+const switches = Object.freeze(["--unattended", "--safe", "--new"]);
+const implementerRoles = Object.freeze(["implementer", "verifier"]);
+const dualForms = Object.freeze(["tui", "headless"] as const);
+const headlessForms = Object.freeze(["headless"] as const);
+const palette = (fg: string) => ({ palette: { fg, bg: "transparent" } });
+const hubGrants = {
+  ask: "every write, edit and shell command asks",
+  "ask-when-needed": "write and edit inside the project run without asking; shell and git writes still ask",
+  "never-ask": "every tool runs without asking, inside the hub sandbox and path guard",
+};
+
+// Sources: peer-catalog.ts roles, roster.ts defaults, start-mode.ts forms, permission-mode.ts grants,
+// daemon.ts runtime mappings/stop policy, budget.ts exemptions, and ui/peer-palette.ts CSS foregrounds.
+export const BUILTIN_DEFINITIONS_WITHOUT_QWEN: readonly AdapterDefinition[] = Object.freeze([
+  {
+    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", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("claude", ctx), conductorStartable: true,
+      unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--dangerously-load-development-channels", "--dangerously-skip-permissions"]) },
+    identity: { mcp: "channel-plugin" },
+    // ponytail: A1 compatibility, existing daemon permission hooks remain authority until A2; absence is not unmanaged or a refusal.
+    permission: { modes: {}, grants: { ask: "Claude's own permission rules decide",
+      "ask-when-needed": "file tools on project files run without asking, outside .agenthub, .git and agent configuration; other tools keep Claude's own rules",
+      "never-ask": "every tool runs without asking" } },
+    session: { idField: "sessionId", currentId: sessionId("sessionId"), configDirEnv: "CLAUDE_CONFIG_DIR", zeroTurnFresh: true, launchKind: "claude-channel", launchRecord: true },
+    turnEnd: "native-hook", budget: { account: "claude", checkpoint: true },
+    cli: { command: "claude", startWords: () => ["claude"] }, display: palette("#6495ed"), hooks: { recallPlatform: "claude" },
+  },
+  {
+    api: 1, kind: "codex", displayName: "Codex", family: "codex", transport: "codex-appserver",
+    roles: Object.freeze(["implementer"]), defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
+    start: { forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("codex", ctx), conductorStartable: true,
+      unattended: true, hubSwitches: switches, ownedFlags: Object.freeze(["--remote", "--yolo", "--dangerously-bypass-approvals-and-sandbox"]) },
+    identity: { mcp: "env" },
+    permission: { modes: { ask: { kind: "native-only", note: "restore the session's captured native approval policy" },
+      "ask-when-needed": { kind: "codex-approval", policy: "on-request" }, "never-ask": { kind: "codex-approval", policy: "never" } },
+      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: { idField: "threadId", currentId: sessionId("threadId"), configDirEnv: "CODEX_HOME", zeroTurnFresh: true, launchKind: "codex", launchRecord: true },
+    turnEnd: "adapter", budget: { account: "codex", checkpoint: true },
+    cli: { command: "codex", startWords: () => ["codex"] }, display: palette("#22b8cf"), hooks: { recallPlatform: "codex" },
+  },
+  {
+    api: 1, kind: "kimi", displayName: "Kimi Code", family: "kimi", transport: "acp",
+    roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: false, hubSandboxed: false },
+    start: { forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("kimi", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    // ACP sessions carry headless identity; the existing CLI alone owns the TUI's project MCP entry.
+    identity: { mcp: "acp-session" }, attach: { pullOnlyForms: Object.freeze(["tui"] as const) },
+    permission: { modes: { ask: { kind: "acp-mode", modeId: "default" }, "ask-when-needed": { kind: "acp-mode", modeId: "yolo" }, "never-ask": { kind: "acp-mode", modeId: "auto" } },
+      grants: { ask: "Kimi asks as it does on its own", "ask-when-needed": "Kimi's yolo mode: it asks only where it judges it must", "never-ask": "Kimi's auto mode: nothing asks" },
+      unmanagedForms: Object.freeze(["tui"] as const), 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" },
+    turnEnd: "adapter", budget: { account: "kimi" }, capabilities: { watch: true }, init: { mcpFile: ".kimi-code/mcp.json" },
+    cli: { command: "kimi", startWords: form => ["kimi", "--mode", form] }, display: palette("#bc73ca"),
+  },
+  {
+    api: 1, kind: "pi", displayName: "Pi", family: "pi", transport: "hub-native",
+    roles: implementerRoles, defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: true },
+    start: { forms: dualForms, defaultForm: "tui", ownsTerminal: terminal, launch: ctx => compatibilityLaunch("pi", ctx), conductorStartable: true, autoStart: "pi.auto_start", hubSwitches: [], ownedFlags: [] },
+    identity: { mcp: "env" },
+    // ponytail: A1 compatibility, existing daemon permission hooks remain authority until A2; absence is not unmanaged or a refusal.
+    permission: { modes: {}, grants: { ...hubGrants } },
+    session: { idField: "sessionId", currentId: sessionId("sessionId"), launchKind: "pi", launchRecord: true },
+    turnEnd: "adapter", budget: { account: "pi" },
+    cli: { command: "pi", startWords: form => ["pi", "--mode", form] }, display: palette("#c79936"),
+  },
+  {
+    api: 1, kind: "local", displayName: "Local worker", family: "local", transport: "hub-native",
+    roles: implementerRoles, defaultOnRoster: true, trust: { onPrem: true, hubSandboxed: true },
+    start: { forms: headlessForms, defaultForm: "headless", ownsTerminal: headless, launch: ctx => compatibilityLaunch("local", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    identity: { mcp: "env" },
+    // ponytail: A1 compatibility, existing daemon permission hooks remain authority until A2; absence is not unmanaged or a refusal.
+    permission: { modes: {}, grants: { ...hubGrants } },
+    session: { idField: "sessionId", currentId: sessionId("sessionId"), freshOnRestore: true, launchKind: "local" },
+    turnEnd: "adapter",
+    cli: { command: "local", startWords: () => ["local"] }, display: palette("#4caa77"),
+  },
+  {
+    api: 1, kind: "jcode", displayName: "Jcode", family: "jcode", transport: "acp",
+    roles: implementerRoles, optional: true, defaultOnRoster: false, trust: { onPrem: false, hubSandboxed: false },
+    start: { forms: headlessForms, defaultForm: "headless", ownsTerminal: headless, launch: ctx => compatibilityLaunch("jcode", ctx), conductorStartable: true, hubSwitches: [], ownedFlags: [] },
+    identity: { mcp: "project-file" },
+    permission: { modes: {}, 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" }, turnEnd: "adapter", budget: { account: "jcode" },
+    // Jcode has no dedicated CSS swatch today: retain peer-palette.ts's existing 'other' fallback.
+    cli: { command: "jcode", startWords: () => ["jcode"] }, display: palette("#8a8f99"),
+  },
+] satisfies AdapterDefinition[]);

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

@@ -0,0 +1,4 @@
+import type { PermissionMode } from "../../hub/permission-mode.ts";
+
+/** Shared native mode ids stay independent of the registry's factories. */
+export const KIMI_MODE_IDS: Readonly<Record<PermissionMode, string>> = { ask: "default", "ask-when-needed": "yolo", "never-ask": "auto" };

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

@@ -0,0 +1,24 @@
+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"); }
+}
+
+export function qwenNativeIdentity(instance: string, production: boolean | undefined, init: unknown): boolean {
+  const native = init as { agentInfo?: { name?: unknown; version?: unknown } } | null | undefined;
+  const verified = production === true && instance === "qwen" && native?.agentInfo?.name === "qwen-code" && native?.agentInfo?.version === "0.25.0";
+  if (production && !verified) throw new QwenIdentityError();
+  return verified;
+}
+
+/** Qwen flags follow the configured executable argv, including wrapper/script arguments. */
+export function buildQwenLaunch(command: readonly string[], model?: string): Launch {
+  const [cmd, ...args] = command;
+  if (!cmd) throw new Error("qwen_cmd must name an executable");
+  return { cmd, args: [...args, ...(model ? ["--model", model] : [])] };
+}
+
+export const qwenSessionId = (value: unknown): value is string => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(value);

package/src/adapters/definitions/qwen.ts

@@ -0,0 +1,71 @@
+import { AcpPeer } from "../acp.ts";
+import type { AdapterDefinition } from "../registry-types.ts";
+import { buildQwenLaunch, qwenNativeIdentity, qwenSessionId, QWEN_MODE_IDS } from "./qwen-native.ts";
+import { shellQuote } from "../../cli/terminal-recovery.ts";
+
+/** Production Qwen policy. Legacy AcpPeer callers opt in separately through qwen025. */
+export const QWEN_DEFINITION: AdapterDefinition = {
+  api: 1,
+  kind: "qwen",
+  displayName: "Qwen Code",
+  family: "qwen",
+  transport: "acp",
+  roles: ["implementer", "verifier"],
+  optional: true,
+  defaultOnRoster: false,
+  trust: { onPrem: false, hubSandboxed: false },
+  start: {
+    forms: ["headless"],
+    defaultForm: "headless",
+    ownsTerminal: () => false,
+    conductorStartable: true,
+    hubSwitches: [],
+    ownedFlags: [],
+    preflight: request => request.form !== undefined && request.form !== "headless"
+      ? "Qwen TUI is not offered before its native verification; use ahub qwen --mode headless" : undefined,
+    launch: context => {
+      if (context.form !== "headless") throw new Error("Qwen TUI is not offered before its native verification; use ahub qwen --mode headless");
+      const launch = buildQwenLaunch(context.nativeCommand ?? ["qwen", "--acp"], context.model);
+      const argv = [launch.cmd, ...launch.args];
+      return { ...launch, metadata: { packageEntrypoint: context.entrypoint, argv, command: argv.map(shellQuote).join(" "), env: {} } };
+    },
+    create: context => {
+      if (!("acp" in context.daemon)) throw new Error("Qwen requires its ACP transport options");
+      if (context.permission === "read-only") throw new Error("Qwen has no verified read-only permission mapping");
+      return new AcpPeer(context.instance, { ...context.daemon.acp, qwen025: true, permissionMode: context.permission, mcpServers: context.mcpServers });
+    },
+    conductorStartArgs: args => args.length ? new Error("Qwen start takes no conductor overrides") : {},
+  },
+  identity: { mcp: "acp-session" },
+  permission: {
+    modes: {
+      ask: { kind: "acp-mode", modeId: QWEN_MODE_IDS.ask },
+      "ask-when-needed": { kind: "acp-mode", modeId: QWEN_MODE_IDS["ask-when-needed"] },
+      "never-ask": { kind: "acp-mode", modeId: QWEN_MODE_IDS["never-ask"] },
+    },
+    grants: {
+      ask: "every write, edit and shell command asks",
+      "ask-when-needed": "Qwen auto-edit approves file edits; shell commands ask; NO hub sandbox",
+      "never-ask": "Qwen yolo approves every tool; NO hub sandbox",
+    },
+  },
+  session: {
+    idField: "sessionId",
+    currentId: peer => {
+      const sessionId = peer.recoveryMetadata?.().sessionId;
+      return typeof sessionId === "string" ? sessionId : undefined;
+    },
+    launchKind: "acp",
+    restoreOnStart: true,
+    crashIdentity: row => {
+      const sessionId = row && typeof row === "object" ? (row as { sessionId?: unknown }).sessionId : undefined;
+      return qwenSessionId(sessionId) ? { sessionId } : {};
+    },
+  },
+  turnEnd: "adapter",
+  budget: { account: "qwen" },
+  capabilities: { watch: true },
+  cli: { command: "qwen", startWords: () => ["qwen"] },
+  display: { palette: { fg: "#8a8f99", bg: "transparent" } },
+  hooks: { agentIdentity: init => { qwenNativeIdentity("qwen", true, init); }, recallPlatform: "qwen" },
+};

package/src/adapters/pi.ts

@@ -7,7 +7,7 @@ import { renderDigest, replyAudience, replyParent, type Envelope, type PeerId }
 import { BasePeer } from "../hub/peers.ts";
 import { stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 import { processLiveness, processSignature } from "../pi/process-signature.ts";
-import { validatePiSession } from "../pi/session.ts";
+import { PiSessionBookmarkMismatch, validatePiSession } from "../pi/session.ts";
 import { ApprovalWaitStop, toolResultFailed, type ApprovalProvenance } from "../local/tools.ts";
 import { piToolStepCeiling, type PiToolStepCeiling } from "../pi/ceiling.ts";
 import type { ExecutionBudgetDecision, ExecutionUnit } from "../hub/execution-budget.ts";
@@ -346,7 +346,11 @@ export class PiPeer extends BasePeer {
     const sessions = join(this.opts.stateDir, "pi-sessions");
     mkdirSync(sessions, { recursive: true, mode: 0o700 });
     if (this.opts.sessionFile) {
-      validatePiSession(this.opts.stateDir, this.opts.cwd, this.opts.sessionFile, this.opts.sessionId);
+      try { validatePiSession(this.opts.stateDir, this.opts.cwd, this.opts.sessionFile, this.opts.sessionId); }
+      catch (error) {
+        if (error instanceof PiSessionBookmarkMismatch) throw new PiSessionBookmarkMismatch("Pi session header id does not match the requested session", { cause: error });
+        throw error;
+      }
     }
     const token = randomUUID();
     this.tuiExit = new Promise((resolvePromise) => { this.resolveTuiExit = resolvePromise; });

package/src/adapters/registry-types.ts

@@ -0,0 +1,174 @@
+import type { Launch, StatusLineTee, FactsHook } from "../cli/launch.ts";
+import type { LaunchMetadata, TerminalBinding } from "../cli/terminal-recovery.ts";
+import type { UsageWindow } from "../hub/budget.ts";
+import type { ContextReading } from "../hub/context-window.ts";
+import type { PeerAdapter } from "../hub/peers.ts";
+import type { PermissionMode } from "../hub/permission-mode.ts";
+import type { AcpOptions } from "./acp.ts";
+import type { CodexOptions } from "./codex-appserver.ts";
+import type { JcodeOptions } from "./jcode.ts";
+import type { LocalOptions } from "./local-worker.ts";
+import type { PiOptions } from "./pi.ts";
+
+export type StartForm = "tui" | "headless";
+
+/** Existing buildLaunch inputs plus the startup-bound instance and project identity. */
+export interface LaunchContext {
+  instance: string;
+  form: StartForm;
+  projectRoot: string;
+  stateDir: string;
+  entrypoint: string;
+  userArgs: string[];
+  unattended: boolean;
+  proxyUrl?: string;
+  codexBin?: string;
+  statusLine?: StatusLineTee;
+  facts?: FactsHook;
+  preview?: boolean;
+  model?: string;
+  fresh?: boolean;
+  env: Readonly<Record<string, string>>;
+  /** Existing validated config argv (or the existing redacted preview), never model input. */
+  nativeCommand?: readonly string[];
+}
+
+export type LaunchPlan = Launch & { metadata: LaunchMetadata; mcpFile?: { path: string; entry: unknown } };
+
+/** A factory receives exactly its existing transport options, with no cross-transport callback widening. */
+export type DaemonPorts =
+  | { codex: CodexOptions }
+  | { acp: AcpOptions }
+  | { jcode: JcodeOptions }
+  | { pi: PiOptions }
+  | { local: LocalOptions };
+
+export interface CreateContext<Ports extends DaemonPorts = DaemonPorts> {
+  instance: string;
+  projectRoot: string;
+  stateDir: string;
+  kindConfig: unknown;
+  permission: PermissionMode | "read-only";
+  mcpServers: NonNullable<AcpOptions["mcpServers"]>;
+  daemon: Ports;
+}
+
+export interface StartRequest {
+  instance: string;
+  form?: StartForm;
+  model?: string;
+  route?: string;
+  unattended?: boolean;
+  replaceSession?: boolean;
+  existing?: PeerAdapter;
+}
+
+export interface VersionContext {
+  instance: string;
+  peer?: PeerAdapter;
+  env: Readonly<Record<string, string>>;
+}
+
+export type NativeModeSpec =
+  | { kind: "acp-mode"; modeId: string }
+  | { kind: "codex-approval"; policy: string }
+  | { kind: "launch-flag"; argv: string[] }
+  | { kind: "hub-gate"; allow: readonly ("read" | "search" | "think")[] }
+  | { kind: "native-only"; note: string };
+
+export interface QuotaReader {
+  source: string;
+  read(peer: PeerAdapter): UsageWindow[] | undefined;
+  resetOnWindow?: boolean;
+}
+
+export interface ContextReader {
+  source: ContextReading["source"];
+  read(peer: PeerAdapter): ContextReading | undefined;
+}
+
+export interface CapabilityManifest {
+  capabilities: {
+    id: string;
+    kind: "command" | "skill" | "mcp_tool";
+    name: string;
+    description: string;
+    inputSchema?: unknown;
+    sideEffect: "read" | "write" | "exec" | "external";
+  }[];
+}
+
+/** Only the frozen native seams are extensible; a definition cannot add an arbitrary daemon callback. */
+export interface NativeHooks {
+  agentIdentity(init: unknown): void;
+  onAttach(instance: string): void;
+  onDetach(instance: string): void;
+  factsHook: (msg: unknown) => unknown;
+  conversationRevert(turnId: string): Promise<void>;
+  replaceSession(req: StartRequest): Promise<unknown>;
+  pluginInventory(env: Readonly<Record<string, string>>): string[];
+  recallPlatform: string;
+}
+
+/** Adapter API 1, including the merged revision-3 members frozen in issue #451. */
+export interface AdapterDefinition {
+  api: 1;
+  kind: string;
+  displayName: string;
+  family: string;
+  transport: "acp" | "codex-appserver" | "claude-channel" | "ws-pull" | "hub-native";
+  roles: readonly string[];
+  optional?: boolean;
+  defaultOnRoster?: boolean;
+  trust: { onPrem: boolean; hubSandboxed: boolean };
+  start: {
+    forms: readonly StartForm[];
+    defaultForm: StartForm;
+    ownsTerminal(form: StartForm): boolean;
+    launch(ctx: LaunchContext): LaunchPlan;
+    create?(ctx: CreateContext): PeerAdapter;
+    preflight?(ctx: StartRequest): string | undefined;
+    version?(ctx: VersionContext): string | undefined;
+    conductorStartable: boolean;
+    autoStart?: "pi.auto_start";
+    unattended?: boolean;
+    hubSwitches: readonly string[];
+    ownedFlags: readonly string[];
+    conductorStartArgs?(args: string[]): { mode?: StartForm } | Error;
+  };
+  identity: { mcp: "acp-session" | "project-file" | "env" | "channel-plugin" };
+  attach?: { pullOnlyForms?: readonly StartForm[] };
+  permission: {
+    modes: Partial<Record<PermissionMode, NativeModeSpec>>;
+    grants?: Partial<Record<PermissionMode, string>>;
+    readOnly?: NativeModeSpec;
+    unmanaged?: string;
+    unmanagedForms?: readonly StartForm[];
+    unmanagedNote?: string;
+  };
+  session: {
+    idField: "sessionId" | "threadId";
+    currentId(peer: PeerAdapter): string | undefined;
+    configDirEnv?: "CODEX_HOME" | "CLAUDE_CONFIG_DIR";
+    resumeArgv?(binding: TerminalBinding, fresh: boolean): string[];
+    transcriptPath?(binding: TerminalBinding): string | undefined;
+    transcriptExists?(binding: TerminalBinding): boolean | "unknown";
+    zeroTurnFresh?: boolean;
+    freshOnRestore?: boolean;
+    restoreOnStart?: boolean;
+    launchKind?: string;
+    launchRecord?: boolean;
+    crashIdentity?(row: unknown): { sessionId?: string; sessionFile?: string };
+  };
+  turnEnd: "adapter" | "native-hook";
+  budget?: { account: string; reader?: QuotaReader; context?: ContextReader; checkpoint?: boolean };
+  capabilities?: { manifest?(peer: PeerAdapter): Promise<CapabilityManifest>; watch?: boolean };
+  init?: { templateFragment?: string; mcpFile?: string };
+  cli: {
+    command: string;
+    startWords(form: StartForm): string[];
+    stopNotice?(form: StartForm, owner: PeerAdapter | undefined): string;
+  };
+  display: { palette: { fg: string; bg: string } };
+  hooks?: Partial<NativeHooks>;
+}

package/src/adapters/registry.ts

@@ -0,0 +1,36 @@
+import { BUILTIN_DEFINITIONS_WITHOUT_QWEN } from "./definitions/builtin-metadata.ts";
+import { QWEN_DEFINITION } from "./definitions/qwen.ts";
+import type { AdapterDefinition } from "./registry-types.ts";
+
+export type * from "./registry-types.ts";
+export const ADAPTER_API = 1;
+
+function immutable<T>(value: T, seen = new WeakSet<object>()): T {
+  if (!value || typeof value !== "object" || seen.has(value)) return value;
+  seen.add(value);
+  for (const member of Object.values(value)) immutable(member, seen);
+  return Object.freeze(value);
+}
+
+/** 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"),
+  QWEN_DEFINITION,
+  ...BUILTIN_DEFINITIONS_WITHOUT_QWEN.filter(definition => definition.kind === "jcode"),
+]);
+const definitions = new Map<string, AdapterDefinition>();
+for (const definition of ADAPTERS) {
+  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;
+}
+export function definitionOf(id: string): AdapterDefinition | undefined {
+  return definitions.get(id);
+}
+export function familyOf(id: string): string | undefined {
+  return definitionOf(id)?.family;
+}