@xopcai/xopc 0.0.269 → 0.0.272

package/dist/src/proactive/execution/context.js

@@ -1,8 +1,9 @@
 import { getSqliteDatabase } from "../../storage/sqlite/transaction.js";
 import { getAssertionSlot, listUserAssertions } from "../../user-model/repository.js";
 import "../../user-model/index.js";
-import { getDiscussionCapture, getLatestDiscussionOrganization } from "../../discussions/repository.js";
 import { authorizedConnectedSource } from "./authorization.js";
+import { authorizedMailThread, requireMailFollowUp } from "../follow-ups.js";
+import { getDiscussionCapture, getLatestDiscussionOrganization } from "../../discussions/repository.js";
 import { wrapExternalContent } from "../../gateway/security/external-content.js";
 //#region src/proactive/execution/context.ts
 const MAX_EVENT_COUNT = 50;
@@ -27,7 +28,12 @@ function emptyContext() {
 	};
 }
 function authorizedConnectedSourceItem(event, scenarioKey) {
-	return authorizedConnectedSource(event.subject_id, event.workspace_id, scenarioKey, event.agent_id);
+	const item = authorizedConnectedSource(event.subject_id, event.workspace_id, scenarioKey, event.agent_id);
+	if (item && event.type === "connected_source.calendar_window.v1") {
+		const payload = JSON.parse(event.payload_json);
+		if (payload.meetingStartsAt !== item.occurredAt || payload.contentHash && payload.contentHash !== item.contentHash) return null;
+	}
+	return item;
 }
 var EventBatchContextProvider = class {
 	id = "event_batch";
@@ -53,11 +59,13 @@ var ConnectedSourceContextProvider = class {
 	async collect(input) {
 		const items = [];
 		const snapshotItems = [];
+		const seen = /* @__PURE__ */ new Set();
 		const evidenceIds = [];
 		for (const event of eventRows(input.eventIds)) {
 			if (!event.type.startsWith("connected_source.") || event.type.includes("_deleted.")) continue;
 			const item = authorizedConnectedSourceItem(event, input.scenarioKey);
-			if (!item) continue;
+			if (!item || seen.has(item.id)) continue;
+			seen.add(item.id);
 			const evidenceId = `source-item:${item.id}`;
 			const common = {
 				evidenceId,
@@ -325,6 +333,43 @@ var DiscussionContextProvider = class {
 		};
 	}
 };
+var MailFollowUpContextProvider = class {
+	id = "follow_up";
+	async collect(input) {
+		const event = eventRows(input.eventIds).findLast((row) => row.subject_kind === "mail_follow_up");
+		if (!event) return emptyContext();
+		const follow = requireMailFollowUp(event.workspace_id, event.subject_id);
+		const thread = authorizedMailThread(follow);
+		if (!thread || follow.status !== "watching") return emptyContext();
+		const common = {
+			followUpId: follow.id,
+			revision: follow.revision,
+			fingerprint: thread.fingerprint,
+			dueAt: follow.due_at,
+			deadlinePassed: Date.parse(follow.due_at) <= Date.now()
+		};
+		return {
+			content: {
+				...common,
+				instructions: follow.instructions,
+				items: thread.items.map((item) => ({
+					evidenceId: `source-item:${item.id}`,
+					occurredAt: item.occurredAt,
+					content: wrapExternalContent(item.normalizedText?.slice(0, 4e3) ?? "", { source: "email" })
+				}))
+			},
+			snapshotContent: {
+				...common,
+				items: thread.items.map((item) => ({
+					sourceItemId: item.id,
+					contentHash: item.contentHash,
+					occurredAt: item.occurredAt
+				}))
+			},
+			evidenceIds: thread.items.map((item) => `source-item:${item.id}`)
+		};
+	}
+};
 var ContextProviderRegistry = class {
 	constructor(providers = [
 		new EventBatchContextProvider(),
@@ -334,7 +379,8 @@ var ContextProviderRegistry = class {
 		new MeetingWorkspaceContextProvider(),
 		new ProjectStateContextProvider(),
 		new AutomationStateContextProvider(),
-		new DiscussionContextProvider()
+		new DiscussionContextProvider(),
+		new MailFollowUpContextProvider()
 	]) {
 		this.providers = providers;
 	}
@@ -357,4 +403,4 @@ var ContextProviderRegistry = class {
 	}
 };
 //#endregion
-export { AutomationStateContextProvider, ConnectedSourceContextProvider, ContextProviderRegistry, DiscussionContextProvider, EventBatchContextProvider, InternalObjectContextProvider, MeetingWorkspaceContextProvider, ProjectStateContextProvider, UserModelContextProvider };
+export { AutomationStateContextProvider, ConnectedSourceContextProvider, ContextProviderRegistry, DiscussionContextProvider, EventBatchContextProvider, InternalObjectContextProvider, MailFollowUpContextProvider, MeetingWorkspaceContextProvider, ProjectStateContextProvider, UserModelContextProvider };

package/dist/src/proactive/execution/insight.js

@@ -1,3 +1,4 @@
+import { ProactiveArtifactSchema } from "../../../packages/gateway-contract/src/proactive.js";
 import { stripCodeFences } from "../../providers/model-response.js";
 //#region src/proactive/execution/insight.ts
 const URGENCY = new Set([
@@ -65,6 +66,7 @@ function parseInsightCandidate(raw, allowedEvidenceIds) {
 	const proposedAction = parseProposedAction(row.proposedAction);
 	if (proposedAction && (!decision || decision.options.length !== 2 || decision.options[0]?.id !== "approve" || decision.options[1]?.id !== "reject")) throw new Error("Insight proposedAction requires approve and reject decision options");
 	return {
+		...row.artifact != null ? { artifact: ProactiveArtifactSchema.parse(row.artifact) } : {},
 		title: boundedText(row.title, "title", 160),
 		summary: boundedText(row.summary, "summary", 1200),
 		whyNow: boundedText(row.whyNow, "whyNow", 800),
@@ -91,7 +93,7 @@ function isValuableInsight(candidate, policy = {
 	minConfidence: .65,
 	minScore: .6
 }) {
-	return candidate.confidence >= policy.minConfidence && candidate.urgency !== "low" && scoreInsight(candidate) >= policy.minScore;
+	return candidate.confidence >= policy.minConfidence && (candidate.urgency !== "low" || Boolean(candidate.artifact)) && scoreInsight(candidate) >= policy.minScore;
 }
 function parseAnalysisResult(raw, allowedEvidenceIds) {
 	let value;

package/dist/src/proactive/execution/repository.js

@@ -107,11 +107,19 @@ function finishRun(input, now = /* @__PURE__ */ new Date()) {
       JOIN proactive_events e ON e.event_id = be.event_id
       WHERE be.batch_id = ?
       ORDER BY e.subject_kind, e.subject_id`).all(input.run.batchId).map((row) => `${str(row, "subject_kind")}:${str(row, "subject_id")}`);
-		const fingerprint = input.candidate ? createHash("sha256").update([...subjectScope, ...[
-			input.candidate.title,
-			input.candidate.summary,
-			input.candidate.recommendation
-		].map((value) => value.trim().toLowerCase().replace(/\s+/g, " "))].join("\n")).digest("hex") : void 0;
+		const snapshot = db.prepare(`SELECT c.content_json FROM proactive_runs r JOIN proactive_context_snapshots c
+      ON c.snapshot_id = r.context_snapshot_id WHERE r.run_id = ?`).get(input.run.id);
+		const sourceVersions = snapshot ? JSON.parse(snapshot.content_json) : {};
+		const fingerprint = input.candidate ? createHash("sha256").update([
+			...subjectScope,
+			JSON.stringify(input.candidate.artifact ?? null),
+			JSON.stringify(sourceVersions.connected_source ?? sourceVersions.project_state ?? sourceVersions.follow_up ?? null),
+			...[
+				input.candidate.title,
+				input.candidate.summary,
+				input.candidate.recommendation
+			].map((value) => value.trim().toLowerCase().replace(/\s+/g, " "))
+		].join("\n")).digest("hex") : void 0;
 		const duplicate = fingerprint ? db.prepare(`SELECT 1 FROM proactive_insights
       WHERE subscription_id = ? AND scenario_key = ? AND content_fingerprint = ? AND created_at >= ? LIMIT 1`).get(input.run.subscriptionId, input.run.scenarioKey, fingerprint, (/* @__PURE__ */ new Date(now.getTime() - (input.cooldownSeconds ?? 10080 * 60) * 1e3)).toISOString()) : void 0;
 		const valuable = Boolean(input.candidate) && !duplicate;
@@ -141,6 +149,7 @@ function finishRun(input, now = /* @__PURE__ */ new Date()) {
       why_now, impact, recommendation, work_done, decision_json, proposed_action_json, urgency, confidence, value_score,
       evidence_ids_json, content_fingerprint, created_at)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(insight.id, insight.runId, insight.subscriptionId, insight.scenarioKey, insight.title, insight.summary, insight.whyNow, insight.impact, insight.recommendation, insight.workDone, insight.decision ? JSON.stringify(insight.decision) : null, insight.proposedAction ? JSON.stringify(insight.proposedAction) : null, insight.urgency, insight.confidence, insight.valueScore, JSON.stringify(insight.evidenceIds), fingerprint, insight.createdAt);
+		if (insight.artifact) db.prepare("UPDATE proactive_insights SET artifact_json = ? WHERE insight_id = ?").run(JSON.stringify(insight.artifact), insight.id);
 		return insight;
 	});
 }
@@ -165,6 +174,7 @@ function listInsights(limit = 50) {
 		impact: str(row, "impact"),
 		recommendation: str(row, "recommendation"),
 		workDone: str(row, "work_done"),
+		...row.artifact_json ? { artifact: JSON.parse(str(row, "artifact_json")) } : {},
 		...row.decision_json ? { decision: JSON.parse(str(row, "decision_json")) } : {},
 		...row.proposed_action_json ? { proposedAction: JSON.parse(str(row, "proposed_action_json")) } : {},
 		urgency: str(row, "urgency"),

package/dist/src/proactive/execution/types.d.ts

@@ -1,3 +1,4 @@
+import type { ProactiveArtifact } from '@xopcai/gateway-contract';
 export interface ContextSnapshot {
     id: string;
     batchId: string;
@@ -6,6 +7,7 @@ export interface ContextSnapshot {
     createdAt: string;
 }
 export interface InsightCandidate {
+    artifact?: ProactiveArtifact;
     title: string;
     summary: string;
     whyNow: string;

package/dist/src/proactive/execution/worker.js

@@ -1,6 +1,7 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { getSqliteDatabase } from "../../storage/sqlite/transaction.js";
+import { authorizedConnectedSource } from "./authorization.js";
 import { effectiveProactivePolicy } from "../policy/service.js";
 import { getPromptRevision, getScenario } from "../scenarios/repository.js";
 import { composeScenarioPrompt } from "../scenarios/prompt-composer.js";
@@ -9,6 +10,7 @@ import { ContextProviderRegistry } from "./context.js";
 import { attachSnapshot, claimNextRun, eventIdsForBatch, failRun, finishRun, saveSnapshot } from "./repository.js";
 import { isValuableInsight, parseAnalysisResult, scoreInsight } from "./insight.js";
 import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 //#region src/proactive/execution/worker.ts
 init_logger();
 const log = createLogger("ProactiveWorker");
@@ -86,11 +88,14 @@ var ProactiveWorker = class {
 					subscriptionId: run.subscriptionId
 				});
 				const revoked = context.evidenceIds.some((id) => !latestContext.evidenceIds.includes(id));
-				const result = revoked ? {
+				const changed = !isDeepStrictEqual(context.snapshotContent ?? context.content, latestContext.snapshotContent ?? latestContext.content);
+				const unavailable = context.evidenceIds.some((id) => id.startsWith("source-item:") && !authorizedConnectedSource(id.slice(12), effectiveProactivePolicy(run.subscriptionId).workspaceId, run.scenarioKey));
+				const result = revoked || changed ? {
 					result: "no_insight",
-					reason: "source_unavailable"
+					reason: unavailable ? "source_unavailable" : "source_changed"
 				} : parseAnalysisResult(output.text, new Set(latestContext.evidenceIds));
 				const candidate = result.result === "insight" ? result.candidate : void 0;
+				if (run.scenarioKey === "communication_follow_up" && (candidate?.decision || candidate?.proposedAction)) throw new Error("Communication preparation must return a draft or update; actions require the conversation confirmation flow");
 				const valueScore = candidate ? scoreInsight(candidate) : 0;
 				const enabled = effectiveProactivePolicy(run.subscriptionId).enabled;
 				const valuable = enabled && candidate && isValuableInsight(candidate, scenario.valuePolicy);

package/dist/src/proactive/experience.d.ts

@@ -0,0 +1,69 @@
+export declare function startDelegation(workspace: string, value: unknown): {
+    effectiveLevel: "off" | "active" | "quiet" | "balanced";
+    schedule: Record<string, import("node:sqlite").SQLOutputValue>;
+    revision: number;
+    level: "off" | "active" | "quiet" | "balanced";
+    delivery: "digest" | "inbox" | "important";
+    completedAt: string;
+    scanIntervalMinutes: number;
+    userInstructions: string;
+    id: string;
+    scenarioKey: string;
+    workspaceId: string;
+    scopeKind: "workspace" | "project";
+    scopeId: string;
+    enabled: boolean;
+    activePromptRevisionId?: string;
+    createdAt: string;
+    updatedAt: string;
+};
+/** Queue work in the existing worker; HTTP and conversation requests do not own model runs. */
+export declare function checkDelegation(workspace: string, id: string): {
+    status: "queued";
+};
+export declare function delegationOverview(workspace: string): {
+    followUps: {
+        id: string;
+        subscriptionId: string;
+        instructions: string;
+        dueAt: string;
+        status: "completed" | "paused" | "watching";
+        revision: number;
+        lastCheckedAt: string;
+        sessionKey: string;
+        sourceAvailable: boolean;
+        enabled: boolean;
+        subject: string;
+        latestMessageAt: string;
+        latestDirection: string;
+        lastSyncedAt: string;
+        syncFailed: boolean;
+    }[];
+    needsDecision: import("@xopcai/gateway-contract/src/proactive.js").ProactiveCard[];
+    prepared: import("@xopcai/gateway-contract/src/proactive.js").ProactiveCard[];
+    updates: import("@xopcai/gateway-contract/src/proactive.js").ProactiveCard[];
+    delegations: {
+        effectiveEnabled: boolean;
+        project: Record<string, import("node:sqlite").SQLOutputValue>;
+        latestRun: Record<string, import("node:sqlite").SQLOutputValue>;
+        pending: boolean;
+        effectiveLevel: "off" | "active" | "quiet" | "balanced";
+        schedule: Record<string, import("node:sqlite").SQLOutputValue>;
+        revision: number;
+        level: "off" | "active" | "quiet" | "balanced";
+        delivery: "digest" | "inbox" | "important";
+        completedAt: string;
+        scanIntervalMinutes: number;
+        userInstructions: string;
+        id: string;
+        scenarioKey: string;
+        workspaceId: string;
+        scopeKind: "workspace" | "project";
+        scopeId: string;
+        enabled: boolean;
+        activePromptRevisionId?: string;
+        createdAt: string;
+        updatedAt: string;
+    }[];
+};
+export declare function completeDeliveredProjects(now?: Date): void;

package/dist/src/proactive/experience.js

@@ -0,0 +1,90 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { ProactiveConflict, effectiveProactivePolicy } from "./policy/service.js";
+import { controlledSubscriptions, createControlledSubscription, requireSubscription, updateControlledSubscription } from "./scenarios/control.js";
+import { ProactiveScenarioService } from "./scenarios/service.js";
+import { ProactiveEventService } from "./service.js";
+import { listMailFollowUps } from "./follow-ups.js";
+import { getCard } from "./inbox/cards.js";
+import { scanDueProjects } from "./temporal/schedule.js";
+import { z } from "zod";
+//#region src/proactive/experience.ts
+const DelegateSchema = z.object({
+	scenarioKey: z.enum([
+		"project_delivery_risk",
+		"meeting_preparation",
+		"discussion_follow_up"
+	]),
+	projectId: z.string().min(1).optional(),
+	instructions: z.string().trim().min(1).max(12e3)
+}).strict();
+function startDelegation(workspace, value) {
+	const input = DelegateSchema.parse(value);
+	if (input.scenarioKey === "project_delivery_risk" && !input.projectId) throw new Error("Choose a project");
+	if (input.scenarioKey !== "project_delivery_risk" && input.projectId) throw new Error("This service uses workspace sources");
+	const subscription = createControlledSubscription(workspace, {
+		scenarioKey: input.scenarioKey,
+		scopeKind: input.projectId ? "project" : "workspace",
+		scopeId: input.projectId ?? workspace,
+		userInstructions: input.instructions
+	});
+	if (input.projectId && effectiveProactivePolicy(subscription.id).enabled) checkDelegation(workspace, subscription.id);
+	return subscription;
+}
+/** Queue work in the existing worker; HTTP and conversation requests do not own model runs. */
+function checkDelegation(workspace, id) {
+	const sub = requireSubscription(id, workspace);
+	if (!effectiveProactivePolicy(id).enabled) throw new Error("Resume this service before checking");
+	if (sub.scopeKind !== "project") throw new Error("This service checks when connected sources change");
+	return runSqliteWriteTransaction((db) => {
+		if (db.prepare("SELECT 1 FROM proactive_signal_batches WHERE subscription_id = ? AND status IN ('collecting', 'ready', 'processing')").get(id)) return { status: "queued" };
+		const last = db.prepare("SELECT MAX(started_at) AS at FROM proactive_runs WHERE subscription_id = ?").get(id);
+		if (last.at && Date.parse(last.at) > Date.now() - 6e4) throw new ProactiveConflict("A check just finished; try again in a minute");
+		db.prepare(`INSERT INTO proactive_schedule_state(subscription_id, next_due_at) VALUES (?, ?)
+      ON CONFLICT(subscription_id) DO UPDATE SET next_due_at = excluded.next_due_at, last_fingerprint = NULL`).run(id, (/* @__PURE__ */ new Date()).toISOString());
+		scanDueProjects(new ProactiveEventService(() => new ProactiveScenarioService().routes()));
+		db.prepare("UPDATE proactive_signal_batches SET ready_at = ?, status = 'ready' WHERE subscription_id = ? AND status = 'collecting'").run((/* @__PURE__ */ new Date()).toISOString(), id);
+		return { status: "queued" };
+	});
+}
+function delegationOverview(workspace) {
+	const db = getSqliteDatabase();
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const cards = db.prepare(`SELECT i.inbox_item_id FROM proactive_inbox_items i
+    JOIN proactive_insights x USING(insight_id) JOIN proactive_scenario_subscriptions s USING(subscription_id)
+    WHERE s.workspace_id = ? AND i.withdrawn_at IS NULL AND i.status IN ('unread', 'read')
+    AND (i.expires_at IS NULL OR i.expires_at > ?)
+    ORDER BY CASE WHEN x.action_status = 'approval_required' THEN 0 WHEN x.artifact_json IS NOT NULL THEN 1 ELSE 2 END,
+    x.value_score DESC, i.updated_at DESC LIMIT 100`).all(workspace, now).map((row) => getCard(row.inbox_item_id, workspace)).filter((card) => !["withdrawn", "expired"].includes(card.status));
+	return {
+		followUps: listMailFollowUps(workspace),
+		needsDecision: cards.filter((card) => card.decision && card.actionStatus !== "completed"),
+		prepared: cards.filter((card) => card.artifact && !card.decision),
+		updates: cards.filter((card) => !card.artifact && !card.decision),
+		delegations: controlledSubscriptions(workspace).map((sub) => ({
+			...sub,
+			effectiveEnabled: effectiveProactivePolicy(sub.id).enabled,
+			project: sub.scopeKind === "project" ? db.prepare("SELECT name, status FROM projects WHERE project_id = ?").get(sub.scopeId) ?? null : null,
+			latestRun: db.prepare(`SELECT status, outcome_reason AS reason, completed_at AS completedAt, started_at AS startedAt, error_message AS error
+        FROM proactive_runs WHERE subscription_id = ? ORDER BY started_at DESC LIMIT 1`).get(sub.id) ?? null,
+			pending: Boolean(db.prepare("SELECT 1 FROM proactive_signal_batches WHERE subscription_id = ? AND status IN ('collecting', 'ready', 'processing')").get(sub.id))
+		}))
+	};
+}
+function completeDeliveredProjects(now = /* @__PURE__ */ new Date()) {
+	const db = getSqliteDatabase();
+	const rows = db.prepare(`SELECT s.subscription_id, s.workspace_id FROM proactive_scenario_subscriptions s
+    JOIN projects p ON p.project_id = s.scope_id WHERE s.scope_kind = 'project' AND s.enabled = 1
+    AND p.status IN ('completed', 'cancelled', 'archived')`).all();
+	for (const row of rows) {
+		const current = controlledSubscriptions(row.workspace_id).find((sub) => sub.id === row.subscription_id);
+		updateControlledSubscription(row.workspace_id, row.subscription_id, {
+			expectedRevision: current.revision,
+			enabled: false,
+			completedAt: now.toISOString()
+		});
+		db.prepare(`UPDATE proactive_inbox_items SET status = 'resolved', resolution = 'project_ended', updated_at = ?
+      WHERE insight_id IN (SELECT insight_id FROM proactive_insights WHERE subscription_id = ?) AND status <> 'resolved'`).run(now.toISOString(), row.subscription_id);
+	}
+}
+//#endregion
+export { checkDelegation, completeDeliveredProjects, delegationOverview, startDelegation };

package/dist/src/proactive/follow-ups.d.ts

@@ -0,0 +1,123 @@
+import { ProactiveEventService } from './service.js';
+export declare const COMMUNICATION_SCENARIO = "communication_follow_up";
+export type MailFollowUp = {
+    id: string;
+    subscription_id: string;
+    workspace_id: string;
+    source_item_id: string;
+    instructions: string;
+    due_at: string;
+    status: 'watching' | 'paused' | 'completed';
+    revision: number;
+    last_fingerprint: string | null;
+    last_checked_at: string | null;
+    session_key: string | null;
+};
+export declare function requireMailFollowUp(workspace: string, id: string): MailFollowUp;
+export declare function authorizedMailThread(follow: MailFollowUp): {
+    origin: import("../knowledge/types.js").KnowledgeSourceItem;
+    items: import("../knowledge/types.js").KnowledgeSourceItem[];
+    threadKey: string;
+    fingerprint: string;
+};
+export declare function mailFollowUpView(follow: MailFollowUp): {
+    id: string;
+    subscriptionId: string;
+    instructions: string;
+    dueAt: string;
+    status: "completed" | "paused" | "watching";
+    revision: number;
+    lastCheckedAt: string;
+    sessionKey: string;
+    sourceAvailable: boolean;
+    enabled: boolean;
+    subject: string;
+    latestMessageAt: string;
+    latestDirection: string;
+    lastSyncedAt: string;
+    syncFailed: boolean;
+};
+export declare function listMailFollowUps(workspace: string): {
+    id: string;
+    subscriptionId: string;
+    instructions: string;
+    dueAt: string;
+    status: "completed" | "paused" | "watching";
+    revision: number;
+    lastCheckedAt: string;
+    sessionKey: string;
+    sourceAvailable: boolean;
+    enabled: boolean;
+    subject: string;
+    latestMessageAt: string;
+    latestDirection: string;
+    lastSyncedAt: string;
+    syncFailed: boolean;
+}[];
+export declare function mailFollowUpSources(workspace: string): {
+    id: string;
+    subject: string;
+    sender: string;
+    occurredAt: string;
+    accountLabel: string;
+}[];
+export declare function startMailFollowUp(workspace: string, value: unknown): {
+    id: string;
+    subscriptionId: string;
+    instructions: string;
+    dueAt: string;
+    status: "completed" | "paused" | "watching";
+    revision: number;
+    lastCheckedAt: string;
+    sessionKey: string;
+    sourceAvailable: boolean;
+    enabled: boolean;
+    subject: string;
+    latestMessageAt: string;
+    latestDirection: string;
+    lastSyncedAt: string;
+    syncFailed: boolean;
+};
+export declare function updateMailFollowUp(workspace: string, id: string, value: unknown): {
+    id: string;
+    subscriptionId: string;
+    instructions: string;
+    dueAt: string;
+    status: "completed" | "paused" | "watching";
+    revision: number;
+    lastCheckedAt: string;
+    sessionKey: string;
+    sourceAvailable: boolean;
+    enabled: boolean;
+    subject: string;
+    latestMessageAt: string;
+    latestDirection: string;
+    lastSyncedAt: string;
+    syncFailed: boolean;
+};
+/** Keep the existing chat and its exact connector confirmation flow as the write boundary. */
+export declare function continueMailFollowUp(workspace: string, id: string, sessionKey: string): {
+    followUp: {
+        id: string;
+        subscriptionId: string;
+        instructions: string;
+        dueAt: string;
+        status: "completed" | "paused" | "watching";
+        revision: number;
+        lastCheckedAt: string;
+        sessionKey: string;
+        sourceAvailable: boolean;
+        enabled: boolean;
+        subject: string;
+        latestMessageAt: string;
+        latestDirection: string;
+        lastSyncedAt: string;
+        syncFailed: boolean;
+    };
+    connectionId: unknown;
+    sourceItemId: string;
+    threadId: string;
+    instruction: string;
+};
+/** Poll only delegated threads; unchanged threads and passed deadlines produce no repeat signals. */
+export declare function scanMailFollowUps(events: ProactiveEventService, now?: Date): number;

package/dist/src/proactive/follow-ups.js

@@ -0,0 +1,169 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { listKnowledgeSourceItems } from "../storage/sqlite/knowledge-repository.js";
+import { getConnectorConnection } from "../storage/sqlite/connector-repository.js";
+import { emailFields, readMailThread } from "./mail-thread.js";
+import { authorizedConnectedSource } from "./execution/authorization.js";
+import { ProactiveConflict, effectiveProactivePolicy } from "./policy/service.js";
+import { listSubscriptions } from "./scenarios/repository.js";
+import { createControlledSubscription } from "./scenarios/control.js";
+import { ProactiveScenarioService } from "./scenarios/service.js";
+import { ProactiveEventService } from "./service.js";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+//#region src/proactive/follow-ups.ts
+const COMMUNICATION_SCENARIO = "communication_follow_up";
+const CreateSchema = z.object({
+	sourceItemId: z.string().min(1),
+	instructions: z.string().trim().min(1).max(12e3),
+	dueAt: z.string().datetime()
+}).strict();
+const UpdateSchema = z.object({
+	expectedRevision: z.number().int().positive(),
+	instructions: z.string().trim().min(1).max(12e3).optional(),
+	dueAt: z.string().datetime().optional(),
+	status: z.enum([
+		"watching",
+		"paused",
+		"completed"
+	]).optional()
+}).strict();
+function requireMailFollowUp(workspace, id) {
+	const row = getSqliteDatabase().prepare("SELECT * FROM proactive_follow_ups WHERE id = ? AND workspace_id = ?").get(id, workspace);
+	if (!row) throw new Error("Follow-up not found");
+	return row;
+}
+function authorizedMailThread(follow) {
+	if (!authorizedConnectedSource(follow.source_item_id, follow.workspace_id, "communication_follow_up")) return null;
+	const thread = readMailThread(follow.source_item_id);
+	if (!thread || thread.items.some((item) => !authorizedConnectedSource(item.id, follow.workspace_id, "communication_follow_up") || item.metadata.connectionId !== thread.origin.metadata.connectionId)) return null;
+	return thread;
+}
+function mailFollowUpView(follow) {
+	const thread = authorizedMailThread(follow);
+	const latest = thread?.items.at(-1);
+	const sync = thread ? getSqliteDatabase().prepare("SELECT status, error, finished_at FROM knowledge_sync_runs WHERE source_instance_id = ? ORDER BY started_at DESC LIMIT 1").get(thread.origin.sourceInstanceId) : void 0;
+	return {
+		id: follow.id,
+		subscriptionId: follow.subscription_id,
+		instructions: follow.instructions,
+		dueAt: follow.due_at,
+		status: follow.status,
+		revision: follow.revision,
+		lastCheckedAt: follow.last_checked_at,
+		sessionKey: follow.session_key,
+		sourceAvailable: Boolean(thread),
+		enabled: effectiveProactivePolicy(follow.subscription_id).enabled,
+		subject: thread ? emailFields(thread.origin.normalizedText).subject ?? "Email follow-up" : null,
+		latestMessageAt: latest?.occurredAt ?? null,
+		latestDirection: latest ? emailFields(latest.normalizedText).labels?.includes("SENT") ? "sent" : emailFields(latest.normalizedText).labels?.includes("INBOX") ? "received" : "unknown" : null,
+		lastSyncedAt: sync?.finished_at ? new Date(sync.finished_at).toISOString() : null,
+		syncFailed: Boolean(sync?.error)
+	};
+}
+function listMailFollowUps(workspace) {
+	return getSqliteDatabase().prepare("SELECT * FROM proactive_follow_ups WHERE workspace_id = ? ORDER BY updated_at DESC").all(workspace).map(mailFollowUpView);
+}
+function mailFollowUpSources(workspace) {
+	const seen = /* @__PURE__ */ new Set();
+	return listKnowledgeSourceItems({
+		itemType: "email",
+		limit: 500
+	}).flatMap((item) => {
+		if (!authorizedConnectedSource(item.id, workspace, "communication_follow_up")) return [];
+		const thread = readMailThread(item.id);
+		if (!thread || seen.has(thread.threadKey)) return [];
+		seen.add(thread.threadKey);
+		const fields = emailFields(item.normalizedText);
+		const connection = getConnectorConnection(String(item.metadata.connectionId));
+		const account = connection?.alias ?? connection?.identity.email ?? connection?.identity.name;
+		return [{
+			id: item.id,
+			subject: fields.subject ?? "Email",
+			sender: fields.sender ?? "",
+			occurredAt: item.occurredAt,
+			accountLabel: typeof account === "string" ? account : "Connected email account"
+		}];
+	}).slice(0, 100);
+}
+function startMailFollowUp(workspace, value) {
+	const input = CreateSchema.parse(value);
+	if (Date.parse(input.dueAt) <= Date.now()) throw new Error("Choose a future follow-up time");
+	if (!authorizedConnectedSource(input.sourceItemId, workspace, "communication_follow_up")) throw new Error("Authorize this email account for proactive follow-up first");
+	const thread = readMailThread(input.sourceItemId);
+	if (!thread) throw new Error("This email has no available thread");
+	return runSqliteWriteTransaction((db) => {
+		if (db.prepare("SELECT 1 FROM proactive_follow_ups WHERE workspace_id = ? AND thread_key = ?").get(workspace, thread.threadKey)) throw new ProactiveConflict("This conversation is already delegated; update the existing follow-up");
+		const sub = listSubscriptions("communication_follow_up").find((item) => item.workspaceId === workspace) ?? createControlledSubscription(workspace, {
+			scenarioKey: "communication_follow_up",
+			scopeKind: "workspace",
+			scopeId: workspace
+		});
+		const id = randomUUID();
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		db.prepare(`INSERT INTO proactive_follow_ups(id, subscription_id, workspace_id, source_item_id, thread_key, instructions, due_at, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, sub.id, workspace, input.sourceItemId, thread.threadKey, input.instructions, input.dueAt, now, now);
+		scanMailFollowUps(new ProactiveEventService(() => new ProactiveScenarioService().routes()));
+		return mailFollowUpView(requireMailFollowUp(workspace, id));
+	});
+}
+function updateMailFollowUp(workspace, id, value) {
+	const input = UpdateSchema.parse(value);
+	return runSqliteWriteTransaction((db) => {
+		const row = requireMailFollowUp(workspace, id);
+		if (row.revision !== input.expectedRevision) throw new ProactiveConflict("Follow-up changed; refresh before editing");
+		if (input.dueAt && Date.parse(input.dueAt) <= Date.now()) throw new Error("Choose a future follow-up time");
+		db.prepare(`UPDATE proactive_follow_ups SET instructions = ?, due_at = ?, status = ?, revision = revision + 1,
+      last_fingerprint = NULL, updated_at = ? WHERE id = ?`).run(input.instructions ?? row.instructions, input.dueAt ?? row.due_at, input.status ?? row.status, (/* @__PURE__ */ new Date()).toISOString(), id);
+		scanMailFollowUps(new ProactiveEventService(() => new ProactiveScenarioService().routes()));
+		return mailFollowUpView(requireMailFollowUp(workspace, id));
+	});
+}
+/** Keep the existing chat and its exact connector confirmation flow as the write boundary. */
+function continueMailFollowUp(workspace, id, sessionKey) {
+	const follow = requireMailFollowUp(workspace, id);
+	const thread = authorizedMailThread(follow);
+	if (!thread || follow.status !== "watching" || !effectiveProactivePolicy(follow.subscription_id).enabled) throw new Error("Resume and authorize this follow-up before continuing");
+	getSqliteDatabase().prepare("UPDATE proactive_follow_ups SET session_key = ? WHERE id = ?").run(sessionKey, id);
+	return {
+		followUp: mailFollowUpView(requireMailFollowUp(workspace, id)),
+		connectionId: thread.origin.metadata.connectionId,
+		sourceItemId: thread.origin.id,
+		threadId: emailFields(thread.origin.normalizedText).threadId,
+		instruction: "Read the current card and latest thread using this exact connection. Review the recipients and complete draft with the user before sending through the connector approval flow. Never infer successful delivery from a draft or approval. Use provider results, then continue watching synchronized replies."
+	};
+}
+/** Poll only delegated threads; unchanged threads and passed deadlines produce no repeat signals. */
+function scanMailFollowUps(events, now = /* @__PURE__ */ new Date()) {
+	const db = getSqliteDatabase();
+	let published = 0;
+	for (const follow of db.prepare("SELECT * FROM proactive_follow_ups WHERE status = 'watching'").all()) {
+		if (!effectiveProactivePolicy(follow.subscription_id, now).enabled) continue;
+		const thread = authorizedMailThread(follow);
+		if (!thread) continue;
+		const fingerprint = `${follow.revision}:${thread.fingerprint}:${Date.parse(follow.due_at) <= now.getTime() ? "due" : "waiting"}`;
+		if (fingerprint !== follow.last_fingerprint) {
+			if (events.publish({
+				type: "proactive.follow_up.v1",
+				schemaVersion: 1,
+				source: {
+					kind: "connector",
+					id: String(thread.origin.metadata.connectionId)
+				},
+				subject: {
+					kind: "mail_follow_up",
+					id: follow.id
+				},
+				actor: { kind: "system" },
+				scope: { workspaceId: follow.workspace_id },
+				occurredAt: now.toISOString(),
+				dedupeKey: `mail-follow-up:${follow.id}:${fingerprint}`,
+				sensitivity: "personal",
+				payload: { followUpId: follow.id }
+			}, now).inserted) published++;
+		}
+		db.prepare("UPDATE proactive_follow_ups SET last_fingerprint = ?, last_checked_at = ? WHERE id = ?").run(fingerprint, now.toISOString(), follow.id);
+	}
+	return published;
+}
+//#endregion
+export { COMMUNICATION_SCENARIO, authorizedMailThread, continueMailFollowUp, listMailFollowUps, mailFollowUpSources, mailFollowUpView, requireMailFollowUp, scanMailFollowUps, startMailFollowUp, updateMailFollowUp };