agent-trellis 0.7.0 → 0.8.0

package/dist/commands/doctor.js

@@ -1,6 +1,6 @@
 /**
  * `trellis doctor` — read-only cross-agent scan. No `.trellis/` canonical
- * source required (docs/roadmap.md): this compares the four agents' own
+ * source required (docs/roadmap.md): this compares the five agents' own
  * current state against each other, the same manual process used
  * throughout docs/research.md's investigation, now formalized.
  */
@@ -9,7 +9,9 @@ import * as claudeCodeProbe from "../probes/claude-code.js";
 import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
 import * as piProbe from "../probes/pi.js";
+import * as kimiCodeProbe from "../probes/kimi-code.js";
 import { loadCanonicalSource } from "../core/canonical.js";
+import { GATEWAY_ENTRY_NAME, RUNTIME_ENTRY_NAME, resolveMcpPlan } from "../adapters/mcpPlan.js";
 import { ALL_AGENTS } from "../core/types.js";
 /**
  * Interim default until P1 wires this from `.trellis/mcp/servers.yaml`'s
@@ -32,6 +34,7 @@ const EXIT_NONZERO_KINDS = new Set([
     "drift",
     "case-mismatch",
     "parse-diagnostic",
+    "runtime-drift",
 ]);
 /** Exported so tests can assert on this resolution directly, without
  * routing through real per-agent probes `runDoctor` also runs. */
@@ -72,6 +75,7 @@ export async function collectDoctorReport(homeDir = homedir(), knownHostInjected
         { agent: "codex", run: () => codexProbe.probe(homeDir, { probeMcp }) },
         { agent: "kiro", run: () => kiroProbe.probe(homeDir, { probeMcp }) },
         { agent: "pi", run: () => piProbe.probe(homeDir) },
+        { agent: "kimi-code", run: () => kimiCodeProbe.probe(homeDir, { probeMcp }) },
     ];
     // One agent erroring must not blank the other three's results.
     const settled = await Promise.allSettled(probeList.map((p) => p.run()));
@@ -89,7 +93,15 @@ export async function collectDoctorReport(homeDir = homedir(), knownHostInjected
             });
         }
     });
-    findings.push(...detectDuplication(snapshots), ...detectCollisions(snapshots, knownHostInjected), ...detectCrossAgentDrift(snapshots), ...detectCaseMismatches(snapshots), ...detectParseDiagnostics(snapshots), ...detectMcpUnreachable(snapshots));
+    let canonical;
+    try {
+        canonical = loadCanonicalSource(homeDir);
+    }
+    catch {
+        // Doctor remains useful as a standalone cross-agent scanner when
+        // canonical has not been initialized yet.
+    }
+    findings.push(...detectDuplication(snapshots), ...detectCollisions(snapshots, knownHostInjected), ...detectCrossAgentDrift(snapshots), ...detectCaseMismatches(snapshots), ...detectParseDiagnostics(snapshots), ...(canonical ? detectRuntimeDrift(snapshots, canonical) : []), ...detectMcpUnreachable(snapshots));
     return { snapshots, findings };
 }
 /**
@@ -233,6 +245,30 @@ export function detectMcpUnreachable(snapshots) {
     }
     return findings;
 }
+/** Compares runtime entries against the same canonical MCP plan that sync
+ * uses. Only missing Trellis-owned runtime edges are reported; extra
+ * user-authored MCP entries remain outside doctor ownership. */
+export function detectRuntimeDrift(snapshots, canonical) {
+    const findings = [];
+    for (const snap of snapshots) {
+        if (!snap.present || !canonical.managedAgents.includes(snap.agent) || snap.agent === "pi")
+            continue;
+        const expected = resolveMcpPlan(snap.agent, canonical.mcp, canonical.managedAgents, canonical.secretsPolicy).desired
+            .map((entry) => entry.name)
+            .filter((name) => name === RUNTIME_ENTRY_NAME || name === GATEWAY_ENTRY_NAME);
+        const actual = new Set(snap.mcpServers.map((server) => server.name));
+        for (const name of expected) {
+            if (!actual.has(name)) {
+                findings.push({
+                    kind: "runtime-drift",
+                    agent: snap.agent,
+                    message: "canonical expects MCP runtime entry \"" + name + "\" for " + snap.agent + ", but it is missing from the agent static configuration",
+                });
+            }
+        }
+    }
+    return findings;
+}
 /** Exported so `trellis onboard` can reuse it verbatim for its own final
  * stage (trellis-onboard-closed-loop) rather than a second copy of this
  * formatting. */

package/dist/commands/init.d.ts

@@ -29,7 +29,7 @@ export interface InitReport {
 /** Exported so `migrate` can byte-compare canonical `agents.md` against
  * this exact string (design.md D3, trellis-cli-migrate) rather than
  * retyping an equivalent one that could silently drift from this. */
-export declare const AGENTS_MD_TEMPLATE = "# Shared instructions\n\nWrite what every agent should know here \u2014 communication preferences,\nproject conventions, anything you'd otherwise repeat per agent.\n\nAlready using Claude Code, Codex, Kiro, or pi? `trellis migrate --from\n<agent>` imports its real instructions and skills instead of starting\nfrom this placeholder.\n";
+export declare const AGENTS_MD_TEMPLATE = "# Shared instructions\n\nWrite what every agent should know here \u2014 communication preferences,\nproject conventions, anything you'd otherwise repeat per agent.\n\nAlready using Claude Code, Codex, Kiro, pi, or Kimi Code? `trellis migrate --from\n<agent>` imports its real instructions and skills instead of starting\nfrom this placeholder.\n";
 /**
  * Trellis never spawns an installer itself (global package installs are
  * exactly the kind of irreversible, system-wide action that needs the
@@ -38,7 +38,9 @@ export declare const AGENTS_MD_TEMPLATE = "# Shared instructions\n\nWrite what e
  * own current install docs, same discipline as everything else here.
  */
 export declare const INSTALL_HINTS: Record<AgentId, string>;
-export declare function collectInitReport(homeDir?: string): Promise<InitReport>;
+export declare function collectInitReport(homeDir?: string, options?: {
+    write?: boolean;
+}): Promise<InitReport>;
 export declare function runInit(opts?: RunInitOptions): Promise<{
     exitCode: number;
 }>;

package/dist/commands/init.js

@@ -15,6 +15,7 @@ import * as claudeCodeProbe from "../probes/claude-code.js";
 import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
 import * as piProbe from "../probes/pi.js";
+import * as kimiCodeProbe from "../probes/kimi-code.js";
 import { ALL_AGENTS } from "../core/types.js";
 /** Exported so `migrate` can byte-compare canonical `agents.md` against
  * this exact string (design.md D3, trellis-cli-migrate) rather than
@@ -24,7 +25,7 @@ export const AGENTS_MD_TEMPLATE = `# Shared instructions
 Write what every agent should know here — communication preferences,
 project conventions, anything you'd otherwise repeat per agent.
 
-Already using Claude Code, Codex, Kiro, or pi? \`trellis migrate --from
+Already using Claude Code, Codex, Kiro, pi, or Kimi Code? \`trellis migrate --from
 <agent>\` imports its real instructions and skills instead of starting
 from this placeholder.
 `;
@@ -93,32 +94,44 @@ export const INSTALL_HINTS = {
     codex: "npm install -g @openai/codex",
     kiro: "https://kiro.dev/downloads/",
     pi: "npm install -g @earendil-works/pi-coding-agent",
+    "kimi-code": "curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash",
 };
-function ensureFile(path, template) {
+function ensureFile(path, template, write = true) {
     if (existsSync(path)) {
         return { path, action: "already-present" };
     }
-    writeFileSync(path, template);
+    if (write)
+        writeFileSync(path, template);
     return { path, action: "create" };
 }
-export async function collectInitReport(homeDir = homedir()) {
+export async function collectInitReport(homeDir = homedir(), options = {}) {
+    const write = options.write !== false;
     const root = join(homeDir, ".trellis");
-    mkdirSync(root, { recursive: true });
-    mkdirSync(join(root, "mcp"), { recursive: true });
-    mkdirSync(join(root, "skills"), { recursive: true });
-    mkdirSync(join(root, "agents"), { recursive: true });
-    mkdirSync(join(root, "memories"), { recursive: true });
+    if (write) {
+        mkdirSync(root, { recursive: true });
+        mkdirSync(join(root, "mcp"), { recursive: true });
+        mkdirSync(join(root, "skills"), { recursive: true });
+        mkdirSync(join(root, "agents"), { recursive: true });
+        mkdirSync(join(root, "memories"), { recursive: true });
+    }
     const files = [
-        ensureFile(join(root, "agents.md"), AGENTS_MD_TEMPLATE),
-        ensureFile(join(root, "mcp", "servers.yaml"), serversYamlTemplate()),
-        ensureFile(join(root, "secrets.policy.yaml"), secretsPolicyYamlTemplate()),
-        ensureFile(join(root, "managed.yaml"), managedYamlTemplate()),
+        ensureFile(join(root, "agents.md"), AGENTS_MD_TEMPLATE, write),
+        ensureFile(join(root, "mcp", "servers.yaml"), serversYamlTemplate(), write),
+        ensureFile(join(root, "secrets.policy.yaml"), secretsPolicyYamlTemplate(), write),
+        ensureFile(join(root, "managed.yaml"), managedYamlTemplate(), write),
     ];
+    const here = dirname(fileURLToPath(import.meta.url));
+    const builtinSkillPath = join(root, "skills", "trellis-runtime", "SKILL.md");
+    const builtinSkillTemplate = readFileSync(join(here, "..", "..", "schema", "builtin-skills", "trellis-runtime", "SKILL.md"), "utf8");
+    if (write)
+        mkdirSync(dirname(builtinSkillPath), { recursive: true });
+    files.push(ensureFile(builtinSkillPath, builtinSkillTemplate, write));
     const probes = [
         { agent: "claude-code", run: () => claudeCodeProbe.probe(homeDir) },
         { agent: "codex", run: () => codexProbe.probe(homeDir) },
         { agent: "kiro", run: () => kiroProbe.probe(homeDir) },
         { agent: "pi", run: () => piProbe.probe(homeDir) },
+        { agent: "kimi-code", run: () => kimiCodeProbe.probe(homeDir) },
     ];
     const settled = await Promise.allSettled(probes.map((p) => p.run()));
     const agents = settled.map((result, index) => {

package/dist/commands/kimi.d.ts

@@ -0,0 +1,16 @@
+/** Runtime-first Kimi Code launcher.
+ *
+ * Kimi automatically discovers ~/.agents/skills. When canonical delivery is
+ * `mcp`, passing one empty --skills-dir is the only documented way to replace
+ * both user/project Skill roots for this launch and prevent duplicate native
+ * Skill delivery. Native/both modes invoke Kimi normally.
+ */
+import { spawn as spawnProcess } from "node:child_process";
+export interface RunKimiOptions {
+    homeDir?: string;
+    env?: NodeJS.ProcessEnv;
+    spawn?: typeof spawnProcess;
+}
+export declare function runKimi(args?: readonly string[], opts?: RunKimiOptions): Promise<{
+    exitCode: number;
+}>;

package/dist/commands/kimi.js

@@ -0,0 +1,64 @@
+/** Runtime-first Kimi Code launcher.
+ *
+ * Kimi automatically discovers ~/.agents/skills. When canonical delivery is
+ * `mcp`, passing one empty --skills-dir is the only documented way to replace
+ * both user/project Skill roots for this launch and prevent duplicate native
+ * Skill delivery. Native/both modes invoke Kimi normally.
+ */
+import { execFileSync, spawn as spawnProcess } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { capabilityDeliveryForAgent } from "../core/types.js";
+import { loadCanonicalSource } from "../core/canonical.js";
+function resolveKimiCommand(homeDir, env) {
+    const explicit = env.TRELLIS_KIMI_BIN;
+    if (explicit && existsSync(explicit))
+        return explicit;
+    const homeBinary = join(env.KIMI_CODE_HOME ?? join(homeDir, ".kimi-code"), "bin", "kimi");
+    if (existsSync(homeBinary))
+        return homeBinary;
+    try {
+        return execFileSync("which", ["kimi"], { encoding: "utf8", env }).trim() || "kimi";
+    }
+    catch {
+        return "kimi";
+    }
+}
+function hasSkillsDirArg(args) {
+    return args.some((arg) => arg === "--skills-dir" || arg.startsWith("--skills-dir="));
+}
+export async function runKimi(args = [], opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const env = { ...process.env, ...(opts.env ?? {}) };
+    let canonical;
+    try {
+        canonical = loadCanonicalSource(homeDir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    const delivery = capabilityDeliveryForAgent("kimi-code", canonical.mcp);
+    const runtimeOnly = delivery === "mcp";
+    if (runtimeOnly && hasSkillsDirArg(args)) {
+        console.error("trellis kimi: --skills-dir cannot be combined with Runtime-only delivery; change mcp.runtime.delivery.kimi-code or use native Kimi directly");
+        return { exitCode: 1 };
+    }
+    let emptySkillsDir;
+    const launchArgs = [...args];
+    if (runtimeOnly) {
+        emptySkillsDir = mkdtempSync(join(tmpdir(), "trellis-kimi-empty-skills-"));
+        launchArgs.unshift("--skills-dir", emptySkillsDir);
+    }
+    const command = resolveKimiCommand(homeDir, env);
+    const spawn = opts.spawn ?? spawnProcess;
+    const child = spawn(command, launchArgs, { stdio: "inherit", env });
+    const exitCode = await new Promise((resolve) => {
+        child.once("error", () => resolve(1));
+        child.once("exit", (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+    });
+    if (emptySkillsDir)
+        rmSync(emptySkillsDir, { recursive: true, force: true });
+    return { exitCode };
+}

package/dist/commands/manage.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Explicit lifecycle management for `~/.trellis/managed.yaml`.
+ *
+ * Onboarding stays additive: omission must never silently revoke Trellis's
+ * write authorization. Exact replacement and subtraction live here so they
+ * are deliberate, visible in shell history, dry-runnable, and recoverable.
+ */
+import type { AgentId } from "../core/types.js";
+export type ManageOperation = "list" | "set" | "add" | "remove";
+export interface ManagePlan {
+    operation: ManageOperation;
+    current: AgentId[];
+    desired: AgentId[];
+    added: AgentId[];
+    removed: AgentId[];
+    changed: boolean;
+}
+export interface ParsedManageArgs {
+    operation: ManageOperation;
+    ids?: string;
+    json: boolean;
+    dryRun: boolean;
+}
+export type ManagePlanResult = {
+    plan: ManagePlan;
+} | {
+    error: string;
+};
+export declare function parseManageArgs(argv: readonly string[]): ParsedManageArgs | {
+    error: string;
+};
+export declare function collectManagePlan(operation: ManageOperation, rawIds: string | undefined, homeDir?: string): ManagePlanResult;
+export declare function applyManagePlan(plan: ManagePlan, homeDir?: string): void;
+export declare function runManage(parsed: ParsedManageArgs, opts?: {
+    homeDir?: string;
+}): {
+    exitCode: number;
+    plan?: ManagePlan;
+};

package/dist/commands/manage.js

@@ -0,0 +1,126 @@
+/**
+ * Explicit lifecycle management for `~/.trellis/managed.yaml`.
+ *
+ * Onboarding stays additive: omission must never silently revoke Trellis's
+ * write authorization. Exact replacement and subtraction live here so they
+ * are deliberate, visible in shell history, dry-runnable, and recoverable.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { ALL_AGENTS } from "../core/types.js";
+import { openBackupSession } from "../lib/backup.js";
+function stableAgents(ids) {
+    const selected = new Set(ids);
+    return ALL_AGENTS.filter((id) => selected.has(id));
+}
+function parseAgentList(raw, allowNone) {
+    if (raw === undefined || raw.trim() === "") {
+        return { error: `agent list is required — use a comma-separated subset of ${ALL_AGENTS.join(", ")}${allowNone ? ", or none" : ""}` };
+    }
+    if (raw.trim().toLowerCase() === "none") {
+        return allowNone ? { agents: [] } : { error: '"none" is valid only for `trellis manage set none`' };
+    }
+    const tokens = raw.split(",").map((token) => token.trim()).filter(Boolean);
+    const invalid = tokens.filter((token) => !ALL_AGENTS.includes(token));
+    if (invalid.length > 0) {
+        return { error: `unknown agent id${invalid.length === 1 ? "" : "s"}: ${invalid.join(", ")} — expected ${ALL_AGENTS.join(", ")}` };
+    }
+    return { agents: stableAgents(tokens) };
+}
+export function parseManageArgs(argv) {
+    const [rawOperation, ...rest] = argv;
+    if (rawOperation !== "list" && rawOperation !== "set" && rawOperation !== "add" && rawOperation !== "remove") {
+        return { error: `unknown manage operation "${rawOperation ?? "(none)"}" — expected list, set, add, or remove` };
+    }
+    const unknownFlags = rest.filter((arg) => arg.startsWith("--") && arg !== "--json" && arg !== "--dry-run");
+    if (unknownFlags.length > 0)
+        return { error: `unknown manage flag "${unknownFlags[0]}"` };
+    const positional = rest.filter((arg) => !arg.startsWith("--"));
+    if (rawOperation === "list") {
+        if (positional.length > 0)
+            return { error: "manage list accepts no agent list" };
+    }
+    else if (positional.length !== 1) {
+        return { error: `manage ${rawOperation} requires exactly one comma-separated agent list` };
+    }
+    return {
+        operation: rawOperation,
+        ids: positional[0],
+        json: rest.includes("--json"),
+        dryRun: rest.includes("--dry-run"),
+    };
+}
+export function collectManagePlan(operation, rawIds, homeDir = homedir()) {
+    const current = stableAgents(loadCanonicalSource(homeDir).managedAgents);
+    if (operation === "list") {
+        return { plan: { operation, current, desired: current, added: [], removed: [], changed: false } };
+    }
+    const parsed = parseAgentList(rawIds, operation === "set");
+    if ("error" in parsed)
+        return parsed;
+    const requested = new Set(parsed.agents);
+    const desired = operation === "set"
+        ? stableAgents(requested)
+        : operation === "add"
+            ? stableAgents([...current, ...requested])
+            : stableAgents(current.filter((id) => !requested.has(id)));
+    const currentSet = new Set(current);
+    const desiredSet = new Set(desired);
+    const added = desired.filter((id) => !currentSet.has(id));
+    const removed = current.filter((id) => !desiredSet.has(id));
+    return {
+        plan: {
+            operation,
+            current,
+            desired,
+            added,
+            removed,
+            changed: added.length > 0 || removed.length > 0,
+        },
+    };
+}
+export function applyManagePlan(plan, homeDir = homedir()) {
+    if (!plan.changed || plan.operation === "list")
+        return;
+    const session = openBackupSession(homeDir, `manage-${plan.operation}`);
+    session.writeFile(join(homeDir, ".trellis", "managed.yaml"), `agents: [${plan.desired.join(", ")}]\n`);
+    session.finalize();
+}
+function displayAgents(agents) {
+    return agents.length > 0 ? agents.join(", ") : "(none)";
+}
+export function runManage(parsed, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    let result;
+    try {
+        result = collectManagePlan(parsed.operation, parsed.ids, homeDir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    if ("error" in result) {
+        console.error(result.error);
+        return { exitCode: 1 };
+    }
+    const { plan } = result;
+    if (!parsed.dryRun)
+        applyManagePlan(plan, homeDir);
+    if (parsed.json) {
+        console.log(JSON.stringify(plan, null, 2));
+    }
+    else if (parsed.operation === "list") {
+        console.log(`managed agents: ${displayAgents(plan.current)}`);
+    }
+    else {
+        console.log(`${parsed.dryRun ? "[dry run] " : ""}managed agents: ${displayAgents(plan.current)} -> ${displayAgents(plan.desired)}`);
+        if (!plan.changed)
+            console.log("  no change");
+        if (plan.added.length > 0)
+            console.log(`  added: ${plan.added.join(", ")}`);
+        if (plan.removed.length > 0)
+            console.log(`  detached: ${plan.removed.join(", ")} (native state preserved)`);
+    }
+    return { exitCode: 0, plan };
+}

package/dist/commands/mcp.d.ts

@@ -12,7 +12,7 @@
  */
 import { type ServersYamlWriteResult } from "../core/canonical.js";
 import type { AdapterPlanItem } from "../core/adapter.js";
-import type { AgentId, McpServerDef, Transport } from "../core/types.js";
+import type { AgentId, McpAuthMode, McpConfig, McpServerDef, Transport } from "../core/types.js";
 import { type BackupSession } from "../lib/backup.js";
 export interface RunMcpSyncOptions {
     json?: boolean;
@@ -24,6 +24,9 @@ export interface RunMcpSyncOptions {
     /** Onboard-only seam — see RunSyncOptions.managedAgents. Never a CLI
      * flag. */
     managedAgents?: readonly AgentId[];
+    /** Onboard-only canonical MCP override used to preview a route selection
+     * before writing it to servers.yaml. */
+    mcp?: McpConfig;
     /** Onboard-only seam — see RunSyncOptions.backupSession. Never a CLI
      * flag. */
     backupSession?: BackupSession;
@@ -47,6 +50,7 @@ export declare function printReport(report: McpSyncReport, dryRun: boolean): voi
 export interface McpListEntry {
     name: string;
     transport: Transport;
+    auth?: McpAuthMode;
     enabled: boolean;
     agents: readonly AgentId[];
     command?: string;
@@ -75,6 +79,7 @@ export declare function runMcpList(opts?: {
  * command's own inline flag parsing in src/cli.ts. */
 export interface McpAddRawArgs {
     transport?: string;
+    auth?: string;
     command?: string;
     /** Comma-separated. */
     args?: string;
@@ -107,6 +112,22 @@ export interface McpAddPlan {
  * always refuses, ever (design.md D4).
  */
 export declare function collectMcpAddPlan(name: string | undefined, raw: McpAddRawArgs, homeDir?: string): McpAddPlan;
+export type McpSetAuthAction = "updated" | "already-set" | "not-found" | "invalid-input";
+export interface McpSetAuthPlan {
+    name: string;
+    auth: "oauth" | "none";
+    action: McpSetAuthAction;
+    detail: string;
+    def?: McpServerDef;
+}
+export declare function collectMcpSetAuthPlan(name: string | undefined, auth: string | undefined, homeDir?: string): McpSetAuthPlan;
+export declare function runMcpSetAuth(name: string | undefined, auth: string | undefined, opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): {
+    exitCode: number;
+};
 export declare function applyMcpAddPlan(plan: McpAddPlan, homeDir?: string): ServersYamlWriteResult;
 export declare function runMcpAdd(name: string | undefined, raw: McpAddRawArgs, opts?: {
     homeDir?: string;

package/dist/commands/mcp.js

@@ -18,12 +18,14 @@ import { ClaudeCodeAdapter } from "../adapters/claude-code.js";
 import { CodexAdapter } from "../adapters/codex.js";
 import { KiroAdapter } from "../adapters/kiro.js";
 import { PiAdapter } from "../adapters/pi.js";
+import { KimiCodeAdapter } from "../adapters/kimi-code.js";
 import { openBackupSession } from "../lib/backup.js";
 const ADAPTER_FACTORY = {
     "claude-code": (homeDir) => new ClaudeCodeAdapter(homeDir),
     codex: (homeDir) => new CodexAdapter(homeDir),
     kiro: (homeDir) => new KiroAdapter(homeDir),
     pi: (homeDir) => new PiAdapter(homeDir),
+    "kimi-code": (homeDir) => new KimiCodeAdapter(homeDir),
 };
 /** Only agents in `canonical.managedAgents` — see src/commands/sync.ts's
  * own copy of this same restriction (trellis-managed-agents). */
@@ -33,7 +35,11 @@ function buildAdapters(homeDir, managedAgents) {
 export async function collectMcpSyncReport(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
     const loaded = loadCanonicalSource(homeDir);
-    const canonical = opts.managedAgents ? { ...loaded, managedAgents: opts.managedAgents } : loaded;
+    const canonical = {
+        ...loaded,
+        ...(opts.managedAgents ? { managedAgents: opts.managedAgents } : {}),
+        ...(opts.mcp ? { mcp: opts.mcp } : {}),
+    };
     const reports = [];
     const ownSession = !opts.dryRun && !opts.backupSession ? openBackupSession(homeDir, "mcp-sync") : undefined;
     const backup = opts.backupSession ?? ownSession;
@@ -107,6 +113,7 @@ export function collectMcpListPlan(homeDir = homedir()) {
     return Object.entries(canonical.mcp.servers).map(([name, def]) => ({
         name,
         transport: def.transport,
+        auth: def.auth,
         enabled: def.enabled ?? true,
         agents: resolveScope(def.agents, canonical.managedAgents),
         command: def.command,
@@ -136,7 +143,7 @@ export function runMcpList(opts = {}) {
     else {
         for (const e of entries) {
             const scope = e.agents.length > 0 ? e.agents.join(", ") : "(no managed agent reaches it)";
-            console.log(`${e.name} (${e.transport})${e.enabled ? "" : " [disabled]"} — ${scope}`);
+            console.log(`${e.name} (${e.transport}${e.auth === "oauth" ? ", oauth" : ""})${e.enabled ? "" : " [disabled]"} — ${scope}`);
             if (e.env && e.env.length > 0)
                 console.log(`   env: ${e.env.join(", ")} (values never read/printed)`);
             if (e.staticEnv)
@@ -152,6 +159,7 @@ export function parseMcpAddArgs(argv) {
     };
     return {
         transport: flag("--transport"),
+        auth: flag("--auth"),
         command: flag("--command"),
         args: flag("--args"),
         url: flag("--url"),
@@ -202,6 +210,12 @@ export function collectMcpAddPlan(name, raw, homeDir = homedir()) {
     if ((transport === "http" || transport === "sse") && !raw.url) {
         return { name, action: "invalid-input", detail: `--transport ${transport} requires --url` };
     }
+    if (raw.auth !== undefined && raw.auth !== "oauth") {
+        return { name, action: "invalid-input", detail: `--auth must be "oauth" when provided (got ${raw.auth})` };
+    }
+    if (raw.auth === "oauth" && transport === "stdio") {
+        return { name, action: "invalid-input", detail: "--auth oauth requires an http or sse MCP server" };
+    }
     const agentsList = parseCsv(raw.agents);
     if (agentsList) {
         for (const id of agentsList) {
@@ -215,6 +229,7 @@ export function collectMcpAddPlan(name, raw, homeDir = homedir()) {
     }
     const def = {
         transport,
+        ...(raw.auth === "oauth" ? { auth: "oauth" } : {}),
         ...(raw.command ? { command: raw.command } : {}),
         ...(parseCsv(raw.args) ? { args: parseCsv(raw.args) } : {}),
         ...(raw.url ? { url: raw.url } : {}),
@@ -234,6 +249,54 @@ export function collectMcpAddPlan(name, raw, homeDir = homedir()) {
     }
     return { name, action: "create", detail: "will add to servers.yaml", def };
 }
+export function collectMcpSetAuthPlan(name, auth, homeDir = homedir()) {
+    const mode = auth === "oauth" || auth === "none" ? auth : undefined;
+    if (!name)
+        return { name: "(none)", auth: (mode ?? "none"), action: "invalid-input", detail: "usage: trellis mcp set <name> --auth oauth|none" };
+    if (!mode)
+        return { name, auth: "none", action: "invalid-input", detail: `--auth must be "oauth" or "none" (got ${auth ?? "(missing)"})` };
+    const canonical = loadCanonicalSource(homeDir);
+    const current = canonical.mcp.servers[name];
+    if (!current)
+        return { name, auth: mode, action: "not-found", detail: `no canonical MCP server named "${name}"` };
+    if (mode === "oauth" && !current.url) {
+        return { name, auth: mode, action: "invalid-input", detail: "auth: oauth requires an http or sse MCP server" };
+    }
+    const next = mode === "oauth" ? { ...current, auth: "oauth" } : (() => {
+        const { auth: _auth, ...withoutAuth } = current;
+        return withoutAuth;
+    })();
+    if (JSON.stringify(current) === JSON.stringify(next))
+        return { name, auth: mode, action: "already-set", detail: `auth is already ${mode}`, def: next };
+    return { name, auth: mode, action: "updated", detail: `set auth to ${mode}`, def: next };
+}
+export function runMcpSetAuth(name, auth, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    let plan;
+    try {
+        plan = collectMcpSetAuthPlan(name, auth, homeDir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    let writeError;
+    if (!opts.dryRun && plan.action === "updated" && plan.def) {
+        const result = upsertServerYaml(serversYamlPath(homeDir), plan.name, plan.def);
+        if (!result.ok)
+            writeError = result.error;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(writeError ? { ...plan, writeError } : plan, null, 2));
+    }
+    else {
+        console.log(`${opts.dryRun ? "[dry run] " : ""}mcp set ${plan.name}`);
+        console.log(`  [${plan.action}] ${plan.detail}`);
+        if (writeError)
+            console.error(`  write failed: ${writeError}`);
+    }
+    return { exitCode: ["invalid-input", "not-found"].includes(plan.action) || Boolean(writeError) ? 1 : 0 };
+}
 export function applyMcpAddPlan(plan, homeDir = homedir()) {
     if (plan.action !== "create" || !plan.def)
         return { ok: true };

package/dist/commands/mcpGateway.d.ts

@@ -51,3 +51,9 @@ export declare function resolveGatewayUpstreams(agentId: AgentId, canonical: Pic
 export declare function runMcpGateway(opts: RunMcpGatewayOptions): Promise<{
     exitCode: number;
 }>;
+/** The first-class runtime entrypoint. mcp-gateway remains a compatibility
+ * alias for existing native agent config, but both edges use the same
+ * provider registry and backend construction path. */
+export declare function runMcpRuntime(opts: RunMcpGatewayOptions): Promise<{
+    exitCode: number;
+}>;