@xopcai/xopc 0.0.160 → 0.0.162

package/dist/src/storage/sqlite/migrations/runner.js

@@ -12,7 +12,7 @@ const log = createLogger("Sqlite:Migrations");
 /** Baseline schema version applied from schema.sql on first open. */
 const XOPC_DB_BASELINE_SCHEMA_VERSION = 11;
 /** Latest schema version this release supports (increment when adding migrations). */
-const XOPC_DB_SCHEMA_VERSION = 52;
+const XOPC_DB_SCHEMA_VERSION = 58;
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 function resolveMigrationsDir(override) {
 	if (override) return override;
@@ -46,7 +46,7 @@ function applySingleMigration(db, migration) {
 * Each step runs in its own transaction and updates schema_meta on success.
 */
 function applyPendingMigrations(db, options = {}) {
-	const targetVersion = options.targetVersion ?? 52;
+	const targetVersion = options.targetVersion ?? 58;
 	let currentVersion = readSchemaVersion(db);
 	if (currentVersion > targetVersion) throw new DatabaseSchemaTooNewError(currentVersion, targetVersion);
 	if (currentVersion >= targetVersion) return currentVersion;
@@ -62,7 +62,7 @@ function applyPendingMigrations(db, options = {}) {
 }
 /** Inspect schema version without mutating the database. */
 function inspectSchemaMigrationStatus(db, options = {}) {
-	const appVersion = options.targetVersion ?? 52;
+	const appVersion = options.targetVersion ?? 58;
 	const dbVersion = readSchemaVersion(db);
 	if (dbVersion > appVersion) return {
 		dbVersion,

package/dist/src/storage/sqlite/migrations/runner.ts

@@ -19,7 +19,7 @@ const log = createLogger('Sqlite:Migrations');
 export const XOPC_DB_BASELINE_SCHEMA_VERSION = 11;
 
 /** Latest schema version this release supports (increment when adding migrations). */
-export const XOPC_DB_SCHEMA_VERSION = 52;
+export const XOPC_DB_SCHEMA_VERSION = 58;
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 

package/dist/src/storage/sqlite/relationship-settings-repository.d.ts

@@ -0,0 +1,17 @@
+export type SupportMode = 'efficient' | 'coach' | 'companion' | 'auto';
+export interface RelationshipSettings {
+    supportMode: SupportMode;
+    proactiveEnabled: boolean;
+    quietStart?: string;
+    quietEnd?: string;
+    allowedTopics: string[];
+    blockedTopics: string[];
+    updatedAt: number;
+}
+export declare function getRelationshipSettings(): RelationshipSettings;
+export declare function updateRelationshipSettings(patch: Partial<Omit<RelationshipSettings, 'updatedAt'>>): RelationshipSettings;
+export declare function buildRelationshipPrompt(settings: RelationshipSettings): string;
+export declare function isProactiveSupportAllowed(settings: RelationshipSettings, input: {
+    now: Date;
+    topic: string;
+}): boolean;

package/dist/src/storage/sqlite/relationship-settings-repository.js

@@ -0,0 +1,64 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "./transaction.js";
+import { LOCAL_USER_ID } from "../../user-context/owner.js";
+//#region src/storage/sqlite/relationship-settings-repository.ts
+function fromRow(row) {
+	return {
+		supportMode: row.support_mode,
+		proactiveEnabled: row.proactive_enabled === 1,
+		...row.quiet_start ? { quietStart: row.quiet_start } : {},
+		...row.quiet_end ? { quietEnd: row.quiet_end } : {},
+		allowedTopics: JSON.parse(row.allowed_topics_json),
+		blockedTopics: JSON.parse(row.blocked_topics_json),
+		updatedAt: row.updated_at
+	};
+}
+function getRelationshipSettings() {
+	return fromRow(getSqliteDatabase().prepare(`SELECT support_mode, proactive_enabled, quiet_start, quiet_end,
+              allowed_topics_json, blocked_topics_json, updated_at
+       FROM relationship_settings WHERE owner_id = ?`).get(LOCAL_USER_ID));
+}
+function updateRelationshipSettings(patch) {
+	const next = {
+		...getRelationshipSettings(),
+		...patch,
+		updatedAt: Date.now()
+	};
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`UPDATE relationship_settings
+       SET support_mode = ?, proactive_enabled = ?, quiet_start = ?, quiet_end = ?,
+           allowed_topics_json = ?, blocked_topics_json = ?, updated_at = ?
+       WHERE owner_id = ?`).run(next.supportMode, Number(next.proactiveEnabled), next.quietStart ?? null, next.quietEnd ?? null, JSON.stringify(next.allowedTopics), JSON.stringify(next.blockedTopics), next.updatedAt, LOCAL_USER_ID);
+	});
+	return next;
+}
+function buildRelationshipPrompt(settings) {
+	return [
+		"## Support mode",
+		{
+			efficient: "Prioritize direct action and concise answers. Acknowledge emotion briefly only when it materially helps.",
+			coach: "Help the user clarify goals and move forward. Ask focused questions and turn reflection into practical next steps.",
+			companion: "Acknowledge the user’s experience before offering solutions. Do not rush advice; ask whether they want listening or action when unclear.",
+			auto: "Infer whether the user needs listening, validation, analysis, advice, or action. Ask one concise question when the need is ambiguous."
+		}[settings.supportMode],
+		"Never claim to have human feelings, encourage exclusivity or dependency, use guilt, or present yourself as a replacement for human relationships or professional care.",
+		"Treat inferred emotions as hypotheses, not facts. In high-risk situations, encourage timely support from trusted people or appropriate emergency/professional services."
+	].join("\n\n");
+}
+function isProactiveSupportAllowed(settings, input) {
+	if (!settings.proactiveEnabled) return false;
+	const topic = input.topic.trim().toLocaleLowerCase();
+	if (settings.blockedTopics.map((value) => value.toLocaleLowerCase()).includes(topic)) return false;
+	const allowed = settings.allowedTopics.map((value) => value.toLocaleLowerCase());
+	if (allowed.length > 0 && !allowed.includes(topic)) return false;
+	if (!settings.quietStart || !settings.quietEnd) return true;
+	const minutes = input.now.getHours() * 60 + input.now.getMinutes();
+	const toMinutes = (value) => {
+		const [hours, minute] = value.split(":").map(Number);
+		return hours * 60 + minute;
+	};
+	const start = toMinutes(settings.quietStart);
+	const end = toMinutes(settings.quietEnd);
+	return !(start <= end ? minutes >= start && minutes < end : minutes >= start || minutes < end);
+}
+//#endregion
+export { buildRelationshipPrompt, getRelationshipSettings, isProactiveSupportAllowed, updateRelationshipSettings };

package/dist/src/storage/sqlite/schema.js

@@ -31,7 +31,7 @@ function ensureXopcDatabaseSchema(db) {
 		bootstrapFreshDatabase(db);
 		currentVersion = 11;
 	}
-	applyPendingMigrations(db, { targetVersion: 52 });
+	applyPendingMigrations(db, { targetVersion: 58 });
 }
 //#endregion
 export { SCHEMA_META_SCHEMA_VERSION_KEY, XOPC_DB_BASELINE_SCHEMA_VERSION, XOPC_DB_SCHEMA_VERSION, ensureSchemaMetaTable, ensureXopcDatabaseSchema, readSchemaVersion, readSchemaVersionForTest, setSchemaVersion };

package/dist/src/storage/sqlite/schema.sql

@@ -724,3 +724,49 @@ CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_reference_consents_pending
 
 CREATE INDEX IF NOT EXISTS idx_memory_reference_consents_resolution
   ON memory_reference_consents(record_id, status, session_key, expires_at);
+
+CREATE TABLE IF NOT EXISTS browser_recipes (
+  recipe_id TEXT PRIMARY KEY,
+  revision INTEGER NOT NULL,
+  name TEXT NOT NULL,
+  description TEXT,
+  status TEXT NOT NULL CHECK (status IN ('published', 'disabled')),
+  yaml_source TEXT NOT NULL,
+  risk_level TEXT NOT NULL CHECK (risk_level IN ('read_only', 'account_write', 'sensitive')),
+  domains_json TEXT NOT NULL,
+  created_at_ms INTEGER NOT NULL,
+  updated_at_ms INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS browser_recipe_runs (
+  run_id TEXT PRIMARY KEY,
+  recipe_id TEXT NOT NULL,
+  recipe_revision INTEGER NOT NULL,
+  recipe_yaml TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('queued', 'running', 'succeeded', 'failed', 'cancelled')),
+  args_json TEXT NOT NULL,
+  result_json TEXT,
+  error TEXT,
+  created_at_ms INTEGER NOT NULL,
+  started_at_ms INTEGER,
+  ended_at_ms INTEGER,
+  duration_ms INTEGER,
+  FOREIGN KEY (recipe_id) REFERENCES browser_recipes(recipe_id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_browser_recipe_runs_recipe_created
+  ON browser_recipe_runs(recipe_id, created_at_ms DESC);
+
+CREATE TABLE IF NOT EXISTS browser_recipe_run_events (
+  event_id TEXT PRIMARY KEY,
+  run_id TEXT NOT NULL,
+  seq INTEGER NOT NULL,
+  type TEXT NOT NULL,
+  data_json TEXT,
+  created_at_ms INTEGER NOT NULL,
+  UNIQUE(run_id, seq),
+  FOREIGN KEY (run_id) REFERENCES browser_recipe_runs(run_id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_browser_recipe_run_events_run_seq
+  ON browser_recipe_run_events(run_id, seq ASC);

package/dist/src/storage/sqlite/task-outcome-repository.d.ts

@@ -0,0 +1,90 @@
+import { type TaskFailureCode, type TaskFailurePhase, type TaskRecoveryAction, type TaskVerification } from '../../agent/outcomes/task-verifier.js';
+export type TaskOutcomeStatus = 'running' | 'succeeded' | 'failed' | 'cancelled';
+export type TaskFeedbackOutcome = 'helpful' | 'not_helpful';
+export interface TaskContract {
+    objective: string;
+    deliverables: string[];
+    acceptanceCriteria: string[];
+    constraints: string[];
+    approvalRequired: string[];
+}
+export interface TaskEvidence {
+    kind: 'artifact' | 'test' | 'state' | 'source';
+    title: string;
+    summary: string;
+    uri?: string;
+    verifies?: string[];
+}
+export interface TaskOutcome {
+    runId: string;
+    sessionKey: string;
+    channel: string;
+    objective: string;
+    status: TaskOutcomeStatus;
+    summary?: string;
+    contract?: TaskContract;
+    evidence: TaskEvidence[];
+    verification: TaskVerification;
+    failure?: {
+        code: TaskFailureCode;
+        phase: TaskFailurePhase;
+        recoveryAction: TaskRecoveryAction;
+    };
+    feedback?: {
+        outcome: TaskFeedbackOutcome;
+        reason?: string;
+        needsCorrection?: boolean;
+        supportFit?: boolean;
+    };
+    startedAt: number;
+    completedAt?: number;
+    updatedAt: number;
+}
+export interface TaskOutcomeMetrics {
+    total: number;
+    completed: number;
+    succeeded: number;
+    verified: number;
+    helpful: number;
+    notHelpful: number;
+    completionRate: number;
+    successRate: number;
+    verificationRate: number;
+    helpfulRate: number;
+}
+export declare function startTaskOutcome(input: {
+    runId: string;
+    sessionKey: string;
+    channel: string;
+    objective: string;
+    now?: number;
+}): TaskOutcome;
+export declare function completeTaskOutcome(input: {
+    runId: string;
+    status: Exclude<TaskOutcomeStatus, 'running'>;
+    summary: string;
+    now?: number;
+}): TaskOutcome | undefined;
+export declare function updateTaskOutcome(input: {
+    runId: string;
+    contract?: TaskContract;
+    evidence?: TaskEvidence[];
+    summary?: string;
+    now?: number;
+}): TaskOutcome | undefined;
+export declare function setTaskOutcomeFeedback(input: {
+    sessionKey: string;
+    assistantTimestamp: number;
+    outcome: TaskFeedbackOutcome;
+    reason?: string;
+    needsCorrection?: boolean;
+    supportFit?: boolean;
+    now?: number;
+}): TaskOutcome | undefined;
+export declare function getTaskOutcome(runId: string): TaskOutcome | undefined;
+export declare function findTaskOutcomeForAssistant(sessionKey: string, assistantTimestamp: number): TaskOutcome | undefined;
+export declare function listTaskOutcomes(input?: {
+    sessionKey?: string;
+    limit?: number;
+}): TaskOutcome[];
+export declare function summarizeTaskOutcomes(): TaskOutcomeMetrics;

package/dist/src/storage/sqlite/task-outcome-repository.js

@@ -0,0 +1,138 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "./transaction.js";
+import { diagnoseTaskFailure, verifyTaskCompletion } from "../../agent/outcomes/task-verifier.js";
+//#region src/storage/sqlite/task-outcome-repository.ts
+function fromRow(row) {
+	const contract = row.contract_json ? JSON.parse(row.contract_json) : void 0;
+	const evidence = JSON.parse(row.evidence_json);
+	const feedback = row.feedback_outcome ? {
+		outcome: row.feedback_outcome,
+		...row.feedback_reason ? { reason: row.feedback_reason } : {},
+		...row.needs_correction === null ? {} : { needsCorrection: row.needs_correction === 1 },
+		...row.support_fit === null ? {} : { supportFit: row.support_fit === 1 }
+	} : void 0;
+	return {
+		runId: row.run_id,
+		sessionKey: row.session_key,
+		channel: row.channel,
+		objective: row.objective,
+		status: row.status,
+		...row.summary ? { summary: row.summary } : {},
+		...contract ? { contract } : {},
+		evidence,
+		verification: {
+			...JSON.parse(row.verification_json),
+			status: row.verification_status
+		},
+		...row.failure_code && row.failure_phase && row.recovery_action ? { failure: {
+			code: row.failure_code,
+			phase: row.failure_phase,
+			recoveryAction: row.recovery_action
+		} } : {},
+		...feedback ? { feedback } : {},
+		startedAt: row.started_at,
+		...row.completed_at === null ? {} : { completedAt: row.completed_at },
+		updatedAt: row.updated_at
+	};
+}
+const SELECT_COLUMNS = `run_id, session_key, channel, objective, status, summary,
+  contract_json, evidence_json, feedback_outcome, feedback_reason,
+  needs_correction, support_fit, started_at, completed_at, updated_at,
+  verification_status, verification_json, failure_code, failure_phase, recovery_action`;
+function startTaskOutcome(input) {
+	const now = input.now ?? Date.now();
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`INSERT INTO task_outcomes (
+        run_id, session_key, channel, objective, status, started_at, updated_at
+      ) VALUES (?, ?, ?, ?, 'running', ?, ?)`).run(input.runId, input.sessionKey, input.channel, input.objective, now, now);
+	});
+	return getTaskOutcome(input.runId);
+}
+function completeTaskOutcome(input) {
+	const now = input.now ?? Date.now();
+	const current = getTaskOutcome(input.runId);
+	if (!current) return void 0;
+	const verification = verifyTaskCompletion({
+		status: input.status,
+		acceptanceCriteria: current.contract?.acceptanceCriteria ?? [],
+		evidence: current.evidence
+	});
+	const failure = input.status === "succeeded" ? void 0 : diagnoseTaskFailure({
+		status: input.status,
+		summary: input.summary
+	});
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`UPDATE task_outcomes
+       SET status = ?, summary = ?, completed_at = ?, updated_at = ?,
+           verification_status = ?, verification_json = ?, failure_code = ?,
+           failure_phase = ?, recovery_action = ?
+       WHERE run_id = ?`).run(input.status, input.summary, now, now, verification.status, JSON.stringify({ checks: verification.checks }), failure?.code ?? null, failure?.phase ?? null, failure?.recoveryAction ?? null, input.runId);
+	});
+	return getTaskOutcome(input.runId);
+}
+function updateTaskOutcome(input) {
+	const current = getTaskOutcome(input.runId);
+	if (!current) return void 0;
+	const now = input.now ?? Date.now();
+	const contract = input.contract === void 0 ? current.contract : input.contract;
+	const evidence = input.evidence === void 0 ? current.evidence : input.evidence;
+	const summary = input.summary === void 0 ? current.summary : input.summary;
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`UPDATE task_outcomes
+       SET contract_json = ?, evidence_json = ?, summary = ?, updated_at = ?
+       WHERE run_id = ?`).run(contract ? JSON.stringify(contract) : null, JSON.stringify(evidence), summary ?? null, now, input.runId);
+	});
+	return getTaskOutcome(input.runId);
+}
+function setTaskOutcomeFeedback(input) {
+	const matched = findTaskOutcomeForAssistant(input.sessionKey, input.assistantTimestamp);
+	if (!matched) return void 0;
+	const now = input.now ?? Date.now();
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`UPDATE task_outcomes
+       SET feedback_outcome = ?, feedback_reason = ?, needs_correction = ?, support_fit = ?, updated_at = ?
+       WHERE run_id = ?`).run(input.outcome, input.reason ?? null, input.needsCorrection === void 0 ? null : Number(input.needsCorrection), input.supportFit === void 0 ? null : Number(input.supportFit), now, matched.runId);
+	});
+	return getTaskOutcome(matched.runId);
+}
+function getTaskOutcome(runId) {
+	const row = getSqliteDatabase().prepare(`SELECT ${SELECT_COLUMNS} FROM task_outcomes WHERE run_id = ?`).get(runId);
+	return row ? fromRow(row) : void 0;
+}
+function findTaskOutcomeForAssistant(sessionKey, assistantTimestamp) {
+	const row = getSqliteDatabase().prepare(`SELECT ${SELECT_COLUMNS}
+       FROM task_outcomes
+       WHERE session_key = ?
+         AND started_at <= ?
+       ORDER BY started_at DESC
+       LIMIT 1`).get(sessionKey, assistantTimestamp);
+	return row ? fromRow(row) : void 0;
+}
+function listTaskOutcomes(input = {}) {
+	const limit = Math.max(1, Math.min(100, Math.floor(input.limit ?? 50)));
+	return (input.sessionKey ? getSqliteDatabase().prepare(`SELECT ${SELECT_COLUMNS} FROM task_outcomes WHERE session_key = ? ORDER BY started_at DESC LIMIT ?`).all(input.sessionKey, limit) : getSqliteDatabase().prepare(`SELECT ${SELECT_COLUMNS} FROM task_outcomes ORDER BY started_at DESC LIMIT ?`).all(limit)).map((row) => fromRow(row));
+}
+function summarizeTaskOutcomes() {
+	const row = getSqliteDatabase().prepare(`SELECT
+        COUNT(*) AS total,
+        SUM(CASE WHEN status != 'running' THEN 1 ELSE 0 END) AS completed,
+        SUM(CASE WHEN status = 'succeeded' THEN 1 ELSE 0 END) AS succeeded,
+        SUM(CASE WHEN verification_status = 'passed' THEN 1 ELSE 0 END) AS verified,
+        SUM(CASE WHEN feedback_outcome = 'helpful' THEN 1 ELSE 0 END) AS helpful,
+        SUM(CASE WHEN feedback_outcome = 'not_helpful' THEN 1 ELSE 0 END) AS not_helpful
+       FROM task_outcomes`).get();
+	const rated = row.helpful + row.not_helpful;
+	return {
+		total: row.total,
+		completed: row.completed,
+		succeeded: row.succeeded,
+		verified: row.verified,
+		helpful: row.helpful,
+		notHelpful: row.not_helpful,
+		completionRate: row.total ? row.completed / row.total : 0,
+		successRate: row.completed ? row.succeeded / row.completed : 0,
+		verificationRate: row.completed ? row.verified / row.completed : 0,
+		helpfulRate: rated ? row.helpful / rated : 0
+	};
+}
+//#endregion
+export { completeTaskOutcome, findTaskOutcomeForAssistant, getTaskOutcome, listTaskOutcomes, setTaskOutcomeFeedback, startTaskOutcome, summarizeTaskOutcomes, updateTaskOutcome };

package/dist/src/user-context/interaction-state.d.ts

@@ -0,0 +1,13 @@
+export type SupportNeed = 'listen' | 'clarify' | 'advise' | 'act' | 'unknown';
+export type InteractionStateSource = 'explicit' | 'inferred';
+export type RelationshipRepairStatus = 'none' | 'needed' | 'repaired';
+export interface InteractionStateSignal {
+    supportNeed: SupportNeed;
+    emotionHypothesis?: string;
+    confidence: number;
+    source: InteractionStateSource;
+    repairStatus: RelationshipRepairStatus;
+    repairReason?: string;
+}
+export declare function inferInteractionState(message: string): InteractionStateSignal;
+export declare function buildInteractionStatePrompt(signal: InteractionStateSignal): string;

package/dist/src/user-context/interaction-state.js

@@ -0,0 +1,69 @@
+//#region src/user-context/interaction-state.ts
+function inferInteractionState(message) {
+	const text = message.trim().toLocaleLowerCase();
+	if (/你.{0,6}(没|不).{0,6}(理解|懂)|别.{0,4}(建议|说教)|太(啰嗦|冷淡)|you (do not|don't) understand|stop giving (me )?advice|too verbose|too cold/.test(text)) return {
+		supportNeed: "listen",
+		confidence: .95,
+		source: "explicit",
+		repairStatus: "needed",
+		repairReason: message.trim().slice(0, 240)
+	};
+	if (/这样(好多|对了)|这次对了|谢谢.{0,6}(理解|调整)|that's better|you got it|this is better/.test(text)) return {
+		supportNeed: "unknown",
+		confidence: .9,
+		source: "explicit",
+		repairStatus: "repaired"
+	};
+	if (/不想听建议|只想.{0,4}(说|聊|倾诉)|听我说|no advice|just (listen|let me talk)/.test(text)) return {
+		supportNeed: "listen",
+		confidence: .95,
+		source: "explicit",
+		repairStatus: "none"
+	};
+	if (/帮我(梳理|理清|想清楚)|一起分析|help me (clarify|think through)|talk this through/.test(text)) return {
+		supportNeed: "clarify",
+		confidence: .9,
+		source: "explicit",
+		repairStatus: "none"
+	};
+	if (/你建议|怎么办|该怎么|给我建议|what should i do|what do you recommend|advice/.test(text)) return {
+		supportNeed: "advise",
+		confidence: .9,
+		source: "explicit",
+		repairStatus: "none"
+	};
+	if (/帮我(做|改|创建|实现|处理|发送)|请(完成|执行)|\b(build|fix|create|implement|send|run)\b/.test(text)) return {
+		supportNeed: "act",
+		confidence: .85,
+		source: "explicit",
+		repairStatus: "none"
+	};
+	const emotion = text.match(/(焦虑|难过|委屈|生气|疲惫|累|害怕|孤独|anxious|sad|angry|exhausted|afraid|lonely)/)?.[1];
+	if (emotion) return {
+		supportNeed: "listen",
+		emotionHypothesis: emotion,
+		confidence: .55,
+		source: "inferred",
+		repairStatus: "none"
+	};
+	return {
+		supportNeed: "unknown",
+		confidence: .3,
+		source: "inferred",
+		repairStatus: "none"
+	};
+}
+function buildInteractionStatePrompt(signal) {
+	const lines = ["## Current interaction state", {
+		listen: "Prioritize listening and acknowledgment. Do not rush into advice or an action list.",
+		clarify: "Help the user organize the situation with one focused question at a time.",
+		advise: "Offer a clear recommendation with concise reasoning and practical options.",
+		act: "Prioritize execution, state the intended outcome, and verify the result.",
+		unknown: "Do not assume the support needed. If it matters, ask one concise question."
+	}[signal.supportNeed]];
+	if (signal.emotionHypothesis) lines.push(`Possible current emotion: ${signal.emotionHypothesis} (confidence ${signal.confidence.toFixed(2)}). Treat this only as a hypothesis.`);
+	if (signal.repairStatus === "needed") lines.push("Relationship repair is needed: briefly acknowledge the specific mismatch, do not defend yourself, adjust immediately, and ask at most one concise question.");
+	return lines.join("\n\n");
+}
+//#endregion
+export { buildInteractionStatePrompt, inferInteractionState };

package/dist/src/user-context/memory-use-audit.d.ts

@@ -0,0 +1,10 @@
+import type { MemoryTraceEventPayload } from '../storage/sqlite/memory-records-repository.js';
+export declare function summarizeMemoryUseAudit(traces: MemoryTraceEventPayload[]): {
+    total: number;
+    injectTurns: number;
+    turnsUsingMemory: number;
+    selectedRecords: number;
+    helpful: number;
+    notHelpful: number;
+    skippedReasons: Record<string, number>;
+};

package/dist/src/user-context/memory-use-audit.js

@@ -0,0 +1,25 @@
+//#region src/user-context/memory-use-audit.ts
+function summarizeMemoryUseAudit(traces) {
+	const injects = traces.filter((trace) => trace.phase === "inject");
+	const skippedReasons = {};
+	let selectedRecords = 0;
+	let helpful = 0;
+	let notHelpful = 0;
+	for (const trace of injects) {
+		selectedRecords += trace.selectedRecordIds.length;
+		if (trace.skippedReason) skippedReasons[trace.skippedReason] = (skippedReasons[trace.skippedReason] ?? 0) + 1;
+		if (trace.feedback?.outcome === "helpful") helpful += 1;
+		if (trace.feedback?.outcome === "not_helpful" || trace.feedback?.outcome === "irrelevant") notHelpful += 1;
+	}
+	return {
+		total: traces.length,
+		injectTurns: injects.length,
+		turnsUsingMemory: injects.filter((trace) => trace.selectedRecordIds.length > 0).length,
+		selectedRecords,
+		helpful,
+		notHelpful,
+		skippedReasons
+	};
+}
+//#endregion
+export { summarizeMemoryUseAudit };

package/dist/src/user-context/personal-playbook.d.ts

@@ -0,0 +1,11 @@
+import type { MemoryRecord } from '../agent/memory/types.js';
+export declare const PERSONAL_PLAYBOOK_RULE_TAG = "playbook:rule";
+export declare const PERSONAL_PLAYBOOK_DISABLED_TAG = "playbook:disabled";
+export declare const PERSONAL_PLAYBOOK_ORDER_PREFIX = "playbook:order:";
+export interface PersonalPlaybookContext {
+    channel?: string;
+    supportNeed?: 'listen' | 'clarify' | 'advise' | 'act' | 'unknown';
+}
+export declare function personalPlaybookContext(record: MemoryRecord): PersonalPlaybookContext;
+export declare function patchPersonalPlaybookContextTags(tags: string[], patch: PersonalPlaybookContext): string[];
+export declare function buildPersonalPlaybookPrompt(records: MemoryRecord[], context?: PersonalPlaybookContext): string;

package/dist/src/user-context/personal-playbook.js

@@ -0,0 +1,41 @@
+//#region src/user-context/personal-playbook.ts
+const PERSONAL_PLAYBOOK_RULE_TAG = "playbook:rule";
+const PERSONAL_PLAYBOOK_DISABLED_TAG = "playbook:disabled";
+const PERSONAL_PLAYBOOK_ORDER_PREFIX = "playbook:order:";
+const PLAYBOOK_CHANNEL_PREFIX = "playbook:when:channel:";
+const PLAYBOOK_SUPPORT_PREFIX = "playbook:when:support:";
+function personalPlaybookContext(record) {
+	const channel = record.tags?.find((tag) => tag.startsWith(PLAYBOOK_CHANNEL_PREFIX))?.slice(22);
+	const supportNeed = record.tags?.find((tag) => tag.startsWith(PLAYBOOK_SUPPORT_PREFIX))?.slice(22);
+	return {
+		...channel ? { channel: decodeURIComponent(channel) } : {},
+		...supportNeed ? { supportNeed } : {}
+	};
+}
+function patchPersonalPlaybookContextTags(tags, patch) {
+	let next = tags;
+	if ("channel" in patch) {
+		next = next.filter((tag) => !tag.startsWith(PLAYBOOK_CHANNEL_PREFIX));
+		if (patch.channel) next.push(`${PLAYBOOK_CHANNEL_PREFIX}${encodeURIComponent(patch.channel)}`);
+	}
+	if ("supportNeed" in patch) {
+		next = next.filter((tag) => !tag.startsWith(PLAYBOOK_SUPPORT_PREFIX));
+		if (patch.supportNeed) next.push(`${PLAYBOOK_SUPPORT_PREFIX}${patch.supportNeed}`);
+	}
+	return [...new Set(next)];
+}
+function order(record) {
+	const tag = record.tags?.find((value) => value.startsWith(PERSONAL_PLAYBOOK_ORDER_PREFIX));
+	const parsed = tag ? Number.parseInt(tag.slice(15), 10) : NaN;
+	return Number.isFinite(parsed) ? parsed : 1e3;
+}
+function buildPersonalPlaybookPrompt(records, context = {}) {
+	const rules = records.filter((record) => record.status === "active").filter((record) => record.tags?.includes(PERSONAL_PLAYBOOK_RULE_TAG)).filter((record) => !record.tags?.includes(PERSONAL_PLAYBOOK_DISABLED_TAG)).filter((record) => {
+		const condition = personalPlaybookContext(record);
+		return (!condition.channel || condition.channel === context.channel) && (!condition.supportNeed || condition.supportNeed === context.supportNeed);
+	}).sort((left, right) => order(left) - order(right) || left.updatedAt.localeCompare(right.updatedAt));
+	if (!rules.length) return "";
+	return ["## Personal playbook", ...rules.map((record) => `- ${record.content}`)].join("\n");
+}
+//#endregion
+export { PERSONAL_PLAYBOOK_DISABLED_TAG, PERSONAL_PLAYBOOK_ORDER_PREFIX, PERSONAL_PLAYBOOK_RULE_TAG, buildPersonalPlaybookPrompt, patchPersonalPlaybookContextTags, personalPlaybookContext };

package/dist/src/user-context/projection.d.ts

@@ -22,11 +22,15 @@ export declare function projectUserContextRecord(record: MemoryRecord): {
     disclosurePolicy: import("../agent/memory/types.js").MemoryDisclosurePolicy;
     stability: import("../agent/memory/lifecycle.js").MemoryStabilityBand;
     stabilityScore: number;
+    confidence: number;
     reviewAt: string;
     reviewDue: boolean;
     evidenceCount: number;
     sourcePath: string;
     latestEvidenceAt: string;
+    validFrom: string;
+    validTo: string;
+    expiresAt: string;
 };
 export declare function isPersonalContextConnector(definition: ConnectorDefinition): boolean;
 export declare function recordsDerivedFromPersonalContextSource(records: MemoryRecord[], sourceInstanceId: string): MemoryRecord[];

package/dist/src/user-context/projection.js

@@ -57,11 +57,15 @@ function projectUserContextRecord(record) {
 		disclosurePolicy: record.disclosurePolicy,
 		stability: lifecycle.band,
 		stabilityScore: lifecycle.score,
+		confidence: record.confidence,
 		reviewAt: lifecycle.reviewAt,
 		reviewDue: lifecycle.reviewDue,
 		evidenceCount: record.evidence?.length ?? 0,
 		sourcePath: record.source.path,
-		latestEvidenceAt
+		latestEvidenceAt,
+		validFrom: record.validFrom,
+		validTo: record.validTo,
+		expiresAt: record.expiresAt
 	};
 }
 function isPersonalContextConnector(definition) {

package/dist/src/user-context/relationship-continuity.d.ts

@@ -0,0 +1,14 @@
+import type { MemoryRecord } from '../agent/memory/types.js';
+export declare const RELATIONSHIP_FOLLOW_UP_TAG = "relationship:follow-up";
+export interface RelationshipFollowUpRequest {
+    subject: string;
+    reviewAfter?: string;
+}
+export declare function extractExplicitRelationshipFollowUp(message: string, nowMs?: number): RelationshipFollowUpRequest | null;
+export declare function recordExplicitRelationshipFollowUp(input: {
+    sessionKey: string;
+    sourceAgentId: string;
+    message: string;
+    nowMs?: number;
+}): MemoryRecord | null;
+export declare function buildRelationshipContinuityPrompt(records: MemoryRecord[], nowMs?: number): string;