open-multi-agent-kit 0.78.0

package/dist/util/checkpoint.js

@@ -0,0 +1,238 @@
+import { mkdir, writeFile, readFile, readdir } from "fs/promises";
+import { isAbsolute, join, normalize } from "path";
+import { runShell } from "./shell.js";
+import { redactSecrets } from "../orchestration/state-persister.js";
+import { getProjectRoot, pathExists, readTextFile } from "./fs.js";
+import { validateRunId } from "./run-store.js";
+const CHECKPOINTS_DIR = ".omk/checkpoints";
+const PROTECTED_CHECKPOINT_PATH_MARKERS = [
+    ".env",
+    ".pem",
+    ".key",
+    "id_rsa",
+    "id_ed25519",
+    "credentials.json",
+    "service-account",
+    ".p12",
+    ".pfx",
+    ".keystore",
+];
+function sanitizeLabel(label) {
+    return label.replace(/[^a-zA-Z0-9_-]/g, "_").substring(0, 64);
+}
+function getCheckpointsBasePath() {
+    return join(getProjectRoot(), CHECKPOINTS_DIR);
+}
+function getCheckpointPath(runId, checkpointId) {
+    return join(getCheckpointsBasePath(), validateRunId(runId), sanitizeLabel(checkpointId));
+}
+function getRunPath(runId) {
+    return join(getProjectRoot(), ".omk", "runs", validateRunId(runId));
+}
+function sanitizeJsonText(content) {
+    try {
+        return JSON.stringify(redactSecrets(JSON.parse(content)), null, 2);
+    }
+    catch {
+        return String(redactSecrets(content));
+    }
+}
+function normalizePatchPath(pathValue) {
+    return normalize(pathValue.replace(/^"?[ab]\//, "").replace(/"?$/, ""));
+}
+function protectedPatchPathReason(pathValue) {
+    const normalized = normalizePatchPath(pathValue);
+    if (!normalized || normalized === "/dev/null")
+        return null;
+    if (isAbsolute(normalized) || normalized.startsWith(".."))
+        return `unsafe checkpoint path: ${pathValue}`;
+    const lower = normalized.toLowerCase();
+    const base = lower.split(/[\\/]/).pop() ?? lower;
+    if (PROTECTED_CHECKPOINT_PATH_MARKERS.some((marker) => lower.includes(marker) || base === marker)) {
+        return `protected checkpoint path: ${pathValue}`;
+    }
+    return null;
+}
+function validateCheckpointPatchPaths(patchContent) {
+    for (const line of patchContent.split(/\r?\n/)) {
+        let candidate = null;
+        if (line.startsWith("diff --git ")) {
+            const parts = line.split(/\s+/);
+            candidate = parts[2] ?? parts[3] ?? null;
+        }
+        else if (line.startsWith("+++ ") || line.startsWith("--- ")) {
+            candidate = line.slice(4).trim();
+        }
+        if (!candidate || candidate === "/dev/null")
+            continue;
+        const reason = protectedPatchPathReason(candidate);
+        if (reason)
+            return reason;
+    }
+    return null;
+}
+export async function saveCheckpoint(runId, label, metadata) {
+    const timestamp = new Date().toISOString().replace(/:/g, "-");
+    const checkpointId = `${sanitizeLabel(label)}-${timestamp}`;
+    const cpPath = getCheckpointPath(runId, checkpointId);
+    await mkdir(cpPath, { recursive: true });
+    const meta = redactSecrets({
+        timestamp: new Date().toISOString(),
+        label,
+        runId,
+        ...(metadata ?? {}),
+    });
+    await writeFile(join(cpPath, "metadata.json"), JSON.stringify(meta, null, 2), "utf-8");
+    const projectRoot = getProjectRoot();
+    const gitDiffResult = await runShell("git", ["diff", "HEAD"], { cwd: projectRoot, timeout: 10000 });
+    const patchContent = !gitDiffResult.failed ? gitDiffResult.stdout : "";
+    await writeFile(join(cpPath, "git-patch.diff"), patchContent, "utf-8");
+    const runDir = getRunPath(runId);
+    const todosPath = join(runDir, "todos.json");
+    if (await pathExists(todosPath)) {
+        const todosContent = await readFile(todosPath, "utf-8");
+        await writeFile(join(cpPath, "todos.json"), sanitizeJsonText(todosContent), "utf-8");
+    }
+    const statePath = join(runDir, "state.json");
+    if (await pathExists(statePath)) {
+        const stateContent = await readFile(statePath, "utf-8");
+        await writeFile(join(cpPath, "state.json"), sanitizeJsonText(stateContent), "utf-8");
+    }
+    return { checkpointId, path: cpPath };
+}
+export async function listCheckpoints(runId) {
+    const basePath = getCheckpointsBasePath();
+    if (!(await pathExists(basePath)))
+        return [];
+    const results = [];
+    const runDirs = await readdir(basePath, { withFileTypes: true });
+    for (const runDir of runDirs) {
+        if (!runDir.isDirectory())
+            continue;
+        const currentRunId = runDir.name;
+        if (runId && currentRunId !== runId)
+            continue;
+        const runPath = join(basePath, currentRunId);
+        const cpDirs = await readdir(runPath, { withFileTypes: true });
+        for (const cpDir of cpDirs) {
+            if (!cpDir.isDirectory())
+                continue;
+            const checkpointId = cpDir.name;
+            const metaPath = join(runPath, checkpointId, "metadata.json");
+            if (!(await pathExists(metaPath)))
+                continue;
+            try {
+                const metaContent = await readFile(metaPath, "utf-8");
+                const meta = JSON.parse(metaContent);
+                results.push({
+                    checkpointId,
+                    runId: currentRunId,
+                    label: meta.label ?? checkpointId,
+                    createdAt: meta.timestamp ?? "",
+                });
+            }
+            catch {
+                // skip malformed metadata
+            }
+        }
+    }
+    return results.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+export async function restoreCheckpoint(checkpointId, runId, options = {}) {
+    const cpPath = getCheckpointPath(runId, checkpointId);
+    const projectRoot = getProjectRoot();
+    const restoredFiles = [];
+    if (!(await pathExists(cpPath))) {
+        return { success: false, restoredFiles, message: `Checkpoint not found: ${cpPath}` };
+    }
+    const patchPath = join(cpPath, "git-patch.diff");
+    const patchContent = await readTextFile(patchPath, "");
+    if (patchContent.trim().length > 0) {
+        const unsafePatchPath = validateCheckpointPatchPaths(patchContent);
+        if (unsafePatchPath) {
+            return {
+                success: false,
+                restoredFiles,
+                message: `Checkpoint restore refused: ${unsafePatchPath}`,
+            };
+        }
+        const dirtyCheck = await runShell("git", ["status", "--porcelain", "--untracked-files=normal"], {
+            cwd: projectRoot,
+            timeout: 10000,
+        });
+        if (!options.force && !dirtyCheck.failed && dirtyCheck.stdout.trim().length > 0) {
+            return {
+                success: false,
+                restoredFiles,
+                message: "Checkpoint restore refused: dirty worktree. Re-run with force after reviewing local changes.",
+            };
+        }
+        const gitApplyCheck = await runShell("git", ["apply", "--check", patchPath], {
+            cwd: projectRoot,
+            timeout: 10000,
+        });
+        if (!gitApplyCheck.failed) {
+            const gitApply = await runShell("git", ["apply", patchPath], {
+                cwd: projectRoot,
+                timeout: 10000,
+            });
+            if (gitApply.failed) {
+                return {
+                    success: false,
+                    restoredFiles,
+                    message: `Git apply failed: ${gitApply.stderr}`,
+                };
+            }
+            restoredFiles.push("git-patch.diff (applied)");
+        }
+        else {
+            const patchCheck = await runShell("patch", ["-p1", "--dry-run", "-i", patchPath], {
+                cwd: projectRoot,
+                timeout: 10000,
+            });
+            if (!patchCheck.failed) {
+                const patchApply = await runShell("patch", ["-p1", "-i", patchPath], {
+                    cwd: projectRoot,
+                    timeout: 10000,
+                });
+                if (patchApply.failed) {
+                    return {
+                        success: false,
+                        restoredFiles,
+                        message: `patch command failed: ${patchApply.stderr}`,
+                    };
+                }
+                restoredFiles.push("git-patch.diff (applied via patch)");
+            }
+            else {
+                return {
+                    success: false,
+                    restoredFiles,
+                    message: `Patch cannot be applied: ${gitApplyCheck.stderr || patchCheck.stderr}`,
+                };
+            }
+        }
+    }
+    const runDir = getRunPath(runId);
+    const todosCpPath = join(cpPath, "todos.json");
+    if (await pathExists(todosCpPath)) {
+        const todosContent = await readFile(todosCpPath, "utf-8");
+        const todosRunPath = join(runDir, "todos.json");
+        await mkdir(runDir, { recursive: true });
+        await writeFile(todosRunPath, sanitizeJsonText(todosContent), "utf-8");
+        restoredFiles.push("todos.json");
+    }
+    const stateCpPath = join(cpPath, "state.json");
+    if (await pathExists(stateCpPath)) {
+        const stateContent = await readFile(stateCpPath, "utf-8");
+        const stateRunPath = join(runDir, "state.json");
+        await mkdir(runDir, { recursive: true });
+        await writeFile(stateRunPath, sanitizeJsonText(stateContent), "utf-8");
+        restoredFiles.push("state.json");
+    }
+    return {
+        success: true,
+        restoredFiles,
+        message: `Restored ${restoredFiles.length} items from checkpoint ${checkpointId}`,
+    };
+}

package/dist/util/cli-contract.d.ts

@@ -0,0 +1,46 @@
+/**
+ * CLI Contract helpers — enforce JSON-mode stdout purity and typed command results.
+ *
+ * Rules:
+ * - --json → stdout is exactly one JSON document, no banners/ANSI/human text.
+ * - Human diagnostics go to stderr only.
+ * - Command functions must NOT call process.exit; they throw CliError or return CommandResult.
+ * - Only src/cli.ts adapters set process.exitCode.
+ */
+export interface CommandResult<T = void> {
+    ok: boolean;
+    exitCode: number;
+    data?: T;
+    diagnostics?: string[];
+}
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    readonly diagnostics?: string[] | undefined;
+    constructor(message: string, exitCode?: number, diagnostics?: string[] | undefined);
+}
+export declare class UsageError extends CliError {
+    constructor(message: string, diagnostics?: string[]);
+}
+export declare class NotFoundError extends CliError {
+    constructor(message: string, diagnostics?: string[]);
+}
+export declare class VerificationError extends CliError {
+    constructor(message: string, diagnostics?: string[]);
+}
+export declare class InterruptedError extends CliError {
+    constructor(message?: string);
+}
+/** Emit a single JSON document to stdout. */
+export declare function emitJson(data: unknown): void;
+/** Emit error: JSON to stdout (in JSON mode), human text to stderr (always). */
+export declare function emitError(message: string, json: boolean, jsonPayload?: Record<string, unknown>): void;
+/** Build a successful CommandResult. */
+export declare function successResult<T>(data?: T): CommandResult<T>;
+/** Build a failed CommandResult. */
+export declare function failureResult(exitCode: number, diagnostics?: string[]): CommandResult;
+/** Adapter: convert a CommandResult to CLI exit code. Does NOT call process.exit. */
+export declare function applyExitCode(result: CommandResult): void;
+/** Returns true when stdout should be JSON-only (no ANSI, no human text). */
+export declare function isJsonMode(options: {
+    json?: boolean;
+}): boolean;

package/dist/util/cli-contract.js

@@ -0,0 +1,72 @@
+/**
+ * CLI Contract helpers — enforce JSON-mode stdout purity and typed command results.
+ *
+ * Rules:
+ * - --json → stdout is exactly one JSON document, no banners/ANSI/human text.
+ * - Human diagnostics go to stderr only.
+ * - Command functions must NOT call process.exit; they throw CliError or return CommandResult.
+ * - Only src/cli.ts adapters set process.exitCode.
+ */
+export class CliError extends Error {
+    exitCode;
+    diagnostics;
+    constructor(message, exitCode = 1, diagnostics) {
+        super(message);
+        this.exitCode = exitCode;
+        this.diagnostics = diagnostics;
+        this.name = "CliError";
+    }
+}
+export class UsageError extends CliError {
+    constructor(message, diagnostics) {
+        super(message, 1, diagnostics);
+        this.name = "UsageError";
+    }
+}
+export class NotFoundError extends CliError {
+    constructor(message, diagnostics) {
+        super(message, 1, diagnostics);
+        this.name = "NotFoundError";
+    }
+}
+export class VerificationError extends CliError {
+    constructor(message, diagnostics) {
+        super(message, 1, diagnostics);
+        this.name = "VerificationError";
+    }
+}
+export class InterruptedError extends CliError {
+    constructor(message = "Interrupted") {
+        super(message, 130);
+        this.name = "InterruptedError";
+    }
+}
+/** Emit a single JSON document to stdout. */
+export function emitJson(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+/** Emit error: JSON to stdout (in JSON mode), human text to stderr (always). */
+export function emitError(message, json, jsonPayload) {
+    if (json) {
+        console.log(JSON.stringify({ error: message, ...jsonPayload }, null, 2));
+    }
+    console.error(message);
+}
+/** Build a successful CommandResult. */
+export function successResult(data) {
+    return { ok: true, exitCode: 0, data };
+}
+/** Build a failed CommandResult. */
+export function failureResult(exitCode, diagnostics) {
+    return { ok: false, exitCode, diagnostics };
+}
+/** Adapter: convert a CommandResult to CLI exit code. Does NOT call process.exit. */
+export function applyExitCode(result) {
+    if (!result.ok && process.exitCode === undefined) {
+        process.exitCode = result.exitCode;
+    }
+}
+/** Returns true when stdout should be JSON-only (no ANSI, no human text). */
+export function isJsonMode(options) {
+    return Boolean(options.json);
+}

package/dist/util/cron-engine.d.ts

@@ -0,0 +1,24 @@
+import type { CronJob, CronRun } from "../contracts/orchestration.js";
+export type CronTickHandler = (job: CronJob) => Promise<void>;
+export interface CronEngine {
+    start(): void;
+    stop(): void;
+    listJobs(): CronJob[];
+    runJobNow(name: string): Promise<CronRun | null>;
+    getRuns(jobName: string): Promise<CronRun[]>;
+    enableJob(name: string): void;
+    disableJob(name: string): void;
+}
+export interface CronEngineOptions {
+    jobs?: CronJob[];
+}
+export declare function loadCronJobs(): Promise<CronJob[]>;
+export declare function mergeCronRuntimeState(loadedJobs: CronJob[], previousJobs: CronJob[], now?: number): CronJob[];
+export declare function createCronEngine(handler: CronTickHandler, options?: CronEngineOptions): CronEngine;
+export declare function validateCronJobName(name: string): string;
+/**
+ * Compute the next run time given a schedule expression.
+ * Supports: standard cron 5-field, @yearly, @monthly, @weekly, @daily, @hourly,
+ * and @every <duration> (e.g., @every 1m, @every 30m, @every 1h).
+ */
+export declare function computeNextRun(schedule: string, lastRunAt?: string, catchup?: boolean): string;

package/dist/util/cron-engine.js

@@ -0,0 +1,227 @@
+import { readFile, mkdir, readdir, writeFile } from "fs/promises";
+import { join } from "path";
+import { getProjectRoot, pathExists } from "./fs.js";
+const TICK_INTERVAL_MS = 15_000; // Check every 15 seconds
+const CRON_CONFIG_PATH = ".omk/cron.yml";
+const CRON_RUNS_DIR = ".omk/cron-runs";
+function normalizeJob(j, index) {
+    return {
+        name: j.name ?? `job-${index}`,
+        schedule: j.schedule ?? "@daily",
+        dagFile: j.dagFile ?? "",
+        concurrencyPolicy: j.concurrencyPolicy ?? "forbid",
+        enabled: j.enabled !== false,
+        catchup: j.catchup === true,
+        timeoutPreset: j.timeoutPreset,
+        lastRunAt: j.lastRunAt,
+        nextRunAt: j.nextRunAt,
+    };
+}
+export async function loadCronJobs() {
+    const root = getProjectRoot();
+    const configPath = join(root, CRON_CONFIG_PATH);
+    if (!(await pathExists(configPath)))
+        return [];
+    try {
+        const content = await readFile(configPath, "utf-8");
+        const yaml = await import("yaml");
+        const doc = yaml.parse(content);
+        if (!doc?.jobs)
+            return [];
+        return doc.jobs.map((j, index) => normalizeJob(j, index));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to load cron config ${configPath}: ${message}`);
+    }
+}
+export function mergeCronRuntimeState(loadedJobs, previousJobs, now = Date.now()) {
+    const previousByName = new Map(previousJobs.map((job) => [job.name, job]));
+    return loadedJobs.map((loaded, index) => {
+        const previous = previousByName.get(loaded.name);
+        const job = normalizeJob({
+            ...loaded,
+            lastRunAt: loaded.lastRunAt ?? previous?.lastRunAt,
+            nextRunAt: loaded.nextRunAt ?? previous?.nextRunAt,
+        }, index);
+        if (!job.nextRunAt && job.enabled) {
+            job.nextRunAt = computeNextRun(job.schedule, job.lastRunAt, job.catchup);
+        }
+        // If catchup is disabled and we missed the window, skip to next.
+        if (!job.catchup && job.nextRunAt && Date.parse(job.nextRunAt) < now - TICK_INTERVAL_MS * 2) {
+            job.nextRunAt = computeNextRun(job.schedule, new Date(now).toISOString(), false);
+        }
+        return job;
+    });
+}
+export function createCronEngine(handler, options = {}) {
+    const state = {
+        jobs: (options.jobs ?? []).map((job, index) => normalizeJob(job, index)),
+        activeRuns: new Map(),
+        timer: null,
+        handler,
+    };
+    async function refreshJobs() {
+        state.jobs = mergeCronRuntimeState(await loadCronJobs(), state.jobs, Date.now());
+    }
+    async function tick() {
+        await refreshJobs();
+        const now = Date.now();
+        for (const job of state.jobs) {
+            if (!job.enabled)
+                continue;
+            if (!job.nextRunAt) {
+                job.nextRunAt = computeNextRun(job.schedule, job.lastRunAt, job.catchup);
+                continue;
+            }
+            if (Date.parse(job.nextRunAt) > now)
+                continue;
+            // Concurrency check
+            const active = state.activeRuns.get(job.name);
+            if (active) {
+                if (job.concurrencyPolicy === "forbid") {
+                    continue;
+                }
+                if (job.concurrencyPolicy === "replace") {
+                    // We can't truly cancel the promise, but we detach tracking
+                    state.activeRuns.delete(job.name);
+                }
+                // "allow" proceeds
+            }
+            const runPromise = executeJob(job).then(() => undefined);
+            state.activeRuns.set(job.name, runPromise);
+            runPromise.finally(() => {
+                if (state.activeRuns.get(job.name) === runPromise) {
+                    state.activeRuns.delete(job.name);
+                }
+            });
+            job.lastRunAt = new Date().toISOString();
+            job.nextRunAt = computeNextRun(job.schedule, job.lastRunAt, job.catchup);
+        }
+    }
+    async function executeJob(job) {
+        const safeName = validateCronJobName(job.name);
+        const runId = `${job.name}-${Date.now()}`;
+        const root = getProjectRoot();
+        const logDir = join(root, CRON_RUNS_DIR, safeName);
+        await mkdir(logDir, { recursive: true });
+        const logPath = join(logDir, `${new Date().toISOString().replace(/[:.]/g, "-")}.json`);
+        const cronRun = {
+            jobName: job.name,
+            startedAt: new Date().toISOString(),
+            success: false,
+            runId,
+            logPath,
+        };
+        try {
+            await state.handler(job);
+            cronRun.success = true;
+            cronRun.completedAt = new Date().toISOString();
+        }
+        catch (err) {
+            cronRun.success = false;
+            cronRun.error = err instanceof Error ? err.message : String(err);
+            cronRun.completedAt = new Date().toISOString();
+        }
+        await writeFile(logPath, JSON.stringify(cronRun, null, 2));
+        return cronRun;
+    }
+    return {
+        start() {
+            if (state.timer)
+                return;
+            void tick();
+            state.timer = setInterval(() => void tick(), TICK_INTERVAL_MS);
+        },
+        stop() {
+            if (state.timer) {
+                clearInterval(state.timer);
+                state.timer = null;
+            }
+        },
+        listJobs() {
+            return state.jobs.map((j) => ({ ...j }));
+        },
+        async runJobNow(name) {
+            const job = state.jobs.find((j) => j.name === name);
+            if (!job)
+                return null;
+            return executeJob(job);
+        },
+        async getRuns(jobName) {
+            const root = getProjectRoot();
+            const logDir = join(root, CRON_RUNS_DIR, validateCronJobName(jobName));
+            if (!(await pathExists(logDir)))
+                return [];
+            const files = await readdir(logDir).catch(() => []);
+            const runs = [];
+            for (const file of files.filter((f) => f.endsWith(".json"))) {
+                try {
+                    const content = await readFile(join(logDir, file), "utf-8");
+                    runs.push(JSON.parse(content));
+                }
+                catch {
+                    // ignore malformed
+                }
+            }
+            return runs.sort((a, b) => Date.parse(a.startedAt) - Date.parse(b.startedAt));
+        },
+        enableJob(name) {
+            const job = state.jobs.find((j) => j.name === name);
+            if (job)
+                job.enabled = true;
+        },
+        disableJob(name) {
+            const job = state.jobs.find((j) => j.name === name);
+            if (job)
+                job.enabled = false;
+        },
+    };
+}
+export function validateCronJobName(name) {
+    const trimmed = name.trim();
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(trimmed) || trimmed.includes("..")) {
+        throw new Error(`Invalid cron job name: ${name}`);
+    }
+    return trimmed;
+}
+/**
+ * Compute the next run time given a schedule expression.
+ * Supports: standard cron 5-field, @yearly, @monthly, @weekly, @daily, @hourly,
+ * and @every <duration> (e.g., @every 1m, @every 30m, @every 1h).
+ */
+export function computeNextRun(schedule, lastRunAt, catchup = false) {
+    const lastRun = lastRunAt ? Date.parse(lastRunAt) : Date.now();
+    const base = catchup ? lastRun : Math.max(lastRun, Date.now());
+    // @every duration
+    const everyMatch = schedule.match(/^@every\s+(\d+)([smhd])$/i);
+    if (everyMatch) {
+        const value = Number.parseInt(everyMatch[1], 10);
+        const unit = everyMatch[2].toLowerCase();
+        const ms = unit === "s" ? value * 1000 :
+            unit === "m" ? value * 60_000 :
+                unit === "h" ? value * 3600_000 :
+                    value * 86400_000;
+        return new Date(base + ms).toISOString();
+    }
+    // Named schedules
+    const now = new Date(base);
+    switch (schedule) {
+        case "@yearly":
+        case "@annually":
+            return new Date(now.getFullYear() + 1, 0, 1, 0, 0, 0, 0).toISOString();
+        case "@monthly":
+            return new Date(now.getFullYear(), now.getMonth() + 1, 1, 0, 0, 0, 0).toISOString();
+        case "@weekly":
+            return new Date(now.getFullYear(), now.getMonth(), now.getDate() + (7 - now.getDay()), 0, 0, 0, 0).toISOString();
+        case "@daily":
+        case "@midnight":
+            return new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1, 0, 0, 0, 0).toISOString();
+        case "@hourly":
+            return new Date(now.getFullYear(), now.getMonth(), now.getDate(), now.getHours() + 1, 0, 0, 0).toISOString();
+        default:
+            // Simple 5-field cron: attempt to advance by 1 minute for basic cases
+            // Full cron parser is out of scope; fallback to +1 hour for unrecognized
+            return new Date(base + 3600_000).toISOString();
+    }
+}

package/dist/util/events-logger.d.ts

@@ -0,0 +1,30 @@
+export type ReplayEventType = "replay-start" | "replay-end" | "node-start" | "node-complete" | "node-fallback" | "state-change";
+export type TelemetryEventType = ReplayEventType | "lane.started" | "lane.activity" | "lane.heartbeat" | "lane.completed" | "lane.failed" | "lane.stalled" | "agent.spawned" | "tool.started" | "tool.completed" | "mcp.started" | "mcp.completed" | "mcp.failed" | "hook.started" | "hook.completed" | "provider.route" | "provider.fallback" | "provider.request.started" | "provider.request.completed" | "provider.request.failed" | "provider.advisory.started" | "provider.advisory.completed" | "provider.advisory.failed" | "evidence.result";
+export interface TelemetryEvent {
+    schemaVersion: "telemetry.v1";
+    type: TelemetryEventType;
+    timestamp: string;
+    seq: number;
+    runId: string;
+    nodeId?: string;
+    laneId?: string;
+    agentId?: string;
+    toolName?: string;
+    provider?: string;
+    status?: string;
+    data?: Record<string, unknown>;
+}
+export type ReplayEvent = TelemetryEvent;
+export interface ReadEventsOptions {
+    afterSeq?: number;
+    limit?: number;
+}
+type EventInput = Omit<TelemetryEvent, "schemaVersion" | "timestamp" | "seq"> & {
+    schemaVersion?: "telemetry.v1";
+    timestamp?: string;
+    seq?: number;
+};
+export declare function appendEvent(runDir: string, event: EventInput): Promise<void>;
+export declare function readEvents(runDir: string): Promise<ReplayEvent[]>;
+export declare function tailEvents(runDir: string, options?: ReadEventsOptions): Promise<ReplayEvent[]>;
+export {};