pi-fabric 0.1.0

package/dist/subagents/budget-ledger.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Cross-process cost budget ledger for a Fabric recursion tree.
+ *
+ * A recursion tree spans one Pi process per node. Each node's SubagentManager
+ * records the cost of the children it spawns into a single append-only JSONL
+ * file, and checks the accumulated spend before spawning another child. The
+ * ledger path and budget travel to descendants through PI_FABRIC_BUDGET*
+ * environment variables, which the worker forwards to child Pi processes via
+ * `{ ...process.env }`.
+ *
+ * This mirrors ypi's RLM_BUDGET / RLM_COST_FILE model: the check is best-effort
+ * (concurrent children can each pass the check before any cost lands, so a tree
+ * may slightly overshoot), while the race-free ceiling remains the per-execution
+ * call count (subagents.maxPerExecution). Cost is recorded only after a child
+ * finishes, matching ypi's append-after-completion semantics.
+ */
+export interface BudgetLedgerEntry {
+    id: string;
+    depth: number;
+    cost: number;
+    tokens: number;
+    ts: number;
+}
+export interface BudgetLedgerSummary {
+    cost: number;
+    tokens: number;
+}
+export interface BudgetLedgerState {
+    budget: number;
+    file: string;
+    id: string;
+}
+/**
+ * Read the active budget state inherited from the recursion-tree root.
+ * Returns undefined when no budget is active for this process.
+ */
+export declare function activeBudgetState(): BudgetLedgerState | undefined;
+/**
+ * Initialize a shared ledger for a recursion tree and seed the environment
+ * variables that descendants inherit. Only call at the tree root (depth 0)
+ * when no budget has been inherited and a positive budget is configured.
+ */
+export declare function initBudgetLedger(budget: number): BudgetLedgerState;
+/**
+ * Clear the budget environment variables seeded by initBudgetLedger. Called by
+ * the owning (depth-0) manager on close so a long-lived host process does not
+ * leak an active budget into a later, unrelated session.
+ */
+export declare function clearOwnedBudgetEnv(): void;
+/**
+ * Sum the append-only ledger. Malformed lines are tolerated, matching ypi's
+ * rlm_cost parser: a single bad entry must not abort the whole read.
+ */
+export declare function readBudgetLedger(file: string): BudgetLedgerSummary;
+/**
+ * Append a child's incurred cost to the shared ledger. O_APPEND makes small
+ * single-line writes atomic across concurrent writers on POSIX, which is
+ * sufficient because each manager appends one entry after a child settles.
+ */
+export declare function appendBudgetLedger(file: string, entry: BudgetLedgerEntry): void;
+//# sourceMappingURL=budget-ledger.d.ts.map

package/dist/subagents/budget-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-ledger.d.ts","sourceRoot":"","sources":["../../src/subagents/budget-ledger.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAYD;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,GAAG,SAAS,CAKjE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CASlE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAI1C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAoBlE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAO/E"}

package/dist/subagents/budget-ledger.js

@@ -0,0 +1,92 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const ENV_BUDGET = "PI_FABRIC_BUDGET";
+const ENV_BUDGET_FILE = "PI_FABRIC_BUDGET_FILE";
+const ENV_BUDGET_ID = "PI_FABRIC_BUDGET_ID";
+const parseFloatFinite = (value) => {
+    if (!value)
+        return undefined;
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+};
+/**
+ * Read the active budget state inherited from the recursion-tree root.
+ * Returns undefined when no budget is active for this process.
+ */
+export function activeBudgetState() {
+    const file = process.env[ENV_BUDGET_FILE];
+    const budget = parseFloatFinite(process.env[ENV_BUDGET]);
+    if (!file || budget === undefined || budget <= 0)
+        return undefined;
+    return { budget, file, id: process.env[ENV_BUDGET_ID] ?? "" };
+}
+/**
+ * Initialize a shared ledger for a recursion tree and seed the environment
+ * variables that descendants inherit. Only call at the tree root (depth 0)
+ * when no budget has been inherited and a positive budget is configured.
+ */
+export function initBudgetLedger(budget) {
+    const directory = fs.mkdtempSync(path.join(os.tmpdir(), "pi-fabric-budget-"));
+    const file = path.join(directory, "cost.jsonl");
+    fs.writeFileSync(file, "", { mode: 0o600 });
+    const id = randomUUID().replaceAll("-", "").slice(0, 16);
+    process.env[ENV_BUDGET] = String(budget);
+    process.env[ENV_BUDGET_FILE] = file;
+    process.env[ENV_BUDGET_ID] = id;
+    return { budget, file, id };
+}
+/**
+ * Clear the budget environment variables seeded by initBudgetLedger. Called by
+ * the owning (depth-0) manager on close so a long-lived host process does not
+ * leak an active budget into a later, unrelated session.
+ */
+export function clearOwnedBudgetEnv() {
+    delete process.env[ENV_BUDGET];
+    delete process.env[ENV_BUDGET_FILE];
+    delete process.env[ENV_BUDGET_ID];
+}
+/**
+ * Sum the append-only ledger. Malformed lines are tolerated, matching ypi's
+ * rlm_cost parser: a single bad entry must not abort the whole read.
+ */
+export function readBudgetLedger(file) {
+    let cost = 0;
+    let tokens = 0;
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return { cost, tokens };
+    }
+    for (const line of raw.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            cost += Number(parsed.cost) || 0;
+            tokens += Number(parsed.tokens) || 0;
+        }
+        catch {
+            // Ignore malformed cost lines; the ledger is best-effort.
+        }
+    }
+    return { cost, tokens };
+}
+/**
+ * Append a child's incurred cost to the shared ledger. O_APPEND makes small
+ * single-line writes atomic across concurrent writers on POSIX, which is
+ * sufficient because each manager appends one entry after a child settles.
+ */
+export function appendBudgetLedger(file, entry) {
+    try {
+        fs.appendFileSync(file, `${JSON.stringify(entry)}\n`);
+    }
+    catch {
+        // A ledger write failure must not break the agent run; the next check
+        // still guards against runaway spend via the per-execution call ceiling.
+    }
+}
+//# sourceMappingURL=budget-ledger.js.map

package/dist/subagents/budget-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-ledger.js","sourceRoot":"","sources":["../../src/subagents/budget-ledger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAsC7B,MAAM,UAAU,GAAG,kBAAkB,CAAC;AACtC,MAAM,eAAe,GAAG,uBAAuB,CAAC;AAChD,MAAM,aAAa,GAAG,qBAAqB,CAAC;AAE5C,MAAM,gBAAgB,GAAG,CAAC,KAAyB,EAAsB,EAAE;IACzE,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IACxC,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AACtD,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;IACzD,IAAI,CAAC,IAAI,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACnE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC;AAChE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,SAAS,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,mBAAmB,CAAC,CAAC,CAAC;IAC9E,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IAChD,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5C,MAAM,EAAE,GAAG,UAAU,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACzD,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IACzC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,GAAG,EAAE,CAAC;IAChC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC/B,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACpC,OAAO,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC1B,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;YAAE,SAAS;QAC3B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAA+B,CAAC;YAC9D,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,0DAA0D;QAC5D,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,KAAwB;IACvE,IAAI,CAAC;QACH,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;QACtE,yEAAyE;IAC3E,CAAC;AACH,CAAC"}

package/dist/subagents/manager.d.ts

@@ -0,0 +1,27 @@
+import type { FabricSubagentConfig } from "../config.js";
+import type { SubagentHandleInfo, SubagentRunRecord, SubagentRunRequest, SubagentRunResult } from "./types.js";
+export declare class SubagentManager {
+    #private;
+    readonly cwd: string;
+    readonly config: FabricSubagentConfig;
+    constructor(cwd: string, config: FabricSubagentConfig, options?: {
+        workerPath?: string;
+        fabricExtensionPath?: string;
+        piBinary?: string;
+        runRoot?: string;
+        fullCodeMode?: boolean;
+        onBackgroundComplete?: (result: SubagentRunResult) => void;
+    });
+    spawn(request: SubagentRunRequest, signal?: AbortSignal): Promise<SubagentHandleInfo>;
+    run(request: SubagentRunRequest, signal?: AbortSignal): Promise<SubagentRunResult>;
+    wait(id: string): Promise<SubagentRunResult>;
+    detachSignal(id: string): void;
+    status(id: string): SubagentRunRecord | SubagentHandleInfo;
+    list(): Array<SubagentRunRecord | SubagentHandleInfo>;
+    stop(id: string): Promise<SubagentRunResult>;
+    cleanup(id: string, deleteBranch?: boolean): Promise<{
+        cleaned: boolean;
+    }>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/subagents/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/subagents/manager.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAA2B,MAAM,cAAc,CAAC;AAMlF,OAAO,KAAK,EAEV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EAGlB,MAAM,YAAY,CAAC;AAwHpB,qBAAa,eAAe;;IAiBxB,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,QAAQ,CAAC,MAAM,EAAE,oBAAoB;gBAD5B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,oBAAoB,EACrC,OAAO,GAAE;QACP,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,oBAAoB,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;KACvD;IA8BF,KAAK,CAAC,OAAO,EAAE,kBAAkB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAoJrF,GAAG,CAAC,OAAO,EAAE,kBAAkB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAKlF,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAMlD,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAU9B,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,kBAAkB;IAO1D,IAAI,IAAI,KAAK,CAAC,iBAAiB,GAAG,kBAAkB,CAAC;IAI/C,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAiB5C,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,YAAY,UAAQ,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAWxE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CA+K7B"}