@herbertgao/pi-extensions 2026.9.7 → 2026.9.9

package/node_modules/pi-typesafe/dist/client.js

@@ -0,0 +1,188 @@
+import { TypeSafeClient } from "@typesafe-ai/sdk";
+import { recordAuthFailure, recordAuthVerified } from "./auth.js";
+import { evaluateAll, evaluateMany } from "./batch.js";
+import { keySituation } from "./credentials.js";
+import { TypeSafeIntegrationError, safeError } from "./errors.js";
+import { DEFAULT_MAX_INPUT_BYTES, assertWithinByteLimit, prepareEvaluationRequest } from "./schema.js";
+import { DEFAULT_USD_PER_MTOK, capsFromEnvironment, estimateUsd, mergeCaps, openUsageLedger } from "./usage.js";
+/** Default attempts per client instance; the extension quotes the same number in its consent copy. */
+export const DEFAULT_MAX_REQUESTS = 20;
+function positiveInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new TypeSafeIntegrationError("configuration", `${label} must be a positive safe integer.`);
+    }
+    return value;
+}
+function positiveNumber(value, label) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new TypeSafeIntegrationError("configuration", `${label} must be a positive number.`);
+    }
+    return value;
+}
+function validResult(result, questions) {
+    const probability = (value) => Number.isFinite(value) && value >= 0 && value <= 1;
+    if (!result || typeof result.model !== "string" || !result.model || !result.usage || !result.answers)
+        return false;
+    for (const count of [result.usage.input_tokens, result.usage.output_tokens]) {
+        if (!Number.isSafeInteger(count) || count < 0)
+            return false;
+    }
+    if (Object.keys(result.answers).length !== Object.keys(questions).length)
+        return false;
+    for (const [id, question] of Object.entries(questions)) {
+        const answer = result.answers[id];
+        if (!answer || answer.type !== question.type)
+            return false;
+        if (answer.type === "noul") {
+            if (!probability(answer.noul))
+                return false;
+            continue;
+        }
+        if (!probability(answer.confidence) || !answer.probabilities)
+            return false;
+        const keys = question.type === "choice" ? Object.keys(question.criteria)
+            : question.type === "score" ? question.criteria.map((_, index) => String(index)) : [];
+        const probabilities = new Map(Object.entries(answer.probabilities));
+        if (probabilities.size !== keys.length || keys.some(key => !probability(probabilities.get(key) ?? NaN)))
+            return false;
+        if (answer.type === "choice" && !keys.includes(answer.choice))
+            return false;
+        if (answer.type === "score" && (!Number.isFinite(answer.score) || answer.score < 0 || answer.score > keys.length - 1 || !answer.legend))
+            return false;
+    }
+    return true;
+}
+const CAP_LABELS = {
+    requestsPerDay: "daily request cap",
+    inputTokensPerDay: "daily input-token cap",
+    usdPerDay: "daily spend cap",
+};
+function capsDescription(caps) {
+    const parts = [
+        caps.maxRequests === undefined ? undefined : `${caps.maxRequests} per session`,
+        caps.maxRequestsPerDay === undefined ? undefined : `${caps.maxRequestsPerDay} requests per day`,
+        caps.maxInputTokensPerDay === undefined ? undefined : `${caps.maxInputTokensPerDay} input tokens per day`,
+        caps.maxUsdPerDay === undefined ? undefined : `$${caps.maxUsdPerDay} per day`,
+    ].filter((part) => part !== undefined);
+    return parts.length ? `Caps: ${parts.join(", ")}.` : "No request or spend caps are set.";
+}
+/** A bounded, server-side TypeSafe client independent of Pi's runtime. */
+export function createTypeSafe(options = {}) {
+    let apiKey = options.apiKey?.trim();
+    if (!apiKey) {
+        const situation = keySituation();
+        if (situation.kind === "unusable")
+            throw new TypeSafeIntegrationError("configuration", situation.reason);
+        if (situation.kind === "environment" || situation.kind === "stored")
+            apiKey = situation.key;
+    }
+    if (!apiKey)
+        throw new TypeSafeIntegrationError("configuration", "No TypeSafe API key. Run /typesafe login in Pi, or set TYPESAFE_API_KEY in the environment.");
+    const timeout = positiveInteger(options.timeoutMs ?? 15_000, "timeoutMs");
+    const maxInputBytes = positiveInteger(options.maxInputBytes ?? DEFAULT_MAX_INPUT_BYTES, "maxInputBytes");
+    const maxRequests = positiveInteger(options.maxRequests ?? DEFAULT_MAX_REQUESTS, "maxRequests");
+    const usdPerMTok = positiveNumber(options.usdPerMTok ?? DEFAULT_USD_PER_MTOK, "usdPerMTok");
+    const caps = mergeCaps({
+        maxRequests,
+        ...(options.maxRequestsPerDay === undefined ? {} : { maxRequestsPerDay: positiveInteger(options.maxRequestsPerDay, "maxRequestsPerDay") }),
+        ...(options.maxInputTokensPerDay === undefined ? {} : { maxInputTokensPerDay: positiveInteger(options.maxInputTokensPerDay, "maxInputTokensPerDay") }),
+        ...(options.maxUsdPerDay === undefined ? {} : { maxUsdPerDay: positiveNumber(options.maxUsdPerDay, "maxUsdPerDay") }),
+    }, capsFromEnvironment());
+    const model = options.model ?? "jev-latest";
+    if (typeof model !== "string" || !model.trim() || model.length > 100)
+        throw new TypeSafeIntegrationError("configuration", "model must be a nonempty string of at most 100 characters.");
+    // Do not inherit SDK debug logging or alternate destinations from the environment.
+    const client = new TypeSafeClient({
+        apiKey,
+        defaultModel: model,
+        baseURL: "https://api.typesafe.ai",
+        timeout,
+        retry: { maxRetries: 0 },
+        logLevel: "off",
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+    });
+    const ledger = options.ledger ?? openUsageLedger({ usdPerMTok });
+    const usage = { requestsStarted: 0, requestsSucceeded: 0, requestsFailed: 0, inputTokens: 0, outputTokens: 0 };
+    // Auth state writes are deduplicated: one verification record per process, one record per distinct failure.
+    let verificationRecorded = false;
+    let lastFailureRecorded;
+    const snapshot = () => ({ ...usage, estimatedUsd: estimateUsd(usage.inputTokens, usdPerMTok) });
+    const blocked = () => (usage.requestsStarted >= maxRequests ? undefined : ledger.blocked(caps));
+    const typesafe = {
+        getUsage: snapshot,
+        getSpend: () => {
+            const reached = blocked();
+            return {
+                session: snapshot(),
+                today: ledger.today(),
+                caps,
+                usdPerMTok,
+                ...(reached === undefined ? {} : { blocked: reached }),
+            };
+        },
+        async listModels(callOptions = {}) {
+            try {
+                const models = await client.models.list(callOptions);
+                if (!Array.isArray(models))
+                    throw new TypeSafeIntegrationError("response", "TypeSafe returned an unexpected model list.");
+                if (!verificationRecorded) {
+                    verificationRecorded = true;
+                    recordAuthVerified();
+                }
+                return models.map(card => card?.name).filter((name) => typeof name === "string" && name.length > 0 && name.length <= 100);
+            }
+            catch (error) {
+                throw safeError(error);
+            }
+        },
+        async evaluate(input, callOptions = {}) {
+            const validated = prepareEvaluationRequest(input, { maxInputBytes });
+            const body = JSON.stringify({ ...validated, model: validated.model ?? model });
+            assertWithinByteLimit(body, maxInputBytes);
+            if (callOptions.signal?.aborted)
+                throw new TypeSafeIntegrationError("aborted", "TypeSafe request cancelled before submission.");
+            if (usage.requestsStarted >= maxRequests) {
+                throw new TypeSafeIntegrationError("budget", `TypeSafe request limit reached (${maxRequests} attempts per client instance). ${capsDescription(caps)}`);
+            }
+            const reached = ledger.blocked(caps);
+            if (reached) {
+                // Name the cap, the used amount, and the day, so a long run stops loudly instead of burning tokens unnoticed.
+                throw new TypeSafeIntegrationError("budget", `TypeSafe ${CAP_LABELS[reached.cap]} reached (${reached.used} of ${reached.limit} on ${reached.day}); no request was submitted. Requests resume after the local day rolls over, or raise the cap deliberately.`);
+            }
+            // Snapshot before awaiting so later mutations cannot change the request or validation.
+            const request = JSON.parse(body);
+            usage.requestsStarted += 1;
+            ledger.recordStart();
+            const start = performance.now();
+            try {
+                const result = await client.systemOne(request, callOptions);
+                if (!validResult(result, request.questions))
+                    throw new TypeSafeIntegrationError("response", "TypeSafe returned an unexpected answer or usage format.");
+                usage.requestsSucceeded += 1;
+                usage.inputTokens += result.usage.input_tokens;
+                usage.outputTokens += result.usage.output_tokens;
+                ledger.recordSuccess(result.usage.input_tokens, result.usage.output_tokens);
+                if (!verificationRecorded) {
+                    verificationRecorded = true;
+                    recordAuthVerified();
+                }
+                return { ...result, elapsedMs: Math.round(performance.now() - start) };
+            }
+            catch (error) {
+                const safe = safeError(error);
+                // The request was submitted, so it counts even when it fails; the reason stays visible in `authState()`.
+                usage.requestsFailed += 1;
+                ledger.recordFailure();
+                const fingerprint = `${safe.code}:${safe.status ?? ""}:${safe.message}`;
+                if (lastFailureRecorded !== fingerprint) {
+                    lastFailureRecorded = fingerprint;
+                    recordAuthFailure(safe);
+                }
+                throw safe;
+            }
+        },
+        evaluateMany: (requests, batchOptions = {}) => evaluateMany(typesafe, requests, batchOptions),
+        evaluateAll: (request, batchOptions = {}) => evaluateAll(typesafe, request, batchOptions),
+    };
+    return typesafe;
+}

package/node_modules/pi-typesafe/dist/credentials.d.ts

@@ -0,0 +1,46 @@
+export type KeySource = "environment" | "stored";
+/** The complete, never-throwing answer to "which key is in effect". */
+export type KeySituation = {
+    readonly kind: "environment";
+    readonly key: string;
+} | {
+    readonly kind: "stored";
+    readonly key: string;
+    readonly path: string;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "unusable";
+    readonly path: string;
+    readonly reason: string;
+};
+/** Mirrors Pi's agent directory rule; every pi-typesafe file lives in this one directory. */
+export declare function piTypesafeDir(): string;
+/** Where the key lives, next to Pi's own auth.json. */
+export declare function credentialsPath(): string;
+/** Accepts the key only when it is a plausible token; never logs or echoes the value. */
+export declare function normalizeApiKey(value: unknown): string;
+/**
+ * The stored key, or `undefined` when the file is missing, unreadable, or holds no usable value. Throws
+ * `configuration` when the file is readable by other users; keySituation() reports that case as `unusable` instead.
+ */
+export declare function readStoredApiKey(): string | undefined;
+/**
+ * What the environment, the login store, and file permissions add up to right now. Never throws; the "unusable" kind
+ * carries the user-facing reason (a stored key that other local users can read).
+ */
+export declare function keySituation(): KeySituation;
+/** Short phrase naming the source; full sentences stay with the caller. */
+export declare function keySourceLabel(situation: KeySituation): string;
+/**
+ * The pre-0.4.0 key interface, frozen for existing callers: environment first so CI and scripts stay explicit, the
+ * stored key as the interactive default, `undefined` when no key is configured, and a `configuration` error when a
+ * store must not be read. New code should call keySituation() instead: same precedence, never throws, and the
+ * "must not be read" case arrives as `unusable` with the reason.
+ */
+export declare function resolveApiKey(): {
+    key: string;
+    source: KeySource;
+} | undefined;
+export declare function storeApiKey(value: unknown): string;
+export declare function clearStoredApiKey(): boolean;

package/node_modules/pi-typesafe/dist/credentials.js

@@ -0,0 +1,112 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { TypeSafeIntegrationError } from "./errors.js";
+/** Mirrors Pi's agent directory rule; every pi-typesafe file lives in this one directory. */
+export function piTypesafeDir() {
+    const configured = process.env.PI_CODING_AGENT_DIR?.trim();
+    const agentDir = configured
+        ? (configured === "~" || configured.startsWith("~/") ? join(homedir(), configured.slice(1)) : configured)
+        : join(homedir(), ".pi", "agent");
+    return join(agentDir, "pi-typesafe");
+}
+/** Where the key lives, next to Pi's own auth.json. */
+export function credentialsPath() {
+    return join(piTypesafeDir(), "auth.json");
+}
+/** Accepts the key only when it is a plausible token; never logs or echoes the value. */
+export function normalizeApiKey(value) {
+    const key = typeof value === "string" ? value.trim() : "";
+    if (key.length < 16 || key.length > 512 || /\s/.test(key) || /[^\x21-\x7e]/.test(key)) {
+        throw new TypeSafeIntegrationError("validation", "That does not look like a TypeSafe API key. Copy the complete key from console.typesafe.ai and try again; nothing was saved.");
+    }
+    return key;
+}
+/**
+ * The stored key, or `undefined` when the file is missing, unreadable, or holds no usable value. Throws
+ * `configuration` when the file is readable by other users; keySituation() reports that case as `unusable` instead.
+ */
+export function readStoredApiKey() {
+    const path = credentialsPath();
+    try {
+        if (process.platform !== "win32" && (statSync(path).mode & 0o077) !== 0) {
+            // Refuse to use a key other local users can read; the user must fix permissions or log in again.
+            throw new TypeSafeIntegrationError("configuration", `Refusing to read ${path}: it is readable by other users. Run chmod 600 on it, or run /typesafe logout and /typesafe login.`);
+        }
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        const key = parsed && typeof parsed === "object" ? parsed.apiKey : undefined;
+        return typeof key === "string" && key.trim() ? key.trim() : undefined;
+    }
+    catch (error) {
+        if (error instanceof TypeSafeIntegrationError)
+            throw error;
+        return undefined;
+    }
+}
+/**
+ * What the environment, the login store, and file permissions add up to right now. Never throws; the "unusable" kind
+ * carries the user-facing reason (a stored key that other local users can read).
+ */
+export function keySituation() {
+    const fromEnvironment = process.env.TYPESAFE_API_KEY?.trim();
+    if (fromEnvironment)
+        return { kind: "environment", key: fromEnvironment };
+    const path = credentialsPath();
+    try {
+        const key = readStoredApiKey();
+        return key ? { kind: "stored", key, path } : { kind: "missing" };
+    }
+    catch (error) {
+        // readStoredApiKey only throws for a store this process must not use; report it instead of failing the caller.
+        if (error instanceof TypeSafeIntegrationError && error.code === "configuration")
+            return { kind: "unusable", path, reason: error.message };
+        throw error;
+    }
+}
+/** Short phrase naming the source; full sentences stay with the caller. */
+export function keySourceLabel(situation) {
+    switch (situation.kind) {
+        case "environment": return "TYPESAFE_API_KEY";
+        case "stored": return "/typesafe login";
+        case "missing": return "no key";
+        case "unusable": return "unusable key";
+    }
+}
+/**
+ * The pre-0.4.0 key interface, frozen for existing callers: environment first so CI and scripts stay explicit, the
+ * stored key as the interactive default, `undefined` when no key is configured, and a `configuration` error when a
+ * store must not be read. New code should call keySituation() instead: same precedence, never throws, and the
+ * "must not be read" case arrives as `unusable` with the reason.
+ */
+export function resolveApiKey() {
+    const situation = keySituation();
+    if (situation.kind === "unusable")
+        throw new TypeSafeIntegrationError("configuration", situation.reason);
+    return situation.kind === "environment" || situation.kind === "stored" ? { key: situation.key, source: situation.kind } : undefined;
+}
+export function storeApiKey(value) {
+    const key = normalizeApiKey(value);
+    const path = credentialsPath();
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        const temporary = `${path}.${process.pid}.tmp`;
+        writeFileSync(temporary, `${JSON.stringify({ apiKey: key }, null, 2)}\n`, { mode: 0o600, flag: "w" });
+        chmodSync(temporary, 0o600);
+        renameSync(temporary, path);
+    }
+    catch {
+        throw new TypeSafeIntegrationError("configuration", `Could not write ${path}. Check directory permissions, or set TYPESAFE_API_KEY in the environment instead.`);
+    }
+    return path;
+}
+export function clearStoredApiKey() {
+    const path = credentialsPath();
+    try {
+        statSync(path);
+    }
+    catch {
+        return false;
+    }
+    rmSync(path, { force: true });
+    return true;
+}

package/node_modules/pi-typesafe/dist/errors.d.ts

@@ -0,0 +1,9 @@
+export type IntegrationErrorCode = "configuration" | "validation" | "budget" | "aborted" | "timeout" | "http" | "connection" | "response";
+/** Safe to display: never contains upstream bodies, headers, keys, or submitted state. */
+export declare class TypeSafeIntegrationError extends Error {
+    readonly code: IntegrationErrorCode;
+    readonly status?: number | undefined;
+    readonly name = "TypeSafeIntegrationError";
+    constructor(code: IntegrationErrorCode, message: string, status?: number | undefined);
+}
+export declare function safeError(error: unknown): TypeSafeIntegrationError;

package/node_modules/pi-typesafe/dist/errors.js

@@ -0,0 +1,31 @@
+import { APIError, APIConnectionError, APITimeoutError, APIUserAbortError } from "@typesafe-ai/sdk";
+/** Safe to display: never contains upstream bodies, headers, keys, or submitted state. */
+export class TypeSafeIntegrationError extends Error {
+    code;
+    status;
+    name = "TypeSafeIntegrationError";
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+export function safeError(error) {
+    if (error instanceof TypeSafeIntegrationError)
+        return error;
+    if (error instanceof APIUserAbortError)
+        return new TypeSafeIntegrationError("aborted", "TypeSafe request cancelled; an already submitted request may still be billed.");
+    if (error instanceof APITimeoutError)
+        return new TypeSafeIntegrationError("timeout", "TypeSafe request timed out; it was not retried and may still be billed.");
+    if (error instanceof APIError) {
+        const advice = error.status === 401 ? "Check TYPESAFE_API_KEY."
+            : error.status === 403 ? "Check your account access and model permissions."
+                : error.status === 429 ? "Check your account quota and try again later."
+                    : error.status === 400 || error.status === 422 ? "Check the question format and model limits."
+                        : "Try again later or check the service status.";
+        return new TypeSafeIntegrationError("http", `TypeSafe returned HTTP ${error.status}. ${advice} No automatic retry was made.`, error.status);
+    }
+    if (error instanceof APIConnectionError)
+        return new TypeSafeIntegrationError("connection", "Could not complete the TypeSafe connection. No automatic retry was made.");
+    return new TypeSafeIntegrationError("response", "TypeSafe returned an unreadable or unexpected response.");
+}

package/node_modules/pi-typesafe/dist/extension.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/** Native Pi registration; importing the root library does not load this module. */
+export default function typesafeExtension(pi: ExtensionAPI): void;

package/node_modules/pi-typesafe/dist/extension.js

@@ -0,0 +1,222 @@
+import { Text } from "@earendil-works/pi-tui";
+import { createTypeSafe, DEFAULT_MAX_REQUESTS } from "./client.js";
+import { authState, clearAuthState, describeAuth } from "./auth.js";
+import { clearStoredApiKey, credentialsPath, keySituation, keySourceLabel } from "./credentials.js";
+import { TypeSafeIntegrationError, safeError } from "./errors.js";
+import { loginWithPrompt } from "./login.js";
+import { DEFAULT_MAX_INPUT_BYTES, evaluationSchema, normalizeEvaluationRequest, prepareEvaluationRequest } from "./schema.js";
+const disclosure = "Submitted state and questions will be sent to api.typesafe.ai and may incur charges. Do not include secrets. The extension does not collect files or conversation history. Results are model judgments, not proof or authorization.";
+const sample = {
+    state: { message: "I was charged twice for my subscription. Please help today." },
+    questions: {
+        category: { type: "choice", instructions: "Which team should handle this message?", criteria: { billing: "Charges and payments", technical: "Software failures", other: "None of these" } },
+        urgent: { type: "noul", instructions: "Does the sender request help today?" },
+        frustration: { type: "score", instructions: "How frustrated does the sender sound?", criteria: ["A neutral request without expressed frustration", "Expressed frustration while remaining civil", "Explicit anger or threats"] },
+    },
+};
+function format(result, expanded = false) {
+    const lines = [`TypeSafe · ${JSON.stringify(result.model)} · ${result.elapsedMs} ms`];
+    for (const [id, answer] of Object.entries(result.answers)) {
+        const label = JSON.stringify(id);
+        if (answer.type === "noul")
+            lines.push(`${label}: P(yes) = ${answer.noul.toFixed(3)}`);
+        else if (answer.type === "choice")
+            lines.push(`${label}: ${JSON.stringify(answer.choice)} · confidence ${answer.confidence.toFixed(3)}`);
+        else
+            lines.push(`${label}: ${answer.score.toFixed(3)} · confidence ${answer.confidence.toFixed(3)}`);
+        if (expanded && answer.type !== "noul")
+            lines.push(`  ${JSON.stringify(answer.probabilities)}`);
+    }
+    lines.push(`${result.usage.input_tokens} input / ${result.usage.output_tokens} output tokens`);
+    lines.push("Confidence is distribution concentration, not proof of correctness.");
+    return lines.join("\n");
+}
+/** Native Pi registration; importing the root library does not load this module. */
+export default function typesafeExtension(pi) {
+    let enabled = process.env.PI_TYPESAFE_ENABLED === "1";
+    let client;
+    // One callout per distinct degradation per session: a long run must not bury the reason in repeated notices.
+    let calledOut;
+    const getClient = () => client ??= createTypeSafe();
+    const callOut = (ctx, key, text) => {
+        if (calledOut === key)
+            return;
+        calledOut = key;
+        try {
+            if (ctx?.hasUI)
+                ctx.ui.notify(text, "warning");
+            else
+                pi.sendMessage({ customType: "typesafe-status", content: text, display: true });
+        }
+        catch {
+            // Reporting must never replace the failure it describes, and a headless run may have no message channel.
+        }
+    };
+    pi.on("session_start", async (_event, ctx) => {
+        enabled = process.env.PI_TYPESAFE_ENABLED === "1";
+        client = undefined;
+        calledOut = undefined;
+        // An enabled extension with no usable key used to look exactly like a working one. Say it at startup; an
+        // unverified-but-present key stays quiet, because the first request is what proves it.
+        const auth = describeAuth(authState());
+        if (enabled && auth.level === "error")
+            callOut(ctx, `start:${auth.level}`, `TypeSafe is enabled but judgments are skipped. ${auth.text}`);
+    });
+    pi.registerEntryRenderer("typesafe-result", (entry, { expanded }) => new Text(entry.data ? format(entry.data, expanded) : "TypeSafe · no result", 0, 0));
+    pi.registerTool({
+        name: "typesafe_evaluate",
+        label: "TypeSafe",
+        description: `Evaluate supplied state with independent Choice, Score, and Noul questions in one TypeSafe request. Each question judges the whole state, so when several items are involved, put each item in a named state field (e.g. \`reports.r1\`) and ask one question per item per dimension (e.g. \`r1_owner\`, \`r2_owner\`), naming the field in the instructions; never aggregate several items into one question. ${disclosure} Requires operator opt-in via /typesafe enable or PI_TYPESAFE_ENABLED=1. Limit: 32 questions, ${DEFAULT_MAX_INPUT_BYTES / 1024} KiB JSON, ${DEFAULT_MAX_REQUESTS} attempts per session; no retries.`,
+        promptSnippet: "Ask batched structured questions with TypeSafe (external service; operator opt-in required)",
+        promptGuidelines: [
+            "Use typesafe_evaluate only for requested semantic judgments, not calculations or exact lookups; send only the relevant permitted data.",
+            "Batch independent typesafe_evaluate questions over the same state; use code or explicit permission rules for actions, never confidence as authorization.",
+            "When typesafe_evaluate judges several items, give each item a named state field and ask one question per item per dimension, naming the field in the instructions; one question over many items returns an unusable blend.",
+            "Report typesafe_evaluate answers as the model's judgments with their probabilities; do not replace them with your own guesses, and say when an answer is uncertain.",
+        ],
+        parameters: evaluationSchema,
+        // Pi validates against `parameters` after this hook; the cast only names the schema's type.
+        prepareArguments: args => normalizeEvaluationRequest(args),
+        async execute(_id, params, signal, _onUpdate, ctx) {
+            if (!enabled)
+                throw new TypeSafeIntegrationError("configuration", "TypeSafe is disabled. Ask the operator to run /typesafe enable; do not enable it by editing configuration or environment files.");
+            // The tool admits through the same rule as the library; evaluate() re-runs it idempotently.
+            const request = prepareEvaluationRequest(params);
+            try {
+                const result = await getClient().evaluate(request, signal ? { signal } : {});
+                return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
+            }
+            catch (error) {
+                const safe = safeError(error);
+                // Authentication degradation is louder than a single failed call: it means every later judgment is skipped.
+                const rejected = safe.code === "http" && (safe.status === 401 || safe.status === 403);
+                if (rejected || safe.code === "configuration") {
+                    callOut(ctx, `run:${safe.code}:${safe.status ?? ""}`, `TypeSafe is not authenticated (${safe.message}) Judgments will fail until the key is fixed.`);
+                }
+                throw safe;
+            }
+        },
+        renderCall(args) {
+            return new Text(`TypeSafe · ${Object.keys(args.questions ?? {}).length} questions · external request`, 0, 0);
+        },
+        renderResult(result, { expanded, isPartial }) {
+            if (isPartial)
+                return new Text("TypeSafe · waiting for response", 0, 0);
+            if (!result.details?.answers)
+                return new Text(result.content.filter(part => part.type === "text").map(part => part.text).join("\n"), 0, 0);
+            return new Text(format(result.details, expanded), 0, 0);
+        },
+    });
+    const actions = ["login", "logout", "setup", "status", "enable", "disable", "test", "playground"];
+    pi.registerCommand("typesafe", {
+        description: "TypeSafe login, consent, usage, sample test, and JSON playground",
+        getArgumentCompletions(prefix) {
+            const matches = actions.filter(action => action.startsWith(prefix)).map(action => ({ value: action, label: action }));
+            return matches.length ? matches : null;
+        },
+        async handler(args, ctx) {
+            const action = args.trim() || "status";
+            const report = (text, level = "info") => {
+                if (ctx.hasUI)
+                    ctx.ui.notify(text, level);
+                else
+                    pi.sendMessage({ customType: "typesafe-status", content: text, display: true });
+            };
+            try {
+                if (action === "status") {
+                    const spend = client?.getSpend();
+                    const auth = describeAuth(authState());
+                    const session = spend
+                        ? `Session ${spend.session.requestsStarted}/${DEFAULT_MAX_REQUESTS} attempts, ${spend.session.requestsSucceeded} successful, ${spend.session.requestsFailed} failed, ${spend.session.inputTokens} input tokens (~$${spend.session.estimatedUsd.toFixed(4)}).`
+                        : `Session 0/${DEFAULT_MAX_REQUESTS} attempts; no client yet in this session.`;
+                    const today = spend
+                        ? `Today ${spend.today.requestsStarted} requests (${spend.today.requestsSucceeded} ok, ${spend.today.requestsFailed} failed), ${spend.today.inputTokens} input tokens, ~$${spend.today.estimatedUsd.toFixed(4)}.`
+                        : "";
+                    const blocked = spend?.blocked ? ` Cap reached: ${spend.blocked.cap} ${spend.blocked.used}/${spend.blocked.limit} on ${spend.blocked.day}; no request will be submitted until the local day rolls over.` : "";
+                    report(`TypeSafe: ${enabled ? "enabled" : "disabled"}. ${auth.text} ${session} ${today}${blocked} Model: jev-latest. Session limits reset on session start/reload; daily counters persist and caps come from client options or PI_TYPESAFE_MAX_* environment variables. ${disclosure}`, auth.level === "error" && enabled ? "warning" : "info");
+                    return;
+                }
+                if (action === "logout") {
+                    const removed = clearStoredApiKey();
+                    clearAuthState();
+                    client = undefined;
+                    enabled = false;
+                    report(removed ? `Removed the stored key at ${credentialsPath()}. TypeSafe is disabled.` : "No stored key to remove." + (process.env.TYPESAFE_API_KEY?.trim() ? " TYPESAFE_API_KEY is still set in the environment." : ""));
+                    return;
+                }
+                if (action === "disable") {
+                    enabled = false;
+                    report("TypeSafe disabled for future agent calls. In-flight requests are not cancelled.");
+                    return;
+                }
+                if (!actions.includes(action)) {
+                    report(`Usage: /typesafe ${actions.join(" | ")}`, "warning");
+                    return;
+                }
+                if (!ctx.hasUI) {
+                    report("This command needs interactive Pi. For headless tool use, explicitly set PI_TYPESAFE_ENABLED=1 and TYPESAFE_API_KEY before launching Pi.", "warning");
+                    return;
+                }
+                const situation = keySituation();
+                if (action === "login" || (action === "setup" && situation.kind === "missing")) {
+                    if (process.env.TYPESAFE_API_KEY?.trim()) {
+                        report("TYPESAFE_API_KEY is set in the environment and takes precedence over a stored key. Unset it before using /typesafe login.", "warning");
+                        return;
+                    }
+                    const login = await loginWithPrompt(ctx);
+                    if (login === undefined) {
+                        report("Login cancelled; nothing was saved.");
+                        return;
+                    }
+                    client = undefined;
+                    report(`Key verified (${login.models} model${login.models === 1 ? "" : "s"} available) and saved to ${login.path} with owner-only permissions. Run /typesafe enable to allow agent tool calls.`);
+                    return;
+                }
+                if (action === "setup") {
+                    const current = situation.kind === "environment" || situation.kind === "stored" ? `configured via ${keySourceLabel(situation)}`
+                        : situation.kind === "unusable" ? `unusable — ${situation.reason}`
+                            : "missing";
+                    report(`Key ${current}. Run /typesafe test for one sample request or /typesafe enable to allow agent tool calls.`);
+                    return;
+                }
+                if (action === "enable") {
+                    if (situation.kind === "missing") {
+                        report("Run /typesafe login first: no API key is configured.", "warning");
+                        return;
+                    }
+                    if (situation.kind === "unusable") {
+                        report(`The stored key cannot be used. ${situation.reason}`, "warning");
+                        return;
+                    }
+                    if (await ctx.ui.confirm("Enable TypeSafe for this session?", disclosure)) {
+                        enabled = true;
+                        report(`TypeSafe enabled. Up to ${DEFAULT_MAX_REQUESTS} attempts in this session; /typesafe disable stops future agent calls.`);
+                    }
+                    return;
+                }
+                let request = sample;
+                if (action === "playground") {
+                    const text = await ctx.ui.editor("TypeSafe request JSON · edit state and questions", JSON.stringify(sample, null, 2));
+                    if (text === undefined)
+                        return;
+                    try {
+                        request = JSON.parse(text);
+                    }
+                    catch {
+                        report("Invalid JSON. Keep quoted strings on one line; nothing was sent.", "error");
+                        return;
+                    }
+                }
+                const validated = prepareEvaluationRequest(request);
+                if (!await ctx.ui.confirm("Send this TypeSafe request?", disclosure))
+                    return;
+                const result = await getClient().evaluate(validated);
+                // Playground results stay out of LLM context; the agent tool returns its own results normally.
+                pi.appendEntry("typesafe-result", result);
+            }
+            catch (error) {
+                report(safeError(error).message, "error");
+            }
+        },
+    });
+}

package/node_modules/pi-typesafe/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { createTypeSafe, DEFAULT_MAX_REQUESTS } from "./client.js";
+export type { TypeSafe, TypeSafeOptions, EvaluationOptions, Evaluation, UsageSnapshot, SpendReport, } from "./client.js";
+export { ask, DEFAULT_ASK_TIMEOUT_MS } from "./ask.js";
+export type { AskAnswer, AskOptions, Judge } from "./ask.js";
+export { fanOut, DEFAULT_CONCURRENCY, evaluateMany, evaluateAll, chunkEvaluationRequest } from "./batch.js";
+export type { BatchEvaluation, BatchOptions, FanOutOptions, Settled } from "./batch.js";
+export { authState, authStatePath, clearAuthState, describeAuth, recordAuthFailure, recordAuthVerified } from "./auth.js";
+export type { AuthFailure, AuthReport, AuthState } from "./auth.js";
+export { clearStoredApiKey, credentialsPath, keySituation, keySourceLabel, normalizeApiKey, piTypesafeDir, resolveApiKey, storeApiKey, } from "./credentials.js";
+export type { KeySituation, KeySource } from "./credentials.js";
+export { capsFromEnvironment, DEFAULT_USD_PER_MTOK, emptyTotals, estimateUsd, localDay, mergeCaps, openUsageLedger, usagePath, } from "./usage.js";
+export type { BlockedCap, SpendCaps, UsageLedger, UsageLedgerOptions, UsageReport, UsageTotals } from "./usage.js";
+export { TypeSafeIntegrationError } from "./errors.js";
+export type { IntegrationErrorCode } from "./errors.js";
+export { DEFAULT_MAX_INPUT_BYTES, DEFAULT_MAX_QUESTIONS, evaluationSchema, normalizeEvaluationRequest, parseEvaluationRequest, prepareEvaluationRequest, } from "./schema.js";
+export type { PrepareEvaluationOptions } from "./schema.js";
+export { choice, noul, score } from "@typesafe-ai/sdk";
+export type { Questions, Question, SystemOneRequest, SystemOneResult, EntryType, JsonValue, ChoiceQuestion, ChoiceResponse, NoulQuestion, NoulResponse, ScoreQuestion, ScoreResponse, Usage, } from "@typesafe-ai/sdk";

package/node_modules/pi-typesafe/dist/index.js

@@ -0,0 +1,9 @@
+export { createTypeSafe, DEFAULT_MAX_REQUESTS } from "./client.js";
+export { ask, DEFAULT_ASK_TIMEOUT_MS } from "./ask.js";
+export { fanOut, DEFAULT_CONCURRENCY, evaluateMany, evaluateAll, chunkEvaluationRequest } from "./batch.js";
+export { authState, authStatePath, clearAuthState, describeAuth, recordAuthFailure, recordAuthVerified } from "./auth.js";
+export { clearStoredApiKey, credentialsPath, keySituation, keySourceLabel, normalizeApiKey, piTypesafeDir, resolveApiKey, storeApiKey, } from "./credentials.js";
+export { capsFromEnvironment, DEFAULT_USD_PER_MTOK, emptyTotals, estimateUsd, localDay, mergeCaps, openUsageLedger, usagePath, } from "./usage.js";
+export { TypeSafeIntegrationError } from "./errors.js";
+export { DEFAULT_MAX_INPUT_BYTES, DEFAULT_MAX_QUESTIONS, evaluationSchema, normalizeEvaluationRequest, parseEvaluationRequest, prepareEvaluationRequest, } from "./schema.js";
+export { choice, noul, score } from "@typesafe-ai/sdk";