@cr1ms0n/pi-subagent 0.8.8 → 0.9.0

package/src/routing-policy.ts

@@ -0,0 +1,268 @@
+import { isThinkingLevel } from "./thinking.js";
+import {
+  DEFAULT_API_KEY_ENV,
+  DEFAULT_ROUTING_TIMEOUT_MS,
+  DEFAULT_SELECTOR_MODEL,
+  MAX_ROUTING_MODEL_ID_LENGTH,
+  MAX_ROUTING_MODELS,
+  MAX_ROUTING_SELECTOR_MODEL_LENGTH,
+  ROUTING_TIMEOUT_MAX_MS,
+  ROUTING_TIMEOUT_MIN_MS,
+  type JevRoutingConfig,
+  type JevRoutingModelEntry,
+  type RoutingModelCandidate,
+  type RoutingToolCandidate,
+} from "./routing-types.js";
+
+// Re-exported so integration can import routing types from their owning routing module.
+export type {
+  JevRoutingConfig,
+  JevRoutingModelEntry,
+  RoutingModelCandidate,
+  RoutingToolCandidate,
+} from "./routing-types.js";
+
+/**
+ * Strict, pure parser/formatter for the mandatory `jevRouting` subtree.
+ *
+ * This module owns only the user-controlled routing configuration:
+ *
+ * - `parseJevRouting(raw, source?)` parses the `jevRouting` **subtree** (not the whole
+ *   `~/.pi/subagent.json` file) and returns an immutable snapshot. It throws a plain
+ *   `Error` with an actionable message on any unknown field, duplicate/blank model ID,
+ *   blank description, invalid environment-variable name, non-integer/out-of-range timeout
+ *   or unsupported candidate count. Callers (`src/config.ts`) catch that message and expose
+ *   it as a config error; no credential or provider catalog is read.
+ * - `formatJevRoutingPrompt` renders model-facing guidance and works with **no** config, no
+ *   credential and no inference, so management actions stay independent of routing setup.
+ * - The candidate helpers are pure; they never contact Pi or TypeSafe.
+ *
+ * The credential *value* must never be stored in config: only the environment-variable name
+ * is parsed and returned. The parser rejects unknown fields, so an accidental `apiKey` or
+ * `apiKeyValue` field is an error rather than silently ignored.
+ */
+
+/** Default config-file label used in prose (owned by `config.ts` for file reads). */
+export const JEV_ROUTING_CONFIG_FILE = "~/.pi/subagent.json";
+
+const ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Exact provider/model ID: at least one slash, further ID slashes allowed; no whitespace, control chars or globs. */
+const MODEL_ID = /^[^\s\u0000-\u001f\u007f/*?]+(?:\/[^\s\u0000-\u001f\u007f/*?]+)+$/u;
+const MAX_GUIDANCE_MODEL_LINES = 50;
+
+function invalid(source: string, message: string): never {
+  throw new Error(`Invalid jevRouting in ${source}: ${message}`);
+}
+
+function requireObject(value: unknown, source: string, pathName: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    invalid(source, `${pathName} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function rejectUnknownKeys(record: Record<string, unknown>, allowed: readonly string[], source: string, pathName: string): void {
+  const unknown = Object.keys(record).filter((key) => !allowed.includes(key));
+  if (unknown.length) invalid(source, `${pathName} has unknown field(s): ${unknown.join(", ")}`);
+}
+
+function parseSelectorModel(value: unknown, source: string): string {
+  if (value === undefined) return DEFAULT_SELECTOR_MODEL;
+  if (typeof value !== "string") invalid(source, "selectorModel must be a string");
+  const model = value.trim();
+  if (!model || model.length > MAX_ROUTING_SELECTOR_MODEL_LENGTH || /[\s\u0000-\u001f\u007f]/u.test(model)) {
+    invalid(source, `selectorModel must be a non-empty selector alias or version without whitespace or control characters`);
+  }
+  return model;
+}
+
+function parseApiKeyEnv(value: unknown, source: string): string {
+  if (value === undefined) return DEFAULT_API_KEY_ENV;
+  if (typeof value !== "string" || !ENV_VAR_NAME.test(value.trim())) {
+    invalid(source, "apiKeyEnv must be an environment-variable name such as TYPESAFE_API_KEY (the credential value must not be stored in config)");
+  }
+  return value.trim();
+}
+
+function parseTimeoutMs(value: unknown, source: string): number {
+  if (value === undefined) return DEFAULT_ROUTING_TIMEOUT_MS;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < ROUTING_TIMEOUT_MIN_MS || value > ROUTING_TIMEOUT_MAX_MS) {
+    invalid(source, `timeoutMs must be an integer between ${ROUTING_TIMEOUT_MIN_MS} and ${ROUTING_TIMEOUT_MAX_MS}`);
+  }
+  return value;
+}
+
+function parseModelEntry(value: unknown, pathName: string, source: string): JevRoutingModelEntry {
+  const record = requireObject(value, source, pathName);
+  rejectUnknownKeys(record, ["model", "description", "thinking"], source, pathName);
+
+  const rawModel = record.model;
+  const model = typeof rawModel === "string" ? rawModel.trim() : "";
+  if (!model || model.length > MAX_ROUTING_MODEL_ID_LENGTH || !MODEL_ID.test(model)) {
+    invalid(source, `${pathName}.model must be an exact provider/model-id without whitespace, control characters or glob patterns`);
+  }
+
+  const rawDescription = record.description;
+  if (typeof rawDescription !== "string" || !rawDescription.trim()) {
+    invalid(source, `${pathName}.description must be a non-blank user-written characteristics description`);
+  }
+
+  const thinking = record.thinking;
+  if (thinking !== undefined && !isThinkingLevel(thinking)) {
+    invalid(source, `${pathName}.thinking must be a non-empty Pi thinking-level string without whitespace or control characters`);
+  }
+
+  return Object.freeze({
+    model,
+    description: rawDescription,
+    ...(thinking === undefined ? {} : { thinking }),
+  });
+}
+
+function parseModels(value: unknown, source: string): readonly JevRoutingModelEntry[] {
+  if (value === undefined) invalid(source, "models is required and must list at least one candidate model");
+  if (!Array.isArray(value)) invalid(source, "models must be an array of candidate model entries");
+  if (value.length === 0) invalid(source, `models must list at least 1 candidate model`);
+  if (value.length > MAX_ROUTING_MODELS) invalid(source, `models must not list more than ${MAX_ROUTING_MODELS} candidates`);
+
+  const entries: JevRoutingModelEntry[] = [];
+  const seen = new Set<string>();
+  for (let index = 0; index < value.length; index++) {
+    const entry = parseModelEntry(value[index], `models[${index}]`, source);
+    if (seen.has(entry.model)) invalid(source, `models contains duplicate model ID ${JSON.stringify(entry.model)}`);
+    seen.add(entry.model);
+    entries.push(entry);
+  }
+  return Object.freeze(entries);
+}
+
+/**
+ * Parse and freeze the `jevRouting` subtree.
+ *
+ * @param raw    the value at `config.jevRouting` (the subtree, not the whole config file)
+ * @param source human-readable source label used in error messages
+ */
+export function parseJevRouting(raw: unknown, source = JEV_ROUTING_CONFIG_FILE): JevRoutingConfig {
+  const record = requireObject(raw, source, "jevRouting");
+  rejectUnknownKeys(record, ["selectorModel", "apiKeyEnv", "timeoutMs", "models"], source, "jevRouting");
+
+  const snapshot: JevRoutingConfig = {
+    selectorModel: parseSelectorModel(record.selectorModel, source),
+    apiKeyEnv: parseApiKeyEnv(record.apiKeyEnv, source),
+    timeoutMs: parseTimeoutMs(record.timeoutMs, source),
+    models: parseModels(record.models, source),
+  };
+  return Object.freeze(snapshot);
+}
+
+/** A documented manual-migration/template snippet; contains no credential value. */
+export function jevRoutingTemplate(): string {
+  return JSON.stringify({
+    jevRouting: {
+      selectorModel: DEFAULT_SELECTOR_MODEL,
+      apiKeyEnv: DEFAULT_API_KEY_ENV,
+      timeoutMs: DEFAULT_ROUTING_TIMEOUT_MS,
+      models: [
+        {
+          model: "<provider/model-id>",
+          description: "<user-written characteristics, including Chinese>",
+          thinking: "<optional opaque Pi thinking default>",
+        },
+      ],
+    },
+  }, null, 2);
+}
+
+function freezeCandidate(entry: JevRoutingModelEntry): RoutingModelCandidate {
+  return Object.freeze({
+    model: entry.model,
+    description: entry.description,
+    ...(entry.thinking === undefined ? {} : { thinking: entry.thinking }),
+  });
+}
+
+/** Frozen candidate list in configured order; descriptions are preserved unchanged. */
+export function modelCandidates(config: JevRoutingConfig): readonly RoutingModelCandidate[] {
+  return Object.freeze(config.models.map(freezeCandidate));
+}
+
+/**
+ * Intersect the dedicated list with locally available exact model IDs, preserving the
+ * user's configured order. No ranking, cost or quality preset is applied. An empty result
+ * means the caller must reject before any HTTP request.
+ */
+export function eligibleModelCandidates(
+  config: JevRoutingConfig,
+  availableModels: readonly string[],
+): readonly RoutingModelCandidate[] {
+  const available = new Set(availableModels);
+  return Object.freeze(config.models.filter((entry) => available.has(entry.model)).map(freezeCandidate));
+}
+
+/** The selected candidate's optional Pi thinking default, or `undefined`. */
+export function candidateThinking(config: JevRoutingConfig, model: string): string | undefined {
+  return config.models.find((entry) => entry.model === model)?.thinking;
+}
+
+/**
+ * Build frozen tool candidates from local tool metadata. Blank names are dropped and
+ * duplicate names keep the first description; no schema, source path or executable
+ * definition is retained.
+ */
+export function toToolCandidates(
+  tools: ReadonlyArray<{ name: string; description?: string }>,
+): readonly RoutingToolCandidate[] {
+  const seen = new Set<string>();
+  const candidates: RoutingToolCandidate[] = [];
+  for (const tool of tools) {
+    const name = typeof tool?.name === "string" ? tool.name.trim() : "";
+    if (!name || seen.has(name)) continue;
+    seen.add(name);
+    const description = typeof tool.description === "string" ? tool.description : "";
+    candidates.push(Object.freeze({ name, description }));
+  }
+  return Object.freeze(candidates);
+}
+
+function routingSummary(config: JevRoutingConfig): string[] {
+  const lines = [
+    "## Subagent routing (Jev / TypeSafe)",
+    "Every new task/tasks[] spawn, action:\"plan\" request, /btw, resume, fork and synthesis is routed by the Jev selector against the user's candidate-model list.",
+    "Do not pass model or fallback_models: those fields no longer select a route on new work and are rejected. Management actions (status/wait/cancel/steer/diff/apply/discard) never call the selector and need no credential.",
+    `Selector: ${config.selectorModel} (pin an exact version instead of the moving alias to make selection reproducible).`,
+    `Credential: environment variable ${config.apiKeyEnv}, read locally at request time; the value is never stored in config, prompts, logs or results.`,
+    `Logical selection deadline: ${config.timeoutMs} ms, covering all selector requests and waiting for one invocation.`,
+    "Only Pi-backed new dispatch is supported; native Codex/Claude new dispatches are rejected rather than routed.",
+    "Candidate models (exact IDs; the user's per-model characteristics are the matching criteria):",
+  ];
+  const listed = config.models.slice(0, MAX_GUIDANCE_MODEL_LINES);
+  for (const entry of listed) {
+    lines.push(`- ${entry.model}: thinking default ${entry.thinking ?? "(unset)"}`);
+  }
+  if (config.models.length > listed.length) {
+    lines.push(`- …and ${config.models.length - listed.length} more configured candidate(s); every configured candidate is eligible.`);
+  }
+  lines.push(
+    "The selector returns one execution model and an individual include/exclude decision per eligible tool. Unknown, unsafe or unavailable choices are rejected locally, and required Pi control-plane tools are added locally rather than chosen by the selector.",
+  );
+  return lines;
+}
+
+/**
+ * Model-facing guidance. Pure: renders correctly with no config and never reads the
+ * environment or performs inference, so management stays available while routing is
+ * missing or broken.
+ */
+export function formatJevRoutingPrompt(config: JevRoutingConfig | undefined, error?: string): string {
+  if (!config) {
+    return [
+      "## Subagent routing (Jev / TypeSafe)",
+      error || `No valid jevRouting configuration was found in ${JEV_ROUTING_CONFIG_FILE}.`,
+      "Management actions (status/wait/cancel/steer/diff/apply/discard) remain available, but every new task/tasks[] spawn, plan, /btw, resume, fork and synthesis is rejected until jevRouting is configured.",
+      "Add jevRouting with selectorModel, apiKeyEnv and 1-255 candidate model entries (exact provider/model IDs plus user-written characteristics, including Chinese). The credential itself is read from the named environment variable at request time and is never stored in the config file.",
+      "Do not pass model or fallback_models; the selector chooses the execution model and tools.",
+      "Use the package routing template; do not invent model IDs or import legacy modelPolicy entries automatically.",
+    ].join("\n");
+  }
+  return routingSummary(config).join("\n");
+}

package/src/routing-types.ts

@@ -0,0 +1,217 @@
+/**
+ * Shared Jev routing contract: DTOs, decisions, receipts and resource limits.
+ *
+ * This module deliberately has **no engine imports**. It must stay importable from the
+ * composition root, from route persistence/usage code, and from isolated offline harnesses
+ * without pulling in config, policy, registry or process code. Only Node builtins and the
+ * leaf `thinking.ts` helper may be used by dependants.
+ *
+ * Everything here describes the *selector boundary*. Local permission enforcement, profile
+ * filtering and mandatory Pi control-plane tools stay in `src/policy.ts` and the caller.
+ */
+
+/**
+ * Fixed official TypeSafe endpoint. The first version has no custom base URL, proxy or
+ * task-selected endpoint; the transport always uses this constant with `redirect:"error"`.
+ */
+export const TYPESAFE_SYSTEMONE_ENDPOINT = "https://api.typesafe.ai/v1/systemone";
+
+/** Stable alias default. An exact supported version may be pinned through config. */
+export const DEFAULT_SELECTOR_MODEL = "jev-latest";
+/** Environment variable that holds the TypeSafe credential. Never the credential value. */
+export const DEFAULT_API_KEY_ENV = "TYPESAFE_API_KEY";
+/** Default logical selection deadline in milliseconds. */
+export const DEFAULT_ROUTING_TIMEOUT_MS = 15_000;
+export const ROUTING_TIMEOUT_MIN_MS = 100;
+export const ROUTING_TIMEOUT_MAX_MS = 600_000;
+/** Dedicated candidate-model allowlist bounds (Choice supports up to 255 options). */
+export const MAX_ROUTING_MODELS = 255;
+/** Eligible tool questions per logical selection. */
+export const MAX_ROUTING_TOOL_QUESTIONS = 256;
+/** Serialized request bound (local resource limit, not an advertised provider token limit). */
+export const MAX_ROUTING_REQUEST_BYTES = 24 * 1024;
+/** Response body bound; larger bodies are rejected, never truncated. */
+export const MAX_ROUTING_RESPONSE_BYTES = 1024 * 1024;
+/** Concurrent selector HTTP requests across overlapping router calls. */
+export const DEFAULT_ROUTING_CONCURRENCY = 2;
+/** Documented tolerance for a Choice probability distribution summing to 1. */
+export const PROBABILITY_SUM_TOLERANCE = 0.02;
+/** Bounds for opaque identifier strings read from untrusted responses/config. */
+export const MAX_SELECTOR_VERSION_LENGTH = 128;
+export const MAX_ROUTING_MODEL_ID_LENGTH = 256;
+export const MAX_ROUTING_SELECTOR_MODEL_LENGTH = 128;
+
+/** Why this logical selection ran. Metadata only; never part of the HTTP DTO. */
+export type RoutingPurpose = "plan" | "dispatch" | "synthesis";
+/** Local execution profile the caller already enforced. */
+export type RoutingProfile = "explore" | "review" | "general";
+
+/**
+ * Stable machine-readable failure codes. Messages are safe for models and the TUI and never
+ * contain raw provider bodies, headers, credentials, task text or filesystem paths.
+ */
+export type RoutingFailureCode =
+  | "invalid_input"
+  | "missing_api_key"
+  | "no_candidate_models"
+  | "too_many_models"
+  | "too_many_tools"
+  | "request_too_large"
+  | "response_too_large"
+  | "transport_error"
+  | "timeout"
+  | "aborted"
+  | "unauthorized"
+  | "invalid_request"
+  | "rate_limited"
+  | "overloaded"
+  | "http_error"
+  | "malformed_response"
+  | "invalid_decision";
+
+/** Outcome of one actual HTTP attempt. */
+export type RoutingReceiptOutcome = "success" | "error" | "timeout" | "aborted";
+/** `unknown` is the honest state whenever tokens were not validly reported. */
+export type RoutingUsageStatus = "reported" | "unknown";
+
+/** One configured candidate model entry, owned by the user's `jevRouting` config. */
+export interface JevRoutingModelEntry {
+  /** Exact provider/model ID; no globs or Pi fuzzy-match patterns. */
+  readonly model: string;
+  /** User-written characteristics, including Chinese; the selector's matching criteria. */
+  readonly description: string;
+  /** Optional opaque Pi thinking default for this model. Local only, never a Jev question. */
+  readonly thinking?: string;
+}
+
+/**
+ * Immutable `jevRouting` snapshot parsed from the user config subtree.
+ * The credential value never appears here — only the environment-variable name.
+ */
+export interface JevRoutingConfig {
+  readonly selectorModel: string;
+  readonly apiKeyEnv: string;
+  readonly timeoutMs: number;
+  readonly models: readonly JevRoutingModelEntry[];
+}
+
+/** A candidate model that is both configured and locally eligible. */
+export interface RoutingModelCandidate {
+  readonly model: string;
+  readonly description: string;
+  readonly thinking?: string;
+}
+
+/**
+ * A tool offered to the selector. The caller must have already removed mandatory local
+ * additions (Pi control-plane tools) — those are never Jev questions.
+ */
+export interface RoutingToolCandidate {
+  readonly name: string;
+  readonly description: string;
+}
+
+/** Necessary typed constraints. Schema examples, paths and session IDs must not be added. */
+export interface RoutingConstraints {
+  readonly profile: RoutingProfile;
+  /** Opaque Pi thinking level requested by the task/agent/profile. */
+  readonly requestedThinking?: string;
+  readonly structuredOutput?: boolean;
+}
+
+/**
+ * The only routing input. It intentionally cannot carry a `TaskSpec`, `ParentContext`,
+ * agent config, system prompt, persona, tool schema or session identity.
+ */
+export interface RoutingSelectInput {
+  /** Current delegated task text only. */
+  readonly task: string;
+  /** Locally eligible candidate models, preserving the user's configured order. */
+  readonly models: readonly RoutingModelCandidate[];
+  /** Eligible non-mandatory tools; an empty/absent list means a model-only question. */
+  readonly tools?: readonly RoutingToolCandidate[];
+  readonly constraints?: RoutingConstraints;
+}
+
+/** Everything that is metadata or lifecycle, kept out of the HTTP DTO. */
+export interface RoutingSelectOptions {
+  readonly purpose: RoutingPurpose;
+  /** Zero-based task index for parallel/plan fanout; metadata only. */
+  readonly taskIndex?: number;
+  readonly signal?: AbortSignal;
+  /** Caller absolute deadline (epoch ms). The logical deadline is the smaller bound. */
+  readonly deadline?: number;
+}
+
+/**
+ * One receipt per **actual** HTTP attempt. `requestId` is always a full unique ID.
+ * Tokens are retained even when the decision is later rejected; when no valid usage was
+ * reported, `usageStatus` stays `unknown` rather than an invented zero.
+ */
+export interface RoutingReceipt {
+  readonly requestId: string;
+  readonly purpose: RoutingPurpose;
+  readonly taskIndex?: number;
+  /** Selector model requested (alias or pinned version). */
+  readonly selectorModel: string;
+  /** Actual selector version reported by a parseable response. */
+  readonly selectorVersion?: string;
+  readonly outcome: RoutingReceiptOutcome;
+  readonly code?: RoutingFailureCode;
+  readonly httpStatus?: number;
+  readonly durationMs: number;
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly usageStatus: RoutingUsageStatus;
+  /** TypeSafe reports tokens, not billed currency. Never inferred locally. */
+  readonly currency: "unknown";
+}
+
+/**
+ * A validated selection. `selectedTools` is the Jev-chosen subset only; the caller still
+ * applies local capability validation, adds mandatory Pi control-plane tools and recomputes
+ * writer capability.
+ */
+export interface RoutingDecision {
+  /** Unique logical decision ID, separate from every receipt/request ID. */
+  readonly decisionId: string;
+  readonly purpose: RoutingPurpose;
+  readonly taskIndex?: number;
+  readonly selectedModel: string;
+  readonly selectedTools: readonly string[];
+  /** Confidence of the model Choice. Diagnostic only; never a permission threshold. */
+  readonly confidence?: number;
+  readonly selectorModel: string;
+  /** Primary selector version: the version reported by the model response. */
+  readonly selectorVersion?: string;
+  /**
+   * Every distinct selector version observed across this selection, in first-seen order.
+   * A moving alias such as `jev-latest` may resolve differently between the model and tool
+   * requests; that is recorded, never treated as an error.
+   */
+  readonly selectorVersions: readonly string[];
+  /** Total logical selection latency, including all requests and waiting. */
+  readonly latencyMs: number;
+  /** Receipt IDs backing this decision, in issue order. */
+  readonly receiptIds: readonly string[];
+}
+
+/** Discriminated result: failures never throw and always return available receipts. */
+export type RoutingResult =
+  | {
+      readonly ok: true;
+      readonly decision: RoutingDecision;
+      readonly receipts: readonly RoutingReceipt[];
+      /**
+       * Safe, non-secret diagnostics when an injected receipt sink failed. Receipt tokens are
+       * still returned; the caller can retry persistence for the listed request IDs.
+       */
+      readonly persistenceErrors?: readonly string[];
+    }
+  | {
+      readonly ok: false;
+      readonly code: RoutingFailureCode;
+      readonly message: string;
+      readonly receipts: readonly RoutingReceipt[];
+      readonly persistenceErrors?: readonly string[];
+    };