stageflow 0.36.0 → 0.40.0

package/dist/agents/sessions.d.ts

@@ -0,0 +1,38 @@
+import type { OtlpSink } from "./otlpSink.js";
+import type { ConversationBackend } from "./runtime/types.js";
+import type { AgentService, AgentSessionDetail } from "./service.js";
+export type { ConversationBackend, ConversationMessage } from "./runtime/types.js";
+export type SendTurnInput = {
+    projectRoot: string;
+    agentId: string;
+    sessionId?: string;
+    text: string;
+    /** Who sent the message (display name or channel identity). */
+    author?: string | null;
+    /** Where a new session came from: console, cli, mcp, schedule, or a provider id. */
+    source?: string;
+    onDelta?: (text: string) => void;
+    onSessionOpened?: (sessionId: string) => void;
+    /** Retry this earlier, interrupted turn: its user message is reused, not asked again. */
+    resumeTurnId?: string;
+};
+export type ConversationOptions = {
+    service: AgentService;
+    backend: ConversationBackend;
+    otlpSink?: OtlpSink | undefined;
+    logError?: (message: string) => void;
+};
+/** One turn: open (if needed) → record user message → model + tools → guardrails → record reply. */
+export declare class AgentConversation {
+    private readonly options;
+    private readonly depth;
+    private readonly parentSignal?;
+    private controller;
+    constructor(options: ConversationOptions, depth?: number, parentSignal?: AbortSignal | undefined);
+    stop(): void;
+    send(input: SendTurnInput): Promise<AgentSessionDetail>;
+    private runTurn;
+    private score;
+    /** Best-effort push to the configured OTLP collector; a collector outage never fails a turn. */
+    private exportLive;
+}

package/dist/agents/sessions.js

@@ -0,0 +1,321 @@
+import { randomBytes } from "node:crypto";
+import { assertDelegateAllowed } from "./delegate.js";
+import { AgentError, isAgentError } from "./errors.js";
+import { guardedStream } from "./guardrails.js";
+import { fitHistory } from "./historyFit.js";
+import { isToolGranted, requiresAskFirst } from "./policy.js";
+import { prepareSpan } from "./trace.js";
+const GROUNDEDNESS_PROMPT = (reply, evidence) => [
+    "Rate how well the ANSWER is supported by the TOOL OUTPUTS, from 0 (unsupported or contradicted) to 1 (fully supported).",
+    "Reply with only the number.",
+    "",
+    "TOOL OUTPUTS:",
+    ...evidence.map((e, i) => `[${i + 1}] ${e.slice(0, 4000)}`),
+    "",
+    "ANSWER:",
+    reply.slice(0, 8000),
+].join("\n");
+function spanId() {
+    return randomBytes(8).toString("hex");
+}
+function toJson(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/** One turn: open (if needed) → record user message → model + tools → guardrails → record reply. */
+export class AgentConversation {
+    options;
+    depth;
+    parentSignal;
+    controller = null;
+    constructor(options, depth = 0, parentSignal) {
+        this.options = options;
+        this.depth = depth;
+        this.parentSignal = parentSignal;
+    }
+    stop() {
+        this.controller?.abort();
+    }
+    async send(input) {
+        const { service, backend } = this.options;
+        const controller = new AbortController();
+        this.controller = controller;
+        const onParentAbort = () => controller.abort();
+        this.parentSignal?.addEventListener("abort", onParentAbort, { once: true });
+        try {
+            let sessionId = input.sessionId;
+            if (!sessionId) {
+                const opened = await service.openSession(input.projectRoot, input.agentId, {
+                    source: input.source ?? "console",
+                    sourceRef: input.author ?? null,
+                });
+                sessionId = opened.id;
+                input.onSessionOpened?.(sessionId);
+            }
+            const active = await service.beginTurn(input.projectRoot, sessionId, {
+                text: input.text,
+                author: input.author ?? null,
+                ...(input.resumeTurnId ? { resumeTurnId: input.resumeTurnId } : {}),
+            });
+            if (active.session.agentId !== input.agentId) {
+                await service.completeTurn(input.projectRoot, active.turn.id, { status: "failed", errorCode: "agent.session_not_found" });
+                throw new AgentError("agent.session_not_found");
+            }
+            try {
+                return await this.runTurn(input, sessionId, active, controller);
+            }
+            catch (error) {
+                // A failure outside the model call (storage, spans) must not leave the session stuck running.
+                const state = (await service.getSession(input.projectRoot, sessionId).catch(() => undefined))?.turns.find((t) => t.id === active.turn.id);
+                if (state && (state.status === "running" || state.status === "waiting")) {
+                    await service.completeTurn(input.projectRoot, active.turn.id, {
+                        status: "failed",
+                        errorCode: isAgentError(error) ? error.code : "agent.backend_failed",
+                    }).catch(() => undefined);
+                }
+                throw error;
+            }
+        }
+        finally {
+            this.parentSignal?.removeEventListener("abort", onParentAbort);
+            if (this.controller === controller)
+                this.controller = null;
+        }
+    }
+    async runTurn(input, sessionId, active, controller) {
+        const { service, backend } = this.options;
+        const { definition, turn } = active;
+        const capture = definition.observability.capture;
+        const rootId = spanId();
+        const startedAt = new Date();
+        const record = (draft) => {
+            const span = prepareSpan(capture, draft);
+            if (span)
+                service.recordSpan(input.projectRoot, span);
+        };
+        const toolStarts = new Map();
+        let stopReason;
+        let gateChain = Promise.resolve();
+        const gateOne = async (call) => {
+            if (!isToolGranted(definition, call.tool)) {
+                return { allow: false, reason: `Tool ${call.tool} is not granted to this agent.` };
+            }
+            if (!requiresAskFirst(definition, call.tool))
+                return { allow: true };
+            const gateStart = new Date();
+            const approval = await service.requestApproval(input.projectRoot, sessionId, {
+                tool: call.tool,
+                payload: call.input,
+                turnId: turn.id,
+            });
+            if (approval.status === "approved")
+                return { allow: true };
+            // Parked unless the decision already landed between the request and now.
+            const parked = await service.waitOnApproval(input.projectRoot, turn.id, approval.id);
+            let outcome;
+            if (parked === "waiting") {
+                outcome = await service.approvalBroker.wait(approval.id, { expiresAt: approval.expiresAt, signal: controller.signal, now: () => service.clockMs() });
+                if (outcome === "expired")
+                    await service.pendingApprovals(input.projectRoot);
+                // A stopped turn must not leave its approval open: it could be approved later with nobody waiting.
+                if (outcome === "aborted")
+                    await service.closeApproval(input.projectRoot, approval.id);
+                else
+                    await service.resumeTurn(input.projectRoot, turn.id);
+            }
+            else {
+                outcome = parked === "inactive" ? "aborted" : parked;
+            }
+            record({
+                turnId: turn.id,
+                parentSpanId: rootId,
+                name: `approval ${call.tool}`,
+                kind: "gate",
+                status: outcome === "approved" ? "ok" : "error",
+                startedAt: gateStart,
+                endedAt: new Date(),
+                attributes: { "stageflow.approval.outcome": outcome, "gen_ai.tool.name": call.tool },
+            });
+            if (outcome === "approved")
+                return { allow: true };
+            if (outcome === "aborted")
+                return { allow: false, reason: "The turn was stopped.", stopTurn: true };
+            if (outcome === "denied")
+                return { allow: false, reason: `The operator denied ${call.tool}. Do not retry it; continue without it or explain.` };
+            if (definition.approvals.on_timeout === "deny") {
+                stopReason = { code: "agent.approval_expired", message: "Approval timed out" };
+                return { allow: false, reason: "Approval timed out; the turn was ended.", stopTurn: true };
+            }
+            return { allow: false, reason: `Approval for ${call.tool} timed out and the action was skipped. Continue without it.` };
+        };
+        const hooks = {
+            gate: (call) => {
+                const next = gateChain.then(() => gateOne(call));
+                gateChain = next.catch(() => undefined);
+                return next;
+            },
+            toolStarted: (call) => {
+                toolStarts.set(call.id, new Date());
+            },
+            toolFinished: (call, result) => {
+                const isAgent = call.tool.startsWith("agent:");
+                record({
+                    turnId: turn.id,
+                    parentSpanId: rootId,
+                    name: isAgent ? `invoke_agent ${call.tool.slice(6)}` : `execute_tool ${call.tool}`,
+                    kind: (isAgent ? "sub_agent" : "tool"),
+                    status: result.ok ? "ok" : "error",
+                    startedAt: toolStarts.get(call.id) ?? new Date(),
+                    endedAt: new Date(),
+                    attributes: { "gen_ai.tool.name": call.tool },
+                    input: toJson(call.input),
+                    output: result.output,
+                });
+            },
+            modelFinished: (info) => {
+                record({
+                    turnId: turn.id,
+                    parentSpanId: rootId,
+                    name: "chat",
+                    kind: "model",
+                    status: "ok",
+                    startedAt: info.startedAt,
+                    endedAt: info.endedAt,
+                    usage: { inputTokens: info.inputTokens, outputTokens: info.outputTokens },
+                    attributes: {
+                        "gen_ai.system": definition.model.backend,
+                        ...(info.model ? { "gen_ai.request.model": info.model } : {}),
+                        "gen_ai.usage.cost_usd": info.costUsd,
+                    },
+                });
+            },
+            delegate: async (agentId, message) => {
+                assertDelegateAllowed(definition, agentId, this.depth);
+                const child = new AgentConversation(this.options, this.depth + 1, controller.signal);
+                try {
+                    const detail = await child.send({
+                        projectRoot: input.projectRoot,
+                        agentId,
+                        text: message,
+                        source: "agent",
+                        author: active.session.agentId,
+                    });
+                    return [...detail.messages].reverse().find((m) => m.role === "assistant")?.text ?? "(no reply)";
+                }
+                catch (error) {
+                    return `Sub-agent ${agentId} failed: ${isAgentError(error) ? error.code : "error"}${error instanceof Error && error.message !== error.code ? ` (${error.message})` : ""}`;
+                }
+            },
+        };
+        const stream = guardedStream(definition.guardrails, input.onDelta);
+        let result;
+        try {
+            const transcript = [...active.history, active.userMessage].map((m) => ({ role: m.role, text: m.text }));
+            result = await backend.complete({
+                sessionId,
+                projectRoot: input.projectRoot,
+                definition,
+                messages: [...fitHistory(transcript.slice(0, -1), definition.limits.long_context), transcript.at(-1)],
+                signal: controller.signal,
+                onDelta: (text) => stream.push(text),
+                hooks,
+            });
+        }
+        catch (error) {
+            stream.discard();
+            const code = isAgentError(error) ? error.code : "agent.backend_failed";
+            record({ turnId: turn.id, name: `invoke_agent ${definition.id}`, kind: "agent", status: "error", startedAt, endedAt: new Date(), attributes: { "error.type": code } });
+            await service.completeTurn(input.projectRoot, turn.id, { status: "failed", errorCode: code });
+            this.exportLive(input.projectRoot, definition, turn.id);
+            throw error;
+        }
+        const cancelled = controller.signal.aborted;
+        const usage = result.usage;
+        const endRoot = (status) => {
+            const rootSpan = prepareSpan(capture, {
+                turnId: turn.id,
+                name: `invoke_agent ${definition.id}`,
+                kind: "agent",
+                status,
+                startedAt,
+                endedAt: new Date(),
+                ...(usage ? { usage: { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens } } : {}),
+                attributes: {
+                    "gen_ai.agent.name": definition.id,
+                    "stageflow.agent.revision": active.session.revision,
+                    ...(definition.model.id ? { "gen_ai.request.model": definition.model.id } : {}),
+                },
+                input: input.text,
+                output: result.text,
+            });
+            if (rootSpan)
+                service.recordSpan(input.projectRoot, { ...rootSpan, id: rootId });
+        };
+        const guard = stream.release(result.text);
+        if (!guard.ok) {
+            record({ turnId: turn.id, parentSpanId: rootId, name: "guardrail", kind: "guardrail", status: "error", startedAt: new Date(), endedAt: new Date(), attributes: { "stageflow.guardrail.pattern": guard.pattern } });
+            endRoot("error");
+            await service.completeTurn(input.projectRoot, turn.id, {
+                status: "failed",
+                errorCode: "agent.guardrail_blocked",
+                ...(usage ? { usage, costUsd: usage.costUsd } : {}),
+            });
+            this.exportLive(input.projectRoot, definition, turn.id);
+            throw new AgentError("agent.guardrail_blocked", `Reply blocked by guardrail ${guard.pattern}`);
+        }
+        const evalScores = await this.score(input.projectRoot, definition, turn.id, rootId, result, controller.signal, cancelled || stopReason !== undefined);
+        const failed = stopReason !== undefined;
+        endRoot(cancelled ? "cancelled" : failed ? "error" : "ok");
+        const detail = await service.completeTurn(input.projectRoot, turn.id, {
+            status: failed ? "failed" : cancelled ? "cancelled" : "succeeded",
+            ...(failed ? { errorCode: stopReason.code } : {}),
+            assistantText: result.text,
+            ...(usage ? { usage, costUsd: usage.costUsd } : {}),
+            ...(evalScores.length > 0 ? { evalScores } : {}),
+        });
+        this.exportLive(input.projectRoot, definition, turn.id);
+        return detail;
+    }
+    async score(projectRoot, definition, turnId, rootId, result, signal, skip) {
+        const { backend, service } = this.options;
+        if (skip || !definition.evals.groundedness || !backend.judge || result.toolOutputs.length === 0 || !result.text.trim())
+            return [];
+        const startedAt = new Date();
+        try {
+            const raw = await backend.judge({ projectRoot, definition, prompt: GROUNDEDNESS_PROMPT(result.text, result.toolOutputs), signal });
+            const match = /(?:^|[^\d.])(1(?:\.0+)?|0?\.\d+|0)(?![\d])/.exec(raw.trim());
+            if (!match)
+                throw new Error("no score in judge output");
+            const score = Math.min(1, Math.max(0, Number(match[1])));
+            const span = prepareSpan(definition.observability.capture, {
+                turnId, parentSpanId: rootId, name: "eval groundedness", kind: "guardrail", status: "ok", startedAt, endedAt: new Date(),
+                attributes: { "gen_ai.evaluation.name": "groundedness", "gen_ai.evaluation.score.value": score },
+            });
+            if (span)
+                service.recordSpan(projectRoot, span);
+            return [{ metric: "groundedness", score }];
+        }
+        catch (error) {
+            this.options.logError?.(`groundedness eval failed: ${error instanceof Error ? error.message : String(error)}`);
+            return [];
+        }
+    }
+    /** Best-effort push to the configured OTLP collector; a collector outage never fails a turn. */
+    exportLive(projectRoot, definition, turnId) {
+        const sink = this.options.otlpSink;
+        if (!sink || !definition.observability.otlp || definition.observability.capture === "off")
+            return;
+        void (async () => {
+            try {
+                await sink(this.options.service.exportTurnOtlp(projectRoot, turnId));
+            }
+            catch (error) {
+                this.options.logError?.(`OTLP export failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        })();
+    }
+}

package/dist/agents/store.d.ts

@@ -0,0 +1,277 @@
+import type Database from "better-sqlite3";
+import { type AgentDefinition, type AgentIssue } from "../config/loadAgent.js";
+/**
+ * SQLite persistence for project agents (migration 013). Every method is a
+ * single statement or an explicit transaction; nothing here swallows a
+ * storage error. Business rules live in AgentService.
+ */
+export type RevisionSource = "console" | "file" | "author" | "restore" | "api";
+/**
+ * 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 declare const SESSION_STATUSES: readonly ["open", "running", "waiting", "held", "closed"];
+export type SessionStatus = (typeof SESSION_STATUSES)[number];
+export declare function isSessionStatus(value: string): value is SessionStatus;
+export type TurnStatus = "running" | "waiting" | "succeeded" | "failed" | "cancelled";
+export type ApprovalStatus = "pending" | "approved" | "denied" | "expired";
+export type ApprovalActor = {
+    kind: "operator";
+} | {
+    kind: "channel";
+    channelId: string;
+};
+export type OutboundSendState = "submitted" | "unknown";
+export type AgentDefinitionRow = {
+    agentId: string;
+    currentRevision: number;
+    archived: boolean;
+    fileHash: string | null;
+    issues: AgentIssue[];
+    createdAt: string;
+    updatedAt: string;
+};
+export type AgentRevision = {
+    agentId: string;
+    revision: number;
+    definition: AgentDefinition;
+    yaml: string;
+    source: RevisionSource;
+    author: string | null;
+    summary: string | null;
+    restoredFrom: number | null;
+    createdAt: string;
+};
+export type AgentRevisionMeta = Omit<AgentRevision, "definition" | "yaml">;
+export type AgentSession = {
+    id: string;
+    agentId: string;
+    revision: number;
+    backend: "pi" | "claude";
+    status: SessionStatus;
+    source: string;
+    sourceRef: string | null;
+    threadKey: string | null;
+    title: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+/** A session row plus rollups over its turns, for list views. */
+export type AgentSessionListItem = AgentSession & {
+    turnCount: number;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number | null;
+    lastTurnStatus: TurnStatus | null;
+};
+export type AgentMessage = {
+    id: string;
+    sessionId: string;
+    seq: number;
+    turnId: string | null;
+    role: "user" | "assistant";
+    author: string | null;
+    text: string;
+    createdAt: string;
+};
+export type AgentTurn = {
+    id: string;
+    sessionId: string;
+    seq: number;
+    revision: number;
+    traceId: string;
+    status: TurnStatus;
+    errorCode: string | null;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    costUsd: number | null;
+    startedAt: string;
+    endedAt: string | null;
+};
+export type DeliveryState = "pending" | "sending" | "delivered" | "failed" | "unknown";
+/** A reply on a channel and how getting it to the person went. */
+export type AgentDelivery = {
+    turnId: string;
+    sessionId: string;
+    connectionId: string;
+    provider: string;
+    replyTo: string;
+    text: string;
+    state: DeliveryState;
+    attempts: number;
+    errorCode: string | null;
+    errorMessage: string | null;
+    /** True when a later attempt may work (a definite failure that is not a configuration problem). */
+    retryable: boolean;
+    nextAttemptAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type AgentSpan = {
+    id: string;
+    turnId: string;
+    parentSpanId: string | null;
+    name: string;
+    kind: string;
+    status: string;
+    startedAt: string;
+    endedAt: string | null;
+    durationMs: number | null;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    attributes: Record<string, unknown>;
+    inputText: string | null;
+    outputText: string | null;
+};
+export type AgentApproval = {
+    id: string;
+    sessionId: string;
+    turnId: string | null;
+    tool: string;
+    payload: Record<string, unknown>;
+    payloadHash: string;
+    status: ApprovalStatus;
+    createdAt: string;
+    expiresAt: string;
+    decidedAt: string | null;
+    actor: ApprovalActor | null;
+};
+export type AgentEvalScore = {
+    turnId: string;
+    metric: string;
+    score: number;
+    recordedAt: string;
+};
+export type SessionQuery = {
+    status?: SessionStatus;
+    source?: string;
+    search?: string;
+    limit: number;
+    /** Opaque cursor from a previous page. */
+    cursor?: string;
+};
+export type SessionStats = {
+    total: number;
+    active: number;
+    last7Days: number;
+    waiting: number;
+    lastActivityAt: string | null;
+    /** Turns that ended in the window, and how many of those succeeded. */
+    turnsFinished7d: number;
+    turnsSucceeded7d: number;
+    /** Sum of known turn costs in the window; null when no turn reported a cost. */
+    cost7d: number | null;
+    /** Sum of known turn costs across every session, all time; null when no turn reported a cost. */
+    costTotal: number | null;
+};
+export declare function agentProjectKey(projectRoot: string): string;
+export declare class AgentStore {
+    private readonly db;
+    constructor(db: Database.Database);
+    transaction<T>(work: () => T): T;
+    listDefinitions(projectKey: string): AgentDefinitionRow[];
+    getDefinition(projectKey: string, agentId: string): AgentDefinitionRow | undefined;
+    /** Record the file's latest observed state without changing the revision (invalid edit, archive, restore). */
+    updateDefinitionState(projectKey: string, agentId: string, patch: {
+        archived?: boolean;
+        fileHash?: string | null;
+        issues?: AgentIssue[];
+    }, now: string): void;
+    /** Append the next revision and make it current. Returns the new revision number. */
+    appendRevision(projectKey: string, input: {
+        definition: AgentDefinition;
+        yaml: string;
+        source: RevisionSource;
+        author?: string | null;
+        summary?: string | null;
+        restoredFrom?: number | null;
+        fileHash: string;
+        now: string;
+    }): number;
+    /** First sighting of a file that never parsed: no revision yet, only issues. */
+    recordInvalidNewDefinition(projectKey: string, agentId: string, fileHash: string, issues: AgentIssue[], now: string): void;
+    getRevision(projectKey: string, agentId: string, revision: number): AgentRevision | undefined;
+    listRevisions(projectKey: string, agentId: string): AgentRevisionMeta[];
+    insertSession(projectKey: string, session: AgentSession): void;
+    getSession(sessionId: string): (AgentSession & {
+        projectKey: string;
+    }) | undefined;
+    findSessionByThread(projectKey: string, agentId: string, threadKey: string): AgentSession | undefined;
+    updateSession(sessionId: string, patch: Partial<Pick<AgentSession, "status" | "backend" | "title">>, now: string): void;
+    /** One agent's sessions, or every agent's when `agentId` is omitted. */
+    listSessions(projectKey: string, agentId: string | undefined, query: SessionQuery): {
+        sessions: AgentSessionListItem[];
+        nextCursor: string | null;
+    };
+    /** One visitor's sessions on one agent, newest first (public web chat). */
+    listSessionsForRef(projectKey: string, agentId: string, source: string, sourceRef: string, limit: number): AgentSession[];
+    /** Stats for one agent, or for every agent when `agentId` is omitted. */
+    sessionStats(projectKey: string, agentId: string | undefined, since: string): SessionStats;
+    /** Ids of every session an agent has had, for releasing what a runtime holds for them. */
+    sessionIdsOf(projectKey: string, agentId: string): string[];
+    appendMessage(message: Omit<AgentMessage, "seq">): AgentMessage;
+    listMessages(sessionId: string): AgentMessage[];
+    insertTurn(turn: Omit<AgentTurn, "seq">): AgentTurn;
+    finishTurn(turnId: string, patch: Pick<AgentTurn, "status" | "errorCode" | "inputTokens" | "outputTokens" | "costUsd" | "endedAt">): void;
+    /** Change a finished turn's outcome after the fact, for example when its reply could not be delivered. */
+    setTurnOutcome(turnId: string, status: TurnStatus, errorCode: string | null): void;
+    insertDelivery(delivery: AgentDelivery): void;
+    getDelivery(turnId: string): AgentDelivery | undefined;
+    listDeliveries(sessionId: string): AgentDelivery[];
+    updateDelivery(turnId: string, patch: Partial<Pick<AgentDelivery, "state" | "attempts" | "errorCode" | "errorMessage" | "retryable" | "nextAttemptAt">>, now: string): void;
+    /**
+     * 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: string, states: string[], now: string, options?: {
+        dueRetry?: boolean;
+    }): AgentDelivery | undefined;
+    /** Failed deliveries a retry is due for. */
+    dueDeliveries(now: string): AgentDelivery[];
+    /** Sends cut off mid-flight by a restart: whether they arrived is unknown. Returns the turns affected. */
+    settleInterruptedDeliveries(now: string): string[];
+    /** The most recent delivery of an agent that did not get through, for the channel status line. */
+    latestUndelivered(agentId: string, projectKey: string): AgentDelivery | undefined;
+    setTurnStatus(turnId: string, status: TurnStatus): void;
+    getTurn(turnId: string): AgentTurn | undefined;
+    listTurns(sessionId: string): AgentTurn[];
+    /** 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(): string[];
+    /** Give an unanswered user message to a new turn, so a retry does not repeat it in the transcript. */
+    moveMessageToTurn(messageId: string, turnId: string): void;
+    failInterruptedTurns(now: string): number;
+    insertSpan(span: AgentSpan): void;
+    listSpansForTurn(turnId: string): AgentSpan[];
+    listSpansForSession(sessionId: string): AgentSpan[];
+    recordEvalScore(score: AgentEvalScore): void;
+    listEvalScores(sessionId: string): AgentEvalScore[];
+    insertApproval(approval: AgentApproval): void;
+    getPendingApproval(sessionId: string): AgentApproval | undefined;
+    findApprovalByPayload(sessionId: string, payloadHash: string): AgentApproval | undefined;
+    listApprovals(sessionId: string): AgentApproval[];
+    listPendingApprovals(projectKey: string): Array<AgentApproval & {
+        agentId: string;
+    }>;
+    decideApproval(approvalId: string, patch: {
+        status: Exclude<ApprovalStatus, "pending">;
+        decidedAt: string;
+        actor: ApprovalActor | null;
+    }): void;
+    /** Expire every pending approval past its deadline; returns the affected approvals. */
+    expireApprovals(now: string): Array<{
+        approvalId: string;
+        sessionId: string;
+    }>;
+    /** Close (as expired) the pending approvals raised by a turn that is over; returns their ids. */
+    closePendingApprovalsOfTurn(turnId: string, now: string): string[];
+    getApproval(approvalId: string): AgentApproval | undefined;
+    markPayloadExecuted(sessionId: string, payloadHash: string, now: string): void;
+    hasExecutedPayload(sessionId: string, payloadHash: string): boolean;
+    /** True the first time a provider event is seen for this project. */
+    rememberInboundEvent(projectKey: string, dedupeKey: string, now: string): boolean;
+    getOutboundState(sessionId: string, operationKey: string): OutboundSendState | undefined;
+    setOutboundState(sessionId: string, operationKey: string, state: OutboundSendState, now: string): void;
+    getScheduleNextRun(projectKey: string, agentId: string): string | undefined;
+    setScheduleNextRun(projectKey: string, agentId: string, nextRunAt: string): void;
+}