@code-yeongyu/senpi 2026.7.31 → 2026.8.3

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/dist/utils/unavailable-tool-text.d.ts

@@ -0,0 +1,3 @@
+export declare function demotedToolCallText(name: string, availableToolNames: readonly string[], firstOccurrence: boolean): string;
+export declare function demotedToolResultText(name: string, content: string): string;
+//# sourceMappingURL=unavailable-tool-text.d.ts.map

package/node_modules/@earendil-works/pi-ai/dist/utils/unavailable-tool-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unavailable-tool-text.d.ts","sourceRoot":"","sources":["../../src/utils/unavailable-tool-text.ts"],"names":[],"mappings":"AAqBA,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,MAAM,EACZ,kBAAkB,EAAE,SAAS,MAAM,EAAE,EACrC,eAAe,EAAE,OAAO,GACtB,MAAM,CAUR;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAI3E"}

package/node_modules/@earendil-works/pi-ai/dist/utils/unavailable-tool-text.js

@@ -0,0 +1,36 @@
+const MAX_LISTED_TOOLS = 8;
+function escapeXmlAttribute(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll('"', """)
+        .replaceAll("'", "'")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}
+function availableToolGuidance(availableToolNames) {
+    if (availableToolNames.length === 0) {
+        return "To edit files, call only tools available in this request.";
+    }
+    const listed = availableToolNames.slice(0, MAX_LISTED_TOOLS).join(", ");
+    const omitted = availableToolNames.length - MAX_LISTED_TOOLS;
+    const suffix = omitted > 0 ? ` (and ${omitted} more)` : "";
+    return `To edit files, call your own tools: ${listed}${suffix}.`;
+}
+export function demotedToolCallText(name, availableToolNames, firstOccurrence) {
+    const escapedName = escapeXmlAttribute(name);
+    if (!firstOccurrence)
+        return `<unavailable-tool-call name="${escapedName}"/>`;
+    return [
+        `<unavailable-tool-call name="${escapedName}">`,
+        "Transcript record, not an action available to you. An earlier model in this session",
+        `called "${escapedName}"; that tool does not exist for you and its input is omitted.`,
+        availableToolGuidance(availableToolNames),
+        "</unavailable-tool-call>",
+    ].join("\n");
+}
+export function demotedToolResultText(name, content) {
+    const escapedName = escapeXmlAttribute(name);
+    const safeContent = content.replace(/<\/unavailable-tool-result/gi, (match) => `&lt;${match.slice(1)}`);
+    return `<unavailable-tool-result name="${escapedName}">${safeContent}</unavailable-tool-result>`;
+}
+//# sourceMappingURL=unavailable-tool-text.js.map

package/node_modules/@earendil-works/pi-ai/dist/utils/unavailable-tool-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unavailable-tool-text.js","sourceRoot":"","sources":["../../src/utils/unavailable-tool-text.ts"],"names":[],"mappings":"AAAA,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAE3B,SAAS,kBAAkB,CAAC,KAAa;IACxC,OAAO,KAAK;SACV,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC;SACxB,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC;SACzB,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC;SACzB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC;SACvB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AAC3B,CAAC;AAED,SAAS,qBAAqB,CAAC,kBAAqC;IACnE,IAAI,kBAAkB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrC,OAAO,2DAA2D,CAAC;IACpE,CAAC;IACD,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxE,MAAM,OAAO,GAAG,kBAAkB,CAAC,MAAM,GAAG,gBAAgB,CAAC;IAC7D,MAAM,MAAM,GAAG,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3D,OAAO,uCAAuC,MAAM,GAAG,MAAM,GAAG,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,mBAAmB,CAClC,IAAY,EACZ,kBAAqC,EACrC,eAAwB;IAExB,MAAM,WAAW,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,CAAC,eAAe;QAAE,OAAO,gCAAgC,WAAW,KAAK,CAAC;IAC9E,OAAO;QACN,gCAAgC,WAAW,IAAI;QAC/C,qFAAqF;QACrF,WAAW,WAAW,+DAA+D;QACrF,qBAAqB,CAAC,kBAAkB,CAAC;QACzC,0BAA0B;KAC1B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACd,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,IAAY,EAAE,OAAe;IAClE,MAAM,WAAW,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,8BAA8B,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACxG,OAAO,kCAAkC,WAAW,KAAK,WAAW,4BAA4B,CAAC;AAClG,CAAC","sourcesContent":["const MAX_LISTED_TOOLS = 8;\n\nfunction escapeXmlAttribute(value: string): string {\n\treturn value\n\t\t.replaceAll(\"&\", \"&amp;\")\n\t\t.replaceAll('\"', \"&quot;\")\n\t\t.replaceAll(\"'\", \"&apos;\")\n\t\t.replaceAll(\"<\", \"&lt;\")\n\t\t.replaceAll(\">\", \"&gt;\");\n}\n\nfunction availableToolGuidance(availableToolNames: readonly string[]): string {\n\tif (availableToolNames.length === 0) {\n\t\treturn \"To edit files, call only tools available in this request.\";\n\t}\n\tconst listed = availableToolNames.slice(0, MAX_LISTED_TOOLS).join(\", \");\n\tconst omitted = availableToolNames.length - MAX_LISTED_TOOLS;\n\tconst suffix = omitted > 0 ? ` (and ${omitted} more)` : \"\";\n\treturn `To edit files, call your own tools: ${listed}${suffix}.`;\n}\n\nexport function demotedToolCallText(\n\tname: string,\n\tavailableToolNames: readonly string[],\n\tfirstOccurrence: boolean,\n): string {\n\tconst escapedName = escapeXmlAttribute(name);\n\tif (!firstOccurrence) return `<unavailable-tool-call name=\"${escapedName}\"/>`;\n\treturn [\n\t\t`<unavailable-tool-call name=\"${escapedName}\">`,\n\t\t\"Transcript record, not an action available to you. An earlier model in this session\",\n\t\t`called \"${escapedName}\"; that tool does not exist for you and its input is omitted.`,\n\t\tavailableToolGuidance(availableToolNames),\n\t\t\"</unavailable-tool-call>\",\n\t].join(\"\\n\");\n}\n\nexport function demotedToolResultText(name: string, content: string): string {\n\tconst escapedName = escapeXmlAttribute(name);\n\tconst safeContent = content.replace(/<\\/unavailable-tool-result/gi, (match) => `&lt;${match.slice(1)}`);\n\treturn `<unavailable-tool-result name=\"${escapedName}\">${safeContent}</unavailable-tool-result>`;\n}\n"]}

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

@@ -1,7 +1,7 @@
 {
 	"name": "@earendil-works/pi-ai",
 	"private": true,
-	"version": "2026.7.31",
+	"version": "2026.8.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-client/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+- Added the experimental transport-neutral `PiClient` and multi-session `PiSessionHandle` APIs with structured `PiServerError` responses.

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

@@ -0,0 +1,64 @@
+# @earendil-works/pi-client
+
+Transport-neutral client for remote pi sessions. `PiClient` exchanges length-prefixed CBOR messages through a small `ByteTransport` interface. The package has no Node-specific imports.
+
+```ts
+import { PiClient, type ByteTransportFactory } from "@earendil-works/pi-client";
+
+const transportFactory: ByteTransportFactory = async (handlers) => {
+  // Connect using WebSocket, Unix socket, or another ordered byte transport.
+  return {
+    async send(chunk) {
+      // Deliver chunks in invocation order and honor backpressure.
+    },
+    close() {},
+  };
+};
+
+const client = new PiClient({ token: bearerToken, transportFactory });
+await client.connect();
+const session = await client.createSession({ cwd: "/workspace" });
+const unsubscribe = session.subscribe((snapshot) => render(snapshot));
+await session.prompt("Inspect this project");
+unsubscribe();
+```
+
+Call `handlers.onData(chunk)` for inbound bytes, `handlers.onClose()` for an orderly terminal close, and `handlers.onError(error)` for transport failures. A factory must create a fresh transport for every connection attempt.
+
+`PiClient` does not reconnect automatically. Call `reconnect()` after disconnection. One connection can attach several sessions. Requests are correlated by ID. Server snapshots and successful response snapshots are authoritative, while progress events do not mutate snapshot state optimistically. Read cached session summaries from `client.snapshot?.sessions`; call `listSessions()` to request a refreshed list from the server.
+
+`acquireSession()` returns an independent `SessionLease`; leases cannot be constructed directly. Use `{ mode: "exclusive" }` for a lifecycle or mutation coordinator and `{ mode: "shared" }` when multiple low-level consumers intentionally share the session. Exclusive acquisition fails with `PiSessionOwnershipError` while any lease exists, and shared acquisition fails while an exclusive lease exists. `attachSession()` is a shared-acquisition convenience method. `createSession()` returns an exclusive lease for the newly created session.
+
+Calling `dispose()` or `detach()` releases only that lease. A lease rejects commands as soon as release begins. The client sends the protocol detach request after the final lease is released. If explicit `detach()` fails, the lease becomes active again for retry. If cleanup-oriented `dispose()` fails, it reports the protocol error but relinquishes local ownership; `PiClient` reconciles the failed protocol cleanup before the next acquisition. A released lease becomes unavailable without affecting other shared leases. Server removal or disconnection invalidates every lease for the affected attachment, and disposing an invalidated lease is a no-op. Commands fail with `PiDisconnectedError` while the client is disconnected and `PiSessionDetachedError` when the client is connected but a lease is releasing, released, or invalidated. Leases implement `AsyncDisposable`.
+
+`subscribe()` observes authoritative snapshots. `onEvent()` observes protocol events. Both return an unsubscribe function. Structured errors returned by the server are exposed as `PiServerError`.
+
+## Limits and security
+
+`PiClientOptions.maxFrameLength` bounds inbound and outbound CBOR payloads. Configure matching limits on the client and server. Transports should separately bound queued outbound bytes and preserve send order.
+
+Treat peers as untrusted. Use a secure transport where required and protect the protocol bearer token.
+
+Subscriber exceptions are isolated from protocol state. Set `onListenerError` in `PiClientOptions` to report them to application logging or diagnostics.
+
+## Unix-domain sockets
+
+Node.js and Bun consumers can use the separately exported Unix-domain socket transport:
+
+```ts
+import { PiClient } from "@earendil-works/pi-client";
+import { createUnixTransportFactory } from "@earendil-works/pi-client/unix";
+
+const client = new PiClient({
+  token: bearerToken,
+  transportFactory: createUnixTransportFactory({
+    path: "/tmp/pi.sock",
+  }),
+});
+
+await client.connect();
+```
+
+`maxPendingBytes` bounds queued outbound data. It defaults to four times the protocol frame limit. The transport preserves send order and waits for socket backpressure before resolving each send.
+
+The `@earendil-works/pi-client` root remains transport- and runtime-neutral. Importing the Node-compatible transport requires the explicit `@earendil-works/pi-client/unix` subpath.

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

@@ -0,0 +1,25 @@
+import { type ServerEvent, type ServerSnapshot, type SessionSummary } from "@earendil-works/pi-protocol";
+import { type AcquireSessionOptions, type PiSessionHandle } from "./session-handle.ts";
+import type { ConnectionState, ConnectionStateChange, CreateSessionOptions, PiClientOptions, Unsubscribe } from "./types.ts";
+export declare class PiClient {
+    #private;
+    constructor(options: PiClientOptions);
+    get disposed(): boolean;
+    get connectionState(): ConnectionState;
+    get connected(): boolean;
+    get snapshot(): ServerSnapshot | undefined;
+    static connect(options: PiClientOptions): Promise<PiClient>;
+    connect(): Promise<ServerSnapshot>;
+    reconnect(): Promise<ServerSnapshot>;
+    disconnect(reason?: string): void;
+    subscribe(listener: (snapshot: ServerSnapshot) => void): Unsubscribe;
+    onEvent(listener: (event: ServerEvent) => void): Unsubscribe;
+    onConnectionStateChange(listener: (change: ConnectionStateChange) => void): Unsubscribe;
+    listSessions(): Promise<readonly SessionSummary[]>;
+    createSession(options?: CreateSessionOptions): Promise<PiSessionHandle>;
+    attachSession(sessionId: string): Promise<PiSessionHandle>;
+    acquireSession(sessionId: string, options: AcquireSessionOptions): Promise<PiSessionHandle>;
+    dispose(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAQN,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,MAAM,6BAA6B,CAAC;AAWrC,OAAO,EACN,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EAIpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EACX,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,WAAW,EACX,MAAM,YAAY,CAAC;AAcpB,qBAAa,QAAQ;;IAiBpB,YAAY,OAAO,EAAE,eAAe,EAWnC;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,eAAe,IAAI,eAAe,CAErC;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,QAAQ,IAAI,cAAc,GAAG,SAAS,CAEzC;IAED,OAAa,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAShE;IAED,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,CAIjC;IAED,SAAS,IAAI,OAAO,CAAC,cAAc,CAAC,CAEnC;IAED,UAAU,CAAC,MAAM,SAAwB,GAAG,IAAI,CAE/C;IAED,SAAS,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,GAAG,WAAW,CAGnE;IAED,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,WAAW,CAG3D;IAED,uBAAuB,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,qBAAqB,KAAK,IAAI,GAAG,WAAW,CAItF;IAEK,YAAY,IAAI,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CAEvD;IAEK,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,eAAe,CAAC,CAIhF;IAEK,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAE/D;IAEK,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC,CA0BhG;IAqKD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAWvB;IAED,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAErC;CA2ED"}