@xopcai/xopc 0.0.309 → 0.0.312

package/dist/src/scenes/metrics.js

@@ -0,0 +1,100 @@
+//#region src/scenes/metrics.ts
+/** Explicit feedback is a usefulness signal, not proof of adoption or saved time. */
+var SceneMetrics = class {
+	constructor(db, clock = Date.now, modelRef = () => null) {
+		this.db = db;
+		this.clock = clock;
+		this.modelRef = modelRef;
+	}
+	diagnostics(principal) {
+		if (!principal.ownerId.trim() || !principal.workspaceId.trim()) throw new Error("Scene principal is required");
+		const now = this.clock();
+		const queue = this.db.prepare(`SELECT COUNT(*) AS depth, MIN(i.due_at) AS oldest
+      FROM scene_trigger_intents i JOIN scene_activations a ON a.id = i.activation_id
+      WHERE a.owner_id = ? AND a.workspace_id = ? AND i.status = 'pending'`).get(principal.ownerId, principal.workspaceId);
+		const usage = this.db.prepare(`SELECT COUNT(*) AS calls, COALESCE(SUM(u.total_tokens), 0) AS tokens,
+      COALESCE(SUM(u.estimated_cost), 0) AS cost FROM scene_model_usage u JOIN scene_runs r ON r.id = u.run_id
+      JOIN scene_activations a ON a.id = r.activation_id WHERE a.owner_id = ? AND a.workspace_id = ? AND u.recorded_at >= ?`).get(principal.ownerId, principal.workspaceId, now - 7 * 864e5);
+		const connectorReads = Number(this.db.prepare(`SELECT COALESCE(SUM(request_count), 0) AS count FROM scene_connector_usage
+      WHERE owner_id = ? AND workspace_id = ? AND utc_day >= ?`).get(principal.ownerId, principal.workspaceId, Math.floor(now / 864e5) - 6)?.count);
+		const notifications = this.db.prepare(`SELECT status, COUNT(*) AS count FROM notification_dispatches
+      WHERE owner_id = ? AND workspace_id = ? GROUP BY status`).all(principal.ownerId, principal.workspaceId);
+		const activations = this.db.prepare(`SELECT a.id, a.status,
+      (SELECT MAX(created_at) FROM scene_runs WHERE activation_id = a.id) AS last_check_at,
+      (SELECT reason FROM scene_runs WHERE activation_id = a.id ORDER BY created_at DESC, id DESC LIMIT 1) AS last_reason,
+      CASE WHEN a.status = 'active' THEN (SELECT MIN(next_due_at) FROM scene_schedule_cursors WHERE activation_id = a.id) END AS next_schedule_at,
+      (SELECT MIN(due_at) FROM scene_work_items WHERE activation_id = a.id AND status = 'watching') AS deadline_at,
+      CASE WHEN a.status = 'active' THEN (SELECT MIN(due_at) FROM scene_work_items WHERE activation_id = a.id AND status = 'watching' AND (last_triggered_revision IS NULL OR last_triggered_revision <> revision)) END AS next_deadline_check_at,
+      (SELECT MIN(retry_at) FROM scene_runs WHERE activation_id = a.id AND status = 'retry_wait') AS retry_at,
+      (SELECT reason FROM scene_source_health WHERE activation_id = a.id) AS source_reason,
+      (SELECT last_attempt_at FROM scene_source_health WHERE activation_id = a.id) AS source_attempt_at,
+      (SELECT consecutive_failures FROM scene_source_health WHERE activation_id = a.id) AS source_failures,
+      (SELECT last_success_at FROM scene_source_health WHERE activation_id = a.id) AS source_success_at,
+      (SELECT retry_at FROM scene_source_health WHERE activation_id = a.id) AS source_retry_at
+      FROM scene_activations a WHERE a.owner_id = ? AND a.workspace_id = ? ORDER BY a.id LIMIT 100`).all(principal.ownerId, principal.workspaceId);
+		const policyRow = this.db.prepare("SELECT preferences_json FROM scene_preferences WHERE owner_id = ? AND workspace_id = ?").get(principal.ownerId, principal.workspaceId);
+		const policy = policyRow ? JSON.parse(String(policyRow.preferences_json)) : {};
+		const checksPaused = policy.checksPaused === true || Date.parse(policy.checksPausedUntil ?? "") > now;
+		if (checksPaused) for (const activation of activations) {
+			activation.next_schedule_at = null;
+			activation.next_deadline_check_at = null;
+			activation.retry_at = null;
+		}
+		let currentModel = null;
+		try {
+			currentModel = this.modelRef();
+		} catch {}
+		return {
+			checksPaused,
+			currentModel,
+			pendingChecks: Number(queue.depth),
+			oldestDueWaitMs: queue.oldest == null ? 0 : Math.max(0, now - Number(queue.oldest)),
+			lastSevenDays: {
+				modelCalls: Number(usage.calls),
+				connectorReads,
+				tokens: Number(usage.tokens),
+				estimatedCost: Number(usage.cost)
+			},
+			notifications,
+			activations
+		};
+	}
+	forUser(principal, days = 7) {
+		if (!principal.ownerId?.trim() || !principal.workspaceId?.trim()) throw new Error("Scene principal is required");
+		if (!Number.isInteger(days) || days < 1 || days > 90) throw new Error("Scene metric window must be 1–90 days");
+		const until = this.clock();
+		const since = until - days * 864e5;
+		const feedback = this.db.prepare(`SELECT
+      COUNT(*) AS ratedOutcomes,
+      COALESCE(SUM(CASE WHEN f.rating = 'useful' THEN 1 ELSE 0 END), 0) AS usefulOutcomes,
+      COALESCE(SUM(CASE WHEN f.rating = 'not_useful' THEN 1 ELSE 0 END), 0) AS unhelpfulOutcomes,
+      COUNT(DISTINCT CASE WHEN f.rating = 'useful' THEN a.id END) AS scenesWithUsefulOutcomes
+      FROM scene_feedback_history f JOIN scene_feedback latest
+        ON latest.presentation_id = f.presentation_id AND latest.revision = f.revision
+      JOIN scene_presentations p ON p.id = f.presentation_id 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 a.owner_id = ? AND a.workspace_id = ?
+        AND f.recorded_at >= ? AND f.recorded_at < ?`).get(principal.ownerId, principal.workspaceId, since, until);
+		const work = this.db.prepare(`SELECT COUNT(*) AS checks,
+      COALESCE(SUM(CASE WHEN r.status = 'failed' THEN 1 ELSE 0 END), 0) AS failedChecks,
+      COALESCE(SUM(CASE WHEN r.status = 'skipped' THEN 1 ELSE 0 END), 0) AS skippedChecks
+      FROM scene_runs r JOIN scene_activations a ON a.id = r.activation_id
+      WHERE a.owner_id = ? AND a.workspace_id = ? AND r.created_at >= ? AND r.created_at < ?`).get(principal.ownerId, principal.workspaceId, since, until);
+		return {
+			window: {
+				since,
+				until,
+				days
+			},
+			ratedOutcomes: Number(feedback.ratedOutcomes),
+			usefulOutcomes: Number(feedback.usefulOutcomes),
+			unhelpfulOutcomes: Number(feedback.unhelpfulOutcomes),
+			scenesWithUsefulOutcomes: Number(feedback.scenesWithUsefulOutcomes),
+			checks: Number(work.checks),
+			failedChecks: Number(work.failedChecks),
+			skippedChecks: Number(work.skippedChecks)
+		};
+	}
+};
+//#endregion
+export { SceneMetrics };

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

@@ -0,0 +1,3 @@
+import type { Config } from '../config/schema.js';
+/** Scene reasoning follows the existing agent model policy and falls back to chat. */
+export declare function resolveSceneModelRef(config: Config): string;

package/dist/src/scenes/model.js

@@ -0,0 +1,10 @@
+import { init_agent_scope, resolveDefaultAgentId } from "../agent/agent-scope.js";
+import { resolveModelSelector } from "../config/agent-model-intents.js";
+//#region src/scenes/model.ts
+init_agent_scope();
+/** Scene reasoning follows the existing agent model policy and falls back to chat. */
+function resolveSceneModelRef(config) {
+	return resolveModelSelector(config, resolveDefaultAgentId(config), "@reasoning");
+}
+//#endregion
+export { resolveSceneModelRef };

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

@@ -0,0 +1,17 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { NotificationResult } from '../notifications/resultOutbox.js';
+export type SceneNotificationEligibility = {
+    action: 'cancel';
+    reason: string;
+} | {
+    action: 'defer';
+    until: number;
+} | {
+    action: 'eligible';
+    activationId: string;
+    presentationId: string;
+    revision: number;
+    kind: string;
+};
+/** Local result eligibility only. The host must still recheck connector authorization and attention policy. */
+export declare function sceneNotificationEligibility(db: DatabaseSync, result: NotificationResult, now: number, expectedRevision?: number): SceneNotificationEligibility;

package/dist/src/scenes/notificationEligibility.js

@@ -0,0 +1,72 @@
+//#region src/scenes/notificationEligibility.ts
+/** Local result eligibility only. The host must still recheck connector authorization and attention policy. */
+function sceneNotificationEligibility(db, result, now, expectedRevision) {
+	if (!result.ownerId.trim() || !result.workspaceId.trim() || !result.subjectId.trim()) return {
+		action: "cancel",
+		reason: "invalid_scope"
+	};
+	const row = db.prepare(`SELECT p.id, p.status, p.notification_revision, p.withdrawn_at, p.expires_at, p.snoozed_until,
+      r.activation_id, r.activation_revision, a.revision, a.status AS activation_status, o.kind
+    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 p.destination = 'inbox' AND a.owner_id = ? AND a.workspace_id = ?`).get(result.subjectId, result.ownerId, result.workspaceId);
+	if (!row) return {
+		action: "cancel",
+		reason: "result_unavailable"
+	};
+	if (row.activation_status !== "active") return {
+		action: "cancel",
+		reason: "activation_inactive"
+	};
+	if (row.activation_revision !== row.revision) return {
+		action: "cancel",
+		reason: "activation_changed"
+	};
+	if (row.kind === "no_change") return {
+		action: "cancel",
+		reason: "no_change"
+	};
+	if (expectedRevision !== void 0 && row.notification_revision !== expectedRevision) return {
+		action: "cancel",
+		reason: "result_changed"
+	};
+	if (row.withdrawn_at !== null || row.status === "withdrawn") return {
+		action: "cancel",
+		reason: "result_withdrawn"
+	};
+	if (row.expires_at !== null && Number(row.expires_at) <= now) return {
+		action: "cancel",
+		reason: "result_expired"
+	};
+	if (row.status === "read" || row.status === "resolved") return {
+		action: "cancel",
+		reason: "result_reviewed"
+	};
+	if (row.status === "snoozed") {
+		if (row.snoozed_until === null) return {
+			action: "cancel",
+			reason: "invalid_snooze"
+		};
+		if (Number(row.snoozed_until) > now) return {
+			action: "defer",
+			until: Number(row.snoozed_until)
+		};
+	} else if (row.status !== "unread") return {
+		action: "cancel",
+		reason: "result_unavailable"
+	};
+	const health = db.prepare("SELECT reason, retry_at FROM scene_source_health WHERE activation_id = ?").get(row.activation_id);
+	if (health?.reason) return {
+		action: "defer",
+		until: Math.max(now + 6e4, Number(health.retry_at ?? 0))
+	};
+	return {
+		action: "eligible",
+		activationId: String(row.activation_id),
+		presentationId: String(row.id),
+		revision: Number(row.notification_revision),
+		kind: String(row.kind)
+	};
+}
+//#endregion
+export { sceneNotificationEligibility };

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

@@ -0,0 +1,7 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { NotificationResultOutbox, type NotificationResult, type PublicationDecision } from '../notifications/resultOutbox.js';
+import { type SceneNotificationEligibility } from './notificationEligibility.js';
+/** The required host callback applies attention policy and persists notification/dispatch records, without sending. */
+export declare function createSceneNotificationOutbox(db: DatabaseSync, publish: (result: NotificationResult, eligible: Extract<SceneNotificationEligibility, {
+    action: 'eligible';
+}>) => PublicationDecision, clock?: () => number): NotificationResultOutbox;

package/dist/src/scenes/notificationPublication.js

@@ -0,0 +1,43 @@
+import { ScenePreferenceService, sceneChecksAllowed } from "./preferences.js";
+import { notificationQuietUntil } from "../notifications/quietHours.js";
+import { NotificationResultOutbox } from "../notifications/resultOutbox.js";
+import { sceneNotificationEligibility } from "./notificationEligibility.js";
+//#region src/scenes/notificationPublication.ts
+/** The required host callback applies attention policy and persists notification/dispatch records, without sending. */
+function createSceneNotificationOutbox(db, publish, clock = Date.now) {
+	return new NotificationResultOutbox(db, (result) => {
+		const now = clock();
+		const eligibility = sceneNotificationEligibility(db, result, now);
+		if (eligibility.action === "cancel") return {
+			action: "settle",
+			reason: eligibility.reason
+		};
+		if (eligibility.action === "defer") return {
+			...eligibility,
+			reason: "result_snoozed"
+		};
+		const preferences = new ScenePreferenceService(db).get(result);
+		if (!sceneChecksAllowed(preferences, now)) return {
+			action: "settle",
+			reason: "checks_paused"
+		};
+		if (preferences.notificationsMuted || preferences.level === "quiet") return {
+			action: "settle",
+			reason: "notifications_muted"
+		};
+		if (preferences.suppressWhileViewing && db.prepare(`SELECT 1 FROM notification_presence
+      WHERE owner_id = ? AND workspace_id = ? AND subject_id = ? AND subject_revision = ? AND expires_at > ?`).get(result.ownerId, result.workspaceId, result.subjectId, eligibility.revision, now)) return {
+			action: "settle",
+			reason: "result_viewed"
+		};
+		const quietUntil = notificationQuietUntil(preferences, now);
+		if (quietUntil !== null) return {
+			action: "defer",
+			until: quietUntil,
+			reason: "quiet_hours"
+		};
+		return publish(result, eligibility);
+	}, clock);
+}
+//#endregion
+export { createSceneNotificationOutbox };

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

@@ -0,0 +1,40 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { z } from 'zod';
+import type { ScenePrincipal } from './contracts.js';
+export declare const scenePreferencesSchema: z.ZodObject<{
+    level: z.ZodDefault<z.ZodEnum<{
+        active: "active";
+        quiet: "quiet";
+        balanced: "balanced";
+    }>>;
+    timezone: z.ZodDefault<z.ZodString>;
+    quietStartHour: z.ZodDefault<z.ZodNumber>;
+    quietEndHour: z.ZodDefault<z.ZodNumber>;
+    dailyNotificationLimit: z.ZodDefault<z.ZodNumber>;
+    digestEnabled: z.ZodDefault<z.ZodBoolean>;
+    digestHour: z.ZodDefault<z.ZodNumber>;
+    digestMinute: z.ZodDefault<z.ZodNumber>;
+    preferredChannel: z.ZodDefault<z.ZodEnum<{
+        browser: "browser";
+        in_app: "in_app";
+    }>>;
+    suppressWhileViewing: z.ZodDefault<z.ZodBoolean>;
+    checksPaused: z.ZodDefault<z.ZodBoolean>;
+    checksPausedUntil: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    notificationsMuted: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export type ScenePreferences = z.infer<typeof scenePreferencesSchema>;
+/** Owner-scoped choices. Muting presentation never changes check permissions or deletes work. */
+export declare class ScenePreferenceService {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    get(principal: ScenePrincipal): ScenePreferences & {
+        revision: number;
+    };
+    update(principal: ScenePrincipal, value: unknown): ScenePreferences & {
+        revision: number;
+    };
+    recordPresence(principal: ScenePrincipal, value: unknown, now?: number): void;
+    private assertPrincipal;
+}
+export declare function sceneChecksAllowed(preferences: ScenePreferences, now: number): boolean;

package/dist/src/scenes/preferences.js

@@ -0,0 +1,108 @@
+import { SceneConflictError, SceneNotFoundError } from "./repository.js";
+import { z } from "zod";
+//#region src/scenes/preferences.ts
+const hour = z.number().int().min(0).max(23);
+const scenePreferencesSchema = z.strictObject({
+	level: z.enum([
+		"quiet",
+		"balanced",
+		"active"
+	]).default("balanced"),
+	timezone: z.string().min(1).max(100).refine((value) => {
+		try {
+			new Intl.DateTimeFormat("en", { timeZone: value });
+			return true;
+		} catch {
+			return false;
+		}
+	}).default("Asia/Shanghai"),
+	quietStartHour: hour.default(22),
+	quietEndHour: hour.default(8),
+	dailyNotificationLimit: z.number().int().min(0).max(30).default(3),
+	digestEnabled: z.boolean().default(false),
+	digestHour: hour.default(18),
+	digestMinute: z.number().int().min(0).max(59).default(0),
+	preferredChannel: z.enum(["in_app", "browser"]).default("browser"),
+	suppressWhileViewing: z.boolean().default(true),
+	checksPaused: z.boolean().default(false),
+	checksPausedUntil: z.string().datetime({ offset: true }).nullable().default(null),
+	notificationsMuted: z.boolean().default(false)
+});
+/** Owner-scoped choices. Muting presentation never changes check permissions or deletes work. */
+var ScenePreferenceService = class {
+	constructor(db) {
+		this.db = db;
+	}
+	get(principal) {
+		this.assertPrincipal(principal);
+		const row = this.db.prepare("SELECT preferences_json, revision FROM scene_preferences WHERE owner_id = ? AND workspace_id = ?").get(principal.ownerId, principal.workspaceId);
+		return {
+			...scenePreferencesSchema.parse(row ? JSON.parse(String(row.preferences_json)) : {}),
+			revision: row ? Number(row.revision) : 0
+		};
+	}
+	update(principal, value) {
+		this.assertPrincipal(principal);
+		const supplied = z.record(z.string(), z.unknown()).parse(value);
+		const { expectedRevision, ...parsed } = scenePreferencesSchema.partial().extend({ expectedRevision: z.number().int().nonnegative() }).parse(value);
+		const patch = Object.fromEntries(Object.entries(parsed).filter(([key]) => Object.hasOwn(supplied, key) && supplied[key] !== void 0));
+		this.db.exec("SAVEPOINT scene_preferences_write");
+		try {
+			const { revision, ...current } = this.get(principal);
+			if (revision !== expectedRevision) throw new SceneConflictError("Scene preferences changed");
+			const next = scenePreferencesSchema.parse({
+				...current,
+				...patch
+			});
+			this.db.prepare(`INSERT INTO scene_preferences(owner_id, workspace_id, preferences_json, revision) VALUES (?, ?, ?, ?)
+        ON CONFLICT(owner_id, workspace_id) DO UPDATE SET preferences_json = excluded.preferences_json, revision = excluded.revision`).run(principal.ownerId, principal.workspaceId, JSON.stringify(next), revision + 1);
+			if (next.checksPaused !== current.checksPaused || next.checksPausedUntil !== current.checksPausedUntil) {
+				this.db.prepare("UPDATE scene_activations SET revision = revision + 1 WHERE owner_id = ? AND workspace_id = ? AND status = 'active'").run(principal.ownerId, principal.workspaceId);
+				this.db.prepare(`UPDATE scene_runs SET status = 'cancelled', reason = 'check_policy_changed', lease_epoch = lease_epoch + 1,
+          lease_owner = NULL, lease_until = NULL WHERE status IN ('running', 'retry_wait') AND activation_id IN
+          (SELECT id FROM scene_activations WHERE owner_id = ? AND workspace_id = ?)`).run(principal.ownerId, principal.workspaceId);
+				this.db.prepare(`UPDATE scene_trigger_intents SET status = 'cancelled' WHERE status IN ('pending', 'claimed') AND activation_id IN
+          (SELECT id FROM scene_activations WHERE owner_id = ? AND workspace_id = ?)`).run(principal.ownerId, principal.workspaceId);
+			}
+			this.db.exec("RELEASE scene_preferences_write");
+			return {
+				...next,
+				revision: revision + 1
+			};
+		} catch (error) {
+			this.db.exec("ROLLBACK TO scene_preferences_write");
+			this.db.exec("RELEASE scene_preferences_write");
+			throw error;
+		}
+	}
+	recordPresence(principal, value, now = Date.now()) {
+		this.assertPrincipal(principal);
+		const input = z.strictObject({
+			clientId: z.string().trim().min(1).max(100),
+			surface: z.enum(["web", "electron"]),
+			presentationId: z.string().min(1).max(200),
+			visible: z.boolean()
+		}).parse(value);
+		if (!input.visible) {
+			this.db.prepare("DELETE FROM notification_presence WHERE owner_id = ? AND workspace_id = ? AND client_id = ?").run(principal.ownerId, principal.workspaceId, input.clientId);
+			return;
+		}
+		const row = this.db.prepare(`SELECT p.notification_revision 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 = ? AND p.withdrawn_at IS NULL`).get(input.presentationId, principal.ownerId, principal.workspaceId);
+		if (!row) throw new SceneNotFoundError("Scene result not found");
+		this.db.prepare(`INSERT INTO notification_presence VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(owner_id, workspace_id, client_id) DO UPDATE SET surface = excluded.surface,
+        expires_at = excluded.expires_at, subject_id = excluded.subject_id, subject_revision = excluded.subject_revision`).run(principal.ownerId, principal.workspaceId, input.clientId, input.surface, now + 45e3, input.presentationId, row.notification_revision);
+		this.db.prepare("DELETE FROM notification_presence WHERE expires_at <= ?").run(now);
+	}
+	assertPrincipal(principal) {
+		if (!principal.ownerId.trim() || !principal.workspaceId.trim()) throw new Error("Scene principal is required");
+	}
+};
+function sceneChecksAllowed(preferences, now) {
+	return !preferences.checksPaused && !(preferences.checksPausedUntil && Date.parse(preferences.checksPausedUntil) > now);
+}
+//#endregion
+export { ScenePreferenceService, sceneChecksAllowed, scenePreferencesSchema };

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

@@ -0,0 +1,7 @@
+export type SceneSourceFailure = 'source_not_ready' | 'needs_permission' | 'source_rate_limited' | 'source_timeout';
+/** A source failure is separate from a model execution failure. */
+export declare class SceneSourceNotReady extends Error {
+    readonly reason: SceneSourceFailure;
+    constructor(reason?: SceneSourceFailure);
+}
+export declare function sceneSourceFailureReason(error: unknown): SceneSourceFailure;

package/dist/src/scenes/readiness.js

@@ -0,0 +1,20 @@
+//#region src/scenes/readiness.ts
+/** A source failure is separate from a model execution failure. */
+var SceneSourceNotReady = class extends Error {
+	constructor(reason = "source_not_ready") {
+		super("Scene source is stale or not synchronized yet");
+		this.reason = reason;
+	}
+};
+function sceneSourceFailureReason(error) {
+	if (error instanceof SceneSourceNotReady) return error.reason;
+	const value = error;
+	const status = Number(value?.statusCode ?? value?.status);
+	const message = typeof error === "string" ? error : value?.message ?? "";
+	if (status === 429 || /\b429\b|rate.?limit|too many requests/i.test(message)) return "source_rate_limited";
+	if (status === 401 || status === 403 || /\b401\b|\b403\b|permission|authorization|authorized|access|token.*expired|invalid.grant/i.test(message)) return "needs_permission";
+	if (value?.name === "AbortError" || value?.name === "TimeoutError" || /timed out|timeout/i.test(message)) return "source_timeout";
+	return "source_not_ready";
+}
+//#endregion
+export { SceneSourceNotReady, sceneSourceFailureReason };

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

@@ -0,0 +1,174 @@
+import type { SceneModelUsage } from './contracts.js';
+import type { DatabaseSync } from 'node:sqlite';
+import { type ActivationStatus, type SceneActivation, type ScenePrincipal, type SceneTemplate } from './contracts.js';
+export interface SceneEventInput {
+    source: string;
+    sourceEventId: string;
+    eventType: string;
+    subjectId: string;
+    occurredAt: number;
+    accountId?: string;
+}
+export interface SceneRunClaim {
+    id: string;
+    intentId: string;
+    activationId: string;
+    activationRevision: number;
+    leaseOwner: string;
+    leaseEpoch: number;
+    attempt: number;
+}
+export interface SceneWorkItem {
+    id: string;
+    activationId: string;
+    subjectId: string;
+    accountId: string;
+    dueAt: number;
+    revision: number;
+    status: 'watching' | 'paused' | 'completed';
+}
+export declare class SceneConflictError extends Error {
+}
+export declare class SceneNotFoundError extends Error {
+}
+export declare class SceneInputError extends Error {
+}
+/** The caller supplies the database; storage is initialized by the normal database upgrade. */
+export declare class SceneRepository {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    private transaction;
+    installTemplate(value: unknown): SceneTemplate;
+    getTemplate(key: string, version: string): SceneTemplate;
+    listTemplates(): SceneTemplate[];
+    listRuns(principal: ScenePrincipal, activationId: string, limit?: number, afterId?: string): Record<string, import("node:sqlite").SQLOutputValue>[];
+    createActivation(principal: ScenePrincipal, value: unknown, requestId?: string): SceneActivation;
+    listActivations(principal: ScenePrincipal, limit?: number, afterId?: string): SceneActivation[];
+    getActivation(principal: ScenePrincipal, id: string): SceneActivation;
+    recordSourceHealth(activation: SceneActivation, reason: string | null, now: number, retryAt?: number | null): void;
+    getSourceHealth(activationId: string): Record<string, import("node:sqlite").SQLOutputValue>;
+    reuseUnchangedResult(claim: SceneRunClaim, hash: string, now: number, inspectOnly?: boolean): boolean;
+    /** Configuration edits require a fresh preflight before any execution resumes. */
+    configureActivation(principal: ScenePrincipal, id: string, revision: number, value: unknown): SceneActivation;
+    writeNotes(principal: ScenePrincipal, id: string, value: unknown, now: number): number;
+    readNotes(principal: ScenePrincipal, id: string): Record<string, import("node:sqlite").SQLOutputValue>;
+    listWorkItems(principal: ScenePrincipal, activationId: string, limit?: number, afterId?: string): Record<string, import("node:sqlite").SQLOutputValue>[];
+    listSchedules(principal: ScenePrincipal, activationId: string): {
+        triggerKey: string;
+        schedule: {
+            weekdays: number[];
+            hour: number;
+            minute: number;
+            timeZone: string;
+        };
+        revision: number;
+        nextDueAt: number;
+    }[];
+    createWorkItem(principal: ScenePrincipal, activationId: string, input: {
+        subjectId: string;
+        accountId: string;
+        dueAt: number;
+    }, now: number): SceneWorkItem;
+    /** Internal worker scan; identity comes from persisted ownership, never an event payload. */
+    recordModelUsage(claim: SceneRunClaim, usage: SceneModelUsage, now: number): void;
+    listMailObservationItems(afterId?: string, now?: number): Array<{
+        principal: ScenePrincipal;
+        item: SceneWorkItem;
+    }>;
+    isMailObservationCurrent(activation: SceneActivation, item: SceneWorkItem, now?: number): boolean;
+    observeMailWorkItem(principal: ScenePrincipal, item: SceneWorkItem, fingerprint: string, now: number): boolean;
+    /** Revision changes invalidate only this item's pending work and visible results. */
+    updateWorkItem(principal: ScenePrincipal, id: string, input: {
+        expectedRevision: number;
+        status?: SceneWorkItem['status'];
+        dueAt?: number;
+    }, now: number): SceneWorkItem;
+    /** Due dates are durable; restarting cannot generate a second occurrence. */
+    enqueueDueWorkItems(now: number): number;
+    transitionActivation(principal: ScenePrincipal, id: string, revision: number, status: ActivationStatus, now?: number): SceneActivation;
+    setSchedule(principal: ScenePrincipal, activationId: string, triggerKey: string, expectedRevision: number, value: unknown, now: number): number;
+    /** Coalesces missed occurrences into at most one bounded catch-up per schedule. */
+    enqueueDueSchedules(now: number): number;
+    /** Called by an authorized producer inside its domain transaction when applicable. */
+    acceptTrigger(principal: ScenePrincipal, activationId: string, input: {
+        event: SceneEventInput;
+        triggerKey: string;
+        occurrenceKey: string;
+        dueAt: number;
+    }, now: number): string;
+    acceptManualCheck(principal: ScenePrincipal, activationId: string, triggerKey: string, requestId: string, now: number): string;
+    claimNext(worker: string, now: number, leaseMs?: number): SceneRunClaim | null;
+    renewLease(claim: SceneRunClaim, now: number, leaseMs: number): boolean;
+    reserveModelCall(claim: SceneRunClaim, now: number, limits?: {
+        activation: number;
+        owner: number;
+    }): boolean;
+    deferRun(claim: SceneRunClaim, now: number, reason: 'source_not_ready' | 'daily_budget', retryAt: number): 'deferred' | 'failed' | 'discarded';
+    getRunInput(claim: SceneRunClaim, now: number): {
+        activation: SceneActivation;
+        subjectId: string;
+        accountId?: string;
+        notBefore?: number;
+    } | null;
+    saveSnapshot(claim: SceneRunClaim, hash: string, evidenceIds: string[], now: number): boolean;
+    finishReadOnlyRun(claim: SceneRunClaim, result: {
+        kind: 'no_change' | 'observation' | 'artifact' | 'decision';
+        summary: string;
+        evidenceIds: string[];
+    }, now: number): boolean;
+    listInbox(principal: ScenePrincipal, limit?: number, afterId?: string, activationId?: string | null): {
+        createdAt: number;
+        sources: {
+            kind: string;
+            title: string;
+            sender: string;
+            href: string;
+        }[];
+        sourceHealth: Record<string, import("node:sqlite").SQLOutputValue>;
+        id: string;
+        activationId: string;
+        outcomeId: string;
+        content: unknown;
+        status: string;
+        readOnly: boolean;
+    }[];
+    getPresentation(principal: ScenePrincipal, id: string): {
+        createdAt: number;
+        sources: {
+            kind: string;
+            title: string;
+            sender: string;
+            href: string;
+        }[];
+        sourceHealth: Record<string, import("node:sqlite").SQLOutputValue>;
+        id: string;
+        activationId: string;
+        outcomeId: string;
+        content: unknown;
+        status: string;
+        readOnly: boolean;
+    };
+    listDigestResults(principal: ScenePrincipal, digestId: string, limit?: number, afterId?: string): {
+        outcomes: {
+            createdAt: number;
+            sources: {
+                kind: string;
+                title: string;
+                sender: string;
+                href: string;
+            }[];
+            sourceHealth: Record<string, import("node:sqlite").SQLOutputValue>;
+            id: string;
+            activationId: string;
+            outcomeId: string;
+            content: unknown;
+            status: string;
+            readOnly: boolean;
+        }[];
+        nextCursor: string;
+    };
+    failRun(claim: SceneRunClaim, now: number, reason: string, retryAt?: number): boolean;
+    private isCurrentClaim;
+    private readClaim;
+    private assertPrincipal;
+}