converse-mcp-server 4.0.0 → 4.1.1

package/.env.example

@@ -51,6 +51,11 @@ OPENROUTER_API_KEY=your_openrouter_api_key_here
 # OPENROUTER_REFERER=https://github.com/FallDownTheSystem/converse
 # OPENROUTER_TITLE=Converse
 
+# Get your TypeSafe API key from: https://typesafe.ai
+# Enables the decide tool's native host for Jev decision models. Without it,
+# decide reaches Jev through OPENROUTER_API_KEY instead.
+TYPESAFE_API_KEY=your_typesafe_api_key_here
+
 # ============================================
 # Codex Configuration (Optional)
 # ============================================

package/README.md

@@ -182,6 +182,25 @@ Cancel running asynchronous operations when needed.
 }
 ```
 
+### 4. Decide Tool
+
+Ask a System One decision model (TypeSafe's Jev) typed questions about a state and get calibrated answers instead of text: a yes probability (`noul`), a chosen option with per-option probabilities (`choice`), or a rubric position with per-level probabilities (`score`). Batch many questions into one call; they are judged in parallel against the same state. Needs `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY` (TypeSafe first, falling back to OpenRouter).
+
+```javascript
+{
+  "state": { "message": "I was charged twice for order A-104. Please fix this ASAP." },
+  "questions": {
+    "urgent": { "type": "noul", "instructions": "Does the message convey urgency?" },
+    "team": { "type": "choice", "instructions": "Which team should handle this?",
+              "criteria": { "billing": "Payments, refunds", "technical": "Bugs, outages" } },
+    "frustration": { "type": "score", "instructions": "How frustrated is the customer?",
+                     "criteria": ["Calm", "Frustrated", "Very angry"] }
+  }
+}
+```
+
+See [docs/API.md](docs/API.md#decide-tool) for the full schema, model routing, and usage guidance.
+
 ## 🤖 AI Summarization Feature
 
 When enabled, the server automatically generates intelligent titles and summaries for better context understanding:

package/docs/API.md

@@ -366,6 +366,110 @@ The response renders a human-readable status (start time, elapsed time, turn/mod
 
 Only jobs in a `queued` or `running` state can be cancelled; already-completed, failed, or cancelled jobs return a non-cancellable status.
 
+## Decide Tool
+
+**Description**: Ask a System One decision model (TypeSafe's Jev family) typed questions about a state. Decision models return calibrated probabilities, never text, so they have their own tool and their own providers: `chat` routing never reaches them, and `decide` never reaches a chat model.
+
+### Request Schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "state": { "anyOf": [{ "type": "string" }, { "type": "object" }, { "type": "array" }] },
+    "questions": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "type": { "type": "string", "enum": ["noul", "choice", "score"] },
+          "instructions": { "anyOf": [{ "type": "string" }, { "type": "object" }, { "type": "array" }] },
+          "criteria": { "anyOf": [{ "type": "object" }, { "type": "array" }] }
+        },
+        "required": ["type", "instructions"]
+      }
+    },
+    "model": { "type": "string", "description": "Default: \"auto\"" },
+    "files": { "type": "array", "items": { "type": "string" } }
+  },
+  "required": ["questions"],
+  "additionalProperties": false
+}
+```
+
+- **`state`**: the material to judge. An object with descriptively named fields works best; use an array for sequences such as chat messages. Optional when `files` is given.
+- **`questions`**: named questions, each judged in parallel and in isolation against the same state. The name is your own label and becomes the answer key. Batching many questions into one call adds almost no latency or cost.
+- **`files`**: text files added to the state as `{ "files": { "<path>": "<content>" } }`. When `state` is also given, it moves to `input`. Line ranges (`file.txt{10:50}`) are supported; images are rejected.
+
+| Type | `criteria` | Answer |
+|---|---|---|
+| `noul` | Optional `{ "true": "...", "false": "..." }` | `noul`: probability 0..1 of yes |
+| `choice` | Required `{ "<option>": "description" \| null }`, 2–255 options | `choice`, per-option `probabilities`, `confidence` |
+| `score` | Required ordered array of levels, lowest first, 2–10 levels | `score` (probability-weighted level position), `legend`, per-level `probabilities`, `confidence` |
+
+`instructions` and criteria descriptions may be objects or arrays that bundle reference data with the question; refer to their fields by `` `name` `` in the text. Questions are validated before any request is sent.
+
+### Models and Providers
+
+| Provider | Key | Models |
+|---|---|---|
+| `typesafe` (native, `https://api.typesafe.ai/v1/systemone`) | `TYPESAFE_API_KEY` | `jev-latest`, `jev-1.13.0` (alias `jev-1.13`), `jev-preview`, any versioned `jev-X.Y.Z` |
+| `openrouter` (`https://openrouter.ai/api/v1/systemone`) | `OPENROUTER_API_KEY` | `~typesafe/jev-latest` (alias `jev-latest`), `typesafe/jev-1.13` (aliases `jev-1.13`, `jev-1.13.0`), any `vendor/model` slug |
+
+- `auto` (default): TypeSafe's default model, falling back to OpenRouter's.
+- A bare name such as `jev-1.13` goes to every configured provider that serves it, native first, and each provider receives its own model ID. OpenRouter does not serve `jev-preview` or patch-level IDs other than those listed above.
+- `typesafe:jev-1.13.0` or `openrouter:~typesafe/jev-latest` pins one provider.
+
+Each provider call retries timeouts, 408, 429 and 5xx with backoff, honoring `Retry-After`. Auth failures, exhausted retries and malformed responses fall back to the next provider. A 400/422 request fault stops immediately, because every host would reject it the same way.
+
+### Example Usage
+
+```json
+{
+  "state": { "message": "I was charged twice for order A-104. Please fix this ASAP." },
+  "questions": {
+    "urgent": { "type": "noul", "instructions": "Does the message convey urgency?" },
+    "team": {
+      "type": "choice",
+      "instructions": "Which team should handle this?",
+      "criteria": { "billing": "Payments, invoicing, refunds", "technical": "Bugs, outages", "sales": null }
+    },
+    "frustration": {
+      "type": "score",
+      "instructions": "How frustrated is the customer?",
+      "criteria": ["Calm", "Frustrated", "Very angry"]
+    }
+  }
+}
+```
+
+### Response Format
+
+A one-line summary per answer (options at 0.00 omitted), followed by the answers with full distributions, in the same JSON shape whichever provider served them:
+
+````
+Decision · typesafe/jev-1.13-20260917 via OpenRouter · 394 input tokens · $0.000017
+- urgent (noul): 0.97
+- team (choice): billing · confidence 1.00 · billing 1.00
+- frustration (score): 1.24 on 0–2 · confidence 0.64 · 1 Frustrated 0.76, 2 Very angry 0.24
+
+```json
+{
+  "model": "typesafe/jev-1.13-20260917",
+  "provider": "openrouter",
+  "answers": { "urgent": { "type": "noul", "noul": 0.97 }, "...": {} },
+  "usage": { "input_tokens": 394, "output_tokens": 70, "cost": 0.000016548 },
+  "id": "gen-dec-..."
+}
+```
+````
+
+`usage.cost` is reported by OpenRouter only (`null` from TypeSafe). A fallback is noted under the summary line.
+
+### Usage Guidance
+
+Jev reads questions literally and is weak at counting, arithmetic, date comparison, and multi-hop reasoning; do those in code and ask narrow, atomic questions. Split compound judgments into separate questions and combine them in code. Treat low `confidence` as a signal to escalate to a generative model or a human. Limits: text only, about 64k tokens per request and 32k for the state plus the longest single question.
+
 ## Supported Models
 
 Provide models as plain name strings in the `models` array. Each entry is `auto`, a provider name (its default model), `provider:model` (that model on that provider only), or a bare model ID/alias (the first set-up provider that offers it). Names that match no provider's list are rejected with suggestions. See [Model Selection](#model-selection) for the full rules.
@@ -714,6 +818,7 @@ ANTHROPIC_API_KEY=sk-ant-...
 MISTRAL_API_KEY=...
 DEEPSEEK_API_KEY=...
 OPENROUTER_API_KEY=sk-or-...
+TYPESAFE_API_KEY=...            # decide tool only
 ```
 
 **MCP client configuration:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "converse-mcp-server",
-  "version": "4.0.0",
+  "version": "4.1.1",
   "description": "Converse MCP Server - Converse with other LLMs with chat and consensus tools",
   "type": "module",
   "main": "src/index.js",

package/src/config.js

@@ -214,6 +214,12 @@ const CONFIG_SCHEMA = {
       secret: true,
       description: 'OpenRouter API key',
     },
+    TYPESAFE_API_KEY: {
+      type: 'string',
+      required: false,
+      secret: true,
+      description: 'TypeSafe API key (System One decision models for the decide tool)',
+    },
   },
 
   // Provider-specific configuration
@@ -707,7 +713,7 @@ export async function loadConfig() {
 
     if (availableKeys.length === 0 && !hasVertexAI && !hasSdkProvider) {
       errors.push(
-        'At least one API key must be configured: OPENAI_API_KEY, XAI_API_KEY, GOOGLE_API_KEY, GEMINI_API_KEY, ANTHROPIC_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY, or OPENROUTER_API_KEY. Alternatively, configure Google Vertex AI or use an SDK-based provider (codex, claude, copilot) or the Antigravity CLI (gemini-cli).',
+        'At least one API key must be configured: OPENAI_API_KEY, XAI_API_KEY, GOOGLE_API_KEY, GEMINI_API_KEY, ANTHROPIC_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY, OPENROUTER_API_KEY, or TYPESAFE_API_KEY. Alternatively, configure Google Vertex AI or use an SDK-based provider (codex, claude, copilot) or the Antigravity CLI (gemini-cli).',
       );
     }
 

package/src/decisionProviders/index.js

@@ -0,0 +1,174 @@
+/**
+ * Decision Providers
+ *
+ * Hosts of System One decision models (TypeSafe's Jev family). These are kept
+ * apart from the chat provider registry on purpose: a decision model takes a
+ * state plus typed questions and returns probabilities, never text, so it must
+ * never be reachable from `chat` routing ("auto", bare names, failover), and
+ * the `decide` tool must never reach a chat model.
+ *
+ * Spec grammar mirrors chat routing:
+ * - `auto` (or empty) — every configured provider's default, in priority order
+ * - `provider` / `provider:` — that provider's default model
+ * - `provider:model` — that provider only
+ * - `model` — every provider that serves the name, in priority order; the
+ *   first is used and the rest are failover candidates
+ */
+
+import { getCustomHeaders as getOpenRouterAttributionHeaders } from '../providers/openrouter.js';
+
+/**
+ * Model catalogs map each provider's own model ID to the names that route to
+ * it. OpenRouter only knows `~typesafe/jev-latest` and `typesafe/jev-1.13`
+ * (it rejects `jev-1.13.0` and `jev-preview`), so native IDs are translated
+ * per provider rather than by a blanket prefix rewrite.
+ */
+export const DECISION_PROVIDERS = {
+  typesafe: {
+    name: 'typesafe',
+    label: 'TypeSafe',
+    baseURL: 'https://api.typesafe.ai',
+    apiKeyEnv: 'TYPESAFE_API_KEY',
+    defaultModel: 'jev-latest',
+    models: {
+      'jev-latest': ['jev', '~typesafe/jev-latest'],
+      'jev-1.13.0': ['jev-1.13', 'typesafe/jev-1.13'],
+      'jev-preview': [],
+    },
+    // TypeSafe accepts every published versioned ID, listed or not.
+    passthrough: (name) => /^jev-\d+\.\d+(\.\d+)?$/i.test(name),
+    headers: (config) => ({ Authorization: `Bearer ${config.apiKeys.typesafe}` }),
+    isAvailable: (config) => Boolean(config?.apiKeys?.typesafe),
+  },
+  openrouter: {
+    name: 'openrouter',
+    label: 'OpenRouter',
+    baseURL: 'https://openrouter.ai/api',
+    apiKeyEnv: 'OPENROUTER_API_KEY',
+    defaultModel: '~typesafe/jev-latest',
+    models: {
+      '~typesafe/jev-latest': ['jev-latest', 'jev'],
+      'typesafe/jev-1.13': ['jev-1.13', 'jev-1.13.0'],
+    },
+    // Decision models OpenRouter adds later are reachable by full slug.
+    passthrough: (name) => name.includes('/'),
+    headers: (config) => ({
+      Authorization: `Bearer ${config.apiKeys.openrouter}`,
+      ...getOpenRouterAttributionHeaders(config),
+    }),
+    isAvailable: (config) => Boolean(config?.apiKeys?.openrouter),
+  },
+};
+
+/** Failover order: the native host first, then OpenRouter. */
+export const DECISION_PROVIDER_PRIORITY = ['typesafe', 'openrouter'];
+
+/**
+ * Resolve a name against one provider's catalog, then its passthrough rule.
+ * @returns {string|null} The model ID to send to that provider
+ */
+export function findDecisionModel(provider, name) {
+  const wanted = String(name).trim().toLowerCase();
+  if (!wanted) return null;
+  for (const [id, aliases] of Object.entries(provider.models)) {
+    if (id.toLowerCase() === wanted || aliases.some((a) => a.toLowerCase() === wanted)) {
+      return id;
+    }
+  }
+  return provider.passthrough(String(name).trim()) ? String(name).trim() : null;
+}
+
+function setupHint(provider) {
+  return `set ${provider.apiKeyEnv}`;
+}
+
+function knownModels() {
+  const names = new Set();
+  for (const providerName of DECISION_PROVIDER_PRIORITY) {
+    const provider = DECISION_PROVIDERS[providerName];
+    for (const [id, aliases] of Object.entries(provider.models)) {
+      names.add(id);
+      aliases.forEach((a) => names.add(a));
+    }
+  }
+  return [...names];
+}
+
+function ok(candidates) {
+  return { status: 'ok', candidates, error: null };
+}
+
+function fail(status, error) {
+  return { status, candidates: [], error };
+}
+
+/**
+ * Resolve a decision model spec into an ordered candidate list.
+ * @param {string} spec - Model spec (see module grammar)
+ * @param {object} config - Server configuration (for API keys)
+ * @returns {{ status: 'ok'|'unknown'|'unavailable', candidates: Array<{ providerName: string, provider: object, model: string }>, error: string|null }}
+ */
+export function resolveDecisionModel(spec, config) {
+  const raw = String(spec ?? '').trim();
+  const namespaces = DECISION_PROVIDER_PRIORITY.join(', ');
+
+  if (!raw || raw.toLowerCase() === 'auto') {
+    const candidates = DECISION_PROVIDER_PRIORITY
+      .map((name) => DECISION_PROVIDERS[name])
+      .filter((provider) => provider.isAvailable(config))
+      .map((provider) => ({ providerName: provider.name, provider, model: provider.defaultModel }));
+    if (candidates.length === 0) {
+      return fail(
+        'unavailable',
+        `No decision provider is configured: ${DECISION_PROVIDER_PRIORITY.map((n) => `${n} (${setupHint(DECISION_PROVIDERS[n])})`).join('; ')}.`,
+      );
+    }
+    return ok(candidates);
+  }
+
+  const colon = raw.indexOf(':');
+  const hasNamespace = colon > 0 && !raw.slice(0, colon).includes('/');
+  const namespace = hasNamespace ? raw.slice(0, colon).toLowerCase() : raw.toLowerCase();
+
+  if (hasNamespace || DECISION_PROVIDERS[namespace]) {
+    const provider = DECISION_PROVIDERS[namespace];
+    if (!provider) {
+      return fail('unknown', `Unknown decision provider "${raw.slice(0, colon)}". Providers: ${namespaces}.`);
+    }
+    const name = hasNamespace ? raw.slice(colon + 1).trim() : '';
+    const model = name ? findDecisionModel(provider, name) : provider.defaultModel;
+    if (!model) {
+      return fail(
+        'unknown',
+        `${provider.label} does not serve "${name}". Models: ${Object.keys(provider.models).join(', ')}.`,
+      );
+    }
+    if (!provider.isAvailable(config)) {
+      return fail('unavailable', `${provider.label} is not configured (${setupHint(provider)}).`);
+    }
+    return ok([{ providerName: provider.name, provider, model }]);
+  }
+
+  const matches = DECISION_PROVIDER_PRIORITY
+    .map((providerName) => {
+      const provider = DECISION_PROVIDERS[providerName];
+      const model = findDecisionModel(provider, raw);
+      return model ? { providerName, provider, model } : null;
+    })
+    .filter(Boolean);
+
+  if (matches.length === 0) {
+    return fail(
+      'unknown',
+      `Unknown decision model "${raw}". Use "auto", a provider (${namespaces}), "provider:model", or one of: ${knownModels().join(', ')}.`,
+    );
+  }
+  const available = matches.filter((m) => m.provider.isAvailable(config));
+  if (available.length === 0) {
+    return fail(
+      'unavailable',
+      `"${raw}" is served by ${matches.map((m) => `${m.providerName} (${setupHint(m.provider)})`).join('; ')}, but none is configured.`,
+    );
+  }
+  return ok(available);
+}

package/src/decisionProviders/systemOne.js

@@ -0,0 +1,199 @@
+/**
+ * System One HTTP client
+ *
+ * One client for every host of the System One decision API. TypeSafe serves it
+ * natively at `/v1/systemone`; OpenRouter serves the same request/response
+ * schema at the same path under its own base URL, so providers differ only in
+ * base URL, key, and headers.
+ *
+ * Plain fetch rather than @typesafe-ai/sdk: the schema is small, the tool
+ * needs its own abort signal and error mapping, and the SDK's model listing
+ * breaks against OpenRouter.
+ */
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_RETRIES = 2;
+const BACKOFF_INITIAL_MS = 500;
+const BACKOFF_MAX_MS = 5_000;
+// A longer server-requested wait is better spent failing over to another host.
+const MAX_RETRY_AFTER_MS = 30_000;
+
+/**
+ * Error from a System One call. `retryable` marks failures worth repeating or
+ * failing over (network, timeout, 408/429/5xx, auth); `terminal` marks request
+ * faults that every host would reject the same way.
+ */
+export class DecisionError extends Error {
+  constructor(message, { status = null, retryable = false, terminal = false, requestId = null, retryAfterMs = null } = {}) {
+    super(message);
+    this.name = 'DecisionError';
+    this.status = status;
+    this.retryable = retryable;
+    this.terminal = terminal;
+    this.requestId = requestId;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+/**
+ * Render a validation issue list (zod-style `[{path, message}]`) as one line
+ * per issue; anything else is returned as-is.
+ */
+function formatIssues(text) {
+  let issues;
+  try {
+    issues = JSON.parse(text);
+  } catch {
+    return text;
+  }
+  if (!Array.isArray(issues) || !issues.every((i) => i && typeof i.message === 'string')) {
+    return text;
+  }
+  return issues
+    .map((i) => (Array.isArray(i.path) && i.path.length ? `${i.path.join('.')}: ${i.message}` : i.message))
+    .join('; ');
+}
+
+/**
+ * Extract a readable message from an error body. OpenRouter wraps errors as
+ * `{ error: { message } }`; TypeSafe answers `{ detail: { error_type, message } }`,
+ * or `{ detail }` as a string or a list of validation issues.
+ */
+export function extractErrorMessage(body, rawText) {
+  if (typeof body?.detail?.message === 'string') {
+    const type = body.detail.error_type ? `${body.detail.error_type}: ` : '';
+    return `${type}${body.detail.message}`;
+  }
+  const nested = body?.error?.message ?? body?.error ?? body?.detail ?? body?.message;
+  if (typeof nested === 'string') {
+    const inner = nested.match(/^HTTP \d+: (\{.*\})$/s);
+    if (inner) {
+      try {
+        return extractErrorMessage(JSON.parse(inner[1]), inner[1]);
+      } catch {
+        return nested;
+      }
+    }
+    return formatIssues(nested);
+  }
+  if (Array.isArray(nested)) {
+    return nested
+      .map((d) => (d?.loc ? `${d.loc.join('.')}: ${d.msg}` : d?.msg || JSON.stringify(d)))
+      .join('; ');
+  }
+  return rawText?.trim() || 'No error details returned';
+}
+
+function parseRetryAfter(headers) {
+  const ms = Number(headers.get('retry-after-ms'));
+  if (Number.isFinite(ms) && ms > 0) return ms;
+  const value = headers.get('retry-after');
+  if (!value) return null;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return seconds * 1000;
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? null : Math.max(0, date - Date.now());
+}
+
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(signal.reason);
+    }
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+async function sendOnce({ url, headers, body, signal, timeoutMs }) {
+  const attemptSignal = signal
+    ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)])
+    : AbortSignal.timeout(timeoutMs);
+
+  let response;
+  try {
+    response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body: JSON.stringify(body),
+      signal: attemptSignal,
+    });
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    const timedOut = error?.name === 'TimeoutError';
+    throw new DecisionError(
+      timedOut ? `Request timed out after ${timeoutMs / 1000}s` : `Connection failed: ${error.message}`,
+      { retryable: true },
+    );
+  }
+
+  const rawText = await response.text();
+  let parsed = null;
+  try {
+    parsed = rawText ? JSON.parse(rawText) : null;
+  } catch {
+    parsed = null;
+  }
+
+  if (!response.ok) {
+    const status = response.status;
+    throw new DecisionError(`HTTP ${status}: ${extractErrorMessage(parsed, rawText)}`, {
+      status,
+      retryable: status === 408 || status === 429 || status >= 500 || status === 401 || status === 403,
+      terminal: status === 400 || status === 422,
+      requestId: response.headers.get('x-typesafe-request-id') || response.headers.get('x-generation-id'),
+      retryAfterMs: parseRetryAfter(response.headers),
+    });
+  }
+
+  if (!parsed || typeof parsed.answers !== 'object' || parsed.answers === null) {
+    throw new DecisionError('Malformed response: missing "answers" object', { status: response.status });
+  }
+  return parsed;
+}
+
+/**
+ * POST a decision request, retrying transient failures (except auth, which
+ * retrying cannot fix) with exponential backoff that honors Retry-After.
+ * @param {object} params
+ * @param {string} params.baseURL - Host base, e.g. https://api.typesafe.ai
+ * @param {object} params.headers - Auth and attribution headers
+ * @param {object} params.body - `{ model, state, questions }`
+ * @param {AbortSignal} [params.signal] - Caller cancellation
+ * @param {number} [params.timeoutMs] - Per-attempt timeout
+ * @param {number} [params.maxRetries] - Retries after the first attempt
+ * @returns {Promise<object>} Parsed response body
+ */
+export async function callSystemOne({
+  baseURL,
+  headers,
+  body,
+  signal,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  maxRetries = DEFAULT_MAX_RETRIES,
+}) {
+  const url = `${baseURL.replace(/\/+$/, '')}/v1/systemone`;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await sendOnce({ url, headers, body, signal, timeoutMs });
+    } catch (error) {
+      const authFailure = error.status === 401 || error.status === 403;
+      if (!(error instanceof DecisionError) || !error.retryable || authFailure || attempt >= maxRetries) {
+        throw error;
+      }
+      if (error.retryAfterMs !== null && error.retryAfterMs > MAX_RETRY_AFTER_MS) {
+        throw error;
+      }
+      const backoff = Math.min(BACKOFF_INITIAL_MS * 2 ** attempt, BACKOFF_MAX_MS);
+      await sleep(error.retryAfterMs ?? backoff, signal);
+    }
+  }
+}

package/src/prompts/helpPrompt.js

@@ -152,6 +152,27 @@ function generateToolExamplesFromSchema(toolName, inputSchema) {
     ].join('\n');
   }
 
+  if (toolName === 'decide') {
+    const decideExample = {
+      state: { message: 'I was charged twice for order A-104. Please fix this ASAP.' },
+      questions: {
+        urgent: { type: 'noul', instructions: 'Does the message convey urgency?' },
+        team: {
+          type: 'choice',
+          instructions: 'Which team should handle this?',
+          criteria: { billing: 'Payments, invoicing, refunds', technical: 'Bugs, outages', sales: null },
+        },
+        frustration: {
+          type: 'score',
+          instructions: 'How frustrated is the customer?',
+          criteria: ['Calm', 'Frustrated', 'Very angry'],
+        },
+      },
+      model: 'auto',
+    };
+    return `\`\`\`json\n${JSON.stringify(decideExample, null, 2)}\n\`\`\``;
+  }
+
   if (toolName === 'check_status' || toolName === 'cancel_job') {
     if (properties.continuation_id)
       example.continuation_id = SAMPLE_VALUES.continuation_id;
@@ -412,8 +433,9 @@ export function generateHelpContent(config = null) {
         prop.default !== undefined
           ? ` (default: ${JSON.stringify(prop.default)})`
           : '';
+      const type = prop.type ?? prop.anyOf?.map((s) => s.type).join(' | ');
       params.push(
-        `- **${name}** (${isRequired ? 'required' : 'optional'}, ${prop.type}): ${prop.description}${defaultValue}`,
+        `- **${name}** (${isRequired ? 'required' : 'optional'}, ${type}): ${prop.description}${defaultValue}`,
       );
     }
 

package/src/providers/openrouter.js

@@ -203,7 +203,7 @@ function validateApiKey(apiKey) {
  * `X-Title`), while still accepting the legacy `openrouterreferer`/
  * `openroutertitle` config-key spellings as input.
  */
-function getCustomHeaders(config) {
+export function getCustomHeaders(config) {
   const headers = {};
 
   const referer =

package/src/tools/decide.js

@@ -0,0 +1,319 @@
+/**
+ * Decide Tool - System One decision models
+ *
+ * Asks a decision model (TypeSafe's Jev family) typed questions about a state
+ * and returns calibrated answers: a probability for yes/no questions, a
+ * probability distribution for choices and rubric scores. Decision models
+ * never generate text, so this is a separate tool rather than a chat mode.
+ */
+
+import { createToolResponse, createToolError } from './index.js';
+import { resolveDecisionModel } from '../decisionProviders/index.js';
+import { callSystemOne } from '../decisionProviders/systemOne.js';
+import { validateAllPaths } from '../utils/fileValidator.js';
+import { createLogger } from '../utils/logger.js';
+
+const logger = createLogger('decide');
+
+const QUESTION_TYPES = ['noul', 'choice', 'score'];
+const QUESTION_FIELDS = ['type', 'instructions', 'criteria'];
+const MAX_CHOICE_OPTIONS = 255;
+const MIN_SCORE_LEVELS = 2;
+const MAX_SCORE_LEVELS = 10;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** Criteria descriptions may be plain text or structured reference data. */
+function isCriterionValue(value) {
+  return (typeof value === 'string' && value.trim() !== '') || isPlainObject(value) || Array.isArray(value);
+}
+
+function validateState(state) {
+  if (typeof state === 'string') {
+    return state.trim() ? null : '"state" must not be empty.';
+  }
+  if (isPlainObject(state) || Array.isArray(state)) return null;
+  return '"state" must be a string, an object, or an array.';
+}
+
+function validateQuestion(key, question) {
+  const at = `questions.${key}`;
+  if (!isPlainObject(question)) return `${at} must be an object with "type" and "instructions".`;
+
+  const unknown = Object.keys(question).filter((f) => !QUESTION_FIELDS.includes(f));
+  if (unknown.length) {
+    return `${at} has unknown field(s): ${unknown.join(', ')}. Allowed: ${QUESTION_FIELDS.join(', ')}.`;
+  }
+  if (!QUESTION_TYPES.includes(question.type)) {
+    return `${at}.type must be one of: ${QUESTION_TYPES.join(', ')}.`;
+  }
+
+  const { instructions, criteria } = question;
+  const hasInstructions =
+    (typeof instructions === 'string' && instructions.trim() !== '') ||
+    (isPlainObject(instructions) && Object.keys(instructions).length > 0) ||
+    (Array.isArray(instructions) && instructions.length > 0);
+  if (!hasInstructions) {
+    return `${at}.instructions must be a non-empty string, object, or array.`;
+  }
+
+  if (question.type === 'noul') {
+    if (criteria === undefined) return null;
+    const keys = isPlainObject(criteria) ? Object.keys(criteria).sort() : null;
+    if (!keys || keys.join(',') !== 'false,true' || !isCriterionValue(criteria.true) || !isCriterionValue(criteria.false)) {
+      return `${at}.criteria for a noul question must be { "true": "...", "false": "..." } with both descriptions.`;
+    }
+    return null;
+  }
+
+  if (question.type === 'choice') {
+    if (!isPlainObject(criteria)) {
+      return `${at}.criteria for a choice question must map option names to descriptions (or null).`;
+    }
+    const options = Object.entries(criteria);
+    if (options.length < 2 || options.length > MAX_CHOICE_OPTIONS) {
+      return `${at}.criteria must have 2 to ${MAX_CHOICE_OPTIONS} options (got ${options.length}).`;
+    }
+    const bad = options.filter(([, v]) => v !== null && !isCriterionValue(v)).map(([k]) => k);
+    if (bad.length) {
+      return `${at}.criteria option(s) ${bad.join(', ')} need a description string, object, array, or null.`;
+    }
+    return null;
+  }
+
+  if (!Array.isArray(criteria)) {
+    return `${at}.criteria for a score question must be an ordered array of level descriptions.`;
+  }
+  if (criteria.length < MIN_SCORE_LEVELS || criteria.length > MAX_SCORE_LEVELS) {
+    return `${at}.criteria must have ${MIN_SCORE_LEVELS} to ${MAX_SCORE_LEVELS} levels (got ${criteria.length}).`;
+  }
+  if (!criteria.every(isCriterionValue)) {
+    return `${at}.criteria levels must each be a non-empty description.`;
+  }
+  return null;
+}
+
+/**
+ * Check questions locally: the API reports schema faults as nested validation
+ * dumps, and a local message is both clearer and free.
+ * @returns {string|null} First problem found
+ */
+export function validateQuestions(questions) {
+  if (!isPlainObject(questions) || Object.keys(questions).length === 0) {
+    return '"questions" must be an object with at least one named question.';
+  }
+  for (const [key, question] of Object.entries(questions)) {
+    if (!key.trim()) return 'Question names must not be empty.';
+    const error = validateQuestion(key, question);
+    if (error) return error;
+  }
+  return null;
+}
+
+/**
+ * Read files into a `{ path: content }` map. Every file must load as text:
+ * a silently missing file would change the state being judged.
+ */
+async function loadFiles(files, contextProcessor, config) {
+  const validation = await validateAllPaths(
+    { files },
+    { clientCwd: config?.server?.client_cwd },
+  );
+  if (!validation.valid) {
+    return { error: validation.errors.join('; ') };
+  }
+
+  const result = await contextProcessor.processUnifiedContext(
+    { files },
+    { enforceSecurityCheck: false, skipSecurityCheck: true, clientCwd: config?.server?.client_cwd },
+  );
+  const problems = [];
+  const contents = {};
+  for (const file of result.files) {
+    if (file.type === 'error') {
+      problems.push(`${file.originalPath}: ${file.error}`);
+    } else if (file.type !== 'text') {
+      problems.push(`${file.originalPath}: decision models accept text only`);
+    } else {
+      contents[file.originalPath] = file.content;
+    }
+  }
+  if (result.errors?.length) problems.push(...result.errors.map((e) => e.message));
+  return problems.length ? { error: problems.join('; ') } : { contents };
+}
+
+function fixed(n) {
+  return typeof n === 'number' ? n.toFixed(2) : String(n);
+}
+
+/**
+ * Options at or rounding to zero are left out of the summary line; the JSON
+ * block still carries the full distribution.
+ */
+function byProbability(probabilities, label = (k) => k) {
+  return Object.entries(probabilities || {})
+    .filter(([, p]) => fixed(p) !== '0.00')
+    .sort(([, a], [, b]) => b - a)
+    .map(([k, p]) => `${label(k)} ${fixed(p)}`)
+    .join(', ');
+}
+
+function summarizeAnswer(key, answer) {
+  const type = answer?.type ?? 'unknown';
+  if (type === 'noul') {
+    return `- ${key} (noul): ${fixed(answer.noul)}`;
+  }
+  if (type === 'choice') {
+    return `- ${key} (choice): ${answer.choice} · confidence ${fixed(answer.confidence)} · ${byProbability(answer.probabilities)}`;
+  }
+  if (type === 'score') {
+    const levels = Object.keys(answer.legend || answer.probabilities || {});
+    const range = levels.length ? ` on 0–${levels.length - 1}` : '';
+    const label = (k) => (answer.legend?.[k] ? `${k} ${answer.legend[k]}` : k);
+    return `- ${key} (score): ${fixed(answer.score)}${range} · confidence ${fixed(answer.confidence)} · ${byProbability(answer.probabilities, label)}`;
+  }
+  return `- ${key} (${type}): ${JSON.stringify(answer)}`;
+}
+
+function formatResult(response, candidate, failures) {
+  const usage = response.usage || {};
+  const header = [
+    `Decision · ${response.model || candidate.model} via ${candidate.provider.label}`,
+    usage.input_tokens !== undefined ? `${usage.input_tokens} input tokens` : null,
+    typeof usage.cost === 'number' ? `$${usage.cost.toFixed(6)}` : null,
+  ].filter(Boolean).join(' · ');
+
+  const lines = [header];
+  for (const failure of failures) {
+    lines.push(`(${failure.provider} failed, fell back: ${failure.message})`);
+  }
+  lines.push(...Object.entries(response.answers).map(([key, answer]) => summarizeAnswer(key, answer)));
+
+  const payload = {
+    model: response.model ?? candidate.model,
+    provider: candidate.providerName,
+    answers: response.answers,
+    usage: {
+      input_tokens: usage.input_tokens ?? null,
+      output_tokens: usage.output_tokens ?? null,
+      cost: typeof usage.cost === 'number' ? usage.cost : null,
+    },
+    ...(response.id ? { id: response.id } : {}),
+  };
+  return `${lines.join('\n')}\n\n\`\`\`json\n${JSON.stringify(payload, null, 2)}\n\`\`\``;
+}
+
+/**
+ * Decide MCP Tool
+ * @param {object} args - Tool arguments
+ * @param {string|object|Array} [args.state] - Material to judge
+ * @param {object} args.questions - Named typed questions
+ * @param {string} [args.model] - Model spec, default "auto"
+ * @param {string[]} [args.files] - Text files added to the state
+ * @param {object} dependencies - Injected dependencies (config, contextProcessor, signal)
+ * @returns {Promise<object>} MCP tool response
+ */
+export async function decideTool(args, dependencies) {
+  const { config, contextProcessor, signal } = dependencies;
+  const { state, questions, model = 'auto', files = [] } = args;
+
+  if (!Array.isArray(files) || !files.every((f) => typeof f === 'string' && f.trim())) {
+    return createToolError('"files" must be an array of file paths.');
+  }
+  if (state === undefined && files.length === 0) {
+    return createToolError('Provide "state", "files", or both: there is nothing to judge.');
+  }
+  const stateError = state === undefined ? null : validateState(state);
+  if (stateError) return createToolError(stateError);
+  const questionError = validateQuestions(questions);
+  if (questionError) return createToolError(questionError);
+
+  const route = resolveDecisionModel(model, config);
+  if (route.status !== 'ok') return createToolError(route.error);
+
+  let finalState = state;
+  if (files.length > 0) {
+    const loaded = await loadFiles(files, contextProcessor, config);
+    if (loaded.error) return createToolError(`Could not load files: ${loaded.error}`);
+    finalState = state === undefined ? { files: loaded.contents } : { input: state, files: loaded.contents };
+  }
+
+  const failures = [];
+  for (const candidate of route.candidates) {
+    try {
+      const response = await callSystemOne({
+        baseURL: candidate.provider.baseURL,
+        headers: candidate.provider.headers(config),
+        body: { model: candidate.model, state: finalState, questions },
+        signal,
+      });
+      return createToolResponse(formatResult(response, candidate, failures));
+    } catch (error) {
+      if (signal?.aborted) return createToolError('Decision request cancelled.');
+      logger.error('Decision request failed', { provider: candidate.providerName, model: candidate.model, error: error.message });
+      failures.push({ provider: candidate.providerName, message: error.message });
+      if (error.terminal) break;
+    }
+  }
+
+  const detail = failures.map((f) => `${f.provider}: ${f.message}`).join('; ');
+  return createToolError(`Decision request failed (${detail})`);
+}
+
+decideTool.description =
+  'DECIDE — ask a System One decision model (TypeSafe Jev) typed questions about a state and get calibrated answers, not text. ' +
+  'Question types: "noul" (yes/no → probability 0..1), "choice" (pick one of 2–255 named options → choice, per-option probabilities, confidence), ' +
+  '"score" (ordered rubric of 2–10 levels → weighted position, per-level probabilities, confidence). ' +
+  'Batch independent questions over the same state into one call: they are judged in parallel and in isolation, so none sees another\'s answer; each extra question adds its own input tokens. ' +
+  'Best for fast semantic judgments (classify, route, select, verify, rank). Ask one narrow, coherent judgment per question, with its full meaning in the question; ' +
+  'split independently useful dimensions, but a bounded action choice or contextual interpretation is a valid single question. Do counting, arithmetic, and date comparison in code. ' +
+  'confidence measures how concentrated the distribution is, not permission to act: take the top option to pick a best, and treat a noul near 0.5 as "yes and no equally likely". ' +
+  'Text only, no explanations are returned. ' +
+  'Limits: ~64k tokens per request, ~32k for state plus the longest question.';
+
+decideTool.inputSchema = {
+  type: 'object',
+  properties: {
+    state: {
+      anyOf: [{ type: 'string' }, { type: 'object' }, { type: 'array' }],
+      description:
+        'The material to judge: plain text, or JSON (an object with descriptively named fields is best; an array for sequences such as messages). Optional when "files" is given.',
+    },
+    questions: {
+      type: 'object',
+      description:
+        'Named questions, all answered against the same state. The name is your own label and is returned as the answer key. ' +
+        'Each question: { "type": "noul"|"choice"|"score", "instructions": string|object|array, "criteria": ... }. ' +
+        'criteria — noul: optional { "true": "...", "false": "..." }; choice: required { "<option>": "description" | null } (2–255 options); ' +
+        'score: required ordered array of level descriptions, lowest first (2–10 levels). ' +
+        'instructions may be an object bundling the question with reference data, referenced by `name` in the text. ' +
+        'Example: { "team": { "type": "choice", "instructions": "Which team should handle this?", "criteria": { "billing": "Payments, refunds", "technical": "Bugs, outages" } } }',
+      additionalProperties: {
+        type: 'object',
+        properties: {
+          type: { type: 'string', enum: QUESTION_TYPES },
+          instructions: { anyOf: [{ type: 'string' }, { type: 'object' }, { type: 'array' }] },
+          criteria: { anyOf: [{ type: 'object' }, { type: 'array' }] },
+        },
+        required: ['type', 'instructions'],
+        additionalProperties: false,
+      },
+    },
+    model: {
+      type: 'string',
+      description:
+        'Decision model. "auto" (default): TypeSafe, falling back to OpenRouter. "jev-latest", "jev-1.13": first configured provider that serves it, with fallback. ' +
+        '"typesafe:jev-1.13.0", "openrouter:~typesafe/jev-latest": that provider only. Providers: typesafe (TYPESAFE_API_KEY), openrouter (OPENROUTER_API_KEY).',
+    },
+    files: {
+      type: 'array',
+      items: { type: 'string' },
+      description:
+        'Text files added to the state as { "files": { "<path>": "<content>" } }; a given state moves to "input". Supports line ranges: file.txt{10:50}. Images are rejected.',
+    },
+  },
+  required: ['questions'],
+  additionalProperties: false,
+};

package/src/tools/index.js

@@ -9,6 +9,7 @@
 import { chatTool } from './chat.js';
 import { checkStatusTool } from './checkStatus.js';
 import { cancelJobTool } from './cancelJob.js';
+import { decideTool } from './decide.js';
 
 /**
  * Tool registry map
@@ -19,6 +20,7 @@ const tools = {
   chat: chatTool,
   check_status: checkStatusTool,
   cancel_job: cancelJobTool,
+  decide: decideTool,
 };
 
 /**