stageflow 0.36.0 → 0.40.0

package/dist/agents/store.js

@@ -0,0 +1,643 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { agentDefinitionSchema } from "../config/loadAgent.js";
+/**
+ * The one list of session statuses. The database CHECK (migration 013), the HTTP filter and the MCP tool schema all
+ * read this. `held` is kept because the CHECK allows it and old rows may carry it; nothing writes it any more.
+ */
+export const SESSION_STATUSES = ["open", "running", "waiting", "held", "closed"];
+export function isSessionStatus(value) {
+    return SESSION_STATUSES.includes(value);
+}
+export function agentProjectKey(projectRoot) {
+    return createHash("sha256").update(path.resolve(projectRoot)).digest("hex").slice(0, 16);
+}
+const str = (value) => value;
+const strOrNull = (value) => (value === null || value === undefined ? null : value);
+const numOrNull = (value) => (value === null || value === undefined ? null : Number(value));
+function toDefinitionRow(row) {
+    return {
+        agentId: str(row.agent_id),
+        currentRevision: Number(row.current_revision),
+        archived: row.archived === 1,
+        fileHash: strOrNull(row.file_hash),
+        issues: row.issues_json ? JSON.parse(str(row.issues_json)) : [],
+        createdAt: str(row.created_at),
+        updatedAt: str(row.updated_at),
+    };
+}
+function toRevisionMeta(row) {
+    return {
+        agentId: str(row.agent_id),
+        revision: Number(row.revision),
+        source: str(row.source),
+        author: strOrNull(row.author),
+        summary: strOrNull(row.summary),
+        restoredFrom: numOrNull(row.restored_from),
+        createdAt: str(row.created_at),
+    };
+}
+/** Revisions saved before a block existed read back with that block's defaults. */
+function withCurrentDefaults(stored) {
+    const parsed = agentDefinitionSchema.safeParse(stored);
+    return parsed.success ? parsed.data : stored;
+}
+function toRevision(row) {
+    return {
+        ...toRevisionMeta(row),
+        definition: withCurrentDefaults(JSON.parse(str(row.definition_json))),
+        yaml: str(row.yaml_text),
+    };
+}
+function toSession(row) {
+    return {
+        id: str(row.session_id),
+        agentId: str(row.agent_id),
+        revision: Number(row.revision),
+        backend: str(row.backend),
+        status: str(row.status),
+        source: str(row.source),
+        sourceRef: strOrNull(row.source_ref),
+        threadKey: strOrNull(row.thread_key),
+        title: strOrNull(row.title),
+        createdAt: str(row.created_at),
+        updatedAt: str(row.updated_at),
+    };
+}
+function toMessage(row) {
+    return {
+        id: str(row.message_id),
+        sessionId: str(row.session_id),
+        seq: Number(row.seq),
+        turnId: strOrNull(row.turn_id),
+        role: str(row.role),
+        author: strOrNull(row.author),
+        text: str(row.text),
+        createdAt: str(row.created_at),
+    };
+}
+function toTurn(row) {
+    return {
+        id: str(row.turn_id),
+        sessionId: str(row.session_id),
+        seq: Number(row.seq),
+        revision: Number(row.revision),
+        traceId: str(row.trace_id),
+        status: str(row.status),
+        errorCode: strOrNull(row.error_code),
+        inputTokens: numOrNull(row.input_tokens),
+        outputTokens: numOrNull(row.output_tokens),
+        costUsd: numOrNull(row.cost_usd),
+        startedAt: str(row.started_at),
+        endedAt: strOrNull(row.ended_at),
+    };
+}
+function toDelivery(row) {
+    return {
+        turnId: str(row.turn_id),
+        sessionId: str(row.session_id),
+        connectionId: str(row.connection_id),
+        provider: str(row.provider),
+        replyTo: str(row.reply_to),
+        text: str(row.text),
+        state: str(row.state),
+        attempts: Number(row.attempts),
+        errorCode: strOrNull(row.error_code),
+        errorMessage: strOrNull(row.error_message),
+        retryable: Number(row.retryable) === 1,
+        nextAttemptAt: strOrNull(row.next_attempt_at),
+        createdAt: str(row.created_at),
+        updatedAt: str(row.updated_at),
+    };
+}
+function toSpan(row) {
+    return {
+        id: str(row.span_id),
+        turnId: str(row.turn_id),
+        parentSpanId: strOrNull(row.parent_span_id),
+        name: str(row.name),
+        kind: str(row.kind),
+        status: str(row.status),
+        startedAt: str(row.started_at),
+        endedAt: strOrNull(row.ended_at),
+        durationMs: numOrNull(row.duration_ms),
+        inputTokens: numOrNull(row.input_tokens),
+        outputTokens: numOrNull(row.output_tokens),
+        attributes: JSON.parse(str(row.attributes_json)),
+        inputText: strOrNull(row.input_text),
+        outputText: strOrNull(row.output_text),
+    };
+}
+function toApproval(row) {
+    return {
+        id: str(row.approval_id),
+        sessionId: str(row.session_id),
+        turnId: strOrNull(row.turn_id),
+        tool: str(row.tool),
+        payload: JSON.parse(str(row.payload_json)),
+        payloadHash: str(row.payload_hash),
+        status: str(row.status),
+        createdAt: str(row.created_at),
+        expiresAt: str(row.expires_at),
+        decidedAt: strOrNull(row.decided_at),
+        actor: row.actor_json ? JSON.parse(str(row.actor_json)) : null,
+    };
+}
+function encodeCursor(updatedAt, sessionId) {
+    return Buffer.from(JSON.stringify([updatedAt, sessionId])).toString("base64url");
+}
+function decodeCursor(cursor) {
+    try {
+        const value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (Array.isArray(value) && value.length === 2 && value.every((item) => typeof item === "string")) {
+            return value;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+export class AgentStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    transaction(work) {
+        return this.db.transaction(work)();
+    }
+    /* ---------- definitions and revisions ---------- */
+    listDefinitions(projectKey) {
+        return this.db
+            .prepare(`SELECT * FROM agent_definitions WHERE project_key = ? ORDER BY agent_id`)
+            .all(projectKey).map(toDefinitionRow);
+    }
+    getDefinition(projectKey, agentId) {
+        const row = this.db
+            .prepare(`SELECT * FROM agent_definitions WHERE project_key = ? AND agent_id = ?`)
+            .get(projectKey, agentId);
+        return row ? toDefinitionRow(row) : undefined;
+    }
+    /** Record the file's latest observed state without changing the revision (invalid edit, archive, restore). */
+    updateDefinitionState(projectKey, agentId, patch, now) {
+        const current = this.getDefinition(projectKey, agentId);
+        if (!current)
+            return;
+        this.db
+            .prepare(`UPDATE agent_definitions
+           SET archived = ?, file_hash = ?, issues_json = ?, updated_at = ?
+         WHERE project_key = ? AND agent_id = ?`)
+            .run((patch.archived ?? current.archived) ? 1 : 0, patch.fileHash === undefined ? current.fileHash : patch.fileHash, JSON.stringify(patch.issues ?? current.issues), now, projectKey, agentId);
+    }
+    /** Append the next revision and make it current. Returns the new revision number. */
+    appendRevision(projectKey, input) {
+        return this.transaction(() => {
+            const agentId = input.definition.id;
+            const existing = this.getDefinition(projectKey, agentId);
+            const revision = (existing?.currentRevision ?? 0) + 1;
+            this.db
+                .prepare(`INSERT INTO agent_revisions
+             (project_key, agent_id, revision, definition_json, yaml_text, source, author, summary, restored_from, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(projectKey, agentId, revision, JSON.stringify(input.definition), input.yaml, input.source, input.author ?? null, input.summary ?? null, input.restoredFrom ?? null, input.now);
+            if (existing) {
+                this.db
+                    .prepare(`UPDATE agent_definitions
+               SET current_revision = ?, archived = 0, file_hash = ?, issues_json = '[]', updated_at = ?
+             WHERE project_key = ? AND agent_id = ?`)
+                    .run(revision, input.fileHash, input.now, projectKey, agentId);
+            }
+            else {
+                this.db
+                    .prepare(`INSERT INTO agent_definitions
+               (project_key, agent_id, current_revision, archived, file_hash, issues_json, created_at, updated_at)
+             VALUES (?, ?, ?, 0, ?, '[]', ?, ?)`)
+                    .run(projectKey, agentId, revision, input.fileHash, input.now, input.now);
+            }
+            return revision;
+        });
+    }
+    /** First sighting of a file that never parsed: no revision yet, only issues. */
+    recordInvalidNewDefinition(projectKey, agentId, fileHash, issues, now) {
+        this.db
+            .prepare(`INSERT INTO agent_definitions
+           (project_key, agent_id, current_revision, archived, file_hash, issues_json, created_at, updated_at)
+         VALUES (?, ?, 0, 0, ?, ?, ?, ?)
+         ON CONFLICT (project_key, agent_id) DO UPDATE
+           SET file_hash = excluded.file_hash, issues_json = excluded.issues_json, archived = 0,
+               updated_at = excluded.updated_at`)
+            .run(projectKey, agentId, fileHash, JSON.stringify(issues), now, now);
+    }
+    getRevision(projectKey, agentId, revision) {
+        const row = this.db
+            .prepare(`SELECT * FROM agent_revisions WHERE project_key = ? AND agent_id = ? AND revision = ?`)
+            .get(projectKey, agentId, revision);
+        return row ? toRevision(row) : undefined;
+    }
+    listRevisions(projectKey, agentId) {
+        return this.db
+            .prepare(`SELECT agent_id, revision, source, author, summary, restored_from, created_at
+             FROM agent_revisions WHERE project_key = ? AND agent_id = ? ORDER BY revision DESC`)
+            .all(projectKey, agentId).map(toRevisionMeta);
+    }
+    /* ---------- sessions and messages ---------- */
+    insertSession(projectKey, session) {
+        this.db
+            .prepare(`INSERT INTO agent_sessions
+           (session_id, project_key, agent_id, revision, backend, status, source, source_ref, thread_key, title,
+            created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(session.id, projectKey, session.agentId, session.revision, session.backend, session.status, session.source, session.sourceRef, session.threadKey, session.title, session.createdAt, session.updatedAt);
+    }
+    getSession(sessionId) {
+        const row = this.db.prepare(`SELECT * FROM agent_sessions WHERE session_id = ?`).get(sessionId);
+        return row ? { ...toSession(row), projectKey: str(row.project_key) } : undefined;
+    }
+    findSessionByThread(projectKey, agentId, threadKey) {
+        const row = this.db
+            .prepare(`SELECT * FROM agent_sessions WHERE project_key = ? AND agent_id = ? AND thread_key = ?`)
+            .get(projectKey, agentId, threadKey);
+        return row ? toSession(row) : undefined;
+    }
+    updateSession(sessionId, patch, now) {
+        const sets = ["updated_at = @now"];
+        if (patch.status !== undefined)
+            sets.push("status = @status");
+        if (patch.backend !== undefined)
+            sets.push("backend = @backend");
+        if (patch.title !== undefined)
+            sets.push("title = @title");
+        this.db
+            .prepare(`UPDATE agent_sessions SET ${sets.join(", ")} WHERE session_id = @sessionId`)
+            .run({ ...patch, now, sessionId });
+    }
+    /** One agent's sessions, or every agent's when `agentId` is omitted. */
+    listSessions(projectKey, agentId, query) {
+        const where = ["project_key = @projectKey"];
+        const params = { projectKey, limit: query.limit + 1 };
+        if (agentId !== undefined) {
+            where.push("agent_id = @agentId");
+            params.agentId = agentId;
+        }
+        if (query.status) {
+            where.push("status = @status");
+            params.status = query.status;
+        }
+        if (query.source) {
+            where.push("source = @source");
+            params.source = query.source;
+        }
+        if (query.search) {
+            where.push(`(title LIKE @search ESCAPE '\\' OR session_id LIKE @search ESCAPE '\\'
+          OR EXISTS (SELECT 1 FROM agent_messages m WHERE m.session_id = agent_sessions.session_id
+                     AND m.text LIKE @search ESCAPE '\\'))`);
+            params.search = `%${query.search.replace(/[\\%_]/g, (char) => `\\${char}`)}%`;
+        }
+        const cursor = query.cursor ? decodeCursor(query.cursor) : undefined;
+        if (cursor) {
+            where.push("(updated_at < @cursorAt OR (updated_at = @cursorAt AND session_id < @cursorId))");
+            params.cursorAt = cursor[0];
+            params.cursorId = cursor[1];
+        }
+        const rows = this.db
+            .prepare(`SELECT agent_sessions.*,
+                (SELECT COUNT(*) FROM agent_turns t WHERE t.session_id = agent_sessions.session_id) AS turn_count,
+                (SELECT COALESCE(SUM(input_tokens), 0) FROM agent_turns t
+                  WHERE t.session_id = agent_sessions.session_id) AS input_tokens,
+                (SELECT COALESCE(SUM(output_tokens), 0) FROM agent_turns t
+                  WHERE t.session_id = agent_sessions.session_id) AS output_tokens,
+                (SELECT SUM(cost_usd) FROM agent_turns t WHERE t.session_id = agent_sessions.session_id) AS cost_usd,
+                (SELECT status FROM agent_turns t WHERE t.session_id = agent_sessions.session_id
+                  ORDER BY seq DESC LIMIT 1) AS last_turn_status
+           FROM agent_sessions WHERE ${where.join(" AND ")}
+         ORDER BY updated_at DESC, session_id DESC LIMIT @limit`)
+            .all(params);
+        const sessions = rows.slice(0, query.limit).map((row) => ({
+            ...toSession(row),
+            turnCount: Number(row.turn_count),
+            inputTokens: Number(row.input_tokens),
+            outputTokens: Number(row.output_tokens),
+            costUsd: numOrNull(row.cost_usd),
+            lastTurnStatus: strOrNull(row.last_turn_status),
+        }));
+        const last = sessions.at(-1);
+        return {
+            sessions,
+            nextCursor: rows.length > query.limit && last ? encodeCursor(last.updatedAt, last.id) : null,
+        };
+    }
+    /** One visitor's sessions on one agent, newest first (public web chat). */
+    listSessionsForRef(projectKey, agentId, source, sourceRef, limit) {
+        return this.db
+            .prepare(`SELECT * FROM agent_sessions
+            WHERE project_key = ? AND agent_id = ? AND source = ? AND source_ref = ?
+            ORDER BY updated_at DESC, session_id DESC LIMIT ?`)
+            .all(projectKey, agentId, source, sourceRef, limit).map(toSession);
+    }
+    /** Stats for one agent, or for every agent when `agentId` is omitted. */
+    sessionStats(projectKey, agentId, since) {
+        const agentFilter = agentId === undefined ? "" : " AND agent_id = @agentId";
+        const sessionAgentFilter = agentId === undefined ? "" : " AND s.agent_id = @agentId";
+        const bind = (extra) => (agentId === undefined ? extra : { ...extra, agentId });
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS total,
+                SUM(CASE WHEN status IN ('running', 'waiting') THEN 1 ELSE 0 END) AS active,
+                SUM(CASE WHEN status = 'waiting' THEN 1 ELSE 0 END) AS waiting,
+                SUM(CASE WHEN created_at >= @since THEN 1 ELSE 0 END) AS recent,
+                MAX(updated_at) AS last_activity
+           FROM agent_sessions WHERE project_key = @projectKey${agentFilter}`)
+            .get(bind({ projectKey, since }));
+        const turns = this.db
+            .prepare(`SELECT SUM(CASE WHEN t.started_at >= @since AND t.status IN ('succeeded', 'failed', 'cancelled') THEN 1 ELSE 0 END) AS finished,
+                SUM(CASE WHEN t.started_at >= @since AND t.status = 'succeeded' THEN 1 ELSE 0 END) AS succeeded,
+                SUM(CASE WHEN t.started_at >= @since THEN t.cost_usd END) AS cost,
+                SUM(t.cost_usd) AS cost_all
+           FROM agent_turns t JOIN agent_sessions s ON s.session_id = t.session_id
+          WHERE s.project_key = @projectKey${sessionAgentFilter}`)
+            .get(bind({ projectKey, since }));
+        return {
+            total: Number(row.total ?? 0),
+            active: Number(row.active ?? 0),
+            waiting: Number(row.waiting ?? 0),
+            last7Days: Number(row.recent ?? 0),
+            lastActivityAt: strOrNull(row.last_activity),
+            turnsFinished7d: Number(turns.finished ?? 0),
+            turnsSucceeded7d: Number(turns.succeeded ?? 0),
+            cost7d: numOrNull(turns.cost),
+            costTotal: numOrNull(turns.cost_all),
+        };
+    }
+    /** Ids of every session an agent has had, for releasing what a runtime holds for them. */
+    sessionIdsOf(projectKey, agentId) {
+        return this.db.prepare(`SELECT session_id FROM agent_sessions WHERE project_key = ? AND agent_id = ?`).all(projectKey, agentId).map((row) => str(row.session_id));
+    }
+    appendMessage(message) {
+        const seq = Number(this.db
+            .prepare(`SELECT COALESCE(MAX(seq), 0) + 1 AS next FROM agent_messages WHERE session_id = ?`)
+            .get(message.sessionId).next);
+        this.db
+            .prepare(`INSERT INTO agent_messages (message_id, session_id, seq, turn_id, role, author, text, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(message.id, message.sessionId, seq, message.turnId, message.role, message.author, message.text, message.createdAt);
+        return { ...message, seq };
+    }
+    listMessages(sessionId) {
+        return this.db.prepare(`SELECT * FROM agent_messages WHERE session_id = ? ORDER BY seq`).all(sessionId).map(toMessage);
+    }
+    /* ---------- turns, spans, evals ---------- */
+    insertTurn(turn) {
+        const seq = Number(this.db
+            .prepare(`SELECT COALESCE(MAX(seq), 0) + 1 AS next FROM agent_turns WHERE session_id = ?`)
+            .get(turn.sessionId).next);
+        this.db
+            .prepare(`INSERT INTO agent_turns
+           (turn_id, session_id, seq, revision, trace_id, status, error_code, input_tokens, output_tokens, cost_usd,
+            started_at, ended_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(turn.id, turn.sessionId, seq, turn.revision, turn.traceId, turn.status, turn.errorCode, turn.inputTokens, turn.outputTokens, turn.costUsd, turn.startedAt, turn.endedAt);
+        return { ...turn, seq };
+    }
+    finishTurn(turnId, patch) {
+        this.db
+            .prepare(`UPDATE agent_turns
+            SET status = @status, error_code = @errorCode, input_tokens = @inputTokens,
+                output_tokens = @outputTokens, cost_usd = @costUsd, ended_at = @endedAt
+          WHERE turn_id = @turnId`)
+            .run({ ...patch, turnId });
+    }
+    /** Change a finished turn's outcome after the fact, for example when its reply could not be delivered. */
+    setTurnOutcome(turnId, status, errorCode) {
+        this.db.prepare(`UPDATE agent_turns SET status = ?, error_code = ? WHERE turn_id = ?`).run(status, errorCode, turnId);
+    }
+    insertDelivery(delivery) {
+        this.db
+            .prepare(`INSERT INTO agent_deliveries
+           (turn_id, session_id, connection_id, provider, reply_to, text, state, attempts, error_code, error_message, retryable, next_attempt_at, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(delivery.turnId, delivery.sessionId, delivery.connectionId, delivery.provider, delivery.replyTo, delivery.text, delivery.state, delivery.attempts, delivery.errorCode, delivery.errorMessage, delivery.retryable ? 1 : 0, delivery.nextAttemptAt, delivery.createdAt, delivery.updatedAt);
+    }
+    getDelivery(turnId) {
+        const row = this.db.prepare(`SELECT * FROM agent_deliveries WHERE turn_id = ?`).get(turnId);
+        return row ? toDelivery(row) : undefined;
+    }
+    listDeliveries(sessionId) {
+        return this.db.prepare(`SELECT * FROM agent_deliveries WHERE session_id = ? ORDER BY created_at`).all(sessionId).map(toDelivery);
+    }
+    updateDelivery(turnId, patch, now) {
+        const current = this.getDelivery(turnId);
+        if (!current)
+            return;
+        const next = { ...current, ...patch };
+        this.db
+            .prepare(`UPDATE agent_deliveries SET state = ?, attempts = ?, error_code = ?, error_message = ?, retryable = ?, next_attempt_at = ?, updated_at = ? WHERE turn_id = ?`)
+            .run(next.state, next.attempts, next.errorCode, next.errorMessage, next.retryable ? 1 : 0, next.nextAttemptAt, now, turnId);
+    }
+    /**
+     * Atomically take a delivery for sending: one UPDATE that only matches while it is still in an allowed state (and,
+     * for a retry, still due), so two overlapping attempts cannot both win. Returns the claimed row or undefined.
+     */
+    claimDelivery(turnId, states, now, options = {}) {
+        const placeholders = states.map(() => "?").join(", ");
+        const due = options.dueRetry ? " AND retryable = 1 AND next_attempt_at IS NOT NULL AND next_attempt_at <= ?" : "";
+        const result = this.db
+            .prepare(`UPDATE agent_deliveries
+            SET state = 'sending', attempts = attempts + 1, error_code = NULL, error_message = NULL,
+                retryable = 0, next_attempt_at = NULL, updated_at = ?
+          WHERE turn_id = ? AND state IN (${placeholders})${due}`)
+            .run(now, turnId, ...states, ...(options.dueRetry ? [now] : []));
+        return result.changes === 1 ? this.getDelivery(turnId) : undefined;
+    }
+    /** Failed deliveries a retry is due for. */
+    dueDeliveries(now) {
+        return this.db.prepare(`SELECT * FROM agent_deliveries WHERE state = 'failed' AND retryable = 1 AND next_attempt_at IS NOT NULL AND next_attempt_at <= ? ORDER BY next_attempt_at`).all(now).map(toDelivery);
+    }
+    /** Sends cut off mid-flight by a restart: whether they arrived is unknown. Returns the turns affected. */
+    settleInterruptedDeliveries(now) {
+        const ids = this.db.prepare(`SELECT turn_id FROM agent_deliveries WHERE state = 'sending'`).all().map((row) => str(row.turn_id));
+        this.db
+            .prepare(`UPDATE agent_deliveries SET state = 'unknown', error_code = 'CHANNEL_SEND_OUTCOME_UNKNOWN', error_message = 'The Host restarted while the reply was being sent', retryable = 0, next_attempt_at = NULL, updated_at = ? WHERE state = 'sending'`)
+            .run(now);
+        return ids;
+    }
+    /** The most recent delivery of an agent that did not get through, for the channel status line. */
+    latestUndelivered(agentId, projectKey) {
+        const row = this.db
+            .prepare(`SELECT d.* FROM agent_deliveries d JOIN agent_sessions s ON s.session_id = d.session_id
+          WHERE s.project_key = ? AND s.agent_id = ? AND d.state IN ('failed', 'unknown')
+          ORDER BY d.updated_at DESC LIMIT 1`)
+            .get(projectKey, agentId);
+        return row ? toDelivery(row) : undefined;
+    }
+    setTurnStatus(turnId, status) {
+        this.db.prepare(`UPDATE agent_turns SET status = ? WHERE turn_id = ?`).run(status, turnId);
+    }
+    getTurn(turnId) {
+        const row = this.db.prepare(`SELECT * FROM agent_turns WHERE turn_id = ?`).get(turnId);
+        return row ? toTurn(row) : undefined;
+    }
+    listTurns(sessionId) {
+        return this.db.prepare(`SELECT * FROM agent_turns WHERE session_id = ? ORDER BY seq`).all(sessionId).map(toTurn);
+    }
+    /** Turns left `running` by a host that stopped mid-turn. */
+    /** Turns a restart is about to fail: they were mid-flight when the Host went down. */
+    interruptedTurnIds() {
+        return this.db.prepare(`SELECT turn_id FROM agent_turns WHERE status IN ('running', 'waiting')`).all().map((row) => str(row.turn_id));
+    }
+    /** Give an unanswered user message to a new turn, so a retry does not repeat it in the transcript. */
+    moveMessageToTurn(messageId, turnId) {
+        this.db.prepare(`UPDATE agent_messages SET turn_id = ? WHERE message_id = ?`).run(turnId, messageId);
+    }
+    failInterruptedTurns(now) {
+        return this.transaction(() => {
+            const result = this.db
+                .prepare(`UPDATE agent_turns SET status = 'failed', error_code = 'agent.host_restarted', ended_at = ?
+            WHERE status IN ('running', 'waiting')`)
+                .run(now);
+            this.db
+                .prepare(`UPDATE agent_sessions SET status = 'open', updated_at = ? WHERE status IN ('running', 'waiting')`)
+                .run(now);
+            this.db
+                .prepare(`UPDATE agent_approvals SET status = 'expired' WHERE status = 'pending'`)
+                .run();
+            return result.changes;
+        });
+    }
+    insertSpan(span) {
+        this.db
+            .prepare(`INSERT INTO agent_spans
+           (span_id, turn_id, parent_span_id, name, kind, status, started_at, ended_at, duration_ms,
+            input_tokens, output_tokens, attributes_json, input_text, output_text)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(span.id, span.turnId, span.parentSpanId, span.name, span.kind, span.status, span.startedAt, span.endedAt, span.durationMs, span.inputTokens, span.outputTokens, JSON.stringify(span.attributes), span.inputText, span.outputText);
+    }
+    listSpansForTurn(turnId) {
+        return this.db.prepare(`SELECT * FROM agent_spans WHERE turn_id = ? ORDER BY started_at, span_id`).all(turnId).map(toSpan);
+    }
+    listSpansForSession(sessionId) {
+        return this.db
+            .prepare(`SELECT s.* FROM agent_spans s JOIN agent_turns t ON t.turn_id = s.turn_id
+            WHERE t.session_id = ? ORDER BY t.seq, s.started_at, s.span_id`)
+            .all(sessionId).map(toSpan);
+    }
+    recordEvalScore(score) {
+        this.db
+            .prepare(`INSERT INTO agent_eval_scores (turn_id, metric, score, recorded_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT (turn_id, metric) DO UPDATE SET score = excluded.score, recorded_at = excluded.recorded_at`)
+            .run(score.turnId, score.metric, score.score, score.recordedAt);
+    }
+    listEvalScores(sessionId) {
+        return this.db
+            .prepare(`SELECT e.* FROM agent_eval_scores e JOIN agent_turns t ON t.turn_id = e.turn_id
+            WHERE t.session_id = ? ORDER BY t.seq`)
+            .all(sessionId).map((row) => ({
+            turnId: str(row.turn_id),
+            metric: str(row.metric),
+            score: Number(row.score),
+            recordedAt: str(row.recorded_at),
+        }));
+    }
+    /* ---------- approvals ---------- */
+    insertApproval(approval) {
+        this.db
+            .prepare(`INSERT INTO agent_approvals
+           (approval_id, session_id, turn_id, tool, payload_json, payload_hash, status, created_at, expires_at,
+            decided_at, actor_json)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(approval.id, approval.sessionId, approval.turnId, approval.tool, JSON.stringify(approval.payload), approval.payloadHash, approval.status, approval.createdAt, approval.expiresAt, approval.decidedAt, approval.actor ? JSON.stringify(approval.actor) : null);
+    }
+    getPendingApproval(sessionId) {
+        const row = this.db
+            .prepare(`SELECT * FROM agent_approvals WHERE session_id = ? AND status = 'pending'`)
+            .get(sessionId);
+        return row ? toApproval(row) : undefined;
+    }
+    findApprovalByPayload(sessionId, payloadHash) {
+        const row = this.db
+            .prepare(`SELECT * FROM agent_approvals WHERE session_id = ? AND payload_hash = ? ORDER BY created_at DESC LIMIT 1`)
+            .get(sessionId, payloadHash);
+        return row ? toApproval(row) : undefined;
+    }
+    listApprovals(sessionId) {
+        return this.db
+            .prepare(`SELECT * FROM agent_approvals WHERE session_id = ? ORDER BY created_at`)
+            .all(sessionId).map(toApproval);
+    }
+    listPendingApprovals(projectKey) {
+        return this.db
+            .prepare(`SELECT a.*, s.agent_id FROM agent_approvals a JOIN agent_sessions s ON s.session_id = a.session_id
+            WHERE s.project_key = ? AND a.status = 'pending' ORDER BY a.created_at`)
+            .all(projectKey).map((row) => ({ ...toApproval(row), agentId: str(row.agent_id) }));
+    }
+    decideApproval(approvalId, patch) {
+        this.db
+            .prepare(`UPDATE agent_approvals SET status = ?, decided_at = ?, actor_json = ?
+          WHERE approval_id = ? AND status = 'pending'`)
+            .run(patch.status, patch.decidedAt, patch.actor ? JSON.stringify(patch.actor) : null, approvalId);
+    }
+    /** Expire every pending approval past its deadline; returns the affected approvals. */
+    expireApprovals(now) {
+        return this.transaction(() => {
+            const rows = this.db
+                .prepare(`SELECT approval_id, session_id FROM agent_approvals WHERE status = 'pending' AND expires_at <= ?`)
+                .all(now);
+            for (const row of rows) {
+                this.decideApproval(str(row.approval_id), { status: "expired", decidedAt: now, actor: null });
+            }
+            return rows.map((row) => ({ approvalId: str(row.approval_id), sessionId: str(row.session_id) }));
+        });
+    }
+    /** Close (as expired) the pending approvals raised by a turn that is over; returns their ids. */
+    closePendingApprovalsOfTurn(turnId, now) {
+        return this.transaction(() => {
+            const rows = this.db.prepare(`SELECT approval_id FROM agent_approvals WHERE turn_id = ? AND status = 'pending'`).all(turnId);
+            for (const row of rows)
+                this.decideApproval(str(row.approval_id), { status: "expired", decidedAt: now, actor: null });
+            return rows.map((row) => str(row.approval_id));
+        });
+    }
+    getApproval(approvalId) {
+        const row = this.db.prepare(`SELECT * FROM agent_approvals WHERE approval_id = ?`).get(approvalId);
+        return row ? toApproval(row) : undefined;
+    }
+    markPayloadExecuted(sessionId, payloadHash, now) {
+        this.db
+            .prepare(`INSERT OR IGNORE INTO agent_executed_payloads (session_id, payload_hash, executed_at) VALUES (?, ?, ?)`)
+            .run(sessionId, payloadHash, now);
+    }
+    hasExecutedPayload(sessionId, payloadHash) {
+        return (this.db
+            .prepare(`SELECT 1 FROM agent_executed_payloads WHERE session_id = ? AND payload_hash = ?`)
+            .get(sessionId, payloadHash) !== undefined);
+    }
+    /* ---------- communications and schedules ---------- */
+    /** True the first time a provider event is seen for this project. */
+    rememberInboundEvent(projectKey, dedupeKey, now) {
+        return (this.db
+            .prepare(`INSERT OR IGNORE INTO agent_inbound_events (project_key, dedupe_key, received_at) VALUES (?, ?, ?)`)
+            .run(projectKey, dedupeKey, now).changes === 1);
+    }
+    getOutboundState(sessionId, operationKey) {
+        const row = this.db
+            .prepare(`SELECT state FROM agent_outbound_sends WHERE session_id = ? AND operation_key = ?`)
+            .get(sessionId, operationKey);
+        return row ? str(row.state) : undefined;
+    }
+    setOutboundState(sessionId, operationKey, state, now) {
+        this.db
+            .prepare(`INSERT INTO agent_outbound_sends (session_id, operation_key, state, updated_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT (session_id, operation_key) DO UPDATE SET state = excluded.state, updated_at = excluded.updated_at`)
+            .run(sessionId, operationKey, state, now);
+    }
+    getScheduleNextRun(projectKey, agentId) {
+        const row = this.db
+            .prepare(`SELECT next_run_at FROM agent_schedules WHERE project_key = ? AND agent_id = ?`)
+            .get(projectKey, agentId);
+        return row ? str(row.next_run_at) : undefined;
+    }
+    setScheduleNextRun(projectKey, agentId, nextRunAt) {
+        this.db
+            .prepare(`INSERT INTO agent_schedules (project_key, agent_id, next_run_at) VALUES (?, ?, ?)
+         ON CONFLICT (project_key, agent_id) DO UPDATE SET next_run_at = excluded.next_run_at`)
+            .run(projectKey, agentId, nextRunAt);
+    }
+}

package/dist/agents/trace.d.ts

@@ -0,0 +1,27 @@
+import type { AgentTraceCapture } from "../config/loadAgent.js";
+import type { AgentSpan } from "./store.js";
+export type SpanKind = "agent" | "model" | "tool" | "sub_agent" | "guardrail" | "gate" | "internal";
+export type SpanStatus = "ok" | "error" | "cancelled";
+export type SpanDraft = {
+    turnId: string;
+    parentSpanId?: string | null;
+    name: string;
+    kind: SpanKind;
+    status: SpanStatus;
+    startedAt: Date;
+    endedAt?: Date;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    attributes?: Record<string, unknown>;
+    input?: string;
+    output?: string;
+};
+/**
+ * Apply the revision's capture mode to a span before it is stored:
+ * `off` records nothing, `metadata` drops prompt/argument/result bodies, and
+ * `full` keeps them after secret redaction. Redaction happens here, before
+ * storage, so export never sees an unredacted body.
+ */
+export declare function prepareSpan(capture: AgentTraceCapture, draft: SpanDraft): AgentSpan | null;