@sovara/runner 0.4.4 → 0.4.6

package/README.md

@@ -1,8 +1,8 @@
 # @sovara/runner
 
 TypeScript runner for [Sovara](https://docs.sovara-labs.com) — wrap your script in a
-single function and Sovara records every LLM call, tool invocation, and log
-line into structured run steps.
+single function and Sovara records supported LLM, MCP, and framework tool
+calls, plus log lines, as structured run steps.
 
 The runner is the TS counterpart to the Python `sovara` runner. It targets
 the same Sovara server, produces the same step shapes, and is safe to mix
@@ -14,8 +14,8 @@ Documentation: https://docs.sovara-labs.com
 
 - Node 18 or newer (built-in `fetch`).
 - A reachable Sovara backend. For local use, open the Sovara desktop app.
-  Enterprise agent projects should use their project-specific connection flow.
-- A Sovara user and project, configured once with `sovara init`.
+  Remote agent hosts use a project-scoped agent token.
+- A Sovara project name for `new SovaraClient({ projectName })`.
 
 ## Install
 
@@ -37,13 +37,14 @@ npm install @anthropic-ai/claude-agent-sdk
 ## Quick start
 
 ```ts
-import { withSovaraRun } from "@sovara/runner";
 import OpenAI from "openai";
+import { SovaraClient } from "@sovara/runner";
 
-const openai = new OpenAI();
+const openai_client = new OpenAI();
+const sovara_client = new SovaraClient({ projectName: "My Project" });
 
-await withSovaraRun("hello-world", async () => {
-  const response = await openai.responses.create({
+await sovara_client.run("hello-world", async () => {
+  const response = await openai_client.responses.create({
     model: "gpt-5",
     input: "Say hello.",
   });
@@ -56,16 +57,21 @@ That's the full integration. The call to OpenAI is captured automatically;
 `console.log` output is captured as run logs; the run shows up in the
 Sovara UI.
 
+OpenAI Agents function tools created with `tool()` and MCP calls are also
+captured automatically inside a run. Use `trace` only for important custom
+operations that are not already captured.
+
 ## How it works
 
-Importing `@sovara/runner` patches two transports at module load:
+Importing `@sovara/runner` patches the supported provider transports at module
+load, including:
 
 - `globalThis.fetch` — wraps every `fetch` call.
 - `node:http` and `node:https` — wraps `http.request` / `http.get` and
   their HTTPS counterparts. This covers `axios` and any library that uses
   Node's HTTP modules directly.
 
-Inside `withSovaraRun(...)`, calls to whitelisted endpoints are observed:
+Inside `sovara_client.run(...)`, calls to whitelisted endpoints are observed:
 the runner builds a request envelope, posts it to the Sovara server's
 `/internal/runner/llm/prepare` endpoint (which optionally applies
 runtime preparation such as lessons injection), executes the prepared
@@ -90,84 +96,99 @@ completes.
 
 ## API
 
-### `withSovaraRun(name | options, fn)`
+### `new SovaraClient(options)`
 
 ```ts
-export type WithSovaraRunOptions = {
-  name: string; // required run name
+export type SovaraClientOptions = {
+  projectName: string; // required Sovara project name
+  url?: string; // exec server URL (default: http://127.0.0.1:5960)
+  agentToken?: string; // optional project-scoped agent token
+  fetch?: typeof globalThis.fetch; // optional caller-owned transport
+};
+
+export type SovaraRunOptions = {
   clientRunId?: string; // optional project-scoped correlation id
-  url?: string; // server URL (default: http://127.0.0.1:5959)
   captureLogs?: boolean; // default: true
-  project?: { name?: string; description?: string };
+  lessonScope?: string | string[] | null; // optional lesson folder scope
 };
 
-export function withSovaraRun<T>(
-  input: string | WithSovaraRunOptions,
-  fn: () => Promise<T> | T,
-): Promise<T>;
+export class SovaraClient {
+  run<T>(
+    name: string,
+    fn: () => Promise<T> | T,
+    options?: SovaraRunOptions,
+  ): Promise<T>;
+}
 ```
 
-The string form is shorthand for `{ name: input }`. The runner returns
+The client owns project identity and connection configuration. `run()` returns
 whatever `fn` returns.
 
 **Top-level call** (no parent run on the stack):
 
 1. Health-checks the configured server and fails fast if it is unreachable.
-2. Resolves the active user. Fails hard with a `sovara init` hint if
-   user setup is missing.
-3. Resolves the project for `process.cwd()`. Fails hard with a `sovara init`
-   hint if the cwd isn't part of a known Sovara project.
-4. Registers the run, runs `fn` inside an `AsyncLocalStorage` scope, and
+2. Uses the client's `projectName` and `process.cwd()` metadata for the run.
+3. Registers the run, runs `fn` inside an `AsyncLocalStorage` scope, and
    deregisters in `finally`.
 
-**Nested top-level call** (called from inside another `withSovaraRun`):
+**Nested top-level call** (called from inside another `sovara_client.run()`):
 
-The nested `withSovaraRun` call is ignored with a warning and `fn` runs inside
-the existing active scope. Use `withSovaraSubrun(...)` for child execution.
+The nested run is ignored with a warning and `fn` runs inside the existing
+active scope. Use `sovara_client.subrun(...)` for child execution.
 
-`fn` exceptions propagate untouched. The run is deregistered in either
-case.
+`fn` exceptions propagate untouched. The run is deregistered in either case.
 
 ### Subruns
 
 ```ts
-await withSovaraRun("pipeline", async () => {
-  const docs = await withSovaraSubrun("retrieve", async () => loadDocs());
-  await withSovaraSubrun("summarize", async () => summarize(docs));
+await sovara_client.run("pipeline", async () => {
+  const docs = await sovara_client.subrun("retrieve", async () => loadDocs());
+  await sovara_client.subrun("summarize", async () => summarize(docs));
 });
 ```
 
-Every explicit `withSovaraSubrun` becomes a child run under the active scope.
+Every explicit `sovara_client.subrun(...)` becomes a child run under the active
+scope.
 
 ### Logs
 
 Standard `console.log`, `console.error`, and any direct writes to
-`process.stdout` / `process.stderr` are captured into the run log
-buffer and flushed to the server every 250ms.
+`process.stdout` / `process.stderr` are captured into the run log buffer and
+flushed to the server every 250ms.
 
 Disable with `captureLogs: false`:
 
 ```ts
-await withSovaraRun({ name: "noisy", captureLogs: false }, async () => {
-  // stdout/stderr will not be tee'd to the server
-});
+await sovara_client.run(
+  "noisy",
+  async () => {
+    // stdout/stderr will not be tee'd to the server
+  },
+  { captureLogs: false },
+);
 ```
 
-### User and project overrides
+### Project and server
 
 ```ts
-await withSovaraRun(
-  {
-    name: "billing-job",
-    user: { fullName: "CI Bot", email: "ci@example.com" },
-    project: { name: "Billing", description: "Nightly invoice run" },
-  },
-  async () => doWork(),
-);
+const sovara_client = new SovaraClient({ projectName: "Billing" });
+await sovara_client.run("billing-job", async () => doWork());
 ```
 
-Overrides are only applied if user/project are present. They don't bypass
-the `sovara init` requirement — they just refine the values.
+Pass `projectName` once when constructing the client. A remote agent host can
+also configure its exec URL and project-scoped token there. The custom `fetch`
+is optional:
+
+```ts
+const sovara_client = new SovaraClient({
+  projectName: "Billing",
+  url: "https://exec.example.com",
+  agentToken: process.env.SOVARA_AGENT_TOKEN,
+  fetch: customFetch,
+});
+
+await sovara_client.run("billing-job", async () => doWork());
+```
 
 ### `trace(fn, options?)`
 
@@ -176,7 +197,9 @@ HTTP call on its own, but should still appear as a tool step in the Sovara
 run steps.
 
 ```ts
-import { trace, withSovaraRun } from "@sovara/runner";
+import { SovaraClient, trace } from "@sovara/runner";
+
+const sovara_client = new SovaraClient({ projectName: "My Project" });
 
 const lookupCustomer = trace(
   async function lookupCustomer(customerId: string) {
@@ -185,7 +208,7 @@ const lookupCustomer = trace(
   { meta: { system: "crm" } },
 );
 
-await withSovaraRun("support-agent", async () => {
+await sovara_client.run("support-agent", async () => {
   const customer = await lookupCustomer("cust_123");
   // Continue your agent flow with customer.
 });
@@ -194,8 +217,9 @@ await withSovaraRun("support-agent", async () => {
 `trace` records function arguments as the step input and the return value as
 the step output. If the wrapped function throws, the error type and message
 are recorded and the original exception is re-thrown. Outside an active
-`withSovaraRun(...)` scope, the wrapper calls the function normally without
-recording anything.
+`sovara_client.run(...)` scope, the wrapper calls the function normally without
+recording anything. Do not also wrap OpenAI Agents `tool()` functions or MCP
+tools; Sovara captures those automatically.
 
 ```ts
 export type TraceOptions = {
@@ -246,16 +270,18 @@ That single import change is the entire integration. The wrapper:
   matches the Python runner's behavior.
 - Throws if `options.env.ANTHROPIC_BASE_URL` already points at the
   Sovara proxy, to prevent infinite proxy loops.
-- Outside a `withSovaraRun` scope, `query()` and `startup()` are
+- Outside a `sovara_client.run(...)` scope, `query()` and `startup()` are
   pass-throughs to the real SDK with zero overhead.
 
 ### Example
 
 ```ts
-import { withSovaraRun } from "@sovara/runner";
+import { SovaraClient } from "@sovara/runner";
 import { query } from "@sovara/runner/claude";
 
-await withSovaraRun("agent-task", async () => {
+const sovara_client = new SovaraClient({ projectName: "My Project" });
+
+await sovara_client.run("agent-task", async () => {
   for await (const message of query({
     prompt: "List the largest files in the current directory.",
   })) {
@@ -287,16 +313,26 @@ for await (const message of handle.query("What did I install last?")) {
 | ---------------------------- | -------------------------------------------------------------------------- | ----------------------- |
 | `SOVARA_EXEC_SERVER_PORT`    | Exec server port (used to compute the default URL)                         | `5960`                  |
 | `SOVARA_EXEC_SERVER_URL`     | Explicit exec server URL                                                   | `http://127.0.0.1:5960` |
+| `SOVARA_AGENT_TOKEN`         | Project-scoped token for a remote/headless agent                           | unset                   |
 | `SOVARA_CLAUDE_PROXY_ACTIVE` | Set automatically by `@sovara/runner/claude` to prevent nested proxy loops | unset                   |
 
 ### Server URL
 
-The TypeScript runner uses the local exec server by default. Pass `url` per call only when the caller explicitly manages a different exec-server connection:
+The TypeScript runner uses the local exec server by default. Pass `url` when
+constructing the client if the caller manages a different exec-server connection:
 
 ```ts
-await withSovaraRun({ name: "demo", url: "http://localhost:6000" }, fn);
+const sovara_client = new SovaraClient({
+  projectName: "My Project",
+  url: "http://localhost:6000",
+});
+
+await sovara_client.run("demo", fn);
 ```
 
+Pass `agentToken` for remote project authentication. It falls back to
+`SOVARA_AGENT_TOKEN`. Pass `fetch` only when a caller-owned transport is needed.
+
 ## Error messages
 
 The runner fails fast for misconfiguration. Common ones:
@@ -304,8 +340,8 @@ The runner fails fast for misconfiguration. Common ones:
 - **`Sovara exec server is not reachable at <url>. Run sovara-exec-server start or use the Sovara CLI package that bundles it.`**
   Start the exec server or pass `url` when the caller owns exec-server setup.
 
-- **``Sovara project setup is missing for <cwd>. Run `sovara init --project-root "<cwd>" --project-name <project-name>` and retry.``**
-  Run the suggested `sovara init` command.
+- **`projectName is required.`**
+  Pass `projectName` to `new SovaraClient(...)`.
 
 - **`Custom Claude Agent SDK transports are not supported yet under sovara.`**
   Remove `options.transport` from your `query()` / `startup()` call.

package/dist/apiTypes.d.ts

@@ -1,4 +1,5 @@
 export declare const API_TYPE_HTTPX_CLIENT_SEND = "httpx.Client.send";
 export declare const API_TYPE_HTTPX_ASYNC_CLIENT_SEND = "httpx.AsyncClient.send";
 export declare const API_TYPE_MCP_CLIENT_SESSION_SEND_REQUEST = "MCP.ClientSession.send_request";
+export declare const API_TYPE_OPENAI_AGENTS_FUNCTION_TOOL_RUN = "openai_agents.FunctionTool.run";
 //# sourceMappingURL=apiTypes.d.ts.map

package/dist/apiTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apiTypes.d.ts","sourceRoot":"","sources":["../src/apiTypes.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,0BAA0B,sBAAsB,CAAC;AAC9D,eAAO,MAAM,gCAAgC,2BAA2B,CAAC;AACzE,eAAO,MAAM,wCAAwC,mCAAmC,CAAC"}
+{"version":3,"file":"apiTypes.d.ts","sourceRoot":"","sources":["../src/apiTypes.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,0BAA0B,sBAAsB,CAAC;AAC9D,eAAO,MAAM,gCAAgC,2BAA2B,CAAC;AACzE,eAAO,MAAM,wCAAwC,mCAAmC,CAAC;AACzF,eAAO,MAAM,wCAAwC,mCAAmC,CAAC"}

package/dist/apiTypes.js

@@ -1,4 +1,5 @@
 export const API_TYPE_HTTPX_CLIENT_SEND = "httpx.Client.send";
 export const API_TYPE_HTTPX_ASYNC_CLIENT_SEND = "httpx.AsyncClient.send";
 export const API_TYPE_MCP_CLIENT_SESSION_SEND_REQUEST = "MCP.ClientSession.send_request";
+export const API_TYPE_OPENAI_AGENTS_FUNCTION_TOOL_RUN = "openai_agents.FunctionTool.run";
 //# sourceMappingURL=apiTypes.js.map

package/dist/apiTypes.js.map

@@ -1 +1 @@
-{"version":3,"file":"apiTypes.js","sourceRoot":"","sources":["../src/apiTypes.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,0BAA0B,GAAG,mBAAmB,CAAC;AAC9D,MAAM,CAAC,MAAM,gCAAgC,GAAG,wBAAwB,CAAC;AACzE,MAAM,CAAC,MAAM,wCAAwC,GAAG,gCAAgC,CAAC"}
+{"version":3,"file":"apiTypes.js","sourceRoot":"","sources":["../src/apiTypes.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,0BAA0B,GAAG,mBAAmB,CAAC;AAC9D,MAAM,CAAC,MAAM,gCAAgC,GAAG,wBAAwB,CAAC;AACzE,MAAM,CAAC,MAAM,wCAAwC,GAAG,gCAAgC,CAAC;AACzF,MAAM,CAAC,MAAM,wCAAwC,GAAG,gCAAgC,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,35 @@
+import { type LessonScopeInput } from "./context.js";
+import type { MetricValue } from "./runtimeClient.js";
+export type SovaraClientOptions = {
+    projectName: string;
+    url?: string;
+    agentToken?: string;
+    fetch?: typeof globalThis.fetch;
+};
+export type SovaraRunOptions = {
+    clientRunId?: string;
+    captureLogs?: boolean;
+    lessonScope?: LessonScopeInput;
+};
+export type SovaraSubrunOptions = {
+    lessonScope?: LessonScopeInput;
+};
+type RunFunction<T> = () => Promise<T> | T;
+export declare class SovaraClient {
+    readonly projectName: string;
+    private readonly url?;
+    private readonly agentToken?;
+    private readonly fetch?;
+    constructor(options: SovaraClientOptions);
+    run<T>(name: string, fn: RunFunction<T>, options?: SovaraRunOptions): Promise<T>;
+    subrun<T>(name: string, fn: RunFunction<T>, options?: SovaraSubrunOptions): Promise<T>;
+    lessonScope<T>(scope: LessonScopeInput, fn: RunFunction<T>): Promise<T>;
+    logInput(input: unknown): Promise<void>;
+    logOutput(output: unknown): Promise<void>;
+    logMetrics(metrics: Record<string, MetricValue>): Promise<void>;
+    injectLessons(context: unknown): Promise<string>;
+    queueForAnnotation(): Promise<void>;
+    getRunId(): string | undefined;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAUL,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,MAAM,MAAM,mBAAmB,GAAG;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,gBAAgB,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,WAAW,CAAC,EAAE,gBAAgB,CAAC;CAChC,CAAC;AAEF,KAAK,WAAW,CAAC,CAAC,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAE3C,qBAAa,YAAY;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAA0B;gBAErC,OAAO,EAAE,mBAAmB;IAUxC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,CAAC,CAAC;IAcpF,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,CAAC,CAAC;IAI1F,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIvE,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/D,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAIhD,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAInC,QAAQ,IAAI,MAAM,GAAG,SAAS;CAG/B"}

package/dist/client.js

@@ -0,0 +1,52 @@
+import { getRunId, logInput, logMetrics, logOutput, normalizeProjectName, queueForAnnotation, withLessonScope, withSovaraRun, withSovaraSubrun, } from "./context.js";
+import { injectLessons } from "./lessons.js";
+export class SovaraClient {
+    projectName;
+    url;
+    agentToken;
+    fetch;
+    constructor(options) {
+        if (!options || typeof options !== "object") {
+            throw new TypeError("SovaraClient requires an options object with projectName.");
+        }
+        this.projectName = normalizeProjectName(options.projectName);
+        this.url = options.url;
+        this.agentToken = options.agentToken;
+        this.fetch = options.fetch;
+    }
+    run(name, fn, options = {}) {
+        return withSovaraRun({
+            ...options,
+            name,
+            projectName: this.projectName,
+            url: this.url,
+            agentToken: this.agentToken,
+            fetch: this.fetch,
+        }, fn);
+    }
+    subrun(name, fn, options = {}) {
+        return withSovaraSubrun({ name, ...options }, fn);
+    }
+    lessonScope(scope, fn) {
+        return withLessonScope(scope, fn);
+    }
+    logInput(input) {
+        return logInput(input);
+    }
+    logOutput(output) {
+        return logOutput(output);
+    }
+    logMetrics(metrics) {
+        return logMetrics(metrics);
+    }
+    injectLessons(context) {
+        return injectLessons(context);
+    }
+    queueForAnnotation() {
+        return queueForAnnotation();
+    }
+    getRunId() {
+        return getRunId();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,SAAS,EACT,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,gBAAgB,GAEjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAsB7C,MAAM,OAAO,YAAY;IACd,WAAW,CAAS;IACZ,GAAG,CAAU;IACb,UAAU,CAAU;IACpB,KAAK,CAA2B;IAEjD,YAAY,OAA4B;QACtC,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC5C,MAAM,IAAI,SAAS,CAAC,2DAA2D,CAAC,CAAC;QACnF,CAAC;QACD,IAAI,CAAC,WAAW,GAAG,oBAAoB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC7D,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC7B,CAAC;IAED,GAAG,CAAI,IAAY,EAAE,EAAkB,EAAE,UAA4B,EAAE;QACrE,OAAO,aAAa,CAClB;YACE,GAAG,OAAO;YACV,IAAI;YACJ,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB,EACD,EAAE,CACH,CAAC;IACJ,CAAC;IAED,MAAM,CAAI,IAAY,EAAE,EAAkB,EAAE,UAA+B,EAAE;QAC3E,OAAO,gBAAgB,CAAC,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,WAAW,CAAI,KAAuB,EAAE,EAAkB;QACxD,OAAO,eAAe,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,QAAQ,CAAC,KAAc;QACrB,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IAED,SAAS,CAAC,MAAe;QACvB,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAED,UAAU,CAAC,OAAoC;QAC7C,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAED,aAAa,CAAC,OAAgB;QAC5B,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAED,kBAAkB;QAChB,OAAO,kBAAkB,EAAE,CAAC;IAC9B,CAAC;IAED,QAAQ;QACN,OAAO,QAAQ,EAAE,CAAC;IACpB,CAAC;CACF"}

package/dist/context.d.ts

@@ -1,10 +1,12 @@
 import { RuntimeClient, type MetricValue } from "./runtimeClient.js";
 export type WithSovaraRunOptions = {
-    name: string;
+    name?: string;
     clientRunId?: string;
     url?: string;
+    agentToken?: string;
+    fetch?: typeof globalThis.fetch;
     captureLogs?: boolean;
-    projectName?: string;
+    projectName: string;
     lessonScope?: LessonScopeInput;
     __testing?: {
         client?: RunScopeClient;
@@ -23,12 +25,12 @@ export type RunScope = {
     client: RunScopeClient;
     lessonScopePaths: string[] | null;
 };
-export declare const client: RuntimeClient;
 export type WithSovaraSubrunOptions = {
     name: string;
     lessonScope?: LessonScopeInput;
 };
 export type LessonScopeInput = string | string[] | null | undefined;
+export declare function normalizeProjectName(projectName: unknown): string;
 export declare function normalizeLessonScope(scope: LessonScopeInput): string[] | null;
 export declare function getCurrentRunScope(): RunScope | undefined;
 export declare function getRunId(): string | undefined;
@@ -36,7 +38,7 @@ export declare function logMetrics(metrics: Record<string, MetricValue>): Promis
 export declare function logInput(input: unknown): Promise<void>;
 export declare function logOutput(output: unknown): Promise<void>;
 export declare function queueForAnnotation(): Promise<void>;
-export declare function withSovaraRun<T>(input: string | WithSovaraRunOptions, fn: () => Promise<T> | T): Promise<T>;
+export declare function withSovaraRun<T>(input: WithSovaraRunOptions, fn: () => Promise<T> | T): Promise<T>;
 export declare function withSovaraSubrun<T>(input: string | WithSovaraSubrunOptions, fn: () => Promise<T> | T): Promise<T>;
 export declare function withLessonScope<T>(lessonScope: LessonScopeInput, fn: () => Promise<T> | T): Promise<T>;
 export {};

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,aAAa,EAAsB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAMzF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,SAAS,CAAC,EAAE;QACV,MAAM,CAAC,EAAE,cAAc,CAAC;QACxB,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;CACH,CAAC;AAEF,KAAK,yBAAyB,GAC1B,gBAAgB,GAChB,eAAe,GACf,cAAc,GACd,aAAa,GACb,aAAa,GACb,cAAc,GACd,iBAAiB,CAAC;AAEtB,KAAK,sBAAsB,GACvB,YAAY,GACZ,UAAU,GACV,WAAW,GACX,6BAA6B,CAAC;AAElC,KAAK,2BAA2B,GAAG,2BAA2B,CAAC;AAE/D,KAAK,4BAA4B,GAAG,cAAc,GAAG,iBAAiB,CAAC;AAEvE,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,aAAa,EAAE,yBAAyB,CAAC,GACzE,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,sBAAsB,CAAC,CAAC,GACpD,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,2BAA2B,GAAG,4BAA4B,CAAC,CAAC,CAAC;AAE3F,MAAM,MAAM,QAAQ,GAAG;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,cAAc,CAAC;IACvB,gBAAgB,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CACnC,CAAC;AAKF,eAAO,MAAM,MAAM,eAA4C,CAAC;AAEhE,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,gBAAgB,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,CAAC;AAyCpE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,EAAE,GAAG,IAAI,CAgB7E;AAyCD,wBAAgB,kBAAkB,IAAI,QAAQ,GAAG,SAAS,CAEzD;AAUD,wBAAgB,QAAQ,IAAI,MAAM,GAAG,SAAS,CAE7C;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAKpF;AAED,wBAAsB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAK5D;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAK9D;AAED,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKxD;AAED,wBAAsB,aAAa,CAAC,CAAC,EACnC,KAAK,EAAE,MAAM,GAAG,oBAAoB,EACpC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CA6GZ;AAED,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,KAAK,EAAE,MAAM,GAAG,uBAAuB,EACvC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CA2BZ;AAED,wBAAsB,eAAe,CAAC,CAAC,EACrC,WAAW,EAAE,gBAAgB,EAC7B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CASZ"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/context.js

@@ -1,30 +1,79 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { loadAgentConnection, resolveProjectConfig } from "./agentCredentials.js";
+import { randomUUID } from "node:crypto";
+import { renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
 import { collectCodeVersion } from "./codeVersion.js";
 import { readRunnerConfig } from "./env.js";
 import { installRunLogCapture } from "./runLogCapture.js";
 import { RuntimeClient, RuntimeClientError } from "./runtimeClient.js";
 import { ensureServerRunning } from "./serverLifecycle.js";
-import { isDegraded, markDegraded, raiseIfConfigError, SovaraConfigError } from "./failsafe.js";
+import { isDegraded, markDegraded, raiseIfConfigError } from "./failsafe.js";
 import { ensureMcpPatchInstalled } from "./mcpPatch.js";
+import { ensureOpenAIAgentsPatchInstalled } from "./openaiAgentsPatch.js";
 import { warnOnce } from "./util/logger.js";
 const scopeStorage = new AsyncLocalStorage();
 const lessonScopeStorage = new AsyncLocalStorage();
-export const client = new RuntimeClient(readRunnerConfig().url);
 const ROOT_SCOPE_MARKERS = new Set(["", ".", "/"]);
+export function normalizeProjectName(projectName) {
+    if (projectName === null || projectName === undefined) {
+        throw new Error("projectName is required.");
+    }
+    if (typeof projectName !== "string") {
+        throw new TypeError("projectName must be a string.");
+    }
+    const normalized = projectName.trim();
+    if (!normalized) {
+        throw new Error("projectName is required.");
+    }
+    return normalized;
+}
 function normalizeRunOptions(input) {
-    const options = typeof input === "string" ? { name: input } : input;
-    const name = options.name.trim();
+    if (typeof input === "string") {
+        throw new Error("SovaraClient.run() requires a client-bound project name.");
+    }
+    const options = input;
+    if (options.name !== undefined && typeof options.name !== "string") {
+        throw new Error("SovaraClient.run() name must be a string.");
+    }
+    const name = options.name === undefined ? defaultTopLevelRunName() : options.name.trim();
     if (!name) {
-        throw new Error("withSovaraRun() name must be a non-empty string.");
+        throw new Error("SovaraClient.run() name must be a non-empty string.");
     }
     return { ...options, name };
 }
+function defaultTopLevelRunName() {
+    return `Run ${randomUUID().replace(/-/g, "").slice(0, 4)}`;
+}
+function writeRunResult(result) {
+    const path = process.env.SOVARA_RUN_FILE;
+    if (!path)
+        return;
+    const absolutePath = resolve(path);
+    const tempPath = `${dirname(absolutePath)}/.${basename(absolutePath)}.${randomUUID()}`;
+    try {
+        writeFileSync(tempPath, JSON.stringify({
+            run_id: result.runId,
+            project_id: result.projectId,
+            project_name: result.projectName,
+            appended: result.appended,
+        }), { encoding: "utf8", flag: "wx", mode: 0o600 });
+        renameSync(tempPath, absolutePath);
+    }
+    catch {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch {
+            // The temporary file may not have been created.
+        }
+        warnOnce("publish-run-result", "[sovara] Failed to publish run result.");
+    }
+}
 function normalizeSubrunOptions(input) {
     const options = typeof input === "string" ? { name: input } : input;
     const name = options.name.trim();
     if (!name) {
-        throw new Error("withSovaraSubrun() name must be a non-empty string.");
+        throw new Error("SovaraClient.subrun() name must be a non-empty string.");
     }
     return { ...options, name };
 }
@@ -87,15 +136,7 @@ function scopeWithLessonScope(parent, lessonScopePaths) {
     };
 }
 function resolveRunProjectConfig(cwd, options) {
-    try {
-        return resolveProjectConfig(cwd, options.projectName);
-    }
-    catch (error) {
-        if (options.__testing?.client && options.__testing.skipLifecycle) {
-            return { projectName: "Project", projectRoot: cwd };
-        }
-        throw new SovaraConfigError(error instanceof Error ? error.message : String(error));
-    }
+    return { projectName: normalizeProjectName(options.projectName), projectRoot: cwd };
 }
 export function getCurrentRunScope() {
     return scopeStorage.getStore();
@@ -143,35 +184,34 @@ export async function queueForAnnotation() {
     await scope.client.requestAnnotationEvaluation({ runId: scope.runId });
 }
 export async function withSovaraRun(input, fn) {
-    await ensureMcpPatchInstalled();
+    await Promise.all([ensureMcpPatchInstalled(), ensureOpenAIAgentsPatchInstalled()]);
     const options = normalizeRunOptions(input);
     const parent = getCurrentRunScope();
     if (!parent && isDegraded()) {
         return await fn();
     }
     if (parent) {
-        console.warn("withSovaraRun() was called inside an active run; ignoring nested run. Use withSovaraSubrun() for child agent execution.");
+        console.warn("SovaraClient.run() was called inside an active run; ignoring nested run. Use SovaraClient.subrun() for child agent execution.");
         return await fn();
     }
     const config = readRunnerConfig();
     const project = resolveRunProjectConfig(config.cwd, options);
-    const connection = loadAgentConnection(project.projectName);
-    const url = options.url ?? connection?.serverUrl ?? config.url;
+    const url = options.url ?? config.url;
     const skipLifecycle = options.__testing?.skipLifecycle ?? false;
     if (!skipLifecycle) {
-        const reachable = await ensureServerRunning(url);
+        const reachable = await ensureServerRunning(url, options.fetch ? { fetchFn: options.fetch } : undefined);
         if (!reachable) {
             return await fn(); // no-op: run user code without a scope
         }
     }
-    const client = options.__testing?.client ?? new RuntimeClient(url, undefined, connection?.agentToken);
+    const client = options.__testing?.client
+        ?? new RuntimeClient(url, options.fetch, options.agentToken);
     const codeVersion = collectCodeVersion(project.projectRoot);
     let registration;
     try {
         registration = await client.registerRun({
             name: options.name,
             clientRunId: options.clientRunId,
-            projectId: connection?.projectId,
             projectName: project.projectName,
             projectRoot: project.projectRoot,
             codeVersion,
@@ -234,13 +274,21 @@ export async function withSovaraRun(input, fn) {
                 throw error;
             }
         }
+        finally {
+            writeRunResult({
+                runId: registration.runId,
+                projectId: registration.projectId,
+                projectName: project.projectName,
+                appended: registration.appended ?? false,
+            });
+        }
     }
 }
 export async function withSovaraSubrun(input, fn) {
     const options = normalizeSubrunOptions(input);
     const parent = getCurrentRunScope();
     if (!parent) {
-        throw new Error("withSovaraSubrun() requires an active Sovara run.");
+        throw new Error("SovaraClient.subrun() requires an active Sovara run.");
     }
     const lessonScopePaths = resolveLessonScope(options.lessonScope, parent.lessonScopePaths);
     const subrun = await parent.client.registerSubrun({