runline 0.30.0 → 0.31.0

package/dist/plugins/linear/src/views.js

@@ -1,5 +1,5 @@
 import * as t from "typebox";
-import { bindGetAction, bindListAction, buildConnArgs, CUSTOM_VIEW_FIELDS, FEED_ITEM_FIELDS, gql, INITIATIVE_FIELDS, ISSUE_LITE, key, LIST_INPUT_SCHEMA, mergeIssueScopeFilter, PROJECT_FIELDS, requireUnscoped, } from "./shared.js";
+import { bindGetAction, bindListAction, buildConnArgs, CUSTOM_VIEW_FIELDS, FEED_ITEM_FIELDS, gql, INITIATIVE_FIELDS, ISSUE_LITE, key, LIST_INPUT_SCHEMA, mergeIssueScopeFilter, PROJECT_FIELDS, requireUnscoped, withScopedNote, } from "./shared.js";
 const ISSUE_FILTER_DESCRIPTION = "IssueFilter payload. Examples: label { labels: { id: { in: ['label-id'] } } }; project { project: { id: { eq: 'project-id' } } }; assignee { assignee: { id: { eq: 'user-id' } } }; state { state: { id: { eq: 'state-id' } } }; priority { priority: { eq: 1 } }; due window { dueDate: { gte: '2026-06-09', lte: '2026-06-16' } }; combine with and/or arrays.";
 export function registerViewActions(rl) {
     const listAction = bindListAction(rl);
@@ -7,7 +7,9 @@ export function registerViewActions(rl) {
     function customViewConnectionAction(name, description, connectionField, filterTypeName, selection, includeSubTeamsDescription) {
         rl.registerAction(name, {
             access: "read",
-            description,
+            description: connectionField === "issues"
+                ? description
+                : withScopedNote(description),
             inputSchema: t.Object({
                 viewId: t.String({ description: "The custom view ID or slug" }),
                 ...LIST_INPUT_SCHEMA,
@@ -19,11 +21,11 @@ export function registerViewActions(rl) {
             }),
             async execute(input, ctx) {
                 const opts = (input ?? {});
-                const scopedOpts = connectionField === "issues"
-                    ? { ...opts, filter: mergeIssueScopeFilter(ctx, opts.filter) }
-                    : opts;
                 if (connectionField !== "issues")
                     requireUnscoped(ctx, name);
+                const scopedOpts = connectionField === "issues"
+                    ? { ...opts, filter: await mergeIssueScopeFilter(ctx, opts.filter) }
+                    : opts;
                 const { argsDecl, argsCall, vars } = buildConnArgs(scopedOpts, filterTypeName);
                 const declParts = ["$id: String!", argsDecl.slice(1, -1)];
                 const callParts = [argsCall.slice(1, -1)];
@@ -46,7 +48,7 @@ export function registerViewActions(rl) {
     getAction("view.get", "Get a custom view by ID or slug.", "customView", CUSTOM_VIEW_FIELDS);
     rl.registerAction("view.create", {
         access: "write",
-        description: "Create a custom view. Set filterData for issue views; projectFilterData, initiativeFilterData, or feedItemFilterData for other view types. Read matches back with view.issues/projects/initiatives/updates.",
+        description: withScopedNote("Create a custom view. Set filterData for issue views; projectFilterData, initiativeFilterData, or feedItemFilterData for other view types. Read matches back with view.issues/projects/initiatives/updates."),
         inputSchema: t.Object({
             name: t.String({ description: "The name of the custom view" }),
             description: t.Optional(t.String({ description: "The description of the custom view" })),
@@ -77,7 +79,7 @@ export function registerViewActions(rl) {
     });
     rl.registerAction("view.update", {
         access: "write",
-        description: "Update a custom view. All fields optional; only provided fields are updated.",
+        description: withScopedNote("Update a custom view. All fields optional; only provided fields are updated."),
         inputSchema: t.Object({
             id: t.String({
                 description: "The identifier of the custom view to update",
@@ -109,7 +111,7 @@ export function registerViewActions(rl) {
     });
     rl.registerAction("view.delete", {
         access: "write",
-        description: "Delete a custom view.",
+        description: withScopedNote("Delete a custom view."),
         inputSchema: t.Object({
             id: t.String({
                 description: "The identifier of the custom view to delete",

package/dist/plugins/linear/src/webhooks.js

@@ -1,5 +1,5 @@
 import * as t from "typebox";
-import { bindGetAction, bindListAction, gql, key, requireUnscoped, WEBHOOK_FIELDS, } from "./shared.js";
+import { bindGetAction, bindListAction, gql, key, requireUnscoped, WEBHOOK_FIELDS, withScopedNote, } from "./shared.js";
 export function registerWebhookActions(rl) {
     const listAction = bindListAction(rl);
     const getAction = bindGetAction(rl);
@@ -7,7 +7,7 @@ export function registerWebhookActions(rl) {
     getAction("webhook.get", "Get a webhook by ID.", "webhook", WEBHOOK_FIELDS);
     rl.registerAction("webhook.create", {
         access: "write",
-        description: "Create a webhook. resourceTypes example: ['Issue','Comment','Project'].",
+        description: withScopedNote("Create a webhook. resourceTypes example: ['Issue','Comment','Project']."),
         inputSchema: t.Object({
             url: t.String({
                 description: "The URL that will be called on data changes",
@@ -40,7 +40,7 @@ export function registerWebhookActions(rl) {
     });
     rl.registerAction("webhook.update", {
         access: "write",
-        description: "Update a webhook. teamId and allPublicTeams cannot be changed after creation.",
+        description: withScopedNote("Update a webhook. teamId and allPublicTeams cannot be changed after creation."),
         inputSchema: t.Object({
             id: t.String({ description: "The identifier of the webhook to update" }),
             url: t.Optional(t.String({
@@ -64,7 +64,7 @@ export function registerWebhookActions(rl) {
     });
     rl.registerAction("webhook.delete", {
         access: "write",
-        description: "Delete a webhook.",
+        description: withScopedNote("Delete a webhook."),
         inputSchema: t.Object({
             id: t.String({ description: "The identifier of the webhook to delete" }),
         }),
@@ -76,7 +76,7 @@ export function registerWebhookActions(rl) {
     });
     rl.registerAction("webhook.rotateSecret", {
         access: "write",
-        description: "Rotate a webhook's signing secret. Returns the new secret.",
+        description: withScopedNote("Rotate a webhook's signing secret. Returns the new secret."),
         inputSchema: t.Object({
             id: t.String({
                 description: "The identifier of the webhook to rotate the secret for",

package/dist/plugins/openai/src/index.js

@@ -18,8 +18,27 @@
 import { readImageInput, SEND_FILE_NOTE, writeImageFile, } from "../../_shared/imageFile.js";
 const ENDPOINT = "https://api.openai.com/v1/images/generations";
 const EDIT_ENDPOINT = "https://api.openai.com/v1/images/edits";
-/** Newest GPT Image model; override per call or via the connection. */
-const DEFAULT_MODEL = "gpt-image-2";
+/**
+ * Newest GPT Image model; override per call or via the connection.
+ *
+ * The GPT Image 2.5 line ships as two models: `gpt-image-2.5-flare`
+ * (OpenAI's own default — gpt-image-2 quality at up to half the latency)
+ * and `gpt-image-2.5-sunburst` (precision editing). Both widen the
+ * quality range and take custom sizes; see QUALITY_RULE and SIZE_RULE.
+ * Pin `gpt-image-2` via `defaultModel` to stay on the older line.
+ */
+const DEFAULT_MODEL = "gpt-image-2.5-flare";
+/**
+ * The size contract, shared by create and edit so the two cannot drift apart.
+ *
+ * All four constraints bind together: the total-pixel floor is the one that
+ * surprises, because 512x512 satisfies every other rule and still 400s.
+ */
+const SIZE_RULE = "gpt-image-2 and gpt-image-2.5-* take any WIDTHxHEIGHT with both sides multiples of 16, aspect between 1:3 and 3:1, " +
+    "no edge over 3840, and a total between 655,360 and 8,294,400 pixels — so 512x512 is too small and 1536x864 is fine; " +
+    "above 2560x1440 is experimental. gpt-image-1* and dall-e-* take 1024x1024 | 1536x1024 | 1024x1536.";
+/** Quality tiers, likewise shared. `auto` is what the 2.5 models pick by default. */
+const QUALITY_RULE = "low | medium | high | auto, plus xhigh | max on gpt-image-2.5-*";
 /**
  * Model precedence, shared by create and edit: the call wins, then the
  * connection's `defaultModel` (or OPENAI_IMAGE_MODEL), then the newest
@@ -41,7 +60,7 @@ export default function openai(rl) {
         defaultModel: {
             type: "string",
             required: false,
-            description: "Default image model when a call omits `model` — e.g. gpt-image-1 to pin the older line. Defaults to gpt-image-2.",
+            description: "Default image model when a call omits `model` — e.g. gpt-image-2 to pin the older line. Defaults to gpt-image-2.5-flare.",
             env: "OPENAI_IMAGE_MODEL",
         },
     });
@@ -62,17 +81,17 @@ export default function openai(rl) {
             model: {
                 type: "string",
                 required: false,
-                description: "gpt-image-2 | gpt-image-1 | gpt-image-1-mini | dall-e-3 | dall-e-2. Omit to use the connection default.",
+                description: "gpt-image-2.5-flare | gpt-image-2.5-sunburst | gpt-image-2 | gpt-image-1 | gpt-image-1-mini | dall-e-3 | dall-e-2. Omit to use the connection default.",
             },
             size: {
                 type: "string",
                 required: false,
-                description: "WxH (default: 1024x1024). Allowed sizes vary by model.",
+                description: `WxH (default: 1024x1024) or auto. ${SIZE_RULE}`,
             },
             quality: {
                 type: "string",
                 required: false,
-                description: "low | medium | high (gpt-image) or standard | hd (dall-e-3)",
+                description: `${QUALITY_RULE}; standard | hd (dall-e-3)`,
             },
             style: {
                 type: "string",
@@ -164,17 +183,17 @@ export default function openai(rl) {
             model: {
                 type: "string",
                 required: false,
-                description: "gpt-image-2 | gpt-image-1 | gpt-image-1-mini. Omit to use the connection default.",
+                description: "gpt-image-2.5-flare | gpt-image-2.5-sunburst | gpt-image-2 | gpt-image-1 | gpt-image-1-mini. Omit to use the connection default.",
             },
             size: {
                 type: "string",
                 required: false,
-                description: "WxH output size. Omit to let the API match the input.",
+                description: `WxH output size. Omit to let the API match the input. ${SIZE_RULE}`,
             },
             quality: {
                 type: "string",
                 required: false,
-                description: "low | medium | high",
+                description: QUALITY_RULE,
             },
             n: {
                 type: "number",

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

@@ -0,0 +1,172 @@
+/**
+ * The offline half of the plugin's progressive disclosure: everything an
+ * agent should know before writing questions, without a network call and
+ * without pasting the whole of docs.typesafe.ai into every description.
+ *
+ * `typesafe.guide` serves these topics. Condensed from docs.typesafe.ai
+ * (concepts, confidence, patterns, cookbooks) and the jev-1.13 jaggedness
+ * page, reviewed 2026-09-16.
+ */
+export const GUIDE_TOPICS = [
+    "design",
+    "confidence",
+    "jaggedness",
+    "patterns",
+    "cookbooks",
+    "limits",
+    "sources",
+];
+export const GUIDE = {
+    design: {
+        model: "Jev is a System One model: it evaluates typed questions against a state and returns typed answers with calibrated " +
+            "probabilities. It does not generate text, cannot produce a type error, and cannot invent an option you did not declare. " +
+            "Typed output guarantees the interface, not the truth: calibration is a property of groups of predictions, not of " +
+            "any single answer, so validate performance in your own domain.",
+        shape: "Code stays in control of execution. The model supplies the fuzzy judgment; every branch, threshold, arithmetic step, " +
+            "and side effect belongs to your code. Think of a question as a learned semantic branch instruction.",
+        rules: [
+            "One question, one judgment. Split independently useful dimensions — but not a relationship you are asking about, and atomic does not mean trivial: a bounded action selection is one judgment.",
+            "Write literally. The model answers the words in the instruction, not the intent behind them. Name nested state by backticked path.",
+            "Send the smallest state that answers the question. Unrelated detail is a distractor and costs accuracy.",
+            "Batch every question about a state into one call, including speculative ones, each with its premise stated. Extra questions are near-free in latency, not in tokens.",
+            "Sequence a second call only when an answer decides what evidence to fetch, what state to build, or what the next options are.",
+            "Keep questions and thresholds together in one module. They are the part humans need to review.",
+            "Prefer a closed set the model chooses from over asking it to produce a value. For extraction, find candidates with regex or a generative model, then have Jev pick the right one — and check candidate coverage, because it cannot choose a value you omitted.",
+        ],
+        choosing: {
+            choice: "Pick one of a declared set. Routing, classification, ranking a candidate against options, function selection.",
+            score: "Rate against an ordered rubric. Severity, frustration, relevance, quality. Levels can be the actions you will take.",
+            noul: "One yes/no proposition. Guardrail checks, relevance filters, presence tests. Cheapest way to fan out over a list.",
+        },
+    },
+    confidence: {
+        definition: "confidence is a single number from 0 to 1 derived from the answer's own probability distribution: concentrated means " +
+            "certain, flat means uncertain. Choice and Score carry it; Noul does not, because its noul value is already the probability.",
+        ownMeasure: "The full probabilities map is always returned. If TypeSafe's confidence statistic does not fit your decision, compute " +
+            "your own from the distribution — margin between top two, entropy, mass above a level.",
+        bands: {
+            high: "Act automatically.",
+            medium: "Proceed with caution — confirm with the user, flag for review, or gather more state.",
+            low: "Consider not acting: route to a human, ask for clarification, or fall back to another system.",
+        },
+        bandsAreNotALaw: "Confidence summarizes how concentrated the distribution is. It is not a measure of workflow correctness and not " +
+            "permission to act. Several genuinely acceptable options spread probability too, so low confidence on a harmless " +
+            "preference is not a problem to solve, and uncertainty on a branch you never read can be ignored outright.",
+        noulIsNotIntensity: "A Noul near 0.5 means yes and no are about equally likely. It is not a medium-intensity reading — reach for a " +
+            "Score when you want degree.",
+        thresholds: "A threshold is not one number for the whole system. Gate each action at the level its blast radius deserves: a " +
+            "read-only screen can act on a mediocre confidence, an irreversible transfer should not. Start conservative, measure " +
+            "against your own labelled data and consequences, and move the numbers deliberately.",
+        antipattern: "If all you want is the best option, take the highest-probability choice — no threshold needed. Reach for confidence " +
+            "when 'should I act at all' is a real question, and for probabilities when you have a specific statistical algorithm in mind.",
+    },
+    jaggedness: {
+        applies: "jev-1.13, reviewed 2026-09-16.",
+        failureModes: [
+            {
+                mode: "Literal reading",
+                detail: "Scoping words, negations, and implied conditions are taken at face value. When you look at a wrong answer and " +
+                    "catch yourself explaining what you really meant, that explanation is the missing half of the instruction.",
+                instead: "Write the exact condition; put boundary cases in the option or level descriptions.",
+            },
+            {
+                mode: "Math and numbers",
+                detail: "Not a calculator. Counting is unreliable and the error grows with the size of the thing counted. Numeric " +
+                    "representations (hex colors, RGB triples, assembly) underperform their semantic equivalents.",
+                instead: "Keep arithmetic in code. To count items matching a criterion, ask one Noul per item in a single batched call and sum the results yourself.",
+            },
+            {
+                mode: "Date and time comparison",
+                detail: "Dates are read as text, not as ordered quantities. Ordering, distance, and window membership are all unreliable, worse with mixed formats.",
+                instead: "Extract the parts as Choices over closed sets (twelve months, thirty-one days) with an explicit 'not stated' option, then assemble and compare in code.",
+            },
+            {
+                mode: "Indirection",
+                detail: "Double negatives and properties-of-properties cost accuracy with every hop.",
+                instead: "Ask directly, and name the relevant part of the state.",
+            },
+            {
+                mode: "Large state full of irrelevant detail",
+                detail: "Accuracy falls as unrelated content grows, and attribution of a wrong answer gets harder.",
+                instead: "Retrieve and filter in code first. Where you cannot, use a Noul as a relevance filter before the real questions.",
+            },
+            {
+                mode: "Adversarial content",
+                detail: "State is treated as data, not as hostile. Injected instructions, misleading framing, and text that argues for its " +
+                    "own classification can move the answer. This limits how much a single Jev call can be trusted as a standalone guardrail.",
+                instead: "Be explicit in the criteria, test edge cases before deploying, and keep a defence in depth around it.",
+            },
+            {
+                mode: "Contradictory instructions and criteria",
+                detail: "Criteria that pull against the instruction confuse the model — a Noul whose true means 'no' is the classic case.",
+                instead: "Treat criteria as an extension of the instruction, phrased so an average reader would agree they match.",
+            },
+            {
+                mode: "Generation",
+                detail: "Not trained to generate. Chaining choices to spell out text is slow and poor.",
+                instead: "Bound the answer space and let Jev pick; use a generative model when you genuinely need new text.",
+            },
+        ],
+    },
+    patterns: {
+        speculativeFanOut: "Ask everything you might need about a state in one call, including questions you may never read, stating each " +
+            "speculative premise explicitly in its own instructions since the questions cannot see one another. Extra questions " +
+            "barely move latency, and a branch that turns out to matter already has its answer.",
+        confidenceGatedRouting: "Two axes: the answer says what, the confidence says whether to act. Automate the confident cases, review the rest. " +
+            "This is the pattern that makes the model's uncertainty a feature rather than a liability.",
+        compositeScoring: "Break a complex judgment into atomic scores and combine them with weights your code owns. The weights stay reviewable " +
+            "and tunable without retraining or reprompting anything.",
+        intentRouting: "Classify the incoming request, then send it to the cheapest handler that can serve it: deterministic code, a specialist " +
+            "LLM, or a human. The classification costs a fraction of a cent and roughly 300ms.",
+        cascade: "Screen with Jev, escalate only what survives. A cheap first pass in front of an expensive model recovers most of the " +
+            "quality at a fraction of the spend.",
+    },
+    cookbooks: {
+        note: "Worked examples at https://docs.typesafe.ai/cookbooks — the ones closest to agent infrastructure:",
+        items: [
+            "rerank_typesafe — one question per query/candidate pair re-ranks a BM25 shortlist; top-1 accuracy 5% to 18%, top-10 38% to 62%.",
+            "skill_suggestion — picks at most one skill from a 182-skill catalog: one call ranks them all and asks whether a skill is needed, a second reads the top three and may reject all.",
+            "classifying_rag_passages — score every retrieved passage, then decide in code what reaches the answering model; drops passages carrying prompt injection.",
+            "llm_guardrails — screen messages in and out with hazard questions plus a severity score, then threshold to pass, review, block, or route.",
+            "function_calling — map function names and closed-set arguments to confidence-aware questions.",
+            "citation_check — decide whether a quote's context supports the claim, with confidence flagging for review.",
+            "semantic_find — score hundreds of line ids in one request, plus a Noul for 'is the answer here at all'.",
+            "parallel_questions — 13 questions in one call: 12.2x cheaper and 10.0x faster than 13 calls, same answers.",
+        ],
+    },
+    limits: {
+        context: [
+            "~64k tokens for state plus all questions together.",
+            "~32k tokens for state plus the single longest question.",
+            "Packing many questions into one call is the efficient use of that budget.",
+        ],
+        rateLimits: "250,000 tokens/sec and 1,200 requests/minute, adjusted dynamically by TypeSafe without notice. This plugin retries " +
+            "429 and any 5xx (including the undocumented 503 model_unavailable) with backoff, honouring retry-after; " +
+            "connection field maxRetries, default 2.",
+        price: "$0.042 per million input tokens. Output tokens are free. Typical call: 70-500ms.",
+        modality: "Text only — strings, JSON objects, arrays of text. No images, audio, or video.",
+        accuracy: "On TypeSafe's own four-workflow benchmark Jev lands near mid-tier LLM accuracy (~68%) while being one to two orders " +
+            "of magnitude cheaper and faster. Those numbers are self-reported and unreproduced; measure on your own data before " +
+            "trusting a threshold.",
+    },
+    sources: {
+        trust: "The live docs are the source of truth. Everything above is a condensed snapshot taken 2026-09-16 against jev-1.13: " +
+            "good for orientation and for writing a first question, not authoritative. Read the docs for anything " +
+            "version-dependent, any model past jev-1.13, or a cookbook you want in full rather than in one line.",
+        docsIndex: "https://docs.typesafe.ai/llms.txt lists every page and cookbook. Read targeted pages from it rather than the site.",
+        markdown: "Any docs page serves Markdown by appending .md to its path, e.g. https://docs.typesafe.ai/concepts/state.md. " +
+            "Resolve relative links against https://docs.typesafe.ai.",
+        officialSkill: "TypeSafe publishes an agent skill covering the same ground in more depth: " +
+            "https://raw.githubusercontent.com/typesafe-ai/skills/main/skills/typesafe-ai/SKILL.md " +
+            "(repo https://github.com/typesafe-ai/skills). This guide is condensed from it and from the docs. Read the skill " +
+            "when you are designing a whole workflow; this guide is enough for writing one good question.",
+        startHere: {
+            "programming model": "https://docs.typesafe.ai/concepts/how-to-build-with-system-one.md",
+            "what to build": "https://docs.typesafe.ai/concepts/use-case-map.md",
+            "state and questions": "https://docs.typesafe.ai/concepts/state.md, https://docs.typesafe.ai/primitives.md",
+            uncertainty: "https://docs.typesafe.ai/confidence.md",
+            "wire format": "https://docs.typesafe.ai/api.md",
+            "current failure modes": "https://docs.typesafe.ai/model-jaggedness/jev-1.13.md",
+        },
+    },
+};

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

@@ -0,0 +1,169 @@
+import * as t from "typebox";
+import { GUIDE, GUIDE_TOPICS } from "./guide.js";
+import { choiceRubric, noulRubric, questionsSchema, scoreRubric, toWireQuestion, toWireQuestions, } from "./questions.js";
+import { DEFAULT_BASE, DEFAULT_MODEL, evaluate, modelSchema, request, resolveModel, STRICT, stateSchema, } from "./shared.js";
+/**
+ * TypeSafe AI's Jev — a System One model — as runline actions.
+ *
+ * Jev does not generate text. You send a state plus typed questions and it
+ * returns values your code branches on, with calibrated probabilities and
+ * confidence, in 70-500ms for $0.042 per million input tokens (output free).
+ * Every question in a request is evaluated in parallel against the same
+ * state, so batching is nearly free.
+ *
+ * Auth: a TypeSafe API key (bearer), env TYPESAFE_API_KEY.
+ *
+ *   await typesafe.noul({ state: ticket, instructions: "Does this request a refund?" })
+ *   await typesafe.evaluate({ state: ticket, questions: [...] })
+ *   await typesafe.guide({ topic: "jaggedness" })
+ */
+const SUMMARY = "Jev (TypeSafe System One) returns typed decisions with calibrated probabilities instead of text — ~70-500ms and a " +
+    "fraction of a cent, versus a full LLM turn.";
+const USE_WHEN = "Reach for it whenever a bounded decision is currently costing an LLM turn: intent routing, classification, ranking " +
+    "without embeddings, relevance filtering, screening before a tool call. Not for generation, arithmetic, counting, or " +
+    "date comparison — read typesafe.guide first if you have not.";
+export default function typesafe(rl) {
+    rl.setName("typesafe");
+    rl.setVersion("0.1.0");
+    rl.setConnectionSchema(t.Object({
+        apiKey: t.String({
+            env: "TYPESAFE_API_KEY",
+            description: "TypeSafe API key, sent as a bearer token. Mint one at https://console.typesafe.ai/settings/keys. Store only in secrets.",
+        }),
+        model: t.Optional(t.String({
+            env: "TYPESAFE_MODEL",
+            default: DEFAULT_MODEL,
+            description: "Default model for every call. 'jev-latest' (stable) or 'jev-preview', or pin a version such as 'jev-1.13.0' when thresholds are tuned against it.",
+        })),
+        baseUrl: t.Optional(t.String({
+            env: "TYPESAFE_API_BASE",
+            default: DEFAULT_BASE,
+            description: "TypeSafe API base URL.",
+        })),
+        maxRetries: t.Optional(t.Integer({
+            minimum: 0,
+            maximum: 5,
+            default: 2,
+            description: "Retries with exponential backoff on 429 and on any 5xx, honouring retry-after. Every action here is a pure read, so a retry can never double an effect. A 4xx other than 429 is your bug and never retries.",
+        })),
+    }));
+    /* ---------------------------------------------------------------- */
+    /* The primary call                                                 */
+    /* ---------------------------------------------------------------- */
+    rl.registerAction("evaluate", {
+        access: "read",
+        description: `Ask many typed questions about one state in a single parallel call. ${SUMMARY} ` +
+            "Returns one answer per question id, each carrying its full probability distribution and confidence — nothing is " +
+            `flattened to a verdict, so your code decides what to act on and what to escalate. ${USE_WHEN}`,
+        inputSchema: t.Object({
+            state: stateSchema,
+            questions: questionsSchema,
+            model: t.Optional(modelSchema),
+        }, STRICT),
+        async execute(input, ctx) {
+            const { state, questions, model } = input;
+            const response = await evaluate(ctx, state, toWireQuestions(questions), resolveModel(ctx, model));
+            return {
+                model: response.model,
+                answers: response.answers,
+                usage: response.usage,
+            };
+        },
+    });
+    /* ---------------------------------------------------------------- */
+    /* Single-question shorthands                                       */
+    /* ---------------------------------------------------------------- */
+    const single = (name, description, rubric) => {
+        rl.registerAction(name, {
+            access: "read",
+            description,
+            inputSchema: t.Object({
+                state: stateSchema,
+                ...rubric,
+                model: t.Optional(modelSchema),
+            }, STRICT),
+            async execute(input, ctx) {
+                const { state, model, ...rest } = input;
+                // The rubric fields are this primitive's own, validated against the
+                // schema before execute runs; the id names the lone question.
+                const question = toWireQuestion({
+                    ...rest,
+                    id: name,
+                    type: name,
+                });
+                const response = await evaluate(ctx, state, { [name]: question }, resolveModel(ctx, model));
+                const answer = response.answers[name];
+                if (!answer)
+                    throw new Error(`TypeSafe returned no ${name} answer.`);
+                return { ...answer, model: response.model, usage: response.usage };
+            },
+        });
+    };
+    single("choice", "Pick one option from a declared set, with the probability of every option and a confidence score. " +
+        `${SUMMARY} Shorthand for a one-question evaluate — when you need more than one judgment about the same state, ` +
+        "use typesafe.evaluate instead: questions run in parallel, so a second question costs tokens but barely any " +
+        "latency, while a second call costs a whole round trip.", choiceRubric);
+    single("score", "Rate the state against an ordered rubric, returning a probability-weighted score, the per-level distribution, and confidence. " +
+        `${SUMMARY} Shorthand for a one-question evaluate; batch through typesafe.evaluate when you have several judgments to make.`, scoreRubric);
+    single("noul", "Evaluate one yes/no statement, returning the probability it is true (0 to 1). The cheapest primitive: a relevance " +
+        `filter, a guardrail check, a presence test. ${SUMMARY} Shorthand for a one-question evaluate; to test a list of ` +
+        "items, ask one noul per item through typesafe.evaluate in a single call and combine the results in code.", noulRubric);
+    /* ---------------------------------------------------------------- */
+    /* Escape hatch and metadata                                        */
+    /* ---------------------------------------------------------------- */
+    rl.registerAction("raw", {
+        access: "read",
+        description: "POST a literal TypeSafe request body to /v1/systemone, unmodified. Reach for it only when the typed actions cannot " +
+            "express the shape: structured criteria, or a question type added to the API after this plugin. Structured " +
+            "instructions need no escape hatch — typesafe.evaluate accepts them. Prefer evaluate: it validates before you spend.",
+        inputSchema: t.Object({
+            state: stateSchema,
+            questions: t.Record(t.String(), t.Unknown(), {
+                minProperties: 1,
+                description: "The wire-format questions map: your question id -> { type: 'choice' | 'score' | 'noul', instructions, criteria }. " +
+                    "criteria is an option->description map for choice, an ordered array of level descriptions for score, and " +
+                    "{ true, false } for noul. Answers return under the same ids.",
+            }),
+            model: t.Optional(modelSchema),
+        }, STRICT),
+        async execute(input, ctx) {
+            const { state, questions, model } = input;
+            return evaluate(ctx, state, questions, resolveModel(ctx, model));
+        },
+    });
+    rl.registerAction("model.list", {
+        access: "read",
+        description: "List the models and aliases this account may send in `model`, each with a description and release date. " +
+            "Versioned ids such as 'jev-1.13.0' are accepted whether or not they appear here.",
+        inputSchema: t.Object({}, STRICT),
+        async execute(_input, ctx) {
+            const body = await request(ctx, "/v1/models");
+            if (!Array.isArray(body.models)) {
+                throw new Error("TypeSafe returned a response with no models list.");
+            }
+            return body.models;
+        },
+    });
+    rl.registerAction("guide", {
+        access: "read",
+        description: "How to write questions that work, offline and free — no API key or network call. Read this before your first " +
+            "evaluate: it covers question design, the confidence bands and how to set thresholds by blast radius, the eight " +
+            "known failure modes of jev-1.13 (literal reading, counting, dates, prompt injection...), the architectural " +
+            "patterns, and the hard limits. Most bad results are a question-design problem this answers. It is a condensed " +
+            "snapshot of TypeSafe's docs and official agent skill, taken 2026-09-16 against jev-1.13 — topic 'sources' carries " +
+            "the links to both, and the live docs win wherever they disagree with this.",
+        inputSchema: t.Object({
+            topic: t.Optional(t.Union(GUIDE_TOPICS.map((topic) => t.Literal(topic)), {
+                description: "design (atomic questions, which primitive to use) | confidence (bands, thresholds by risk) | " +
+                    "jaggedness (what jev-1.13 gets wrong and what to do instead) | patterns (fan-out, confidence-gated " +
+                    "routing, composite scoring, intent routing, cascade) | cookbooks (worked examples) | limits (context, " +
+                    "rate, price, accuracy) | sources (live docs index, the .md convention, TypeSafe's official agent skill, " +
+                    "and how far to trust this snapshot). Omit for all of it — it is small.",
+            })),
+        }, STRICT),
+        async execute(input) {
+            const { topic } = (input ?? {});
+            return topic ? { topic, ...GUIDE[topic] } : GUIDE;
+        },
+    });
+}