stageflow 0.36.0 → 0.40.0

package/dist/memory/host.js

@@ -0,0 +1,394 @@
+import { copyFile, link, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { MEMORY_CARD_MAX, MEMORY_DESCRIPTION_MAX, MEMORY_KEY_MAX, MEMORY_PAGE_CAP, isMemoryId, memoryCardFileName, } from "./ids.js";
+const MEMORY_SEARCH_MAX = 20;
+const CARD_FILE = /^[0-9a-f]{64}$/;
+const COVER_PREVIOUS = ".body.md.prev";
+export const MEMORY_ERROR_CODES = [
+    "MEMORY_INVALID_ID",
+    "MEMORY_INVALID_DESCRIPTION",
+    "MEMORY_INVALID_KEY",
+    "MEMORY_EXISTS",
+    "MEMORY_NOT_FOUND",
+    "MEMORY_NO_PREVIOUS",
+    "MEMORY_CARD_EXISTS",
+    "MEMORY_CARD_NOT_FOUND",
+    "MEMORY_TOO_MANY_CARDS",
+    "MEMORY_MISMATCH",
+    "MEMORY_UNREADABLE",
+    "MEMORY_TOO_LARGE",
+    "MEMORY_NOT_ATTACHED",
+];
+export class MemoryError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.name = "MemoryError";
+        this.code = code;
+    }
+}
+export function memoryHome(env = process.env) {
+    const raw = env.STAGEFLOW_HOME?.trim();
+    if (raw)
+        return raw;
+    return globalStageflowHome();
+}
+export function memoryDir(home, id) {
+    return path.join(home, "memories", id);
+}
+function checkId(id) {
+    if (!isMemoryId(id))
+        throw new MemoryError("MEMORY_INVALID_ID");
+}
+function checkDescription(description) {
+    const text = description.trim();
+    if (text.length < 1 || text.length > MEMORY_DESCRIPTION_MAX) {
+        throw new MemoryError("MEMORY_INVALID_DESCRIPTION");
+    }
+    return text;
+}
+function checkBody(body) {
+    if (typeof body !== "string" || body.length > MEMORY_PAGE_CAP)
+        throw new MemoryError("MEMORY_TOO_LARGE");
+}
+function checkKey(key) {
+    if (typeof key !== "string")
+        throw new MemoryError("MEMORY_INVALID_KEY");
+    const text = key.trim();
+    if (text.length < 1 || text.length > MEMORY_KEY_MAX)
+        throw new MemoryError("MEMORY_INVALID_KEY");
+    return text;
+}
+export function inspectMemorySync(home, id) {
+    if (!isMemoryId(id))
+        return { ok: false, code: "MEMORY_INVALID_ID" };
+    const file = path.join(memoryDir(home, id), "memory.yaml");
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return { ok: false, code: "MEMORY_NOT_FOUND" };
+        return { ok: false, code: "MEMORY_UNREADABLE" };
+    }
+    return inspectYaml(id, text);
+}
+function inspectYaml(id, text) {
+    let raw;
+    try {
+        raw = parseYaml(text);
+    }
+    catch {
+        return { ok: false, code: "MEMORY_UNREADABLE" };
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return { ok: false, code: "MEMORY_UNREADABLE" };
+    }
+    const doc = raw;
+    if (doc.version !== 1)
+        return { ok: false, code: "MEMORY_UNREADABLE" };
+    if (doc.id !== id)
+        return { ok: false, code: "MEMORY_MISMATCH" };
+    if (typeof doc.description !== "string" || doc.description.trim().length < 1 || doc.description.trim().length > MEMORY_DESCRIPTION_MAX) {
+        return { ok: false, code: "MEMORY_UNREADABLE" };
+    }
+    return { ok: true, meta: { id, description: doc.description.trim() } };
+}
+async function readMetaAt(home, id) {
+    checkId(id);
+    const file = path.join(memoryDir(home, id), "memory.yaml");
+    let text;
+    try {
+        text = await readFile(file, "utf8");
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            throw new MemoryError("MEMORY_NOT_FOUND");
+        throw new MemoryError("MEMORY_UNREADABLE");
+    }
+    const inspected = inspectYaml(id, text);
+    if (!inspected.ok)
+        throw new MemoryError(inspected.code);
+    return inspected.meta;
+}
+function encodeCard(key, body) {
+    return JSON.stringify({ key, body });
+}
+function decodeCard(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new MemoryError("MEMORY_UNREADABLE");
+    }
+    if (typeof raw !== "object" || raw === null)
+        throw new MemoryError("MEMORY_UNREADABLE");
+    const key = raw.key;
+    const body = raw.body;
+    if (typeof key !== "string" || typeof body !== "string")
+        throw new MemoryError("MEMORY_UNREADABLE");
+    return { key, body };
+}
+/** A kept copy is either the text or absent. Cover and card files share this. */
+async function readKept(file) {
+    try {
+        return await readFile(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw new MemoryError("MEMORY_UNREADABLE");
+    }
+}
+async function readCardFile(file) {
+    const text = await readKept(file);
+    if (text === null)
+        return undefined;
+    return decodeCard(text);
+}
+function cardPaths(dir, key) {
+    const name = memoryCardFileName(key);
+    return {
+        name,
+        current: path.join(dir, name),
+        previous: path.join(dir, `.${name}.prev`),
+    };
+}
+function tempPath(dir, name) {
+    return path.join(dir, `.${name}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
+}
+async function commitNew(dir, name, content) {
+    const tmp = tempPath(dir, name);
+    const dest = path.join(dir, name);
+    try {
+        await writeFile(tmp, content, "utf8");
+        try {
+            await link(tmp, dest);
+            await rm(tmp, { force: true });
+        }
+        catch (linkError) {
+            if (linkError.code === "EEXIST")
+                throw new MemoryError("MEMORY_CARD_EXISTS");
+            await copyFile(tmp, dest);
+            await rm(tmp, { force: true });
+        }
+    }
+    catch (error) {
+        await rm(tmp, { force: true });
+        if (error instanceof MemoryError)
+            throw error;
+        if (error.code === "EEXIST")
+            throw new MemoryError("MEMORY_CARD_EXISTS");
+        throw new MemoryError("MEMORY_UNREADABLE");
+    }
+}
+async function commitReplacing(dir, name, previousName, content) {
+    const tmp = tempPath(dir, name);
+    try {
+        await writeFile(tmp, content, "utf8");
+        try {
+            await copyFile(path.join(dir, name), path.join(dir, previousName));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        await rename(tmp, path.join(dir, name));
+    }
+    catch (error) {
+        await rm(tmp, { force: true });
+        if (error instanceof MemoryError)
+            throw error;
+        throw new MemoryError("MEMORY_UNREADABLE");
+    }
+}
+async function currentCards(dir) {
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new MemoryError("MEMORY_NOT_FOUND");
+        throw new MemoryError("MEMORY_UNREADABLE");
+    }
+    const cards = [];
+    for (const name of names) {
+        if (!CARD_FILE.test(name))
+            continue;
+        const card = await readCardFile(path.join(dir, name));
+        if (card)
+            cards.push(card);
+    }
+    return cards;
+}
+function snippetFor(key, body, query) {
+    const needle = query.toLowerCase();
+    const bodyAt = body.toLowerCase().indexOf(needle);
+    const source = bodyAt >= 0 ? body : key;
+    const at = bodyAt >= 0 ? bodyAt : source.toLowerCase().indexOf(needle);
+    if (at < 0)
+        return source.slice(0, 80);
+    const start = Math.max(0, at - 40);
+    const end = Math.min(source.length, at + needle.length + 40);
+    return source.slice(start, end);
+}
+export function createMemoryHost(home) {
+    return {
+        async create(input) {
+            checkId(input.id);
+            const description = checkDescription(input.description);
+            const dir = memoryDir(home, input.id);
+            await mkdir(path.join(home, "memories"), { recursive: true });
+            try {
+                await mkdir(dir);
+            }
+            catch (error) {
+                if (error.code === "EEXIST")
+                    throw new MemoryError("MEMORY_EXISTS");
+                throw error;
+            }
+            const yaml = stringifyYaml({ id: input.id, version: 1, description }, { lineWidth: 0 });
+            try {
+                await writeFile(path.join(dir, "memory.yaml"), yaml, "utf8");
+                await writeFile(path.join(dir, "body.md"), "", "utf8");
+            }
+            catch (error) {
+                await rm(dir, { recursive: true, force: true });
+                throw error;
+            }
+            return { id: input.id, description, body: "" };
+        },
+        async list() {
+            let names;
+            try {
+                names = await readdir(path.join(home, "memories"));
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return [];
+                throw error;
+            }
+            const metas = [];
+            for (const name of names) {
+                const inspected = inspectMemorySync(home, name);
+                if (!inspected.ok)
+                    continue;
+                const cards = await currentCards(memoryDir(home, name));
+                metas.push({ id: inspected.meta.id, description: inspected.meta.description, cardCount: cards.length });
+            }
+            metas.sort((a, b) => a.id.localeCompare(b.id));
+            return metas;
+        },
+        async read(id) {
+            await readMetaAt(home, id);
+            try {
+                return await readFile(path.join(memoryDir(home, id), "body.md"), "utf8");
+            }
+            catch {
+                throw new MemoryError("MEMORY_UNREADABLE");
+            }
+        },
+        readMeta(id) {
+            return readMetaAt(home, id);
+        },
+        async replace(id, body) {
+            await readMetaAt(home, id);
+            checkBody(body);
+            const dir = memoryDir(home, id);
+            await commitReplacing(dir, "body.md", COVER_PREVIOUS, body);
+        },
+        async readPreviousCover(id) {
+            await readMetaAt(home, id);
+            const text = await readKept(path.join(memoryDir(home, id), COVER_PREVIOUS));
+            if (text === null)
+                throw new MemoryError("MEMORY_NO_PREVIOUS");
+            return text;
+        },
+        async addCard(id, key, body) {
+            const dir = memoryDir(home, id);
+            await readMetaAt(home, id);
+            const trimmed = checkKey(key);
+            checkBody(body);
+            const paths = cardPaths(dir, trimmed);
+            if (await readCardFile(paths.current))
+                throw new MemoryError("MEMORY_CARD_EXISTS");
+            if ((await currentCards(dir)).length >= MEMORY_CARD_MAX)
+                throw new MemoryError("MEMORY_TOO_MANY_CARDS");
+            await commitNew(dir, paths.name, encodeCard(trimmed, body));
+        },
+        async updateCard(id, key, body) {
+            const dir = memoryDir(home, id);
+            await readMetaAt(home, id);
+            const trimmed = checkKey(key);
+            checkBody(body);
+            const paths = cardPaths(dir, trimmed);
+            if (!(await readCardFile(paths.current)))
+                throw new MemoryError("MEMORY_CARD_NOT_FOUND");
+            await commitReplacing(dir, paths.name, `.${paths.name}.prev`, encodeCard(trimmed, body));
+        },
+        async readCard(id, key) {
+            await readMetaAt(home, id);
+            const trimmed = checkKey(key);
+            const card = await readCardFile(cardPaths(memoryDir(home, id), trimmed).current);
+            if (!card)
+                throw new MemoryError("MEMORY_CARD_NOT_FOUND");
+            return card.body;
+        },
+        async readPreviousCard(id, key) {
+            await readMetaAt(home, id);
+            const trimmed = checkKey(key);
+            const card = await readCardFile(cardPaths(memoryDir(home, id), trimmed).previous);
+            if (!card)
+                throw new MemoryError("MEMORY_CARD_NOT_FOUND");
+            return card.body;
+        },
+        async listCards(id) {
+            const dir = memoryDir(home, id);
+            await readMetaAt(home, id);
+            const keys = (await currentCards(dir)).map((card) => card.key);
+            keys.sort((a, b) => a.localeCompare(b));
+            return keys;
+        },
+        async searchCards(id, query) {
+            const dir = memoryDir(home, id);
+            await readMetaAt(home, id);
+            if (typeof query !== "string" || query.length === 0)
+                return [];
+            const needle = query.toLowerCase();
+            const hits = [];
+            for (const card of await currentCards(dir)) {
+                if (!card.key.toLowerCase().includes(needle) && !card.body.toLowerCase().includes(needle))
+                    continue;
+                hits.push({ key: card.key, snippet: snippetFor(card.key, card.body, query) });
+            }
+            hits.sort((a, b) => a.key.localeCompare(b.key));
+            return hits.slice(0, MEMORY_SEARCH_MAX);
+        },
+        async deleteCard(id, key) {
+            const dir = memoryDir(home, id);
+            await readMetaAt(home, id);
+            const trimmed = checkKey(key);
+            const paths = cardPaths(dir, trimmed);
+            if (!(await readCardFile(paths.current)))
+                throw new MemoryError("MEMORY_CARD_NOT_FOUND");
+            try {
+                await rm(paths.current, { force: true });
+                await rm(paths.previous, { force: true });
+            }
+            catch {
+                throw new MemoryError("MEMORY_UNREADABLE");
+            }
+        },
+    };
+}
+export function memoryHostFor(env = process.env) {
+    return createMemoryHost(memoryHome(env));
+}

package/dist/memory/ids.d.ts

@@ -0,0 +1,15 @@
+export declare const MEMORY_ID_PATTERN: RegExp;
+export declare const MEMORY_PAGE_CAP = 64000;
+export declare const MEMORY_DESCRIPTION_MAX = 500;
+export declare const MEMORY_KEY_MAX = 1024;
+export declare const MEMORY_CARD_MAX = 200;
+export declare function memoryCardFileName(key: string): string;
+export declare function isMemoryId(value: string): boolean;
+/** `undefined` when the key is absent or an empty list. Duplicates and bad ids fail. */
+export declare function parseMemoryIdList(raw: unknown): {
+    ok: true;
+    value: string[] | undefined;
+} | {
+    ok: false;
+    message: string;
+};

package/dist/memory/ids.js

@@ -0,0 +1,31 @@
+import { createHash } from "node:crypto";
+export const MEMORY_ID_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+export const MEMORY_PAGE_CAP = 64_000;
+export const MEMORY_DESCRIPTION_MAX = 500;
+export const MEMORY_KEY_MAX = 1024;
+export const MEMORY_CARD_MAX = 200;
+export function memoryCardFileName(key) {
+    return createHash("sha256").update(key, "utf8").digest("hex");
+}
+export function isMemoryId(value) {
+    return MEMORY_ID_PATTERN.test(value);
+}
+/** `undefined` when the key is absent or an empty list. Duplicates and bad ids fail. */
+export function parseMemoryIdList(raw) {
+    if (raw === undefined)
+        return { ok: true, value: undefined };
+    if (!Array.isArray(raw))
+        return { ok: false, message: "memories must be a list of ids" };
+    if (raw.length === 0)
+        return { ok: true, value: undefined };
+    const ids = [];
+    for (const item of raw) {
+        if (typeof item !== "string" || !isMemoryId(item)) {
+            return { ok: false, message: "each memory id must be lowercase letters, digits, _ or -, starting with a letter, at most 64 characters" };
+        }
+        ids.push(item);
+    }
+    if (new Set(ids).size !== ids.length)
+        return { ok: false, message: "duplicate memory id" };
+    return { ok: true, value: ids };
+}

package/dist/memory/worker.d.ts

@@ -0,0 +1 @@
+export declare function workerMemoryForStage(ids: readonly string[]): Promise<import("./access.js").StageMemory>;

package/dist/memory/worker.js

@@ -0,0 +1,84 @@
+import { randomUUID } from "node:crypto";
+import { MemoryError } from "./host.js";
+import { attachMemory } from "./access.js";
+const TIMEOUT_MS = 30_000;
+function request(type, input) {
+    return new Promise((resolve, reject) => {
+        if (!process.connected || !process.send) {
+            reject(new MemoryError("MEMORY_NOT_ATTACHED"));
+            return;
+        }
+        const requestId = randomUUID();
+        const finish = (error, response) => {
+            clearTimeout(timer);
+            process.off("message", receive);
+            process.off("disconnect", disconnected);
+            if (error)
+                reject(error);
+            else
+                resolve(response);
+        };
+        const disconnected = () => finish(new MemoryError("MEMORY_UNREADABLE"));
+        const receive = (message) => {
+            const response = message;
+            if (response?.type !== "memory.response" || response.requestId !== requestId)
+                return;
+            finish(undefined, response);
+        };
+        const timer = setTimeout(disconnected, TIMEOUT_MS);
+        process.on("message", receive);
+        process.once("disconnect", disconnected);
+        process.send({ type, requestId, input }, (error) => {
+            if (error)
+                disconnected();
+        });
+    });
+}
+export function workerMemoryForStage(ids) {
+    return attachMemory(ids, workerStageMemory());
+}
+function workerStageMemory() {
+    return {
+        async read(id) {
+            const response = await request("memory.read", { memory: id });
+            if (response.error)
+                throw new MemoryError(response.error.code);
+            return response.body ?? "";
+        },
+        async replace(id, content) {
+            const response = await request("memory.replace", { memory: id, content });
+            if (response.error)
+                throw new MemoryError(response.error.code);
+        },
+        async meta(id) {
+            const response = await request("memory.meta", { memory: id });
+            if (response.error || !response.meta)
+                throw new MemoryError(response.error?.code ?? "MEMORY_UNREADABLE");
+            return response.meta;
+        },
+        async addCard(id, key, body) {
+            const response = await request("memory.addCard", { memory: id, key, content: body });
+            if (response.error)
+                throw new MemoryError(response.error.code);
+        },
+        async updateCard(id, key, body) {
+            const response = await request("memory.updateCard", { memory: id, key, content: body });
+            if (response.error)
+                throw new MemoryError(response.error.code);
+        },
+        async readCard(id, key) {
+            const response = await request("memory.readCard", { memory: id, key });
+            if (response.error)
+                throw new MemoryError(response.error.code);
+            return response.body ?? "";
+        },
+        async searchCards(id, query) {
+            const response = await request("memory.searchCards", { memory: id, query });
+            if (response.error)
+                throw new MemoryError(response.error.code);
+            if (!response.hits)
+                throw new MemoryError("MEMORY_UNREADABLE");
+            return response.hits;
+        },
+    };
+}

package/dist/models/catalog.d.ts

@@ -0,0 +1,113 @@
+/** Last resort when nothing is connected and nothing is configured. Pi resolves unknown OpenRouter ids. */
+export declare const LAST_RESORT_MODEL = "openrouter/nvidia/nemotron-3.5-lightning:free";
+export type CatalogModel = {
+    /** `provider/model`, the form Pi resolves and stage, pipeline and agent files store. */
+    id: string;
+    provider: string;
+    name: string;
+    free: boolean;
+    contextWindow?: number;
+    reasoning?: boolean;
+    /** The provider runs its own file and shell tools beside Pi's, so agent grants and approvals cannot hold. */
+    nativeTools: boolean;
+};
+export type CatalogProvider = {
+    id: string;
+    name: string;
+    models: CatalogModel[];
+    /** `live`: Pi's catalog for this provider refreshed; `fallback`: built-in or cached list after an error. */
+    source: "live" | "fallback";
+    error?: string;
+};
+export type ModelCatalogSnapshot = {
+    /** Connected providers only. */
+    providers: CatalogProvider[];
+    /** Every model id across `providers`, sorted. */
+    models: string[];
+    fetchedAt: string;
+};
+/** The slice of Pi's ModelRuntime the catalog reads. */
+export type CatalogRuntime = {
+    getProviders(): ReadonlyArray<{
+        id: string;
+        name?: string;
+    }>;
+    getProviderAuthStatus(providerId: string): {
+        configured: boolean;
+    };
+    listCredentials(): Promise<ReadonlyArray<{
+        providerId: string;
+    }>>;
+    getModels(providerId?: string): ReadonlyArray<{
+        id: string;
+        name?: string;
+        provider: string;
+        contextWindow?: number;
+        reasoning?: boolean;
+        cost?: {
+            input?: number;
+            output?: number;
+        };
+    }>;
+    refresh(options?: {
+        allowNetwork?: boolean;
+        providers?: readonly string[];
+        force?: boolean;
+        signal?: AbortSignal;
+    }): Promise<{
+        errors: ReadonlyMap<string, Error>;
+    } | void>;
+};
+export type CursorModelSource = () => {
+    connected: boolean;
+    modelIds: string[];
+};
+export type ModelCatalogOptions = {
+    cwd: string;
+    createRuntime?: (authPath: string) => Promise<CatalogRuntime>;
+    cursor?: CursorModelSource;
+    now?: () => number;
+    /** How long a built snapshot is reused before connections are re-read. */
+    ttlMs?: number;
+    refreshTimeoutMs?: number;
+};
+/**
+ * The one place model lists and the default model come from. Models are those of connected
+ * providers, asked of Pi's registry (live where the provider lists models, built-in otherwise).
+ */
+export declare class ModelCatalog {
+    private readonly options;
+    private cached;
+    private inflight;
+    private lastDefault;
+    constructor(options: ModelCatalogOptions);
+    private now;
+    /** Cached list; rebuilt when older than the TTL or when `refresh` forces Pi to refetch provider catalogs. */
+    snapshot(options?: {
+        refresh?: boolean;
+    }): Promise<ModelCatalogSnapshot>;
+    refresh(): Promise<ModelCatalogSnapshot>;
+    /** True when the id belongs to a connected provider. Custom ids still run; this only drives warnings. */
+    isKnown(id: string): Promise<boolean>;
+    /**
+     * stageflow.yaml `model`, then the Settings workshop model, then the catalog's pick: the last-resort
+     * model when connected, else the first free model, else the first model, else the last resort.
+     */
+    defaultModel(): Promise<string>;
+    /** Synchronous default for call sites that cannot await: the last resolved default, else the last resort. */
+    peekDefault(): string;
+    private remember;
+    private configuredDefault;
+    private configuredDefaultSync;
+    private pick;
+    private build;
+}
+/**
+ * The most recently resolved default, for call sites that cannot await. Hosts resolve it at boot,
+ * so this is the catalog's answer, not a second source.
+ */
+export declare function peekDefaultModel(): string;
+/** The Host's catalog for a working directory, shared by every consumer in the process. */
+export declare function getModelCatalog(cwd: string): ModelCatalog;
+export declare function resetModelCatalogsForTests(): void;
+export declare function setModelCatalogForTests(cwd: string, catalog: ModelCatalog): void;