@xopcai/xopc 0.0.309 → 0.0.311

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

@@ -0,0 +1,17 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ProductNotification } from '@xopcai/gateway-contract';
+import { type SceneActivation, type ScenePermission } from './contracts.js';
+/** Page notifications commit with the result outbox; transport routing is never inferred. */
+export declare class SceneResultNotifications {
+    private readonly db;
+    private readonly authorize;
+    private readonly publish;
+    private readonly clock;
+    private readonly outbox;
+    private committed;
+    constructor(db: DatabaseSync, authorize: (activation: SceneActivation) => ScenePermission, publish: (notification: ProductNotification) => void, clock?: () => number);
+    /** Realtime is a hint after commit; durable results and events survive a disconnected page. */
+    drain(limit?: number): number;
+    private reserveBudget;
+    private flushDigests;
+}

package/dist/src/scenes/resultNotifications.js

@@ -0,0 +1,204 @@
+import { init_transaction, runSqliteSavepoint } from "../storage/sqlite/transaction.js";
+import { createNotificationEvent } from "../notifications/store.js";
+import { enqueueBrowserDispatches } from "../notifications/browserSubscriptions.js";
+import { intersectPermissions, sceneContentHash } from "./contracts.js";
+import { nextSceneScheduleAt } from "./schedule.js";
+import { SceneRepository } from "./repository.js";
+import { ScenePreferenceService, sceneChecksAllowed } from "./preferences.js";
+import { notificationQuietUntil } from "../notifications/quietHours.js";
+import { sceneNotificationEligibility } from "./notificationEligibility.js";
+import { createSceneNotificationOutbox } from "./notificationPublication.js";
+import { randomUUID } from "node:crypto";
+//#region src/scenes/resultNotifications.ts
+init_transaction();
+/** Page notifications commit with the result outbox; transport routing is never inferred. */
+var SceneResultNotifications = class {
+	outbox;
+	committed = [];
+	constructor(db, authorize, publish, clock = Date.now) {
+		this.db = db;
+		this.authorize = authorize;
+		this.publish = publish;
+		this.clock = clock;
+		const repository = new SceneRepository(db);
+		const preferences = new ScenePreferenceService(db);
+		this.outbox = createSceneNotificationOutbox(db, (result, eligible) => {
+			const activation = repository.getActivation(result, eligible.activationId);
+			if (sceneContentHash(intersectPermissions(activation.permissions, authorize(activation))) !== sceneContentHash(intersectPermissions(activation.permissions))) return {
+				action: "settle",
+				reason: "permission_revoked"
+			};
+			const now = clock();
+			const policy = preferences.get(result);
+			if (policy.digestEnabled) {
+				const due = nextSceneScheduleAt({
+					weekdays: [
+						0,
+						1,
+						2,
+						3,
+						4,
+						5,
+						6
+					],
+					hour: policy.digestHour,
+					minute: policy.digestMinute,
+					timeZone: policy.timezone
+				}, now);
+				db.prepare(`INSERT INTO notification_digest_queue(subject_id, owner_id, workspace_id, subject_revision, mode, due_at, status)
+          VALUES (?, ?, ?, ?, 'daily', ?, 'pending') ON CONFLICT(subject_id) DO UPDATE SET
+          subject_revision = excluded.subject_revision, due_at = excluded.due_at, status = 'pending', consumed_at = NULL`).run(result.subjectId, result.ownerId, result.workspaceId, eligible.revision, due);
+				return {
+					action: "settle",
+					reason: "digest_queued"
+				};
+			}
+			const key = `scene.result:${eligible.presentationId}:${eligible.revision}`;
+			if (!this.reserveBudget(result, key, policy, now)) return {
+				action: "settle",
+				reason: "daily_budget"
+			};
+			const event = createNotificationEvent({
+				dedupeKey: key,
+				createdAt: now,
+				deviceIds: [],
+				notification: {
+					type: "scene.result",
+					priority: "normal",
+					target: {
+						kind: "scene_result",
+						activationId: eligible.activationId,
+						presentationId: eligible.presentationId
+					},
+					title: {
+						en: "A scene result is ready",
+						zh: "场景有新成果"
+					},
+					body: {
+						en: "Open the scene to review it.",
+						zh: "打开场景查看并反馈。"
+					},
+					payload: {
+						ownerId: result.ownerId,
+						workspaceId: result.workspaceId,
+						notificationRevision: eligible.revision,
+						deliveryChannel: "in_app"
+					}
+				}
+			}, db);
+			if (policy.preferredChannel === "browser") enqueueBrowserDispatches(db, result, event.notification.id, result.subjectId, eligible.revision, now);
+			if (event.created) this.committed.push(event.notification);
+			return {
+				action: "settle",
+				reason: "page_notification"
+			};
+		}, clock);
+	}
+	/** Realtime is a hint after commit; durable results and events survive a disconnected page. */
+	drain(limit = 100) {
+		if (!Number.isInteger(limit) || limit < 1 || limit > 1e3) throw new Error("Invalid scene notification batch size");
+		let drained = 0;
+		for (; drained < limit; drained++) {
+			this.committed = [];
+			if (!this.outbox.drainOne()) break;
+			for (const event of this.committed) if (this.db.prepare("SELECT 1 FROM notification_events WHERE event_id = ?").get(event.id)) this.publish(event);
+		}
+		this.flushDigests();
+		return drained;
+	}
+	reserveBudget(owner, key, policy, now) {
+		const day = new Intl.DateTimeFormat("en-CA", {
+			timeZone: policy.timezone,
+			year: "numeric",
+			month: "2-digit",
+			day: "2-digit"
+		}).format(now);
+		if (this.db.prepare("SELECT 1 FROM notification_attention_budget WHERE dedupe_key = ?").get(key)) return true;
+		if (Number(this.db.prepare(`SELECT count(*) AS n FROM notification_attention_budget
+      WHERE owner_id = ? AND workspace_id = ? AND local_day = ?`).get(owner.ownerId, owner.workspaceId, day)?.n) >= policy.dailyNotificationLimit) return false;
+		this.db.prepare("INSERT INTO notification_attention_budget VALUES (?, ?, ?, ?, ?)").run(key, owner.ownerId, owner.workspaceId, day, now);
+		return true;
+	}
+	flushDigests() {
+		const now = this.clock();
+		const owners = this.db.prepare(`SELECT DISTINCT owner_id, workspace_id FROM notification_digest_queue
+      WHERE status = 'pending' AND due_at <= ? ORDER BY owner_id, workspace_id LIMIT 100`).all(now);
+		for (const owner of owners) {
+			const event = runSqliteSavepoint(this.db, () => {
+				const principal = {
+					ownerId: String(owner.owner_id),
+					workspaceId: String(owner.workspace_id)
+				};
+				const policy = new ScenePreferenceService(this.db).get(principal);
+				const rows = this.db.prepare(`SELECT * FROM notification_digest_queue WHERE owner_id = ? AND workspace_id = ?
+          AND status = 'pending' AND due_at <= ? ORDER BY due_at, subject_id LIMIT 100`).all(principal.ownerId, principal.workspaceId, now);
+				const quiet = notificationQuietUntil(policy, now);
+				const members = [];
+				for (const row of rows) {
+					const result = {
+						...principal,
+						id: String(row.subject_id),
+						subjectId: String(row.subject_id)
+					};
+					const eligible = sceneNotificationEligibility(this.db, result, now, Number(row.subject_revision));
+					let until = eligible.action === "defer" ? eligible.until : null;
+					let allowed = eligible.action === "eligible" && sceneChecksAllowed(policy, now) && !policy.notificationsMuted && policy.level !== "quiet";
+					if (allowed && eligible.action === "eligible") {
+						const activation = new SceneRepository(this.db).getActivation(principal, eligible.activationId);
+						allowed = sceneContentHash(intersectPermissions(activation.permissions, this.authorize(activation))) === sceneContentHash(intersectPermissions(activation.permissions));
+						if (policy.suppressWhileViewing && this.db.prepare(`SELECT 1 FROM notification_presence WHERE owner_id = ? AND workspace_id = ?
+              AND subject_id = ? AND subject_revision = ? AND expires_at > ?`).get(principal.ownerId, principal.workspaceId, row.subject_id, row.subject_revision, now)) allowed = false;
+						if (allowed) until = quiet;
+					}
+					if (until !== null) {
+						this.db.prepare("UPDATE notification_digest_queue SET due_at = ? WHERE subject_id = ?").run(until, row.subject_id);
+						continue;
+					}
+					this.db.prepare("UPDATE notification_digest_queue SET status = 'consumed', consumed_at = ? WHERE subject_id = ?").run(now, row.subject_id);
+					if (allowed) members.push({
+						id: String(row.subject_id),
+						revision: Number(row.subject_revision)
+					});
+				}
+				if (!members.length) return null;
+				const occurrence = `daily:${rows[0].due_at}:${members[0].id}`;
+				const key = `scene.digest:${sceneContentHash([principal, occurrence])}`;
+				if (!this.reserveBudget(principal, key, policy, now)) return null;
+				const id = randomUUID();
+				const created = createNotificationEvent({
+					dedupeKey: key,
+					createdAt: now,
+					deviceIds: [],
+					notification: {
+						type: "scene.digest",
+						priority: "normal",
+						target: {
+							kind: "scene_digest",
+							digestId: id
+						},
+						title: {
+							en: "Your scene digest is ready",
+							zh: "场景摘要已就绪"
+						},
+						body: {
+							en: "Open the app to review your results.",
+							zh: "打开页面查看成果。"
+						},
+						payload: {
+							...principal,
+							deliveryChannel: "in_app"
+						}
+					}
+				}, this.db);
+				this.db.prepare("INSERT INTO notification_digests VALUES (?, ?, ?, ?, ?, ?)").run(id, principal.ownerId, principal.workspaceId, occurrence, now, created.notification.id);
+				const insert = this.db.prepare("INSERT INTO notification_digest_members VALUES (?, ?, ?)");
+				for (const member of members) insert.run(id, member.id, member.revision);
+				if (policy.preferredChannel === "browser") enqueueBrowserDispatches(this.db, principal, created.notification.id, null, 1, now);
+				return created.created ? created.notification : null;
+			});
+			if (event) this.publish(event);
+		}
+	}
+};
+//#endregion
+export { SceneResultNotifications };

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

@@ -0,0 +1,25 @@
+import type { SceneExecutionService } from './execution.js';
+import type { SceneRepository } from './repository.js';
+import type { SceneMailObservationService } from './mailObservations.js';
+/** Single-Gateway pump. Durable occurrence, lease and budget rules remain in the domain. */
+export declare class SceneRuntime {
+    private readonly repository;
+    private readonly execution;
+    private readonly observations;
+    private readonly clock;
+    private readonly intervalMs;
+    private readonly worker;
+    private controller;
+    private timer?;
+    private running?;
+    private observing?;
+    private observationCursor;
+    private stopping?;
+    constructor(repository: SceneRepository, execution: SceneExecutionService, observations: Pick<SceneMailObservationService, 'scan'>, clock?: () => number, intervalMs?: number);
+    start(): void;
+    /** Ingests due occurrences even when an earlier model call is still running. */
+    tick(): Promise<void>;
+    private observe;
+    /** Cancels the active read/model call before the host closes SQLite. */
+    stop(): Promise<void>;
+}

package/dist/src/scenes/runtime.js

@@ -0,0 +1,101 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { randomUUID } from "node:crypto";
+//#region src/scenes/runtime.ts
+init_logger();
+const log = createLogger("SceneRuntime");
+/** Single-Gateway pump. Durable occurrence, lease and budget rules remain in the domain. */
+var SceneRuntime = class {
+	worker = `scene:${randomUUID()}`;
+	controller = new AbortController();
+	timer;
+	running;
+	observing;
+	observationCursor = "";
+	stopping;
+	constructor(repository, execution, observations, clock = Date.now, intervalMs = 5e3) {
+		this.repository = repository;
+		this.execution = execution;
+		this.observations = observations;
+		this.clock = clock;
+		this.intervalMs = intervalMs;
+		if (!Number.isInteger(intervalMs) || intervalMs < 100 || intervalMs > 6e4) throw new Error("Invalid scene poll interval");
+	}
+	start() {
+		if (this.stopping) throw new Error("Scene runtime is stopping");
+		if (this.timer) return;
+		if (this.controller.signal.aborted) this.controller = new AbortController();
+		const poll = () => {
+			this.tick().catch((err) => log.error({
+				err,
+				phase: "scene_poll"
+			}, "Scene poll failed"));
+		};
+		this.timer = setInterval(poll, this.intervalMs);
+		this.timer.unref();
+		poll();
+	}
+	/** Ingests due occurrences even when an earlier model call is still running. */
+	async tick() {
+		this.controller.signal.throwIfAborted();
+		const now = this.clock();
+		this.repository.enqueueDueWorkItems(now);
+		this.repository.enqueueDueSchedules(now);
+		if (!this.observing) this.observe();
+		if (this.running) {
+			await Promise.all([this.running, this.observing]);
+			return;
+		}
+		const signal = this.controller.signal;
+		const run = this.execution.runNext(this.worker, signal).then(() => void 0);
+		this.running = run;
+		const execution = run.finally(() => {
+			if (this.running === run) this.running = void 0;
+		});
+		await Promise.all([execution, this.observing]);
+	}
+	observe() {
+		const controller = new AbortController();
+		const outer = this.controller.signal;
+		const abort = () => controller.abort(outer.reason);
+		outer.addEventListener("abort", abort, { once: true });
+		const timeout = setTimeout(() => controller.abort(/* @__PURE__ */ new Error("Scene mail observation timed out")), 3e4);
+		let removeListener = () => {};
+		const aborted = new Promise((_, reject) => {
+			const listener = () => reject(controller.signal.reason);
+			controller.signal.addEventListener("abort", listener, { once: true });
+			removeListener = () => controller.signal.removeEventListener("abort", listener);
+		});
+		const scan = Promise.resolve().then(() => {
+			controller.signal.throwIfAborted();
+			return this.observations.scan(controller.signal, this.observationCursor, (id) => {
+				if (!controller.signal.aborted) this.observationCursor = id;
+			});
+		}).then((result) => {
+			controller.signal.throwIfAborted();
+			this.observationCursor = result.nextCursor ?? "";
+		});
+		const observing = Promise.race([scan, aborted]).finally(() => {
+			clearTimeout(timeout);
+			removeListener();
+			outer.removeEventListener("abort", abort);
+			if (this.observing === observing) this.observing = void 0;
+		});
+		this.observing = observing;
+	}
+	/** Cancels the active read/model call before the host closes SQLite. */
+	stop() {
+		if (this.stopping) return this.stopping;
+		if (this.timer) clearInterval(this.timer);
+		this.timer = void 0;
+		this.controller.abort(/* @__PURE__ */ new Error("Scene runtime stopped"));
+		const stopped = Promise.allSettled([this.running, this.observing]).then(() => void 0);
+		this.stopping = stopped;
+		stopped.finally(() => {
+			if (this.stopping === stopped) this.stopping = void 0;
+		});
+		return stopped;
+	}
+};
+//#endregion
+export { SceneRuntime };

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

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+/** A local wall-clock schedule, not an arbitrary cron or workflow language. */
+export declare const sceneScheduleSchema: z.ZodObject<{
+    weekdays: z.ZodArray<z.ZodNumber>;
+    hour: z.ZodNumber;
+    minute: z.ZodNumber;
+    timeZone: z.ZodString;
+}, z.core.$strict>;
+export declare function nextSceneScheduleAt(value: unknown, now: number): number;

package/dist/src/scenes/schedule.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { DateTime } from "luxon";
+//#region src/scenes/schedule.ts
+/** A local wall-clock schedule, not an arbitrary cron or workflow language. */
+const sceneScheduleSchema = z.strictObject({
+	weekdays: z.array(z.number().int().min(0).max(6)).min(1).max(7).refine((days) => new Set(days).size === days.length, "Duplicate weekdays"),
+	hour: z.number().int().min(0).max(23),
+	minute: z.number().int().min(0).max(59),
+	timeZone: z.string().trim().min(1).max(100).refine((timeZone) => {
+		try {
+			new Intl.DateTimeFormat("en", { timeZone });
+			return DateTime.now().setZone(timeZone).isValid;
+		} catch {
+			return false;
+		}
+	}, "Invalid time zone")
+});
+function nextSceneScheduleAt(value, now) {
+	if (!Number.isSafeInteger(now) || now < 0) throw new Error("Invalid scene schedule time");
+	const schedule = sceneScheduleSchema.parse(value);
+	const today = DateTime.fromMillis(now, { zone: schedule.timeZone }).startOf("day");
+	for (let day = 0; day < 15; day += 1) {
+		const date = today.plus({ days: day });
+		if (!schedule.weekdays.includes(date.weekday % 7)) continue;
+		let candidate = date.set({
+			hour: schedule.hour,
+			minute: schedule.minute,
+			second: 0,
+			millisecond: 0
+		});
+		if (candidate.hour !== schedule.hour || candidate.minute !== schedule.minute) {
+			const requestedMinute = schedule.hour * 60 + schedule.minute;
+			for (let step = 0; step < 1440; step += 1) {
+				const previous = candidate.minus({ minutes: 1 });
+				if (previous.toISODate() !== date.toISODate() || previous.hour * 60 + previous.minute < requestedMinute) break;
+				candidate = previous;
+			}
+		}
+		const first = Math.min(...candidate.getPossibleOffsets().map((value) => value.toMillis()));
+		if (first > now) return first;
+	}
+	throw new Error("No scene schedule occurrence within the search window");
+}
+//#endregion
+export { nextSceneScheduleAt, sceneScheduleSchema };

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

@@ -0,0 +1,29 @@
+import { type SceneActivation, type ScenePermission, type ScenePrincipal } from './contracts.js';
+import type { SceneContextProvider } from './execution.js';
+import { SceneRepository } from './repository.js';
+export declare class SceneSetupError extends Error {
+    readonly missing: string[];
+    constructor(missing: string[]);
+}
+/** User-facing operations share one authorization boundary, independent of the UI. */
+export declare class SceneApplicationService {
+    private readonly repository;
+    private readonly providers;
+    private readonly authorize;
+    private readonly clock;
+    private readonly modelReadiness;
+    constructor(repository: SceneRepository, providers: readonly SceneContextProvider[], authorize: (activation: SceneActivation) => Promise<ScenePermission>, clock?: () => number, modelReadiness?: () => string[]);
+    preflight(principal: ScenePrincipal, value: unknown): Promise<{
+        ready: boolean;
+        missing: string[];
+    }>;
+    private checkReadiness;
+    start(principal: ScenePrincipal, value: unknown, requestId: string): Promise<SceneActivation>;
+    check(principal: ScenePrincipal, activationId: string, requestId: string): string;
+    transition(principal: ScenePrincipal, id: string, value: unknown): Promise<SceneActivation>;
+    configure(principal: ScenePrincipal, id: string, value: unknown): SceneActivation;
+    writeNotes(principal: ScenePrincipal, id: string, value: unknown): number;
+    createWorkItem(principal: ScenePrincipal, id: string, value: unknown): import("./repository.js").SceneWorkItem;
+    setSchedule(principal: ScenePrincipal, id: string, triggerKey: string, value: unknown): number;
+    updateWorkItem(principal: ScenePrincipal, id: string, value: unknown): import("./repository.js").SceneWorkItem;
+}

package/dist/src/scenes/service.js

@@ -0,0 +1,116 @@
+import { activationInputSchema, activationStatuses, intersectPermissions, validateTemplate } from "./contracts.js";
+import { sceneScheduleSchema } from "./schedule.js";
+import { z } from "zod";
+//#region src/scenes/service.ts
+var SceneSetupError = class extends Error {
+	constructor(missing) {
+		super(`Scene setup is incomplete: ${missing.join(", ")}`);
+		this.missing = missing;
+	}
+};
+/** User-facing operations share one authorization boundary, independent of the UI. */
+var SceneApplicationService = class {
+	constructor(repository, providers, authorize, clock = Date.now, modelReadiness = () => []) {
+		this.repository = repository;
+		this.providers = providers;
+		this.authorize = authorize;
+		this.clock = clock;
+		this.modelReadiness = modelReadiness;
+	}
+	async preflight(principal, value) {
+		const input = activationInputSchema.parse(value);
+		return this.checkReadiness({
+			...input,
+			...principal,
+			id: "preflight",
+			revision: 1,
+			status: "needs_setup"
+		});
+	}
+	async checkReadiness(activation) {
+		const input = activation;
+		const template = validateTemplate(this.repository.getTemplate(input.templateKey, input.templateVersion), {
+			contextProviders: this.providers.map((provider) => provider.id),
+			effectHandlers: []
+		});
+		const permissions = intersectPermissions(input.permissions, await this.authorize(activation));
+		const missing = template.contextProviders.filter((provider) => !permissions.contextProviders.includes(provider)).map((id) => `context:${id}`);
+		missing.push(...this.modelReadiness());
+		missing.push(...input.permissions.accountIds.filter((id) => !permissions.accountIds.includes(id)).map((id) => `account:${id}`));
+		if (input.permissions.effectHandlers.length > 0) missing.push("read_only_execution");
+		if (input.permissions.contextProviders.some((id) => !template.contextProviders.includes(id))) missing.push("unrequested_context");
+		if (template.key === "mail-follow-up" && (input.scope.kind !== "objects" || input.scope.ids.length !== 1 || input.permissions.accountIds.length !== 1)) missing.push("one_mail_thread_and_account");
+		if (template.contextProviders.includes("user_notes") && input.scope.kind !== "personal") missing.push("personal_notes_scope");
+		return {
+			ready: missing.length === 0,
+			missing
+		};
+	}
+	async start(principal, value, requestId) {
+		if (!requestId.trim()) throw new Error("Scene request identity is required");
+		const preflight = await this.preflight(principal, value);
+		if (!preflight.ready) throw new SceneSetupError(preflight.missing);
+		const activation = this.repository.createActivation(principal, value, requestId);
+		if (activation.status !== "needs_setup") return activation;
+		return this.repository.transitionActivation(principal, activation.id, activation.revision, "active", this.clock());
+	}
+	check(principal, activationId, requestId) {
+		if (!requestId.trim() || requestId.length > 200) throw new Error("Scene request identity is required");
+		const activation = this.repository.getActivation(principal, activationId);
+		const trigger = this.repository.getTemplate(activation.templateKey, activation.templateVersion).triggers.find((item) => item.type === "manual");
+		if (!trigger) throw new Error("Scene template does not support manual checks");
+		return this.repository.acceptManualCheck(principal, activationId, trigger.id, requestId, this.clock());
+	}
+	async transition(principal, id, value) {
+		const input = z.strictObject({
+			expectedRevision: z.number().int().positive(),
+			status: z.enum(activationStatuses)
+		}).parse(value);
+		const activation = this.repository.getActivation(principal, id);
+		if (input.status === "active") {
+			const result = await this.checkReadiness(activation);
+			if (!result.ready) throw new SceneSetupError(result.missing);
+		}
+		return this.repository.transitionActivation(principal, id, input.expectedRevision, input.status, this.clock());
+	}
+	configure(principal, id, value) {
+		const { expectedRevision, ...input } = activationInputSchema.pick({
+			goal: true,
+			scope: true,
+			permissions: true
+		}).extend({ expectedRevision: z.number().int().positive() }).parse(value);
+		return this.repository.configureActivation(principal, id, expectedRevision, input);
+	}
+	writeNotes(principal, id, value) {
+		return this.repository.writeNotes(principal, id, value, this.clock());
+	}
+	createWorkItem(principal, id, value) {
+		const input = z.strictObject({
+			subjectId: z.string().trim().min(1).max(200),
+			accountId: z.string().trim().min(1).max(200),
+			dueAt: z.number().int().refine((time) => time > this.clock(), "Deadline must be in the future")
+		}).parse(value);
+		return this.repository.createWorkItem(principal, id, input, this.clock());
+	}
+	setSchedule(principal, id, triggerKey, value) {
+		const input = z.strictObject({
+			expectedRevision: z.number().int().nonnegative(),
+			schedule: sceneScheduleSchema
+		}).parse(value);
+		return this.repository.setSchedule(principal, id, triggerKey, input.expectedRevision, input.schedule, this.clock());
+	}
+	updateWorkItem(principal, id, value) {
+		const input = z.strictObject({
+			expectedRevision: z.number().int().positive(),
+			dueAt: z.number().int().nonnegative().optional(),
+			status: z.enum([
+				"watching",
+				"paused",
+				"completed"
+			]).optional()
+		}).parse(value);
+		return this.repository.updateWorkItem(principal, id, input, this.clock());
+	}
+};
+//#endregion
+export { SceneApplicationService, SceneSetupError };

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

@@ -0,0 +1,64 @@
+export declare const mailFollowUpTemplate: {
+    schemaVersion: 1;
+    key: string;
+    version: string;
+    title: string;
+    description: string;
+    goalMode: "finite" | "ongoing";
+    contextProviders: string[];
+    triggers: ({
+        id: string;
+        type: "manual";
+    } | {
+        id: string;
+        type: "event";
+        eventType: string;
+    } | {
+        id: string;
+        type: "schedule";
+    })[];
+    execution: {
+        kind: "agent";
+        instruction: string;
+        limits: {
+            timeoutSeconds: number;
+            maxIterations: number;
+            maxToolCalls: number;
+            maxOutputTokens: number;
+        };
+    };
+    allowedOutcomeKinds: ("artifact" | "receipt" | "decision" | "observation" | "no_change" | "state_change" | "effect_proposal")[];
+    allowedEffectHandlers: string[];
+};
+export declare const familyPlanTemplate: {
+    schemaVersion: 1;
+    key: string;
+    version: string;
+    title: string;
+    description: string;
+    goalMode: "finite" | "ongoing";
+    contextProviders: string[];
+    triggers: ({
+        id: string;
+        type: "manual";
+    } | {
+        id: string;
+        type: "event";
+        eventType: string;
+    } | {
+        id: string;
+        type: "schedule";
+    })[];
+    execution: {
+        kind: "agent";
+        instruction: string;
+        limits: {
+            timeoutSeconds: number;
+            maxIterations: number;
+            maxToolCalls: number;
+            maxOutputTokens: number;
+        };
+    };
+    allowedOutcomeKinds: ("artifact" | "receipt" | "decision" | "observation" | "no_change" | "state_change" | "effect_proposal")[];
+    allowedEffectHandlers: string[];
+};