@consciousclouds/conductor-sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog — @consciousclouds/conductor-sdk
+
+Versioned on the independent frontend-SDK lifecycle (NOT `contract_version`).
+
+## [0.1.0] — 2026-06-16
+
+### Added
+
+- Conductor wire types (`TurnRequest`, `ResolveRequest`, `ResolveResult`, the
+  seven frozen SSE event payloads, `ConductorEventName`/`ConductorEventDataMap`),
+  generated from `platform/contracts/conductor/v1/` by
+  `platform/codegen/conductor/generate.py`.
+- Tool / personality / capability declaration types
+  (`ToolDeclaration`, `PersonalityDeclaration`, `Capability`).
+- A thin `createConductorClient({ baseUrl, headers?, fetchImpl?, validate? })`:
+  `stream()` (SSE), `turn()` (delta accumulation + completed), and
+  `resolveApproval()`. `ConductorClientError` for transport failures.
+- A reusable, transport-agnostic SSE frame parser (`parseSseFrames`).
+- `validateTurnRequest()` / `validateResolveRequest()` / `validateSseEvent()`
+  (zod) mirroring the JSON Schema.
+
+### Notes
+
+- Authoritative contract is the JSON Schema under
+  `platform/contracts/conductor/v1/`. The generated types derive from it.
+- `baseUrl` is a configurable Conductor-compatible endpoint. The SDK never
+  hard-codes a gateway URL, never adds a gateway route, and never mints
+  identity — it forwards the `Authorization` / `X-Tenant-ID` headers the caller
+  supplies.
+- No business logic, no caching, no retries-with-elevation (the locked SDK rule).

package/LICENSE

@@ -0,0 +1,171 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any
+      Contribution embodied within the Work constitutes direct or contributory
+      patent infringement, then any patent licenses granted to You under
+      this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative Works
+          a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works that
+          You distribute, all copyright, patent, trademark, and attribution
+          notices from the Source form of the Work, excluding those notices
+          that do not pertain to any part of the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the attribution
+          notices contained within such NOTICE file, in at least one of the
+          following places: within a NOTICE text provided as part of the
+          Derivative Works; within the Source form or documentation, if
+          provided along with the Derivative Works; or, within a display
+          generated by the Derivative Works, if and wherever such third-party
+          notices normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License. You may
+          add Your own attribution notices within Derivative Works that You
+          distribute, alongside or in addition to the NOTICE text from the
+          Work, provided that such additional attribution notices cannot be
+          construed as modifying the License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work by
+      You to the Licensor shall be under the terms and conditions of this
+      License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any conditions of TITLE,
+      MERCHANTIBILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely
+      responsible for determining the appropriateness of using or
+      redistributing the Work and assume any risks associated with Your
+      exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a result
+      of this License or out of the use or inability to use the Work
+      (including but not limited to damages for loss of goodwill, work
+      stoppage, computer failure or malfunction, or all other commercial
+      damages or losses), even if such Contributor has been advised of the
+      possibility of such damages.
+
+   9. Accepting Warranty or Liability. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a fee
+      for, acceptance of support, warranty, indemnity, or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You may offer such obligations only on
+      Your own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend, and
+      hold each Contributor harmless for any liability incurred by, or
+      claims asserted against, such Contributor by reason of your accepting
+      any such warranty or additional liability.
+
+   Copyright 2024 Conscious Clouds
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,64 @@
+# @consciousclouds/conductor-sdk
+
+Types + a thin client for the **Conductor** runtime — the single AI engine the
+platform's products consume as registered personalities. Two endpoints: a
+streaming **turn** (Server-Sent Events) and an approval **resolve**.
+
+Framework-agnostic and provider-agnostic — no product nouns, no React, no model
+provider. The authoritative contract is the JSON Schema under
+`platform/contracts/conductor/v1/`; the generated types derive from it.
+
+`baseUrl` is a **configurable Conductor-compatible endpoint** — the SDK never
+hard-codes a gateway URL, never adds a gateway route, and never mints identity.
+It forwards the `Authorization` / `X-Tenant-ID` headers the caller supplies.
+
+## Exports
+
+| Subpath | What |
+|---|---|
+| `.` | everything below |
+| `./client` | `createConductorClient()`, `ConductorClientError`, `parseSseFrames()` |
+| `./types` | `TurnRequest`, `ResolveResult`, the SSE event payloads, `CompletedResult` |
+| `./tools` | `ToolDeclaration`, `TOOL_CATEGORIES` |
+| `./personalities` | `PersonalityDeclaration`, `PERSONALITY_TIERS` |
+| `./capabilities` | `Capability`, `CAPABILITY_PATTERN`, `isCapability()` |
+| `./validate` | `validateTurnRequest()`, `validateResolveRequest()`, `validateSseEvent()` |
+
+## Usage
+
+```ts
+import { createConductorClient } from '@consciousclouds/conductor-sdk';
+
+const conductor = createConductorClient({
+  baseUrl: process.env.CONDUCTOR_BASE_URL!, // a Conductor-compatible endpoint
+  headers: () => ({
+    Authorization: `Bearer ${getToken()}`,
+    'X-Tenant-ID': getTenantId(),
+  }),
+});
+
+// Stream a turn, frame by frame.
+await conductor.stream({ prompt: 'Summarize my environments' }, (name, data) => {
+  if (name === 'delta') process.stdout.write(data.text);
+  if (name === 'approval_required') {
+    void conductor.resolveApproval(data.approval_id, 'approve');
+  }
+});
+
+// Or the convenience form: accumulate text + get the completed payload.
+const result = await conductor.turn({ prompt: 'Hello' });
+console.log(result.text, result.cost_usd);
+```
+
+## The frozen event set
+
+`started`, `delta`, `tool_start`, `tool_done`, `approval_required`,
+`completed`, `error`. Adding an event is additive in
+`platform/contracts/conductor/v1/`; regenerate with
+`python platform/codegen/conductor/generate.py` (or `bun run generate:conductor`).
+
+## SDK rule
+
+Types + thin HTTP wrapper only — no business logic, no caching, no
+retries-with-elevation. The runtime authorizes every request against the
+*caller's* identity; this SDK never decides authorization.

package/dist/capabilities.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Capability vocabulary. A capability is a `<primitive>.<verb>` string
+ * (e.g. canvas.read, graph.contribute, conductor.invoke). Re-exported from the
+ * generated contract types.
+ *
+ * @packageDocumentation
+ */
+export type { Capability } from './generated/index.js';
+/**
+ * The capability string pattern, mirroring
+ * platform/contracts/conductor/v1/capability.schema.json. Both segments are
+ * lower_snake_case.
+ */
+export declare const CAPABILITY_PATTERN: RegExp;
+/** True when `value` is a well-formed capability string. */
+export declare function isCapability(value: string): boolean;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAAuB,CAAC;AAEvD,4DAA4D;AAC5D,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD"}

package/dist/capabilities.js

@@ -0,0 +1,18 @@
+/**
+ * Capability vocabulary. A capability is a `<primitive>.<verb>` string
+ * (e.g. canvas.read, graph.contribute, conductor.invoke). Re-exported from the
+ * generated contract types.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The capability string pattern, mirroring
+ * platform/contracts/conductor/v1/capability.schema.json. Both segments are
+ * lower_snake_case.
+ */
+export const CAPABILITY_PATTERN = /^[a-z_]+\.[a-z_]+$/;
+/** True when `value` is a well-formed capability string. */
+export function isCapability(value) {
+    return CAPABILITY_PATTERN.test(value);
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AAEvD,4DAA4D;AAC5D,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACxC,CAAC"}

package/dist/client/conductor-client.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Thin Conductor client — types + HTTP wrapper only (the locked SDK rule).
+ * No business logic, no caching, no retries, no elevation. It forwards the
+ * identity headers the caller supplies and never mints identity.
+ *
+ * The one transport-mechanics affordance it exposes is cancellation: `stream()`
+ * and `turn()` accept an optional `AbortSignal`. Aborting tears down the fetch +
+ * reader. This is NOT a retry/timeout/reconnect policy — resilience POLICY
+ * (backoff, idle-stall, token refresh) lives in the coordination layer
+ * (`@consciousclouds/ai-client`), never here.
+ *
+ * `baseUrl` is a configurable Conductor-compatible HTTP endpoint. The SDK never
+ * hard-codes a gateway URL and never adds a gateway route.
+ *
+ * @packageDocumentation
+ */
+import type { TurnRequest, ResolveResult, ConductorEventName, ConductorEventDataMap, CompletedResult } from '../types/index.js';
+import type { ApprovalDecision } from '../types/index.js';
+export interface ConductorClientOptions {
+    /**
+     * Base URL of a Conductor-compatible HTTP endpoint, e.g.
+     * https://conductor.example.com. Required — the SDK never hard-codes one.
+     */
+    baseUrl: string;
+    /** Optional fetch implementation (defaults to global fetch). */
+    fetchImpl?: typeof fetch;
+    /**
+     * Optional per-request headers (auth, tenant, correlation). The caller owns
+     * identity: typically returns `Authorization` and `X-Tenant-ID`. The SDK
+     * forwards whatever is returned and adds nothing of its own.
+     */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Reserved for symmetry with other SDK clients; unused today. */
+    validate?: boolean;
+}
+/** Callback invoked once per parsed SSE frame, in arrival order. */
+export type ConductorEventHandler = (name: ConductorEventName, data: ConductorEventDataMap[ConductorEventName]) => void;
+/** Per-call transport options. Cancellation only — no policy. */
+export interface ConductorStreamOptions {
+    /**
+     * Aborts the in-flight request. Aborting tears down the fetch + reader; the
+     * returned promise rejects with the abort reason (an `AbortError`). The SDK
+     * does nothing else with it — no retry, no reconnect.
+     */
+    signal?: AbortSignal;
+}
+export interface ConductorClient {
+    /**
+     * POST /api/v1/conductor/turn/stream — opens the SSE stream and invokes
+     * `onEvent` for every frame until the stream ends. Resolves when the stream
+     * is fully consumed; rejects on transport / non-2xx errors. Pass
+     * `opts.signal` to cancel.
+     */
+    stream(input: TurnRequest, onEvent: ConductorEventHandler, opts?: ConductorStreamOptions): Promise<void>;
+    /**
+     * Convenience over stream(): accumulates `delta` text and resolves with the
+     * `completed` payload (+ accumulated text). Rejects on an `error` event or if
+     * the stream ends without a `completed` event.
+     */
+    turn(input: TurnRequest, opts?: ConductorStreamOptions): Promise<CompletedResult>;
+    /**
+     * POST /api/v1/conductor/approvals/:id/resolve — approve or reject a pending
+     * approval surfaced by an `approval_required` event.
+     */
+    resolveApproval(approvalId: string, decision: ApprovalDecision): Promise<ResolveResult>;
+}
+export declare class ConductorClientError extends Error {
+    readonly status?: number | undefined;
+    readonly details?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, details?: unknown | undefined);
+}
+/**
+ * Parse a raw SSE buffer into complete `{ event, data }` frames.
+ *
+ * Frames are separated by a blank line (`\n\n`). Within a frame, `event:` lines
+ * name the event and `data:` lines carry the JSON payload (multiple `data:`
+ * lines are joined with `\n` per the SSE spec). Returns the complete frames and
+ * the unconsumed remainder (a partial frame still being received).
+ */
+export declare function parseSseFrames(buffer: string): {
+    frames: {
+        event: string;
+        data: string;
+    }[];
+    rest: string;
+};
+export declare function createConductorClient(options: ConductorClientOptions): ConductorClient;
+//# sourceMappingURL=conductor-client.d.ts.map

package/dist/client/conductor-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conductor-client.d.ts","sourceRoot":"","sources":["../../src/client/conductor-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACzE,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,oEAAoE;AACpE,MAAM,MAAM,qBAAqB,GAAG,CAClC,IAAI,EAAE,kBAAkB,EACxB,IAAI,EAAE,qBAAqB,CAAC,kBAAkB,CAAC,KAC5C,IAAI,CAAC;AAEV,iEAAiE;AACjE,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,MAAM,CACJ,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,qBAAqB,EAC9B,IAAI,CAAC,EAAE,sBAAsB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAClF;;;OAGG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACzF;AAED,qBAAa,oBAAqB,SAAQ,KAAK;aAG3B,MAAM,CAAC,EAAE,MAAM;aACf,OAAO,CAAC,EAAE,OAAO;gBAFjC,OAAO,EAAE,MAAM,EACC,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,OAAO,CAAC,EAAE,OAAO,YAAA;CAKpC;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG;IAC9C,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC;CACd,CAgCA;AAeD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,eAAe,CAiKtF"}

package/dist/client/conductor-client.js

@@ -0,0 +1,213 @@
+/**
+ * Thin Conductor client — types + HTTP wrapper only (the locked SDK rule).
+ * No business logic, no caching, no retries, no elevation. It forwards the
+ * identity headers the caller supplies and never mints identity.
+ *
+ * The one transport-mechanics affordance it exposes is cancellation: `stream()`
+ * and `turn()` accept an optional `AbortSignal`. Aborting tears down the fetch +
+ * reader. This is NOT a retry/timeout/reconnect policy — resilience POLICY
+ * (backoff, idle-stall, token refresh) lives in the coordination layer
+ * (`@consciousclouds/ai-client`), never here.
+ *
+ * `baseUrl` is a configurable Conductor-compatible HTTP endpoint. The SDK never
+ * hard-codes a gateway URL and never adds a gateway route.
+ *
+ * @packageDocumentation
+ */
+export class ConductorClientError extends Error {
+    constructor(message, status, details) {
+        super(message);
+        this.status = status;
+        this.details = details;
+        this.name = 'ConductorClientError';
+    }
+}
+/**
+ * Parse a raw SSE buffer into complete `{ event, data }` frames.
+ *
+ * Frames are separated by a blank line (`\n\n`). Within a frame, `event:` lines
+ * name the event and `data:` lines carry the JSON payload (multiple `data:`
+ * lines are joined with `\n` per the SSE spec). Returns the complete frames and
+ * the unconsumed remainder (a partial frame still being received).
+ */
+export function parseSseFrames(buffer) {
+    // Normalize CRLF → LF so frame splitting is robust across servers.
+    const normalized = buffer.replace(/\r\n/g, '\n');
+    const frames = [];
+    let searchFrom = 0;
+    let sep = normalized.indexOf('\n\n', searchFrom);
+    while (sep !== -1) {
+        const block = normalized.slice(searchFrom, sep);
+        searchFrom = sep + 2;
+        sep = normalized.indexOf('\n\n', searchFrom);
+        let event = '';
+        const dataLines = [];
+        for (const line of block.split('\n')) {
+            if (line === '' || line.startsWith(':'))
+                continue; // blank / comment line
+            const colon = line.indexOf(':');
+            const field = colon === -1 ? line : line.slice(0, colon);
+            // A single leading space after the colon is stripped per the SSE spec.
+            let value = colon === -1 ? '' : line.slice(colon + 1);
+            if (value.startsWith(' '))
+                value = value.slice(1);
+            if (field === 'event')
+                event = value;
+            else if (field === 'data')
+                dataLines.push(value);
+        }
+        // Only surface frames that actually named an event (skip keep-alives).
+        if (event !== '') {
+            frames.push({ event, data: dataLines.join('\n') });
+        }
+    }
+    return { frames, rest: normalized.slice(searchFrom) };
+}
+function isFrozenEvent(name) {
+    return (name === 'started' ||
+        name === 'delta' ||
+        name === 'tool_start' ||
+        name === 'tool_done' ||
+        name === 'approval_required' ||
+        name === 'completed' ||
+        name === 'error' ||
+        name === 'routed');
+}
+export function createConductorClient(options) {
+    if (!options.baseUrl) {
+        throw new ConductorClientError('createConductorClient requires a baseUrl');
+    }
+    const base = options.baseUrl.replace(/\/$/, '');
+    const doFetch = options.fetchImpl ?? globalThis.fetch;
+    async function resolvedHeaders() {
+        return options.headers ? await options.headers() : {};
+    }
+    const client = {
+        async stream(input, onEvent, opts) {
+            const url = `${base}/api/v1/conductor/turn/stream`;
+            // Bail before any network work if already aborted. Explicit (not throwIfAborted) so the guard
+            // never silently no-ops on a runtime missing that method.
+            if (opts?.signal?.aborted) {
+                throw opts.signal.reason ?? new DOMException('Aborted', 'AbortError');
+            }
+            const headers = await resolvedHeaders();
+            const res = await doFetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Accept: 'text/event-stream',
+                    ...headers,
+                },
+                body: JSON.stringify(input),
+                signal: opts?.signal,
+            });
+            if (!res.ok) {
+                let body;
+                try {
+                    body = await res.json();
+                }
+                catch {
+                    body = undefined;
+                }
+                throw new ConductorClientError(`Conductor turn request failed (${res.status})`, res.status, body);
+            }
+            if (!res.body) {
+                throw new ConductorClientError('Conductor turn response has no body', res.status);
+            }
+            const reader = res.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = '';
+            const dispatch = (frames) => {
+                for (const frame of frames) {
+                    if (!isFrozenEvent(frame.event))
+                        continue; // ignore unknown event names
+                    let parsed = undefined;
+                    if (frame.data !== '') {
+                        try {
+                            parsed = JSON.parse(frame.data);
+                        }
+                        catch {
+                            parsed = frame.data; // surface the raw string if not JSON
+                        }
+                    }
+                    onEvent(frame.event, parsed);
+                }
+            };
+            // eslint-disable-next-line no-constant-condition
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const { frames, rest } = parseSseFrames(buffer);
+                buffer = rest;
+                dispatch(frames);
+            }
+            // Flush any trailing frame that lacked a final blank line.
+            buffer += decoder.decode();
+            if (buffer.trim() !== '') {
+                const { frames } = parseSseFrames(buffer.endsWith('\n\n') ? buffer : `${buffer}\n\n`);
+                dispatch(frames);
+            }
+        },
+        async turn(input, opts) {
+            let text = '';
+            let completed;
+            let failure;
+            let routed;
+            await client.stream(input, (name, data) => {
+                if (name === 'delta') {
+                    text += data.text ?? '';
+                }
+                else if (name === 'completed') {
+                    completed = data;
+                }
+                else if (name === 'error') {
+                    failure = data;
+                }
+                else if (name === 'routed') {
+                    routed = data;
+                }
+            }, opts);
+            if (failure) {
+                throw new ConductorClientError(failure.message, undefined, failure);
+            }
+            if (routed && !completed) {
+                // A deterministic navigation/action turn produces no text+usage result — the host must
+                // PERFORM the directive. The collapse-to-result convenience cannot express that; the caller
+                // must use stream() to receive `routed`. Fail with the directive attached, not a generic miss.
+                throw new ConductorClientError('Conductor turn ended in a navigation/action directive; use stream() to receive `routed` events', undefined, routed);
+            }
+            if (!completed) {
+                throw new ConductorClientError('Conductor turn ended without a completed event');
+            }
+            return { ...completed, text };
+        },
+        async resolveApproval(approvalId, decision) {
+            const url = `${base}/api/v1/conductor/approvals/${encodeURIComponent(approvalId)}/resolve`;
+            const headers = await resolvedHeaders();
+            const res = await doFetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                    ...headers,
+                },
+                body: JSON.stringify({ decision }),
+            });
+            if (!res.ok) {
+                let body;
+                try {
+                    body = await res.json();
+                }
+                catch {
+                    body = undefined;
+                }
+                throw new ConductorClientError(`Conductor approval resolve failed (${res.status})`, res.status, body);
+            }
+            return (await res.json());
+        },
+    };
+    return client;
+}
+//# sourceMappingURL=conductor-client.js.map

package/dist/client/conductor-client.js.map

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

package/dist/generated/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/generated/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generated/index.ts"],"names":[],"mappings":"AAEA,cAAc,YAAY,CAAC"}

package/dist/generated/index.js

@@ -0,0 +1,3 @@
+// AUTO-GENERATED — DO NOT EDIT. Run `python platform/codegen/conductor/generate.py` to regenerate. Source: platform/contracts/conductor/v1/
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/generated/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/generated/index.ts"],"names":[],"mappings":"AAAA,4IAA4I;AAE5I,cAAc,YAAY,CAAC"}