qlogicagent 2.13.3 → 2.13.5

package/dist/agent/agent.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Agent — clean agent execution loop for CLI subprocess mode.
+ *
+ * Thin wrapper around tool-loop.ts. Handles:
+ *   - DI injection (LLMTransport, ToolInvoker, AgentLogger)
+ *   - Turn lifecycle (start event + message repair + delegate to tool loop)
+ *   - Top-level error handling
+ *
+ * The actual tool loop state machine (turn-loop-guard, tool-loop-state,
+ * parallel scheduling, tool filtering, etc.) lives in tool-loop.ts,
+ * ported faithfully from Hub's semantic-turn-tools.ts.
+ *
+ * Zero imports from express/pg/ioredis/ws.
+ */
+import type { AgentLogger, LLMTransport, ToolInvoker, TurnEvent, TurnRequest, HookRegistry } from "./types.js";
+import type { AgentRuntimePorts } from "../runtime/ports/index.js";
+export interface AgentConfig {
+    llmTransport: LLMTransport;
+    apiKey: string;
+    toolInvoker: ToolInvoker;
+    log: AgentLogger;
+    hooks?: HookRegistry;
+    maxRounds?: number;
+    verbose?: boolean;
+    /** Project root directory — used for skill pattern tracking. */
+    projectRoot?: string;
+    runtimePorts: AgentRuntimePorts;
+}
+export declare class Agent {
+    private transport;
+    private apiKey;
+    private toolInvoker;
+    private log;
+    private hooks?;
+    private maxRounds;
+    private projectRoot?;
+    private runtimePorts;
+    constructor(config: AgentConfig);
+    /**
+     * Execute an agent turn. Yields TurnEvent stream.
+     *
+     * 1. Emit start
+     * 2. Repair conversation history
+     * 3. Delegate to executeToolLoop() (full Hub-ported tool loop state machine)
+     * 4. Catch unhandled errors
+     */
+    run(request: TurnRequest, signal?: AbortSignal): AsyncGenerator<TurnEvent>;
+}

package/dist/agent/agent.js

@@ -0,0 +1,197 @@
+/**
+ * Agent — clean agent execution loop for CLI subprocess mode.
+ *
+ * Thin wrapper around tool-loop.ts. Handles:
+ *   - DI injection (LLMTransport, ToolInvoker, AgentLogger)
+ *   - Turn lifecycle (start event + message repair + delegate to tool loop)
+ *   - Top-level error handling
+ *
+ * The actual tool loop state machine (turn-loop-guard, tool-loop-state,
+ * parallel scheduling, tool filtering, etc.) lives in tool-loop.ts,
+ * ported faithfully from Hub's semantic-turn-tools.ts.
+ *
+ * Zero imports from express/pg/ioredis/ws.
+ */
+import { repairOpenAiChatConversation, classifyError, isRetryableCategory, } from "../orchestration/index.js";
+import { executeToolLoop } from "./tool-loop.js";
+import { fireHook } from "../contracts/fire-hook.js";
+import { MAX_ROUNDS_LIMIT, DEFAULT_MAX_ROUNDS } from "./tunable-defaults.js";
+import { recallMemoriesForTurn } from "./memory-recall-injection.js";
+export class Agent {
+    transport;
+    apiKey;
+    toolInvoker;
+    log;
+    hooks;
+    maxRounds;
+    projectRoot;
+    runtimePorts;
+    constructor(config) {
+        this.transport = config.llmTransport;
+        this.apiKey = config.apiKey;
+        this.toolInvoker = config.toolInvoker;
+        this.log = config.log;
+        this.hooks = config.hooks;
+        this.projectRoot = config.projectRoot;
+        this.runtimePorts = config.runtimePorts;
+        this.maxRounds = Math.min(config.maxRounds ?? DEFAULT_MAX_ROUNDS, MAX_ROUNDS_LIMIT);
+    }
+    /**
+     * Execute an agent turn. Yields TurnEvent stream.
+     *
+     * 1. Emit start
+     * 2. Repair conversation history
+     * 3. Delegate to executeToolLoop() (full Hub-ported tool loop state machine)
+     * 4. Catch unhandled errors
+     */
+    async *run(request, signal) {
+        const { turnId, messages: inputMessages, tools, systemPrompt, config } = request;
+        const hookCtx = { sessionId: request.sessionId, turnId };
+        yield { type: "start", turnId };
+        // Hook: turn.submitted
+        fireHook(this.hooks, "turn.submitted", {
+            ...hookCtx,
+            prompt: inputMessages[inputMessages.length - 1]?.content ?? undefined,
+        }, this.log);
+        // Repair malformed tool-call sequences in the input conversation history
+        const repairedMessages = repairOpenAiChatConversation(inputMessages);
+        // Build conversation: prepend system prompt if provided
+        const conversation = [];
+        if (systemPrompt) {
+            conversation.push({ role: "system", content: systemPrompt });
+        }
+        conversation.push(...repairedMessages);
+        // ── QMemory recall injection (hippocampus bridge) ──
+        // Prefetch relevant long-term memories and inject them as a system message.
+        // Orchestration (hook + per-turn byte cap + after_recall) lives in
+        // memory-recall-injection.ts; Agent.run only decides where to splice it.
+        if (this.hooks) {
+            const lastUserMsg = repairedMessages.filter(m => m.role === "user").pop();
+            const query = typeof lastUserMsg?.content === "string"
+                ? lastUserMsg.content.slice(0, 500)
+                : undefined;
+            if (query) {
+                const recalled = await recallMemoriesForTurn({
+                    hooks: this.hooks,
+                    detectRecallCategories: (q) => this.runtimePorts.detectRecallCategories(q),
+                    log: this.log,
+                    sessionId: request.sessionId,
+                    turnId,
+                    query,
+                });
+                if (recalled) {
+                    conversation.splice(systemPrompt ? 1 : 0, 0, { role: "system", content: recalled });
+                }
+            }
+        }
+        const model = config?.model ?? "";
+        const maxRounds = Math.min(config?.maxRounds ?? this.maxRounds, MAX_ROUNDS_LIMIT);
+        try {
+            // Build generateToolUseSummary callback — resolves model from registry at call time (CC parity: Haiku)
+            const generateToolUseSummary = async (toolCalls) => {
+                const smallModel = this.runtimePorts.resolveModelForPurpose("smallModel");
+                if (!smallModel)
+                    return null;
+                try {
+                    const prompt = toolCalls.map(tc => `${tc.name}(${tc.arguments.slice(0, 200)})`).join(", ");
+                    const stream = this.transport.stream({
+                        model: smallModel,
+                        messages: [
+                            { role: "system", content: "Summarize the tool usage in ~30 chars, git-commit-subject style. Reply with ONLY the summary, nothing else." },
+                            { role: "user", content: prompt },
+                        ],
+                        tools: [],
+                        maxTokens: 60,
+                    }, config?.apiKey ?? this.apiKey);
+                    let text = "";
+                    for await (const chunk of stream) {
+                        if (chunk.type === "delta")
+                            text += chunk.text;
+                    }
+                    return text.trim() || null;
+                }
+                catch {
+                    return null;
+                }
+            };
+            // "auto"(智能)= let the model/provider decide natively. We deliberately do NOT
+            // run a per-turn classifier: it adds a round-trip of latency, can't see conversation
+            // context (a bare "继续" looks trivial yet the task may be complex), and is near-useless
+            // on providers that collapse effort levels (DeepSeek maps low/medium→high regardless).
+            // Instead keep reasoning ENABLED with a neutral default so the transport's per-model
+            // logic governs: adaptive-capable models (e.g. Anthropic Opus/Sonnet) self-regulate
+            // depth — zero thinking for trivial, deep for hard — ignoring the effort value; DeepSeek
+            // floors to its native level; flat-effort models (o-series/Kimi) get a sane default.
+            // Manual low/medium/high/xhigh pass through unchanged.
+            let resolvedReasoning = config?.reasoning;
+            if (config?.reasoning?.effort === "auto") {
+                resolvedReasoning = { ...config?.reasoning, effort: "medium" };
+            }
+            const toolLoopParams = {
+                turnId,
+                sessionId: request.sessionId,
+                messages: conversation,
+                tools,
+                model,
+                apiKey: config?.apiKey ?? this.apiKey,
+                temperature: config?.temperature,
+                maxRounds,
+                contextWindowTokens: config?.contextWindowTokens,
+                maxOutputTokens: config?.maxOutputTokens,
+                modelMaxOutputTokens: config?.modelMaxOutputTokens,
+                toolChoice: config?.toolChoice,
+                parentDepth: config?.parentDepth,
+                hooks: this.hooks,
+                fallbackModel: config?.fallbackModel,
+                maxTurns: config?.maxTurns,
+                tokenBudget: config?.tokenBudget,
+                maxConcurrentTools: config?.maxConcurrentTools,
+                streamRequired: config?.streamRequired,
+                reasoning: resolvedReasoning,
+                promptCacheKey: config?.promptCacheKey,
+                promptCacheRetention: config?.promptCacheRetention,
+                serviceTier: config?.serviceTier,
+                openaiBuiltinTools: config?.openaiBuiltinTools,
+                maxToolCalls: config?.maxToolCalls,
+                parallelToolCalls: config?.parallelToolCalls,
+                textVerbosity: config?.textVerbosity,
+                projectRoot: this.projectRoot,
+                generateToolUseSummary,
+                runtimePorts: this.runtimePorts.toolLoop,
+                signal,
+            };
+            let lastEvent;
+            for await (const event of executeToolLoop(toolLoopParams, this.transport, this.toolInvoker, this.log)) {
+                lastEvent = event;
+                yield event;
+            }
+            // Hook: turn.completed / turn.failed based on final event
+            if (lastEvent?.type === "end") {
+                fireHook(this.hooks, "turn.completed", { ...hookCtx }, this.log);
+            }
+            else if (lastEvent?.type === "error") {
+                fireHook(this.hooks, "turn.failed", {
+                    ...hookCtx,
+                    code: lastEvent.code,
+                    error: lastEvent.error,
+                }, this.log);
+            }
+        }
+        catch (err) {
+            if (signal?.aborted) {
+                fireHook(this.hooks, "turn.failed", { ...hookCtx, code: "ABORTED", error: "Turn aborted" }, this.log);
+                yield { type: "error", turnId, error: "Turn aborted", code: "ABORTED" };
+            }
+            else {
+                const message = err instanceof Error ? err.message : String(err);
+                const status = typeof err?.status === "number"
+                    ? err.status
+                    : undefined;
+                const category = classifyError(status, message);
+                this.log.error(`turn ${turnId} error [${category}, retryable=${isRetryableCategory(category)}]: ${message}`);
+                fireHook(this.hooks, "turn.failed", { ...hookCtx, code: category, error: message }, this.log);
+                yield { type: "error", turnId, error: message, code: category };
+            }
+        }
+    }
+}

package/dist/agent/memory-recall-context.d.ts

@@ -0,0 +1,18 @@
+export type RecalledMemorySource = "l1-project-md" | "l2-long-term" | "skill" | "system" | "unknown";
+export interface RecalledMemoryForPrompt {
+    text: string;
+    score?: number;
+    category?: string | null;
+    source?: RecalledMemorySource | string;
+    label?: string;
+}
+export interface RecallMemoryConflict {
+    entity: string;
+    predicate: string;
+    l1Amount: number;
+    l2Amount: number;
+    l1Text: string;
+    l2Text: string;
+}
+export declare function buildRecalledMemorySystemContent(memories: RecalledMemoryForPrompt[]): string;
+export declare function detectRecallMemoryConflicts(memories: RecalledMemoryForPrompt[]): RecallMemoryConflict[];

package/dist/agent/memory-recall-context.js

@@ -0,0 +1,139 @@
+const AMOUNT_PREDICATES = [
+    "接单金额",
+    "合同金额",
+    "报价",
+    "预算",
+    "金额",
+    "price",
+    "amount",
+    "contract amount",
+];
+export function buildRecalledMemorySystemContent(memories) {
+    const conflicts = detectRecallMemoryConflicts(memories);
+    const lines = [
+        "[Recalled memories]",
+        "- L1 project MD is project-scoped working memory.",
+        "- L2 long-term memory is cross-project canonical memory.",
+        "- If L1 and L2 conflict on the same entity/fact, do not silently merge or choose. Surface the conflict and ask the user to confirm. For current-project operational tasks, use L1 only as a project-scoped clue until confirmed into L2.",
+    ];
+    if (conflicts.length > 0) {
+        lines.push("[Memory conflict detected]");
+        for (const conflict of conflicts) {
+            lines.push(`- entity: ${conflict.entity}; fact: ${conflict.predicate}; L1 project MD says: ${formatAmount(conflict.l1Amount)}; L2 long-term says: ${formatAmount(conflict.l2Amount)}; action: ask the user which value is current before using it.`);
+        }
+    }
+    for (const memory of memories) {
+        const label = getMemorySourceLabel(memory);
+        lines.push(`- [${label}] ${memory.text}`);
+    }
+    return lines.join("\n");
+}
+export function detectRecallMemoryConflicts(memories) {
+    const l1Facts = memories
+        .filter(memory => memory.source === "l1-project-md")
+        .flatMap(memory => extractAmountFacts(memory.text));
+    const l2Facts = memories
+        .filter(memory => memory.source === "l2-long-term")
+        .flatMap(memory => extractAmountFacts(memory.text));
+    const conflicts = [];
+    for (const l1 of l1Facts) {
+        for (const l2 of l2Facts) {
+            if (l1.entity === l2.entity
+                && l1.predicate === l2.predicate
+                && l1.amount !== l2.amount) {
+                conflicts.push({
+                    entity: l1.entity,
+                    predicate: l1.predicate,
+                    l1Amount: l1.amount,
+                    l2Amount: l2.amount,
+                    l1Text: l1.text,
+                    l2Text: l2.text,
+                });
+            }
+        }
+    }
+    return dedupeConflicts(conflicts);
+}
+function extractAmountFacts(text) {
+    const facts = [];
+    for (const line of text.split(/\r?\n/)) {
+        const compactLine = line.trim();
+        if (!compactLine)
+            continue;
+        for (const predicate of AMOUNT_PREDICATES) {
+            if (predicate === "金额" && /(接单金额|合同金额)/u.test(compactLine))
+                continue;
+            const pattern = new RegExp(`${escapeRegExp(predicate)}[^0-9.万kK,]{0,12}([0-9][0-9.,]*\\s*(?:万|k|K)?)`, "gi");
+            for (const match of compactLine.matchAll(pattern)) {
+                const amount = normalizeAmount(match[1]);
+                if (amount === null)
+                    continue;
+                facts.push({
+                    entity: inferEntity(compactLine, predicate),
+                    predicate,
+                    amount,
+                    text: compactLine,
+                });
+            }
+        }
+    }
+    return facts;
+}
+function inferEntity(text, predicate) {
+    if (/Galaxy\s+Tech/i.test(text))
+        return "Galaxy Tech";
+    if (text.includes("用户"))
+        return "用户";
+    const predicateIndex = text.toLowerCase().indexOf(predicate.toLowerCase());
+    const prefix = predicateIndex >= 0 ? text.slice(0, predicateIndex) : "";
+    const tokens = prefix
+        .replace(/[#*`:\-，。；;,.]/g, " ")
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+    return tokens[tokens.length - 1] ?? "unknown";
+}
+function normalizeAmount(raw) {
+    const trimmed = raw.replace(/,/g, "").replace(/\s+/g, "").trim();
+    const multiplier = trimmed.endsWith("万")
+        ? 10000
+        : /k$/i.test(trimmed)
+            ? 1000
+            : 1;
+    const numeric = Number(trimmed.replace(/[万kK]$/u, ""));
+    if (!Number.isFinite(numeric))
+        return null;
+    return numeric * multiplier;
+}
+function getMemorySourceLabel(memory) {
+    if (memory.label)
+        return memory.label;
+    switch (memory.source) {
+        case "l1-project-md":
+            return "L1 project MD";
+        case "l2-long-term":
+            return "L2 long-term";
+        case "skill":
+            return "Skill";
+        case "system":
+            return "System";
+        default:
+            return "Memory";
+    }
+}
+function formatAmount(amount) {
+    return Number.isInteger(amount) ? String(amount) : String(Number(amount.toFixed(4)));
+}
+function dedupeConflicts(conflicts) {
+    const seen = new Set();
+    return conflicts.filter(conflict => {
+        const key = `${conflict.entity}\0${conflict.predicate}\0${conflict.l1Amount}\0${conflict.l2Amount}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/agent/memory-recall-context.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agent/memory-recall-context.test.js

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { buildRecalledMemorySystemContent, detectRecallMemoryConflicts, } from "./memory-recall-context.js";
+describe("memory recall context", () => {
+    it("marks L1 project MD and L2 long-term memories as separate sources", () => {
+        const content = buildRecalledMemorySystemContent([
+            {
+                text: "用户接单金额 1000",
+                source: "l1-project-md",
+                label: "L1 project MD",
+            },
+            {
+                text: "用户偏好简洁回答",
+                source: "l2-long-term",
+                label: "L2 long-term",
+            },
+        ]);
+        expect(content).toContain("[L1 project MD]");
+        expect(content).toContain("[L2 long-term]");
+        expect(content).toContain("L1 project MD is project-scoped working memory");
+        expect(content).toContain("L2 long-term memory is cross-project canonical memory");
+    });
+    it("flags same-fact amount conflicts between L1 project MD and L2 long-term memory", () => {
+        const memories = [
+            {
+                text: "用户接单金额 1000",
+                source: "l1-project-md",
+            },
+            {
+                text: "用户接单金额 2000",
+                source: "l2-long-term",
+            },
+        ];
+        const conflicts = detectRecallMemoryConflicts(memories);
+        expect(conflicts).toHaveLength(1);
+        expect(conflicts[0]).toMatchObject({
+            entity: "用户",
+            predicate: "接单金额",
+            l1Amount: 1000,
+            l2Amount: 2000,
+        });
+        const content = buildRecalledMemorySystemContent(memories);
+        expect(content).toContain("[Memory conflict detected]");
+        expect(content).toContain("ask the user which value is current");
+    });
+    it("does not flag the same amount as a conflict", () => {
+        const conflicts = detectRecallMemoryConflicts([
+            {
+                text: "用户接单金额 1000",
+                source: "l1-project-md",
+            },
+            {
+                text: "用户接单金额 1000",
+                source: "l2-long-term",
+            },
+        ]);
+        expect(conflicts).toHaveLength(0);
+    });
+});

package/dist/agent/memory-recall-injection.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Turn-time QMemory recall orchestration (hippocampus bridge).
+ *
+ * Impure counterpart to the pure memory-recall-context.ts: it drives the
+ * `memory.before_recall` hook, caps the recalled set by a per-turn byte budget,
+ * and fires `memory.after_recall`. Kept out of Agent.run so the turn entrypoint
+ * stays a thin lifecycle wrapper; the pure prompt-building (and conflict
+ * detection) stays in memory-recall-context.ts.
+ *
+ * Returns the system-message content to inject (already prefixed), or null when
+ * there is nothing to inject. Recall failures are swallowed — a recall miss must
+ * never block the turn. The caller decides WHERE to splice the message; this
+ * module only decides WHAT (if anything) to inject.
+ */
+import type { AgentLogger, HookRegistry } from "./types.js";
+export interface RecallMemoriesDeps {
+    hooks: HookRegistry;
+    /** P6: maps the query to category recall preferences (runtime port). */
+    detectRecallCategories: (query: string) => {
+        preferred: string[];
+        deprioritized: string[];
+    };
+    log: AgentLogger;
+    sessionId: string;
+    turnId: string;
+    /** Last user message (already truncated by the caller). */
+    query: string;
+}
+/**
+ * Recall long-term memories for this turn and build the system-message content
+ * to inject. Always fires `memory.after_recall` (with the pre-cap count) when the
+ * recall hook runs. Returns null when there is nothing worth injecting.
+ */
+export declare function recallMemoriesForTurn(deps: RecallMemoriesDeps): Promise<string | null>;

package/dist/agent/memory-recall-injection.js

@@ -0,0 +1,66 @@
+/**
+ * Turn-time QMemory recall orchestration (hippocampus bridge).
+ *
+ * Impure counterpart to the pure memory-recall-context.ts: it drives the
+ * `memory.before_recall` hook, caps the recalled set by a per-turn byte budget,
+ * and fires `memory.after_recall`. Kept out of Agent.run so the turn entrypoint
+ * stays a thin lifecycle wrapper; the pure prompt-building (and conflict
+ * detection) stays in memory-recall-context.ts.
+ *
+ * Returns the system-message content to inject (already prefixed), or null when
+ * there is nothing to inject. Recall failures are swallowed — a recall miss must
+ * never block the turn. The caller decides WHERE to splice the message; this
+ * module only decides WHAT (if anything) to inject.
+ */
+import { fireHook } from "../contracts/fire-hook.js";
+import { buildRecalledMemorySystemContent } from "./memory-recall-context.js";
+/** Per-turn injection cap: max bytes of recalled memory text. Prevents context
+ * flooding on early turns when the session budget is already full. */
+const PER_TURN_RECALL_MAX_BYTES = 8192;
+/**
+ * Recall long-term memories for this turn and build the system-message content
+ * to inject. Always fires `memory.after_recall` (with the pre-cap count) when the
+ * recall hook runs. Returns null when there is nothing worth injecting.
+ */
+export async function recallMemoriesForTurn(deps) {
+    const { hooks, detectRecallCategories, log, sessionId, turnId, query } = deps;
+    try {
+        // P6: detect query scenario → category preferences for recall filtering.
+        const categoryHint = detectRecallCategories(query);
+        const recallResult = await hooks.invoke("memory.before_recall", {
+            sessionId,
+            turnId,
+            query,
+            preferredCategories: categoryHint.preferred.length > 0 ? categoryHint.preferred : undefined,
+            deprioritizedCategories: categoryHint.deprioritized.length > 0 ? categoryHint.deprioritized : undefined,
+        });
+        const memories = recallResult?.context?.recalledMemories;
+        let systemContent = null;
+        if (memories && memories.length > 0) {
+            let usedBytes = 0;
+            const capped = [];
+            for (const m of memories) {
+                const entryBytes = (m.text?.length ?? 0) * 2;
+                if (usedBytes + entryBytes > PER_TURN_RECALL_MAX_BYTES)
+                    break;
+                capped.push(m);
+                usedBytes += entryBytes;
+            }
+            if (capped.length > 0) {
+                const memoryBlock = buildRecalledMemorySystemContent(capped);
+                systemContent = `[Recalled memories — context priority: project-specific facts override general user preferences when they conflict]\n${memoryBlock}`;
+            }
+        }
+        // Notify after_recall with the pre-cap count (matches prior behavior).
+        fireHook(hooks, "memory.after_recall", {
+            sessionId,
+            turnId,
+            blockCount: memories?.length ?? 0,
+        }, log);
+        return systemContent;
+    }
+    catch {
+        // Non-fatal: recall failure should not block the turn.
+        return null;
+    }
+}

package/dist/agent/runtime-vars.d.ts

@@ -0,0 +1,48 @@
+/**
+ * RuntimeVars — Unified mutable runtime variables for the agent server.
+ *
+ * All tunable/configurable runtime state that can be changed via RPC
+ * (config.updateTunable) or internal logic should live here. This avoids
+ * scattering mutable state as private fields across stdio-server.ts.
+ *
+ * Categories:
+ *   1. Budget — aggregate token usage tracking and limits
+ *   2. Dream  — idle dream scheduling parameters
+ *
+ * Usage:
+ *   import { runtimeVars } from "../agent/runtime-vars.js";
+ *   runtimeVars.teamTokensUsed += tokens;
+ *   if (runtimeVars.isTeamBudgetExceeded()) { ... }
+ */
+export interface TeamBudgetState {
+    /** Total tokens consumed by all forked sub-agents (accumulated). */
+    tokensUsed: number;
+    /** Maximum total tokens allowed across all forks. 0 = unlimited. */
+    budgetTokens: number;
+}
+export interface DreamState {
+    /** Idle threshold before triggering dream (minutes). */
+    idleMinutes: number;
+    /** Whether idle dream is enabled. */
+    enabled: boolean;
+    /** Last dream timestamp (ms since epoch). */
+    lastDreamAt: number;
+    /** Cooldown between dreams (ms). */
+    cooldownMs: number;
+    /** Max duration for a single dream run (ms). */
+    maxDurationMs: number;
+}
+export declare class RuntimeVars {
+    readonly teamBudget: TeamBudgetState;
+    /** Check if team aggregate budget is exceeded. */
+    isTeamBudgetExceeded(): boolean;
+    /** Record token consumption from a fork and return updated total. */
+    recordForkTokens(tokens: number): number;
+    /** Format budget-exceeded error message. */
+    teamBudgetExceededError(): string;
+    readonly dream: DreamState;
+    /** Reset all accumulated state (e.g. on session end). */
+    resetAccumulators(): void;
+}
+/** Singleton instance — shared across the server lifetime. */
+export declare const runtimeVars: RuntimeVars;

package/dist/agent/runtime-vars.js

@@ -0,0 +1,54 @@
+/**
+ * RuntimeVars — Unified mutable runtime variables for the agent server.
+ *
+ * All tunable/configurable runtime state that can be changed via RPC
+ * (config.updateTunable) or internal logic should live here. This avoids
+ * scattering mutable state as private fields across stdio-server.ts.
+ *
+ * Categories:
+ *   1. Budget — aggregate token usage tracking and limits
+ *   2. Dream  — idle dream scheduling parameters
+ *
+ * Usage:
+ *   import { runtimeVars } from "../agent/runtime-vars.js";
+ *   runtimeVars.teamTokensUsed += tokens;
+ *   if (runtimeVars.isTeamBudgetExceeded()) { ... }
+ */
+import { TEAM_BUDGET_TOKENS } from "./tunable-defaults.js";
+// ── RuntimeVars Class ───────────────────────────────────────
+export class RuntimeVars {
+    // ── Team Budget ─────────────────────────────────────────
+    teamBudget = {
+        tokensUsed: 0,
+        budgetTokens: TEAM_BUDGET_TOKENS,
+    };
+    /** Check if team aggregate budget is exceeded. */
+    isTeamBudgetExceeded() {
+        return (this.teamBudget.budgetTokens > 0 &&
+            this.teamBudget.tokensUsed >= this.teamBudget.budgetTokens);
+    }
+    /** Record token consumption from a fork and return updated total. */
+    recordForkTokens(tokens) {
+        this.teamBudget.tokensUsed += tokens;
+        return this.teamBudget.tokensUsed;
+    }
+    /** Format budget-exceeded error message. */
+    teamBudgetExceededError() {
+        return `Team budget exceeded (${this.teamBudget.tokensUsed} / ${this.teamBudget.budgetTokens} tokens). No more sub-agents allowed.`;
+    }
+    // ── Dream ───────────────────────────────────────────────
+    dream = {
+        idleMinutes: 30,
+        enabled: false,
+        lastDreamAt: 0,
+        cooldownMs: 4 * 60 * 60 * 1000,
+        maxDurationMs: 5 * 60 * 1000,
+    };
+    // ── Reset ───────────────────────────────────────────────
+    /** Reset all accumulated state (e.g. on session end). */
+    resetAccumulators() {
+        this.teamBudget.tokensUsed = 0;
+    }
+}
+/** Singleton instance — shared across the server lifetime. */
+export const runtimeVars = new RuntimeVars();

package/dist/agent/tool-access.d.ts

@@ -0,0 +1 @@
+export * from "../skills/tool-access.js";

package/dist/agent/tool-access.js

@@ -0,0 +1 @@
+export * from "../skills/tool-access.js";