@caupulican/pi-adaptative 0.80.57 → 0.80.59

package/dist/core/agent-session.js

@@ -31,6 +31,7 @@ import { createCoreDiagnosticsToolDefinitions } from "./extensions/builtin.js";
 import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
 import { disposeExtensionEventSubscriptions } from "./extensions/loader.js";
 import { emitSessionShutdownEvent } from "./extensions/runner.js";
+import { decideDemand, ReflectionEngine, } from "./learning/reflection-engine.js";
 import { MemoryManager } from "./memory/memory-manager.js";
 import { FileStoreProvider } from "./memory/providers/file-store.js";
 import { compactToolResultDetailsForRetention } from "./message-retention.js";
@@ -59,6 +60,8 @@ export function parseSkillBlock(text) {
         userMessage: match[4]?.trim() || undefined,
     };
 }
+/** customType for spawned-usage roll-up entries (Cost Aggregation, Model A). */
+export const SPAWNED_USAGE_CUSTOM_TYPE = "spawned_usage";
 // ============================================================================
 // Constants
 // ============================================================================
@@ -2082,6 +2085,9 @@ export class AgentSession {
             setThinkingLevel: (level) => this.setThinkingLevel(level),
             getExternalResourceRoots: () => this.settingsManager.getEffectiveExternalResourceRoots(),
             registerMemoryProvider: (provider) => this.registerMemoryProvider(provider),
+            reportSpawnedUsage: (usage, opts) => {
+                this.addSpawnedUsage(usage, opts);
+            },
         }, {
             getModel: () => this.model,
             isIdle: () => !this.isStreaming,
@@ -3089,6 +3095,260 @@ export class AgentSession {
             contextUsage: this.getContextUsage(),
         };
     }
+    /**
+     * Cumulative usage (full breakdown) for this session's entire spawn subtree: its own
+     * assistant messages PLUS every `spawned_usage` report it has rolled up. Single source of
+     * truth for "how much did this session and everything it spawned spend" — used by print-mode
+     * to emit a child's total so a spawner can roll it up via {@link addSpawnedUsage}.
+     *
+     * Including the `spawned_usage` reports is what keeps the single-hop invariant intact: a child
+     * that itself spawned grandchildren must report own + sub-usage in one number, or the parent
+     * silently under-counts the grandchildren.
+     */
+    getCumulativeUsage() {
+        let input = 0;
+        let output = 0;
+        let cacheRead = 0;
+        let cacheWrite = 0;
+        let totalTokens = 0;
+        let costInput = 0;
+        let costOutput = 0;
+        let costCacheRead = 0;
+        let costCacheWrite = 0;
+        let costTotal = 0;
+        const add = (usage) => {
+            input += usage.input;
+            output += usage.output;
+            cacheRead += usage.cacheRead;
+            cacheWrite += usage.cacheWrite;
+            totalTokens += usage.totalTokens;
+            costInput += usage.cost.input;
+            costOutput += usage.cost.output;
+            costCacheRead += usage.cost.cacheRead;
+            costCacheWrite += usage.cost.cacheWrite;
+            costTotal += usage.cost.total;
+        };
+        for (const message of this.state.messages) {
+            if (message.role !== "assistant")
+                continue;
+            const usage = message.usage;
+            if (!usage)
+                continue;
+            add(usage);
+        }
+        // Roll up usage this session attributed to its own spawned children (single-hop).
+        for (const entry of this.sessionManager.getEntries()) {
+            if (entry.type !== "custom" || entry.customType !== SPAWNED_USAGE_CUSTOM_TYPE)
+                continue;
+            const data = entry.data;
+            if (data?.usage)
+                add(data.usage);
+        }
+        return {
+            input,
+            output,
+            cacheRead,
+            cacheWrite,
+            totalTokens,
+            cost: {
+                input: costInput,
+                output: costOutput,
+                cacheRead: costCacheRead,
+                cacheWrite: costCacheWrite,
+                total: costTotal,
+            },
+        };
+    }
+    /**
+     * Record usage spent by a spawned/subagent session so the footer can roll it into the
+     * displayed cost. Persisted as a `CustomEntry` (`customType: "spawned_usage"`, Model A) so
+     * it survives reload and is reconstructed exactly like main usage; a new/forked session
+     * starts fresh because it owns a new log file.
+     *
+     * Idempotent on `opts.reportId`: a re-report (retry, duplicate `agent_end`) with a
+     * previously-seen id is ignored, so cost cannot be double-counted. Honors the single-hop
+     * invariant documented on {@link SpawnedUsageReport}.
+     *
+     * @returns the id of the appended entry, or `undefined` if the report was a duplicate.
+     */
+    addSpawnedUsage(usage, opts) {
+        const reportId = opts?.reportId;
+        if (reportId) {
+            for (const entry of this.sessionManager.getEntries()) {
+                if (entry.type === "custom" &&
+                    entry.customType === SPAWNED_USAGE_CUSTOM_TYPE &&
+                    entry.data?.reportId === reportId) {
+                    return undefined;
+                }
+            }
+        }
+        const report = {
+            usage,
+            label: opts?.label,
+            sourceSessionId: opts?.sourceSessionId,
+            reportId,
+        };
+        return this.sessionManager.appendCustomEntry(SPAWNED_USAGE_CUSTOM_TYPE, report);
+    }
+    /** Aggregate all recorded spawned-usage reports (see {@link addSpawnedUsage}). */
+    getSpawnedUsage() {
+        let cost = 0;
+        let reports = 0;
+        for (const entry of this.sessionManager.getEntries()) {
+            if (entry.type !== "custom" || entry.customType !== SPAWNED_USAGE_CUSTOM_TYPE)
+                continue;
+            const data = entry.data;
+            if (!data?.usage)
+                continue;
+            cost += data.usage.cost.total;
+            reports += 1;
+        }
+        return { cost, reports };
+    }
+    /**
+     * Run a one-shot LLM completion fully ISOLATED from the main session — the load-bearing
+     * primitive for the native reflection engine (adaptive-agent design §6c/§7).
+     *
+     * Isolation invariants (audited by codex): builds a fresh {@link Context} (no main history), runs
+     * with `tools: []`, sets `cacheRetention: "none"`, and passes **no `sessionId`** — so it cannot
+     * mutate `agent.state.messages`, cannot append session entries, cannot touch the tool registry,
+     * and cannot churn the main session's prompt cache. Mirrors `generateSummary()`'s mechanics.
+     *
+     * Returns the result even on an error/aborted stop reason (callers — e.g. a background reflection
+     * microtask — decide whether to act); it does not throw on a model-level error.
+     */
+    async runIsolatedCompletion(opts) {
+        const model = opts.model ?? this.model;
+        if (!model) {
+            throw new Error("runIsolatedCompletion: no model available");
+        }
+        const thinkingLevel = opts.thinkingLevel ?? "off";
+        // Fresh, isolated context: explicit messages, no tools, nothing from the main session.
+        const context = {
+            systemPrompt: opts.systemPrompt,
+            messages: opts.messages,
+            tools: [],
+        };
+        // Isolate the prompt cache and DELIBERATELY omit sessionId so no session-aware caching/routing
+        // can entangle this call with the main session.
+        const options = {
+            maxTokens: opts.maxTokens,
+            signal: opts.signal,
+            cacheRetention: "none",
+        };
+        // pi-ai's `reasoning` option does not include "off" (that's the provider default already).
+        if (thinkingLevel !== "off") {
+            options.reasoning = thinkingLevel;
+        }
+        // When streamFn is the raw streamSimple (e.g. in tests), auth must be injected explicitly.
+        // Throw only when auth genuinely fails — providers that authenticate without an API key
+        // (OAuth, local no-key) legitimately return ok with an undefined apiKey.
+        if (this.agent.streamFn === streamSimple) {
+            const auth = await this._modelRegistry.getApiKeyAndHeaders(model);
+            if (!auth.ok) {
+                throw new Error(auth.error);
+            }
+            options.apiKey = auth.apiKey;
+            options.headers = auth.headers;
+        }
+        const stream = await this.agent.streamFn(model, context, options);
+        const result = await stream.result();
+        const text = result.content
+            .filter((c) => c.type === "text")
+            .map((c) => c.text)
+            .join("");
+        const usage = result.usage ?? {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            totalTokens: 0,
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+        };
+        return { text, usage, stopReason: result.stopReason };
+    }
+    /**
+     * Native end-of-loop reflection pass (R2). Demand-gates (zero-I/O), and when warranted runs the
+     * {@link ReflectionEngine} via an isolated completion ({@link runIsolatedCompletion}), applies the
+     * resulting memory writes through the bundled `memory` tool, and accounts the reflection's token
+     * cost via the cost-aggregation surface so it stays visible and net-negative-auditable.
+     *
+     * Returns `null` when the gate skips (or in a child session, which must not learn). The whole pass
+     * is best-effort: a model/parse error yields no writes, never throws into the caller.
+     */
+    async runReflectionPass(input) {
+        if (this._isChildSession)
+            return null;
+        const plan = decideDemand(input.signals);
+        if (plan.act === "skip")
+            return null;
+        const complete = (systemPrompt, userPrompt) => this.runIsolatedCompletion({
+            systemPrompt,
+            messages: [{ role: "user", content: [{ type: "text", text: userPrompt }], timestamp: Date.now() }],
+            model: input.model,
+            thinkingLevel: input.thinkingLevel ?? "low",
+            maxTokens: plan.tokenBudget,
+            signal: input.signal,
+        });
+        const result = await new ReflectionEngine().reflect({
+            recentTurnText: input.recentTurnText,
+            // Read memory FRESH (not the prefix-cache-frozen system-prompt block) so confront-before-write
+            // sees writes made earlier this session.
+            existingMemory: this._memoryManager.buildSystemPromptBlockFresh() || "",
+            plan,
+            complete,
+        });
+        for (const write of result.writes) {
+            await this._applyReflectionWrite(write, input.signal);
+        }
+        // Account the reflection's spend so it surfaces in the footer roll-up (net-token visibility).
+        // Idempotent on reportId so a retried/duplicated pass cannot double-count.
+        if (result.usage.cost.total > 0 || result.usage.totalTokens > 0) {
+            this.addSpawnedUsage(result.usage, { label: "reflection", reportId: input.reportId });
+        }
+        return result;
+    }
+    /**
+     * Apply one reflection write through the bundled `memory` tool. `memory_replace`/`memory_remove`
+     * don't carry a target file, so we try MEMORY.md first and fall back to USER.md when the substring
+     * isn't found there. Best-effort: failures are swallowed (reflection must never break a turn).
+     */
+    async _applyReflectionWrite(write, signal) {
+        const memTool = this._memoryManager.getToolDefinitions().find((t) => t.name === "memory");
+        const exec = memTool?.execute;
+        if (!exec)
+            return;
+        const run = (params) => exec("reflection", params, signal, undefined, undefined);
+        if (write.kind === "memory_add") {
+            try {
+                await run({ action: "add", target: write.section === "USER" ? "user" : "memory", content: write.text });
+            }
+            catch {
+                // best-effort; reflection writes must never throw into the turn loop
+            }
+            return;
+        }
+        // replace / remove carry no target file — try MEMORY.md, then USER.md. The memory tool reports
+        // outcomes via `details.success` (it catches its own errors rather than throwing). Only a
+        // genuine "not found in the file" justifies trying the other file; a real failure for a file
+        // (budget exceeded / drift) must NOT fall through and mutate the wrong target.
+        for (const target of ["memory", "user"]) {
+            try {
+                const params = write.kind === "memory_replace"
+                    ? { action: "replace", target, oldContent: write.target, content: write.text }
+                    : { action: "remove", target, oldContent: write.target };
+                const res = await run(params);
+                if (res?.details?.success === true)
+                    return; // applied
+                if (!/not found/i.test(String(res?.details?.error ?? "")))
+                    return; // real failure — don't misapply
+                // substring simply absent from this file — try the next target
+            }
+            catch {
+                // defensive: if the tool ever does throw, try the next target
+            }
+        }
+    }
     getContextUsage() {
         const model = this.model;
         if (!model)