@xopcai/xopc 0.0.136 → 0.0.138

package/dist/src/agent/background-review/coordinator.js

@@ -1,5 +1,8 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { summarizeUserUnderstandingQuality } from "../../storage/sqlite/memory-records-repository.js";
+import "../../storage/sqlite/index.js";
+import { resolveAdaptiveUnderstandingCadence } from "../memory/understanding/quality.js";
 import { isAssistantTurnAborted, isAssistantTurnFailed } from "../orchestration/llm-turn-retry.js";
 import { resolveBackgroundReviewSettings } from "./settings.js";
 import { runBackgroundReviewTurn } from "./run-background-review.js";
@@ -14,41 +17,22 @@ var BackgroundReviewCoordinator = class {
 	}
 	/**
 	* Called before the main `agent.prompt` for a user turn — bumps the memory
-	* counter and arms `pendingMemoryReview` when the cadence interval is hit.
+	* counter and arms a review when the cadence interval is hit.
 	*/
-	beginUserTurn(sessionKey, registeredToolNames) {
-		const cfg = resolveBackgroundReviewSettings(this.opts.getConfig());
-		if (!cfg.enabled || cfg.memoryNudgeInterval <= 0) return;
-		if (!registeredToolNames.includes("curated_memory")) return;
+	beginUserTurn(sessionKey) {
+		const cfg = resolveBackgroundReviewSettings(this.opts.getConfig(), sessionKey);
+		if (!cfg.enabled) return;
 		const state = this.ensureState(sessionKey);
-		state.turnsSinceMemory += 1;
-		if (state.turnsSinceMemory >= cfg.memoryNudgeInterval) {
-			state.pendingMemoryReview = true;
-			state.turnsSinceMemory = 0;
+		const intervalTurns = this.resolveReviewInterval(cfg, state);
+		state.turnsSinceReview += 1;
+		if (state.turnsSinceReview >= intervalTurns) {
+			state.pendingReview = true;
+			state.turnsSinceReview = 0;
 		}
 	}
 	/**
-	* Subscribe to the agent's events to update the skill counter as the
-	* conversation progresses. Idempotent per session — the previous subscription
-	* is torn down before installing the new one.
-	*/
-	attachToAgent(sessionKey, agent, registeredToolNames) {
-		const state = this.ensureState(sessionKey);
-		state.unsubscribe?.();
-		state.unsubscribe = agent.subscribe((ev) => {
-			const cfg = resolveBackgroundReviewSettings(this.opts.getConfig());
-			if (!cfg.enabled || cfg.skillNudgeInterval <= 0) return;
-			if (!registeredToolNames.includes("skill_manage")) return;
-			if (ev.type === "turn_start") state.itersSinceSkill += 1;
-			if (ev.type === "tool_execution_end") {
-				const te = ev;
-				if (!te.isError && typeof te.toolName === "string" && te.toolName.trim() === "skill_manage") state.itersSinceSkill = 0;
-			}
-		});
-	}
-	/**
 	* Fire-and-forget review after the main user turn. Decides whether to run a
-	* memory and/or skills sweep based on the counter state + last assistant text,
+	* understanding sweep based on the counter state + last assistant text,
 	* and delegates the actual review to {@link runBackgroundReviewTurn}.
 	*/
 	scheduleAfterUserTurn(ctx) {
@@ -61,55 +45,62 @@ var BackgroundReviewCoordinator = class {
 	}
 	/** Tear down state for a session (called by `AgentManager.removeAgent`). */
 	forgetSession(sessionKey) {
-		const state = this.states.get(sessionKey);
-		if (!state) return;
-		state.unsubscribe?.();
 		this.states.delete(sessionKey);
 	}
-	/** Tear down every subscription (`AgentManager.dispose` / hot reload). */
+	/** Clear every counter (`AgentManager.dispose` / hot reload). */
 	clear() {
-		for (const state of this.states.values()) state.unsubscribe?.();
 		this.states.clear();
 	}
 	ensureState(sessionKey) {
 		const existing = this.states.get(sessionKey);
 		if (existing) return existing;
 		const state = {
-			turnsSinceMemory: 0,
-			itersSinceSkill: 0,
-			pendingMemoryReview: false
+			turnsSinceReview: 0,
+			pendingReview: false
 		};
 		this.states.set(sessionKey, state);
 		return state;
 	}
+	resolveReviewInterval(settings, state) {
+		if (!settings.adaptiveCadence || !settings.agentId) return settings.reviewIntervalTurns;
+		const now = Date.now();
+		if (state.adaptiveIntervalTurns != null && (state.adaptiveIntervalExpiresAt ?? 0) > now) return state.adaptiveIntervalTurns;
+		try {
+			const metrics = summarizeUserUnderstandingQuality({
+				agentId: settings.agentId,
+				windowDays: 30,
+				nowMs: now
+			});
+			const decision = resolveAdaptiveUnderstandingCadence(settings.reviewIntervalTurns, metrics);
+			state.adaptiveIntervalTurns = decision.effectiveIntervalTurns;
+			state.adaptiveIntervalExpiresAt = now + 5 * 6e4;
+			if (decision.slowed) log.debug({
+				agentId: settings.agentId,
+				baseIntervalTurns: decision.baseIntervalTurns,
+				effectiveIntervalTurns: decision.effectiveIntervalTurns,
+				reasons: decision.reasons
+			}, "User-understanding review cadence slowed by quality signals");
+			return decision.effectiveIntervalTurns;
+		} catch {
+			return settings.reviewIntervalTurns;
+		}
+	}
 	async runReviewIfNeeded(ctx) {
 		const state = this.states.get(ctx.sessionKey);
 		if (!state) return;
-		const settings = resolveBackgroundReviewSettings(this.opts.getConfig());
+		const settings = resolveBackgroundReviewSettings(this.opts.getConfig(), ctx.sessionKey);
 		if (!settings.enabled) return;
 		if (isAssistantTurnAborted(ctx.agent) || isAssistantTurnFailed(ctx.agent)) return;
 		if (!ctx.lastAssistantText?.trim()) return;
-		const reviewMemory = state.pendingMemoryReview;
-		state.pendingMemoryReview = false;
-		let reviewSkills = false;
-		if (settings.skillNudgeInterval > 0 && ctx.registeredToolNames.includes("skill_manage") && state.itersSinceSkill >= settings.skillNudgeInterval) {
-			reviewSkills = true;
-			state.itersSinceSkill = 0;
-		}
-		if (!reviewMemory && !reviewSkills) return;
+		const shouldReview = state.pendingReview;
+		state.pendingReview = false;
+		if (!shouldReview) return;
 		await runBackgroundReviewTurn({
 			sessionKey: ctx.sessionKey,
 			mainAgent: ctx.agent,
 			settings,
-			reviewMemory,
-			reviewSkills,
-			registeredToolNames: [...ctx.registeredToolNames],
-			skillAllowlist: ctx.skillAllowlist ? [...ctx.skillAllowlist] : void 0,
-			workspacePath: ctx.workspacePath,
-			skillManager: ctx.workspaceRuntime.skillManager,
 			memoryManager: ctx.workspaceRuntime.memoryManager,
-			getConfig: () => this.opts.getConfig(),
-			onSkillsFilesystemMutate: this.opts.onSkillsFilesystemMutate
+			getConfig: () => this.opts.getConfig()
 		});
 	}
 };

package/dist/src/agent/background-review/coordinator.js.map

@@ -1 +1 @@
-{"version":3,"file":"coordinator.js","names":[],"sources":["../../../../src/agent/background-review/coordinator.ts"],"sourcesContent":["/**\n * BackgroundReviewCoordinator — owns the per-session counters that decide when\n * to nudge the model into running a quiet \"review memory / review skills\" follow-up\n * after a normal user turn finishes.\n *\n * Previously the nudge state, the `agent.subscribe` plumbing for the skill counter,\n * and the call to `runBackgroundReviewTurn` lived as private methods + a per-instance\n * field on `AgentManager`. Extracted so:\n *   - `AgentInstance` no longer carries an inline counter object.\n *   - The agent-event subscription used to count `tool_execution_end` events is\n *     owned by the coordinator; teardown is automatic on `forgetSession`.\n *   - Future changes to the nudge cadence (per-agent intervals, per-tool counters,\n *     etc.) only touch this file.\n */\n\nimport type { Agent, AgentEvent } from '@earendil-works/pi-agent-core';\n\nimport type { Config } from '../../config/schema.js';\nimport { createLogger } from '../../utils/logger.js';\nimport {\n  isAssistantTurnAborted,\n  isAssistantTurnFailed,\n} from '../orchestration/llm-turn-retry.js';\nimport type { WorkspaceRuntime } from '../workspace-runtime/registry.js';\nimport { resolveBackgroundReviewSettings } from './settings.js';\nimport { runBackgroundReviewTurn } from './run-background-review.js';\n\nconst log = createLogger('BackgroundReviewCoordinator');\n\ninterface NudgeState {\n  turnsSinceMemory: number;\n  itersSinceSkill: number;\n  pendingMemoryReview: boolean;\n  unsubscribe?: () => void;\n}\n\nexport interface BackgroundReviewCoordinatorOptions {\n  /** Effective config snapshot used to look up review-cadence settings. */\n  getConfig: () => Config | undefined;\n  /** Trigger after the review turn writes skill files (lets agents reload prompts). */\n  onSkillsFilesystemMutate: () => void;\n}\n\nexport interface ScheduleReviewContext {\n  sessionKey: string;\n  agent: Agent;\n  registeredToolNames: readonly string[];\n  skillAllowlist?: readonly string[];\n  workspacePath: string;\n  /** Last assistant text — review is skipped when empty. */\n  lastAssistantText: string | null;\n  workspaceRuntime: WorkspaceRuntime;\n}\n\nexport class BackgroundReviewCoordinator {\n  private readonly opts: BackgroundReviewCoordinatorOptions;\n  private readonly states = new Map<string, NudgeState>();\n\n  constructor(opts: BackgroundReviewCoordinatorOptions) {\n    this.opts = opts;\n  }\n\n  /**\n   * Called before the main `agent.prompt` for a user turn — bumps the memory\n   * counter and arms `pendingMemoryReview` when the cadence interval is hit.\n   */\n  beginUserTurn(sessionKey: string, registeredToolNames: readonly string[]): void {\n    const cfg = resolveBackgroundReviewSettings(this.opts.getConfig());\n    if (!cfg.enabled || cfg.memoryNudgeInterval <= 0) return;\n    if (!registeredToolNames.includes('curated_memory')) return;\n\n    const state = this.ensureState(sessionKey);\n    state.turnsSinceMemory += 1;\n    if (state.turnsSinceMemory >= cfg.memoryNudgeInterval) {\n      state.pendingMemoryReview = true;\n      state.turnsSinceMemory = 0;\n    }\n  }\n\n  /**\n   * Subscribe to the agent's events to update the skill counter as the\n   * conversation progresses. Idempotent per session — the previous subscription\n   * is torn down before installing the new one.\n   */\n  attachToAgent(\n    sessionKey: string,\n    agent: Agent,\n    registeredToolNames: readonly string[],\n  ): void {\n    const state = this.ensureState(sessionKey);\n    state.unsubscribe?.();\n    const unsub = agent.subscribe((ev: AgentEvent) => {\n      const cfg = resolveBackgroundReviewSettings(this.opts.getConfig());\n      if (!cfg.enabled || cfg.skillNudgeInterval <= 0) return;\n      if (!registeredToolNames.includes('skill_manage')) return;\n      if (ev.type === 'turn_start') {\n        state.itersSinceSkill += 1;\n      }\n      if (ev.type === 'tool_execution_end') {\n        const te = ev as Extract<AgentEvent, { type: 'tool_execution_end' }>;\n        if (!te.isError && typeof te.toolName === 'string' && te.toolName.trim() === 'skill_manage') {\n          state.itersSinceSkill = 0;\n        }\n      }\n    });\n    state.unsubscribe = unsub;\n  }\n\n  /**\n   * Fire-and-forget review after the main user turn. Decides whether to run a\n   * memory and/or skills sweep based on the counter state + last assistant text,\n   * and delegates the actual review to {@link runBackgroundReviewTurn}.\n   */\n  scheduleAfterUserTurn(ctx: ScheduleReviewContext): void {\n    void this.runReviewIfNeeded(ctx).catch((err) => {\n      log.warn({ err, sessionKey: ctx.sessionKey }, 'Background review failed');\n    });\n  }\n\n  /** Tear down state for a session (called by `AgentManager.removeAgent`). */\n  forgetSession(sessionKey: string): void {\n    const state = this.states.get(sessionKey);\n    if (!state) return;\n    state.unsubscribe?.();\n    this.states.delete(sessionKey);\n  }\n\n  /** Tear down every subscription (`AgentManager.dispose` / hot reload). */\n  clear(): void {\n    for (const state of this.states.values()) {\n      state.unsubscribe?.();\n    }\n    this.states.clear();\n  }\n\n  private ensureState(sessionKey: string): NudgeState {\n    const existing = this.states.get(sessionKey);\n    if (existing) return existing;\n    const state: NudgeState = {\n      turnsSinceMemory: 0,\n      itersSinceSkill: 0,\n      pendingMemoryReview: false,\n    };\n    this.states.set(sessionKey, state);\n    return state;\n  }\n\n  private async runReviewIfNeeded(ctx: ScheduleReviewContext): Promise<void> {\n    const state = this.states.get(ctx.sessionKey);\n    if (!state) return;\n    const settings = resolveBackgroundReviewSettings(this.opts.getConfig());\n    if (!settings.enabled) return;\n    if (isAssistantTurnAborted(ctx.agent) || isAssistantTurnFailed(ctx.agent)) return;\n    if (!ctx.lastAssistantText?.trim()) return;\n\n    const reviewMemory = state.pendingMemoryReview;\n    state.pendingMemoryReview = false;\n\n    let reviewSkills = false;\n    if (\n      settings.skillNudgeInterval > 0 &&\n      ctx.registeredToolNames.includes('skill_manage') &&\n      state.itersSinceSkill >= settings.skillNudgeInterval\n    ) {\n      reviewSkills = true;\n      state.itersSinceSkill = 0;\n    }\n\n    if (!reviewMemory && !reviewSkills) return;\n\n    await runBackgroundReviewTurn({\n      sessionKey: ctx.sessionKey,\n      mainAgent: ctx.agent,\n      settings,\n      reviewMemory,\n      reviewSkills,\n      registeredToolNames: [...ctx.registeredToolNames],\n      skillAllowlist: ctx.skillAllowlist ? [...ctx.skillAllowlist] : undefined,\n      workspacePath: ctx.workspacePath,\n      skillManager: ctx.workspaceRuntime.skillManager,\n      memoryManager: ctx.workspaceRuntime.memoryManager,\n      getConfig: () => this.opts.getConfig(),\n      onSkillsFilesystemMutate: this.opts.onSkillsFilesystemMutate,\n    });\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"coordinator.js","names":[],"sources":["../../../../src/agent/background-review/coordinator.ts"],"sourcesContent":["/**\n * BackgroundReviewCoordinator — owns the per-session counters that decide when\n * to nudge the model into running a quiet user-understanding review\n * after a normal user turn finishes.\n *\n * The nudge state and review scheduling are kept out of the per-session agent\n * instance so:\n *   - `AgentInstance` no longer carries an inline counter object.\n *   - Future changes to the review cadence only touch this file.\n */\n\nimport type { Agent } from '@earendil-works/pi-agent-core';\n\nimport type { Config } from '../../config/schema.js';\nimport { summarizeUserUnderstandingQuality } from '../../storage/sqlite/index.js';\nimport { createLogger } from '../../utils/logger.js';\nimport { resolveAdaptiveUnderstandingCadence } from '../memory/understanding/quality.js';\nimport {\n  isAssistantTurnAborted,\n  isAssistantTurnFailed,\n} from '../orchestration/llm-turn-retry.js';\nimport type { WorkspaceRuntime } from '../workspace-runtime/registry.js';\nimport {\n  resolveBackgroundReviewSettings,\n  type BackgroundReviewSettings,\n} from './settings.js';\nimport { runBackgroundReviewTurn } from './run-background-review.js';\n\nconst log = createLogger('BackgroundReviewCoordinator');\n\ninterface NudgeState {\n  turnsSinceReview: number;\n  pendingReview: boolean;\n  adaptiveIntervalTurns?: number;\n  adaptiveIntervalExpiresAt?: number;\n}\n\nexport interface BackgroundReviewCoordinatorOptions {\n  /** Effective config snapshot used to look up review-cadence settings. */\n  getConfig: () => Config | undefined;\n}\n\nexport interface ScheduleReviewContext {\n  sessionKey: string;\n  agent: Agent;\n  /** Last assistant text — review is skipped when empty. */\n  lastAssistantText: string | null;\n  workspaceRuntime: WorkspaceRuntime;\n}\n\nexport class BackgroundReviewCoordinator {\n  private readonly opts: BackgroundReviewCoordinatorOptions;\n  private readonly states = new Map<string, NudgeState>();\n\n  constructor(opts: BackgroundReviewCoordinatorOptions) {\n    this.opts = opts;\n  }\n\n  /**\n   * Called before the main `agent.prompt` for a user turn — bumps the memory\n   * counter and arms a review when the cadence interval is hit.\n   */\n  beginUserTurn(sessionKey: string): void {\n    const cfg = resolveBackgroundReviewSettings(this.opts.getConfig(), sessionKey);\n    if (!cfg.enabled) return;\n\n    const state = this.ensureState(sessionKey);\n    const intervalTurns = this.resolveReviewInterval(cfg, state);\n    state.turnsSinceReview += 1;\n    if (state.turnsSinceReview >= intervalTurns) {\n      state.pendingReview = true;\n      state.turnsSinceReview = 0;\n    }\n  }\n\n  /**\n   * Fire-and-forget review after the main user turn. Decides whether to run a\n   * understanding sweep based on the counter state + last assistant text,\n   * and delegates the actual review to {@link runBackgroundReviewTurn}.\n   */\n  scheduleAfterUserTurn(ctx: ScheduleReviewContext): void {\n    void this.runReviewIfNeeded(ctx).catch((err) => {\n      log.warn({ err, sessionKey: ctx.sessionKey }, 'Background review failed');\n    });\n  }\n\n  /** Tear down state for a session (called by `AgentManager.removeAgent`). */\n  forgetSession(sessionKey: string): void {\n    this.states.delete(sessionKey);\n  }\n\n  /** Clear every counter (`AgentManager.dispose` / hot reload). */\n  clear(): void {\n    this.states.clear();\n  }\n\n  private ensureState(sessionKey: string): NudgeState {\n    const existing = this.states.get(sessionKey);\n    if (existing) return existing;\n    const state: NudgeState = {\n      turnsSinceReview: 0,\n      pendingReview: false,\n    };\n    this.states.set(sessionKey, state);\n    return state;\n  }\n\n  private resolveReviewInterval(settings: BackgroundReviewSettings, state: NudgeState): number {\n    if (!settings.adaptiveCadence || !settings.agentId) return settings.reviewIntervalTurns;\n    const now = Date.now();\n    if (\n      state.adaptiveIntervalTurns != null\n      && (state.adaptiveIntervalExpiresAt ?? 0) > now\n    ) {\n      return state.adaptiveIntervalTurns;\n    }\n    try {\n      const metrics = summarizeUserUnderstandingQuality({ agentId: settings.agentId, windowDays: 30, nowMs: now });\n      const decision = resolveAdaptiveUnderstandingCadence(settings.reviewIntervalTurns, metrics);\n      state.adaptiveIntervalTurns = decision.effectiveIntervalTurns;\n      state.adaptiveIntervalExpiresAt = now + 5 * 60_000;\n      if (decision.slowed) {\n        log.debug({\n          agentId: settings.agentId,\n          baseIntervalTurns: decision.baseIntervalTurns,\n          effectiveIntervalTurns: decision.effectiveIntervalTurns,\n          reasons: decision.reasons,\n        }, 'User-understanding review cadence slowed by quality signals');\n      }\n      return decision.effectiveIntervalTurns;\n    } catch {\n      return settings.reviewIntervalTurns;\n    }\n  }\n\n  private async runReviewIfNeeded(ctx: ScheduleReviewContext): Promise<void> {\n    const state = this.states.get(ctx.sessionKey);\n    if (!state) return;\n    const settings = resolveBackgroundReviewSettings(this.opts.getConfig(), ctx.sessionKey);\n    if (!settings.enabled) return;\n    if (isAssistantTurnAborted(ctx.agent) || isAssistantTurnFailed(ctx.agent)) return;\n    if (!ctx.lastAssistantText?.trim()) return;\n\n    const shouldReview = state.pendingReview;\n    state.pendingReview = false;\n    if (!shouldReview) return;\n\n    await runBackgroundReviewTurn({\n      sessionKey: ctx.sessionKey,\n      mainAgent: ctx.agent,\n      settings,\n      memoryManager: ctx.workspaceRuntime.memoryManager,\n      getConfig: () => this.opts.getConfig(),\n    });\n  }\n}\n"],"mappings":";;;;;;;;;aAeqD;AAarD,MAAM,MAAM,aAAa,8BAA8B;AAsBvD,IAAa,8BAAb,MAAyC;CACvC;CACA,yBAA0B,IAAI,KAAyB;CAEvD,YAAY,MAA0C;AACpD,OAAK,OAAO;;;;;;CAOd,cAAc,YAA0B;EACtC,MAAM,MAAM,gCAAgC,KAAK,KAAK,WAAW,EAAE,WAAW;AAC9E,MAAI,CAAC,IAAI,QAAS;EAElB,MAAM,QAAQ,KAAK,YAAY,WAAW;EAC1C,MAAM,gBAAgB,KAAK,sBAAsB,KAAK,MAAM;AAC5D,QAAM,oBAAoB;AAC1B,MAAI,MAAM,oBAAoB,eAAe;AAC3C,SAAM,gBAAgB;AACtB,SAAM,mBAAmB;;;;;;;;CAS7B,sBAAsB,KAAkC;AACjD,OAAK,kBAAkB,IAAI,CAAC,OAAO,QAAQ;AAC9C,OAAI,KAAK;IAAE;IAAK,YAAY,IAAI;IAAY,EAAE,2BAA2B;IACzE;;;CAIJ,cAAc,YAA0B;AACtC,OAAK,OAAO,OAAO,WAAW;;;CAIhC,QAAc;AACZ,OAAK,OAAO,OAAO;;CAGrB,YAAoB,YAAgC;EAClD,MAAM,WAAW,KAAK,OAAO,IAAI,WAAW;AAC5C,MAAI,SAAU,QAAO;EACrB,MAAM,QAAoB;GACxB,kBAAkB;GAClB,eAAe;GAChB;AACD,OAAK,OAAO,IAAI,YAAY,MAAM;AAClC,SAAO;;CAGT,sBAA8B,UAAoC,OAA2B;AAC3F,MAAI,CAAC,SAAS,mBAAmB,CAAC,SAAS,QAAS,QAAO,SAAS;EACpE,MAAM,MAAM,KAAK,KAAK;AACtB,MACE,MAAM,yBAAyB,SAC3B,MAAM,6BAA6B,KAAK,IAE5C,QAAO,MAAM;AAEf,MAAI;GACF,MAAM,UAAU,kCAAkC;IAAE,SAAS,SAAS;IAAS,YAAY;IAAI,OAAO;IAAK,CAAC;GAC5G,MAAM,WAAW,oCAAoC,SAAS,qBAAqB,QAAQ;AAC3F,SAAM,wBAAwB,SAAS;AACvC,SAAM,4BAA4B,MAAM,IAAI;AAC5C,OAAI,SAAS,OACX,KAAI,MAAM;IACR,SAAS,SAAS;IAClB,mBAAmB,SAAS;IAC5B,wBAAwB,SAAS;IACjC,SAAS,SAAS;IACnB,EAAE,8DAA8D;AAEnE,UAAO,SAAS;UACV;AACN,UAAO,SAAS;;;CAIpB,MAAc,kBAAkB,KAA2C;EACzE,MAAM,QAAQ,KAAK,OAAO,IAAI,IAAI,WAAW;AAC7C,MAAI,CAAC,MAAO;EACZ,MAAM,WAAW,gCAAgC,KAAK,KAAK,WAAW,EAAE,IAAI,WAAW;AACvF,MAAI,CAAC,SAAS,QAAS;AACvB,MAAI,uBAAuB,IAAI,MAAM,IAAI,sBAAsB,IAAI,MAAM,CAAE;AAC3E,MAAI,CAAC,IAAI,mBAAmB,MAAM,CAAE;EAEpC,MAAM,eAAe,MAAM;AAC3B,QAAM,gBAAgB;AACtB,MAAI,CAAC,aAAc;AAEnB,QAAM,wBAAwB;GAC5B,YAAY,IAAI;GAChB,WAAW,IAAI;GACf;GACA,eAAe,IAAI,iBAAiB;GACpC,iBAAiB,KAAK,KAAK,WAAW;GACvC,CAAC"}

package/dist/src/agent/background-review/prompts.d.ts

@@ -1,4 +1,2 @@
-export declare const MEMORY_REVIEW_USER_PROMPT = "Review the conversation above and consider saving to curated memory if appropriate.\n\nFocus on:\n1. Has the user revealed things about themselves \u2014 persona, desires, preferences, or personal details worth remembering?\n2. Has the user expressed expectations about how you should behave, their work style, or how they want you to operate?\n\nUse curated_memory (MEMORY.md for agent-facing notes, user/MEMORY.md for global user memory) only for durable facts that will still matter in future sessions.\nIf nothing is worth saving, reply with exactly: Nothing to save.";
-export declare const SKILL_REVIEW_USER_PROMPT = "Review the conversation above and consider saving or updating a skill if appropriate.\n\nFocus on: was a non-trivial approach used to complete a task that required trial and error, or changing course from experience, or did the user expect a different reusable method?\n\nUse skills_list / skill_view to inspect existing skills. If a relevant skill exists, update it with skill_manage. Otherwise create a new skill if the approach is reusable.\nIf nothing is worth saving, reply with exactly: Nothing to save.";
-export declare const COMBINED_REVIEW_USER_PROMPT = "Review the conversation above for two separate concerns:\n\n**Curated memory (declarative):** Has the user revealed durable facts about themselves, preferences, or how they want you to behave? If so, save with curated_memory (MEMORY.md vs user/MEMORY.md per tool rules).\n\n**Skills (procedural):** Was a non-trivial reusable workflow established (trial-and-error, environment-specific steps)? Use skills_list / skill_view, then skill_manage to create or patch.\n\nOnly act when something genuinely deserves persistence. If nothing stands out, reply with exactly: Nothing to save.";
-export declare const REVIEW_SYSTEM_PROMPT = "You are a background persistence assistant for the same user session. You do NOT chat with the user \u2014 there is no end user reading this channel.\n\nYour only job: decide whether to write curated_memory and/or skill_manage (plus skills_list / skill_view to inspect skills). Keep tool calls minimal. If nothing deserves saving, reply with exactly: Nothing to save.";
+export declare const MEMORY_REVIEW_USER_PROMPT = "Review the conversation above and identify durable user-understanding candidates.\n\nFocus on:\n1. Has the user revealed things about themselves \u2014 persona, desires, preferences, or personal details worth remembering?\n2. Has the user expressed expectations about how you should behave, their work style, or how they want you to operate?\n\nReturn JSON only, with this shape:\n{\"candidates\":[{\"kind\":\"preference\",\"content\":\"...\",\"confidence\":0.8,\"importance\":0.7,\"durability\":\"durable\",\"sensitivity\":\"normal\",\"disclosurePolicy\":\"referenceable\",\"tags\":[\"background-review\"]}]}\n\nAllowed kinds: preference, boundary, relationship, project_context, commitment, routine, personal_logistics, open_question, milestone, current_state, task_lesson, tool_preference, long_term_goal, derived_insight.\nOnly include facts supported by the conversation and likely to matter in a future session. Never include passwords, tokens, credentials, or speculative diagnoses. Use {\"candidates\":[]} when nothing qualifies.";
+export declare const UNDERSTANDING_REVIEW_SYSTEM_PROMPT = "You are the user-understanding synthesis stage for the same session. You do not chat with the user and cannot write storage directly. Extract only evidence-backed, durable candidates and return strict JSON matching the requested schema.";

package/dist/src/agent/background-review/prompts.js

@@ -1,29 +1,17 @@
 //#region src/agent/background-review/prompts.ts
-const MEMORY_REVIEW_USER_PROMPT = `Review the conversation above and consider saving to curated memory if appropriate.
+const MEMORY_REVIEW_USER_PROMPT = `Review the conversation above and identify durable user-understanding candidates.
 
 Focus on:
 1. Has the user revealed things about themselves — persona, desires, preferences, or personal details worth remembering?
 2. Has the user expressed expectations about how you should behave, their work style, or how they want you to operate?
 
-Use curated_memory (MEMORY.md for agent-facing notes, user/MEMORY.md for global user memory) only for durable facts that will still matter in future sessions.
-If nothing is worth saving, reply with exactly: Nothing to save.`;
-const SKILL_REVIEW_USER_PROMPT = `Review the conversation above and consider saving or updating a skill if appropriate.
+Return JSON only, with this shape:
+{"candidates":[{"kind":"preference","content":"...","confidence":0.8,"importance":0.7,"durability":"durable","sensitivity":"normal","disclosurePolicy":"referenceable","tags":["background-review"]}]}
 
-Focus on: was a non-trivial approach used to complete a task that required trial and error, or changing course from experience, or did the user expect a different reusable method?
-
-Use skills_list / skill_view to inspect existing skills. If a relevant skill exists, update it with skill_manage. Otherwise create a new skill if the approach is reusable.
-If nothing is worth saving, reply with exactly: Nothing to save.`;
-const COMBINED_REVIEW_USER_PROMPT = `Review the conversation above for two separate concerns:
-
-**Curated memory (declarative):** Has the user revealed durable facts about themselves, preferences, or how they want you to behave? If so, save with curated_memory (MEMORY.md vs user/MEMORY.md per tool rules).
-
-**Skills (procedural):** Was a non-trivial reusable workflow established (trial-and-error, environment-specific steps)? Use skills_list / skill_view, then skill_manage to create or patch.
-
-Only act when something genuinely deserves persistence. If nothing stands out, reply with exactly: Nothing to save.`;
-const REVIEW_SYSTEM_PROMPT = `You are a background persistence assistant for the same user session. You do NOT chat with the user — there is no end user reading this channel.
-
-Your only job: decide whether to write curated_memory and/or skill_manage (plus skills_list / skill_view to inspect skills). Keep tool calls minimal. If nothing deserves saving, reply with exactly: Nothing to save.`;
+Allowed kinds: preference, boundary, relationship, project_context, commitment, routine, personal_logistics, open_question, milestone, current_state, task_lesson, tool_preference, long_term_goal, derived_insight.
+Only include facts supported by the conversation and likely to matter in a future session. Never include passwords, tokens, credentials, or speculative diagnoses. Use {"candidates":[]} when nothing qualifies.`;
+const UNDERSTANDING_REVIEW_SYSTEM_PROMPT = `You are the user-understanding synthesis stage for the same session. You do not chat with the user and cannot write storage directly. Extract only evidence-backed, durable candidates and return strict JSON matching the requested schema.`;
 //#endregion
-export { COMBINED_REVIEW_USER_PROMPT, MEMORY_REVIEW_USER_PROMPT, REVIEW_SYSTEM_PROMPT, SKILL_REVIEW_USER_PROMPT };
+export { MEMORY_REVIEW_USER_PROMPT, UNDERSTANDING_REVIEW_SYSTEM_PROMPT };
 
 //# sourceMappingURL=prompts.js.map

package/dist/src/agent/background-review/prompts.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.js","names":[],"sources":["../../../../src/agent/background-review/prompts.ts"],"sourcesContent":["export const MEMORY_REVIEW_USER_PROMPT = `Review the conversation above and consider saving to curated memory if appropriate.\n\nFocus on:\n1. Has the user revealed things about themselves — persona, desires, preferences, or personal details worth remembering?\n2. Has the user expressed expectations about how you should behave, their work style, or how they want you to operate?\n\nUse curated_memory (MEMORY.md for agent-facing notes, user/MEMORY.md for global user memory) only for durable facts that will still matter in future sessions.\nIf nothing is worth saving, reply with exactly: Nothing to save.`;\n\nexport const SKILL_REVIEW_USER_PROMPT = `Review the conversation above and consider saving or updating a skill if appropriate.\n\nFocus on: was a non-trivial approach used to complete a task that required trial and error, or changing course from experience, or did the user expect a different reusable method?\n\nUse skills_list / skill_view to inspect existing skills. If a relevant skill exists, update it with skill_manage. Otherwise create a new skill if the approach is reusable.\nIf nothing is worth saving, reply with exactly: Nothing to save.`;\n\nexport const COMBINED_REVIEW_USER_PROMPT = `Review the conversation above for two separate concerns:\n\n**Curated memory (declarative):** Has the user revealed durable facts about themselves, preferences, or how they want you to behave? If so, save with curated_memory (MEMORY.md vs user/MEMORY.md per tool rules).\n\n**Skills (procedural):** Was a non-trivial reusable workflow established (trial-and-error, environment-specific steps)? Use skills_list / skill_view, then skill_manage to create or patch.\n\nOnly act when something genuinely deserves persistence. If nothing stands out, reply with exactly: Nothing to save.`;\n\nexport const REVIEW_SYSTEM_PROMPT = `You are a background persistence assistant for the same user session. You do NOT chat with the user — there is no end user reading this channel.\n\nYour only job: decide whether to write curated_memory and/or skill_manage (plus skills_list / skill_view to inspect skills). Keep tool calls minimal. If nothing deserves saving, reply with exactly: Nothing to save.`;\n"],"mappings":";AAAA,MAAa,4BAA4B;;;;;;;;AASzC,MAAa,2BAA2B;;;;;;AAOxC,MAAa,8BAA8B;;;;;;;AAQ3C,MAAa,uBAAuB"}
+{"version":3,"file":"prompts.js","names":[],"sources":["../../../../src/agent/background-review/prompts.ts"],"sourcesContent":["export const MEMORY_REVIEW_USER_PROMPT = `Review the conversation above and identify durable user-understanding candidates.\n\nFocus on:\n1. Has the user revealed things about themselves — persona, desires, preferences, or personal details worth remembering?\n2. Has the user expressed expectations about how you should behave, their work style, or how they want you to operate?\n\nReturn JSON only, with this shape:\n{\"candidates\":[{\"kind\":\"preference\",\"content\":\"...\",\"confidence\":0.8,\"importance\":0.7,\"durability\":\"durable\",\"sensitivity\":\"normal\",\"disclosurePolicy\":\"referenceable\",\"tags\":[\"background-review\"]}]}\n\nAllowed kinds: preference, boundary, relationship, project_context, commitment, routine, personal_logistics, open_question, milestone, current_state, task_lesson, tool_preference, long_term_goal, derived_insight.\nOnly include facts supported by the conversation and likely to matter in a future session. Never include passwords, tokens, credentials, or speculative diagnoses. Use {\"candidates\":[]} when nothing qualifies.`;\n\nexport const UNDERSTANDING_REVIEW_SYSTEM_PROMPT = `You are the user-understanding synthesis stage for the same session. You do not chat with the user and cannot write storage directly. Extract only evidence-backed, durable candidates and return strict JSON matching the requested schema.`;\n"],"mappings":";AAAA,MAAa,4BAA4B;;;;;;;;;;;AAYzC,MAAa,qCAAqC"}

package/dist/src/agent/background-review/run-background-review.d.ts

@@ -1,20 +1,12 @@
 import { Agent } from '@earendil-works/pi-agent-core';
 import type { Config } from '../../config/schema.js';
 import type { MemoryManager } from '../memory/manager.js';
-import type { SkillManager } from '../skills/skill-manager.js';
 import type { BackgroundReviewSettings } from './settings.js';
 export interface RunBackgroundReviewParams {
     sessionKey: string;
     mainAgent: Agent;
     settings: BackgroundReviewSettings;
-    reviewMemory: boolean;
-    reviewSkills: boolean;
-    registeredToolNames: string[];
-    skillAllowlist?: string[];
-    workspacePath: string;
-    skillManager: SkillManager;
     memoryManager: MemoryManager;
     getConfig: () => Config | undefined;
-    onSkillsFilesystemMutate: () => void;
 }
 export declare function runBackgroundReviewTurn(params: RunBackgroundReviewParams): Promise<void>;

package/dist/src/agent/background-review/run-background-review.js

@@ -4,14 +4,9 @@ import { init_sync_provider_auth, resolveProviderApiKeySync } from "../../auth/s
 import { getApiKeySync, init_providers } from "../../providers/index.js";
 import { createExtensionAwareStreamFn } from "../../providers/extension-stream-bridge.js";
 import { extractTextContent } from "../context/workspace.js";
-import { createCuratedMemoryTool } from "../tools/curated-memory-tool.js";
 import { resolveAgentTurnTimeoutMs, runAgentTurnWithTimeout } from "../orchestration/run-agent-turn-with-timeout.js";
-import { createSkillViewTool, createSkillsListTool } from "../tools/skills-tools.js";
-import { createSkillManageTool } from "../tools/skill-manage-tool.js";
-import { shouldRegisterCuratedMemoryTool } from "../memory/memory-config.js";
-import { wrapToolsWithProtection } from "../tools/executor.js";
 import { isAssistantTurnAborted, isAssistantTurnFailed } from "../orchestration/llm-turn-retry.js";
-import { COMBINED_REVIEW_USER_PROMPT, MEMORY_REVIEW_USER_PROMPT, REVIEW_SYSTEM_PROMPT, SKILL_REVIEW_USER_PROMPT } from "./prompts.js";
+import { MEMORY_REVIEW_USER_PROMPT, UNDERSTANDING_REVIEW_SYSTEM_PROMPT } from "./prompts.js";
 import { Agent } from "@earendil-works/pi-agent-core";
 //#region src/agent/background-review/run-background-review.ts
 init_sync_provider_auth();
@@ -22,59 +17,84 @@ function cloneMessageTail(messages, max) {
 	const tail = messages.length <= max ? messages : messages.slice(-max);
 	return JSON.parse(JSON.stringify(tail));
 }
-async function runBackgroundReviewTurn(params) {
-	const { sessionKey, mainAgent, settings, reviewMemory, reviewSkills, registeredToolNames, skillAllowlist, workspacePath, skillManager, memoryManager, getConfig, onSkillsFilesystemMutate } = params;
-	const userPrompt = reviewMemory && reviewSkills ? COMBINED_REVIEW_USER_PROMPT : reviewMemory ? MEMORY_REVIEW_USER_PROMPT : SKILL_REVIEW_USER_PROMPT;
-	const rawTools = [];
-	if (reviewMemory && shouldRegisterCuratedMemoryTool(getConfig())) rawTools.push(createCuratedMemoryTool(() => memoryManager));
-	if (reviewSkills) {
-		const ctx = () => ({
-			registeredToolNames,
-			skillAllowlist
-		});
-		rawTools.push(createSkillsListTool({
-			getSkillManager: () => skillManager,
-			getSkillIndexingContext: ctx
-		}), createSkillViewTool({
-			getSkillManager: () => skillManager,
-			getSkillIndexingContext: ctx
-		}), createSkillManageTool({
-			getSkillManager: () => skillManager,
-			getWorkspace: () => workspacePath,
-			onSkillsFilesystemMutate
-		}));
+const ALLOWED_UNDERSTANDING_KINDS = new Set([
+	"preference",
+	"boundary",
+	"relationship",
+	"project_context",
+	"commitment",
+	"routine",
+	"personal_logistics",
+	"open_question",
+	"milestone",
+	"current_state",
+	"task_lesson",
+	"tool_preference",
+	"long_term_goal",
+	"derived_insight"
+]);
+const ALLOWED_SENSITIVITIES = new Set([
+	"normal",
+	"personal",
+	"secret",
+	"regulated"
+]);
+function lastAssistantText(agent) {
+	for (let i = agent.state.messages.length - 1; i >= 0; i--) {
+		const message = agent.state.messages[i];
+		if (message.role !== "assistant") continue;
+		return Array.isArray(message.content) ? extractTextContent(message.content) : String(message.content);
 	}
-	if (rawTools.length === 0) {
-		log.debug({ sessionKey }, "Background review skipped: no tools registered for selected channels");
-		return;
+	return "";
+}
+function parseUnderstandingCandidates(raw) {
+	const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(raw)?.[1];
+	const start = raw.indexOf("{");
+	const end = raw.lastIndexOf("}");
+	const candidateJson = fenced ?? (start >= 0 && end > start ? raw.slice(start, end + 1) : raw);
+	try {
+		const parsed = JSON.parse(candidateJson);
+		if (!Array.isArray(parsed.candidates)) return [];
+		const output = [];
+		for (const value of parsed.candidates.slice(0, 8)) {
+			if (!value || typeof value !== "object") continue;
+			const item = value;
+			if (!ALLOWED_UNDERSTANDING_KINDS.has(item.kind)) continue;
+			if (typeof item.content !== "string" || item.content.trim().length < 4) continue;
+			const confidence = typeof item.confidence === "number" ? item.confidence : .65;
+			const importance = typeof item.importance === "number" ? item.importance : .5;
+			const durability = item.durability === "ephemeral" || item.durability === "recurring" ? item.durability : "durable";
+			const sensitivity = ALLOWED_SENSITIVITIES.has(item.sensitivity) ? item.sensitivity : "personal";
+			const disclosurePolicy = item.disclosurePolicy === "silent" || item.disclosurePolicy === "ask_before_reference" ? item.disclosurePolicy : "referenceable";
+			output.push({
+				kind: item.kind,
+				content: item.content.trim(),
+				confidence: Math.max(0, Math.min(1, confidence)),
+				importance: Math.max(0, Math.min(1, importance)),
+				explicitness: "inferred",
+				durability,
+				sensitivity,
+				disclosurePolicy,
+				tags: Array.isArray(item.tags) ? item.tags.filter((tag) => typeof tag === "string").slice(0, 8) : ["background-review"]
+			});
+		}
+		return output;
+	} catch {
+		return [];
 	}
-	const tools = wrapToolsWithProtection(rawTools, {});
-	const model = mainAgent.state.model;
-	let toolRounds = 0;
-	let aborted = false;
+}
+async function runUnderstandingReview(params) {
+	const { sessionKey, mainAgent, settings, memoryManager, getConfig } = params;
 	const reviewAgent = new Agent({
 		initialState: {
-			systemPrompt: REVIEW_SYSTEM_PROMPT,
-			model,
+			systemPrompt: UNDERSTANDING_REVIEW_SYSTEM_PROMPT,
+			model: mainAgent.state.model,
 			thinkingLevel: "off",
-			tools,
+			tools: [],
 			messages: []
 		},
 		streamFn: createExtensionAwareStreamFn(),
-		getApiKey: (provider) => resolveProviderApiKeySync(provider) ?? getApiKeySync(provider) ?? "",
-		beforeToolCall: async () => {
-			if (aborted) return {
-				block: true,
-				reason: "Background review aborted."
-			};
-			if (toolRounds >= settings.maxToolRounds) return {
-				block: true,
-				reason: `Background review reached max tool rounds (${settings.maxToolRounds}).`
-			};
-		},
-		afterToolCall: async () => {
-			toolRounds += 1;
-		}
+		getApiKey: (provider) => resolveProviderApiKeySync(provider) ?? getApiKeySync(provider) ?? ""
 	});
 	reviewAgent.state.messages = cloneMessageTail(mainAgent.state.messages, settings.maxHistoryMessages);
 	const timeoutMs = Math.min(settings.maxDurationMs, resolveAgentTurnTimeoutMs(getConfig()));
@@ -82,7 +102,7 @@ async function runBackgroundReviewTurn(params) {
 		await runAgentTurnWithTimeout(reviewAgent, async () => {
 			await reviewAgent.prompt({
 				role: "user",
-				content: userPrompt,
+				content: MEMORY_REVIEW_USER_PROMPT,
 				timestamp: Date.now()
 			});
 			await reviewAgent.waitForIdle();
@@ -91,30 +111,25 @@ async function runBackgroundReviewTurn(params) {
 		log.warn({
 			err,
 			sessionKey
-		}, "Background review turn failed or timed out");
-		aborted = true;
+		}, "User-understanding review failed or timed out");
 		reviewAgent.abort();
 		await reviewAgent.waitForIdle().catch(() => {});
 		return;
 	}
-	if (isAssistantTurnAborted(reviewAgent) || isAssistantTurnFailed(reviewAgent)) {
-		log.debug({ sessionKey }, "Background review produced aborted/failed assistant turn");
-		return;
-	}
-	const last = reviewAgent.state.messages;
-	for (let i = last.length - 1; i >= 0; i--) {
-		const msg = last[i];
-		if (msg.role === "assistant") {
-			const content = msg.content;
-			const trimmed = (Array.isArray(content) ? extractTextContent(content) : String(content)).trim();
-			if (trimmed && !/^nothing to save\.?$/i.test(trimmed)) log.info({
-				sessionKey,
-				preview: trimmed.slice(0, 120)
-			}, "Background review completed");
-			else log.debug({ sessionKey }, "Background review: nothing to save");
-			return;
-		}
-	}
+	if (isAssistantTurnAborted(reviewAgent) || isAssistantTurnFailed(reviewAgent)) return;
+	const candidates = parseUnderstandingCandidates(lastAssistantText(reviewAgent));
+	await memoryManager.applyUnderstandingCandidates(candidates, {
+		sessionKey,
+		sourceText: "Background review of the current session transcript",
+		reviewSource: "background"
+	});
+	log.debug({
+		sessionKey,
+		candidateCount: candidates.length
+	}, "User-understanding review completed");
+}
+async function runBackgroundReviewTurn(params) {
+	await runUnderstandingReview(params);
 }
 //#endregion
 export { runBackgroundReviewTurn };

package/dist/src/agent/background-review/run-background-review.js.map

@@ -1 +1 @@
-{"version":3,"file":"run-background-review.js","names":[],"sources":["../../../../src/agent/background-review/run-background-review.ts"],"sourcesContent":["import { Agent, type AgentMessage, type ThinkingLevel } from '@earendil-works/pi-agent-core';\nimport type { Api, Model } from '@earendil-works/pi-ai';\n\nimport type { Config } from '../../config/schema.js';\nimport { resolveProviderApiKeySync } from '../../auth/sync-provider-auth.js';\nimport { getApiKeySync } from '../../providers/index.js';\nimport { createExtensionAwareStreamFn } from '../../providers/extension-stream-bridge.js';\nimport { createLogger } from '../../utils/logger.js';\n\nimport { extractTextContent } from '../context/workspace.js';\nimport { shouldRegisterCuratedMemoryTool } from '../memory/memory-config.js';\nimport type { MemoryManager } from '../memory/manager.js';\nimport {\n  runAgentTurnWithTimeout,\n  resolveAgentTurnTimeoutMs,\n} from '../orchestration/run-agent-turn-with-timeout.js';\nimport {\n  isAssistantTurnAborted,\n  isAssistantTurnFailed,\n} from '../orchestration/llm-turn-retry.js';\nimport type { SkillManager } from '../skills/skill-manager.js';\nimport { createCuratedMemoryTool } from '../tools/curated-memory-tool.js';\nimport { createSkillManageTool } from '../tools/skill-manage-tool.js';\nimport { createSkillsListTool, createSkillViewTool } from '../tools/skills-tools.js';\nimport { wrapToolsWithProtection } from '../tools/executor.js';\n\nimport type { BackgroundReviewSettings } from './settings.js';\nimport {\n  COMBINED_REVIEW_USER_PROMPT,\n  MEMORY_REVIEW_USER_PROMPT,\n  REVIEW_SYSTEM_PROMPT,\n  SKILL_REVIEW_USER_PROMPT,\n} from './prompts.js';\n\nconst log = createLogger('BackgroundReview');\n\nfunction cloneMessageTail(messages: AgentMessage[], max: number): AgentMessage[] {\n  const tail = messages.length <= max ? messages : messages.slice(-max);\n  return JSON.parse(JSON.stringify(tail)) as AgentMessage[];\n}\n\nexport interface RunBackgroundReviewParams {\n  sessionKey: string;\n  mainAgent: Agent;\n  settings: BackgroundReviewSettings;\n  reviewMemory: boolean;\n  reviewSkills: boolean;\n  registeredToolNames: string[];\n  skillAllowlist?: string[];\n  workspacePath: string;\n  skillManager: SkillManager;\n  memoryManager: MemoryManager;\n  getConfig: () => Config | undefined;\n  onSkillsFilesystemMutate: () => void;\n}\n\nexport async function runBackgroundReviewTurn(params: RunBackgroundReviewParams): Promise<void> {\n  const {\n    sessionKey,\n    mainAgent,\n    settings,\n    reviewMemory,\n    reviewSkills,\n    registeredToolNames,\n    skillAllowlist,\n    workspacePath,\n    skillManager,\n    memoryManager,\n    getConfig,\n    onSkillsFilesystemMutate,\n  } = params;\n\n  const userPrompt =\n    reviewMemory && reviewSkills\n      ? COMBINED_REVIEW_USER_PROMPT\n      : reviewMemory\n        ? MEMORY_REVIEW_USER_PROMPT\n        : SKILL_REVIEW_USER_PROMPT;\n\n  const rawTools: any[] = [];\n\n  if (reviewMemory && shouldRegisterCuratedMemoryTool(getConfig())) {\n    rawTools.push(createCuratedMemoryTool(() => memoryManager));\n  }\n\n  if (reviewSkills) {\n    const ctx = () => ({ registeredToolNames, skillAllowlist });\n    rawTools.push(\n      createSkillsListTool({\n        getSkillManager: () => skillManager,\n        getSkillIndexingContext: ctx,\n      }),\n      createSkillViewTool({\n        getSkillManager: () => skillManager,\n        getSkillIndexingContext: ctx,\n      }),\n      createSkillManageTool({\n        getSkillManager: () => skillManager,\n        getWorkspace: () => workspacePath,\n        onSkillsFilesystemMutate,\n      }),\n    );\n  }\n\n  if (rawTools.length === 0) {\n    log.debug({ sessionKey }, 'Background review skipped: no tools registered for selected channels');\n    return;\n  }\n\n  const tools = wrapToolsWithProtection(rawTools, {});\n\n  const model = mainAgent.state.model as Model<Api>;\n  let toolRounds = 0;\n  let aborted = false;\n\n  const reviewAgent = new Agent({\n    initialState: {\n      systemPrompt: REVIEW_SYSTEM_PROMPT,\n      model,\n      thinkingLevel: 'off' as ThinkingLevel,\n      tools,\n      messages: [],\n    },\n    streamFn: createExtensionAwareStreamFn(),\n    getApiKey: (provider: string) =>\n      resolveProviderApiKeySync(provider) ?? getApiKeySync(provider) ?? '',\n    beforeToolCall: async () => {\n      if (aborted) {\n        return { block: true, reason: 'Background review aborted.' };\n      }\n      if (toolRounds >= settings.maxToolRounds) {\n        return {\n          block: true,\n          reason: `Background review reached max tool rounds (${settings.maxToolRounds}).`,\n        };\n      }\n      return undefined;\n    },\n    afterToolCall: async () => {\n      toolRounds += 1;\n      return undefined;\n    },\n  });\n\n  reviewAgent.state.messages = cloneMessageTail(mainAgent.state.messages, settings.maxHistoryMessages);\n\n  const timeoutMs = Math.min(settings.maxDurationMs, resolveAgentTurnTimeoutMs(getConfig()));\n\n  try {\n    await runAgentTurnWithTimeout(\n      reviewAgent,\n      async () => {\n        await reviewAgent.prompt({\n          role: 'user',\n          content: userPrompt,\n          timestamp: Date.now(),\n        });\n        await reviewAgent.waitForIdle();\n      },\n      timeoutMs,\n    );\n  } catch (err) {\n    log.warn({ err, sessionKey }, 'Background review turn failed or timed out');\n    aborted = true;\n    reviewAgent.abort();\n    await reviewAgent.waitForIdle().catch(() => {});\n    return;\n  }\n\n  if (isAssistantTurnAborted(reviewAgent) || isAssistantTurnFailed(reviewAgent)) {\n    log.debug({ sessionKey }, 'Background review produced aborted/failed assistant turn');\n    return;\n  }\n\n  const last = reviewAgent.state.messages;\n  for (let i = last.length - 1; i >= 0; i--) {\n    const msg = last[i];\n    if (msg.role === 'assistant') {\n      const content = msg.content;\n      const text = Array.isArray(content)\n        ? extractTextContent(content as Array<{ type: string; text?: string }>)\n        : String(content);\n      const trimmed = text.trim();\n      if (trimmed && !/^nothing to save\\.?$/i.test(trimmed)) {\n        log.info({ sessionKey, preview: trimmed.slice(0, 120) }, 'Background review completed');\n      } else {\n        log.debug({ sessionKey }, 'Background review: nothing to save');\n      }\n      return;\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;yBAI6E;gBACpB;aAEJ;AA2BrD,MAAM,MAAM,aAAa,mBAAmB;AAE5C,SAAS,iBAAiB,UAA0B,KAA6B;CAC/E,MAAM,OAAO,SAAS,UAAU,MAAM,WAAW,SAAS,MAAM,CAAC,IAAI;AACrE,QAAO,KAAK,MAAM,KAAK,UAAU,KAAK,CAAC;;AAkBzC,eAAsB,wBAAwB,QAAkD;CAC9F,MAAM,EACJ,YACA,WACA,UACA,cACA,cACA,qBACA,gBACA,eACA,cACA,eACA,WACA,6BACE;CAEJ,MAAM,aACJ,gBAAgB,eACZ,8BACA,eACE,4BACA;CAER,MAAM,WAAkB,EAAE;AAE1B,KAAI,gBAAgB,gCAAgC,WAAW,CAAC,CAC9D,UAAS,KAAK,8BAA8B,cAAc,CAAC;AAG7D,KAAI,cAAc;EAChB,MAAM,aAAa;GAAE;GAAqB;GAAgB;AAC1D,WAAS,KACP,qBAAqB;GACnB,uBAAuB;GACvB,yBAAyB;GAC1B,CAAC,EACF,oBAAoB;GAClB,uBAAuB;GACvB,yBAAyB;GAC1B,CAAC,EACF,sBAAsB;GACpB,uBAAuB;GACvB,oBAAoB;GACpB;GACD,CAAC,CACH;;AAGH,KAAI,SAAS,WAAW,GAAG;AACzB,MAAI,MAAM,EAAE,YAAY,EAAE,uEAAuE;AACjG;;CAGF,MAAM,QAAQ,wBAAwB,UAAU,EAAE,CAAC;CAEnD,MAAM,QAAQ,UAAU,MAAM;CAC9B,IAAI,aAAa;CACjB,IAAI,UAAU;CAEd,MAAM,cAAc,IAAI,MAAM;EAC5B,cAAc;GACZ,cAAc;GACd;GACA,eAAe;GACf;GACA,UAAU,EAAE;GACb;EACD,UAAU,8BAA8B;EACxC,YAAY,aACV,0BAA0B,SAAS,IAAI,cAAc,SAAS,IAAI;EACpE,gBAAgB,YAAY;AAC1B,OAAI,QACF,QAAO;IAAE,OAAO;IAAM,QAAQ;IAA8B;AAE9D,OAAI,cAAc,SAAS,cACzB,QAAO;IACL,OAAO;IACP,QAAQ,8CAA8C,SAAS,cAAc;IAC9E;;EAIL,eAAe,YAAY;AACzB,iBAAc;;EAGjB,CAAC;AAEF,aAAY,MAAM,WAAW,iBAAiB,UAAU,MAAM,UAAU,SAAS,mBAAmB;CAEpG,MAAM,YAAY,KAAK,IAAI,SAAS,eAAe,0BAA0B,WAAW,CAAC,CAAC;AAE1F,KAAI;AACF,QAAM,wBACJ,aACA,YAAY;AACV,SAAM,YAAY,OAAO;IACvB,MAAM;IACN,SAAS;IACT,WAAW,KAAK,KAAK;IACtB,CAAC;AACF,SAAM,YAAY,aAAa;KAEjC,UACD;UACM,KAAK;AACZ,MAAI,KAAK;GAAE;GAAK;GAAY,EAAE,6CAA6C;AAC3E,YAAU;AACV,cAAY,OAAO;AACnB,QAAM,YAAY,aAAa,CAAC,YAAY,GAAG;AAC/C;;AAGF,KAAI,uBAAuB,YAAY,IAAI,sBAAsB,YAAY,EAAE;AAC7E,MAAI,MAAM,EAAE,YAAY,EAAE,2DAA2D;AACrF;;CAGF,MAAM,OAAO,YAAY,MAAM;AAC/B,MAAK,IAAI,IAAI,KAAK,SAAS,GAAG,KAAK,GAAG,KAAK;EACzC,MAAM,MAAM,KAAK;AACjB,MAAI,IAAI,SAAS,aAAa;GAC5B,MAAM,UAAU,IAAI;GAIpB,MAAM,WAHO,MAAM,QAAQ,QAAQ,GAC/B,mBAAmB,QAAkD,GACrE,OAAO,QAAQ,EACE,MAAM;AAC3B,OAAI,WAAW,CAAC,wBAAwB,KAAK,QAAQ,CACnD,KAAI,KAAK;IAAE;IAAY,SAAS,QAAQ,MAAM,GAAG,IAAI;IAAE,EAAE,8BAA8B;OAEvF,KAAI,MAAM,EAAE,YAAY,EAAE,qCAAqC;AAEjE"}
+{"version":3,"file":"run-background-review.js","names":[],"sources":["../../../../src/agent/background-review/run-background-review.ts"],"sourcesContent":["import { Agent, type AgentMessage, type ThinkingLevel } from '@earendil-works/pi-agent-core';\nimport type { Api, Model } from '@earendil-works/pi-ai';\n\nimport type { Config } from '../../config/schema.js';\nimport { resolveProviderApiKeySync } from '../../auth/sync-provider-auth.js';\nimport { getApiKeySync } from '../../providers/index.js';\nimport { createExtensionAwareStreamFn } from '../../providers/extension-stream-bridge.js';\nimport { createLogger } from '../../utils/logger.js';\n\nimport { extractTextContent } from '../context/workspace.js';\nimport type { MemoryManager } from '../memory/manager.js';\nimport type { UnderstandingCandidate } from '../memory/understanding/types.js';\nimport {\n  runAgentTurnWithTimeout,\n  resolveAgentTurnTimeoutMs,\n} from '../orchestration/run-agent-turn-with-timeout.js';\nimport {\n  isAssistantTurnAborted,\n  isAssistantTurnFailed,\n} from '../orchestration/llm-turn-retry.js';\n\nimport type { BackgroundReviewSettings } from './settings.js';\nimport {\n  MEMORY_REVIEW_USER_PROMPT,\n  UNDERSTANDING_REVIEW_SYSTEM_PROMPT,\n} from './prompts.js';\n\nconst log = createLogger('BackgroundReview');\n\nfunction cloneMessageTail(messages: AgentMessage[], max: number): AgentMessage[] {\n  const tail = messages.length <= max ? messages : messages.slice(-max);\n  return JSON.parse(JSON.stringify(tail)) as AgentMessage[];\n}\n\nexport interface RunBackgroundReviewParams {\n  sessionKey: string;\n  mainAgent: Agent;\n  settings: BackgroundReviewSettings;\n  memoryManager: MemoryManager;\n  getConfig: () => Config | undefined;\n}\n\nconst ALLOWED_UNDERSTANDING_KINDS = new Set<UnderstandingCandidate['kind']>([\n  'preference', 'boundary', 'relationship', 'project_context', 'commitment', 'routine',\n  'personal_logistics', 'open_question', 'milestone', 'current_state', 'task_lesson',\n  'tool_preference', 'long_term_goal', 'derived_insight',\n]);\nconst ALLOWED_SENSITIVITIES = new Set<UnderstandingCandidate['sensitivity']>([\n  'normal', 'personal', 'secret', 'regulated',\n]);\n\nfunction lastAssistantText(agent: Agent): string {\n  for (let i = agent.state.messages.length - 1; i >= 0; i--) {\n    const message = agent.state.messages[i];\n    if (message.role !== 'assistant') continue;\n    return Array.isArray(message.content)\n      ? extractTextContent(message.content as Array<{ type: string; text?: string }>)\n      : String(message.content);\n  }\n  return '';\n}\n\nfunction parseUnderstandingCandidates(raw: string): UnderstandingCandidate[] {\n  const fenced = /```(?:json)?\\s*([\\s\\S]*?)```/i.exec(raw)?.[1];\n  const start = raw.indexOf('{');\n  const end = raw.lastIndexOf('}');\n  const candidateJson = fenced ?? (start >= 0 && end > start ? raw.slice(start, end + 1) : raw);\n  try {\n    const parsed = JSON.parse(candidateJson) as { candidates?: unknown };\n    if (!Array.isArray(parsed.candidates)) return [];\n    const output: UnderstandingCandidate[] = [];\n    for (const value of parsed.candidates.slice(0, 8)) {\n      if (!value || typeof value !== 'object') continue;\n      const item = value as Record<string, unknown>;\n      if (!ALLOWED_UNDERSTANDING_KINDS.has(item.kind as UnderstandingCandidate['kind'])) continue;\n      if (typeof item.content !== 'string' || item.content.trim().length < 4) continue;\n      const confidence = typeof item.confidence === 'number' ? item.confidence : 0.65;\n      const importance = typeof item.importance === 'number' ? item.importance : 0.5;\n      const durability = item.durability === 'ephemeral' || item.durability === 'recurring'\n        ? item.durability\n        : 'durable';\n      const sensitivity = ALLOWED_SENSITIVITIES.has(item.sensitivity as UnderstandingCandidate['sensitivity'])\n        ? item.sensitivity as UnderstandingCandidate['sensitivity']\n        : 'personal';\n      const disclosurePolicy = item.disclosurePolicy === 'silent' || item.disclosurePolicy === 'ask_before_reference'\n        ? item.disclosurePolicy\n        : 'referenceable';\n      output.push({\n        kind: item.kind as UnderstandingCandidate['kind'],\n        content: item.content.trim(),\n        confidence: Math.max(0, Math.min(1, confidence)),\n        importance: Math.max(0, Math.min(1, importance)),\n        explicitness: 'inferred',\n        durability,\n        sensitivity,\n        disclosurePolicy,\n        tags: Array.isArray(item.tags)\n          ? item.tags.filter((tag): tag is string => typeof tag === 'string').slice(0, 8)\n          : ['background-review'],\n      });\n    }\n    return output;\n  } catch {\n    return [];\n  }\n}\n\nasync function runUnderstandingReview(params: RunBackgroundReviewParams): Promise<void> {\n  const { sessionKey, mainAgent, settings, memoryManager, getConfig } = params;\n  const reviewAgent = new Agent({\n    initialState: {\n      systemPrompt: UNDERSTANDING_REVIEW_SYSTEM_PROMPT,\n      model: mainAgent.state.model as Model<Api>,\n      thinkingLevel: 'off' as ThinkingLevel,\n      tools: [],\n      messages: [],\n    },\n    streamFn: createExtensionAwareStreamFn(),\n    getApiKey: (provider: string) => resolveProviderApiKeySync(provider) ?? getApiKeySync(provider) ?? '',\n  });\n  reviewAgent.state.messages = cloneMessageTail(mainAgent.state.messages, settings.maxHistoryMessages);\n  const timeoutMs = Math.min(settings.maxDurationMs, resolveAgentTurnTimeoutMs(getConfig()));\n  try {\n    await runAgentTurnWithTimeout(reviewAgent, async () => {\n      await reviewAgent.prompt({ role: 'user', content: MEMORY_REVIEW_USER_PROMPT, timestamp: Date.now() });\n      await reviewAgent.waitForIdle();\n    }, timeoutMs);\n  } catch (err) {\n    log.warn({ err, sessionKey }, 'User-understanding review failed or timed out');\n    reviewAgent.abort();\n    await reviewAgent.waitForIdle().catch(() => {});\n    return;\n  }\n  if (isAssistantTurnAborted(reviewAgent) || isAssistantTurnFailed(reviewAgent)) return;\n  const candidates = parseUnderstandingCandidates(lastAssistantText(reviewAgent));\n  await memoryManager.applyUnderstandingCandidates(candidates, {\n    sessionKey,\n    sourceText: 'Background review of the current session transcript',\n    reviewSource: 'background',\n  });\n  log.debug({ sessionKey, candidateCount: candidates.length }, 'User-understanding review completed');\n}\n\nexport async function runBackgroundReviewTurn(params: RunBackgroundReviewParams): Promise<void> {\n  await runUnderstandingReview(params);\n}\n"],"mappings":"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"}

package/dist/src/agent/background-review/settings.d.ts

@@ -1,10 +1,10 @@
 import type { Config } from '../../config/schema.js';
 export interface BackgroundReviewSettings {
     enabled: boolean;
-    memoryNudgeInterval: number;
-    skillNudgeInterval: number;
-    maxToolRounds: number;
+    agentId?: string;
+    adaptiveCadence: boolean;
+    reviewIntervalTurns: number;
     maxHistoryMessages: number;
     maxDurationMs: number;
 }
-export declare function resolveBackgroundReviewSettings(_config: Config | undefined): BackgroundReviewSettings;
+export declare function resolveBackgroundReviewSettings(config: Config | undefined, sessionKey?: string): BackgroundReviewSettings;

package/dist/src/agent/background-review/settings.js

@@ -1,14 +1,29 @@
+import { resolveEffectiveAgentManifestForSession } from "../../config/agent-profile.js";
 //#region src/agent/background-review/settings.ts
-function resolveBackgroundReviewSettings(_config) {
-	const numberOrDefault = (value, fallback) => typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.trunc(value) : fallback;
-	return {
-		enabled: false,
-		memoryNudgeInterval: numberOrDefault(void 0, 10),
-		skillNudgeInterval: numberOrDefault(void 0, 10),
-		maxToolRounds: numberOrDefault(void 0, 8),
-		maxHistoryMessages: numberOrDefault(void 0, 80),
-		maxDurationMs: numberOrDefault(void 0, 12e4)
-	};
+const DEFAULT_SETTINGS = {
+	enabled: false,
+	adaptiveCadence: true,
+	reviewIntervalTurns: 10,
+	maxHistoryMessages: 80,
+	maxDurationMs: 12e4
+};
+function resolveBackgroundReviewSettings(config, sessionKey) {
+	if (!config) return DEFAULT_SETTINGS;
+	try {
+		const manifest = resolveEffectiveAgentManifestForSession(config, sessionKey);
+		const memory = manifest.memory;
+		const understanding = memory.understanding;
+		return {
+			enabled: (memory.mode === "confirmWrite" || memory.mode === "auto") && (understanding?.enabled ?? true),
+			agentId: manifest.id,
+			adaptiveCadence: understanding?.adaptiveCadence ?? true,
+			reviewIntervalTurns: understanding?.reviewIntervalTurns ?? DEFAULT_SETTINGS.reviewIntervalTurns,
+			maxHistoryMessages: understanding?.maxHistoryMessages ?? DEFAULT_SETTINGS.maxHistoryMessages,
+			maxDurationMs: understanding?.maxDurationMs ?? DEFAULT_SETTINGS.maxDurationMs
+		};
+	} catch {
+		return DEFAULT_SETTINGS;
+	}
 }
 //#endregion
 export { resolveBackgroundReviewSettings };