@ouro.bot/cli 0.1.0-alpha.92 → 0.1.0-alpha.921

package/dist/heart/awaiting/await-scheduler.js

@@ -0,0 +1,391 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AwaitScheduler = exports.AWAIT_CRON_LABEL_PREFIX_MARKER = void 0;
+const path = __importStar(require("path"));
+const runtime_1 = require("../../nerves/runtime");
+const await_parser_1 = require("./await-parser");
+const await_runtime_state_1 = require("./await-runtime-state");
+const cadence_1 = require("../daemon/cadence");
+const WATCH_DEBOUNCE_MS = 200;
+/** Cron-label namespace prefix to avoid collision with habits. */
+exports.AWAIT_CRON_LABEL_PREFIX_MARKER = "await";
+/** An await that ships with the package: it has no filer, friend, conversation or request behind it (the same test the private runtime uses for "no relationship"). */
+function isSystemAwait(a) {
+    return !a.request_id && !a.filed_for_friend_id && !a.filed_from_key && (!a.filed_from || a.filed_from === "unknown");
+}
+class AwaitScheduler {
+    agent;
+    awaitsDir;
+    osCronManager;
+    onAwaitFire;
+    onAwaitExpire;
+    deps;
+    execForVerify;
+    verifyJobs;
+    platform;
+    watcher = null;
+    debounceTimer = null;
+    parseErrors = [];
+    timerFallbacks = new Map();
+    degradedAwaitNames = new Map();
+    periodicTimer = null;
+    constructor(options) {
+        this.agent = options.agent;
+        this.awaitsDir = options.awaitsDir;
+        this.osCronManager = options.osCronManager;
+        this.onAwaitFire = options.onAwaitFire;
+        this.onAwaitExpire = options.onAwaitExpire;
+        this.deps = options.deps;
+        this.execForVerify = options.execForVerify;
+        this.verifyJobs = options.verifyJobs;
+        this.platform = options.platform ?? process.platform;
+    }
+    start() {
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.await_scheduler_start",
+            message: "await scheduler starting",
+            meta: { agent: this.agent, awaitsDir: this.awaitsDir },
+        });
+        // Ensure the awaits dir exists before scanning + attaching the file watcher.
+        // Without this, fs.watch ENOENTs on cold start and the watcher is never installed,
+        // so a freshly-filed first-ever await has to wait for the next periodic reconcile.
+        this.deps.mkdir(this.awaitsDir);
+        const awaits = this.scanAwaits();
+        this.expireOverdueByMaxAge(awaits);
+        const remaining = awaits.filter((a) => a.status === "pending" && !this.isExpiredByMaxAge(a));
+        const jobs = this.buildJobs(remaining);
+        this.osCronManager.sync(jobs);
+        this.verifyCronAndCreateFallbacks(jobs);
+        this.fireOverdueAwaits(remaining);
+    }
+    reconcile() {
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.await_scheduler_reconcile",
+            message: "await scheduler reconciling",
+            meta: { agent: this.agent },
+        });
+        this.clearAllTimerFallbacks();
+        const awaits = this.scanAwaits();
+        this.expireOverdueByMaxAge(awaits);
+        const remaining = awaits.filter((a) => a.status === "pending" && !this.isExpiredByMaxAge(a));
+        const jobs = this.buildJobs(remaining);
+        this.osCronManager.sync(jobs);
+        this.verifyCronAndCreateFallbacks(jobs);
+        this.fireOverdueAwaits(remaining);
+    }
+    stop() {
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.await_scheduler_end",
+            message: "await scheduler stopping",
+            meta: { agent: this.agent },
+        });
+        this.stopPeriodicReconciliation();
+        this.clearAllTimerFallbacks();
+        this.osCronManager.removeAll();
+    }
+    getParseErrors() {
+        return [...this.parseErrors];
+    }
+    getDegradedAwaits() {
+        const out = [];
+        for (const [name, reason] of this.degradedAwaitNames)
+            out.push({ name, reason });
+        return out;
+    }
+    getAwaitFile(name) {
+        const filePath = path.join(this.awaitsDir, `${name}.md`);
+        try {
+            const content = this.deps.readFile(filePath, "utf-8");
+            return (0, await_runtime_state_1.applyAwaitRuntimeState)(path.dirname(this.awaitsDir), (0, await_parser_1.parseAwaitFile)(content, filePath));
+        }
+        catch {
+            return null;
+        }
+    }
+    watchForChanges() {
+        const watchFn = this.deps.watch;
+        if (!watchFn)
+            return;
+        try {
+            this.watcher = watchFn(this.awaitsDir, (_event, _filename) => {
+                if (this.debounceTimer !== null)
+                    clearTimeout(this.debounceTimer);
+                this.debounceTimer = setTimeout(() => {
+                    this.debounceTimer = null;
+                    this.reconcile();
+                }, WATCH_DEBOUNCE_MS);
+            });
+            /* v8 ignore start — ENOENT catch requires real missing directory @preserve */
+        }
+        catch {
+            // awaits dir may not exist yet — skip watching silently
+        }
+        /* v8 ignore stop */
+    }
+    stopWatching() {
+        if (this.debounceTimer !== null) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        if (this.watcher !== null) {
+            this.watcher.close();
+            this.watcher = null;
+        }
+    }
+    static DEFAULT_PERIODIC_INTERVAL_MS = 300_000;
+    static INITIAL_RECONCILIATION_DELAY_MS = 30_000;
+    startPeriodicReconciliation(intervalMs) {
+        const interval = intervalMs ?? AwaitScheduler.DEFAULT_PERIODIC_INTERVAL_MS;
+        this.periodicTimer = setTimeout(() => {
+            this.reconcile();
+            this.scheduleNextReconciliation(interval);
+        }, AwaitScheduler.INITIAL_RECONCILIATION_DELAY_MS);
+    }
+    stopPeriodicReconciliation() {
+        if (this.periodicTimer !== null) {
+            clearTimeout(this.periodicTimer);
+            this.periodicTimer = null;
+        }
+    }
+    scheduleNextReconciliation(intervalMs) {
+        this.periodicTimer = setTimeout(() => {
+            this.reconcile();
+            this.scheduleNextReconciliation(intervalMs);
+        }, intervalMs);
+    }
+    fireOverdueAwaits(awaits) {
+        for (const a of awaits) {
+            if (!a.cadence)
+                continue;
+            const cadenceMs = (0, cadence_1.parseCadenceToMs)(a.cadence);
+            if (cadenceMs === null)
+                continue;
+            const nowMs = this.deps.now();
+            const lastChecked = a.last_checked ?? null;
+            if (lastChecked === null) {
+                // A package-managed (system) await that was never checked is not overdue until one cadence has passed since it was created: a daemon restart
+                // (every upgrade) must not fire it at once. Awaits filed at runtime keep firing straight away. Without a readable created_at it fires as before.
+                const createdMs = a.created_at ? new Date(a.created_at).getTime() : Number.NaN;
+                if (isSystemAwait(a) && Number.isFinite(createdMs) && nowMs - createdMs < cadenceMs)
+                    continue;
+                (0, runtime_1.emitNervesEvent)({
+                    component: "daemon",
+                    event: "daemon.await_fire",
+                    message: "firing overdue await (never checked)",
+                    meta: { awaitName: a.name, agent: this.agent },
+                });
+                this.onAwaitFire(a.name);
+                continue;
+            }
+            const lastCheckedMs = new Date(lastChecked).getTime();
+            const elapsed = nowMs - lastCheckedMs;
+            if (elapsed >= cadenceMs) {
+                (0, runtime_1.emitNervesEvent)({
+                    component: "daemon",
+                    event: "daemon.await_fire",
+                    message: "firing overdue await",
+                    meta: { awaitName: a.name, agent: this.agent, elapsedMs: elapsed },
+                });
+                this.onAwaitFire(a.name);
+            }
+        }
+    }
+    isExpiredByMaxAge(a) {
+        if (a.status !== "pending")
+            return false;
+        if (!a.max_age || !a.created_at)
+            return false;
+        const ageMs = (0, cadence_1.parseCadenceToMs)(a.max_age);
+        if (ageMs === null)
+            return false;
+        const createdMs = new Date(a.created_at).getTime();
+        if (!Number.isFinite(createdMs))
+            return false;
+        return this.deps.now() - createdMs >= ageMs;
+    }
+    expireOverdueByMaxAge(awaits) {
+        for (const a of awaits) {
+            if (this.isExpiredByMaxAge(a)) {
+                (0, runtime_1.emitNervesEvent)({
+                    component: "daemon",
+                    event: "daemon.await_expire",
+                    message: "await max_age elapsed; expiring",
+                    meta: { awaitName: a.name, agent: this.agent, max_age: a.max_age, created_at: a.created_at },
+                });
+                this.onAwaitExpire(a.name);
+            }
+        }
+    }
+    verifyCronAndCreateFallbacks(jobs) {
+        if (!this.execForVerify && !this.verifyJobs)
+            return;
+        const verifiedLabels = this.verifyJobs?.(jobs)
+            ? new Set(jobs.map((job) => this.platform === "darwin" ? `bot.ouro.${job.agent}.${job.taskId}` : job.taskId.replace(/^await\./u, "")))
+            : this.execForVerify ? this.verifyCronEntries() : new Set();
+        for (const job of jobs) {
+            // job.taskId is already namespaced as "await.<name>". The bare name is
+            // what we pass to `--await` and what shows up in the crontab regex
+            // capture, so we strip the prefix for linux verification.
+            /* v8 ignore start -- defensive: buildJobs always namespaces taskId @preserve */
+            const bareName = job.taskId.startsWith(`${exports.AWAIT_CRON_LABEL_PREFIX_MARKER}.`)
+                ? job.taskId.slice(exports.AWAIT_CRON_LABEL_PREFIX_MARKER.length + 1)
+                : job.taskId;
+            /* v8 ignore stop */
+            const label = `bot.ouro.${job.agent}.${job.taskId}`;
+            const isVerified = this.platform === "darwin"
+                ? verifiedLabels.has(label)
+                : verifiedLabels.has(bareName);
+            if (!isVerified) {
+                (0, runtime_1.emitNervesEvent)({
+                    component: "daemon",
+                    event: "daemon.await_cron_verification_failed",
+                    message: `cron verification failed for await: ${bareName}`,
+                    meta: { awaitName: bareName, agent: job.agent, label },
+                });
+                const awaitFile = this.getAwaitFile(bareName);
+                const ms = awaitFile?.cadence ? (0, cadence_1.parseCadenceToMs)(awaitFile.cadence) : null;
+                if (ms !== null)
+                    this.createTimerFallback(bareName, ms);
+                this.degradedAwaitNames.set(bareName, "cron registration failed — using timer fallback");
+            }
+        }
+    }
+    verifyCronEntries() {
+        const verified = new Set();
+        try {
+            if (this.platform === "darwin") {
+                const output = this.execForVerify("launchctl list");
+                const lines = output.split("\n");
+                for (const line of lines) {
+                    const match = line.match(/bot\.ouro\.\S+\.await\.\S+/);
+                    if (match)
+                        verified.add(match[0]);
+                }
+            }
+            else {
+                const output = this.execForVerify("crontab -l");
+                const lines = output.split("\n");
+                for (const line of lines) {
+                    const match = line.match(/ouro poke \S+ --await (\S+)/);
+                    if (match)
+                        verified.add(match[1]);
+                }
+            }
+        }
+        catch {
+            // best-effort
+        }
+        return verified;
+    }
+    createTimerFallback(awaitName, cadenceMs) {
+        const schedule = () => {
+            const timer = setTimeout(() => {
+                this.onAwaitFire(awaitName);
+                schedule();
+            }, cadenceMs);
+            this.timerFallbacks.set(awaitName, timer);
+        };
+        schedule();
+    }
+    clearAllTimerFallbacks() {
+        for (const timer of this.timerFallbacks.values())
+            clearTimeout(timer);
+        this.timerFallbacks.clear();
+        this.degradedAwaitNames.clear();
+    }
+    scanAwaits() {
+        let files;
+        try {
+            files = this.deps.readdir(this.awaitsDir);
+        }
+        catch {
+            this.parseErrors = [];
+            return [];
+        }
+        const awaits = [];
+        const errors = [];
+        for (const file of files) {
+            if (!file.endsWith(".md"))
+                continue;
+            const filePath = path.join(this.awaitsDir, file);
+            try {
+                const content = this.deps.readFile(filePath, "utf-8");
+                const a = (0, await_runtime_state_1.applyAwaitRuntimeState)(path.dirname(this.awaitsDir), (0, await_parser_1.parseAwaitFile)(content, filePath));
+                awaits.push(a);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                errors.push({ file, error: errorMessage });
+                (0, runtime_1.emitNervesEvent)({
+                    level: "error",
+                    component: "daemon",
+                    event: "daemon.await_parse_error",
+                    message: "failed to parse await file",
+                    meta: { file, error: errorMessage, agent: this.agent },
+                });
+            }
+        }
+        this.parseErrors = errors;
+        return awaits;
+    }
+    buildJobs(awaits) {
+        const jobs = [];
+        for (const a of awaits) {
+            /* v8 ignore next -- defensive: callers (start/reconcile) pre-filter to pending awaits @preserve */
+            if (a.status !== "pending")
+                continue;
+            if (!a.cadence)
+                continue;
+            const cronSchedule = (0, cadence_1.parseCadenceToCron)(a.cadence);
+            if (cronSchedule === null)
+                continue;
+            jobs.push({
+                id: `${this.agent}:${exports.AWAIT_CRON_LABEL_PREFIX_MARKER}.${a.name}:cadence`,
+                agent: this.agent,
+                taskId: `${exports.AWAIT_CRON_LABEL_PREFIX_MARKER}.${a.name}`,
+                schedule: cronSchedule,
+                lastRun: a.last_checked ?? null,
+                command: `${this.deps.ouroPath} poke ${this.agent} --await ${a.name}`,
+                taskPath: path.join(this.awaitsDir, `${a.name}.md`),
+            });
+        }
+        return jobs;
+    }
+}
+exports.AwaitScheduler = AwaitScheduler;

package/dist/heart/background-operations.js

@@ -0,0 +1,281 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readBackgroundOperation = readBackgroundOperation;
+exports.listBackgroundOperations = listBackgroundOperations;
+exports.startBackgroundOperation = startBackgroundOperation;
+exports.markBackgroundOperationRunning = markBackgroundOperationRunning;
+exports.updateBackgroundOperation = updateBackgroundOperation;
+exports.completeBackgroundOperation = completeBackgroundOperation;
+exports.failBackgroundOperation = failBackgroundOperation;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../nerves/runtime");
+const identity_1 = require("./identity");
+function operationsDir(agentName, agentRoot = (0, identity_1.getAgentRoot)(agentName)) {
+    return path.join(agentRoot, "state", "background-operations");
+}
+function operationPath(locator) {
+    return path.join(operationsDir(locator.agentName, locator.agentRoot), `${locator.id}.json`);
+}
+function normalizeProgress(progress) {
+    if (!progress)
+        return undefined;
+    const normalized = {};
+    if (typeof progress.current === "number" && Number.isFinite(progress.current))
+        normalized.current = progress.current;
+    if (typeof progress.total === "number" && Number.isFinite(progress.total))
+        normalized.total = progress.total;
+    if (typeof progress.unit === "string" && progress.unit.trim().length > 0)
+        normalized.unit = progress.unit.trim();
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+function normalizeRecord(record) {
+    if (record.schemaVersion !== 1)
+        return null;
+    if (typeof record.id !== "string" || record.id.trim().length === 0)
+        return null;
+    if (typeof record.agentName !== "string" || record.agentName.trim().length === 0)
+        return null;
+    if (typeof record.kind !== "string" || record.kind.trim().length === 0)
+        return null;
+    if (typeof record.title !== "string" || record.title.trim().length === 0)
+        return null;
+    if (typeof record.summary !== "string" || record.summary.trim().length === 0)
+        return null;
+    if (typeof record.createdAt !== "string" || record.createdAt.trim().length === 0)
+        return null;
+    if (typeof record.updatedAt !== "string" || record.updatedAt.trim().length === 0)
+        return null;
+    if (record.status !== "queued"
+        && record.status !== "running"
+        && record.status !== "succeeded"
+        && record.status !== "failed") {
+        return null;
+    }
+    const normalized = {
+        schemaVersion: 1,
+        id: record.id,
+        agentName: record.agentName,
+        kind: record.kind,
+        title: record.title,
+        status: record.status,
+        summary: record.summary,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+    };
+    if (typeof record.detail === "string" && record.detail.trim().length > 0)
+        normalized.detail = record.detail.trim();
+    if (typeof record.startedAt === "string" && record.startedAt.trim().length > 0)
+        normalized.startedAt = record.startedAt;
+    if (typeof record.finishedAt === "string" && record.finishedAt.trim().length > 0)
+        normalized.finishedAt = record.finishedAt;
+    const progress = normalizeProgress(record.progress);
+    if (progress)
+        normalized.progress = progress;
+    if (record.spec && typeof record.spec === "object" && !Array.isArray(record.spec))
+        normalized.spec = { ...record.spec };
+    if (record.result && typeof record.result === "object" && !Array.isArray(record.result))
+        normalized.result = { ...record.result };
+    if (record.error && typeof record.error.message === "string" && record.error.message.trim().length > 0) {
+        normalized.error = { message: record.error.message.trim() };
+    }
+    if (record.failure && typeof record.failure === "object" && !Array.isArray(record.failure)) {
+        const failureClass = typeof record.failure.class === "string" ? record.failure.class.trim() : "";
+        const retryDisposition = record.failure.retryDisposition;
+        const hint = typeof record.failure.hint === "string" ? record.failure.hint.trim() : "";
+        if (failureClass) {
+            normalized.failure = {
+                class: failureClass,
+                ...(retryDisposition === "retry-safe" || retryDisposition === "fix-before-retry" || retryDisposition === "investigate-first"
+                    ? { retryDisposition }
+                    : {}),
+                ...(hint ? { hint } : {}),
+            };
+        }
+    }
+    if (Array.isArray(record.remediation)) {
+        const remediation = record.remediation.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+        if (remediation.length > 0)
+            normalized.remediation = remediation;
+    }
+    return normalized;
+}
+function readRecord(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        return normalizeRecord(parsed);
+    }
+    catch {
+        return null;
+    }
+}
+function specText(spec, key) {
+    const value = spec?.[key];
+    return typeof value === "string" ? value.trim() : "";
+}
+function visibleOperationKey(record) {
+    if (record.kind !== "mail.import-mbox")
+        return null;
+    const filePath = specText(record.spec, "filePath");
+    if (!filePath)
+        return null;
+    const ownerEmail = specText(record.spec, "ownerEmail").toLowerCase();
+    const source = specText(record.spec, "source").toLowerCase();
+    return `${record.agentName.toLowerCase()}|${record.kind}|${filePath}|${ownerEmail}|${source}`;
+}
+function writeRecord(locator, record) {
+    const normalized = normalizeRecord(record);
+    if (!normalized) {
+        throw new Error(`invalid background operation record: ${locator.id}`);
+    }
+    fs.mkdirSync(operationsDir(locator.agentName, locator.agentRoot), { recursive: true });
+    fs.writeFileSync(operationPath(locator), `${JSON.stringify(normalized, null, 2)}\n`, "utf-8");
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.background_operation_written",
+        message: "background operation state written",
+        meta: { agentName: locator.agentName, id: locator.id, kind: normalized.kind, status: normalized.status },
+    });
+    return normalized;
+}
+function requireRecord(locator) {
+    const record = readBackgroundOperation(locator);
+    if (!record) {
+        throw new Error(`background operation not found: ${locator.id}`);
+    }
+    return record;
+}
+function readBackgroundOperation(locator) {
+    return readRecord(operationPath(locator));
+}
+function listBackgroundOperations(input) {
+    const dir = operationsDir(input.agentName, input.agentRoot);
+    if (!fs.existsSync(dir))
+        return [];
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const records = entries
+        .filter((entry) => entry.endsWith(".json"))
+        .map((entry) => readRecord(path.join(dir, entry)))
+        .filter((entry) => entry !== null)
+        .sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt));
+    const visibleKeys = new Set();
+    const visible = records.filter((record) => {
+        const key = visibleOperationKey(record);
+        if (!key)
+            return true;
+        if (visibleKeys.has(key))
+            return false;
+        visibleKeys.add(key);
+        return true;
+    });
+    return visible.slice(0, input.limit ?? 10);
+}
+function startBackgroundOperation(input) {
+    return writeRecord(input, {
+        schemaVersion: 1,
+        id: input.id,
+        agentName: input.agentName,
+        kind: input.kind,
+        title: input.title,
+        status: "queued",
+        summary: input.summary,
+        createdAt: input.createdAt,
+        updatedAt: input.createdAt,
+        ...(input.spec ? { spec: input.spec } : {}),
+    });
+}
+function markBackgroundOperationRunning(input) {
+    const current = requireRecord(input);
+    const updatedAt = input.updatedAt ?? input.startedAt;
+    return writeRecord(input, {
+        ...current,
+        status: "running",
+        summary: input.summary ?? current.summary,
+        ...(input.detail ? { detail: input.detail } : {}),
+        ...(normalizeProgress(input.progress) ? { progress: normalizeProgress(input.progress) } : {}),
+        startedAt: input.startedAt,
+        updatedAt,
+        ...(current.finishedAt ? { finishedAt: current.finishedAt } : {}),
+    });
+}
+function updateBackgroundOperation(input) {
+    const current = requireRecord(input);
+    return writeRecord(input, {
+        ...current,
+        summary: input.summary ?? current.summary,
+        ...(input.detail ? { detail: input.detail } : {}),
+        ...(normalizeProgress(input.progress) ? { progress: normalizeProgress(input.progress) } : {}),
+        ...(input.spec ? { spec: input.spec } : {}),
+        updatedAt: input.updatedAt ?? current.updatedAt,
+    });
+}
+function completeBackgroundOperation(input) {
+    const current = requireRecord(input);
+    return writeRecord(input, {
+        ...current,
+        status: "succeeded",
+        summary: input.summary ?? current.summary,
+        ...(input.detail ? { detail: input.detail } : {}),
+        ...(normalizeProgress(input.progress) ? { progress: normalizeProgress(input.progress) } : {}),
+        ...(input.result ? { result: input.result } : {}),
+        error: undefined,
+        remediation: undefined,
+        failure: undefined,
+        finishedAt: input.finishedAt,
+        updatedAt: input.updatedAt ?? input.finishedAt,
+    });
+}
+function failBackgroundOperation(input) {
+    const current = requireRecord(input);
+    return writeRecord(input, {
+        ...current,
+        status: "failed",
+        summary: input.summary ?? current.summary,
+        ...(input.detail ? { detail: input.detail } : {}),
+        ...(normalizeProgress(input.progress) ? { progress: normalizeProgress(input.progress) } : {}),
+        error: { message: input.error },
+        ...(input.failure ? { failure: input.failure } : {}),
+        ...(input.remediation && input.remediation.length > 0 ? { remediation: input.remediation } : {}),
+        finishedAt: input.finishedAt,
+        updatedAt: input.updatedAt ?? input.finishedAt,
+    });
+}