@corbits/system-one 0.2.0 → 0.3.1

package/README.md

@@ -57,15 +57,16 @@ Boolean questions answer as `noul`, a probability from 0 to 1 that the answer is
 
 ## Reference
 
-| Export                            | Description                                                                      |
-| --------------------------------- | -------------------------------------------------------------------------------- |
-| `evaluate(input, options?)`       | Runs one evaluation. Returns `EvaluateResult`: decisions or a `FallbackResult`.  |
-| `createSystemOneAdapter(config?)` | Returns a `ProviderAdapter` for `runInference`. `config` is an `EvaluateConfig`. |
-| `SYSTEM_ONE_PROVIDER`             | The `"corbits-system-one"` provider id.                                          |
-| `DEFAULT_TIMEOUT_MS`              | `1500`, the default `timeoutMs`.                                                 |
-| `SystemOneError`                  | Thrown for invalid input or a `custom` endpoint without a `url`.                 |
-| `SystemOneTelemetryEvent`         | Schema and type for events passed to `onTelemetry`.                              |
-| `EvaluateOptions`, `EvaluateDeps` | Types for `options`: `onTelemetry`, and `deps: { fetch, scheduler }`.            |
+| Export                            | Description                                                                         |
+| --------------------------------- | ----------------------------------------------------------------------------------- |
+| `evaluate(input, options?)`       | Runs one evaluation. Returns `EvaluateResult`: decisions or a `FallbackResult`.     |
+| `createSystemOneAdapter(config?)` | Returns a `ProviderAdapter` for `runInference`. `config` is an `EvaluateConfig`.    |
+| `createSystemOneAdapterFactory`   | Interchange `AdapterFactory` for `SIDECAR_ADAPTER_MANIFEST`; takes offering quirks. |
+| `SYSTEM_ONE_PROVIDER`             | The `"corbits-system-one"` provider id.                                             |
+| `DEFAULT_TIMEOUT_MS`              | `1500`, the default `timeoutMs`.                                                    |
+| `SystemOneError`                  | Thrown for invalid input or a `custom` endpoint without a `url`.                    |
+| `SystemOneTelemetryEvent`         | Schema and type for events passed to `onTelemetry`.                                 |
+| `EvaluateOptions`, `EvaluateDeps` | Types for `options`: `onTelemetry`, and `deps: { fetch, scheduler }`.               |
 
 `Question`, `QuestionList`, `Decision`, `EvaluateInput`, `EvaluateConfig`, `EndpointConfig`, `EvaluateResult` and `FallbackResult` are exported as arktype schemas and types.
 
@@ -169,6 +170,49 @@ for await (const event of runInference({
 
 The adapter emits one `inference.text.delta` per decision, whose `token` is the decision as JSON, then an `inference.usage` event. The harness supplies the credential through `readMaterial` and owns retries. A malformed response body is a `ProtocolMismatchError`, not a fallback.
 
+### Manifest factory
+
+`createSystemOneAdapterFactory(source, quirks?)` is an Interchange `AdapterFactory`, so a stock sidecar loads it from `SIDECAR_ADAPTER_MANIFEST` with no custom code:
+
+```json
+[
+  {
+    "provider": "corbits-system-one",
+    "specifier": "@corbits/system-one",
+    "export": "createSystemOneAdapterFactory"
+  }
+]
+```
+
+The hub offering's `quirks` are validated and all optional:
+
+```json
+{
+  "endpoint": {
+    "kind": "custom",
+    "url": "https://opencode.ai/zen/v1/systemone"
+  },
+  "model": "jev-1.13",
+  "questions": [{ "type": "boolean", "id": "gate", "instructions": "Allow?" }],
+  "state": {}
+}
+```
+
+Without `endpoint`, the adapter posts to the catalog provider's `baseURL` + `/systemone`, the host the offering's credential was issued for. A `model` quirk (top level or on `endpoint`) is the model sent on the wire, so one catalog model can be served by providers that name it differently. `questions` and `state` are per-call defaults; `providerOptions.systemOne` on a call wins field by field. Unknown keys throw. The adapter sends the bearer sentinel and the harness injects the offering's credential.
+
+| Provider          | Provider `baseURL`                         | `model` quirk                 |
+| ----------------- | ------------------------------------------ | ----------------------------- |
+| TypeSafe          | `https://api.typesafe.ai/v1`               | `jev-latest`                  |
+| Vercel AI Gateway | `https://ai-gateway.vercel.sh/typesafe/v1` | `typesafe-ai/jev`             |
+| OpenRouter        | `https://openrouter.ai/api/v1`             | `typesafe/jev-1.13`           |
+| OpenCode Zen      | `https://opencode.ai/zen/v1`               | `jev-1.13` or `jev-1.13-free` |
+
+## Upgrading to 0.3.1
+
+- `createSystemOneAdapterFactory` without an `endpoint` quirk now posts to the catalog provider's `baseURL` + `/systemone` instead of the official TypeSafe URL. Set the provider `baseURL` to the API root (for example `https://api.typesafe.ai/v1`), or keep the old behavior with `{"endpoint":{"kind":"official"}}`. The harness sends the offering's credential to whatever URL the adapter returns, so only set an explicit `endpoint` on a host that credential belongs to.
+- A `model` quirk now overrides the model the harness passes (the catalog canonical name).
+- `createSystemOneAdapter` and `evaluate` are unchanged.
+
 ## Upgrading from 0.1
 
 - `HttpError`, `NetworkError` and `TimeoutError` are removed. Transport failures return a `FallbackResult`.

package/dist/adapter.d.ts

@@ -1,12 +1,14 @@
-import { type ProviderAdapter } from "@intx/inference";
+import { type AdapterFactory, type ProviderAdapter } from "@intx/inference";
 import { type EvaluateConfig } from "./schemas.js";
 /** Provider id this package serves. */
 export declare const SYSTEM_ONE_PROVIDER = "corbits-system-one";
+export declare function createSystemOneAdapter(config?: EvaluateConfig): ProviderAdapter;
 /**
- * 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.
+ * Interchange `AdapterFactory` for `SIDECAR_ADAPTER_MANIFEST`: validates the
+ * offering's `quirks` and builds the same adapter `createSystemOneAdapter`
+ * does. Without an
+ * `endpoint` quirk, requests go to the catalog provider's `baseURL` +
+ * `/systemone`. A quirk `model` (on `endpoint` or top level) is the model
+ * sent on the wire, overriding the catalog's canonical name.
  */
-export declare function createSystemOneAdapter(config?: EvaluateConfig): ProviderAdapter;
+export declare const createSystemOneAdapterFactory: AdapterFactory;

package/dist/adapter.js

@@ -1,7 +1,7 @@
 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";
+import { Decision, toDecision, toWireQuestions, WireResponseBody, EndpointConfig, QuestionList, State, } from "./schemas.js";
 // ---------------------------------------------------------------------------
 // Adapter
 // ---------------------------------------------------------------------------
@@ -109,8 +109,13 @@ function parseDecisions(body, provider) {
  * 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) {
+function createSystemOneProviderAdapter(config, source) {
     const endpoint = resolveEndpoint(config?.endpoint);
+    const usageSource = source ?? {
+        sourceId: SYSTEM_ONE_PROVIDER,
+        provider: SYSTEM_ONE_PROVIDER,
+        model: endpoint.model,
+    };
     const buildRequest = (messages, model, options) => {
         let state = { transcript: transcriptText(messages) };
         let questions = DEFAULT_QUESTIONS;
@@ -160,9 +165,8 @@ export function createSystemOneAdapter(config) {
             data: {
                 usage: toTokenUsage(usage),
                 source: {
-                    sourceId: SYSTEM_ONE_PROVIDER,
-                    provider: SYSTEM_ONE_PROVIDER,
-                    model: model ?? endpoint.model,
+                    ...usageSource,
+                    model: model ?? usageSource.model,
                 },
             },
         });
@@ -192,3 +196,58 @@ export function createSystemOneAdapter(config) {
         extractRetryAfterMs,
     };
 }
+export function createSystemOneAdapter(config) {
+    return createSystemOneProviderAdapter(config);
+}
+// Deployment quirks a hub offering carries for this provider. `questions`
+// and `state` are per-call defaults: a call's own `providerOptions.systemOne`
+// wins field by field.
+const SystemOneFactoryQuirks = type({
+    "endpoint?": EndpointConfig,
+    "model?": "string",
+    "questions?": QuestionList,
+    "state?": State,
+    "+": "reject",
+});
+// Interchange joins a relative request path to the catalog provider's
+// `baseURL`, the host the offering's credential was issued for.
+const PROVIDER_ENDPOINT = { kind: "custom", url: "/systemone" };
+/**
+ * Interchange `AdapterFactory` for `SIDECAR_ADAPTER_MANIFEST`: validates the
+ * offering's `quirks` and builds the same adapter `createSystemOneAdapter`
+ * does. Without an
+ * `endpoint` quirk, requests go to the catalog provider's `baseURL` +
+ * `/systemone`. A quirk `model` (on `endpoint` or top level) is the model
+ * sent on the wire, overriding the catalog's canonical name.
+ */
+export const createSystemOneAdapterFactory = (source, quirks) => {
+    const parsed = SystemOneFactoryQuirks(quirks ?? {});
+    if (parsed instanceof type.errors) {
+        throw new Error(`${SYSTEM_ONE_PROVIDER} adapter: invalid quirks: ${parsed.summary}`);
+    }
+    const wireModel = parsed.endpoint?.model ?? parsed.model;
+    if (wireModel === "") {
+        throw new Error(`${SYSTEM_ONE_PROVIDER} adapter: invalid quirks: model must not be empty`);
+    }
+    const adapter = createSystemOneProviderAdapter({ endpoint: parsed.endpoint ?? PROVIDER_ENDPOINT }, source);
+    const defaults = {
+        ...(parsed.state !== undefined && { state: parsed.state }),
+        ...(parsed.questions !== undefined && { questions: parsed.questions }),
+    };
+    return {
+        ...adapter,
+        buildRequest: (messages, model, options) => {
+            const raw = options.providerOptions?.["systemOne"];
+            const call = raw === undefined ? {} : raw;
+            return adapter.buildRequest(messages, wireModel ?? model, {
+                ...options,
+                providerOptions: {
+                    ...options.providerOptions,
+                    systemOne: typeof call === "object" && call !== null
+                        ? { ...defaults, ...call }
+                        : call,
+                },
+            });
+        },
+    };
+};

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { DEFAULT_TIMEOUT_MS } from "./config.js";
 export type { EvaluateDeps } from "./client.js";
 export { evaluate } from "./evaluate.js";
 export type { EvaluateOptions } from "./evaluate.js";
-export { createSystemOneAdapter, SYSTEM_ONE_PROVIDER } from "./adapter.js";
+export { createSystemOneAdapter, createSystemOneAdapterFactory, SYSTEM_ONE_PROVIDER, } from "./adapter.js";
 export { SystemOneError } from "./errors.js";
 export type { SystemOneErrorCode } from "./errors.js";
 export { SystemOneTelemetryEvent } from "./telemetry.js";

package/dist/index.js

@@ -1,6 +1,6 @@
 export { DEFAULT_TIMEOUT_MS } from "./config.js";
 export { evaluate } from "./evaluate.js";
-export { createSystemOneAdapter, SYSTEM_ONE_PROVIDER } from "./adapter.js";
+export { createSystemOneAdapter, createSystemOneAdapterFactory, SYSTEM_ONE_PROVIDER, } from "./adapter.js";
 export { SystemOneError } from "./errors.js";
 export { SystemOneTelemetryEvent } from "./telemetry.js";
 export { BooleanQuestion, ChoiceQuestion, Decision, Description, EndpointConfig, EvaluateConfig, EvaluateInput, EvaluateResult, FallbackReason, FallbackResult, NoulQuestion, ProbabilityMap, Question, QuestionList, ScoreQuestion, State, Usage, } from "./schemas.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@corbits/system-one",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Typed-decision evaluation client for System One (Jev-class) models: arktype question/decision schemas, endpoint configuration with gateway override, and timeout/fallback semantics.",
   "keywords": [
     "corbits",