@zleap-ai/sag-cli 0.2.0

package/dist/cli.js

@@ -0,0 +1,3109 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { confirm, password, select } from "@inquirer/prompts";
+
+// package.json
+var package_default = {
+  name: "@zleap-ai/sag-cli",
+  version: "0.2.0",
+  description: "Command-line client and diagnostics for SAG knowledge bases",
+  type: "module",
+  bin: {
+    sag: "dist/cli.js"
+  },
+  files: [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  scripts: {
+    build: "tsup",
+    dev: "tsx src/cli.ts",
+    test: "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    typecheck: "tsc --noEmit",
+    lint: "eslint .",
+    format: "prettier --write .",
+    "format:check": "prettier --check .",
+    check: "npm run format:check && npm run lint && npm run typecheck && npm test && npm run build",
+    prepare: "husky",
+    commitlint: "commitlint",
+    changeset: "changeset",
+    "version-packages": "changeset version",
+    "release:check": "bash scripts/release.sh",
+    release: "bash scripts/release.sh --publish"
+  },
+  engines: {
+    node: ">=20.19.0"
+  },
+  publishConfig: {
+    access: "public"
+  },
+  license: "MIT",
+  dependencies: {
+    "@inquirer/prompts": "^8.5.2",
+    "@modelcontextprotocol/client": "^2.0.0",
+    commander: "^14.0.3",
+    "proper-lockfile": "^4.1.2",
+    yaml: "^2.9.0",
+    zod: "^4.4.3"
+  },
+  optionalDependencies: {
+    "@napi-rs/keyring": "^1.3.0"
+  },
+  devDependencies: {
+    "@changesets/cli": "^2.31.1",
+    "@commitlint/cli": "^20.0.0",
+    "@commitlint/config-conventional": "^20.0.0",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^20.19.43",
+    "@types/proper-lockfile": "^4.1.4",
+    "@typescript-eslint/eslint-plugin": "^8.65.0",
+    "@typescript-eslint/parser": "^8.65.0",
+    "@vitest/coverage-v8": "^4.1.10",
+    eslint: "^10.8.0",
+    husky: "^9.1.7",
+    "lint-staged": "^16.2.7",
+    prettier: "^3.9.6",
+    tsup: "^8.5.1",
+    tsx: "^4.23.1",
+    typescript: "^6.0.3",
+    vitest: "^4.1.10"
+  },
+  "lint-staged": {
+    "*.{ts,js,mjs,cjs}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md,yml,yaml}": [
+      "prettier --write"
+    ]
+  }
+};
+
+// src/agents/claude-code.ts
+import { readFile } from "fs/promises";
+import os from "os";
+import path from "path";
+import { z } from "zod";
+
+// src/core/errors.ts
+var CliError = class extends Error {
+  code;
+  exitCode;
+  hint;
+  cause;
+  constructor(code, message, options) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+    this.exitCode = options.exitCode;
+    this.hint = options.hint;
+    this.cause = options.cause;
+  }
+  toShape() {
+    return {
+      code: this.code,
+      message: this.message,
+      ...this.hint ? { hint: this.hint } : {}
+    };
+  }
+};
+var exitCodes = {
+  success: 0,
+  invalidArgument: 2,
+  networkUnreachable: 10,
+  serviceNotReady: 11,
+  authRequired: 20,
+  permissionDenied: 21,
+  resourceNotFound: 30,
+  documentNotReady: 31,
+  mcpFailed: 40,
+  hostNotFound: 41,
+  hostConfigFailed: 42,
+  configConflict: 50,
+  dependencyMissing: 60,
+  internalError: 70
+};
+function toCliError(error) {
+  if (error instanceof CliError) {
+    return error;
+  }
+  return new CliError("INTERNAL_ERROR", "Unexpected internal error", {
+    exitCode: exitCodes.internalError,
+    cause: error,
+    hint: "Run again with SAG_DEBUG=1 for technical details."
+  });
+}
+
+// src/agents/adapter.ts
+import { createHash } from "crypto";
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, nested]) => [key, canonicalize(nested)])
+    );
+  }
+  return value;
+}
+function fingerprintValue(value) {
+  const canonical = JSON.stringify(canonicalize(value));
+  return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+function fingerprintConnection(spec) {
+  return fingerprintValue(spec);
+}
+function connectionKey(agent, scope, serverName) {
+  return `${agent}:${scope}:${serverName}`;
+}
+
+// src/agents/claude-code.ts
+var claudeConfigSchema = z.object({
+  mcpServers: z.record(z.string(), z.unknown()).optional()
+});
+var claudeEntrySchema = z.object({
+  type: z.literal("stdio").optional(),
+  command: z.string().min(1),
+  args: z.array(z.string()).optional(),
+  env: z.record(z.string(), z.string()).optional()
+});
+function invalidSpec() {
+  return new CliError(
+    "INVALID_ARGUMENT",
+    "Claude Code v0.2 supports Docker stdio MCP connections only",
+    {
+      exitCode: exitCodes.invalidArgument
+    }
+  );
+}
+function hostFailure(message, cause) {
+  return new CliError("HOST_CONFIG_FAILED", message, {
+    exitCode: exitCodes.hostConfigFailed,
+    ...cause ? { cause } : {},
+    hint: "Run `claude mcp list` to inspect the current Claude Code MCP configuration."
+  });
+}
+function ensureSuccess(result, action) {
+  if (result.exitCode !== 0) {
+    throw hostFailure(`Claude Code failed to ${action}`);
+  }
+}
+var ClaudeCodeAdapter = class {
+  constructor(runner, options = {}) {
+    this.runner = runner;
+    const configPath = options.configPath ?? path.join(os.homedir(), ".claude.json");
+    this.readConfig = options.readConfig ?? (() => readFile(configPath, "utf8").catch((error) => {
+      if (error.code === "ENOENT") return "{}";
+      throw error;
+    }));
+  }
+  runner;
+  id = "claude-code";
+  readConfig;
+  async detect() {
+    try {
+      const result = await this.runner.run({
+        command: "claude",
+        args: ["--version"],
+        timeoutMs: 5e3
+      });
+      if (result.exitCode !== 0) {
+        throw new Error("Claude Code returned an error");
+      }
+      return { id: this.id, version: result.stdout.trim() };
+    } catch (cause) {
+      throw new CliError("HOST_NOT_FOUND", "Claude Code CLI was not found", {
+        exitCode: exitCodes.hostNotFound,
+        cause,
+        hint: "Install Claude Code and ensure `claude` is available on PATH."
+      });
+    }
+  }
+  async read(name, scope) {
+    try {
+      const config = claudeConfigSchema.parse(JSON.parse(await this.readConfig()));
+      const rawEntry = config.mcpServers?.[name];
+      if (!rawEntry) return null;
+      const entry = claudeEntrySchema.parse(rawEntry);
+      const spec = {
+        transport: "stdio",
+        command: entry.command,
+        args: entry.args ?? [],
+        env: entry.env ?? {}
+      };
+      return {
+        agent: this.id,
+        name,
+        scope,
+        spec,
+        fingerprint: fingerprintConnection(spec)
+      };
+    } catch (cause) {
+      throw hostFailure("Claude Code user MCP configuration is invalid", cause);
+    }
+  }
+  async add(name, scope, spec) {
+    if (spec.transport !== "stdio" || Object.keys(spec.env).length) {
+      throw invalidSpec();
+    }
+    ensureSuccess(
+      await this.runner.run({
+        command: "claude",
+        args: ["mcp", "add", "--scope", scope, name, "--", spec.command, ...spec.args],
+        timeoutMs: 15e3
+      }),
+      "add the MCP server"
+    );
+  }
+  async remove(name, scope) {
+    ensureSuccess(
+      await this.runner.run({
+        command: "claude",
+        args: ["mcp", "remove", "--scope", scope, name],
+        timeoutMs: 15e3
+      }),
+      "remove the MCP server"
+    );
+  }
+};
+
+// src/agents/codex.ts
+import { z as z2 } from "zod";
+var codexEntrySchema = z2.object({
+  name: z2.string().optional(),
+  enabled: z2.boolean(),
+  disabled_reason: z2.unknown().optional(),
+  transport: z2.object({
+    type: z2.literal("stdio"),
+    command: z2.string().min(1),
+    args: z2.array(z2.string()).optional(),
+    env: z2.record(z2.string(), z2.string()).nullish()
+  }).passthrough(),
+  startup_timeout_sec: z2.number().nullish(),
+  tool_timeout_sec: z2.number().nullish(),
+  auth_status: z2.unknown().optional()
+}).passthrough();
+var CODEX_STATUS_FIELDS = /* @__PURE__ */ new Set(["name", "disabled_reason", "auth_status"]);
+function invalidSpec2() {
+  return new CliError(
+    "INVALID_ARGUMENT",
+    "Codex v0.2 supports Docker stdio MCP connections only",
+    {
+      exitCode: exitCodes.invalidArgument
+    }
+  );
+}
+function hostFailure2(message, cause) {
+  return new CliError("HOST_CONFIG_FAILED", message, {
+    exitCode: exitCodes.hostConfigFailed,
+    ...cause ? { cause } : {},
+    hint: "Run `codex mcp list` to inspect the current Codex MCP configuration."
+  });
+}
+function ensureSuccess2(result, action) {
+  if (result.exitCode !== 0) {
+    throw hostFailure2(`Codex failed to ${action}`);
+  }
+}
+var CodexAdapter = class {
+  constructor(runner) {
+    this.runner = runner;
+  }
+  runner;
+  id = "codex";
+  async detect() {
+    try {
+      const result = await this.runner.run({
+        command: "codex",
+        args: ["--version"],
+        timeoutMs: 5e3
+      });
+      if (result.exitCode !== 0) throw new Error("Codex returned an error");
+      return { id: this.id, version: result.stdout.trim() };
+    } catch (cause) {
+      throw new CliError("HOST_NOT_FOUND", "Codex CLI was not found", {
+        exitCode: exitCodes.hostNotFound,
+        cause,
+        hint: "Install Codex CLI and ensure `codex` is available on PATH."
+      });
+    }
+  }
+  async read(name, scope) {
+    const result = await this.runner.run({
+      command: "codex",
+      args: ["mcp", "get", name, "--json"],
+      timeoutMs: 15e3
+    });
+    if (result.exitCode !== 0) {
+      if (/not found|does not exist|no mcp server/iu.test(result.stderr)) {
+        return null;
+      }
+      throw hostFailure2("Codex failed to read the MCP configuration");
+    }
+    try {
+      const entry = codexEntrySchema.parse(JSON.parse(result.stdout));
+      const spec = {
+        transport: "stdio",
+        command: entry.transport.command,
+        args: entry.transport.args ?? [],
+        env: entry.transport.env ?? {}
+      };
+      const configuration = Object.fromEntries(
+        Object.entries(entry).filter(([key]) => !CODEX_STATUS_FIELDS.has(key))
+      );
+      return {
+        agent: this.id,
+        name,
+        scope,
+        spec,
+        fingerprint: fingerprintValue(configuration)
+      };
+    } catch (cause) {
+      throw hostFailure2("Codex returned an invalid MCP configuration", cause);
+    }
+  }
+  async add(name, scope, spec) {
+    if (scope !== "user" || spec.transport !== "stdio" || Object.keys(spec.env).length) {
+      throw invalidSpec2();
+    }
+    ensureSuccess2(
+      await this.runner.run({
+        command: "codex",
+        args: ["mcp", "add", name, "--", spec.command, ...spec.args],
+        timeoutMs: 15e3
+      }),
+      "add the MCP server"
+    );
+  }
+  async remove(name, scope) {
+    if (scope !== "user") {
+      throw invalidSpec2();
+    }
+    ensureSuccess2(
+      await this.runner.run({
+        command: "codex",
+        args: ["mcp", "remove", name],
+        timeoutMs: 15e3
+      }),
+      "remove the MCP server"
+    );
+  }
+};
+
+// src/agents/state.ts
+import { chmod, mkdir, readFile as readFile2, rename, unlink, writeFile } from "fs/promises";
+import path2 from "path";
+import { lock } from "proper-lockfile";
+import { parse, stringify } from "yaml";
+import { z as z3 } from "zod";
+var managedConnectionSchema = z3.strictObject({
+  agent: z3.enum(["codex", "claude-code"]),
+  provider: z3.literal("docker-stdio"),
+  profile: z3.string().min(1),
+  serverName: z3.string().min(1),
+  docker: z3.strictObject({
+    composeProject: z3.string().min(1).optional(),
+    composeService: z3.string().min(1).optional(),
+    containerName: z3.string().min(1)
+  }),
+  sourceId: z3.string().min(1).nullable(),
+  scope: z3.literal("user"),
+  fingerprint: z3.string().regex(/^sha256:[a-f0-9]{64}$/u),
+  createdAt: z3.string().min(1)
+});
+var managedConnectionsSchema = z3.strictObject({
+  version: z3.literal(1),
+  connections: z3.record(z3.string(), managedConnectionSchema)
+});
+function emptyState() {
+  return { version: 1, connections: {} };
+}
+function invalidState(cause, filePath) {
+  return new CliError("CONFIG_CONFLICT", "Managed connection state is invalid", {
+    exitCode: exitCodes.configConflict,
+    cause,
+    hint: `Review or restore ${filePath}.`
+  });
+}
+var ManagedConnectionStore = class {
+  constructor(filePath) {
+    this.filePath = filePath;
+  }
+  filePath;
+  async #withLock(operation) {
+    await mkdir(path2.dirname(this.filePath), { recursive: true });
+    let release;
+    try {
+      release = await lock(this.filePath, {
+        realpath: false,
+        stale: 1e4,
+        update: 2e3,
+        retries: {
+          retries: 40,
+          factor: 1,
+          minTimeout: 25,
+          maxTimeout: 100
+        }
+      });
+    } catch (cause) {
+      throw new CliError("CONFIG_CONFLICT", "Managed connection state is busy", {
+        exitCode: exitCodes.configConflict,
+        cause,
+        hint: "Wait for the other SAG CLI Agent command to finish and retry."
+      });
+    }
+    try {
+      return await operation();
+    } finally {
+      await release();
+    }
+  }
+  async load() {
+    let raw;
+    try {
+      raw = await readFile2(this.filePath, "utf8");
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return emptyState();
+      }
+      throw error;
+    }
+    try {
+      return managedConnectionsSchema.parse(parse(raw));
+    } catch (cause) {
+      throw invalidState(cause, this.filePath);
+    }
+  }
+  async #saveUnlocked(state) {
+    let validated;
+    try {
+      validated = managedConnectionsSchema.parse(state);
+    } catch (cause) {
+      throw invalidState(cause, this.filePath);
+    }
+    const directory = path2.dirname(this.filePath);
+    await mkdir(directory, { recursive: true });
+    const temporaryPath = path2.join(
+      directory,
+      `.${path2.basename(this.filePath)}.${process.pid}.${Date.now()}.tmp`
+    );
+    try {
+      await writeFile(temporaryPath, stringify(validated), {
+        encoding: "utf8",
+        mode: 384
+      });
+      await rename(temporaryPath, this.filePath);
+      await chmod(this.filePath, 384);
+    } catch (error) {
+      await unlink(temporaryPath).catch(() => void 0);
+      throw error;
+    }
+  }
+  async save(state) {
+    await this.#withLock(() => this.#saveUnlocked(state));
+  }
+  async get(key) {
+    return (await this.load()).connections[key] ?? null;
+  }
+  async set(connection) {
+    const validated = (() => {
+      try {
+        return managedConnectionSchema.parse(connection);
+      } catch (cause) {
+        throw invalidState(cause, this.filePath);
+      }
+    })();
+    await this.#withLock(async () => {
+      const state = await this.load();
+      const key = connectionKey(validated.agent, validated.scope, validated.serverName);
+      state.connections[key] = validated;
+      await this.#saveUnlocked(state);
+    });
+  }
+  async delete(key) {
+    await this.#withLock(async () => {
+      const state = await this.load();
+      delete state.connections[key];
+      await this.#saveUnlocked(state);
+    });
+  }
+  async list(input) {
+    return Object.values((await this.load()).connections).filter(
+      (connection) => (!input?.agent || connection.agent === input.agent) && (!input?.scope || connection.scope === input.scope)
+    );
+  }
+};
+
+// src/config/store.ts
+import { mkdir as mkdir2, readFile as readFile3, rename as rename2, unlink as unlink2, writeFile as writeFile2 } from "fs/promises";
+import path3 from "path";
+import { parse as parse2, stringify as stringify2 } from "yaml";
+
+// src/config/resolve.ts
+var PROFILE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/u;
+var STRIPPED_PATHS = /* @__PURE__ */ new Set(["/", "/api/v1", "/api/v1/", "/mcp", "/mcp/"]);
+function validateProfileName(name) {
+  if (!PROFILE_NAME.test(name)) {
+    throw new CliError("INVALID_ARGUMENT", `Invalid profile name: ${name}`, {
+      exitCode: exitCodes.invalidArgument,
+      hint: "Use 1-64 letters, numbers, hyphens, or underscores."
+    });
+  }
+  return name;
+}
+function normalizeOrigin(input) {
+  let url;
+  try {
+    url = new URL(input);
+  } catch (cause) {
+    throw new CliError("INVALID_ARGUMENT", `Invalid SAG URL: ${input}`, {
+      exitCode: exitCodes.invalidArgument,
+      cause,
+      hint: "Use an absolute HTTP or HTTPS URL such as http://localhost:8000."
+    });
+  }
+  if (!["http:", "https:"].includes(url.protocol)) {
+    throw new CliError("INVALID_ARGUMENT", "SAG URL must use HTTP or HTTPS", {
+      exitCode: exitCodes.invalidArgument
+    });
+  }
+  if (url.username || url.password) {
+    throw new CliError("INVALID_ARGUMENT", "SAG URL must not contain credentials", {
+      exitCode: exitCodes.invalidArgument
+    });
+  }
+  if (url.search || url.hash) {
+    throw new CliError(
+      "INVALID_ARGUMENT",
+      "SAG URL must not contain a query string or fragment",
+      { exitCode: exitCodes.invalidArgument }
+    );
+  }
+  if (!STRIPPED_PATHS.has(url.pathname)) {
+    throw new CliError(
+      "INVALID_ARGUMENT",
+      `Unsupported path in SAG URL: ${url.pathname}`,
+      {
+        exitCode: exitCodes.invalidArgument,
+        hint: "Store only the SAG origin; /api/v1 and /mcp/ are added automatically."
+      }
+    );
+  }
+  return url.origin;
+}
+function profileOrThrow(config, name) {
+  validateProfileName(name);
+  const profile = config.profiles[name];
+  if (!profile) {
+    throw new CliError("RESOURCE_NOT_FOUND", `Profile not found: ${name}`, {
+      exitCode: exitCodes.resourceNotFound,
+      hint: "Run `sag profile list` to view configured profiles."
+    });
+  }
+  return profile;
+}
+function withOptionalFields(base, profileName, profile, environmentToken) {
+  return {
+    ...base,
+    ...profileName ? { profileName } : {},
+    ...profile ? { credentialRef: profile.credentialRef } : {},
+    ...environmentToken ? { environmentToken } : {}
+  };
+}
+function resolveConnection(options, environment, config) {
+  const environmentToken = environment.SAG_TOKEN?.trim() || void 0;
+  if (options.url) {
+    const profileName = options.profile ? validateProfileName(options.profile) : void 0;
+    const profile = profileName ? profileOrThrow(config, profileName) : void 0;
+    return withOptionalFields(
+      { url: normalizeOrigin(options.url), source: "explicit-url" },
+      profileName,
+      profile,
+      environmentToken
+    );
+  }
+  if (options.profile) {
+    const profileName = validateProfileName(options.profile);
+    const profile = profileOrThrow(config, profileName);
+    return withOptionalFields(
+      { url: normalizeOrigin(profile.url), source: "explicit-profile" },
+      profileName,
+      profile,
+      environmentToken
+    );
+  }
+  if (environment.SAG_URL) {
+    return withOptionalFields(
+      {
+        url: normalizeOrigin(environment.SAG_URL),
+        source: "environment-url"
+      },
+      void 0,
+      void 0,
+      environmentToken
+    );
+  }
+  if (environment.SAG_PROFILE) {
+    const profileName = validateProfileName(environment.SAG_PROFILE);
+    const profile = profileOrThrow(config, profileName);
+    return withOptionalFields(
+      { url: normalizeOrigin(profile.url), source: "environment-profile" },
+      profileName,
+      profile,
+      environmentToken
+    );
+  }
+  if (config.currentProfile) {
+    const profileName = config.currentProfile;
+    const profile = profileOrThrow(config, profileName);
+    return withOptionalFields(
+      { url: normalizeOrigin(profile.url), source: "current-profile" },
+      profileName,
+      profile,
+      environmentToken
+    );
+  }
+  return withOptionalFields(
+    { url: "http://127.0.0.1:8000", source: "local-probe" },
+    void 0,
+    void 0,
+    environmentToken
+  );
+}
+
+// src/config/schema.ts
+import { z as z4 } from "zod";
+var profileSchema = z4.object({
+  url: z4.string(),
+  credentialRef: z4.string().min(1),
+  defaults: z4.object({
+    output: z4.enum(["human", "json"]).optional()
+  }).optional()
+});
+var cliConfigSchema = z4.object({
+  version: z4.literal(1),
+  currentProfile: z4.string().optional(),
+  profiles: z4.record(z4.string(), profileSchema)
+});
+var emptyConfig = () => ({
+  version: 1,
+  profiles: {}
+});
+
+// src/config/store.ts
+var ConfigStore = class {
+  constructor(filePath) {
+    this.filePath = filePath;
+  }
+  filePath;
+  async load() {
+    let raw;
+    try {
+      raw = await readFile3(this.filePath, "utf8");
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return emptyConfig();
+      }
+      throw error;
+    }
+    try {
+      return cliConfigSchema.parse(parse2(raw));
+    } catch (cause) {
+      throw new CliError("CONFIG_CONFLICT", "CLI config is invalid", {
+        exitCode: exitCodes.configConflict,
+        cause,
+        hint: `Review or restore ${this.filePath}.`
+      });
+    }
+  }
+  async save(config) {
+    const validated = cliConfigSchema.parse(config);
+    const directory = path3.dirname(this.filePath);
+    await mkdir2(directory, { recursive: true });
+    const temporaryPath = path3.join(
+      directory,
+      `.${path3.basename(this.filePath)}.${process.pid}.${Date.now()}.tmp`
+    );
+    try {
+      await writeFile2(temporaryPath, stringify2(validated), {
+        encoding: "utf8",
+        mode: 384
+      });
+      await rename2(temporaryPath, this.filePath);
+    } catch (error) {
+      await unlink2(temporaryPath).catch(() => void 0);
+      throw error;
+    }
+  }
+  async addProfile(name, url) {
+    validateProfileName(name);
+    const normalizedUrl = normalizeOrigin(url);
+    const config = await this.load();
+    const existing = config.profiles[name];
+    if (existing && existing.url !== normalizedUrl) {
+      throw new CliError(
+        "CONFIG_CONFLICT",
+        `Profile already points to a different SAG origin: ${name}`,
+        {
+          exitCode: exitCodes.configConflict,
+          hint: "Remove the profile first or choose another name."
+        }
+      );
+    }
+    const profile = existing ?? {
+      url: normalizedUrl,
+      credentialRef: `sag-cli/${name}`
+    };
+    config.profiles[name] = profile;
+    config.currentProfile ??= name;
+    await this.save(config);
+    return {
+      name,
+      current: config.currentProfile === name,
+      ...profile
+    };
+  }
+  async listProfiles() {
+    const config = await this.load();
+    return Object.entries(config.profiles).sort(([left], [right]) => left.localeCompare(right)).map(([name, profile]) => ({
+      name,
+      current: config.currentProfile === name,
+      ...profile
+    }));
+  }
+  async getProfile(name) {
+    const config = await this.load();
+    const selectedName = name ?? config.currentProfile;
+    if (!selectedName || !config.profiles[selectedName]) {
+      throw new CliError("RESOURCE_NOT_FOUND", "Profile not found", {
+        exitCode: exitCodes.resourceNotFound,
+        hint: "Run `sag profile add <name> <url>` first."
+      });
+    }
+    return {
+      name: selectedName,
+      current: config.currentProfile === selectedName,
+      ...config.profiles[selectedName]
+    };
+  }
+  async useProfile(name) {
+    const config = await this.load();
+    validateProfileName(name);
+    const profile = config.profiles[name];
+    if (!profile) {
+      throw new CliError("RESOURCE_NOT_FOUND", `Profile not found: ${name}`, {
+        exitCode: exitCodes.resourceNotFound
+      });
+    }
+    config.currentProfile = name;
+    await this.save(config);
+    return { name, current: true, ...profile };
+  }
+  async removeProfile(name) {
+    const config = await this.load();
+    validateProfileName(name);
+    if (!config.profiles[name]) {
+      throw new CliError("RESOURCE_NOT_FOUND", `Profile not found: ${name}`, {
+        exitCode: exitCodes.resourceNotFound
+      });
+    }
+    delete config.profiles[name];
+    if (config.currentProfile === name) {
+      config.currentProfile = Object.keys(config.profiles).sort()[0];
+      if (!config.currentProfile) {
+        delete config.currentProfile;
+      }
+    }
+    await this.save(config);
+  }
+};
+
+// src/config/paths.ts
+import os2 from "os";
+import path4 from "path";
+function defaultConfigPath(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const homeDirectory = options.homeDirectory ?? os2.homedir();
+  const environment = options.environment ?? process.env;
+  if (platform === "darwin") {
+    return path4.join(
+      homeDirectory,
+      "Library",
+      "Application Support",
+      "sag-cli",
+      "config.yaml"
+    );
+  }
+  if (platform === "win32") {
+    const appData = environment.APPDATA;
+    return path4.join(
+      appData || path4.join(homeDirectory, "AppData", "Roaming"),
+      "sag-cli",
+      "config.yaml"
+    );
+  }
+  const xdgConfig = environment.XDG_CONFIG_HOME;
+  return path4.join(
+    xdgConfig || path4.join(homeDirectory, ".config"),
+    "sag-cli",
+    "config.yaml"
+  );
+}
+function defaultManagedConnectionsPath(options = {}) {
+  return path4.join(
+    path4.dirname(defaultConfigPath(options)),
+    "managed-connections.yaml"
+  );
+}
+
+// src/credentials/memory.ts
+var MemoryCredentialStore = class {
+  kind = "memory";
+  #values = /* @__PURE__ */ new Map();
+  async get(reference) {
+    return this.#values.get(reference) ?? null;
+  }
+  async set(reference, value) {
+    this.#values.set(reference, value);
+  }
+  async delete(reference) {
+    this.#values.delete(reference);
+  }
+};
+
+// src/credentials/keychain.ts
+var SERVICE_NAME = "@zleap-ai/sag-cli";
+var KeychainCredentialStore = class {
+  constructor(entryFactory) {
+    this.entryFactory = entryFactory;
+  }
+  entryFactory;
+  kind = "keychain";
+  async get(reference) {
+    return this.entryFactory(SERVICE_NAME, reference).getPassword();
+  }
+  async set(reference, value) {
+    this.entryFactory(SERVICE_NAME, reference).setPassword(value);
+  }
+  async delete(reference) {
+    this.entryFactory(SERVICE_NAME, reference).deletePassword();
+  }
+};
+async function createKeychainCredentialStore() {
+  const { Entry } = await import("@napi-rs/keyring");
+  return new KeychainCredentialStore((service, account) => new Entry(service, account));
+}
+async function createCredentialStore(loadKeychain = createKeychainCredentialStore) {
+  try {
+    return { store: await loadKeychain() };
+  } catch {
+    return {
+      store: new MemoryCredentialStore(),
+      warning: "System Keychain is unavailable; credentials will remain in memory only and must be provided again next time."
+    };
+  }
+}
+
+// src/docker/schemas.ts
+import { z as z5 } from "zod";
+var dockerVersionSchema = z5.object({
+  Platform: z5.object({
+    Name: z5.string().min(1)
+  })
+});
+var dockerPsLineSchema = z5.object({
+  ID: z5.string().min(1),
+  Names: z5.string().min(1),
+  Image: z5.string(),
+  Labels: z5.string()
+});
+var dockerInspectSchema = z5.array(
+  z5.object({
+    Id: z5.string().min(1),
+    Name: z5.string().min(1),
+    Config: z5.object({
+      Labels: z5.record(z5.string(), z5.string()).nullish()
+    }),
+    State: z5.object({
+      Running: z5.boolean(),
+      Health: z5.object({
+        Status: z5.enum(["healthy", "unhealthy", "starting"])
+      }).optional()
+    })
+  })
+).length(1);
+
+// src/docker/client.ts
+var DOCKER_TIMEOUT_MS = 5e3;
+function dependencyFailure(message, cause) {
+  return new CliError("DEPENDENCY_MISSING", message, {
+    exitCode: exitCodes.dependencyMissing,
+    ...cause ? { cause } : {},
+    hint: "Check that Docker Desktop or Docker Engine is running and accessible."
+  });
+}
+function invalidDockerResponse(cause) {
+  return new CliError("INVALID_RESPONSE", "Docker returned an invalid response", {
+    exitCode: exitCodes.internalError,
+    cause,
+    hint: "Check the installed Docker CLI version and try again."
+  });
+}
+function parseLabels(value) {
+  const labels = {};
+  for (const pair of value.split(",")) {
+    if (!pair) continue;
+    const separator = pair.indexOf("=");
+    if (separator === -1) continue;
+    labels[pair.slice(0, separator)] = pair.slice(separator + 1);
+  }
+  return labels;
+}
+var DockerClient = class {
+  constructor(runner) {
+    this.runner = runner;
+  }
+  runner;
+  async version() {
+    const result = await this.runner.run({
+      command: "docker",
+      args: ["version", "--format", "{{json .Server}}"],
+      timeoutMs: DOCKER_TIMEOUT_MS
+    });
+    if (result.exitCode !== 0) {
+      throw dependencyFailure("Docker daemon is unavailable");
+    }
+    try {
+      const parsed = dockerVersionSchema.parse(JSON.parse(result.stdout));
+      return { platformName: parsed.Platform.Name };
+    } catch (cause) {
+      throw invalidDockerResponse(cause);
+    }
+  }
+  async listRunningContainers() {
+    const result = await this.runner.run({
+      command: "docker",
+      args: ["ps", "--format", "{{json .}}"],
+      timeoutMs: DOCKER_TIMEOUT_MS
+    });
+    if (result.exitCode !== 0) {
+      throw dependencyFailure("Unable to list Docker containers");
+    }
+    if (!result.stdout.trim()) return [];
+    try {
+      return result.stdout.trim().split(/\r?\n/u).map((line) => dockerPsLineSchema.parse(JSON.parse(line))).map((container) => ({
+        id: container.ID,
+        name: container.Names,
+        image: container.Image,
+        labels: parseLabels(container.Labels)
+      }));
+    } catch (cause) {
+      throw invalidDockerResponse(cause);
+    }
+  }
+  async inspect(container) {
+    const result = await this.runner.run({
+      command: "docker",
+      args: ["inspect", container],
+      timeoutMs: DOCKER_TIMEOUT_MS
+    });
+    if (result.exitCode !== 0) {
+      if (/no such (?:object|container)/iu.test(result.stderr)) {
+        throw new CliError("RESOURCE_NOT_FOUND", "Docker container was not found", {
+          exitCode: exitCodes.resourceNotFound,
+          hint: "Check the container name or omit `--container` to auto-discover SAG."
+        });
+      }
+      throw dependencyFailure("Unable to inspect the Docker container");
+    }
+    try {
+      const inspection = dockerInspectSchema.parse(JSON.parse(result.stdout))[0];
+      return {
+        id: inspection.Id,
+        name: inspection.Name.replace(/^\/+/u, ""),
+        running: inspection.State.Running,
+        health: inspection.State.Health?.Status ?? "none",
+        labels: inspection.Config.Labels ?? {}
+      };
+    } catch (cause) {
+      throw invalidDockerResponse(cause);
+    }
+  }
+  async canImportMcp(container) {
+    const result = await this.runner.run({
+      command: "docker",
+      args: ["exec", container, "python", "-c", "import sag_api.mcp.server"],
+      timeoutMs: DOCKER_TIMEOUT_MS
+    });
+    return result.exitCode === 0;
+  }
+};
+
+// src/mcp/verifier.ts
+import { Client } from "@modelcontextprotocol/client";
+import {
+  getDefaultEnvironment,
+  StdioClientTransport
+} from "@modelcontextprotocol/client/stdio";
+
+// src/mcp/failure.ts
+function localMcpFailure(stage, message, options = {}) {
+  const failureCause = {
+    stage,
+    ...options.cause ? { cause: options.cause } : {}
+  };
+  return new CliError("MCP_FAILED", message, {
+    exitCode: exitCodes.mcpFailed,
+    cause: failureCause,
+    hint: options.hint ?? "Check the SAG API container logs and retry `sag mcp test`."
+  });
+}
+function localMcpFailureStage(error) {
+  if (error.code !== "MCP_FAILED" || typeof error.cause !== "object") {
+    return void 0;
+  }
+  const stage = error.cause?.stage;
+  return stage === "entrypoint" || stage === "protocol" || stage === "tools" || stage === "knowledge" ? stage : void 0;
+}
+
+// src/mcp/verifier.ts
+var REQUIRED_SAG_TOOLS = [
+  "list_sources",
+  "list_documents",
+  "outline",
+  "search",
+  "grep",
+  "get_chunk",
+  "read",
+  "get_entity"
+];
+var McpVerifier = class {
+  constructor(cliVersion) {
+    this.cliVersion = cliVersion;
+  }
+  cliVersion;
+  async verify(spec, options) {
+    if (spec.transport !== "stdio") {
+      throw new CliError(
+        "INVALID_ARGUMENT",
+        "HTTP MCP is not supported in SAG CLI v0.2",
+        {
+          exitCode: exitCodes.invalidArgument,
+          hint: "Use a local Docker stdio connection."
+        }
+      );
+    }
+    const client = new Client(
+      {
+        name: "@zleap-ai/sag-cli",
+        version: this.cliVersion
+      },
+      {
+        versionNegotiation: {
+          mode: "auto",
+          probe: {
+            timeoutMs: Math.min(options.timeoutMs, 250),
+            maxRetries: 0
+          }
+        }
+      }
+    );
+    const transport = new StdioClientTransport({
+      command: spec.command,
+      args: spec.args,
+      env: {
+        ...getDefaultEnvironment(),
+        ...spec.env
+      },
+      stderr: "pipe"
+    });
+    transport.stderr?.on("data", () => void 0);
+    try {
+      await client.connect(transport, { timeout: options.timeoutMs });
+      const era = client.getProtocolEra();
+      const protocolVersion = client.getNegotiatedProtocolVersion();
+      if (!era || !protocolVersion) {
+        throw localMcpFailure(
+          "protocol",
+          "MCP protocol negotiation returned no version"
+        );
+      }
+      const listed = await client.listTools(void 0, {
+        timeout: options.timeoutMs,
+        cacheMode: "refresh"
+      }).catch((cause) => {
+        throw localMcpFailure("tools", "Unable to list SAG MCP tools", {
+          cause
+        });
+      });
+      const tools = listed.tools.map((tool) => tool.name);
+      const missingTools = REQUIRED_SAG_TOOLS.filter(
+        (required) => !tools.includes(required)
+      );
+      if (missingTools.length) {
+        throw localMcpFailure(
+          "tools",
+          `SAG MCP is missing required tools: ${missingTools.join(", ")}`
+        );
+      }
+      const listSources2 = await client.callTool(
+        {
+          name: "list_sources",
+          arguments: {}
+        },
+        { timeout: options.timeoutMs }
+      ).catch((cause) => {
+        throw localMcpFailure("knowledge", "Unable to call SAG MCP list_sources", {
+          cause
+        });
+      });
+      if (listSources2.isError) {
+        throw localMcpFailure("knowledge", "SAG MCP list_sources returned an error");
+      }
+      const server = client.getServerVersion();
+      return {
+        transport: "stdio",
+        era,
+        protocolVersion,
+        ...server ? { server } : {},
+        tools,
+        missingTools,
+        listSourcesCallable: true
+      };
+    } catch (cause) {
+      if (cause instanceof CliError) {
+        throw cause;
+      }
+      throw localMcpFailure("protocol", "Unable to verify SAG MCP", { cause });
+    } finally {
+      await client.close().catch(() => void 0);
+    }
+  }
+};
+
+// src/process/runner.ts
+import { spawn } from "child_process";
+var NodeProcessRunner = class {
+  async run(input) {
+    return new Promise((resolve, reject) => {
+      const child = spawn(input.command, input.args, {
+        shell: false,
+        env: input.env ?? process.env,
+        stdio: [input.stdin === "pipe" ? "pipe" : "ignore", "pipe", "pipe"]
+      });
+      const childStdout = child.stdout;
+      const childStderr = child.stderr;
+      let stdout = "";
+      let stderr = "";
+      let timedOut = false;
+      let forceKill;
+      const timeout = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+        forceKill = setTimeout(() => {
+          child.kill("SIGKILL");
+        }, 250);
+      }, input.timeoutMs);
+      childStdout?.setEncoding("utf8");
+      childStderr?.setEncoding("utf8");
+      childStdout?.on("data", (chunk) => {
+        stdout += chunk;
+      });
+      childStderr?.on("data", (chunk) => {
+        stderr += chunk;
+      });
+      child.on("error", (cause) => {
+        clearTimeout(timeout);
+        if (forceKill) clearTimeout(forceKill);
+        reject(
+          new CliError("DEPENDENCY_MISSING", `Unable to start ${input.command}`, {
+            exitCode: exitCodes.dependencyMissing,
+            cause,
+            hint: `Install ${input.command} and ensure it is available on PATH.`
+          })
+        );
+      });
+      child.on("close", (exitCode) => {
+        clearTimeout(timeout);
+        if (forceKill) clearTimeout(forceKill);
+        if (timedOut) {
+          reject(
+            new CliError("DEPENDENCY_MISSING", `${input.command} timed out`, {
+              exitCode: exitCodes.dependencyMissing,
+              hint: `Check that ${input.command} is responsive and try again.`
+            })
+          );
+          return;
+        }
+        resolve({
+          exitCode: exitCode ?? 1,
+          stdout,
+          stderr
+        });
+      });
+    });
+  }
+};
+
+// src/program.ts
+import { Command, CommanderError, Option } from "commander";
+
+// src/api/schemas.ts
+import { z as z6 } from "zod";
+var dateTime = z6.string().min(1);
+var rootSchema = z6.object({
+  name: z6.string().min(1),
+  version: z6.string().min(1),
+  docs: z6.string()
+}).passthrough();
+var readySchema = z6.object({
+  status: z6.string(),
+  db: z6.boolean()
+}).passthrough();
+var capabilitiesSchema = z6.record(z6.string(), z6.unknown());
+var userSchema = z6.object({
+  id: z6.string().min(1),
+  email: z6.string(),
+  name: z6.string(),
+  created_at: dateTime.optional()
+}).passthrough();
+var sourceSchema = z6.object({
+  id: z6.string().min(1),
+  name: z6.string(),
+  description: z6.string(),
+  source_type: z6.enum(["document", "web", "message", "audio"]),
+  connector_kind: z6.string(),
+  status: z6.enum(["active", "paused", "error"]),
+  document_count: z6.number().int().nonnegative(),
+  chunk_count: z6.number().int().nonnegative(),
+  event_count: z6.number().int().nonnegative(),
+  created_at: dateTime,
+  updated_at: dateTime
+}).passthrough();
+var documentStatusSchema = z6.enum([
+  "pending",
+  "loading",
+  "extracting",
+  "paused",
+  "ready",
+  "failed"
+]);
+var documentSchema = z6.object({
+  id: z6.string().min(1),
+  source_id: z6.string().min(1),
+  filename: z6.string(),
+  content_type: z6.string(),
+  size_bytes: z6.number().int().nonnegative(),
+  status: documentStatusSchema,
+  chunk_count: z6.number().int().nonnegative(),
+  event_count: z6.number().int().nonnegative(),
+  progress: z6.number().int().min(0).max(100),
+  token_usage: z6.number().int().nonnegative(),
+  error: z6.string().nullable(),
+  created_at: dateTime,
+  updated_at: dateTime
+}).passthrough();
+var searchSectionSchema = z6.object({
+  chunk_id: z6.string().nullable(),
+  heading: z6.string(),
+  content: z6.string(),
+  score: z6.number(),
+  rank: z6.number().int(),
+  source_id: z6.string().nullable(),
+  source_name: z6.string().nullable().optional()
+}).passthrough();
+var searchEventSchema = z6.object({
+  id: z6.string(),
+  title: z6.string(),
+  summary: z6.string(),
+  rank: z6.number().int(),
+  score: z6.number()
+}).passthrough();
+var sourceHitSchema = z6.object({
+  source_id: z6.string(),
+  source_name: z6.string().nullable().optional(),
+  event_hits: z6.number().int(),
+  max_score: z6.number(),
+  latest_event_time: z6.string().nullable().optional()
+}).passthrough();
+var searchResponseSchema = z6.object({
+  query: z6.string(),
+  sections: z6.array(searchSectionSchema),
+  events: z6.array(searchEventSchema),
+  entities: z6.array(z6.record(z6.string(), z6.unknown())),
+  relations: z6.array(z6.record(z6.string(), z6.unknown())),
+  source_hits: z6.array(sourceHitSchema),
+  summary: z6.string(),
+  exploration_id: z6.string().nullable(),
+  stats: z6.record(z6.string(), z6.unknown())
+}).passthrough();
+var mcpDescriptorSchema = z6.object({
+  name: z6.string(),
+  scope: z6.string(),
+  source_count: z6.number().int().nonnegative(),
+  tools: z6.array(z6.string()),
+  http: z6.object({
+    transport: z6.string(),
+    url: z6.string().url(),
+    headers: z6.record(z6.string(), z6.string())
+  }).passthrough()
+}).passthrough();
+
+// src/api/client.ts
+var SagClient = class {
+  #origin;
+  #token;
+  #timeoutMs;
+  #locale;
+  #fetch;
+  constructor(options) {
+    this.#origin = normalizeOrigin(options.origin);
+    this.#token = options.token;
+    this.#timeoutMs = options.timeoutMs ?? 1e4;
+    this.#locale = options.locale ?? "zh-CN";
+    this.#fetch = options.fetchImplementation ?? fetch;
+  }
+  root() {
+    return this.#request("/", rootSchema, { authenticated: false });
+  }
+  ready() {
+    return this.#request("/api/v1/system/ready", readySchema, {
+      authenticated: false
+    });
+  }
+  capabilities() {
+    return this.#request("/api/v1/system/capabilities", capabilitiesSchema, {
+      authenticated: false
+    });
+  }
+  me() {
+    return this.#request("/api/v1/auth/me", userSchema);
+  }
+  mcpDescriptor() {
+    return this.#request("/api/v1/system/mcp", mcpDescriptorSchema);
+  }
+  listSources() {
+    return this.#request("/api/v1/sources", sourceSchema.array());
+  }
+  getSource(sourceId) {
+    return this.#request(
+      `/api/v1/sources/${encodeURIComponent(sourceId)}`,
+      sourceSchema
+    );
+  }
+  listDocuments(sourceId) {
+    return this.#request(
+      `/api/v1/sources/${encodeURIComponent(sourceId)}/documents`,
+      documentSchema.array()
+    );
+  }
+  getDocument(sourceId, documentId) {
+    return this.#request(
+      `/api/v1/sources/${encodeURIComponent(sourceId)}/documents/${encodeURIComponent(documentId)}`,
+      documentSchema
+    );
+  }
+  search(input) {
+    return this.#request("/api/v1/search", searchResponseSchema, {
+      method: "POST",
+      body: input
+    });
+  }
+  async #request(path5, schema, options = {}) {
+    const authenticated = options.authenticated ?? true;
+    if (authenticated && !this.#token) {
+      throw new CliError("AUTH_REQUIRED", "No SAG token is configured", {
+        exitCode: exitCodes.authRequired,
+        hint: "Run `sag auth login` or set SAG_TOKEN."
+      });
+    }
+    const headers = new Headers({
+      Accept: "application/json",
+      "Accept-Language": this.#locale
+    });
+    if (authenticated && this.#token) {
+      headers.set("Authorization", `Bearer ${this.#token}`);
+    }
+    if (options.body !== void 0) {
+      headers.set("Content-Type", "application/json");
+    }
+    let response;
+    try {
+      response = await this.#fetch(new URL(path5, `${this.#origin}/`), {
+        method: options.method ?? "GET",
+        headers,
+        ...options.body !== void 0 ? { body: JSON.stringify(options.body) } : {},
+        signal: AbortSignal.timeout(this.#timeoutMs)
+      });
+    } catch (cause) {
+      throw new CliError("NETWORK_UNREACHABLE", `Cannot reach SAG at ${this.#origin}`, {
+        exitCode: exitCodes.networkUnreachable,
+        cause,
+        hint: "Check that SAG is running and the URL is reachable."
+      });
+    }
+    const payload = await this.#readPayload(response);
+    if (!response.ok) {
+      throw this.#httpError(response.status, payload);
+    }
+    const parsed = schema.safeParse(payload);
+    if (!parsed.success) {
+      throw new CliError("INVALID_RESPONSE", "SAG returned an incompatible response", {
+        exitCode: exitCodes.internalError,
+        cause: parsed.error,
+        hint: "Check the SAG/CLI compatibility matrix."
+      });
+    }
+    return parsed.data;
+  }
+  async #readPayload(response) {
+    try {
+      return await response.json();
+    } catch (cause) {
+      throw new CliError("INVALID_RESPONSE", "SAG returned invalid JSON", {
+        exitCode: exitCodes.internalError,
+        cause
+      });
+    }
+  }
+  #httpError(status2, payload) {
+    const serverMessage = payload && typeof payload === "object" && "error" in payload && payload.error && typeof payload.error === "object" && "message" in payload.error && typeof payload.error.message === "string" ? payload.error.message : `SAG request failed with HTTP ${status2}`;
+    if (status2 === 401) {
+      return new CliError("AUTH_REQUIRED", serverMessage, {
+        exitCode: exitCodes.authRequired,
+        hint: "Run `sag auth login` to refresh the token."
+      });
+    }
+    if (status2 === 403) {
+      return new CliError("PERMISSION_DENIED", serverMessage, {
+        exitCode: exitCodes.permissionDenied
+      });
+    }
+    if (status2 === 404) {
+      return new CliError("RESOURCE_NOT_FOUND", serverMessage, {
+        exitCode: exitCodes.resourceNotFound
+      });
+    }
+    if (status2 === 409) {
+      return new CliError("DOCUMENT_NOT_READY", serverMessage, {
+        exitCode: exitCodes.documentNotReady
+      });
+    }
+    if (status2 >= 500) {
+      return new CliError("SERVICE_NOT_READY", serverMessage, {
+        exitCode: exitCodes.serviceNotReady
+      });
+    }
+    return new CliError("INVALID_RESPONSE", serverMessage, {
+      exitCode: exitCodes.internalError
+    });
+  }
+};
+
+// src/agents/orchestrator.ts
+var SERVER_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/u;
+function validateServerName(serverName) {
+  if (!SERVER_NAME_PATTERN.test(serverName)) {
+    throw new CliError("INVALID_ARGUMENT", "Invalid MCP server name", {
+      exitCode: exitCodes.invalidArgument,
+      hint: "Use 1-64 letters, numbers, dots, underscores, or dashes."
+    });
+  }
+}
+function conflict(message) {
+  return new CliError("CONFIG_CONFLICT", message, {
+    exitCode: exitCodes.configConflict,
+    hint: "Choose another `--name` or restore the SAG CLI managed entry."
+  });
+}
+function hostFailure3(message, cause, hint) {
+  return new CliError("HOST_CONFIG_FAILED", message, {
+    exitCode: exitCodes.hostConfigFailed,
+    ...cause ? { cause } : {},
+    hint: hint ?? "Inspect the Agent MCP configuration and run the command again."
+  });
+}
+function determinePlan(input) {
+  let action;
+  if (!input.hostFingerprint || !input.hostSpecFingerprint) {
+    if (input.managed) {
+      throw conflict("Managed state exists but the Agent MCP entry is missing");
+    }
+    action = "create";
+  } else if (!input.managed) {
+    throw conflict("The Agent MCP name is already owned by the user");
+  } else if (input.managed.fingerprint !== input.hostFingerprint) {
+    throw conflict("The managed Agent MCP entry was changed outside SAG CLI");
+  } else if (input.hostSpecFingerprint === input.desiredFingerprint) {
+    action = "unchanged";
+  } else {
+    action = "update";
+  }
+  return {
+    action,
+    agent: input.agent,
+    serverName: input.serverName,
+    scope: input.scope,
+    provider: "docker-stdio",
+    target: input.target.name,
+    sourceId: input.sourceId ?? null,
+    ...input.hostSpecFingerprint ? { currentFingerprint: input.hostSpecFingerprint } : {},
+    desiredFingerprint: input.desiredFingerprint
+  };
+}
+function managedConnection(input, resolved, fingerprint, existing) {
+  return {
+    agent: input.agent,
+    provider: "docker-stdio",
+    profile: input.profile,
+    serverName: input.serverName,
+    docker: {
+      ...resolved.target.composeProject ? { composeProject: resolved.target.composeProject } : {},
+      ...resolved.target.composeService ? { composeService: resolved.target.composeService } : {},
+      containerName: resolved.target.name
+    },
+    sourceId: input.sourceId ?? null,
+    scope: input.scope,
+    fingerprint,
+    createdAt: existing?.createdAt ?? input.now().toISOString()
+  };
+}
+async function rollbackHost(input) {
+  if (input.previousSpec) {
+    try {
+      await input.adapter.remove(input.serverName, input.scope);
+    } catch {
+    }
+    await input.adapter.add(input.serverName, input.scope, input.previousSpec);
+    const restored = await input.adapter.read(input.serverName, input.scope);
+    if (!restored || restored.fingerprint !== (input.previousFingerprint ?? fingerprintConnection(input.previousSpec))) {
+      throw new Error("Previous Agent MCP entry was not restored");
+    }
+    return;
+  }
+  await input.adapter.remove(input.serverName, input.scope);
+}
+async function connectAgent(input) {
+  validateServerName(input.serverName);
+  const resolved = await input.resolveConnection();
+  await input.verifier.verify(resolved.spec, { timeoutMs: input.timeoutMs });
+  await input.adapter.detect();
+  const host = await input.adapter.read(input.serverName, input.scope);
+  const key = connectionKey(input.agent, input.scope, input.serverName);
+  const managed = await input.state.get(key);
+  const desiredFingerprint = fingerprintConnection(resolved.spec);
+  const plan = determinePlan({
+    agent: input.agent,
+    serverName: input.serverName,
+    scope: input.scope,
+    target: resolved.target,
+    ...input.sourceId ? { sourceId: input.sourceId } : {},
+    desiredFingerprint,
+    ...host ? { hostFingerprint: host.fingerprint } : {},
+    ...host ? { hostSpecFingerprint: fingerprintConnection(host.spec) } : {},
+    managed
+  });
+  if (plan.action === "unchanged") {
+    return {
+      agent: input.agent,
+      serverName: input.serverName,
+      scope: input.scope,
+      action: "unchanged",
+      changed: false,
+      verified: true,
+      dryRun: false,
+      plan
+    };
+  }
+  if (input.dryRun) {
+    return {
+      agent: input.agent,
+      serverName: input.serverName,
+      scope: input.scope,
+      action: plan.action,
+      changed: false,
+      verified: true,
+      dryRun: true,
+      plan
+    };
+  }
+  if (!input.yes && !await input.confirm(
+    `${plan.action === "create" ? "Add" : "Update"} ${input.serverName} in ${input.agent}?`
+  )) {
+    return {
+      agent: input.agent,
+      serverName: input.serverName,
+      scope: input.scope,
+      action: "cancelled",
+      changed: false,
+      verified: true,
+      dryRun: false,
+      plan
+    };
+  }
+  try {
+    if (plan.action === "update") {
+      await input.adapter.remove(input.serverName, input.scope);
+    }
+    await input.adapter.add(input.serverName, input.scope, resolved.spec);
+    const readBack = await input.adapter.read(input.serverName, input.scope);
+    if (!readBack || fingerprintConnection(readBack.spec) !== desiredFingerprint) {
+      throw hostFailure3("Agent MCP read-back did not match the requested connection");
+    }
+    await input.verifier.verify(readBack.spec, { timeoutMs: input.timeoutMs });
+    await input.state.set(
+      managedConnection(input, resolved, readBack.fingerprint, managed)
+    );
+  } catch (cause) {
+    try {
+      await rollbackHost({
+        adapter: input.adapter,
+        serverName: input.serverName,
+        scope: input.scope,
+        ...host ? { previousSpec: host.spec } : {},
+        ...host ? { previousFingerprint: host.fingerprint } : {}
+      });
+    } catch {
+      throw hostFailure3(
+        "Agent MCP configuration failed and rollback also failed",
+        cause,
+        `Inspect the ${input.agent} MCP entry \`${input.serverName}\` before retrying.`
+      );
+    }
+    throw hostFailure3(
+      "Agent MCP configuration failed; changes were rolled back",
+      cause
+    );
+  }
+  return {
+    agent: input.agent,
+    serverName: input.serverName,
+    scope: input.scope,
+    action: plan.action,
+    changed: true,
+    verified: true,
+    dryRun: false,
+    plan
+  };
+}
+async function disconnectAgent(input) {
+  validateServerName(input.serverName);
+  await input.adapter.detect();
+  const key = connectionKey(input.agent, input.scope, input.serverName);
+  const managed = await input.state.get(key);
+  if (!managed) {
+    throw conflict("The Agent MCP entry is not managed by SAG CLI");
+  }
+  const host = await input.adapter.read(input.serverName, input.scope);
+  if (!host) {
+    throw conflict("Managed state exists but the Agent MCP entry is missing");
+  }
+  if (host.fingerprint !== managed.fingerprint) {
+    throw conflict("The managed Agent MCP entry was changed outside SAG CLI");
+  }
+  const plan = {
+    action: "unchanged",
+    agent: input.agent,
+    serverName: input.serverName,
+    scope: input.scope,
+    provider: "docker-stdio",
+    target: managed.docker.containerName,
+    sourceId: managed.sourceId,
+    currentFingerprint: host.fingerprint,
+    desiredFingerprint: host.fingerprint
+  };
+  if (!input.yes && !await input.confirm(`Remove ${input.serverName} from ${input.agent}?`)) {
+    return {
+      agent: input.agent,
+      serverName: input.serverName,
+      scope: input.scope,
+      action: "cancelled",
+      changed: false,
+      verified: true,
+      dryRun: false,
+      plan
+    };
+  }
+  await input.adapter.remove(input.serverName, input.scope);
+  try {
+    await input.state.delete(key);
+  } catch (cause) {
+    try {
+      await input.adapter.add(input.serverName, input.scope, host.spec);
+    } catch {
+      throw hostFailure3(
+        "Managed state cleanup failed and the Agent entry could not be restored",
+        cause
+      );
+    }
+    throw hostFailure3(
+      "Managed state cleanup failed; the Agent entry was restored",
+      cause
+    );
+  }
+  return {
+    agent: input.agent,
+    serverName: input.serverName,
+    scope: input.scope,
+    action: "disconnect",
+    changed: true,
+    verified: true,
+    dryRun: false,
+    plan
+  };
+}
+
+// src/mcp/docker-stdio-provider.ts
+var SOURCE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u;
+var DockerStdioProvider = class {
+  id = "docker-stdio";
+  async inspect(input) {
+    return {
+      provider: this.id,
+      ready: true,
+      target: input.target.name
+    };
+  }
+  async createSpec(input) {
+    if (input.sourceId && !SOURCE_ID_PATTERN.test(input.sourceId)) {
+      throw new CliError("INVALID_ARGUMENT", "Invalid SAG source id", {
+        exitCode: exitCodes.invalidArgument,
+        hint: "Use 1-128 letters, numbers, underscores, or dashes."
+      });
+    }
+    const sourceArguments = input.sourceId ? ["-e", `SAG_MCP_SOURCE_ID=${input.sourceId}`] : [];
+    return {
+      transport: "stdio",
+      command: "docker",
+      args: [
+        "exec",
+        "-i",
+        ...sourceArguments,
+        input.target.name,
+        "python",
+        "-m",
+        "sag_api.mcp.server"
+      ],
+      env: {}
+    };
+  }
+};
+
+// src/docker/discovery.ts
+var CONTAINER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/u;
+function validateContainer(value) {
+  if (!CONTAINER_PATTERN.test(value)) {
+    throw new CliError("INVALID_ARGUMENT", "Invalid Docker container name or id", {
+      exitCode: exitCodes.invalidArgument,
+      hint: "Use 1-128 letters, numbers, dots, underscores, or dashes."
+    });
+  }
+}
+function toTarget(inspection) {
+  const composeProject = inspection.labels["com.docker.compose.project"] || void 0;
+  const composeService = inspection.labels["com.docker.compose.service"] || void 0;
+  return {
+    id: inspection.id,
+    name: inspection.name,
+    ...composeProject ? { composeProject } : {},
+    ...composeService ? { composeService } : {},
+    health: inspection.health
+  };
+}
+async function validateTarget(docker, container) {
+  const inspection = await docker.inspect(container);
+  if (!inspection.running || inspection.health === "unhealthy" || inspection.health === "starting") {
+    throw new CliError("SERVICE_NOT_READY", "SAG API container is not ready", {
+      exitCode: exitCodes.serviceNotReady,
+      hint: "Check the SAG API container health and logs."
+    });
+  }
+  if (!await docker.canImportMcp(inspection.name)) {
+    throw localMcpFailure(
+      "entrypoint",
+      "SAG API container does not provide the stdio MCP entrypoint",
+      {
+        hint: "Use a compatible SAG image that includes sag_api.mcp.server."
+      }
+    );
+  }
+  return toTarget(inspection);
+}
+async function discoverSagContainer(input) {
+  await input.docker.version();
+  if (input.container) {
+    validateContainer(input.container);
+    return validateTarget(input.docker, input.container);
+  }
+  const containers = await input.docker.listRunningContainers();
+  const apiCandidates = containers.filter(
+    (container) => container.labels["com.docker.compose.service"] === "api"
+  );
+  if (!apiCandidates.length) {
+    throw new CliError("RESOURCE_NOT_FOUND", "No SAG API container was found", {
+      exitCode: exitCodes.resourceNotFound,
+      hint: "Start SAG Docker or pass `--container <name-or-id>`."
+    });
+  }
+  const targets = [];
+  let firstFailure;
+  let preferredFailure;
+  for (const candidate of apiCandidates) {
+    try {
+      targets.push(await validateTarget(input.docker, candidate.id));
+    } catch (error) {
+      firstFailure ??= error;
+      if (candidate.labels["com.docker.compose.project"] === "sag") {
+        preferredFailure ??= error;
+      }
+    }
+  }
+  if (!targets.length) {
+    throw preferredFailure ?? firstFailure;
+  }
+  const preferredTargets = targets.filter((target) => target.composeProject === "sag");
+  const rankedTargets = preferredTargets.length ? preferredTargets : targets;
+  if (rankedTargets.length === 1) {
+    return rankedTargets[0];
+  }
+  if (!input.interactive || !input.select) {
+    throw new CliError("CONFIG_CONFLICT", "Multiple SAG API containers were found", {
+      exitCode: exitCodes.configConflict,
+      hint: "Pass `--container <name-or-id>` to select one."
+    });
+  }
+  const selectedId = await input.select(rankedTargets);
+  const selected = rankedTargets.find(
+    (target) => target.id === selectedId || target.name === selectedId
+  );
+  if (!selected) {
+    throw new CliError("INVALID_ARGUMENT", "Invalid Docker container selection", {
+      exitCode: exitCodes.invalidArgument
+    });
+  }
+  return selected;
+}
+
+// src/commands/agent.ts
+async function connectLocalAgent(runtime2, input) {
+  return connectAgent({
+    agent: input.agent,
+    serverName: input.serverName,
+    scope: "user",
+    profile: input.profile,
+    ...input.sourceId ? { sourceId: input.sourceId } : {},
+    timeoutMs: input.timeoutMs,
+    dryRun: input.dryRun,
+    yes: input.yes,
+    resolveConnection: async () => {
+      const target = await discoverSagContainer({
+        docker: runtime2.docker,
+        ...input.container ? { container: input.container } : {},
+        interactive: runtime2.interactive,
+        select: runtime2.selectContainer
+      });
+      const spec = await new DockerStdioProvider().createSpec({
+        target,
+        ...input.sourceId ? { sourceId: input.sourceId } : {}
+      });
+      return { target, spec };
+    },
+    verifier: runtime2.verifier,
+    adapter: runtime2.adapters[input.agent],
+    state: runtime2.state,
+    confirm: input.confirm,
+    now: input.now
+  });
+}
+async function agentStatus(runtime2, agent, serverName) {
+  const adapter = runtime2.adapters[agent];
+  let version;
+  try {
+    version = (await adapter.detect()).version;
+  } catch {
+    return {
+      agent,
+      installed: false,
+      serverName,
+      status: "unavailable",
+      managed: false,
+      verified: false
+    };
+  }
+  const key = connectionKey(agent, "user", serverName);
+  const [managed, host] = await Promise.all([
+    runtime2.state.get(key),
+    adapter.read(serverName, "user")
+  ]);
+  if (!host) {
+    return {
+      agent,
+      installed: true,
+      version,
+      serverName,
+      status: managed ? "drifted" : "disconnected",
+      managed: Boolean(managed),
+      verified: false
+    };
+  }
+  if (!managed) {
+    return {
+      agent,
+      installed: true,
+      version,
+      serverName,
+      status: "unmanaged",
+      managed: false,
+      verified: false
+    };
+  }
+  if (host.fingerprint !== managed.fingerprint) {
+    return {
+      agent,
+      installed: true,
+      version,
+      serverName,
+      status: "drifted",
+      managed: true,
+      verified: false
+    };
+  }
+  try {
+    await runtime2.verifier.verify(host.spec, { timeoutMs: 15e3 });
+    return {
+      agent,
+      installed: true,
+      version,
+      serverName,
+      status: "connected",
+      managed: true,
+      verified: true
+    };
+  } catch {
+    return {
+      agent,
+      installed: true,
+      version,
+      serverName,
+      status: "unavailable",
+      managed: true,
+      verified: false
+    };
+  }
+}
+async function statusLocalAgents(runtime2, input) {
+  const agents = input.agent ? [input.agent] : ["codex", "claude-code"];
+  return Promise.all(
+    agents.map((agent) => agentStatus(runtime2, agent, input.serverName))
+  );
+}
+async function listAgentHosts(runtime2) {
+  return Promise.all(
+    ["codex", "claude-code"].map(async (agent) => {
+      const managedConnections = (await runtime2.state.list({ agent })).length;
+      try {
+        const installation = await runtime2.adapters[agent].detect();
+        return {
+          agent,
+          installed: true,
+          version: installation.version,
+          managedConnections
+        };
+      } catch {
+        return { agent, installed: false, managedConnections };
+      }
+    })
+  );
+}
+async function disconnectLocalAgent(runtime2, input) {
+  return disconnectAgent({
+    agent: input.agent,
+    serverName: input.serverName,
+    scope: "user",
+    adapter: runtime2.adapters[input.agent],
+    state: runtime2.state,
+    yes: input.yes,
+    confirm: input.confirm
+  });
+}
+
+// src/commands/auth.ts
+async function login(input) {
+  const token = input.environmentToken?.trim() || await input.promptToken();
+  if (!token.trim()) {
+    throw new CliError("AUTH_REQUIRED", "A SAG token is required", {
+      exitCode: exitCodes.authRequired,
+      hint: "Paste a token when prompted or set SAG_TOKEN."
+    });
+  }
+  const user = await input.validate(token);
+  await input.store.set(input.credentialRef, token);
+  return {
+    authenticated: true,
+    credentialRef: input.credentialRef,
+    credentialStore: input.store.kind,
+    user
+  };
+}
+async function status(input) {
+  const token = input.environmentToken?.trim() || await input.store.get(input.credentialRef);
+  if (!token) {
+    return {
+      authenticated: false,
+      credentialRef: input.credentialRef,
+      credentialStore: input.store.kind
+    };
+  }
+  const user = await input.validate(token);
+  return {
+    authenticated: true,
+    credentialRef: input.credentialRef,
+    credentialStore: input.store.kind,
+    user
+  };
+}
+async function logout(input) {
+  await input.store.delete(input.credentialRef);
+  return {
+    authenticated: false,
+    credentialRef: input.credentialRef
+  };
+}
+
+// src/commands/document.ts
+function requiredIdentifier(value, label) {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new CliError("INVALID_ARGUMENT", `${label} is required`, {
+      exitCode: exitCodes.invalidArgument
+    });
+  }
+  return normalized;
+}
+function summarizeDocuments(documents) {
+  const statuses = {
+    pending: 0,
+    loading: 0,
+    extracting: 0,
+    paused: 0,
+    ready: 0,
+    failed: 0
+  };
+  for (const document of documents) {
+    statuses[document.status] += 1;
+  }
+  return {
+    total: documents.length,
+    statuses,
+    searchable: documents.length > 0 && statuses.ready === documents.length
+  };
+}
+async function listDocuments(client, sourceId) {
+  return client.listDocuments(requiredIdentifier(sourceId, "Source ID"));
+}
+async function getDocument(client, sourceId, documentId) {
+  return client.getDocument(
+    requiredIdentifier(sourceId, "Source ID"),
+    requiredIdentifier(documentId, "Document ID")
+  );
+}
+async function documentStatus(client, sourceId, documentId) {
+  const normalizedSourceId = requiredIdentifier(sourceId, "Source ID");
+  if (documentId !== void 0) {
+    const document = await getDocument(client, normalizedSourceId, documentId);
+    return {
+      mode: "document",
+      document,
+      searchable: document.status === "ready"
+    };
+  }
+  const summary = summarizeDocuments(await client.listDocuments(normalizedSourceId));
+  return {
+    mode: "source",
+    sourceId: normalizedSourceId,
+    total: summary.total,
+    statuses: summary.statuses,
+    searchable: summary.searchable
+  };
+}
+
+// src/commands/mcp.ts
+async function testLocalMcp(runtime2, input) {
+  const container = await discoverSagContainer({
+    docker: runtime2.docker,
+    ...input.container ? { container: input.container } : {},
+    interactive: runtime2.interactive,
+    select: runtime2.selectContainer
+  });
+  const spec = await new DockerStdioProvider().createSpec({
+    target: container,
+    ...input.sourceId ? { sourceId: input.sourceId } : {}
+  });
+  const verification = await runtime2.verifier.verify(spec, {
+    timeoutMs: input.timeoutMs
+  });
+  return {
+    provider: "docker-stdio",
+    container,
+    sourceId: input.sourceId ?? null,
+    ...verification
+  };
+}
+function skipped(name, detail) {
+  return {
+    name,
+    status: "warn",
+    code: "CHECK_SKIPPED",
+    detail
+  };
+}
+async function localMcpDoctorChecks(runtime2, input) {
+  try {
+    const report = await testLocalMcp(runtime2, input);
+    return [
+      {
+        name: "docker",
+        status: "pass",
+        code: "DOCKER_READY",
+        detail: "Docker daemon is available"
+      },
+      {
+        name: "sagContainer",
+        status: "pass",
+        code: "SAG_CONTAINER_READY",
+        detail: `${report.container.name} is ${report.container.health}`
+      },
+      {
+        name: "mcpEntrypoint",
+        status: "pass",
+        code: "MCP_ENTRYPOINT_READY",
+        detail: "sag_api.mcp.server is importable"
+      },
+      {
+        name: "mcpProtocol",
+        status: "pass",
+        code: "MCP_PROTOCOL_READY",
+        detail: `${report.protocolVersion} ${report.era}`
+      },
+      {
+        name: "mcpTools",
+        status: "pass",
+        code: "MCP_TOOLS_READY",
+        detail: `${report.tools.length} tools`
+      },
+      {
+        name: "mcpKnowledge",
+        status: "pass",
+        code: "MCP_KNOWLEDGE_READY",
+        detail: "list_sources callable"
+      }
+    ];
+  } catch (error) {
+    const cliError = toCliError(error);
+    const mcpStage = localMcpFailureStage(cliError);
+    const failedName = cliError.code === "DEPENDENCY_MISSING" ? "docker" : cliError.code === "RESOURCE_NOT_FOUND" || cliError.code === "SERVICE_NOT_READY" ? "sagContainer" : mcpStage === "entrypoint" ? "mcpEntrypoint" : mcpStage === "tools" ? "mcpTools" : mcpStage === "knowledge" ? "mcpKnowledge" : "mcpProtocol";
+    const names = [
+      "docker",
+      "sagContainer",
+      "mcpEntrypoint",
+      "mcpProtocol",
+      "mcpTools",
+      "mcpKnowledge"
+    ];
+    const failedIndex = names.indexOf(failedName);
+    return names.map((name, index) => {
+      if (index < failedIndex) {
+        return {
+          name,
+          status: "pass",
+          code: "CHECK_COMPLETED",
+          detail: "Prerequisite check passed"
+        };
+      }
+      if (index === failedIndex) {
+        return {
+          name,
+          status: "fail",
+          code: cliError.code,
+          detail: cliError.message,
+          ...cliError.hint ? { hint: cliError.hint } : {}
+        };
+      }
+      return skipped(name, `Skipped because ${failedName} failed`);
+    });
+  }
+}
+
+// src/commands/search.ts
+function invalid(message) {
+  throw new CliError("INVALID_ARGUMENT", message, {
+    exitCode: exitCodes.invalidArgument
+  });
+}
+async function searchKnowledge(client, query, options = {}) {
+  const normalizedQuery = query.trim();
+  if (!normalizedQuery) {
+    invalid("Query is required");
+  }
+  if (normalizedQuery.length > 4e3) {
+    invalid("Query must not exceed 4000 characters");
+  }
+  if (options.topK !== void 0 && (!Number.isInteger(options.topK) || options.topK < 1 || options.topK > 50)) {
+    invalid("top-k must be between 1 and 50");
+  }
+  if (options.strategy !== void 0 && !["vector", "multi"].includes(options.strategy)) {
+    invalid("strategy must be vector or multi");
+  }
+  const sourceIds = [
+    ...new Set(
+      (options.sourceIds ?? []).map((sourceId) => sourceId.trim()).filter(Boolean)
+    )
+  ];
+  return client.search({
+    query: normalizedQuery,
+    ...sourceIds.length ? { source_ids: sourceIds } : {},
+    ...options.topK !== void 0 ? { top_k: options.topK } : {},
+    ...options.strategy !== void 0 ? { strategy: options.strategy } : {},
+    save_exploration: false
+  });
+}
+
+// src/commands/source.ts
+function requiredSourceId(sourceId) {
+  const normalized = sourceId.trim();
+  if (!normalized) {
+    throw new CliError("INVALID_ARGUMENT", "Source ID is required", {
+      exitCode: exitCodes.invalidArgument
+    });
+  }
+  return normalized;
+}
+function listSources(client) {
+  return client.listSources();
+}
+async function getSource(client, sourceId) {
+  return client.getSource(requiredSourceId(sourceId));
+}
+async function sourceStatus(client, sourceId) {
+  if (sourceId === void 0) {
+    const sources = await client.listSources();
+    const documentSummaries = await Promise.all(
+      sources.map(
+        async (source2) => summarizeDocuments(await client.listDocuments(source2.id))
+      )
+    );
+    return {
+      total: sources.length,
+      statuses: {
+        active: sources.filter(({ status: status2 }) => status2 === "active").length,
+        paused: sources.filter(({ status: status2 }) => status2 === "paused").length,
+        error: sources.filter(({ status: status2 }) => status2 === "error").length
+      },
+      documents: {
+        total: documentSummaries.reduce((total, summary2) => total + summary2.total, 0),
+        ready: documentSummaries.reduce(
+          (total, summary2) => total + summary2.statuses.ready,
+          0
+        ),
+        pending: documentSummaries.reduce(
+          (total, summary2) => total + summary2.statuses.pending,
+          0
+        ),
+        loading: documentSummaries.reduce(
+          (total, summary2) => total + summary2.statuses.loading,
+          0
+        ),
+        extracting: documentSummaries.reduce(
+          (total, summary2) => total + summary2.statuses.extracting,
+          0
+        ),
+        paused: documentSummaries.reduce(
+          (total, summary2) => total + summary2.statuses.paused,
+          0
+        ),
+        failed: documentSummaries.reduce(
+          (total, summary2) => total + summary2.statuses.failed,
+          0
+        )
+      },
+      searchableSources: documentSummaries.filter(({ searchable }) => searchable).length
+    };
+  }
+  const normalizedSourceId = requiredSourceId(sourceId);
+  const [source, documents] = await Promise.all([
+    client.getSource(normalizedSourceId),
+    client.listDocuments(normalizedSourceId)
+  ]);
+  const summary = summarizeDocuments(documents);
+  return {
+    source,
+    documents: {
+      total: summary.total,
+      ready: summary.statuses.ready,
+      pending: summary.statuses.pending,
+      loading: summary.statuses.loading,
+      extracting: summary.statuses.extracting,
+      paused: summary.statuses.paused,
+      failed: summary.statuses.failed,
+      searchable: summary.searchable
+    }
+  };
+}
+
+// src/core/context.ts
+import { createHash as createHash2 } from "crypto";
+function directCredentialRef(url) {
+  const fingerprint = createHash2("sha256").update(url).digest("hex").slice(0, 16);
+  return `sag-cli/direct-${fingerprint}`;
+}
+async function createRuntimeContext(input) {
+  const config = await input.configStore.load();
+  const connection = resolveConnection(input.options, input.environment, config);
+  const credentialRef = connection.credentialRef ?? directCredentialRef(connection.url);
+  const token = connection.environmentToken ?? await input.credentialStore.get(credentialRef) ?? void 0;
+  return {
+    connection,
+    credentialRef,
+    ...token ? { token } : {},
+    client: input.createClient({
+      origin: connection.url,
+      ...token ? { token } : {}
+    })
+  };
+}
+
+// src/core/result.ts
+var OUTPUT_SCHEMA = "sag.cli.v1";
+function success(data) {
+  return {
+    schema: OUTPUT_SCHEMA,
+    ok: true,
+    data
+  };
+}
+function failure(error) {
+  return {
+    schema: OUTPUT_SCHEMA,
+    ok: false,
+    error: error.toShape()
+  };
+}
+
+// src/diagnostics/doctor.ts
+function emptyDocumentStatuses() {
+  return {
+    pending: 0,
+    loading: 0,
+    extracting: 0,
+    paused: 0,
+    ready: 0,
+    failed: 0
+  };
+}
+function errorCheck(name, error, fallbackHint) {
+  const cliError = toCliError(error);
+  const hint = cliError.hint ?? fallbackHint;
+  return {
+    name,
+    status: "fail",
+    code: cliError.code,
+    detail: cliError.message,
+    ...hint ? { hint } : {}
+  };
+}
+function skippedCheck(name, reason) {
+  return {
+    name,
+    status: "warn",
+    code: "CHECK_SKIPPED",
+    detail: reason
+  };
+}
+function overallStatus(checks) {
+  if (checks.some((check) => check.status === "fail")) {
+    return "fail";
+  }
+  if (checks.some((check) => check.status === "warn")) {
+    return "warn";
+  }
+  return "pass";
+}
+function sagVersionCheck(name, version) {
+  const match = /^(\d+)\.(\d+)(?:\.|$)/u.exec(version);
+  if (!match) {
+    return {
+      name: "service",
+      status: "warn",
+      code: "SAG_VERSION_UNVERIFIED",
+      detail: `${name} ${version}`,
+      hint: "This SAG version could not be checked against >=1.4.0 <2.0.0."
+    };
+  }
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  if (major !== 1 || minor < 4) {
+    return {
+      name: "service",
+      status: "fail",
+      code: "SAG_VERSION_INCOMPATIBLE",
+      detail: `${name} ${version} is outside the supported range >=1.4.0 <2.0.0`,
+      hint: "Use a compatible SAG version or upgrade SAG CLI."
+    };
+  }
+  return {
+    name: "service",
+    status: "pass",
+    code: "SAG_REACHABLE",
+    detail: `${name} ${version}`
+  };
+}
+function documentDetail(total, statuses) {
+  const displayOrder = [
+    "ready",
+    "pending",
+    "loading",
+    "extracting",
+    "paused",
+    "failed"
+  ];
+  const parts = displayOrder.filter((status2) => statuses[status2] > 0).map((status2) => `${statuses[status2]} ${status2}`);
+  return `${total} ${total === 1 ? "document" : "documents"}${parts.length ? `: ${parts.join(", ")}` : ""}`;
+}
+async function runDoctor(client, input, localMcpChecks) {
+  const checks = [];
+  let sagVersion;
+  let authenticated = false;
+  let sources;
+  const documentStatuses = emptyDocumentStatuses();
+  let documentCount = 0;
+  let mcpTools = 0;
+  try {
+    const root = await client.root();
+    sagVersion = root.version;
+    checks.push(sagVersionCheck(root.name, root.version));
+  } catch (error) {
+    checks.push(errorCheck("service", error));
+  }
+  try {
+    const ready = await client.ready();
+    if (!ready.db || ready.status !== "ready") {
+      checks.push({
+        name: "readiness",
+        status: "fail",
+        code: "SERVICE_NOT_READY",
+        detail: "SAG database is not ready",
+        hint: "Check SAG API and database logs."
+      });
+    } else {
+      checks.push({
+        name: "readiness",
+        status: "pass",
+        code: "SAG_READY",
+        detail: "Database is ready"
+      });
+    }
+  } catch (error) {
+    checks.push(errorCheck("readiness", error));
+  }
+  try {
+    const user = await client.me();
+    authenticated = true;
+    checks.push({
+      name: "authentication",
+      status: "pass",
+      code: "AUTH_VALID",
+      detail: `${user.name} <${user.email}>`
+    });
+  } catch (error) {
+    checks.push(
+      errorCheck("authentication", error, "Run `sag auth login` or set SAG_TOKEN.")
+    );
+  }
+  if (!authenticated) {
+    const reason = "Skipped because authentication failed";
+    checks.push(skippedCheck("sources", reason));
+    checks.push(skippedCheck("documents", reason));
+    checks.push(skippedCheck("mcp", reason));
+  } else {
+    try {
+      sources = await client.listSources();
+      checks.push({
+        name: "sources",
+        status: sources.length ? "pass" : "warn",
+        code: sources.length ? "SOURCES_AVAILABLE" : "NO_SOURCES",
+        detail: `${sources.length} ${sources.length === 1 ? "source" : "sources"}`,
+        ...!sources.length ? { hint: "Create and populate a knowledge source in SAG." } : {}
+      });
+    } catch (error) {
+      checks.push(errorCheck("sources", error));
+    }
+    if (!sources) {
+      checks.push(
+        skippedCheck("documents", "Skipped because sources could not be listed")
+      );
+    } else {
+      try {
+        const documents = (await Promise.all(sources.map((source) => client.listDocuments(source.id)))).flat();
+        documentCount = documents.length;
+        for (const document of documents) {
+          documentStatuses[document.status] += 1;
+        }
+        const hasUnready = documentStatuses.pending + documentStatuses.loading + documentStatuses.extracting + documentStatuses.paused + documentStatuses.failed > 0;
+        checks.push({
+          name: "documents",
+          status: hasUnready || !documents.length ? "warn" : "pass",
+          code: !documents.length ? "NO_DOCUMENTS" : hasUnready ? "DOCUMENTS_PROCESSING" : "DOCUMENTS_READY",
+          detail: documentDetail(documentCount, documentStatuses),
+          ...hasUnready ? {
+            hint: `Run \`sag document status --source ${sources[0]?.id ?? "<source-id>"}\` for details.`
+          } : {}
+        });
+      } catch (error) {
+        checks.push(errorCheck("documents", error));
+      }
+    }
+    try {
+      const descriptor = await client.mcpDescriptor();
+      mcpTools = descriptor.tools.length;
+      checks.push({
+        name: "mcp",
+        status: "pass",
+        code: "MCP_DESCRIPTOR_READY",
+        detail: `${mcpTools} tools via ${descriptor.http.transport}`
+      });
+    } catch (error) {
+      checks.push(errorCheck("mcp", error));
+    }
+  }
+  if (localMcpChecks) {
+    try {
+      checks.push(...await localMcpChecks());
+    } catch (error) {
+      checks.push(errorCheck("docker", error));
+    }
+  }
+  return {
+    status: overallStatus(checks),
+    url: input.url,
+    ...input.profileName ? { profileName: input.profileName } : {},
+    ...sagVersion ? { sagVersion } : {},
+    checks,
+    summary: {
+      sources: sources?.length ?? 0,
+      documents: documentCount,
+      documentStatuses,
+      mcpTools
+    }
+  };
+}
+
+// src/output/human.ts
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function renderRows(rows) {
+  if (!rows.length) return "No results.\n";
+  const preferredColumns = [
+    "current",
+    "agent",
+    "installed",
+    "version",
+    "serverName",
+    "managed",
+    "verified",
+    "managedConnections",
+    "id",
+    "name",
+    "filename",
+    "status",
+    "url",
+    "document_count",
+    "chunk_count",
+    "progress"
+  ];
+  const available = new Set(rows.flatMap((row) => Object.keys(row)));
+  const columns = preferredColumns.filter((column) => available.has(column));
+  const selected = columns.length ? columns : Object.keys(rows[0] ?? {});
+  const widths = selected.map(
+    (column) => Math.max(column.length, ...rows.map((row) => String(row[column] ?? "").length))
+  );
+  const line = (values) => values.map((value, index) => String(value ?? "").padEnd(widths[index] ?? 0)).join("  ").trimEnd();
+  return `${[
+    line(selected),
+    line(widths.map((width) => "-".repeat(width))),
+    ...rows.map((row) => line(selected.map((column) => row[column])))
+  ].join("\n")}
+`;
+}
+function renderDoctor(report) {
+  const lines = [
+    `SAG doctor: ${report.status.toUpperCase()}`,
+    `URL: ${report.url}`,
+    ...report.checks.map(
+      (check) => `${check.status === "pass" ? "\u2713" : check.status === "warn" ? "!" : "\u2717"} ${check.name}: ${check.detail}${check.hint ? ` \u2014 ${check.hint}` : ""}`
+    )
+  ];
+  return `${lines.join("\n")}
+`;
+}
+function renderSearch(value) {
+  const summary = typeof value.summary === "string" ? value.summary : "";
+  const sections = Array.isArray(value.sections) ? value.sections.filter(isRecord) : [];
+  const lines = [
+    summary,
+    ...sections.map((section) => {
+      const source = section.source_name || section.source_id || "Unknown source";
+      const heading = section.heading || "Result";
+      const content = section.content || "";
+      return `[${source}] ${heading}
+${content}`;
+    })
+  ].filter(Boolean);
+  return `${lines.join("\n\n")}
+`;
+}
+function renderLocalMcp(value) {
+  const container = isRecord(value.container) ? value.container : {};
+  const tools = Array.isArray(value.tools) ? value.tools : [];
+  return `${[
+    "SAG MCP: PASS",
+    `Container: ${String(container.name ?? "unknown")}`,
+    `Health: ${String(container.health ?? "unknown")}`,
+    `Protocol: ${String(value.protocolVersion ?? "unknown")} (${String(value.era ?? "unknown")})`,
+    `Tools: ${tools.length}`,
+    `Knowledge: ${value.listSourcesCallable ? "list_sources callable" : "unavailable"}`
+  ].join("\n")}
+`;
+}
+function renderHuman(value, quiet = false) {
+  if (quiet) {
+    if (Array.isArray(value)) {
+      return `${value.map(
+        (item) => isRecord(item) ? item.id ?? item.name ?? JSON.stringify(item) : item
+      ).join("\n")}
+`;
+    }
+    if (isRecord(value) && typeof value.summary === "string") {
+      return `${value.summary}
+`;
+    }
+  }
+  if (Array.isArray(value) && value.every(isRecord)) {
+    return renderRows(value);
+  }
+  if (isRecord(value) && Array.isArray(value.checks) && "summary" in value) {
+    return renderDoctor(value);
+  }
+  if (isRecord(value) && Array.isArray(value.sections) && "query" in value) {
+    return renderSearch(value);
+  }
+  if (isRecord(value) && value.provider === "docker-stdio" && "protocolVersion" in value && "container" in value) {
+    return renderLocalMcp(value);
+  }
+  if (typeof value === "string") {
+    return `${value}
+`;
+  }
+  return `${JSON.stringify(value, null, 2)}
+`;
+}
+
+// src/output/redaction.ts
+var SENSITIVE_KEYS = /* @__PURE__ */ new Set([
+  "authorization",
+  "token",
+  "access_token",
+  "password",
+  "secret",
+  "secretkey",
+  "secret_key"
+]);
+var BEARER_TOKEN = /\bBearer\s+[^\s"',}\]]+/giu;
+function redactString(value) {
+  return value.replace(BEARER_TOKEN, "Bearer [REDACTED]");
+}
+function redact(value) {
+  if (typeof value === "string") {
+    return redactString(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redact(item));
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => {
+        const normalizedKey = key.toLowerCase();
+        if (normalizedKey === "authorization" && typeof item === "string") {
+          return [key, redactString(item)];
+        }
+        return [key, SENSITIVE_KEYS.has(normalizedKey) ? "[REDACTED]" : redact(item)];
+      })
+    );
+  }
+  return value;
+}
+
+// src/output/json.ts
+function renderJson(result) {
+  return `${JSON.stringify(redact(result))}
+`;
+}
+
+// src/program.ts
+function parseInteger(value) {
+  return Number.parseInt(value, 10);
+}
+function parsePositiveInteger(value) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new CliError("INVALID_ARGUMENT", "Expected a positive integer", {
+      exitCode: exitCodes.invalidArgument
+    });
+  }
+  return parsed;
+}
+function parseAgent(value) {
+  if (value === "codex" || value === "claude-code") {
+    return value;
+  }
+  throw new CliError("INVALID_ARGUMENT", `Unsupported Agent: ${value}`, {
+    exitCode: exitCodes.invalidArgument,
+    hint: "Choose codex or claude-code."
+  });
+}
+function commandOptions(program) {
+  return program.opts();
+}
+function emit(program, dependencies2, data) {
+  const options = commandOptions(program);
+  dependencies2.writeStdout(
+    options.json ? renderJson(success(data)) : renderHuman(data, options.quiet ?? false)
+  );
+}
+async function runtime(program, dependencies2) {
+  const options = commandOptions(program);
+  return createRuntimeContext({
+    options: {
+      ...options.url ? { url: options.url } : {},
+      ...options.profile ? { profile: options.profile } : {}
+    },
+    environment: dependencies2.environment,
+    configStore: dependencies2.configStore,
+    credentialStore: dependencies2.credentialStore,
+    createClient: dependencies2.createClient
+  });
+}
+function localMcpRuntime(dependencies2) {
+  if (!dependencies2.localMcp) {
+    throw new CliError("DEPENDENCY_MISSING", "Local MCP runtime is unavailable", {
+      exitCode: exitCodes.dependencyMissing
+    });
+  }
+  return dependencies2.localMcp;
+}
+async function selectedProfileName(program, dependencies2) {
+  const options = commandOptions(program);
+  if (options.profile) {
+    await dependencies2.configStore.getProfile(options.profile);
+    return options.profile;
+  }
+  return (await dependencies2.configStore.load()).currentProfile ?? "local";
+}
+async function selectedServerName(program, dependencies2, explicitName) {
+  const profile = await selectedProfileName(program, dependencies2);
+  return {
+    profile,
+    serverName: explicitName ?? `sag-knowledge-${profile}`
+  };
+}
+function addProfileCommands(program, dependencies2) {
+  const profile = program.command("profile").description("Manage SAG profiles");
+  profile.command("add").argument("<name>").argument("<url>").action(async (name, url) => {
+    emit(program, dependencies2, await dependencies2.configStore.addProfile(name, url));
+  });
+  profile.command("list").action(async () => {
+    emit(program, dependencies2, await dependencies2.configStore.listProfiles());
+  });
+  profile.command("use").argument("<name>").action(async (name) => {
+    emit(program, dependencies2, await dependencies2.configStore.useProfile(name));
+  });
+  profile.command("show").argument("[name]").action(async (name) => {
+    emit(program, dependencies2, await dependencies2.configStore.getProfile(name));
+  });
+  profile.command("remove").argument("<name>").action(async (name) => {
+    if (!commandOptions(program).yes && !await dependencies2.confirm(`Remove profile ${name}?`)) {
+      emit(program, dependencies2, { removed: null, cancelled: true });
+      return;
+    }
+    await dependencies2.configStore.removeProfile(name);
+    emit(program, dependencies2, { removed: name });
+  });
+}
+function addAuthCommands(program, dependencies2) {
+  const auth = program.command("auth").description("Manage SAG credentials");
+  auth.command("login").action(async () => {
+    const context = await runtime(program, dependencies2);
+    const result = await login({
+      credentialRef: context.credentialRef,
+      ...context.connection.environmentToken ? { environmentToken: context.connection.environmentToken } : {},
+      promptToken: dependencies2.promptToken,
+      validate: async (token) => dependencies2.createClient({ origin: context.connection.url, token }).me(),
+      store: dependencies2.credentialStore
+    });
+    emit(program, dependencies2, result);
+  });
+  auth.command("status").action(async () => {
+    const context = await runtime(program, dependencies2);
+    const result = await status({
+      credentialRef: context.credentialRef,
+      ...context.connection.environmentToken ? { environmentToken: context.connection.environmentToken } : {},
+      validate: async (token) => dependencies2.createClient({ origin: context.connection.url, token }).me(),
+      store: dependencies2.credentialStore
+    });
+    emit(program, dependencies2, result);
+  });
+  auth.command("logout").action(async () => {
+    const context = await runtime(program, dependencies2);
+    emit(
+      program,
+      dependencies2,
+      await logout({
+        credentialRef: context.credentialRef,
+        store: dependencies2.credentialStore
+      })
+    );
+  });
+}
+function addKnowledgeCommands(program, dependencies2) {
+  program.command("doctor").action(async () => {
+    const context = await runtime(program, dependencies2);
+    emit(
+      program,
+      dependencies2,
+      await runDoctor(
+        context.client,
+        {
+          url: context.connection.url,
+          ...context.connection.profileName ? { profileName: context.connection.profileName } : {}
+        },
+        dependencies2.localMcp ? () => localMcpDoctorChecks(dependencies2.localMcp, {
+          timeoutMs: 15e3
+        }) : void 0
+      )
+    );
+  });
+  const source = program.command("source").description("Inspect SAG sources");
+  source.command("list").action(async () => {
+    const context = await runtime(program, dependencies2);
+    emit(program, dependencies2, await listSources(context.client));
+  });
+  source.command("get").argument("<source-id>").action(async (sourceId) => {
+    const context = await runtime(program, dependencies2);
+    emit(program, dependencies2, await getSource(context.client, sourceId));
+  });
+  source.command("status").argument("[source-id]").action(async (sourceId) => {
+    const context = await runtime(program, dependencies2);
+    emit(program, dependencies2, await sourceStatus(context.client, sourceId));
+  });
+  const document = program.command("document").description("Inspect SAG documents");
+  document.command("list").requiredOption("--source <source-id>").action(async (options) => {
+    const context = await runtime(program, dependencies2);
+    emit(program, dependencies2, await listDocuments(context.client, options.source));
+  });
+  document.command("get").argument("<document-id>").requiredOption("--source <source-id>").action(async (documentId, options) => {
+    const context = await runtime(program, dependencies2);
+    emit(
+      program,
+      dependencies2,
+      await getDocument(context.client, options.source, documentId)
+    );
+  });
+  document.command("status").argument("[document-id]").requiredOption("--source <source-id>").action(async (documentId, options) => {
+    const context = await runtime(program, dependencies2);
+    emit(
+      program,
+      dependencies2,
+      await documentStatus(context.client, options.source, documentId)
+    );
+  });
+  program.command("search").argument("<query>").option("--source <source-id...>").option("--top-k <number>", "Maximum result count", parseInteger).addOption(new Option("--strategy <strategy>").choices(["vector", "multi"])).action(
+    async (query, options) => {
+      const context = await runtime(program, dependencies2);
+      emit(
+        program,
+        dependencies2,
+        await searchKnowledge(context.client, query, {
+          ...options.source ? { sourceIds: options.source } : {},
+          ...options.topK !== void 0 ? { topK: options.topK } : {},
+          ...options.strategy ? { strategy: options.strategy } : {}
+        })
+      );
+    }
+  );
+}
+function addLocalMcpCommands(program, dependencies2) {
+  const mcp = program.command("mcp").description("Verify local SAG MCP");
+  mcp.command("test").option("--source-id <source-id>").option("--container <name-or-id>").option("--timeout <milliseconds>", "MCP timeout", parsePositiveInteger, 15e3).action(
+    async (options) => {
+      emit(
+        program,
+        dependencies2,
+        await testLocalMcp(localMcpRuntime(dependencies2), {
+          ...options.sourceId ? { sourceId: options.sourceId } : {},
+          ...options.container ? { container: options.container } : {},
+          timeoutMs: options.timeout
+        })
+      );
+    }
+  );
+}
+function addAgentCommands(program, dependencies2) {
+  const agent = program.command("agent").description("Manage Agent MCP connections");
+  agent.command("list").action(async () => {
+    emit(program, dependencies2, await listAgentHosts(localMcpRuntime(dependencies2)));
+  });
+  agent.command("connect").argument("<agent>", "codex or claude-code", parseAgent).option("--source-id <source-id>").option("--container <name-or-id>").option("--name <server-name>").option("--timeout <milliseconds>", "MCP timeout", parsePositiveInteger, 15e3).option("--dry-run", "Show the plan without changing configuration").action(
+    async (agentId, options) => {
+      const selection = await selectedServerName(program, dependencies2, options.name);
+      emit(
+        program,
+        dependencies2,
+        await connectLocalAgent(localMcpRuntime(dependencies2), {
+          agent: agentId,
+          serverName: selection.serverName,
+          profile: selection.profile,
+          ...options.sourceId ? { sourceId: options.sourceId } : {},
+          ...options.container ? { container: options.container } : {},
+          timeoutMs: options.timeout,
+          dryRun: options.dryRun ?? false,
+          yes: commandOptions(program).yes ?? false,
+          confirm: dependencies2.confirm,
+          now: () => /* @__PURE__ */ new Date()
+        })
+      );
+    }
+  );
+  agent.command("status").argument("[agent]", "codex or claude-code", parseAgent).option("--name <server-name>").action(async (agentId, options) => {
+    const selection = await selectedServerName(program, dependencies2, options.name);
+    emit(
+      program,
+      dependencies2,
+      await statusLocalAgents(localMcpRuntime(dependencies2), {
+        ...agentId ? { agent: agentId } : {},
+        serverName: selection.serverName
+      })
+    );
+  });
+  agent.command("disconnect").argument("<agent>", "codex or claude-code", parseAgent).option("--name <server-name>").action(async (agentId, options) => {
+    const selection = await selectedServerName(program, dependencies2, options.name);
+    emit(
+      program,
+      dependencies2,
+      await disconnectLocalAgent(localMcpRuntime(dependencies2), {
+        agent: agentId,
+        serverName: selection.serverName,
+        yes: commandOptions(program).yes ?? false,
+        confirm: dependencies2.confirm
+      })
+    );
+  });
+}
+function createProgram(dependencies2) {
+  const program = new Command();
+  program.name("sag").description("Command-line client and diagnostics for SAG").showHelpAfterError().exitOverride().option("--json", "Output a stable JSON envelope").option("--quiet", "Output only essential values").option("--profile <name>", "Use a configured SAG profile").option("--url <origin>", "Use a SAG origin without saving it").option("--yes", "Confirm safe local configuration changes").configureOutput({
+    writeOut: dependencies2.writeStdout,
+    writeErr: dependencies2.writeStderr
+  });
+  program.command("version").action(() => {
+    const options = commandOptions(program);
+    if (options.json) {
+      dependencies2.writeStdout(
+        renderJson(success({ name: "sag", version: dependencies2.version }))
+      );
+    } else {
+      dependencies2.writeStdout(`sag ${dependencies2.version}
+`);
+    }
+  });
+  addProfileCommands(program, dependencies2);
+  addAuthCommands(program, dependencies2);
+  addKnowledgeCommands(program, dependencies2);
+  addLocalMcpCommands(program, dependencies2);
+  addAgentCommands(program, dependencies2);
+  return program;
+}
+async function runCli(arguments_, dependencies2) {
+  const json = arguments_.includes("--json");
+  try {
+    await createProgram(dependencies2).parseAsync(arguments_);
+    return exitCodes.success;
+  } catch (error) {
+    if (error instanceof CommanderError && error.exitCode === 0) {
+      return 0;
+    }
+    const cliError = error instanceof CommanderError ? new CliError("INVALID_ARGUMENT", error.message, {
+      exitCode: exitCodes.invalidArgument
+    }) : toCliError(error);
+    if (json) {
+      dependencies2.writeStdout(renderJson(failure(cliError)));
+    } else {
+      dependencies2.writeStderr(
+        `Error [${cliError.code}]: ${cliError.message}${cliError.hint ? `
+Hint: ${cliError.hint}` : ""}
+`
+      );
+      if (dependencies2.environment.SAG_DEBUG === "1" && cliError.cause instanceof Error) {
+        dependencies2.writeStderr(`${cliError.cause.stack ?? cliError.cause.message}
+`);
+      }
+    }
+    return cliError.exitCode;
+  }
+}
+var defaultClientFactory = (options) => new SagClient(options);
+
+// src/cli.ts
+var credentialSelection = await createCredentialStore();
+if (credentialSelection.warning) {
+  process.stderr.write(`Warning: ${credentialSelection.warning}
+`);
+}
+var processRunner = new NodeProcessRunner();
+var dependencies = {
+  version: package_default.version,
+  environment: process.env,
+  configStore: new ConfigStore(defaultConfigPath()),
+  credentialStore: credentialSelection.store,
+  createClient: defaultClientFactory,
+  promptToken: () => password({
+    message: "SAG Token",
+    mask: "*"
+  }),
+  confirm: (message) => confirm({ message, default: false }),
+  writeStdout: (value) => process.stdout.write(value),
+  writeStderr: (value) => process.stderr.write(value),
+  localMcp: {
+    docker: new DockerClient(processRunner),
+    verifier: new McpVerifier(package_default.version),
+    state: new ManagedConnectionStore(defaultManagedConnectionsPath()),
+    adapters: {
+      codex: new CodexAdapter(processRunner),
+      "claude-code": new ClaudeCodeAdapter(processRunner)
+    },
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    selectContainer: (candidates) => select({
+      message: "Select the SAG API container",
+      choices: candidates.map((candidate) => ({
+        name: `${candidate.name} (${candidate.composeProject ?? "no Compose project"})`,
+        value: candidate.id
+      }))
+    })
+  }
+};
+process.exitCode = await runCli(process.argv, dependencies);
+//# sourceMappingURL=cli.js.map