@nanhara/hara 0.125.1 → 0.126.0

package/dist/mcp/client.js

@@ -4,11 +4,12 @@ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
 import { registerTool } from "../tools/registry.js";
 import { redactToolSubprocessOutput, toolSubprocessEnv } from "../security/subprocess-env.js";
 import { sensitiveStructuredInputReason } from "../security/sensitive-files.js";
-const clients = [];
+const clients = new Map();
 const DEFAULT_STARTUP_TIMEOUT_MS = 10_000;
 const MIN_STARTUP_TIMEOUT_MS = 50;
 const MAX_STARTUP_TIMEOUT_MS = 60_000;
 const safeDiagnosticName = (name) => name.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, 128) || "server";
+const NPM_UNKNOWN_USER_CONFIG_NOISE = /^npm\s+warn\s+Unknown user config "(?:always-auth|home)"(?:\s|\(|\.|$)/i;
 function startupTimeout(value) {
     if (value === undefined || !Number.isFinite(value))
         return DEFAULT_STARTUP_TIMEOUT_MS;
@@ -60,6 +61,12 @@ function mcpStderrRedactor(name, explicitEnv, log) {
             .replace(/\r?\n$/, "");
         if (!clean)
             return;
+        // npm 11 prints these host-user `.npmrc` deprecation notices before an npx-backed MCP server writes
+        // anything. They are neither server diagnostics nor actionable inside Hara, and repeating them in the
+        // TUI makes a healthy MCP startup look broken. Keep the filter deliberately exact: all other npm/MCP
+        // warnings and every error still cross the bounded redactor. Never read or rewrite the user's `.npmrc`.
+        if (NPM_UNKNOWN_USER_CONFIG_NOISE.test(clean))
+            return;
         const message = `mcp: ${safeName} stderr: ${clean}`;
         if (emitted + message.length > totalLimit) {
             log(`mcp: ${safeName} stderr: [further diagnostics omitted]`);
@@ -124,15 +131,20 @@ export async function connectMcpServers(servers, log, options = {}) {
         return 0;
     }
     const timeoutMs = startupTimeout(options.timeoutMs);
-    const requestOptions = { timeout: timeoutMs, maxTotalTimeout: timeoutMs };
+    const requestOptions = { timeout: timeoutMs, maxTotalTimeout: timeoutMs, signal: options.signal };
     let count = 0;
     for (const [name, cfg] of Object.entries(servers)) {
         const diagnosticName = safeDiagnosticName(name);
+        if (clients.has(name)) {
+            log(`mcp: ${diagnosticName} already connected`);
+            continue;
+        }
         let flushStderr;
         let transport;
         let client;
         let stage = "connect";
         try {
+            options.signal?.throwIfAborted();
             transport = new StdioClientTransport({
                 command: cfg.command,
                 args: cfg.args ?? [],
@@ -152,8 +164,10 @@ export async function connectMcpServers(servers, log, options = {}) {
             client = new Client({ name: "hara", version: "0.4.0" }, { capabilities: {} });
             await client.connect(transport, requestOptions);
             stage = "list tools";
+            options.signal?.throwIfAborted();
             const activeClient = client;
             const { tools } = await activeClient.listTools(undefined, requestOptions);
+            options.signal?.throwIfAborted();
             for (const t of tools) {
                 const schema = t.inputSchema ?? { type: "object", properties: {} };
                 registerTool({
@@ -161,6 +175,7 @@ export async function connectMcpServers(servers, log, options = {}) {
                     description: t.description ?? `${name}/${t.name}`,
                     input_schema: schema,
                     kind: "exec",
+                    visibility: "deferred",
                     trustBoundary: "external",
                     async run(input, ctx) {
                         if (!ctx.ask && process.env.HARA_ALLOW_TRUSTED_EXTENSIONS !== "1") {
@@ -169,7 +184,7 @@ export async function connectMcpServers(servers, log, options = {}) {
                         const protectedReason = sensitiveStructuredInputReason(input, ctx.cwd);
                         if (protectedReason)
                             return `Blocked: MCP input names protected ${protectedReason}.`;
-                        const res = await activeClient.callTool({ name: t.name, arguments: input ?? {} });
+                        const res = await activeClient.callTool({ name: t.name, arguments: input ?? {} }, undefined, { signal: ctx.signal });
                         const blocks = Array.isArray(res?.content) ? res.content : [];
                         const text = blocks.map((b) => (b?.type === "text" ? b.text : JSON.stringify(b))).join("\n");
                         return redactToolSubprocessOutput(text || "(no output)", process.env, cfg.env ?? {});
@@ -177,7 +192,7 @@ export async function connectMcpServers(servers, log, options = {}) {
                 });
                 count++;
             }
-            clients.push(activeClient);
+            clients.set(name, activeClient);
             log(`mcp: ${diagnosticName} → ${tools.length} tool(s)`);
         }
         catch (e) {
@@ -193,8 +208,60 @@ export async function connectMcpServers(servers, log, options = {}) {
     }
     return count;
 }
+/** Register a zero-side-effect launcher for configured MCP servers. The model sees only this bounded index
+ * until a relevant task calls it; connecting one server dynamically registers its real tools for the next
+ * provider round (runAgent rebuilds tool specs every round). */
+export function registerLazyMcpServers(servers, log) {
+    const names = Object.keys(servers);
+    if (!names.length)
+        return;
+    const display = names
+        .slice(0, 24)
+        .map((name) => safeDiagnosticName(name))
+        .join(", ");
+    const more = names.length > 24 ? `, … (${names.length - 24} more)` : "";
+    registerTool({
+        name: "mcp_connect",
+        description: "Connect exactly one configured MCP server when the current task first needs it. " +
+            "Do not call speculatively: launching it executes reviewed external code outside Hara's protected-file boundary. " +
+            `Configured servers: ${display}${more}. After success, its mcp__<server>__* tools appear on the next turn.`,
+        input_schema: {
+            type: "object",
+            properties: {
+                server: {
+                    type: "string",
+                    enum: names,
+                    description: "Exact configured server name to connect.",
+                },
+            },
+            required: ["server"],
+        },
+        kind: "exec",
+        trustBoundary: "external",
+        async run(input, ctx) {
+            const name = typeof input?.server === "string" ? input.server : "";
+            const cfg = servers[name];
+            if (!cfg) {
+                return `Error: unknown MCP server '${safeDiagnosticName(name)}'. Available: ${display}${more}.`;
+            }
+            if (!ctx.ask && process.env.HARA_ALLOW_TRUSTED_EXTENSIONS !== "1") {
+                return ("Blocked: MCP is a trusted extension outside Hara's file boundary and is disabled in " +
+                    "non-interactive runs. Set HARA_ALLOW_TRUSTED_EXTENSIONS=1 before launch only after reviewing the server.");
+            }
+            if (clients.has(name))
+                return `MCP server '${safeDiagnosticName(name)}' is already connected.`;
+            const runtimeLog = ctx.ui ? (message) => ctx.ui.notice(message) : log;
+            const count = await connectMcpServers({ [name]: cfg }, runtimeLog, { approved: true, signal: ctx.signal });
+            if (!clients.has(name)) {
+                return `Error: MCP server '${safeDiagnosticName(name)}' failed to connect. Review its redacted startup diagnostics.`;
+            }
+            return (`Connected MCP server '${safeDiagnosticName(name)}'; ${count} tool(s) are now available under ` +
+                `mcp__${safeDiagnosticName(name)}__*. Continue with the specific tool needed for the task.`);
+        },
+    });
+}
 export async function closeMcp() {
-    for (const cl of clients) {
+    for (const cl of clients.values()) {
         try {
             await cl.close();
         }
@@ -202,5 +269,5 @@ export async function closeMcp() {
             /* ignore */
         }
     }
-    clients.length = 0;
+    clients.clear();
 }

package/dist/providers/bounded-turn.js

@@ -33,6 +33,12 @@ export async function boundedProviderTurn(provider, args, options) {
         // microtask starts. Re-check here so an already-cancelled auxiliary call never incurs a request/cost.
         .then(() => controller.signal.aborted ? errorResult(`${label} cancelled`) : provider.turn({ ...args, signal: controller.signal }))
         .catch((error) => errorResult(error instanceof Error ? error.message : String(error)));
+    try {
+        options.onProviderTurn?.(turn);
+    }
+    catch {
+        // Observability must never weaken the provider boundary.
+    }
     const result = await Promise.race([turn, stopped]);
     clearTimeout(timer);
     parent?.removeEventListener("abort", onParentAbort);

package/dist/providers/factory.js

@@ -0,0 +1,54 @@
+// Shared provider construction for the interactive CLI, Desktop serve, gateway approval/judge calls, and
+// connection tests. Every path must interpret auth:none/OAuth/wire-protocol targets identically.
+import { providerIsLocal } from "../config.js";
+import { getValidQwenAuth } from "./qwen-oauth.js";
+import { createAnthropicProvider } from "./anthropic.js";
+import { createOpenAIProvider } from "./openai.js";
+import { resolvePlatform } from "./registry.js";
+export async function createProviderForTarget(target, reasoningEffort) {
+    const { provider, apiKey, model, baseURL } = target;
+    if (provider === "qwen-oauth") {
+        const auth = await getValidQwenAuth();
+        if (!auth)
+            return null;
+        return createOpenAIProvider({
+            apiKey: auth.accessToken,
+            baseURL: auth.baseURL,
+            model,
+            label: provider,
+            reasoningEffort,
+        });
+    }
+    // The OpenAI SDK requires a non-empty constructor value even when a compatible local endpoint has no
+    // authentication. This sentinel never leaves the process for cloud targets and local targets have already
+    // discarded all user credentials at target resolution.
+    const transportKey = apiKey ?? (providerIsLocal(provider) ? "hara-local-no-secret" : undefined);
+    if (!transportKey)
+        return null;
+    const wire = resolvePlatform(provider, baseURL).wireApi;
+    if (wire === "anthropic") {
+        return createAnthropicProvider({ apiKey: transportKey, model, baseURL, reasoningEffort });
+    }
+    if (wire === "responses") {
+        return {
+            id: provider,
+            model,
+            async turn() {
+                return {
+                    text: "",
+                    toolUses: [],
+                    stop: "error",
+                    errorMsg: "This endpoint uses the OpenAI Responses API, which hara doesn't speak yet. Point hara at an OpenAI-compatible chat endpoint (…/compatible-mode/v1 or …/v1) or an Anthropic-compatible endpoint (…/apps/anthropic).",
+                };
+            },
+        };
+    }
+    return createOpenAIProvider({
+        apiKey: transportKey,
+        model,
+        baseURL,
+        label: provider,
+        reasoningEffort,
+        omitAuthorization: providerIsLocal(provider),
+    });
+}

package/dist/providers/models.js

@@ -1,21 +1,54 @@
+// Alibaba Coding Plan's documented exact ids (verified 2026-07-18). Live `/models` remains authoritative;
+// this list is only a usability fallback because the coding endpoint/key combinations do not all enumerate.
+// Keep exact casing: Coding Plan explicitly forbids guessing compatible/version-like aliases.
+export const CODING_PLAN_FALLBACK_MODELS = Object.freeze([
+    "qwen3.7-plus",
+    "qwen3.6-plus",
+    "kimi-k2.5",
+    "glm-5",
+    "MiniMax-M2.5",
+    "qwen3.5-plus",
+    "qwen3-max-2026-01-23",
+    "qwen3-coder-next",
+    "qwen3-coder-plus",
+    "glm-4.7",
+]);
+export function codingPlanFallbackModels(baseURL) {
+    if (!baseURL)
+        return [];
+    try {
+        const host = new URL(baseURL).hostname.toLowerCase();
+        return host === "coding.dashscope.aliyuncs.com" || host === "coding-intl.dashscope.aliyuncs.com"
+            ? [...CODING_PLAN_FALLBACK_MODELS]
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
 // Model discovery — "what can this key run?" A coding-plan / OpenAI-compatible key usually exposes many
 // models (Qwen, GLM, Kimi, …) via `GET {baseURL}/models`; the /model picker lists them so you switch by
-// arrow keys, not by memorizing ids. Best-effort: many endpoints don't implement it → [] and the picker
-// falls back to typing an id. `fetchImpl` is injected so this stays pure/testable.
+// arrow keys, not by memorizing ids. Live results win. A bounded request falls back to Alibaba's documented
+// exact Coding Plan ids only on the two official coding hosts; other endpoints keep the existing [] →
+// type-an-id behavior. `fetchImpl` is injected so this stays pure/testable.
 export async function listModels(baseURL, apiKey, fetchImpl = fetch) {
     if (!baseURL)
         return []; // SDK-default hosts (anthropic/openai) — no custom endpoint to enumerate
+    const fallback = codingPlanFallbackModels(baseURL);
     try {
         const url = baseURL.replace(/\/+$/, "") + "/models";
-        const r = await fetchImpl(url, { headers: { Authorization: `Bearer ${apiKey}` } });
+        const headers = {};
+        if (apiKey)
+            headers.Authorization = `Bearer ${apiKey}`;
+        const r = await fetchImpl(url, { headers, signal: AbortSignal.timeout(5_000) });
         if (!r.ok)
-            return [];
+            return fallback;
         const j = (await r.json());
         const ids = (j?.data ?? []).map((m) => m?.id).filter((x) => typeof x === "string" && x.length > 0);
         // Stable order + de-dup so the picker list doesn't jump around between opens.
-        return [...new Set(ids)].sort((a, b) => a.localeCompare(b));
+        return ids.length ? [...new Set(ids)].sort((a, b) => a.localeCompare(b)) : fallback;
     }
     catch {
-        return [];
+        return fallback;
     }
 }

package/dist/providers/openai.js

@@ -80,7 +80,12 @@ export function toOpenAI(system, history) {
 }
 /** OpenAI-compatible provider (works with OpenAI, Qwen/DashScope, GLM, Kimi, …). */
 export function createOpenAIProvider(opts) {
-    const client = new OpenAI({ apiKey: opts.apiKey, maxRetries: 4, ...(opts.baseURL ? { baseURL: opts.baseURL } : {}) });
+    const client = new OpenAI({
+        apiKey: opts.apiKey,
+        maxRetries: 4,
+        ...(opts.baseURL ? { baseURL: opts.baseURL } : {}),
+        ...(opts.omitAuthorization ? { defaultHeaders: { Authorization: null } } : {}),
+    });
     return {
         id: opts.label ?? "openai",
         model: opts.model,

package/dist/providers/reasoning.js

@@ -8,6 +8,16 @@
 export function isReasoningModel(model) {
     return /^(o1|o3|o4|gpt-5)/i.test(model);
 }
+/** Endpoint capability is not enough: Alibaba's Coding Plan serves qwen3-coder-next/plus on the same
+ * DashScope URL as thinking models, but documents both coder ids as not supporting thinking mode. */
+export function supportsReasoningStyle(style, model = "") {
+    if (style === "none")
+        return false;
+    if (style === "enable_thinking" && /^qwen3-coder-(?:next|plus)(?:-|$)/i.test(model.split("/").at(-1) ?? model)) {
+        return false;
+    }
+    return true;
+}
 /** Translate the dial into request params to MERGE into the wire body (chat/responses styles). Returns an
  *  empty object — leave the request untouched — when the dial is UNSET (keep the model's own default; zero
  *  impact, the safe default) or the style/model has nothing to add. Anthropic's `thinking_budget` is built
@@ -17,6 +27,8 @@ export function reasoningParams(style, effort, model = "") {
         return {};
     switch (style) {
         case "enable_thinking":
+            if (!supportsReasoningStyle(style, model))
+                return {};
             // off → false (stop the thinking phase, fast); any explicit level → true (keep it on).
             return { enable_thinking: effort !== "off" };
         case "ollama_think":

package/dist/providers/registry.js

@@ -32,6 +32,7 @@ const BY_PROVIDER = {
     glm: { wireApi: "chat", reasoning: "none", cache: "auto" }, // Zhipu native /paas/v4 — different thinking param; leave alone (its /anthropic endpoint resolves via baseURL)
     deepseek: { wireApi: "chat", reasoning: "deepseek", cache: "auto" }, // V4: thinking:{type} + reasoning_effort(high|max)
     ollama: { wireApi: "chat", reasoning: "ollama_think", cache: "none" }, // local; `think` toggles reasoning
+    lmstudio: { wireApi: "chat", reasoning: "ollama_think", cache: "none" }, // local OpenAI-compatible server
     openai: { wireApi: "chat", reasoning: "reasoning_effort", cache: "auto" },
     openrouter: { wireApi: "chat", reasoning: "none", cache: "auto" },
     "hara-gateway": { wireApi: "chat", reasoning: "none", cache: "auto" },

package/dist/providers/target.js

@@ -0,0 +1,98 @@
+import { providerDefaultBaseURL, providerDefaultModel, providerEnvKey, isProviderId, providerIsLocal, } from "../config.js";
+import { getProfile, PERSONAL_ID, resolveActive, } from "../profile/profile.js";
+/** Resolve the identity profile for the same cwd used to load config. */
+export function profileForConfig(cfg) {
+    const resolution = resolveActive(cfg.cwd);
+    if (resolution.id !== PERSONAL_ID) {
+        const profile = getProfile(resolution.id);
+        if (profile)
+            return { profile, resolution };
+    }
+    return {
+        resolution: resolution.id === PERSONAL_ID
+            ? resolution
+            : { id: PERSONAL_ID, source: "fallback" },
+        profile: {
+            id: PERSONAL_ID,
+            kind: "byok",
+            label: "Personal",
+            provider: cfg.provider,
+            apiKey: cfg.apiKey,
+            baseURL: cfg.baseURL,
+            defaultModel: cfg.model,
+        },
+    };
+}
+/**
+ * Resolve one BYOK/local transport target.
+ *
+ * A named Profile is an identity boundary: its vendor, credential and endpoint must not be replaced by
+ * the always-populated personal/global config. Explicit HARA_* values remain one-shot overrides. The
+ * personal profile and explicit sidecars continue to use the merged config.
+ */
+export function resolveByokProviderTarget(cfg, profile, sidecarOverride, env = process.env) {
+    const personalOrOverride = profile.id === "personal" || sidecarOverride;
+    const profileProvider = profile.provider && profile.provider !== "hara-gateway" ? profile.provider : "anthropic";
+    const environmentProvider = isProviderId(env.HARA_PROVIDER) && env.HARA_PROVIDER !== "hara-gateway"
+        ? env.HARA_PROVIDER
+        : undefined;
+    const provider = personalOrOverride
+        ? (cfg.provider !== "hara-gateway" ? cfg.provider : profileProvider)
+        : environmentProvider ?? profileProvider;
+    const namedProviderChanged = !personalOrOverride && provider !== profileProvider;
+    const envKey = providerEnvKey(provider);
+    const providerEnvApiKey = envKey ? env[envKey] : undefined;
+    const candidateApiKey = personalOrOverride
+        ? cfg.apiKey ?? profile.apiKey
+        : env.HARA_API_KEY ?? providerEnvApiKey ?? (namedProviderChanged ? undefined : profile.apiKey);
+    // Ollama/LM Studio declare auth:none. Never forward a stale cloud key (including HARA_API_KEY) to a
+    // loopback process that happens to occupy the configured port.
+    const apiKey = providerIsLocal(provider) ? undefined : candidateApiKey;
+    const baseURL = personalOrOverride
+        ? cfg.baseURL ?? profile.baseURL ?? providerDefaultBaseURL(provider)
+        : env.HARA_BASE_URL
+            ?? (namedProviderChanged ? undefined : profile.baseURL)
+            ?? providerDefaultBaseURL(provider);
+    const profileModel = profile.model || profile.defaultModel || "";
+    const model = personalOrOverride
+        ? cfg.model || env.HARA_MODEL || profileModel
+        : env.HARA_MODEL
+            || (namedProviderChanged ? "" : profileModel)
+            || providerDefaultModel(provider);
+    return { provider, apiKey, baseURL, model };
+}
+/**
+ * Apply an explicit runtime selection (session model, role model, vision/route sidecar, fallback).
+ *
+ * A provider switch starts a fresh credential/endpoint boundary; absent fields use that provider's public
+ * defaults and never inherit the previous profile's key or host.
+ */
+export function overrideProviderTarget(base, override) {
+    if (!override)
+        return base;
+    const owns = (key) => Object.prototype.hasOwnProperty.call(override, key);
+    const provider = override.provider ?? base.provider;
+    const providerChanged = provider !== base.provider;
+    const apiKey = providerIsLocal(provider)
+        ? undefined
+        : owns("apiKey")
+            ? override.apiKey
+            : providerChanged
+                ? undefined
+                : base.apiKey;
+    const baseURL = owns("baseURL")
+        ? override.baseURL
+        : providerChanged
+            ? providerDefaultBaseURL(provider)
+            : base.baseURL;
+    const model = owns("model") && override.model
+        ? override.model
+        : providerChanged
+            ? providerDefaultModel(provider)
+            : base.model;
+    return { provider, apiKey, baseURL, model };
+}
+/** Gateway profiles own their default, while an explicit session/role model remains selectable. */
+export function resolveGatewayModel(cfg, profile, env = process.env, requestedModel) {
+    return env.HARA_MODEL || requestedModel || profile.model || profile.defaultModel || cfg.model;
+}

package/dist/security/guardian.js

@@ -223,7 +223,12 @@ export async function guardianVeto(provider, action, history, opts = {}) {
             history: [{ role: "user", content: prompt }],
             tools: [],
             onText: () => { },
-        }, { timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS, signal: opts.signal, label: "security guardian" });
+        }, {
+            timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            signal: opts.signal,
+            label: "security guardian",
+            onProviderTurn: opts.onProviderTurn,
+        });
         if (r.stop === "error")
             return { decision: "allow", reason: "" }; // fail-open on model error
         return parseVerdict(r.text);

package/dist/security/private-state.js

@@ -8,7 +8,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { FileReadLimitError, MAX_EDIT_READ_BYTES, decodeUtf8Strict, openVerifiedRegularFileNoFollow, verifyOpenedRegularFileSync, } from "../fs-read.js";
 import { optionalPosixOpenFlag } from "../fs-open-flags.js";
 import { sameOpenedFileIdentity } from "../fs-identity.js";
-const PRIVATE_TREES = new Set(["sessions", "checkpoints", "index", "gateway", "cron", "weixin"]);
+const PRIVATE_TREES = new Set(["sessions", "checkpoints", "index", "gateway", "cron", "weixin", "tool-results"]);
 const tightenedHomes = new Set();
 const DEFAULT_MIGRATION_CAP = 50_000;
 function isMissing(error) {

package/dist/security/secrets.js

@@ -87,6 +87,25 @@ export function redactSensitiveText(text) {
     }
     return { text: out, redactions };
 }
+/** Remove caller-known secret values before pattern matching. Provider/server errors may echo an opaque key
+ * that has no recognizable prefix, so field-name and token-shape heuristics alone cannot uphold no-echo APIs. */
+export function redactKnownSecrets(text, secrets) {
+    let out = text;
+    const exactHits = [];
+    for (const value of secrets) {
+        if (!value)
+            continue;
+        const variants = new Set([value, encodeURIComponent(value)]);
+        for (const variant of variants) {
+            if (!variant || !out.includes(variant))
+                continue;
+            out = out.split(variant).join("***");
+            exactHits.push("known-secret");
+        }
+    }
+    const patterned = redactSensitiveText(out);
+    return { text: patterned.text, redactions: [...exactHits, ...patterned.redactions] };
+}
 /** Structured tool/config data often carries an opaque value that has no recognizable token prefix. In that
  *  case the FIELD name is the evidence (`apiKey`, `access_token`, `FEISHU_APP_SECRET`, …). Keep this narrow
  *  enough not to erase ordinary fields such as `tokenCount` or `secretary`. */

package/dist/serve/protocol.js

@@ -3,8 +3,10 @@
 // Everything here is PURE (parse + frame builders + error codes) and unit-tested.
 //
 // Client → server requests:
-//   initialize        {token,capabilities?}      → {name,version,protocol,cwd,provider,model,
+//   initialize        {token,capabilities?}      → {name,version,protocol,cwd,provider,model,setupState,
 //                                                   capabilities:{methods:[…]}}  (feature detection)
+//   server.shutdown   {}                         → {accepted:true} (authenticated graceful local shutdown;
+//                                                   BUSY while any client work/approval is active)
 //   session.list      {cwd?}                     → {sessions:[{id,title,cwd,model,updatedAt}]}
 //   session.create    {cwd?,approval?}           → {sessionId,model}
 //   session.resume    {sessionId}                → {sessionId,model,history:[{role,text}]}
@@ -19,6 +21,9 @@
 //   automation.list   {}                          → {jobs:[{id,name,mode,enabled,lastRunAt,lastStatus,…}],
 //                                                    sessions:[{id,title,source,sourceName,updatedAt,…}]}
 //   models.list       {}                          → {models:[…], current, effortLevels:[…]}
+//   settings.providers.list {}                    → redacted provider catalog + current profile state
+//   settings.providers.test {provider,model,…}     → {ok,models,error?} (credential is ephemeral)
+//   settings.providers.save {provider,model,…}     → redacted state (credential is never returned)
 //   automation.add    {name,schedule,task,mode?,cwd?,tz?} → {id,name,schedule}
 //   automation.toggle {id,enabled}                → {id,enabled}
 //   automation.delete {id}                        → {id,deleted}
@@ -37,7 +42,7 @@ export const ERR = {
     PARAMS: -32602,
     INTERNAL: -32603,
     UNAUTHORIZED: -32001, // initialize first (or bad token)
-    BUSY: -32002, // session already has a turn in flight
+    BUSY: -32002, // requested operation conflicts with active server/session work
     NO_SESSION: -32003, // unknown/expired sessionId
     LOCKED: -32004, // session held by another live hara process (single-writer lock)
 };