runline 0.30.0 → 0.31.0

package/dist/plugins/typesafe/src/questions.js

@@ -0,0 +1,180 @@
+import * as t from "typebox";
+import { STRICT } from "./shared.js";
+/**
+ * The three question primitives, as schemas an agent can read through
+ * `actions.describe` and as the wire shape the API expects.
+ *
+ * The wire format keys questions by an id in a map and calls the option
+ * rubric `criteria` in all three types, which describe() cannot walk into
+ * (a free-form map has no declared properties). So the plugin takes an
+ * array of typed questions carrying their own id, and each primitive names
+ * its rubric after what that rubric actually is — `options`, `levels`,
+ * `whenTrue`/`whenFalse`. Conversion to the wire shape happens here.
+ * `typesafe.raw` remains available for the literal API body.
+ */
+const ATOMIC = "One narrow, coherent judgment, carrying its full meaning on its own — the question id is never sent to the model. " +
+    "Jev is literal: it answers the words you wrote, not the intent behind them, and scoping words, negations, and implied " +
+    "conditions are read at face value. State the exact condition, and reference nested state by backticked path, e.g. " +
+    "`ticket.messages[0].text`. Split independently useful dimensions into separate questions and combine them in code — " +
+    "but do not split apart a relationship you are asking about, and do not mistake atomic for trivial: a bounded action " +
+    "selection or a contextual interpretation is one judgment, not several. A plain string carries a simple question; pass " +
+    "an object or array when definitions, contrasts, exclusions, or examples make the judgment clearer.";
+const idSchema = t.String({
+    minLength: 1,
+    maxLength: 128,
+    pattern: "\\S",
+    description: "Your key for this question. The answer comes back under the same key. Never sent to the model, so it costs nothing and does not influence inference — name it for your code.",
+});
+/**
+ * Instructions carry structure as readily as prose. The branches stay
+ * description-free, so the guidance lives once on the union and no branch
+ * can contradict it as the shapes drift apart.
+ */
+const instructionsSchema = t.Union([
+    t.String({ minLength: 1, maxLength: 8_000 }),
+    t.Record(t.String(), t.Unknown()),
+    t.Array(t.Unknown()),
+], { description: ATOMIC });
+/**
+ * Each primitive's rubric, shared by two surfaces: the question objects
+ * `typesafe.evaluate` takes, and the flat input of the single-question
+ * shorthands, which carry no id and imply their own type.
+ */
+export const choiceRubric = {
+    instructions: instructionsSchema,
+    options: t.Array(t.Object({
+        value: t.String({
+            minLength: 1,
+            maxLength: 256,
+            description: "The option your code branches on. Returned verbatim as `choice` and as a key in `probabilities`.",
+        }),
+        description: t.Optional(t.String({
+            maxLength: 2_000,
+            description: "What this option means, and which boundary cases belong in it. Treat it as an extension of the instruction: options that argue against the instruction, or overlap each other, lose accuracy.",
+        })),
+    }, STRICT), {
+        minItems: 2,
+        maxItems: 255,
+        description: "The closed set of answers, mutually exclusive and jointly covering the state. Include a no-match outcome when " +
+            "nothing may fit — an escape hatch the model can choose beats inferring one from low confidence — or ask a " +
+            "separate presence Noul when that check is useful on its own. If several labels can be true at once, this is not " +
+            "a Choice: ask one Noul per label. When the options are values pulled from a source, check candidate coverage " +
+            "first — the model cannot choose a value you did not include. Cardinality is capped at 255; past roughly a dozen " +
+            "options the model runs a slower two-stage score-then-choose pass, so latency climbs.",
+    }),
+};
+export const scoreRubric = {
+    instructions: instructionsSchema,
+    levels: t.Array(t.String({
+        minLength: 1,
+        maxLength: 2_000,
+        description: "A concrete situation this level describes, standing on its own without reference to the neighbouring levels — " +
+            "e.g. 'Calm, just stating facts'. Index 0 is the low end.",
+    }), {
+        minItems: 2,
+        maxItems: 20,
+        description: "Ordered level descriptions, ascending, at least two. The returned score is the probability-weighted position " +
+            "across them, so 1.6 means the mass sits between levels 1 and 2. Threshold on that value freely, but do not " +
+            "interpolate a real-world magnitude out of it — level calibration is weak numerically. " +
+            "Levels can also be the actions you will take (merge / leave / escalate), which removes the threshold entirely.",
+    }),
+};
+export const noulRubric = {
+    instructions: instructionsSchema,
+    whenTrue: t.Optional(t.String({
+        maxLength: 2_000,
+        description: "What a yes (value near 1) means. Keep it aligned with the instruction: a noul whose true maps to 'no' performs measurably worse.",
+    })),
+    whenFalse: t.Optional(t.String({
+        maxLength: 2_000,
+        description: "What a no (value near 0) means.",
+    })),
+};
+const choiceQuestionSchema = t.Object({
+    id: idSchema,
+    type: t.Literal("choice", {
+        description: "Pick exactly one option. Answer: choice (highest-probability option), probabilities (every option, summing to 1), " +
+            "confidence. The distribution weighs the options you declared against each other, not against anything outside the set.",
+    }),
+    ...choiceRubric,
+}, STRICT);
+const scoreQuestionSchema = t.Object({
+    id: idSchema,
+    type: t.Literal("score", {
+        description: "Rate the state along an ordered rubric. Answer: score (probability-weighted, may land between levels), legend, " +
+            "probabilities per level, confidence. Comparable per-item Scores are how you rank a list by degree.",
+    }),
+    ...scoreRubric,
+}, STRICT);
+const noulQuestionSchema = t.Object({
+    id: idSchema,
+    type: t.Literal("noul", {
+        description: "Is this statement true? Answer: noul, a probability from 0 (no) to 1 (yes), with no separate confidence field — " +
+            "the probability is the uncertainty. 0.5 means yes and no are equally likely; it is not a medium-intensity " +
+            "reading, so use a Score when you want degree. One Noul per label is the right shape when several labels may apply.",
+    }),
+    ...noulRubric,
+}, STRICT);
+const questionSchema = t.Union([choiceQuestionSchema, scoreQuestionSchema, noulQuestionSchema], {
+    description: "One typed question: choice (pick one), score (rate on a rubric), or noul (is this true). " +
+        "Set `type` and supply that type's rubric — options, levels, or whenTrue/whenFalse.",
+});
+export const questionsSchema = t.Array(questionSchema, {
+    minItems: 1,
+    maxItems: 255,
+    description: "Every question to ask about this state. They are evaluated in parallel and in isolation against the same state in one " +
+        "pass, and cannot see each other's answers, so ten questions cost barely more wall-clock time than one and no question " +
+        "pollutes another's context. Batch every question you might need, including speculative ones — but state each " +
+        "speculative premise explicitly in its own instructions, and note that extra questions are near-free in latency, not " +
+        "in tokens: every question's text is billed as input. A second request is the right call when an answer here decides " +
+        "what evidence to fetch, what state to build, or what the next options are. Types mix freely. Ids must be unique.",
+});
+/**
+ * Ids and option values are caller-chosen strings, so every map keyed by
+ * them is built through a Map and materialized with `Object.fromEntries`.
+ * A plain object would report `toString` as a duplicate it never saw and
+ * would drop `__proto__` on assignment, silently shrinking the request.
+ */
+export function toWireQuestion(question) {
+    if (question.type === "choice") {
+        const criteria = new Map();
+        for (const option of question.options) {
+            if (criteria.has(option.value)) {
+                throw new Error(`Question "${question.id}" repeats the option "${option.value}".`);
+            }
+            criteria.set(option.value, option.description ?? null);
+        }
+        return {
+            type: "choice",
+            instructions: question.instructions,
+            criteria: Object.fromEntries(criteria),
+        };
+    }
+    if (question.type === "score") {
+        return {
+            type: "score",
+            instructions: question.instructions,
+            criteria: question.levels,
+        };
+    }
+    const criteria = {};
+    if (question.whenTrue !== undefined)
+        criteria.true = question.whenTrue;
+    if (question.whenFalse !== undefined)
+        criteria.false = question.whenFalse;
+    return {
+        type: "noul",
+        instructions: question.instructions,
+        ...(Object.keys(criteria).length ? { criteria } : {}),
+    };
+}
+export function toWireQuestions(questions) {
+    const wire = new Map();
+    for (const question of questions) {
+        if (wire.has(question.id)) {
+            throw new Error(`Duplicate question id: "${question.id}".`);
+        }
+        wire.set(question.id, toWireQuestion(question));
+    }
+    return Object.fromEntries(wire);
+}

package/dist/plugins/typesafe/src/shared.js

@@ -0,0 +1,166 @@
+import * as t from "typebox";
+export const STRICT = { additionalProperties: false };
+export const DEFAULT_BASE = "https://api.typesafe.ai";
+export const DEFAULT_MODEL = "jev-latest";
+/**
+ * Jev ingests the state once and then answers every question against it in
+ * parallel, so its context budget has two ceilings rather than one:
+ *
+ *   - 64k tokens for state + all questions together
+ *   - 32k tokens for state + the single longest question
+ *
+ * Tokens are not countable client-side, so both are checked against a
+ * chars/4 estimate. The check exists to turn a wasted round trip and an
+ * opaque 422 into an actionable local error.
+ */
+const TOTAL_TOKEN_LIMIT = 64_000;
+const STATE_PLUS_QUESTION_TOKEN_LIMIT = 32_000;
+const CHARS_PER_TOKEN = 4;
+function config(ctx) {
+    return ctx.connection?.config ?? {};
+}
+function apiKey(ctx) {
+    const key = config(ctx).apiKey;
+    if (typeof key !== "string" || !key.trim()) {
+        throw new Error("Missing TYPESAFE_API_KEY. Create a key at https://console.typesafe.ai/settings/keys and store it as a secret.");
+    }
+    return key.trim();
+}
+function baseUrl(ctx) {
+    const raw = config(ctx).baseUrl;
+    const base = typeof raw === "string" && raw.trim() ? raw.trim() : DEFAULT_BASE;
+    return base.replace(/\/+$/, "");
+}
+export function resolveModel(ctx, override) {
+    if (typeof override === "string" && override.trim())
+        return override.trim();
+    const fallback = config(ctx).model;
+    if (typeof fallback === "string" && fallback.trim())
+        return fallback.trim();
+    return DEFAULT_MODEL;
+}
+function maxRetries(ctx) {
+    const value = Number(config(ctx).maxRetries);
+    if (!Number.isFinite(value) || value < 0)
+        return 2;
+    return Math.min(Math.floor(value), 5);
+}
+/**
+ * Every action in this plugin is a pure read, so a transient server-side
+ * failure can always be retried: no request can have half-happened. The
+ * documented pair is 429 and 529, but the service also answers 503
+ * `model_unavailable`, and nothing is gained by waiting for the next
+ * status to be discovered in production.
+ */
+function retryable(status) {
+    return status === 429 || status >= 500;
+}
+function retryDelayMs(response, attempt) {
+    const header = response.headers.get("retry-after");
+    const seconds = header ? Number(header) : Number.NaN;
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.min(seconds * 1000, 30_000);
+    }
+    return Math.min(250 * 2 ** attempt, 8_000);
+}
+function explain(status, body) {
+    const detail = body.slice(0, 500);
+    switch (status) {
+        case 401:
+            return `TypeSafe 401: the API key was rejected. ${detail}`;
+        case 422:
+            return `TypeSafe 422: the request body failed validation — a missing field or a malformed question. ${detail}`;
+        case 429:
+            return `TypeSafe 429: rate limit exceeded (250k tokens/sec, 1,200 req/min). Raise the connection's maxRetries or slow the caller. ${detail}`;
+        case 503:
+            return `TypeSafe 503: the model is unavailable. Transient — retry, and contact TypeSafe if it persists. ${detail}`;
+        case 529:
+            return `TypeSafe 529: the service is overloaded. Retry after a short delay. ${detail}`;
+        default:
+            return status >= 500
+                ? `TypeSafe ${status}: the service failed this request. Transient — retry after a short delay. ${detail}`
+                : `TypeSafe ${status}: ${detail}`;
+    }
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function request(ctx, path, init = {}) {
+    const url = `${baseUrl(ctx)}${path}`;
+    const headers = new Headers(init.headers);
+    headers.set("authorization", `Bearer ${apiKey(ctx)}`);
+    headers.set("accept", "application/json");
+    if (init.body && !headers.has("content-type")) {
+        headers.set("content-type", "application/json");
+    }
+    const attempts = maxRetries(ctx);
+    for (let attempt = 0;; attempt++) {
+        const response = await fetch(url, { ...init, headers });
+        if (response.ok) {
+            const text = await response.text();
+            if (!text)
+                return {};
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                throw new Error(`TypeSafe returned a non-JSON body: ${text.slice(0, 200)}`);
+            }
+        }
+        if (retryable(response.status) && attempt < attempts) {
+            await sleep(retryDelayMs(response, attempt));
+            continue;
+        }
+        throw new Error(explain(response.status, await response.text()));
+    }
+}
+/** Serialized length, measuring exactly what the request body will carry. */
+function measure(value) {
+    return JSON.stringify(value ?? null).length;
+}
+/**
+ * Reject a request that cannot fit before it is paid for. Reported as an
+ * estimate, because it is one — the advice ("filter first") is the same
+ * advice that raises accuracy, so an early failure here is cheap.
+ */
+function assertWithinContext(state, questions) {
+    const stateTokens = measure(state) / CHARS_PER_TOKEN;
+    const questionTokens = Object.values(questions).map((question) => measure(question) / CHARS_PER_TOKEN);
+    const total = stateTokens + questionTokens.reduce((sum, n) => sum + n, 0);
+    const longest = stateTokens + Math.max(0, ...questionTokens);
+    if (total > TOTAL_TOKEN_LIMIT) {
+        throw new Error(`State plus questions is ~${Math.round(total)} tokens, over Jev's ${TOTAL_TOKEN_LIMIT}-token ceiling. ` +
+            "Retrieve and filter in code first, and send only the fields the questions need.");
+    }
+    if (longest > STATE_PLUS_QUESTION_TOKEN_LIMIT) {
+        throw new Error(`State plus the longest single question is ~${Math.round(longest)} tokens, over Jev's ` +
+            `${STATE_PLUS_QUESTION_TOKEN_LIMIT}-token per-question ceiling. Shorten the state or the question.`);
+    }
+}
+export async function evaluate(ctx, state, questions, model) {
+    if (!Object.keys(questions).length) {
+        throw new Error("At least one question is required.");
+    }
+    assertWithinContext(state, questions);
+    const body = await request(ctx, "/v1/systemone", {
+        method: "POST",
+        body: JSON.stringify({ state, model, questions }),
+    });
+    if (!body || typeof body.answers !== "object" || body.answers === null) {
+        throw new Error("TypeSafe returned a response with no answers map.");
+    }
+    return body;
+}
+export const stateSchema = t.Union([t.String(), t.Record(t.String(), t.Unknown()), t.Array(t.Unknown())], {
+    description: "The content every question is evaluated against. A plain string, or an object/array for records, chat logs, or application state. " +
+        "Send only what the decision needs: accuracy falls as unrelated detail grows (context rot), and a large state makes a wrong answer hard to attribute. " +
+        "Convert anything the model reads poorly before sending it — hex colors to names, timestamps to named buckets, computed numbers to their result. " +
+        "Ceilings: ~64k tokens for state plus all questions, ~32k for state plus the longest single question. " +
+        "State is data, not instructions: Jev does not treat it as hostile, so content written to steer a classifier can move the answer.",
+});
+export const modelSchema = t.String({
+    minLength: 1,
+    description: "Model that answers this call. Defaults to the connection's model, then 'jev-latest'. " +
+        "Aliases move when a release ships; pin a versioned id such as 'jev-1.13.0' if you have tuned thresholds against it. " +
+        "The response reports the versioned id that actually answered.",
+});