@cspeach/cli 1.1.24 → 1.1.26

package/dist/router/byok-classifier.js

@@ -0,0 +1,159 @@
+/**
+ * Skill routing without our server (2026-10-02): BYOK and ai-hub.
+ *
+ * The site promises that in BYOK (the customer's own Anthropic key) prompts
+ * never touch CSPeach servers, and that in ai-hub they stay in the customer's
+ * SAP BTP landscape. Until today classifyPrompt POSTed every free-text prompt
+ * — plus pasted screenshots, the SAP alias and the last skill — to
+ * {proxy}/v1/classify in every mode, and the proxy classified it on CSPeach's
+ * key. Now:
+ *   - BYOK: one Messages API call, direct to the model API, with the
+ *     customer's keychain key; router model = the one CSPeach serves
+ *     (roles.router from the public /v1/model-config), with a default.
+ *   - ai-hub (review item 3): the same call through the customer's own hub
+ *     (llm.ai_hub_base_url, their token, their model alias), with today's
+ *     field set only — no output_config, like the ai-hub provider.
+ *
+ * Same quality as managed: the request and its handling come from
+ * router-core.ts, a verbatim copy of the proxy's router core (system prompt
+ * from the signed manifest or the bundled copy — router-prompt.ts; JSON
+ * schema via structured outputs; thinking off; max_tokens 600; self-heal
+ * without output_config on a 400; one retry on an unparseable answer; then the
+ * low-confidence fallback).
+ *
+ * Latency (review item 1): ONE overall deadline covers every call (self-heal
+ * and retry included); past it the caller routes by local rules with the
+ * timeout notice. Ctrl+C aborts the in-flight call at once.
+ *
+ * Nothing in here talks to a CSPeach host. The only other network read on
+ * this path is the public signed manifest (router-prompt.ts), which carries
+ * no prompt data.
+ */
+import Anthropic from '@anthropic-ai/sdk';
+import keychain from '../auth/keychain.js';
+import { byokRouterModel } from '../models/server-config.js';
+import { addRouterSpend } from '../cost/router-spend.js';
+import { loadRouterPrompt } from './router-prompt.js';
+import { ROUTER_UNPARSEABLE_RESULT, buildRouterRequest, runRouterCalls, } from './router-core.js';
+/** Same keychain entry the BYOK provider reads (byok-provider.ts) and login writes. */
+export const BYOK_KEYCHAIN_SERVICE = 'cspeach.anthropic';
+export const BYOK_KEYCHAIN_ACCOUNT = 'api-key';
+/** Same keychain entry the ai-hub provider reads. */
+const AI_HUB_KEYCHAIN_SERVICE = 'cspeach.ai-hub';
+const AI_HUB_KEYCHAIN_ACCOUNT = 'token';
+/** The ai-hub provider's default alias (ai-hub-provider.ts). */
+const AI_HUB_DEFAULT_MODEL = 'anthropic--claude-opus-4-6';
+/** Per model call; the SDK retries a timeout / dropped connection once (maxRetries 1). */
+const ROUTER_CALL_TIMEOUT_MS = 8000;
+/** One deadline for the whole routing step (every call, self-heal and retry included). */
+const ROUTER_DEADLINE_MS = 10_000;
+let deadlineOverride;
+/** Test-only: shorten the overall routing deadline (undefined = default). */
+export function __setRouterDeadlineForTests(ms) {
+    deadlineOverride = ms;
+}
+let selfHealWarned = false;
+/** Test-only: re-arm the once-per-session self-heal warning. */
+export function __resetRouterWarnForTests() {
+    selfHealWarned = false;
+}
+export class ByokRouterFailure extends Error {
+    failure;
+    constructor(failure) {
+        super(`router call failed (${failure.kind})`);
+        this.failure = failure;
+        this.name = 'ByokRouterFailure';
+    }
+}
+function causeOf(err) {
+    const e = err;
+    if (e?.cause)
+        return `${e.cause.code ?? e.cause.errno ?? 'unknown'}${e.cause.message ? `: ${e.cause.message}` : ''}`;
+    return e?.message ?? String(err);
+}
+function cancelled() {
+    const e = new Error('routing cancelled');
+    e.name = 'AbortError';
+    return e;
+}
+/**
+ * Classify one prompt on the laptop. Returns the router's answer (or the
+ * low-confidence fallback when it gave no parseable answer twice). Throws:
+ * AbortError on a user cancel; ByokRouterFailure for a model-API failure or
+ * the overall deadline; an Error when no key / token is configured.
+ */
+export async function classifyByok(prompt, context, images, opts = {}) {
+    const target = opts.target ?? { mode: 'byok' };
+    if (opts.signal?.aborted)
+        throw cancelled();
+    const key = target.mode === 'byok'
+        ? await keychain.getPassword(BYOK_KEYCHAIN_SERVICE, BYOK_KEYCHAIN_ACCOUNT)
+        : await keychain.getPassword(AI_HUB_KEYCHAIN_SERVICE, AI_HUB_KEYCHAIN_ACCOUNT);
+    if (!key) {
+        throw new Error(target.mode === 'byok'
+            ? 'BYOK Anthropic API key not configured — run: cspeach config set llm.byok_key <key>'
+            : 'AI Hub token not configured — run: cspeach config set llm.ai_hub_token <token>');
+    }
+    // One controller for the whole step: the user's cancel OR the deadline.
+    const ctrl = new AbortController();
+    let deadlineHit = false;
+    const timer = setTimeout(() => { deadlineHit = true; ctrl.abort(); }, deadlineOverride ?? ROUTER_DEADLINE_MS);
+    timer.unref?.();
+    const onUserAbort = () => ctrl.abort();
+    opts.signal?.addEventListener('abort', onUserAbort, { once: true });
+    const userCancelled = () => opts.signal?.aborted === true;
+    try {
+        const { prompt: routerPrompt } = await loadRouterPrompt({ signal: ctrl.signal });
+        const model = target.mode === 'byok' ? byokRouterModel() : (target.modelAlias ?? AI_HUB_DEFAULT_MODEL);
+        const full = buildRouterRequest(model, prompt, context, images, routerPrompt);
+        // ai-hub: today's field set only (the hub has no flag for newer fields).
+        const request = target.mode === 'byok'
+            ? full
+            : (({ output_config: _dropped, ...rest }) => rest)(full);
+        const sdk = new Anthropic({
+            apiKey: key,
+            maxRetries: 1,
+            timeout: ROUTER_CALL_TIMEOUT_MS,
+            ...(target.mode === 'ai-hub' ? { baseURL: target.baseURL } : {}),
+        });
+        const { result } = await runRouterCalls((req) => sdk.messages.create(req, { signal: ctrl.signal }), request, {
+            // Once per session — a model that rejects structured outputs would
+            // otherwise print this on every prompt.
+            warn: (message, detail) => {
+                if (selfHealWarned)
+                    return;
+                selfHealWarned = true;
+                console.warn(message, detail);
+            },
+            // The customer's own bill (BYOK) — counted in the USD meter as each
+            // call finishes, so a deadline / cancel after call 1 keeps call 1
+            // (review S1). ai-hub is billed by their BTP account at rates we
+            // don't know: not priced here.
+            onCall: (c) => { if (target.mode === 'byok')
+                addRouterSpend(model, c.usage); },
+        });
+        return result ?? { ...ROUTER_UNPARSEABLE_RESULT, alternates: [] };
+    }
+    catch (err) {
+        if (userCancelled())
+            throw cancelled();
+        if (deadlineHit)
+            throw new ByokRouterFailure({ kind: 'timeout', detail: 'routing deadline' });
+        if (err instanceof Anthropic.APIUserAbortError)
+            throw cancelled();
+        if (err instanceof Anthropic.APIConnectionTimeoutError) {
+            throw new ByokRouterFailure({ kind: 'timeout', detail: causeOf(err) });
+        }
+        if (err instanceof Anthropic.APIConnectionError) {
+            throw new ByokRouterFailure({ kind: 'connection', detail: causeOf(err) });
+        }
+        if (err instanceof Anthropic.APIError && typeof err.status === 'number') {
+            throw new ByokRouterFailure({ kind: 'http', status: err.status });
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+        opts.signal?.removeEventListener('abort', onUserAbort);
+    }
+}

package/dist/router/classifier.js

@@ -1,10 +1,11 @@
 import { loadConfig } from '../config/loader.js';
 import { getStore } from '../auth/api-key.js';
-import { classify as classifyLocal } from '../classifier/client.js';
+import { classify as classifyLocal, classifyWithConfidence } from '../classifier/client.js';
 import { SKILL_CATALOG, SKILL_ALIASES, resolveSkillAlias } from '../skill-catalog.js';
 import { isBuiltinCommandHead } from '../repl/builtin-commands.js';
 import { expandImageAttachments } from '../projects/image-attachments.js';
 import { expandImageChips } from '../ui/clipboard-image.js';
+import { classifyByok, ByokRouterFailure } from './byok-classifier.js';
 /** A non-2xx answer from the classify endpoint (fix 9: carries the kind). */
 export class ClassifyHttpError extends Error {
     status;
@@ -15,6 +16,51 @@ export class ClassifyHttpError extends Error {
         this.name = 'ClassifyHttpError';
     }
 }
+/**
+ * Live fix 2026-10-02 — the classify endpoint answered 2xx but the body was
+ * not a classification (not JSON, or no skill). Used to escape as a raw
+ * SyntaxError; now a routing failure the callers degrade from.
+ */
+export class ClassifyBodyError extends Error {
+    transport_kind = 'failed';
+    constructor() {
+        super('classifier returned an unreadable answer');
+        this.name = 'ClassifyBodyError';
+    }
+}
+/**
+ * The bundled local-rules pick used whenever the remote classifier gives no
+ * answer (transport failure, and since 2026-10-02 any classify failure).
+ * Confidence 0.3 < 0.60 ⇒ the low-confidence path (picker / one-shot notice).
+ *
+ * 2026-10-02: the no-rule-matched default is abap-explain (read-only,
+ * generic — the same default the router uses for an unparseable answer). It
+ * was abap-radar, retired 2026-06-28 (merged into abap-explain's technical
+ * mode).
+ */
+export function localRulesResult(prompt) {
+    return { skill: classifyLocal(prompt) ?? 'abap-explain', confidence: 0.3, alternates: [] };
+}
+/**
+ * Local mode's routing (2026-10-02, review items 3 + S2): the bundled rules
+ * only — the prompt never leaves the laptop. A matching rule is a real pick,
+ * not a failure fallback, so there is no "couldn't route" notice: an
+ * unambiguous (strong) rule routes silently (0.85), any other match opens the
+ * picker preselected (0.6); no match is the low-confidence local-rules result
+ * (picker, abap-explain).
+ *
+ * Why not the local model: local endpoints (Ollama / vLLM, OpenAI-compatible)
+ * have no structured outputs, small local models are unreliable at strict
+ * JSON routing, and a large one adds seconds per prompt on a laptop — on top
+ * of the turn itself. Local mode is text-only today; instant, offline,
+ * deterministic rules with a one-key confirm fit it better.
+ */
+function localModeResult(prompt) {
+    const hit = classifyWithConfidence(prompt);
+    return hit
+        ? { skill: resolveSkillAlias(hit.skill), confidence: hit.confidence, alternates: [] }
+        : localRulesResult(prompt);
+}
 // 8s — sized to cover the observed Fly cold-start (~3.2s on the 2026-05-20
 // probe) plus headroom for a slow network. Tighter values risk timing out
 // legitimate cold-start hits and burning the retry budget on the same.
@@ -111,6 +157,31 @@ export async function classifyPrompt(prompt, context, opts = {}) {
         throw new Error('slash command reached the classifier — explicit /commands must be routed before classification (CLI bug, please report)');
     }
     const cfg = await loadConfig();
+    // 2026-10-02 (local routing): outside managed mode the prompt never goes to
+    // a CSPeach host. BYOK classifies on the laptop, direct to the model API
+    // with the customer's own key; ai-hub through the customer's own hub;
+    // local by the bundled rules (byok-classifier.ts / localModeResult).
+    // Managed keeps /v1/classify below, byte-identical.
+    const mode = cfg.llm?.mode;
+    if (mode === 'local') {
+        if (opts.signal?.aborted)
+            throw routingCancelled();
+        return localModeResult(prompt);
+    }
+    if (mode === 'byok')
+        return classifyPromptByok(prompt, context, opts, { mode: 'byok' });
+    if (mode === 'ai-hub') {
+        const baseURL = cfg.llm.ai_hub_base_url;
+        if (!baseURL)
+            throw new Error('ai-hub mode requires llm.ai_hub_base_url — run: cspeach config set llm.ai_hub_base_url <url>');
+        // llm.ai_hub_router_model (optional, 2026-10-02) routes on a cheaper /
+        // faster deployment; unset ⇒ the session alias.
+        return classifyPromptByok(prompt, context, opts, {
+            mode: 'ai-hub',
+            baseURL,
+            modelAlias: cfg.llm.ai_hub_router_model ?? cfg.llm.ai_hub_model_alias,
+        });
+    }
     const store = await getStore();
     const key = await store.get();
     if (!key)
@@ -147,11 +218,8 @@ export async function classifyPrompt(prompt, context, opts = {}) {
         // local rules so the user's turn is NOT dropped — they still get a
         // coaching picker (confidence 0.3 < 0.60 = picker decision), and the
         // REPL surfaces an offline hint with the real cause.
-        const skill = classifyLocal(prompt) ?? 'abap-radar';
         return {
-            skill,
-            confidence: 0.3,
-            alternates: [],
+            ...localRulesResult(prompt),
             offline: true,
             transport_error: lastErr ? extractCause(lastErr) : 'unknown',
             transport_kind: transportKindOf(lastErr),
@@ -159,7 +227,28 @@ export async function classifyPrompt(prompt, context, opts = {}) {
     }
     if (!r.ok)
         throw new ClassifyHttpError(r.status);
-    const result = (await r.json());
+    // Live fix 2026-10-02: an unreadable 2xx body is a routing failure, not a
+    // raw SyntaxError escaping to the caller.
+    let result;
+    try {
+        result = (await r.json());
+    }
+    catch {
+        throw new ClassifyBodyError();
+    }
+    return normaliseResult(result);
+}
+/**
+ * The checks every classification gets, wherever it came from (the proxy, or
+ * since 2026-10-02 the BYOK router on the laptop).
+ */
+function normaliseResult(result) {
+    if (!result || typeof result.skill !== 'string' || result.skill === '')
+        throw new ClassifyBodyError();
+    if (typeof result.confidence !== 'number')
+        result.confidence = 0;
+    if (!Array.isArray(result.alternates))
+        result.alternates = [];
     // Portfolio-merge resilience (2026-06-12): the proxy classifier's skill
     // list can lag a rename (it still knows 'abap-dump-analyze' until its
     // SKILL_LIST is redeployed). Map retired names — primary and alternates —
@@ -171,6 +260,41 @@ export async function classifyPrompt(prompt, context, opts = {}) {
     }
     return result;
 }
+/**
+ * BYOK / ai-hub branch of classifyPrompt (2026-10-02). Same contract as the managed
+ * path — a result, a low-confidence local-rules result when the router could
+ * not be reached, ClassifyHttpError for an HTTP failure, AbortError on cancel
+ * — so every caller (Ink REPL, classic REPL, one-shot) is unchanged.
+ */
+async function classifyPromptByok(prompt, context, opts, target) {
+    if (opts.signal?.aborted)
+        throw routingCancelled();
+    const images = await promptImages(prompt, opts.cwd ?? process.cwd());
+    if (opts.signal?.aborted)
+        throw routingCancelled();
+    try {
+        const result = await classifyByok(prompt, { sap_system: context.sap_system, last_skill: context.last_skill }, images, { signal: opts.signal, target });
+        return normaliseResult({ ...result });
+    }
+    catch (err) {
+        if (opts.signal?.aborted)
+            throw routingCancelled();
+        if (err instanceof ByokRouterFailure) {
+            const f = err.failure;
+            if (f.kind === 'http')
+                throw new ClassifyHttpError(f.status);
+            // The model API was not reached. 'failed', not 'network': the network
+            // notice names the CSPeach service, which BYOK routing never calls.
+            return {
+                ...localRulesResult(prompt),
+                offline: true,
+                transport_error: f.detail,
+                transport_kind: f.kind === 'timeout' ? 'timeout' : 'failed',
+            };
+        }
+        throw err;
+    }
+}
 export function parseShortcut(input) {
     // `/skill-name rest` → { skill: 'abap-skill-name', prompt: 'rest' }
     //   abap- prefix auto-prepended if missing (all skills in KV use abap-* namespace).

package/dist/router/router-core.js

@@ -0,0 +1,307 @@
+// GENERATED COPY — do not edit here. Edit cspeach-proxy/src/classifier/router-core.ts,
+// then run `npx tsx scripts/sync-router-core.ts` (prebuild runs it too).
+// src/router/__tests__/router-core-pin.test.ts fails when this copy drifts.
+// ---- verbatim copy of cspeach-proxy/src/classifier/router-core.ts below ----
+// ROUTER CORE — the single source of the skill router's instructions and call
+// behaviour (2026-10-02, BYOK local routing).
+//
+// Why this file exists: in BYOK mode the customer's prompt must never reach a
+// CSPeach server, so the CLI classifies on the laptop, direct to the model
+// with the customer's own key. To keep that routing exactly as good as the
+// managed /v1/classify route, both sides run THIS code:
+//   - the proxy imports it (classifier/haiku.ts, and skills/skill-manifest.ts,
+//     which publishes ROUTER_PROMPT inside the signed skill manifest);
+//   - the CLI carries a byte-identical copy at
+//     cspeach-cli/src/router/router-core.ts (scripts/sync-router-core.ts
+//     writes it; a CLI test fails on any drift).
+//
+// RULES for this file: NO imports (it must compile, unchanged, in both
+// packages); keep it plain TypeScript that passes both tsconfigs. Editing the
+// skill list or routing notes here changes managed routing (after a proxy
+// deploy), the signed manifest (after publish-skill-manifest) and the CLI's
+// bundled fallback (after sync-router-core + a CLI release).
+/**
+ * Version of the router entry's SHAPE in the signed manifest
+ * ({ schema_version, system, screenshot_note }). A CLI uses a manifest router
+ * entry only when it knows this version; otherwise it keeps its bundled copy.
+ * Bump it only when the shape or the request contract changes — not for text
+ * edits.
+ */
+export const ROUTER_SCHEMA_VERSION = 1;
+/**
+ * Revision of the router TEXT and request (2026-10-02, review item 2). Bump
+ * it on EVERY change to SKILL_DESCRIPTIONS, the routing notes, ROUTER_SYSTEM,
+ * SCREENSHOT_NOTE or buildRouterRequest. A BYOK CLI prefers the signed
+ * manifest's router entry only when its revision is the same or newer than
+ * its own bundled copy — so a stale published manifest never rolls a newer
+ * CLI back to older routing. router-revision-pin.test.ts fails until bumped.
+ */
+export const ROUTER_REVISION = 1;
+// 2026-06-12: keep in lockstep with .claude/skills (35 abap skills).
+// abap-dump replaced abap-dump-analyze + abap-dump-triage (portfolio merge);
+// added previously-missing abap-plan, abap-fiori-build, abap-cca-merge, abap-upgrade-merge.
+// 2026-06-28 (M1-M4 portfolio merges): removed 4 donor skills — abap-radar → abap-explain
+// (technical orientation mode); abap-document → abap-handover (object scope); abap-performance
+// → abap-review (performance lens); abap-cloud-check → abap-review (cloud lens). Skill count
+// drops from 35 to 31. abap-preflight is NOT removed (chained by abap-transport-analysis).
+// 2026-06-15 (Bug #1): pair every skill with a one-line description. Haiku was
+// routing on bare NAMES — "color the lines on a custom Z report" matched the word
+// "enhance" (82%) when it should have been abap-refactor; Haiku never saw that
+// abap-enhance = extend SAP STANDARD only. The one-liners + routing notes below
+// encode the key disambiguations directly. These keys ARE the skill list — there
+// is no separate name array to drift out of sync.
+// 2026-09-25: added abap-cap (CAP phase 1) — "build a CAP app" had no home and
+// fell back to abap-generate at low confidence.
+// 2026-10-01: added abap-app (app lane routing slice 1) — one entry from a spec
+// document to a running app; the CAP routing note below is unchanged.
+export const SKILL_DESCRIPTIONS = {
+    'abap-app': 'Build an app FROM a spec or requirements document (Word, PDF, Excel or text) — finds the spec gaps, picks the app lane (backend + UI) and confirms it with the developer, then plans and builds the app.',
+    'abap-atc-fix': 'Run ATC checks on an object and auto-fix findings where safe.',
+    'abap-cap': 'Build a CAP (SAP Cloud Application Programming Model, Node.js / CDS) app on the laptop — domain model, service, handlers, Fiori Elements app — run it locally and prove it with the Fiori checks. Side-by-side (BTP) extensions, not the ABAP core.',
+    'abap-cca': 'Custom Code Analysis — inventory + classify a whole custom-code estate (Keep/Fix/Retire) for S/4HANA migration / Clean Core.',
+    'abap-cca-merge': 'Merge multiple parallel CCA assessment files into one consolidated assessment.',
+    'abap-data-model': 'Design and create DDIC objects — domains, data elements, tables, structures.',
+    'abap-design': 'Design solution architecture — object list, dependency sequence, pattern selection. After spec-gap, before coding.',
+    'abap-dump': 'Diagnose ABAP short dumps (ST22 runtime errors) and fix them.',
+    'abap-eml': 'Write and test EML (Entity Manipulation Language) for RAP business objects.',
+    'abap-enhance': 'Extend SAP-delivered STANDARD objects via BAdI / enhancement spots / exits. ONLY for standard objects — never for editing your own custom Z/Y code.',
+    'abap-estimate': 'Effort estimation for ABAP tickets — component breakdown, hour ranges, risk.',
+    'abap-explain': 'Understand an existing object — plain-language explanation (default) or a `technical` developer orientation (deps, tables, risks, modernization notes).',
+    'abap-fiori-build': 'Build a freestyle SAPUI5 app on the laptop from already-published OData services.',
+    'abap-generate': 'Create NEW ABAP code/objects from a requirement (greenfield).',
+    'abap-handover': 'Documentation for an object (`object` scope) or a whole package (`package` scope) — purpose, interfaces, deps, catalog, architecture, config.',
+    'abap-impact': 'Analyze the impact of changing an object before touching it — where-used, dependents, risk.',
+    'abap-incident': 'End-to-end incident pipeline — from short dump to fix deployed and documented.',
+    'abap-migrate': 'ECC→S/4HANA migration assessment for custom objects — API analysis, successor lookup, per-object effort.',
+    'abap-modernize': 'Transform a CLASSIC program into a modern architecture (e.g. report → Fiori Elements / RAP) for the release level.',
+    'abap-plan': 'Plan and run a multi-session SAP project — phase envelope carries state across sessions, one phase per session.',
+    'abap-preflight': 'Pre-release checklist for a change set — dependencies, tests, rollback, readiness.',
+    'abap-rap': 'Scaffold a complete RAP stack from scratch — table, CDS interface+projection, BDEF, behavior class, service definition+binding.',
+    'abap-refactor': 'Modify / improve / add a feature to EXISTING custom ABAP code in place — restructure, clean up, or change a Z/Y program/class (incl. small feature changes like adding output coloring).',
+    'abap-review': 'Read-only code review across lenses: `quality` (default, 7 criteria), `performance` (N+1/SELECT*/indexes), `cloud` (clean-core / ABAP Cloud readiness).',
+    'abap-segw': 'Implement SEGW OData service methods (MPC/DPC) for an existing gateway project.',
+    'abap-spec-gap': "Find what's missing before coding — business questions, technical gaps, edge cases, test scenarios.",
+    'abap-test': 'Generate ABAP Unit test classes for existing code.',
+    'abap-transport': 'Transport management — create requests, validate object lists, release transports.',
+    'abap-transport-analysis': 'Pre-release transport analysis — list objects, ATC each, cross-dependency + conflict checks.',
+    'abap-upgrade-fix': 'Interactive upgrade remediation — fix ATC findings object-by-object with successor-API lookup and approval.',
+    'abap-upgrade-merge': 'Merge multiple parallel upgrade-fix progress files into one consolidated progress.',
+    'abap-upgrade-scan': 'Scan custom code for S/4HANA upgrade findings — ATC readiness variant, categorize, remediation plan.',
+    'abap-upgrade-verify': 'Verify upgrade remediation — re-run ATC, compare against baseline, flag regressions.',
+};
+export const SKILL_LIST = Object.keys(SKILL_DESCRIPTIONS);
+// Screenshot-aware routing (2026-09-23) — appended ONLY when images are sent,
+// so text-only routing keeps the exact pre-feature instructions.
+export const SCREENSHOT_NOTE = `
+
+A screenshot is attached. Read it (error text, transaction code such as ST22/ATC/SE80, object names) and classify on the prompt AND the screenshot together — a vague prompt ("can you see this?") with an ST22 dump is abap-dump. Also add "screenshot": a one-line reading of it (e.g. "ST22 dump: CX_SY_ZERODIVIDE in ZCL_X, method CALC").`;
+export const ROUTER_SYSTEM = `You classify user prompts into ABAP-development skills. Given a prompt and context, return JSON: {"skill": "<name>", "confidence": 0-1, "alternates": ["<name>"], "reasoning": "..."}.
+
+Skills (name — what it is for):
+${SKILL_LIST.map((n) => `- ${n} — ${SKILL_DESCRIPTIONS[n]}`).join('\n')}
+
+Routing notes:
+- Editing, changing, or adding a feature to an EXISTING custom (Z*/Y*) object → abap-refactor (in-place change) or abap-generate (new objects). abap-enhance is ONLY for SAP-delivered STANDARD objects — never for custom code.
+- "Make a classic report modern / turn it into Fiori" → abap-modernize. "Build a full RAP stack from scratch" → abap-rap.
+- CAP / cds / Node.js / a side-by-side BTP app or extension → abap-cap. On-stack RAP inside the ABAP system → abap-rap. A UI on an already-published OData service → abap-fiori-build.
+- Building an app FROM a spec or requirements document (Word / PDF / Excel, 'build the app in this spec') → abap-app. A direct request without a spec document keeps its own skill.
+- Quick cold-read / orientation of an object → abap-explain (technical audience).
+- Performance issues / N+1 / SELECT * → abap-review (performance lens). Clean-core / ABAP Cloud readiness of one object → abap-review (cloud lens); estate-wide clean-core → abap-cca.
+- Developer documentation of an object → abap-handover (object scope).
+
+Pick the single best skill. Confidence is 0.75+ if the intent clearly matches one skill, 0.6-0.75 if two skills are plausible, <0.6 if none are clearly right.`;
+export const ROUTER_PROMPT = {
+    schema_version: ROUTER_SCHEMA_VERSION,
+    revision: ROUTER_REVISION,
+    system: ROUTER_SYSTEM,
+    screenshot_note: SCREENSHOT_NOTE,
+};
+/**
+ * A router entry read from outside (the signed manifest), or null when it is
+ * not one this code can use — unknown schema version, missing revision,
+ * missing or empty text.
+ * Callers then keep ROUTER_PROMPT. Never throws.
+ */
+export function asRouterPrompt(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const r = raw;
+    if (r.schema_version !== ROUTER_SCHEMA_VERSION)
+        return null;
+    if (typeof r.revision !== 'number' || !Number.isInteger(r.revision) || r.revision < 0)
+        return null;
+    if (typeof r.system !== 'string' || r.system.trim() === '')
+        return null;
+    if (typeof r.screenshot_note !== 'string')
+        return null;
+    return { schema_version: ROUTER_SCHEMA_VERSION, revision: r.revision, system: r.system, screenshot_note: r.screenshot_note };
+}
+const tok = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+// Live fix 2026-10-02: some prompts made the router answer in prose instead of
+// JSON (e.g. a read-only question ending "Answer in a short list." — the router
+// followed the user's format request). classifyWithUsage threw 'Classifier
+// produced non-JSON output' and /v1/classify returned HTTP 500, which the CLI
+// one-shot surfaced as "unhandled error". Three layers now:
+//   1. Structured outputs (output_config.format, json_schema) ask the API for
+//      JSON. Chosen over an assistant prefill of "{" — the router role is
+//      admin-tunable and prefill is rejected (400) on every 4.6+ model — and
+//      over forced tool use — tool_choice "tool" is rejected on Opus 5.5 /
+//      Sonnet 5.5 / Fable 5.1. Structured outputs run on the default router
+//      (claude-haiku-4-5) and the current 5.x models. SYSTEM is unchanged, so
+//      routing for normal prompts is the same.
+//   2. A strict parse; an unparseable answer is retried ONCE.
+//   3. Still unparseable → ROUTER_UNPARSEABLE_RESULT (confidence 0 ⇒ the CLI's
+//      low-confidence path: picker in the REPL, top-1 + notice in one-shot),
+//      flagged `unparseable` so the route does not cache it. Never a throw.
+// Upstream API errors (network / 4xx / 5xx from the provider) still throw; the
+// route turns them into a JSON 502 and the CLI degrades to local rules.
+/** abap-explain: read-only and generic — the safest default when the router gave no answer. */
+export const ROUTER_UNPARSEABLE_RESULT = Object.freeze({
+    skill: 'abap-explain',
+    confidence: 0,
+    alternates: [],
+    reasoning: 'router_unparseable',
+});
+/** JSON schema for the router answer — the same fields SYSTEM asks for. */
+export function resultSchema(withScreenshot) {
+    return {
+        type: 'object',
+        properties: {
+            skill: { type: 'string' },
+            confidence: { type: 'number' },
+            alternates: { type: 'array', items: { type: 'string' } },
+            reasoning: { type: 'string' },
+            // Only offered when a screenshot was sent (SCREENSHOT_NOTE asks for it).
+            ...(withScreenshot ? { screenshot: { type: 'string' } } : {}),
+        },
+        required: ['skill', 'confidence', 'alternates', 'reasoning'],
+        additionalProperties: false,
+    };
+}
+/** The router's text → a RouterResult, or null when it is not one. Never throws. */
+export function parseRouterText(text) {
+    const candidates = [text.trim()];
+    const m = text.match(/\{[\s\S]*\}/);
+    if (m && m[0] !== candidates[0])
+        candidates.push(m[0]);
+    for (const c of candidates) {
+        let v;
+        try {
+            v = JSON.parse(c);
+        }
+        catch {
+            continue;
+        }
+        if (!v || typeof v !== 'object' || Array.isArray(v))
+            continue;
+        const r = v;
+        if (typeof r.skill !== 'string' || r.skill.trim() === '')
+            continue;
+        return {
+            ...r,
+            confidence: typeof r.confidence === 'number' && Number.isFinite(r.confidence) ? r.confidence : 0,
+            alternates: Array.isArray(r.alternates) ? r.alternates.filter((a) => typeof a === 'string') : [],
+        };
+    }
+    return null;
+}
+/** The user turn the router sees: the prompt plus the routing context. */
+export function routerUserMessage(prompt, context) {
+    return `Prompt: ${prompt}\n\nContext: sap_system=${context.sap_system ?? 'unknown'}, last_skill=${context.last_skill ?? 'none'}`;
+}
+/** The router request body (Messages API), exactly as the proxy has sent it since 2026-10-02. */
+export function buildRouterRequest(model, prompt, context, images = [], routerPrompt = ROUTER_PROMPT) {
+    const userMsg = routerUserMessage(prompt, context);
+    return {
+        model,
+        // Root cause found live 2026-10-02 (v54): the router model (claude-sonnet-5)
+        // thinks by default and, on harder prompts, spent all 300 tokens on a
+        // thinking block — stop_reason max_tokens, no text, unparseable. Routing is
+        // a quick pick: thinking off, and headroom for the JSON answer.
+        max_tokens: 600,
+        thinking: { type: 'disabled' },
+        system: images.length === 0 ? routerPrompt.system : routerPrompt.system + routerPrompt.screenshot_note,
+        // 2026-10-02: JSON via structured outputs (see the note above).
+        output_config: { format: { type: 'json_schema', schema: resultSchema(images.length > 0) } },
+        // Screenshot-aware routing (2026-09-23): images ride ahead of the text in
+        // the same message; with none, the plain string is sent as before.
+        messages: [{
+                role: 'user',
+                content: images.length === 0
+                    ? userMsg
+                    : [
+                        ...images.map((im) => ({
+                            type: 'image',
+                            source: { type: 'base64', media_type: im.media_type, data: im.data },
+                        })),
+                        { type: 'text', text: userMsg },
+                    ],
+            }],
+    };
+}
+/**
+ * Send the router request: the self-heal, parse, one retry. `create` is the
+ * caller's Messages API call (the proxy's org-key client, or the CLI's BYOK
+ * client) — injected so this file stays import-free. Provider errors other
+ * than the self-heal case are rethrown for the caller to map.
+ */
+export async function runRouterCalls(create, request, opts = {}) {
+    const now = opts.now ?? Date.now;
+    // 2026-10-02 (self-healing): the router role is admin-tunable, and not every
+    // model accepts structured outputs (e.g. Sonnet 4.6 / Opus 4.6–4.7 are not on
+    // the supported list). Sending output_config to one of those is a 400 on
+    // EVERY classify — all customers would drop to the CLI's local rules. So a
+    // 400 while output_config is sent re-sends the same call ONCE without it;
+    // the parse / retry / fallback below then works as before (SYSTEM still
+    // asks for JSON). A 400 without output_config, and any non-400, surface.
+    let req = request;
+    const send = async () => {
+        try {
+            return await create(req);
+        }
+        catch (err) {
+            if ('output_config' in req && err?.status === 400) {
+                opts.warn?.(`[classify] router model ${request.model} rejected output_config (400) — retrying without structured outputs:`, err instanceof Error ? err.message : String(err));
+                const { output_config: _dropped, ...rest } = request;
+                req = rest;
+                return await create(req);
+            }
+            throw err;
+        }
+    };
+    const calls = [];
+    let result = null;
+    // At most two parsed answers: the first, and ONE retry when it is unparseable.
+    for (let attempt = 0; attempt < 2 && result === null; attempt++) {
+        const startedAt = now();
+        const res = await send();
+        const u = res?.usage ?? {};
+        const call = {
+            usage: {
+                input: tok(u.input_tokens),
+                output: tok(u.output_tokens),
+                cacheRead: tok(u.cache_read_input_tokens),
+                cacheCreate: tok(u.cache_creation_input_tokens),
+            },
+            latencyMs: now() - startedAt,
+        };
+        calls.push(call);
+        opts.onCall?.(call);
+        const content = Array.isArray(res?.content) ? res.content : [];
+        const text = content
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text)
+            .join('\n');
+        result = parseRouterText(text);
+    }
+    return { result, calls };
+}
+/** Token counts summed over every call made. */
+export function sumRouterUsage(calls) {
+    return calls.reduce((s, c) => ({
+        input: s.input + c.usage.input,
+        output: s.output + c.usage.output,
+        cacheRead: s.cacheRead + c.usage.cacheRead,
+        cacheCreate: s.cacheCreate + c.usage.cacheCreate,
+    }), { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 });
+}