instar 0.28.102 → 0.28.103

package/dist/core/PreCompactionFlush.js

@@ -0,0 +1,282 @@
+/**
+ * PreCompactionFlush — Save important context to MEMORY.md *before* Claude Code
+ * compaction collapses working memory.
+ *
+ * Architecture (Option A — server-side, agent-noninterruptive):
+ *   1. Claude Code emits PreCompact hook → instar's hook-event-reporter POSTs
+ *      to /hooks/events → HookEventReceiver emits 'PreCompact' event.
+ *   2. This class listens on that event. On each fire, it:
+ *      a. Locates the agent's transcript jsonl using Claude Code's standard
+ *         path convention: ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl
+ *      b. Reads the last N chars of the transcript (default 30KB) — bounded
+ *         to keep the LLM call cheap.
+ *      c. Sends a fact-extraction prompt to the shared intelligence provider
+ *         (subscription path, no per-call cost on default config).
+ *      d. Parses the response. Acceptable shapes: JSON array, JSON object
+ *         with `facts` array, or markdown bullet list. Any valid fact has
+ *         `slug` (kebab-case, ≤48 chars) and `body` (≤500 chars).
+ *      e. For each parsed fact, writes a new file under
+ *         `<projectDir>/.instar/memory/learning_<ts>_<slug>.md` with the
+ *         standard memory frontmatter (type=learning).
+ *      f. Appends a one-line index entry to `<projectDir>/.instar/MEMORY.md`
+ *         if a "## Learnings" or similar section exists (best-effort).
+ *      g. Writes a structured audit entry to
+ *         `<projectDir>/.instar/audit/pre-compaction-flush.jsonl`.
+ *
+ * Safety properties:
+ *   - Default `enabled: false` — flush is opt-in. The behavior change is
+ *     additive and the audit log surfaces every fire, so operators can
+ *     observe before enabling.
+ *   - `maxFactsPerFlush` (default 5) caps the blast radius if the LLM
+ *     hallucinates a long list.
+ *   - All writes are best-effort: any single failure (transcript missing,
+ *     LLM error, file write race) is audited and returns; never throws.
+ *   - Calls run async/detached from the hook caller. The hook itself
+ *     returns immediately so compaction is never delayed.
+ *
+ * Spec: docs/specs/OPENCLAW-IMPORT-PRE-COMPACTION-FLUSH-SPEC.md
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+export const DEFAULT_PRE_COMPACTION_FLUSH_CONFIG = {
+    enabled: false,
+    maxFactsPerFlush: 5,
+    transcriptCharBudget: 30_000,
+};
+export class PreCompactionFlush {
+    deps;
+    config;
+    constructor(deps, config) {
+        this.deps = deps;
+        this.config = config;
+    }
+    /**
+     * Handle a PreCompact event. Fire-and-forget; never throws to the caller.
+     * Returns the audit entry it wrote (for tests).
+     */
+    async handle(payload) {
+        const startedAt = (this.deps.now?.() ?? new Date()).getTime();
+        const flushId = `flush_${crypto.randomBytes(6).toString('hex')}`;
+        const sessionId = payload.session_id ?? '';
+        const trigger = payload.trigger;
+        const audit = (outcome, extra) => {
+            const entry = {
+                flushId,
+                sessionId,
+                trigger,
+                at: (this.deps.now?.() ?? new Date()).toISOString(),
+                outcome,
+                durationMs: (this.deps.now?.() ?? new Date()).getTime() - startedAt,
+                ...extra,
+            };
+            this.writeAudit(entry);
+            return entry;
+        };
+        if (!this.config.enabled)
+            return audit('disabled');
+        if (!this.deps.intelligence)
+            return audit('no-intelligence');
+        if (!sessionId)
+            return audit('no-session-id');
+        const transcriptPath = this.resolveTranscriptPath(payload);
+        const transcriptTail = this.readTranscriptTail(transcriptPath);
+        if (!transcriptTail)
+            return audit('no-transcript', { reason: `path: ${transcriptPath}` });
+        let llmResponse;
+        try {
+            llmResponse = await this.deps.intelligence.evaluate(this.buildPrompt(transcriptTail), { maxTokens: 800, temperature: 0 });
+        }
+        catch (err) {
+            return audit('provider-error', { reason: String(err).slice(0, 200) });
+        }
+        const facts = this.parseFacts(llmResponse).slice(0, this.config.maxFactsPerFlush);
+        if (facts.length === 0) {
+            // Distinguish "LLM returned NONE / empty list" from "couldn't parse".
+            if (/^\s*NONE\s*$/i.test(llmResponse) || /^\s*\[\s*\]\s*$/.test(llmResponse)) {
+                return audit('no-facts');
+            }
+            return audit('parse-failure', { reason: llmResponse.slice(0, 200) });
+        }
+        let written = 0;
+        try {
+            for (const fact of facts) {
+                if (this.writeFact(flushId, fact))
+                    written++;
+            }
+            this.appendMemoryIndex(facts, flushId);
+        }
+        catch (err) {
+            return audit('write-error', { reason: String(err).slice(0, 200), factsWritten: written });
+        }
+        return audit('ok', { factsWritten: written });
+    }
+    /** Build the flush prompt. Exported as a member for test inspection. */
+    buildPrompt(transcriptTail) {
+        return [
+            'You are an instar agent about to undergo context compaction. Recent conversation will be',
+            'collapsed into a generic summary. Identify 0-5 DURABLE facts from the recent conversation',
+            'that should survive compaction by being written to MEMORY.md as learnings.',
+            '',
+            'A durable fact is:',
+            '  - specific (not "we talked about X")',
+            '  - actionable for a future session ("X is at path Y", "approach Z works for case W")',
+            '  - not already in your code or git history (those are recoverable from disk)',
+            '  - not ephemeral state ("I am about to commit", "I am waiting for CI")',
+            '',
+            'Respond with a JSON array of objects, each with:',
+            '  - "slug": kebab-case, max 48 chars, identifies the fact uniquely',
+            '  - "body": 1-3 sentences, max 500 chars',
+            '',
+            'If nothing durable surfaces, respond with the literal token: NONE',
+            '',
+            'Recent conversation (tail):',
+            '---',
+            transcriptTail,
+            '---',
+            '',
+            'Respond with the JSON array or NONE. No other text.',
+        ].join('\n');
+    }
+    /** Parse the LLM response into facts. Accepts JSON array, JSON object with `facts`, or markdown. */
+    parseFacts(response) {
+        const trimmed = response.trim();
+        if (/^\s*NONE\s*$/i.test(trimmed))
+            return [];
+        // Try fenced JSON first.
+        const fenceMatch = trimmed.match(/```(?:json)?\s*([\s\S]+?)\s*```/);
+        const candidate = fenceMatch ? fenceMatch[1] : trimmed;
+        try {
+            const parsed = JSON.parse(candidate);
+            const arr = Array.isArray(parsed)
+                ? parsed
+                : (parsed && typeof parsed === 'object' && Array.isArray(parsed.facts)
+                    ? parsed.facts
+                    : null);
+            if (!arr)
+                return [];
+            const facts = [];
+            for (const item of arr) {
+                const fact = this.coerceFact(item);
+                if (fact)
+                    facts.push(fact);
+            }
+            return facts;
+        }
+        catch {
+            return [];
+        }
+    }
+    coerceFact(item) {
+        if (!item || typeof item !== 'object')
+            return null;
+        const obj = item;
+        const rawSlug = typeof obj.slug === 'string' ? obj.slug : null;
+        const rawBody = typeof obj.body === 'string' ? obj.body : null;
+        if (!rawSlug || !rawBody)
+            return null;
+        const slug = rawSlug
+            .toLowerCase()
+            .replace(/[^a-z0-9-]+/g, '-')
+            .replace(/^-+|-+$/g, '')
+            .slice(0, 48);
+        if (!slug)
+            return null;
+        const body = rawBody.trim().slice(0, 500);
+        if (!body)
+            return null;
+        return { slug, body };
+    }
+    resolveTranscriptPath(payload) {
+        if (payload.transcript_path)
+            return payload.transcript_path;
+        if (!payload.session_id)
+            return '';
+        const root = this.deps.claudeProjectsRoot ?? path.join(os.homedir(), '.claude', 'projects');
+        const encoded = this.deps.projectDir.replace(/[\/.]/g, '-');
+        return path.join(root, encoded, `${payload.session_id}.jsonl`);
+    }
+    readTranscriptTail(transcriptPath) {
+        if (!transcriptPath || !fs.existsSync(transcriptPath))
+            return null;
+        try {
+            const stat = fs.statSync(transcriptPath);
+            const budget = this.config.transcriptCharBudget;
+            if (stat.size <= budget) {
+                return fs.readFileSync(transcriptPath, 'utf8');
+            }
+            const fd = fs.openSync(transcriptPath, 'r');
+            const buf = Buffer.alloc(budget);
+            fs.readSync(fd, buf, 0, budget, stat.size - budget);
+            fs.closeSync(fd);
+            // Drop leading partial line so we start on a complete event boundary.
+            const text = buf.toString('utf8');
+            const firstNl = text.indexOf('\n');
+            return firstNl >= 0 ? text.slice(firstNl + 1) : text;
+        }
+        catch {
+            return null;
+        }
+    }
+    writeFact(flushId, fact) {
+        try {
+            const ts = (this.deps.now?.() ?? new Date()).toISOString().replace(/[:.]/g, '-');
+            const memoryDir = path.join(this.deps.projectDir, '.instar', 'memory');
+            fs.mkdirSync(memoryDir, { recursive: true });
+            const file = path.join(memoryDir, `learning_precompact_${ts}_${fact.slug}.md`);
+            const body = [
+                '---',
+                `name: precompact-${fact.slug}`,
+                `description: ${fact.body.split('\n')[0].slice(0, 120)}`,
+                'metadata:',
+                '  type: learning',
+                `  source: pre-compaction-flush`,
+                `  flushId: ${flushId}`,
+                '---',
+                '',
+                fact.body,
+                '',
+            ].join('\n');
+            fs.writeFileSync(file, body);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    appendMemoryIndex(facts, flushId) {
+        try {
+            const indexPath = path.join(this.deps.projectDir, '.instar', 'MEMORY.md');
+            if (!fs.existsSync(indexPath))
+                return;
+            const existing = fs.readFileSync(indexPath, 'utf8');
+            const newLines = facts.map((f) => `- [precompact: ${f.slug}](memory/learning_precompact_*_${f.slug}.md) — ${f.body.split('\n')[0].slice(0, 120)} (flush ${flushId})`);
+            // Append under a "## Pre-Compaction Saves" section, creating it if missing.
+            const SECTION = '## Pre-Compaction Saves';
+            let updated;
+            if (existing.includes(SECTION)) {
+                updated = existing.replace(new RegExp(`(${SECTION}[^\n]*\n)`), (m) => `${m}${newLines.join('\n')}\n`);
+            }
+            else {
+                updated = existing.trimEnd() + `\n\n${SECTION}\n\n${newLines.join('\n')}\n`;
+            }
+            fs.writeFileSync(indexPath, updated);
+        }
+        catch {
+            // Best effort.
+        }
+    }
+    writeAudit(entry) {
+        try {
+            const auditDir = path.join(this.deps.projectDir, '.instar', 'audit');
+            fs.mkdirSync(auditDir, { recursive: true });
+            const auditPath = path.join(auditDir, 'pre-compaction-flush.jsonl');
+            fs.appendFileSync(auditPath, JSON.stringify(entry) + '\n');
+        }
+        catch {
+            // Audit must never throw.
+        }
+    }
+}
+//# sourceMappingURL=PreCompactionFlush.js.map

package/dist/core/PreCompactionFlush.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PreCompactionFlush.js","sourceRoot":"","sources":["../../src/core/PreCompactionFlush.ts"],"names":[],"mappings":"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"}

package/dist/core/PromptBuildRecall.d.ts

@@ -0,0 +1,97 @@
+/**
+ * PromptBuildRecall — bounded pre-reply memory recall, imported from OpenClaw's
+ * `before_prompt_build` hook pattern.
+ *
+ * OpenClaw's active-memory plugin runs a recall pass before every eligible
+ * prompt and injects the result as a system-prompt prefix. The shape Instar
+ * adopts here:
+ *
+ *   1. A typed primitive (`PromptBuildRecall.recall()`) that takes the user's
+ *      message + a session id, returns a context-text string to inject.
+ *   2. Bounded blast radius: result is capped at `maxRecallChars` (default
+ *      1200), pulls at most `maxRecallResults` entries (default 5).
+ *   3. Per-call timeout (default 2000 ms — the recall runs synchronously inside
+ *      a Claude Code UserPromptSubmit hook, so it must be fast).
+ *   4. Cache: identical (user-message, agent) pairs dedupe with a `cacheTtlMs`
+ *      window (default 15 s). Repeated rapid prompts don't re-search.
+ *   5. Circuit breaker: after `circuitBreakerMaxFailures` consecutive errors
+ *      (default 3) the breaker opens for `circuitBreakerCooldownMs` (default
+ *      60 s) and recall short-circuits to empty.
+ *   6. Tool allowlist: the OpenClaw pattern restricts the recall sub-agent to
+ *      `[memory_recall, memory_search, memory_get]`. Here there's no
+ *      sub-agent — recall calls `SemanticMemory.search` directly. Implicit
+ *      allowlist: read-only memory queries, never anything else.
+ *
+ * Spec: docs/specs/OPENCLAW-IMPORT-BEFORE-PROMPT-BUILD-SPEC.md.
+ */
+import type { SemanticMemory } from '../memory/SemanticMemory.js';
+export interface PromptBuildRecallConfig {
+    enabled: boolean;
+    /** Hard cap on the size of the injected context block. Default 1200. */
+    maxRecallChars: number;
+    /** Hard cap on the number of memory entries pulled. Default 5. */
+    maxRecallResults: number;
+    /** TTL for the in-process recall cache. Default 15 000 ms. */
+    cacheTtlMs: number;
+    /** Consecutive failures before the circuit opens. Default 3. */
+    circuitBreakerMaxFailures: number;
+    /** Cooldown after the circuit opens. Default 60 000 ms. */
+    circuitBreakerCooldownMs: number;
+    /** Per-call timeout in ms. Default 2 000 ms. Recall is on the hot path. */
+    recallTimeoutMs: number;
+    /** Minimum confidence filter passed to SemanticMemory.search. Default 0.5. */
+    minConfidence: number;
+}
+export declare const DEFAULT_PROMPT_BUILD_RECALL_CONFIG: PromptBuildRecallConfig;
+export interface PromptBuildRecallDeps {
+    semanticMemory: SemanticMemory | null;
+    now?: () => number;
+}
+export type PromptBuildRecallSource = 'fresh' | 'cached' | 'disabled' | 'no-memory' | 'circuit-open' | 'timeout' | 'empty' | 'error';
+export interface PromptBuildRecallResult {
+    contextText: string;
+    source: PromptBuildRecallSource;
+    elapsedMs: number;
+    resultsCount: number;
+    cacheKey: string;
+}
+interface CircuitState {
+    consecutiveFailures: number;
+    openUntil: number;
+}
+export declare class PromptBuildRecall {
+    private readonly deps;
+    private readonly config;
+    private readonly cache;
+    private circuit;
+    constructor(deps: PromptBuildRecallDeps, config: PromptBuildRecallConfig);
+    /**
+     * Run a recall pass for a user message. Returns the context-text to inject
+     * into the system prompt (or empty string if nothing useful surfaces).
+     *
+     * Synchronous because the caller (UserPromptSubmit hook) blocks on the
+     * response. The recall path itself uses sqlite-backed SemanticMemory which
+     * is fast and synchronous; the only "async" guard is the timeout, which is
+     * enforced by checking elapsed time after the search.
+     */
+    recall(opts: {
+        userMessage: string;
+        sessionId?: string;
+    }): PromptBuildRecallResult;
+    /**
+     * Format the recall context block. Capped at `maxRecallChars`. Each entry
+     * gets a single line: "- <name>: <description-first-line>". Entries are
+     * dropped (not truncated) if adding them would exceed the cap.
+     */
+    private formatContextBlock;
+    private makeCacheKey;
+    private now;
+    /** Test hook: inspect the cache without exporting Map. */
+    getCacheSize(): number;
+    /** Test hook: inspect the circuit. */
+    getCircuitState(): Readonly<CircuitState>;
+    /** Test hook: clear cache and circuit. */
+    reset(): void;
+}
+export {};
+//# sourceMappingURL=PromptBuildRecall.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PromptBuildRecall.d.ts","sourceRoot":"","sources":["../../src/core/PromptBuildRecall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,gBAAgB,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,yBAAyB,EAAE,MAAM,CAAC;IAClC,2DAA2D;IAC3D,wBAAwB,EAAE,MAAM,CAAC;IACjC,2EAA2E;IAC3E,eAAe,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,kCAAkC,EAAE,uBAShD,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,uBAAuB,GAC/B,OAAO,GACP,QAAQ,GACR,UAAU,GACV,WAAW,GACX,cAAc,GACd,SAAS,GACT,OAAO,GACP,OAAO,CAAC;AAEZ,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,uBAAuB,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAOD,UAAU,YAAY;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,OAAO,CAA0D;gBAE7D,IAAI,EAAE,qBAAqB,EAAE,MAAM,EAAE,uBAAuB;IAKxE;;;;;;;;OAQG;IACH,MAAM,CAAC,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,uBAAuB;IA8DlF;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAkB1B,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,GAAG;IAIX,0DAA0D;IAC1D,YAAY,IAAI,MAAM;IAItB,sCAAsC;IACtC,eAAe,IAAI,QAAQ,CAAC,YAAY,CAAC;IAIzC,0CAA0C;IAC1C,KAAK,IAAI,IAAI;CAId"}

package/dist/core/PromptBuildRecall.js

@@ -0,0 +1,152 @@
+/**
+ * PromptBuildRecall — bounded pre-reply memory recall, imported from OpenClaw's
+ * `before_prompt_build` hook pattern.
+ *
+ * OpenClaw's active-memory plugin runs a recall pass before every eligible
+ * prompt and injects the result as a system-prompt prefix. The shape Instar
+ * adopts here:
+ *
+ *   1. A typed primitive (`PromptBuildRecall.recall()`) that takes the user's
+ *      message + a session id, returns a context-text string to inject.
+ *   2. Bounded blast radius: result is capped at `maxRecallChars` (default
+ *      1200), pulls at most `maxRecallResults` entries (default 5).
+ *   3. Per-call timeout (default 2000 ms — the recall runs synchronously inside
+ *      a Claude Code UserPromptSubmit hook, so it must be fast).
+ *   4. Cache: identical (user-message, agent) pairs dedupe with a `cacheTtlMs`
+ *      window (default 15 s). Repeated rapid prompts don't re-search.
+ *   5. Circuit breaker: after `circuitBreakerMaxFailures` consecutive errors
+ *      (default 3) the breaker opens for `circuitBreakerCooldownMs` (default
+ *      60 s) and recall short-circuits to empty.
+ *   6. Tool allowlist: the OpenClaw pattern restricts the recall sub-agent to
+ *      `[memory_recall, memory_search, memory_get]`. Here there's no
+ *      sub-agent — recall calls `SemanticMemory.search` directly. Implicit
+ *      allowlist: read-only memory queries, never anything else.
+ *
+ * Spec: docs/specs/OPENCLAW-IMPORT-BEFORE-PROMPT-BUILD-SPEC.md.
+ */
+import crypto from 'node:crypto';
+export const DEFAULT_PROMPT_BUILD_RECALL_CONFIG = {
+    enabled: false,
+    maxRecallChars: 1200,
+    maxRecallResults: 5,
+    cacheTtlMs: 15_000,
+    circuitBreakerMaxFailures: 3,
+    circuitBreakerCooldownMs: 60_000,
+    recallTimeoutMs: 2_000,
+    minConfidence: 0.5,
+};
+export class PromptBuildRecall {
+    deps;
+    config;
+    cache = new Map();
+    circuit = { consecutiveFailures: 0, openUntil: 0 };
+    constructor(deps, config) {
+        this.deps = deps;
+        this.config = config;
+    }
+    /**
+     * Run a recall pass for a user message. Returns the context-text to inject
+     * into the system prompt (or empty string if nothing useful surfaces).
+     *
+     * Synchronous because the caller (UserPromptSubmit hook) blocks on the
+     * response. The recall path itself uses sqlite-backed SemanticMemory which
+     * is fast and synchronous; the only "async" guard is the timeout, which is
+     * enforced by checking elapsed time after the search.
+     */
+    recall(opts) {
+        const start = this.now();
+        const cacheKey = this.makeCacheKey(opts);
+        if (!this.config.enabled) {
+            return { contextText: '', source: 'disabled', elapsedMs: 0, resultsCount: 0, cacheKey };
+        }
+        // Cache hit?
+        const cached = this.cache.get(cacheKey);
+        if (cached && cached.expiresAt > start) {
+            return { ...cached.value, source: 'cached', elapsedMs: this.now() - start };
+        }
+        // Circuit breaker open?
+        if (this.circuit.openUntil > start) {
+            return { contextText: '', source: 'circuit-open', elapsedMs: 0, resultsCount: 0, cacheKey };
+        }
+        if (!this.deps.semanticMemory) {
+            return { contextText: '', source: 'no-memory', elapsedMs: 0, resultsCount: 0, cacheKey };
+        }
+        let entries = [];
+        try {
+            const raw = this.deps.semanticMemory.search(opts.userMessage, {
+                limit: this.config.maxRecallResults,
+                minConfidence: this.config.minConfidence,
+            });
+            entries = raw;
+            this.circuit.consecutiveFailures = 0;
+        }
+        catch {
+            this.circuit.consecutiveFailures++;
+            if (this.circuit.consecutiveFailures >= this.config.circuitBreakerMaxFailures) {
+                this.circuit.openUntil = start + this.config.circuitBreakerCooldownMs;
+            }
+            return { contextText: '', source: 'error', elapsedMs: this.now() - start, resultsCount: 0, cacheKey };
+        }
+        const elapsed = this.now() - start;
+        if (elapsed > this.config.recallTimeoutMs) {
+            return { contextText: '', source: 'timeout', elapsedMs: elapsed, resultsCount: 0, cacheKey };
+        }
+        if (entries.length === 0) {
+            const result = { contextText: '', source: 'empty', elapsedMs: elapsed, resultsCount: 0, cacheKey };
+            this.cache.set(cacheKey, { value: result, expiresAt: start + this.config.cacheTtlMs });
+            return result;
+        }
+        const contextText = this.formatContextBlock(entries);
+        const result = {
+            contextText,
+            source: 'fresh',
+            elapsedMs: elapsed,
+            resultsCount: entries.length,
+            cacheKey,
+        };
+        this.cache.set(cacheKey, { value: result, expiresAt: start + this.config.cacheTtlMs });
+        return result;
+    }
+    /**
+     * Format the recall context block. Capped at `maxRecallChars`. Each entry
+     * gets a single line: "- <name>: <description-first-line>". Entries are
+     * dropped (not truncated) if adding them would exceed the cap.
+     */
+    formatContextBlock(entries) {
+        const header = '<active_memory_recall>';
+        const footer = '</active_memory_recall>';
+        const lines = [header];
+        let used = header.length + footer.length + 2; // \n boundaries
+        for (const entry of entries) {
+            const desc = (entry.description ?? '').split('\n')[0].trim();
+            const line = desc ? `- ${entry.name}: ${desc}` : `- ${entry.name}`;
+            if (used + line.length + 1 > this.config.maxRecallChars)
+                break;
+            lines.push(line);
+            used += line.length + 1;
+        }
+        lines.push(footer);
+        return lines.join('\n');
+    }
+    makeCacheKey(opts) {
+        const normalized = opts.userMessage.trim().toLowerCase().slice(0, 500);
+        return crypto.createHash('sha1').update(normalized).digest('hex').slice(0, 16);
+    }
+    now() {
+        return this.deps.now?.() ?? Date.now();
+    }
+    /** Test hook: inspect the cache without exporting Map. */
+    getCacheSize() {
+        return this.cache.size;
+    }
+    /** Test hook: inspect the circuit. */
+    getCircuitState() {
+        return { ...this.circuit };
+    }
+    /** Test hook: clear cache and circuit. */
+    reset() {
+        this.cache.clear();
+        this.circuit = { consecutiveFailures: 0, openUntil: 0 };
+    }
+}
+//# sourceMappingURL=PromptBuildRecall.js.map

package/dist/core/PromptBuildRecall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PromptBuildRecall.js","sourceRoot":"","sources":["../../src/core/PromptBuildRecall.ts"],"names":[],"mappings":"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"}

package/dist/core/selectIntelligenceProvider.d.ts

@@ -0,0 +1,41 @@
+/**
+ * selectIntelligenceProvider — choose the shared LLM provider with subscription-by-default
+ * safety guarantees.
+ *
+ * Rules:
+ *   1. Anthropic API mode requires BOTH `intelligenceProvider: "anthropic-api"` AND
+ *      `intelligenceProviderConfirmed: true` in config. Either one alone is rejected with
+ *      a visible warning, and selection falls through to Claude CLI.
+ *   2. With both flags set and an `ANTHROPIC_API_KEY` available, API mode engages and the
+ *      caller is expected to render a billing banner (signaled via `apiModeActive`).
+ *   3. If API mode is rejected (or never requested), Claude CLI is attempted next.
+ *   4. If neither succeeds, the result is `provider: null, source: 'none'`. The caller
+ *      degrades gracefully — there is NO silent fallback to the API even if an
+ *      `ANTHROPIC_API_KEY` is present in the environment. The presence of the env key
+ *      without explicit opt-in is reported via `apiKeyIgnored: true`.
+ *
+ * This is the single chokepoint where Instar's subscription-by-default principle is
+ * enforced. Every other LLM-gated feature shares the provider this function returns.
+ */
+import type { IntelligenceProvider } from './types.js';
+export interface IntelligenceSelectionInput {
+    intelligenceProvider?: string;
+    intelligenceProviderConfirmed?: boolean;
+    anthropicApiKey?: string | undefined;
+    claudePath?: string | undefined;
+    buildClaude: (claudePath: string) => IntelligenceProvider | null;
+    buildAnthropic: (apiKey: string) => IntelligenceProvider | null;
+}
+export type IntelligenceSource = 'anthropic-api-confirmed' | 'claude-cli' | 'none';
+export interface IntelligenceSelection {
+    provider: IntelligenceProvider | null;
+    source: IntelligenceSource;
+    /** Human-readable warnings the caller should surface via console + degradation log. */
+    warnings: string[];
+    /** True iff API mode is the active, confirmed selection (caller should render billing banner). */
+    apiModeActive: boolean;
+    /** True iff ANTHROPIC_API_KEY was present in env but NOT used due to subscription-by-default. */
+    apiKeyIgnored: boolean;
+}
+export declare function selectIntelligenceProvider(input: IntelligenceSelectionInput): IntelligenceSelection;
+//# sourceMappingURL=selectIntelligenceProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"selectIntelligenceProvider.d.ts","sourceRoot":"","sources":["../../src/core/selectIntelligenceProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,MAAM,WAAW,0BAA0B;IACzC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,WAAW,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,oBAAoB,GAAG,IAAI,CAAC;IACjE,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,oBAAoB,GAAG,IAAI,CAAC;CACjE;AAED,MAAM,MAAM,kBAAkB,GAC1B,yBAAyB,GACzB,YAAY,GACZ,MAAM,CAAC;AAEX,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACtC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,uFAAuF;IACvF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,kGAAkG;IAClG,aAAa,EAAE,OAAO,CAAC;IACvB,iGAAiG;IACjG,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,0BAA0B,GAAG,qBAAqB,CAsEnG"}