@qodo/sdk 0.13.4 → 2.0.0-next.1

package/dist/client/QodoClient.js

@@ -0,0 +1,803 @@
+/**
+ * `QodoClient` — the SDK 2.0 entry point.
+ *
+ * One typed wrapper layer above QAR's wire vocabulary. Sub-clients (`tasks`,
+ * `tools`, `info`, `pipeline`) mirror QAR's `kind` taxonomy; consumers `for await`
+ * the iterator returned by `tasks.start` and switch on `event.kind`.
+ *
+ * Construction is cheap and synchronous: validate options, hold the bearer, hand
+ * back sub-clients. `connect()` opens the WebSocket lazily; `disconnect()` tears
+ * it down.
+ */
+import { AuthProvider, QodoAuthError } from '../auth/index.js';
+import { TaskClient } from './TaskClient.js';
+import { ToolClient } from './ToolClient.js';
+import { InfoClient } from './InfoClient.js';
+import { SpecsClient } from './SpecsClient.js';
+import { PipelineClient } from './PipelineClient.js';
+import { BulletinClient } from './BulletinClient.js';
+import { ArtifactsClient } from './ArtifactsClient.js';
+import { StateClient } from './StateClient.js';
+import { AgentsClient } from './AgentsClient.js';
+import { QarRegistryClient } from './QarRegistryClient.js';
+import { SkillsManager } from '../skills/manager.js';
+import { QodoSkillsMcpServer, asMcpHandler } from '../skills/mcp/index.js';
+import { Connection, RawSubscription } from './connection.js';
+import { defaultTransportFactory } from './transport.js';
+import { QodoClientOptionsError, QodoMcpToolError } from './errors.js';
+import { resolveOTel } from '../observability/resolveOTel.js';
+import { SpanRecorder } from '../observability/spans.js';
+import { TraceContextProvider } from '../observability/traceContext.js';
+import { TransportMetrics } from '../observability/transportMetrics.js';
+import { getCurrentVersion } from '../version.js';
+export class QodoClient {
+    /** Task lifecycle surface — `task.start` / `task.continue` / `task.cancel` / `task.resubscribe`. */
+    tasks;
+    /** Tool tunneling surface — inbound `tool.request`, outbound `tool.response`. */
+    tools;
+    /** Bootstrap surface — `GET /v1/info`, `GET /v1/auth/me`. */
+    info;
+    /** Pre-flight surface — `POST /v1/specs/validate` for inline specs. */
+    specs;
+    /** Pipeline DSL — chained over the task primitive. */
+    pipeline;
+    /** Read-only observer for QAR's `bulletin.post` envelopes (multi-agent coordination). */
+    bulletin;
+    /** Read-only observer for QAR's `artifact.add` envelopes (durable artifacts). */
+    artifacts;
+    /** Read-only observer for QAR's `state.update` envelopes (per-skill state mutations). */
+    state;
+    /** Read-only observer for QAR's `agent.spawn` envelopes (sub-agent topology). */
+    agents;
+    /**
+     * SDK-process-scoped local registries for consumer-built agents and MCP
+     * servers. See {@link QarRegistryClient} for the surface — `registerAgent`,
+     * `registerMcp`, plus unregister / lookup helpers.
+     *
+     * The SDK ships with zero built-in MCPs; everything a consumer wants
+     * their agents to call must be registered here (or be a server-side
+     * managed tool via `AgentSpec.use_managed_tools`).
+     */
+    qar;
+    /**
+     * Skills foundation surface. Present iff `ClientOptions.skills` was
+     * provided at construction. `undefined` when skills are disabled —
+     * consumers branch on this before reaching for `.list()` / `.get()`.
+     *
+     * Discovery is lazy: the manager walks sources on the first
+     * `tasks.startWithAgent` / `tasks.startWithGraph` invocation that
+     * needs the catalog (or when the consumer calls `await
+     * client.skills.discover()` explicitly). Subsequent uses share the
+     * cached snapshot for the SDK lifetime.
+     */
+    skills;
+    /**
+     * `qodo-skills` MCP server. Present iff `ClientOptions.skills` was
+     * provided at construction. Auto-registered via
+     * `client.qar.registerMcp('qodo-skills', { transport: 'sdk', handler })` —
+     * the SDK ships zero built-in MCPs by default, with `qodo-skills` as
+     * the per-config exception. The handler owns the three tools
+     * (`list_skills`, `get_skill`, `get_skill_file`) and the in-memory
+     * body / file caches.
+     *
+     * `undefined` when `skills` is not configured — the server isn't
+     * registered either, so the no-MCPs invariant holds for default-config
+     * consumers.
+     */
+    skillsMcpServer;
+    /** Frozen copy of the construction options for runtime introspection. */
+    options;
+    /**
+     * Wire-level transport counters covering the reconnect + replay path.
+     * Three monotonic counters:
+     *
+     *   - `replay_envelopes_received_total` — envelopes received as descendants
+     *     of a `task.resubscribe` anchor.
+     *   - `resubscribes_sent_total` — `task.resubscribe` envelopes the SDK
+     *     emitted (auto-replay on reconnect AND manual `tasks.resubscribe`).
+     *   - `replay_anchor_missing_total` — inbound `error { code:
+     *     'replay_anchor_missing' }` envelopes from QAR.
+     *
+     * Counters survive across reconnects and `disconnect()`. Read via
+     * {@link TransportMetrics.snapshot}.
+     */
+    transportMetrics;
+    authProvider;
+    transportFactory;
+    /**
+     * OTel API the SDK emits spans against. Resolved once at construction time
+     * via the explicit `options.otel` first, then a best-effort dynamic
+     * `import('@opentelemetry/api')`. `undefined` means no OTel — every span
+     * call is a no-op and `traceparent` falls back to a fresh random.
+     */
+    otel;
+    traceContext;
+    /** @internal — exposed to the sub-clients via `getSpanRecorder()`. */
+    spanRecorder;
+    connection = null;
+    connectInFlight = null;
+    constructor(opts) {
+        QodoClient.validateOptions(opts);
+        this.options = opts;
+        this.authProvider = QodoClient.buildAuthProvider(opts);
+        this.transportFactory = opts.transport ?? defaultTransportFactory;
+        this.otel = resolveOTel(opts.otel);
+        this.traceContext = new TraceContextProvider(this.otel);
+        this.spanRecorder = new SpanRecorder(this.otel, getCurrentVersion());
+        this.transportMetrics = new TransportMetrics();
+        this.qar = new QarRegistryClient();
+        if (opts.skills !== undefined) {
+            this.skills = new SkillsManager(opts.skills);
+            // The `qodo-skills` MCP server is the one default MCP the SDK
+            // ships, gated on the consumer opting in to skills. Tools
+            // (`list_skills`, `get_skill`, `get_skill_file`) auto-approved;
+            // effects of loaded skill bodies are gated separately by the trust
+            // model.
+            this.skillsMcpServer = new QodoSkillsMcpServer(this.skills);
+            this.qar.registerMcp('qodo-skills', {
+                transport: 'sdk',
+                handler: asMcpHandler(this.skillsMcpServer),
+            });
+        }
+        this.tools = new ToolClient(() => this.requireConnection(), this.spanRecorder);
+        this.tasks = new TaskClient(() => this.requireConnection(), this.spanRecorder, this.qar, 
+        // Lazy `SpecsClient` resolver — `tasks` is constructed before `specs`,
+        // so we defer the dereference until `startWithGraph({ preflight: true })`
+        // actually needs it.
+        () => this.specs, this.transportMetrics, this.skills, 
+        // `defineFunctionTool` auto-bind callback. Routes through the
+        // `ToolClient`'s public `bindFunctionTools` method so the
+        // explicit + implicit registration paths share one
+        // implementation. Idempotent — calling this for the same tool
+        // repeatedly just keeps the same entry in the router's map.
+        (tools) => {
+            this.tools.bindFunctionTools(tools);
+        });
+        this.info = new InfoClient({
+            baseUrl: opts.baseUrl,
+            authProvider: this.authProvider,
+            ...(opts.headers !== undefined ? { headers: opts.headers } : {}),
+            ...(opts.allowInsecureTransport !== undefined
+                ? { allowInsecureTransport: opts.allowInsecureTransport }
+                : {}),
+        });
+        this.specs = new SpecsClient({
+            baseUrl: opts.baseUrl,
+            authProvider: this.authProvider,
+            ...(opts.headers !== undefined ? { headers: opts.headers } : {}),
+            ...(opts.allowInsecureTransport !== undefined
+                ? { allowInsecureTransport: opts.allowInsecureTransport }
+                : {}),
+        });
+        this.pipeline = new PipelineClient(this);
+        this.bulletin = new BulletinClient();
+        this.artifacts = new ArtifactsClient();
+        this.state = new StateClient();
+        this.agents = new AgentsClient();
+    }
+    /**
+     * Open the underlying WebSocket. Idempotent — calling twice without an
+     * intervening `disconnect()` returns the same live connection.
+     *
+     * On a 401/403 from the upgrade, throws `QodoAuthError` with the auth source
+     * named so the caller can fix the right surface (env var, file, or explicit).
+     */
+    async connect() {
+        if (this.connection !== null && this.connection.isOpen)
+            return;
+        if (this.connectInFlight !== null) {
+            await this.connectInFlight;
+            return;
+        }
+        this.authProvider.validate();
+        const { token } = this.authProvider.getAuthConfig();
+        const wsUrl = QodoClient.deriveWsUrl(this.options.baseUrl, this.options.allowInsecureTransport ?? false);
+        const maxPausedQueueSize = this.options.backpressure?.maxPausedQueueSize;
+        const reconnect = this.options.reconnect;
+        const span = this.spanRecorder.startConnectSpan();
+        // Run the WS upgrade inside the connect span's context. The `Connection`
+        // doesn't send any envelopes during `open()` (no traceparent emission to
+        // affect), but consumer code reading `getActiveSpan()` from inside an
+        // `await client.connect()` continuation will see the connect span — so
+        // any custom logging / hooks there nest correctly.
+        this.connectInFlight = span.withContext(async () => {
+            try {
+                return await Connection.open({
+                    factory: this.transportFactory,
+                    url: wsUrl,
+                    headers: { Authorization: `Bearer ${token}` },
+                    traceContext: this.traceContext,
+                    metrics: this.transportMetrics,
+                    ...(maxPausedQueueSize !== undefined ? { maxPausedQueueSize } : {}),
+                    ...(reconnect !== undefined ? { reconnect } : {}),
+                });
+            }
+            catch (err) {
+                if (err instanceof QodoAuthError) {
+                    // Re-throw with the auth-source diagnostic so the user knows where to fix.
+                    this.authProvider.handle401Error();
+                }
+                throw err;
+            }
+        });
+        try {
+            this.connection = await this.connectInFlight;
+            // The `Connection` no longer carries a session id — each
+            // `task.start` creates a server-derived session, and the SDK
+            // tracks `task_id → session_id` per-Task. Connect/disconnect
+            // spans report only that the upgrade succeeded; session
+            // attribution lives on the per-Task `qar.client.task.*` spans
+            // where it actually applies.
+            span.succeed();
+        }
+        catch (err) {
+            span.fail(err);
+            throw err;
+        }
+        finally {
+            this.connectInFlight = null;
+        }
+        // Kick off skills discovery alongside the WS upgrade so the first
+        // `tasks.startWithAgent` / `tasks.startWithGraph` sees a populated
+        // catalog. Errors during discovery don't block connect — the
+        // manager surfaces per-source `sdk.skill.error` events through the
+        // configured telemetry sink.
+        if (this.skills !== undefined) {
+            try {
+                await this.skills.discover();
+            }
+            catch {
+                // best-effort — telemetry already emitted at the manager
+            }
+        }
+        // Bind the tool-tunneling fan-out *after* the connection is committed so
+        // an inbound `tool.request` arriving with zero `onRequest` handlers
+        // deterministically emits `outcome: "denied"` rather than leaving QAR's
+        // agent loop paused on the `tool_call_id`.
+        this.tools._bindConnection(this.connection);
+        // When skills are configured, attach a `tool.request` bridge that
+        // intercepts `qodo-skills.list_skills` / `qodo-skills.get_skill` /
+        // `qodo-skills.get_skill_file` calls and dispatches them through the
+        // registered MCP handler. Bare names (no `qodo-skills.` prefix) are
+        // also matched so QAR deployments routing by short name see the same
+        // surface. Other tool names fall through to consumer-registered
+        // handlers via `client.tools.onRequest(...)`.
+        this.attachSkillsMcpBridge();
+        // Rebuild pooled MCP `Client` entries for any remote/stdio configs
+        // registered before connect (typical happy path — consumer wires
+        // `registerMcp` before `connect()`) AND any that survived a prior
+        // `disconnect()` cycle (pool was dispose()d but registry state
+        // persisted). Idempotent across reconnects.
+        this.qar._rebuildPoolEntries();
+        // Install a lifecycle hook on the registry so the generic
+        // `tool.request` MCP bridge attaches symmetric to remote / stdio MCP
+        // presence. Skipping the attach when zero remote MCPs are registered
+        // preserves `ToolClient`'s "no handler → deterministic deny" path; a
+        // bridge that returns `undefined` for every unresolved call would
+        // shadow the deny fallback. `_installRemoteMcpHook` synchronously
+        // fires `onFirstRegistered` if any remote / stdio MCPs were already
+        // registered pre-connect.
+        this.qar._installRemoteMcpHook({
+            onFirstRegistered: () => this.attachRemoteMcpBridge(),
+            onLastUnregistered: () => this.detachRemoteMcpBridge(),
+        });
+        // Wire the read-only observer sub-clients to the live connection. Each
+        // sub-client keeps its handler registry across connect/disconnect cycles
+        // — `attach` just registers a fresh `InboundSubscription` against the
+        // current `Connection` so envelopes start flowing.
+        this.bulletin.attach(this.connection);
+        this.artifacts.attach(this.connection);
+        this.state.attach(this.connection);
+        this.agents.attach(this.connection);
+    }
+    /**
+     * Subscription token returned by `attachSkillsMcpBridge`. Kept so that
+     * `disconnect()` can clean up the bridge alongside the tool dispatcher.
+     * Initialized to `null` until skills are wired.
+     */
+    skillsMcpBridge = null;
+    /**
+     * Auto-wire a `tool.request` handler that intercepts qodo-skills tool
+     * calls and dispatches them through the registered MCP handler. Skipped
+     * when `skillsMcpServer` is undefined (consumer didn't opt into skills).
+     *
+     * **Tool-name matching.** The qodo-skills MCP exposes three tools:
+     * `list_skills`, `get_skill`, `get_skill_file`. QAR deployments may
+     * surface them either bare or under the `qodo-skills.` server prefix
+     * (the open MCP convention). The bridge accepts both shapes — anything
+     * else falls through to consumer-registered handlers via the normal
+     * `client.tools.onRequest(...)` stack.
+     *
+     * **Why the bridge lives here.** The qodo-skills tools are intrinsic
+     * to the Skills feature, not a generic MCP we registered for the
+     * consumer's convenience — the SDK owns their dispatch end to end.
+     * Auto-wiring the bridge here keeps the consumer's `onRequest` stack
+     * free of skills routing concerns.
+     *
+     * **Symmetric projection auto-include.** The dispatch end
+     * (this bridge) is only half the contract. The other half is the
+     * wire-side surface: `TaskClient.projectMcpToolsForWire` /
+     * `mergeQodoSkillsTools` auto-includes the three
+     * `qodo-skills.list_skills` / `qodo-skills.get_skill` /
+     * `qodo-skills.get_skill_file` entries in every dispatched agent's
+     * `function_tools` list when `ClientOptions.skills` is configured,
+     * regardless of the consumer's `mcpTools.allowlist`. The bridge
+     * matches what the projection advertises; the projection ships what
+     * the slim-index preamble references. Both ends move together — if
+     * you change the tool names here, mirror the change in
+     * `qodoSkillsFunctionToolDefs()` (skills/mcp/server.ts) and the
+     * `BLOCK_PREAMBLE` text (skills/render.ts).
+     *
+     * **Precedence vs. remote MCPs.** The skills bridge is attached
+     * BEFORE the generic remote-MCP bridge in `QodoClient.connect()`, so
+     * its bare-name match on `list_skills` / `get_skill` /
+     * `get_skill_file` wins over a registered remote MCP that happens to
+     * advertise the same name. This is intentional — the qodo-skills
+     * tools are intrinsic to the Skills feature surface and consumers
+     * shouldn't be able to shadow them by registering a same-named remote
+     * MCP. A consumer who legitimately needs to reach a remote MCP's
+     * same-named tool uses the prefix form: `mcp-name.list_skills` (or
+     * `mcp-name:list_skills` / `mcp-name/list_skills`) — the remote-MCP
+     * bridge resolves the prefix form against the registered MCP set, not
+     * against the skills bridge's hardcoded names.
+     */
+    attachSkillsMcpBridge() {
+        const server = this.skillsMcpServer;
+        if (server === undefined)
+            return;
+        if (this.skillsMcpBridge !== null)
+            return;
+        const QODO_SKILLS_TOOLS = new Set(['list_skills', 'get_skill', 'get_skill_file']);
+        const stripPrefix = (name) => {
+            if (QODO_SKILLS_TOOLS.has(name))
+                return name;
+            const prefix = 'qodo-skills.';
+            if (name.startsWith(prefix)) {
+                const bare = name.slice(prefix.length);
+                if (QODO_SKILLS_TOOLS.has(bare))
+                    return bare;
+            }
+            // Some MCP runtimes use a `:` separator (`qodo-skills:list_skills`).
+            const colonPrefix = 'qodo-skills:';
+            if (name.startsWith(colonPrefix)) {
+                const bare = name.slice(colonPrefix.length);
+                if (QODO_SKILLS_TOOLS.has(bare))
+                    return bare;
+            }
+            return undefined;
+        };
+        // Register the skills bridge as a FALLBACK handler so the
+        // dispatcher's "no consumer handler → deterministic deny" path
+        // stays consumer-keyed. SDK auto-bridges are advisory routing
+        // layers, not consumer-side handlers.
+        this.skillsMcpBridge = this.tools._attachFallbackHandler(async (request) => {
+            const calls = request.payload.calls;
+            // Identify which calls (if any) target qodo-skills.
+            const targeting = calls.map((c) => stripPrefix(c.name));
+            if (targeting.every((t) => t === undefined)) {
+                // No qodo-skills calls in this batch — let the consumer's
+                // handler stack process the whole batch.
+                return undefined;
+            }
+            if (targeting.some((t) => t === undefined)) {
+                // Mixed batch (some qodo-skills, some not). `ToolClient`'s
+                // handler stack semantics are "first non-undefined claims the
+                // entire batch" — if we returned a partial array here, every
+                // non-qodo-skills call would be force-denied and consumer
+                // handlers would never run. Better to defer: return `undefined`
+                // so the consumer's handler sees the batch. The consumer is
+                // responsible for routing qodo-skills calls (e.g., by
+                // delegating to `client.skillsMcpServer.callTool` for those
+                // entries).
+                //
+                // QAR's current single-server-per-batch convention means this
+                // path is unreachable in normal operation; the safe-by-default
+                // posture exists so a future QAR routing change doesn't silently
+                // break mixed batches.
+                return undefined;
+            }
+            // All-qodo-skills batch — safe to claim. The handler returns
+            // ToolResponseResult[] positionally matching `calls`; the
+            // ToolClient dispatcher pairs them with each call's tool_call_id
+            // at the wire boundary.
+            const responses = await Promise.all(calls.map(async (call, i) => {
+                const bare = targeting[i];
+                const mcpResult = await server.callTool(bare, call.arguments);
+                if (mcpResult.isError === true) {
+                    const message = mcpResult.content[0]?.type === 'text'
+                        ? mcpResult.content[0].text
+                        : 'qodo-skills tool returned an error';
+                    return { outcome: 'error', error: message };
+                }
+                // Success — serialize the MCP envelope as the tool's JSON
+                // result. QAR's agent loop reads this as the tool response
+                // body. The MCP envelope's `content` array is JSON-cloned so
+                // the wire payload is a plain JsonObject (no Buffers, etc. —
+                // the MCP server already base64-encodes binary content).
+                return {
+                    outcome: 'success',
+                    result: JSON.parse(JSON.stringify(mcpResult)),
+                };
+            }));
+            return responses;
+        });
+    }
+    /**
+     * Subscription token returned by `attachRemoteMcpBridge`. Mirrors
+     * {@link skillsMcpBridge} — kept so `disconnect()` can detach the bridge
+     * alongside the skills variant.
+     */
+    remoteMcpBridge = null;
+    /**
+     * Auto-wire a `tool.request` handler that resolves each call's
+     * `name` against `qar.resolveMcpForTool` and dispatches the resolved set
+     * through {@link QarRegistryClient.callMcpTool} (which round-trips via the
+     * canonical `@modelcontextprotocol/sdk` `Client.callTool`).
+     *
+     * **Claim semantics.** Three batch shapes:
+     *
+     *   - **All-resolved** — every call's name routes to a registered
+     *     remote / stdio MCP. Bridge claims; each call dispatches via
+     *     {@link QarRegistryClient.callMcpTool}; per-call success /
+     *     error responses are returned positionally.
+     *
+     *   - **All-unresolved** — no call routes to any registered MCP.
+     *     Bridge returns `undefined` so consumer-registered
+     *     `client.tools.onRequest(...)` handlers can intercept the
+     *     batch (consumers may legitimately wire unrelated custom tools
+     *     alongside remote MCPs). Consumers who register remote MCPs
+     *     and want unknown-tool calls handled MUST register their own
+     *     `onRequest` handler; otherwise the call waits for QAR's
+     *     per-task tool-response timeout (the documented wire-side safety
+     *     net for the "all handlers returned undefined" case).
+     *
+     *   - **Mixed batch** — some resolved, some not. Returns `undefined`
+     *     so consumer-registered `client.tools.onRequest(...)` handlers
+     *     can intercept. QAR's single-server-per-batch convention means
+     *     this path is unreachable in normal operation; the defer posture
+     *     is the safety hatch for a future QAR routing change that might
+     *     produce mixed batches.
+     *
+     * **Bare-name catalog race.** First-dispatch bare-name resolution
+     * scans the cached `entry.tools` populated by `listTools()` at
+     * `commitEntry` time. A `tool.request` arriving immediately after
+     * `registerMcp` (before connect+listTools resolved) would otherwise
+     * see an empty catalog and fall into the all-unresolved defer path.
+     * The bridge awaits {@link QarRegistryClient._waitForMcpCatalogsToSettle}
+     * before deciding "unresolved" so first-call timing doesn't
+     * mis-classify a legitimate bare-name lookup as unknown.
+     */
+    attachRemoteMcpBridge() {
+        if (this.remoteMcpBridge !== null)
+            return;
+        // No live connection — `ToolClient.onRequest` would throw because the
+        // dispatcher seam can only attach against an open WebSocket. The hook
+        // fires during the connect span; if the user invoked
+        // `qar.registerMcp(... remote ...)` before connect, the bridge attach
+        // happens on the next `connect()` via `_rebuildPoolEntries` →
+        // `_installRemoteMcpHook` ordering. Calls landing here without a live
+        // connection mean the hook fired during reconnect ordering — bail to
+        // let the install cycle complete; subsequent registers re-fire the
+        // hook with the bridge slot still empty.
+        if (this.connection === null)
+            return;
+        // Register the remote-MCP bridge as a FALLBACK handler so
+        // consumer-registered `onRequest` handlers get first claim and the
+        // dispatcher's "no consumer handler → deterministic deny" fallback
+        // fires deterministically when no consumer has wired in a handler.
+        this.remoteMcpBridge = this.tools._attachFallbackHandler(async (request) => {
+            const calls = request.payload.calls;
+            let resolved = calls.map((c) => this.qar.resolveMcpForTool(c.name));
+            if (resolved.some((r) => r === undefined)) {
+                // First-call race protection — if any name failed to resolve,
+                // wait for every pending catalog to settle and re-scan. This
+                // makes the bare-name fallback robust against the
+                // `registerMcp → tool.request` timing window where the
+                // background `listTools()` hasn't populated the cache yet.
+                await this.qar._waitForMcpCatalogsToSettle();
+                resolved = calls.map((c) => this.qar.resolveMcpForTool(c.name));
+            }
+            // Defer ANY batch with at least one unresolved name back to the
+            // consumer's handler stack. Only claim batches that are fully
+            // resolved against the registered MCP set. This preserves
+            // `client.tools.onRequest(...)` ergonomics for consumers who wire
+            // both remote MCPs and hand-crafted handlers for unrelated tools.
+            if (resolved.some((r) => r === undefined)) {
+                return undefined;
+            }
+            const responses = await Promise.all(calls.map(async (call, i) => {
+                const route = resolved[i];
+                try {
+                    const mcpResult = await this.qar.callMcpTool(route.mcpName, route.toolName, call.arguments);
+                    return {
+                        outcome: 'success',
+                        result: JSON.parse(JSON.stringify(mcpResult)),
+                    };
+                }
+                catch (err) {
+                    // MCP convention treats `{ isError: true, content: [...] }`
+                    // as a NORMAL tool result — the structured content is meant
+                    // for the LLM to read + self-correct ("invalid input: missing
+                    // field X"). Collapsing it to a string `outcome:'error'`
+                    // drops the very signal the LLM needs.
+                    //
+                    // `QodoMcpToolError.mcpResult` is populated only on the
+                    // isError-envelope path; the transport-throw path leaves it
+                    // undefined and falls through to `outcome:'error'` with the
+                    // message (the right wire shape for SDK-side failures).
+                    if (err instanceof QodoMcpToolError && err.mcpResult !== undefined) {
+                        return {
+                            outcome: 'success',
+                            result: JSON.parse(JSON.stringify(err.mcpResult)),
+                        };
+                    }
+                    return {
+                        outcome: 'error',
+                        error: err instanceof Error ? err.message : String(err),
+                    };
+                }
+            }));
+            return responses;
+        });
+    }
+    /**
+     * Detach the remote-MCP bridge. Idempotent — safe to call when the
+     * bridge is already detached. Fired both from {@link disconnect} and
+     * from the registry hook when the last remote / stdio MCP is
+     * unregistered (preserves `ToolClient`'s deny fallback for subsequent
+     * `tool.request` envelopes).
+     */
+    detachRemoteMcpBridge() {
+        if (this.remoteMcpBridge === null)
+            return;
+        this.remoteMcpBridge.unsubscribe();
+        this.remoteMcpBridge = null;
+    }
+    /**
+     * Close the underlying WebSocket and abort any in-flight task iterators.
+     * Idempotent.
+     */
+    async disconnect() {
+        if (this.connectInFlight !== null) {
+            try {
+                await this.connectInFlight;
+            }
+            catch {
+                // Connect may have failed; either way we proceed to tear down.
+            }
+        }
+        // Null `this.connection` BEFORE the awaited pool teardown so two
+        // concurrent `disconnect()` calls don't both capture the same live
+        // connection (and emit duplicate disconnect spans / re-detach
+        // observers). `Connection.close()` is idempotent so the
+        // late-capturing call wouldn't double-close, but the duplicate
+        // span emission + redundant observer detach is wasted work worth
+        // avoiding.
+        const conn = this.connection;
+        this.connection = null;
+        // MCP pool teardown + bridge unsubscribe MUST run on every
+        // `disconnect()` call — including the "registered a stdio MCP,
+        // never called connect(), now calling disconnect()" path. Pool
+        // entries are spawned at `registerMcp` time (eager connect), so the
+        // subprocess is alive even before the QAR WebSocket is opened.
+        // Gating pool dispose on the live WS connection leaks subprocesses
+        // + reconnect-timer HTTP keep-alives whenever the consumer
+        // registers MCPs without ever calling connect().
+        //
+        // We run the bridge / pool / skills cleanups BEFORE the WS-state
+        // branch so the never-connected path still reaches them; the WS-state
+        // branch handles span emission + observer-sub-client detach only.
+        if (this.skillsMcpBridge !== null) {
+            this.skillsMcpBridge.unsubscribe();
+            this.skillsMcpBridge = null;
+        }
+        if (this.skillsMcpServer !== undefined) {
+            this.skillsMcpServer.dispose();
+        }
+        this.detachRemoteMcpBridge();
+        this.qar._clearRemoteMcpHook();
+        // Close every pooled MCP `Client` so subprocess MCPs aren't
+        // orphaned and HTTP transports drop their reconnect timers. The registry
+        // itself is process-scoped (not connection-scoped); the next connect()
+        // re-attaches the bridge and the pool will re-register entries lazily
+        // on the next `qar.registerMcp` call. Pool entries currently in the map
+        // ARE disposed — a reconnect after disconnect drops every remote/stdio
+        // registration, mirroring how `skillsMcpServer.dispose()` drops the
+        // skills caches above.
+        await this.qar._disposePool();
+        if (conn === null)
+            return;
+        // No connection-level session_id to attach. The disconnect span
+        // covers transport teardown only; per-Task session attribution is
+        // on the `qar.client.task.*` spans.
+        const span = this.spanRecorder.startDisconnectSpan({});
+        // `this.connection` was already nulled at the top of `disconnect()`
+        // (anti-duplicate-tear-down).
+        // Detach observer sub-clients before closing the connection so their
+        // ports unregister cleanly and the next `connect()` starts with a fresh
+        // `InboundSubscription` registered against the new transport.
+        this.bulletin.detach();
+        this.artifacts.detach();
+        this.state.detach();
+        this.agents.detach();
+        try {
+            span.withContext(() => conn.close());
+            span.succeed();
+        }
+        catch (err) {
+            span.fail(err);
+            throw err;
+        }
+    }
+    /**
+     * Send a raw envelope verbatim. Escape hatch for advanced consumers — most
+     * callers use `tasks.start` / `tasks.continue` / `tools.respond` instead.
+     *
+     * The envelope must already be fully populated:
+     *   - `message_id`, `ts`, `envelope_version`, `trace_context` on every kind
+     *   - `session_id` on every kind EXCEPT `task.start`
+     *
+     * The `task.start` envelope is a `_StartEnvelopeBase` (no `session_id`
+     * on the wire); the type narrowing on {@link TaskStartEnvelope} omits
+     * the field so raw senders cannot compile an invalid `task.start`.
+     * All other kinds inherit `_OngoingEnvelopeBase` and require
+     * `session_id`.
+     *
+     * The connection writes the envelope through the underlying transport
+     * unchanged.
+     */
+    send(envelope) {
+        this.requireConnection().sendRawEnvelope(envelope);
+    }
+    /**
+     * Subscribe to every inbound envelope plus the SDK-internal
+     * `qar.client.*` lifecycle events. The same envelopes that drive
+     * `tasks.start()` iterators flow here too; useful for telemetry / logging /
+     * advanced consumers.
+     *
+     * Yielded type is the union `Envelope | ClientEvent`. `Envelope` arms carry
+     * the wire `kind` discriminators; `ClientEvent` arms carry `qar.client.*`
+     * keys that can never collide with QAR envelope kinds. `switch (ev.kind)`
+     * narrows cleanly between the two.
+     */
+    receive() {
+        const conn = this.requireConnection();
+        const sub = new RawSubscription((s) => conn.unsubscribe(s));
+        conn.subscribe(sub);
+        return sub;
+    }
+    /**
+     * Whether the underlying connection is currently in `flow.pause`.
+     * `false` when not connected — disconnect always resets the flag.
+     *
+     * The SDK obeys backpressure transparently; consumers don't normally need
+     * to check this. It's exposed for richer surfaces (CLIs, UIs) that want to
+     * show a "server overloaded; waiting" indicator. Reading this is cheap and
+     * synchronous.
+     */
+    get isPaused() {
+        return this.connection?.isPaused ?? false;
+    }
+    /** @internal — used by sub-clients to access the live connection. */
+    requireConnection() {
+        if (this.connection === null || !this.connection.isOpen) {
+            throw new Error('QodoClient is not connected. Call await client.connect() first.');
+        }
+        return this.connection;
+    }
+    /**
+     * Synchronous validation of `ClientOptions`. Runs at construction time so
+     * misconfigured callers fail fast instead of at the first `tasks.start`.
+     *
+     * Treats the construction call as a system boundary — JavaScript callers can
+     * pass `null` even though TypeScript bars it, so we check both `undefined`
+     * and `null` and refuse with a typed error rather than letting a subsequent
+     * property access throw an unhelpful `TypeError`.
+     */
+    static validateOptions(opts) {
+        if (typeof opts.baseUrl !== 'string' || opts.baseUrl.length === 0) {
+            throw new QodoClientOptionsError('ClientOptions.baseUrl is required and must be a non-empty string');
+        }
+        if (opts.auth === undefined || opts.auth === null) {
+            throw new QodoClientOptionsError('ClientOptions.auth is required (use "env" or { apiKey })');
+        }
+        if (opts.auth !== 'env') {
+            if (typeof opts.auth !== 'object') {
+                throw new QodoClientOptionsError('ClientOptions.auth must be "env" or an object with an apiKey');
+            }
+            const apiKey = opts.auth.apiKey;
+            if (typeof apiKey !== 'string' || apiKey.length === 0) {
+                throw new QodoClientOptionsError('ClientOptions.auth.apiKey must be a non-empty string');
+            }
+        }
+        // `allowInsecureTransport` gates a security-relevant codepath (sending the
+        // bearer over plaintext). Runtime-validate the type so a JS caller can't
+        // pass a truthy non-boolean (e.g. `'false'`, `1`) and silently bypass the
+        // `https://`-only default. The downstream guards check `!== true` rather
+        // than `!value` for the same reason.
+        if (opts.allowInsecureTransport !== undefined &&
+            typeof opts.allowInsecureTransport !== 'boolean') {
+            throw new QodoClientOptionsError('ClientOptions.allowInsecureTransport must be a boolean (or omitted)');
+        }
+        // Backpressure tuning is optional. When provided, validate at construction
+        // time so JS callers (which TS can't constrain) get a typed error rather
+        // than a coerced cap that silently misbehaves at the throttle boundary.
+        if (opts.backpressure !== undefined && opts.backpressure !== null) {
+            if (typeof opts.backpressure !== 'object') {
+                throw new QodoClientOptionsError('ClientOptions.backpressure must be an object (or omitted)');
+            }
+            const cap = opts.backpressure.maxPausedQueueSize;
+            if (cap !== undefined) {
+                if (typeof cap !== 'number' || !Number.isFinite(cap) || !Number.isInteger(cap) || cap < 1) {
+                    throw new QodoClientOptionsError('ClientOptions.backpressure.maxPausedQueueSize must be a positive integer');
+                }
+            }
+        }
+        // Scheme + insecure-transport validation runs eagerly at construction
+        // so the docs claim ("Construction is synchronous and validates options
+        // eagerly — bad configuration throws `QodoClientOptionsError`
+        // immediately.") matches reality. `connect()` still calls `deriveWsUrl`
+        // to compute the actual WS URL, but the throwing edge moves to
+        // construction time. `deriveWsUrl` is pure; both args are validated
+        // immediately above, so the call is safe.
+        QodoClient.deriveWsUrl(opts.baseUrl, opts.allowInsecureTransport ?? false);
+    }
+    static buildAuthProvider(opts) {
+        if (opts.auth === 'env')
+            return new AuthProvider();
+        return new AuthProvider(opts.auth.apiKey);
+    }
+    /**
+     * Map the consumer-supplied `baseUrl` (typically `https://qar.qodo.ai`) onto
+     * the WS endpoint. `https://` → `wss://`; existing `wss://` is left as-is.
+     * Trailing slashes on `baseUrl` are stripped before joining.
+     *
+     * Insecure schemes (`http://` / `ws://`) are refused unless
+     * `allowInsecureTransport` is `true`. Rationale: `connect()` always sends the
+     * bearer token in the upgrade `Authorization` header — over `ws://` that's
+     * plaintext on the wire. The opt-in keeps local-dev workflows possible
+     * without making credential leakage a default footgun.
+     */
+    static deriveWsUrl(baseUrl, allowInsecureTransport) {
+        // Trim trailing slashes via a bounded character walk rather than the regex
+        // `/\/+$/.replace(...)`. CodeQL flags `\/+$` as a polynomial-redos pattern
+        // (js/polynomial-redos) — even though the actual time complexity is linear
+        // for this anchored single-character class, the engine's regex-pattern
+        // analyzer can't prove that. Walking the end of the string is both safer
+        // and cheaper.
+        let end = baseUrl.length;
+        while (end > 0 && baseUrl.charCodeAt(end - 1) === 0x2f /* '/' */) {
+            end -= 1;
+        }
+        const trimmed = baseUrl.slice(0, end);
+        let wsBase;
+        let insecure = false;
+        if (trimmed.startsWith('https://')) {
+            wsBase = `wss://${trimmed.slice('https://'.length)}`;
+        }
+        else if (trimmed.startsWith('http://')) {
+            wsBase = `ws://${trimmed.slice('http://'.length)}`;
+            insecure = true;
+        }
+        else if (trimmed.startsWith('wss://')) {
+            wsBase = trimmed;
+        }
+        else if (trimmed.startsWith('ws://')) {
+            wsBase = trimmed;
+            insecure = true;
+        }
+        else {
+            throw new QodoClientOptionsError(`ClientOptions.baseUrl must use http(s):// or ws(s)://; got "${baseUrl}"`);
+        }
+        // `!== true` instead of `!value` — `validateOptions` already rejects
+        // non-boolean inputs, but keep the gate strict-equal so a future code
+        // path that bypasses validation can't slip a truthy non-boolean through.
+        if (insecure && allowInsecureTransport !== true) {
+            throw new QodoClientOptionsError(`ClientOptions.baseUrl uses an insecure scheme ("${baseUrl}") which would transmit ` +
+                `the bearer token in plaintext. Use https:// or wss:// in production, or set ` +
+                `allowInsecureTransport: true to opt in for local development.`);
+        }
+        return `${wsBase}/v2/qar/ws/connect`;
+    }
+}
+//# sourceMappingURL=QodoClient.js.map