orchid-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,176 @@
+                                 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, whether in Source or
+      Object form, 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 any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to 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 otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated 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 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 a Contribution incorporated 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, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          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 as an addendum to the LICENSE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this 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.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   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 warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, 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 consequential 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 any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional 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 act 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.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,150 @@
+# Orchid TypeScript SDK
+
+The Orchid TypeScript SDK is a lightweight, thin SDK designed to work seamlessly with Orchid - [the Orchestration Interactive Debugger](https://orchidtrace.xyz).
+
+It automatically intercepts outgoing LLM and external API requests (e.g., OpenAI, Anthropic, Gemini, Vertex AI, SerpAPI, etc.) and routes them through the local Orchid Proxy. This enables full request capturing, visualization, interactive debugging, and mock replay capabilities in unit tests or local development environments.
+
+**Requires Node.js 18+** (native `fetch` and `AsyncLocalStorage`).
+
+---
+
+## Installation
+
+```bash
+npm install orchid-sdk
+```
+
+---
+
+## Quickstart
+
+### 1. Initialization
+
+Call `await init()` at the entry point of your application (before instantiating any LLM clients).
+
+```ts
+import { init } from "orchid-sdk";
+
+// Initialize the Orchid environment and patch the global fetch
+await init();
+
+// Now, standard client libraries will automatically route through the Orchid proxy!
+import OpenAI from "openai";
+const client = new OpenAI();
+```
+
+### 2. Session Contexts
+
+Use `session()` to group API exchanges under a specific session ID and mode. Context propagates safely across async boundaries via `AsyncLocalStorage`.
+
+```ts
+import { init, session } from "orchid-sdk";
+
+await init();
+
+// Intercept and capture requests in this block under a custom session name
+await session("user-onboarding-flow", "capture", async () => {
+  // Outgoing LLM calls here will be captured under session ID 'user-onboarding-flow'
+  const response = await client.chat.completions.create({
+    model: "gpt-5.2",
+    messages: [{ role: "user", content: "Hello!" }],
+  });
+});
+```
+
+Supported modes are:
+* `"capture"`: Intercepts and records all outgoing requests.
+* `"replay"`: Intercepts requests and serves mocked responses from previously recorded exchanges.
+* `"passthrough"`: Bypasses the proxy database logging (requests still pass through but are not recorded/mocked).
+
+### Explicit fetch wrapper (no global patching)
+
+If you prefer not to patch `globalThis.fetch`, pass `orchidFetch` directly to clients that accept a custom fetch implementation:
+
+```ts
+import { orchidFetch } from "orchid-sdk";
+import OpenAI from "openai";
+
+const client = new OpenAI({ fetch: orchidFetch });
+```
+
+---
+
+## Capture & Replay Test Helper (`withReplay`)
+
+`withReplay()` automates capturing and replaying HTTP exchanges. It is framework-agnostic and works in vitest, jest, or `node:test`, ensuring test suites are deterministic and do not make expensive, slow, or volatile external network calls.
+
+```ts
+import { withReplay } from "orchid-sdk";
+
+test("user greeting", () =>
+  withReplay("tests/fixtures/test_user_greeting.json", async () => {
+    // If ORCHID_RECORD=1: executes the API call and saves results to the JSON fixture file.
+    // If ORCHID_RECORD=0 or unset: mocks the API call using the contents of the fixture file.
+    const response = await client.chat.completions.create({
+      model: "gpt-5.2",
+      messages: [{ role: "user", content: "Say hello!" }],
+    });
+    expect(response.choices[0].message.content.toLowerCase()).toContain("hello");
+  }));
+```
+
+---
+
+## Orchid Control Client
+
+For programmatic control over recorded fixtures, use `OrchidControlClient` to check health, export, or import fixtures.
+
+```ts
+import { OrchidControlClient } from "orchid-sdk";
+
+// Create the client pointing to the control port (default: 4321)
+const controlClient = new OrchidControlClient();
+
+// Check if the query service is active
+if (await controlClient.checkHealth()) {
+  // Export a recorded session to a local JSON file
+  await controlClient.exportFixture("my-session-123", "fixtures/session_data.json");
+
+  // Import a local JSON fixture database back into the proxy
+  await controlClient.importFixture("fixtures/session_data.json");
+}
+```
+
+---
+
+## Configuration (Environment Variables)
+
+| Variable | Default | Description |
+| :--- | :--- | :--- |
+| `ORCHID_PROXY_URL` | `http://127.0.0.1:4320/v1` | The Orchid Proxy intercept endpoint. |
+| `ORCHID_QUERY_URL` | derived (`:4321`) | The Query & Control API endpoint. |
+| `ORCHID_PROXY_KEY` | — | Auth key sent as `X-Orchid-Proxy-Key`. |
+| `ORCHID_API_KEY` | — | Control plane API key (`X-Orchid-Api-Key`). |
+| `ORCHID_SESSION_ID` / `ORCHID_MODE` | — | Global session/mode fallback when no `session()` scope is active. |
+| `ORCHID_CAPTURE_DOMAINS` | — | Comma-separated extra domains to intercept, or `*` for all. |
+| `ORCHID_IGNORE_DOMAINS` | — | Comma-separated domains to never intercept. |
+| `ORCHID_RECORD` | — | Set to `1` to run `withReplay` blocks in record mode. |
+| `ORCHID_BYPASS_HEALTHCHECK` | — | Set to `True` to skip the init health check. |
+
+---
+
+## How It Works (Auto-Instrumentation)
+
+When you call `init()`, the SDK patches `globalThis.fetch` (Node's native undici-backed fetch). This automatically intercepts libraries like `openai` and `@anthropic-ai/sdk`, which use the global fetch as their underlying HTTP transport. Requests to core LLM providers (and any `ORCHID_CAPTURE_DOMAINS`) are rewritten to the proxy with `X-Orchid-*` control headers attached; localhost traffic is never intercepted.
+
+### Fail-Soft Fallback
+
+The SDK is built to be resilient. During initialization, the SDK performs a fast health check on the Orchid Query service.
+* If the proxy or control service is **offline**, the SDK silently falls back to direct routing. The global fetch is not patched, and environment base URLs are not modified.
+* If the patch is active but the proxy goes offline mid-session, the wrapper catches connection failures, logs a warning, case-insensitively purges internal Orchid headers (preventing key leakage), and seamlessly retries the request directly to the upstream public API.
+
+---
+
+## Development
+
+```bash
+npm install
+npm test        # vitest
+npm run build   # tsup -> dist/ (esm + cjs + d.ts)
+```

package/dist/index.cjs

@@ -0,0 +1,346 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  OrchidControlClient: () => OrchidControlClient,
+  currentMode: () => currentMode,
+  currentSessionId: () => currentSessionId,
+  init: () => init,
+  orchidFetch: () => orchidFetch,
+  session: () => session,
+  uninstall: () => uninstall,
+  withReplay: () => withReplay
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/context.ts
+var import_node_async_hooks = require("async_hooks");
+var storage = new import_node_async_hooks.AsyncLocalStorage();
+function currentSessionId() {
+  return storage.getStore()?.sessionId ?? process.env.ORCHID_SESSION_ID ?? void 0;
+}
+function currentMode() {
+  return storage.getStore()?.mode ?? process.env.ORCHID_MODE ?? void 0;
+}
+function session(sessionId, mode, fn) {
+  return storage.run({ sessionId, mode }, fn);
+}
+
+// src/core.ts
+var CORE_PROVIDERS = [
+  "api.openai.com",
+  "api.anthropic.com",
+  "generativelanguage.googleapis.com",
+  "aiplatform.googleapis.com"
+];
+var LOCAL_HOSTS = ["localhost", "127.0.0.1", "::1", "[::1]"];
+var patched = false;
+var offlineFallback = false;
+var originalFetch;
+function proxyUrl() {
+  return process.env.ORCHID_PROXY_URL ?? "http://127.0.0.1:4320/v1";
+}
+function envList(name) {
+  return (process.env[name] ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+function isCoreProvider(host) {
+  return CORE_PROVIDERS.some((c) => host.includes(c));
+}
+function shouldIntercept(url) {
+  if (offlineFallback) return false;
+  const host = url.hostname;
+  if (LOCAL_HOSTS.some((h) => host === h)) return false;
+  if (envList("ORCHID_IGNORE_DOMAINS").some((d) => host.includes(d))) {
+    return false;
+  }
+  if (isCoreProvider(host)) return true;
+  const capture = envList("ORCHID_CAPTURE_DOMAINS");
+  if (capture.includes("*")) return true;
+  if (capture.some((d) => host.includes(d))) return true;
+  return false;
+}
+function rewriteUrl(originalUrl) {
+  const proxy = new URL(proxyUrl());
+  const rewritten = new URL(originalUrl.toString());
+  rewritten.protocol = proxy.protocol;
+  rewritten.host = proxy.host;
+  if (isCoreProvider(originalUrl.hostname)) {
+    const proxyBasePath = proxy.pathname.replace(/\/+$/, "");
+    if (proxyBasePath && !originalUrl.pathname.startsWith(proxyBasePath)) {
+      rewritten.pathname = proxyBasePath + originalUrl.pathname;
+    }
+  }
+  return rewritten;
+}
+function injectHeaders(headers, targetUrl, originalUrl) {
+  const proxy = new URL(proxyUrl());
+  if (targetUrl.host !== proxy.host) return;
+  const proxyKey = process.env.ORCHID_PROXY_KEY;
+  if (proxyKey) headers.set("X-Orchid-Proxy-Key", proxyKey);
+  const sessionId = currentSessionId();
+  let mode = currentMode();
+  if (sessionId) {
+    headers.set("X-Orchid-Session-Id", sessionId);
+    if (!mode) mode = "capture";
+  }
+  if (mode) headers.set("X-Orchid-Mode", mode);
+  if (originalUrl && originalUrl.host !== proxy.host) {
+    headers.set(
+      "X-Orchid-Target-Url",
+      `${originalUrl.protocol}//${originalUrl.host}`
+    );
+  }
+}
+function purgeOrchidHeaders(headers) {
+  const toDelete = [];
+  headers.forEach((_value, key) => {
+    if (key.toLowerCase().startsWith("x-orchid-")) toDelete.push(key);
+  });
+  for (const key of toDelete) headers.delete(key);
+}
+function isConnectionError(err) {
+  if (!(err instanceof Error)) return false;
+  const cause = err.cause;
+  const code = cause?.code ?? err.code;
+  return code === "ECONNREFUSED" || code === "ECONNRESET" || code === "EHOSTUNREACH" || code === "ENOTFOUND" || code === "ETIMEDOUT" || code === "UND_ERR_CONNECT_TIMEOUT" || code === "UND_ERR_SOCKET";
+}
+var orchidFetch = async (input, init2) => {
+  const baseFetch = originalFetch ?? globalThis.fetch;
+  const request = new Request(input, init2);
+  const original = new URL(request.url);
+  if (!shouldIntercept(original)) {
+    const headers2 = new Headers(request.headers);
+    injectHeaders(headers2, original);
+    return baseFetch(new Request(request, { headers: headers2 }));
+  }
+  const rewritten = rewriteUrl(original);
+  const headers = new Headers(request.headers);
+  injectHeaders(headers, rewritten, original);
+  const proxied = new Request(rewritten, {
+    method: request.method,
+    headers,
+    body: request.body,
+    // Required by undici when streaming a body
+    ...request.body ? { duplex: "half" } : {},
+    redirect: request.redirect,
+    signal: request.signal
+  });
+  try {
+    return await baseFetch(proxied);
+  } catch (err) {
+    if (!isConnectionError(err)) throw err;
+    console.warn(
+      `[orchid] Proxy connection failed (${String(err)}). Falling back to direct routing: ${original}`
+    );
+    const fallbackHeaders = new Headers(request.headers);
+    purgeOrchidHeaders(fallbackHeaders);
+    return baseFetch(
+      new Request(original, {
+        method: request.method,
+        headers: fallbackHeaders,
+        body: request.body,
+        ...request.body ? { duplex: "half" } : {},
+        redirect: request.redirect,
+        signal: request.signal
+      })
+    );
+  }
+};
+function deriveQueryUrl() {
+  const explicit = process.env.ORCHID_QUERY_URL;
+  if (explicit) return explicit;
+  const proxy = new URL(proxyUrl());
+  if (proxy.port === "4320") proxy.port = "4321";
+  proxy.pathname = "";
+  return proxy.toString().replace(/\/+$/, "");
+}
+async function proxyIsHealthy() {
+  const baseFetch = originalFetch ?? globalThis.fetch;
+  try {
+    const resp = await baseFetch(`${deriveQueryUrl()}/health`, {
+      signal: AbortSignal.timeout(1e3)
+    });
+    return resp.status === 200;
+  } catch {
+    return false;
+  }
+}
+async function init(options = {}) {
+  offlineFallback = false;
+  const proxy = proxyUrl();
+  let parsed;
+  try {
+    parsed = new URL(proxy);
+  } catch {
+    throw new Error(`Malformed ORCHID_PROXY_URL: ${proxy}`);
+  }
+  if (!parsed.protocol || !parsed.host) {
+    throw new Error(`Malformed ORCHID_PROXY_URL: ${proxy}`);
+  }
+  const bypass = options.bypassHealthCheck === true || process.env.ORCHID_BYPASS_HEALTHCHECK === "True" || process.env.VITEST !== void 0;
+  if (!bypass) {
+    offlineFallback = !await proxyIsHealthy();
+  }
+  if (!offlineFallback) {
+    process.env.OPENAI_BASE_URL = proxy;
+  }
+  if (!patched && !offlineFallback) {
+    originalFetch = globalThis.fetch;
+    globalThis.fetch = orchidFetch;
+    patched = true;
+  }
+}
+function uninstall() {
+  if (patched && originalFetch) {
+    globalThis.fetch = originalFetch;
+    originalFetch = void 0;
+    patched = false;
+  }
+  offlineFallback = false;
+}
+
+// src/client.ts
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+var OrchidControlClient = class {
+  queryUrl;
+  apiKey;
+  /**
+   * @param queryUrl URL of the Orchid Query service (default: http://127.0.0.1:4321).
+   * @param apiKey API key for authenticating with the control plane.
+   */
+  constructor(queryUrl, apiKey) {
+    this.queryUrl = queryUrl ?? process.env.ORCHID_QUERY_URL ?? "http://127.0.0.1:4321";
+    this.apiKey = apiKey ?? process.env.ORCHID_API_KEY ?? void 0;
+  }
+  headers() {
+    return this.apiKey ? { "X-Orchid-Api-Key": this.apiKey } : {};
+  }
+  /** Checks the health of the Orchid Query service. */
+  async checkHealth() {
+    try {
+      const resp = await fetch(`${this.queryUrl}/health`, {
+        headers: this.headers(),
+        signal: AbortSignal.timeout(5e3)
+      });
+      return resp.status === 200;
+    } catch (err) {
+      console.warn(`[orchid] Query service health check failed: ${String(err)}`);
+      return false;
+    }
+  }
+  /**
+   * Exports all captured exchanges for a session from the proxy and saves
+   * them to a local JSON fixture file.
+   */
+  async exportFixture(sessionId, path) {
+    try {
+      const resp = await fetch(
+        `${this.queryUrl}/v1/sessions/${encodeURIComponent(sessionId)}/export`,
+        { headers: this.headers() }
+      );
+      if (resp.status === 404) {
+        console.warn(`[orchid] Session ${sessionId} not found to export.`);
+        return false;
+      }
+      if (!resp.ok) {
+        throw new Error(`Export failed with status ${resp.status}`);
+      }
+      const fixture = await resp.json();
+      await (0, import_promises.mkdir)((0, import_node_path.dirname)(path), { recursive: true });
+      await (0, import_promises.writeFile)(path, JSON.stringify(fixture, null, 2));
+      return true;
+    } catch (err) {
+      console.warn(
+        `[orchid] Failed to export fixture for session ${sessionId} to ${path}: ${String(err)}`
+      );
+      return false;
+    }
+  }
+  /**
+   * Reads a local JSON fixture file and imports its exchanges into the
+   * Orchid Proxy database.
+   *
+   * @throws If the fixture file does not exist or the import request fails.
+   */
+  async importFixture(path) {
+    const raw = await (0, import_promises.readFile)(path, "utf-8");
+    const fixture = JSON.parse(raw);
+    const resp = await fetch(`${this.queryUrl}/v1/sessions/import`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...this.headers() },
+      body: JSON.stringify(fixture)
+    });
+    if (!resp.ok) {
+      throw new Error(`Import failed with status ${resp.status}`);
+    }
+    return resp.status === 201;
+  }
+};
+
+// src/replay.ts
+var import_promises2 = require("fs/promises");
+var import_node_fs = require("fs");
+var import_node_path2 = require("path");
+function recordMode() {
+  return ["1", "true", "yes"].includes(
+    (process.env.ORCHID_RECORD ?? "").toLowerCase()
+  );
+}
+async function fixtureSessionId(path) {
+  if (!(0, import_node_fs.existsSync)(path)) return void 0;
+  try {
+    const data = JSON.parse(await (0, import_promises2.readFile)(path, "utf-8"));
+    return data?.session?.id ?? void 0;
+  } catch {
+    return void 0;
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function withReplay(fixturePath, fn, options = {}) {
+  const client = new OrchidControlClient();
+  const sessionId = options.sessionId ?? await fixtureSessionId(fixturePath) ?? (0, import_node_path2.basename)(fixturePath, (0, import_node_path2.extname)(fixturePath));
+  if (recordMode()) {
+    const result = await session(sessionId, "capture", fn);
+    const flushSleep = Number(process.env.ORCHID_FLUSH_SLEEP ?? "0.2");
+    if (flushSleep > 0) await sleep(flushSleep * 1e3);
+    await client.exportFixture(sessionId, fixturePath);
+    return result;
+  }
+  if (!(0, import_node_fs.existsSync)(fixturePath)) {
+    throw new Error(`Fixture file not found: ${fixturePath}`);
+  }
+  await client.importFixture(fixturePath);
+  return session(sessionId, "replay", fn);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  OrchidControlClient,
+  currentMode,
+  currentSessionId,
+  init,
+  orchidFetch,
+  session,
+  uninstall,
+  withReplay
+});

package/dist/index.d.cts

@@ -0,0 +1,103 @@
+/**
+ * An explicit fetch wrapper implementing Orchid interception. Use this
+ * directly (e.g. pass it as a custom `fetch` to an LLM client) if you prefer
+ * not to patch the global fetch.
+ */
+declare const orchidFetch: typeof globalThis.fetch;
+interface InitOptions {
+    /** Skip the proxy health check (also enabled by ORCHID_BYPASS_HEALTHCHECK=True or under vitest). */
+    bypassHealthCheck?: boolean;
+}
+/**
+ * Initializes the Orchid Thin SDK environment.
+ *
+ * Checks if the Orchid Proxy is online via health check. If online, patches
+ * `globalThis.fetch` to route LLM requests through the Orchid Proxy and
+ * overrides `OPENAI_BASE_URL`. If the proxy is offline, fail-soft (direct
+ * routing) is maintained and no patch is applied.
+ *
+ * Call this at the entry point of your application, before instantiating any
+ * LLM clients.
+ */
+declare function init(options?: InitOptions): Promise<void>;
+/** Restores the original global fetch. Intended for tests. */
+declare function uninstall(): void;
+
+type OrchidMode = "capture" | "replay" | "passthrough" | "log";
+interface OrchidContext {
+    sessionId: string;
+    mode: OrchidMode;
+}
+/** Returns the active session ID, falling back to ORCHID_SESSION_ID. */
+declare function currentSessionId(): string | undefined;
+/** Returns the active mode, falling back to ORCHID_MODE. */
+declare function currentMode(): string | undefined;
+/**
+ * Runs `fn` with the given Orchid session context. All requests dispatched
+ * (transitively) inside `fn` are grouped under `sessionId` with the given mode.
+ *
+ * ```ts
+ * await session("user-onboarding-flow", "capture", async () => {
+ *   await client.chat.completions.create({ ... });
+ * });
+ * ```
+ */
+declare function session<T>(sessionId: string, mode: OrchidMode, fn: () => T): T;
+
+/**
+ * Control client for managing the Orchid capture/replay database.
+ * Provides methods to perform health checks, export captured sessions,
+ * and import fixtures into the Orchid Proxy.
+ */
+declare class OrchidControlClient {
+    readonly queryUrl: string;
+    readonly apiKey?: string;
+    /**
+     * @param queryUrl URL of the Orchid Query service (default: http://127.0.0.1:4321).
+     * @param apiKey API key for authenticating with the control plane.
+     */
+    constructor(queryUrl?: string, apiKey?: string);
+    private headers;
+    /** Checks the health of the Orchid Query service. */
+    checkHealth(): Promise<boolean>;
+    /**
+     * Exports all captured exchanges for a session from the proxy and saves
+     * them to a local JSON fixture file.
+     */
+    exportFixture(sessionId: string, path: string): Promise<boolean>;
+    /**
+     * Reads a local JSON fixture file and imports its exchanges into the
+     * Orchid Proxy database.
+     *
+     * @throws If the fixture file does not exist or the import request fails.
+     */
+    importFixture(path: string): Promise<boolean>;
+}
+
+/**
+ * Runs `fn` with capture/replay backed by a JSON fixture file. Framework
+ * agnostic — works as a plain wrapper in vitest, jest, or node:test.
+ *
+ * - If `ORCHID_RECORD=1`: runs `fn` in capture mode and exports the session's
+ *   HTTP traffic to the fixture path afterwards.
+ * - Otherwise: imports the fixture into the proxy and runs `fn` in replay
+ *   mode, serving mocked responses with no external network calls.
+ *
+ * ```ts
+ * test("user greeting", () =>
+ *   withReplay("tests/fixtures/test_user_greeting.json", async () => {
+ *     const response = await client.chat.completions.create({ ... });
+ *     expect(response.choices[0].message.content).toMatch(/hello/i);
+ *   }));
+ * ```
+ *
+ * @param fixturePath Local JSON file path where traffic is saved/replayed.
+ * @param fn The function to run under the fixture's session.
+ * @param options.sessionId Session ID override; defaults to the fixture's
+ *   recorded session ID, then the fixture file's base name.
+ */
+declare function withReplay<T>(fixturePath: string, fn: () => Promise<T>, options?: {
+    sessionId?: string;
+}): Promise<T>;
+
+export { type InitOptions, type OrchidContext, OrchidControlClient, type OrchidMode, currentMode, currentSessionId, init, orchidFetch, session, uninstall, withReplay };

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * An explicit fetch wrapper implementing Orchid interception. Use this
+ * directly (e.g. pass it as a custom `fetch` to an LLM client) if you prefer
+ * not to patch the global fetch.
+ */
+declare const orchidFetch: typeof globalThis.fetch;
+interface InitOptions {
+    /** Skip the proxy health check (also enabled by ORCHID_BYPASS_HEALTHCHECK=True or under vitest). */
+    bypassHealthCheck?: boolean;
+}
+/**
+ * Initializes the Orchid Thin SDK environment.
+ *
+ * Checks if the Orchid Proxy is online via health check. If online, patches
+ * `globalThis.fetch` to route LLM requests through the Orchid Proxy and
+ * overrides `OPENAI_BASE_URL`. If the proxy is offline, fail-soft (direct
+ * routing) is maintained and no patch is applied.
+ *
+ * Call this at the entry point of your application, before instantiating any
+ * LLM clients.
+ */
+declare function init(options?: InitOptions): Promise<void>;
+/** Restores the original global fetch. Intended for tests. */
+declare function uninstall(): void;
+
+type OrchidMode = "capture" | "replay" | "passthrough" | "log";
+interface OrchidContext {
+    sessionId: string;
+    mode: OrchidMode;
+}
+/** Returns the active session ID, falling back to ORCHID_SESSION_ID. */
+declare function currentSessionId(): string | undefined;
+/** Returns the active mode, falling back to ORCHID_MODE. */
+declare function currentMode(): string | undefined;
+/**
+ * Runs `fn` with the given Orchid session context. All requests dispatched
+ * (transitively) inside `fn` are grouped under `sessionId` with the given mode.
+ *
+ * ```ts
+ * await session("user-onboarding-flow", "capture", async () => {
+ *   await client.chat.completions.create({ ... });
+ * });
+ * ```
+ */
+declare function session<T>(sessionId: string, mode: OrchidMode, fn: () => T): T;
+
+/**
+ * Control client for managing the Orchid capture/replay database.
+ * Provides methods to perform health checks, export captured sessions,
+ * and import fixtures into the Orchid Proxy.
+ */
+declare class OrchidControlClient {
+    readonly queryUrl: string;
+    readonly apiKey?: string;
+    /**
+     * @param queryUrl URL of the Orchid Query service (default: http://127.0.0.1:4321).
+     * @param apiKey API key for authenticating with the control plane.
+     */
+    constructor(queryUrl?: string, apiKey?: string);
+    private headers;
+    /** Checks the health of the Orchid Query service. */
+    checkHealth(): Promise<boolean>;
+    /**
+     * Exports all captured exchanges for a session from the proxy and saves
+     * them to a local JSON fixture file.
+     */
+    exportFixture(sessionId: string, path: string): Promise<boolean>;
+    /**
+     * Reads a local JSON fixture file and imports its exchanges into the
+     * Orchid Proxy database.
+     *
+     * @throws If the fixture file does not exist or the import request fails.
+     */
+    importFixture(path: string): Promise<boolean>;
+}
+
+/**
+ * Runs `fn` with capture/replay backed by a JSON fixture file. Framework
+ * agnostic — works as a plain wrapper in vitest, jest, or node:test.
+ *
+ * - If `ORCHID_RECORD=1`: runs `fn` in capture mode and exports the session's
+ *   HTTP traffic to the fixture path afterwards.
+ * - Otherwise: imports the fixture into the proxy and runs `fn` in replay
+ *   mode, serving mocked responses with no external network calls.
+ *
+ * ```ts
+ * test("user greeting", () =>
+ *   withReplay("tests/fixtures/test_user_greeting.json", async () => {
+ *     const response = await client.chat.completions.create({ ... });
+ *     expect(response.choices[0].message.content).toMatch(/hello/i);
+ *   }));
+ * ```
+ *
+ * @param fixturePath Local JSON file path where traffic is saved/replayed.
+ * @param fn The function to run under the fixture's session.
+ * @param options.sessionId Session ID override; defaults to the fixture's
+ *   recorded session ID, then the fixture file's base name.
+ */
+declare function withReplay<T>(fixturePath: string, fn: () => Promise<T>, options?: {
+    sessionId?: string;
+}): Promise<T>;
+
+export { type InitOptions, type OrchidContext, OrchidControlClient, type OrchidMode, currentMode, currentSessionId, init, orchidFetch, session, uninstall, withReplay };

package/dist/index.js

@@ -0,0 +1,312 @@
+// src/context.ts
+import { AsyncLocalStorage } from "async_hooks";
+var storage = new AsyncLocalStorage();
+function currentSessionId() {
+  return storage.getStore()?.sessionId ?? process.env.ORCHID_SESSION_ID ?? void 0;
+}
+function currentMode() {
+  return storage.getStore()?.mode ?? process.env.ORCHID_MODE ?? void 0;
+}
+function session(sessionId, mode, fn) {
+  return storage.run({ sessionId, mode }, fn);
+}
+
+// src/core.ts
+var CORE_PROVIDERS = [
+  "api.openai.com",
+  "api.anthropic.com",
+  "generativelanguage.googleapis.com",
+  "aiplatform.googleapis.com"
+];
+var LOCAL_HOSTS = ["localhost", "127.0.0.1", "::1", "[::1]"];
+var patched = false;
+var offlineFallback = false;
+var originalFetch;
+function proxyUrl() {
+  return process.env.ORCHID_PROXY_URL ?? "http://127.0.0.1:4320/v1";
+}
+function envList(name) {
+  return (process.env[name] ?? "").split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+function isCoreProvider(host) {
+  return CORE_PROVIDERS.some((c) => host.includes(c));
+}
+function shouldIntercept(url) {
+  if (offlineFallback) return false;
+  const host = url.hostname;
+  if (LOCAL_HOSTS.some((h) => host === h)) return false;
+  if (envList("ORCHID_IGNORE_DOMAINS").some((d) => host.includes(d))) {
+    return false;
+  }
+  if (isCoreProvider(host)) return true;
+  const capture = envList("ORCHID_CAPTURE_DOMAINS");
+  if (capture.includes("*")) return true;
+  if (capture.some((d) => host.includes(d))) return true;
+  return false;
+}
+function rewriteUrl(originalUrl) {
+  const proxy = new URL(proxyUrl());
+  const rewritten = new URL(originalUrl.toString());
+  rewritten.protocol = proxy.protocol;
+  rewritten.host = proxy.host;
+  if (isCoreProvider(originalUrl.hostname)) {
+    const proxyBasePath = proxy.pathname.replace(/\/+$/, "");
+    if (proxyBasePath && !originalUrl.pathname.startsWith(proxyBasePath)) {
+      rewritten.pathname = proxyBasePath + originalUrl.pathname;
+    }
+  }
+  return rewritten;
+}
+function injectHeaders(headers, targetUrl, originalUrl) {
+  const proxy = new URL(proxyUrl());
+  if (targetUrl.host !== proxy.host) return;
+  const proxyKey = process.env.ORCHID_PROXY_KEY;
+  if (proxyKey) headers.set("X-Orchid-Proxy-Key", proxyKey);
+  const sessionId = currentSessionId();
+  let mode = currentMode();
+  if (sessionId) {
+    headers.set("X-Orchid-Session-Id", sessionId);
+    if (!mode) mode = "capture";
+  }
+  if (mode) headers.set("X-Orchid-Mode", mode);
+  if (originalUrl && originalUrl.host !== proxy.host) {
+    headers.set(
+      "X-Orchid-Target-Url",
+      `${originalUrl.protocol}//${originalUrl.host}`
+    );
+  }
+}
+function purgeOrchidHeaders(headers) {
+  const toDelete = [];
+  headers.forEach((_value, key) => {
+    if (key.toLowerCase().startsWith("x-orchid-")) toDelete.push(key);
+  });
+  for (const key of toDelete) headers.delete(key);
+}
+function isConnectionError(err) {
+  if (!(err instanceof Error)) return false;
+  const cause = err.cause;
+  const code = cause?.code ?? err.code;
+  return code === "ECONNREFUSED" || code === "ECONNRESET" || code === "EHOSTUNREACH" || code === "ENOTFOUND" || code === "ETIMEDOUT" || code === "UND_ERR_CONNECT_TIMEOUT" || code === "UND_ERR_SOCKET";
+}
+var orchidFetch = async (input, init2) => {
+  const baseFetch = originalFetch ?? globalThis.fetch;
+  const request = new Request(input, init2);
+  const original = new URL(request.url);
+  if (!shouldIntercept(original)) {
+    const headers2 = new Headers(request.headers);
+    injectHeaders(headers2, original);
+    return baseFetch(new Request(request, { headers: headers2 }));
+  }
+  const rewritten = rewriteUrl(original);
+  const headers = new Headers(request.headers);
+  injectHeaders(headers, rewritten, original);
+  const proxied = new Request(rewritten, {
+    method: request.method,
+    headers,
+    body: request.body,
+    // Required by undici when streaming a body
+    ...request.body ? { duplex: "half" } : {},
+    redirect: request.redirect,
+    signal: request.signal
+  });
+  try {
+    return await baseFetch(proxied);
+  } catch (err) {
+    if (!isConnectionError(err)) throw err;
+    console.warn(
+      `[orchid] Proxy connection failed (${String(err)}). Falling back to direct routing: ${original}`
+    );
+    const fallbackHeaders = new Headers(request.headers);
+    purgeOrchidHeaders(fallbackHeaders);
+    return baseFetch(
+      new Request(original, {
+        method: request.method,
+        headers: fallbackHeaders,
+        body: request.body,
+        ...request.body ? { duplex: "half" } : {},
+        redirect: request.redirect,
+        signal: request.signal
+      })
+    );
+  }
+};
+function deriveQueryUrl() {
+  const explicit = process.env.ORCHID_QUERY_URL;
+  if (explicit) return explicit;
+  const proxy = new URL(proxyUrl());
+  if (proxy.port === "4320") proxy.port = "4321";
+  proxy.pathname = "";
+  return proxy.toString().replace(/\/+$/, "");
+}
+async function proxyIsHealthy() {
+  const baseFetch = originalFetch ?? globalThis.fetch;
+  try {
+    const resp = await baseFetch(`${deriveQueryUrl()}/health`, {
+      signal: AbortSignal.timeout(1e3)
+    });
+    return resp.status === 200;
+  } catch {
+    return false;
+  }
+}
+async function init(options = {}) {
+  offlineFallback = false;
+  const proxy = proxyUrl();
+  let parsed;
+  try {
+    parsed = new URL(proxy);
+  } catch {
+    throw new Error(`Malformed ORCHID_PROXY_URL: ${proxy}`);
+  }
+  if (!parsed.protocol || !parsed.host) {
+    throw new Error(`Malformed ORCHID_PROXY_URL: ${proxy}`);
+  }
+  const bypass = options.bypassHealthCheck === true || process.env.ORCHID_BYPASS_HEALTHCHECK === "True" || process.env.VITEST !== void 0;
+  if (!bypass) {
+    offlineFallback = !await proxyIsHealthy();
+  }
+  if (!offlineFallback) {
+    process.env.OPENAI_BASE_URL = proxy;
+  }
+  if (!patched && !offlineFallback) {
+    originalFetch = globalThis.fetch;
+    globalThis.fetch = orchidFetch;
+    patched = true;
+  }
+}
+function uninstall() {
+  if (patched && originalFetch) {
+    globalThis.fetch = originalFetch;
+    originalFetch = void 0;
+    patched = false;
+  }
+  offlineFallback = false;
+}
+
+// src/client.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname } from "path";
+var OrchidControlClient = class {
+  queryUrl;
+  apiKey;
+  /**
+   * @param queryUrl URL of the Orchid Query service (default: http://127.0.0.1:4321).
+   * @param apiKey API key for authenticating with the control plane.
+   */
+  constructor(queryUrl, apiKey) {
+    this.queryUrl = queryUrl ?? process.env.ORCHID_QUERY_URL ?? "http://127.0.0.1:4321";
+    this.apiKey = apiKey ?? process.env.ORCHID_API_KEY ?? void 0;
+  }
+  headers() {
+    return this.apiKey ? { "X-Orchid-Api-Key": this.apiKey } : {};
+  }
+  /** Checks the health of the Orchid Query service. */
+  async checkHealth() {
+    try {
+      const resp = await fetch(`${this.queryUrl}/health`, {
+        headers: this.headers(),
+        signal: AbortSignal.timeout(5e3)
+      });
+      return resp.status === 200;
+    } catch (err) {
+      console.warn(`[orchid] Query service health check failed: ${String(err)}`);
+      return false;
+    }
+  }
+  /**
+   * Exports all captured exchanges for a session from the proxy and saves
+   * them to a local JSON fixture file.
+   */
+  async exportFixture(sessionId, path) {
+    try {
+      const resp = await fetch(
+        `${this.queryUrl}/v1/sessions/${encodeURIComponent(sessionId)}/export`,
+        { headers: this.headers() }
+      );
+      if (resp.status === 404) {
+        console.warn(`[orchid] Session ${sessionId} not found to export.`);
+        return false;
+      }
+      if (!resp.ok) {
+        throw new Error(`Export failed with status ${resp.status}`);
+      }
+      const fixture = await resp.json();
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, JSON.stringify(fixture, null, 2));
+      return true;
+    } catch (err) {
+      console.warn(
+        `[orchid] Failed to export fixture for session ${sessionId} to ${path}: ${String(err)}`
+      );
+      return false;
+    }
+  }
+  /**
+   * Reads a local JSON fixture file and imports its exchanges into the
+   * Orchid Proxy database.
+   *
+   * @throws If the fixture file does not exist or the import request fails.
+   */
+  async importFixture(path) {
+    const raw = await readFile(path, "utf-8");
+    const fixture = JSON.parse(raw);
+    const resp = await fetch(`${this.queryUrl}/v1/sessions/import`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...this.headers() },
+      body: JSON.stringify(fixture)
+    });
+    if (!resp.ok) {
+      throw new Error(`Import failed with status ${resp.status}`);
+    }
+    return resp.status === 201;
+  }
+};
+
+// src/replay.ts
+import { readFile as readFile2 } from "fs/promises";
+import { existsSync } from "fs";
+import { basename, extname } from "path";
+function recordMode() {
+  return ["1", "true", "yes"].includes(
+    (process.env.ORCHID_RECORD ?? "").toLowerCase()
+  );
+}
+async function fixtureSessionId(path) {
+  if (!existsSync(path)) return void 0;
+  try {
+    const data = JSON.parse(await readFile2(path, "utf-8"));
+    return data?.session?.id ?? void 0;
+  } catch {
+    return void 0;
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function withReplay(fixturePath, fn, options = {}) {
+  const client = new OrchidControlClient();
+  const sessionId = options.sessionId ?? await fixtureSessionId(fixturePath) ?? basename(fixturePath, extname(fixturePath));
+  if (recordMode()) {
+    const result = await session(sessionId, "capture", fn);
+    const flushSleep = Number(process.env.ORCHID_FLUSH_SLEEP ?? "0.2");
+    if (flushSleep > 0) await sleep(flushSleep * 1e3);
+    await client.exportFixture(sessionId, fixturePath);
+    return result;
+  }
+  if (!existsSync(fixturePath)) {
+    throw new Error(`Fixture file not found: ${fixturePath}`);
+  }
+  await client.importFixture(fixturePath);
+  return session(sessionId, "replay", fn);
+}
+export {
+  OrchidControlClient,
+  currentMode,
+  currentSessionId,
+  init,
+  orchidFetch,
+  session,
+  uninstall,
+  withReplay
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "orchid-sdk",
+  "version": "0.1.0",
+  "description": "Thin TypeScript SDK for Orchid — the Orchestration Interactive Debugger. Routes outbound LLM requests through the local Orchid Proxy for capture, replay, and interactive debugging.",
+  "author": "Orchid Team <team@orchid.dev>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mario-guerra/orchid.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mario-guerra/orchid/issues"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "orchid",
+    "llm",
+    "proxy",
+    "capture",
+    "replay",
+    "debugging",
+    "observability"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}