@synsci/sdk 2.0.23 → 2.0.24

package/dist/src/v2/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./client.js";
 export * from "./server.js";
+export * from "./runtime.js";
 import type { ServerOptions } from "./server.js";
 export declare function createOpenScience(options?: ServerOptions): Promise<{
     client: import("./client.js").OpenScienceClient;

package/dist/src/v2/index.js

@@ -1,5 +1,6 @@
 export * from "./client.js";
 export * from "./server.js";
+export * from "./runtime.js";
 import { createOpenScienceClient } from "./client.js";
 import { createOpenScienceServer } from "./server.js";
 export async function createOpenScience(options) {

package/dist/src/v2/runtime.d.ts

@@ -0,0 +1,35 @@
+import { type OpenScienceClientConfig } from "./client.js";
+import type { RuntimeEvent, RuntimeEventReplay, RuntimePromptAccepted, RuntimePromptData } from "./gen/types.gen.js";
+export type RuntimePromptInput = NonNullable<RuntimePromptData["body"]>;
+export type RuntimeEventInput = {
+    sessionID: string;
+    /** Replay events strictly after this per-session sequence. */
+    afterSequence?: number;
+    signal?: AbortSignal;
+};
+export declare class RuntimeEventCursorError extends Error {
+    readonly status = 409;
+    constructor(message?: string);
+}
+export type OpenScienceRuntimeConfig = OpenScienceClientConfig & {
+    directory?: string;
+    projectID?: string;
+    project?: string;
+    /** Delay before reconnecting an event stream that ended without an error. */
+    runtimeReconnectDelayMs?: number;
+};
+/**
+ * Stable, result-first facade over the generated HTTP client.
+ *
+ * The facade carries `Last-Event-ID` across reconnects; the server treats that
+ * ID as the authoritative cursor, so each yielded event is durably replayable
+ * and sequences remain monotonic within a session.
+ */
+export declare class OpenScienceRuntime {
+    #private;
+    constructor(config?: OpenScienceRuntimeConfig);
+    prompt(input: RuntimePromptInput): Promise<RuntimePromptAccepted>;
+    replay(input: Omit<RuntimeEventInput, "signal">): Promise<RuntimeEventReplay>;
+    events(input: RuntimeEventInput): AsyncGenerator<RuntimeEvent, void, void>;
+}
+export declare function createOpenScienceRuntime(config?: OpenScienceRuntimeConfig): OpenScienceRuntime;

package/dist/src/v2/runtime.js

@@ -0,0 +1,100 @@
+import { createOpenScienceClient } from "./client.js";
+export class RuntimeEventCursorError extends Error {
+    status = 409;
+    constructor(message = "The runtime event cursor is outside the retained window") {
+        super(message);
+        this.name = "RuntimeEventCursorError";
+    }
+}
+function statusFromSseError(error) {
+    if (!(error instanceof Error))
+        return;
+    const match = error.message.match(/SSE failed:\s+(\d{3})\b/);
+    if (!match)
+        return;
+    return Number(match[1]);
+}
+function waitForReconnect(delay, signal) {
+    if (signal?.aborted || delay <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(done, delay);
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        }
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}
+/**
+ * Stable, result-first facade over the generated HTTP client.
+ *
+ * The facade carries `Last-Event-ID` across reconnects; the server treats that
+ * ID as the authoritative cursor, so each yielded event is durably replayable
+ * and sequences remain monotonic within a session.
+ */
+export class OpenScienceRuntime {
+    #client;
+    #reconnectDelay;
+    constructor(config) {
+        const { runtimeReconnectDelayMs: _, ...clientConfig } = config ?? {};
+        this.#client = createOpenScienceClient(clientConfig);
+        this.#reconnectDelay = Math.max(0, config?.runtimeReconnectDelayMs ?? 100);
+    }
+    prompt(input) {
+        return this.#client.runtime
+            .prompt(input, {
+            throwOnError: true,
+        })
+            .then((result) => result.data);
+    }
+    replay(input) {
+        return this.#client.runtime
+            .replay(input, {
+            throwOnError: true,
+        })
+            .then((result) => result.data);
+    }
+    async *events(input) {
+        const { signal, ...parameters } = input;
+        let lastSequence = input.afterSequence;
+        let failures = 0;
+        while (!signal?.aborted) {
+            let connectionError;
+            const result = await this.#client.runtime.subscribe(parameters, {
+                signal,
+                throwOnError: true,
+                // The stable facade owns reconnect policy so normal EOF and HTTP
+                // errors follow the same cursor-aware path.
+                sseMaxRetryAttempts: 1,
+                headers: lastSequence === undefined ? undefined : { "Last-Event-ID": String(lastSequence) },
+                onSseError(error) {
+                    connectionError = error;
+                },
+            });
+            for await (const event of result.stream) {
+                lastSequence = event.sequence;
+                failures = 0;
+                yield event;
+            }
+            if (signal?.aborted)
+                return;
+            if (connectionError) {
+                const status = statusFromSseError(connectionError);
+                if (status === 409)
+                    throw new RuntimeEventCursorError(connectionError.message);
+                if (status !== undefined && status >= 400 && status < 500)
+                    throw connectionError;
+                failures += 1;
+            }
+            const delay = connectionError
+                ? Math.min(this.#reconnectDelay * 2 ** Math.max(0, failures - 1), 30_000)
+                : this.#reconnectDelay;
+            await waitForReconnect(delay, signal);
+        }
+    }
+}
+export function createOpenScienceRuntime(config) {
+    return new OpenScienceRuntime(config);
+}

package/dist/test/review-contract.d.ts

@@ -0,0 +1,25 @@
+import type { OpenScienceClient } from "../src/v2/client.js";
+import type { SettingsReviewGetData, SettingsReviewGetResponse, SettingsReviewGetResponses, SettingsReviewSetData, SettingsReviewSetResponse, SettingsReviewSetResponses } from "../src/v2/gen/types.gen.js";
+type Assert<T extends true> = T;
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+type Field<T, K extends PropertyKey> = K extends keyof NonNullable<T> ? true : false;
+type Review = OpenScienceClient["settings"]["review"];
+type _reviewGet = Assert<Field<Review, "get">>;
+type _reviewSet = Assert<Field<Review, "set">>;
+type _getData = Assert<Equal<SettingsReviewGetData["url"], "/settings/review">>;
+type _getResponses = Assert<Equal<keyof SettingsReviewGetResponses, 200>>;
+type _getResponse = Assert<Equal<SettingsReviewGetResponse, SettingsReviewGetResponses[200]>>;
+type _setData = Assert<Equal<SettingsReviewSetData["url"], "/settings/review">>;
+type _setResponses = Assert<Equal<keyof SettingsReviewSetResponses, 200>>;
+type _setResponse = Assert<Equal<SettingsReviewSetResponse, SettingsReviewSetResponses[200]>>;
+export declare const reviewContract: {
+    readonly get: _reviewGet;
+    readonly set: _reviewSet;
+    readonly getData: _getData;
+    readonly getResponses: _getResponses;
+    readonly getResponse: _getResponse;
+    readonly setData: _setData;
+    readonly setResponses: _setResponses;
+    readonly setResponse: _setResponse;
+};
+export {};

package/dist/test/review-contract.js

@@ -0,0 +1,10 @@
+export const reviewContract = {
+    get: true,
+    set: true,
+    getData: true,
+    getResponses: true,
+    getResponse: true,
+    setData: true,
+    setResponses: true,
+    setResponse: true,
+};

package/dist/test/review.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/review.test.js

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { createOpenScienceClient } from "../src/v2/client.js";
+test("review settings retain the published get and set client contract", async () => {
+    const requests = [];
+    const client = createOpenScienceClient({
+        baseUrl: "http://review.test",
+        fetch: async (input) => {
+            const request = input instanceof Request ? input : new Request(input);
+            requests.push(request);
+            return Response.json({ auto: request.method === "PUT", model: null });
+        },
+    });
+    await client.settings.review.get();
+    await client.settings.review.set({ auto: true, model: null });
+    assert.equal(requests[0]?.url, "http://review.test/settings/review");
+    assert.equal(requests[0]?.method, "GET");
+    assert.equal(requests[1]?.url, "http://review.test/settings/review");
+    assert.equal(requests[1]?.method, "PUT");
+    assert.deepEqual(await requests[1]?.json(), { auto: true, model: null });
+});

package/dist/test/runtime-contract.d.ts

@@ -0,0 +1,19 @@
+import { createOpenScienceRuntime, type RuntimePromptInput } from "../src/v2/runtime.js";
+import type { RuntimeEvent, RuntimeEventReplay, RuntimePromptAccepted } from "../src/v2/gen/types.gen.js";
+type Assert<T extends true> = T;
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+type _promptInput = Assert<Equal<RuntimePromptInput, {
+    sessionID: string;
+    message: string;
+    effort: "normal" | "ultra";
+}>>;
+type _promptResult = Assert<Equal<Awaited<ReturnType<ReturnType<typeof createOpenScienceRuntime>["prompt"]>>, RuntimePromptAccepted>>;
+type _replayResult = Assert<Equal<Awaited<ReturnType<ReturnType<typeof createOpenScienceRuntime>["replay"]>>, RuntimeEventReplay>>;
+type _eventsResult = Assert<Equal<ReturnType<ReturnType<typeof createOpenScienceRuntime>["events"]>, AsyncGenerator<RuntimeEvent, void, void>>>;
+export declare const runtimeContract: {
+    promptInput: _promptInput;
+    promptResult: _promptResult;
+    replayResult: _replayResult;
+    eventsResult: _eventsResult;
+};
+export {};

package/dist/test/runtime-contract.js

@@ -0,0 +1,6 @@
+export const runtimeContract = {
+    promptInput: true,
+    promptResult: true,
+    replayResult: true,
+    eventsResult: true,
+};

package/dist/test/runtime.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/runtime.test.js

@@ -0,0 +1,134 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import { createOpenScienceRuntime, RuntimeEventCursorError } from "../src/v2/runtime.js";
+describe("OpenScienceRuntime", () => {
+    test("sends the strict public prompt contract and returns the accepted run", async () => {
+        let request;
+        const runtime = createOpenScienceRuntime({
+            baseUrl: "http://runtime.test",
+            fetch: async (input) => {
+                request = input instanceof Request ? input : new Request(input);
+                return Response.json({ runID: "run_public", acceptedAt: 123 }, { status: 202 });
+            },
+        });
+        assert.deepEqual(await runtime.prompt({ sessionID: "ses_public", message: "Analyze this", effort: "ultra" }), {
+            runID: "run_public",
+            acceptedAt: 123,
+        });
+        assert.equal(request?.url, "http://runtime.test/runtime/prompt");
+        assert.equal(request?.method, "POST");
+        assert.deepEqual(await request?.json(), {
+            sessionID: "ses_public",
+            message: "Analyze this",
+            effort: "ultra",
+        });
+    });
+    test("generated prompt serialization keeps normal effort in the request body", async () => {
+        let body;
+        const runtime = createOpenScienceRuntime({
+            baseUrl: "http://runtime.test",
+            fetch: async (input) => {
+                const request = input instanceof Request ? input : new Request(input);
+                body = await request.json();
+                return Response.json({ runID: "run_normal", acceptedAt: 321 }, { status: 202 });
+            },
+        });
+        await runtime.prompt({ sessionID: "ses_normal", message: "Summarize", effort: "normal" });
+        assert.deepEqual(body, { sessionID: "ses_normal", message: "Summarize", effort: "normal" });
+    });
+    test("replays from a sequence cursor and yields typed SSE events", async () => {
+        const urls = [];
+        const controller = new AbortController();
+        const event = {
+            sequence: 4,
+            sessionID: "ses_public",
+            runID: "run_public",
+            type: "runtime.completed",
+            properties: { messageID: "msg_public" },
+            time: 456,
+        };
+        const runtime = createOpenScienceRuntime({
+            baseUrl: "http://runtime.test",
+            fetch: async (input) => {
+                const request = input instanceof Request ? input : new Request(input);
+                urls.push(request.url);
+                if (request.url.includes("/replay")) {
+                    return Response.json({ events: [event], oldestSequence: 1, latestSequence: 4 });
+                }
+                return new Response(`id: 4\nevent: runtime.completed\ndata: ${JSON.stringify(event)}\n\n`, {
+                    headers: { "content-type": "text/event-stream" },
+                });
+            },
+        });
+        assert.deepEqual(await runtime.replay({ sessionID: "ses_public", afterSequence: 3 }), {
+            events: [event],
+            oldestSequence: 1,
+            latestSequence: 4,
+        });
+        const received = [];
+        for await (const item of runtime.events({ sessionID: "ses_public", afterSequence: 3, signal: controller.signal })) {
+            received.push(item);
+            controller.abort();
+        }
+        assert.deepEqual(received, [event]);
+        assert.deepEqual(urls, [
+            "http://runtime.test/runtime/events/replay?sessionID=ses_public&afterSequence=3",
+            "http://runtime.test/runtime/events?sessionID=ses_public&afterSequence=3",
+        ]);
+    });
+    test("reconnects after clean EOF with the last delivered sequence", async () => {
+        const requests = [];
+        const controller = new AbortController();
+        const event = (sequence) => ({
+            sequence,
+            sessionID: "ses_reconnect",
+            runID: "run_reconnect",
+            type: sequence === 1 ? "runtime.accepted" : "runtime.completed",
+            properties: sequence === 1 ? { effort: "normal" } : { messageID: "msg_done" },
+            time: sequence,
+        });
+        const runtime = createOpenScienceRuntime({
+            baseUrl: "http://runtime.test",
+            runtimeReconnectDelayMs: 0,
+            fetch: async (input) => {
+                const request = input instanceof Request ? input : new Request(input);
+                requests.push(request);
+                const current = event(requests.length);
+                return new Response(`id: ${current.sequence}\nevent: ${current.type}\ndata: ${JSON.stringify(current)}\n\n`, {
+                    headers: { "content-type": "text/event-stream" },
+                });
+            },
+        });
+        const received = [];
+        for await (const item of runtime.events({
+            sessionID: "ses_reconnect",
+            afterSequence: 0,
+            signal: controller.signal,
+        })) {
+            received.push(item);
+            if (received.length === 2)
+                controller.abort();
+        }
+        assert.deepEqual(received.map((item) => item.sequence), [1, 2]);
+        assert.equal(requests.length, 2);
+        assert.equal(requests[0]?.headers.get("Last-Event-ID"), "0");
+        assert.equal(requests[1]?.headers.get("Last-Event-ID"), "1");
+    });
+    test("surfaces a retained-window conflict without retrying forever", async () => {
+        let calls = 0;
+        const runtime = createOpenScienceRuntime({
+            baseUrl: "http://runtime.test",
+            runtimeReconnectDelayMs: 0,
+            fetch: async () => {
+                calls += 1;
+                return Response.json({ error: "cursor_expired" }, { status: 409, statusText: "Conflict" });
+            },
+        });
+        await assert.rejects(async () => {
+            for await (const _ of runtime.events({ sessionID: "ses_expired", afterSequence: 1 })) {
+                // No event is expected.
+            }
+        }, RuntimeEventCursorError);
+        assert.equal(calls, 1);
+    });
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@synsci/sdk",
-  "version": "2.0.23",
+  "version": "2.0.24",
   "type": "module",
   "license": "Apache-2.0",
   "scripts": {