@xingular/harness 1.0.0 → 1.2.0

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

@@ -31,6 +31,8 @@ export declare const runEventTypeSchema: z.ZodEnum<{
     "reaction.added": "reaction.added";
     "agent.message": "agent.message";
     "checklist.updated": "checklist.updated";
+    checkpoint: "checkpoint";
+    heartbeat: "heartbeat";
     "artifact.added": "artifact.added";
     "file.changed": "file.changed";
     "usage.updated": "usage.updated";
@@ -50,10 +52,19 @@ export declare const toolAttachmentRefsSchema: z.ZodArray<z.ZodObject<{
     mimeType: z.ZodString;
 }, z.core.$strict>>;
 export type ToolAttachmentRef = z.infer<typeof toolAttachmentRefSchema>;
+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>;
 /** One line of the run's checklist. The list has no ids: every update replaces all of it. */
@@ -67,6 +78,73 @@ export declare const checklistItemSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type ChecklistItem = z.infer<typeof checklistItemSchema>;
 export declare const MAX_CHECKLIST_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";
@@ -148,9 +226,37 @@ 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>;
 /** Payload schema per discriminant. */
@@ -277,10 +383,12 @@ export declare const runEventPayloadSchemas: {
         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;
@@ -334,6 +442,43 @@ export declare const runEventPayloadSchemas: {
             }>;
         }, 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;
+    }, z.core.$strict>;
     'artifact.added': z.ZodObject<{
         artifactId: z.ZodString;
         name: z.ZodString;
@@ -401,9 +546,37 @@ export declare const runEventPayloadSchemas: {
             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<{
@@ -452,6 +625,8 @@ export declare const runEventSchema: z.ZodObject<{
         "reaction.added": "reaction.added";
         "agent.message": "agent.message";
         "checklist.updated": "checklist.updated";
+        checkpoint: "checkpoint";
+        heartbeat: "heartbeat";
         "artifact.added": "artifact.added";
         "file.changed": "file.changed";
         "usage.updated": "usage.updated";
@@ -483,6 +658,8 @@ export interface RunRecord {
     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;
     attachmentCount: number;
@@ -500,6 +677,10 @@ export interface RunRecord {
     /** 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;
 }
 export declare const runRecordSchema: z.ZodObject<{
     resumedFromRunId: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
@@ -514,6 +695,7 @@ export declare const runRecordSchema: z.ZodObject<{
     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>>;
     attachmentCount: z.ZodDefault<z.ZodNumber>;
@@ -527,8 +709,11 @@ export declare const runRecordSchema: z.ZodObject<{
     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>>>;
 }, 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 {};

package/dist/sdk/sessions/contracts.js

@@ -22,6 +22,8 @@ export const runEventTypeSchema = z.enum([
     'reaction.added',
     'agent.message',
     'checklist.updated',
+    'checkpoint',
+    'heartbeat',
     'artifact.added',
     'file.changed',
     'usage.updated',
@@ -91,7 +93,39 @@ const approvalRequestedPayload = z.object({
     automatic: approvalAutomaticSchema.optional()
 });
 const approvalResolvedPayload = z.object({ approvalId: z.string(), decision: z.enum(['approved', 'denied', 'native']), automatic: approvalAutomaticSchema.optional() });
-export const questionOptionSchema = z.object({ label: z.string().min(1), description: z.string().optional(), recommended: z.boolean().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()
+});
 const questionBatchFields = {
     batchId: z.string().min(1).optional(),
     batchIndex: z.number().int().min(1).max(5).optional(),
@@ -110,12 +144,17 @@ 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(),
     ...questionBatchFields
-}).superRefine(questionBatchRefinement);
+}).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()),
@@ -140,6 +179,49 @@ export const checklistItemSchema = z.object({ text: z.string().min(1).max(500),
 export const MAX_CHECKLIST_ITEMS = 50;
 /** The whole checklist as the model last wrote it; the latest event replaces every earlier one. */
 const checklistPayload = z.object({ items: z.array(checklistItemSchema).max(MAX_CHECKLIST_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()
+}).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. */
@@ -191,9 +273,19 @@ 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()
+    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({
@@ -228,6 +320,8 @@ export const runEventPayloadSchemas = {
     'reaction.added': reactionAddedPayload,
     'agent.message': agentMessagePayload,
     'checklist.updated': checklistPayload,
+    checkpoint: checkpointPayload,
+    heartbeat: heartbeatPayload,
     'artifact.added': artifactPayload,
     'file.changed': fileChangedPayload,
     'usage.updated': usagePayloadSchema,
@@ -269,6 +363,7 @@ export const runRecordSchema = z.object({
     sessionId: z.string(),
     nativeSessionId: text,
     workingDirectory: text,
+    workspaceRoot: text.optional(),
     worktreeId: text,
     goal: text,
     attachmentCount: z.number().int().nonnegative().default(0),
@@ -281,7 +376,9 @@ export const runRecordSchema = z.object({
     agentId: text,
     trigger: text,
     variantScope: text.optional(),
-    variantVersion: text.optional()
+    variantVersion: text.optional(),
+    profile: text.optional(),
+    title: text.optional()
 });
 /** Records written before PROP-0009 name the variant `harnessScope` and `harnessVersion`. */
 export function upgradeRunRecord(raw) {

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;
+};

package/dist/sdk/sessions/control.js

@@ -0,0 +1,158 @@
+// Session commands that need no model: read the branch tree, move to another branch, fork, clone,
+// name, copy the last reply, and export to JSONL. They act on the saved native history directly,
+// so a host that opens one Pi session per turn offers the same commands as the terminal.
+// Compacting, navigating with a summary and exporting to HTML need a live session: they run as a
+// session command through `sessions.run` (see `SessionCommand`).
+import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
+import { isAbsolute, relative } from 'node:path';
+import { SessionManager } from '@earendil-works/pi-coding-agent';
+import { invalid, notFound } from "../core/errors.js";
+import { sessionFile as newestSessionFile } from "../prompt/compile.js";
+/** A move without a summary is saved as this entry, so the next turn opens on the chosen branch. */
+export const NAVIGATION_ENTRY = 'xingular-navigation';
+function within(dir, file) {
+    const path = relative(realpathSync(dir), realpathSync(file));
+    return !path.startsWith('..') && !isAbsolute(path);
+}
+function resolveFile(ref) {
+    if (!ref.sessionDir || !existsSync(ref.sessionDir))
+        throw notFound('This conversation has no saved history yet.');
+    const file = ref.sessionFile ?? newestSessionFile(ref.sessionDir);
+    if (!file || !existsSync(file))
+        throw notFound('This conversation has no saved history yet.');
+    if (!file.endsWith('.jsonl') || !within(ref.sessionDir, file))
+        throw invalid('The history must be a .jsonl file in the session folder.');
+    return realpathSync(file);
+}
+function open(ref, targetDir) {
+    const file = resolveFile(ref);
+    return { manager: SessionManager.open(file, targetDir ?? ref.sessionDir, ref.cwd ?? undefined), file };
+}
+function contentText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content.map((part) => part && typeof part === 'object' && part.type === 'text' ? String(part.text ?? '') : '').join(' ');
+}
+function entryText(entry) {
+    const record = entry;
+    if (entry.type === 'message') {
+        const message = record.message;
+        return { role: message?.role, text: contentText(message?.content) };
+    }
+    if (entry.type === 'branch_summary' || entry.type === 'compaction')
+        return { text: String(record.summary ?? '') };
+    if (entry.type === 'session_info')
+        return { text: String(record.name ?? '') };
+    if (entry.type === 'model_change')
+        return { text: `${record.provider ?? ''}/${record.modelId ?? ''}` };
+    return { text: '' };
+}
+const oneLine = (text) => text.replace(/\s+/g, ' ').trim().slice(0, 160);
+function flatten(nodes, depth, out) {
+    for (const node of nodes) {
+        const entry = node.entry;
+        const { role, text } = entryText(entry);
+        if (entry.type === 'custom' || entry.type === 'label') {
+            flatten(node.children, depth, out);
+            continue;
+        }
+        out.push({
+            id: entry.id,
+            parentId: entry.parentId ?? null,
+            type: entry.type,
+            ...(role ? { role } : {}),
+            text: oneLine(text),
+            ...(node.label ? { label: node.label } : {}),
+            timestamp: entry.timestamp,
+            depth
+        });
+        flatten(node.children, node.children.length > 1 ? depth + 1 : depth, out);
+    }
+}
+export function tree(ref) {
+    const { manager, file } = open(ref);
+    const entries = [];
+    flatten(manager.getTree(), 0, entries);
+    const forkPoints = manager.getBranch()
+        .filter((entry) => entry.type === 'message' && entryText(entry).role === 'user')
+        .map((entry) => ({ entryId: entry.id, text: oneLine(entryText(entry).text) }));
+    return { sessionFile: file, leafId: manager.getLeafId(), entries, forkPoints };
+}
+/**
+ * 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 function navigate(ref) {
+    const { manager } = open(ref);
+    const entry = manager.getEntry(ref.entryId);
+    if (!entry)
+        throw notFound(`No entry ${ref.entryId} in this conversation.`);
+    const { role, text } = entryText(entry);
+    const userMessage = entry.type === 'message' && role === 'user';
+    const target = userMessage ? entry.parentId ?? null : entry.id;
+    if (target)
+        manager.branch(target);
+    else
+        manager.resetLeaf();
+    manager.appendCustomEntry(NAVIGATION_ENTRY, { to: target });
+    return { leafId: target, ...(userMessage ? { editorText: text } : {}) };
+}
+/** A new history in `targetDir` that ends just before one of the person's messages. */
+export function fork(ref) {
+    const { manager } = open(ref, ensureDir(ref.targetDir));
+    const entry = manager.getEntry(ref.entryId);
+    const { role, text } = entry ? entryText(entry) : { text: '' };
+    if (!entry || entry.type !== 'message' || role !== 'user')
+        throw invalid('Fork from one of your messages.');
+    const sessionFile = entry.parentId
+        ? manager.createBranchedSession(entry.parentId)
+        : SessionManager.create(manager.getCwd(), ref.targetDir).getSessionFile();
+    if (!sessionFile)
+        throw invalid('The fork could not be saved.');
+    return { sessionFile, editorText: text };
+}
+/** A new history in `targetDir` with the whole current branch. */
+export function clone(ref) {
+    const { manager } = open(ref, ensureDir(ref.targetDir));
+    const leaf = manager.getLeafId();
+    if (!leaf)
+        throw invalid('Nothing to clone yet.');
+    const sessionFile = manager.createBranchedSession(leaf);
+    if (!sessionFile)
+        throw invalid('The clone could not be saved.');
+    return { sessionFile };
+}
+export function rename(ref) {
+    const name = ref.name.trim();
+    if (!name)
+        throw invalid('A session name cannot be empty.');
+    open(ref).manager.appendSessionInfo(name);
+    return { name };
+}
+/** The text of the last reply on the current branch, or null before the first. */
+export function lastReply(ref) {
+    const branch = open(ref).manager.getBranch();
+    for (let index = branch.length - 1; index >= 0; index -= 1) {
+        const { role, text } = entryText(branch[index]);
+        if (branch[index].type === 'message' && role === 'assistant' && text.trim())
+            return { text: text.trim() };
+    }
+    return { text: null };
+}
+/** Writes the current branch as JSONL. HTML needs a live session: see `SessionCommand`. */
+export function exportJsonl(ref) {
+    if (!isAbsolute(ref.path) || !ref.path.endsWith('.jsonl'))
+        throw invalid('Export to an absolute .jsonl path.');
+    const { manager } = open(ref);
+    const lines = [manager.getHeader(), ...manager.getBranch()].filter(Boolean).map((entry) => JSON.stringify(entry));
+    writeFileSync(ref.path, `${lines.join('\n')}\n`, 'utf8');
+    return { path: ref.path };
+}
+function ensureDir(dir) {
+    if (!isAbsolute(dir))
+        throw invalid('The new history folder must be an absolute path.');
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}