@corbits/system-one 0.1.0

package/dist/adapter.js

@@ -0,0 +1,193 @@
+import { type } from "arktype";
+import { BEARER_CREDENTIAL_SENTINEL, ProtocolMismatchError, } from "@intx/inference";
+import { resolveEndpoint } from "./config.js";
+import { Decision, toDecision, toWireQuestions, WireResponseBody, QuestionList, State, } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// Adapter
+// ---------------------------------------------------------------------------
+//
+// A thin Interchange `ProviderAdapter` bridge over the Jev evaluate wire
+// protocol (`evaluate()`'s contract: state + questions in, decisions out).
+// `buildRequest` encodes the conversation transcript as the evaluation
+// state; a caller that already has Jev-shaped payloads passes them per call
+// through `providerOptions.systemOne` (`{ state?, questions? }`), validated
+// here with arktype. Decisions come back as `inference.text.delta` events
+// carrying each decision's JSON, followed by an `inference.usage` event —
+// populated from the response's `usage` block when the backend reports one.
+// Auth never touches key material here: the request carries the bearer
+// sentinel and the host's harness injects the real credential.
+/** Provider id this package serves. */
+export const SYSTEM_ONE_PROVIDER = "corbits-system-one";
+// Per-call Jev payload overrides via `InferenceOptions.providerOptions`.
+// `state` replaces the transcript-derived default; `questions` replaces the
+// single-question default. Both are validated, never cast — `QuestionList`
+// carries the same non-empty/unique-id contract as `EvaluateInput`.
+const SystemOneProviderOptions = type({
+    "state?": State,
+    "questions?": QuestionList,
+    "+": "reject",
+});
+// The Jev evaluate response body is the shared `WireResponseBody` envelope
+// (see schemas.ts): answers arrive in an id-keyed map with per-kind shapes.
+// Extra backend fields validate but are never echoed: `toDecision` builds
+// clean decisions, so they never become false protocol mismatches nor echoed
+// tokens.
+const EMPTY_PARTIAL = { text: "" };
+const ZERO_USAGE = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    thinking: 0,
+};
+// The bridge default question, used when the caller supplies no questions
+// via `providerOptions.systemOne`: a conversation has no inherent Jev
+// questions, so the adapter asks the one boolean every transcript answers —
+// whether the turn responds — and lets the host interpret the decision.
+const DEFAULT_QUESTIONS = [
+    {
+        type: "boolean",
+        id: "response",
+        instructions: "Does this turn respond to the conversation?",
+    },
+];
+function transcriptText(turns) {
+    const texts = [];
+    for (const turn of turns) {
+        const parts = [];
+        const content = turn.content;
+        for (const block of content) {
+            if (block.type === "text")
+                parts.push(block.text);
+        }
+        if (parts.length > 0)
+            texts.push(`${turn.role}: ${parts.join("")}`);
+    }
+    return texts.join("\n");
+}
+function toTokenUsage(usage) {
+    if (usage === undefined)
+        return ZERO_USAGE;
+    return {
+        input: usage.input_tokens,
+        output: usage.output_tokens,
+        cacheRead: 0,
+        cacheWrite: 0,
+        thinking: 0,
+    };
+}
+function parseDecisions(body, provider) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch (cause) {
+        throw new ProtocolMismatchError(`${provider} parseJSONResponse: malformed JSON response body: ${cause instanceof Error ? cause.message : String(cause)}`, body);
+    }
+    const envelope = WireResponseBody(parsed);
+    if (envelope instanceof type.errors) {
+        throw new ProtocolMismatchError(`${provider} parseJSONResponse: response failed schema validation: ${envelope.summary}`, parsed);
+    }
+    const decisions = Object.keys(envelope.answers).map((id) => {
+        const answer = envelope.answers[id];
+        if (answer === undefined) {
+            throw new ProtocolMismatchError(`${provider} parseJSONResponse: answer id "${id}" vanished during parsing`, parsed);
+        }
+        try {
+            return toDecision(id, answer);
+        }
+        catch (cause) {
+            throw new ProtocolMismatchError(`${provider} parseJSONResponse: ${cause instanceof Error ? cause.message : String(cause)}`, parsed);
+        }
+    });
+    return { decisions, usage: envelope.usage };
+}
+/**
+ * Builds the Interchange `ProviderAdapter` for System One against the
+ * host's single copy of `@intx/inference` (peer dependency, never vendored).
+ * The optional `config` pins the endpoint (official by default, gateway, or
+ * a custom URL) and the per-call model default; the inference call's own
+ * `model` argument wins for the request body.
+ */
+export function createSystemOneAdapter(config) {
+    const endpoint = resolveEndpoint(config?.endpoint);
+    const source = {
+        sourceId: SYSTEM_ONE_PROVIDER,
+        provider: SYSTEM_ONE_PROVIDER,
+        model: endpoint.model ?? "unknown",
+    };
+    const buildRequest = (messages, model, options) => {
+        let state = { transcript: transcriptText(messages) };
+        let questions = DEFAULT_QUESTIONS;
+        const rawOverrides = options.providerOptions?.["systemOne"];
+        if (rawOverrides !== undefined) {
+            const overrides = SystemOneProviderOptions(rawOverrides);
+            if (overrides instanceof type.errors) {
+                throw new ProtocolMismatchError(`${SYSTEM_ONE_PROVIDER} buildRequest: invalid providerOptions.systemOne: ${overrides.summary}`, rawOverrides);
+            }
+            if (overrides.state !== undefined)
+                state = overrides.state;
+            if (overrides.questions !== undefined)
+                questions = overrides.questions;
+        }
+        const requestModel = model || endpoint.model || "unknown";
+        source.model = requestModel;
+        const headers = {
+            "content-type": "application/json",
+            accept: "application/json",
+            authorization: BEARER_CREDENTIAL_SENTINEL,
+        };
+        return {
+            url: endpoint.url,
+            headers,
+            body: JSON.stringify({
+                state,
+                questions: toWireQuestions(questions),
+                model: requestModel,
+            }),
+        };
+    };
+    const parseJSONResponse = (responseBody) => {
+        const { decisions, usage } = parseDecisions(responseBody, SYSTEM_ONE_PROVIDER);
+        const events = [];
+        let index = 0;
+        for (const decision of decisions) {
+            const token = JSON.stringify(decision);
+            events.push({
+                type: "inference.text.delta",
+                seq: 0,
+                data: { token, partial: EMPTY_PARTIAL, index },
+            });
+            index += 1;
+        }
+        events.push({
+            type: "inference.usage",
+            seq: 0,
+            data: { usage: toTokenUsage(usage), source: { ...source } },
+        });
+        return events;
+    };
+    // The Jev evaluate protocol is non-streaming: a streaming chunk is just a
+    // complete body arriving early, so the SSE path decodes the same JSON.
+    const parseResponse = (sseData) => parseJSONResponse(sseData);
+    // Jev answers 429/529 with a `retry-after` header; surfacing it lets the
+    // host harness's retry policy honor the backend's own backoff hint.
+    const extractRetryAfterMs = (headers) => {
+        const raw = headers.get("retry-after");
+        if (raw === null)
+            return undefined;
+        const seconds = Number(raw);
+        if (Number.isFinite(seconds) && seconds >= 0)
+            return seconds * 1000;
+        const at = Date.parse(raw);
+        if (!Number.isNaN(at))
+            return Math.max(0, at - Date.now());
+        return undefined;
+    };
+    return {
+        buildRequest,
+        parseResponse,
+        parseJSONResponse,
+        extractRetryAfterMs,
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,21 @@
+/** Options for one evaluation POST: timeout and auth, resolved by `evaluate`. */
+export type PostEvaluateOptions = {
+    timeoutMs?: number;
+    apiKey?: string;
+};
+/** The decoded JSON body of a 2xx evaluation response, with its latency. */
+export type PostEvaluateResponse = {
+    data: unknown;
+    latencyMs: number;
+    httpStatus: number;
+};
+/**
+ * POSTs an evaluation payload and returns the decoded JSON body. Sends
+ * `Authorization: Bearer <apiKey>` only when a key is present; aborts the
+ * exchange when `timeoutMs` elapses. A `timeoutMs` that is not a finite
+ * number >= 0 falls back to `DEFAULT_TIMEOUT_MS`. Throws `TimeoutError` on
+ * timeout, `HttpError` (status only, never the body) on non-2xx, and
+ * `NetworkError` when no HTTP exchange completes or the 2xx body is not
+ * valid JSON.
+ */
+export declare function postEvaluate(url: string, body: unknown, options: PostEvaluateOptions): Promise<PostEvaluateResponse>;

package/dist/client.js

@@ -0,0 +1,67 @@
+import { DEFAULT_TIMEOUT_MS } from "./config.js";
+import { HttpError, NetworkError, SystemOneError, TimeoutError, } from "./errors.js";
+/**
+ * POSTs an evaluation payload and returns the decoded JSON body. Sends
+ * `Authorization: Bearer <apiKey>` only when a key is present; aborts the
+ * exchange when `timeoutMs` elapses. A `timeoutMs` that is not a finite
+ * number >= 0 falls back to `DEFAULT_TIMEOUT_MS`. Throws `TimeoutError` on
+ * timeout, `HttpError` (status only, never the body) on non-2xx, and
+ * `NetworkError` when no HTTP exchange completes or the 2xx body is not
+ * valid JSON.
+ */
+export async function postEvaluate(url, body, options) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(body);
+    }
+    catch {
+        throw new SystemOneError("parse-error", "postEvaluate: request body is not JSON-serializable");
+    }
+    const rawTimeoutMs = options.timeoutMs;
+    const timeoutMs = rawTimeoutMs !== undefined &&
+        Number.isFinite(rawTimeoutMs) &&
+        rawTimeoutMs >= 0
+        ? rawTimeoutMs
+        : DEFAULT_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    const start = Date.now();
+    try {
+        const headers = {
+            "content-type": "application/json",
+            accept: "application/json",
+        };
+        if (options.apiKey !== undefined && options.apiKey !== "") {
+            headers["authorization"] = `Bearer ${options.apiKey}`;
+        }
+        let res;
+        try {
+            res = await fetch(url, {
+                method: "POST",
+                headers,
+                body: serialized,
+                signal: controller.signal,
+            });
+        }
+        catch (cause) {
+            if (controller.signal.aborted)
+                throw new TimeoutError(timeoutMs);
+            throw new NetworkError(`system-one request failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        if (!res.ok)
+            throw new HttpError(res.status);
+        let data;
+        try {
+            data = await res.json();
+        }
+        catch {
+            throw new NetworkError("system-one response body is not valid JSON");
+        }
+        return { data, latencyMs: Date.now() - start, httpStatus: res.status };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,36 @@
+import type { EndpointConfig } from "./schemas.js";
+export declare const SystemOneQuirks: import("arktype/internal/variants/object.ts").ObjectType<{
+    baseUrl?: string;
+    model?: string;
+}, {}>;
+export type SystemOneQuirks = typeof SystemOneQuirks.infer;
+export declare const SYSTEM_ONE_DEFAULT_QUIRKS: SystemOneQuirks;
+export declare const GATEWAY_QUIRKS: SystemOneQuirks;
+export declare const TYPESAFE_API_KEY_ENV = "TYPESAFE_API_KEY";
+export declare const GATEWAY_API_KEY_ENV = "AI_GATEWAY_API_KEY";
+export declare const GATEWAY_OIDC_ENV = "VERCEL_OIDC_TOKEN";
+export declare const SYSTEM_ONE_API_KEY_ENV = "SYSTEM_ONE_API_KEY";
+/**
+ * Default bound for one evaluation round trip in milliseconds. 1500ms: a
+ * single non-streaming POST over an already-warm connection should answer
+ * far inside a second, and there is no published pilot SLO to calibrate
+ * against yet — so the default fails fast to a typed `FallbackResult`
+ * instead of holding the caller's round trip hostage. Callers with slower
+ * backends (or a custom endpoint across regions) set `timeoutMs` per call.
+ */
+export declare const DEFAULT_TIMEOUT_MS = 1500;
+/** One resolved evaluation target: the URL to POST, the model to send. */
+export type ResolvedEndpoint = {
+    url: string;
+    backend: "corbits-system-one" | "gateway" | "custom";
+    model?: string;
+};
+/**
+ * Resolves an evaluation endpoint to a concrete POST target. A per-call
+ * `endpoint` wins over the package default (`official`); `custom` must
+ * carry its own `url` and throws a typed `SystemOneError` when it does
+ * not. A `custom` target keeps the `'custom'` backend label so telemetry
+ * distinguishes caller-routed traffic from the official endpoint —
+ * `'gateway'` is reserved for the proxy quirks path.
+ */
+export declare function resolveEndpoint(endpoint?: EndpointConfig): ResolvedEndpoint;

package/dist/config.js

@@ -0,0 +1,88 @@
+import { type } from "arktype";
+import { SystemOneError } from "./errors.js";
+// ---------------------------------------------------------------------------
+// Quirks
+// ---------------------------------------------------------------------------
+//
+// Everything one System One backend needs to bend the shared evaluation wire
+// protocol to its own endpoint, expressed as data instead of a fork of the
+// client. Every field here must be JSON-safe: quirks ride inside persisted
+// configuration, so a function-valued field would silently fail to survive
+// that round trip.
+// Per-endpoint accommodations for the System One evaluation protocol. Every
+// field is optional; an absent field resolves to the protocol default, so a
+// caller that supplies no quirks gets no accommodation.
+export const SystemOneQuirks = type({
+    "baseUrl?": "string",
+    "model?": "string",
+    "+": "reject",
+});
+// The official System One endpoint: the documented Jev systemone route with
+// the stable model alias. Callers needing the proxied route use `gateway`;
+// callers with their own deployment use `custom` with an explicit `url`.
+export const SYSTEM_ONE_DEFAULT_QUIRKS = {
+    baseUrl: "https://api.typesafe.ai/v1/systemone",
+    model: "jev-latest",
+};
+// The Vercel AI Gateway proxy for the Jev model, TypeSafe-compatible REST
+// shape. Callers select it per call with `endpoint: { kind: "gateway" }`.
+export const GATEWAY_QUIRKS = {
+    baseUrl: "https://ai-gateway.vercel.sh/typesafe/v1/systemone",
+    model: "typesafe-ai/jev",
+};
+// Credential sources, one per endpoint: a TypeSafe key never authenticates
+// to the gateway and a gateway key never authenticates to TypeSafe direct,
+// so each endpoint reads its own names. `SYSTEM_ONE_API_KEY` stays as the
+// legacy universal fallback (and the key for `custom` endpoints).
+export const TYPESAFE_API_KEY_ENV = "TYPESAFE_API_KEY";
+export const GATEWAY_API_KEY_ENV = "AI_GATEWAY_API_KEY";
+export const GATEWAY_OIDC_ENV = "VERCEL_OIDC_TOKEN";
+export const SYSTEM_ONE_API_KEY_ENV = "SYSTEM_ONE_API_KEY";
+// ---------------------------------------------------------------------------
+// Edge defaults and endpoint resolution
+// ---------------------------------------------------------------------------
+//
+// Defaults resolve here, at the `evaluate` edge, never inside a schema:
+// schemas parse, they don't fill in defaults.
+/**
+ * Default bound for one evaluation round trip in milliseconds. 1500ms: a
+ * single non-streaming POST over an already-warm connection should answer
+ * far inside a second, and there is no published pilot SLO to calibrate
+ * against yet — so the default fails fast to a typed `FallbackResult`
+ * instead of holding the caller's round trip hostage. Callers with slower
+ * backends (or a custom endpoint across regions) set `timeoutMs` per call.
+ */
+export const DEFAULT_TIMEOUT_MS = 1500;
+/**
+ * Resolves an evaluation endpoint to a concrete POST target. A per-call
+ * `endpoint` wins over the package default (`official`); `custom` must
+ * carry its own `url` and throws a typed `SystemOneError` when it does
+ * not. A `custom` target keeps the `'custom'` backend label so telemetry
+ * distinguishes caller-routed traffic from the official endpoint —
+ * `'gateway'` is reserved for the proxy quirks path.
+ */
+export function resolveEndpoint(endpoint) {
+    if (endpoint?.kind === "custom") {
+        if (endpoint.url === "") {
+            throw new SystemOneError("config-error", 'evaluate: endpoint kind "custom" requires an explicit url');
+        }
+        const resolved = { url: endpoint.url, backend: "custom" };
+        if (endpoint.model !== undefined)
+            resolved.model = endpoint.model;
+        return resolved;
+    }
+    const kind = endpoint?.kind ?? "official";
+    const quirks = kind === "gateway" ? GATEWAY_QUIRKS : SYSTEM_ONE_DEFAULT_QUIRKS;
+    const url = quirks.baseUrl;
+    if (url === undefined || url === "") {
+        throw new SystemOneError("backend-unreachable", `evaluate: no baseUrl configured for endpoint kind "${kind}"`);
+    }
+    const resolved = {
+        url,
+        backend: kind === "gateway" ? "gateway" : "corbits-system-one",
+    };
+    const model = endpoint?.model ?? quirks.model;
+    if (model !== undefined)
+        resolved.model = model;
+    return resolved;
+}

package/dist/errors.d.ts

@@ -0,0 +1,35 @@
+import type { FallbackReason } from "./schemas.js";
+/** Every error code `evaluate` can throw. Thrown-only codes (`"not-implemented"`, `"config-error"`) never appear as fallback reasons. */
+export type SystemOneErrorCode = FallbackReason | "not-implemented" | "config-error";
+/** Typed error thrown when `evaluate` cannot return a result at all. */
+export declare class SystemOneError extends Error {
+    readonly code: SystemOneErrorCode;
+    constructor(code: SystemOneErrorCode, message: string);
+}
+/**
+ * The evaluation POST exceeded its timeout budget. Thrown by `postEvaluate`;
+ * `evaluate` reports it as a `FallbackResult` with reason `'timeout'`.
+ */
+export declare class TimeoutError extends SystemOneError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * The evaluation POST never completed an HTTP exchange (DNS/TLS failure,
+ * refused connection, reset stream) or the 200 body was not valid JSON.
+ * Thrown by `postEvaluate`; `evaluate` reports it as a `FallbackResult`
+ * with reason `'network'`.
+ */
+export declare class NetworkError extends SystemOneError {
+    constructor(message: string);
+}
+/**
+ * The evaluation POST completed with a non-2xx status. Carries the status
+ * only — never the response body, which is untrusted vendor output.
+ * Thrown by `postEvaluate`; `evaluate` reports it as a `FallbackResult`
+ * with reason `'http-error'`.
+ */
+export declare class HttpError extends SystemOneError {
+    readonly httpStatus: number;
+    constructor(httpStatus: number);
+}

package/dist/errors.js

@@ -0,0 +1,47 @@
+/** Typed error thrown when `evaluate` cannot return a result at all. */
+export class SystemOneError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SystemOneError";
+        this.code = code;
+    }
+}
+/**
+ * The evaluation POST exceeded its timeout budget. Thrown by `postEvaluate`;
+ * `evaluate` reports it as a `FallbackResult` with reason `'timeout'`.
+ */
+export class TimeoutError extends SystemOneError {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super("timeout", `system-one request timed out after ${timeoutMs}ms`);
+        this.name = "TimeoutError";
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * The evaluation POST never completed an HTTP exchange (DNS/TLS failure,
+ * refused connection, reset stream) or the 200 body was not valid JSON.
+ * Thrown by `postEvaluate`; `evaluate` reports it as a `FallbackResult`
+ * with reason `'network'`.
+ */
+export class NetworkError extends SystemOneError {
+    constructor(message) {
+        super("network", message);
+        this.name = "NetworkError";
+    }
+}
+/**
+ * The evaluation POST completed with a non-2xx status. Carries the status
+ * only — never the response body, which is untrusted vendor output.
+ * Thrown by `postEvaluate`; `evaluate` reports it as a `FallbackResult`
+ * with reason `'http-error'`.
+ */
+export class HttpError extends SystemOneError {
+    httpStatus;
+    constructor(httpStatus) {
+        super("http-error", `system-one request failed with HTTP ${httpStatus}`);
+        this.name = "HttpError";
+        this.httpStatus = httpStatus;
+    }
+}

package/dist/evaluate.d.ts

@@ -0,0 +1,18 @@
+import { EvaluateInput, type EvaluateResult, type FallbackResult } from "./schemas.js";
+/**
+ * Runs one typed-decision evaluation against System One (or its gateway)
+ * and returns either the backend's decisions or a typed fallback. One POST
+ * per call no matter how many questions are asked. Credential precedence:
+ * a non-empty per-call `apiKey` (an empty string falls through to the
+ * environment, never shadowing it), then the endpoint's environment key —
+ * `TYPESAFE_API_KEY` for official, `AI_GATEWAY_API_KEY` then
+ * `VERCEL_OIDC_TOKEN` for gateway — then the legacy `SYSTEM_ONE_API_KEY`
+ * fallback, then a fail-closed `'no-key'` fallback with zero fetch calls.
+ * A `timeoutMs` that is not a finite number >= 0 falls back to
+ * `DEFAULT_TIMEOUT_MS`. Transport failures map to matching fallback reasons
+ * (`'timeout'`, `'network'`, `'http-error'`); backend output that fails
+ * strict validation maps to `'parse-error'` with the violation in `detail`.
+ * Only caller-side misuse (invalid input, a `custom` endpoint without a
+ * `url`) throws, as a typed `SystemOneError`.
+ */
+export declare function evaluate(input: EvaluateInput): Promise<EvaluateResult | FallbackResult>;