@xopcai/xopc 0.0.277 → 0.0.282

package/dist/src/voice/audio/normalize.js

@@ -8,6 +8,12 @@ const TARGET_SAMPLE_RATE = 16e3;
 const MAX_DECODED_DURATION_SECONDS = 900;
 const MAX_DECODED_BYTES = TARGET_SAMPLE_RATE * 4 * MAX_DECODED_DURATION_SECONDS;
 const MAX_SEGMENTED_DURATION_SECONDS = 1800;
+const LOCAL_AUDIO_INPUT_OPTIONS = [
+	"-protocol_whitelist",
+	"file,pipe",
+	"-format_whitelist",
+	"wav,matroska,webm,ogg,mp3,mov"
+];
 var AudioNormalizationError = class extends Error {
 	code = "unsupported_audio_codec";
 	constructor(message, options) {
@@ -73,23 +79,30 @@ function runFfmpeg(args, options = {}) {
 		let outputBytes = 0;
 		let errorBytes = 0;
 		let settled = false;
+		let terminationError;
+		let killTimer;
 		const finish = (error) => {
 			if (settled) return;
 			settled = true;
+			if (killTimer) clearTimeout(killTimer);
 			options.signal?.removeEventListener("abort", abort);
 			if (error) reject(error);
 			else resolve(Buffer.concat(stdout));
 		};
-		const abort = () => {
+		const terminate = (error) => {
+			if (terminationError || settled) return;
+			terminationError = error;
 			child.kill("SIGTERM");
-			finish(new AudioNormalizationError("Audio decoding was cancelled"));
+			killTimer = setTimeout(() => child.kill("SIGKILL"), 2e3);
+			killTimer.unref();
 		};
+		const abort = () => terminate(new AudioNormalizationError("Audio decoding was cancelled"));
 		options.signal?.addEventListener("abort", abort, { once: true });
 		child.stdout.on("data", (chunk) => {
+			if (terminationError) return;
 			outputBytes += chunk.length;
 			if (options.maxOutputBytes != null && outputBytes > options.maxOutputBytes) {
-				child.kill("SIGTERM");
-				finish(new AudioNormalizationError("Decoded audio exceeds the supported duration"));
+				terminate(new AudioNormalizationError("Decoded audio exceeds the supported duration"));
 				return;
 			}
 			stdout.push(chunk);
@@ -105,6 +118,10 @@ function runFfmpeg(args, options = {}) {
 		});
 		child.once("close", (code) => {
 			if (settled) return;
+			if (terminationError) {
+				finish(terminationError);
+				return;
+			}
 			if (code === 0) finish();
 			else finish(new AudioNormalizationError(Buffer.concat(stderr).toString("utf8").trim() || `Unsupported or corrupt audio (decoder exit ${code})`));
 		});
@@ -123,6 +140,7 @@ async function decodeAudioToMonoFloat32(input) {
 		if (!(error instanceof UnsupportedWavEncodingError)) throw error;
 	}
 	const bytes = await runFfmpeg([
+		...LOCAL_AUDIO_INPUT_OPTIONS,
 		"-i",
 		"pipe:0",
 		"-map",
@@ -159,6 +177,7 @@ async function forEachNormalizedAudioSegment(input, consume) {
 	const outputPattern = join(directory, "segment-%05d.wav");
 	try {
 		await runFfmpeg([
+			...LOCAL_AUDIO_INPUT_OPTIONS,
 			"-i",
 			input.filePath,
 			"-map",
@@ -184,11 +203,15 @@ async function forEachNormalizedAudioSegment(input, consume) {
 		if (files.length === 0) throw new AudioNormalizationError("Audio decoder produced no segments");
 		let decodedDurationSeconds = 0;
 		for (const file of files) {
+			input.signal?.throwIfAborted();
 			const decoded = decodeWavToMonoFloat32(await readFile(join(directory, file)));
 			decodedDurationSeconds += decoded.durationSeconds;
 			if (decodedDurationSeconds > maxDurationSeconds + .05) throw new AudioNormalizationError(`Decoded audio exceeds the ${Math.round(maxDurationSeconds)} second limit`);
 		}
-		for (let index = 0; index < files.length; index += 1) await consume(await readFile(join(directory, files[index])), index);
+		for (let index = 0; index < files.length; index += 1) {
+			input.signal?.throwIfAborted();
+			await consume(await readFile(join(directory, files[index])), index);
+		}
 		return files.length;
 	} finally {
 		await rm(directory, {

package/dist/src/voice/stt/transcribe-core.js

@@ -82,6 +82,7 @@ async function transcribe(audioBuffer, config, options) {
 	const fallbackFrom = chosen.provider && chosen.provider !== primaryProvider ? primaryProvider : void 0;
 	return {
 		text: output.text,
+		...output.segments ? { segments: output.segments } : {},
 		provider: chosen.provider ?? "unknown",
 		...output.durationSeconds !== void 0 ? { duration: output.durationSeconds } : {},
 		...output.language || options?.language ? { language: output.language ?? options?.language } : {},

package/dist/src/voice/stt/types.d.ts

@@ -6,6 +6,7 @@
  * (see src/media-understanding/types.ts).
  */
 export interface STTResult {
+    segments?: import('../../media-understanding/types.js').AudioTranscriptionSegment[];
     /** Transcribed text. */
     text: string;
     /** Provider that performed the transcription (e.g. "alibaba", "openai"). */

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

@@ -5,6 +5,7 @@ export declare function analyzeWorkContext(input: {
     config: Config;
     snapshot: WorkContextSnapshot;
     candidateContext?: WorkDiscoveryCandidate[];
+    projectOverviewOnly?: boolean;
     signal?: AbortSignal;
 }): Promise<{
     modelRef: string;

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

@@ -184,27 +184,33 @@ async function analyzeWorkContext(input) {
 			"You help a user resume real work in one explicitly selected local folder.",
 			"Analyze only the supplied bounded snapshot. Never claim that you ran commands, tests, or inspected anything absent from it.",
 			"Return only one JSON object with projectSummary, currentState, uncertainties, suggestions, profileCandidates, workThreads, conversationStarter, lowConfidence, and contextQuestion.",
-			"profileCandidates contains only durable user-specific role, responsibility, preference, routine, communication, boundary, or relationship facts that are directly supported and would remain useful outside this repository snapshot.",
-			"Do not put the project stack, packages, architecture, deployment setup, repository conventions, or current task in profileCandidates. Put project facts in projectSummary/currentState and current work in workThreads.",
-			"Each profile candidate has category (role, responsibility, preference, routine, communication, boundary, or relationship), factKey, statement, confidence, and evidence.",
-			"Put current or desired outcomes in workThreads, not profileCandidates. Emit boundary or relationship only when directly stated in user-authored evidence; never infer private relationship labels or expanded permissions.",
-			"factKey is a stable language-neutral lowercase identifier such as workflow:code-review:github; equivalent facts in different languages must use the same factKey.",
 			USER_FACING_UNDERSTANDING_WRITING_GUIDANCE,
-			"Do not infer sensitive traits, identity, health, finances, political views, or anything not directly supported by the work evidence.",
-			"workThreads contains every distinct evidence-backed work stream with topicKey, title, summary, horizon, status, confidence, and evidenceRefs. Do not merge unrelated streams to force a fixed count.",
-			"horizon is current, ongoing, or long_term. status is active, paused, blocked, completed, or uncertain.",
-			"topicKey is a short stable topic identifier. evidenceRefs must use exact relative paths from the snapshot or git://recent-state.",
-			"Distinguish one-off recent edits from work sustained across multiple days. Prefer one current thread and only add ongoing or long_term threads when evidence supports them.",
-			"For a normal result, suggestions must contain exactly 3 materially different next steps.",
-			"Each suggestion must include actionType, title, rationale, evidence, actionPrompt, confidence, expectedTask, estimatedMinutes, risk, and verification.",
-			"actionType must be summarize_recent_work, inspect_related_tests, or plan_next_step.",
-			"risk must be analysis, command, or file_write. estimatedMinutes is an integer from 1 to 30.",
-			"verification is a short array describing how the user can tell the task is real.",
-			"Each evidence item contains an optional exact relative path from the snapshot and one concrete observation.",
-			"actionPrompt asks the assistant to investigate or continue the step; it does not silently authorize file changes.",
-			"conversationStarter is one concise, editable first-person prompt the user can send immediately. Ground it in the most important visible project or directory signal, ask the assistant to explain before acting, and never silently authorize file changes.",
-			"Always return conversationStarter, including when confidence is low.",
-			"If the current objective is unclear or fewer than three credible suggestions exist, set lowConfidence=true, return suggestions=[], and ask one concise contextQuestion.",
+			...input.projectOverviewOnly ? [
+				"This request is background project understanding. Return empty suggestions, profileCandidates, and workThreads; omit conversationStarter and contextQuestion. Do not ask the user to make decisions.",
+				"Use projectSummary to describe the documented purpose and structure, and currentState for startup/test commands, project conventions, and constraints. Cite the supporting relative file paths inline.",
+				"Keep the overview concise. Distinguish documented facts from interpretations. Put missing goals and uncertain assumptions in uncertainties; never treat inferred goals as user-confirmed."
+			] : [
+				"profileCandidates contains only durable user-specific role, responsibility, preference, routine, communication, boundary, or relationship facts that are directly supported and would remain useful outside this repository snapshot.",
+				"Do not put the project stack, packages, architecture, deployment setup, repository conventions, or current task in profileCandidates. Put project facts in projectSummary/currentState and current work in workThreads.",
+				"Each profile candidate has category (role, responsibility, preference, routine, communication, boundary, or relationship), factKey, statement, confidence, and evidence.",
+				"Put current or desired outcomes in workThreads, not profileCandidates. Emit boundary or relationship only when directly stated in user-authored evidence; never infer private relationship labels or expanded permissions.",
+				"factKey is a stable language-neutral lowercase identifier such as workflow:code-review:github; equivalent facts in different languages must use the same factKey.",
+				"Do not infer sensitive traits, identity, health, finances, political views, or anything not directly supported by the work evidence.",
+				"workThreads contains every distinct evidence-backed work stream with topicKey, title, summary, horizon, status, confidence, and evidenceRefs. Do not merge unrelated streams to force a fixed count.",
+				"horizon is current, ongoing, or long_term. status is active, paused, blocked, completed, or uncertain.",
+				"topicKey is a short stable topic identifier. evidenceRefs must use exact relative paths from the snapshot or git://recent-state.",
+				"Distinguish one-off recent edits from work sustained across multiple days. Prefer one current thread and only add ongoing or long_term threads when evidence supports them.",
+				"For a normal result, suggestions must contain exactly 3 materially different next steps.",
+				"Each suggestion must include actionType, title, rationale, evidence, actionPrompt, confidence, expectedTask, estimatedMinutes, risk, and verification.",
+				"actionType must be summarize_recent_work, inspect_related_tests, or plan_next_step.",
+				"risk must be analysis, command, or file_write. estimatedMinutes is an integer from 1 to 30.",
+				"verification is a short array describing how the user can tell the task is real.",
+				"Each evidence item contains an optional exact relative path from the snapshot and one concrete observation.",
+				"actionPrompt asks the assistant to investigate or continue the step; it does not silently authorize file changes.",
+				"conversationStarter is one concise, editable first-person prompt the user can send immediately. Ground it in the most important visible project or directory signal, ask the assistant to explain before acting, and never silently authorize file changes.",
+				"Always return conversationStarter, including when confidence is low.",
+				"If the current objective is unclear or fewer than three credible suggestions exist, set lowConfidence=true, return suggestions=[], and ask one concise contextQuestion."
+			],
 			"Use Simplified Chinese for every user-facing string when the visible snapshot documents are mainly Chinese; otherwise use English.",
 			"",
 			input.candidateContext?.length ? `Other ranked local work projects (metadata only):\n${JSON.stringify(input.candidateContext.slice(0, 8).map((candidate) => ({
@@ -220,7 +226,7 @@ async function analyzeWorkContext(input) {
 		].join("\n"),
 		timestamp: Date.now()
 	}] }, {
-		maxTokens: WORK_ANALYSIS_MAX_TOKENS,
+		maxTokens: input.projectOverviewOnly ? 2e3 : WORK_ANALYSIS_MAX_TOKENS,
 		temperature: .1,
 		signal: input.signal
 	});
@@ -232,7 +238,7 @@ async function analyzeWorkContext(input) {
 	const suggestions = Array.isArray(parsed.suggestions) ? parsed.suggestions.map((value) => validateSuggestion(value, allowedPaths)).filter((value) => Boolean(value)) : [];
 	const profileCandidates = Array.isArray(parsed.profileCandidates) ? parsed.profileCandidates.map((value) => validateProfileCandidate(value)).filter((value) => Boolean(value)) : [];
 	const workThreadCandidates = Array.isArray(parsed.workThreads) ? parsed.workThreads.map((value) => validateWorkThreadCandidate(value, allowedThreadRefs)).filter((value) => Boolean(value)) : [];
-	if (parsed.lowConfidence === true || suggestions.length !== 3) {
+	if (parsed.lowConfidence === true || !input.projectOverviewOnly && suggestions.length !== 3) {
 		const fallback = lowConfidenceResult(input.snapshot, typeof parsed.contextQuestion === "string" ? parsed.contextQuestion.trim().slice(0, 500) : void 0, typeof parsed.conversationStarter === "string" ? parsed.conversationStarter : void 0);
 		const projectSummary = typeof parsed.projectSummary === "string" && parsed.projectSummary.trim() ? parsed.projectSummary.trim().slice(0, 1200) : fallback.projectSummary;
 		const currentState = typeof parsed.currentState === "string" && parsed.currentState.trim() ? parsed.currentState.trim().slice(0, 1200) : fallback.currentState;

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

@@ -1,13 +1,13 @@
 import { analyzeUnderstandingSources, analyzeWorkContext, workDiscoveryResultMarkdown } from "./analyzer.js";
-import { WORK_DISCOVERY_SCAN_POLICY_VERSION, canonicalWorkDiscoveryRoot, previewWorkDiscoveryRoot, probeWorkDiscoveryRoot, readWorkDiscoveryTextExcerpt, searchWorkDiscoveryText, summarizeWorkContextSnapshot } from "./probe.js";
 import { discoverWorkCandidates, resolvePersonalWorkRoots } from "./candidate-discovery.js";
 import { workDiscoveryFingerprintsEqual } from "./incremental.js";
-import { createWorkDiscoveryRun, getWorkDiscoveryOnboardingState, getWorkDiscoveryRun, getWorkDiscoveryRunByIdempotencyKey, setWorkDiscoveryFeedback, setWorkDiscoveryOnboardingState, updateWorkDiscoveryRun } from "./repository.js";
+import { createWorkDiscoveryRun, getProjectUnderstandingRun, getWorkDiscoveryOnboardingState, getWorkDiscoveryRun, getWorkDiscoveryRunByIdempotencyKey, listPendingProjectUnderstandingRuns, setWorkDiscoveryFeedback, setWorkDiscoveryOnboardingState, updateWorkDiscoveryRun } from "./repository.js";
 import { findActiveWorkDiscoverySourceRefresh, listWorkDiscoverySourceRefreshes, recordWorkDiscoverySourceRefresh, updateWorkDiscoverySourceRefreshForRun } from "./incremental-repository.js";
 import { appendWorkUnderstandingEvidence, createWorkUnderstandingInvestigation, getWorkUnderstandingInvestigation, getWorkUnderstandingInvestigationForRun, listWorkUnderstandingEvidence, resetWorkUnderstandingInvestigation, updateWorkUnderstandingEvidenceObservation, updateWorkUnderstandingInvestigation } from "./investigation-repository.js";
+import { WORK_DISCOVERY_SCAN_POLICY_VERSION, canonicalWorkDiscoveryRoot, previewWorkDiscoveryRoot, probeWorkDiscoveryRoot, readWorkDiscoveryTextExcerpt, searchWorkDiscoveryText, summarizeWorkContextSnapshot } from "./probe.js";
 import { DEFAULT_WORK_INVESTIGATION_BUDGET, investigateWorkContext } from "./investigator.js";
 import { persistWorkThreadsFromDiscovery } from "./thread-service.js";
 import { getWorkDiscoveryDirectorySource, listWorkDiscoveryDirectorySources, revokeWorkDiscoveryDirectorySource, upsertWorkDiscoveryDirectorySource } from "./source-repository.js";
 import { WorkDiscoveryService, normalizeUnderstandingSourceItems } from "./service.js";
 import { evaluateQuickUnderstandingCase, evaluateWorkUnderstandingCase, meetsQuickUnderstandingGate } from "./evaluation.js";
-export { DEFAULT_WORK_INVESTIGATION_BUDGET, WORK_DISCOVERY_SCAN_POLICY_VERSION, WorkDiscoveryService, analyzeUnderstandingSources, analyzeWorkContext, appendWorkUnderstandingEvidence, canonicalWorkDiscoveryRoot, createWorkDiscoveryRun, createWorkUnderstandingInvestigation, discoverWorkCandidates, evaluateQuickUnderstandingCase, evaluateWorkUnderstandingCase, findActiveWorkDiscoverySourceRefresh, getWorkDiscoveryDirectorySource, getWorkDiscoveryOnboardingState, getWorkDiscoveryRun, getWorkDiscoveryRunByIdempotencyKey, getWorkUnderstandingInvestigation, getWorkUnderstandingInvestigationForRun, investigateWorkContext, listWorkDiscoveryDirectorySources, listWorkDiscoverySourceRefreshes, listWorkUnderstandingEvidence, meetsQuickUnderstandingGate, normalizeUnderstandingSourceItems, persistWorkThreadsFromDiscovery, previewWorkDiscoveryRoot, probeWorkDiscoveryRoot, readWorkDiscoveryTextExcerpt, recordWorkDiscoverySourceRefresh, resetWorkUnderstandingInvestigation, resolvePersonalWorkRoots, revokeWorkDiscoveryDirectorySource, searchWorkDiscoveryText, setWorkDiscoveryFeedback, setWorkDiscoveryOnboardingState, summarizeWorkContextSnapshot, updateWorkDiscoveryRun, updateWorkDiscoverySourceRefreshForRun, updateWorkUnderstandingEvidenceObservation, updateWorkUnderstandingInvestigation, upsertWorkDiscoveryDirectorySource, workDiscoveryFingerprintsEqual, workDiscoveryResultMarkdown };
+export { DEFAULT_WORK_INVESTIGATION_BUDGET, WORK_DISCOVERY_SCAN_POLICY_VERSION, WorkDiscoveryService, analyzeUnderstandingSources, analyzeWorkContext, appendWorkUnderstandingEvidence, canonicalWorkDiscoveryRoot, createWorkDiscoveryRun, createWorkUnderstandingInvestigation, discoverWorkCandidates, evaluateQuickUnderstandingCase, evaluateWorkUnderstandingCase, findActiveWorkDiscoverySourceRefresh, getProjectUnderstandingRun, getWorkDiscoveryDirectorySource, getWorkDiscoveryOnboardingState, getWorkDiscoveryRun, getWorkDiscoveryRunByIdempotencyKey, getWorkUnderstandingInvestigation, getWorkUnderstandingInvestigationForRun, investigateWorkContext, listPendingProjectUnderstandingRuns, listWorkDiscoveryDirectorySources, listWorkDiscoverySourceRefreshes, listWorkUnderstandingEvidence, meetsQuickUnderstandingGate, normalizeUnderstandingSourceItems, persistWorkThreadsFromDiscovery, previewWorkDiscoveryRoot, probeWorkDiscoveryRoot, readWorkDiscoveryTextExcerpt, recordWorkDiscoverySourceRefresh, resetWorkUnderstandingInvestigation, resolvePersonalWorkRoots, revokeWorkDiscoveryDirectorySource, searchWorkDiscoveryText, setWorkDiscoveryFeedback, setWorkDiscoveryOnboardingState, summarizeWorkContextSnapshot, updateWorkDiscoveryRun, updateWorkDiscoverySourceRefreshForRun, updateWorkUnderstandingEvidenceObservation, updateWorkUnderstandingInvestigation, upsertWorkDiscoveryDirectorySource, workDiscoveryFingerprintsEqual, workDiscoveryResultMarkdown };

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

@@ -3,8 +3,8 @@ 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 { readWorkDiscoveryTextExcerpt, searchWorkDiscoveryText } from "./probe.js";
 import { createHash } from "node:crypto";
 //#region src/work-discovery/investigator.ts
 init_schema();

package/dist/src/work-discovery/project-understanding.d.ts

@@ -0,0 +1,7 @@
+export declare function getProjectUnderstandingOverview(projectId: string): import("../knowledge-memory/domain.js").KnowledgeItem;
+export declare function saveProjectUnderstandingOverview(input: {
+    projectId: string;
+    content: string;
+    correctedByUser?: boolean;
+    evidenceRefs?: string[];
+}): import("../knowledge-memory/domain.js").KnowledgeItem;

package/dist/src/work-discovery/project-understanding.js

@@ -0,0 +1,38 @@
+import { listKnowledgeItems, writeKnowledgeItem } from "../knowledge-memory/repository.js";
+import "../knowledge-memory/index.js";
+//#region src/work-discovery/project-understanding.ts
+function getProjectUnderstandingOverview(projectId) {
+	return listKnowledgeItems({
+		scope: {
+			type: "project",
+			id: projectId
+		},
+		statuses: ["active"],
+		canonicalKey: `project-understanding:${projectId}`,
+		limit: 1
+	})[0];
+}
+function saveProjectUnderstandingOverview(input) {
+	const existing = getProjectUnderstandingOverview(input.projectId);
+	if (!input.correctedByUser && existing?.originClass === "owner") return existing;
+	return writeKnowledgeItem({
+		kind: "project_fact",
+		scope: {
+			type: "project",
+			id: input.projectId
+		},
+		canonicalKey: `project-understanding:${input.projectId}`,
+		content: input.content.slice(0, 6e3),
+		status: "active",
+		importance: .9,
+		confidence: input.correctedByUser ? 1 : .7,
+		originClass: input.correctedByUser ? "owner" : "agent",
+		source: {
+			provider: "project-understanding",
+			evidenceRefs: input.evidenceRefs ?? []
+		},
+		replaceExisting: true
+	}).item;
+}
+//#endregion
+export { getProjectUnderstandingOverview, saveProjectUnderstandingOverview };

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

@@ -8,10 +8,12 @@ export declare function setWorkDiscoveryOnboardingState(input: {
 export declare function createWorkDiscoveryRun(run: WorkDiscoveryRun): WorkDiscoveryRun;
 export declare function getWorkDiscoveryRun(id: string): WorkDiscoveryRun | null;
 export declare function getWorkDiscoveryRunByIdempotencyKey(key: string): WorkDiscoveryRun | null;
+export declare function getProjectUnderstandingRun(projectId: string): WorkDiscoveryRun | null;
+export declare function listPendingProjectUnderstandingRuns(): WorkDiscoveryRun[];
 export declare function setWorkDiscoveryFeedback(input: {
     runId: string;
     recognitionDecision: WorkDiscoveryRecognitionDecision;
     correctedIntent?: string;
     nowMs?: number;
 }): WorkDiscoveryFeedback;
-export declare function updateWorkDiscoveryRun(id: string, patch: Partial<Pick<WorkDiscoveryRun, 'status' | 'stage' | 'snapshot' | 'result' | 'errorCode' | 'errorMessage' | 'startedAt' | 'completedAt' | 'canceledAt'>>): WorkDiscoveryRun | null;
+export declare function updateWorkDiscoveryRun(id: string, patch: Partial<Pick<WorkDiscoveryRun, 'status' | 'stage' | 'snapshot' | 'result' | 'errorCode' | 'errorMessage' | 'startedAt' | 'completedAt' | 'canceledAt' | 'attempts'>>): WorkDiscoveryRun | null;

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

@@ -21,6 +21,8 @@ function onboardingFromRow(row) {
 function runFromRow(row) {
 	return {
 		id: row.id,
+		mode: row.mode,
+		attempts: row.attempts,
 		idempotencyKey: row.idempotency_key,
 		source: row.source,
 		status: row.status,
@@ -85,8 +87,8 @@ function createWorkDiscoveryRun(run) {
 		db.prepare(`INSERT INTO work_discovery_runs (
         id, idempotency_key, source, status, stage, root_path, project_id, session_key,
         agent_id, model_ref, scan_policy_version, snapshot_summary_json, result_json,
-        error_code, error_message, created_at, started_at, completed_at, canceled_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(run.id, run.idempotencyKey, run.source, run.status, run.stage ?? null, run.rootPath, run.projectId, run.sessionKey, run.agentId, run.modelRef, run.scanPolicyVersion, run.snapshot ? JSON.stringify(run.snapshot) : null, run.result ? JSON.stringify(run.result) : null, run.errorCode ?? null, run.errorMessage ?? null, run.createdAt, run.startedAt ?? null, run.completedAt ?? null, run.canceledAt ?? null);
+        error_code, error_message, created_at, started_at, completed_at, canceled_at, mode, attempts
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(run.id, run.idempotencyKey, run.source, run.status, run.stage ?? null, run.rootPath, run.projectId, run.sessionKey, run.agentId, run.modelRef, run.scanPolicyVersion, run.snapshot ? JSON.stringify(run.snapshot) : null, run.result ? JSON.stringify(run.result) : null, run.errorCode ?? null, run.errorMessage ?? null, run.createdAt, run.startedAt ?? null, run.completedAt ?? null, run.canceledAt ?? null, run.mode ?? "interactive", run.attempts ?? 0);
 	});
 	return getWorkDiscoveryRun(run.id);
 }
@@ -98,6 +100,17 @@ function getWorkDiscoveryRunByIdempotencyKey(key) {
 	const { db } = requireXopcDatabase();
 	return readRun(db, "idempotency_key", key);
 }
+function getProjectUnderstandingRun(projectId) {
+	const { db } = requireXopcDatabase();
+	const row = db.prepare(`SELECT * FROM work_discovery_runs
+    WHERE project_id = ? AND mode = 'background' ORDER BY created_at DESC, rowid DESC LIMIT 1`).get(projectId);
+	return row ? runFromRow(row) : null;
+}
+function listPendingProjectUnderstandingRuns() {
+	const { db } = requireXopcDatabase();
+	return db.prepare(`SELECT * FROM work_discovery_runs
+    WHERE mode = 'background' AND status IN ('queued', 'probing', 'analyzing')`).all().map(runFromRow);
+}
 function setWorkDiscoveryFeedback(input) {
 	const now = input.nowMs ?? Date.now();
 	runSqliteWriteTransaction((db) => {
@@ -122,10 +135,10 @@ function updateWorkDiscoveryRun(id, patch) {
 	runSqliteWriteTransaction((db) => {
 		db.prepare(`UPDATE work_discovery_runs SET
         status = ?, stage = ?, snapshot_summary_json = ?, result_json = ?,
-        error_code = ?, error_message = ?, started_at = ?, completed_at = ?, canceled_at = ?
-       WHERE id = ?`).run(next.status, next.stage ?? null, next.snapshot ? JSON.stringify(next.snapshot) : null, next.result ? JSON.stringify(next.result) : null, next.errorCode ?? null, next.errorMessage ?? null, next.startedAt ?? null, next.completedAt ?? null, next.canceledAt ?? null, id);
+        error_code = ?, error_message = ?, started_at = ?, completed_at = ?, canceled_at = ?, attempts = ?
+       WHERE id = ?`).run(next.status, next.stage ?? null, next.snapshot ? JSON.stringify(next.snapshot) : null, next.result ? JSON.stringify(next.result) : null, next.errorCode ?? null, next.errorMessage ?? null, next.startedAt ?? null, next.completedAt ?? null, next.canceledAt ?? null, next.attempts ?? 0, id);
 	});
 	return getWorkDiscoveryRun(id);
 }
 //#endregion
-export { createWorkDiscoveryRun, getWorkDiscoveryOnboardingState, getWorkDiscoveryRun, getWorkDiscoveryRunByIdempotencyKey, setWorkDiscoveryFeedback, setWorkDiscoveryOnboardingState, updateWorkDiscoveryRun };
+export { createWorkDiscoveryRun, getProjectUnderstandingRun, getWorkDiscoveryOnboardingState, getWorkDiscoveryRun, getWorkDiscoveryRunByIdempotencyKey, listPendingProjectUnderstandingRuns, setWorkDiscoveryFeedback, setWorkDiscoveryOnboardingState, updateWorkDiscoveryRun };

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

@@ -15,9 +15,17 @@ export interface WorkDiscoveryServiceOptions {
 export declare class WorkDiscoveryService {
     private readonly options;
     private readonly abortControllers;
+    private readonly executions;
+    private stopped;
     private readonly candidateContexts;
     private readonly activity;
     constructor(options: WorkDiscoveryServiceOptions);
+    startProjectUnderstanding(projectId: string): WorkDiscoveryRun;
+    resumeProjectUnderstanding(): void;
+    stop(): Promise<void>;
+    private trackExecution;
+    private scheduleProjectUnderstanding;
+    private runProjectUnderstanding;
     isEnabled(): boolean;
     getOnboardingState(): WorkDiscoveryOnboardingState;
     dismissOnboarding(): WorkDiscoveryOnboardingState;