@ashx-j/lunr 0.1.0

package/dist/core/subscriptions.d.ts

@@ -0,0 +1,64 @@
+/**
+ * lunr: multi-subscription API-key pools per provider.
+ *
+ * The pool lives in subscriptions.json next to auth.json; auth.json always
+ * holds the ACTIVE credential, so rotation is just mirroring the chosen pool
+ * key into auth.json via AuthStorage.modify. Persistence reuses the
+ * AuthStorage backend classes (proper-lockfile guarded read-modify-write,
+ * mode 0600) pointed at the subscriptions.json path.
+ *
+ * Raw keys are never logged or embedded in error messages — errors refer to
+ * provider and key ids only.
+ */
+import type { CredentialStore } from "@earendil-works/pi-ai";
+import { type AuthStorageBackend } from "./auth-storage.ts";
+export interface SubEntry {
+    id: string;
+    name: string;
+    key: string;
+    addedAt: number;
+    exhaustedUntil?: number;
+    lastError?: string;
+}
+interface ProviderPool {
+    active: string;
+    keys: SubEntry[];
+}
+type SubscriptionData = Record<string, ProviderPool>;
+export declare class SubscriptionManager {
+    private data;
+    private loaded;
+    private storage;
+    private authStorage;
+    private queue;
+    private memoryExhausted;
+    private constructor();
+    static create(authStorage: CredentialStore, path?: string): SubscriptionManager;
+    static fromStorage(authStorage: CredentialStore, storage: AuthStorageBackend): SubscriptionManager;
+    static inMemory(authStorage: CredentialStore, data?: SubscriptionData): SubscriptionManager;
+    private parseStorageData;
+    private ensureLoaded;
+    private enqueue;
+    private persist;
+    private readRawCredential;
+    private ensurePool;
+    private nextId;
+    private mirrorActive;
+    list(providerId: string): Promise<SubEntry[]>;
+    getActive(providerId: string): Promise<SubEntry | undefined>;
+    addKey(providerId: string, key: string, name?: string): Promise<SubEntry>;
+    removeKey(providerId: string, id: string): Promise<void>;
+    renameKey(providerId: string, id: string, name: string): Promise<void>;
+    setActive(providerId: string, id: string): Promise<void>;
+    /**
+     * Mark the active key exhausted and rotate to the next non-exhausted key in
+     * round-robin order. A parseable reset time is persisted as exhaustedUntil;
+     * otherwise the exhaustion is process-local only. Returns the new active key,
+     * or null when no non-exhausted alternative exists (current key stays active).
+     */
+    rotateOnFailure(providerId: string, errorMessage: string, now?: number): Promise<SubEntry | null>;
+    /** Manual reactivate: clears persisted and process-local exhaustion for a key. */
+    clearExhaustion(providerId: string, id: string): Promise<void>;
+}
+export {};
+//# sourceMappingURL=subscriptions.d.ts.map

package/dist/core/subscriptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../../src/core/subscriptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAc,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGzE,OAAO,EAAE,KAAK,kBAAkB,EAAsD,MAAM,mBAAmB,CAAC;AAGhH,MAAM,WAAW,QAAQ;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,YAAY;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,EAAE,CAAC;CACjB;AAED,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAErD,qBAAa,mBAAmB;IAC/B,OAAO,CAAC,IAAI,CAAwB;IACpC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,WAAW,CAAkB;IAErC,OAAO,CAAC,KAAK,CAAuC;IAGpD,OAAO,CAAC,eAAe,CAAkC;IAEzD,OAAO,eAGN;IAED,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAK9E;IAED,MAAM,CAAC,WAAW,CAAC,WAAW,EAAE,eAAe,EAAE,OAAO,EAAE,kBAAkB,GAAG,mBAAmB,CAEjG;IAED,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,eAAe,EAAE,IAAI,GAAE,gBAAqB,GAAG,mBAAmB,CAI9F;IAED,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,OAAO;YAQD,iBAAiB;YAajB,UAAU;IAiBxB,OAAO,CAAC,MAAM;YASA,YAAY;IAIpB,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAKlD;IAEK,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAKjE;IAEK,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAY9E;IAEK,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA8B7D;IAEK,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ3E;IAEK,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS7D;IAED;;;;;OAKG;IACG,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA0ClH;IAED,kFAAkF;IAC5E,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAenE;CACD","sourcesContent":["/**\n * lunr: multi-subscription API-key pools per provider.\n *\n * The pool lives in subscriptions.json next to auth.json; auth.json always\n * holds the ACTIVE credential, so rotation is just mirroring the chosen pool\n * key into auth.json via AuthStorage.modify. Persistence reuses the\n * AuthStorage backend classes (proper-lockfile guarded read-modify-write,\n * mode 0600) pointed at the subscriptions.json path.\n *\n * Raw keys are never logged or embedded in error messages — errors refer to\n * provider and key ids only.\n */\n\nimport type { Credential, CredentialStore } from \"@earendil-works/pi-ai\";\nimport { join } from \"path\";\nimport { getAgentDir } from \"../config.ts\";\nimport { type AuthStorageBackend, FileAuthStorageBackend, InMemoryAuthStorageBackend } from \"./auth-storage.ts\";\nimport { parseResetTimeMs } from \"./usage-limit.ts\";\n\nexport interface SubEntry {\n\tid: string;\n\tname: string;\n\tkey: string;\n\taddedAt: number;\n\texhaustedUntil?: number;\n\tlastError?: string;\n}\n\ninterface ProviderPool {\n\tactive: string;\n\tkeys: SubEntry[];\n}\n\ntype SubscriptionData = Record<string, ProviderPool>;\n\nexport class SubscriptionManager {\n\tprivate data: SubscriptionData = {};\n\tprivate loaded = false;\n\tprivate storage: AuthStorageBackend;\n\tprivate authStorage: CredentialStore;\n\t// In-process write queue so mutations serialize even before the file lock.\n\tprivate queue: Promise<unknown> = Promise.resolve();\n\t// Per-provider ids of keys exhausted without a parseable reset time.\n\t// Process-local on purpose: infinite exhaustion is never persisted.\n\tprivate memoryExhausted = new Map<string, Set<string>>();\n\n\tprivate constructor(authStorage: CredentialStore, storage: AuthStorageBackend) {\n\t\tthis.authStorage = authStorage;\n\t\tthis.storage = storage;\n\t}\n\n\tstatic create(authStorage: CredentialStore, path?: string): SubscriptionManager {\n\t\treturn new SubscriptionManager(\n\t\t\tauthStorage,\n\t\t\tnew FileAuthStorageBackend(path ?? join(getAgentDir(), \"subscriptions.json\")),\n\t\t);\n\t}\n\n\tstatic fromStorage(authStorage: CredentialStore, storage: AuthStorageBackend): SubscriptionManager {\n\t\treturn new SubscriptionManager(authStorage, storage);\n\t}\n\n\tstatic inMemory(authStorage: CredentialStore, data: SubscriptionData = {}): SubscriptionManager {\n\t\tconst storage = new InMemoryAuthStorageBackend();\n\t\tstorage.withLock(() => ({ result: undefined, next: JSON.stringify(data, null, 2) }));\n\t\treturn SubscriptionManager.fromStorage(authStorage, storage);\n\t}\n\n\tprivate parseStorageData(content: string | undefined): SubscriptionData {\n\t\tif (!content) {\n\t\t\treturn {};\n\t\t}\n\t\treturn JSON.parse(content) as SubscriptionData;\n\t}\n\n\tprivate ensureLoaded(): void {\n\t\tif (this.loaded) return;\n\t\tthis.loaded = true;\n\t\tlet content: string | undefined;\n\t\ttry {\n\t\t\tthis.storage.withLock((current) => {\n\t\t\t\tcontent = current;\n\t\t\t\treturn { result: undefined };\n\t\t\t});\n\t\t\tthis.data = this.parseStorageData(content);\n\t\t} catch {\n\t\t\t// Preserve the empty snapshot; a malformed file is never overwritten by a load.\n\t\t}\n\t}\n\n\tprivate enqueue<T>(fn: () => Promise<T>): Promise<T> {\n\t\tconst next = this.queue.then(fn);\n\t\tthis.queue = next.catch(() => {});\n\t\treturn next;\n\t}\n\n\tprivate persist(): Promise<void> {\n\t\treturn this.storage.withLockAsync(async () => ({\n\t\t\tresult: undefined,\n\t\t\tnext: JSON.stringify(this.data, null, 2),\n\t\t}));\n\t}\n\n\t/** Raw stored credential read via the modify path (returning undefined leaves it unchanged). */\n\tprivate async readRawCredential(providerId: string): Promise<Credential | undefined> {\n\t\tlet current: Credential | undefined;\n\t\tawait this.authStorage.modify(providerId, async (credential) => {\n\t\t\tcurrent = credential;\n\t\t\treturn undefined;\n\t\t});\n\t\treturn current;\n\t}\n\n\t/**\n\t * Pool for a provider, lazy-importing an existing stored api_key credential\n\t * as \"Sub 1\" on first access. OAuth credentials are not imported.\n\t */\n\tprivate async ensurePool(providerId: string): Promise<ProviderPool | undefined> {\n\t\tthis.ensureLoaded();\n\t\tconst existing = this.data[providerId];\n\t\tif (existing) return existing;\n\n\t\tconst credential = await this.readRawCredential(providerId);\n\t\tif (credential?.type !== \"api_key\" || credential.key === undefined) return undefined;\n\n\t\tconst pool: ProviderPool = {\n\t\t\tactive: \"1\",\n\t\t\tkeys: [{ id: \"1\", name: \"Sub 1\", key: credential.key, addedAt: Date.now() }],\n\t\t};\n\t\tthis.data = { ...this.data, [providerId]: pool };\n\t\tawait this.persist();\n\t\treturn pool;\n\t}\n\n\tprivate nextId(pool: ProviderPool): string {\n\t\tlet max = 0;\n\t\tfor (const entry of pool.keys) {\n\t\t\tconst numeric = Number.parseInt(entry.id, 10);\n\t\t\tif (Number.isFinite(numeric) && numeric > max) max = numeric;\n\t\t}\n\t\treturn String(max + 1);\n\t}\n\n\tprivate async mirrorActive(providerId: string, key: string): Promise<void> {\n\t\tawait this.authStorage.modify(providerId, async () => ({ type: \"api_key\", key }));\n\t}\n\n\tasync list(providerId: string): Promise<SubEntry[]> {\n\t\treturn this.enqueue(async () => {\n\t\t\tconst pool = await this.ensurePool(providerId);\n\t\t\treturn pool ? [...pool.keys] : [];\n\t\t});\n\t}\n\n\tasync getActive(providerId: string): Promise<SubEntry | undefined> {\n\t\treturn this.enqueue(async () => {\n\t\t\tconst pool = await this.ensurePool(providerId);\n\t\t\treturn pool?.keys.find((entry) => entry.id === pool.active);\n\t\t});\n\t}\n\n\tasync addKey(providerId: string, key: string, name?: string): Promise<SubEntry> {\n\t\treturn this.enqueue(async () => {\n\t\t\tthis.ensureLoaded();\n\t\t\tconst pool = await this.ensurePool(providerId);\n\t\t\tconst id = pool ? this.nextId(pool) : \"1\";\n\t\t\tconst entry: SubEntry = { id, name: name ?? `Sub ${id}`, key, addedAt: Date.now() };\n\t\t\tconst keys = [...(pool?.keys ?? []), entry];\n\t\t\tthis.data = { ...this.data, [providerId]: { active: id, keys } };\n\t\t\tawait this.persist();\n\t\t\tawait this.mirrorActive(providerId, key);\n\t\t\treturn entry;\n\t\t});\n\t}\n\n\tasync removeKey(providerId: string, id: string): Promise<void> {\n\t\treturn this.enqueue(async () => {\n\t\t\tconst pool = await this.ensurePool(providerId);\n\t\t\tif (!pool || !pool.keys.some((entry) => entry.id === id)) return;\n\n\t\t\tconst keys = pool.keys.filter((entry) => entry.id !== id);\n\t\t\tthis.memoryExhausted.get(providerId)?.delete(id);\n\n\t\t\tif (keys.length === 0) {\n\t\t\t\tconst data = { ...this.data };\n\t\t\t\tdelete data[providerId];\n\t\t\t\tthis.data = data;\n\t\t\t\tawait this.persist();\n\t\t\t\tawait this.authStorage.delete(providerId);\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tlet active = pool.active;\n\t\t\tif (active === id) {\n\t\t\t\tactive = keys[0]?.id ?? active;\n\t\t\t\tthis.data = { ...this.data, [providerId]: { active, keys } };\n\t\t\t\tawait this.persist();\n\t\t\t\tconst promoted = keys.find((entry) => entry.id === active);\n\t\t\t\tif (promoted) await this.mirrorActive(providerId, promoted.key);\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tthis.data = { ...this.data, [providerId]: { active, keys } };\n\t\t\tawait this.persist();\n\t\t});\n\t}\n\n\tasync renameKey(providerId: string, id: string, name: string): Promise<void> {\n\t\treturn this.enqueue(async () => {\n\t\t\tconst pool = await this.ensurePool(providerId);\n\t\t\tif (!pool) return;\n\t\t\tconst keys = pool.keys.map((entry) => (entry.id === id ? { ...entry, name } : entry));\n\t\t\tthis.data = { ...this.data, [providerId]: { ...pool, keys } };\n\t\t\tawait this.persist();\n\t\t});\n\t}\n\n\tasync setActive(providerId: string, id: string): Promise<void> {\n\t\treturn this.enqueue(async () => {\n\t\t\tconst pool = await this.ensurePool(providerId);\n\t\t\tconst entry = pool?.keys.find((candidate) => candidate.id === id);\n\t\t\tif (!pool || !entry) return;\n\t\t\tthis.data = { ...this.data, [providerId]: { ...pool, active: id } };\n\t\t\tawait this.persist();\n\t\t\tawait this.mirrorActive(providerId, entry.key);\n\t\t});\n\t}\n\n\t/**\n\t * Mark the active key exhausted and rotate to the next non-exhausted key in\n\t * round-robin order. A parseable reset time is persisted as exhaustedUntil;\n\t * otherwise the exhaustion is process-local only. Returns the new active key,\n\t * or null when no non-exhausted alternative exists (current key stays active).\n\t */\n\tasync rotateOnFailure(providerId: string, errorMessage: string, now: number = Date.now()): Promise<SubEntry | null> {\n\t\treturn this.enqueue(async () => {\n\t\t\tconst pool = await this.ensurePool(providerId);\n\t\t\tif (!pool) return null;\n\t\t\tconst currentIndex = pool.keys.findIndex((entry) => entry.id === pool.active);\n\t\t\tif (currentIndex === -1) return null;\n\t\t\tconst current = pool.keys[currentIndex];\n\t\t\tif (!current) return null;\n\n\t\t\tconst resetAt = parseResetTimeMs(errorMessage);\n\t\t\tlet keys = pool.keys;\n\t\t\tif (resetAt !== undefined && resetAt > now) {\n\t\t\t\tkeys = pool.keys.map((entry) =>\n\t\t\t\t\tentry.id === current.id ? { ...entry, exhaustedUntil: resetAt, lastError: errorMessage } : entry,\n\t\t\t\t);\n\t\t\t} else {\n\t\t\t\tconst set = this.memoryExhausted.get(providerId) ?? new Set<string>();\n\t\t\t\tset.add(current.id);\n\t\t\t\tthis.memoryExhausted.set(providerId, set);\n\t\t\t}\n\n\t\t\tconst isExhausted = (entry: SubEntry): boolean =>\n\t\t\t\tthis.memoryExhausted.get(providerId)?.has(entry.id) === true ||\n\t\t\t\t(entry.exhaustedUntil !== undefined && entry.exhaustedUntil > now);\n\n\t\t\tfor (let offset = 1; offset < keys.length; offset++) {\n\t\t\t\tconst candidate = keys[(currentIndex + offset) % keys.length];\n\t\t\t\tif (!candidate || isExhausted(candidate)) continue;\n\t\t\t\tthis.data = { ...this.data, [providerId]: { active: candidate.id, keys } };\n\t\t\t\tawait this.persist();\n\t\t\t\tawait this.mirrorActive(providerId, candidate.key);\n\t\t\t\treturn candidate;\n\t\t\t}\n\n\t\t\t// No alternative: keep the (now-exhausted) current key active, but still\n\t\t\t// persist its exhaustion state when a reset time was recorded.\n\t\t\tif (keys !== pool.keys) {\n\t\t\t\tthis.data = { ...this.data, [providerId]: { ...pool, keys } };\n\t\t\t\tawait this.persist();\n\t\t\t}\n\t\t\treturn null;\n\t\t});\n\t}\n\n\t/** Manual reactivate: clears persisted and process-local exhaustion for a key. */\n\tasync clearExhaustion(providerId: string, id: string): Promise<void> {\n\t\treturn this.enqueue(async () => {\n\t\t\tthis.memoryExhausted.get(providerId)?.delete(id);\n\t\t\tconst pool = await this.ensurePool(providerId);\n\t\t\tif (!pool) return;\n\t\t\tconst target = pool.keys.find((entry) => entry.id === id);\n\t\t\tif (!target || (target.exhaustedUntil === undefined && target.lastError === undefined)) return;\n\t\t\tconst keys = pool.keys.map((entry) => {\n\t\t\t\tif (entry.id !== id) return entry;\n\t\t\t\tconst { exhaustedUntil: _exhaustedUntil, lastError: _lastError, ...rest } = entry;\n\t\t\t\treturn rest;\n\t\t\t});\n\t\t\tthis.data = { ...this.data, [providerId]: { ...pool, keys } };\n\t\t\tawait this.persist();\n\t\t});\n\t}\n}\n"]}

package/dist/core/subscriptions.js

@@ -0,0 +1,259 @@
+/**
+ * lunr: multi-subscription API-key pools per provider.
+ *
+ * The pool lives in subscriptions.json next to auth.json; auth.json always
+ * holds the ACTIVE credential, so rotation is just mirroring the chosen pool
+ * key into auth.json via AuthStorage.modify. Persistence reuses the
+ * AuthStorage backend classes (proper-lockfile guarded read-modify-write,
+ * mode 0600) pointed at the subscriptions.json path.
+ *
+ * Raw keys are never logged or embedded in error messages — errors refer to
+ * provider and key ids only.
+ */
+import { join } from "path";
+import { getAgentDir } from "../config.js";
+import { FileAuthStorageBackend, InMemoryAuthStorageBackend } from "./auth-storage.js";
+import { parseResetTimeMs } from "./usage-limit.js";
+export class SubscriptionManager {
+    data = {};
+    loaded = false;
+    storage;
+    authStorage;
+    // In-process write queue so mutations serialize even before the file lock.
+    queue = Promise.resolve();
+    // Per-provider ids of keys exhausted without a parseable reset time.
+    // Process-local on purpose: infinite exhaustion is never persisted.
+    memoryExhausted = new Map();
+    constructor(authStorage, storage) {
+        this.authStorage = authStorage;
+        this.storage = storage;
+    }
+    static create(authStorage, path) {
+        return new SubscriptionManager(authStorage, new FileAuthStorageBackend(path ?? join(getAgentDir(), "subscriptions.json")));
+    }
+    static fromStorage(authStorage, storage) {
+        return new SubscriptionManager(authStorage, storage);
+    }
+    static inMemory(authStorage, data = {}) {
+        const storage = new InMemoryAuthStorageBackend();
+        storage.withLock(() => ({ result: undefined, next: JSON.stringify(data, null, 2) }));
+        return SubscriptionManager.fromStorage(authStorage, storage);
+    }
+    parseStorageData(content) {
+        if (!content) {
+            return {};
+        }
+        return JSON.parse(content);
+    }
+    ensureLoaded() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        let content;
+        try {
+            this.storage.withLock((current) => {
+                content = current;
+                return { result: undefined };
+            });
+            this.data = this.parseStorageData(content);
+        }
+        catch {
+            // Preserve the empty snapshot; a malformed file is never overwritten by a load.
+        }
+    }
+    enqueue(fn) {
+        const next = this.queue.then(fn);
+        this.queue = next.catch(() => { });
+        return next;
+    }
+    persist() {
+        return this.storage.withLockAsync(async () => ({
+            result: undefined,
+            next: JSON.stringify(this.data, null, 2),
+        }));
+    }
+    /** Raw stored credential read via the modify path (returning undefined leaves it unchanged). */
+    async readRawCredential(providerId) {
+        let current;
+        await this.authStorage.modify(providerId, async (credential) => {
+            current = credential;
+            return undefined;
+        });
+        return current;
+    }
+    /**
+     * Pool for a provider, lazy-importing an existing stored api_key credential
+     * as "Sub 1" on first access. OAuth credentials are not imported.
+     */
+    async ensurePool(providerId) {
+        this.ensureLoaded();
+        const existing = this.data[providerId];
+        if (existing)
+            return existing;
+        const credential = await this.readRawCredential(providerId);
+        if (credential?.type !== "api_key" || credential.key === undefined)
+            return undefined;
+        const pool = {
+            active: "1",
+            keys: [{ id: "1", name: "Sub 1", key: credential.key, addedAt: Date.now() }],
+        };
+        this.data = { ...this.data, [providerId]: pool };
+        await this.persist();
+        return pool;
+    }
+    nextId(pool) {
+        let max = 0;
+        for (const entry of pool.keys) {
+            const numeric = Number.parseInt(entry.id, 10);
+            if (Number.isFinite(numeric) && numeric > max)
+                max = numeric;
+        }
+        return String(max + 1);
+    }
+    async mirrorActive(providerId, key) {
+        await this.authStorage.modify(providerId, async () => ({ type: "api_key", key }));
+    }
+    async list(providerId) {
+        return this.enqueue(async () => {
+            const pool = await this.ensurePool(providerId);
+            return pool ? [...pool.keys] : [];
+        });
+    }
+    async getActive(providerId) {
+        return this.enqueue(async () => {
+            const pool = await this.ensurePool(providerId);
+            return pool?.keys.find((entry) => entry.id === pool.active);
+        });
+    }
+    async addKey(providerId, key, name) {
+        return this.enqueue(async () => {
+            this.ensureLoaded();
+            const pool = await this.ensurePool(providerId);
+            const id = pool ? this.nextId(pool) : "1";
+            const entry = { id, name: name ?? `Sub ${id}`, key, addedAt: Date.now() };
+            const keys = [...(pool?.keys ?? []), entry];
+            this.data = { ...this.data, [providerId]: { active: id, keys } };
+            await this.persist();
+            await this.mirrorActive(providerId, key);
+            return entry;
+        });
+    }
+    async removeKey(providerId, id) {
+        return this.enqueue(async () => {
+            const pool = await this.ensurePool(providerId);
+            if (!pool || !pool.keys.some((entry) => entry.id === id))
+                return;
+            const keys = pool.keys.filter((entry) => entry.id !== id);
+            this.memoryExhausted.get(providerId)?.delete(id);
+            if (keys.length === 0) {
+                const data = { ...this.data };
+                delete data[providerId];
+                this.data = data;
+                await this.persist();
+                await this.authStorage.delete(providerId);
+                return;
+            }
+            let active = pool.active;
+            if (active === id) {
+                active = keys[0]?.id ?? active;
+                this.data = { ...this.data, [providerId]: { active, keys } };
+                await this.persist();
+                const promoted = keys.find((entry) => entry.id === active);
+                if (promoted)
+                    await this.mirrorActive(providerId, promoted.key);
+                return;
+            }
+            this.data = { ...this.data, [providerId]: { active, keys } };
+            await this.persist();
+        });
+    }
+    async renameKey(providerId, id, name) {
+        return this.enqueue(async () => {
+            const pool = await this.ensurePool(providerId);
+            if (!pool)
+                return;
+            const keys = pool.keys.map((entry) => (entry.id === id ? { ...entry, name } : entry));
+            this.data = { ...this.data, [providerId]: { ...pool, keys } };
+            await this.persist();
+        });
+    }
+    async setActive(providerId, id) {
+        return this.enqueue(async () => {
+            const pool = await this.ensurePool(providerId);
+            const entry = pool?.keys.find((candidate) => candidate.id === id);
+            if (!pool || !entry)
+                return;
+            this.data = { ...this.data, [providerId]: { ...pool, active: id } };
+            await this.persist();
+            await this.mirrorActive(providerId, entry.key);
+        });
+    }
+    /**
+     * Mark the active key exhausted and rotate to the next non-exhausted key in
+     * round-robin order. A parseable reset time is persisted as exhaustedUntil;
+     * otherwise the exhaustion is process-local only. Returns the new active key,
+     * or null when no non-exhausted alternative exists (current key stays active).
+     */
+    async rotateOnFailure(providerId, errorMessage, now = Date.now()) {
+        return this.enqueue(async () => {
+            const pool = await this.ensurePool(providerId);
+            if (!pool)
+                return null;
+            const currentIndex = pool.keys.findIndex((entry) => entry.id === pool.active);
+            if (currentIndex === -1)
+                return null;
+            const current = pool.keys[currentIndex];
+            if (!current)
+                return null;
+            const resetAt = parseResetTimeMs(errorMessage);
+            let keys = pool.keys;
+            if (resetAt !== undefined && resetAt > now) {
+                keys = pool.keys.map((entry) => entry.id === current.id ? { ...entry, exhaustedUntil: resetAt, lastError: errorMessage } : entry);
+            }
+            else {
+                const set = this.memoryExhausted.get(providerId) ?? new Set();
+                set.add(current.id);
+                this.memoryExhausted.set(providerId, set);
+            }
+            const isExhausted = (entry) => this.memoryExhausted.get(providerId)?.has(entry.id) === true ||
+                (entry.exhaustedUntil !== undefined && entry.exhaustedUntil > now);
+            for (let offset = 1; offset < keys.length; offset++) {
+                const candidate = keys[(currentIndex + offset) % keys.length];
+                if (!candidate || isExhausted(candidate))
+                    continue;
+                this.data = { ...this.data, [providerId]: { active: candidate.id, keys } };
+                await this.persist();
+                await this.mirrorActive(providerId, candidate.key);
+                return candidate;
+            }
+            // No alternative: keep the (now-exhausted) current key active, but still
+            // persist its exhaustion state when a reset time was recorded.
+            if (keys !== pool.keys) {
+                this.data = { ...this.data, [providerId]: { ...pool, keys } };
+                await this.persist();
+            }
+            return null;
+        });
+    }
+    /** Manual reactivate: clears persisted and process-local exhaustion for a key. */
+    async clearExhaustion(providerId, id) {
+        return this.enqueue(async () => {
+            this.memoryExhausted.get(providerId)?.delete(id);
+            const pool = await this.ensurePool(providerId);
+            if (!pool)
+                return;
+            const target = pool.keys.find((entry) => entry.id === id);
+            if (!target || (target.exhaustedUntil === undefined && target.lastError === undefined))
+                return;
+            const keys = pool.keys.map((entry) => {
+                if (entry.id !== id)
+                    return entry;
+                const { exhaustedUntil: _exhaustedUntil, lastError: _lastError, ...rest } = entry;
+                return rest;
+            });
+            this.data = { ...this.data, [providerId]: { ...pool, keys } };
+            await this.persist();
+        });
+    }
+}
+//# sourceMappingURL=subscriptions.js.map

package/dist/core/subscriptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.js","sourceRoot":"","sources":["../../src/core/subscriptions.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * lunr: multi-subscription API-key pools per provider.\n *\n * The pool lives in subscriptions.json next to auth.json; auth.json always\n * holds the ACTIVE credential, so rotation is just mirroring the chosen pool\n * key into auth.json via AuthStorage.modify. Persistence reuses the\n * AuthStorage backend classes (proper-lockfile guarded read-modify-write,\n * mode 0600) pointed at the subscriptions.json path.\n *\n * Raw keys are never logged or embedded in error messages — errors refer to\n * provider and key ids only.\n */\n\nimport type { Credential, CredentialStore } from \"@earendil-works/pi-ai\";\nimport { join } from \"path\";\nimport { getAgentDir } from \"../config.ts\";\nimport { type AuthStorageBackend, FileAuthStorageBackend, InMemoryAuthStorageBackend } from \"./auth-storage.ts\";\nimport { parseResetTimeMs } from \"./usage-limit.ts\";\n\nexport interface SubEntry {\n\tid: string;\n\tname: string;\n\tkey: string;\n\taddedAt: number;\n\texhaustedUntil?: number;\n\tlastError?: string;\n}\n\ninterface ProviderPool {\n\tactive: string;\n\tkeys: SubEntry[];\n}\n\ntype SubscriptionData = Record<string, ProviderPool>;\n\nexport class SubscriptionManager {\n\tprivate data: SubscriptionData = {};\n\tprivate loaded = false;\n\tprivate storage: AuthStorageBackend;\n\tprivate authStorage: CredentialStore;\n\t// In-process write queue so mutations serialize even before the file lock.\n\tprivate queue: Promise<unknown> = Promise.resolve();\n\t// Per-provider ids of keys exhausted without a parseable reset time.\n\t// Process-local on purpose: infinite exhaustion is never persisted.\n\tprivate memoryExhausted = new Map<string, Set<string>>();\n\n\tprivate constructor(authStorage: CredentialStore, storage: AuthStorageBackend) {\n\t\tthis.authStorage = authStorage;\n\t\tthis.storage = storage;\n\t}\n\n\tstatic create(authStorage: CredentialStore, path?: string): SubscriptionManager {\n\t\treturn new SubscriptionManager(\n\t\t\tauthStorage,\n\t\t\tnew FileAuthStorageBackend(path ?? join(getAgentDir(), \"subscriptions.json\")),\n\t\t);\n\t}\n\n\tstatic fromStorage(authStorage: CredentialStore, storage: AuthStorageBackend): SubscriptionManager {\n\t\treturn new SubscriptionManager(authStorage, storage);\n\t}\n\n\tstatic inMemory(authStorage: CredentialStore, data: SubscriptionData = {}): SubscriptionManager {\n\t\tconst storage = new InMemoryAuthStorageBackend();\n\t\tstorage.withLock(() => ({ result: undefined, next: JSON.stringify(data, null, 2) }));\n\t\treturn SubscriptionManager.fromStorage(authStorage, storage);\n\t}\n\n\tprivate parseStorageData(content: string | undefined): SubscriptionData {\n\t\tif (!content) {\n\t\t\treturn {};\n\t\t}\n\t\treturn JSON.parse(content) as SubscriptionData;\n\t}\n\n\tprivate ensureLoaded(): void {\n\t\tif (this.loaded) return;\n\t\tthis.loaded = true;\n\t\tlet content: string | undefined;\n\t\ttry {\n\t\t\tthis.storage.withLock((current) => {\n\t\t\t\tcontent = current;\n\t\t\t\treturn { result: undefined };\n\t\t\t});\n\t\t\tthis.data = this.parseStorageData(content);\n\t\t} catch {\n\t\t\t// Preserve the empty snapshot; a malformed file is never overwritten by a load.\n\t\t}\n\t}\n\n\tprivate enqueue<T>(fn: () => Promise<T>): Promise<T> {\n\t\tconst next = this.queue.then(fn);\n\t\tthis.queue = next.catch(() => {});\n\t\treturn next;\n\t}\n\n\tprivate persist(): Promise<void> {\n\t\treturn this.storage.withLockAsync(async () => ({\n\t\t\tresult: undefined,\n\t\t\tnext: JSON.stringify(this.data, null, 2),\n\t\t}));\n\t}\n\n\t/** Raw stored credential read via the modify path (returning undefined leaves it unchanged). */\n\tprivate async readRawCredential(providerId: string): Promise<Credential | undefined> {\n\t\tlet current: Credential | undefined;\n\t\tawait this.authStorage.modify(providerId, async (credential) => {\n\t\t\tcurrent = credential;\n\t\t\treturn undefined;\n\t\t});\n\t\treturn current;\n\t}\n\n\t/**\n\t * Pool for a provider, lazy-importing an existing stored api_key credential\n\t * as \"Sub 1\" on first access. OAuth credentials are not imported.\n\t */\n\tprivate async ensurePool(providerId: string): Promise<ProviderPool | undefined> {\n\t\tthis.ensureLoaded();\n\t\tconst existing = this.data[providerId];\n\t\tif (existing) return existing;\n\n\t\tconst credential = await this.readRawCredential(providerId);\n\t\tif (credential?.type !== \"api_key\" || credential.key === undefined) return undefined;\n\n\t\tconst pool: ProviderPool = {\n\t\t\tactive: \"1\",\n\t\t\tkeys: [{ id: \"1\", name: \"Sub 1\", key: credential.key, addedAt: Date.now() }],\n\t\t};\n\t\tthis.data = { ...this.data, [providerId]: pool };\n\t\tawait this.persist();\n\t\treturn pool;\n\t}\n\n\tprivate nextId(pool: ProviderPool): string {\n\t\tlet max = 0;\n\t\tfor (const entry of pool.keys) {\n\t\t\tconst numeric = Number.parseInt(entry.id, 10);\n\t\t\tif (Number.isFinite(numeric) && numeric > max) max = numeric;\n\t\t}\n\t\treturn String(max + 1);\n\t}\n\n\tprivate async mirrorActive(providerId: string, key: string): Promise<void> {\n\t\tawait this.authStorage.modify(providerId, async () => ({ type: \"api_key\", key }));\n\t}\n\n\tasync list(providerId: string): Promise<SubEntry[]> {\n\t\treturn this.enqueue(async () => {\n\t\t\tconst pool = await this.ensurePool(providerId);\n\t\t\treturn pool ? [...pool.keys] : [];\n\t\t});\n\t}\n\n\tasync getActive(providerId: string): Promise<SubEntry | undefined> {\n\t\treturn this.enqueue(async () => {\n\t\t\tconst pool = await this.ensurePool(providerId);\n\t\t\treturn pool?.keys.find((entry) => entry.id === pool.active);\n\t\t});\n\t}\n\n\tasync addKey(providerId: string, key: string, name?: string): Promise<SubEntry> {\n\t\treturn this.enqueue(async () => {\n\t\t\tthis.ensureLoaded();\n\t\t\tconst pool = await this.ensurePool(providerId);\n\t\t\tconst id = pool ? this.nextId(pool) : \"1\";\n\t\t\tconst entry: SubEntry = { id, name: name ?? `Sub ${id}`, key, addedAt: Date.now() };\n\t\t\tconst keys = [...(pool?.keys ?? []), entry];\n\t\t\tthis.data = { ...this.data, [providerId]: { active: id, keys } };\n\t\t\tawait this.persist();\n\t\t\tawait this.mirrorActive(providerId, key);\n\t\t\treturn entry;\n\t\t});\n\t}\n\n\tasync removeKey(providerId: string, id: string): Promise<void> {\n\t\treturn this.enqueue(async () => {\n\t\t\tconst pool = await this.ensurePool(providerId);\n\t\t\tif (!pool || !pool.keys.some((entry) => entry.id === id)) return;\n\n\t\t\tconst keys = pool.keys.filter((entry) => entry.id !== id);\n\t\t\tthis.memoryExhausted.get(providerId)?.delete(id);\n\n\t\t\tif (keys.length === 0) {\n\t\t\t\tconst data = { ...this.data };\n\t\t\t\tdelete data[providerId];\n\t\t\t\tthis.data = data;\n\t\t\t\tawait this.persist();\n\t\t\t\tawait this.authStorage.delete(providerId);\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tlet active = pool.active;\n\t\t\tif (active === id) {\n\t\t\t\tactive = keys[0]?.id ?? active;\n\t\t\t\tthis.data = { ...this.data, [providerId]: { active, keys } };\n\t\t\t\tawait this.persist();\n\t\t\t\tconst promoted = keys.find((entry) => entry.id === active);\n\t\t\t\tif (promoted) await this.mirrorActive(providerId, promoted.key);\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tthis.data = { ...this.data, [providerId]: { active, keys } };\n\t\t\tawait this.persist();\n\t\t});\n\t}\n\n\tasync renameKey(providerId: string, id: string, name: string): Promise<void> {\n\t\treturn this.enqueue(async () => {\n\t\t\tconst pool = await this.ensurePool(providerId);\n\t\t\tif (!pool) return;\n\t\t\tconst keys = pool.keys.map((entry) => (entry.id === id ? { ...entry, name } : entry));\n\t\t\tthis.data = { ...this.data, [providerId]: { ...pool, keys } };\n\t\t\tawait this.persist();\n\t\t});\n\t}\n\n\tasync setActive(providerId: string, id: string): Promise<void> {\n\t\treturn this.enqueue(async () => {\n\t\t\tconst pool = await this.ensurePool(providerId);\n\t\t\tconst entry = pool?.keys.find((candidate) => candidate.id === id);\n\t\t\tif (!pool || !entry) return;\n\t\t\tthis.data = { ...this.data, [providerId]: { ...pool, active: id } };\n\t\t\tawait this.persist();\n\t\t\tawait this.mirrorActive(providerId, entry.key);\n\t\t});\n\t}\n\n\t/**\n\t * Mark the active key exhausted and rotate to the next non-exhausted key in\n\t * round-robin order. A parseable reset time is persisted as exhaustedUntil;\n\t * otherwise the exhaustion is process-local only. Returns the new active key,\n\t * or null when no non-exhausted alternative exists (current key stays active).\n\t */\n\tasync rotateOnFailure(providerId: string, errorMessage: string, now: number = Date.now()): Promise<SubEntry | null> {\n\t\treturn this.enqueue(async () => {\n\t\t\tconst pool = await this.ensurePool(providerId);\n\t\t\tif (!pool) return null;\n\t\t\tconst currentIndex = pool.keys.findIndex((entry) => entry.id === pool.active);\n\t\t\tif (currentIndex === -1) return null;\n\t\t\tconst current = pool.keys[currentIndex];\n\t\t\tif (!current) return null;\n\n\t\t\tconst resetAt = parseResetTimeMs(errorMessage);\n\t\t\tlet keys = pool.keys;\n\t\t\tif (resetAt !== undefined && resetAt > now) {\n\t\t\t\tkeys = pool.keys.map((entry) =>\n\t\t\t\t\tentry.id === current.id ? { ...entry, exhaustedUntil: resetAt, lastError: errorMessage } : entry,\n\t\t\t\t);\n\t\t\t} else {\n\t\t\t\tconst set = this.memoryExhausted.get(providerId) ?? new Set<string>();\n\t\t\t\tset.add(current.id);\n\t\t\t\tthis.memoryExhausted.set(providerId, set);\n\t\t\t}\n\n\t\t\tconst isExhausted = (entry: SubEntry): boolean =>\n\t\t\t\tthis.memoryExhausted.get(providerId)?.has(entry.id) === true ||\n\t\t\t\t(entry.exhaustedUntil !== undefined && entry.exhaustedUntil > now);\n\n\t\t\tfor (let offset = 1; offset < keys.length; offset++) {\n\t\t\t\tconst candidate = keys[(currentIndex + offset) % keys.length];\n\t\t\t\tif (!candidate || isExhausted(candidate)) continue;\n\t\t\t\tthis.data = { ...this.data, [providerId]: { active: candidate.id, keys } };\n\t\t\t\tawait this.persist();\n\t\t\t\tawait this.mirrorActive(providerId, candidate.key);\n\t\t\t\treturn candidate;\n\t\t\t}\n\n\t\t\t// No alternative: keep the (now-exhausted) current key active, but still\n\t\t\t// persist its exhaustion state when a reset time was recorded.\n\t\t\tif (keys !== pool.keys) {\n\t\t\t\tthis.data = { ...this.data, [providerId]: { ...pool, keys } };\n\t\t\t\tawait this.persist();\n\t\t\t}\n\t\t\treturn null;\n\t\t});\n\t}\n\n\t/** Manual reactivate: clears persisted and process-local exhaustion for a key. */\n\tasync clearExhaustion(providerId: string, id: string): Promise<void> {\n\t\treturn this.enqueue(async () => {\n\t\t\tthis.memoryExhausted.get(providerId)?.delete(id);\n\t\t\tconst pool = await this.ensurePool(providerId);\n\t\t\tif (!pool) return;\n\t\t\tconst target = pool.keys.find((entry) => entry.id === id);\n\t\t\tif (!target || (target.exhaustedUntil === undefined && target.lastError === undefined)) return;\n\t\t\tconst keys = pool.keys.map((entry) => {\n\t\t\t\tif (entry.id !== id) return entry;\n\t\t\t\tconst { exhaustedUntil: _exhaustedUntil, lastError: _lastError, ...rest } = entry;\n\t\t\t\treturn rest;\n\t\t\t});\n\t\t\tthis.data = { ...this.data, [providerId]: { ...pool, keys } };\n\t\t\tawait this.persist();\n\t\t});\n\t}\n}\n"]}

package/dist/core/swarm.d.ts

@@ -0,0 +1,41 @@
+/**
+ * lunR: reusable swarm prompt builder.
+ *
+ * Moved out of interactive-mode so the gateway can decompose tasks across
+ * parallel subagents the same way the TUI does.
+ */
+export declare function buildSwarmPrompt(task: string): string;
+/**
+ * lunR: agent-swarm auto-activation gate helpers.
+ *
+ * When the model launches more than SWARM_APPROVAL_THRESHOLD parallel subagents
+ * in a single `subagent` tool call, that counts as an auto-activated agent swarm
+ * and requires user approval in every permission mode except `auto` (see
+ * core/permissions.ts). An explicit /swarm turn is pre-approved because the user
+ * already asked for the swarm.
+ */
+/** Parallel-subagent count above which the swarm approval gate engages. */
+export declare const SWARM_APPROVAL_THRESHOLD = 2;
+/**
+ * Effective number of parallel subagents a `subagent` tool call will launch:
+ * the `tasks` array (with `count` multipliers) plus any `chain` step `parallel`
+ * fan-out blocks. Sequential chain steps and single-agent calls count as 0.
+ * Dynamic `expand` fan-out has no static count and is not gated.
+ */
+export declare function effectiveSwarmCount(args: Record<string, unknown>): number;
+interface BranchEntryLike {
+    type: string;
+    message?: {
+        role?: string;
+        content?: unknown;
+    };
+}
+/**
+ * True when the current turn started from an explicit /swarm prompt (the most
+ * recent user message carries the literal `[SWARM MODE]` prefix). Both the TUI
+ * and the gateway inject the same buildSwarmPrompt text, so this works on both
+ * surfaces without extra state.
+ */
+export declare function isExplicitSwarmTurn(branch: readonly BranchEntryLike[]): boolean;
+export {};
+//# sourceMappingURL=swarm.d.ts.map

package/dist/core/swarm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swarm.d.ts","sourceRoot":"","sources":["../../src/core/swarm.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASrD;AAED;;;;;;;;GAQG;AAEH,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAO1C;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAczE;AAED,UAAU,eAAe;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC/C;AAaD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,GAAG,OAAO,CAO/E","sourcesContent":["/**\n * lunR: reusable swarm prompt builder.\n *\n * Moved out of interactive-mode so the gateway can decompose tasks across\n * parallel subagents the same way the TUI does.\n */\n\nexport function buildSwarmPrompt(task: string): string {\n\treturn `[SWARM MODE] Task: ${task}\nAct as an orchestrator. 1) Decompose into 3-8 independent subtasks. 2) Launch them\nin ONE parallel subagent call (async:false), picking an agent + model tier per\nsubtask (prefer scout for exploration, worker for implementation, reviewer for\nverification). 3) Synthesize the results and report. Rules: max 8 concurrent\nsubagents; no nested fan-out; if a subtask fails, retry once with the heavy tier\nbefore giving up on it; keep your final report under 100 lines with per-subtask\nstatus.`;\n}\n\n/**\n * lunR: agent-swarm auto-activation gate helpers.\n *\n * When the model launches more than SWARM_APPROVAL_THRESHOLD parallel subagents\n * in a single `subagent` tool call, that counts as an auto-activated agent swarm\n * and requires user approval in every permission mode except `auto` (see\n * core/permissions.ts). An explicit /swarm turn is pre-approved because the user\n * already asked for the swarm.\n */\n\n/** Parallel-subagent count above which the swarm approval gate engages. */\nexport const SWARM_APPROVAL_THRESHOLD = 2;\n\nfunction countEntry(item: unknown): number {\n\tconst count = item && typeof item === \"object\" ? (item as { count?: unknown }).count : undefined;\n\treturn typeof count === \"number\" && Number.isInteger(count) && count >= 1 ? count : 1;\n}\n\n/**\n * Effective number of parallel subagents a `subagent` tool call will launch:\n * the `tasks` array (with `count` multipliers) plus any `chain` step `parallel`\n * fan-out blocks. Sequential chain steps and single-agent calls count as 0.\n * Dynamic `expand` fan-out has no static count and is not gated.\n */\nexport function effectiveSwarmCount(args: Record<string, unknown>): number {\n\tlet total = 0;\n\tif (Array.isArray(args.tasks)) {\n\t\tfor (const task of args.tasks) total += countEntry(task);\n\t}\n\tif (Array.isArray(args.chain)) {\n\t\tfor (const step of args.chain) {\n\t\t\tconst parallel = step && typeof step === \"object\" ? (step as { parallel?: unknown }).parallel : undefined;\n\t\t\tif (Array.isArray(parallel)) {\n\t\t\t\tfor (const child of parallel) total += countEntry(child);\n\t\t\t}\n\t\t}\n\t}\n\treturn total;\n}\n\ninterface BranchEntryLike {\n\ttype: string;\n\tmessage?: { role?: string; content?: unknown };\n}\n\nfunction messageText(content: unknown): string {\n\tif (typeof content === \"string\") return content;\n\tif (Array.isArray(content)) {\n\t\treturn content\n\t\t\t.filter((c) => c && typeof c === \"object\" && (c as { type?: unknown }).type === \"text\")\n\t\t\t.map((c) => String((c as { text?: unknown }).text ?? \"\"))\n\t\t\t.join(\"\");\n\t}\n\treturn \"\";\n}\n\n/**\n * True when the current turn started from an explicit /swarm prompt (the most\n * recent user message carries the literal `[SWARM MODE]` prefix). Both the TUI\n * and the gateway inject the same buildSwarmPrompt text, so this works on both\n * surfaces without extra state.\n */\nexport function isExplicitSwarmTurn(branch: readonly BranchEntryLike[]): boolean {\n\tfor (let i = branch.length - 1; i >= 0; i--) {\n\t\tconst entry = branch[i];\n\t\tif (entry.type !== \"message\" || entry.message?.role !== \"user\") continue;\n\t\treturn messageText(entry.message.content).startsWith(\"[SWARM MODE]\");\n\t}\n\treturn false;\n}\n"]}

package/dist/core/swarm.js

@@ -0,0 +1,81 @@
+/**
+ * lunR: reusable swarm prompt builder.
+ *
+ * Moved out of interactive-mode so the gateway can decompose tasks across
+ * parallel subagents the same way the TUI does.
+ */
+export function buildSwarmPrompt(task) {
+    return `[SWARM MODE] Task: ${task}
+Act as an orchestrator. 1) Decompose into 3-8 independent subtasks. 2) Launch them
+in ONE parallel subagent call (async:false), picking an agent + model tier per
+subtask (prefer scout for exploration, worker for implementation, reviewer for
+verification). 3) Synthesize the results and report. Rules: max 8 concurrent
+subagents; no nested fan-out; if a subtask fails, retry once with the heavy tier
+before giving up on it; keep your final report under 100 lines with per-subtask
+status.`;
+}
+/**
+ * lunR: agent-swarm auto-activation gate helpers.
+ *
+ * When the model launches more than SWARM_APPROVAL_THRESHOLD parallel subagents
+ * in a single `subagent` tool call, that counts as an auto-activated agent swarm
+ * and requires user approval in every permission mode except `auto` (see
+ * core/permissions.ts). An explicit /swarm turn is pre-approved because the user
+ * already asked for the swarm.
+ */
+/** Parallel-subagent count above which the swarm approval gate engages. */
+export const SWARM_APPROVAL_THRESHOLD = 2;
+function countEntry(item) {
+    const count = item && typeof item === "object" ? item.count : undefined;
+    return typeof count === "number" && Number.isInteger(count) && count >= 1 ? count : 1;
+}
+/**
+ * Effective number of parallel subagents a `subagent` tool call will launch:
+ * the `tasks` array (with `count` multipliers) plus any `chain` step `parallel`
+ * fan-out blocks. Sequential chain steps and single-agent calls count as 0.
+ * Dynamic `expand` fan-out has no static count and is not gated.
+ */
+export function effectiveSwarmCount(args) {
+    let total = 0;
+    if (Array.isArray(args.tasks)) {
+        for (const task of args.tasks)
+            total += countEntry(task);
+    }
+    if (Array.isArray(args.chain)) {
+        for (const step of args.chain) {
+            const parallel = step && typeof step === "object" ? step.parallel : undefined;
+            if (Array.isArray(parallel)) {
+                for (const child of parallel)
+                    total += countEntry(child);
+            }
+        }
+    }
+    return total;
+}
+function messageText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .filter((c) => c && typeof c === "object" && c.type === "text")
+            .map((c) => String(c.text ?? ""))
+            .join("");
+    }
+    return "";
+}
+/**
+ * True when the current turn started from an explicit /swarm prompt (the most
+ * recent user message carries the literal `[SWARM MODE]` prefix). Both the TUI
+ * and the gateway inject the same buildSwarmPrompt text, so this works on both
+ * surfaces without extra state.
+ */
+export function isExplicitSwarmTurn(branch) {
+    for (let i = branch.length - 1; i >= 0; i--) {
+        const entry = branch[i];
+        if (entry.type !== "message" || entry.message?.role !== "user")
+            continue;
+        return messageText(entry.message.content).startsWith("[SWARM MODE]");
+    }
+    return false;
+}
+//# sourceMappingURL=swarm.js.map

package/dist/core/swarm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"swarm.js","sourceRoot":"","sources":["../../src/core/swarm.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAU;IACtD,OAAO,sBAAsB,IAAI;;;;;;;QAO1B,CAAC;AAAA,CACR;AAED;;;;;;;;GAQG;AAEH,2EAA2E;AAC3E,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAE1C,SAAS,UAAU,CAAC,IAAa,EAAU;IAC1C,MAAM,KAAK,GAAG,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAE,IAA4B,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACjG,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAAA,CACtF;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAA6B,EAAU;IAC1E,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;YAAE,KAAK,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC/B,MAAM,QAAQ,GAAG,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAE,IAA+B,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;YAC1G,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC7B,KAAK,MAAM,KAAK,IAAI,QAAQ;oBAAE,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;YAC1D,CAAC;QACF,CAAC;IACF,CAAC;IACD,OAAO,KAAK,CAAC;AAAA,CACb;AAOD,SAAS,WAAW,CAAC,OAAgB,EAAU;IAC9C,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChD,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,OAAO,OAAO;aACZ,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAK,CAAwB,CAAC,IAAI,KAAK,MAAM,CAAC;aACtF,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAE,CAAwB,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;aACxD,IAAI,CAAC,EAAE,CAAC,CAAC;IACZ,CAAC;IACD,OAAO,EAAE,CAAC;AAAA,CACV;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAkC,EAAW;IAChF,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACxB,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,EAAE,IAAI,KAAK,MAAM;YAAE,SAAS;QACzE,OAAO,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,KAAK,CAAC;AAAA,CACb","sourcesContent":["/**\n * lunR: reusable swarm prompt builder.\n *\n * Moved out of interactive-mode so the gateway can decompose tasks across\n * parallel subagents the same way the TUI does.\n */\n\nexport function buildSwarmPrompt(task: string): string {\n\treturn `[SWARM MODE] Task: ${task}\nAct as an orchestrator. 1) Decompose into 3-8 independent subtasks. 2) Launch them\nin ONE parallel subagent call (async:false), picking an agent + model tier per\nsubtask (prefer scout for exploration, worker for implementation, reviewer for\nverification). 3) Synthesize the results and report. Rules: max 8 concurrent\nsubagents; no nested fan-out; if a subtask fails, retry once with the heavy tier\nbefore giving up on it; keep your final report under 100 lines with per-subtask\nstatus.`;\n}\n\n/**\n * lunR: agent-swarm auto-activation gate helpers.\n *\n * When the model launches more than SWARM_APPROVAL_THRESHOLD parallel subagents\n * in a single `subagent` tool call, that counts as an auto-activated agent swarm\n * and requires user approval in every permission mode except `auto` (see\n * core/permissions.ts). An explicit /swarm turn is pre-approved because the user\n * already asked for the swarm.\n */\n\n/** Parallel-subagent count above which the swarm approval gate engages. */\nexport const SWARM_APPROVAL_THRESHOLD = 2;\n\nfunction countEntry(item: unknown): number {\n\tconst count = item && typeof item === \"object\" ? (item as { count?: unknown }).count : undefined;\n\treturn typeof count === \"number\" && Number.isInteger(count) && count >= 1 ? count : 1;\n}\n\n/**\n * Effective number of parallel subagents a `subagent` tool call will launch:\n * the `tasks` array (with `count` multipliers) plus any `chain` step `parallel`\n * fan-out blocks. Sequential chain steps and single-agent calls count as 0.\n * Dynamic `expand` fan-out has no static count and is not gated.\n */\nexport function effectiveSwarmCount(args: Record<string, unknown>): number {\n\tlet total = 0;\n\tif (Array.isArray(args.tasks)) {\n\t\tfor (const task of args.tasks) total += countEntry(task);\n\t}\n\tif (Array.isArray(args.chain)) {\n\t\tfor (const step of args.chain) {\n\t\t\tconst parallel = step && typeof step === \"object\" ? (step as { parallel?: unknown }).parallel : undefined;\n\t\t\tif (Array.isArray(parallel)) {\n\t\t\t\tfor (const child of parallel) total += countEntry(child);\n\t\t\t}\n\t\t}\n\t}\n\treturn total;\n}\n\ninterface BranchEntryLike {\n\ttype: string;\n\tmessage?: { role?: string; content?: unknown };\n}\n\nfunction messageText(content: unknown): string {\n\tif (typeof content === \"string\") return content;\n\tif (Array.isArray(content)) {\n\t\treturn content\n\t\t\t.filter((c) => c && typeof c === \"object\" && (c as { type?: unknown }).type === \"text\")\n\t\t\t.map((c) => String((c as { text?: unknown }).text ?? \"\"))\n\t\t\t.join(\"\");\n\t}\n\treturn \"\";\n}\n\n/**\n * True when the current turn started from an explicit /swarm prompt (the most\n * recent user message carries the literal `[SWARM MODE]` prefix). Both the TUI\n * and the gateway inject the same buildSwarmPrompt text, so this works on both\n * surfaces without extra state.\n */\nexport function isExplicitSwarmTurn(branch: readonly BranchEntryLike[]): boolean {\n\tfor (let i = branch.length - 1; i >= 0; i--) {\n\t\tconst entry = branch[i];\n\t\tif (entry.type !== \"message\" || entry.message?.role !== \"user\") continue;\n\t\treturn messageText(entry.message.content).startsWith(\"[SWARM MODE]\");\n\t}\n\treturn false;\n}\n"]}

package/dist/core/system-prompt.d.ts

@@ -0,0 +1,28 @@
+/**
+ * System prompt construction and project context loading
+ */
+import { type Skill } from "./skills.ts";
+export interface BuildSystemPromptOptions {
+    /** Custom system prompt (replaces default). */
+    customPrompt?: string;
+    /** Tools to include in prompt. Default: [read, bash, edit, write] */
+    selectedTools?: string[];
+    /** Optional one-line tool snippets keyed by tool name. */
+    toolSnippets?: Record<string, string>;
+    /** Additional guideline bullets appended to the default system prompt guidelines. */
+    promptGuidelines?: string[];
+    /** Text to append to system prompt. */
+    appendSystemPrompt?: string;
+    /** Working directory. */
+    cwd: string;
+    /** Pre-loaded context files. */
+    contextFiles?: Array<{
+        path: string;
+        content: string;
+    }>;
+    /** Pre-loaded skills. */
+    skills?: Skill[];
+}
+/** Build the system prompt with tools, guidelines, and context */
+export declare function buildSystemPrompt(options: BuildSystemPromptOptions): string;
+//# sourceMappingURL=system-prompt.d.ts.map

package/dist/core/system-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/core/system-prompt.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAyB,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAEhE,MAAM,WAAW,wBAAwB;IACxC,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,uCAAuC;IACvC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,yBAAyB;IACzB,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;CACjB;AAED,kEAAkE;AAClE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CAkI3E","sourcesContent":["/**\n * System prompt construction and project context loading\n */\n\nimport { getDocsPath, getExamplesPath, getReadmePath } from \"../config.ts\";\nimport { formatSkillsForPrompt, type Skill } from \"./skills.ts\";\n\nexport interface BuildSystemPromptOptions {\n\t/** Custom system prompt (replaces default). */\n\tcustomPrompt?: string;\n\t/** Tools to include in prompt. Default: [read, bash, edit, write] */\n\tselectedTools?: string[];\n\t/** Optional one-line tool snippets keyed by tool name. */\n\ttoolSnippets?: Record<string, string>;\n\t/** Additional guideline bullets appended to the default system prompt guidelines. */\n\tpromptGuidelines?: string[];\n\t/** Text to append to system prompt. */\n\tappendSystemPrompt?: string;\n\t/** Working directory. */\n\tcwd: string;\n\t/** Pre-loaded context files. */\n\tcontextFiles?: Array<{ path: string; content: string }>;\n\t/** Pre-loaded skills. */\n\tskills?: Skill[];\n}\n\n/** Build the system prompt with tools, guidelines, and context */\nexport function buildSystemPrompt(options: BuildSystemPromptOptions): string {\n\tconst {\n\t\tcustomPrompt,\n\t\tselectedTools,\n\t\ttoolSnippets,\n\t\tpromptGuidelines,\n\t\tappendSystemPrompt,\n\t\tcwd,\n\t\tcontextFiles: providedContextFiles,\n\t\tskills: providedSkills,\n\t} = options;\n\tconst promptCwd = cwd.replace(/\\\\/g, \"/\");\n\n\tconst appendSection = appendSystemPrompt ? `\\n\\n${appendSystemPrompt}` : \"\";\n\n\tconst contextFiles = providedContextFiles ?? [];\n\tconst skills = providedSkills ?? [];\n\n\tif (customPrompt) {\n\t\tlet prompt = customPrompt;\n\n\t\tif (appendSection) {\n\t\t\tprompt += appendSection;\n\t\t}\n\n\t\t// Append project context files\n\t\tif (contextFiles.length > 0) {\n\t\t\tprompt += \"\\n\\n<project_context>\\n\\n\";\n\t\t\tprompt += \"Project-specific instructions and guidelines:\\n\\n\";\n\t\t\tfor (const { path: filePath, content } of contextFiles) {\n\t\t\t\tprompt += `<project_instructions path=\"${filePath}\">\\n${content}\\n</project_instructions>\\n\\n`;\n\t\t\t}\n\t\t\tprompt += \"</project_context>\\n\";\n\t\t}\n\n\t\t// Append skills section (only if read tool is available)\n\t\tconst customPromptHasRead = !selectedTools || selectedTools.includes(\"read\");\n\t\tif (customPromptHasRead && skills.length > 0) {\n\t\t\tprompt += formatSkillsForPrompt(skills);\n\t\t}\n\n\t\tprompt += `\\nCurrent working directory: ${promptCwd}`;\n\n\t\treturn prompt;\n\t}\n\n\t// Get absolute paths to documentation and examples\n\tconst readmePath = getReadmePath();\n\tconst docsPath = getDocsPath();\n\tconst examplesPath = getExamplesPath();\n\n\t// Build tools list based on selected tools.\n\t// A tool appears in Available tools only when the caller provides a one-line snippet.\n\tconst tools = selectedTools || [\"read\", \"bash\", \"edit\", \"write\"];\n\tconst visibleTools = tools.filter((name) => !!toolSnippets?.[name]);\n\tconst toolsList =\n\t\tvisibleTools.length > 0 ? visibleTools.map((name) => `- ${name}: ${toolSnippets![name]}`).join(\"\\n\") : \"(none)\";\n\n\t// Build guidelines based on which tools are actually available\n\tconst guidelinesList: string[] = [];\n\tconst guidelinesSet = new Set<string>();\n\tconst addGuideline = (guideline: string): void => {\n\t\tif (guidelinesSet.has(guideline)) {\n\t\t\treturn;\n\t\t}\n\t\tguidelinesSet.add(guideline);\n\t\tguidelinesList.push(guideline);\n\t};\n\n\tconst hasBash = tools.includes(\"bash\");\n\tconst hasGrep = tools.includes(\"grep\");\n\tconst hasFind = tools.includes(\"find\");\n\tconst hasLs = tools.includes(\"ls\");\n\tconst hasRead = tools.includes(\"read\");\n\n\t// File exploration guidelines\n\tif (hasBash && !hasGrep && !hasFind && !hasLs) {\n\t\taddGuideline(\"Use bash for file operations like ls, rg, find\");\n\t}\n\n\tfor (const guideline of promptGuidelines ?? []) {\n\t\tconst normalized = guideline.trim();\n\t\tif (normalized.length > 0) {\n\t\t\taddGuideline(normalized);\n\t\t}\n\t}\n\n\tconst guidelines = guidelinesList.map((g) => `- ${g}`).join(\"\\n\");\n\tconst guidelinesSection = guidelines ? `Guidelines:\\n${guidelines}\\n\\n` : \"\";\n\n\tlet prompt = `You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.\n\nAvailable tools:\n${toolsList}\n\nIn addition to the tools above, you may have access to other custom tools depending on the project.\n\n${guidelinesSection}Plan mode: the user toggles it with /plan. While active, investigate read-only and present a concrete plan before any file changes.\n\nPi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):\n- Main documentation: ${readmePath}\n- Additional docs: ${docsPath}\n- Examples: ${examplesPath} (extensions, custom tools, SDK)\n- When reading pi docs or examples, resolve docs/... under Additional docs and examples/... under Examples, not the current working directory\n- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md)\n- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing\n- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;\n\n\tif (appendSection) {\n\t\tprompt += appendSection;\n\t}\n\n\t// Append project context files\n\tif (contextFiles.length > 0) {\n\t\tprompt += \"\\n\\n<project_context>\\n\\n\";\n\t\tprompt += \"Project-specific instructions and guidelines:\\n\\n\";\n\t\tfor (const { path: filePath, content } of contextFiles) {\n\t\t\tprompt += `<project_instructions path=\"${filePath}\">\\n${content}\\n</project_instructions>\\n\\n`;\n\t\t}\n\t\tprompt += \"</project_context>\\n\";\n\t}\n\n\t// Append skills section (only if read tool is available)\n\tif (hasRead && skills.length > 0) {\n\t\tprompt += formatSkillsForPrompt(skills);\n\t}\n\n\tprompt += `\\nCurrent working directory: ${promptCwd}`;\n\n\treturn prompt;\n}\n"]}