@ashulab/carrier 0.0.0-stage → 0.1.0

package/dist/config/schema.js

@@ -0,0 +1,225 @@
+import { isAbsolute } from 'node:path';
+import { LogLevel } from '@ashulab/universal-logger';
+import { z } from 'zod';
+import { harnessNames, localProvidersOf } from '../harnesses/names.js';
+import { expandHome } from './default-path.js';
+import { resolveRepoConfig } from './resolve.js';
+/** `owner/name`, each part a plain folder name: the managed clone lives in `repos/<owner>/<name>`. */
+export const repoNamePattern = /^(?!\.{1,2}\/)(?!.*\/\.{1,2}$)[\w.-]+\/[\w.-]+$/;
+/** Who the agent of a role says it is: a one-line name (it ends up in GitHub text) and a prompt. A repo's persona replaces the global one whole. */
+export const persona = z.strictObject({
+    name: z.string().trim().min(1).max(40).regex(/^[^\r\n]+$/).optional(),
+    prompt: z.string().trim().min(1).max(4000).optional(),
+});
+/** An AI provider account / connection. */
+export const aiProvider = z.strictObject({
+    harness: z.enum(harnessNames),
+    /** Optional default model for this provider connection. */
+    model: z.string().min(1).optional(),
+    /** Run on a local server through the harness's CLI instead of the cloud. */
+    provider: z.enum(['lmstudio', 'ollama']).optional(),
+    /** `CLAUDE_CONFIG_DIR` for Claude, `CODEX_HOME` for Codex. Absolute once `~` is expanded. */
+    configDir: z.string().min(1).transform(expandHome).optional(),
+});
+/** The key of a provider or option: stored and shown as is. */
+export const optionNamePattern = /^[a-z][a-z0-9-]{0,39}$/;
+// A role keeps its GitHub identity and persona, and points at an AI provider and model.
+const agent = z.strictObject({
+    persona: persona.optional(),
+    profile: z.string().min(1),
+    provider: z.string().min(1),
+    model: z.string().min(1),
+});
+// The two shapes the spike fixed (docs/research/agent-forge.md): a bot through Agent Forge, or the user's own `gh` login. No secrets here.
+const profile = z.discriminatedUnion('kind', [
+    z.strictObject({ kind: z.literal('forge'), agent: z.string().min(1) }),
+    z.strictObject({ kind: z.literal('gh') }),
+]);
+export const failoverTriggers = ['usage_limit', 'rate_limit', 'service_down'];
+export function matchesFailoverTrigger(triggers, failureKind, failureDetail) {
+    if (!failureKind)
+        return false;
+    if (triggers.includes('usage_limit') && failureKind === 'usage_limit')
+        return true;
+    const isRateLimit = failureKind === 'api_error' && (failureDetail?.includes('429') || /rate[-_ ]?limit|overloaded/i.test(failureDetail ?? ''));
+    if (triggers.includes('rate_limit') && isRateLimit)
+        return true;
+    if (triggers.includes('service_down') && (failureKind === 'spawn_error' || (failureKind === 'api_error' && !isRateLimit)))
+        return true;
+    return false;
+}
+const failoverSchema = z.strictObject({
+    enabled: z.boolean(),
+    triggers: z.array(z.enum(failoverTriggers)).min(1).optional(),
+    default: z.array(z.string()).optional(),
+    roles: z
+        .strictObject({
+        author: z.array(z.string()).optional(),
+        reviewer: z.array(z.string()).optional(),
+        leadReviewer: z.array(z.string()).optional(),
+    })
+        .partial()
+        .optional(),
+});
+export const configSchema = z
+    .strictObject({
+    pollIntervalMinutes: z.number().positive(),
+    finishedWindowDays: z.int().min(1).max(30),
+    logLevel: z.enum(LogLevel),
+    /** `shared`: the author and the reviewer may be the same GitHub profile (ADR 0011). */
+    identities: z.enum(['separate', 'shared']),
+    repos: z
+        .array(z.strictObject({
+        name: z.string().regex(repoNamePattern, 'must be owner/name'),
+        agents: z.strictObject({ author: agent.partial(), reviewer: agent.partial(), leadReviewer: agent.partial().optional() }).partial().optional(),
+    }))
+        .min(1),
+    profiles: z.record(z.string(), profile),
+    orchestratorProfile: z.string().min(1),
+    providers: z.record(z.string(), aiProvider),
+    agents: z.strictObject({ author: agent, reviewer: agent, leadReviewer: agent.optional() }),
+    /** Off unless present and enabled. Moves a role to the next AI provider upon usage_limit, rate_limit, or service_down. */
+    failover: failoverSchema.optional(),
+    limits: z.strictObject({
+        maxConcurrentEpics: z.int().positive(),
+        maxReviews: z.int().positive(),
+        maxExecutionRetries: z.int().nonnegative(),
+        maxExecutionHours: z.union([z.literal('unlimited'), z.int().positive()]),
+        githubCallTimeoutSeconds: z.int().positive(),
+        /** How long a reserved epic waits for its choice of agent options when there are two or more. */
+        optionChoiceSeconds: z.int().positive(),
+    }),
+})
+    .superRefine((config, ctx) => {
+    const refs = [
+        [['orchestratorProfile'], config.orchestratorProfile],
+        [['agents', 'author', 'profile'], config.agents.author.profile],
+        [['agents', 'reviewer', 'profile'], config.agents.reviewer.profile],
+    ];
+    if (config.agents.leadReviewer)
+        refs.push([['agents', 'leadReviewer', 'profile'], config.agents.leadReviewer.profile]);
+    config.repos.forEach((repo, i) => {
+        for (const role of ['author', 'reviewer', 'leadReviewer']) {
+            const profile = repo.agents?.[role]?.profile;
+            if (profile !== undefined)
+                refs.push([['repos', i, 'agents', role, 'profile'], profile]);
+        }
+    });
+    for (const [path, name] of refs) {
+        if (!(name in config.profiles)) {
+            ctx.addIssue({ code: 'custom', path, message: `profile "${name}" is not declared in profiles` });
+        }
+    }
+    const providerRefs = [
+        [['agents', 'author', 'provider'], config.agents.author.provider],
+        [['agents', 'reviewer', 'provider'], config.agents.reviewer.provider],
+    ];
+    if (config.agents.leadReviewer)
+        providerRefs.push([['agents', 'leadReviewer', 'provider'], config.agents.leadReviewer.provider]);
+    config.repos.forEach((repo, i) => {
+        for (const role of ['author', 'reviewer', 'leadReviewer']) {
+            const provider = repo.agents?.[role]?.provider;
+            if (provider !== undefined)
+                providerRefs.push([['repos', i, 'agents', role, 'provider'], provider]);
+        }
+    });
+    for (const [path, name] of providerRefs) {
+        if (!Object.hasOwn(config.providers, name)) {
+            ctx.addIssue({ code: 'custom', path, message: `provider "${name}" is not declared in providers` });
+        }
+    }
+    if (config.failover?.enabled) {
+        const hasDefault = config.failover.default && config.failover.default.length > 0;
+        const hasRoles = config.failover.roles && Object.values(config.failover.roles).some((r) => r && r.length > 0);
+        if (!hasDefault && !hasRoles) {
+            ctx.addIssue({ code: 'custom', path: ['failover'], message: 'failover is enabled but has neither a default nor role-specific fallback order' });
+        }
+    }
+    const checkFailoverList = (list, basePath) => {
+        if (!list)
+            return;
+        const named = new Set();
+        list.forEach((name, i) => {
+            const p = [...basePath, i];
+            const label = basePath.join('.');
+            if (!Object.hasOwn(config.providers, name)) {
+                ctx.addIssue({ code: 'custom', path: p, message: `${label}: provider "${name}" is not declared in providers` });
+            }
+            else if (named.has(name)) {
+                ctx.addIssue({ code: 'custom', path: p, message: `${label}: provider "${name}" appears twice` });
+            }
+            named.add(name);
+        });
+    };
+    if (config.failover) {
+        checkFailoverList(config.failover.default, ['failover', 'default']);
+        if (config.failover.roles) {
+            for (const role of ['author', 'reviewer', 'leadReviewer']) {
+                checkFailoverList(config.failover.roles[role], ['failover', 'roles', role]);
+            }
+        }
+    }
+    for (const [name, p] of Object.entries(config.providers)) {
+        const where = `providers.${name}`;
+        if (!optionNamePattern.test(name)) {
+            ctx.addIssue({ code: 'custom', path: ['providers', name], message: `${where}: a provider name is a lowercase word: letters, digits and hyphens, starting with a letter, up to 40 characters` });
+        }
+        if (p.provider !== undefined && !localProvidersOf[p.harness].includes(p.provider)) {
+            ctx.addIssue({ code: 'custom', path: ['providers', name, 'provider'], message: `${where}: ${p.harness} cannot use the provider "${p.provider}"` });
+        }
+        if (p.configDir !== undefined && p.harness === 'agy') {
+            ctx.addIssue({ code: 'custom', path: ['providers', name, 'configDir'], message: `${where}: agy has no config folder setting, so it cannot have a configDir` });
+        }
+        else if (p.configDir !== undefined && p.configDir !== '' && !isAbsolute(p.configDir)) {
+            ctx.addIssue({ code: 'custom', path: ['providers', name, 'configDir'], message: `${where}: configDir must be an absolute path, or start with ~/ (got "${p.configDir}")` });
+        }
+    }
+    // Solve's worktrees are `worktrees/<repo>/<feature>`, with no owner: same-name repos would share paths.
+    const seen = new Map();
+    config.repos.forEach((repo, i) => {
+        const folder = repo.name.split('/').pop().toLowerCase();
+        const first = seen.get(folder);
+        if (first === undefined)
+            seen.set(folder, repo.name);
+        else
+            ctx.addIssue({ code: 'custom', path: ['repos', i, 'name'], message: `repo "${repo.name}" has the same folder name as "${first}"; Solve's worktree paths have no owner` });
+        if (repo.agents?.leadReviewer && !config.agents.leadReviewer) {
+            for (const field of ['provider', 'profile', 'model']) {
+                if (!repo.agents.leadReviewer[field]) {
+                    ctx.addIssue({
+                        code: 'custom',
+                        path: ['repos', i, 'agents', 'leadReviewer', field],
+                        message: `repo "${repo.name}": agents.leadReviewer.${field} is required when no top-level agents.leadReviewer is configured`,
+                    });
+                }
+            }
+        }
+    });
+    // Under separate identities, author and reviewer must differ, globally and for each repo once its overrides are applied.
+    if (config.identities !== 'separate')
+        return;
+    // A global clash is reported once, not again for every repo that inherits it.
+    const clash = (path, where, profile, role1 = 'agents.author.profile', role2 = 'agents.reviewer.profile') => ctx.addIssue({
+        code: 'custom',
+        path,
+        message: `${where}${role1} and ${role2} must differ, both are "${profile}" (or set identities to "shared" to use one account for both)`,
+    });
+    if (config.agents.author.profile === config.agents.reviewer.profile) {
+        clash(['agents'], '', config.agents.author.profile);
+        return;
+    }
+    if (config.agents.leadReviewer && config.agents.author.profile === config.agents.leadReviewer.profile) {
+        clash(['agents'], '', config.agents.author.profile, 'agents.author.profile', 'agents.leadReviewer.profile');
+        return;
+    }
+    config.repos.forEach((repo, i) => {
+        const resolved = resolveRepoConfig(config, repo).agents;
+        if (!resolved.author || !resolved.reviewer)
+            return;
+        if (resolved.author.profile === resolved.reviewer.profile)
+            clash(['repos', i, 'agents'], `repo "${repo.name}": `, resolved.author.profile);
+        else if (resolved.leadReviewer && resolved.author.profile === resolved.leadReviewer.profile) {
+            clash(['repos', i, 'agents'], `repo "${repo.name}": `, resolved.author.profile, 'agents.author.profile', 'agents.leadReviewer.profile');
+        }
+    });
+});

package/dist/control/epic.js

@@ -0,0 +1,219 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createScopedLogger } from '@ashulab/universal-logger';
+import { and, desc, eq, sql } from 'drizzle-orm';
+import { callerResults } from '../storage/caller-results.js';
+import { epicReviewThreads } from '../storage/epic-review-threads.js';
+import { epicSlices } from '../storage/epic-slices.js';
+import { executionEvents } from '../storage/events.js';
+import { executions } from '../storage/executions.js';
+import { epics } from '../storage/schema.js';
+import { optionsOf } from '../status/snapshot.js';
+import { agentOf } from './sessions.js';
+const log = createScopedLogger('control');
+// The reply is bounded: with these, a round weighs at most about 60 KB, far under the client's 8 MiB line.
+export const MAX_ROUNDS = 50;
+const MAX_BLOCKERS = 50;
+const MAX_OBSERVATIONS = 50;
+const MAX_COMMITS = 50;
+const MAX_TEXT = 200;
+const MAX_URL = 500;
+const MAX_ACTIVITY = 80;
+const MAX_LIVE_EVENTS = 500; // per kind, newest first, of the one running execution
+/** A title compared without caring for case or spacing. */
+const normal = (title) => title.trim().replace(/\s+/g, ' ').toLowerCase();
+/** The same blocker in two rounds: by id when both have one, else by title. */
+const same = (a, b) => (a.id !== null && b.id !== null ? a.id === b.id : normal(a.title) === normal(b.title));
+/**
+ * Blockers of a round against the open ones of the round before it in the same attempt: the same blocker is carried, one that
+ * disappeared is fixed, a new one is new. A mark is exact when ids settle it (the first round has nothing to match, so new is certain);
+ * otherwise it comes from matching titles and is approximate. `resolved` is what the reviewer said it considers fixed.
+ */
+function marked(current, previous, resolved) {
+    const prior = previous ?? [];
+    const blocker = (b, mark, approximate) => ({ id: b.id, title: b.title, url: b.url, mark, approximate });
+    const allIds = (list) => list.every(({ id }) => id !== null);
+    return [
+        ...current.map((b) => blocker(b, prior.some((p) => same(b, p)) ? 'carried' : 'new', previous !== null && (b.id === null || !allIds(prior)))),
+        ...prior
+            .filter((p) => current.some((b) => same(b, p)) === false)
+            .map((p) => blocker(p, 'fixed', !(p.id !== null && (resolved.includes(p.id) || allIds(current))))),
+    ].slice(0, MAX_BLOCKERS);
+}
+/** git in a folder; null when the folder is gone (expected: an epic's worktree is removed when it ends) or git failed (logged). */
+export function git(cwd, args) {
+    if (existsSync(cwd) === false)
+        return null;
+    try {
+        // no optional locks: reading an agent's worktree must not refresh its index under the agent's own commit
+        return execFileSync('git', args, { cwd, encoding: 'utf8', timeout: 5_000, maxBuffer: 32 * 1024 * 1024, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' }, stdio: ['ignore', 'pipe', 'pipe'] });
+    }
+    catch (error) {
+        log.warn('git failed in an epic worktree', { cwd, args: args[0], error: String(error) });
+        return null;
+    }
+}
+// A range of two shas never changes, so asking git once is enough (this is polled every few seconds).
+// Oldest entry out past the cap, so a long-lived engine does not grow with every round it ever saw.
+const MAX_CACHED_RANGES = 500;
+const commitCache = new Map();
+/** The commits a fix added between the head the review saw and the head it left; empty when there is no worktree to ask. */
+function commitsBetween(cwd, from, to) {
+    if (cwd === null)
+        return [];
+    const key = `${cwd}\0${from}..${to}`;
+    const cached = commitCache.get(key);
+    if (cached)
+        return cached;
+    const out = git(cwd, ['log', `--max-count=${MAX_COMMITS}`, '--format=%H%x00%s', `${from}..${to}`]);
+    if (out === null)
+        return [];
+    const commits = out.split('\n').filter(Boolean).map((line) => {
+        const [sha = '', subject = ''] = line.split('\0');
+        return { sha, subject: subject.slice(0, MAX_TEXT) };
+    });
+    if (commitCache.size >= MAX_CACHED_RANGES)
+        commitCache.delete(commitCache.keys().next().value);
+    commitCache.set(key, commits);
+    return commits;
+}
+/**
+ * The lane and the activity of the agent building each slice, by slice number: the agent is the one whose newest `task` event
+ * names the slice and has no status (a second `task` event ends it). Only the running author execution is read, newest events
+ * first and capped, so it never grows with the table. The lane is a hint: `lane` in an event's payload, else `--lane-N` in a call's argument.
+ */
+function liveHints(db, epicId) {
+    const hints = new Map();
+    const running = db
+        .select({ executionId: executions.executionId })
+        .from(executions)
+        .where(and(eq(executions.epicId, epicId), eq(executions.stage, 'ship'), eq(executions.status, 'running')))
+        .orderBy(desc(sql `executions.rowid`))
+        .get();
+    if (running === undefined)
+        return hints;
+    const newest = (kind) => db.select().from(executionEvents).where(and(eq(executionEvents.executionId, running.executionId), eq(executionEvents.kind, kind))).orderBy(desc(executionEvents.id)).limit(MAX_LIVE_EVENTS).all();
+    const calls = newest('tool_start');
+    const seen = new Set();
+    for (const task of newest('task')) {
+        if (task.agentId === null || seen.has(task.agentId))
+            continue;
+        seen.add(task.agentId);
+        const slice = task.payload?.slice;
+        if (task.status !== null || slice === undefined || hints.has(slice))
+            continue;
+        const mine = calls.filter((call) => call.agentId === task.agentId);
+        const lane = mine.map((call) => call.payload?.lane ?? Number(/--lane-(\d+)/.exec(call.arg ?? '')?.[1] ?? NaN)).find((n) => Number.isNaN(n) === false);
+        const call = mine[0];
+        hints.set(slice, { lane: lane ?? null, activity: call === undefined ? null : [call.tool, call.arg].filter((part) => part !== null).join(' ').replace(/\s+/g, ' ').slice(0, MAX_ACTIVITY) });
+    }
+    return hints;
+}
+/**
+ * The stage timeline, review rounds, worktrees and branch of an epic; null for one the engine does not know.
+ * Built from the executions and the stored results, so it also reads an epic that has finished. A round is a review that
+ * left a result: technical retries leave none and make no round. An epic put back in the queue starts new rounds from 1
+ * after the old ones, which stay in the list. `slices` is the cache of GitHub the poll keeps (ADR 0008); `pr` is the block the poll cached from GitHub, null while the epic has no pull request, and `threads` the pull request's review threads cached with it.
+ */
+export function epicOf(db, repo, issue) {
+    const epic = db.select().from(epics).where(and(eq(epics.repo, repo), eq(epics.issue, issue))).get();
+    if (epic === undefined)
+        return null;
+    const runs = db
+        .select({ run: executions, result: callerResults.result })
+        .from(executions)
+        .leftJoin(callerResults, eq(callerResults.executionId, executions.executionId))
+        .where(eq(executions.epicId, epic.id))
+        .orderBy(sql `executions.rowid`)
+        .all();
+    // Rounds, attempt by attempt: a ship after a review or a fix is an epic that started again.
+    let attempt = 0;
+    let worked = false; // a review or a fix ran in this attempt
+    let open = null; // the previous round's open blockers; null before the first round
+    const found = [];
+    for (const { run, result } of runs) {
+        if (run.stage === 'ship') {
+            if (worked) {
+                attempt++;
+                worked = false;
+                open = null;
+            }
+            continue;
+        }
+        worked = true;
+        const last = found.at(-1);
+        if (run.stage === 'fix') {
+            if (last === undefined || last.attempt !== attempt)
+                continue;
+            last.fixed = true;
+            if (result === null)
+                continue; // a retry or one still running
+            const parsed = JSON.parse(result);
+            last.round.fixMs = run.finishedAt === null ? null : run.finishedAt - run.startedAt;
+            last.round.fixedSha = parsed.outcome === 'completed' ? parsed.pr.headSha : null;
+            continue;
+        }
+        if (result === null)
+            continue;
+        const parsed = JSON.parse(result);
+        if (parsed.outcome === 'needs_human')
+            continue; // the reviewer stopped: no verdict to show
+        const toFound = ({ id, title, url }) => ({ id: id ?? null, title: title.slice(0, MAX_TEXT), url: url !== undefined && url.length <= MAX_URL ? url : null });
+        const blockers = parsed.outcome === 'changes_requested' ? parsed.blockers.map(toFound) : [];
+        const observations = parsed.outcome === 'completed' ? (parsed.observations ?? []).slice(0, MAX_OBSERVATIONS).map(toFound) : [];
+        found.push({
+            attempt,
+            fixed: false,
+            round: {
+                round: run.round ?? (found.filter((f) => f.attempt === attempt).length + 1),
+                reviewer: agentOf(run, epic.config),
+                verdict: parsed.outcome === 'completed' ? 'approved' : 'changes_requested',
+                blockers: marked(blockers, open, parsed.resolved ?? []),
+                observations,
+                reviewMs: run.finishedAt === null ? null : run.finishedAt - run.startedAt,
+                fixMs: null,
+                reviewedSha: parsed.pr.headSha,
+                fixedSha: null,
+                commits: [],
+            },
+        });
+        open = blockers;
+    }
+    const hitLimit = epic.status === 'needs_human' && epic.needsHumanReason?.startsWith('review limit') === true;
+    const rounds = found.slice(-MAX_ROUNDS).map(({ round, attempt: of, fixed }) => {
+        // Nothing answered it and nothing follows: the epic stopped there for the limit.
+        if (round.verdict === 'changes_requested' && fixed === false && (of < attempt || hitLimit))
+            round.verdict = 'limit_reached';
+        if (round.reviewedSha !== null && round.fixedSha !== null)
+            round.commits = commitsBetween(epic.workspace, round.reviewedSha, round.fixedSha);
+        return round;
+    });
+    // The stages of the current attempt: queued, then each contiguous run of a stage, then ready.
+    const stages = [{ stage: 'queued', startedAt: epic.queuedAt, endedAt: epic.startedAt }];
+    if (epic.startedAt !== null) {
+        const startedAt = epic.startedAt;
+        const segments = [];
+        for (const { run } of runs) {
+            if (run.startedAt >= startedAt && segments.at(-1)?.stage !== run.stage)
+                segments.push({ stage: run.stage, startedAt: segments.length === 0 ? startedAt : run.startedAt });
+        }
+        // reserved, the clone still being prepared: no execution yet
+        if (segments.length === 0 && epic.stage !== null)
+            segments.push({ stage: epic.stage, startedAt });
+        const ended = epic.status === 'running' ? null : epic.finishedAt;
+        stages.push(...segments.map((segment, i) => ({ ...segment, endedAt: segments[i + 1]?.startedAt ?? ended })));
+        if (epic.status === 'ready_for_test' && epic.finishedAt !== null)
+            stages.push({ stage: 'ready', startedAt: epic.finishedAt, endedAt: null });
+    }
+    const reviewer = runs.findLast(({ run }) => run.stage === 'review' && run.workspace !== null)?.run.workspace ?? null;
+    const worktrees = [
+        ...(epic.workspace === null ? [] : [{ kind: 'epic', lane: null, path: epic.workspace }]),
+        ...(reviewer === null ? [] : [{ kind: 'reviewer', lane: null, path: reviewer }]),
+    ];
+    // the row records the branch once ship is validated; before that the worktree's HEAD is the only place it is
+    const branch = epic.branch ?? (epic.workspace === null ? null : (git(epic.workspace, ['symbolic-ref', '--short', 'HEAD'])?.trim() || null));
+    const slices = db.select().from(epicSlices).where(eq(epicSlices.epicId, epic.id)).orderBy(epicSlices.number).all();
+    const threads = db.select().from(epicReviewThreads).where(eq(epicReviewThreads.epicId, epic.id)).orderBy(epicReviewThreads.position).all();
+    const hints = liveHints(db, epic.id);
+    return { stages, rounds, slices: slices.map(({ number, title, state, blockedBy, prNumber, prState, prMergedAt, closedAt, readAt }) => ({ number, title, state, blockedBy, prNumber, prState, prMergedAt, closedAt, readAt, lane: null, activity: null, ...(state === 'in_progress' && hints.get(number)) })), slicesTruncated: slices.some((s) => s.truncated), threads: threads.map(({ epicId, position, readAt, truncated, ...thread }) => thread), threadsTruncated: threads.some((t) => t.truncated), worktrees, branch, options: optionsOf(epic), pr: epic.pr };
+}

package/dist/control/events.js

@@ -0,0 +1,48 @@
+import { and, asc, desc, eq, gt } from 'drizzle-orm';
+import { executionEvents } from '../storage/events.js';
+import { executions } from '../storage/executions.js';
+import { epics } from '../storage/schema.js';
+import { agentOf } from './sessions.js';
+// Only what ExecEvent names leaves: the slice and lane hints in the payload are for the engine.
+const wire = (row) => ({
+    id: row.id,
+    at: row.at,
+    kind: row.kind,
+    ...(row.payload?.text !== undefined && { text: row.payload.text }),
+    ...(row.callId !== null && { callId: row.callId }),
+    ...(row.agentId !== null && { agentId: row.agentId }),
+    ...(row.tool !== null && { tool: row.tool }),
+    ...(row.arg !== null && { arg: row.arg }),
+    ...(row.summary !== null && { summary: row.summary }),
+    ...(row.status !== null && { status: row.status }),
+    ...(row.durationMs !== null && { durationMs: row.durationMs }),
+    ...(row.payload?.description !== undefined && { description: row.payload.description }),
+    ...(row.payload?.output !== undefined && { output: row.payload.output }),
+    ...(row.payload?.diff !== undefined && { diff: row.payload.diff }),
+});
+// The harnesses that have an events parser.
+const structuredHarnesses = ['claude', 'codex', 'agy'];
+/**
+ * The events of an execution after the cursor, oldest first, at most `limit`; null for an execution the engine does not know.
+ * A harness with no parser yet (a future one; today all three have one) answers `structured: false` and no events.
+ */
+export function eventsOf(db, executionId, after, limit) {
+    const row = db.select({ execution: executions, config: epics.config }).from(executions).innerJoin(epics, eq(epics.id, executions.epicId)).where(eq(executions.executionId, executionId)).get();
+    if (row === undefined)
+        return null;
+    const running = row.execution.status === 'running';
+    if (!structuredHarnesses.includes(agentOf(row.execution, row.config).harness))
+        return { events: [], next: after, running, structured: false };
+    const events = db.select().from(executionEvents).where(and(eq(executionEvents.executionId, executionId), gt(executionEvents.id, after))).orderBy(asc(executionEvents.id)).limit(limit).all().map(wire);
+    return { events, next: events.at(-1)?.id ?? after, running, structured: true };
+}
+// A line of the Overview: what the agent is doing now, in the words of its newest event.
+const describe = (row) => {
+    const call = [row.tool, row.arg].filter((part) => part !== null).join(' ');
+    return (row.kind === 'tool_start' ? call : row.kind === 'tool_end' ? [row.tool, row.summary].filter((part) => part !== null).join(' ') : (row.payload?.text ?? '')).slice(0, 200);
+};
+/** The newest event of an execution for the snapshot; null while it has none. */
+export function lastEventOf(db, executionId) {
+    const row = db.select().from(executionEvents).where(eq(executionEvents.executionId, executionId)).orderBy(desc(executionEvents.id)).limit(1).get();
+    return row === undefined ? null : { kind: row.kind, text: describe(row), at: row.at };
+}