@qodo/sdk 0.13.4 → 2.0.0-next.0

package/dist/client/mcp/substituteEnv.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `${ENV_VAR}` substitution for MCP header values.
+ *
+ * SDK1 ergonomic — header values like `"Bearer ${HANDBOOK_API_TOKEN}"` are
+ * resolved against `process.env` at connect time so consumers can author
+ * static `mcpServers` configs (typically loaded from disk or embedded in
+ * source) without committing secrets. Preserved verbatim to keep SDK1 →
+ * SDK2 migration ergonomically equivalent for typical MCP-header
+ * substitution use cases.
+ *
+ * Semantics:
+ *   - `${VAR}` references `process.env.VAR`. Unset variables resolve to the
+ *     empty string; this matches shell expansion (`echo "$UNSET"` → `""`)
+ *     and SDK1's behavior.
+ *   - `$VAR` (no braces) is NOT substituted — we keep substitution explicit
+ *     so a literal `$200` in a header isn't accidentally interpreted as a
+ *     reference to `process.env[200]`.
+ *   - `\${VAR}` is an escape — emits the literal `${VAR}` without
+ *     substitution. Useful for the rare case where the header value
+ *     genuinely contains `${...}` literals.
+ *
+ * The implementation is platform-neutral: `process.env` is the only OS
+ * touchpoint. Browsers don't run the MCP bridge (subprocess + arbitrary
+ * fetch authority are server-side concerns), so a Node-only assumption is
+ * fine; the browser shim falls through to identity behavior.
+ */
+/**
+ * Substitute `${VAR}` references in a single string against `process.env`.
+ * Returns the resolved string; unset references collapse to empty.
+ *
+ * `\${VAR}` is the escape form — it emits the literal `${VAR}` so callers
+ * can carry through a value that contains the syntax verbatim.
+ */
+export declare function substituteEnvInString(value: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Substitute `${VAR}` references across every value in a string-keyed map.
+ * Returns a fresh object; the input is not mutated. Keys are passed through
+ * unchanged (header names aren't subject to env substitution).
+ */
+export declare function substituteEnvInHeaders(headers: {
+    readonly [key: string]: string;
+} | undefined, env?: NodeJS.ProcessEnv): {
+    [key: string]: string;
+} | undefined;
+//# sourceMappingURL=substituteEnv.d.ts.map

package/dist/client/mcp/substituteEnv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"substituteEnv.d.ts","sourceRoot":"","sources":["../../../src/client/mcp/substituteEnv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAajG;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GAAG,SAAS,EACvD,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GAAG,SAAS,CAOvC"}

package/dist/client/mcp/substituteEnv.js

@@ -0,0 +1,63 @@
+/**
+ * `${ENV_VAR}` substitution for MCP header values.
+ *
+ * SDK1 ergonomic — header values like `"Bearer ${HANDBOOK_API_TOKEN}"` are
+ * resolved against `process.env` at connect time so consumers can author
+ * static `mcpServers` configs (typically loaded from disk or embedded in
+ * source) without committing secrets. Preserved verbatim to keep SDK1 →
+ * SDK2 migration ergonomically equivalent for typical MCP-header
+ * substitution use cases.
+ *
+ * Semantics:
+ *   - `${VAR}` references `process.env.VAR`. Unset variables resolve to the
+ *     empty string; this matches shell expansion (`echo "$UNSET"` → `""`)
+ *     and SDK1's behavior.
+ *   - `$VAR` (no braces) is NOT substituted — we keep substitution explicit
+ *     so a literal `$200` in a header isn't accidentally interpreted as a
+ *     reference to `process.env[200]`.
+ *   - `\${VAR}` is an escape — emits the literal `${VAR}` without
+ *     substitution. Useful for the rare case where the header value
+ *     genuinely contains `${...}` literals.
+ *
+ * The implementation is platform-neutral: `process.env` is the only OS
+ * touchpoint. Browsers don't run the MCP bridge (subprocess + arbitrary
+ * fetch authority are server-side concerns), so a Node-only assumption is
+ * fine; the browser shim falls through to identity behavior.
+ */
+const ENV_PATTERN = /\\\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/**
+ * Substitute `${VAR}` references in a single string against `process.env`.
+ * Returns the resolved string; unset references collapse to empty.
+ *
+ * `\${VAR}` is the escape form — it emits the literal `${VAR}` so callers
+ * can carry through a value that contains the syntax verbatim.
+ */
+export function substituteEnvInString(value, env = process.env) {
+    return value.replace(ENV_PATTERN, (_match, escaped, ref) => {
+        if (escaped !== undefined) {
+            // Escape sequence — emit literal `${VAR}` without substitution.
+            return `\${${escaped}}`;
+        }
+        if (ref === undefined) {
+            // Defensive — the regex always matches one of the two capture groups.
+            return _match;
+        }
+        const resolved = env[ref];
+        return resolved ?? '';
+    });
+}
+/**
+ * Substitute `${VAR}` references across every value in a string-keyed map.
+ * Returns a fresh object; the input is not mutated. Keys are passed through
+ * unchanged (header names aren't subject to env substitution).
+ */
+export function substituteEnvInHeaders(headers, env = process.env) {
+    if (headers === undefined)
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(headers)) {
+        out[key] = substituteEnvInString(value, env);
+    }
+    return out;
+}
+//# sourceMappingURL=substituteEnv.js.map

package/dist/client/mcp/substituteEnv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"substituteEnv.js","sourceRoot":"","sources":["../../../src/client/mcp/substituteEnv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,WAAW,GAAG,kEAAkE,CAAC;AAEvF;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa,EAAE,MAAyB,OAAO,CAAC,GAAG;IACvF,OAAO,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,MAAM,EAAE,OAA2B,EAAE,GAAuB,EAAE,EAAE;QACjG,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,gEAAgE;YAChE,OAAO,MAAM,OAAO,GAAG,CAAC;QAC1B,CAAC;QACD,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,sEAAsE;YACtE,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1B,OAAO,QAAQ,IAAI,EAAE,CAAC;IACxB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAuD,EACvD,MAAyB,OAAO,CAAC,GAAG;IAEpC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC5C,MAAM,GAAG,GAA8B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,GAAG,CAAC,GAAG,qBAAqB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/client/observers.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Building blocks for the read-only sub-clients that surface QAR's
+ * `bulletin.post`, `artifact.add`, `state.update`, and `agent.spawn`
+ * envelopes to opt-in consumers.
+ *
+ * These sub-clients are observers — they tap inbound envelopes alongside the
+ * `TaskSubscription` chain (so the same envelope still drives the canonical
+ * `AsyncIterable<TaskEvent>` from `client.tasks.start()`). Multiple handlers
+ * per kind are allowed and run in registration order; throws are swallowed
+ * so a misbehaving consumer never crashes the WS loop.
+ */
+import type { Envelope, EnvelopeKind } from '../qar/envelopes.js';
+/**
+ * Token returned by the four `client.{bulletin,artifacts,state,agents}.on*`
+ * methods. `close()` deregisters the handler; subsequent envelopes do not
+ * invoke it. Idempotent.
+ *
+ * Distinct from `Subscription` (`unsubscribe()`) on `ToolClient` — the four
+ * read-only event surfaces use `close()` to mirror QAR's spawn-lifecycle
+ * vocabulary (see `docs/sdk2/event-surfaces.md`).
+ */
+export interface EventSubscription {
+    close(): void;
+}
+/**
+ * Shared base for the four kind-filtered observer sub-clients. Holds the
+ * handler registry; `attach`/`detach` are called by `QodoClient` on
+ * `connect`/`disconnect`. Registrations made before `connect()` are honored
+ * once the WS opens — consumers can wire handlers eagerly during construction.
+ */
+export declare abstract class KindObserverClient<K extends EnvelopeKind, E extends Envelope & {
+    readonly kind: K;
+}> {
+    private readonly kind;
+    private port;
+    private connection;
+    private readonly registrations;
+    protected constructor(kind: K);
+    /**
+     * Called by the port from `close()` / `fail()`. The connection is already
+     * tearing itself down (it cleared its own subscription set), so do NOT
+     * call `unsubscribe` here — just clear the sub-client's pointers so a
+     * later `attach()` against a fresh connection starts cleanly. Guards on
+     * identity in case a stale port from a prior attach cycle fires after
+     * the sub-client already moved on.
+     */
+    private onPortUnbound;
+    /**
+     * Register a handler. The optional `matches` predicate runs per envelope —
+     * sub-classes pass their filter shape through it. Returns an
+     * `EventSubscription` whose `close()` is idempotent.
+     */
+    protected register(handler: (env: E) => void, matches?: (env: E) => boolean): EventSubscription;
+    private dispatch;
+    private logHandlerError;
+}
+//# sourceMappingURL=observers.d.ts.map

package/dist/client/observers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observers.d.ts","sourceRoot":"","sources":["../../src/client/observers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAKlE;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,IAAI,IAAI,CAAC;CACf;AA4ED;;;;;GAKG;AACH,8BAAsB,kBAAkB,CACtC,CAAC,SAAS,YAAY,EACtB,CAAC,SAAS,QAAQ,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;CAAE;IAMnB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJ3C,OAAO,CAAC,IAAI,CAAuC;IACnD,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA8B;IAE5D,SAAS,aAA8B,IAAI,EAAE,CAAC;IA4B9C;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAMrB;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAChB,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,EACzB,OAAO,GAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAoB,GACxC,iBAAiB;IAcpB,OAAO,CAAC,QAAQ;IAgChB,OAAO,CAAC,eAAe;CAqBxB"}

package/dist/client/observers.js

@@ -0,0 +1,203 @@
+/**
+ * Building blocks for the read-only sub-clients that surface QAR's
+ * `bulletin.post`, `artifact.add`, `state.update`, and `agent.spawn`
+ * envelopes to opt-in consumers.
+ *
+ * These sub-clients are observers — they tap inbound envelopes alongside the
+ * `TaskSubscription` chain (so the same envelope still drives the canonical
+ * `AsyncIterable<TaskEvent>` from `client.tasks.start()`). Multiple handlers
+ * per kind are allowed and run in registration order; throws are swallowed
+ * so a misbehaving consumer never crashes the WS loop.
+ */
+import { isThenable } from './internal/thenable.js';
+/**
+ * Inbound subscription that filters by `kind` and fans out to a sub-client's
+ * handler list.
+ *
+ * `Connection.fanout` invokes `consider` on every registered subscription
+ * unconditionally — the boolean return is a leftover hook from an earlier
+ * design and is not used to short-circuit fan-out today. So observer ports
+ * coexist naturally with `TaskSubscription`: the same envelope flows down
+ * both paths without one preventing the other.
+ *
+ * `fail`/`close` notify the owning client through `onUnbound` so it can drop
+ * its `connection`/`port` pointers when the transport tears down without an
+ * explicit `disconnect()`.
+ */
+class KindObserverPort {
+    kind;
+    dispatch;
+    onUnbound;
+    constructor(kind, dispatch, onUnbound) {
+        this.kind = kind;
+        this.dispatch = dispatch;
+        this.onUnbound = onUnbound;
+    }
+    consider(env) {
+        if (env.kind === this.kind) {
+            // Defense-in-depth: even though `dispatch` already routes handler
+            // throws through `logHandlerError`, an exception inside the logger
+            // itself would otherwise escape into `Connection.fanout` and break
+            // every other subscription on this socket. Any throw at this seam is
+            // dropped — there is no recovery surface.
+            try {
+                this.dispatch(env);
+            }
+            catch {
+                // Last-ditch: never let an observer crash the WS dispatch loop.
+            }
+        }
+        // Return value is informational; fan-out on `Connection` does not branch
+        // on it. Kept `false` for consistency with `RawSubscription`'s tap pattern.
+        return false;
+    }
+    // `qar.client.*` reconnect/replay events flow through `client.receive()`
+    // consumers and `TaskSubscription`s, not through observer surfaces
+    // (those are envelope-only — the four QAR envelope kinds the sub-clients
+    // care about). No-op so the interface contract is satisfied without
+    // expanding the public surface.
+    considerClient(_ev) { }
+    fail(_err) {
+        // The `error` envelope is the consumer-facing failure signal; observers
+        // don't surface transport-level failures separately. But we DO need to
+        // tell the owning sub-client that its port is now orphaned, so a future
+        // `attach()` doesn't try to `unsubscribe` from a torn-down connection.
+        this.onUnbound();
+    }
+    close() {
+        // Connection closed cleanly: drop the port reference on the owning
+        // sub-client. Handler registrations stay on the sub-client; the next
+        // `attach()` will create a fresh port.
+        this.onUnbound();
+    }
+}
+/**
+ * Shared base for the four kind-filtered observer sub-clients. Holds the
+ * handler registry; `attach`/`detach` are called by `QodoClient` on
+ * `connect`/`disconnect`. Registrations made before `connect()` are honored
+ * once the WS opens — consumers can wire handlers eagerly during construction.
+ */
+export class KindObserverClient {
+    kind;
+    port = null;
+    connection = null;
+    registrations = [];
+    constructor(kind) {
+        this.kind = kind;
+    }
+    /** @internal — invoked by `QodoClient.connect()`. */
+    attach(connection) {
+        if (this.connection !== null) {
+            // Defensive: a second `attach()` without a `detach()` would leak the
+            // previous port. Drop it cleanly first.
+            this.detach();
+        }
+        const port = new KindObserverPort(this.kind, (env) => this.dispatch(env), () => this.onPortUnbound(port));
+        connection.subscribe(port);
+        this.connection = connection;
+        this.port = port;
+    }
+    /** @internal — invoked by `QodoClient.disconnect()`. */
+    detach() {
+        if (this.connection !== null && this.port !== null) {
+            this.connection.unsubscribe(this.port);
+        }
+        this.connection = null;
+        this.port = null;
+    }
+    /**
+     * Called by the port from `close()` / `fail()`. The connection is already
+     * tearing itself down (it cleared its own subscription set), so do NOT
+     * call `unsubscribe` here — just clear the sub-client's pointers so a
+     * later `attach()` against a fresh connection starts cleanly. Guards on
+     * identity in case a stale port from a prior attach cycle fires after
+     * the sub-client already moved on.
+     */
+    onPortUnbound(port) {
+        if (this.port !== port)
+            return;
+        this.connection = null;
+        this.port = null;
+    }
+    /**
+     * Register a handler. The optional `matches` predicate runs per envelope —
+     * sub-classes pass their filter shape through it. Returns an
+     * `EventSubscription` whose `close()` is idempotent.
+     */
+    register(handler, matches = () => true) {
+        const reg = { handler, matches };
+        this.registrations.push(reg);
+        let closed = false;
+        return {
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                const idx = this.registrations.indexOf(reg);
+                if (idx !== -1)
+                    this.registrations.splice(idx, 1);
+            },
+        };
+    }
+    dispatch(env) {
+        // Snapshot so a handler that closes its own subscription (or registers a
+        // sibling) doesn't disturb the in-flight iteration.
+        const snapshot = [...this.registrations];
+        for (const reg of snapshot) {
+            let isMatch;
+            try {
+                isMatch = reg.matches(env);
+            }
+            catch (err) {
+                // A throwing predicate is a consumer bug, not a transport bug. Treat
+                // it the same as a throwing handler: log + skip, keep the WS alive.
+                this.logHandlerError(err);
+                continue;
+            }
+            if (!isMatch)
+                continue;
+            // Both synchronous throws AND async (Promise) rejections must be
+            // routed through `logHandlerError` so the documented "handler failures
+            // are swallowed" guarantee holds for `async` consumers too. The
+            // try/catch covers sync; the `isThenable` branch covers async without
+            // allocating a Promise wrapper for every synchronous handler call —
+            // dispatch is on the WS hot path, so the per-call cost matters.
+            try {
+                const ret = reg.handler(env);
+                if (isThenable(ret)) {
+                    ret.then(undefined, (err) => this.logHandlerError(err));
+                }
+            }
+            catch (err) {
+                this.logHandlerError(err);
+            }
+        }
+    }
+    logHandlerError(err) {
+        // The "handler failures are swallowed" guarantee extends to the logger
+        // itself. A hostile `Error` whose `stack`/`message` getters throw, or a
+        // user-overridden `console.error` that throws, would otherwise escape
+        // into `KindObserverPort.consider` and onward into `Connection.fanout`.
+        // Wrap the body so the library never crashes the WS loop just to print a
+        // diagnostic.
+        try {
+            const msg = err instanceof Error ? err.stack ?? err.message : String(err);
+            console.error(`[@qodo/sdk] ${this.kind} handler threw — swallowed: ${msg}`);
+        }
+        catch {
+            try {
+                // Fallback: print without `String(err)` / message extraction in case
+                // `err` itself is the throwing party.
+                console.error(`[@qodo/sdk] ${this.kind} handler threw — swallowed (logger error)`);
+            }
+            catch {
+                // Even the fallback failed (e.g. a fully wedged `console`). Drop
+                // silently — the priority is keeping dispatch alive.
+            }
+        }
+    }
+}
+// `isThenable` lives in `./internal/thenable.ts` so `ToolClient.ts` and
+// this module share one canonical implementation — diverging copies were
+// a maintenance trap.
+//# sourceMappingURL=observers.js.map

package/dist/client/observers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observers.js","sourceRoot":"","sources":["../../src/client/observers.ts"],"names":[],"mappings":"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"}

package/dist/client/options.d.ts

@@ -0,0 +1,269 @@
+/**
+ * Construction options for `QodoClient` and friends.
+ *
+ * Strict — no `any` at the public surface. Optional fields that may grow over
+ * time (e.g. `headers`, `transport`) carry an index-signature-free interface so
+ * adding a key is a SemVer-additive change rather than a silent extension.
+ */
+import type { OTelAPI } from '../tracing/types.js';
+import type { MessageId, SessionId } from '../qar/ids.js';
+import type { WSTransportFactory } from './transport.js';
+import type { SkillsConfig, SkillSpecifier } from '../skills/types.js';
+/**
+ * Auth strategy passed to the client.
+ *
+ * `'env'` reads `QODO_API_KEY` (and falls back to `~/.qodo/auth.key`) via the
+ * existing `AuthProvider`; explicit `{ apiKey }` uses the literal value.
+ *
+ * No environment selector beyond this — 2.0 talks to QAR only. The endpoint
+ * itself is `baseUrl`.
+ */
+export type ClientAuth = 'env' | {
+    readonly apiKey: string;
+};
+/** Connection-level retry / backoff hints. */
+export interface ClientReconnectOptions {
+    /** Hard cap on reconnect attempts before the iterator throws. */
+    readonly maxAttempts?: number;
+    /** Initial backoff delay in milliseconds. */
+    readonly initialBackoffMs?: number;
+    /** Backoff multiplier applied each attempt. */
+    readonly backoffMultiplier?: number;
+}
+/**
+ * App-level backpressure tuning. QAR emits `flow.pause` when its
+ * per-session in-flight envelope counter crosses the high watermark; the SDK
+ * queues subsequent `task.start` / `task.continue` until `flow.resume`
+ * arrives. `tool.response` and `task.cancel` ignore the pause — the server is
+ * either awaiting them (tool answer) or the user wants out (cancel).
+ */
+export interface ClientBackpressureOptions {
+    /**
+     * Soft cap on the number of envelopes the SDK will hold in its paused queue.
+     * Past this, public-API calls reject with `QodoBackpressureError`. Default
+     * `100`. Healthy traffic typically queues 0–2 envelopes; reaching the cap
+     * means the consumer is driving far above QAR's in-flight ceiling.
+     */
+    readonly maxPausedQueueSize?: number;
+}
+/**
+ * Construction options for `QodoClient`.
+ *
+ * Required: `baseUrl` (the QAR deployment), `auth`. Everything else is optional.
+ */
+export interface ClientOptions {
+    /**
+     * Base URL of the QAR deployment, e.g. `https://qar.qodo.ai`. The client
+     * derives the WS endpoint (`wss://<base>/v2/qar/ws/connect`) and HTTP routes
+     * (`<base>/v1/info`, `<base>/v1/auth/me`, …) from this.
+     */
+    readonly baseUrl: string;
+    /** How to obtain the bearer token. */
+    readonly auth: ClientAuth;
+    /**
+     * Optional OTel API surface (typically `import * as otel from '@opentelemetry/api'`).
+     *
+     * If provided, the client emits `qar.client.*` spans and propagates W3C
+     * Trace Context on every outbound envelope. If omitted, the client
+     * no-ops cleanly — no warnings, no bundled fallback TracerProvider.
+     */
+    readonly otel?: OTelAPI;
+    /** Reconnect / backoff hints. */
+    readonly reconnect?: ClientReconnectOptions;
+    /** App-level backpressure tuning. */
+    readonly backpressure?: ClientBackpressureOptions;
+    /**
+     * Extra HTTP headers attached to non-WS calls (`/v1/info`, `/v1/auth/me`, …).
+     * The bearer header is set automatically from `auth`.
+     */
+    readonly headers?: {
+        readonly [name: string]: string;
+    };
+    /**
+     * Override the WebSocket transport factory.
+     *
+     * Default: `defaultTransportFactory`, which opens a real WS connection via the
+     * `ws` package. Tests inject a fake factory to avoid the network. Useful for
+     * consumers running in environments where `ws` doesn't fit (e.g. browsers
+     * with the WHATWG WebSocket — they'd write a thin adapter here).
+     */
+    readonly transport?: WSTransportFactory;
+    /**
+     * Skills foundation config. When provided, the client builds a
+     * `SkillsManager` at construction; `tasks.startWithAgent` and
+     * `tasks.startWithGraph` auto-inject a slim `<available_skills>` block
+     * into inline-agent instructions before the envelope hits the wire.
+     *
+     * Omit to disable; pass `{ sources: [] }` to opt in to the manager
+     * surface but ship no skills. The block lands inside the consumer's
+     * existing instructions text — a first-class `available_skills` wire
+     * field is a follow-up.
+     */
+    readonly skills?: SkillsConfig;
+    /**
+     * Opt in to sending the bearer token over an insecure (`http://` / `ws://`)
+     * transport.
+     *
+     * `connect()` always emits the `Authorization: Bearer <token>` header on the
+     * upgrade. Over `ws://` that header is plaintext on the wire — a passive
+     * observer can capture the token. The default rejects insecure URLs in
+     * `connect()` (before the upgrade actually happens) so the failure surfaces
+     * with a typed `QodoClientOptionsError` and the bearer is never sent.
+     *
+     * Set to `true` for **local development only** (e.g. `ws://localhost:8000`
+     * against a dev QAR). Production consumers must use `wss://`.
+     *
+     * Default: `false`.
+     */
+    readonly allowInsecureTransport?: boolean;
+}
+/** Per-task options forwarded to `tasks.start` / `tasks.continue`. */
+export interface TaskOptions {
+    /**
+     * Abort signal for cooperative cancellation. The iterator stops yielding and
+     * an in-flight task is cancelled via `task.cancel`.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Caller-pinned skills for this run. Each entry is a bare name,
+     * vendor/name, or vendor/name@version specifier; the SkillsManager
+     * resolves and marks them `[loaded]` in the slim index. Unresolved
+     * names throw `SkillNotFoundError` synchronously. `undefined` falls
+     * back to `SkillsConfig.activate`; `[]` is "explicitly pinned nothing"
+     * (overrides constructor default).
+     *
+     * Records the pinned set in the slim index; runtime body injection
+     * (the L1 caller-pinned activation path) is provided by the
+     * `qodo-skills` MCP server.
+     */
+    readonly skills?: readonly SkillSpecifier[];
+    /**
+     * "Current file" context for the `paths:` filter. Consumers without a
+     * current-file concept omit this; the renderer treats `paths:` as
+     * no-op for those skills.
+     */
+    readonly skillsCurrentFile?: string;
+    /**
+     * Optional caller-supplied work-unit identity for cross-pod session
+     * serialization on the deterministic-key path.
+     *
+     * When OMITTED (default), QAR mints a fresh `uuidv7()` and derives
+     * `session_id` from that — every `task.start` call produces a unique
+     * session_id and no two pods coordinate. This is the **DX default** —
+     * the right shape for one-shot scripts, CLI tools, single-process
+     * consumers, and any caller that doesn't need cross-pod coordination.
+     *
+     * When PRESENT, QAR derives `session_id = uuidv5(QAR_NS_V1,
+     * tenant_id + ":" + idempotencyKey)`. Two pods receiving the same
+     * `(tenant_id, idempotencyKey)` derive the same `session_id` and
+     * serialize on the same lease key (`qar.session_runs`) — the basis
+     * for Slack-thread-per-pod, PR-per-pod, customer-issue-per-pod
+     * scale-out topologies. Encode your app-level fine scope INTO the
+     * string:
+     *
+     *   - Slack threads: `${teamId}:${channelId}:${threadTs}` (or
+     *     `${teamId}:dm:${userId}` for DM fallback)
+     *   - GitHub PRs: `${owner}/${repo}:pr:${prNumber}`
+     *   - Customer issues: `${customerId}:${issueId}`
+     *
+     * **Validation** (mirrors QAR's `Field(min_length=1, max_length=512,
+     * pattern=r"^[^\x00]+$")`): 1–512 **Unicode code points** (NOT bytes
+     * — counted with `[...str].length`), no NUL byte. Invalid values
+     * throw {@link QodoIdempotencyKeyValidationError} synchronously,
+     * before the wire write.
+     *
+     * **Anti-patterns**:
+     *   - `idempotencyKey = Date.now()` — looks deterministic, collides
+     *     on rapid-fire calls within clock resolution.
+     *   - `idempotencyKey = randomUUID()` / fresh random per call — works
+     *     correctly (every call gets a unique session_id) but defeats
+     *     the purpose; omit the field and let the server mint instead.
+     *
+     * **Lost-ack retry contract** (mandatory): the omitted-key path is
+     * **non-idempotent** across `task.start` retries. If the client
+     * issues `task.start` without `idempotencyKey`, doesn't receive the
+     * `task.started` ack (transport drop, timeout), and naively retries,
+     * the server mints a NEW uuidv7 and a SECOND fresh session starts.
+     * The SDK MUST NOT silently retry an uncertain `task.start` without
+     * a sticky key. Consumers requiring lost-ack idempotent retry MUST
+     * pass a deterministic key (domain-derived or a sticky per-attempt
+     * UUIDv7). A Phase-2 `attemptKey()` helper that codifies the
+     * sticky-per-attempt pattern is tracked separately.
+     */
+    readonly idempotencyKey?: string;
+    /**
+     * Explicit cold-address `session_id`.
+     *
+     * Meaningful only for `tasks.continue` (and via {@link ResubscribeOptions}
+     * for `tasks.resubscribe`). On `tasks.start` this field is IGNORED at
+     * both the wire and span layers:
+     *   - The wire envelope strips `session_id` (admission CREATES the
+     *     session); a caller-supplied value cannot reach the server.
+     *   - SDK-side span attribution (`subscribeAndSend`) explicitly gates
+     *     this field on `outbound.kind !== 'task.start'` so a stale caller
+     *     value can't pollute the `task.start` span's `qar.session_id`
+     *     attribute before the server-derived id arrives via the
+     *     `task.started` ack.
+     *
+     * Pass the value the SDK previously exposed on `await stream.sessionId`
+     * (or persisted alongside the `taskId` from a prior admission) when
+     * reusing the `taskId` across processes.
+     *
+     * When OMITTED on a continue call, the SDK looks up the per-Task
+     * session captured from the in-process `task.started` ack. If neither
+     * a captured session nor an explicit override is available, the SDK
+     * throws {@link QodoColdAddressError} synchronously BEFORE the wire
+     * write — the doctrinal correct shape for cross-process recovery,
+     * replacing a zero-UUID sentinel that would otherwise send a rejected
+     * frame to the wire.
+     */
+    readonly sessionId?: SessionId;
+}
+/**
+ * Options for `tasks.cancel`. The payload arg already carries the cancel
+ * reason; this options bag is for control fields (abort signal,
+ * cold-address `sessionId`).
+ */
+export interface TaskCancelOptions {
+    /** Abort signal for cooperative cancellation of the cancel itself. */
+    readonly signal?: AbortSignal;
+    /**
+     * Explicit cold-address `session_id` for cancelling a task across
+     * processes. Same semantics as the `sessionId` field on {@link TaskOptions}:
+     * required when the `taskId` was hydrated from durable storage rather
+     * than observed from an in-process `task.started`.
+     */
+    readonly sessionId?: SessionId;
+}
+/**
+ * Options for `tools.respond`. Today carries only the cold-address
+ * `sessionId` override; an explicit options bag is the right shape for
+ * future control fields (e.g. per-call abort, span overrides) without
+ * breaking the existing overload signature.
+ */
+export interface ToolRespondOptions {
+    /**
+     * Explicit cold-address `session_id` for responding to a `tool_call_id`
+     * whose originating `tool.request` was never observed in this process
+     * (cross-process HITL flow: a long-running approval lands on a
+     * different SDK instance than the one that emitted the request).
+     */
+    readonly sessionId?: SessionId;
+}
+/**
+ * Options for `tasks.resubscribe`. Mirrors `TaskResubscribePayload` so consumers
+ * can hand the same shape they'd hand the wire.
+ */
+export interface ResubscribeOptions extends TaskOptions {
+    /**
+     * The most recent `message_id` the client has already observed. QAR replays
+     * from immediately after this point (server-side per-session ring buffer,
+     * cap 1000 envelopes per the design doc).
+     *
+     * Maps to `since_message_id` on the wire when the client encodes the
+     * envelope. Branded `MessageId` so consumers can't accidentally pass a
+     * `TaskId` / `SessionId` here.
+     */
+    readonly sinceMessageId?: MessageId;
+}
+//# sourceMappingURL=options.d.ts.map

package/dist/client/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/client/options.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,8CAA8C;AAC9C,MAAM,WAAW,sBAAsB;IACrC,iEAAiE;IACjE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,6CAA6C;IAC7C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,+CAA+C;IAC/C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAE1B;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAExB,iCAAiC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC;IAE5C,qCAAqC;IACrC,QAAQ,CAAC,YAAY,CAAC,EAAE,yBAAyB,CAAC;IAElD;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAEvD;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAExC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAE/B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAC3C;AAED,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAE5C;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8CG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAEjC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,CAAC;CACrC"}