@code-yeongyu/senpi 2026.8.1 → 2026.8.3-3

package/node_modules/@earendil-works/pi-ai/dist/utils/retry-hint.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Strict 429 retry-hint extractor with canonical marker helpers.
+ *
+ * Precedence (first match wins, malformed source falls through):
+ *   1. retry-after-ms header  (strict `^\d+(?:\.\d+)?$`, ceil)
+ *   2. retry-after header      (strict integer delta-seconds `^\d+$`, else HTTP-date)
+ *   3. x-ratelimit-reset{,-requests,-tokens}  (epoch seconds, max-wins)
+ *   4. JSON retryDelay strings (ms/s/m units, recursive, max-wins; numeric rejected)
+ *   5. body prose              (ms-marker, seconds-marker, relative, resets-at ISO8601)
+ *
+ * Eligibility gate: status 429 OR body marks rate-limit error.
+ * Explicit zero = 0 (beats lower-precedence positives).
+ * Past absolute times clamp to 0.
+ * Absolute times resolve against response Date header (clock-skew safe), else nowMs.
+ */
+export interface RetryHintInput {
+    status?: number;
+    headers?: Headers;
+    bodyText: string;
+}
+export declare function extract429RetryAfterMs(input: RetryHintInput, nowMs?: number): number | undefined;
+export declare function appendRetryAfterMsMarker(message: string, hintMs: number): string;
+export declare function parseRetryAfterMsMarker(message: string): number | undefined;
+//# sourceMappingURL=retry-hint.d.ts.map

package/node_modules/@earendil-works/pi-ai/dist/utils/retry-hint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-hint.d.ts","sourceRoot":"","sources":["../../src/utils/retry-hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAgBH,MAAM,WAAW,cAAc;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CACjB;AA+KD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAuBhG;AAID,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEhF;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI3E"}

package/node_modules/@earendil-works/pi-ai/dist/utils/retry-hint.js

@@ -0,0 +1,233 @@
+/**
+ * Strict 429 retry-hint extractor with canonical marker helpers.
+ *
+ * Precedence (first match wins, malformed source falls through):
+ *   1. retry-after-ms header  (strict `^\d+(?:\.\d+)?$`, ceil)
+ *   2. retry-after header      (strict integer delta-seconds `^\d+$`, else HTTP-date)
+ *   3. x-ratelimit-reset{,-requests,-tokens}  (epoch seconds, max-wins)
+ *   4. JSON retryDelay strings (ms/s/m units, recursive, max-wins; numeric rejected)
+ *   5. body prose              (ms-marker, seconds-marker, relative, resets-at ISO8601)
+ *
+ * Eligibility gate: status 429 OR body marks rate-limit error.
+ * Explicit zero = 0 (beats lower-precedence positives).
+ * Past absolute times clamp to 0.
+ * Absolute times resolve against response Date header (clock-skew safe), else nowMs.
+ */
+const MARKER_RE = /\(retry-after-ms: (\d+)\)$/;
+const RATE_LIMIT_BODY_RE = /\b(rate_limit_error|rate_limit_exceeded|too_many_requests|resource_exhausted|rate limit (?:exceeded|hit)|too many requests)\b/i;
+const RATE_LIMIT_JSON_VALUES = new Set([
+    "rate_limit_error",
+    "rate_limit_exceeded",
+    "too_many_requests",
+    "resource_exhausted",
+]);
+const RETRY_AFTER_MS_RE = /^\d+(?:\.\d+)?$/;
+const DELTA_SECONDS_RE = /^\d+$/;
+/* ---------- eligibility ---------- */
+function isRateLimited(status, bodyText) {
+    if (status === 429)
+        return true;
+    if (RATE_LIMIT_BODY_RE.test(bodyText))
+        return true;
+    // JSON type/code fields or retryDelay presence (rate-limit signal)
+    const json = tryParseJSON(bodyText);
+    if (json !== undefined) {
+        const found = scanValue(json, (v, k) => {
+            if (k !== undefined && k.toLowerCase() === "retrydelay" && typeof v === "string")
+                return true;
+            if (typeof v === "string" && RATE_LIMIT_JSON_VALUES.has(v))
+                return true;
+            if (v === 429)
+                return true;
+            return false;
+        });
+        if (found)
+            return true;
+    }
+    return false;
+}
+/* ---------- 1. retry-after-ms header ---------- */
+function fromRetryAfterMsHeader(h) {
+    const raw = h?.get("retry-after-ms");
+    if (raw === null || raw === undefined)
+        return undefined;
+    if (!RETRY_AFTER_MS_RE.test(raw))
+        return undefined;
+    const val = Number.parseFloat(raw);
+    if (!Number.isFinite(val) || val < 0)
+        return undefined;
+    return Math.ceil(val);
+}
+/* ---------- 2. retry-after header ---------- */
+function fromRetryAfterHeader(h, nowMs) {
+    const raw = h?.get("retry-after");
+    if (raw === null || raw === undefined)
+        return undefined;
+    // integer delta-seconds
+    if (DELTA_SECONDS_RE.test(raw)) {
+        return Number.parseInt(raw, 10) * 1000;
+    }
+    // HTTP-date — must contain alphabetic chars to be a real date string
+    if (/[a-zA-Z]/.test(raw)) {
+        const parsed = Date.parse(raw);
+        if (!Number.isNaN(parsed)) {
+            const base = dateHeaderMs(h) ?? nowMs;
+            return clampAbsolute(parsed, base);
+        }
+    }
+    return undefined;
+}
+/* ---------- 3. x-ratelimit-reset* headers ---------- */
+function fromXRateLimitReset(h, nowMs) {
+    let best;
+    for (const key of ["x-ratelimit-reset", "x-ratelimit-reset-requests", "x-ratelimit-reset-tokens"]) {
+        const raw = h?.get(key);
+        if (raw === null || raw === undefined)
+            continue;
+        const epoch = Number.parseFloat(raw);
+        if (!Number.isFinite(epoch) || epoch < 0)
+            continue;
+        // reject "12abc" — strict number check
+        if (!/^\d+(?:\.\d+)?$/.test(raw))
+            continue;
+        const delta = Math.ceil(epoch * 1000 - nowMs);
+        const clamped = Math.max(0, delta);
+        if (best === undefined || clamped > best)
+            best = clamped;
+    }
+    return best;
+}
+/* ---------- 4. JSON retryDelay (recursive, max-wins) ---------- */
+const RETRY_DELAY_RE = /^(\d+(?:\.\d+)?)\s*(ms|s|m)$/;
+function fromJsonRetryDelay(bodyText) {
+    const json = tryParseJSON(bodyText);
+    if (json === undefined)
+        return undefined;
+    let best;
+    scanValue(json, (v) => {
+        if (typeof v !== "string")
+            return false;
+        const m = v.match(RETRY_DELAY_RE);
+        if (!m)
+            return false;
+        const num = Number.parseFloat(m[1]);
+        const unit = m[2];
+        const ms = unit === "ms" ? num : unit === "s" ? num * 1000 : num * 60_000;
+        const intMs = Math.ceil(ms);
+        if (best === undefined || intMs > best)
+            best = intMs;
+        return false; // keep scanning
+    });
+    return best;
+}
+/* ---------- 5. body prose ---------- */
+function fromBodyProse(bodyText, nowMs) {
+    // ms-marker: retry-after-ms: <N>
+    let m = bodyText.match(/retry-after-ms:\s*(\d+)/i);
+    if (m)
+        return Number.parseInt(m[1], 10);
+    // seconds-marker: retry-after: <N>
+    m = bodyText.match(/retry-after:\s*(\d+)/i);
+    if (m)
+        return Number.parseInt(m[1], 10) * 1000;
+    // relative prose: try again | retry | wait after ... [in] N <unit>
+    m = bodyText.match(/(?:try again|retry|wait after).*?(?:in\s+)?(\d+(?:\.\d+)?)\s*(ms|s|sec|seconds?|m|min|minutes?)\b/i);
+    if (m)
+        return convertUnit(Number.parseFloat(m[1]), m[2]);
+    // resets at <ISO8601-with-tz>
+    m = bodyText.match(/resets?\s+at\s+(\S+)/i);
+    if (m) {
+        const parsed = Date.parse(m[1]);
+        if (!Number.isNaN(parsed))
+            return clampAbsolute(parsed, nowMs);
+    }
+    return undefined;
+}
+/* ---------- helpers ---------- */
+function dateHeaderMs(h) {
+    const raw = h?.get("date");
+    if (raw === null || raw === undefined)
+        return undefined;
+    const parsed = Date.parse(raw);
+    return Number.isNaN(parsed) ? undefined : parsed;
+}
+function clampAbsolute(targetMs, baseMs) {
+    return Math.max(0, targetMs - baseMs);
+}
+function convertUnit(num, unit) {
+    const u = unit.toLowerCase();
+    if (u === "ms")
+        return Math.ceil(num);
+    if (u === "s" || u === "sec" || u === "second" || u === "seconds")
+        return Math.ceil(num * 1000);
+    return Math.ceil(num * 60_000); // m / min / minute / minutes
+}
+/** Recursively walk JSON, calling fn on every leaf value with its key. */
+function scanValue(value, fn, key) {
+    if (value === null)
+        return fn(null, key);
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+        return fn(value, key);
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            if (scanValue(item, fn, key))
+                return true;
+        }
+        return false;
+    }
+    if (typeof value === "object") {
+        for (const [k, v] of Object.entries(value)) {
+            if (scanValue(v, fn, k))
+                return true;
+        }
+        return false;
+    }
+    return false;
+}
+function tryParseJSON(text) {
+    // strip SSE data: prefix lines
+    const cleaned = text.replace(/^data:\s*/gm, "").trim();
+    if (!cleaned.startsWith("{") && !cleaned.startsWith("["))
+        return undefined;
+    try {
+        return JSON.parse(cleaned);
+    }
+    catch {
+        return undefined;
+    }
+}
+/* ---------- main extractor ---------- */
+export function extract429RetryAfterMs(input, nowMs) {
+    const now = nowMs ?? Date.now();
+    if (!isRateLimited(input.status, input.bodyText))
+        return undefined;
+    // 1. retry-after-ms header
+    const fromMs = fromRetryAfterMsHeader(input.headers);
+    if (fromMs !== undefined)
+        return fromMs;
+    // 2. retry-after header
+    const fromRa = fromRetryAfterHeader(input.headers, now);
+    if (fromRa !== undefined)
+        return fromRa;
+    // 3. x-ratelimit-reset* headers
+    const fromXrl = fromXRateLimitReset(input.headers, now);
+    if (fromXrl !== undefined)
+        return fromXrl;
+    // 4. JSON retryDelay
+    const fromJson = fromJsonRetryDelay(input.bodyText);
+    if (fromJson !== undefined)
+        return fromJson;
+    // 5. body prose
+    return fromBodyProse(input.bodyText, now);
+}
+/* ---------- marker helpers ---------- */
+export function appendRetryAfterMsMarker(message, hintMs) {
+    return `${message} (retry-after-ms: ${hintMs})`;
+}
+export function parseRetryAfterMsMarker(message) {
+    const m = message.match(MARKER_RE);
+    if (!m)
+        return undefined;
+    return Number.parseInt(m[1], 10);
+}
+//# sourceMappingURL=retry-hint.js.map

package/node_modules/@earendil-works/pi-ai/dist/utils/retry-hint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-hint.js","sourceRoot":"","sources":["../../src/utils/retry-hint.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Strict 429 retry-hint extractor with canonical marker helpers.\n *\n * Precedence (first match wins, malformed source falls through):\n *   1. retry-after-ms header  (strict `^\\d+(?:\\.\\d+)?$`, ceil)\n *   2. retry-after header      (strict integer delta-seconds `^\\d+$`, else HTTP-date)\n *   3. x-ratelimit-reset{,-requests,-tokens}  (epoch seconds, max-wins)\n *   4. JSON retryDelay strings (ms/s/m units, recursive, max-wins; numeric rejected)\n *   5. body prose              (ms-marker, seconds-marker, relative, resets-at ISO8601)\n *\n * Eligibility gate: status 429 OR body marks rate-limit error.\n * Explicit zero = 0 (beats lower-precedence positives).\n * Past absolute times clamp to 0.\n * Absolute times resolve against response Date header (clock-skew safe), else nowMs.\n */\n\nconst MARKER_RE = /\\(retry-after-ms: (\\d+)\\)$/;\nconst RATE_LIMIT_BODY_RE =\n\t/\\b(rate_limit_error|rate_limit_exceeded|too_many_requests|resource_exhausted|rate limit (?:exceeded|hit)|too many requests)\\b/i;\nconst RATE_LIMIT_JSON_VALUES = new Set([\n\t\"rate_limit_error\",\n\t\"rate_limit_exceeded\",\n\t\"too_many_requests\",\n\t\"resource_exhausted\",\n]);\nconst RETRY_AFTER_MS_RE = /^\\d+(?:\\.\\d+)?$/;\nconst DELTA_SECONDS_RE = /^\\d+$/;\n\n/* ---------- public types ---------- */\n\nexport interface RetryHintInput {\n\tstatus?: number;\n\theaders?: Headers;\n\tbodyText: string;\n}\n\n/* ---------- eligibility ---------- */\n\nfunction isRateLimited(status: number | undefined, bodyText: string): boolean {\n\tif (status === 429) return true;\n\tif (RATE_LIMIT_BODY_RE.test(bodyText)) return true;\n\t// JSON type/code fields or retryDelay presence (rate-limit signal)\n\tconst json = tryParseJSON(bodyText);\n\tif (json !== undefined) {\n\t\tconst found = scanValue(json, (v, k) => {\n\t\t\tif (k !== undefined && k.toLowerCase() === \"retrydelay\" && typeof v === \"string\") return true;\n\t\t\tif (typeof v === \"string\" && RATE_LIMIT_JSON_VALUES.has(v)) return true;\n\t\t\tif (v === 429) return true;\n\t\t\treturn false;\n\t\t});\n\t\tif (found) return true;\n\t}\n\treturn false;\n}\n\n/* ---------- 1. retry-after-ms header ---------- */\n\nfunction fromRetryAfterMsHeader(h: Headers | undefined): number | undefined {\n\tconst raw = h?.get(\"retry-after-ms\");\n\tif (raw === null || raw === undefined) return undefined;\n\tif (!RETRY_AFTER_MS_RE.test(raw)) return undefined;\n\tconst val = Number.parseFloat(raw);\n\tif (!Number.isFinite(val) || val < 0) return undefined;\n\treturn Math.ceil(val);\n}\n\n/* ---------- 2. retry-after header ---------- */\n\nfunction fromRetryAfterHeader(h: Headers | undefined, nowMs: number): number | undefined {\n\tconst raw = h?.get(\"retry-after\");\n\tif (raw === null || raw === undefined) return undefined;\n\t// integer delta-seconds\n\tif (DELTA_SECONDS_RE.test(raw)) {\n\t\treturn Number.parseInt(raw, 10) * 1000;\n\t}\n\t// HTTP-date — must contain alphabetic chars to be a real date string\n\tif (/[a-zA-Z]/.test(raw)) {\n\t\tconst parsed = Date.parse(raw);\n\t\tif (!Number.isNaN(parsed)) {\n\t\t\tconst base = dateHeaderMs(h) ?? nowMs;\n\t\t\treturn clampAbsolute(parsed, base);\n\t\t}\n\t}\n\treturn undefined;\n}\n\n/* ---------- 3. x-ratelimit-reset* headers ---------- */\n\nfunction fromXRateLimitReset(h: Headers | undefined, nowMs: number): number | undefined {\n\tlet best: number | undefined;\n\tfor (const key of [\"x-ratelimit-reset\", \"x-ratelimit-reset-requests\", \"x-ratelimit-reset-tokens\"]) {\n\t\tconst raw = h?.get(key);\n\t\tif (raw === null || raw === undefined) continue;\n\t\tconst epoch = Number.parseFloat(raw);\n\t\tif (!Number.isFinite(epoch) || epoch < 0) continue;\n\t\t// reject \"12abc\" — strict number check\n\t\tif (!/^\\d+(?:\\.\\d+)?$/.test(raw)) continue;\n\t\tconst delta = Math.ceil(epoch * 1000 - nowMs);\n\t\tconst clamped = Math.max(0, delta);\n\t\tif (best === undefined || clamped > best) best = clamped;\n\t}\n\treturn best;\n}\n\n/* ---------- 4. JSON retryDelay (recursive, max-wins) ---------- */\n\nconst RETRY_DELAY_RE = /^(\\d+(?:\\.\\d+)?)\\s*(ms|s|m)$/;\n\nfunction fromJsonRetryDelay(bodyText: string): number | undefined {\n\tconst json = tryParseJSON(bodyText);\n\tif (json === undefined) return undefined;\n\tlet best: number | undefined;\n\tscanValue(json, (v) => {\n\t\tif (typeof v !== \"string\") return false;\n\t\tconst m = v.match(RETRY_DELAY_RE);\n\t\tif (!m) return false;\n\t\tconst num = Number.parseFloat(m[1]);\n\t\tconst unit = m[2];\n\t\tconst ms = unit === \"ms\" ? num : unit === \"s\" ? num * 1000 : num * 60_000;\n\t\tconst intMs = Math.ceil(ms);\n\t\tif (best === undefined || intMs > best) best = intMs;\n\t\treturn false; // keep scanning\n\t});\n\treturn best;\n}\n\n/* ---------- 5. body prose ---------- */\n\nfunction fromBodyProse(bodyText: string, nowMs: number): number | undefined {\n\t// ms-marker: retry-after-ms: <N>\n\tlet m = bodyText.match(/retry-after-ms:\\s*(\\d+)/i);\n\tif (m) return Number.parseInt(m[1], 10);\n\n\t// seconds-marker: retry-after: <N>\n\tm = bodyText.match(/retry-after:\\s*(\\d+)/i);\n\tif (m) return Number.parseInt(m[1], 10) * 1000;\n\n\t// relative prose: try again | retry | wait after ... [in] N <unit>\n\tm = bodyText.match(\n\t\t/(?:try again|retry|wait after).*?(?:in\\s+)?(\\d+(?:\\.\\d+)?)\\s*(ms|s|sec|seconds?|m|min|minutes?)\\b/i,\n\t);\n\tif (m) return convertUnit(Number.parseFloat(m[1]), m[2]);\n\n\t// resets at <ISO8601-with-tz>\n\tm = bodyText.match(/resets?\\s+at\\s+(\\S+)/i);\n\tif (m) {\n\t\tconst parsed = Date.parse(m[1]);\n\t\tif (!Number.isNaN(parsed)) return clampAbsolute(parsed, nowMs);\n\t}\n\n\treturn undefined;\n}\n\n/* ---------- helpers ---------- */\n\nfunction dateHeaderMs(h: Headers | undefined): number | undefined {\n\tconst raw = h?.get(\"date\");\n\tif (raw === null || raw === undefined) return undefined;\n\tconst parsed = Date.parse(raw);\n\treturn Number.isNaN(parsed) ? undefined : parsed;\n}\n\nfunction clampAbsolute(targetMs: number, baseMs: number): number {\n\treturn Math.max(0, targetMs - baseMs);\n}\n\nfunction convertUnit(num: number, unit: string): number {\n\tconst u = unit.toLowerCase();\n\tif (u === \"ms\") return Math.ceil(num);\n\tif (u === \"s\" || u === \"sec\" || u === \"second\" || u === \"seconds\") return Math.ceil(num * 1000);\n\treturn Math.ceil(num * 60_000); // m / min / minute / minutes\n}\n\n/** Recursively walk JSON, calling fn on every leaf value with its key. */\nfunction scanValue(\n\tvalue: unknown,\n\tfn: (v: string | number | boolean | null, key?: string) => boolean,\n\tkey?: string,\n): boolean {\n\tif (value === null) return fn(null, key);\n\tif (typeof value === \"string\" || typeof value === \"number\" || typeof value === \"boolean\") return fn(value, key);\n\tif (Array.isArray(value)) {\n\t\tfor (const item of value) {\n\t\t\tif (scanValue(item, fn, key)) return true;\n\t\t}\n\t\treturn false;\n\t}\n\tif (typeof value === \"object\") {\n\t\tfor (const [k, v] of Object.entries(value)) {\n\t\t\tif (scanValue(v, fn, k)) return true;\n\t\t}\n\t\treturn false;\n\t}\n\treturn false;\n}\n\nfunction tryParseJSON(text: string): unknown {\n\t// strip SSE data: prefix lines\n\tconst cleaned = text.replace(/^data:\\s*/gm, \"\").trim();\n\tif (!cleaned.startsWith(\"{\") && !cleaned.startsWith(\"[\")) return undefined;\n\ttry {\n\t\treturn JSON.parse(cleaned);\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/* ---------- main extractor ---------- */\n\nexport function extract429RetryAfterMs(input: RetryHintInput, nowMs?: number): number | undefined {\n\tconst now = nowMs ?? Date.now();\n\n\tif (!isRateLimited(input.status, input.bodyText)) return undefined;\n\n\t// 1. retry-after-ms header\n\tconst fromMs = fromRetryAfterMsHeader(input.headers);\n\tif (fromMs !== undefined) return fromMs;\n\n\t// 2. retry-after header\n\tconst fromRa = fromRetryAfterHeader(input.headers, now);\n\tif (fromRa !== undefined) return fromRa;\n\n\t// 3. x-ratelimit-reset* headers\n\tconst fromXrl = fromXRateLimitReset(input.headers, now);\n\tif (fromXrl !== undefined) return fromXrl;\n\n\t// 4. JSON retryDelay\n\tconst fromJson = fromJsonRetryDelay(input.bodyText);\n\tif (fromJson !== undefined) return fromJson;\n\n\t// 5. body prose\n\treturn fromBodyProse(input.bodyText, now);\n}\n\n/* ---------- marker helpers ---------- */\n\nexport function appendRetryAfterMsMarker(message: string, hintMs: number): string {\n\treturn `${message} (retry-after-ms: ${hintMs})`;\n}\n\nexport function parseRetryAfterMsMarker(message: string): number | undefined {\n\tconst m = message.match(MARKER_RE);\n\tif (!m) return undefined;\n\treturn Number.parseInt(m[1], 10);\n}\n"]}

package/node_modules/@earendil-works/pi-ai/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@earendil-works/pi-ai",
 	"private": true,
-	"version": "2026.8.1",
+	"version": "2026.8.3-3",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -28,6 +28,10 @@
 			"types": "./dist/api/*.d.ts",
 			"import": "./dist/api/*.js"
 		},
+		"./utils/*": {
+			"types": "./dist/utils/*.d.ts",
+			"import": "./dist/utils/*.js"
+		},
 		"./oauth": {
 			"types": "./dist/oauth.d.ts",
 			"import": "./dist/oauth.js"
@@ -59,12 +63,12 @@
 		"generate-model-catalog": "tsx scripts/generate-models.ts --strict --json-only --json-output ../../.artifacts/model-catalog",
 		"generate-image-models": "tsx scripts/generate-image-models.ts --strict",
 		"check:model-data": "tsx scripts/check-model-data.ts",
-		"build": "tsgo -p tsconfig.build.json && shx chmod +x dist/cli.js && shx rm -rf dist/providers/data && shx cp -r src/providers/data dist/providers/data",
-		"build:offline": "npm run check:model-data && tsgo -p tsconfig.build.json && shx chmod +x dist/cli.js && shx rm -rf dist/providers/data && shx cp -r src/providers/data dist/providers/data",
-		"dev": "tsgo -p tsconfig.build.json --watch --preserveWatchOutput",
-		"dev:tsc": "tsgo -p tsconfig.build.json --watch --preserveWatchOutput",
+		"build": "tsc -p tsconfig.build.json && shx chmod +x dist/cli.js && shx rm -rf dist/providers/data && shx cp -r src/providers/data dist/providers/data",
+		"build:offline": "npm run check:model-data && tsc -p tsconfig.build.json && shx chmod +x dist/cli.js && shx rm -rf dist/providers/data && shx cp -r src/providers/data dist/providers/data",
+		"dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+		"dev:tsc": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
 		"test": "vitest --run",
-		"prepublishOnly": "shx rm -rf dist && tsx scripts/generate-models.ts && tsx scripts/generate-image-models.ts && tsgo -p tsconfig.build.json && shx chmod +x dist/cli.js"
+		"prepublishOnly": "shx rm -rf dist && tsx scripts/generate-models.ts && tsx scripts/generate-image-models.ts && tsc -p tsconfig.build.json && shx chmod +x dist/cli.js"
 	},
 	"dependencies": {
 		"@anthropic-ai/sdk": "0.91.1",

package/node_modules/@earendil-works/pi-pty/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@earendil-works/pi-pty",
 	"private": true,
-	"version": "2026.8.1",
+	"version": "2026.8.3-3",
 	"description": "Typed PTY session loader for Senpi persistent terminals",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -32,7 +32,7 @@
 	],
 	"scripts": {
 		"clean": "shx rm -rf dist",
-		"build": "tsgo -p tsconfig.build.json",
+		"build": "tsc -p tsconfig.build.json",
 		"test": "vitest --run test",
 		"check:prebuild": "node native/check-prebuild-fresh.mjs",
 		"prepublishOnly": "npm run clean && npm run build"

package/node_modules/@earendil-works/pi-tui/README.md

@@ -4,25 +4,27 @@ Minimal terminal UI framework with differential rendering and synchronized outpu
 
 ## Features
 
-- **Differential Rendering**: Three-strategy rendering system that only updates what changed
+- **Interchangeable Renderers**: Shared `TUI` interface with main-screen and alternate-screen implementations
+- **Differential Rendering**: Updates only changed lines or viewport rows
+- **Application-owned Scrolling**: Alternate-screen viewport supports mouse, trackpad, and keyboard navigation
 - **Synchronized Output**: Uses CSI 2026 for atomic screen updates (no flicker)
 - **Bracketed Paste Mode**: Handles large pastes correctly with markers for >10 line pastes
 - **Component-based**: Simple Component interface with render() method
 - **Theme Support**: Components accept theme interfaces for customizable styling
-- **Built-in Components**: Text, TruncatedText, Input, Editor, Markdown, Loader, SelectList, SettingsList, Spacer, Image, Box, Container
+- **Built-in Components**: Text, TruncatedText, Input, Editor, Markdown, Loader, SelectList, SettingsList, Spacer, Image, Box, Container, VStack, HStack, ScrollView
 - **Inline Images**: Renders images in terminals that support Kitty or iTerm2 graphics protocols
 - **Autocomplete Support**: File paths and slash commands
 
 ## Quick Start
 
 ```typescript
-import { TUI, Text, Editor, ProcessTerminal, matchesKey } from "@earendil-works/pi-tui";
+import { type TUI, Text, Editor, ProcessTerminal, TuiMainScreen, matchesKey } from "@earendil-works/pi-tui";
 
 // Create terminal
 const terminal = new ProcessTerminal();
 
-// Create TUI
-const tui = new TUI(terminal);
+// Create the default main-screen renderer through the shared TUI interface
+const tui: TUI = new TuiMainScreen(terminal);
 
 // Add components
 tui.addChild(new Text("Welcome to my app!"));
@@ -52,12 +54,20 @@ tui.start();
 
 ## Core API
 
-### TUI
+### TUI interface and renderers
 
-Main container that manages components and rendering.
+`TUI` is the shared interface for component management, focus, overlays, input, lifecycle, terminal queries, and rendering. Choose a concrete renderer only when constructing the application:
+
+- `TuiMainScreen` renders into the main terminal buffer and preserves terminal scrollback.
+- `TuiAltScreen` renders a fixed-height viewport in the alternate terminal buffer with application-owned scrolling. When stopped, it restores the main buffer and prints the complete final document.
 
 ```typescript
-const tui = new TUI(terminal);
+import { type TUI, TuiAltScreen, TuiMainScreen } from "@earendil-works/pi-tui";
+
+const tui: TUI = new TuiMainScreen(terminal);
+// To use an application-owned viewport in the alternate terminal buffer instead:
+// const tui: TUI = new TuiAltScreen(terminal);
+
 tui.addChild(component);
 tui.removeChild(component);
 tui.start();
@@ -68,6 +78,53 @@ tui.requestRender(); // Request a re-render
 tui.onDebug = () => console.log("Debug triggered");
 ```
 
+### Alternate-screen viewport layouts
+
+`TuiAltScreen` can render an explicit terminal-height layout. `VStack` and `HStack` allocate constrained regions, while `ScrollView` owns scrolling for one region. These semantics are intentionally unavailable on `TuiMainScreen`, where the terminal owns scrollback.
+
+```typescript
+import {
+  Container,
+  isViewportTUI,
+  ScrollView,
+  Text,
+  VStack,
+} from "@earendil-works/pi-tui";
+
+const transcript = new Container();
+transcript.addChild(new Text("History"));
+
+const editorAndFooter = new VStack([
+  editor,
+  new Text("status"),
+]);
+
+if (isViewportTUI(tui)) {
+  tui.setLayoutRoot(new VStack([
+    {
+      component: new ScrollView(transcript, {
+        follow: "end",
+        primary: true,
+        overscroll: "chain",
+      }),
+      basis: 0,
+      grow: 1,
+      minSize: 1,
+    },
+    {
+      component: editorAndFooter,
+      basis: "auto",
+      shrink: 1,
+      minSize: 1,
+    },
+  ]));
+}
+```
+
+Stack entries support `basis`, `grow`, `shrink`, `minSize`, `maxSize`, and responsive `visible` callbacks. Mouse-wheel input targets the scroll view under the pointer and unused delta chains to outer scroll views by default. The primary scroll view receives the alternate-screen keyboard navigation actions and wheel input over non-scrollable regions. It can also jump between OSC 133 semantic prompt markers, matching common terminal prompt-navigation shortcuts.
+
+Layout geometry is rebuilt for each requested frame. Stateful components are retained, and their existing rendered-line caches remain effective. Calling `render(width)` directly on these layout components produces an unbounded document, which is also used when alt mode restores the main screen.
+
 ### Overlays
 
 Overlays render components on top of existing content without replacing it. Useful for dialogs, menus, and modal UI.
@@ -190,7 +247,7 @@ When a `Focusable` component has focus, TUI:
 3. Positions the hardware terminal cursor at that location
 4. Shows the hardware cursor only when `showHardwareCursor` is enabled
 
-The cursor remains hidden by default. This keeps the fake cursor rendering, while still positioning the hardware cursor for terminals that track IME candidate windows with hidden cursors. Some terminals require a visible hardware cursor for IME positioning; enable it with the `TUI` constructor option, `setShowHardwareCursor(true)`, or `PI_HARDWARE_CURSOR=1`. The `Editor` and `Input` built-in components already implement this interface.
+The cursor remains hidden by default. This keeps the fake cursor rendering, while still positioning the hardware cursor for terminals that track IME candidate windows with hidden cursors. Some terminals require a visible hardware cursor for IME positioning; enable it with the renderer constructor's `showHardwareCursor` argument, `setShowHardwareCursor(true)`, or `PI_HARDWARE_CURSOR=1`. The `Editor` and `Input` built-in components already implement this interface.
 
 **Container components with embedded inputs:** When a container component (dialog, selector, etc.) contains an `Input` or `Editor` child, the container must implement `Focusable` and propagate the focus state to the child:
 
@@ -535,6 +592,10 @@ tui.addChild(image);
 
 Supported formats: PNG, JPEG, GIF, WebP. Dimensions are parsed from the image headers automatically.
 
+#### Alternate-screen image compatibility
+
+`TuiAltScreen` supports inline images and partial viewport cropping in terminals that implement the Kitty graphics protocol, including Kitty and Ghostty. iTerm2's inline-image protocol does not provide operations to delete an existing placement or crop its source while scrolling. To prevent stale images from remaining over repainted content, `TuiAltScreen` renders image components as text placeholders in iTerm2. `TuiMainScreen` continues to render iTerm2 inline images normally.
+
 ## Autocomplete
 
 ### CombinedAutocompleteProvider
@@ -588,15 +649,17 @@ if (matchesKey(data, Key.enter)) {
 - With modifiers: `Key.ctrl("c")`, `Key.shift("tab")`, `Key.alt("left")`, `Key.ctrlShift("p")`
 - String format also works: `"enter"`, `"ctrl+c"`, `"shift+tab"`, `"ctrl+shift+p"`
 
-## Differential Rendering
+## Rendering modes
 
-The TUI uses three rendering strategies:
+`TuiMainScreen` uses three rendering strategies:
 
 1. **First Render**: Output all lines without clearing scrollback
-2. **Width Changed or Change Above Viewport**: Clear screen and full re-render
-3. **Normal Update**: Move cursor to first changed line, clear to end, render changed lines
+2. **Width Changed or Change Above Viewport**: Clear screen and fully re-render
+3. **Normal Update**: Move the cursor to the first changed line, clear to the end, and render changed lines
+
+`TuiAltScreen` owns a terminal-height viewport. Without an explicit layout root it preserves the legacy single-document scrolling behavior. With `setLayoutRoot()`, `VStack`, `HStack`, and nested `ScrollView` components can reserve fixed regions and independently scroll constrained regions. It updates changed viewport rows in place, follows streaming output while at the bottom, and preserves a manually selected scroll position while content grows. Mouse-wheel and configurable keyboard navigation scroll without modifying terminal scrollback, including jumps between OSC 133 semantic prompt markers. Clicking an OSC 8 hyperlink opens it with the configured URL handler. Dragging with the primary mouse button selects text and copies it to the clipboard with OSC 52; holding the drag at a scroll view's top or bottom edge auto-scrolls and extends the selection into off-screen content. Kitty images support vertical viewport cropping; iTerm2 inline images fall back to text because the iTerm2 protocol cannot delete or crop placements during viewport repainting.
 
-All updates are wrapped in **synchronized output** (`\x1b[?2026h` ... `\x1b[?2026l`) for atomic, flicker-free rendering.
+Both renderers wrap updates in **synchronized output** (`\x1b[?2026h` ... `\x1b[?2026l`) for atomic, flicker-free rendering.
 
 ## Terminal Interface
 

package/node_modules/@earendil-works/pi-tui/dist/TuiAltScreen.d.ts

@@ -0,0 +1,83 @@
+import type { Terminal } from "./terminal.ts";
+import { type Component, TuiBase, VIEWPORT_TUI, type ViewportTUI } from "./tui.ts";
+export interface TuiAltScreenOptions {
+    /** Number of logical lines moved for each mouse-wheel event. */
+    wheelScrollLines?: number;
+    /** Capture mouse events for viewport scrolling and application-owned text selection. */
+    mouse?: boolean;
+    /** Open an OSC 8 hyperlink activated with a primary-button click. */
+    openUrl?: (url: string) => void;
+}
+/** Alternate-screen TUI with a scrollable, application-owned viewport. */
+export declare class TuiAltScreen extends TuiBase implements ViewportTUI {
+    readonly [VIEWPORT_TUI]: true;
+    private previousScreen;
+    private lastDocument;
+    private previousScreenWidth;
+    private previousScreenHeight;
+    private layoutRoot;
+    private currentLayout;
+    private readonly implicitDocument;
+    private readonly implicitScrollView;
+    private readonly flashes;
+    private altScreenActive;
+    private imageProtocol;
+    private savedCapabilities?;
+    private selectionAnchor?;
+    private selectionFocus?;
+    private selectionDragPointer?;
+    private selectionAutoScrollDirection;
+    private selectionAutoScrollTimer?;
+    private selectionPressActive;
+    private scrollbarDrag?;
+    private scrollbarHover?;
+    private pressedUrl?;
+    private selectionDragged;
+    private readonly wheelScrollLines;
+    private readonly mouseEnabled;
+    private readonly openUrl?;
+    constructor(terminal: Terminal, showHardwareCursor?: boolean, logDirectory?: string, options?: TuiAltScreenOptions);
+    get viewportTop(): number;
+    get isFollowingOutput(): boolean;
+    setLayoutRoot(component: Component | undefined): void;
+    render(width: number): string[];
+    invalidate(): void;
+    protected getMountedRoots(): readonly Component[];
+    private getPrimaryScrollView;
+    protected beforeTerminalStart(): void;
+    protected beforeTerminalStop(): void;
+    protected afterTerminalStop(): void;
+    private deleteAltScreenKittyImages;
+    protected resetRenderState(): void;
+    scrollBy(lines: number): void;
+    scrollToTop(): void;
+    scrollToBottom(): void;
+    private scrollToPrompt;
+    /** Show a transient message in the alternate-screen flash stack. */
+    flash(message: string, durationMs?: number): void;
+    private handleViewportInput;
+    private parseWheelEvent;
+    private routeWheel;
+    private parseSgrMouseEvent;
+    private getScrollbarTargetAt;
+    private setScrollbarHover;
+    private updateScrollbarHover;
+    private stopScrollbarHover;
+    private handleScrollbarMouseEvent;
+    private stopScrollbarDrag;
+    private getScrollSelectionPoint;
+    private getSelectionPoint;
+    private updateSelectionAutoScroll;
+    private autoScrollSelection;
+    private stopSelectionAutoScroll;
+    private handleSelectionMouseEvent;
+    private getSelectionBounds;
+    private getSelectionColumns;
+    private copySelectionToClipboard;
+    private applySelectionHighlight;
+    private applySelection;
+    private isMouseSequence;
+    private compositeFlashes;
+    protected doRender(): void;
+}
+//# sourceMappingURL=TuiAltScreen.d.ts.map

package/node_modules/@earendil-works/pi-tui/dist/TuiAltScreen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TuiAltScreen.d.ts","sourceRoot":"","sources":["../src/TuiAltScreen.ts"],"names":[],"mappings":"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"}