@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/sessions/contracts.js

@@ -0,0 +1,545 @@
+// Run records and the run-event stream: the one contract every session shares. Every event is
+// validated against these schemas before it is persisted or handed to a listener.
+import { z } from 'zod';
+export const runStatusSchema = z.enum(['queued', 'running', 'waiting_for_approval', 'waiting_for_input', 'interrupted', 'completed', 'failed']);
+export const runEventTypeSchema = z.enum([
+    'started',
+    'context.snapshot',
+    'message.delta',
+    'message.completed',
+    'message.steered',
+    'tool.started',
+    'tool.completed',
+    'tool.refused',
+    'retry.started',
+    'retry.ended',
+    'compaction.started',
+    'compaction.ended',
+    'approval.requested',
+    'approval.resolved',
+    'question.requested',
+    'question.answered',
+    'extension.notice',
+    'reaction.added',
+    'agent.message',
+    'todo.updated',
+    // Written before the rename; accepted so stored run logs keep their lists. Never written now.
+    'checklist.updated',
+    'checkpoint',
+    'heartbeat',
+    'artifact.added',
+    'file.changed',
+    'usage.updated',
+    'account.status',
+    'status.changed',
+    'failed',
+    'completed'
+]);
+const messageDeltaPayload = z.object({ messageId: z.string(), text: z.string() });
+const messageCompletedPayload = z.object({ messageId: z.string(), role: z.enum(['user', 'assistant']), text: z.string() });
+/** A message the person sent into the run while it was going; the model reads it from its next request on. */
+const messageSteeredPayload = z.object({ text: z.string() });
+const contextSnapshotPayload = z.object({
+    systemPrompt: z.string().max(100_000),
+    contextUpdate: z.string().max(100_000).optional(),
+    tools: z.array(z.object({ name: z.string(), description: z.string().max(2_000), parameters: z.unknown() })).max(120),
+    /** The headroom Pi held the run to when it measured compaction, as the session's own settings give it. */
+    compaction: z.object({ enabled: z.boolean(), reserveTokens: z.number().nonnegative() }).optional(),
+    systemPromptTruncated: z.boolean().optional(),
+    contextUpdateTruncated: z.boolean().optional(),
+    toolsTruncated: z.boolean().optional()
+});
+/** Generic reference to content a provider stores outside the run-event stream. */
+export const toolAttachmentRefSchema = z.object({
+    id: z.string().min(1).max(300),
+    name: z.string().min(1).max(500),
+    mimeType: z.string().min(1).max(100)
+}).strict();
+export const toolAttachmentRefsSchema = z.array(toolAttachmentRefSchema).max(16);
+const toolPayload = z.object({
+    toolCallId: z.string(),
+    name: z.string(),
+    summary: z.string().max(200).optional(),
+    input: z.string().max(24_000).optional(),
+    inputTruncated: z.boolean().optional(),
+    output: z.string().max(24_000).optional(),
+    outputTruncated: z.boolean().optional(),
+    ok: z.boolean().optional(),
+    /** On `tool.completed`: how long the call ran, and the size of what it returned to the model. */
+    durationMs: z.number().optional(),
+    resultChars: z.number().optional(),
+    /** Opaque attachment references. Content stays outside the run event stream. */
+    attachments: toolAttachmentRefsSchema.optional()
+});
+const retryStartedPayload = z.object({ attempt: z.number(), maxAttempts: z.number(), delayMs: z.number(), error: z.string().max(1_000).optional() });
+const retryEndedPayload = z.object({ attempt: z.number(), success: z.boolean(), error: z.string().max(1_000).optional() });
+/**
+ * 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 const refusalCodeSchema = z.enum([
+    /** Plan mode allows only research tools and read-only Bash. */
+    'plan_mode',
+    /** A file write or command outside the active project workspace, or a workspace that could not be verified. */
+    'workspace',
+    /** The host's work scope does not cover the call. */
+    'scope',
+    /** The host's tool policy disabled the tool. */
+    'policy',
+    /** The tool is outside the run's capability set. */
+    'capability',
+    /** A person was asked and declined. */
+    'approval_denied',
+    /** The call needs a person and the run has nobody to ask: refinement, reflection, diagnostics. */
+    'unattended',
+    /** The reply reached its work-slice budget. */
+    'work_slice',
+    /** The terminal controller could not be reached to decide. */
+    'controller_unavailable'
+]);
+const toolRefusedPayload = z.object({
+    toolCallId: z.string(),
+    name: z.string(),
+    code: refusalCodeSchema,
+    reason: z.string().max(2_000)
+});
+const compactionStartedPayload = z.object({
+    reason: z.string(),
+    /** The latest request's size and the model's limit when compaction began, when known. */
+    contextTokens: z.number().optional(),
+    contextWindow: z.number().optional()
+});
+const compactionEndedPayload = z.object({
+    reason: z.string(),
+    aborted: z.boolean(),
+    willRetry: z.boolean().optional(),
+    error: z.string().max(1_000).optional(),
+    tokensBefore: z.number().optional(),
+    tokensAfter: z.number().optional(),
+    summary: z.string().max(24_000).optional(),
+    summaryTruncated: z.boolean().optional()
+});
+/** Granted without asking: the standing switch, a remembered tool, or the embedding application's own scope. */
+const approvalAutomaticSchema = z.enum(['always', 'remembered', 'scope']);
+const approvalRequestedPayload = z.object({
+    approvalId: z.string(),
+    target: z.string(),
+    action: z.string(),
+    screenshotRef: z.string().optional(),
+    operation: z.object({ tool: z.string(), args: z.unknown() }).optional(),
+    /** A tool the user may choose to always allow for this session. */
+    rememberable: z.boolean().optional(),
+    /** Set when the request was granted as it was made, so nobody is waiting on it. */
+    automatic: approvalAutomaticSchema.optional()
+});
+const approvalResolvedPayload = z.object({ approvalId: z.string(), decision: z.enum(['approved', 'denied', 'native']), automatic: approvalAutomaticSchema.optional() });
+export const QUESTION_SKETCH_MAX_LINES = 24;
+export const QUESTION_SKETCH_MAX_COLUMNS = 80;
+export const QUESTION_SKETCH_MAX_LENGTH = QUESTION_SKETCH_MAX_LINES * QUESTION_SKETCH_MAX_COLUMNS + QUESTION_SKETCH_MAX_LINES - 1;
+export const QUESTION_SKETCH_PATTERN = `^(?:[\\x20-\\x7e]{0,${QUESTION_SKETCH_MAX_COLUMNS}})(?:\\n[\\x20-\\x7e]{0,${QUESTION_SKETCH_MAX_COLUMNS}}){0,${QUESTION_SKETCH_MAX_LINES - 1}}$`;
+export const questionSketchSchema = z.string()
+    .min(1)
+    .max(QUESTION_SKETCH_MAX_LENGTH)
+    .regex(new RegExp(QUESTION_SKETCH_PATTERN), 'Sketches use up to 24 LF-separated lines of at most 80 printable ASCII characters.')
+    .refine((sketch) => {
+    const lines = sketch.split('\n');
+    return lines.length <= QUESTION_SKETCH_MAX_LINES &&
+        lines.every((line) => line.length <= QUESTION_SKETCH_MAX_COLUMNS && /^[\x20-\x7e]*$/u.test(line)) &&
+        /[^ \n]/u.test(sketch);
+}, 'A sketch needs visible content and must use up to 24 LF-separated lines of at most 80 printable ASCII characters.');
+export function questionSketchError(uiSketch, options) {
+    if (uiSketch !== undefined && uiSketch !== true)
+        return 'Set uiSketch to true to enable question sketches.';
+    const sketches = options.map((option) => option.sketch);
+    if (uiSketch === true && sketches.some((sketch) => sketch === undefined))
+        return 'Sketch mode requires a sketch for every choice.';
+    if (uiSketch !== true && sketches.some((sketch) => sketch !== undefined))
+        return 'Choice sketches require uiSketch: true.';
+    if (sketches.some((sketch) => sketch !== undefined && !questionSketchSchema.safeParse(sketch).success)) {
+        return 'Each choice sketch must use 1–24 lines of at most 80 printable ASCII characters and contain a visible character.';
+    }
+    return undefined;
+}
+export const questionOptionSchema = z.object({
+    label: z.string().min(1),
+    description: z.string().optional(),
+    recommended: z.boolean().optional(),
+    sketch: questionSketchSchema.optional()
+});
+/**
+ * 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 function questionAnswerProblem(question, answer) {
+    const name = question.summary?.trim() ? `Question "${question.summary.trim()}"` : 'This question';
+    const selected = answer.selected;
+    if (question.multiSelect !== true && selected.length > 1) {
+        return { field: 'selection', message: `${name} takes one choice, but ${selected.length} were selected.` };
+    }
+    if (new Set(selected).size !== selected.length) {
+        return { field: 'selection', message: `${name} lists the same choice more than once.` };
+    }
+    const unknown = selected.find((label) => !question.options.some((option) => option.label === label));
+    if (unknown !== undefined) {
+        return { field: 'selection', message: `${name} does not offer "${unknown}".` };
+    }
+    if (answer.text?.trim() && question.allowText === false) {
+        return { field: 'text', message: `${name} does not take a typed answer; choose one of its options.` };
+    }
+    for (const [label, note] of Object.entries(answer.notes ?? {})) {
+        const normalized = typeof note === 'string' ? note.trim() : '';
+        if (!normalized)
+            continue;
+        if (!selected.includes(label)) {
+            return { field: 'notes', message: `${name}: a note is attached to "${label}", which is not selected.` };
+        }
+        if (normalized.length > 10_000) {
+            return { field: 'notes', message: `${name}: the note for "${label}" is longer than 10,000 characters.` };
+        }
+    }
+    return null;
+}
+const questionBatchFields = {
+    batchId: z.string().min(1).optional(),
+    batchIndex: z.number().int().min(1).max(5).optional(),
+    batchCount: z.number().int().min(1).max(5).optional()
+};
+const questionBatchRefinement = (value, context) => {
+    const fields = [value.batchId, value.batchIndex, value.batchCount];
+    if (fields.some((field) => field !== undefined) && fields.some((field) => field === undefined)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: 'Question batch fields must be supplied together.' });
+    }
+    if (value.batchIndex !== undefined && value.batchCount !== undefined && value.batchIndex > value.batchCount) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: 'Question batch index cannot exceed its count.' });
+    }
+};
+const questionRequestedPayload = z.object({
+    questionId: z.string(),
+    question: z.string().min(1),
+    summary: z.string().min(1).max(100).optional(),
+    uiSketch: z.literal(true).optional(),
+    options: z.array(questionOptionSchema),
+    multiSelect: z.boolean(),
+    allowText: z.boolean(),
+    userOnly: z.boolean().optional(),
+    /** The Pi extension dialog this question stands for (ADR-0083); a host may ignore it. */
+    dialog: z.object({
+        kind: z.enum(['select', 'confirm', 'input', 'editor']),
+        title: z.string().max(4_000),
+        message: z.string().max(4_000).optional(),
+        placeholder: z.string().max(4_000).optional(),
+        prefill: z.string().max(100_000).optional(),
+        options: z.array(z.string().max(4_000)).max(200).optional()
+    }).optional(),
+    ...questionBatchFields
+}).superRefine(questionBatchRefinement).superRefine((value, context) => {
+    const error = questionSketchError(value.uiSketch, value.options);
+    if (error)
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ['options'], message: error });
+});
+const questionAnsweredPayload = z.object({
+    questionId: z.string(),
+    selected: z.array(z.string()),
+    text: z.string().optional(),
+    notes: z.record(z.string(), z.string().max(10_000)).optional(),
+    ...questionBatchFields
+}).superRefine(questionBatchRefinement);
+/** A short emoji sequence, never words or numbers. */
+const reactionAddedPayload = z.object({ emoji: z.string().min(1).refine((text) => Buffer.byteLength(text) <= 16 && !/[A-Za-z0-9\s]/.test(text)) });
+/** A message this run's agent sent to (`to`) or received back from (`from`) another agent. */
+const agentMessagePayload = z.object({ direction: z.enum(['to', 'from']), agentId: z.string(), agentName: z.string(), text: z.string() });
+/** A status line, a notification or an error from a Pi extension loaded in the session. */
+const extensionNoticePayload = z.object({
+    kind: z.enum(['notify', 'status', 'widget', 'title', 'error']),
+    level: z.enum(['info', 'warning', 'error']).optional(),
+    key: z.string().optional(),
+    text: z.string(),
+    extension: z.string().optional()
+});
+/** One line of the run's todo list. The list has no ids: every update replaces all of it. */
+export const todoItemSchema = z.object({ text: z.string().min(1).max(500), status: z.enum(['pending', 'in_progress', 'completed']) }).strict();
+export const MAX_TODO_ITEMS = 50;
+/** The whole todo list as the model last wrote it; the latest event replaces every earlier one. */
+const todoPayload = z.object({ items: z.array(todoItemSchema).max(MAX_TODO_ITEMS) }).strict();
+export const MAX_CHECKPOINT_SUMMARY = 1_200;
+export const MAX_CHECKPOINT_DONE = 20;
+export const MAX_CHECKPOINT_EVIDENCE = 5;
+export const MAX_CHECKPOINT_FILES = 20;
+export const MAX_CHECKPOINT_CHECKS = 8;
+export 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 const checkpointItemSchema = z.object({
+    item: z.string().min(1).max(300),
+    evidence: z.array(z.string().min(1).max(300)).max(MAX_CHECKPOINT_EVIDENCE).default([])
+}).strict();
+export const checkpointFileSchema = z.object({ path: z.string().min(1).max(300), why: z.string().max(200).default('') }).strict();
+export const checkpointCheckSchema = z.object({
+    command: z.string().min(1).max(200),
+    ok: z.boolean(),
+    detail: z.string().max(300).optional()
+}).strict();
+export const checkpointDecisionSchema = z.object({ what: z.string().min(1).max(200), why: z.string().max(300).default('') }).strict();
+export const checkpointReasonSchema = z.enum(['budget', 'stuck', 'compaction-thrash', 'requested']);
+const checkpointPayload = z.object({
+    summary: z.string().max(MAX_CHECKPOINT_SUMMARY),
+    done: z.array(checkpointItemSchema).max(MAX_CHECKPOINT_DONE).default([]),
+    next: z.string().max(500).default(''),
+    blocked: z.string().max(500).optional(),
+    files: z.array(checkpointFileSchema).max(MAX_CHECKPOINT_FILES).default([]),
+    checks: z.array(checkpointCheckSchema).max(MAX_CHECKPOINT_CHECKS).default([]),
+    decisions: z.array(checkpointDecisionSchema).max(MAX_CHECKPOINT_DECISIONS).default([]),
+    /** Which slice of the session wrote it, from 1. */
+    slice: z.number().int().positive(),
+    reason: checkpointReasonSchema
+}).strict();
+/** Counters a live reply reports while it works; a person and the watchdog read liveness from it. */
+const heartbeatPayload = z.object({
+    steps: z.number().int().nonnegative(),
+    elapsedMs: z.number().nonnegative(),
+    lastTool: z.string().max(120).nullable(),
+    compactions: z.number().int().nonnegative(),
+    slice: z.number().int().positive(),
+    maxToolCalls: z.number().int().nonnegative(),
+    /** The tools running when the beat was taken (deduplicated names), so a long wait says what it waits on. */
+    activeTools: z.array(z.string().max(120)).max(16).optional(),
+    /** How long the oldest of them has been running. */
+    oldestToolMs: z.number().nonnegative().optional()
+}).strict();
+const artifactPayload = z.object({ artifactId: z.string(), name: z.string(), file: z.unknown().optional() });
+const fileChangedPayload = z.object({ path: z.string(), change: z.enum(['added', 'modified', 'deleted']) });
+/** Where a cost figure comes from: Pi reported it, or the tokens were priced at list rates. */
+export const costSourceSchema = z.enum(['harness', 'estimate', 'mixed']);
+/** What one model request used. Token fields mean the same as on the run's totals. */
+export const usageRequestSchema = z.object({
+    /** Position in the run, from 1. */
+    index: z.number(),
+    responseId: z.string().optional(),
+    model: z.string().optional(),
+    provider: z.string().optional(),
+    inputTokens: z.number().optional(),
+    cacheReadTokens: z.number().optional(),
+    cacheWriteTokens: z.number().optional(),
+    outputTokens: z.number().optional(),
+    reasoningTokens: z.number().optional(),
+    costUsd: z.number().optional(),
+    costSource: z.enum(['harness', 'estimate']).optional(),
+    /** Separate provider-supplied summary; never generic private thinking content. */
+    reasoningSummary: z.string().max(4_000).optional(),
+    /** From sending the request to the end of the response, and to its first output. */
+    durationMs: z.number().optional(),
+    ttftMs: z.number().optional(),
+    stopReason: z.string().optional()
+});
+/** Token totals so far in this run (cumulative for the run, not the native session). */
+export const usagePayloadSchema = z.object({
+    /** Input tokens that were not read from the provider's cache. */
+    inputTokens: z.number().optional(),
+    /** Includes reasoning tokens. */
+    outputTokens: z.number().optional(),
+    cacheReadTokens: z.number().optional(),
+    cacheWriteTokens: z.number().optional(),
+    reasoningTokens: z.number().optional(),
+    costUsd: z.number().optional(),
+    costSource: costSourceSchema.optional(),
+    /** Model requests made so far. */
+    requests: z.number().optional(),
+    /** Size of the latest request (not cumulative), and the model's limit. */
+    contextTokens: z.number().optional(),
+    contextWindow: z.number().optional(),
+    model: z.string().optional(),
+    provider: z.string().optional(),
+    /** The request this update reports. */
+    request: usageRequestSchema.optional()
+});
+export const accountIssueCategorySchema = z.enum(['auth_expired', 'rate_limited', 'quota', 'network', 'unknown']);
+export const accountLimitSchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    usedPercent: z.number().nullable().optional(),
+    remainingPercent: z.number().nullable().optional(),
+    resetsAt: z.string().nullable().optional(),
+    windowMinutes: z.number().nullable().optional(),
+    status: z.string().nullable().optional(),
+    provider: z.string().nullable().optional(),
+    kind: z.enum(['window', 'rate', 'credit', 'configured', 'error']).nullable().optional(),
+    unit: z.enum(['percent', 'requests', 'tokens', 'usd', 'currency', 'count']).nullable().optional(),
+    used: z.number().nullable().optional(),
+    limit: z.number().nullable().optional(),
+    remaining: z.number().nullable().optional(),
+    source: z.enum(['headers', 'provider', 'estimate', 'error']).nullable().optional(),
+    observedAt: z.string().nullable().optional(),
+    detail: z.string().nullable().optional()
+});
+/** Limit snapshots, plan changes, and classified account failures. */
+const accountStatusPayload = z.object({
+    accountId: z.string(),
+    category: accountIssueCategorySchema.optional(),
+    message: z.string().optional(),
+    resetsAt: z.string().optional(),
+    plan: z.string().optional(),
+    limits: z.array(accountLimitSchema).optional()
+});
+/**
+ * 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 const runStopCodeSchema = z.enum([
+    'completed',
+    /** A person stopped the run. */
+    'user_abort',
+    /** The reply reached its work-slice budget and handed off. */
+    'slice_budget',
+    /** Three compactions in one reply ended it. */
+    'compaction_thrash',
+    /** A goal stopped for the person (ADR-0072). */
+    'needs_person',
+    /** A goal stopped on a limit, a pause or a stall with work left (ADR-0072, ADR-0075). */
+    'unfinished',
+    /** The model request failed (auth, quota, rate limit, network, unsupported model). */
+    'provider_error',
+    /** The run stopped reporting progress or heartbeats. */
+    'stalled',
+    /** The owning process went away without settling the run. */
+    'owner_gone',
+    /** The harness started and found the run unsettled. */
+    'harness_restart',
+    /** The terminal needs attention: a startup error or a lost decision callback. */
+    'terminal_attention',
+    /** The terminal closed while the run was live. */
+    'terminal_closed',
+    /** An ancestor run stopped, so this one did too. */
+    'parent_stopped',
+    /** Any other failure. */
+    'failed'
+]);
+/** The stop code of a failure code, which may come from a host or an older writer. */
+export const stopCodeOf = (code) => {
+    const parsed = runStopCodeSchema.safeParse(code);
+    if (parsed.success)
+        return parsed.data;
+    return code.startsWith('provider_') ? 'provider_error' : 'failed';
+};
+const statusPayload = z.object({ status: runStatusSchema, reason: z.string().optional(), code: runStopCodeSchema.optional() });
+const failedPayload = z.object({ code: z.string(), message: z.string() });
+const emptyPayload = z.object({}).passthrough();
+/** Payload schema per discriminant. */
+export const runEventPayloadSchemas = {
+    started: emptyPayload,
+    'context.snapshot': contextSnapshotPayload,
+    'message.delta': messageDeltaPayload,
+    'message.completed': messageCompletedPayload,
+    'message.steered': messageSteeredPayload,
+    'tool.started': toolPayload,
+    'tool.completed': toolPayload,
+    'tool.refused': toolRefusedPayload,
+    'retry.started': retryStartedPayload,
+    'retry.ended': retryEndedPayload,
+    'compaction.started': compactionStartedPayload,
+    'compaction.ended': compactionEndedPayload,
+    'approval.requested': approvalRequestedPayload,
+    'approval.resolved': approvalResolvedPayload,
+    'question.requested': questionRequestedPayload,
+    'question.answered': questionAnsweredPayload,
+    'extension.notice': extensionNoticePayload,
+    'reaction.added': reactionAddedPayload,
+    'agent.message': agentMessagePayload,
+    'todo.updated': todoPayload,
+    'checklist.updated': todoPayload,
+    checkpoint: checkpointPayload,
+    heartbeat: heartbeatPayload,
+    'artifact.added': artifactPayload,
+    'file.changed': fileChangedPayload,
+    'usage.updated': usagePayloadSchema,
+    'account.status': accountStatusPayload,
+    'status.changed': statusPayload,
+    failed: failedPayload,
+    completed: emptyPayload
+};
+export const runEventSchema = z
+    .object({
+    id: z.string(),
+    runId: z.string(),
+    sessionId: z.string(),
+    sequence: z.number().int().nonnegative(),
+    timestamp: z.string(),
+    type: runEventTypeSchema,
+    payload: z.unknown(),
+    /** The native event this one was derived from, kept as evidence. */
+    native: z.unknown().optional(),
+    /** Set when consecutive text deltas were merged for relay; covers sequences coalescedFrom..sequence. */
+    coalescedFrom: z.number().int().nonnegative().optional()
+})
+    .superRefine((event, context) => {
+    if (!runEventPayloadSchemas[event.type].safeParse(event.payload).success) {
+        context.addIssue({ code: 'custom', path: ['payload'], message: `Invalid payload for ${event.type}` });
+    }
+});
+export const goalModeSchema = z.object({
+    goalId: z.string(),
+    objective: z.string(),
+    status: z.enum(['active', 'paused', 'blocked', 'usage_limited', 'budget_limited', 'complete']),
+    limits: z.object({ rounds: z.number().int().positive(), hours: z.number().positive() }),
+    rounds: z.number().int().nonnegative(),
+    timeUsedSeconds: z.number().nonnegative(),
+    createdAt: z.number(),
+    updatedAt: z.number(),
+    claimed: z.boolean(),
+    lastReason: z.string()
+});
+const text = z.string().nullish().transform((value) => value ?? null);
+export const runRecordSchema = z.object({
+    resumedFromRunId: text,
+    parentRunId: text,
+    relation: text,
+    terminalReason: text,
+    terminalCode: runStopCodeSchema.nullish().transform((value) => value ?? null),
+    id: z.string(),
+    projectId: text,
+    mode: z.string(),
+    effectiveMode: z.enum(['plan', 'normal']).optional(),
+    harness: z.string(),
+    sessionType: z.string(),
+    sessionId: z.string(),
+    nativeSessionId: text,
+    workingDirectory: text,
+    workspaceRoot: text.optional(),
+    worktreeId: text,
+    goal: text,
+    goalMode: goalModeSchema.nullish().transform((value) => value ?? null).optional(),
+    attachmentCount: z.number().int().nonnegative().default(0),
+    startedAt: z.string(),
+    endedAt: text,
+    status: z.string(),
+    exitCode: z.number().int().nullish().transform((value) => value ?? null),
+    handoffId: text,
+    accountId: text,
+    agentId: text,
+    trigger: text,
+    variantScope: text.optional(),
+    variantVersion: text.optional(),
+    profile: text.optional(),
+    title: text.optional(),
+    model: text.optional(),
+    effort: text.optional(),
+    loadedSkills: z.array(z.string()).optional(),
+    activatedPlugins: z.array(z.string()).optional(),
+    workspaceSnapshot: z.object({ kind: z.literal('git-snapshot'), repo: z.string(), commit: z.string(), omitted: z.number().int().nonnegative().optional() }).nullish()
+});
+/** Records written before PROP-0009 name the variant `harnessScope` and `harnessVersion`. */
+export function upgradeRunRecord(raw) {
+    if (!raw || typeof raw !== 'object')
+        return raw;
+    const record = raw;
+    if (!('harnessScope' in record) && !('harnessVersion' in record))
+        return raw;
+    const { harnessScope, harnessVersion, ...rest } = record;
+    return { variantScope: harnessScope, variantVersion: harnessVersion, ...rest };
+}
+export const ACTIVE_STATUSES = ['queued', 'running', 'waiting_for_approval', 'waiting_for_input'];
+export function isActiveStatus(status) {
+    return ACTIVE_STATUSES.includes(status);
+}

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

@@ -0,0 +1,72 @@
+/** Which saved history a command acts on: one file in the folder, or the newest there. */
+export interface SessionRef {
+    sessionDir: string;
+    sessionFile?: string | null;
+    /** Recorded in a new history's header. Defaults to the source history's own folder. */
+    cwd?: string | null;
+}
+export interface SessionTreeEntry {
+    id: string;
+    parentId: string | null;
+    type: string;
+    /** `user`, `assistant`, `toolResult`, ... for a message entry. */
+    role?: string;
+    /** One line of what the entry says, at most 160 characters. */
+    text: string;
+    label?: string;
+    timestamp: string;
+    /** How deep in the tree, for indentation. */
+    depth: number;
+}
+export interface SessionTree {
+    sessionFile: string;
+    leafId: string | null;
+    entries: SessionTreeEntry[];
+    /** The person's messages on the current branch, newest last: where `/fork` may start. */
+    forkPoints: {
+        entryId: string;
+        text: string;
+    }[];
+}
+/** A move without a summary is saved as this entry, so the next turn opens on the chosen branch. */
+export declare const NAVIGATION_ENTRY = "xingular-navigation";
+export declare function tree(ref: SessionRef): SessionTree;
+/**
+ * Moves the conversation to another entry without a summary. Choosing one of the person's
+ * messages goes to just before it and gives its text back to edit, as the terminal does.
+ */
+export declare function navigate(ref: SessionRef & {
+    entryId: string;
+}): {
+    leafId: string | null;
+    editorText?: string;
+};
+/** A new history in `targetDir` that ends just before one of the person's messages. */
+export declare function fork(ref: SessionRef & {
+    entryId: string;
+    targetDir: string;
+}): {
+    sessionFile: string;
+    editorText: string;
+};
+/** A new history in `targetDir` with the whole current branch. */
+export declare function clone(ref: SessionRef & {
+    targetDir: string;
+}): {
+    sessionFile: string;
+};
+export declare function rename(ref: SessionRef & {
+    name: string;
+}): {
+    name: string;
+};
+/** The text of the last reply on the current branch, or null before the first. */
+export declare function lastReply(ref: SessionRef): {
+    text: string | null;
+};
+/** Writes the current branch as JSONL. HTML needs a live session: see `SessionCommand`. */
+export declare function exportJsonl(ref: SessionRef & {
+    path: string;
+}): {
+    path: string;
+};