@qodo/sdk 0.13.4 → 2.0.0-next.1

package/dist/client/BulletinClient.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `BulletinClient` — observer for QAR's `bulletin.post` envelopes.
+ *
+ * Bulletins are the wire shape behind multi-agent coordination: agents
+ * publish findings on a shared board so peers can react without coupling
+ * directly. The SDK side is read-only — consumers (Studio, dashboards) opt
+ * into the stream; agents do not push bulletins from the client.
+ *
+ * The payload is `JsonObject`-shaped (the upstream type tightens once
+ * QAR's bulletin work tightens). The filter helper below matches
+ * against the two well-known fields QAR's runtime emits today
+ * (`topic`, `agent_id`); they're optional and best-effort — a bulletin
+ * lacking the field never matches the filter.
+ */
+import type { BulletinPostEnvelope } from '../qar/envelopes.js';
+import { KindObserverClient } from './observers.js';
+import type { EventSubscription } from './observers.js';
+/**
+ * Best-effort filter for `bulletin.post` envelopes. Each field, when set,
+ * must equal the same-named field in the envelope payload. Bulletins whose
+ * payload omits a filtered field do not match.
+ */
+export interface BulletinFilter {
+    /** Match against `payload.topic` (QAR convention for board partitioning). */
+    readonly topic?: string;
+    /** Match against `payload.agent_id` (the agent that posted the finding). */
+    readonly agent_id?: string;
+}
+export type BulletinHandler = (env: BulletinPostEnvelope) => void;
+export declare class BulletinClient extends KindObserverClient<'bulletin.post', BulletinPostEnvelope> {
+    /**
+     * Register a handler invoked for every inbound `bulletin.post` envelope.
+     *
+     * Multiple handlers per client are allowed; they fire in registration order.
+     * A handler that throws is logged and the dispatch loop continues — the WS
+     * stream is not affected. The returned `EventSubscription`'s `close()`
+     * deregisters the handler.
+     *
+     * The two-arg overload accepts a `BulletinFilter`; only envelopes whose
+     * payload matches every set field invoke the handler.
+     */
+    onFinding(handler: BulletinHandler): EventSubscription;
+    onFinding(filter: BulletinFilter, handler: BulletinHandler): EventSubscription;
+}
+//# sourceMappingURL=BulletinClient.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BulletinClient.d.ts","sourceRoot":"","sources":["../../src/client/BulletinClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,oBAAoB,KAAK,IAAI,CAAC;AAElE,qBAAa,cAAe,SAAQ,kBAAkB,CAAC,eAAe,EAAE,oBAAoB,CAAC;IAM3F;;;;;;;;;;OAUG;IACI,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,iBAAiB;IACtD,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,eAAe,GAAG,iBAAiB;CActF"}

package/dist/client/BulletinClient.js

@@ -0,0 +1,51 @@
+/**
+ * `BulletinClient` — observer for QAR's `bulletin.post` envelopes.
+ *
+ * Bulletins are the wire shape behind multi-agent coordination: agents
+ * publish findings on a shared board so peers can react without coupling
+ * directly. The SDK side is read-only — consumers (Studio, dashboards) opt
+ * into the stream; agents do not push bulletins from the client.
+ *
+ * The payload is `JsonObject`-shaped (the upstream type tightens once
+ * QAR's bulletin work tightens). The filter helper below matches
+ * against the two well-known fields QAR's runtime emits today
+ * (`topic`, `agent_id`); they're optional and best-effort — a bulletin
+ * lacking the field never matches the filter.
+ */
+import { KindObserverClient } from './observers.js';
+export class BulletinClient extends KindObserverClient {
+    /** @internal — instantiated by `QodoClient`. */
+    constructor() {
+        super('bulletin.post');
+    }
+    onFinding(filterOrHandler, maybeHandler) {
+        if (typeof filterOrHandler === 'function') {
+            return this.register(filterOrHandler);
+        }
+        if (maybeHandler === undefined) {
+            throw new Error('BulletinClient.onFinding: handler is required when a filter is supplied');
+        }
+        const filter = filterOrHandler;
+        return this.register(maybeHandler, (env) => bulletinMatches(env, filter));
+    }
+}
+function bulletinMatches(env, filter) {
+    // Filter helpers are best-effort — a malformed payload (null, primitive,
+    // array) or a hostile property getter must behave like a non-match rather
+    // than throwing inside the predicate and getting logged as a handler error.
+    try {
+        const payload = env.payload;
+        if (payload === null || typeof payload !== 'object')
+            return false;
+        const obj = payload;
+        if (filter.topic !== undefined && obj.topic !== filter.topic)
+            return false;
+        if (filter.agent_id !== undefined && obj.agent_id !== filter.agent_id)
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=BulletinClient.js.map

package/dist/client/BulletinClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BulletinClient.js","sourceRoot":"","sources":["../../src/client/BulletinClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAiBpD,MAAM,OAAO,cAAe,SAAQ,kBAAyD;IAC3F,gDAAgD;IAChD;QACE,KAAK,CAAC,eAAe,CAAC,CAAC;IACzB,CAAC;IAeM,SAAS,CACd,eAAiD,EACjD,YAA8B;QAE9B,IAAI,OAAO,eAAe,KAAK,UAAU,EAAE,CAAC;YAC1C,OAAO,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;QACxC,CAAC;QACD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,yEAAyE,CAAC,CAAC;QAC7F,CAAC;QACD,MAAM,MAAM,GAAG,eAAe,CAAC;QAC/B,OAAO,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5E,CAAC;CACF;AAED,SAAS,eAAe,CAAC,GAAyB,EAAE,MAAsB;IACxE,yEAAyE;IACzE,0EAA0E;IAC1E,4EAA4E;IAC5E,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,GAAG,CAAC,OAAkB,CAAC;QACvC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAClE,MAAM,GAAG,GAAG,OAAkC,CAAC;QAC/C,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,KAAK,KAAK,MAAM,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QAC3E,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAC;QACpF,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/client/InfoClient.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `InfoClient` — backed by `GET /v1/info` and `GET /v1/auth/me` on QAR.
+ *
+ * Both surfaces are HTTP-not-WS: the consumer can call them before opening a
+ * WebSocket (e.g. to discover the bootstrap document, or to confirm identity
+ * before kicking off a task). The implementation reuses the bearer resolved
+ * by `AuthProvider` so Studio / IDE-extension consumers don't have to thread
+ * the token themselves.
+ *
+ * No caching at this layer — consumers that want it (Studio's tool inventory
+ * panel) wrap the call themselves. The wire-level rate-limit policy lives on
+ * `QARInfo.rate_limits` as a per-route map.
+ */
+import type { QARInfo, LeanPrincipal } from '../qar/info.js';
+export declare class InfoClient {
+    private readonly baseUrl;
+    private readonly allowInsecureTransport;
+    private readonly authProvider;
+    private readonly extraHeaders;
+    private readonly fetchImpl;
+    private cachedHttpBase;
+    /**
+     * Fetch the bootstrap document. Calls `GET <baseUrl>/v1/info`.
+     *
+     * The result is intentionally not cached at this layer — consumers who want
+     * caching wrap the call themselves. Rate-limit data lives on
+     * `QARInfo.rate_limits` as a per-route map.
+     *
+     * Throws `QodoAuthError` on 401/403 (with the auth source named in the
+     * message), and a plain `Error` on any other non-2xx response.
+     */
+    get(): Promise<QARInfo>;
+    /**
+     * Fetch the resolved principal via `GET <baseUrl>/v1/auth/me`.
+     *
+     * Bearer-token auth flows here unchanged from 1.x — the same path, the same
+     * `LeanPrincipal` shape. Throws `QodoAuthError` on 401/403.
+     */
+    me(): Promise<LeanPrincipal>;
+    private request;
+    /**
+     * URL parsing is lazy on purpose: `QodoClient.validateOptions` only checks
+     * `baseUrl` is a non-empty string. Eager derivation would change behavior
+     * for callers who construct a client with an invalid scheme but never call
+     * any HTTP method. Cache the result so repeated calls don't re-parse.
+     */
+    private requireHttpBase;
+    private static readBodySafely;
+    /**
+     * Map the consumer-supplied `baseUrl` (typically `https://qar.qodo.ai` or
+     * `wss://qar.qodo.ai`) onto the HTTP origin used for `/v1/info` and
+     * `/v1/auth/me`. Symmetric with `QodoClient.deriveWsUrl`: trailing slashes
+     * are stripped, `wss://` → `https://`, `ws://` → `http://` (gated by
+     * `allowInsecureTransport`).
+     */
+    private static deriveHttpBaseUrl;
+}
+//# sourceMappingURL=InfoClient.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"InfoClient.d.ts","sourceRoot":"","sources":["../../src/client/InfoClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAe7D,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAU;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsC;IACnE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,cAAc,CAAuB;IAW7C;;;;;;;;;OASG;IACU,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC;IAIpC;;;;;OAKG;IACU,EAAE,IAAI,OAAO,CAAC,aAAa,CAAC;YAI3B,OAAO;IAwBrB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;mBASF,cAAc;IAUnC;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;CAgCjC"}

package/dist/client/InfoClient.js

@@ -0,0 +1,135 @@
+/**
+ * `InfoClient` — backed by `GET /v1/info` and `GET /v1/auth/me` on QAR.
+ *
+ * Both surfaces are HTTP-not-WS: the consumer can call them before opening a
+ * WebSocket (e.g. to discover the bootstrap document, or to confirm identity
+ * before kicking off a task). The implementation reuses the bearer resolved
+ * by `AuthProvider` so Studio / IDE-extension consumers don't have to thread
+ * the token themselves.
+ *
+ * No caching at this layer — consumers that want it (Studio's tool inventory
+ * panel) wrap the call themselves. The wire-level rate-limit policy lives on
+ * `QARInfo.rate_limits` as a per-route map.
+ */
+import { QodoClientOptionsError } from './errors.js';
+export class InfoClient {
+    baseUrl;
+    allowInsecureTransport;
+    authProvider;
+    extraHeaders;
+    fetchImpl;
+    cachedHttpBase = null;
+    /** @internal — constructed by `QodoClient`. */
+    constructor(deps) {
+        this.baseUrl = deps.baseUrl;
+        this.allowInsecureTransport = deps.allowInsecureTransport ?? false;
+        this.authProvider = deps.authProvider;
+        this.extraHeaders = deps.headers ?? {};
+        this.fetchImpl = deps.fetchImpl ?? ((input, init) => fetch(input, init));
+    }
+    /**
+     * Fetch the bootstrap document. Calls `GET <baseUrl>/v1/info`.
+     *
+     * The result is intentionally not cached at this layer — consumers who want
+     * caching wrap the call themselves. Rate-limit data lives on
+     * `QARInfo.rate_limits` as a per-route map.
+     *
+     * Throws `QodoAuthError` on 401/403 (with the auth source named in the
+     * message), and a plain `Error` on any other non-2xx response.
+     */
+    async get() {
+        return this.request('/v1/info');
+    }
+    /**
+     * Fetch the resolved principal via `GET <baseUrl>/v1/auth/me`.
+     *
+     * Bearer-token auth flows here unchanged from 1.x — the same path, the same
+     * `LeanPrincipal` shape. Throws `QodoAuthError` on 401/403.
+     */
+    async me() {
+        return this.request('/v1/auth/me');
+    }
+    async request(path) {
+        this.authProvider.validate();
+        const { token } = this.authProvider.getAuthConfig();
+        const url = `${this.requireHttpBase()}${path}`;
+        const response = await this.fetchImpl(url, {
+            method: 'GET',
+            headers: {
+                ...this.extraHeaders,
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/json',
+            },
+        });
+        if (response.status === 401 || response.status === 403) {
+            this.authProvider.handle401Error();
+        }
+        if (!response.ok) {
+            const body = await InfoClient.readBodySafely(response);
+            throw new Error(`GET ${path} failed: ${response.status} ${response.statusText}${body ? ` — ${body}` : ''}`);
+        }
+        return (await response.json());
+    }
+    /**
+     * URL parsing is lazy on purpose: `QodoClient.validateOptions` only checks
+     * `baseUrl` is a non-empty string. Eager derivation would change behavior
+     * for callers who construct a client with an invalid scheme but never call
+     * any HTTP method. Cache the result so repeated calls don't re-parse.
+     */
+    requireHttpBase() {
+        if (this.cachedHttpBase !== null)
+            return this.cachedHttpBase;
+        this.cachedHttpBase = InfoClient.deriveHttpBaseUrl(this.baseUrl, this.allowInsecureTransport);
+        return this.cachedHttpBase;
+    }
+    static async readBodySafely(response) {
+        try {
+            const text = await response.text();
+            return text.length > 512 ? `${text.slice(0, 512)}…` : text;
+        }
+        catch {
+            // Body read errors are non-actionable here — caller already has status / statusText.
+            return '';
+        }
+    }
+    /**
+     * Map the consumer-supplied `baseUrl` (typically `https://qar.qodo.ai` or
+     * `wss://qar.qodo.ai`) onto the HTTP origin used for `/v1/info` and
+     * `/v1/auth/me`. Symmetric with `QodoClient.deriveWsUrl`: trailing slashes
+     * are stripped, `wss://` → `https://`, `ws://` → `http://` (gated by
+     * `allowInsecureTransport`).
+     */
+    static deriveHttpBaseUrl(baseUrl, allowInsecureTransport) {
+        let end = baseUrl.length;
+        while (end > 0 && baseUrl.charCodeAt(end - 1) === 0x2f /* '/' */) {
+            end -= 1;
+        }
+        const trimmed = baseUrl.slice(0, end);
+        let httpBase;
+        let insecure = false;
+        if (trimmed.startsWith('https://')) {
+            httpBase = trimmed;
+        }
+        else if (trimmed.startsWith('http://')) {
+            httpBase = trimmed;
+            insecure = true;
+        }
+        else if (trimmed.startsWith('wss://')) {
+            httpBase = `https://${trimmed.slice('wss://'.length)}`;
+        }
+        else if (trimmed.startsWith('ws://')) {
+            httpBase = `http://${trimmed.slice('ws://'.length)}`;
+            insecure = true;
+        }
+        else {
+            throw new QodoClientOptionsError(`ClientOptions.baseUrl must use http(s):// or ws(s)://; got "${baseUrl}"`);
+        }
+        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 httpBase;
+    }
+}
+//# sourceMappingURL=InfoClient.js.map

package/dist/client/InfoClient.js.map

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

package/dist/client/PipelineClient.d.ts

@@ -0,0 +1,162 @@
+/**
+ * `PipelineClient` — pipeline DSL surface, refactored against the SDK 2.0 task primitive.
+ *
+ * The pipeline DSL chains user lambdas that typically call
+ * `client.tasks.start(...)` under the hood. The 1.x pipeline runner
+ * (which wrapped `QodoSDK.run`) is gone.
+ *
+ * The DSL is intentionally pure orchestration — each step is a TypeScript async
+ * function. Steps that want to talk to QAR call `client.tasks.start(...)`
+ * (exposed on the step context) and await the result. No new wire shape;
+ * the pipeline runner is a state machine over a sequence of immutable
+ * entries.
+ *
+ * The builder is immutable on each chain call so consumers can fork a
+ * partial pipeline safely.
+ */
+import type { JsonObject } from '../qar/json.js';
+import type { QodoClient } from './QodoClient.js';
+/**
+ * One step in a pipeline. The closure receives a typed context carrying the
+ * accumulated state, the execution id, the step name, and the owning
+ * {@link QodoClient}. Returning a JSON-shaped object patches the state for
+ * downstream steps; returning `undefined` (or an empty object) leaves state
+ * unchanged.
+ *
+ * Strict typing on the return is deliberate: pipeline state is a public
+ * concept that consumer code inspects, so we don't widen to `any`.
+ */
+export type PipelineStepFn = (ctx: PipelineStepContext) => JsonObject | void | Promise<JsonObject | void>;
+/** Context passed to each step's closure. */
+export interface PipelineStepContext {
+    /** Accumulated state from prior steps. */
+    readonly state: JsonObject;
+    /** The pipeline's per-execution correlation id (UUIDv7-shaped). */
+    readonly executionId: string;
+    /** Step name, set by the builder. */
+    readonly stepName: string;
+    /**
+     * The {@link QodoClient} the pipeline was built from. Exposed so step
+     * closures can call `client.tasks.start(...)` (or any other sub-client)
+     * without closing over an external variable. Matches the 1.x DSL convention
+     * (`{ sdk, state }`).
+     */
+    readonly client: QodoClient;
+}
+/**
+ * A gate predicate evaluated between steps. The return value is coerced with
+ * `Boolean(...)` — anything truthy continues the pipeline, anything falsy
+ * stops it. Sync or async.
+ *
+ * Widened past `boolean` so consumers can write the natural JS shape
+ * `gate(name, (s) => s.issues.length)` (a number) or
+ * `gate(name, (s) => s.issues)` (an array) without an extra `!!` or
+ * `=== true` cast.
+ */
+export type PipelineGateFn = (state: JsonObject) => unknown;
+/**
+ * Per-step error strategy.
+ *
+ * - `fail-fast` (default) — step throws → `execute()` rethrows.
+ * - `continue` — step throws → error is recorded on the step log and the
+ *   pipeline keeps going; state is not mutated by the failed step.
+ * - `collect` — same as `continue`, plus the aggregated errors are exposed on
+ *   {@link PipelineResult.errors} for the caller to inspect after the run
+ *   completes.
+ */
+export type PipelineErrorStrategy = 'fail-fast' | 'continue' | 'collect';
+/** Final result returned by `PipelineBuilder.execute()`. */
+export interface PipelineResult {
+    /** Final accumulated state after the last step ran (or the gate short-circuited). */
+    readonly state: JsonObject;
+    /** Per-entry log in execution order. Parallel groups produce one entry per branch. */
+    readonly steps: readonly PipelineStepLog[];
+    /**
+     * Errors collected under `collect` strategy, keyed by step name. Empty
+     * array if no step failed or the strategy was `fail-fast` / `continue`.
+     */
+    readonly errors: readonly PipelineStepError[];
+    /**
+     * True if a gate predicate returned falsy and short-circuited execution.
+     * Consumers can distinguish "gate stopped us" from "ran to completion".
+     */
+    readonly gated: boolean;
+}
+/** Per-step execution record. */
+export interface PipelineStepLog {
+    readonly name: string;
+    readonly success: boolean;
+    readonly durationMs: number;
+    readonly error?: string;
+}
+/** Collected-mode error record. */
+export interface PipelineStepError {
+    readonly name: string;
+    readonly error: string;
+}
+/** Symbol key for the hook-bearing internal execute path. */
+export declare const PIPELINE_TRACE_HOOKS: unique symbol;
+/**
+ * Fluent builder. Each chain method returns a new instance — the builder is
+ * structurally immutable so a consumer can fan out a base pipeline into
+ * multiple variants.
+ */
+export declare class PipelineBuilder {
+    /**
+     * Reach this via {@link PipelineClient.build} — that's the public entry
+     * point. The constructor signature stays exported (not strip-tagged) so
+     * the published `.d.ts` carries a real `(client)` signature; without it,
+     * the strip-tag compiler step would synthesize an implicit no-arg
+     * `new PipelineBuilder()` for consumers, and pipelines built that way
+     * would see `ctx.client === undefined`. The multi-arg chain-extension
+     * shape lives on the private `cloneWith` helper so the internal
+     * `PipelineEntry` type doesn't leak into the published declarations.
+     */
+    constructor(client: QodoClient);
+    /** Build a new builder that shares this builder's client but swaps in the supplied chain state. */
+    private cloneWith;
+    /** Append a sequential step. */
+    step(name: string, fn: PipelineStepFn): PipelineBuilder;
+    /**
+     * Run a group of steps in parallel. Every branch sees the same input state;
+     * branches that succeed contribute their returned patches to the merged
+     * state in declaration order (later in the array wins on key conflicts).
+     * Branch failures are governed by the *currently active* error strategy.
+     */
+    parallel(steps: ReadonlyArray<{
+        readonly name: string;
+        readonly fn: PipelineStepFn;
+    }>): PipelineBuilder;
+    /**
+     * Insert a gate predicate. Falsy → pipeline short-circuits and `execute()`
+     * resolves with `gated: true` and the current accumulated state. Truthy →
+     * continue.
+     */
+    gate(name: string, fn: PipelineGateFn): PipelineBuilder;
+    /**
+     * Set the per-step error strategy for subsequent steps. Doesn't retroactively
+     * change strategies on entries already in the chain — each entry records the
+     * strategy in effect at the moment it was appended.
+     */
+    onError(strategy: PipelineErrorStrategy): PipelineBuilder;
+    /** Execute the pipeline against the given initial state. */
+    execute(initialState?: JsonObject): Promise<PipelineResult>;
+    private executeInternal;
+}
+/**
+ * Entry point for the pipeline DSL. Reachable via `client.pipeline.build()`.
+ */
+export declare class PipelineClient {
+    /**
+     * Construction is intended for use by `QodoClient`; consumers reach a live
+     * instance via `client.pipeline`. The constructor signature is kept
+     * undecorated so the strip-tag compiler step doesn't erase it from the
+     * published `.d.ts` — otherwise a synthesized no-arg constructor would let
+     * consumers build a `PipelineClient` with no client reference, producing
+     * pipelines whose steps see `ctx.client === undefined`.
+     */
+    constructor(client: QodoClient);
+    /** Construct a fresh `PipelineBuilder` bound to this client. */
+    build(): PipelineBuilder;
+}
+//# sourceMappingURL=PipelineClient.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PipelineClient.d.ts","sourceRoot":"","sources":["../../src/client/PipelineClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,CAC3B,GAAG,EAAE,mBAAmB,KACrB,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;AAEpD,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC;AAE5D;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;AAEzE,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,sFAAsF;IACtF,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC9C;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,iCAAiC;AACjC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,mCAAmC;AACnC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAuCD,6DAA6D;AAC7D,eAAO,MAAM,oBAAoB,EAAE,OAAO,MAAoD,CAAC;AAE/F;;;;GAIG;AACH,qBAAa,eAAe;IAQ1B;;;;;;;;;OASG;gBACgB,MAAM,EAAE,UAAU;IAWrC,mGAAmG;IACnG,OAAO,CAAC,SAAS;IAcjB,gCAAgC;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,cAAc,GAAG,eAAe;IAa9D;;;;;OAKG;IACI,QAAQ,CACb,KAAK,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAA;KAAE,CAAC,GAC3E,eAAe;IAiClB;;;;OAIG;IACI,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,cAAc,GAAG,eAAe;IAa9D;;;;OAIG;IACI,OAAO,CAAC,QAAQ,EAAE,qBAAqB,GAAG,eAAe;IAShE,4DAA4D;IAC/C,OAAO,CAAC,YAAY,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC;YAiB1D,eAAe;CAoI9B;AAED;;GAEG;AACH,qBAAa,cAAc;IAIzB;;;;;;;OAOG;gBACgB,MAAM,EAAE,UAAU;IASrC,gEAAgE;IACzD,KAAK,IAAI,eAAe;CAGhC"}