@herbertgao/pi-extensions 2026.9.11 → 2026.9.13

package/node_modules/pi-mcp-adapter/jev-client.ts

@@ -0,0 +1,273 @@
+import { TypeSafeClient } from "@typesafe-ai/sdk";
+import type { McpExtensionState } from "./state.ts";
+import { isServerDisabled } from "./types.ts";
+import { combineAbortSignals } from "./runtime-owner.ts";
+import { resolveJevCredential, TYPESAFE_API_ORIGIN, type JevCredentialResolution } from "./jev-key-store.ts";
+import type { JevAnswer, JevBudget, JevEvaluateInput, JevEvaluationData, JevEvaluationEnvelope, JevJson, JevQuestion, ResolvedJevSettings } from "./jev-contracts.ts";
+
+export { TYPESAFE_API_ORIGIN };
+export type { ResolvedJevSettings } from "./jev-contracts.ts";
+
+const DEFAULTS: ResolvedJevSettings = {
+  semanticSearch: false, scriptEvaluation: false, allowedServers: [], model: "jev-1.13.0",
+  requestTimeoutMs: 5_000, maxRetries: 0, maxStateBytes: 262_144,
+  maxQuestionsPerRequest: 64, maxEvaluationsPerScript: 8,
+  maxEvaluationBytesPerScript: 524_288, maxEvaluationTokensPerScript: 32_768, semanticCandidateLimit: 127,
+  semanticMinProbability: 0.2,
+};
+const DANGEROUS_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+type JevSettingsInput = Partial<ResolvedJevSettings>;
+type Host = { client: TypeSafeClient };
+const hosts = new WeakMap<McpExtensionState, Host>();
+const credentials = new WeakMap<McpExtensionState, Extract<JevCredentialResolution, { status: "present" }>>();
+
+function resolveCredential(state: McpExtensionState): JevCredentialResolution {
+  const existing = credentials.get(state);
+  if (existing) return existing;
+  const credential = resolveJevCredential();
+  if (credential.status === "present") credentials.set(state, credential);
+  return credential;
+}
+
+export function areJevSourcesAllowed(state: McpExtensionState, settings: ResolvedJevSettings, sources: Iterable<string>): boolean {
+  for (const source of sources) {
+    const server = state.config.mcpServers[source];
+    if (!settings.allowedServers.includes(source) || !server || isServerDisabled(server)) return false;
+  }
+  return true;
+}
+
+function record(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) throw new Error(`${label} must be a plain object`);
+  return value as Record<string, unknown>;
+}
+function boolean(value: unknown, fallback: boolean, label: string): boolean {
+  if (value === undefined) return fallback;
+  if (typeof value !== "boolean") throw new Error(`${label} must be a boolean`);
+  return value;
+}
+function integer(value: unknown, fallback: number, min: number, max: number, label: string): number {
+  if (value === undefined) return fallback;
+  if (!Number.isInteger(value) || (value as number) < min || (value as number) > max) throw new Error(`${label} must be an integer from ${min} to ${max}`);
+  return value as number;
+}
+
+export function validateJevSettings(value: unknown): ResolvedJevSettings {
+  if (value === undefined || value === false) return { ...DEFAULTS, allowedServers: [...DEFAULTS.allowedServers] };
+  const input = record(value, "settings.jev") as JevSettingsInput;
+  const allowed = new Set(Object.keys(DEFAULTS));
+  for (const key of Object.keys(input)) if (!allowed.has(key)) throw new Error(`settings.jev.${key} is not supported`);
+  if (input.allowedServers !== undefined && (!Array.isArray(input.allowedServers) || input.allowedServers.some(name => typeof name !== "string" || name.length === 0 || DANGEROUS_KEYS.has(name) || /[\u0000-\u001f\u007f]/.test(name)))) {
+    throw new Error("settings.jev.allowedServers must contain non-empty safe server names");
+  }
+  const model = input.model ?? DEFAULTS.model;
+  if (typeof model !== "string" || model.length === 0 || model.length > 128 || /(?:latest|preview)/i.test(model)) throw new Error("settings.jev.model must be a pinned model name");
+  const probability = input.semanticMinProbability ?? DEFAULTS.semanticMinProbability;
+  if (typeof probability !== "number" || !Number.isFinite(probability) || probability < 0 || probability > 1) throw new Error("settings.jev.semanticMinProbability must be from 0 to 1");
+  return {
+    semanticSearch: boolean(input.semanticSearch, DEFAULTS.semanticSearch, "settings.jev.semanticSearch"),
+    scriptEvaluation: boolean(input.scriptEvaluation, DEFAULTS.scriptEvaluation, "settings.jev.scriptEvaluation"),
+    allowedServers: [...new Set(input.allowedServers ?? DEFAULTS.allowedServers)], model,
+    requestTimeoutMs: integer(input.requestTimeoutMs, DEFAULTS.requestTimeoutMs, 100, 30_000, "settings.jev.requestTimeoutMs"),
+    maxRetries: integer(input.maxRetries, DEFAULTS.maxRetries, 0, 2, "settings.jev.maxRetries"),
+    maxStateBytes: integer(input.maxStateBytes, DEFAULTS.maxStateBytes, 1, 1_048_576, "settings.jev.maxStateBytes"),
+    maxQuestionsPerRequest: integer(input.maxQuestionsPerRequest, DEFAULTS.maxQuestionsPerRequest, 1, 128, "settings.jev.maxQuestionsPerRequest"),
+    maxEvaluationsPerScript: integer(input.maxEvaluationsPerScript, DEFAULTS.maxEvaluationsPerScript, 1, 32, "settings.jev.maxEvaluationsPerScript"),
+    maxEvaluationBytesPerScript: integer(input.maxEvaluationBytesPerScript, DEFAULTS.maxEvaluationBytesPerScript, 1, 4_194_304, "settings.jev.maxEvaluationBytesPerScript"),
+    maxEvaluationTokensPerScript: integer(input.maxEvaluationTokensPerScript, DEFAULTS.maxEvaluationTokensPerScript, 1, 1_000_000, "settings.jev.maxEvaluationTokensPerScript"),
+    semanticCandidateLimit: integer(input.semanticCandidateLimit, DEFAULTS.semanticCandidateLimit, 2, 127, "settings.jev.semanticCandidateLimit"),
+    semanticMinProbability: probability,
+  };
+}
+
+export function resolveSemanticJevSettings(
+  state: McpExtensionState,
+  credentialResolver?: () => JevCredentialResolution,
+): ResolvedJevSettings {
+  const configured = state.config.settings?.jev;
+  const settings = validateJevSettings(configured);
+  if (configured === false || configured?.semanticSearch === false) return settings;
+  const semanticSearch = settings.semanticSearch || (credentialResolver ? credentialResolver() : resolveCredential(state)).status === "present";
+  const hasExplicitAllowlist = configured !== undefined && Object.hasOwn(configured, "allowedServers");
+  const allowedServers = hasExplicitAllowlist
+    ? settings.allowedServers
+    : Object.keys(state.config.mcpServers).filter((name) => !isServerDisabled(state.config.mcpServers[name]));
+  return { ...settings, semanticSearch, allowedServers };
+}
+
+function validateJson(value: unknown, path: string, seen = new Set<object>()): asserts value is JevJson {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number") { if (Number.isFinite(value)) return; throw new Error(`${path} contains a non-finite number`); }
+  if (typeof value !== "object") throw new Error(`${path} is not JSON-compatible`);
+  if (seen.has(value)) throw new Error(`${path} contains a cycle`);
+  seen.add(value);
+  if (Array.isArray(value)) value.forEach((item, index) => validateJson(item, `${path}[${index}]`, seen));
+  else {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) throw new Error(`${path} contains a non-plain object`);
+    for (const [key, item] of Object.entries(value)) {
+      if (DANGEROUS_KEYS.has(key)) throw new Error(`${path} contains an unsafe key`);
+      validateJson(item, `${path}.${key}`, seen);
+    }
+  }
+  seen.delete(value);
+}
+function validateId(id: string, label: string): void {
+  if (id.length === 0 || id.length > 128 || DANGEROUS_KEYS.has(id) || /[\u0000-\u001f\u007f]/.test(id)) throw new Error(`${label} contains an invalid identifier`);
+}
+function validateSource(source: string): void {
+  if (source.length === 0 || DANGEROUS_KEYS.has(source) || /[\u0000-\u001f\u007f]/.test(source)) throw new Error("sources contains an invalid server name");
+}
+function exactKeys(value: Record<string, unknown>, allowed: string[], label: string): void {
+  if (Object.keys(value).some(key => !allowed.includes(key))) throw new Error(`${label} contains unsupported fields`);
+}
+
+export function validateJevEvaluateInput(value: unknown, limits: ResolvedJevSettings): JevEvaluateInput {
+  const input = record(value, "Jev evaluation input");
+  exactKeys(input, ["state", "questions", "sources"], "Jev evaluation input");
+  if (!("state" in input)) throw new Error("Jev evaluation input requires state");
+  validateJson(input.state, "state");
+  const stateBytes = Buffer.byteLength(JSON.stringify(input.state));
+  if (stateBytes > limits.maxStateBytes) throw new Error("Jev state exceeds maxStateBytes");
+  const questions = record(input.questions, "questions");
+  const entries = Object.entries(questions);
+  if (entries.length < 1 || entries.length > limits.maxQuestionsPerRequest) throw new Error("Jev question count is outside the configured limit");
+  for (const [id, raw] of entries) {
+    validateId(id, "questions");
+    const question = record(raw, `question ${id}`);
+    if (question.type === "choice") {
+      exactKeys(question, ["type", "instructions", "criteria"], `question ${id}`);
+      const criteria = record(question.criteria, `question ${id} criteria`);
+      const labels = Object.keys(criteria);
+      if (labels.length < 2 || labels.length > 128) throw new Error(`question ${id} choice criteria must have 2 to 128 labels`);
+      for (const label of labels) { validateId(label, `question ${id} criteria`); validateJson(criteria[label], `question ${id} criteria.${label}`); }
+    } else if (question.type === "score") {
+      exactKeys(question, ["type", "instructions", "criteria"], `question ${id}`);
+      if (!Array.isArray(question.criteria) || question.criteria.length < 2 || question.criteria.length > 16) throw new Error(`question ${id} score criteria must have 2 to 16 entries`);
+      validateJson(question.criteria, `question ${id} criteria`);
+    } else if (question.type === "noul") {
+      exactKeys(question, ["type", "instructions", "criteria"], `question ${id}`);
+      if (question.criteria !== undefined) {
+        const criteria = record(question.criteria, `question ${id} criteria`);
+        exactKeys(criteria, ["true", "false"], `question ${id} criteria`);
+        validateJson(criteria, `question ${id} criteria`);
+      }
+    } else throw new Error(`question ${id} has an invalid type`);
+    if (question.instructions !== undefined) validateJson(question.instructions, `question ${id} instructions`);
+  }
+  let sources: string[] | undefined;
+  if (input.sources !== undefined) {
+    if (!Array.isArray(input.sources)) throw new Error("sources must be an array");
+    sources = input.sources.map((source, index) => { if (typeof source !== "string") throw new Error(`sources[${index}] must be a string`); validateSource(source); return source; });
+    if (new Set(sources).size !== sources.length) throw new Error("sources must not contain duplicates");
+  }
+  const normalized = { state: input.state, questions: questions as Record<string, JevQuestion>, ...(sources ? { sources } : {}) } as JevEvaluateInput;
+  if (Buffer.byteLength(JSON.stringify(normalized)) > limits.maxEvaluationBytesPerScript) throw new Error("Jev request exceeds the configured byte limit");
+  return normalized;
+}
+
+function safeNumber(value: unknown, label: string, integerOnly = false): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || (integerOnly && !Number.isInteger(value))) throw new Error(`Invalid ${label}`);
+  return value;
+}
+function probability(value: unknown, label: string): number {
+  const number = safeNumber(value, label);
+  if (number > 1) throw new Error(`Invalid ${label}`);
+  return number;
+}
+function sameKeys(actual: Record<string, unknown>, expected: string[]): boolean {
+  const keys = Object.keys(actual);
+  return keys.length === expected.length && expected.every(key => Object.hasOwn(actual, key));
+}
+function validateResponse(value: unknown, input: JevEvaluateInput): JevEvaluationData {
+  const response = record(value, "response");
+  exactKeys(response, ["model", "answers", "usage"], "response");
+  const answers = record(response.answers, "response answers");
+  const questionNames = Object.keys(input.questions);
+  if (!sameKeys(answers, questionNames)) throw new Error("Response answer keys do not match questions");
+  const validated: Record<string, JevAnswer> = {};
+  for (const name of questionNames) {
+    const question = input.questions[name]!;
+    const answer = record(answers[name], `answer ${name}`);
+    if (answer.type !== question.type) throw new Error(`Answer ${name} type does not match`);
+    if (question.type === "choice") {
+      exactKeys(answer, ["type", "choice", "confidence", "probabilities"], `answer ${name}`);
+      const labels = Object.keys(question.criteria);
+      if (typeof answer.choice !== "string" || !Object.hasOwn(question.criteria, answer.choice)) throw new Error(`Answer ${name} choice is invalid`);
+      const probabilities = record(answer.probabilities, `answer ${name} probabilities`);
+      if (!sameKeys(probabilities, labels)) throw new Error(`Answer ${name} probability keys are invalid`);
+      validated[name] = { type: "choice", choice: answer.choice, confidence: probability(answer.confidence, "confidence"), probabilities: Object.fromEntries(labels.map(label => [label, probability(probabilities[label], "probability")])) };
+    } else if (question.type === "score") {
+      exactKeys(answer, ["type", "score", "confidence", "probabilities", "legend"], `answer ${name}`);
+      const labels = question.criteria.map((_, index) => String(index));
+      const probabilities = record(answer.probabilities, `answer ${name} probabilities`);
+      if (!sameKeys(probabilities, labels)) throw new Error(`Answer ${name} probability keys are invalid`);
+      const score = safeNumber(answer.score, "score");
+      if (score > question.criteria.length - 1) throw new Error(`Answer ${name} score is invalid`);
+      validated[name] = { type: "score", score, confidence: probability(answer.confidence, "confidence"), probabilities: Object.fromEntries(labels.map(label => [label, probability(probabilities[label], "probability")])) };
+    } else {
+      exactKeys(answer, ["type", "noul"], `answer ${name}`);
+      validated[name] = { type: "noul", noul: probability(answer.noul, "noul") };
+    }
+  }
+  if (typeof response.model !== "string" || response.model.length === 0 || response.model.length > 128) throw new Error("Invalid response model");
+  const usage = record(response.usage, "response usage");
+  if (!sameKeys(usage, ["input_tokens", "output_tokens"])) throw new Error("Invalid response usage");
+  return { answers: validated, model: response.model, usage: { inputTokens: safeNumber(usage.input_tokens, "input tokens", true), outputTokens: safeNumber(usage.output_tokens, "output tokens", true) } };
+}
+
+function fixedOriginFetch(input: string, init?: RequestInit): Promise<Response> {
+  const url = new URL(input);
+  if (url.origin !== TYPESAFE_API_ORIGIN) throw new Error("TypeSafe request origin rejected");
+  return fetch(input, { ...init, redirect: "error" });
+}
+function getHost(state: McpExtensionState, settings: ResolvedJevSettings): Host | JevEvaluationEnvelope {
+  const existing = hosts.get(state);
+  if (existing) return existing;
+  const credential = resolveCredential(state);
+  if (credential.status === "missing") return { ok: false, error: { code: "credential_missing", message: "TypeSafe API key is not configured." } };
+  if (credential.status === "unavailable") return { ok: false, error: { code: "credential_unavailable", message: credential.message } };
+  const host = { client: new TypeSafeClient({ apiKey: credential.apiKey, baseURL: TYPESAFE_API_ORIGIN, defaultModel: settings.model, logLevel: "off", retry: { maxRetries: settings.maxRetries }, timeout: settings.requestTimeoutMs, defaultHeaders: {}, fetch: fixedOriginFetch }) };
+  hosts.set(state, host);
+  return host;
+}
+function failure(error: unknown, signal: AbortSignal | undefined, timedOut: boolean): JevEvaluationEnvelope {
+  if (timedOut) return { ok: false, error: { code: "timeout", message: "TypeSafe evaluation timed out.", retryable: true } };
+  if (signal?.aborted || (error instanceof Error && error.name === "APIUserAbortError")) return { ok: false, error: { code: "aborted", message: "TypeSafe evaluation was aborted." } };
+  const status = typeof error === "object" && error !== null && "status" in error ? (error as { status?: unknown }).status : undefined;
+  if (status === 401 || status === 403) return { ok: false, error: { code: "authentication_failed", message: "TypeSafe authentication failed." } };
+  if (status === 408) return { ok: false, error: { code: "timeout", message: "TypeSafe evaluation timed out.", retryable: true } };
+  if (status === 429) return { ok: false, error: { code: "rate_limited", message: "TypeSafe rate limit exceeded.", retryable: true } };
+  if (typeof status === "number" && status >= 500) return { ok: false, error: { code: "service_unavailable", message: "TypeSafe service is unavailable.", retryable: true } };
+  if (status === 400 || status === 422) return { ok: false, error: { code: "invalid_request", message: "TypeSafe rejected the evaluation request." } };
+  if (error instanceof Error && (error.name === "APIConnectionError" || error.name === "APITimeoutError")) return { ok: false, error: { code: "service_unavailable", message: "TypeSafe service is unavailable.", retryable: true } };
+  return { ok: false, error: { code: "invalid_response", message: "TypeSafe returned an invalid response." } };
+}
+
+export async function evaluateJev(state: McpExtensionState, value: JevEvaluateInput, options: { purpose: "script" | "semantic-search"; signal?: AbortSignal; budget?: JevBudget; observedSources?: readonly string[] }): Promise<JevEvaluationEnvelope> {
+  let settings: ResolvedJevSettings;
+  let input: JevEvaluateInput;
+  try { settings = options.purpose === "semantic-search" ? resolveSemanticJevSettings(state) : validateJevSettings(state.config.settings?.jev); input = validateJevEvaluateInput(value, settings); }
+  catch { return { ok: false, error: { code: "invalid_request", message: "Invalid TypeSafe evaluation request or settings." } }; }
+  if ((options.purpose === "script" && !settings.scriptEvaluation) || (options.purpose === "semantic-search" && !settings.semanticSearch)) return { ok: false, error: { code: "disabled", message: "TypeSafe evaluation is disabled." } };
+  const sources = new Set([...(input.sources ?? []), ...(options.observedSources ?? [])]);
+  if (!areJevSourcesAllowed(state, settings, sources)) return { ok: false, error: { code: "data_policy_denied", message: "Evaluation sources are not allowed by policy." } };
+  const bytes = Buffer.byteLength(JSON.stringify(input));
+  if (options.budget && !options.budget.consume(bytes)) return { ok: false, error: { code: "budget_exhausted", message: "TypeSafe evaluation budget exhausted." } };
+  const resolved = getHost(state, settings);
+  if (!("client" in resolved)) return resolved;
+  const deadline = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => { timedOut = true; deadline.abort(new Error("TypeSafe evaluation deadline exceeded")); }, settings.requestTimeoutMs);
+  const signal = combineAbortSignals(options.signal, state.owner.signal, deadline.signal);
+  try {
+    const request = { state: input.state, questions: input.questions, model: settings.model };
+    const raw = await resolved.client.systemOne(request as Parameters<TypeSafeClient["systemOne"]>[0], { ...(signal ? { signal } : {}), timeout: settings.requestTimeoutMs, retry: { maxRetries: settings.maxRetries } });
+    try { return { ok: true, data: validateResponse(raw, input) }; }
+    catch { return { ok: false, error: { code: "invalid_response", message: "TypeSafe returned an invalid response." } }; }
+  } catch (error) { return failure(error, signal, timedOut); }
+  finally { clearTimeout(timer); }
+}

package/node_modules/pi-mcp-adapter/jev-contracts.ts

@@ -0,0 +1,53 @@
+export type JevJson = null | boolean | number | string | JevJson[] | { [key: string]: JevJson };
+
+export type JevQuestion =
+  | { type: "choice"; instructions?: JevJson; criteria: Record<string, JevJson> }
+  | { type: "score"; instructions?: JevJson; criteria: [JevJson, JevJson, ...JevJson[]] }
+  | { type: "noul"; instructions?: JevJson; criteria?: { true?: JevJson; false?: JevJson } };
+
+export interface JevEvaluateInput {
+  state: JevJson;
+  questions: Record<string, JevQuestion>;
+  /** MCP servers whose metadata/results were copied into state. Empty/omitted means no MCP-derived data. */
+  sources?: string[];
+}
+
+export type JevAnswer =
+  | { type: "choice"; choice: string; confidence: number; probabilities: Record<string, number> }
+  | { type: "score"; score: number; confidence: number; probabilities: Record<string, number> }
+  | { type: "noul"; noul: number };
+
+export interface JevEvaluationData {
+  answers: Record<string, JevAnswer>;
+  model: string;
+  usage: { inputTokens: number; outputTokens: number };
+}
+
+export type JevErrorCode =
+  | "disabled" | "invalid_request" | "data_policy_denied" | "budget_exhausted"
+  | "credential_missing" | "credential_unavailable" | "authentication_failed"
+  | "timeout" | "aborted" | "rate_limited" | "service_unavailable" | "invalid_response";
+
+export type JevEvaluationEnvelope =
+  | { ok: true; data: JevEvaluationData }
+  | { ok: false; error: { code: JevErrorCode; message: string; retryable?: boolean } };
+
+export interface ResolvedJevSettings {
+  semanticSearch: boolean;
+  scriptEvaluation: boolean;
+  allowedServers: string[];
+  model: string;
+  requestTimeoutMs: number;
+  maxRetries: number;
+  maxStateBytes: number;
+  maxQuestionsPerRequest: number;
+  maxEvaluationsPerScript: number;
+  maxEvaluationBytesPerScript: number;
+  maxEvaluationTokensPerScript: number;
+  semanticCandidateLimit: number;
+  semanticMinProbability: number;
+}
+
+export interface JevBudget {
+  consume(bytes: number): boolean;
+}

package/node_modules/pi-mcp-adapter/jev-key-store.ts

@@ -0,0 +1,79 @@
+import { createSecureKeyringStore, type SecureKeyringStore } from "./secure-keyring.ts";
+
+export const TYPESAFE_API_ORIGIN = "https://api.typesafe.ai";
+export const JEV_KEYRING_SERVICE = "pi-mcp-adapter.service-key";
+export const JEV_KEYRING_ACCOUNT = "typesafe@sha256(https://api.typesafe.ai)";
+
+interface StoredJevKey {
+  version: 1;
+  provider: "typesafe";
+  origin: typeof TYPESAFE_API_ORIGIN;
+  apiKey: string;
+}
+
+export class JevCredentialStoreError extends Error {
+  readonly code = "JEV_CREDENTIAL_STORE_UNAVAILABLE";
+  constructor(readonly operation: "read" | "write" | "remove", cause: unknown) {
+    super(`TypeSafe API key secure credential store unavailable during ${operation}. Configure or unlock the OS credential store and retry.`, { cause });
+    this.name = "JevCredentialStoreError";
+  }
+}
+
+export type JevCredentialResolution =
+  | { status: "present"; source: "environment" | "keyring"; apiKey: string }
+  | { status: "missing" }
+  | { status: "unavailable"; message: string };
+
+function validateApiKey(value: unknown): string {
+  if (typeof value !== "string" || value.trim().length === 0 || /[\u0000-\u001f\u007f]/.test(value)) {
+    throw new Error("TypeSafe API key must be a non-empty string without control characters");
+  }
+  return value;
+}
+
+function store(): SecureKeyringStore {
+  return createSecureKeyringStore(JEV_KEYRING_SERVICE);
+}
+
+function readStoredKey(secretStore: SecureKeyringStore = store()): string | undefined {
+  let payload: string | undefined;
+  try { payload = secretStore.read(JEV_KEYRING_ACCOUNT); }
+  catch (error) { throw new JevCredentialStoreError("read", error); }
+  if (payload === undefined) return undefined;
+  try {
+    const value: unknown = JSON.parse(payload);
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid record");
+    const record = value as Partial<StoredJevKey>;
+    const keys = Object.keys(record);
+    if (keys.length !== 4 || !["version", "provider", "origin", "apiKey"].every(key => Object.hasOwn(record, key))) throw new Error("invalid record fields");
+    if (record.version !== 1 || record.provider !== "typesafe" || record.origin !== TYPESAFE_API_ORIGIN) throw new Error("invalid or mismatched record");
+    return validateApiKey(record.apiKey);
+  } catch (error) {
+    throw new JevCredentialStoreError("read", error);
+  }
+}
+
+export function resolveJevCredential(env: NodeJS.ProcessEnv = process.env, secretStore?: SecureKeyringStore): JevCredentialResolution {
+  if (Object.hasOwn(env, "TYPESAFE_API_KEY")) {
+    try { return { status: "present", source: "environment", apiKey: validateApiKey(env.TYPESAFE_API_KEY) }; }
+    catch { return { status: "unavailable", message: "TYPESAFE_API_KEY is present but invalid." }; }
+  }
+  try {
+    const apiKey = readStoredKey(secretStore ?? store());
+    return apiKey === undefined ? { status: "missing" } : { status: "present", source: "keyring", apiKey };
+  } catch (error) {
+    if (!(error instanceof JevCredentialStoreError)) throw error;
+    return { status: "unavailable", message: error.message };
+  }
+}
+
+export function saveJevApiKey(apiKey: string, secretStore: SecureKeyringStore = store()): void {
+  const record: StoredJevKey = { version: 1, provider: "typesafe", origin: TYPESAFE_API_ORIGIN, apiKey: validateApiKey(apiKey) };
+  try { secretStore.write(JEV_KEYRING_ACCOUNT, JSON.stringify(record)); }
+  catch (error) { throw new JevCredentialStoreError("write", error); }
+}
+
+export function removeJevApiKey(secretStore: SecureKeyringStore = store()): void {
+  try { secretStore.remove(JEV_KEYRING_ACCOUNT); }
+  catch (error) { throw new JevCredentialStoreError("remove", error); }
+}

package/node_modules/pi-mcp-adapter/lifecycle.ts

@@ -1,6 +1,11 @@
 import { SdkError, SdkErrorCode } from "@modelcontextprotocol/client";
 import { isServerDisabled, type ServerDefinition } from "./types.ts";
-import { isTransientHttpConnectError, type McpServerManager, type ServerConnection } from "./server-manager.ts";
+import {
+  isTransientHttpConnectError,
+  isUnauthorizedHttpError,
+  type McpServerManager,
+  type ServerConnection,
+} from "./server-manager.ts";
 import { hasPendingAuth } from "./mcp-auth-flow.ts";
 import { logger } from "./logger.ts";
 import { formatTerminalError, parallelLimit, sanitizeTerminalText } from "./utils.ts";
@@ -223,7 +228,7 @@ export class McpLifecycleManager {
         await this.handleSupersededConnection(name, definition, connection, signal, retrySuperseded);
         return;
       }
-      if (!shouldReconnectAfterRefresh(error, hadSessionId)) {
+      if (!shouldReconnectAfterRefresh(error, hadSessionId, definition)) {
         this.reportConnectionFailure(name, definition, error, "refresh", connection);
         return;
       }
@@ -439,8 +444,14 @@ export class McpLifecycleManager {
   }
 }
 
-function shouldReconnectAfterRefresh(error: unknown, hadSessionId: boolean): boolean {
+function shouldReconnectAfterRefresh(
+  error: unknown,
+  hadSessionId: boolean,
+  definition: ServerDefinition,
+): boolean {
   if (isTerminatedSession(error, hadSessionId)) return true;
+  // Reconnect baked bearer sources so connect-time resolution runs again.
+  if (definition.auth === "bearer" && isUnauthorizedHttpError(error)) return true;
   return error instanceof SdkError
     && (error.code === SdkErrorCode.NotConnected || error.code === SdkErrorCode.ConnectionClosed);
 }

package/node_modules/pi-mcp-adapter/mcp-bearer-store.ts

@@ -1,16 +1,5 @@
 import { createHash } from "node:crypto";
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-
-type KeyringEntry = {
-  getPassword(): string | null;
-  setPassword(password: string): void;
-  deleteCredential(): boolean;
-};
-
-type KeyringEntryConstructor = new (service: string, account: string) => KeyringEntry;
-type KeyringModule = { Entry: KeyringEntryConstructor };
-type KeyringRequire = ((id: string) => unknown) & { resolve(id: string): string };
+import { createSecureKeyringStore, getTestSecureKeyringEntries, getTestSecureKeyringReadCount, removeTestSecureKeyringEntry, resetTestSecureKeyring, setTestSecureKeyringEntry } from "./secure-keyring.ts";
 
 type BearerSecretStore = {
   read(account: string): string | undefined;
@@ -29,15 +18,8 @@ interface BearerChunkManifest {
   chunkDigest: string;
 }
 
-const require = createRequire(import.meta.url);
 const BEARER_SECRET_SERVICE = "pi-mcp-adapter.bearer";
-const TEST_AUTH_STORE_ENV = "PI_MCP_ADAPTER_TEST_AUTH_STORE";
 const BEARER_SECRET_CHUNK_SIZE = 1000;
-const BEARER_SECRET_VALUE_LIMIT = 1280;
-
-let KeyringEntryClass: KeyringEntryConstructor | undefined;
-const memoryBearerEntries = new Map<string, string>();
-let testBearerSecretStoreReadCount = 0;
 
 export class BearerCredentialStoreError extends Error {
   readonly code = "BEARER_CREDENTIAL_STORE_UNAVAILABLE";
@@ -56,124 +38,8 @@ export type BearerCredentialStatus =
   | { status: "url-mismatch" }
   | { status: "unavailable"; message: string };
 
-const memoryBearerSecretStore: BearerSecretStore = {
-  read(account) {
-    testBearerSecretStoreReadCount++;
-    return memoryBearerEntries.get(account);
-  },
-  write(account, payload) {
-    memoryBearerEntries.set(account, payload);
-  },
-  remove(account) {
-    memoryBearerEntries.delete(account);
-  },
-};
-
-const sizeLimitedBearerSecretStore: BearerSecretStore = {
-  read(account) {
-    testBearerSecretStoreReadCount++;
-    return memoryBearerEntries.get(account);
-  },
-  write(account, payload) {
-    if (payload.length > BEARER_SECRET_VALUE_LIMIT) {
-      throw new Error(`Value of 'password encoded as UTF-16' is longer than the platform limit of ${BEARER_SECRET_VALUE_LIMIT * 2} chars`);
-    }
-    memoryBearerEntries.set(account, payload);
-  },
-  remove(account) {
-    memoryBearerEntries.delete(account);
-  },
-};
-
-const unavailableBearerSecretStore: BearerSecretStore = {
-  read() {
-    testBearerSecretStoreReadCount++;
-    throw new Error("simulated secure credential store unavailable");
-  },
-  write() {
-    throw new Error("simulated secure credential store unavailable");
-  },
-  remove() {
-    throw new Error("simulated secure credential store unavailable");
-  },
-};
-
-const keyringBearerSecretStore: BearerSecretStore = {
-  read(account) {
-    return getKeyringEntry(account).getPassword() ?? undefined;
-  },
-  write(account, payload) {
-    getKeyringEntry(account).setPassword(payload);
-  },
-  remove(account) {
-    getKeyringEntry(account).deleteCredential();
-  },
-};
-
 function getBearerSecretStore(): BearerSecretStore {
-  if (process.env[TEST_AUTH_STORE_ENV] === "memory") return memoryBearerSecretStore;
-  if (process.env[TEST_AUTH_STORE_ENV] === "sizelimited") return sizeLimitedBearerSecretStore;
-  if (process.env[TEST_AUTH_STORE_ENV] === "unavailable") return unavailableBearerSecretStore;
-  return keyringBearerSecretStore;
-}
-
-function getKeyringEntry(account: string): KeyringEntry {
-  try {
-    KeyringEntryClass ??= loadKeyringEntryClass();
-    return new KeyringEntryClass(BEARER_SECRET_SERVICE, account);
-  } catch (error) {
-    throw new Error("Bearer token secure credential storage is unavailable. Configure the OS credential store and retry.", { cause: error });
-  }
-}
-
-function loadKeyringEntryClass(keyringRequire: KeyringRequire = require, platform: NodeJS.Platform = process.platform, arch: NodeJS.Architecture = process.arch): KeyringEntryConstructor {
-  try {
-    return (keyringRequire("@napi-rs/keyring") as KeyringModule).Entry;
-  } catch (loaderError) {
-    try {
-      return loadKeyringNativeBindingFallback(keyringRequire, platform, arch).Entry;
-    } catch (fallbackError) {
-      const message = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
-      throw new Error(`Failed to load @napi-rs/keyring; absolute-path native binding fallback also failed: ${message}`, { cause: loaderError });
-    }
-  }
-}
-
-function loadKeyringNativeBindingFallback(keyringRequire: KeyringRequire, platform: NodeJS.Platform, arch: NodeJS.Architecture): KeyringModule {
-  const targets = getKeyringNativeBindingSuffixes(platform, arch).map(suffix => ({
-    packageName: `@napi-rs/keyring-${suffix}`,
-    bindingFile: `keyring.${suffix}.node`,
-  }));
-  let lastError: unknown;
-  for (const target of targets) {
-    try {
-      const packageJsonPath = keyringRequire.resolve(`${target.packageName}/package.json`);
-      return keyringRequire(join(dirname(packageJsonPath), target.bindingFile)) as KeyringModule;
-    } catch (error) {
-      lastError = error;
-    }
-  }
-  throw lastError instanceof Error ? lastError : new Error(String(lastError));
-}
-
-function getKeyringNativeBindingSuffixes(platform: NodeJS.Platform, arch: NodeJS.Architecture): string[] {
-  if (platform === "darwin") {
-    if (arch === "arm64") return ["darwin-arm64"];
-    if (arch === "x64") return ["darwin-x64"];
-  }
-  if (platform === "win32") {
-    if (arch === "arm64") return ["win32-arm64-msvc"];
-    if (arch === "x64") return ["win32-x64-msvc"];
-    if (arch === "ia32") return ["win32-ia32-msvc"];
-  }
-  if (platform === "linux") {
-    if (arch === "arm64") return ["linux-arm64-gnu", "linux-arm64-musl"];
-    if (arch === "arm") return ["linux-arm-gnueabihf"];
-    if (arch === "riscv64") return ["linux-riscv64-gnu"];
-    if (arch === "x64") return ["linux-x64-gnu", "linux-x64-musl"];
-  }
-  if (platform === "freebsd" && arch === "x64") return ["freebsd-x64"];
-  return [];
+  return createSecureKeyringStore(BEARER_SECRET_SERVICE);
 }
 
 function getBearerAccount(serverName: string): string {
@@ -364,22 +230,21 @@ export function inspectBearerTokenForUrl(serverName: string, serverUrl: string):
 }
 
 export function resetTestBearerTokenStore(): void {
-  memoryBearerEntries.clear();
-  testBearerSecretStoreReadCount = 0;
+  resetTestSecureKeyring();
 }
 
 export function getTestBearerTokenStoreEntries(): [string, string][] {
-  return [...memoryBearerEntries.entries()];
+  return getTestSecureKeyringEntries().filter(([key]) => key.startsWith(`${BEARER_SECRET_SERVICE}\0`)).map(([key, value]) => [key.slice(BEARER_SECRET_SERVICE.length + 1), value]);
 }
 
 export function removeTestBearerTokenStoreEntry(account: string): void {
-  memoryBearerEntries.delete(account);
+  removeTestSecureKeyringEntry(BEARER_SECRET_SERVICE, account);
 }
 
 export function setTestBearerTokenStoreEntry(account: string, payload: string): void {
-  memoryBearerEntries.set(account, payload);
+  setTestSecureKeyringEntry(BEARER_SECRET_SERVICE, account, payload);
 }
 
 export function getTestBearerTokenStoreReadCount(): number {
-  return testBearerSecretStoreReadCount;
+  return getTestSecureKeyringReadCount();
 }