@xopcai/xopc 0.0.308 → 0.0.311

package/dist/src/scenes/execution.js

@@ -0,0 +1,168 @@
+import { intersectPermissions, sceneContentHash } from "./contracts.js";
+import { SceneSourceNotReady, sceneSourceFailureReason } from "./readiness.js";
+import { z } from "zod";
+//#region src/scenes/execution.ts
+const readOnlyResultSchema = z.strictObject({
+	kind: z.enum([
+		"no_change",
+		"observation",
+		"artifact",
+		"decision"
+	]),
+	summary: z.string().max(32e3),
+	evidenceIds: z.array(z.string().min(1)).max(100)
+}).refine((result) => result.kind === "no_change" || result.summary.trim().length > 0 && result.evidenceIds.length > 0, "A useful result requires evidence");
+var SceneExecutionRejected = class extends Error {
+	constructor(reason) {
+		super(reason);
+		this.reason = reason;
+	}
+};
+function evidenceAllowed(item, activation, permissions, now) {
+	if (!item.id || !item.revision || !Number.isFinite(item.freshUntil) || item.freshUntil <= now) return false;
+	if (item.ownerId !== activation.ownerId || item.workspaceId !== activation.workspaceId) return false;
+	if (item.accountId !== void 0 && !permissions.accountIds.includes(item.accountId)) return false;
+	const scope = activation.scope;
+	if (scope.kind === "objects") return scope.ids.includes(item.subjectId);
+	if (scope.kind === "project") return item.projectId === scope.id;
+	if (scope.kind === "conversation") return item.conversationId === scope.id;
+	return true;
+}
+/** Runs one durable claim without exposing messaging, filesystem or write tools. */
+var SceneExecutionService = class {
+	constructor(repository, providers, executor, authorize, clock = Date.now) {
+		this.repository = repository;
+		this.providers = providers;
+		this.executor = executor;
+		this.authorize = authorize;
+		this.clock = clock;
+		if (new Set(providers.map((provider) => provider.id)).size !== providers.length) throw new Error("Duplicate scene context providers");
+	}
+	async runNext(worker, outerSignal) {
+		outerSignal?.throwIfAborted();
+		const claim = this.repository.claimNext(worker, this.clock(), 62e4);
+		if (!claim) return "idle";
+		const runInput = this.repository.getRunInput(claim, this.clock());
+		if (!runInput) return "discarded";
+		const { activation, subjectId, accountId, notBefore } = runInput;
+		const template = this.repository.getTemplate(activation.templateKey, activation.templateVersion);
+		if (!this.repository.renewLease(claim, this.clock(), template.execution.limits.timeoutSeconds * 1e3 + 5e3)) return "discarded";
+		const controller = new AbortController();
+		const abort = () => controller.abort(outerSignal?.reason);
+		outerSignal?.addEventListener("abort", abort, { once: true });
+		if (outerSignal?.aborted) abort();
+		const timeout = setTimeout(() => controller.abort(/* @__PURE__ */ new Error("Scene execution timed out")), template.execution.limits.timeoutSeconds * 1e3);
+		let stopWaiting;
+		const aborted = new Promise((_, reject) => {
+			const listener = () => reject(controller.signal.reason ?? /* @__PURE__ */ new Error("Scene execution aborted"));
+			controller.signal.addEventListener("abort", listener, { once: true });
+			stopWaiting = () => controller.signal.removeEventListener("abort", listener);
+			if (controller.signal.aborted) listener();
+		});
+		const assertCurrent = () => {
+			controller.signal.throwIfAborted();
+			if (!this.repository.getRunInput(claim, this.clock())) throw new SceneExecutionRejected("activation_changed");
+		};
+		const readContext = async () => {
+			assertCurrent();
+			let granted;
+			try {
+				granted = await this.authorize(activation);
+			} catch (error) {
+				if (template.contextProviders.includes("mail")) this.repository.recordSourceHealth(activation, sceneSourceFailureReason(error), this.clock(), this.clock() + 6e4);
+				throw error;
+			}
+			assertCurrent();
+			const permissions = intersectPermissions(granted, activation.permissions, {
+				accountIds: accountId === void 0 ? activation.permissions.accountIds : [accountId],
+				contextProviders: template.contextProviders,
+				effectHandlers: []
+			});
+			const evidence = [];
+			for (const providerId of template.contextProviders) {
+				if (!permissions.contextProviders.includes(providerId)) {
+					if (providerId === "mail") this.repository.recordSourceHealth(activation, "needs_permission", this.clock(), this.clock() + 6e4);
+					throw new SceneExecutionRejected("needs_permission");
+				}
+				const provider = this.providers.find((item) => item.id === providerId);
+				if (!provider) throw new SceneExecutionRejected("provider_unavailable");
+				let items;
+				try {
+					items = await provider.read({
+						activation,
+						subjectId,
+						permissions,
+						notBefore,
+						signal: controller.signal
+					});
+				} catch (error) {
+					if (providerId === "mail" && !outerSignal?.aborted) this.repository.recordSourceHealth(activation, sceneSourceFailureReason(error), this.clock(), this.clock() + 6e4);
+					throw error;
+				}
+				assertCurrent();
+				if (providerId === "mail" && items.some((item) => item.accountId === void 0)) throw new SceneExecutionRejected("missing_account_identity");
+				if (items.some((item) => !evidenceAllowed(item, activation, permissions, this.clock()))) throw new SceneExecutionRejected("unauthorized_or_stale_evidence");
+				evidence.push(...items);
+			}
+			if (evidence.length > 100 || evidence.reduce((size, item) => size + item.content.length, 0) > 12e4) throw new SceneExecutionRejected("context_budget_exceeded");
+			if (new Set(evidence.map((item) => item.id)).size !== evidence.length) throw new SceneExecutionRejected("duplicate_evidence");
+			evidence.sort((left, right) => left.id.localeCompare(right.id));
+			const fingerprint = sceneContentHash(evidence.map(({ freshUntil: _freshUntil, ...item }) => item));
+			if (template.contextProviders.includes("mail")) this.repository.recordSourceHealth(activation, null, this.clock());
+			return {
+				evidence,
+				fingerprint,
+				permissions
+			};
+		};
+		const execute = async () => {
+			const snapshot = await readContext();
+			if (!this.repository.saveSnapshot(claim, snapshot.fingerprint, snapshot.evidence.map((item) => item.id), this.clock())) return "discarded";
+			if (this.repository.reuseUnchangedResult(claim, snapshot.fingerprint, this.clock(), true)) {
+				const current = await readContext();
+				assertCurrent();
+				if (current.fingerprint !== snapshot.fingerprint || sceneContentHash(current.permissions) !== sceneContentHash(snapshot.permissions)) throw new SceneExecutionRejected("source_changed");
+				if (this.repository.reuseUnchangedResult(claim, snapshot.fingerprint, this.clock())) return "completed";
+			}
+			if (snapshot.evidence.length > 0 && !this.repository.reserveModelCall(claim, this.clock())) {
+				const now = this.clock();
+				return this.repository.deferRun(claim, now, "daily_budget", (Math.floor(now / 864e5) + 1) * 864e5);
+			}
+			const raw = snapshot.evidence.length === 0 ? {
+				kind: "no_change",
+				summary: "",
+				evidenceIds: []
+			} : await this.executor.execute({
+				template,
+				goal: activation.goal,
+				evidence: snapshot.evidence,
+				signal: controller.signal,
+				onUsage: (usage) => {
+					assertCurrent();
+					this.repository.recordModelUsage(claim, usage, this.clock());
+				}
+			});
+			assertCurrent();
+			const result = readOnlyResultSchema.parse(raw);
+			if (!template.allowedOutcomeKinds.includes(result.kind)) throw new SceneExecutionRejected("invalid_model_result");
+			if (result.evidenceIds.some((id) => !snapshot.evidence.some((item) => item.id === id))) throw new SceneExecutionRejected("unknown_evidence");
+			const current = await readContext();
+			assertCurrent();
+			if (current.fingerprint !== snapshot.fingerprint || sceneContentHash(current.permissions) !== sceneContentHash(snapshot.permissions)) throw new SceneExecutionRejected("source_changed");
+			return this.repository.finishReadOnlyRun(claim, result, this.clock()) ? "completed" : "discarded";
+		};
+		try {
+			return await Promise.race([execute(), aborted]);
+		} catch (error) {
+			if (!controller.signal.aborted && error instanceof SceneSourceNotReady) return this.repository.deferRun(claim, this.clock(), "source_not_ready", this.clock() + 6e4);
+			this.repository.failRun(claim, this.clock(), controller.signal.aborted ? "execution_aborted" : error instanceof SceneExecutionRejected ? error.reason : error instanceof z.ZodError || error instanceof SyntaxError ? "invalid_model_result" : "execution_failed");
+			return "failed";
+		} finally {
+			clearTimeout(timeout);
+			stopWaiting?.();
+			outerSignal?.removeEventListener("abort", abort);
+		}
+	}
+};
+//#endregion
+export { SceneExecutionService, readOnlyResultSchema };

package/dist/src/scenes/httpServices.d.ts

@@ -0,0 +1,34 @@
+import type { BrowserSubscriptionService } from '../notifications/browserSubscriptions.js';
+import type { ScenePrincipal } from './contracts.js';
+import type { SceneInboxService } from './inbox.js';
+import type { SceneRepository } from './repository.js';
+import type { SceneApplicationService } from './service.js';
+import type { SceneMailContextProvider } from './mailContext.js';
+import type { ScenePreferenceService } from './preferences.js';
+import type { SceneMetrics } from './metrics.js';
+/** An explicitly installed scene domain; never resolves to the old runtime. */
+export interface SceneHttpServices {
+    repository: SceneRepository;
+    application: SceneApplicationService;
+    inbox: SceneInboxService;
+    mail: SceneMailContextProvider;
+    mailDiscovery?: {
+        listAccounts(principal: ScenePrincipal): Array<{
+            id: string;
+            label: string;
+        }>;
+        searchSources(principal: ScenePrincipal, value: unknown, signal: AbortSignal): Promise<Array<{
+            id: string;
+            accountId: string;
+            subject: string;
+            sender: string;
+        }>>;
+    };
+    metrics: SceneMetrics;
+    preferences: ScenePreferenceService;
+    browser: BrowserSubscriptionService;
+}
+export interface SceneAccess {
+    principal: ScenePrincipal;
+    services: SceneHttpServices;
+}

package/dist/src/scenes/inbox.d.ts

@@ -0,0 +1,16 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ScenePrincipal } from './contracts.js';
+/** Feedback records a user's judgment, never an inferred successful action. */
+export declare class SceneInboxService {
+    private readonly db;
+    private readonly clock;
+    constructor(db: DatabaseSync, clock?: () => number);
+    setRead(principal: ScenePrincipal, id: string, read: boolean): void;
+    feedback(principal: ScenePrincipal, id: string, value: unknown): number;
+    getFeedback(principal: ScenePrincipal, id: string): {
+        rating: string;
+        note: string;
+        revision: number;
+    } | null;
+    private assertVisible;
+}

package/dist/src/scenes/inbox.js

@@ -0,0 +1,68 @@
+import { SceneConflictError, SceneNotFoundError } from "./repository.js";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+//#region src/scenes/inbox.ts
+const feedbackSchema = z.strictObject({
+	expectedRevision: z.number().int().nonnegative(),
+	rating: z.enum(["useful", "not_useful"]),
+	note: z.string().trim().max(2e3).optional()
+});
+const actionable = `withdrawn_at IS NULL AND (expires_at IS NULL OR expires_at > ?)
+  AND (status IN ('unread', 'read') OR (status = 'snoozed' AND snoozed_until <= ?))`;
+/** Feedback records a user's judgment, never an inferred successful action. */
+var SceneInboxService = class {
+	constructor(db, clock = Date.now) {
+		this.db = db;
+		this.clock = clock;
+	}
+	setRead(principal, id, read) {
+		if (typeof read !== "boolean") throw new Error("Read state must be a boolean");
+		this.assertVisible(principal, id);
+		const now = this.clock();
+		if (this.db.prepare(`UPDATE scene_presentations SET status = ?, revision = revision + 1, updated_at = ? WHERE id = ? AND ${actionable}`).run(read ? "read" : "unread", now, id, now, now).changes !== 1) throw new SceneConflictError("Scene presentation was withdrawn");
+	}
+	feedback(principal, id, value) {
+		const input = feedbackSchema.parse(value);
+		this.assertVisible(principal, id);
+		this.db.exec("SAVEPOINT scene_feedback_write");
+		try {
+			const now = this.clock();
+			const note = input.note ?? String(this.db.prepare("SELECT note FROM scene_feedback WHERE presentation_id = ?").get(id)?.note ?? "");
+			if ((input.expectedRevision === 0 ? this.db.prepare(`INSERT INTO scene_feedback (presentation_id, rating, note, revision, updated_at)
+            SELECT ?, ?, ?, 1, ? WHERE EXISTS (SELECT 1 FROM scene_presentations WHERE id = ? AND ${actionable})
+            ON CONFLICT(presentation_id) DO NOTHING`).run(id, input.rating, note, now, id, now, now) : this.db.prepare(`UPDATE scene_feedback SET rating = ?, note = ?, revision = revision + 1, updated_at = ?
+            WHERE presentation_id = ? AND revision = ?
+            AND EXISTS (SELECT 1 FROM scene_presentations WHERE id = ? AND ${actionable})`).run(input.rating, note, now, id, input.expectedRevision, id, now, now)).changes !== 1) throw new SceneConflictError("Scene feedback changed");
+			this.db.prepare(`INSERT INTO scene_feedback_history(id, presentation_id, rating, note, revision, recorded_at)
+        VALUES (?, ?, ?, ?, ?, ?)`).run(randomUUID(), id, input.rating, note, input.expectedRevision + 1, now);
+			this.db.exec("RELEASE scene_feedback_write");
+			return input.expectedRevision + 1;
+		} catch (error) {
+			this.db.exec("ROLLBACK TO scene_feedback_write");
+			this.db.exec("RELEASE scene_feedback_write");
+			throw error;
+		}
+	}
+	getFeedback(principal, id) {
+		this.assertVisible(principal, id);
+		const row = this.db.prepare("SELECT rating, note, revision FROM scene_feedback WHERE presentation_id = ?").get(id);
+		return row ? {
+			rating: String(row.rating),
+			note: String(row.note),
+			revision: Number(row.revision)
+		} : null;
+	}
+	assertVisible(principal, id) {
+		if (!principal.ownerId?.trim() || !principal.workspaceId?.trim()) throw new Error("Scene principal is required");
+		const row = this.db.prepare(`SELECT p.status, p.withdrawn_at, p.expires_at, p.snoozed_until FROM scene_presentations p
+      JOIN scene_outcomes o ON o.id = p.outcome_id JOIN scene_runs r ON r.id = o.run_id
+      JOIN scene_activations a ON a.id = r.activation_id
+      WHERE p.id = ? AND a.owner_id = ? AND a.workspace_id = ?`).get(id, principal.ownerId, principal.workspaceId);
+		if (!row) throw new SceneNotFoundError("Scene presentation not found");
+		const now = this.clock();
+		if (row.status === "withdrawn" || row.withdrawn_at !== null) throw new SceneConflictError("Scene presentation was withdrawn");
+		if (row.status === "resolved" || row.expires_at !== null && Number(row.expires_at) <= now || row.status === "snoozed" && (row.snoozed_until === null || Number(row.snoozed_until) > now)) throw new SceneConflictError("Scene presentation is not currently actionable");
+	}
+};
+//#endregion
+export { SceneInboxService };

package/dist/src/scenes/mailContext.d.ts

@@ -0,0 +1,20 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { SceneContextProvider, SceneEvidence } from './execution.js';
+import type { SceneActivation, ScenePrincipal } from './contracts.js';
+/** Reads a bounded, account-scoped thread from synchronized connector knowledge. */
+export declare class SceneMailContextProvider implements SceneContextProvider {
+    private readonly db;
+    private readonly clock;
+    readonly id = "mail";
+    constructor(db: DatabaseSync, clock?: () => number);
+    /** Resolve current account grants for the exact delegated source, including reconnects and revocation. */
+    authorizedAccounts(activation: SceneActivation): string[];
+    /** Picker metadata only; choosing an item still requires explicit activation consent. */
+    listSources(principal: ScenePrincipal, limit?: number, afterId?: string): {
+        id: string;
+        accountId: string;
+        subject: string;
+        sender: string;
+    }[];
+    read(input: Parameters<SceneContextProvider['read']>[0]): Promise<SceneEvidence[]>;
+}

package/dist/src/scenes/mailContext.js

@@ -0,0 +1,106 @@
+import { SceneSourceNotReady } from "./readiness.js";
+//#region src/scenes/mailContext.ts
+const accountJoin = `JOIN connector_accounts a ON a.id = c.account_id AND a.current_connection_id = c.id
+  AND a.principal_id = c.principal_id AND a.connector_id = c.connector_id
+  JOIN connector_installations installation ON installation.id = c.installation_id
+  AND installation.principal_id = c.principal_id AND installation.connector_id = c.connector_id`;
+const accountPolicy = `a.enabled = 1 AND installation.enabled = 1 AND c.status = 'active'
+  AND json_array_length(installation.allowed_agent_ids_json) = 0 AND a.allowed_agent_ids_json IS NULL
+  AND (installation.selected_account_ids_json = 'null' OR EXISTS
+    (SELECT 1 FROM json_each(installation.selected_account_ids_json) WHERE value = a.id))`;
+/** Reads a bounded, account-scoped thread from synchronized connector knowledge. */
+var SceneMailContextProvider = class {
+	id = "mail";
+	constructor(db, clock = Date.now) {
+		this.db = db;
+		this.clock = clock;
+	}
+	/** Resolve current account grants for the exact delegated source, including reconnects and revocation. */
+	authorizedAccounts(activation) {
+		if (activation.scope.kind !== "objects" || activation.scope.ids.length !== 1) return [];
+		const row = this.db.prepare(`SELECT a.id FROM knowledge_source_items k
+      JOIN connector_connections c ON c.id = json_extract(CASE WHEN json_valid(k.metadata_json) THEN k.metadata_json ELSE '{}' END, '$.connectionId')
+      ${accountJoin}
+      WHERE k.item_id = ? AND k.item_type = 'email' AND k.deleted_at IS NULL
+        AND k.sensitivity NOT IN ('secret', 'regulated')
+        AND json_valid(k.metadata_json) AND json_valid(k.normalized_text)
+        AND json_type(k.normalized_text, '$.threadId') = 'text'
+        AND length(trim(json_extract(k.normalized_text, '$.threadId'))) > 0
+        AND NOT EXISTS (SELECT 1 FROM json_each(k.normalized_text, '$.labels') WHERE value IN ('DRAFT', 'TRASH', 'SPAM'))
+        AND json_extract(k.metadata_json, '$.workspaceId') = ? AND c.principal_id = ?
+        AND ${accountPolicy}
+        AND (c.expires_at IS NULL OR julianday(c.expires_at) > julianday(?, 'unixepoch'))`).get(activation.scope.ids[0], activation.workspaceId, activation.ownerId, this.clock() / 1e3);
+		return row && activation.permissions.accountIds.includes(String(row.id)) ? [String(row.id)] : [];
+	}
+	/** Picker metadata only; choosing an item still requires explicit activation consent. */
+	listSources(principal, limit = 50, afterId = "") {
+		if (!principal.ownerId.trim() || !principal.workspaceId.trim()) throw new Error("Scene principal is required");
+		if (!Number.isInteger(limit) || limit < 1 || limit > 100) throw new Error("Invalid source list limit");
+		return this.db.prepare(`SELECT k.item_id AS id, a.id AS accountId,
+        substr(json_extract(k.normalized_text, '$.subject'), 1, 300) AS subject,
+        substr(json_extract(k.normalized_text, '$.sender'), 1, 300) AS sender
+      FROM knowledge_source_items k
+      JOIN connector_connections c ON c.id = json_extract(CASE WHEN json_valid(k.metadata_json) THEN k.metadata_json ELSE '{}' END, '$.connectionId')
+      ${accountJoin}
+      WHERE k.item_type = 'email' AND k.deleted_at IS NULL AND k.sensitivity NOT IN ('secret', 'regulated')
+        AND json_valid(k.normalized_text) AND json_valid(k.metadata_json)
+        AND json_extract(k.metadata_json, '$.workspaceId') = ? AND c.principal_id = ?
+        AND ${accountPolicy}
+        AND (c.expires_at IS NULL OR julianday(c.expires_at) > julianday(?, 'unixepoch'))
+        AND json_type(k.normalized_text, '$.threadId') = 'text' AND length(trim(json_extract(k.normalized_text, '$.threadId'))) > 0
+        AND NOT EXISTS (SELECT 1 FROM json_each(k.normalized_text, '$.labels') WHERE value IN ('DRAFT', 'TRASH', 'SPAM'))
+        AND k.item_id > ? ORDER BY k.item_id LIMIT ?`).all(principal.workspaceId, principal.ownerId, this.clock() / 1e3, afterId, limit).map((row) => ({
+			id: String(row.id),
+			accountId: String(row.accountId),
+			subject: typeof row.subject === "string" ? row.subject : "",
+			sender: typeof row.sender === "string" ? row.sender : ""
+		}));
+	}
+	async read(input) {
+		input.signal.throwIfAborted();
+		if (!input.permissions.contextProviders.includes(this.id)) throw new Error("Mail context permission is required");
+		const origin = this.db.prepare(`SELECT * FROM knowledge_source_items WHERE item_id = ? AND item_type = 'email' AND deleted_at IS NULL`).get(input.subjectId);
+		if (!origin) throw new Error("Mail source unavailable");
+		const metadata = JSON.parse(origin.metadata_json);
+		if (metadata.workspaceId !== input.activation.workspaceId || typeof metadata.connectionId !== "string") throw new Error("Mail source workspace mismatch");
+		const connection = this.db.prepare(`SELECT c.account_id, c.expires_at FROM connector_connections c
+      ${accountJoin} WHERE c.id = ? AND c.principal_id = ? AND ${accountPolicy}`).get(metadata.connectionId, input.activation.ownerId);
+		if (!connection || !input.permissions.accountIds.includes(connection.account_id)) throw new Error("Mail account permission is required");
+		if (connection.expires_at !== null && !(Date.parse(connection.expires_at) > this.clock())) throw new Error("Mail connection is expired");
+		const fields = JSON.parse(origin.normalized_text);
+		if (typeof fields.threadId !== "string" || !fields.threadId.trim()) throw new Error("Mail thread identity unavailable");
+		if (Array.isArray(fields.labels) && fields.labels.some((label) => [
+			"DRAFT",
+			"TRASH",
+			"SPAM"
+		].includes(label))) throw new Error("Mail origin is not an active message");
+		const sync = this.db.prepare(`SELECT status, started_at, finished_at FROM knowledge_sync_runs
+      WHERE source_instance_id = ? AND collection_scope = ? ORDER BY started_at DESC, rowid DESC LIMIT 1`).get(origin.source_instance_id, origin.collection_scope);
+		const now = this.clock();
+		if (!sync || sync.status !== "succeeded" || sync.finished_at === null || sync.finished_at < sync.started_at || sync.started_at > now || sync.finished_at > now || sync.started_at + 30 * 6e4 <= now || input.notBefore !== void 0 && sync.started_at < input.notBefore) throw new SceneSourceNotReady();
+		const messages = this.db.prepare(`SELECT * FROM knowledge_source_items
+      WHERE source_instance_id = ? AND collection_scope = ? AND item_type = 'email' AND deleted_at IS NULL
+      AND json_valid(normalized_text) AND json_valid(metadata_json)
+      AND json_extract(normalized_text, '$.threadId') = ?
+      AND json_extract(metadata_json, '$.connectionId') = ?
+      AND json_extract(metadata_json, '$.workspaceId') = ?
+      AND NOT EXISTS (SELECT 1 FROM json_each(normalized_text, '$.labels') WHERE value IN ('DRAFT', 'TRASH', 'SPAM'))
+      ORDER BY occurred_at, item_id LIMIT 31`).all(origin.source_instance_id, origin.collection_scope, fields.threadId, metadata.connectionId, input.activation.workspaceId);
+		if (!messages.length || messages.length > 30) throw new Error("Mail thread cannot be read completely within its budget");
+		if (messages.some((item) => ["secret", "regulated"].includes(item.sensitivity))) throw new Error("Mail thread contains restricted evidence");
+		input.signal.throwIfAborted();
+		return messages.map((item) => ({
+			id: item.item_id,
+			subjectId: input.subjectId,
+			ownerId: input.activation.ownerId,
+			workspaceId: input.activation.workspaceId,
+			accountId: connection.account_id,
+			revision: item.content_hash,
+			freshUntil: sync.started_at + 30 * 6e4,
+			...item.occurred_at !== null ? { occurredAt: item.occurred_at } : {},
+			content: item.normalized_text
+		}));
+	}
+};
+//#endregion
+export { SceneMailContextProvider };

package/dist/src/scenes/mailObservations.d.ts

@@ -0,0 +1,20 @@
+import { type SceneActivation, type ScenePermission } from './contracts.js';
+import type { SceneContextProvider } from './execution.js';
+import { SceneRepository } from './repository.js';
+/** Observes only explicitly delegated threads; the host owns scan scheduling. */
+export declare class SceneMailObservationService {
+    private readonly repository;
+    private readonly provider;
+    private readonly authorize;
+    private readonly clock;
+    private readonly intervalMs;
+    private readonly itemTimeoutMs;
+    private nextScanAt;
+    private readonly failures;
+    constructor(repository: SceneRepository, provider: SceneContextProvider, authorize: (activation: SceneActivation) => Promise<ScenePermission>, clock?: () => number, intervalMs?: number, itemTimeoutMs?: number);
+    scan(signal: AbortSignal, afterId?: string, progress?: (id: string) => void): Promise<{
+        changed: number;
+        unavailable: number;
+        nextCursor: string | null;
+    }>;
+}

package/dist/src/scenes/mailObservations.js

@@ -0,0 +1,107 @@
+import { intersectPermissions, sceneContentHash } from "./contracts.js";
+import { sceneSourceFailureReason } from "./readiness.js";
+//#region src/scenes/mailObservations.ts
+/** Observes only explicitly delegated threads; the host owns scan scheduling. */
+var SceneMailObservationService = class {
+	nextScanAt = 0;
+	failures = /* @__PURE__ */ new Map();
+	constructor(repository, provider, authorize, clock = Date.now, intervalMs = 0, itemTimeoutMs = 5e3) {
+		this.repository = repository;
+		this.provider = provider;
+		this.authorize = authorize;
+		this.clock = clock;
+		this.intervalMs = intervalMs;
+		this.itemTimeoutMs = itemTimeoutMs;
+		if (provider.id !== "mail") throw new Error("Mail observation requires the mail context provider");
+	}
+	async scan(signal, afterId = "", progress) {
+		signal.throwIfAborted();
+		if (!afterId && this.clock() < this.nextScanAt) return {
+			changed: 0,
+			unavailable: 0,
+			nextCursor: null
+		};
+		const items = this.repository.listMailObservationItems(afterId, this.clock());
+		const started = Date.now();
+		let lastId = afterId;
+		let processed = 0;
+		let changed = 0;
+		let unavailable = 0;
+		for (const { principal, item } of items) {
+			signal.throwIfAborted();
+			if (Date.now() - started >= 2e4) break;
+			lastId = item.id;
+			processed += 1;
+			const backoff = this.failures.get(item.accountId);
+			if (this.intervalMs > 0 && backoff && backoff.until > this.clock()) {
+				progress?.(lastId);
+				continue;
+			}
+			const controller = new AbortController();
+			const abort = () => controller.abort(signal.reason);
+			signal.addEventListener("abort", abort, { once: true });
+			const timeout = setTimeout(() => controller.abort(/* @__PURE__ */ new Error("Mail item timed out")), this.itemTimeoutMs);
+			let rejectAbort = () => {};
+			const aborted = new Promise((_, reject) => {
+				rejectAbort = () => reject(controller.signal.reason);
+				controller.signal.addEventListener("abort", rejectAbort, { once: true });
+			});
+			let activation;
+			try {
+				activation = this.repository.getActivation(principal, item.activationId);
+				const template = this.repository.getTemplate(activation.templateKey, activation.templateVersion);
+				if (!template.contextProviders.includes("mail") || !template.triggers.some((trigger) => trigger.type === "event" && trigger.eventType === "mail.thread.changed") || activation.scope.kind !== "objects" || !activation.scope.ids.includes(item.subjectId)) throw new Error("Mail observation is outside the template or delegated scope");
+				const permissions = intersectPermissions(activation.permissions, await Promise.race([this.authorize(activation), aborted]), {
+					accountIds: [item.accountId],
+					contextProviders: ["mail"],
+					effectHandlers: []
+				});
+				signal.throwIfAborted();
+				if (!this.repository.isMailObservationCurrent(activation, item, this.clock())) throw new Error("Mail delegation changed during authorization");
+				if (!permissions.accountIds.includes(item.accountId) || !permissions.contextProviders.includes("mail")) throw new Error("Mail observation permission is required");
+				const evidence = await Promise.race([this.provider.read({
+					activation,
+					permissions,
+					subjectId: item.subjectId,
+					signal: controller.signal
+				}), aborted]);
+				signal.throwIfAborted();
+				if (!evidence.length || evidence.length > 100 || new Set(evidence.map((entry) => entry.id)).size !== evidence.length || evidence.reduce((size, entry) => size + entry.content.length, 0) > 12e4 || evidence.some((entry) => !entry.id || !entry.revision || entry.ownerId !== principal.ownerId || entry.workspaceId !== principal.workspaceId || entry.accountId !== item.accountId || entry.subjectId !== item.subjectId || !Number.isFinite(entry.freshUntil) || entry.freshUntil <= this.clock())) throw new Error("Mail observation is incomplete or unauthorized");
+				const currentPermissions = intersectPermissions(permissions, await Promise.race([this.authorize(activation), aborted]));
+				signal.throwIfAborted();
+				if (!this.repository.isMailObservationCurrent(activation, item, this.clock())) throw new Error("Mail delegation changed during observation");
+				if (sceneContentHash(currentPermissions) !== sceneContentHash(permissions)) throw new Error("Mail observation permission changed");
+				this.repository.recordSourceHealth(activation, null, this.clock());
+				this.failures.delete(item.accountId);
+				const fingerprint = sceneContentHash(evidence.map(({ freshUntil: _freshUntil, ...entry }) => entry).sort((a, b) => a.id.localeCompare(b.id)));
+				if (this.repository.observeMailWorkItem(principal, item, fingerprint, this.clock())) changed += 1;
+			} catch (error) {
+				signal.throwIfAborted();
+				unavailable += 1;
+				const retryDelay = Math.max(this.intervalMs, Math.min(3e5, 1e4 * 2 ** Math.min((backoff?.count ?? 0) + 1, 5)));
+				if (activation && this.repository.isMailObservationCurrent(activation, item, this.clock())) this.repository.recordSourceHealth(activation, sceneSourceFailureReason(error), this.clock(), this.clock() + Math.max(retryDelay, 6e4));
+				if (this.intervalMs > 0) {
+					const count = Math.min((backoff?.count ?? 0) + 1, 5);
+					this.failures.set(item.accountId, {
+						count,
+						until: this.clock() + Math.min(3e5, 1e4 * 2 ** count)
+					});
+				}
+			} finally {
+				clearTimeout(timeout);
+				signal.removeEventListener("abort", abort);
+				controller.signal.removeEventListener("abort", rejectAbort);
+				if (!signal.aborted) progress?.(lastId);
+			}
+		}
+		const nextCursor = processed < items.length || items.length === 100 ? lastId : null;
+		if (nextCursor === null) this.nextScanAt = this.clock() + this.intervalMs;
+		return {
+			changed,
+			unavailable,
+			nextCursor
+		};
+	}
+};
+//#endregion
+export { SceneMailObservationService };

package/dist/src/scenes/maintenance.d.ts

@@ -0,0 +1,3 @@
+import type { DatabaseSync } from 'node:sqlite';
+/** Keeps identity/deduplication rows; removes bounded old payloads only after their work is terminal. */
+export declare function maintainSceneStorage(db: DatabaseSync, now?: number): void;

package/dist/src/scenes/maintenance.js

@@ -0,0 +1,24 @@
+import { init_transaction, runSqliteSavepoint } from "../storage/sqlite/transaction.js";
+//#region src/scenes/maintenance.ts
+init_transaction();
+/** Keeps identity/deduplication rows; removes bounded old payloads only after their work is terminal. */
+function maintainSceneStorage(db, now = Date.now()) {
+	const cutoff = now - 90 * 864e5;
+	runSqliteSavepoint(db, () => {
+		db.prepare("DELETE FROM scene_connector_usage WHERE utc_day < ?").run(Math.floor(cutoff / 864e5));
+		db.prepare("DELETE FROM notification_presence WHERE expires_at <= ?").run(now);
+		db.prepare("DELETE FROM notification_browser_subscriptions WHERE expires_at <= ?").run(now);
+		db.prepare(`DELETE FROM scene_mail_sources WHERE id IN (SELECT s.id FROM scene_mail_sources s
+      WHERE s.selected_at < ? AND NOT EXISTS (SELECT 1 FROM scene_activations a, json_each(a.scope_json, '$.ids') ids WHERE ids.value = s.id)
+      ORDER BY selected_at LIMIT 100)`).run(now - 30 * 864e5);
+		for (const table of [
+			"scene_context_snapshots",
+			"scene_model_reservations",
+			"scene_model_usage"
+		]) db.prepare(`DELETE FROM ${table} WHERE run_id IN (SELECT DISTINCT r.id FROM scene_runs r JOIN ${table} t ON t.run_id = r.id
+        WHERE r.status NOT IN ('running', 'retry_wait') AND r.created_at < ? ORDER BY r.created_at LIMIT 100)`).run(cutoff);
+		db.prepare("DELETE FROM notification_attention_budget WHERE dedupe_key IN (SELECT dedupe_key FROM notification_attention_budget WHERE created_at < ? LIMIT 100)").run(cutoff);
+	});
+}
+//#endregion
+export { maintainSceneStorage };

package/dist/src/scenes/metrics.d.ts

@@ -0,0 +1,35 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ScenePrincipal } from './contracts.js';
+/** Explicit feedback is a usefulness signal, not proof of adoption or saved time. */
+export declare class SceneMetrics {
+    private readonly db;
+    private readonly clock;
+    constructor(db: DatabaseSync, clock?: () => number);
+    diagnostics(principal: ScenePrincipal): {
+        checksPaused: boolean;
+        pendingChecks: number;
+        oldestDueWaitMs: number;
+        lastSevenDays: {
+            modelCalls: number;
+            connectorReads: number;
+            tokens: number;
+            estimatedCost: number;
+        };
+        notifications: Record<string, import("node:sqlite").SQLOutputValue>[];
+        activations: Record<string, import("node:sqlite").SQLOutputValue>[];
+    };
+    forUser(principal: ScenePrincipal, days?: number): {
+        window: {
+            since: number;
+            until: number;
+            days: number;
+        };
+        ratedOutcomes: number;
+        usefulOutcomes: number;
+        unhelpfulOutcomes: number;
+        scenesWithUsefulOutcomes: number;
+        checks: number;
+        failedChecks: number;
+        skippedChecks: number;
+    };
+}