@caupulican/pi-adaptative 0.81.41 → 0.81.43

package/dist/core/reflection-controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reflection-controller.d.ts","sourceRoot":"","sources":["../../src/core/reflection-controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EACN,KAAK,KAAK,EAIV,KAAK,aAAa,EAClB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EACN,KAAK,GAAG,EAGR,KAAK,KAAK,EAEV,KAAK,mBAAmB,EAExB,KAAK,KAAK,EACV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAGN,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAkC,KAAK,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAC7G,OAAO,EAKN,KAAK,mBAAmB,EAGxB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACN,KAAK,aAAa,EAGlB,KAAK,gBAAgB,EAErB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAG7D,MAAM,WAAW,wBAAwB;IACxC,sFAAsF;IACtF,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IACnC,4EAA0E;IAC1E,QAAQ,IAAI,KAAK,CAAC;IAClB,oGAAoG;IACpG,iBAAiB,IAAI,OAAO,CAAC;IAC7B,6EAA6E;IAC7E,gBAAgB,IAAI,aAAa,CAAC;IAClC,2GAAyG;IACzG,gBAAgB,IAAI,aAAa,CAAC;IAClC,gGAA8F;IAC9F,kBAAkB,IAAI,eAAe,CAAC;IACtC,gFAA8E;IAC9E,iBAAiB,IAAI,cAAc,CAAC;IACpC,uFAAqF;IACrF,WAAW,IAAI,MAAM,CAAC;IACtB,wEAAsE;IACtE,cAAc,IAAI,OAAO,CAAC;IAC1B,gFAAgF;IAChF,UAAU,IAAI,OAAO,CAAC;IACtB,8FAA4F;IAC5F,mBAAmB,IAAI,WAAW,CAAC;IACnC,sEAAsE;IACtE,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5C,sFAAsF;IACtF,qBAAqB,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC3D,gGAAgG;IAChG,eAAe,CACd,KAAK,EAAE,KAAK,EACZ,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GACpE,MAAM,GAAG,SAAS,CAAC;IACtB,oEAAoE;IACpE,4BAA4B,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAAC;IACjE,4FAA4F;IAC5F,2BAA2B,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,mBAAmB,CAAC,sBAAsB,CAAC,CAAC;IAC5F,0FAA0F;IAC1F,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD;;;;;OAKG;IACH,MAAM,CAAC,IAAI,MAAM,CAAC;CAClB;AAID,eAAO,MAAM,uCAAuC,yCAAyC,CAAC;AAG9F,eAAO,MAAM,mCAAmC,4BAA4B,CAAC;AAE7E,qBAAa,oBAAoB;IAChC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA2B;IAEhD,YAAY,IAAI,EAAE,wBAAwB,EAEzC;IAED;;;;;;;;;;;;;OAaG;IACG,qBAAqB,CAAC,IAAI,EAAE,yBAAyB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAgM9F;IAED;;;;;;;;OAQG;IACG,iBAAiB,CAAC,KAAK,EAAE;QAC9B,OAAO,EAAE,aAAa,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,KAAK,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QACnB,aAAa,CAAC,EAAE,aAAa,CAAC;QAC9B,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,8FAA8F;QAC9F,QAAQ,CAAC,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CA0KnC;IAED,uBAAuB,IAAI,mBAAmB,EAAE,CAE/C;IAED;;;;;OAKG;IACG,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAmErF;YASa,qBAAqB;IA2DnC;;;;;;;;;OASG;IACH,OAAO,CAAC,2BAA2B;IA8BnC;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;CAwB/B","sourcesContent":["/**\n * Native reflection + learning-write controller.\n *\n * Extracted verbatim from agent-session.ts (god-file decomposition). Owns the end-of-loop reflection\n * pass (R2), the isolated-completion primitive it runs on, and the learning-apply/rollback path that\n * turns reflection writes into gated, audited durable memory/skill changes. It mutates NO session\n * fields — every durable effect goes through the bundled memory tool, the session log (via deps), or\n * the skills dir; the whole pass is best-effort and never throws into the turn loop. Reads live\n * session state (model/agent/registry/memory/settings) through narrow deps accessors rather than the\n * whole AgentSession.\n */\n\nimport { existsSync, mkdirSync, writeFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport {\n\ttype Agent,\n\ttype AgentContext,\n\ttype AgentLoopConfig,\n\trunAgentLoop,\n\ttype ThinkingLevel,\n} from \"@caupulican/pi-agent-core\";\nimport type { SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport {\n\ttype Api,\n\ttype AssistantMessage,\n\ttype Context,\n\ttype Model,\n\tresolveModelThinkingLevel,\n\ttype SimpleStreamOptions,\n\ttype TextContent,\n\ttype Usage,\n} from \"@caupulican/pi-ai\";\nimport {\n\tcomputeLaneAffinityKey,\n\tDEFAULT_ISOLATED_LANE_KIND,\n\ttype IsolatedCompletionOptions,\n\ttype IsolatedCompletionResult,\n} from \"./agent-session-contracts.ts\";\nimport type { LearningDecision } from \"./autonomy/contracts.ts\";\nimport { AUTONOMY_TELEMETRY_EVENT_TYPES, type AutonomyTelemetryEvent } from \"./autonomy/telemetry-events.ts\";\nimport {\n\tAPPLY_WRITE_REFUSED_REASON_CODE,\n\tappendLearningAuditSnapshot,\n\tcontradictionsForReflectionWrite,\n\tgetLearningAuditSnapshots,\n\ttype LearningAuditRecord,\n\tproposalFromReflectionWrite,\n\trollbackPlanForReflectionWrite,\n} from \"./learning/learning-audit.ts\";\nimport { evaluateLearningDecision } from \"./learning/learning-gate.ts\";\nimport { ObservationStore, observationKey } from \"./learning/observation-store.ts\";\nimport {\n\ttype DemandSignals,\n\tdecideDemand,\n\tReflectionEngine,\n\ttype ReflectionResult,\n\ttype ReflectionWrite,\n} from \"./learning/reflection-engine.ts\";\nimport type { MemoryManager } from \"./memory/memory-manager.ts\";\nimport type { ModelRegistry } from \"./model-registry.ts\";\nimport { registerInFlightWork } from \"./reload-blockers.ts\";\nimport type { SettingsManager } from \"./settings-manager.ts\";\nimport { runSkillAudit } from \"./tools/skill-audit.ts\";\n\nexport interface ReflectionControllerDeps {\n\t/** Current session model (fallback for an isolated call that omits its own model). */\n\tgetModel(): Model<Api> | undefined;\n\t/** The underlying agent — its `streamFn` runs the isolated completion. */\n\tgetAgent(): Agent;\n\t/** True when the session's stream fn is the raw `streamSimple` provider (auth must be injected). */\n\tisRawStreamSimple(): boolean;\n\t/** Model registry for API-key/header resolution on the raw-provider path. */\n\tgetModelRegistry(): ModelRegistry;\n\t/** Memory subsystem — the bundled `memory` tool applies durable writes; fresh block feeds reflection. */\n\tgetMemoryManager(): MemoryManager;\n\t/** Settings — the learning-apply policy (gate thresholds, auto-apply layers) is read here. */\n\tgetSettingsManager(): SettingsManager;\n\t/** Session log — audit snapshots and learning-audit reads go through this. */\n\tgetSessionManager(): SessionManager;\n\t/** Agent dir — reflection-promoted skills are written under `<agentDir>/skills/`. */\n\tgetAgentDir(): string;\n\t/** Child sessions must not learn — the pass returns null for them. */\n\tisChildSession(): boolean;\n\t/** Disposal short-circuits: no completion, no writes against a dead session. */\n\tisDisposed(): boolean;\n\t/** Session-lifetime abort signal — aborts an in-flight reflection completion on dispose. */\n\tgetReflectionSignal(): AbortSignal;\n\t/** Archive a promoted skill (rollback of a `promote_skill` write). */\n\tarchivePromotedSkill(name: string): boolean;\n\t/** G3/G8 autonomy telemetry sink for learning-gate outcomes and approval requests. */\n\temitAutonomyTelemetry(event: AutonomyTelemetryEvent): void;\n\t/** Account the reflection pass's token spend into the cost roll-up (idempotent on reportId). */\n\taddSpawnedUsage(\n\t\tusage: Usage,\n\t\topts?: { label?: string; sourceSessionId?: string; reportId?: string },\n\t): string | undefined;\n\t/** Persist a learning-gate decision snapshot to the session log. */\n\tsaveLearningDecisionSnapshot(decision: LearningDecision): string;\n\t/** Resolve text-tool fallback for the selected isolated model, not the foreground model. */\n\tresolveTextToolCallProtocol(model: Model<Api>): SimpleStreamOptions[\"textToolCallProtocol\"];\n\t/** Ensure a managed-local model is running/resident before any isolated lane calls it. */\n\tensureModelReady(model: Model<Api>): Promise<void>;\n\t/**\n\t * Session working directory — feeds the skill-overlap audit's project-local skill discovery, the\n\t * same `cwd` the model-invoked `skillify`/`skill_audit` tools already receive (tools/index.ts).\n\t * Optional so a host that has not wired it yet still resolves (falls back to `process.cwd()`,\n\t * mirroring the existing profile-resolution fallback in settings-manager.ts).\n\t */\n\tgetCwd?(): string;\n}\n\n// reasonCode when an automatic skill promotion is blocked by an overlap with an existing skill\n// (skill_audit's similarity threshold) and routed to a consolidation proposal instead of a blind write.\nexport const SKILL_OVERLAP_CONSOLIDATION_REASON_CODE = \"skill_overlap_consolidation_proposed\";\n// reasonCode when the overlap audit itself fails — the promotion is held (not written unaudited)\n// rather than silently skipping the check.\nexport const SKILL_AUDIT_UNAVAILABLE_REASON_CODE = \"skill_audit_unavailable\";\n\nexport class ReflectionController {\n\tprivate readonly deps: ReflectionControllerDeps;\n\n\tconstructor(deps: ReflectionControllerDeps) {\n\t\tthis.deps = deps;\n\t}\n\n\t/**\n\t * Run an LLM completion fully ISOLATED from the main session — the load-bearing primitive for\n\t * reflection and bounded child lanes (adaptive-agent design §6c/§7).\n\t *\n\t * Isolation invariants (audited by codex): builds fresh context (no main history), defaults to no\n\t * tools, and passes **no real `sessionId`** — only a deterministic SYNTHETIC cache-affinity key\n\t * (see {@link computeLaneAffinityKey}) derived from `(laneKind, model, systemPrompt)`, which can never\n\t * equal or embed the real session id. A tool-enabled call receives only caller-owned tools and hooks,\n\t * and is turn-bounded. It cannot mutate `agent.state.messages`, append session entries, or touch the\n\t * foreground tool registry. Mirrors `generateSummary()`'s one-shot mechanics otherwise.\n\t *\n\t * Returns the result even on an error/aborted stop reason (callers — e.g. a background reflection\n\t * microtask — decide whether to act); it does not throw on a model-level error.\n\t */\n\tasync runIsolatedCompletion(opts: IsolatedCompletionOptions): Promise<IsolatedCompletionResult> {\n\t\tconst model = opts.model ?? this.deps.getModel();\n\t\tif (!model) {\n\t\t\tthrow new Error(\"runIsolatedCompletion: no model available\");\n\t\t}\n\t\tawait this.deps.ensureModelReady(model);\n\t\tconst thinkingLevel = resolveModelThinkingLevel(model, opts.thinkingLevel, \"off\");\n\n\t\t// Registered for the full isolated-completion call (one-shot or child-loop) so the\n\t\t// reload gate waits it out — this is the SINGLE choke point every isolated completion in the\n\t\t// codebase runs through (reflection, research/worker/fitness lanes, context-pipeline curation,\n\t\t// model-router judge calls). registerInFlightWork is a pure sync map op (cannot throw), so\n\t\t// placing it as the last statement before `try` still guarantees the matching finally always\n\t\t// runs, on every return path below and on any thrown error.\n\t\tconst deregisterInFlight = registerInFlightWork(\n\t\t\tthis.deps.getAgentDir(),\n\t\t\t\"isolated-completion\",\n\t\t\topts.laneKind ?? DEFAULT_ISOLATED_LANE_KIND,\n\t\t);\n\t\ttry {\n\t\t\t// Fresh, isolated context: explicit messages, caller-owned tools only, nothing from the main session.\n\t\t\tconst context: Context = {\n\t\t\t\tsystemPrompt: opts.systemPrompt,\n\t\t\t\tmessages: opts.messages,\n\t\t\t\ttools: opts.tools ?? [],\n\t\t\t};\n\n\t\t\t// Isolate the prompt cache from the main session by DELIBERATELY never sending the real\n\t\t\t// sessionId. In its place, a deterministic SYNTHETIC affinity key lets providers with\n\t\t\t// session-affinity headers / prompt_cache_key route repeat calls from the SAME lane (same\n\t\t\t// laneKind+model+systemPrompt) to the same cache-warm backend, without entangling this call\n\t\t\t// with — or leaking any identity of — the main session.\n\t\t\tconst affinityKey = computeLaneAffinityKey(\n\t\t\t\topts.laneKind ?? DEFAULT_ISOLATED_LANE_KIND,\n\t\t\t\tmodel,\n\t\t\t\topts.systemPrompt,\n\t\t\t);\n\t\t\tconst options: SimpleStreamOptions = {\n\t\t\t\tmaxTokens: opts.maxTokens,\n\t\t\t\tsignal: opts.signal,\n\t\t\t\tinteractionMode: \"background\",\n\t\t\t\tcacheRetention: opts.cacheRetention,\n\t\t\t\treasoning: thinkingLevel,\n\t\t\t\tsessionId: affinityKey,\n\t\t\t};\n\n\t\t\t// When streamFn is the raw streamSimple (e.g. in tests), auth must be injected explicitly.\n\t\t\t// Throw only when auth genuinely fails — providers that authenticate without an API key\n\t\t\t// (OAuth, local no-key) legitimately return ok with an undefined apiKey.\n\t\t\tif (this.deps.isRawStreamSimple()) {\n\t\t\t\tconst auth = await this.deps.getModelRegistry().getApiKeyAndHeaders(model);\n\t\t\t\tif (!auth.ok) {\n\t\t\t\t\tthrow new Error(auth.error);\n\t\t\t\t}\n\t\t\t\toptions.apiKey = auth.apiKey;\n\t\t\t\toptions.headers = auth.headers;\n\t\t\t}\n\n\t\t\tif (opts.tools && opts.tools.length > 0) {\n\t\t\t\tconst agent = this.deps.getAgent();\n\t\t\t\tconst foregroundModel = agent.state.model;\n\t\t\t\tconst usesForegroundModel = foregroundModel?.provider === model.provider && foregroundModel.id === model.id;\n\t\t\t\tconst textToolCallProtocol = this.deps.resolveTextToolCallProtocol(model);\n\t\t\t\tconst requestedMaxTurns =\n\t\t\t\t\ttypeof opts.maxTurns === \"number\" && Number.isFinite(opts.maxTurns) ? Math.floor(opts.maxTurns) : 6;\n\t\t\t\tconst maxTurns = Math.max(1, Math.min(12, requestedMaxTurns));\n\t\t\t\tlet completedTurns = 0;\n\t\t\t\tconst childContext: AgentContext = {\n\t\t\t\t\tsystemPrompt: opts.systemPrompt,\n\t\t\t\t\tmessages: [],\n\t\t\t\t\ttools: [...opts.tools],\n\t\t\t\t};\n\t\t\t\tconst loopConfig: AgentLoopConfig = {\n\t\t\t\t\tmodel,\n\t\t\t\t\tinteractionMode: \"background\",\n\t\t\t\t\tmaxTokens: opts.maxTokens,\n\t\t\t\t\tcacheRetention: opts.cacheRetention,\n\t\t\t\t\treasoning: thinkingLevel,\n\t\t\t\t\t// Same synthetic per-lane affinity key as the one-shot path above — never the real sessionId.\n\t\t\t\t\tsessionId: affinityKey,\n\t\t\t\t\t...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),\n\t\t\t\t\t...(options.headers !== undefined ? { headers: options.headers } : {}),\n\t\t\t\t\ttemperature: textToolCallProtocol ? 0 : undefined,\n\t\t\t\t\ttextToolCallProtocol,\n\t\t\t\t\tonTextToolProtocolParse: usesForegroundModel ? agent.onTextToolProtocolParse : undefined,\n\t\t\t\t\ttransport: agent.transport,\n\t\t\t\t\tthinkingBudgets: agent.thinkingBudgets,\n\t\t\t\t\tmaxRetryDelayMs: agent.maxRetryDelayMs,\n\t\t\t\t\tmaxStallTurns: Math.max(2, Math.min(maxTurns, agent.maxStallTurns ?? maxTurns)),\n\t\t\t\t\tonRunawayStop: usesForegroundModel ? agent.onRunawayStop : undefined,\n\t\t\t\t\ttoolExecution: \"sequential\",\n\t\t\t\t\ttoolArgumentTeachEnabled: agent.toolArgumentTeachEnabled,\n\t\t\t\t\tonToolArgumentValidation: usesForegroundModel ? agent.onToolArgumentValidation : undefined,\n\t\t\t\t\ttoolValidationEscalationThreshold: agent.toolValidationEscalationThreshold,\n\t\t\t\t\tonToolValidationEscalation: usesForegroundModel ? agent.onToolValidationEscalation : undefined,\n\t\t\t\t\tbeforeToolCall: opts.beforeToolCall,\n\t\t\t\t\tafterToolCall: opts.afterToolCall,\n\t\t\t\t\tshouldStopAfterTurn: () => {\n\t\t\t\t\t\tcompletedTurns += 1;\n\t\t\t\t\t\treturn completedTurns >= maxTurns;\n\t\t\t\t\t},\n\t\t\t\t\tconvertToLlm: agent.convertToLlm,\n\t\t\t\t};\n\t\t\t\tconst messages = await runAgentLoop(\n\t\t\t\t\topts.messages,\n\t\t\t\t\tchildContext,\n\t\t\t\t\tloopConfig,\n\t\t\t\t\t() => {},\n\t\t\t\t\topts.signal,\n\t\t\t\t\tagent.streamFn,\n\t\t\t\t);\n\t\t\t\tconst assistantMessages = messages.filter(\n\t\t\t\t\t(message): message is AssistantMessage => message.role === \"assistant\",\n\t\t\t\t);\n\t\t\t\tlet finalAssistant = assistantMessages.at(-1);\n\t\t\t\tif (!finalAssistant) {\n\t\t\t\t\tthrow new Error(\"runIsolatedCompletion: child loop produced no assistant message\");\n\t\t\t\t}\n\n\t\t\t\tconst hasFinalText = finalAssistant.content.some(\n\t\t\t\t\t(content) => content.type === \"text\" && content.text.trim().length > 0,\n\t\t\t\t);\n\t\t\t\tconst endedOnToolCall = finalAssistant.content.some((content) => content.type === \"toolCall\");\n\t\t\t\tif (opts.finalTextPrompt && !hasFinalText && endedOnToolCall && !opts.signal?.aborted) {\n\t\t\t\t\t// A hard turn bound may stop immediately after successful tool execution. Preserve that bound,\n\t\t\t\t\t// then allow exactly one tool-free synthesis call so the gathered work is not thrown away.\n\t\t\t\t\tconst finalizationMessages = await agent.convertToLlm(messages);\n\t\t\t\t\tconst finalizationStream = await agent.streamFn(\n\t\t\t\t\t\tmodel,\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tsystemPrompt: opts.systemPrompt,\n\t\t\t\t\t\t\tmessages: [\n\t\t\t\t\t\t\t\t...finalizationMessages,\n\t\t\t\t\t\t\t\t{ role: \"user\", content: opts.finalTextPrompt, timestamp: Date.now() },\n\t\t\t\t\t\t\t],\n\t\t\t\t\t\t\ttools: [],\n\t\t\t\t\t\t},\n\t\t\t\t\t\toptions,\n\t\t\t\t\t);\n\t\t\t\t\tfinalAssistant = await finalizationStream.result();\n\t\t\t\t\tassistantMessages.push(finalAssistant);\n\t\t\t\t}\n\n\t\t\t\tconst usage = assistantMessages.reduce<Usage>(\n\t\t\t\t\t(total, message) => ({\n\t\t\t\t\t\tinput: total.input + message.usage.input,\n\t\t\t\t\t\toutput: total.output + message.usage.output,\n\t\t\t\t\t\tcacheRead: total.cacheRead + message.usage.cacheRead,\n\t\t\t\t\t\tcacheWrite: total.cacheWrite + message.usage.cacheWrite,\n\t\t\t\t\t\ttotalTokens: total.totalTokens + message.usage.totalTokens,\n\t\t\t\t\t\tcost: {\n\t\t\t\t\t\t\tinput: total.cost.input + message.usage.cost.input,\n\t\t\t\t\t\t\toutput: total.cost.output + message.usage.cost.output,\n\t\t\t\t\t\t\tcacheRead: total.cost.cacheRead + message.usage.cost.cacheRead,\n\t\t\t\t\t\t\tcacheWrite: total.cost.cacheWrite + message.usage.cost.cacheWrite,\n\t\t\t\t\t\t\ttotal: total.cost.total + message.usage.cost.total,\n\t\t\t\t\t\t},\n\t\t\t\t\t}),\n\t\t\t\t\t{\n\t\t\t\t\t\tinput: 0,\n\t\t\t\t\t\toutput: 0,\n\t\t\t\t\t\tcacheRead: 0,\n\t\t\t\t\t\tcacheWrite: 0,\n\t\t\t\t\t\ttotalTokens: 0,\n\t\t\t\t\t\tcost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },\n\t\t\t\t\t},\n\t\t\t\t);\n\t\t\t\tconst text = finalAssistant.content\n\t\t\t\t\t.filter((content): content is TextContent => content.type === \"text\")\n\t\t\t\t\t.map((content) => content.text)\n\t\t\t\t\t.join(\"\");\n\t\t\t\treturn { text, usage, stopReason: finalAssistant.stopReason };\n\t\t\t}\n\n\t\t\tconst stream = await this.deps.getAgent().streamFn(model, context, options);\n\t\t\tconst result = await stream.result();\n\t\t\tconst text = result.content\n\t\t\t\t.filter((c): c is TextContent => c.type === \"text\")\n\t\t\t\t.map((c) => c.text)\n\t\t\t\t.join(\"\");\n\t\t\tconst usage: Usage = result.usage ?? {\n\t\t\t\tinput: 0,\n\t\t\t\toutput: 0,\n\t\t\t\tcacheRead: 0,\n\t\t\t\tcacheWrite: 0,\n\t\t\t\ttotalTokens: 0,\n\t\t\t\tcost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },\n\t\t\t};\n\t\t\treturn { text, usage, stopReason: result.stopReason };\n\t\t} finally {\n\t\t\tderegisterInFlight();\n\t\t}\n\t}\n\n\t/**\n\t * Native end-of-loop reflection pass (R2). Demand-gates (zero-I/O), and when warranted runs the\n\t * {@link ReflectionEngine} via an isolated completion ({@link runIsolatedCompletion}), applies the\n\t * resulting memory writes through the bundled `memory` tool, and accounts the reflection's token\n\t * cost via the cost-aggregation surface so it stays visible and net-negative-auditable.\n\t *\n\t * Returns `null` when the gate skips (or in a child session, which must not learn). The whole pass\n\t * is best-effort: a model/parse error yields no writes, never throws into the caller.\n\t */\n\tasync runReflectionPass(input: {\n\t\tsignals: DemandSignals;\n\t\trecentTurnText: string;\n\t\tmodel?: Model<Api>;\n\t\tthinkingLevel?: ThinkingLevel;\n\t\tsignal?: AbortSignal;\n\t\t/** Stable id so a duplicate scheduling/retry of the same pass can't double-count its cost. */\n\t\treportId?: string;\n\t}): Promise<ReflectionResult | null> {\n\t\tif (this.deps.isChildSession() || this.deps.isDisposed()) return null;\n\t\tconst plan = decideDemand(input.signals);\n\t\tif (plan.act === \"skip\") return null;\n\n\t\t// Bug #21: tie this background pass to the session lifetime. Disposing the session aborts the\n\t\t// in-flight completion (input.signal can add a more specific abort).\n\t\tconst signal = input.signal\n\t\t\t? AbortSignal.any([input.signal, this.deps.getReflectionSignal()])\n\t\t\t: this.deps.getReflectionSignal();\n\n\t\tconst complete = (systemPrompt: string, userPrompt: string) =>\n\t\t\tthis.runIsolatedCompletion({\n\t\t\t\tsystemPrompt,\n\t\t\t\tmessages: [{ role: \"user\", content: [{ type: \"text\", text: userPrompt }], timestamp: Date.now() }],\n\t\t\t\tmodel: input.model,\n\t\t\t\tthinkingLevel: input.thinkingLevel ?? \"low\",\n\t\t\t\tmaxTokens: plan.tokenBudget,\n\t\t\t\tsignal,\n\t\t\t\t// The reflection system prompt is static (#33) — let the provider cache the prefix so\n\t\t\t\t// repeated passes only pay for the variable tail.\n\t\t\t\tcacheRetention: \"short\",\n\t\t\t\tlaneKind: \"reflection\",\n\t\t\t});\n\n\t\tconst result = await new ReflectionEngine().reflect({\n\t\t\trecentTurnText: input.recentTurnText,\n\t\t\t// Read memory FRESH (not the prefix-cache-frozen system-prompt block) so confront-before-write\n\t\t\t// sees writes made earlier this session.\n\t\t\texistingMemory: this.deps.getMemoryManager().buildSystemPromptBlockFresh() || \"\",\n\t\t\tplan,\n\t\t\tcomplete,\n\t\t});\n\n\t\t// Bug #21: if the session was disposed while the completion was in flight, do NOT write memory\n\t\t// or skills against the dead session.\n\t\tif (this.deps.isDisposed()) return result;\n\n\t\t// Learning apply policy: every durable write is converted to a proposal, decided by the\n\t\t// learning gate, and audited with a rollback plan. With the policy disabled (default) the\n\t\t// legacy direct-apply behavior is preserved — but now leaves audit records with rollback info.\n\t\tconst policy = this.deps.getSettingsManager().getLearningPolicySettings();\n\t\t// The audit id sequence counts STORED snapshots only: it reseeds from the stored count on\n\t\t// every pass, so advancing it for a no-op (which stores nothing) would make later passes\n\t\t// reuse ids — and rollback keys on the id, so a collision blocks or misdirects rollback.\n\t\tlet auditSequence = getLearningAuditSnapshots(this.deps.getSessionManager().getEntries()).length;\n\t\t// G6 evidence strength: durable proposals accumulate observation counts across passes/sessions\n\t\t// so the gate can distinguish a one-off cue from a repeatedly-confirmed lesson. Built once per\n\t\t// pass; every increment is best-effort (store IO must never break reflection).\n\t\tconst observationStore = ObservationStore.forAgentDir(this.deps.getAgentDir());\n\t\tlet writeIndex = 0;\n\t\tfor (const write of result.writes) {\n\t\t\twriteIndex += 1;\n\t\t\tconst proposalId = `${input.reportId ?? \"reflection\"}-w${writeIndex}`;\n\t\t\tconst proposal = proposalFromReflectionWrite(write, proposalId);\n\t\t\tconst rollback = rollbackPlanForReflectionWrite(write);\n\t\t\tlet observations = 1;\n\t\t\tif (policy.enabled) {\n\t\t\t\ttry {\n\t\t\t\t\tobservations = observationStore.increment(observationKey(proposal.layer, proposal.summary));\n\t\t\t\t} catch {\n\t\t\t\t\t// A store read/write failure falls back to a fresh count of 1, which keeps the gate\n\t\t\t\t\t// proposal-first (never spuriously auto-applies) rather than crashing the pass.\n\t\t\t\t\tobservations = 1;\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst decision: LearningDecision = policy.enabled\n\t\t\t\t? evaluateLearningDecision({\n\t\t\t\t\t\tproposal,\n\t\t\t\t\t\tconfidence: policy.reflectionSourceConfidence,\n\t\t\t\t\t\tobservations,\n\t\t\t\t\t\t// A replace/remove supersedes an existing durable fact — the reflection engine's\n\t\t\t\t\t\t// confront-before-write conflict signal — so it routes through approval instead of\n\t\t\t\t\t\t// silently overwriting prior memory. Additive writes contradict nothing.\n\t\t\t\t\t\tcontradictions: contradictionsForReflectionWrite(write),\n\t\t\t\t\t\tsettings: {\n\t\t\t\t\t\t\tenabled: true,\n\t\t\t\t\t\t\tautoApplyEnabled: policy.autoApplyEnabled,\n\t\t\t\t\t\t\tconfidenceThreshold: policy.confidenceThreshold,\n\t\t\t\t\t\t\tminObservations: policy.minObservations,\n\t\t\t\t\t\t\tallowedAutoApplyLayers: policy.allowedAutoApplyLayers,\n\t\t\t\t\t\t\trequireRollbackPlan: policy.requireRollbackPlan,\n\t\t\t\t\t\t\tautoApplySupersessions: policy.autoApplySupersessions,\n\t\t\t\t\t\t},\n\t\t\t\t\t})\n\t\t\t\t: {\n\t\t\t\t\t\tkind: \"apply\",\n\t\t\t\t\t\treasonCode: \"learning_policy_disabled_legacy_apply\",\n\t\t\t\t\t\tconfidence: 0,\n\t\t\t\t\t\tsummary: proposal.summary,\n\t\t\t\t\t\trequiresApproval: false,\n\t\t\t\t\t};\n\n\t\t\tthis.deps.saveLearningDecisionSnapshot(decision);\n\t\t\t// G3: learning-gate outcome. Codes/numbers only — never the proposal summary/memory text.\n\t\t\tthis.deps.emitAutonomyTelemetry({\n\t\t\t\ttype: AUTONOMY_TELEMETRY_EVENT_TYPES.learningDecision,\n\t\t\t\ttimestamp: new Date().toISOString(),\n\t\t\t\tpayload: {\n\t\t\t\t\tkind: decision.kind,\n\t\t\t\t\treasonCode: decision.reasonCode,\n\t\t\t\t\tlayer: proposal.layer,\n\t\t\t\t\tconfidence: decision.confidence,\n\t\t\t\t\trequiresApproval: decision.requiresApproval,\n\t\t\t\t},\n\t\t\t});\n\t\t\t// G8: a proposal that needs human sign-off is an approval REQUEST. Codes/layer only —\n\t\t\t// never the proposal summary/memory text (those live only in the audit snapshot).\n\t\t\tif (decision.requiresApproval) {\n\t\t\t\tthis.deps.emitAutonomyTelemetry({\n\t\t\t\t\ttype: AUTONOMY_TELEMETRY_EVENT_TYPES.approvalRequest,\n\t\t\t\t\ttimestamp: new Date().toISOString(),\n\t\t\t\t\tpayload: {\n\t\t\t\t\t\tkind: decision.kind,\n\t\t\t\t\t\treasonCode: decision.reasonCode,\n\t\t\t\t\t\tlayer: proposal.layer,\n\t\t\t\t\t},\n\t\t\t\t});\n\t\t\t}\n\t\t\t// An automatic skill promotion the gate would otherwise apply must still clear the same\n\t\t\t// skill_audit overlap check the model-invoked `skillify` tool enforces — otherwise reflection\n\t\t\t// can silently write a near-duplicate SKILL.md. A non-overlapping skill is unaffected\n\t\t\t// (skillPromotionBlock stays undefined) and promotes exactly as before.\n\t\t\tconst skillPromotionBlock =\n\t\t\t\twrite.kind === \"promote_skill\" && decision.kind === \"apply\"\n\t\t\t\t\t? this._checkSkillPromotionOverlap(write)\n\t\t\t\t\t: undefined;\n\n\t\t\t// The gate's decision and the write's actual outcome are two different questions: the memory\n\t\t\t// tool can refuse a write (budget exceeded, drift, threat) via details.success:false without\n\t\t\t// throwing. Capture that outcome instead of assuming \"decision.kind === apply\" means it landed\n\t\t\t// — otherwise a refused write leaves a phantom \"apply\" audit whose rollback later fails\n\t\t\t// not-found (or, worse, misfires against whatever now occupies that text).\n\t\t\tconst applied =\n\t\t\t\tdecision.kind === \"apply\" && !skillPromotionBlock ? await this._applyReflectionWrite(write, signal) : false;\n\t\t\tconst writeFailed = decision.kind === \"apply\" && !skillPromotionBlock && !applied;\n\t\t\tif (decision.kind !== \"no-op\") {\n\t\t\t\tauditSequence += 1;\n\t\t\t\tappendLearningAuditSnapshot(this.deps.getSessionManager(), {\n\t\t\t\t\tid: `audit-${auditSequence}`,\n\t\t\t\t\tproposalId,\n\t\t\t\t\tlayer: proposal.layer,\n\t\t\t\t\taction: skillPromotionBlock\n\t\t\t\t\t\t? \"propose\"\n\t\t\t\t\t\t: writeFailed\n\t\t\t\t\t\t\t? \"apply_failed\"\n\t\t\t\t\t\t\t: decision.kind === \"apply\"\n\t\t\t\t\t\t\t\t? \"apply\"\n\t\t\t\t\t\t\t\t: \"propose\",\n\t\t\t\t\tsummary: skillPromotionBlock ? `${proposal.summary} — ${skillPromotionBlock.note}` : proposal.summary,\n\t\t\t\t\treasonCode: skillPromotionBlock\n\t\t\t\t\t\t? skillPromotionBlock.reasonCode\n\t\t\t\t\t\t: writeFailed\n\t\t\t\t\t\t\t? APPLY_WRITE_REFUSED_REASON_CODE\n\t\t\t\t\t\t\t: decision.reasonCode,\n\t\t\t\t\tdecision,\n\t\t\t\t\t// No rollback plan on a failed apply or a held/proposed promotion — nothing durable\n\t\t\t\t\t// landed in either case, so there is nothing to undo.\n\t\t\t\t\trollback: skillPromotionBlock || writeFailed ? undefined : rollback,\n\t\t\t\t\tcreatedAt: new Date().toISOString(),\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\n\t\t// Account the reflection's spend so it surfaces in the footer roll-up (net-token visibility).\n\t\t// Idempotent on reportId so a retried/duplicated pass cannot double-count.\n\t\tif (result.usage.cost.total > 0 || result.usage.totalTokens > 0) {\n\t\t\tthis.deps.addSpawnedUsage(result.usage, { label: \"reflection\", reportId: input.reportId });\n\t\t}\n\t\treturn result;\n\t}\n\n\tgetLearningAuditRecords(): LearningAuditRecord[] {\n\t\treturn getLearningAuditSnapshots(this.deps.getSessionManager().getEntries());\n\t}\n\n\t/**\n\t * Roll back one applied durable learning change by executing the inverse operation recorded in\n\t * its audit record (memory ops run through the same bundled memory-tool path as the original\n\t * apply; promoted skills are archived). Appends a linked \"rollback\" audit record on success so\n\t * the change history stays complete and a change cannot be rolled back twice.\n\t */\n\tasync rollbackLearningWrite(auditId: string): Promise<{ ok: boolean; reason: string }> {\n\t\tif (this.deps.isDisposed()) return { ok: false, reason: \"session_disposed\" };\n\n\t\tconst audits = this.getLearningAuditRecords();\n\t\tconst audit = audits.find((record) => record.id === auditId);\n\t\tif (!audit) return { ok: false, reason: \"audit_not_found\" };\n\t\tif (audit.action !== \"apply\") return { ok: false, reason: \"not_an_applied_change\" };\n\t\tif (audits.some((record) => record.action === \"rollback\" && record.rollbackOf === auditId)) {\n\t\t\treturn { ok: false, reason: \"already_rolled_back\" };\n\t\t}\n\t\tconst rollback = audit.rollback;\n\t\tif (!rollback) return { ok: false, reason: \"no_rollback_plan\" };\n\n\t\t// Every inverse must be VERIFIED-applied before the rollback audit is appended: a silently\n\t\t// failed inverse that still recorded \"rollback\" would permanently self-lock the change\n\t\t// behind already_rolled_back while the durable write is in fact still live.\n\t\tswitch (rollback.kind) {\n\t\t\tcase \"memory_remove\": {\n\t\t\t\tif (!rollback.target) return { ok: false, reason: \"missing_rollback_target\" };\n\t\t\t\tif (!(await this._applyReflectionWrite({ kind: \"memory_remove\", target: rollback.target }))) {\n\t\t\t\t\treturn { ok: false, reason: \"rollback_apply_failed\" };\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tcase \"memory_restore\": {\n\t\t\t\tif (!rollback.target || rollback.previous === undefined) {\n\t\t\t\t\treturn { ok: false, reason: \"missing_rollback_target\" };\n\t\t\t\t}\n\t\t\t\tconst applied = await this._applyReflectionWrite({\n\t\t\t\t\tkind: \"memory_replace\",\n\t\t\t\t\ttarget: rollback.target,\n\t\t\t\t\ttext: rollback.previous,\n\t\t\t\t});\n\t\t\t\tif (!applied) return { ok: false, reason: \"rollback_apply_failed\" };\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tcase \"memory_add\": {\n\t\t\t\tif (rollback.previous === undefined) return { ok: false, reason: \"missing_rollback_target\" };\n\t\t\t\tconst applied = await this._applyReflectionWrite({\n\t\t\t\t\tkind: \"memory_add\",\n\t\t\t\t\tsection: \"MEMORY\",\n\t\t\t\t\ttext: rollback.previous,\n\t\t\t\t});\n\t\t\t\tif (!applied) return { ok: false, reason: \"rollback_apply_failed\" };\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tcase \"archive_skill\": {\n\t\t\t\tif (!rollback.target) return { ok: false, reason: \"missing_rollback_target\" };\n\t\t\t\tif (!this.deps.archivePromotedSkill(rollback.target)) {\n\t\t\t\t\treturn { ok: false, reason: \"skill_archive_failed\" };\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\n\t\tappendLearningAuditSnapshot(this.deps.getSessionManager(), {\n\t\t\tid: `${audit.id}-rollback`,\n\t\t\tproposalId: audit.proposalId,\n\t\t\tlayer: audit.layer,\n\t\t\taction: \"rollback\",\n\t\t\tsummary: `Rolled back: ${audit.summary}`,\n\t\t\treasonCode: \"user_requested_rollback\",\n\t\t\tdecision: audit.decision,\n\t\t\trollbackOf: audit.id,\n\t\t\tcreatedAt: new Date().toISOString(),\n\t\t});\n\t\treturn { ok: true, reason: \"rollback_applied\" };\n\t}\n\n\t/**\n\t * Apply one reflection write through the bundled `memory` tool. `memory_replace`/`memory_remove`\n\t * don't carry a target file, so we try MEMORY.md first and fall back to USER.md when the substring\n\t * isn't found there. Never throws (reflection must never break a turn); returns whether the write\n\t * actually applied so callers that MUST know — rollback's once-only accounting — can react instead\n\t * of recording a success that never happened.\n\t */\n\tprivate async _applyReflectionWrite(write: ReflectionWrite, signal?: AbortSignal): Promise<boolean> {\n\t\t// R7 memory-to-behavior: a recurring procedure is compiled into an executable skill file rather\n\t\t// than stored as a flat fact. Written under the agent skills dir so it loads like any user skill.\n\t\tif (write.kind === \"promote_skill\") {\n\t\t\treturn this._promoteReflectionSkill(write.name, write.description, write.body);\n\t\t}\n\n\t\ttype MemResult = { details?: { success?: boolean; error?: string } };\n\t\ttype MemExec = (\n\t\t\ttoolCallId: string,\n\t\t\tparams: { action: string; target: string; content?: string; oldContent?: string },\n\t\t\tsignal: AbortSignal | undefined,\n\t\t\tonUpdate: undefined,\n\t\t\tctx: undefined,\n\t\t) => Promise<MemResult>;\n\t\tconst memTool = this.deps\n\t\t\t.getMemoryManager()\n\t\t\t.getToolDefinitions()\n\t\t\t.find((t) => t.name === \"memory\");\n\t\tconst exec = memTool?.execute as unknown as MemExec | undefined;\n\t\tif (!exec) return false;\n\n\t\tconst run = (params: Parameters<MemExec>[1]) => exec(\"reflection\", params, signal, undefined, undefined);\n\n\t\tif (write.kind === \"memory_add\") {\n\t\t\ttry {\n\t\t\t\tconst res = await run({\n\t\t\t\t\taction: \"add\",\n\t\t\t\t\ttarget: write.section === \"USER\" ? \"user\" : \"memory\",\n\t\t\t\t\tcontent: write.text,\n\t\t\t\t});\n\t\t\t\treturn res?.details?.success === true;\n\t\t\t} catch {\n\t\t\t\t// best-effort; reflection writes must never throw into the turn loop\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\n\t\t// replace / remove carry no target file — try MEMORY.md, then USER.md. The memory tool reports\n\t\t// outcomes via `details.success` (it catches its own errors rather than throwing). Only a\n\t\t// genuine \"not found in the file\" justifies trying the other file; a real failure for a file\n\t\t// (budget exceeded / drift) must NOT fall through and mutate the wrong target.\n\t\tfor (const target of [\"memory\", \"user\"] as const) {\n\t\t\ttry {\n\t\t\t\tconst params =\n\t\t\t\t\twrite.kind === \"memory_replace\"\n\t\t\t\t\t\t? { action: \"replace\", target, oldContent: write.target, content: write.text }\n\t\t\t\t\t\t: { action: \"remove\", target, oldContent: write.target };\n\t\t\t\tconst res = await run(params);\n\t\t\t\tif (res?.details?.success === true) return true; // applied\n\t\t\t\tif (!/not found/i.test(String(res?.details?.error ?? \"\"))) return false; // real failure — don't misapply\n\t\t\t\t// substring simply absent from this file — try the next target\n\t\t\t} catch {\n\t\t\t\t// defensive: if the tool ever does throw, try the next target\n\t\t\t}\n\t\t}\n\t\treturn false;\n\t}\n\n\t/**\n\t * The same skill_audit overlap check the model-invoked `skillify` tool enforces\n\t * (tools/skillify.ts → tools/skill-audit.ts's `runSkillAudit`), run before an AUTOMATIC promotion\n\t * so the reflection engine can never silently write a near-duplicate SKILL.md. Reuses the audit\n\t * seam unchanged (never duplicated) against the same already-loaded skills universe skillify\n\t * compares a draft against. Returns a block reason when the draft overlaps an existing skill above\n\t * the audit's own similarity threshold, or when the audit itself fails (the promotion is held, not\n\t * written unaudited); undefined when clear to promote. Never throws — mirrors every other\n\t * best-effort check in this file.\n\t */\n\tprivate _checkSkillPromotionOverlap(write: {\n\t\tname: string;\n\t\tdescription: string;\n\t\tbody: string;\n\t}): { reasonCode: string; note: string } | undefined {\n\t\ttry {\n\t\t\tconst cwd = this.deps.getCwd?.() ?? process.cwd();\n\t\t\tconst audit = runSkillAudit(cwd, write);\n\t\t\tconst overlap = audit.nearDuplicates.find((d) => d.a === \"[draft]\" || d.b === \"[draft]\");\n\t\t\tif (!overlap) return undefined;\n\t\t\tconst otherPath = overlap.a === \"[draft]\" ? overlap.b : overlap.a;\n\t\t\t// Every skill file is named \"SKILL.md\" — unlike skillify's own display formatter (which takes\n\t\t\t// the path's last segment and always shows that literal filename), look up the declared\n\t\t\t// frontmatter name so the proposal actually names the skill it overlaps with.\n\t\t\tconst otherName = audit.skills.find((s) => s.path === otherPath)?.name ?? otherPath;\n\t\t\treturn {\n\t\t\t\treasonCode: SKILL_OVERLAP_CONSOLIDATION_REASON_CODE,\n\t\t\t\tnote: `overlaps existing skill \"${otherName}\" (${(overlap.similarity * 100).toFixed(0)}% similar) — consolidation proposed instead of a duplicate write`,\n\t\t\t};\n\t\t} catch {\n\t\t\t// Bounded, observable degradation via the promote path's existing error-reporting shape: an\n\t\t\t// audit failure must never throw into the reflection pass, but it also must not silently\n\t\t\t// fall through to an unaudited write — hold the promotion and record why.\n\t\t\treturn {\n\t\t\t\treasonCode: SKILL_AUDIT_UNAVAILABLE_REASON_CODE,\n\t\t\t\tnote: \"skill overlap audit failed; promotion held rather than written unaudited\",\n\t\t\t};\n\t\t}\n\t}\n\n\t/**\n\t * R7: write a reflection-promoted skill as `<agentDir>/skills/<name>/SKILL.md` so it loads like any\n\t * user skill. Best-effort; never clobbers an existing (hand-authored) skill of the same name. The\n\t * overlap audit runs at the call site in {@link runReflectionPass} — a write only reaches here\n\t * once the draft has already cleared it.\n\t */\n\tprivate _promoteReflectionSkill(rawName: string, description: string, body: string): boolean {\n\t\tconst name = rawName\n\t\t\t.trim()\n\t\t\t.toLowerCase()\n\t\t\t.replace(/[^a-z0-9-]+/g, \"-\")\n\t\t\t.replace(/^-+|-+$/g, \"\")\n\t\t\t.slice(0, 64);\n\t\tif (!name || !body.trim()) return false;\n\t\ttry {\n\t\t\tconst dir = join(this.deps.getAgentDir(), \"skills\", name);\n\t\t\tconst file = join(dir, \"SKILL.md\");\n\t\t\tif (existsSync(file)) return false; // do not overwrite an existing skill\n\t\t\tmkdirSync(dir, { recursive: true });\n\t\t\tconst safeDescription = description.replace(/[\\r\\n]+/g, \" \").trim();\n\t\t\t// `promoted: true` marks this as reflection-generated so the curator (#32) can lifecycle-manage\n\t\t\t// it (archive/consolidate) WITHOUT ever touching hand-authored user skills.\n\t\t\tconst content = `---\\nname: ${name}\\ndescription: ${safeDescription}\\npromoted: true\\n---\\n\\n<!-- Auto-generated by the reflection engine (R7 memory-to-behavior). Review and refine. -->\\n\\n${body.trim()}\\n`;\n\t\t\twriteFileSync(file, content, \"utf-8\");\n\t\t\treturn true;\n\t\t} catch {\n\t\t\t// promotion must never break a turn\n\t\t\treturn false;\n\t\t}\n\t}\n}\n"]}
+{"version":3,"file":"reflection-controller.d.ts","sourceRoot":"","sources":["../../src/core/reflection-controller.ts"],"names":[],"mappings":"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"}

package/dist/core/reflection-controller.js

@@ -9,9 +9,10 @@
  * session state (model/agent/registry/memory/settings) through narrow deps accessors rather than the
  * whole AgentSession.
  */
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { runAgentLoop, } from "@caupulican/pi-agent-core";
+import { runAgentLoop, startAgentProviderRequest, } from "@caupulican/pi-agent-core";
 import { resolveModelThinkingLevel, } from "@caupulican/pi-ai";
 import { computeLaneAffinityKey, DEFAULT_ISOLATED_LANE_KIND, } from "./agent-session-contracts.js";
 import { AUTONOMY_TELEMETRY_EVENT_TYPES } from "./autonomy/telemetry-events.js";
@@ -19,6 +20,8 @@ import { APPLY_WRITE_REFUSED_REASON_CODE, appendLearningAuditSnapshot, contradic
 import { evaluateLearningDecision } from "./learning/learning-gate.js";
 import { ObservationStore, observationKey } from "./learning/observation-store.js";
 import { decideDemand, ReflectionEngine, } from "./learning/reflection-engine.js";
+import { analyzeReflectionTurn, boundReflectionSemanticText, reflectionTriggerPriority, } from "./learning/reflection-turn-analysis.js";
+import { resolveCliModel } from "./model-resolver.js";
 import { registerInFlightWork } from "./reload-blockers.js";
 import { runSkillAudit } from "./tools/skill-audit.js";
 // reasonCode when an automatic skill promotion is blocked by an overlap with an existing skill
@@ -27,11 +30,116 @@ export const SKILL_OVERLAP_CONSOLIDATION_REASON_CODE = "skill_overlap_consolidat
 // reasonCode when the overlap audit itself fails — the promotion is held (not written unaudited)
 // rather than silently skipping the check.
 export const SKILL_AUDIT_UNAVAILABLE_REASON_CODE = "skill_audit_unavailable";
+const REFLECTION_MIN_INTERVAL_MS = 45_000;
+const REFLECTION_PENDING_MAX_CHARS = 12_000;
+const REFLECTION_DIGEST_HISTORY_SIZE = 64;
 export class ReflectionController {
-    deps;
     constructor(deps) {
+        this.pendingTurns = [];
+        this.scheduledDigests = new Set();
+        this.lastScheduledPassAt = 0;
         this.deps = deps;
     }
+    /** Analyze once, schedule bounded background reflection when warranted, and return filtered turn text for sync hooks. */
+    scheduleFromTurn(messages, contextHeadroomPct) {
+        const settings = this.deps.getSettingsManager().getAutoLearnSettings();
+        const analysis = analyzeReflectionTurn(messages, settings.complexTaskToolCalls ?? 12);
+        const enabled = settings.enabled !== false &&
+            settings.reflectionReview !== false &&
+            process.env.PI_NATIVE_REFLECTION !== "0" &&
+            process.env.PI_AUTO_LEARN_CHILD !== "1" &&
+            !this.deps.isChildSession() &&
+            !this.deps.isDisposed();
+        if (!enabled || analysis.trigger === "none" || this.scheduledDigests.has(analysis.digest))
+            return analysis;
+        this.scheduledDigests.add(analysis.digest);
+        while (this.scheduledDigests.size > REFLECTION_DIGEST_HISTORY_SIZE) {
+            const oldest = this.scheduledDigests.values().next().value;
+            if (typeof oldest !== "string")
+                break;
+            this.scheduledDigests.delete(oldest);
+        }
+        this.pendingTurns.push({ analysis, contextHeadroomPct });
+        let pendingChars = this.pendingTurns.reduce((total, turn) => total + turn.analysis.recentTurnText.length, 0);
+        while (this.pendingTurns.length > 1 && pendingChars > REFLECTION_PENDING_MAX_CHARS) {
+            pendingChars -= this.pendingTurns.shift()?.analysis.recentTurnText.length ?? 0;
+        }
+        this.schedulePendingPass();
+        return analysis;
+    }
+    schedulePendingPass() {
+        if (this.activeScheduledPass || this.scheduledTimer || this.pendingTurns.length === 0 || this.deps.isDisposed()) {
+            return;
+        }
+        const delay = Math.max(0, REFLECTION_MIN_INTERVAL_MS - (Date.now() - this.lastScheduledPassAt));
+        if (delay > 0) {
+            this.scheduledTimer = setTimeout(() => {
+                this.scheduledTimer = undefined;
+                this.startPendingPass();
+            }, delay);
+            this.scheduledTimer.unref?.();
+            return;
+        }
+        this.startPendingPass();
+    }
+    startPendingPass() {
+        if (this.activeScheduledPass || this.pendingTurns.length === 0 || this.deps.isDisposed())
+            return;
+        const turns = this.pendingTurns.splice(0);
+        const trigger = turns.reduce((selected, turn) => reflectionTriggerPriority(turn.analysis.trigger) > reflectionTriggerPriority(selected)
+            ? turn.analysis.trigger
+            : selected, "none");
+        const recentTurnText = boundReflectionSemanticText(turns.map((turn) => turn.analysis.recentTurnText).join("\n---\n"), REFLECTION_PENDING_MAX_CHARS);
+        const reportDigest = createHash("sha256")
+            .update(turns.map((turn) => turn.analysis.digest).join("\0"))
+            .digest("hex")
+            .slice(0, 24);
+        const settings = this.deps.getSettingsManager().getAutoLearnSettings();
+        let model;
+        if (settings.model && settings.model !== "active") {
+            const resolved = resolveCliModel({ cliModel: settings.model, modelRegistry: this.deps.getModelRegistry() });
+            if (resolved.model && this.deps.getModelRegistry().hasConfiguredAuth(resolved.model))
+                model = resolved.model;
+        }
+        const toolCallCount = turns.reduce((total, turn) => total + turn.analysis.toolCallCount, 0);
+        const contextHeadroomPct = Math.min(...turns.map((turn) => turn.contextHeadroomPct));
+        this.lastScheduledPassAt = Date.now();
+        this.activeScheduledPass = (async () => {
+            try {
+                await this.runReflectionPass({
+                    signals: {
+                        trigger,
+                        toolCallCount,
+                        hadCorrection: turns.some((turn) => turn.analysis.hadCorrection),
+                        contextHeadroomPct,
+                        usefulLately: 0,
+                    },
+                    recentTurnText,
+                    reportId: `reflection:${reportDigest}`,
+                    model,
+                    thinkingLevel: settings.thinkingLevel ?? "low",
+                    explicitUserMemoryInstruction: turns.every((turn) => turn.analysis.explicitUserMemoryInstruction),
+                });
+            }
+            catch {
+                // Best-effort background learning must never disrupt the foreground turn.
+            }
+            finally {
+                this.activeScheduledPass = undefined;
+                this.schedulePendingPass();
+            }
+        })();
+    }
+    cancelScheduled() {
+        if (this.scheduledTimer)
+            clearTimeout(this.scheduledTimer);
+        this.scheduledTimer = undefined;
+        this.pendingTurns.length = 0;
+    }
+    async waitForActivePass() {
+        while (this.activeScheduledPass)
+            await this.activeScheduledPass;
+    }
     /**
      * Run an LLM completion fully ISOLATED from the main session — the load-bearing primitive for
      * reflection and bounded child lanes (adaptive-agent design §6c/§7).
@@ -40,13 +148,16 @@ export class ReflectionController {
      * tools, and passes **no real `sessionId`** — only a deterministic SYNTHETIC cache-affinity key
      * (see {@link computeLaneAffinityKey}) derived from `(laneKind, model, systemPrompt)`, which can never
      * equal or embed the real session id. A tool-enabled call receives only caller-owned tools and hooks,
-     * and is turn-bounded. It cannot mutate `agent.state.messages`, append session entries, or touch the
+     * and applies a turn bound only when its owner explicitly supplies one. It cannot mutate `agent.state.messages`, append session entries, or touch the
      * foreground tool registry. Mirrors `generateSummary()`'s one-shot mechanics otherwise.
      *
      * 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) {
+        if (opts.maxTurns !== undefined && (!Number.isSafeInteger(opts.maxTurns) || opts.maxTurns <= 0)) {
+            throw new Error("runIsolatedCompletion: maxTurns must be a positive safe integer when provided");
+        }
         const model = opts.model ?? this.deps.getModel();
         if (!model) {
             throw new Error("runIsolatedCompletion: no model available");
@@ -62,9 +173,10 @@ export class ReflectionController {
         const deregisterInFlight = registerInFlightWork(this.deps.getAgentDir(), "isolated-completion", opts.laneKind ?? DEFAULT_ISOLATED_LANE_KIND);
         try {
             // Fresh, isolated context: explicit messages, caller-owned tools only, nothing from the main session.
+            const history = opts.history ?? [];
             const context = {
                 systemPrompt: opts.systemPrompt,
-                messages: opts.messages,
+                messages: [...history, ...opts.messages],
                 tools: opts.tools ?? [],
             };
             // Isolate the prompt cache from the main session by DELIBERATELY never sending the real
@@ -92,51 +204,68 @@ export class ReflectionController {
                 options.apiKey = auth.apiKey;
                 options.headers = auth.headers;
             }
-            if (opts.tools && opts.tools.length > 0) {
-                const agent = this.deps.getAgent();
-                const foregroundModel = agent.state.model;
-                const usesForegroundModel = foregroundModel?.provider === model.provider && foregroundModel.id === model.id;
-                const textToolCallProtocol = this.deps.resolveTextToolCallProtocol(model);
-                const requestedMaxTurns = typeof opts.maxTurns === "number" && Number.isFinite(opts.maxTurns) ? Math.floor(opts.maxTurns) : 6;
-                const maxTurns = Math.max(1, Math.min(12, requestedMaxTurns));
-                let completedTurns = 0;
+            const agent = this.deps.getAgent();
+            const foregroundModel = agent.state.model;
+            const usesForegroundModel = foregroundModel?.provider === model.provider && foregroundModel.id === model.id;
+            const textToolCallProtocol = this.deps.resolveTextToolCallProtocol(model);
+            const maxTurns = opts.maxTurns;
+            let completedTurns = 0;
+            const loopConfig = {
+                model,
+                interactionMode: "background",
+                maxTokens: opts.maxTokens,
+                cacheRetention: opts.cacheRetention,
+                reasoning: thinkingLevel,
+                // Same synthetic per-lane affinity key as the one-shot path above — never the real sessionId.
+                sessionId: affinityKey,
+                ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),
+                ...(options.headers !== undefined ? { headers: options.headers } : {}),
+                getApiKey: agent.getApiKey,
+                resolveRequestReasoning: agent.resolveRequestReasoning,
+                temperature: textToolCallProtocol ? 0 : undefined,
+                textToolCallProtocol,
+                onTextToolProtocolParse: usesForegroundModel ? agent.onTextToolProtocolParse : undefined,
+                transport: agent.transport,
+                thinkingBudgets: agent.thinkingBudgets,
+                maxRetryDelayMs: agent.maxRetryDelayMs,
+                // This remains independent from an owner-provided turn budget: it stops only repeated
+                // identical tool calls, so legitimate long-running work can continue until completion.
+                maxStallTurns: agent.maxStallTurns,
+                onRunawayStop: usesForegroundModel ? agent.onRunawayStop : undefined,
+                toolExecution: "sequential",
+                toolArgumentTeachEnabled: agent.toolArgumentTeachEnabled,
+                onToolArgumentValidation: usesForegroundModel ? agent.onToolArgumentValidation : undefined,
+                toolValidationEscalationThreshold: agent.toolValidationEscalationThreshold,
+                onToolValidationEscalation: usesForegroundModel ? agent.onToolValidationEscalation : undefined,
+                beforeToolCall: opts.beforeToolCall,
+                afterToolCall: opts.afterToolCall,
+                getSteeringMessages: opts.getSteeringMessages,
+                getFollowUpMessages: opts.getFollowUpMessages,
+                transformContext: opts.transformContext,
+                requestPreflight: opts.requestPreflight,
+                ...(maxTurns === undefined
+                    ? {}
+                    : {
+                        shouldStopAfterTurn: () => {
+                            completedTurns += 1;
+                            return completedTurns >= maxTurns;
+                        },
+                    }),
+                convertToLlm: agent.convertToLlm,
+            };
+            // An explicitly supplied surface owns a child tool loop even when it is empty: a model may
+            // hallucinate an unavailable tool and must receive the bounded unknown-tool result so it can
+            // repair. Only an omitted tools option selects the one-shot completion path.
+            if (opts.tools !== undefined) {
                 const childContext = {
                     systemPrompt: opts.systemPrompt,
-                    messages: [],
+                    messages: [...history],
                     tools: [...opts.tools],
                 };
-                const loopConfig = {
-                    model,
-                    interactionMode: "background",
-                    maxTokens: opts.maxTokens,
-                    cacheRetention: opts.cacheRetention,
-                    reasoning: thinkingLevel,
-                    // Same synthetic per-lane affinity key as the one-shot path above — never the real sessionId.
-                    sessionId: affinityKey,
-                    ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),
-                    ...(options.headers !== undefined ? { headers: options.headers } : {}),
-                    temperature: textToolCallProtocol ? 0 : undefined,
-                    textToolCallProtocol,
-                    onTextToolProtocolParse: usesForegroundModel ? agent.onTextToolProtocolParse : undefined,
-                    transport: agent.transport,
-                    thinkingBudgets: agent.thinkingBudgets,
-                    maxRetryDelayMs: agent.maxRetryDelayMs,
-                    maxStallTurns: Math.max(2, Math.min(maxTurns, agent.maxStallTurns ?? maxTurns)),
-                    onRunawayStop: usesForegroundModel ? agent.onRunawayStop : undefined,
-                    toolExecution: "sequential",
-                    toolArgumentTeachEnabled: agent.toolArgumentTeachEnabled,
-                    onToolArgumentValidation: usesForegroundModel ? agent.onToolArgumentValidation : undefined,
-                    toolValidationEscalationThreshold: agent.toolValidationEscalationThreshold,
-                    onToolValidationEscalation: usesForegroundModel ? agent.onToolValidationEscalation : undefined,
-                    beforeToolCall: opts.beforeToolCall,
-                    afterToolCall: opts.afterToolCall,
-                    shouldStopAfterTurn: () => {
-                        completedTurns += 1;
-                        return completedTurns >= maxTurns;
-                    },
-                    convertToLlm: agent.convertToLlm,
-                };
-                const messages = await runAgentLoop(opts.messages, childContext, loopConfig, () => { }, opts.signal, agent.streamFn);
+                const messages = await runAgentLoop(opts.messages, childContext, loopConfig, async (event) => {
+                    if (event.type === "message_end")
+                        await opts.onMessage?.(event.message);
+                }, opts.signal, agent.streamFn);
                 const assistantMessages = messages.filter((message) => message.role === "assistant");
                 let finalAssistant = assistantMessages.at(-1);
                 if (!finalAssistant) {
@@ -147,17 +276,22 @@ export class ReflectionController {
                 if (opts.finalTextPrompt && !hasFinalText && endedOnToolCall && !opts.signal?.aborted) {
                     // A hard turn bound may stop immediately after successful tool execution. Preserve that bound,
                     // then allow exactly one tool-free synthesis call so the gathered work is not thrown away.
-                    const finalizationMessages = await agent.convertToLlm(messages);
-                    const finalizationStream = await agent.streamFn(model, {
+                    const finalizationPrompt = {
+                        role: "user",
+                        content: opts.finalTextPrompt,
+                        timestamp: Date.now(),
+                    };
+                    await opts.onMessage?.(finalizationPrompt);
+                    const finalizationContext = {
                         systemPrompt: opts.systemPrompt,
-                        messages: [
-                            ...finalizationMessages,
-                            { role: "user", content: opts.finalTextPrompt, timestamp: Date.now() },
-                        ],
+                        messages: [...history, ...messages, finalizationPrompt],
                         tools: [],
-                    }, options);
+                    };
+                    const finalizationStream = await startAgentProviderRequest(finalizationContext, loopConfig, opts.signal, agent.streamFn);
                     finalAssistant = await finalizationStream.result();
+                    await opts.onMessage?.(finalAssistant);
                     assistantMessages.push(finalAssistant);
+                    messages.push(finalizationPrompt, finalAssistant);
                 }
                 const usage = assistantMessages.reduce((total, message) => ({
                     input: total.input + message.usage.input,
@@ -184,10 +318,20 @@ export class ReflectionController {
                     .filter((content) => content.type === "text")
                     .map((content) => content.text)
                     .join("");
-                return { text, usage, stopReason: finalAssistant.stopReason };
+                // Isolated inputs are Message values and this loop only adds assistant/tool-result messages,
+                // so the child transcript is safely representable by the public Message[] contract.
+                return {
+                    text,
+                    usage,
+                    stopReason: finalAssistant.stopReason,
+                    messages: [...history, ...messages],
+                };
             }
-            const stream = await this.deps.getAgent().streamFn(model, context, options);
+            for (const message of opts.messages)
+                await opts.onMessage?.(message);
+            const stream = await startAgentProviderRequest(context, loopConfig, opts.signal, agent.streamFn);
             const result = await stream.result();
+            await opts.onMessage?.(result);
             const text = result.content
                 .filter((c) => c.type === "text")
                 .map((c) => c.text)
@@ -200,7 +344,7 @@ export class ReflectionController {
                 totalTokens: 0,
                 cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
             };
-            return { text, usage, stopReason: result.stopReason };
+            return { text, usage, stopReason: result.stopReason, messages: [...history, ...opts.messages, result] };
         }
         finally {
             deregisterInFlight();
@@ -251,7 +395,7 @@ export class ReflectionController {
         if (this.deps.isDisposed())
             return result;
         // Learning apply policy: every durable write is converted to a proposal, decided by the
-        // learning gate, and audited with a rollback plan. With the policy disabled (default) the
+        // learning gate, and audited with a rollback plan. When the policy is explicitly disabled,
         // legacy direct-apply behavior is preserved — but now leaves audit records with rollback info.
         const policy = this.deps.getSettingsManager().getLearningPolicySettings();
         // The audit id sequence counts STORED snapshots only: it reseeds from the stored count on
@@ -279,32 +423,42 @@ export class ReflectionController {
                     observations = 1;
                 }
             }
-            const decision = policy.enabled
-                ? evaluateLearningDecision({
-                    proposal,
-                    confidence: policy.reflectionSourceConfidence,
-                    observations,
-                    // A replace/remove supersedes an existing durable fact — the reflection engine's
-                    // confront-before-write conflict signal — so it routes through approval instead of
-                    // silently overwriting prior memory. Additive writes contradict nothing.
-                    contradictions: contradictionsForReflectionWrite(write),
-                    settings: {
-                        enabled: true,
-                        autoApplyEnabled: policy.autoApplyEnabled,
-                        confidenceThreshold: policy.confidenceThreshold,
-                        minObservations: policy.minObservations,
-                        allowedAutoApplyLayers: policy.allowedAutoApplyLayers,
-                        requireRollbackPlan: policy.requireRollbackPlan,
-                        autoApplySupersessions: policy.autoApplySupersessions,
-                    },
-                })
-                : {
+            const explicitUserMemoryWrite = input.explicitUserMemoryInstruction === true &&
+                (write.kind === "memory_add" || write.kind === "memory_replace");
+            const decision = explicitUserMemoryWrite
+                ? {
                     kind: "apply",
-                    reasonCode: "learning_policy_disabled_legacy_apply",
-                    confidence: 0,
+                    reasonCode: "explicit_user_memory_instruction",
+                    confidence: 100,
                     summary: proposal.summary,
                     requiresApproval: false,
-                };
+                }
+                : policy.enabled
+                    ? evaluateLearningDecision({
+                        proposal,
+                        confidence: policy.reflectionSourceConfidence,
+                        observations,
+                        // A replace/remove supersedes an existing durable fact — the reflection engine's
+                        // confront-before-write conflict signal — so it routes through approval instead of
+                        // silently overwriting prior memory. Additive writes contradict nothing.
+                        contradictions: contradictionsForReflectionWrite(write),
+                        settings: {
+                            enabled: true,
+                            autoApplyEnabled: policy.autoApplyEnabled,
+                            confidenceThreshold: policy.confidenceThreshold,
+                            minObservations: policy.minObservations,
+                            allowedAutoApplyLayers: policy.allowedAutoApplyLayers,
+                            requireRollbackPlan: policy.requireRollbackPlan,
+                            autoApplySupersessions: policy.autoApplySupersessions,
+                        },
+                    })
+                    : {
+                        kind: "apply",
+                        reasonCode: "learning_policy_disabled_legacy_apply",
+                        confidence: 0,
+                        summary: proposal.summary,
+                        requiresApproval: false,
+                    };
             this.deps.saveLearningDecisionSnapshot(decision);
             // G3: learning-gate outcome. Codes/numbers only — never the proposal summary/memory text.
             this.deps.emitAutonomyTelemetry({