@herbertgao/pi-extensions 2026.9.7 → 2026.9.9

package/node_modules/pi-typesafe/dist/key-prompt.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+/** Hidden input in the TUI; falls back to Pi's plain input dialog where custom components are unavailable. */
+export declare function promptForApiKey(ctx: ExtensionCommandContext): Promise<string | undefined>;

package/node_modules/pi-typesafe/dist/key-prompt.js

@@ -0,0 +1,43 @@
+import { Container, CURSOR_MARKER, Input, Key, matchesKey, Text, truncateToWidth } from "@earendil-works/pi-tui";
+/** Single-line input that renders bullets instead of the typed value. */
+class SecretInput extends Input {
+    render(width) {
+        const length = [...this.getValue()].length;
+        const bullets = "•".repeat(Math.min(length, Math.max(0, width - 2)));
+        const cursor = this.focused ? `${CURSOR_MARKER}\x1b[7m \x1b[27m` : "";
+        return [truncateToWidth(bullets + cursor, width, "")];
+    }
+}
+class KeyPrompt extends Container {
+    input = new SecretInput();
+    isFocused = false;
+    constructor(theme, done) {
+        super();
+        this.addChild(new Text(theme.fg("accent", theme.bold("TypeSafe API key")), 1, 0));
+        this.addChild(new Text(theme.fg("muted", "Paste the key from console.typesafe.ai › API Keys. Input is hidden. Enter saves, Esc cancels."), 1, 0));
+        this.addChild(this.input);
+        this.input.onSubmit = value => done(value);
+        this.input.onEscape = () => done(undefined);
+    }
+    get focused() {
+        return this.isFocused;
+    }
+    set focused(value) {
+        this.isFocused = value;
+        this.input.focused = value;
+    }
+    handleInput(data) {
+        if (matchesKey(data, Key.escape)) {
+            this.input.onEscape?.();
+            return;
+        }
+        this.input.handleInput(data);
+    }
+}
+/** Hidden input in the TUI; falls back to Pi's plain input dialog where custom components are unavailable. */
+export async function promptForApiKey(ctx) {
+    if (typeof ctx.ui.custom === "function") {
+        return ctx.ui.custom((_tui, theme, _keybindings, done) => new KeyPrompt(theme, done));
+    }
+    return ctx.ui.input("TypeSafe API key (visible while typing)", "Paste the key, then press Enter");
+}

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

@@ -0,0 +1,27 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { KeySource } from "./credentials.js";
+export interface LoginResult {
+    /** Where the verified key was saved. */
+    path: string;
+    /** Number of models the key can access; proves the key was accepted by the API. */
+    models: number;
+}
+/**
+ * Prompt for a key (hidden input), verify it with a model listing, and store it for every pi-typesafe consumer.
+ * Resolves to undefined when the user cancels. Rejects with TypeSafeIntegrationError for an invalid or unverifiable key.
+ * Refuses when TYPESAFE_API_KEY is set, because the environment would shadow the stored key.
+ */
+export declare function loginWithPrompt(ctx: ExtensionCommandContext): Promise<LoginResult | undefined>;
+export type EnsureApiKeyResult = {
+    source: KeySource;
+    login?: undefined;
+} | {
+    source: "stored";
+    login: LoginResult;
+};
+/**
+ * Use the configured key if there is one; otherwise run the login prompt. `undefined` means the user cancelled.
+ * A store that must not be read throws `configuration` with the reason instead of prompting, so a permissions
+ * problem stays visible; the result shape is frozen for existing callers.
+ */
+export declare function ensureApiKey(ctx: ExtensionCommandContext): Promise<EnsureApiKeyResult | undefined>;

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

@@ -0,0 +1,38 @@
+import { createTypeSafe } from "./client.js";
+import { keySituation, normalizeApiKey, storeApiKey } from "./credentials.js";
+import { TypeSafeIntegrationError } from "./errors.js";
+import { promptForApiKey } from "./key-prompt.js";
+/**
+ * Prompt for a key (hidden input), verify it with a model listing, and store it for every pi-typesafe consumer.
+ * Resolves to undefined when the user cancels. Rejects with TypeSafeIntegrationError for an invalid or unverifiable key.
+ * Refuses when TYPESAFE_API_KEY is set, because the environment would shadow the stored key.
+ */
+export async function loginWithPrompt(ctx) {
+    if (process.env.TYPESAFE_API_KEY?.trim()) {
+        throw new TypeSafeIntegrationError("configuration", "TYPESAFE_API_KEY is set in the environment and takes precedence over a stored key. Unset it before logging in interactively.");
+    }
+    if (!ctx.hasUI) {
+        throw new TypeSafeIntegrationError("configuration", "Logging in needs an interactive session. Set TYPESAFE_API_KEY in the environment instead.");
+    }
+    const entered = await promptForApiKey(ctx);
+    if (entered === undefined)
+        return undefined;
+    const key = normalizeApiKey(entered);
+    // Verify before saving so a bad paste fails here, not on first use.
+    const models = await createTypeSafe({ apiKey: key }).listModels();
+    return { path: storeApiKey(key), models: models.length };
+}
+/**
+ * Use the configured key if there is one; otherwise run the login prompt. `undefined` means the user cancelled.
+ * A store that must not be read throws `configuration` with the reason instead of prompting, so a permissions
+ * problem stays visible; the result shape is frozen for existing callers.
+ */
+export async function ensureApiKey(ctx) {
+    const situation = keySituation();
+    if (situation.kind === "environment" || situation.kind === "stored")
+        return { source: situation.kind };
+    if (situation.kind === "unusable")
+        throw new TypeSafeIntegrationError("configuration", situation.reason);
+    const login = await loginWithPrompt(ctx);
+    return login ? { source: "stored", login } : undefined;
+}

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

@@ -0,0 +1,43 @@
+import type { SystemOneRequest } from "@typesafe-ai/sdk";
+import { Type } from "typebox";
+/** Default UTF-8 JSON byte budget for one evaluation request; the tool and the client share it. */
+export declare const DEFAULT_MAX_INPUT_BYTES = 65536;
+/** Questions one request may ask. More than this needs `chunkEvaluationRequest`, which splits and fans out. */
+export declare const DEFAULT_MAX_QUESTIONS = 32;
+/** The JSON schema used by both the Pi tool and the programmatic interface. */
+export declare const evaluationSchema: Type.TObject<{
+    state: Type.TUnion<[Type.TString, Type.TNull, Type.TArray<Type.TUnknown>, Type.TRecord<"^.*$", Type.TUnknown>]>;
+    questions: Type.TRecord<"^.*$", Type.TUnion<[Type.TObject<{
+        type: Type.TLiteral<"noul">;
+        instructions: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull, Type.TArray<Type.TUnknown>, Type.TRecord<"^.*$", Type.TUnknown>]>>;
+        criteria: Type.TOptional<Type.TUnion<[Type.TNull, Type.TObject<{
+            true: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull, Type.TArray<Type.TUnknown>, Type.TRecord<"^.*$", Type.TUnknown>]>>;
+            false: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull, Type.TArray<Type.TUnknown>, Type.TRecord<"^.*$", Type.TUnknown>]>>;
+        }>]>>;
+    }>, Type.TObject<{
+        type: Type.TLiteral<"choice">;
+        instructions: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull, Type.TArray<Type.TUnknown>, Type.TRecord<"^.*$", Type.TUnknown>]>>;
+        criteria: Type.TRecord<"^.*$", Type.TUnion<[Type.TString, Type.TNull, Type.TArray<Type.TUnknown>, Type.TRecord<"^.*$", Type.TUnknown>]>>;
+    }>, Type.TObject<{
+        type: Type.TLiteral<"score">;
+        instructions: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull, Type.TArray<Type.TUnknown>, Type.TRecord<"^.*$", Type.TUnknown>]>>;
+        criteria: Type.TArray<Type.TUnion<[Type.TString, Type.TNull, Type.TArray<Type.TUnknown>, Type.TRecord<"^.*$", Type.TUnknown>]>>;
+    }>]>>;
+    model: Type.TOptional<Type.TString>;
+}>;
+/** Validate without including submitted content in validation errors. Prefer prepareEvaluationRequest(), which also accepts near-misses and enforces the byte budget. */
+export declare function parseEvaluationRequest(value: unknown): SystemOneRequest;
+/** Accept common near-misses from language models without loosening the schema itself. Prefer prepareEvaluationRequest(), which applies this before validating. */
+export declare function normalizeEvaluationRequest(value: unknown): unknown;
+export interface PrepareEvaluationOptions {
+    /** UTF-8 JSON bytes of the serialized request. Default: DEFAULT_MAX_INPUT_BYTES. */
+    maxInputBytes?: number;
+}
+/** One byte rule for every limit check: measure the serialized request and name the configured limit. */
+export declare function assertWithinByteLimit(text: string, maxInputBytes: number): void;
+/**
+ * The one admission rule: normalize known near-miss aliases, validate the schema and JSON-safety, then enforce the byte
+ * budget — always in that order. The Pi tool, the playground, and client.evaluate() all pass through here, so what one
+ * accepts the others accept.
+ */
+export declare function prepareEvaluationRequest(value: unknown, options?: PrepareEvaluationOptions): SystemOneRequest;

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

@@ -0,0 +1,152 @@
+import { Type } from "typebox";
+import { Check, Errors } from "typebox/value";
+import { TypeSafeIntegrationError } from "./errors.js";
+/** Default UTF-8 JSON byte budget for one evaluation request; the tool and the client share it. */
+export const DEFAULT_MAX_INPUT_BYTES = 65_536;
+/** Questions one request may ask. More than this needs `chunkEvaluationRequest`, which splits and fans out. */
+export const DEFAULT_MAX_QUESTIONS = 32;
+// The API accepts structured descriptions, not only strings.
+const entry = Type.Union([
+    Type.String(),
+    Type.Null(),
+    Type.Array(Type.Unknown()),
+    Type.Record(Type.String(), Type.Unknown()),
+]);
+const instructions = Type.Optional(entry);
+const question = Type.Union([
+    Type.Object({
+        type: Type.Literal("noul"),
+        instructions,
+        criteria: Type.Optional(Type.Union([
+            Type.Null(),
+            Type.Object({ true: Type.Optional(entry), false: Type.Optional(entry) }, { additionalProperties: false }),
+        ])),
+    }, { additionalProperties: false }),
+    Type.Object({
+        type: Type.Literal("choice"),
+        instructions,
+        criteria: Type.Record(Type.String({ minLength: 1, maxLength: 200 }), entry, { minProperties: 1, maxProperties: 64 }),
+    }, { additionalProperties: false }),
+    Type.Object({
+        type: Type.Literal("score"),
+        instructions,
+        criteria: Type.Array(entry, { minItems: 2, maxItems: 32 }),
+    }, { additionalProperties: false }),
+]);
+/** The JSON schema used by both the Pi tool and the programmatic interface. */
+export const evaluationSchema = Type.Object({
+    state: entry,
+    questions: Type.Record(Type.String({ minLength: 1, maxLength: 100 }), question, {
+        minProperties: 1,
+        maxProperties: DEFAULT_MAX_QUESTIONS,
+    }),
+    model: Type.Optional(Type.String({ minLength: 1, maxLength: 100 })),
+}, { additionalProperties: false });
+const usage = `Expected { state, questions: { <id>: { type: "choice", instructions, criteria: { label: description|null } } | { type: "score", instructions, criteria: [level0, level1, ...] } | { type: "noul", instructions } } }; 1–${DEFAULT_MAX_QUESTIONS} questions, Choice 1–64 options, Score 2–32 levels.`;
+/** Paths and messages only; never the submitted values. */
+function describeSchemaErrors(value) {
+    const details = [];
+    for (const error of Errors(evaluationSchema, value)) {
+        const path = error.instancePath.replace(/^\//, "").replace(/\//g, ".") || "request";
+        details.push(`${path.slice(0, 120)}: ${error.message}`);
+        if (details.length === 3)
+            break;
+    }
+    return details.join("; ");
+}
+/** Validate without including submitted content in validation errors. Prefer prepareEvaluationRequest(), which also accepts near-misses and enforces the byte budget. */
+export function parseEvaluationRequest(value) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value) && !isJsonSafe(value)) {
+        throw new TypeSafeIntegrationError("validation", `Invalid evaluation request: state and questions must be plain JSON. ${usage}`);
+    }
+    if (!Check(evaluationSchema, value)) {
+        throw new TypeSafeIntegrationError("validation", `Invalid evaluation request at ${describeSchemaErrors(value)}. ${usage}`);
+    }
+    return value;
+}
+function isJsonSafe(value) {
+    try {
+        // Walk before schema validation to reject cycles and non-JSON values.
+        // Object descriptors avoid executing getters while checking user data.
+        const ancestors = new Set();
+        const walk = (item, depth) => {
+            if (depth > 64)
+                throw new Error();
+            if (item === null || typeof item === "string" || typeof item === "boolean")
+                return;
+            if (typeof item === "number" && Number.isFinite(item))
+                return;
+            if (typeof item !== "object" || ancestors.has(item))
+                throw new Error();
+            if (!Array.isArray(item) && Object.getPrototypeOf(item) !== Object.prototype && Object.getPrototypeOf(item) !== null)
+                throw new Error();
+            ancestors.add(item);
+            if (Object.getOwnPropertySymbols(item).length)
+                throw new Error();
+            for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(item))) {
+                if (Array.isArray(item) && key === "length")
+                    continue;
+                if (!descriptor.enumerable || descriptor.get || descriptor.set)
+                    throw new Error();
+                // SDK helpers include optional object fields whose value is undefined.
+                // JSON serialization omits those fields; array elements must remain JSON.
+                if (descriptor.value === undefined && !Array.isArray(item))
+                    continue;
+                walk(descriptor.value, depth + 1);
+            }
+            ancestors.delete(item);
+        };
+        walk(value, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Accept common near-misses from language models without loosening the schema itself. Prefer prepareEvaluationRequest(), which applies this before validating. */
+export function normalizeEvaluationRequest(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return value;
+    const request = value;
+    const questions = request.questions;
+    if (!questions || typeof questions !== "object" || Array.isArray(questions))
+        return value;
+    const normalized = {};
+    for (const [id, question] of Object.entries(questions)) {
+        if (!question || typeof question !== "object" || Array.isArray(question)) {
+            normalized[id] = question;
+            continue;
+        }
+        const { options, levels, choices, ...rest } = question;
+        const item = { ...rest };
+        if (item.criteria === undefined) {
+            const alias = options ?? levels ?? choices;
+            if (alias !== undefined)
+                item.criteria = alias;
+        }
+        if (item.type === "choice" && Array.isArray(item.criteria) && item.criteria.every(label => typeof label === "string" && label)) {
+            item.criteria = Object.fromEntries(item.criteria.map(label => [label, null]));
+        }
+        if (item.type === "noul" && typeof item.criteria === "string") {
+            item.criteria = { true: item.criteria };
+        }
+        normalized[id] = item;
+    }
+    return { ...request, questions: normalized };
+}
+/** One byte rule for every limit check: measure the serialized request and name the configured limit. */
+export function assertWithinByteLimit(text, maxInputBytes) {
+    if (Buffer.byteLength(text, "utf8") > maxInputBytes) {
+        throw new TypeSafeIntegrationError("validation", `Evaluation exceeds the ${maxInputBytes}-byte input limit.`);
+    }
+}
+/**
+ * The one admission rule: normalize known near-miss aliases, validate the schema and JSON-safety, then enforce the byte
+ * budget — always in that order. The Pi tool, the playground, and client.evaluate() all pass through here, so what one
+ * accepts the others accept.
+ */
+export function prepareEvaluationRequest(value, options = {}) {
+    const validated = parseEvaluationRequest(normalizeEvaluationRequest(value));
+    assertWithinByteLimit(JSON.stringify(validated), options.maxInputBytes ?? DEFAULT_MAX_INPUT_BYTES);
+    return validated;
+}

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

@@ -0,0 +1,3 @@
+export { promptForApiKey } from "./key-prompt.js";
+export { loginWithPrompt, ensureApiKey } from "./login.js";
+export type { LoginResult, EnsureApiKeyResult } from "./login.js";

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

@@ -0,0 +1,3 @@
+// Interactive helpers that need Pi's TUI. Kept out of the root entry so the library stays usable without Pi.
+export { promptForApiKey } from "./key-prompt.js";
+export { loginWithPrompt, ensureApiKey } from "./login.js";

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

@@ -0,0 +1,73 @@
+/**
+ * TypeSafe bills input tokens only; output is free. The default mirrors the $42-per-billion-input-token rate the README
+ * quotes, so a spend cap means something before anyone configures a price. Override it when the rate changes.
+ */
+export declare const DEFAULT_USD_PER_MTOK = 0.042;
+/** Counters for one window (a session, or one local day). */
+export interface UsageTotals {
+    readonly requestsStarted: number;
+    readonly requestsSucceeded: number;
+    readonly requestsFailed: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+}
+/** One day of persisted totals plus the cost estimate for that day. */
+export interface UsageReport extends UsageTotals {
+    readonly day: string;
+    readonly estimatedUsd: number;
+}
+/**
+ * Client-side spend caps. Every field is optional; an absent field is unlimited. Session caps come from the client
+ * options only; day caps also read the `PI_TYPESAFE_MAX_*` environment variables so a headless run can bound itself
+ * without editing code. A cap that is reached raises a `budget` error before the next request leaves the process.
+ */
+export interface SpendCaps {
+    readonly maxRequests?: number;
+    readonly maxRequestsPerDay?: number;
+    readonly maxInputTokensPerDay?: number;
+    readonly maxUsdPerDay?: number;
+}
+/** The cap that stops the next request, with what it allows and what has been used today. */
+export interface BlockedCap {
+    readonly cap: "requestsPerDay" | "inputTokensPerDay" | "usdPerDay";
+    readonly limit: number;
+    readonly used: number;
+    readonly day: string;
+}
+export declare function localDay(now?: Date): string;
+/** The stored ledger. Alongside the key store so one directory holds every pi-typesafe file. */
+export declare function usagePath(): string;
+/** Input-token cost, rounded to a micro-dollar so the number stays readable. */
+export declare function estimateUsd(inputTokens: number, usdPerMTok: number): number;
+export declare function emptyTotals(): UsageTotals;
+/** The caps a headless run may set without code: `PI_TYPESAFE_MAX_USD_PER_DAY` and its siblings. */
+export declare function capsFromEnvironment(env?: NodeJS.ProcessEnv): SpendCaps;
+/** Environment first for day caps, then the explicit option; a cap is never raised by the environment. */
+export declare function mergeCaps(explicit: SpendCaps, environment: SpendCaps): SpendCaps;
+export interface UsageLedgerOptions {
+    /** Defaults to usagePath(); tests point it at a temporary file. */
+    path?: string;
+    /** Clock for the local day and for rollover; injectable for tests. */
+    now?: () => Date;
+    usdPerMTok?: number;
+}
+/**
+ * One day of persisted request, token, and cost totals, plus the caps that stop the next request. The in-memory copy is
+ * authoritative for this process; the file is the cross-process, across-restart record. Reads are defensive, writes are
+ * atomic and best-effort, and a day rolls over on the local date, so a long eval cannot accumulate forever unnoticed.
+ */
+export interface UsageLedger {
+    readonly path: string;
+    readonly usdPerMTok: number;
+    /** Today's totals, after any rollover. */
+    today(): UsageReport;
+    /** Count the attempt before it is submitted; a request that never returns still counts. */
+    recordStart(): void;
+    recordSuccess(inputTokens: number, outputTokens: number): void;
+    recordFailure(): void;
+    /** The reached day cap that blocks the next request, or undefined. The caller owns the caps. */
+    blocked(caps: SpendCaps): BlockedCap | undefined;
+    /** One line for status output: today's requests, tokens, and cost, with the caps that apply. */
+    describe(caps?: SpendCaps): string;
+}
+export declare function openUsageLedger(options?: UsageLedgerOptions): UsageLedger;

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

@@ -0,0 +1,182 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { piTypesafeDir } from "./credentials.js";
+/**
+ * TypeSafe bills input tokens only; output is free. The default mirrors the $42-per-billion-input-token rate the README
+ * quotes, so a spend cap means something before anyone configures a price. Override it when the rate changes.
+ */
+export const DEFAULT_USD_PER_MTOK = 0.042;
+/** Ledger days kept on disk; older entries are dropped on the next write. */
+const KEEP_DAYS = 31;
+const USAGE_VERSION = 1;
+export function localDay(now = new Date()) {
+    const pad = (value) => String(value).padStart(2, "0");
+    return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+/** The stored ledger. Alongside the key store so one directory holds every pi-typesafe file. */
+export function usagePath() {
+    return join(piTypesafeDir(), "usage.json");
+}
+/** Input-token cost, rounded to a micro-dollar so the number stays readable. */
+export function estimateUsd(inputTokens, usdPerMTok) {
+    return Math.round((inputTokens * usdPerMTok) / 1e6 * 1e6) / 1e6;
+}
+export function emptyTotals() {
+    return { requestsStarted: 0, requestsSucceeded: 0, requestsFailed: 0, inputTokens: 0, outputTokens: 0 };
+}
+function count(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+function totalsOf(value) {
+    const raw = (value ?? {});
+    return {
+        requestsStarted: count(raw.requestsStarted),
+        requestsSucceeded: count(raw.requestsSucceeded),
+        requestsFailed: count(raw.requestsFailed),
+        inputTokens: count(raw.inputTokens),
+        outputTokens: count(raw.outputTokens),
+    };
+}
+function readDays(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        const days = parsed && typeof parsed === "object" ? parsed.days : undefined;
+        if (!days || typeof days !== "object" || Array.isArray(days))
+            return {};
+        const result = {};
+        for (const [day, totals] of Object.entries(days)) {
+            if (/^\d{4}-\d{2}-\d{2}$/.test(day))
+                result[day] = totalsOf(totals);
+        }
+        return result;
+    }
+    catch {
+        // A missing, unreadable, or corrupt ledger restarts today's count; it never blocks a request.
+        return {};
+    }
+}
+function keepRecent(days, today) {
+    const names = Object.keys(days).sort();
+    const result = {};
+    for (const name of names.slice(-KEEP_DAYS))
+        result[name] = days[name];
+    result[today] = days[today] ?? emptyTotals();
+    return result;
+}
+/** Owner-only, atomic, and best-effort: a ledger this process cannot write never fails a request. */
+function writeDays(path, days) {
+    const file = { version: USAGE_VERSION, days };
+    const temporary = `${path}.${process.pid}.tmp`;
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileSync(temporary, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600, flag: "w" });
+        chmodSync(temporary, 0o600);
+        renameSync(temporary, path);
+    }
+    catch {
+        try {
+            rmSync(temporary, { force: true });
+        }
+        catch { /* best-effort cleanup only */ }
+    }
+}
+/** The caps a headless run may set without code: `PI_TYPESAFE_MAX_USD_PER_DAY` and its siblings. */
+export function capsFromEnvironment(env = process.env) {
+    const number = (name) => {
+        const raw = env[name]?.trim();
+        if (!raw)
+            return undefined;
+        const value = Number(raw);
+        return Number.isFinite(value) && value > 0 ? value : undefined;
+    };
+    const maxRequestsPerDay = number("PI_TYPESAFE_MAX_REQUESTS_PER_DAY");
+    const maxInputTokensPerDay = number("PI_TYPESAFE_MAX_INPUT_TOKENS_PER_DAY");
+    const maxUsdPerDay = number("PI_TYPESAFE_MAX_USD_PER_DAY");
+    return {
+        ...(maxRequestsPerDay === undefined ? {} : { maxRequestsPerDay: Math.floor(maxRequestsPerDay) }),
+        ...(maxInputTokensPerDay === undefined ? {} : { maxInputTokensPerDay: Math.floor(maxInputTokensPerDay) }),
+        ...(maxUsdPerDay === undefined ? {} : { maxUsdPerDay }),
+    };
+}
+/** Environment first for day caps, then the explicit option; a cap is never raised by the environment. */
+export function mergeCaps(explicit, environment) {
+    const lowest = (a, b) => a === undefined ? b : b === undefined ? a : Math.min(a, b);
+    const maxRequestsPerDay = lowest(explicit.maxRequestsPerDay, environment.maxRequestsPerDay);
+    const maxInputTokensPerDay = lowest(explicit.maxInputTokensPerDay, environment.maxInputTokensPerDay);
+    const maxUsdPerDay = lowest(explicit.maxUsdPerDay, environment.maxUsdPerDay);
+    return {
+        ...(explicit.maxRequests === undefined ? {} : { maxRequests: explicit.maxRequests }),
+        ...(maxRequestsPerDay === undefined ? {} : { maxRequestsPerDay }),
+        ...(maxInputTokensPerDay === undefined ? {} : { maxInputTokensPerDay }),
+        ...(maxUsdPerDay === undefined ? {} : { maxUsdPerDay }),
+    };
+}
+export function openUsageLedger(options = {}) {
+    const path = options.path ?? usagePath();
+    const now = options.now ?? (() => new Date());
+    const usdPerMTok = options.usdPerMTok && options.usdPerMTok > 0 ? options.usdPerMTok : DEFAULT_USD_PER_MTOK;
+    let day = localDay(now());
+    let days = keepRecent(readDays(path), day);
+    let totals = days[day];
+    const report = (value, name) => ({
+        ...value, day: name, estimatedUsd: estimateUsd(value.inputTokens, usdPerMTok),
+    });
+    const save = () => {
+        days = keepRecent({ ...days, [day]: totals }, day);
+        writeDays(path, days);
+    };
+    const roll = () => {
+        const current = localDay(now());
+        if (current === day)
+            return;
+        day = current;
+        totals = days[day] ?? emptyTotals();
+        days = keepRecent(days, day);
+    };
+    const add = (delta) => {
+        roll();
+        totals = {
+            requestsStarted: totals.requestsStarted + (delta.requestsStarted ?? 0),
+            requestsSucceeded: totals.requestsSucceeded + (delta.requestsSucceeded ?? 0),
+            requestsFailed: totals.requestsFailed + (delta.requestsFailed ?? 0),
+            inputTokens: totals.inputTokens + (delta.inputTokens ?? 0),
+            outputTokens: totals.outputTokens + (delta.outputTokens ?? 0),
+        };
+        save();
+    };
+    return {
+        path,
+        usdPerMTok,
+        today: () => { roll(); return report(totals, day); },
+        recordStart: () => add({ requestsStarted: 1 }),
+        recordSuccess: (inputTokens, outputTokens) => add({
+            requestsSucceeded: 1,
+            inputTokens: Number.isSafeInteger(inputTokens) && inputTokens > 0 ? inputTokens : 0,
+            outputTokens: Number.isSafeInteger(outputTokens) && outputTokens > 0 ? outputTokens : 0,
+        }),
+        recordFailure: () => add({ requestsFailed: 1 }),
+        blocked: (caps) => {
+            roll();
+            const checks = [
+                ["requestsPerDay", caps.maxRequestsPerDay, totals.requestsStarted],
+                ["inputTokensPerDay", caps.maxInputTokensPerDay, totals.inputTokens],
+                ["usdPerDay", caps.maxUsdPerDay, estimateUsd(totals.inputTokens, usdPerMTok)],
+            ];
+            for (const [cap, limit, used] of checks) {
+                if (limit !== undefined && used >= limit)
+                    return { cap, limit, used, day };
+            }
+            return undefined;
+        },
+        describe: (caps = {}) => {
+            roll();
+            const current = report(totals, day);
+            const limits = [
+                caps.maxRequestsPerDay === undefined ? undefined : `${current.requestsStarted}/${caps.maxRequestsPerDay} requests`,
+                caps.maxInputTokensPerDay === undefined ? undefined : `${current.inputTokens}/${caps.maxInputTokensPerDay} input tokens`,
+                caps.maxUsdPerDay === undefined ? undefined : `$${current.estimatedUsd.toFixed(4)}/$${caps.maxUsdPerDay.toFixed(2)}`,
+            ].filter((part) => part !== undefined);
+            return `${current.requestsStarted} requests today (${current.requestsSucceeded} ok, ${current.requestsFailed} failed), ${current.inputTokens} input / ${current.outputTokens} output tokens, ~$${current.estimatedUsd.toFixed(4)}${limits.length ? `; caps ${limits.join(", ")}` : "; no daily cap"}`;
+        },
+    };
+}

package/node_modules/pi-typesafe/examples/decision-extension.ts

@@ -0,0 +1,41 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ask, authState, createTypeSafe, choice, describeAuth, noul } from "pi-typesafe";
+
+// A separate extension using the public API, not pi-typesafe's private modules.
+// It owns its own consent and request budget; it does not reuse /typesafe enable.
+export default function decisionExample(pi: ExtensionAPI): void {
+  pi.registerCommand("decision-demo", {
+    description: "Send one synthetic, batched decision request to TypeSafe",
+    async handler(_args, ctx) {
+      if (!ctx.hasUI) return;
+      // Say which key is in effect before showing a data notice, so a missing one is not mistaken for consent.
+      const auth = describeAuth(authState());
+      if (auth.level === "error") {
+        ctx.ui.notify(auth.text, "warning");
+        return;
+      }
+      if (!await ctx.ui.confirm("Send a TypeSafe request?", "This synthetic example goes to api.typesafe.ai and may incur charges.")) return;
+      try {
+        // One client instance, one session budget, and a daily spend cap the script cannot forget.
+        const client = createTypeSafe({ maxRequests: 1, maxUsdPerDay: 1 });
+        const answer = await ask(client, {
+          state: "Please refund the duplicate charge.",
+          questions: {
+            team: choice("Which team should handle the request?", {
+              billing: "Payments and refunds", engineering: "Software defects", other: "Anything else",
+            }),
+            refund: noul("Is the sender requesting a refund?"),
+          },
+        }, { timeoutMs: 5_000 });
+        if (!answer.ok) {
+          ctx.ui.notify(answer.errorCode === "budget" ? `No request was sent: ${answer.error}` : "The example could not complete.", "warning");
+          return;
+        }
+        ctx.ui.notify(`Team: ${answer.answers.team.choice}; P(refund): ${answer.answers.refund.noul}; ${answer.elapsedMs} ms`, "info");
+      } catch (error) {
+        // createTypeSafe rejects an unusable key store; ask() never throws.
+        ctx.ui.notify(error instanceof Error ? error.message : "The example could not start.", "error");
+      }
+    },
+  });
+}

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

@@ -0,0 +1,2 @@
+// Pi entry point. Kept at extensions/index.js so Pi lists the extension as "pi-typesafe".
+export { default } from "../dist/extension.js";