@xopcai/xopc 0.0.179 → 0.0.187

package/dist/src/automations/service/automation-service.js

@@ -5,7 +5,7 @@ import { computeNextAutomationRunAtMs, timerDelayUntil } from "../domain/schedul
 import { AutomationSchema, CreateAutomationSchema, UpdateAutomationSchema } from "../domain/validation.js";
 import { AutomationActionExecutor } from "./action-executor.js";
 import { deleteAutomation, getAutomation, listAutomations, saveAutomation, saveAutomations } from "../storage/automation-repository.js";
-import { appendAutomationRunEvent, getAutomationRun, listAutomationRunEvents, listAutomationRuns, listAutomationRunsForProductEvent, saveAutomationRun } from "../storage/automation-run-repository.js";
+import { appendAutomationRunEvent, getAutomationRun, listAutomationRunEvents, listAutomationRuns, listAutomationRunsForProductEvent, saveAutomationRun, touchAutomationRunLease } from "../storage/automation-run-repository.js";
 import "../storage/index.js";
 import { randomUUID } from "node:crypto";
 //#region src/automations/service/automation-service.ts
@@ -13,6 +13,9 @@ init_logger();
 const log = createLogger("AutomationService");
 const DEFAULT_MAX_CONCURRENT_RUNS = 5;
 const MISSED_RUN_STAGGER_MS = 5e3;
+const RUN_HEARTBEAT_INTERVAL_MS = 1e4;
+const RUN_LEASE_DURATION_MS = 3e4;
+const RETRY_BASE_DELAY_MS = 1e3;
 var AutomationAlreadyRunningError = class extends Error {
 	constructor(automationId, runningRunId) {
 		super(`Automation is already running: ${automationId}`);
@@ -29,6 +32,8 @@ var AutomationService = class {
 	deps = {};
 	maxConcurrentRuns = DEFAULT_MAX_CONCURRENT_RUNS;
 	activeRuns = /* @__PURE__ */ new Map();
+	heartbeatTimers = /* @__PURE__ */ new Map();
+	leaseOwner = `automation-service:${process.pid}:${randomUUID()}`;
 	constructor(signals) {
 		this.signals = signals;
 	}
@@ -42,6 +47,7 @@ var AutomationService = class {
 	async initialize(options) {
 		this.maxConcurrentRuns = Math.max(1, Math.floor(options?.maxConcurrentRuns ?? DEFAULT_MAX_CONCURRENT_RUNS));
 		this.stopped = false;
+		await this.recoverInterruptedRuns();
 		await this.recomputeNextRuns({ catchUp: true });
 		this.armTimer();
 		log.info("Automation service initialized");
@@ -53,6 +59,8 @@ var AutomationService = class {
 			this.timer = null;
 		}
 		for (const controller of this.activeRuns.values()) controller.abort();
+		for (const timer of this.heartbeatTimers.values()) clearInterval(timer);
+		this.heartbeatTimers.clear();
 		log.info("Automation service stopped");
 	}
 	async create(input) {
@@ -160,7 +168,19 @@ var AutomationService = class {
 	async cancelRun(runId) {
 		const controller = this.activeRuns.get(runId);
 		if (!controller) return false;
-		controller.abort();
+		const now = Date.now();
+		const current = getAutomationRun(runId);
+		if (current && current.status === "running") {
+			const cancelling = {
+				...current,
+				status: "cancelling",
+				currentPhase: "cancelling",
+				cancelRequestedAtMs: now
+			};
+			saveAutomationRun(cancelling);
+			this.appendRunEvent(cancelling, "run.cancel_requested", "Automation cancellation requested", { reason: "user_cancelled" });
+		}
+		controller.abort(/* @__PURE__ */ new Error("Automation run was cancelled by the user"));
 		return true;
 	}
 	async getMetrics() {
@@ -187,7 +207,7 @@ var AutomationService = class {
 				...automation,
 				state: { ...automation.state }
 			};
-			if (next.state.runningRunId) {
+			if (next.state.runningRunId && !this.activeRuns.has(next.state.runningRunId)) {
 				next.state.lastRunStatus = "failed";
 				next.state.lastError = "Interrupted by gateway restart";
 				next.state.consecutiveFailures = (next.state.consecutiveFailures ?? 0) + 1;
@@ -237,8 +257,10 @@ var AutomationService = class {
 			triggerSnapshot: automation.trigger,
 			actionSnapshot: automation.action,
 			manual: opts.manual,
-			createdAtMs: now
+			createdAtMs: now,
+			attemptNumber: 1
 		};
+		run.rootRunId = run.id;
 		saveAutomationRun(run);
 		this.appendRunEvent(run, "run.queued", opts.event ? `Event ${opts.event.type} queued automation` : opts.manual ? "Manual run queued" : "Scheduled run queued", {
 			trigger: automation.trigger,
@@ -270,52 +292,129 @@ var AutomationService = class {
 		let run = {
 			...initialRun,
 			status: "running",
-			startedAtMs
+			startedAtMs,
+			currentPhase: "action",
+			heartbeatAtMs: startedAtMs,
+			leaseOwner: this.leaseOwner,
+			leaseExpiresAtMs: startedAtMs + RUN_LEASE_DURATION_MS
 		};
 		saveAutomationRun(run);
 		this.appendRunEvent(run, "run.started", "Automation run started");
+		const heartbeat = setInterval(() => {
+			const now = Date.now();
+			touchAutomationRunLease(run.id, this.leaseOwner, now, now + RUN_LEASE_DURATION_MS);
+		}, RUN_HEARTBEAT_INTERVAL_MS);
+		heartbeat.unref?.();
+		this.heartbeatTimers.set(run.id, heartbeat);
 		let status = "failed";
 		let error;
 		let activePhase = "action";
 		try {
-			this.appendRunEvent(run, "action.started", `Running ${automation.action.kind} action`, {
-				actionKind: automation.action.kind,
-				safety: automation.safety ?? { mode: "auto_apply" }
-			});
-			const outcome = await this.executor.execute(automation, run, controller.signal);
-			status = outcome.status;
-			error = outcome.error;
+			const maxAttempts = Math.max(1, (automation.reliability?.retryCount ?? 0) + 1);
+			let task;
+			for (let attempt = 1;; attempt += 1) {
+				run = {
+					...run,
+					attemptNumber: attempt
+				};
+				saveAutomationRun(run);
+				this.appendRunEvent(run, "action.started", `Running ${automation.action.kind} action`, {
+					actionKind: automation.action.kind,
+					safety: automation.safety ?? { mode: "auto_apply" },
+					attempt,
+					maxAttempts
+				});
+				task = await this.executor.execute(automation, run, controller.signal, { onRunPatch: (patch) => {
+					const previousDeadline = run.deadlineAtMs;
+					run = {
+						...run,
+						...patch
+					};
+					saveAutomationRun(run);
+					if (patch.deadlineAtMs !== void 0 && patch.deadlineAtMs !== previousDeadline) this.appendRunEvent(run, "run.deadline_resolved", "Automation deadline resolved", {
+						deadlineAtMs: patch.deadlineAtMs,
+						timeoutMs: patch.deadlineAtMs - startedAtMs
+					});
+				} });
+				if (!(task.status === "failed") || attempt >= maxAttempts || controller.signal.aborted) break;
+				const delayMs = Math.min(RETRY_BASE_DELAY_MS * 2 ** (attempt - 1), 3e4);
+				this.appendRunEvent(run, "action.retry_scheduled", "Automation action retry scheduled", {
+					attempt,
+					nextAttempt: attempt + 1,
+					maxAttempts,
+					delayMs,
+					status: task.status,
+					error: task.error
+				});
+				await this.waitForRetry(delayMs, controller.signal);
+			}
+			status = task.status;
+			error = task.error;
+			const persistedRun = getAutomationRun(run.id);
+			if (persistedRun) run = {
+				...run,
+				...persistedRun
+			};
 			this.appendRunEvent(run, status === "succeeded" ? "action.completed" : "action.failed", status === "succeeded" ? `${automation.action.kind} action completed` : `${automation.action.kind} action ${status}`, {
-				summary: outcome.summary,
-				error: outcome.error,
-				sessionKey: outcome.sessionKey,
-				workflowRunId: outcome.workflowRunId,
-				model: outcome.model
+				summary: task.summary,
+				error: task.error,
+				sessionKey: task.sessionKey,
+				workflowRunId: task.workflowRunId,
+				model: task.model
 			});
 			run = {
 				...run,
 				status,
-				summary: outcome.summary,
+				summary: task.summary,
 				error,
-				sessionKey: outcome.sessionKey,
-				workflowRunId: outcome.workflowRunId,
-				model: outcome.model
+				sessionKey: task.sessionKey,
+				workflowRunId: task.workflowRunId,
+				model: task.model,
+				deadlineAtMs: task.deadlineAtMs ?? run.deadlineAtMs,
+				termination: task.termination ?? (status === "succeeded" ? {
+					reason: "completed",
+					cancellationConfirmed: true
+				} : status === "failed" ? {
+					reason: "failed",
+					cancellationConfirmed: true
+				} : run.termination)
 			};
-			if ((automation.safety?.mode ?? "auto_apply") !== "auto_apply" && automation.afterRun?.kind === "webhook") this.appendRunEvent(run, "after_run.completed", "After-run webhook skipped by safety mode", { safety: automation.safety ?? { mode: "auto_apply" } });
+			if (task.termination) {
+				const now = Date.now();
+				run = {
+					...run,
+					currentPhase: "cancelling",
+					cancelRequestedAtMs: run.cancelRequestedAtMs ?? now,
+					cancelConfirmedAtMs: task.termination.cancellationConfirmed ? now : void 0
+				};
+				this.appendRunEvent(run, task.termination.cancellationConfirmed ? "run.cancel_confirmed" : "run.cancellation_unconfirmed", task.termination.cancellationConfirmed ? "Automation cancellation confirmed" : "Automation cancellation was not confirmed within the cleanup grace period", { termination: task.termination });
+			}
+			if (status === "timeout" || status === "cancelled") {} else if ((automation.safety?.mode ?? "auto_apply") !== "auto_apply" && automation.afterRun?.kind === "webhook") this.appendRunEvent(run, "after_run.completed", "After-run webhook skipped by safety mode", { safety: automation.safety ?? { mode: "auto_apply" } });
 			else if (automation.afterRun?.kind === "webhook") {
 				activePhase = "after_run";
+				run = {
+					...run,
+					currentPhase: "after_run"
+				};
+				saveAutomationRun(run);
 				this.appendRunEvent(run, "after_run.started", "Calling after-run webhook", { url: automation.afterRun.url });
-				await this.postAfterRunWebhook(automation.afterRun.url, run);
+				await this.postAfterRunWebhook(automation.afterRun.url, run, controller.signal);
 				this.appendRunEvent(run, "after_run.completed", "After-run webhook completed");
 			}
 		} catch (err) {
 			error = err instanceof Error ? err.message : String(err);
-			status = controller.signal.aborted ? "cancelled" : "failed";
+			const deadlineExceeded = run.deadlineAtMs !== void 0 && Date.now() >= run.deadlineAtMs;
+			status = controller.signal.aborted ? "cancelled" : deadlineExceeded ? "timeout" : "failed";
 			this.appendRunEvent(run, activePhase === "after_run" ? "after_run.failed" : "action.failed", `Automation run ${status}`, { error });
 			run = {
 				...run,
 				status,
-				error
+				error,
+				termination: {
+					reason: status === "cancelled" ? "user_cancelled" : status === "timeout" ? "deadline_exceeded" : "failed",
+					component: activePhase === "after_run" ? "automation" : run.termination?.component,
+					cancellationConfirmed: status !== "cancelled" || controller.signal.aborted
+				}
 			};
 		} finally {
 			const endedAtMs = Date.now();
@@ -323,9 +422,19 @@ var AutomationService = class {
 				...run,
 				status,
 				endedAtMs,
-				durationMs: endedAtMs - startedAtMs
+				durationMs: endedAtMs - startedAtMs,
+				currentPhase: "completed"
 			};
 			this.activeRuns.delete(initialRun.id);
+			const heartbeatTimer = this.heartbeatTimers.get(initialRun.id);
+			if (heartbeatTimer) clearInterval(heartbeatTimer);
+			this.heartbeatTimers.delete(initialRun.id);
+			run = {
+				...run,
+				heartbeatAtMs: endedAtMs,
+				leaseOwner: void 0,
+				leaseExpiresAtMs: void 0
+			};
 			runSqliteWriteTransaction(() => {
 				saveAutomationRun(run);
 				this.appendRunEvent(run, "run.completed", `Automation run ${status}`, {
@@ -370,6 +479,73 @@ var AutomationService = class {
 			}
 		}
 	}
+	async recoverInterruptedRuns() {
+		const recoverable = listAutomationRuns({ limit: 500 }).filter((run) => run.status === "queued" || run.status === "running" || run.status === "cancelling");
+		for (const run of recoverable) {
+			const automation = getAutomation(run.automationId);
+			if (run.status === "queued" && automation) {
+				const claimed = {
+					...automation,
+					state: {
+						...automation.state,
+						runningRunId: run.id
+					}
+				};
+				saveAutomation(claimed);
+				this.appendRunEvent(run, "run.recovered", "Queued automation run recovered after restart", { previousLeaseOwner: run.leaseOwner });
+				this.executeRun(claimed, run).catch((err) => {
+					log.error({
+						err,
+						runId: run.id
+					}, "Recovered automation run failed");
+				});
+				continue;
+			}
+			const now = Date.now();
+			const status = run.status === "cancelling" ? "cancelled" : "failed";
+			const error = run.status === "cancelling" ? "Cancellation interrupted by gateway restart" : "Automation execution interrupted by gateway restart";
+			const recovered = {
+				...run,
+				status,
+				error,
+				endedAtMs: now,
+				durationMs: run.startedAtMs ? now - run.startedAtMs : void 0,
+				currentPhase: "completed",
+				heartbeatAtMs: now,
+				leaseOwner: void 0,
+				leaseExpiresAtMs: void 0,
+				termination: {
+					reason: status === "cancelled" ? "user_cancelled" : "failed",
+					component: "automation",
+					cancellationConfirmed: false
+				}
+			};
+			saveAutomationRun(recovered);
+			this.appendRunEvent(recovered, "run.recovered", error, {
+				previousLeaseOwner: run.leaseOwner,
+				previousLeaseExpiresAtMs: run.leaseExpiresAtMs
+			});
+			this.appendRunEvent(recovered, "run.completed", `Automation run ${status}`, {
+				status,
+				error
+			});
+			if (automation) this.finishAutomationRun(automation.id, status, error, now);
+		}
+	}
+	waitForRetry(delayMs, signal) {
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				signal.removeEventListener("abort", onAbort);
+				resolve();
+			}, delayMs);
+			const onAbort = () => {
+				clearTimeout(timer);
+				reject(signal.reason ?? /* @__PURE__ */ new Error("Automation run was cancelled"));
+			};
+			if (signal.aborted) onAbort();
+			else signal.addEventListener("abort", onAbort, { once: true });
+		});
+	}
 	appendRunEvent(run, type, message, data) {
 		appendAutomationRunEvent({
 			id: randomUUID(),
@@ -404,11 +580,14 @@ var AutomationService = class {
 		saveAutomation(next);
 		this.armTimer();
 	}
-	async postAfterRunWebhook(url, run) {
+	async postAfterRunWebhook(url, run, signal) {
+		const remainingMs = run.deadlineAtMs === void 0 ? 3e4 : Math.max(1, run.deadlineAtMs - Date.now());
+		const requestSignal = AbortSignal.any([signal, AbortSignal.timeout(remainingMs)]);
 		const response = await fetch(url, {
 			method: "POST",
 			headers: { "content-type": "application/json" },
-			body: JSON.stringify({ run })
+			body: JSON.stringify({ run }),
+			signal: requestSignal
 		});
 		if (!response.ok) {
 			const text = await response.text().catch(() => "");

package/dist/src/automations/storage/automation-run-repository.d.ts

@@ -1,6 +1,7 @@
 import type { AutomationProductEventRun, AutomationRun, AutomationRunEvent } from '../domain/types.js';
 export declare function appendAutomationRunEvent(event: AutomationRunEvent): void;
 export declare function saveAutomationRun(run: AutomationRun): void;
+export declare function touchAutomationRunLease(runId: string, leaseOwner: string, heartbeatAtMs: number, leaseExpiresAtMs: number): void;
 export declare function listAutomationRunEvents(runId: string): AutomationRunEvent[];
 export declare function getAutomationRun(runId: string): AutomationRun | null;
 export declare function listAutomationRuns(options?: {

package/dist/src/automations/storage/automation-run-repository.js

@@ -19,7 +19,17 @@ function rowToRun(row) {
 		error: row.error ?? void 0,
 		sessionKey: row.session_key ?? void 0,
 		workflowRunId: row.workflow_run_id ?? void 0,
-		model: row.model ?? void 0
+		model: row.model ?? void 0,
+		deadlineAtMs: row.deadline_at_ms ?? void 0,
+		currentPhase: row.current_phase ?? void 0,
+		cancelRequestedAtMs: row.cancel_requested_at_ms ?? void 0,
+		cancelConfirmedAtMs: row.cancel_confirmed_at_ms ?? void 0,
+		termination: row.termination_json ? JSON.parse(row.termination_json) : void 0,
+		heartbeatAtMs: row.heartbeat_at_ms ?? void 0,
+		leaseOwner: row.lease_owner ?? void 0,
+		leaseExpiresAtMs: row.lease_expires_at_ms ?? void 0,
+		attemptNumber: row.attempt_number,
+		rootRunId: row.root_run_id ?? void 0
 	};
 }
 function rowToEvent(row) {
@@ -55,11 +65,19 @@ function saveAutomationRun(run) {
 		db.prepare(`INSERT OR REPLACE INTO automation_runs (
         run_id, automation_id, automation_name, status, trigger_snapshot_json,
         action_snapshot_json, manual, created_at_ms, started_at_ms, ended_at_ms,
-        duration_ms, summary, error, session_key, workflow_run_id, model
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(run.id, run.automationId, run.automationName, run.status, JSON.stringify(run.triggerSnapshot), JSON.stringify(run.actionSnapshot), run.manual ? 1 : 0, run.createdAtMs, run.startedAtMs ?? null, run.endedAtMs ?? null, run.durationMs ?? null, run.summary ?? null, run.error ?? null, run.sessionKey ?? null, run.workflowRunId ?? null, run.model ?? null);
+        duration_ms, summary, error, session_key, workflow_run_id, model,
+        deadline_at_ms, current_phase, cancel_requested_at_ms, cancel_confirmed_at_ms,
+        termination_json, heartbeat_at_ms, lease_owner, lease_expires_at_ms,
+        attempt_number, root_run_id
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(run.id, run.automationId, run.automationName, run.status, JSON.stringify(run.triggerSnapshot), JSON.stringify(run.actionSnapshot), run.manual ? 1 : 0, run.createdAtMs, run.startedAtMs ?? null, run.endedAtMs ?? null, run.durationMs ?? null, run.summary ?? null, run.error ?? null, run.sessionKey ?? null, run.workflowRunId ?? null, run.model ?? null, run.deadlineAtMs ?? null, run.currentPhase ?? null, run.cancelRequestedAtMs ?? null, run.cancelConfirmedAtMs ?? null, run.termination ? JSON.stringify(run.termination) : null, run.heartbeatAtMs ?? null, run.leaseOwner ?? null, run.leaseExpiresAtMs ?? null, run.attemptNumber ?? 1, run.rootRunId ?? run.id);
 		trimRuns(db, run.automationId);
 	});
 }
+function touchAutomationRunLease(runId, leaseOwner, heartbeatAtMs, leaseExpiresAtMs) {
+	getSqliteDatabase().prepare(`UPDATE automation_runs
+       SET heartbeat_at_ms = ?, lease_owner = ?, lease_expires_at_ms = ?
+       WHERE run_id = ? AND status IN ('queued', 'running', 'cancelling')`).run(heartbeatAtMs, leaseOwner, leaseExpiresAtMs, runId);
+}
 function listAutomationRunEvents(runId) {
 	return getSqliteDatabase().prepare(`SELECT event_id, run_id, automation_id, type, message, data_json, created_at_ms
        FROM automation_run_events
@@ -69,7 +87,10 @@ function listAutomationRunEvents(runId) {
 function getAutomationRun(runId) {
 	const row = getSqliteDatabase().prepare(`SELECT run_id, automation_id, automation_name, status, trigger_snapshot_json,
               action_snapshot_json, manual, created_at_ms, started_at_ms, ended_at_ms,
-              duration_ms, summary, error, session_key, workflow_run_id, model
+              duration_ms, summary, error, session_key, workflow_run_id, model,
+              deadline_at_ms, current_phase, cancel_requested_at_ms, cancel_confirmed_at_ms,
+              termination_json, heartbeat_at_ms, lease_owner, lease_expires_at_ms,
+              attempt_number, root_run_id
        FROM automation_runs
        WHERE run_id = ?`).get(runId);
 	return row ? rowToRun(row) : null;
@@ -79,13 +100,19 @@ function listAutomationRuns(options) {
 	const db = getSqliteDatabase();
 	const base = `SELECT run_id, automation_id, automation_name, status, trigger_snapshot_json,
                        action_snapshot_json, manual, created_at_ms, started_at_ms, ended_at_ms,
-                       duration_ms, summary, error, session_key, workflow_run_id, model
+                       duration_ms, summary, error, session_key, workflow_run_id, model,
+                       deadline_at_ms, current_phase, cancel_requested_at_ms, cancel_confirmed_at_ms,
+                       termination_json, heartbeat_at_ms, lease_owner, lease_expires_at_ms,
+                       attempt_number, root_run_id
                 FROM automation_runs`;
 	let rows;
 	if (options?.automationId) rows = db.prepare(`${base} WHERE automation_id = ? ORDER BY created_at_ms DESC LIMIT ?`).all(options.automationId, limit);
 	else if (options?.projectId) rows = db.prepare(`SELECT r.run_id, r.automation_id, r.automation_name, r.status, r.trigger_snapshot_json,
               r.action_snapshot_json, r.manual, r.created_at_ms, r.started_at_ms, r.ended_at_ms,
-              r.duration_ms, r.summary, r.error, r.session_key, r.workflow_run_id, r.model
+              r.duration_ms, r.summary, r.error, r.session_key, r.workflow_run_id, r.model,
+              r.deadline_at_ms, r.current_phase, r.cancel_requested_at_ms, r.cancel_confirmed_at_ms,
+              r.termination_json, r.heartbeat_at_ms, r.lease_owner, r.lease_expires_at_ms,
+              r.attempt_number, r.root_run_id
        FROM automation_runs r
        JOIN automations a ON a.automation_id = r.automation_id
        WHERE a.project_id = ?
@@ -109,6 +136,9 @@ function listAutomationRunsForProductEvent(options) {
 	return getSqliteDatabase().prepare(`SELECT r.run_id, r.automation_id, r.automation_name, r.status, r.trigger_snapshot_json,
               r.action_snapshot_json, r.manual, r.created_at_ms, r.started_at_ms, r.ended_at_ms,
               r.duration_ms, r.summary, r.error, r.session_key, r.workflow_run_id, r.model,
+              r.deadline_at_ms, r.current_phase, r.cancel_requested_at_ms, r.cancel_confirmed_at_ms,
+              r.termination_json, r.heartbeat_at_ms, r.lease_owner, r.lease_expires_at_ms,
+              r.attempt_number, r.root_run_id,
               e.event_id, e.run_id AS event_run_id, e.automation_id AS event_automation_id,
               e.type AS event_type, e.message AS event_message, e.data_json AS event_data_json,
               e.created_at_ms AS event_created_at_ms
@@ -136,4 +166,4 @@ function deleteAutomationRunsForAutomation(automationId) {
 	});
 }
 //#endregion
-export { appendAutomationRunEvent, deleteAutomationRunsForAutomation, getAutomationRun, listAutomationRunEvents, listAutomationRuns, listAutomationRunsForProductEvent, saveAutomationRun };
+export { appendAutomationRunEvent, deleteAutomationRunsForAutomation, getAutomationRun, listAutomationRunEvents, listAutomationRuns, listAutomationRunsForProductEvent, saveAutomationRun, touchAutomationRunLease };

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

@@ -1,3 +1,3 @@
 import { deleteAutomation, getAutomation, listAutomations, saveAutomation, saveAutomations } from "./automation-repository.js";
-import { appendAutomationRunEvent, deleteAutomationRunsForAutomation, getAutomationRun, listAutomationRunEvents, listAutomationRuns, listAutomationRunsForProductEvent, saveAutomationRun } from "./automation-run-repository.js";
-export { appendAutomationRunEvent, deleteAutomation, deleteAutomationRunsForAutomation, getAutomation, getAutomationRun, listAutomationRunEvents, listAutomationRuns, listAutomationRunsForProductEvent, listAutomations, saveAutomation, saveAutomationRun, saveAutomations };
+import { appendAutomationRunEvent, deleteAutomationRunsForAutomation, getAutomationRun, listAutomationRunEvents, listAutomationRuns, listAutomationRunsForProductEvent, saveAutomationRun, touchAutomationRunLease } from "./automation-run-repository.js";
+export { appendAutomationRunEvent, deleteAutomation, deleteAutomationRunsForAutomation, getAutomation, getAutomationRun, listAutomationRunEvents, listAutomationRuns, listAutomationRunsForProductEvent, listAutomations, saveAutomation, saveAutomationRun, saveAutomations, touchAutomationRunLease };

package/dist/src/browser/providers/cloakbrowser.js

@@ -11,9 +11,9 @@ import { createReadStream, createWriteStream } from "node:fs";
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { mkdir, mkdtemp, rm, stat } from "node:fs/promises";
+import AdmZip from "adm-zip";
 import { pipeline } from "node:stream/promises";
 import { Readable, Transform } from "node:stream";
-import AdmZip from "adm-zip";
 //#region src/browser/providers/cloakbrowser.ts
 /**
 * CloakBrowser provider — anti-fingerprint Chromium with stealth capabilities.

package/dist/src/chat-commands/builtins/understanding.d.ts

@@ -0,0 +1 @@
+export declare function registerUnderstandingCommands(): void;

package/dist/src/chat-commands/builtins/understanding.js

@@ -0,0 +1,91 @@
+import { init_agent_scope, resolveDefaultAgentId } from "../../agent/agent-scope.js";
+import { commandRegistry } from "../registry.js";
+import { createManualUnderstanding } from "../../user-context/manual-understanding.js";
+//#region src/chat-commands/builtins/understanding.ts
+init_agent_scope();
+function parseRememberArgs(args) {
+	const trimmed = args.trim();
+	if (trimmed !== "--session" && !trimmed.startsWith("--session ")) return {
+		content: trimmed,
+		sessionOnly: false
+	};
+	return {
+		content: trimmed.slice(9).trim(),
+		sessionOnly: true
+	};
+}
+const rememberCommand = {
+	id: "understanding.remember",
+	name: "remember",
+	description: "Explicitly tell xopc something to remember (--session keeps it in this conversation)",
+	category: "session",
+	scope: ["private"],
+	acceptsArgs: true,
+	examples: ["/remember I prefer concise updates", "/remember --session This chat is about launch planning"],
+	handler: async (ctx, args) => {
+		const { content, sessionOnly } = parseRememberArgs(args);
+		if (!content || content.length > 5e3) return {
+			content: "Usage: /remember [--session] <what xopc should know> (max 5000 characters)",
+			success: false
+		};
+		const result = createManualUnderstanding({
+			agentId: resolveDefaultAgentId(ctx.config),
+			content,
+			kind: "derived_insight",
+			scope: sessionOnly ? {
+				type: "session",
+				sessionKey: ctx.sessionKey
+			} : { type: "global" },
+			sensitivity: "normal",
+			durability: sessionOnly ? "ephemeral" : "durable",
+			disclosurePolicy: "referenceable"
+		});
+		const scopeLabel = sessionOnly ? "this conversation" : "all conversations";
+		return {
+			content: result.created ? `Remembered for ${scopeLabel}. You can review or remove it in About You.` : `This is already remembered for ${scopeLabel}.`,
+			success: true
+		};
+	}
+};
+const learningCommand = {
+	id: "understanding.learning",
+	name: "learning",
+	aliases: ["learn"],
+	description: "Control user-understanding context and learning for this conversation (on | off | status)",
+	category: "session",
+	scope: ["private"],
+	acceptsArgs: true,
+	examples: [
+		"/learning off",
+		"/learning on",
+		"/learning status"
+	],
+	handler: async (ctx, args) => {
+		const store = ctx.getSessionConfigStore?.();
+		if (!store) return {
+			content: "Session settings are unavailable here.",
+			success: false
+		};
+		const action = args.trim().toLowerCase() || "status";
+		if (![
+			"on",
+			"off",
+			"status"
+		].includes(action)) return {
+			content: "Usage: /learning on | off | status",
+			success: false
+		};
+		if (action !== "status") await store.update(ctx.sessionKey, { userContextMode: action === "off" ? "off" : "enabled" });
+		const globallyEnabled = ctx.config.userContext.enabled && ctx.config.userContext.memory.mode !== "off";
+		return {
+			content: globallyEnabled && (await store.get(ctx.sessionKey))?.userContextMode !== "off" ? "User understanding is enabled for this conversation." : globallyEnabled ? "User understanding is off for this conversation. Existing chat history is still stored; use /remember for anything you explicitly want saved." : "User understanding is disabled globally. Existing chat history is still stored.",
+			success: true
+		};
+	}
+};
+function registerUnderstandingCommands() {
+	commandRegistry.register(rememberCommand);
+	commandRegistry.register(learningCommand);
+}
+//#endregion
+export { registerUnderstandingCommands };

package/dist/src/chat-commands/context.d.ts

@@ -11,7 +11,6 @@ import type { MessageBus } from '../infra/bus/index.js';
 import type { SessionStore, SessionConfigStore } from '../session/index.js';
 import type { ThinkLevel, ReasoningLevel, VerboseLevel } from '../agent/transcript/thinking-types.js';
 import type { CompactionResult } from '../agent/memory/compaction.js';
-import type { PersistentGoalApis } from '../agent/goals/persistent-goal-apis.js';
 import type { WorkflowRunServiceLike } from '../workflows/service/workflow-run-service.types.js';
 export interface CommandContextDeps {
     sessionKey: string;
@@ -56,7 +55,6 @@ export interface CommandContextDeps {
     }>;
     emitEvent?: (event: CommandStreamEvent) => void | Promise<void>;
     getSessionContextReport?: (sessionKey: string, mode: 'list' | 'detail' | 'json') => Promise<string>;
-    persistentGoalApis?: PersistentGoalApis;
     workflowRunService?: WorkflowRunServiceLike;
 }
 export declare class CommandContextImpl implements CommandContext {
@@ -72,7 +70,6 @@ export declare class CommandContextImpl implements CommandContext {
     readonly abortCurrentTurn?: () => Promise<void>;
     readonly reloadSkills?: () => Promise<void>;
     readonly installSkillFromSource?: CommandContext['installSkillFromSource'];
-    readonly persistentGoalApis?: PersistentGoalApis;
     readonly workflowRunApis?: CommandContext['workflowRunApis'];
     private deps;
     constructor(deps: CommandContextDeps);

package/dist/src/chat-commands/context.js

@@ -26,7 +26,6 @@ var CommandContextImpl = class {
 	abortCurrentTurn;
 	reloadSkills;
 	installSkillFromSource;
-	persistentGoalApis;
 	workflowRunApis;
 	deps;
 	constructor(deps) {
@@ -53,7 +52,6 @@ var CommandContextImpl = class {
 			};
 		}
 		if (deps.installSkillFromSource) this.installSkillFromSource = deps.installSkillFromSource;
-		this.persistentGoalApis = deps.persistentGoalApis;
 		if (deps.workflowRunService) this.workflowRunApis = {
 			service: deps.workflowRunService,
 			startWorkflowRun: (params) => deps.workflowRunService.startWorkflowRun(params)

package/dist/src/chat-commands/index.d.ts

@@ -17,11 +17,10 @@ export { registerTTSCommands } from './builtins/tts.js';
 export { registerThinkingCommands } from './builtins/thinking.js';
 export { registerConfigCommand } from './builtins/config.js';
 export { registerContextCommands } from './builtins/context.js';
-export { registerGoalCommand } from './builtins/goal.js';
-export { registerSubgoalCommand } from './builtins/subgoal.js';
 export { registerWorkflowCommands } from './builtins/workflow.js';
 export { registerReviewCommand } from './builtins/review.js';
 export { registerSkillCommand } from './builtins/skill.js';
+export { registerUnderstandingCommands } from './builtins/understanding.js';
 export { registerAgentEditCommand } from './agent-edit.js';
 /**
  * Initialize the command system with all built-in commands

package/dist/src/chat-commands/index.js

@@ -8,11 +8,10 @@ import { registerTTSCommands } from "./builtins/tts.js";
 import { registerThinkingCommands } from "./builtins/thinking.js";
 import { registerConfigCommand } from "./builtins/config.js";
 import { registerContextCommands } from "./builtins/context.js";
-import { registerGoalCommand } from "./builtins/goal.js";
-import { registerSubgoalCommand } from "./builtins/subgoal.js";
 import { registerWorkflowCommands } from "./builtins/workflow.js";
 import { registerReviewCommand } from "./builtins/review.js";
 import { registerSkillCommand } from "./builtins/skill.js";
+import { registerUnderstandingCommands } from "./builtins/understanding.js";
 import { registerAgentEditCommand } from "./agent-edit.js";
 import { CommandContextImpl, createCommandContext } from "./context.js";
 //#region src/chat-commands/index.ts
@@ -33,12 +32,11 @@ function initializeCommands() {
 	registerContextCommands();
 	registerTTSCommands();
 	registerThinkingCommands();
-	registerGoalCommand();
-	registerSubgoalCommand();
 	registerWorkflowCommands();
 	registerReviewCommand();
 	registerSkillCommand();
+	registerUnderstandingCommands();
 	registerAgentEditCommand();
 }
 //#endregion
-export { CommandContextImpl, CommandRegistry, commandRegistry, createCommandContext, generateSessionKey, getSessionDisplayName, initializeCommands, normalizeTelegramCommandName, parseSlashCommand, registerAgentEditCommand, registerConfigCommand, registerContextCommands, registerGoalCommand, registerModelCommands, registerReviewCommand, registerSessionCommands, registerSkillCommand, registerSubgoalCommand, registerSystemCommands, registerTTSCommands, registerThinkingCommands, registerWorkflowCommands };
+export { CommandContextImpl, CommandRegistry, commandRegistry, createCommandContext, generateSessionKey, getSessionDisplayName, initializeCommands, normalizeTelegramCommandName, parseSlashCommand, registerAgentEditCommand, registerConfigCommand, registerContextCommands, registerModelCommands, registerReviewCommand, registerSessionCommands, registerSkillCommand, registerSystemCommands, registerTTSCommands, registerThinkingCommands, registerUnderstandingCommands, registerWorkflowCommands };

package/dist/src/chat-commands/types.d.ts

@@ -5,7 +5,6 @@
  * Telegram, Feishu, Web UI, CLI, and other channel surfaces.
  */
 import type { Config } from '../config/schema.js';
-import type { PersistentGoalApis } from '../agent/goals/persistent-goal-apis.js';
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import type { ThinkLevel, ReasoningLevel, VerboseLevel } from '../agent/transcript/thinking-types.js';
 import type { SessionConfigStore } from '../session/index.js';
@@ -218,8 +217,6 @@ export interface CommandContext {
     agentContextReport?(mode?: 'list' | 'detail' | 'json'): Promise<string>;
     /** Abort in-flight assistant generation and channel streaming for this session (e.g. /abort) */
     abortCurrentTurn?(): Promise<void>;
-    /** Session store + continuation scheduling for built-in persistent `/goal` (when wired). */
-    persistentGoalApis?: PersistentGoalApis;
     workflowRunApis?: {
         startWorkflowRun(params: StartWorkflowRunServiceParams): Promise<WorkflowRunServiceResult>;
         service: WorkflowRunServiceLike;