@xopcai/xopc 0.0.159 → 0.0.160

package/dist/src/work-discovery/investigator.js

@@ -0,0 +1,358 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
+import { init_providers, resolveModel } from "../providers/index.js";
+import { completeWithResolvedCredentials } from "../providers/model-call.js";
+import { readWorkDiscoveryTextExcerpt, searchWorkDiscoveryText } from "./probe.js";
+import { appendWorkUnderstandingEvidence, createWorkUnderstandingInvestigation, getWorkUnderstandingInvestigationForRun, resetWorkUnderstandingInvestigation, updateWorkUnderstandingEvidenceObservation, updateWorkUnderstandingInvestigation } from "./investigation-repository.js";
+import { createHash } from "node:crypto";
+//#region src/work-discovery/investigator.ts
+init_schema();
+init_providers();
+init_logger();
+const log = createLogger("WorkInvestigator");
+const DEFAULT_WORK_INVESTIGATION_BUDGET = {
+	maxToolCalls: 6,
+	maxContentChars: 6e4,
+	maxDurationMs: 25e3
+};
+function extractText(content) {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content.map((part) => {
+		if (!part || typeof part !== "object") return "";
+		const item = part;
+		return item.type === "text" && typeof item.text === "string" ? item.text : "";
+	}).join("");
+}
+function parseObject(raw) {
+	const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(raw)?.[1];
+	const start = raw.indexOf("{");
+	const end = raw.lastIndexOf("}");
+	try {
+		const parsed = JSON.parse(fenced ?? (start >= 0 && end > start ? raw.slice(start, end + 1) : raw));
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+function stringList(value, max, maxChars) {
+	return Array.isArray(value) ? value.flatMap((item) => typeof item === "string" && item.trim() ? [item.trim().slice(0, maxChars)] : []).slice(0, max) : [];
+}
+function decisionFromValue(value, allowedPaths) {
+	if (!value || typeof value !== "object") return null;
+	const item = value;
+	const rawAction = item.action;
+	if (!rawAction || typeof rawAction !== "object") return null;
+	const actionValue = rawAction;
+	const reason = typeof actionValue.reason === "string" ? actionValue.reason.trim().slice(0, 300) : "";
+	let action = null;
+	if (actionValue.tool === "finish") action = {
+		tool: "finish",
+		reason: reason || "Enough evidence was collected."
+	};
+	else if (actionValue.tool === "read_text_excerpt") {
+		const relativePath = typeof actionValue.relativePath === "string" ? actionValue.relativePath.trim() : "";
+		if (allowedPaths.has(relativePath)) action = {
+			tool: "read_text_excerpt",
+			relativePath,
+			reason
+		};
+	} else if (actionValue.tool === "search_authorized_text") {
+		const query = typeof actionValue.query === "string" ? actionValue.query.trim().slice(0, 120) : "";
+		if (query.length >= 2) action = {
+			tool: "search_authorized_text",
+			query,
+			reason
+		};
+	}
+	if (!action) return null;
+	const evidenceSummaries = Array.isArray(item.evidenceSummaries) ? item.evidenceSummaries.flatMap((raw) => {
+		if (!raw || typeof raw !== "object") return [];
+		const summary = raw;
+		return typeof summary.evidenceId === "string" && typeof summary.observation === "string" ? [{
+			evidenceId: summary.evidenceId,
+			observation: summary.observation.trim().slice(0, 1e3)
+		}] : [];
+	}).slice(0, 20) : [];
+	return {
+		hypotheses: stringList(item.hypotheses, 6, 400),
+		questions: stringList(item.questions, 6, 400),
+		evidenceSummaries,
+		action
+	};
+}
+function metadataForModel(snapshot) {
+	return {
+		root: snapshot.root,
+		structure: {
+			sampledPaths: snapshot.structure.sampledPaths.slice(0, 200),
+			omittedPathCount: snapshot.structure.omittedPathCount
+		},
+		git: snapshot.git,
+		candidateDocuments: snapshot.documents.slice(0, 30).map((document) => ({
+			relativePath: document.relativePath,
+			modifiedAt: document.modifiedAt,
+			selectionReason: document.selectionReason,
+			truncated: document.truncated
+		}))
+	};
+}
+async function chooseAction(input) {
+	const modelRef = getAgentDefaultModelRef(input.config);
+	if (!modelRef) throw new Error("No default model configured");
+	const evidence = input.runtimeEvidence.slice(-16).map((item) => ({
+		evidenceId: item.record.id,
+		sourceType: item.record.sourceType,
+		sourceRef: item.record.sourceRef,
+		content: item.content.slice(0, 8e3)
+	}));
+	const prompt = [
+		"You are a bounded, read-only work investigation agent.",
+		"Your goal is to determine what the user is currently focused on and what work is being continuously advanced.",
+		"Form hypotheses, identify missing evidence, and choose exactly one next action.",
+		"Available actions are read_text_excerpt(relativePath), search_authorized_text(query), or finish.",
+		"Only choose relativePath values present in sampledPaths. Do not request secrets, credentials, personal traits, or unrelated private information.",
+		"Prefer evidence that distinguishes a current multi-day work thread from a one-off recent edit.",
+		"Use search only for a concise work topic visible in existing metadata or evidence.",
+		"Choose finish when evidence is sufficient or the remaining budget cannot materially improve the conclusion.",
+		"Return one JSON object with hypotheses, questions, evidenceSummaries, and action.",
+		"evidenceSummaries may paraphrase prior evidence by evidenceId; do not quote private content verbatim.",
+		`Remaining budget: ${input.toolCallsRemaining} tool calls, ${input.contentCharsRemaining} content characters.`,
+		JSON.stringify({
+			metadata: metadataForModel(input.snapshot),
+			evidence
+		})
+	].join("\n");
+	return decisionFromValue(parseObject(extractText((await completeWithResolvedCredentials(resolveModel(modelRef), { messages: [{
+		role: "user",
+		content: prompt,
+		timestamp: Date.now()
+	}] }, {
+		maxTokens: 1200,
+		temperature: .1,
+		signal: input.signal
+	})).content)), new Set(input.snapshot.structure.sampledPaths));
+}
+function contentHash(content) {
+	return createHash("sha256").update(content).digest("hex");
+}
+async function investigateWorkContext(input) {
+	const budget = {
+		maxToolCalls: Math.max(1, Math.min(12, input.budget?.maxToolCalls ?? DEFAULT_WORK_INVESTIGATION_BUDGET.maxToolCalls)),
+		maxContentChars: Math.max(4e3, Math.min(12e4, input.budget?.maxContentChars ?? DEFAULT_WORK_INVESTIGATION_BUDGET.maxContentChars)),
+		maxDurationMs: Math.max(100, Math.min(6e4, input.budget?.maxDurationMs ?? DEFAULT_WORK_INVESTIGATION_BUDGET.maxDurationMs))
+	};
+	const existing = getWorkUnderstandingInvestigationForRun(input.discoveryRunId);
+	let investigation = existing ? resetWorkUnderstandingInvestigation(existing.id, budget) : createWorkUnderstandingInvestigation({
+		discoveryRunId: input.discoveryRunId,
+		budget
+	});
+	investigation = updateWorkUnderstandingInvestigation(investigation.id, {
+		status: "investigating",
+		plan: {
+			hypotheses: [],
+			questions: []
+		},
+		toolCallCount: 0,
+		contentCharsRead: 0,
+		errorMessage: void 0,
+		completedAt: void 0
+	});
+	const startedAt = Date.now();
+	const deadlineSignal = AbortSignal.timeout(budget.maxDurationMs);
+	const investigationSignal = input.signal ? AbortSignal.any([input.signal, deadlineSignal]) : deadlineSignal;
+	const runtimeEvidence = [];
+	const documents = /* @__PURE__ */ new Map();
+	let degraded = false;
+	if (input.snapshot.git) {
+		const content = JSON.stringify(input.snapshot.git);
+		const record = appendWorkUnderstandingEvidence({
+			investigationId: investigation.id,
+			...input.sourceGrantId ? { sourceGrantId: input.sourceGrantId } : {},
+			projectId: input.projectId,
+			sourceType: "git",
+			sourceRef: "git://recent-state",
+			observation: `Collected recent Git state with ${input.snapshot.git.changedPaths.length} changed paths.`,
+			contentHash: contentHash(content),
+			collectedAt: Date.now(),
+			sensitivity: "normal"
+		});
+		runtimeEvidence.push({
+			record,
+			content
+		});
+	}
+	try {
+		while (investigation.toolCallCount < budget.maxToolCalls && investigation.contentCharsRead < budget.maxContentChars && Date.now() - startedAt < budget.maxDurationMs) {
+			if (input.signal?.aborted) throw new DOMException("Work investigation canceled", "AbortError");
+			let decision = null;
+			try {
+				decision = await (input.decisionProvider ?? chooseAction)({
+					config: input.config,
+					snapshot: input.snapshot,
+					runtimeEvidence,
+					toolCallsRemaining: budget.maxToolCalls - investigation.toolCallCount,
+					contentCharsRemaining: budget.maxContentChars - investigation.contentCharsRead,
+					signal: investigationSignal
+				});
+			} catch (error) {
+				if (input.signal?.aborted) throw error;
+				degraded = true;
+				log.debug({
+					err: error,
+					investigationId: investigation.id,
+					phase: "planning"
+				}, "Work investigation planning degraded");
+			}
+			if (!decision) break;
+			for (const summary of decision.evidenceSummaries) if (runtimeEvidence.some((item) => item.record.id === summary.evidenceId) && summary.observation) {
+				updateWorkUnderstandingEvidenceObservation(summary.evidenceId, summary.observation);
+				const runtime = runtimeEvidence.find((item) => item.record.id === summary.evidenceId);
+				if (runtime) runtime.record = {
+					...runtime.record,
+					observation: summary.observation
+				};
+			}
+			investigation = updateWorkUnderstandingInvestigation(investigation.id, { plan: {
+				hypotheses: decision.hypotheses,
+				questions: decision.questions
+			} });
+			if (decision.action.tool === "finish") break;
+			investigation = updateWorkUnderstandingInvestigation(investigation.id, { toolCallCount: investigation.toolCallCount + 1 });
+			const charsRemaining = budget.maxContentChars - investigation.contentCharsRead;
+			try {
+				if (decision.action.tool === "read_text_excerpt") {
+					const result = await readWorkDiscoveryTextExcerpt({
+						rootPath: input.rootPath,
+						relativePath: decision.action.relativePath,
+						maxChars: Math.min(12e3, charsRemaining),
+						signal: investigationSignal
+					});
+					if (result.excerpt) {
+						const record = appendWorkUnderstandingEvidence({
+							investigationId: investigation.id,
+							...input.sourceGrantId ? { sourceGrantId: input.sourceGrantId } : {},
+							projectId: input.projectId,
+							sourceType: "file",
+							sourceRef: result.relativePath,
+							observation: `Read a bounded excerpt from ${result.relativePath}.`,
+							contentHash: contentHash(result.excerpt),
+							observedAt: result.modifiedAt,
+							sensitivity: "normal"
+						});
+						runtimeEvidence.push({
+							record,
+							content: result.excerpt,
+							modifiedAt: result.modifiedAt
+						});
+						documents.set(result.relativePath, {
+							relativePath: result.relativePath,
+							modifiedAt: result.modifiedAt,
+							excerpt: result.excerpt,
+							truncated: result.truncated,
+							selectionReason: `agent_investigation: ${decision.action.reason}`.slice(0, 300)
+						});
+						investigation = updateWorkUnderstandingInvestigation(investigation.id, { contentCharsRead: investigation.contentCharsRead + result.excerpt.length });
+					}
+				} else {
+					const results = await searchWorkDiscoveryText({
+						rootPath: input.rootPath,
+						relativePaths: input.snapshot.structure.sampledPaths,
+						query: decision.action.query,
+						signal: investigationSignal
+					});
+					let charsRead = 0;
+					for (const result of results) {
+						const excerpt = result.excerpt.slice(0, Math.max(0, charsRemaining - charsRead));
+						if (!excerpt) break;
+						charsRead += excerpt.length;
+						const record = appendWorkUnderstandingEvidence({
+							investigationId: investigation.id,
+							...input.sourceGrantId ? { sourceGrantId: input.sourceGrantId } : {},
+							projectId: input.projectId,
+							sourceType: "file",
+							sourceRef: result.relativePath,
+							observation: `Found a bounded match for "${decision.action.query}" in ${result.relativePath}.`,
+							contentHash: contentHash(excerpt),
+							observedAt: result.modifiedAt,
+							sensitivity: "normal"
+						});
+						runtimeEvidence.push({
+							record,
+							content: excerpt,
+							modifiedAt: result.modifiedAt
+						});
+						documents.set(result.relativePath, {
+							relativePath: result.relativePath,
+							modifiedAt: result.modifiedAt,
+							excerpt,
+							truncated: true,
+							selectionReason: `agent_search: ${decision.action.reason}`.slice(0, 300)
+						});
+					}
+					investigation = updateWorkUnderstandingInvestigation(investigation.id, { contentCharsRead: investigation.contentCharsRead + charsRead });
+				}
+			} catch (error) {
+				if (input.signal?.aborted) throw error;
+				degraded = true;
+				log.debug({
+					err: error,
+					investigationId: investigation.id,
+					tool: decision.action.tool,
+					phase: "tool_execution"
+				}, "Work investigation tool call skipped");
+			}
+		}
+		if (documents.size === 0) {
+			degraded = true;
+			for (const document of input.snapshot.documents.slice(0, 6)) {
+				if (investigation.contentCharsRead >= budget.maxContentChars) break;
+				const excerpt = document.excerpt.slice(0, budget.maxContentChars - investigation.contentCharsRead);
+				if (!excerpt) continue;
+				const record = appendWorkUnderstandingEvidence({
+					investigationId: investigation.id,
+					...input.sourceGrantId ? { sourceGrantId: input.sourceGrantId } : {},
+					projectId: input.projectId,
+					sourceType: "file",
+					sourceRef: document.relativePath,
+					observation: `Used the bounded discovery excerpt from ${document.relativePath} as fallback evidence.`,
+					contentHash: contentHash(excerpt),
+					observedAt: document.modifiedAt,
+					sensitivity: "normal"
+				});
+				runtimeEvidence.push({
+					record,
+					content: excerpt,
+					modifiedAt: document.modifiedAt
+				});
+				documents.set(document.relativePath, {
+					...document,
+					excerpt,
+					selectionReason: "investigation_fallback"
+				});
+				investigation = updateWorkUnderstandingInvestigation(investigation.id, { contentCharsRead: investigation.contentCharsRead + excerpt.length });
+			}
+		}
+		investigation = updateWorkUnderstandingInvestigation(investigation.id, {
+			status: "completed",
+			completedAt: Date.now()
+		});
+		return {
+			investigation,
+			evidence: runtimeEvidence.map((item) => item.record),
+			documents: [...documents.values()],
+			degraded
+		};
+	} catch (error) {
+		const canceled = input.signal?.aborted || error instanceof DOMException && error.name === "AbortError";
+		updateWorkUnderstandingInvestigation(investigation.id, {
+			status: canceled ? "canceled" : "failed",
+			errorMessage: error instanceof Error ? error.message : String(error),
+			completedAt: Date.now()
+		});
+		throw error;
+	}
+}
+//#endregion
+export { DEFAULT_WORK_INVESTIGATION_BUDGET, investigateWorkContext };

package/dist/src/work-discovery/probe.d.ts

@@ -10,9 +10,31 @@ export declare function previewWorkDiscoveryRoot(rootPath: string): Promise<{
     fingerprint: {
         changedFileCount: number;
         recentAreas: string[];
+        contentSignature: string;
         generatedAt: number;
         branch?: string;
     };
 }>;
 export declare function probeWorkDiscoveryRoot(rootPath: string, signal?: AbortSignal): Promise<WorkContextSnapshot>;
+export declare function readWorkDiscoveryTextExcerpt(input: {
+    rootPath: string;
+    relativePath: string;
+    maxChars?: number;
+    signal?: AbortSignal;
+}): Promise<{
+    relativePath: string;
+    excerpt: string;
+    modifiedAt: number;
+    truncated: boolean;
+}>;
+export declare function searchWorkDiscoveryText(input: {
+    rootPath: string;
+    relativePaths: string[];
+    query: string;
+    signal?: AbortSignal;
+}): Promise<Array<{
+    relativePath: string;
+    excerpt: string;
+    modifiedAt: number;
+}>>;
 export declare function summarizeWorkContextSnapshot(snapshot: WorkContextSnapshot): WorkContextSnapshotSummary;

package/dist/src/work-discovery/probe.js

@@ -3,6 +3,7 @@ import "../projects/index.js";
 import { basename, extname, isAbsolute, relative, resolve, sep } from "node:path";
 import { constants } from "node:fs";
 import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
 import { access, lstat, readFile, readdir, realpath, stat } from "node:fs/promises";
 import { promisify } from "node:util";
 //#region src/work-discovery/probe.ts
@@ -169,6 +170,30 @@ async function gitInfo(root, signal) {
 		return;
 	}
 }
+async function metadataFingerprint(root, signal) {
+	const entries = [];
+	const visit = async (directory, depth) => {
+		if (depth > 2 || entries.length >= 300) return;
+		abortIfNeeded(signal);
+		const children = await readdir(directory, { withFileTypes: true }).catch(() => []);
+		for (const child of children.sort((left, right) => left.name.localeCompare(right.name))) {
+			if (entries.length >= 300) break;
+			if (isSecretFile(child.name)) continue;
+			if (child.isDirectory() && isExcludedDirectory(child.name)) continue;
+			const absolutePath = resolve(directory, child.name);
+			const relativePath = relative(root, absolutePath).replaceAll("\\", "/");
+			if (child.isDirectory()) {
+				await visit(absolutePath, depth + 1);
+				continue;
+			}
+			const info = await lstat(absolutePath).catch(() => null);
+			if (!info?.isFile() || info.isSymbolicLink()) continue;
+			entries.push(`${relativePath}\0${info.size}\0${Math.floor(info.mtimeMs)}`);
+		}
+	};
+	await visit(root, 0);
+	return createHash("sha256").update(entries.join("\n")).digest("hex");
+}
 async function canonicalWorkDiscoveryRoot(input) {
 	const trimmed = input.trim();
 	if (!trimmed || !isAbsolute(trimmed)) throw new Error("An absolute folder path is required");
@@ -181,6 +206,7 @@ async function previewWorkDiscoveryRoot(rootPath) {
 	const canonicalRootPath = await canonicalWorkDiscoveryRoot(rootPath);
 	const inference = inferProjectKind({ workspaceRoot: canonicalRootPath });
 	const git = await gitInfo(canonicalRootPath);
+	const contentSignature = await metadataFingerprint(canonicalRootPath);
 	const recentAreas = Array.from(new Set((git?.changedPaths ?? []).map((path) => {
 		const [first, second] = path.replaceAll("\\", "/").split("/");
 		return second ? `${first}/${second}` : first;
@@ -195,6 +221,7 @@ async function previewWorkDiscoveryRoot(rootPath) {
 			...git?.branch ? { branch: git.branch } : {},
 			changedFileCount: git?.changedPaths.length ?? 0,
 			recentAreas,
+			contentSignature,
 			generatedAt: Date.now()
 		}
 	};
@@ -329,6 +356,66 @@ async function probeWorkDiscoveryRoot(rootPath, signal) {
 		}
 	};
 }
+async function resolveWorkDiscoveryTextFile(rootPath, relativePath) {
+	const root = await canonicalWorkDiscoveryRoot(rootPath);
+	const normalized = relativePath.trim().replaceAll("\\", "/");
+	if (!normalized || isAbsolute(normalized) || normalized.split("/").includes("..")) throw new Error("A safe relative path is required");
+	if (normalized.split("/").some((segment) => isExcludedDirectory(segment)) || isSecretFile(basename(normalized))) throw new Error("The requested path is excluded by the scan policy");
+	if (isLikelyBinary(normalized) || METADATA_ONLY_EXTENSIONS.has(extname(normalized).toLowerCase())) throw new Error("The requested path is not a readable text file");
+	const resolvedPath = await realpath(resolve(root, normalized));
+	if (!isInsideRoot(root, resolvedPath)) throw new Error("The requested path is outside the approved folder");
+	const info = await lstat(resolvedPath);
+	if (!info.isFile() || info.size > MAX_FILE_BYTES * 4) throw new Error("The requested file is not eligible for investigation");
+	return {
+		root,
+		resolvedPath,
+		relativePath: relative(root, resolvedPath),
+		modifiedAt: info.mtimeMs
+	};
+}
+async function readWorkDiscoveryTextExcerpt(input) {
+	abortIfNeeded(input.signal);
+	const file = await resolveWorkDiscoveryTextFile(input.rootPath, input.relativePath);
+	const maxChars = Math.max(500, Math.min(2e4, input.maxChars ?? 8e3));
+	const buffer = await readFile(file.resolvedPath);
+	abortIfNeeded(input.signal);
+	if (buffer.includes(0)) throw new Error("The requested file appears to be binary");
+	const text = buffer.toString("utf8");
+	return {
+		relativePath: file.relativePath,
+		excerpt: text.slice(0, maxChars).trim(),
+		modifiedAt: file.modifiedAt,
+		truncated: text.length > maxChars
+	};
+}
+async function searchWorkDiscoveryText(input) {
+	const query = input.query.trim().slice(0, 120);
+	if (query.length < 2) throw new Error("Search query is too short");
+	const needle = query.toLocaleLowerCase();
+	const results = [];
+	for (const relativePath of input.relativePaths.slice(0, 120)) {
+		abortIfNeeded(input.signal);
+		try {
+			const file = await readWorkDiscoveryTextExcerpt({
+				rootPath: input.rootPath,
+				relativePath,
+				maxChars: 2e4,
+				signal: input.signal
+			});
+			const index = file.excerpt.toLocaleLowerCase().indexOf(needle);
+			if (index < 0) continue;
+			const start = Math.max(0, index - 300);
+			const end = Math.min(file.excerpt.length, index + query.length + 700);
+			results.push({
+				relativePath: file.relativePath,
+				excerpt: file.excerpt.slice(start, end).trim(),
+				modifiedAt: file.modifiedAt
+			});
+			if (results.length >= 8) break;
+		} catch {}
+	}
+	return results;
+}
 function summarizeWorkContextSnapshot(snapshot) {
 	return {
 		projectKind: snapshot.root.projectKind,
@@ -341,4 +428,4 @@ function summarizeWorkContextSnapshot(snapshot) {
 	};
 }
 //#endregion
-export { WORK_DISCOVERY_SCAN_POLICY_VERSION, canonicalWorkDiscoveryRoot, previewWorkDiscoveryRoot, probeWorkDiscoveryRoot, summarizeWorkContextSnapshot };
+export { WORK_DISCOVERY_SCAN_POLICY_VERSION, canonicalWorkDiscoveryRoot, previewWorkDiscoveryRoot, probeWorkDiscoveryRoot, readWorkDiscoveryTextExcerpt, searchWorkDiscoveryText, summarizeWorkContextSnapshot };

package/dist/src/work-discovery/service.d.ts

@@ -1,7 +1,7 @@
 import type { Config } from '../config/schema.js';
 import type { ProjectService } from '../projects/project-service.js';
 import type { SessionIndex } from '../session/manager.js';
-import type { WorkDiscoveryOnboardingState, WorkDiscoveryRecognitionDecision, WorkDiscoveryRun, WorkDiscoverySource } from './types.js';
+import type { WorkDiscoveryCandidate, WorkDiscoveryOnboardingState, WorkDiscoveryRecognitionDecision, WorkDiscoveryRun, WorkDiscoverySource } from './types.js';
 export interface WorkDiscoveryServiceOptions {
     projects: ProjectService;
     sessions: SessionIndex;
@@ -11,19 +11,128 @@ export interface WorkDiscoveryServiceOptions {
 export declare class WorkDiscoveryService {
     private readonly options;
     private readonly abortControllers;
+    private readonly candidateContexts;
     private readonly activity;
     constructor(options: WorkDiscoveryServiceOptions);
     isEnabled(): boolean;
     getOnboardingState(): WorkDiscoveryOnboardingState;
     dismissOnboarding(): WorkDiscoveryOnboardingState;
     getRun(id: string): WorkDiscoveryRun | null;
+    getInvestigation(runId: string): {
+        investigation: import("./types.js").WorkUnderstandingInvestigation;
+        evidence: import("./types.js").WorkUnderstandingEvidenceItem[];
+    };
+    listWorkThreads(options?: {
+        projectId?: string;
+        includeRejected?: boolean;
+        limit?: number;
+    }): import("./types.js").WorkUnderstandingThread[];
+    getWorkThread(id: string): import("./types.js").WorkUnderstandingThread;
+    getSourceLineage(sourceId: string): import("./governance.js").WorkUnderstandingSourceLineage;
+    deleteSourceDerivedData(sourceId: string): {
+        deletedMemoryRecords: number;
+        evidenceCount: number | bigint;
+        deletedThreads: number;
+        retainedThreads: number;
+    };
+    getUnderstandingMetrics(): {
+        completedInvestigations: number;
+        averageToolCalls: number;
+        activeThreads: number;
+        confirmedThreads: number;
+        recognitionConfirmationRate: number;
+        evidenceBySource: {
+            sourceType: string;
+            count: number;
+        }[];
+    };
+    updateWorkThread(input: {
+        id: string;
+        decision: 'confirmed' | 'corrected' | 'rejected' | 'paused' | 'completed';
+        correctedTitle?: string;
+        correctedSummary?: string;
+    }): import("./types.js").WorkUnderstandingThread;
+    discoverCandidates(signal?: AbortSignal): Promise<WorkDiscoveryCandidate[]>;
+    listDirectorySources(): import("./types.js").WorkDiscoveryDirectorySource[];
+    grantDirectorySource(rootPath: string): Promise<import("./types.js").WorkDiscoveryDirectorySource>;
+    checkDirectorySources(): Promise<any[]>;
+    refreshDirectorySourceIfChanged(input: {
+        id: string;
+        idempotencyKey: string;
+    }): Promise<{
+        changed: boolean;
+        refresh: import("./types.js").WorkDiscoverySourceRefresh;
+        reused?: undefined;
+        run?: undefined;
+    } | {
+        changed: boolean;
+        reused: boolean;
+        refresh: import("./types.js").WorkDiscoverySourceRefresh;
+        run: WorkDiscoveryRun;
+    } | {
+        changed: boolean;
+        run: WorkDiscoveryRun;
+        refresh: import("./types.js").WorkDiscoverySourceRefresh;
+        reused?: undefined;
+    }>;
+    revokeDirectorySource(id: string): import("./types.js").WorkDiscoveryDirectorySource;
+    importPersonalContext(rawItems: unknown[], signal?: AbortSignal, runId?: string): Promise<{
+        profileCandidates: {
+            status: "pending" | "accepted";
+            memoryRecordId: string;
+            id: string;
+            category: "role" | "focus" | "technology" | "workflow" | "preference";
+            statement: string;
+            confidence: "high" | "medium" | "low";
+            evidence: string[];
+        }[];
+        workThreads: import("./types.js").WorkUnderstandingThread[];
+        autoRemembered: {
+            status: "pending" | "accepted";
+            memoryRecordId: string;
+            id: string;
+            category: "role" | "focus" | "technology" | "workflow" | "preference";
+            statement: string;
+            confidence: "high" | "medium" | "low";
+            evidence: string[];
+        }[];
+    }>;
+    updatePersonalContextProfile(input: {
+        decisions: Array<{
+            memoryRecordId: string;
+            status: 'accepted' | 'edited' | 'rejected';
+            statement?: string;
+        }>;
+    }): {
+        memoryRecordId: string;
+        status: "rejected" | "accepted" | "edited";
+        statement: string;
+    }[];
+    rescanDirectorySource(input: {
+        id: string;
+        idempotencyKey: string;
+    }): Promise<WorkDiscoveryRun>;
+    startQuickRun(input: {
+        idempotencyKey: string;
+    }): Promise<WorkDiscoveryRun>;
     startRun(input: {
         rootPath: string;
         source: WorkDiscoverySource;
         idempotencyKey: string;
+        candidateContext?: WorkDiscoveryCandidate[];
     }): Promise<WorkDiscoveryRun>;
     private publish;
     private execute;
+    private persistProfileCandidates;
+    updateProfileCandidates(input: {
+        runId: string;
+        decisions: Array<{
+            id: string;
+            status: 'accepted' | 'edited' | 'rejected';
+            statement?: string;
+        }>;
+    }): WorkDiscoveryRun | null;
+    private preserveMemoryRecord;
     cancelRun(id: string): WorkDiscoveryRun | null;
     retryRun(id: string): WorkDiscoveryRun | null;
     submitRecognitionFeedback(input: {