@xopcai/xopc 0.0.218 → 0.0.219

package/dist/src/tui/tui.js

@@ -2,10 +2,10 @@ import { version } from "../../package.js";
 import { resolveStateDir, resolveXopcDatabasePath } from "../config/paths-state.js";
 import { parseAgentSessionKey } from "../routing/session-key-utils.js";
 import { init_agent_session_key, normalizeAgentId } from "../routing/agent-session-key.js";
+import { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { init_paths } from "../config/paths.js";
 import { loadConfig } from "../config/loader.js";
 import { getAllModels, getAllProviders, getApiKey, init_providers, isProviderConfiguredSync } from "../providers/index.js";
-import { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { ProjectTrustStore, hasTrustRequiringProjectResources } from "../project-trust/trust-store.js";
 import { renderWorkflowFinalSummary, renderWorkflowPanel } from "../agent/workflow/snapshot.js";
 import { ensureStarterAgentsInitialized } from "../agent/starter-agents.js";
@@ -27,13 +27,14 @@ import { transcriptTreeEntryIdToRowNumber } from "./tui-transcript-tree.js";
 import { formatTuiCompactionResult, formatTuiShareResult } from "./tui-command-formatters.js";
 import { formatTuiStartupText } from "./tui-startup-text.js";
 import { createTuiCommandHandler, getSlashCommands } from "./tui-commands.js";
-import { GENERATED_TUI_SESSION_SHELL_PATCH, cleanupAbandonedTuiSessions, deleteGeneratedTuiSessionIfEmpty, hideLegacyEmptyTuiSessions, isGeneratedTuiSessionKey } from "./tui-empty-session-cleanup.js";
+import { GENERATED_TUI_SESSION_SHELL_PATCH, cleanupAbandonedTuiSessions, deleteGeneratedTuiSessionIfEmpty, isGeneratedTuiSessionKey } from "./tui-empty-session-cleanup.js";
 import { extensionCustomMessageContentToText, extensionCustomMessageToTurnText, extensionUserMessageContentToText } from "./tui-extension-user-message.js";
 import { resolveFdPath } from "./tui-fd-path.js";
 import { createBackspaceDeduper, drainAndStopTuiSafely, isIgnorableTuiStopError, resolveCtrlCAction, stopTuiSafely } from "./tui-lifecycle.js";
 import { createLocalShellRunner } from "./tui-local-shell.js";
 import { filterModelsForCycle, loadScopedModelRefs, saveScopedModelRefs } from "./tui-scoped-models.js";
 import { openModelPickerOverlay } from "./tui-model-picker.js";
+import { getTuiNewSessionPreferences, rememberTuiAgentModel, rememberTuiSessionContext, tuiGatewayPreferenceKey, tuiInitialAgentConfig } from "./tui-new-session-preferences.js";
 import { runTuiOAuthLogin } from "./tui-oauth-login.js";
 import { openAgentPickerOverlay, openProjectTrustOverlay, openReviewLauncherOverlay, openScopedModelsOverlay, openSessionPickerOverlay, openSessionTreeOverlay, openSettingsOverlay, openThinkingSelectorOverlay, openTimelineOverlay, openTranscriptTreeOverlay, openUserMessageForkOverlay } from "./tui-picker-overlay.js";
 import { formatActiveRunStatus, formatRunDuration } from "./tui-run-status-format.js";
@@ -195,6 +196,7 @@ async function runTui(opts) {
 		sessionMainKey
 	});
 	let tuiSettings = loadTuiSettings();
+	const newSessionPreferenceKey = isLocalMode ? tuiGatewayPreferenceKey() : tuiGatewayPreferenceKey(opts.url ?? "http://localhost:3120");
 	initTuiTheme({ themeId: opts.theme ?? tuiSettings.theme });
 	const state = createInitialState(startup.sessionKey);
 	const generatedStartupSessionKey = !opts.session?.trim() && isGeneratedTuiSessionKey(startup.sessionKey) ? startup.sessionKey : null;
@@ -722,7 +724,7 @@ async function runTui(opts) {
 	};
 	const runExtensionNewSession = async (options) => {
 		await abortActive({ clearUi: false });
-		await setSession(resolveSessionKey(`session-${randomUUID()}`));
+		await startPreferredNewSession("session");
 		await options?.setup?.(sessionSnapshot.manager());
 		await runWithReplacementContext(options?.withSession);
 		return { cancelled: false };
@@ -989,8 +991,34 @@ async function runTui(opts) {
 		sessionSnapshot,
 		onAgentIdChange: (agentId) => {
 			currentAgentId = agentId;
-		}
+		},
+		onSessionInfoChange: () => persistCurrentNewSessionContext()
 	});
+	const persistCurrentNewSessionContext = () => {
+		const current = getTuiNewSessionPreferences(tuiSettings, newSessionPreferenceKey);
+		const normalizedProjectId = state.sessionInfo.projectId?.trim() || null;
+		const currentProjectId = current.lastChatScope.kind === "project" ? current.lastChatScope.projectId : null;
+		if (current.selectedAgentId === currentAgentId && currentProjectId === normalizedProjectId) return;
+		tuiSettings = rememberTuiSessionContext(tuiSettings, newSessionPreferenceKey, {
+			agentId: currentAgentId,
+			projectId: normalizedProjectId
+		});
+		saveTuiSettings(tuiSettings);
+	};
+	const startPreferredNewSession = async (prefix = "tui") => {
+		const projectId = state.sessionInfo.projectId?.trim() || void 0;
+		await setSession(resolveSessionKey(`${prefix}-${randomUUID()}`));
+		const initialAgentConfig = tuiInitialAgentConfig(tuiSettings, newSessionPreferenceKey, currentAgentId);
+		if (initialAgentConfig || projectId) {
+			await client.patchSession(state.currentSessionKey, {
+				...initialAgentConfig,
+				...projectId ? { projectId } : {},
+				...isGeneratedTuiSessionKey(state.currentSessionKey) ? GENERATED_TUI_SESSION_SHELL_PATCH : {}
+			});
+			await refreshSessionInfo();
+		}
+		persistCurrentNewSessionContext();
+	};
 	const refreshSessionInfoWithBorder = async () => {
 		await refreshSessionInfo();
 		updateEditorBorderColor();
@@ -1115,6 +1143,14 @@ async function runTui(opts) {
 		try {
 			await client.patchSession(state.currentSessionKey, { thinkingLevel: level });
 			state.sessionInfo.thinkingLevel = level;
+			const currentModelRef = state.sessionInfo.modelProvider && state.sessionInfo.model ? `${state.sessionInfo.modelProvider}/${state.sessionInfo.model}` : state.sessionInfo.model;
+			if (currentModelRef) {
+				tuiSettings = rememberTuiAgentModel(tuiSettings, newSessionPreferenceKey, currentAgentId, {
+					modelRef: currentModelRef,
+					thinkingLevel: level
+				});
+				saveTuiSettings(tuiSettings);
+			}
 			await refreshSessionInfoWithBorder();
 			updateFooter();
 			chatLog.addStatus(theme.dim(`Thinking level: ${level}`));
@@ -1250,6 +1286,11 @@ async function runTui(opts) {
 			await client.patchSession(state.currentSessionKey, { model: trimmed });
 			state.sessionInfo.modelProvider = selected.provider;
 			state.sessionInfo.model = selected.id;
+			tuiSettings = rememberTuiAgentModel(tuiSettings, newSessionPreferenceKey, currentAgentId, {
+				modelRef: trimmed,
+				...state.sessionInfo.thinkingLevel ? { thinkingLevel: state.sessionInfo.thinkingLevel } : {}
+			});
+			saveTuiSettings(tuiSettings);
 			if (selected.contextWindow != null) state.sessionInfo.contextWindow = selected.contextWindow;
 			await refreshSessionInfoWithBorder();
 			updateFooter();
@@ -1706,6 +1747,10 @@ async function runTui(opts) {
 			await setSession(rawKey);
 			await refreshStartupResources();
 		},
+		newSession: async () => {
+			await startPreferredNewSession();
+			await refreshStartupResources();
+		},
 		resetSession: resetCurrentSession,
 		projectTrust: {
 			cwd: process.cwd(),
@@ -2158,7 +2203,15 @@ async function runTui(opts) {
 				const errorMessage = err instanceof Error ? err.message : String(err);
 				chatLog.addSystem(`Project not selected: ${errorMessage}`);
 			}
+			if (!opts.session?.trim() && isGeneratedTuiSessionKey(state.currentSessionKey)) {
+				const initialAgentConfig = tuiInitialAgentConfig(tuiSettings, newSessionPreferenceKey, currentAgentId);
+				if (initialAgentConfig || opts.thinking?.trim()) await client.patchSession(state.currentSessionKey, {
+					...initialAgentConfig,
+					...opts.thinking?.trim() ? { thinkingLevel: opts.thinking.trim() } : {}
+				});
+			}
 			await refreshSessionInfoWithBorder();
+			persistCurrentNewSessionContext();
 			try {
 				state.pendingInputCount = countPendingChatInputs((await client.getChatInputState(state.currentSessionKey)).inputs);
 			} catch {
@@ -2166,7 +2219,7 @@ async function runTui(opts) {
 			}
 			await refreshModelChoices();
 			await loadSessionHistory({ merge: true });
-			cleanupAbandonedTuiSessions(client, state.currentSessionKey).then(() => hideLegacyEmptyTuiSessions(client)).catch(() => {});
+			cleanupAbandonedTuiSessions(client, state.currentSessionKey).catch(() => {});
 			showStartupCardOnce();
 			refreshStartupResources().then(() => {
 				updateFooter();

package/dist/src/tunnel/frpc-process.js

@@ -45,6 +45,9 @@ function spawnFrpcProcess(frpcBin, configPath) {
 		loginReject = void 0;
 	});
 	child.on("exit", (code, signal) => {
+		loginReject?.(/* @__PURE__ */ new Error(`frpc exited before login (code=${code ?? "null"}, signal=${signal ?? "null"})`));
+		loginResolve = void 0;
+		loginReject = void 0;
 		for (const h of exitHandlers) h(code, signal);
 	});
 	if (!child.pid) throw new Error("Failed to spawn frpc process");

package/dist/src/tunnel/tunnel-service.d.ts

@@ -18,6 +18,7 @@ export declare class TunnelService extends EventEmitter {
     private lastError;
     private state;
     private reconnectAttempt;
+    private reconnectTask;
     private stopping;
     private startContext;
     private frpcDownload;
@@ -36,6 +37,7 @@ export declare class TunnelService extends EventEmitter {
     private resolveRegistration;
     private spawnAndWait;
     private scheduleReconnect;
+    private runReconnectLoop;
     private startHeartbeat;
     private clearHeartbeat;
 }

package/dist/src/tunnel/tunnel-service.js

@@ -36,6 +36,7 @@ var TunnelService = class extends EventEmitter {
 	lastError = null;
 	state = "disconnected";
 	reconnectAttempt = 0;
+	reconnectTask = null;
 	stopping = false;
 	startContext = null;
 	frpcDownload = null;
@@ -240,13 +241,14 @@ var TunnelService = class extends EventEmitter {
 	}
 	async spawnAndWait(frpcBin, configPath, broker, state, heartbeatIntervalMs) {
 		if (this.frpcHandle) {
-			await this.frpcHandle.kill();
+			const previousHandle = this.frpcHandle;
 			this.frpcHandle = null;
+			await previousHandle.kill();
 		}
 		const handle = spawnFrpcProcess(frpcBin, configPath);
 		this.frpcHandle = handle;
 		handle.onExit((code, signal) => {
-			if (this.stopping) return;
+			if (this.stopping || this.frpcHandle !== handle) return;
 			log.warn({
 				code,
 				signal,
@@ -261,33 +263,43 @@ var TunnelService = class extends EventEmitter {
 	}
 	async scheduleReconnect(frpcBin, configPath, broker, state, heartbeatIntervalMs) {
 		if (this.stopping) return;
+		if (this.reconnectTask) return this.reconnectTask;
+		const task = this.runReconnectLoop(frpcBin, configPath, broker, state, heartbeatIntervalMs).finally(() => {
+			if (this.reconnectTask === task) this.reconnectTask = null;
+		});
+		this.reconnectTask = task;
+		return task;
+	}
+	async runReconnectLoop(frpcBin, configPath, broker, state, heartbeatIntervalMs) {
 		const maxAttempts = 5;
-		this.reconnectAttempt += 1;
-		if (this.reconnectAttempt > maxAttempts) {
-			this.state = "error";
-			this.lastError = "frpc reconnect failed after maximum attempts";
-			log.error({ attempts: maxAttempts }, this.lastError);
-			this.emit("tunnel:error", this.lastError);
-			return;
-		}
-		this.state = "reconnecting";
-		this.setStartPhase("reconnecting_frpc", { publicUrl: state.publicUrl ?? null });
-		const delayMs = Math.min(16e3, 1e3 * 2 ** (this.reconnectAttempt - 1));
-		log.info({
-			attempt: this.reconnectAttempt,
-			delayMs
-		}, "Scheduling frpc reconnect");
-		await new Promise((r) => setTimeout(r, delayMs));
-		if (this.stopping) return;
-		try {
-			await this.spawnAndWait(frpcBin, configPath, broker, state, heartbeatIntervalMs);
-			this.clearStartProgress();
-			this.state = "connected";
-			this.reconnectAttempt = 0;
-			this.emit("tunnel:connected");
-		} catch (err) {
-			this.lastError = err instanceof Error ? err.message : String(err);
-			this.scheduleReconnect(frpcBin, configPath, broker, state, heartbeatIntervalMs);
+		while (!this.stopping) {
+			this.reconnectAttempt += 1;
+			if (this.reconnectAttempt > maxAttempts) {
+				this.state = "error";
+				this.lastError = "frpc reconnect failed after maximum attempts";
+				log.error({ attempts: maxAttempts }, this.lastError);
+				this.emit("tunnel:error", this.lastError);
+				return;
+			}
+			this.state = "reconnecting";
+			this.setStartPhase("reconnecting_frpc", { publicUrl: state.publicUrl ?? null });
+			const delayMs = Math.min(16e3, 1e3 * 2 ** (this.reconnectAttempt - 1));
+			log.info({
+				attempt: this.reconnectAttempt,
+				delayMs
+			}, "Scheduling frpc reconnect");
+			await new Promise((resolve) => setTimeout(resolve, delayMs));
+			if (this.stopping) return;
+			try {
+				await this.spawnAndWait(frpcBin, configPath, broker, state, heartbeatIntervalMs);
+				this.clearStartProgress();
+				this.state = "connected";
+				this.reconnectAttempt = 0;
+				this.emit("tunnel:connected");
+				return;
+			} catch (err) {
+				this.lastError = err instanceof Error ? err.message : String(err);
+			}
 		}
 	}
 	startHeartbeat(broker, state, intervalMs) {

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

@@ -0,0 +1,17 @@
+import type { ContextEvidence, UserContextScope } from './domain.js';
+export type ContextObjectView = 'current' | 'review' | 'history';
+export type ContextObjectOrigin = 'told_by_user' | 'observed' | 'inferred' | 'connected_source';
+export type ContextObject = {
+    objectType: 'profile' | 'rule' | 'focus' | 'understanding';
+    objectId: string;
+    status: string;
+    content: string;
+    scope: UserContextScope;
+    origin: ContextObjectOrigin;
+    confidence: number;
+    evidence: ContextEvidence[] | Array<{
+        sourceRef: string;
+    }>;
+    updatedAt: number;
+};
+export declare function listContextObjects(view: ContextObjectView): ContextObject[];

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

@@ -0,0 +1,99 @@
+import { getUserProfile, listCollaborationRules, listUnderstandingEvidence, listUnderstandings } from "../storage/sqlite/user-context-repository.js";
+import "../storage/sqlite/index.js";
+import { getUnderstandingSourceGrant, getUnderstandingSourceRun, listUserFocusEvidence, listUserFocuses } from "./sources/repository.js";
+//#region src/user-context/context-objects.ts
+function understandingOrigin(item, evidence) {
+	if (item.explicitness === "explicit") return "told_by_user";
+	if (evidence.some((entry) => entry.sourceType === "connector")) return "connected_source";
+	return item.explicitness === "observed" ? "observed" : "inferred";
+}
+function includesStatus(view, objectType, status) {
+	if (view === "current") return status === "active";
+	if (view === "review") return objectType === "understanding" ? [
+		"candidate",
+		"needs_review",
+		"stale"
+	].includes(status) : objectType === "focus" && status === "candidate";
+	return objectType === "understanding" ? ["archived", "rejected"].includes(status) : objectType === "focus" ? [
+		"paused",
+		"completed",
+		"rejected"
+	].includes(status) : objectType === "rule" && ["disabled", "archived"].includes(status);
+}
+function listContextObjects(view) {
+	const objects = [];
+	if (view === "current") {
+		const profile = getUserProfile();
+		const fields = [
+			["callName", profile.callName],
+			["role", profile.role],
+			["primaryGoal", profile.primaryGoal],
+			["pronouns", profile.pronouns],
+			["timezone", profile.timezone],
+			["locale", profile.locale]
+		];
+		for (const [field, value] of fields) {
+			if (!value) continue;
+			objects.push({
+				objectType: "profile",
+				objectId: field,
+				status: "active",
+				content: value,
+				scope: { type: "global" },
+				origin: "told_by_user",
+				confidence: 1,
+				evidence: [{ sourceRef: `user-profile://${field}` }],
+				updatedAt: profile.updatedAt
+			});
+		}
+	}
+	for (const rule of listCollaborationRules()) {
+		if (!includesStatus(view, "rule", rule.status)) continue;
+		objects.push({
+			objectType: "rule",
+			objectId: rule.id,
+			status: rule.status,
+			content: rule.statement,
+			scope: rule.scope,
+			origin: "told_by_user",
+			confidence: 1,
+			evidence: [{ sourceRef: `collaboration-rule://${rule.revisionId}` }],
+			updatedAt: rule.updatedAt
+		});
+	}
+	for (const focus of listUserFocuses()) {
+		if (!includesStatus(view, "focus", focus.status)) continue;
+		const sourceRun = focus.sourceRunId ? getUnderstandingSourceRun(focus.sourceRunId) : null;
+		const sourceGrant = sourceRun ? getUnderstandingSourceGrant(sourceRun.grantId) : null;
+		const linkedEvidence = listUserFocusEvidence(focus.id);
+		objects.push({
+			objectType: "focus",
+			objectId: focus.id,
+			status: focus.status,
+			content: `${focus.title}: ${focus.summary}`,
+			scope: focus.scope,
+			origin: focus.explicitness === "explicit" ? "told_by_user" : sourceGrant?.adapterId.startsWith("connector:") ? "connected_source" : focus.explicitness === "observed" ? "observed" : "inferred",
+			confidence: focus.confidence,
+			evidence: linkedEvidence.length ? linkedEvidence : focus.evidenceRefs.map((sourceRef) => ({ sourceRef })),
+			updatedAt: focus.updatedAt
+		});
+	}
+	for (const understanding of listUnderstandings()) {
+		if (!includesStatus(view, "understanding", understanding.status)) continue;
+		const evidence = listUnderstandingEvidence(understanding.id);
+		objects.push({
+			objectType: "understanding",
+			objectId: understanding.id,
+			status: understanding.status,
+			content: understanding.statement,
+			scope: understanding.scope,
+			origin: understandingOrigin(understanding, evidence),
+			confidence: understanding.confidence,
+			evidence,
+			updatedAt: understanding.updatedAt
+		});
+	}
+	return objects.sort((left, right) => right.updatedAt - left.updatedAt);
+}
+//#endregion
+export { listContextObjects };

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

@@ -53,13 +53,14 @@ export type CollaborationRule = {
     updatedAt: number;
 };
 export type PersonalizationItem = {
-    objectType: 'profile' | 'rule' | 'understanding';
+    objectType: 'profile' | 'rule' | 'focus' | 'understanding';
     objectId: string;
     versionId?: string;
     decision: 'selected' | 'irrelevant' | 'expired' | 'scope_mismatch' | 'sensitive' | 'needs_consent' | 'budget_exceeded' | 'conflicted' | 'disabled';
     reason: string;
     content: string;
     sourceLabel: string;
+    origin: 'told_by_user' | 'observed' | 'inferred' | 'connected_source';
     rank?: number;
     score?: number;
     injectedChars: number;
@@ -69,8 +70,19 @@ export type ContextEvidence = {
     sourceType: 'conversation' | 'connector' | 'user' | 'runtime';
     sourceInstanceId?: string;
     sourceRef: string;
+    sourceRunId?: string;
+    sourceItemId?: string;
+    sessionId?: string;
+    turnId?: string;
+    messageId?: string;
+    contentHash?: string;
+    retentionPolicy?: 'metadata_only' | 'derived_only' | 'bounded_raw';
+    processingPolicy?: 'local_only' | 'remote_allowed';
+    extractorId?: string;
+    extractorVersion?: string;
     redactedExcerpt?: string;
     trustLevel: 'owner' | 'trusted' | 'untrusted';
     observedAt: number;
+    ingestedAt: number;
     createdAt: number;
 };

package/dist/src/user-context/evaluation/harness.d.ts

@@ -0,0 +1,13 @@
+export type RetrievalEvaluationCase = {
+    id: string;
+    expectedIds: string[];
+    shouldAbstain?: boolean;
+    retrieve: () => string[];
+};
+export type RetrievalEvaluationMetrics = {
+    cases: number;
+    recallAtK: number;
+    precisionAtK: number;
+    abstentionAccuracy: number;
+};
+export declare function evaluateRetrievalCases(cases: RetrievalEvaluationCase[], k?: number): RetrievalEvaluationMetrics;

package/dist/src/user-context/evaluation/harness.js

@@ -0,0 +1,31 @@
+//#region src/user-context/evaluation/harness.ts
+function evaluateRetrievalCases(cases, k = 3) {
+	let expected = 0;
+	let recalled = 0;
+	let returned = 0;
+	let relevantReturned = 0;
+	let abstentionCases = 0;
+	let correctAbstentions = 0;
+	for (const item of cases) {
+		const results = [...new Set(item.retrieve())].slice(0, Math.max(1, k));
+		const expectedIds = new Set(item.expectedIds);
+		if (item.shouldAbstain) {
+			abstentionCases += 1;
+			if (results.length === 0) correctAbstentions += 1;
+			continue;
+		}
+		expected += expectedIds.size;
+		returned += results.length;
+		const matches = results.filter((id) => expectedIds.has(id)).length;
+		recalled += matches;
+		relevantReturned += matches;
+	}
+	return {
+		cases: cases.length,
+		recallAtK: expected ? recalled / expected : 1,
+		precisionAtK: returned ? relevantReturned / returned : 1,
+		abstentionAccuracy: abstentionCases ? correctAbstentions / abstentionCases : 1
+	};
+}
+//#endregion
+export { evaluateRetrievalCases };

package/dist/src/user-context/extraction/registry.d.ts

@@ -0,0 +1,26 @@
+import { type ContextExtractionRun } from '../../storage/sqlite/index.js';
+import type { UnderstandingKind } from '../domain.js';
+export type ExtractorId = 'explicit-command' | 'deterministic-signal' | 'transcript-synthesis' | 'connector-structural' | 'connector-semantic';
+export type ExtractorDefinition = {
+    id: ExtractorId;
+    version: string;
+    inputKinds: Array<'conversation' | 'connector' | 'file' | 'task'>;
+    requiredProcessingPolicy: 'local_only' | 'remote_allowed';
+    authorityCeiling: 'user_explicit' | 'user_observed' | 'system_inferred' | 'external_untrusted';
+    candidateKinds: UnderstandingKind[];
+    maxAutomaticStatus: 'active' | 'candidate';
+    timeoutMs: number;
+};
+export declare function getExtractorDefinition(id: ExtractorId): ExtractorDefinition;
+export declare function getRegisteredExtractorDefinition(id: string): ExtractorDefinition | undefined;
+export declare function extractionInputHash(input: string): string;
+export declare function claimRegisteredExtraction(input: {
+    extractorId: ExtractorId;
+    sourceRef: string;
+    contentForHash: string;
+    processingPolicy: 'local_only' | 'remote_allowed';
+    destination: ContextExtractionRun['destination'];
+}): {
+    run: ContextExtractionRun;
+    shouldExecute: boolean;
+};

package/dist/src/user-context/extraction/registry.js

@@ -0,0 +1,113 @@
+import { claimContextExtractionRun, finishContextExtractionRun } from "../../storage/sqlite/context-extraction-repository.js";
+import "../../storage/sqlite/index.js";
+import { createHash } from "node:crypto";
+//#region src/user-context/extraction/registry.ts
+const UNDERSTANDING_KINDS = [
+	"preference",
+	"boundary",
+	"relationship",
+	"routine",
+	"current_state",
+	"long_term_goal",
+	"project_context",
+	"task_lesson",
+	"derived_insight"
+];
+const DEFINITIONS = {
+	"explicit-command": {
+		id: "explicit-command",
+		version: "1",
+		inputKinds: ["conversation"],
+		requiredProcessingPolicy: "local_only",
+		authorityCeiling: "user_explicit",
+		candidateKinds: UNDERSTANDING_KINDS,
+		maxAutomaticStatus: "active",
+		timeoutMs: 500
+	},
+	"deterministic-signal": {
+		id: "deterministic-signal",
+		version: "1",
+		inputKinds: ["conversation", "task"],
+		requiredProcessingPolicy: "local_only",
+		authorityCeiling: "user_observed",
+		candidateKinds: UNDERSTANDING_KINDS,
+		maxAutomaticStatus: "candidate",
+		timeoutMs: 500
+	},
+	"transcript-synthesis": {
+		id: "transcript-synthesis",
+		version: "1",
+		inputKinds: ["conversation"],
+		requiredProcessingPolicy: "remote_allowed",
+		authorityCeiling: "system_inferred",
+		candidateKinds: UNDERSTANDING_KINDS,
+		maxAutomaticStatus: "candidate",
+		timeoutMs: 3e4
+	},
+	"connector-structural": {
+		id: "connector-structural",
+		version: "1",
+		inputKinds: ["connector"],
+		requiredProcessingPolicy: "local_only",
+		authorityCeiling: "external_untrusted",
+		candidateKinds: [
+			"project_context",
+			"current_state",
+			"routine"
+		],
+		maxAutomaticStatus: "candidate",
+		timeoutMs: 1e4
+	},
+	"connector-semantic": {
+		id: "connector-semantic",
+		version: "1",
+		inputKinds: ["connector", "file"],
+		requiredProcessingPolicy: "remote_allowed",
+		authorityCeiling: "external_untrusted",
+		candidateKinds: [
+			"preference",
+			"routine",
+			"current_state",
+			"project_context"
+		],
+		maxAutomaticStatus: "candidate",
+		timeoutMs: 3e4
+	}
+};
+function getExtractorDefinition(id) {
+	return DEFINITIONS[id];
+}
+function getRegisteredExtractorDefinition(id) {
+	return DEFINITIONS[id];
+}
+function extractionInputHash(input) {
+	return createHash("sha256").update(input).digest("hex");
+}
+function claimRegisteredExtraction(input) {
+	const definition = getExtractorDefinition(input.extractorId);
+	const claimed = claimContextExtractionRun({
+		sourceRef: input.sourceRef,
+		extractorId: definition.id,
+		extractorVersion: definition.version,
+		processingPolicy: input.processingPolicy,
+		destination: input.destination,
+		inputHash: extractionInputHash(input.contentForHash)
+	});
+	if (definition.requiredProcessingPolicy === "remote_allowed" && input.processingPolicy !== "remote_allowed") {
+		if (claimed.run.status === "running") finishContextExtractionRun({
+			runId: claimed.run.id,
+			status: "skipped",
+			errorCode: "processing_policy"
+		});
+		return {
+			run: {
+				...claimed.run,
+				status: "skipped"
+			},
+			shouldExecute: false
+		};
+	}
+	return claimed;
+}
+//#endregion
+export { claimRegisteredExtraction, extractionInputHash, getExtractorDefinition, getRegisteredExtractorDefinition };

package/dist/src/user-context/extraction/repair.d.ts

@@ -0,0 +1,19 @@
+export type ContextRepairFilter = {
+    runId?: string;
+    sourceRef?: string;
+    extractorId?: string;
+    extractorVersion?: string;
+    objectVersionId?: string;
+};
+export declare function repairExtractedContext(filter: ContextRepairFilter): {
+    runIds: string[];
+    repaired: Array<{
+        objectType: 'focus' | 'understanding';
+        objectId: string;
+    }>;
+    retained: Array<{
+        objectType: 'focus' | 'understanding';
+        objectId: string;
+        reason: string;
+    }>;
+};