@xopcai/xopc 0.0.332 → 0.0.334

package/dist/src/automations/delivery/delivery-router.js

@@ -0,0 +1,318 @@
+import { createLogger } from "../../utils/logger/index.js";
+import { init_logger } from "../../utils/logger.js";
+import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import { getAutomationRun } from "../storage/automation-run-repository.js";
+import "../storage/index.js";
+import { getAutomationEventForRun } from "../events/event-repository.js";
+import { assertUrlSafe } from "../../agent/tools/url-safety.js";
+import "../events/index.js";
+import { resolveAutomationWebhookSecret } from "../webhook-secrets.js";
+import { createHmac, randomUUID } from "node:crypto";
+//#region src/automations/delivery/delivery-router.ts
+init_transaction();
+init_logger();
+const log = createLogger("AutomationDeliveryRouter");
+const MAX_ATTEMPTS = 5;
+const LEASE_MS = 45e3;
+const MAX_INLINE_ARTIFACT_BYTES = 64 * 1024;
+function listAutomationResultDeliveries(input = {}) {
+	const clauses = [];
+	const params = [];
+	if (input.runId) {
+		clauses.push("run_id = ?");
+		params.push(input.runId);
+	}
+	if (input.status) {
+		clauses.push("status = ?");
+		params.push(input.status);
+	}
+	params.push(Math.max(1, Math.min(200, Math.floor(input.limit ?? 50))));
+	return getSqliteDatabase().prepare(`SELECT delivery_id, run_id, destination_key, kind, status, config_json,
+    attempts, next_attempt_at_ms, last_error, created_at_ms, updated_at_ms
+    FROM automation_result_deliveries ${clauses.length ? `WHERE ${clauses.join(" AND ")}` : ""}
+    ORDER BY created_at_ms DESC, run_id DESC, destination_key LIMIT ?`).all(...params).map((row) => ({
+		runId: row.run_id,
+		destinationKey: row.destination_key,
+		kind: row.kind,
+		status: row.status,
+		attempts: row.attempts,
+		nextAttemptAtMs: row.next_attempt_at_ms,
+		...row.last_error ? { lastError: row.last_error } : {},
+		createdAtMs: row.created_at_ms,
+		updatedAtMs: row.updated_at_ms
+	}));
+}
+function retryAutomationResultDelivery(runId, destinationKey) {
+	const now = Date.now();
+	return getSqliteDatabase().prepare(`UPDATE automation_result_deliveries
+    SET status = 'retrying', attempts = 0, next_attempt_at_ms = ?, last_error = NULL,
+        lease_owner = NULL, lease_until_ms = NULL, updated_at_ms = ?
+    WHERE run_id = ? AND destination_key = ? AND status = 'dead_letter'`).run(now, now, runId, destinationKey).changes === 1;
+}
+function getAutomationResultDeliveryMetrics() {
+	const now = Date.now();
+	const row = getSqliteDatabase().prepare(`SELECT
+    SUM(CASE WHEN status IN ('pending', 'retrying', 'delivering') THEN 1 ELSE 0 END) AS pending,
+    SUM(CASE WHEN status = 'dead_letter' THEN 1 ELSE 0 END) AS dead_letters,
+    SUM(CASE WHEN status = 'delivering' AND lease_until_ms > ? THEN 1 ELSE 0 END) AS active_leases
+    FROM automation_result_deliveries`).get(now);
+	return {
+		pending: row.pending ?? 0,
+		deadLetters: row.dead_letters ?? 0,
+		activeLeases: row.active_leases ?? 0
+	};
+}
+function assertArtifacts(artifacts) {
+	for (const artifact of artifacts) {
+		if (artifact.kind === "file") {
+			let uri;
+			try {
+				uri = new URL(artifact.uri);
+			} catch {
+				throw new Error(`Automation file artifact must use an authorized URI: ${artifact.id}`);
+			}
+			if (uri.protocol !== "xopc:" && uri.protocol !== "https:") throw new Error(`Automation file artifact URI is not allowed: ${artifact.id}`);
+			continue;
+		}
+		if (artifact.kind === "reference") continue;
+		if (Buffer.byteLength(JSON.stringify(artifact)) > MAX_INLINE_ARTIFACT_BYTES) throw new Error(`Automation artifact exceeds ${MAX_INLINE_ARTIFACT_BYTES} bytes: ${artifact.id}`);
+	}
+}
+function toResult(run, artifacts) {
+	if (run.endedAtMs === void 0 || ![
+		"succeeded",
+		"failed",
+		"cancelled",
+		"timeout"
+	].includes(run.status)) throw new Error("Cannot deliver an unfinished automation run");
+	assertArtifacts(artifacts);
+	const event = getAutomationEventForRun(run.id);
+	return {
+		schemaVersion: 1,
+		resultId: `result:${run.id}`,
+		runId: run.id,
+		automationId: run.automationId,
+		status: run.status,
+		...run.summary ? { summary: run.summary } : {},
+		...run.error ? { error: {
+			code: `AUTOMATION_${run.status.toUpperCase()}`,
+			message: run.error,
+			retryable: false
+		} } : {},
+		artifacts,
+		correlationId: event?.correlationId ?? run.id,
+		rootEventId: event?.rootEventId ?? run.id,
+		createdAtMs: run.createdAtMs,
+		completedAtMs: run.endedAtMs
+	};
+}
+var AutomationDeliveryRouter = class {
+	active;
+	timer;
+	handlers = /* @__PURE__ */ new Map();
+	owner = `automation-delivery:${process.pid}:${randomUUID()}`;
+	abortController = new AbortController();
+	constructor(options = {}) {
+		this.options = options;
+		this.register("gateway_event", ({ run, config }) => this.options.deliverGatewayEvent?.(run, {
+			notificationPolicy: config.notificationPolicy,
+			requiresAttention: config.requiresAttention === true,
+			...typeof config.projectId === "string" ? { projectId: config.projectId } : {}
+		}));
+		this.register("webhook", (input) => this.postWebhook(input));
+	}
+	register(kind, handler) {
+		if (this.handlers.has(kind)) throw new Error(`Automation delivery handler already registered: ${kind}`);
+		this.handlers.set(kind, handler);
+	}
+	validateArtifacts(artifacts) {
+		assertArtifacts(artifacts);
+	}
+	enqueue(run, automation, suppliedArtifacts = []) {
+		const now = Date.now();
+		const result = toResult(run, suppliedArtifacts.length > 0 ? suppliedArtifacts : run.summary ? [{
+			id: `summary:${run.id}`,
+			kind: "text",
+			text: run.summary,
+			mediaType: "text/plain"
+		}] : []);
+		runSqliteWriteTransaction((db) => {
+			db.prepare(`INSERT INTO automation_results (run_id, result_id, result_json, created_at_ms)
+        VALUES (?, ?, ?, ?)`).run(run.id, result.resultId, JSON.stringify(result), now);
+			const insert = db.prepare(`INSERT INTO automation_result_deliveries (
+        delivery_id, run_id, destination_key, kind, status, config_json, attempts,
+        next_attempt_at_ms, created_at_ms, updated_at_ms
+      ) VALUES (?, ?, ?, ?, 'pending', ?, 0, ?, ?, ?)`);
+			for (const destination of automation.delivery.destinations) {
+				const config = destination.kind === "gateway_event" ? {
+					...destination,
+					notificationPolicy: automation.delivery.notificationPolicy,
+					requiresAttention: run.status !== "succeeded" || (automation.safety?.mode ?? "auto_apply") !== "auto_apply",
+					...automation.projectId ? { projectId: automation.projectId } : {}
+				} : destination;
+				insert.run(randomUUID(), run.id, destination.key, destination.kind, JSON.stringify(config), now, now, now);
+			}
+		});
+	}
+	start() {
+		if (this.timer) return;
+		this.dispatch();
+		this.timer = setInterval(() => void this.dispatch(), 1e3);
+		this.timer.unref?.();
+	}
+	async stop() {
+		if (this.timer) clearInterval(this.timer);
+		this.timer = void 0;
+		this.abortController.abort(/* @__PURE__ */ new Error("Automation delivery router stopped"));
+		await this.active?.catch(() => void 0);
+	}
+	dispatch() {
+		this.active ??= this.runDispatch().finally(() => {
+			this.active = void 0;
+		});
+		return this.active;
+	}
+	claim(limit) {
+		const now = Date.now();
+		return runSqliteWriteTransaction((db) => {
+			const expiredCandidates = db.prepare(`SELECT delivery_id, run_id, destination_key
+        FROM automation_result_deliveries
+        WHERE status = 'delivering' AND lease_until_ms <= ? AND attempts >= ?`).all(now, MAX_ATTEMPTS);
+			const expire = db.prepare(`UPDATE automation_result_deliveries
+        SET status = 'dead_letter', last_error = 'Delivery lease expired after maximum attempts',
+            lease_owner = NULL, lease_until_ms = NULL, updated_at_ms = ?
+        WHERE delivery_id = ? AND status = 'delivering' AND lease_until_ms <= ? AND attempts >= ?`);
+			const expired = [];
+			for (const candidate of expiredCandidates) if (expire.run(now, candidate.delivery_id, now, MAX_ATTEMPTS).changes === 1) expired.push({
+				runId: candidate.run_id,
+				destinationKey: candidate.destination_key,
+				error: "Delivery lease expired after maximum attempts"
+			});
+			const candidates = db.prepare(`SELECT delivery_id, run_id, destination_key, kind, config_json, attempts
+        FROM automation_result_deliveries
+        WHERE attempts < ? AND (
+          (status IN ('pending', 'retrying') AND next_attempt_at_ms <= ?)
+          OR (status = 'delivering' AND lease_until_ms <= ?)
+        )
+        ORDER BY created_at_ms, run_id, destination_key LIMIT ?`).all(MAX_ATTEMPTS, now, now, limit);
+			const claimed = [];
+			const statement = db.prepare(`UPDATE automation_result_deliveries
+        SET status = 'delivering', attempts = attempts + 1, lease_owner = ?, lease_until_ms = ?, updated_at_ms = ?
+        WHERE delivery_id = ? AND attempts = ? AND (
+          (status IN ('pending', 'retrying') AND next_attempt_at_ms <= ?)
+          OR (status = 'delivering' AND lease_until_ms <= ?)
+        )`);
+			for (const candidate of candidates) if (statement.run(this.owner, now + LEASE_MS, now, candidate.delivery_id, candidate.attempts, now, now).changes === 1) claimed.push(candidate);
+			return {
+				rows: claimed,
+				expired
+			};
+		});
+	}
+	async runDispatch() {
+		const { rows, expired } = this.claim(100);
+		for (const item of expired) {
+			this.options.onDeadLetter?.({
+				phase: "result_delivery",
+				...item
+			});
+			log.warn(item, "Automation result delivery moved to dead letter after lease expiry");
+		}
+		let delivered = 0;
+		for (const [index, row] of rows.entries()) {
+			if (this.abortController.signal.aborted) {
+				for (const remaining of rows.slice(index)) this.release(remaining);
+				break;
+			}
+			const run = getAutomationRun(row.run_id);
+			const resultRow = getSqliteDatabase().prepare("SELECT result_json FROM automation_results WHERE run_id = ?").get(row.run_id);
+			if (!run || !resultRow) {
+				this.fail(row, /* @__PURE__ */ new Error("Automation result is unavailable"), true);
+				continue;
+			}
+			try {
+				const handler = this.handlers.get(row.kind);
+				if (!handler) throw new Error(`Automation delivery handler is unavailable: ${row.kind}`);
+				await handler({
+					deliveryId: row.delivery_id,
+					attempt: row.attempts + 1,
+					run,
+					result: JSON.parse(resultRow.result_json),
+					config: JSON.parse(row.config_json),
+					signal: this.abortController.signal
+				});
+				if (getSqliteDatabase().prepare(`UPDATE automation_result_deliveries
+          SET status = 'delivered', last_error = NULL, lease_owner = NULL, lease_until_ms = NULL, updated_at_ms = ?
+          WHERE delivery_id = ? AND status = 'delivering' AND lease_owner = ?`).run(Date.now(), row.delivery_id, this.owner).changes === 1) delivered += 1;
+			} catch (error) {
+				if (this.abortController.signal.aborted) this.release(row);
+				else this.fail(row, error, false);
+			}
+		}
+		return delivered;
+	}
+	release(row) {
+		getSqliteDatabase().prepare(`UPDATE automation_result_deliveries
+      SET status = 'retrying', attempts = MAX(0, attempts - 1), next_attempt_at_ms = ?,
+          lease_owner = NULL, lease_until_ms = NULL, updated_at_ms = ?
+      WHERE delivery_id = ? AND status = 'delivering' AND lease_owner = ?`).run(Date.now(), Date.now(), row.delivery_id, this.owner);
+	}
+	fail(row, error, permanent) {
+		const attempts = row.attempts + 1;
+		const terminal = permanent || attempts >= MAX_ATTEMPTS;
+		const delayMs = Math.min(10 * 6e4, 1e3 * 5 ** Math.max(0, attempts - 1));
+		if (getSqliteDatabase().prepare(`UPDATE automation_result_deliveries
+      SET status = ?, next_attempt_at_ms = ?, last_error = ?, lease_owner = NULL,
+          lease_until_ms = NULL, updated_at_ms = ?
+      WHERE delivery_id = ? AND status = 'delivering' AND lease_owner = ?`).run(terminal ? "dead_letter" : "retrying", Date.now() + delayMs, error instanceof Error ? error.message : String(error), Date.now(), row.delivery_id, this.owner).changes !== 1) return;
+		if (terminal) this.options.onDeadLetter?.({
+			phase: "result_delivery",
+			runId: row.run_id,
+			destinationKey: row.destination_key,
+			error: error instanceof Error ? error.message : String(error)
+		});
+		log.warn({
+			err: error,
+			runId: row.run_id,
+			deliveryKind: row.kind,
+			attempt: attempts
+		}, terminal ? "Automation result delivery moved to dead letter" : "Automation result delivery will retry");
+	}
+	async postWebhook(input) {
+		const endpoint = String(input.config.endpoint ?? "");
+		const secretId = String(input.config.secretId ?? "");
+		assertUrlSafe(endpoint);
+		const secret = resolveAutomationWebhookSecret(secretId);
+		if (!secret) throw new Error(`Automation webhook secret is unavailable: ${secretId}`);
+		const timestamp = String(Date.now());
+		const body = JSON.stringify(input.result);
+		const signature = createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
+		const controller = new AbortController();
+		const onAbort = () => controller.abort(input.signal.reason);
+		input.signal.addEventListener("abort", onAbort, { once: true });
+		if (input.signal.aborted) onAbort();
+		const timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error("Automation delivery timed out")), 3e4);
+		try {
+			const response = await (this.options.fetch ?? fetch)(endpoint, {
+				method: "POST",
+				redirect: "manual",
+				headers: {
+					"content-type": "application/json",
+					"idempotency-key": `${input.result.runId}:${String(input.config.key)}`,
+					"x-xopc-delivery-id": input.deliveryId,
+					"x-xopc-delivery-attempt": String(input.attempt),
+					"x-xopc-timestamp": timestamp,
+					"x-xopc-signature": `sha256=${signature}`
+				},
+				body,
+				signal: controller.signal
+			});
+			if (!response.ok) throw new Error(`Automation delivery failed with HTTP ${response.status}`);
+		} finally {
+			clearTimeout(timer);
+			input.signal.removeEventListener("abort", onAbort);
+		}
+	}
+};
+//#endregion
+export { AutomationDeliveryRouter, getAutomationResultDeliveryMetrics, listAutomationResultDeliveries, retryAutomationResultDelivery };

package/dist/src/automations/delivery/index.d.ts

@@ -0,0 +1 @@
+export * from './delivery-router.js';

package/dist/src/automations/delivery/index.js

@@ -0,0 +1,2 @@
+import { AutomationDeliveryRouter, getAutomationResultDeliveryMetrics, listAutomationResultDeliveries, retryAutomationResultDelivery } from "./delivery-router.js";
+export { AutomationDeliveryRouter, getAutomationResultDeliveryMetrics, listAutomationResultDeliveries, retryAutomationResultDelivery };

package/dist/src/automations/domain/defaults.d.ts

@@ -4,5 +4,4 @@ export declare const DEFAULT_BROWSER_AUTOMATION_TIMEOUT_SECONDS: number;
 export declare function defaultAutomationTimeoutSeconds(action: AutomationAction): number;
 export declare function resolveAutomationTimeoutSeconds(action: AutomationAction, reliability?: {
     executionTimeoutSeconds?: number;
-    timeoutSeconds?: number;
 }): number;

package/dist/src/automations/domain/defaults.js

@@ -5,7 +5,7 @@ function defaultAutomationTimeoutSeconds(action) {
 	return action.kind === "system" ? 60 : action.kind === "browser_automation" ? 600 : DEFAULT_AUTOMATION_TIMEOUT_SECONDS;
 }
 function resolveAutomationTimeoutSeconds(action, reliability) {
-	return reliability?.executionTimeoutSeconds ?? ("timeoutSeconds" in action ? action.timeoutSeconds : void 0) ?? reliability?.timeoutSeconds ?? defaultAutomationTimeoutSeconds(action);
+	return reliability?.executionTimeoutSeconds ?? ("timeoutSeconds" in action ? action.timeoutSeconds : void 0) ?? defaultAutomationTimeoutSeconds(action);
 }
 //#endregion
 export { DEFAULT_AUTOMATION_TIMEOUT_SECONDS, DEFAULT_BROWSER_AUTOMATION_TIMEOUT_SECONDS, defaultAutomationTimeoutSeconds, resolveAutomationTimeoutSeconds };

package/dist/src/automations/domain/index.js

@@ -1,4 +1,4 @@
-import { AutomationActionSchema, AutomationManagementSchema, AutomationReliabilitySchema, AutomationSafetyPolicySchema, AutomationScheduleSchema, AutomationSchema, AutomationStateSchema, AutomationTriggerSchema, CreateAutomationSchema, UpdateAutomationSchema } from "./validation.js";
+import { AutomationActionSchema, AutomationDeliveryPolicySchema, AutomationManagementSchema, AutomationReliabilitySchema, AutomationSafetyPolicySchema, AutomationScheduleSchema, AutomationSchema, AutomationStateSchema, AutomationTriggerSchema, CreateAutomationSchema, UpdateAutomationSchema } from "./validation.js";
 import { computeNextAutomationRunAtMs, computeNextScheduleRunAtMs, timerDelayUntil } from "./schedule.js";
 import { DEFAULT_AUTOMATION_TIMEOUT_SECONDS, DEFAULT_BROWSER_AUTOMATION_TIMEOUT_SECONDS, defaultAutomationTimeoutSeconds, resolveAutomationTimeoutSeconds } from "./defaults.js";
-export { AutomationActionSchema, AutomationManagementSchema, AutomationReliabilitySchema, AutomationSafetyPolicySchema, AutomationScheduleSchema, AutomationSchema, AutomationStateSchema, AutomationTriggerSchema, CreateAutomationSchema, DEFAULT_AUTOMATION_TIMEOUT_SECONDS, DEFAULT_BROWSER_AUTOMATION_TIMEOUT_SECONDS, UpdateAutomationSchema, computeNextAutomationRunAtMs, computeNextScheduleRunAtMs, defaultAutomationTimeoutSeconds, resolveAutomationTimeoutSeconds, timerDelayUntil };
+export { AutomationActionSchema, AutomationDeliveryPolicySchema, AutomationManagementSchema, AutomationReliabilitySchema, AutomationSafetyPolicySchema, AutomationScheduleSchema, AutomationSchema, AutomationStateSchema, AutomationTriggerSchema, CreateAutomationSchema, DEFAULT_AUTOMATION_TIMEOUT_SECONDS, DEFAULT_BROWSER_AUTOMATION_TIMEOUT_SECONDS, UpdateAutomationSchema, computeNextAutomationRunAtMs, computeNextScheduleRunAtMs, defaultAutomationTimeoutSeconds, resolveAutomationTimeoutSeconds, timerDelayUntil };

package/dist/src/automations/domain/types.d.ts

@@ -67,15 +67,41 @@ export interface AutomationManagement {
 }
 export type AutomationConversationMode = 'new_session' | 'continuous';
 export type AutomationNotificationPolicy = 'attention' | 'all' | 'none';
+export type AutomationDeliveryDestination = {
+    key: string;
+    kind: 'gateway_event';
+} | {
+    key: string;
+    kind: 'webhook';
+    endpoint: string;
+    secretId: string;
+} | {
+    key: string;
+    kind: 'file';
+    targetId: string;
+    pathTemplate: string;
+} | {
+    key: string;
+    kind: 'card';
+    channelId: string;
+    templateId: string;
+};
+export interface AutomationDeliveryPolicy {
+    notificationPolicy: AutomationNotificationPolicy;
+    destinations: AutomationDeliveryDestination[];
+}
+export interface AutomationRunDeliveryContext {
+    notificationPolicy: AutomationNotificationPolicy;
+    requiresAttention: boolean;
+    projectId?: string;
+}
 export interface AutomationReliability {
-    /** Overall run deadline. `timeoutSeconds` remains a read-only legacy fallback. */
     executionTimeoutSeconds?: number;
-    timeoutSeconds?: number;
     retryCount?: number;
     maxConcurrentRuns?: number;
     disableAfterConsecutiveFailures?: number;
 }
-export type AutomationRunPhase = 'queued' | 'action' | 'completion_hook' | 'cancelling' | 'completed';
+export type AutomationRunPhase = 'queued' | 'action' | 'cancelling' | 'completed';
 export interface AutomationRunTermination {
     reason: 'completed' | 'failed' | 'user_cancelled' | 'deadline_exceeded';
     component?: 'automation' | 'agent_turn' | 'tool' | 'mcp' | 'process';
@@ -104,8 +130,7 @@ export interface Automation {
     action: AutomationAction;
     safety?: AutomationSafetyPolicy;
     conversationMode: AutomationConversationMode;
-    notificationPolicy: AutomationNotificationPolicy;
-    completionWebhookUrl?: string;
+    delivery: AutomationDeliveryPolicy;
     reliability?: AutomationReliability;
     management?: AutomationManagement;
     state: AutomationState;
@@ -142,7 +167,7 @@ export interface AutomationRun {
     rootRunId?: string;
     readAtMs?: number;
 }
-export type AutomationRunEventType = 'run.queued' | 'run.started' | 'run.deadline_resolved' | 'run.cancel_requested' | 'run.cancel_confirmed' | 'run.cancellation_unconfirmed' | 'run.recovered' | 'action.started' | 'action.retry_scheduled' | 'action.completed' | 'action.failed' | 'completion_hook.started' | 'completion_hook.completed' | 'completion_hook.failed' | 'run.completed';
+export type AutomationRunEventType = 'run.queued' | 'run.started' | 'run.deadline_resolved' | 'run.cancel_requested' | 'run.cancel_confirmed' | 'run.cancellation_unconfirmed' | 'run.recovered' | 'action.started' | 'action.retry_scheduled' | 'action.completed' | 'action.failed' | 'run.completed';
 export interface AutomationRunEvent {
     id: string;
     runId: string;
@@ -157,10 +182,60 @@ export interface AutomationProductEventRun {
     triggerEvent: AutomationRunEvent;
 }
 export interface AutomationEvent {
+    id?: string;
     type: string;
     source?: string;
+    schemaVersion?: number;
+    subject?: {
+        kind: string;
+        id: string;
+    };
     payload?: Record<string, unknown>;
     occurredAtMs?: number;
+    correlationId?: string;
+    causationId?: string;
+    rootEventId?: string;
+    chainDepth?: number;
+    dedupeKey?: string;
+    trust?: 'system' | 'user' | 'connector' | 'untrusted_webhook';
+}
+export interface AutomationEventEnvelope extends AutomationEvent {
+    id: string;
+    source: string;
+    schemaVersion: number;
+    occurredAtMs: number;
+    ingestedAtMs: number;
+    correlationId: string;
+    rootEventId: string;
+    chainDepth: number;
+    trust: 'system' | 'user' | 'connector' | 'untrusted_webhook';
+    payload: Record<string, unknown>;
+}
+export type AutomationEventProjectionStatus = 'pending' | 'projecting' | 'retrying' | 'projected' | 'dead_letter';
+export type AutomationEventDeliveryStatus = 'pending' | 'retrying' | 'queued' | 'completed' | 'failed' | 'cancelled' | 'skipped' | 'dead_letter';
+export interface AutomationEventRecord {
+    event: AutomationEventEnvelope;
+    projectionStatus: AutomationEventProjectionStatus;
+    projectionAttempts: number;
+    projectionError?: string;
+    deliveries: Array<{
+        automationId: string;
+        status: AutomationEventDeliveryStatus;
+        runId?: string;
+        attempts: number;
+        lastError?: string;
+    }>;
+}
+export interface AutomationResultDeliveryRecord {
+    runId: string;
+    destinationKey: string;
+    kind: string;
+    status: 'pending' | 'delivering' | 'retrying' | 'delivered' | 'dead_letter';
+    attempts: number;
+    nextAttemptAtMs: number;
+    lastError?: string;
+    createdAtMs: number;
+    updatedAtMs: number;
 }
 export interface AutomationMetrics {
     totalAutomations: number;
@@ -172,7 +247,73 @@ export interface AutomationMetrics {
         name: string;
         runAtMs: number;
     };
+    pendingEvents: number;
+    oldestPendingEventAgeMs: number;
+    projectionDeadLetters: number;
+    pendingRunDeliveries: number;
+    runDeliveryDeadLetters: number;
+    pendingResultDeliveries: number;
+    resultDeliveryDeadLetters: number;
+    activeExecutions: number;
+    activeDeliveryLeases: number;
+}
+export type AutomationArtifact = {
+    id: string;
+    kind: 'text';
+    text: string;
+    mediaType: 'text/plain' | 'text/markdown';
+} | {
+    id: string;
+    kind: 'json';
+    schema: string;
+    data: Record<string, unknown>;
+} | {
+    id: string;
+    kind: 'file';
+    uri: string;
+    name: string;
+    mediaType: string;
+    bytes?: number;
+    sha256?: string;
+} | {
+    id: string;
+    kind: 'card';
+    schema: string;
+    data: Record<string, unknown>;
+} | {
+    id: string;
+    kind: 'reference';
+    resourceType: string;
+    resourceId: string;
+    url?: string;
+};
+export interface AutomationResultEnvelope {
+    schemaVersion: 1;
+    resultId: string;
+    runId: string;
+    automationId: string;
+    status: Extract<AutomationRunStatus, 'succeeded' | 'failed' | 'cancelled' | 'timeout'>;
+    summary?: string;
+    error?: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    };
+    artifacts: AutomationArtifact[];
+    correlationId: string;
+    rootEventId: string;
+    createdAtMs: number;
+    completedAtMs: number;
 }
+export type AutomationRetrySafety = {
+    mode: 'never';
+} | {
+    mode: 'idempotent';
+    key: 'run_id';
+} | {
+    mode: 'transient_only';
+    classify: (error: unknown) => boolean;
+};
 export interface PrepareAutomationAgentSessionInput {
     automationName?: string;
     conversationId: string;
@@ -210,7 +351,16 @@ export interface AutomationDeps {
             error?: string;
         }>;
     };
-    onRunCompleted?: (run: AutomationRun) => void;
+    onRunCompleted?: (run: AutomationRun, context: AutomationRunDeliveryContext) => void | Promise<void>;
+    onEvent?: (event: AutomationEventEnvelope, signal?: AbortSignal) => void | Promise<void>;
+    onReliabilityAttention?: (input: {
+        phase: 'event_projection' | 'event_delivery' | 'result_delivery';
+        eventId?: string;
+        automationId?: string;
+        runId?: string;
+        destinationKey?: string;
+        error: string;
+    }) => void;
     executeTaskCommand?: (input: {
         taskId: string;
         idempotencyKey: string;
@@ -242,6 +392,7 @@ export interface AutomationActionTask {
     model?: string;
     deadlineAtMs?: number;
     termination?: AutomationRunTermination;
+    artifacts?: AutomationArtifact[];
 }
 export interface AutomationActionExecutionHooks {
     onRunPatch?: (patch: Partial<AutomationRun>) => void | Promise<void>;