@sovara/sdk 0.0.0-stage → 0.9.1

package/dist/client.d.ts

@@ -0,0 +1,52 @@
+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 SovaraTraceOptions = {
+    /** Your stable identifier or a `sovara-` id; `getTraceId()` returns the canonical id. */
+    traceId?: string;
+    evalRunId?: string;
+    captureLogs?: boolean;
+    lessonScope?: LessonScopeInput;
+};
+export type SovaraSubtraceOptions = {
+    lessonScope?: LessonScopeInput;
+};
+/** @deprecated Use SovaraTraceOptions with traceId. */
+export type SovaraRunOptions = Omit<SovaraTraceOptions, "traceId"> & {
+    runId?: string;
+};
+/** @deprecated Use SovaraSubtraceOptions. */
+export type SovaraSubrunOptions = SovaraSubtraceOptions;
+export type SovaraTurnOptions = {
+    turnInput?: string;
+};
+type TraceFunction<T> = () => Promise<T> | T;
+export declare class SovaraClient {
+    readonly projectName: string;
+    private readonly url;
+    private readonly fetch?;
+    private readonly owner;
+    private readonly runtimeClient;
+    constructor(options: SovaraClientOptions);
+    trace<T>(name: string, fn: TraceFunction<T>, options?: SovaraTraceOptions): Promise<T>;
+    subtrace<T>(name: string, fn: TraceFunction<T>, options?: SovaraSubtraceOptions): Promise<T>;
+    /** @deprecated Use trace() with traceId. */
+    run<T>(name: string, fn: TraceFunction<T>, options?: SovaraRunOptions): Promise<T>;
+    /** @deprecated Use subtrace(). */
+    subrun<T>(name: string, fn: TraceFunction<T>, options?: SovaraSubrunOptions): Promise<T>;
+    lessonScope<T>(scope: LessonScopeInput, fn: TraceFunction<T>): Promise<T>;
+    turn<T>(options: SovaraTurnOptions, fn: TraceFunction<T>): Promise<T>;
+    logInput(input: unknown): Promise<void>;
+    logOutput(output: unknown): Promise<void>;
+    logMetrics(metrics: Record<string, MetricValue>): Promise<void>;
+    getTraceId(): string | undefined;
+    /** @deprecated Use getTraceId(). */
+    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":"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"}

package/dist/client.js

@@ -0,0 +1,66 @@
+import { getTraceId, logInput, logMetrics, logOutput, normalizeProjectName, withLessonScope, withSovaraTrace, withSovaraSubtrace, withSovaraTurn, } from "./context.js";
+import { RuntimeClient } from "./runtimeClient.js";
+import { readRunnerConfig } from "./env.js";
+export class SovaraClient {
+    projectName;
+    url;
+    fetch;
+    owner = Object.freeze({});
+    runtimeClient;
+    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 ?? readRunnerConfig().url;
+        this.fetch = options.fetch;
+        this.runtimeClient = new RuntimeClient(this.url, options.fetch, options.agentToken);
+    }
+    trace(name, fn, options = {}) {
+        return withSovaraTrace({
+            ...options,
+            name,
+            projectName: this.projectName,
+            url: this.url,
+            fetch: this.fetch,
+        }, fn, { client: this.runtimeClient, owner: this.owner });
+    }
+    subtrace(name, fn, options = {}) {
+        return withSovaraSubtrace({
+            name,
+            ...options,
+        }, fn, { client: this.runtimeClient, owner: this.owner });
+    }
+    /** @deprecated Use trace() with traceId. */
+    run(name, fn, options = {}) {
+        const { runId, ...rest } = options;
+        return this.trace(name, fn, { ...rest, traceId: runId });
+    }
+    /** @deprecated Use subtrace(). */
+    subrun(name, fn, options = {}) {
+        return this.subtrace(name, fn, options);
+    }
+    lessonScope(scope, fn) {
+        return withLessonScope(scope, fn, this.owner);
+    }
+    turn(options, fn) {
+        return withSovaraTurn(options, fn, this.owner);
+    }
+    logInput(input) {
+        return logInput(input, this.owner);
+    }
+    logOutput(output) {
+        return logOutput(output, this.owner);
+    }
+    logMetrics(metrics) {
+        return logMetrics(metrics, this.owner);
+    }
+    getTraceId() {
+        return getTraceId(this.owner);
+    }
+    /** @deprecated Use getTraceId(). */
+    getRunId() {
+        return this.getTraceId();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/codeVersion.d.ts

@@ -0,0 +1,17 @@
+export type CodeVersion = {
+    type: "git";
+    available: boolean;
+    status: "clean" | "dirty" | "missing_project_root" | "missing_project_config" | "git_unavailable" | "not_git_repo" | "no_commit";
+    repo_root: string | null;
+    commit_sha: string | null;
+    short_commit_sha: string | null;
+    branch: string | null;
+    dirty: boolean | null;
+    remote_url: string | null;
+    web_url: string | null;
+    commit_url: string | null;
+};
+export declare function normalizeGitRemoteURL(remoteURL: string | null | undefined): string | null;
+export declare function buildCommitURL(webURL: string | null, commitSHA: string | null): string | null;
+export declare function collectCodeVersion(projectRoot: string | null | undefined): CodeVersion;
+//# sourceMappingURL=codeVersion.d.ts.map

package/dist/codeVersion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codeVersion.d.ts","sourceRoot":"","sources":["../src/codeVersion.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,KAAK,CAAC;IACZ,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EACF,OAAO,GACP,OAAO,GACP,sBAAsB,GACtB,wBAAwB,GACxB,iBAAiB,GACjB,cAAc,GACd,WAAW,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AA4BF,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CA6BzF;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAiB7F;AAED,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,CAqCtF"}

package/dist/codeVersion.js

@@ -0,0 +1,107 @@
+import { spawnSync } from "node:child_process";
+const GIT_TIMEOUT_MS = 2000;
+const emptyCodeVersion = (status) => ({
+    type: "git",
+    available: false,
+    status,
+    repo_root: null,
+    commit_sha: null,
+    short_commit_sha: null,
+    branch: null,
+    dirty: null,
+    remote_url: null,
+    web_url: null,
+    commit_url: null,
+});
+function runGit(cwd, args) {
+    const result = spawnSync("git", ["-C", cwd, ...args], {
+        encoding: "utf8",
+        timeout: GIT_TIMEOUT_MS,
+    });
+    if (result.error || result.status !== 0) {
+        return { ok: false, stdout: "" };
+    }
+    return { ok: true, stdout: result.stdout.trim() };
+}
+export function normalizeGitRemoteURL(remoteURL) {
+    const remote = remoteURL?.trim();
+    if (!remote) {
+        return null;
+    }
+    const ssh = /^(?:ssh:\/\/)?git@([^/:]+)(?::|\/)(.+)$/.exec(remote);
+    if (ssh) {
+        const host = ssh[1];
+        const path = ssh[2].replace(/\/+$/, "").replace(/\.git$/, "");
+        return path ? `https://${host}/${path}` : null;
+    }
+    let parsed;
+    try {
+        parsed = new URL(remote);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return null;
+    }
+    const path = parsed.pathname.replace(/\/+$/, "").replace(/\.git$/, "");
+    if (!parsed.hostname || !path || path === "/") {
+        return null;
+    }
+    const port = parsed.port ? `:${parsed.port}` : "";
+    return `https://${parsed.hostname}${port}${path}`;
+}
+export function buildCommitURL(webURL, commitSHA) {
+    if (!webURL || !commitSHA) {
+        return null;
+    }
+    let hostname = "";
+    try {
+        hostname = new URL(webURL).hostname;
+    }
+    catch {
+        return null;
+    }
+    if (hostname === "github.com" || hostname.endsWith(".github.com")) {
+        return `${webURL}/commit/${commitSHA}`;
+    }
+    if (hostname === "gitlab.com" || hostname.endsWith(".gitlab.com")) {
+        return `${webURL}/-/commit/${commitSHA}`;
+    }
+    return null;
+}
+export function collectCodeVersion(projectRoot) {
+    if (!projectRoot) {
+        return emptyCodeVersion("missing_project_root");
+    }
+    const repo = runGit(projectRoot, ["rev-parse", "--show-toplevel"]);
+    if (!repo.ok || !repo.stdout) {
+        return emptyCodeVersion("not_git_repo");
+    }
+    const commit = runGit(repo.stdout, ["rev-parse", "HEAD"]);
+    if (!commit.ok || !commit.stdout) {
+        return {
+            ...emptyCodeVersion("no_commit"),
+            repo_root: repo.stdout,
+        };
+    }
+    const branch = runGit(repo.stdout, ["branch", "--show-current"]);
+    const status = runGit(repo.stdout, ["status", "--porcelain", "--untracked-files=all"]);
+    const remote = runGit(repo.stdout, ["remote", "get-url", "origin"]);
+    const dirty = status.ok ? status.stdout.length > 0 : null;
+    const webURL = normalizeGitRemoteURL(remote.ok ? remote.stdout : null);
+    return {
+        type: "git",
+        available: true,
+        status: dirty ? "dirty" : "clean",
+        repo_root: repo.stdout,
+        commit_sha: commit.stdout,
+        short_commit_sha: commit.stdout.slice(0, 7),
+        branch: branch.ok && branch.stdout ? branch.stdout : null,
+        dirty,
+        remote_url: webURL,
+        web_url: webURL,
+        commit_url: buildCommitURL(webURL, commit.stdout),
+    };
+}
+//# sourceMappingURL=codeVersion.js.map

package/dist/codeVersion.js.map

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

package/dist/compatibility.d.ts

@@ -0,0 +1,26 @@
+export type CompatibilityResult = {
+    status: "compatible" | "incompatible";
+    contract: string;
+    selected_version: number | null;
+    client_versions?: number[];
+    server_versions?: number[];
+    server?: {
+        component: string;
+        product_version: string | null;
+    };
+};
+export declare class CompatibilityError extends Error {
+    readonly code: string;
+    readonly result?: CompatibilityResult | undefined;
+    constructor(code: string, message: string, result?: CompatibilityResult | undefined);
+}
+export declare const RUNNER_API_VERSIONS: number[];
+export declare function negotiate(health: unknown, contract: string, supported: number[], expectedComponent: string): CompatibilityResult;
+export declare function clientHeaders(result: CompatibilityResult): Record<string, string>;
+export declare function raiseForCompatibilityResponse(status: number, payload: unknown): void;
+export declare function forgetCompatibility(url: string): void;
+/** Whether the destination's last compatible health response advertised a feature. */
+export declare function hasFeature(url: string, name: string): boolean;
+export declare function compatibilityHeaders(url: string): Record<string, string>;
+export declare function checkCompatibility(url: string, health: unknown): void;
+//# sourceMappingURL=compatibility.d.ts.map

package/dist/compatibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compatibility.d.ts","sourceRoot":"","sources":["../src/compatibility.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,YAAY,GAAG,cAAc,CAAC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,MAAM,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CAChE,CAAC;AAEF,qBAAa,kBAAmB,SAAQ,KAAK;IAEzC,QAAQ,CAAC,IAAI,EAAE,MAAM;IAErB,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB;gBAF5B,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACN,MAAM,CAAC,EAAE,mBAAmB,YAAA;CAKxC;AAED,eAAO,MAAM,mBAAmB,UAAM,CAAC;AA+CvC,wBAAgB,SAAS,CACvB,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EAAE,EACnB,iBAAiB,EAAE,MAAM,GACxB,mBAAmB,CA4CrB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQjF;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAcpF;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAGrD;AAED,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAExE;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAMrE"}

package/dist/compatibility.js

@@ -0,0 +1,130 @@
+import { readFileSync } from "node:fs";
+export class CompatibilityError extends Error {
+    code;
+    result;
+    constructor(code, message, result) {
+        super(message);
+        this.code = code;
+        this.result = result;
+        this.name = "CompatibilityError";
+    }
+}
+export const RUNNER_API_VERSIONS = [5];
+const headersByUrl = new Map();
+const featuresByUrl = new Map();
+const key = (url) => url.replace(/\/+$/, "");
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function versions(value) {
+    if (!Array.isArray(value) || !value.length || value.length > 64
+        || value.some((item) => !Number.isInteger(item) || item < 1 || item > 2147483647)
+        || new Set(value).size !== value.length) {
+        throw new CompatibilityError("invalid_compatibility_metadata", "Invalid contract versions.");
+    }
+    return value;
+}
+function productVersion() {
+    try {
+        const value = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+        return typeof value === "string" ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function latestVersion(value) {
+    if (!Array.isArray(value) || value.length > 64
+        || value.some((item) => !Number.isInteger(item) || item < 1 || item > 2147483647)) {
+        return undefined;
+    }
+    return Math.max(0, ...value);
+}
+function outdatedMessage(result, clientName = "TypeScript SDK") {
+    const client = latestVersion(result?.client_versions)
+        ?? (result?.selected_version === null ? 0 : latestVersion([result?.selected_version]));
+    const server = latestVersion(result?.server_versions);
+    const component = client !== undefined && server !== undefined && client !== server
+        ? (client > server ? "server" : clientName)
+        : `${clientName} or server`;
+    return `Your ${component} is outdated. Please update.`;
+}
+export function negotiate(health, contract, supported, expectedComponent) {
+    versions(supported);
+    if (!record(health)) {
+        throw new CompatibilityError("invalid_compatibility_metadata", "Invalid server health response.");
+    }
+    if (!("compatibility" in health)) {
+        throw new CompatibilityError("incompatible_contract", "Your server is outdated. Please update.", { status: "incompatible", contract, selected_version: null,
+            client_versions: supported, server_versions: [] });
+    }
+    const metadata = health.compatibility;
+    if (!record(metadata)) {
+        throw new CompatibilityError("invalid_compatibility_metadata", "Invalid server compatibility metadata.");
+    }
+    if (metadata.component !== expectedComponent) {
+        throw new CompatibilityError("unexpected_service", "The destination is a different Sovara component.");
+    }
+    const release = metadata.product_version ?? null;
+    if (release !== null && (typeof release !== "string" || release !== release.trim()
+        || !/^[A-Za-z0-9][A-Za-z0-9._+-]{0,127}$/.test(release))) {
+        throw new CompatibilityError("invalid_compatibility_metadata", "Invalid server product version.");
+    }
+    if (!record(metadata.contracts) || !(contract in metadata.contracts)) {
+        throw new CompatibilityError("invalid_compatibility_metadata", "The server omitted its contract declaration.");
+    }
+    const serverVersions = versions(metadata.contracts[contract]);
+    const common = supported.filter((value) => serverVersions.includes(value));
+    const result = {
+        status: common.length ? "compatible" : "incompatible",
+        contract,
+        selected_version: common.length ? Math.max(...common) : null,
+        client_versions: supported,
+        server_versions: serverVersions,
+        server: { component: expectedComponent, product_version: release },
+    };
+    if (!common.length) {
+        throw new CompatibilityError("incompatible_contract", outdatedMessage(result), result);
+    }
+    return result;
+}
+export function clientHeaders(result) {
+    if (result.status !== "compatible")
+        return {};
+    return {
+        "x-sovara-component": "typescript-runner",
+        "x-sovara-version": productVersion() || "unknown",
+        "x-sovara-contract": result.contract,
+        "x-sovara-contract-version": String(result.selected_version),
+    };
+}
+export function raiseForCompatibilityResponse(status, payload) {
+    if ((status === 400 || status === 409) && record(payload)
+        && (payload.error === "incompatible_contract"
+            || payload.error === "invalid_compatibility_metadata")) {
+        const result = record(payload.compatibility_result)
+            ? payload.compatibility_result : undefined;
+        throw new CompatibilityError(payload.error, payload.error === "incompatible_contract"
+            ? outdatedMessage(result)
+            : "Could not connect to the server. Please retry.", result);
+    }
+}
+export function forgetCompatibility(url) {
+    headersByUrl.delete(key(url));
+    featuresByUrl.delete(key(url));
+}
+/** Whether the destination's last compatible health response advertised a feature. */
+export function hasFeature(url, name) {
+    return featuresByUrl.get(key(url))?.[name] === true;
+}
+export function compatibilityHeaders(url) {
+    return { ...headersByUrl.get(key(url)) };
+}
+export function checkCompatibility(url, health) {
+    forgetCompatibility(url);
+    const result = negotiate(health, "runner-api", RUNNER_API_VERSIONS, "exec-server");
+    headersByUrl.set(key(url), clientHeaders(result));
+    const features = health.features;
+    featuresByUrl.set(key(url), record(features) ? features : {});
+}
+//# sourceMappingURL=compatibility.js.map

package/dist/compatibility.js.map

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

package/dist/constants.d.ts

@@ -0,0 +1,9 @@
+export declare function readPositiveIntegerEnv(name: string, defaultValue: number, options?: {
+    maximum?: number;
+}): number;
+export declare function readHttpUrlEnv(name: string, defaultValue: string): string;
+export declare const PORT: number;
+export declare const DEFAULT_SERVER_URL: string;
+export declare const SERVER_BOOT_TIMEOUT_MS = 15000;
+export declare const SERVER_BOOT_POLL_INTERVAL_MS = 500;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACjC,MAAM,CAoBR;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAczE;AAED,eAAO,MAAM,IAAI,QAIhB,CAAC;AAEF,eAAO,MAAM,kBAAkB,QAG9B,CAAC;AACF,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAC7C,eAAO,MAAM,4BAA4B,MAAM,CAAC"}

package/dist/constants.js

@@ -0,0 +1,37 @@
+export function readPositiveIntegerEnv(name, defaultValue, options = {}) {
+    const raw = process.env[name];
+    if (raw === undefined) {
+        return defaultValue;
+    }
+    const valueText = raw.trim();
+    const value = /^[+]?\d+$/.test(valueText) ? Number(valueText) : Number.NaN;
+    const { maximum } = options;
+    if (!Number.isSafeInteger(value)
+        || value <= 0
+        || (maximum !== undefined && value > maximum)) {
+        const constraint = maximum === undefined
+            ? "a positive integer"
+            : `a positive integer no greater than ${maximum}`;
+        throw new Error(`${name} must be ${constraint}; got ${JSON.stringify(raw)}.`);
+    }
+    return value;
+}
+export function readHttpUrlEnv(name, defaultValue) {
+    const raw = process.env[name];
+    const value = (raw ?? defaultValue).trim();
+    try {
+        const parsed = new URL(value);
+        if (!["http:", "https:"].includes(parsed.protocol) || !parsed.hostname) {
+            throw new Error("unsupported URL");
+        }
+    }
+    catch {
+        throw new Error(`${name} must be an absolute HTTP(S) URL.`);
+    }
+    return value.replace(/\/+$/, "");
+}
+export const PORT = readPositiveIntegerEnv("SOVARA_EXEC_SERVER_PORT", 5960, { maximum: 65_535 });
+export const DEFAULT_SERVER_URL = readHttpUrlEnv("SOVARA_EXEC_SERVER_URL", `http://127.0.0.1:${PORT}`);
+export const SERVER_BOOT_TIMEOUT_MS = 15_000;
+export const SERVER_BOOT_POLL_INTERVAL_MS = 500;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,sBAAsB,CACpC,IAAY,EACZ,YAAoB,EACpB,UAAgC,EAAE;IAElC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,MAAM,SAAS,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;IAC3E,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAC5B,IACE,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC;WACzB,KAAK,IAAI,CAAC;WACV,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,GAAG,OAAO,CAAC,EAC7C,CAAC;QACD,MAAM,UAAU,GAAG,OAAO,KAAK,SAAS;YACtC,CAAC,CAAC,oBAAoB;YACtB,CAAC,CAAC,sCAAsC,OAAO,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,YAAY,UAAU,SAAS,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,YAAoB;IAC/D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC;IAE3C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC9B,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACvE,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,mCAAmC,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,CAAC,MAAM,IAAI,GAAG,sBAAsB,CACxC,yBAAyB,EACzB,IAAI,EACJ,EAAE,OAAO,EAAE,MAAM,EAAE,CACpB,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG,cAAc,CAC9C,wBAAwB,EACxB,oBAAoB,IAAI,EAAE,CAC3B,CAAC;AACF,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAC7C,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC"}

package/dist/context.d.ts

@@ -0,0 +1,55 @@
+import { type TraceLogCaptureHandle } from "./traceLogCapture.js";
+import { RuntimeClient, type MetricValue, type TraceWriteCredentials } from "./runtimeClient.js";
+export type WithSovaraTraceOptions = {
+    name?: string;
+    traceId?: string;
+    evalRunId?: string;
+    url?: string;
+    agentToken?: string;
+    fetch?: typeof globalThis.fetch;
+    captureLogs?: boolean;
+    projectName: string;
+    lessonScope?: LessonScopeInput;
+    __testing?: {
+        client?: TraceScopeClient;
+        skipLifecycle?: boolean;
+    };
+};
+type CoreTraceScopeClientMethods = "declareTurn" | "registerSubtrace" | "deregisterTrace" | "updateTraceLog" | "registerTrace" | "prepareCall" | "recordOutput" | "recordException";
+type TraceHelperClientMethods = "logMetrics" | "logInput" | "logOutput";
+export type TraceScopeClient = Pick<RuntimeClient, CoreTraceScopeClientMethods> & Partial<Pick<RuntimeClient, TraceHelperClientMethods>>;
+type TraceClientBinding = {
+    readonly client: TraceScopeClient;
+    readonly owner: object;
+};
+export type TraceScope = {
+    readonly name: string;
+    readonly client: TraceScopeClient;
+    readonly owner: object;
+    readonly credentials: TraceWriteCredentials;
+    readonly turnId: string | null;
+    readonly lessonScopePaths: readonly string[] | null;
+    readonly logCaptureId?: symbol;
+    readonly logCapture?: TraceLogCaptureHandle<TraceScope>;
+};
+export type WithSovaraSubtraceOptions = {
+    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 getCurrentTraceScope(): TraceScope | undefined;
+export type TurnOptions = {
+    turnInput?: string;
+};
+export declare function withSovaraTurn<T>(options: TurnOptions, fn: () => Promise<T> | T, owner: object): Promise<T>;
+export declare function getTraceId(owner?: object): string | undefined;
+export declare function logMetrics(metrics: Record<string, MetricValue>, owner?: object): Promise<void>;
+export declare function logInput(input: unknown, owner?: object): Promise<void>;
+export declare function logOutput(output: unknown, owner?: object): Promise<void>;
+export declare function withSovaraTrace<T>(input: WithSovaraTraceOptions, fn: () => Promise<T> | T, binding?: TraceClientBinding): Promise<T>;
+export declare function withSovaraSubtrace<T>(input: string | WithSovaraSubtraceOptions, fn: () => Promise<T> | T, binding?: TraceClientBinding): Promise<T>;
+export declare function withLessonScope<T>(lessonScope: LessonScopeInput, fn: () => Promise<T> | T, owner?: object): Promise<T>;
+export {};
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,aAAa,EAEb,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC3B,MAAM,oBAAoB,CAAC;AAO5B,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,SAAS,CAAC,EAAE;QACV,MAAM,CAAC,EAAE,gBAAgB,CAAC;QAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;CACH,CAAC;AAMF,KAAK,2BAA2B,GAC5B,aAAa,GACb,kBAAkB,GAClB,iBAAiB,GACjB,gBAAgB,GAChB,eAAe,GACf,aAAa,GACb,cAAc,GACd,iBAAiB,CAAC;AAEtB,KAAK,wBAAwB,GACzB,YAAY,GACZ,UAAU,GACV,WAAW,CAAC;AAEhB,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,aAAa,EAAE,2BAA2B,CAAC,GAC7E,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,wBAAwB,CAAC,CAAC,CAAC;AAEzD,KAAK,kBAAkB,GAAG;IACxB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC,UAAU,CAAC,CAAC;CACzD,CAAC;AAMF,MAAM,MAAM,yBAAyB,GAAG;IACtC,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;AAIpE,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,OAAO,GAAG,MAAM,CAYjE;AAuFD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,EAAE,GAAG,IAAI,CAgB7E;AAqCD,wBAAgB,oBAAoB,IAAI,UAAU,GAAG,SAAS,CAE7D;AASD,MAAM,MAAM,WAAW,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD,wBAAsB,cAAc,CAAC,CAAC,EACpC,OAAO,EAAE,WAAW,EACpB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,CAAC,CAAC,CAgBZ;AAWD,wBAAgB,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI7D;AAED,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACpC,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK5E;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK9E;AAED,wBAAsB,eAAe,CAAC,CAAC,EACrC,KAAK,EAAE,sBAAsB,EAC7B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAqIZ;AAED,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,KAAK,EAAE,MAAM,GAAG,yBAAyB,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAoCZ;AAED,wBAAsB,eAAe,CAAC,CAAC,EACrC,WAAW,EAAE,gBAAgB,EAC7B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,CAAC,CAAC,CAUZ"}