@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/sessions/contracts.d.ts

@@ -0,0 +1,991 @@
+import { z } from 'zod';
+export declare const runStatusSchema: z.ZodEnum<{
+    queued: "queued";
+    running: "running";
+    waiting_for_approval: "waiting_for_approval";
+    waiting_for_input: "waiting_for_input";
+    interrupted: "interrupted";
+    completed: "completed";
+    failed: "failed";
+}>;
+export type RunStatus = z.infer<typeof runStatusSchema>;
+export declare const runEventTypeSchema: z.ZodEnum<{
+    completed: "completed";
+    failed: "failed";
+    started: "started";
+    "context.snapshot": "context.snapshot";
+    "message.delta": "message.delta";
+    "message.completed": "message.completed";
+    "message.steered": "message.steered";
+    "tool.started": "tool.started";
+    "tool.completed": "tool.completed";
+    "tool.refused": "tool.refused";
+    "retry.started": "retry.started";
+    "retry.ended": "retry.ended";
+    "compaction.started": "compaction.started";
+    "compaction.ended": "compaction.ended";
+    "approval.requested": "approval.requested";
+    "approval.resolved": "approval.resolved";
+    "question.requested": "question.requested";
+    "question.answered": "question.answered";
+    "extension.notice": "extension.notice";
+    "reaction.added": "reaction.added";
+    "agent.message": "agent.message";
+    "todo.updated": "todo.updated";
+    "checklist.updated": "checklist.updated";
+    checkpoint: "checkpoint";
+    heartbeat: "heartbeat";
+    "artifact.added": "artifact.added";
+    "file.changed": "file.changed";
+    "usage.updated": "usage.updated";
+    "account.status": "account.status";
+    "status.changed": "status.changed";
+}>;
+export type RunEventType = z.infer<typeof runEventTypeSchema>;
+/** Generic reference to content a provider stores outside the run-event stream. */
+export declare const toolAttachmentRefSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    mimeType: z.ZodString;
+}, z.core.$strict>;
+export declare const toolAttachmentRefsSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    mimeType: z.ZodString;
+}, z.core.$strict>>;
+export type ToolAttachmentRef = z.infer<typeof toolAttachmentRefSchema>;
+/**
+ * Why a call was refused before it ran (PROP-0050). The model still sees the reason as the call's
+ * result; this event says which rule refused it, so a reader need not match the text.
+ */
+export declare const refusalCodeSchema: z.ZodEnum<{
+    plan_mode: "plan_mode";
+    workspace: "workspace";
+    scope: "scope";
+    policy: "policy";
+    capability: "capability";
+    approval_denied: "approval_denied";
+    unattended: "unattended";
+    work_slice: "work_slice";
+    controller_unavailable: "controller_unavailable";
+}>;
+export type RefusalCode = z.infer<typeof refusalCodeSchema>;
+export interface Refusal {
+    code: RefusalCode;
+    reason: string;
+}
+export declare const QUESTION_SKETCH_MAX_LINES = 24;
+export declare const QUESTION_SKETCH_MAX_COLUMNS = 80;
+export declare const QUESTION_SKETCH_MAX_LENGTH: number;
+export declare const QUESTION_SKETCH_PATTERN = "^(?:[\\x20-\\x7e]{0,80})(?:\\n[\\x20-\\x7e]{0,80}){0,23}$";
+export declare const questionSketchSchema: z.ZodString;
+export declare function questionSketchError(uiSketch: unknown, options: readonly {
+    sketch?: unknown;
+}[]): string | undefined;
+export declare const questionOptionSchema: z.ZodObject<{
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    recommended: z.ZodOptional<z.ZodBoolean>;
+    sketch: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type QuestionOption = z.infer<typeof questionOptionSchema>;
+export interface QuestionAnswerProblem {
+    field: 'selection' | 'text' | 'notes';
+    message: string;
+}
+/**
+ * Why an answer to one question would be refused, or `null` when it may be accepted.
+ * The session registry and the front ends share this rule, so a form cannot build an answer
+ * the server rejects, and a refusal can name the field that needs attention.
+ */
+export declare function questionAnswerProblem(question: {
+    summary?: string;
+    options: readonly Pick<QuestionOption, 'label'>[];
+    multiSelect?: boolean;
+    allowText?: boolean;
+}, answer: {
+    selected: readonly string[];
+    text?: string;
+    notes?: Readonly<Record<string, string>>;
+}): QuestionAnswerProblem | null;
+/** One line of the run's todo list. The list has no ids: every update replaces all of it. */
+export declare const todoItemSchema: z.ZodObject<{
+    text: z.ZodString;
+    status: z.ZodEnum<{
+        completed: "completed";
+        pending: "pending";
+        in_progress: "in_progress";
+    }>;
+}, z.core.$strict>;
+export type TodoItem = z.infer<typeof todoItemSchema>;
+export declare const MAX_TODO_ITEMS = 50;
+export declare const MAX_CHECKPOINT_SUMMARY = 1200;
+export declare const MAX_CHECKPOINT_DONE = 20;
+export declare const MAX_CHECKPOINT_EVIDENCE = 5;
+export declare const MAX_CHECKPOINT_FILES = 20;
+export declare const MAX_CHECKPOINT_CHECKS = 8;
+export declare const MAX_CHECKPOINT_DECISIONS = 8;
+/**
+ * The handoff a reply writes when it reaches its work-slice budget. The harness validates and
+ * records it; the next slice is told where this one stopped from it (PROP-0041).
+ */
+export declare const checkpointItemSchema: z.ZodObject<{
+    item: z.ZodString;
+    evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const checkpointFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    why: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+export declare const checkpointCheckSchema: z.ZodObject<{
+    command: z.ZodString;
+    ok: z.ZodBoolean;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const checkpointDecisionSchema: z.ZodObject<{
+    what: z.ZodString;
+    why: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+export declare const checkpointReasonSchema: z.ZodEnum<{
+    budget: "budget";
+    stuck: "stuck";
+    "compaction-thrash": "compaction-thrash";
+    requested: "requested";
+}>;
+declare const checkpointPayload: z.ZodObject<{
+    summary: z.ZodString;
+    done: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        item: z.ZodString;
+        evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    next: z.ZodDefault<z.ZodString>;
+    blocked: z.ZodOptional<z.ZodString>;
+    files: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        why: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>>>;
+    checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        ok: z.ZodBoolean;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    decisions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        what: z.ZodString;
+        why: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>>>;
+    slice: z.ZodNumber;
+    reason: z.ZodEnum<{
+        budget: "budget";
+        stuck: "stuck";
+        "compaction-thrash": "compaction-thrash";
+        requested: "requested";
+    }>;
+}, z.core.$strict>;
+export type Checkpoint = z.infer<typeof checkpointPayload>;
+export type CheckpointItem = z.infer<typeof checkpointItemSchema>;
+export type CheckpointFile = z.infer<typeof checkpointFileSchema>;
+export type CheckpointCheck = z.infer<typeof checkpointCheckSchema>;
+export type CheckpointDecision = z.infer<typeof checkpointDecisionSchema>;
+/** Where a cost figure comes from: Pi reported it, or the tokens were priced at list rates. */
+export declare const costSourceSchema: z.ZodEnum<{
+    harness: "harness";
+    estimate: "estimate";
+    mixed: "mixed";
+}>;
+export type CostSource = z.infer<typeof costSourceSchema>;
+/** What one model request used. Token fields mean the same as on the run's totals. */
+export declare const usageRequestSchema: z.ZodObject<{
+    index: z.ZodNumber;
+    responseId: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodString>;
+    inputTokens: z.ZodOptional<z.ZodNumber>;
+    cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+    cacheWriteTokens: z.ZodOptional<z.ZodNumber>;
+    outputTokens: z.ZodOptional<z.ZodNumber>;
+    reasoningTokens: z.ZodOptional<z.ZodNumber>;
+    costUsd: z.ZodOptional<z.ZodNumber>;
+    costSource: z.ZodOptional<z.ZodEnum<{
+        harness: "harness";
+        estimate: "estimate";
+    }>>;
+    reasoningSummary: z.ZodOptional<z.ZodString>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    ttftMs: z.ZodOptional<z.ZodNumber>;
+    stopReason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type UsageRequest = z.infer<typeof usageRequestSchema>;
+/** Token totals so far in this run (cumulative for the run, not the native session). */
+export declare const usagePayloadSchema: z.ZodObject<{
+    inputTokens: z.ZodOptional<z.ZodNumber>;
+    outputTokens: z.ZodOptional<z.ZodNumber>;
+    cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+    cacheWriteTokens: z.ZodOptional<z.ZodNumber>;
+    reasoningTokens: z.ZodOptional<z.ZodNumber>;
+    costUsd: z.ZodOptional<z.ZodNumber>;
+    costSource: z.ZodOptional<z.ZodEnum<{
+        harness: "harness";
+        estimate: "estimate";
+        mixed: "mixed";
+    }>>;
+    requests: z.ZodOptional<z.ZodNumber>;
+    contextTokens: z.ZodOptional<z.ZodNumber>;
+    contextWindow: z.ZodOptional<z.ZodNumber>;
+    model: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodString>;
+    request: z.ZodOptional<z.ZodObject<{
+        index: z.ZodNumber;
+        responseId: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        provider: z.ZodOptional<z.ZodString>;
+        inputTokens: z.ZodOptional<z.ZodNumber>;
+        cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+        cacheWriteTokens: z.ZodOptional<z.ZodNumber>;
+        outputTokens: z.ZodOptional<z.ZodNumber>;
+        reasoningTokens: z.ZodOptional<z.ZodNumber>;
+        costUsd: z.ZodOptional<z.ZodNumber>;
+        costSource: z.ZodOptional<z.ZodEnum<{
+            harness: "harness";
+            estimate: "estimate";
+        }>>;
+        reasoningSummary: z.ZodOptional<z.ZodString>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        ttftMs: z.ZodOptional<z.ZodNumber>;
+        stopReason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type UsagePayload = z.infer<typeof usagePayloadSchema>;
+export declare const accountIssueCategorySchema: z.ZodEnum<{
+    unknown: "unknown";
+    auth_expired: "auth_expired";
+    rate_limited: "rate_limited";
+    quota: "quota";
+    network: "network";
+}>;
+export type AccountIssueCategory = z.infer<typeof accountIssueCategorySchema>;
+export declare const accountLimitSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    usedPercent: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    remainingPercent: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    resetsAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    windowMinutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    status: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    provider: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    kind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        error: "error";
+        window: "window";
+        rate: "rate";
+        credit: "credit";
+        configured: "configured";
+    }>>>;
+    unit: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        requests: "requests";
+        percent: "percent";
+        tokens: "tokens";
+        usd: "usd";
+        currency: "currency";
+        count: "count";
+    }>>>;
+    used: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    remaining: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    source: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        error: "error";
+        headers: "headers";
+        estimate: "estimate";
+        provider: "provider";
+    }>>>;
+    observedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    detail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type AccountLimit = z.infer<typeof accountLimitSchema>;
+/**
+ * Why a run settled, as a fixed code (PROP-0050). `terminalReason` keeps the human text; this is what
+ * a reader branches on. A `failed` event's `code` is one of these too.
+ */
+export declare const runStopCodeSchema: z.ZodEnum<{
+    completed: "completed";
+    failed: "failed";
+    user_abort: "user_abort";
+    slice_budget: "slice_budget";
+    compaction_thrash: "compaction_thrash";
+    needs_person: "needs_person";
+    unfinished: "unfinished";
+    provider_error: "provider_error";
+    stalled: "stalled";
+    owner_gone: "owner_gone";
+    harness_restart: "harness_restart";
+    terminal_attention: "terminal_attention";
+    terminal_closed: "terminal_closed";
+    parent_stopped: "parent_stopped";
+}>;
+export type RunStopCode = z.infer<typeof runStopCodeSchema>;
+/** The stop code of a failure code, which may come from a host or an older writer. */
+export declare const stopCodeOf: (code: string) => RunStopCode;
+/** Payload schema per discriminant. */
+export declare const runEventPayloadSchemas: {
+    started: z.ZodObject<{}, z.core.$loose>;
+    'context.snapshot': z.ZodObject<{
+        systemPrompt: z.ZodString;
+        contextUpdate: z.ZodOptional<z.ZodString>;
+        tools: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+            parameters: z.ZodUnknown;
+        }, z.core.$strip>>;
+        compaction: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodBoolean;
+            reserveTokens: z.ZodNumber;
+        }, z.core.$strip>>;
+        systemPromptTruncated: z.ZodOptional<z.ZodBoolean>;
+        contextUpdateTruncated: z.ZodOptional<z.ZodBoolean>;
+        toolsTruncated: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    'message.delta': z.ZodObject<{
+        messageId: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$strip>;
+    'message.completed': z.ZodObject<{
+        messageId: z.ZodString;
+        role: z.ZodEnum<{
+            user: "user";
+            assistant: "assistant";
+        }>;
+        text: z.ZodString;
+    }, z.core.$strip>;
+    'message.steered': z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strip>;
+    'tool.started': z.ZodObject<{
+        toolCallId: z.ZodString;
+        name: z.ZodString;
+        summary: z.ZodOptional<z.ZodString>;
+        input: z.ZodOptional<z.ZodString>;
+        inputTruncated: z.ZodOptional<z.ZodBoolean>;
+        output: z.ZodOptional<z.ZodString>;
+        outputTruncated: z.ZodOptional<z.ZodBoolean>;
+        ok: z.ZodOptional<z.ZodBoolean>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        resultChars: z.ZodOptional<z.ZodNumber>;
+        attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            mimeType: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strip>;
+    'tool.completed': z.ZodObject<{
+        toolCallId: z.ZodString;
+        name: z.ZodString;
+        summary: z.ZodOptional<z.ZodString>;
+        input: z.ZodOptional<z.ZodString>;
+        inputTruncated: z.ZodOptional<z.ZodBoolean>;
+        output: z.ZodOptional<z.ZodString>;
+        outputTruncated: z.ZodOptional<z.ZodBoolean>;
+        ok: z.ZodOptional<z.ZodBoolean>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        resultChars: z.ZodOptional<z.ZodNumber>;
+        attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            mimeType: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strip>;
+    'tool.refused': z.ZodObject<{
+        toolCallId: z.ZodString;
+        name: z.ZodString;
+        code: z.ZodEnum<{
+            plan_mode: "plan_mode";
+            workspace: "workspace";
+            scope: "scope";
+            policy: "policy";
+            capability: "capability";
+            approval_denied: "approval_denied";
+            unattended: "unattended";
+            work_slice: "work_slice";
+            controller_unavailable: "controller_unavailable";
+        }>;
+        reason: z.ZodString;
+    }, z.core.$strip>;
+    'retry.started': z.ZodObject<{
+        attempt: z.ZodNumber;
+        maxAttempts: z.ZodNumber;
+        delayMs: z.ZodNumber;
+        error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    'retry.ended': z.ZodObject<{
+        attempt: z.ZodNumber;
+        success: z.ZodBoolean;
+        error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    'compaction.started': z.ZodObject<{
+        reason: z.ZodString;
+        contextTokens: z.ZodOptional<z.ZodNumber>;
+        contextWindow: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    'compaction.ended': z.ZodObject<{
+        reason: z.ZodString;
+        aborted: z.ZodBoolean;
+        willRetry: z.ZodOptional<z.ZodBoolean>;
+        error: z.ZodOptional<z.ZodString>;
+        tokensBefore: z.ZodOptional<z.ZodNumber>;
+        tokensAfter: z.ZodOptional<z.ZodNumber>;
+        summary: z.ZodOptional<z.ZodString>;
+        summaryTruncated: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    'approval.requested': z.ZodObject<{
+        approvalId: z.ZodString;
+        target: z.ZodString;
+        action: z.ZodString;
+        screenshotRef: z.ZodOptional<z.ZodString>;
+        operation: z.ZodOptional<z.ZodObject<{
+            tool: z.ZodString;
+            args: z.ZodUnknown;
+        }, z.core.$strip>>;
+        rememberable: z.ZodOptional<z.ZodBoolean>;
+        automatic: z.ZodOptional<z.ZodEnum<{
+            always: "always";
+            scope: "scope";
+            remembered: "remembered";
+        }>>;
+    }, z.core.$strip>;
+    'approval.resolved': z.ZodObject<{
+        approvalId: z.ZodString;
+        decision: z.ZodEnum<{
+            approved: "approved";
+            denied: "denied";
+            native: "native";
+        }>;
+        automatic: z.ZodOptional<z.ZodEnum<{
+            always: "always";
+            scope: "scope";
+            remembered: "remembered";
+        }>>;
+    }, z.core.$strip>;
+    'question.requested': z.ZodObject<{
+        batchId: z.ZodOptional<z.ZodString>;
+        batchIndex: z.ZodOptional<z.ZodNumber>;
+        batchCount: z.ZodOptional<z.ZodNumber>;
+        questionId: z.ZodString;
+        question: z.ZodString;
+        summary: z.ZodOptional<z.ZodString>;
+        uiSketch: z.ZodOptional<z.ZodLiteral<true>>;
+        options: z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            recommended: z.ZodOptional<z.ZodBoolean>;
+            sketch: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        multiSelect: z.ZodBoolean;
+        allowText: z.ZodBoolean;
+        userOnly: z.ZodOptional<z.ZodBoolean>;
+        dialog: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodEnum<{
+                input: "input";
+                select: "select";
+                confirm: "confirm";
+                editor: "editor";
+            }>;
+            title: z.ZodString;
+            message: z.ZodOptional<z.ZodString>;
+            placeholder: z.ZodOptional<z.ZodString>;
+            prefill: z.ZodOptional<z.ZodString>;
+            options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    'question.answered': z.ZodObject<{
+        batchId: z.ZodOptional<z.ZodString>;
+        batchIndex: z.ZodOptional<z.ZodNumber>;
+        batchCount: z.ZodOptional<z.ZodNumber>;
+        questionId: z.ZodString;
+        selected: z.ZodArray<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+        notes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>;
+    'extension.notice': z.ZodObject<{
+        kind: z.ZodEnum<{
+            error: "error";
+            title: "title";
+            notify: "notify";
+            status: "status";
+            widget: "widget";
+        }>;
+        level: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            info: "info";
+            warning: "warning";
+        }>>;
+        key: z.ZodOptional<z.ZodString>;
+        text: z.ZodString;
+        extension: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    'reaction.added': z.ZodObject<{
+        emoji: z.ZodString;
+    }, z.core.$strip>;
+    'agent.message': z.ZodObject<{
+        direction: z.ZodEnum<{
+            to: "to";
+            from: "from";
+        }>;
+        agentId: z.ZodString;
+        agentName: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$strip>;
+    'todo.updated': z.ZodObject<{
+        items: z.ZodArray<z.ZodObject<{
+            text: z.ZodString;
+            status: z.ZodEnum<{
+                completed: "completed";
+                pending: "pending";
+                in_progress: "in_progress";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    'checklist.updated': z.ZodObject<{
+        items: z.ZodArray<z.ZodObject<{
+            text: z.ZodString;
+            status: z.ZodEnum<{
+                completed: "completed";
+                pending: "pending";
+                in_progress: "in_progress";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    checkpoint: z.ZodObject<{
+        summary: z.ZodString;
+        done: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            item: z.ZodString;
+            evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
+        next: z.ZodDefault<z.ZodString>;
+        blocked: z.ZodOptional<z.ZodString>;
+        files: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            why: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>>>;
+        checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            command: z.ZodString;
+            ok: z.ZodBoolean;
+            detail: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        decisions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            what: z.ZodString;
+            why: z.ZodDefault<z.ZodString>;
+        }, z.core.$strict>>>;
+        slice: z.ZodNumber;
+        reason: z.ZodEnum<{
+            budget: "budget";
+            stuck: "stuck";
+            "compaction-thrash": "compaction-thrash";
+            requested: "requested";
+        }>;
+    }, z.core.$strict>;
+    heartbeat: z.ZodObject<{
+        steps: z.ZodNumber;
+        elapsedMs: z.ZodNumber;
+        lastTool: z.ZodNullable<z.ZodString>;
+        compactions: z.ZodNumber;
+        slice: z.ZodNumber;
+        maxToolCalls: z.ZodNumber;
+        activeTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        oldestToolMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    'artifact.added': z.ZodObject<{
+        artifactId: z.ZodString;
+        name: z.ZodString;
+        file: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>;
+    'file.changed': z.ZodObject<{
+        path: z.ZodString;
+        change: z.ZodEnum<{
+            added: "added";
+            modified: "modified";
+            deleted: "deleted";
+        }>;
+    }, z.core.$strip>;
+    'usage.updated': z.ZodObject<{
+        inputTokens: z.ZodOptional<z.ZodNumber>;
+        outputTokens: z.ZodOptional<z.ZodNumber>;
+        cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+        cacheWriteTokens: z.ZodOptional<z.ZodNumber>;
+        reasoningTokens: z.ZodOptional<z.ZodNumber>;
+        costUsd: z.ZodOptional<z.ZodNumber>;
+        costSource: z.ZodOptional<z.ZodEnum<{
+            harness: "harness";
+            estimate: "estimate";
+            mixed: "mixed";
+        }>>;
+        requests: z.ZodOptional<z.ZodNumber>;
+        contextTokens: z.ZodOptional<z.ZodNumber>;
+        contextWindow: z.ZodOptional<z.ZodNumber>;
+        model: z.ZodOptional<z.ZodString>;
+        provider: z.ZodOptional<z.ZodString>;
+        request: z.ZodOptional<z.ZodObject<{
+            index: z.ZodNumber;
+            responseId: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            provider: z.ZodOptional<z.ZodString>;
+            inputTokens: z.ZodOptional<z.ZodNumber>;
+            cacheReadTokens: z.ZodOptional<z.ZodNumber>;
+            cacheWriteTokens: z.ZodOptional<z.ZodNumber>;
+            outputTokens: z.ZodOptional<z.ZodNumber>;
+            reasoningTokens: z.ZodOptional<z.ZodNumber>;
+            costUsd: z.ZodOptional<z.ZodNumber>;
+            costSource: z.ZodOptional<z.ZodEnum<{
+                harness: "harness";
+                estimate: "estimate";
+            }>>;
+            reasoningSummary: z.ZodOptional<z.ZodString>;
+            durationMs: z.ZodOptional<z.ZodNumber>;
+            ttftMs: z.ZodOptional<z.ZodNumber>;
+            stopReason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    'account.status': z.ZodObject<{
+        accountId: z.ZodString;
+        category: z.ZodOptional<z.ZodEnum<{
+            unknown: "unknown";
+            auth_expired: "auth_expired";
+            rate_limited: "rate_limited";
+            quota: "quota";
+            network: "network";
+        }>>;
+        message: z.ZodOptional<z.ZodString>;
+        resetsAt: z.ZodOptional<z.ZodString>;
+        plan: z.ZodOptional<z.ZodString>;
+        limits: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            usedPercent: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            remainingPercent: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            resetsAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            windowMinutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            status: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            provider: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            kind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                error: "error";
+                window: "window";
+                rate: "rate";
+                credit: "credit";
+                configured: "configured";
+            }>>>;
+            unit: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                requests: "requests";
+                percent: "percent";
+                tokens: "tokens";
+                usd: "usd";
+                currency: "currency";
+                count: "count";
+            }>>>;
+            used: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            limit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            remaining: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            source: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                error: "error";
+                headers: "headers";
+                estimate: "estimate";
+                provider: "provider";
+            }>>>;
+            observedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            detail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+    'status.changed': z.ZodObject<{
+        status: z.ZodEnum<{
+            queued: "queued";
+            running: "running";
+            waiting_for_approval: "waiting_for_approval";
+            waiting_for_input: "waiting_for_input";
+            interrupted: "interrupted";
+            completed: "completed";
+            failed: "failed";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodEnum<{
+            completed: "completed";
+            failed: "failed";
+            user_abort: "user_abort";
+            slice_budget: "slice_budget";
+            compaction_thrash: "compaction_thrash";
+            needs_person: "needs_person";
+            unfinished: "unfinished";
+            provider_error: "provider_error";
+            stalled: "stalled";
+            owner_gone: "owner_gone";
+            harness_restart: "harness_restart";
+            terminal_attention: "terminal_attention";
+            terminal_closed: "terminal_closed";
+            parent_stopped: "parent_stopped";
+        }>>;
+    }, z.core.$strip>;
+    failed: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>;
+    completed: z.ZodObject<{}, z.core.$loose>;
+};
+export declare const runEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    runId: z.ZodString;
+    sessionId: z.ZodString;
+    sequence: z.ZodNumber;
+    timestamp: z.ZodString;
+    type: z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        started: "started";
+        "context.snapshot": "context.snapshot";
+        "message.delta": "message.delta";
+        "message.completed": "message.completed";
+        "message.steered": "message.steered";
+        "tool.started": "tool.started";
+        "tool.completed": "tool.completed";
+        "tool.refused": "tool.refused";
+        "retry.started": "retry.started";
+        "retry.ended": "retry.ended";
+        "compaction.started": "compaction.started";
+        "compaction.ended": "compaction.ended";
+        "approval.requested": "approval.requested";
+        "approval.resolved": "approval.resolved";
+        "question.requested": "question.requested";
+        "question.answered": "question.answered";
+        "extension.notice": "extension.notice";
+        "reaction.added": "reaction.added";
+        "agent.message": "agent.message";
+        "todo.updated": "todo.updated";
+        "checklist.updated": "checklist.updated";
+        checkpoint: "checkpoint";
+        heartbeat: "heartbeat";
+        "artifact.added": "artifact.added";
+        "file.changed": "file.changed";
+        "usage.updated": "usage.updated";
+        "account.status": "account.status";
+        "status.changed": "status.changed";
+    }>;
+    payload: z.ZodUnknown;
+    native: z.ZodOptional<z.ZodUnknown>;
+    coalescedFrom: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type RunEvent = z.infer<typeof runEventSchema>;
+/**
+ * One tracked execution interval of a session. `mode`, `harness`, `sessionType`, `worktreeId`,
+ * `attachmentCount`, `exitCode`, `handoffId` and `trigger` belong to the embedding application:
+ * the harness stores and returns them, and reads only `mode` (`chat` is an agent's own
+ * conversation, `code` is a session in a project).
+ */
+/** A run's /goal as the run record keeps it (ADR-0072). */
+export interface GoalModeRecord {
+    goalId: string;
+    objective: string;
+    status: 'active' | 'paused' | 'blocked' | 'usage_limited' | 'budget_limited' | 'complete';
+    limits: {
+        rounds: number;
+        hours: number;
+    };
+    rounds: number;
+    timeUsedSeconds: number;
+    createdAt: number;
+    updatedAt: number;
+    claimed: boolean;
+    lastReason: string;
+}
+export declare const goalModeSchema: z.ZodObject<{
+    goalId: z.ZodString;
+    objective: z.ZodString;
+    status: z.ZodEnum<{
+        blocked: "blocked";
+        active: "active";
+        paused: "paused";
+        usage_limited: "usage_limited";
+        budget_limited: "budget_limited";
+        complete: "complete";
+    }>;
+    limits: z.ZodObject<{
+        rounds: z.ZodNumber;
+        hours: z.ZodNumber;
+    }, z.core.$strip>;
+    rounds: z.ZodNumber;
+    timeUsedSeconds: z.ZodNumber;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+    claimed: z.ZodBoolean;
+    lastReason: z.ZodString;
+}, z.core.$strip>;
+export interface RunRecord {
+    resumedFromRunId: string | null;
+    /** Opaque run lineage supplied by the embedding application. */
+    parentRunId: string | null;
+    relation: string | null;
+    terminalReason: string | null;
+    /** Why the run settled, as a `RunStopCode`; absent on records written before PROP-0050. */
+    terminalCode?: RunStopCode | null;
+    id: string;
+    projectId: string | null;
+    mode: string;
+    /** Execution mode, distinct from the host's session mode. */
+    effectiveMode?: 'plan' | 'normal';
+    harness: string;
+    sessionType: string;
+    sessionId: string;
+    nativeSessionId: string | null;
+    workingDirectory: string | null;
+    /** Canonical filesystem root whose writes this run may make by default. */
+    workspaceRoot?: string | null;
+    worktreeId: string | null;
+    goal: string | null;
+    /** The run's /goal (ADR-0072): its objective, status, rounds and time. Absent for a run without one. */
+    goalMode?: GoalModeRecord | null;
+    attachmentCount: number;
+    startedAt: string;
+    endedAt: string | null;
+    status: string;
+    exitCode: number | null;
+    handoffId: string | null;
+    /** The account the run used. */
+    accountId: string | null;
+    /** The agent that replied. */
+    agentId: string | null;
+    /** What started the run. */
+    trigger: string | null;
+    /** The variant the run used: its scope and version fingerprint. */
+    variantScope?: string | null;
+    variantVersion?: string | null;
+    /** The agent profile a subagent started from (PROP-0029); null for a copy of its parent. */
+    profile?: string | null;
+    /** The short name a parent gave a subagent, shown in the roster (PROP-0030). */
+    title?: string | null;
+    /** The model the run used, as `provider/id`: the launch selection, then the one the session opened. */
+    model?: string | null;
+    /** The reasoning effort the run used. */
+    effort?: string | null;
+    /** Successful Harness skill loads; absent for runs without observation. */
+    loadedSkills?: string[];
+    /** Plugin identities observed activating; absent when not fully observable. */
+    activatedPlugins?: string[];
+    /**
+     * The git working tree as this person's turn found it, before the agent changed anything: a
+     * commit made without touching the tree or the index. Refinement replays the request from it.
+     * Absent outside git, for runs nobody typed, and when the snapshot took too long.
+     */
+    workspaceSnapshot?: {
+        kind: 'git-snapshot';
+        repo: string;
+        commit: string;
+        omitted?: number;
+    } | null;
+}
+export declare const runRecordSchema: z.ZodObject<{
+    resumedFromRunId: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    parentRunId: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    relation: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    terminalReason: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    terminalCode: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        user_abort: "user_abort";
+        slice_budget: "slice_budget";
+        compaction_thrash: "compaction_thrash";
+        needs_person: "needs_person";
+        unfinished: "unfinished";
+        provider_error: "provider_error";
+        stalled: "stalled";
+        owner_gone: "owner_gone";
+        harness_restart: "harness_restart";
+        terminal_attention: "terminal_attention";
+        terminal_closed: "terminal_closed";
+        parent_stopped: "parent_stopped";
+    }>>>, z.ZodTransform<"completed" | "failed" | "user_abort" | "slice_budget" | "compaction_thrash" | "needs_person" | "unfinished" | "provider_error" | "stalled" | "owner_gone" | "harness_restart" | "terminal_attention" | "terminal_closed" | "parent_stopped" | null, "completed" | "failed" | "user_abort" | "slice_budget" | "compaction_thrash" | "needs_person" | "unfinished" | "provider_error" | "stalled" | "owner_gone" | "harness_restart" | "terminal_attention" | "terminal_closed" | "parent_stopped" | null | undefined>>;
+    id: z.ZodString;
+    projectId: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    mode: z.ZodString;
+    effectiveMode: z.ZodOptional<z.ZodEnum<{
+        plan: "plan";
+        normal: "normal";
+    }>>;
+    harness: z.ZodString;
+    sessionType: z.ZodString;
+    sessionId: z.ZodString;
+    nativeSessionId: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    workingDirectory: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    workspaceRoot: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
+    worktreeId: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    goal: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    goalMode: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        goalId: z.ZodString;
+        objective: z.ZodString;
+        status: z.ZodEnum<{
+            blocked: "blocked";
+            active: "active";
+            paused: "paused";
+            usage_limited: "usage_limited";
+            budget_limited: "budget_limited";
+            complete: "complete";
+        }>;
+        limits: z.ZodObject<{
+            rounds: z.ZodNumber;
+            hours: z.ZodNumber;
+        }, z.core.$strip>;
+        rounds: z.ZodNumber;
+        timeUsedSeconds: z.ZodNumber;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+        claimed: z.ZodBoolean;
+        lastReason: z.ZodString;
+    }, z.core.$strip>>>, z.ZodTransform<{
+        goalId: string;
+        objective: string;
+        status: "blocked" | "active" | "paused" | "usage_limited" | "budget_limited" | "complete";
+        limits: {
+            rounds: number;
+            hours: number;
+        };
+        rounds: number;
+        timeUsedSeconds: number;
+        createdAt: number;
+        updatedAt: number;
+        claimed: boolean;
+        lastReason: string;
+    } | null, {
+        goalId: string;
+        objective: string;
+        status: "blocked" | "active" | "paused" | "usage_limited" | "budget_limited" | "complete";
+        limits: {
+            rounds: number;
+            hours: number;
+        };
+        rounds: number;
+        timeUsedSeconds: number;
+        createdAt: number;
+        updatedAt: number;
+        claimed: boolean;
+        lastReason: string;
+    } | null | undefined>>>;
+    attachmentCount: z.ZodDefault<z.ZodNumber>;
+    startedAt: z.ZodString;
+    endedAt: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    status: z.ZodString;
+    exitCode: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodNumber>>, z.ZodTransform<number | null, number | null | undefined>>;
+    handoffId: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    accountId: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    agentId: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    trigger: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    variantScope: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
+    variantVersion: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
+    profile: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
+    title: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
+    model: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
+    effort: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
+    loadedSkills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    activatedPlugins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    workspaceSnapshot: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        kind: z.ZodLiteral<"git-snapshot">;
+        repo: z.ZodString;
+        commit: z.ZodString;
+        omitted: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** Records written before PROP-0009 name the variant `harnessScope` and `harnessVersion`. */
+export declare function upgradeRunRecord(raw: unknown): unknown;
+export declare const ACTIVE_STATUSES: readonly string[];
+export declare function isActiveStatus(status: string): boolean;
+export {};