@deepseek-harness-tui/dsh-tui 0.11.1 → 0.11.2

package/lib/types/dsh-adapter/migrate/picker.d.ts

@@ -0,0 +1,64 @@
+import { type AdapterScanSpec } from './recent-agents.js';
+/** One selectable picker row (rendered by components/MigratePicker.tsx). */
+export interface MigratePickerRow {
+    readonly agentId: string;
+    readonly label: string;
+    readonly count: number;
+    /** Minutes since the newest source activity, when inside the window. */
+    readonly minutesAgo?: number;
+}
+/** Each adapter's name-only scan shape, shared by count() callers and the activity hint. */
+export declare const MIGRATE_SCAN_SPECS: Readonly<Record<string, AdapterScanSpec>>;
+/**
+ * Collect picker rows for every registered adapter: scan count plus a
+ * recent-activity badge when the source was used inside the window. Recent
+ * sources sort first (newest activity at top), cold sources keep registry
+ * order. Sub-second at real-world scale, but still meant for a background
+ * pass — never the render path.
+ */
+export declare function collectMigratePickerRows(nowMs: number): MigratePickerRow[];
+/** One source's import outcome, parsed from the CLI child's stdout. */
+export interface ImportSummary {
+    readonly agentId: string;
+    readonly imported: number;
+    readonly existing: number;
+}
+/**
+ * Parse per-source import counters out of the CLI's report lines
+ * (`[<agentId>] imported 12 · already present 3`). Pure string work so the
+ * TUI's completion notification can carry real numbers (PRD #3) without
+ * re-running any scan.
+ */
+export declare function parseImportSummary(stdout: string): ImportSummary[];
+/**
+ * Classify one `/migrate` command line (the text AFTER the command word) into
+ * the action Chat must take. Pure and registry-driven on purpose: whether a
+ * command is valid must never depend on the picker having been opened first
+ * (`migrateRows` is empty on a fresh mount, which used to make every
+ * `/migrate <agent>` report an unknown source), and the CLI keeps the same
+ * one-source rule (`dsh-tui migrate a b` is a usage error there too).
+ *
+ * @param rawInput - arguments after `/migrate`, e.g. `" claude-code --dry-run"`.
+ * @param knownAgentIds - the adapter registry's ids (see MIGRATION_ADAPTERS).
+ */
+export declare function resolveMigrateCommand(rawInput: string, knownAgentIds: readonly string[]): MigrateCommand;
+/** What one `/migrate` line asks for. */
+export type MigrateCommand = {
+    readonly kind: 'picker';
+} | {
+    readonly kind: 'import';
+    readonly agentId: string;
+    readonly dryRun: boolean;
+} | {
+    readonly kind: 'unknown';
+    readonly agentId: string;
+}
+/** More than one source named: rejected, like the CLI's usage error. */
+ | {
+    readonly kind: 'usage';
+}
+/** `--dry-run` with no source: previewing needs to know what to preview. */
+ | {
+    readonly kind: 'dry-run-needs-source';
+};
+//# sourceMappingURL=picker.d.ts.map

package/lib/types/dsh-adapter/migrate/picker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"picker.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/migrate/picker.ts"],"names":[],"mappings":"AAWA,OAAO,EAA4C,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAEnG,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,wEAAwE;IACxE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAMxE,CAAA;AAID;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAc1E;AAED,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,CAUlE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CAWxG;AAED,yCAAyC;AACzC,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC/E;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AACxD,wEAAwE;GACtE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE;AAC5B,4EAA4E;GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAA;CAAE,CAAA"}

package/lib/types/dsh-adapter/migrate/picker.js

@@ -0,0 +1,86 @@
+/**
+ * Data collection for the `/migrate` source picker, plus the command
+ * classifier and the child-report parser.
+ *
+ * Combines the name-only scan count (list mode's fast path) with the
+ * recent-activity detector into the row shape the picker renders. Pure data:
+ * no React, no Cordis — Chat imports these helpers and owns all UI.
+ *
+ * @module @deepseek-harness-tui/dsh-tui/migrate/picker
+ */
+import { MIGRATION_ADAPTERS } from './index.js';
+import { collectActivitySamples, recentAgentsFrom } from './recent-agents.js';
+/** Each adapter's name-only scan shape, shared by count() callers and the activity hint. */
+export const MIGRATE_SCAN_SPECS = {
+    'claude-code': { maxDepth: 3, fileMatch: name => name.endsWith('.jsonl') },
+    codex: { maxDepth: 5, fileMatch: name => name.startsWith('rollout-') && name.endsWith('.jsonl') },
+    omp: { maxDepth: 3, fileMatch: name => name.endsWith('.jsonl') },
+    zcode: { maxDepth: 3, fileMatch: name => name.endsWith('.json') },
+    'grok-build': { maxDepth: 2, fileMatch: name => name === 'chat_history.jsonl' },
+};
+const scanOf = (agentId) => MIGRATE_SCAN_SPECS[agentId];
+/**
+ * Collect picker rows for every registered adapter: scan count plus a
+ * recent-activity badge when the source was used inside the window. Recent
+ * sources sort first (newest activity at top), cold sources keep registry
+ * order. Sub-second at real-world scale, but still meant for a background
+ * pass — never the render path.
+ */
+export function collectMigratePickerRows(nowMs) {
+    const samples = collectActivitySamples(MIGRATION_ADAPTERS, adapter => scanOf(adapter.id));
+    const recent = new Map(recentAgentsFrom(samples, nowMs).map(agent => [agent.agentId, agent.minutesAgo]));
+    const rows = MIGRATION_ADAPTERS.map(adapter => ({
+        agentId: adapter.id,
+        label: adapter.label,
+        count: adapter.count !== undefined ? adapter.count() : adapter.discover().sessions.length,
+        minutesAgo: recent.get(adapter.id),
+    }));
+    return rows.sort((a, b) => {
+        const aRecent = a.minutesAgo ?? Number.MAX_SAFE_INTEGER;
+        const bRecent = b.minutesAgo ?? Number.MAX_SAFE_INTEGER;
+        return aRecent - bRecent;
+    });
+}
+/**
+ * Parse per-source import counters out of the CLI's report lines
+ * (`[<agentId>] imported 12 · already present 3`). Pure string work so the
+ * TUI's completion notification can carry real numbers (PRD #3) without
+ * re-running any scan.
+ */
+export function parseImportSummary(stdout) {
+    const summaries = [];
+    for (const match of stdout.matchAll(/\[([a-z0-9-]+)\] imported (\d+)(?: · already present (\d+))?/gu)) {
+        summaries.push({
+            agentId: match[1],
+            imported: Number(match[2]),
+            existing: match[3] === undefined ? 0 : Number(match[3]),
+        });
+    }
+    return summaries;
+}
+/**
+ * Classify one `/migrate` command line (the text AFTER the command word) into
+ * the action Chat must take. Pure and registry-driven on purpose: whether a
+ * command is valid must never depend on the picker having been opened first
+ * (`migrateRows` is empty on a fresh mount, which used to make every
+ * `/migrate <agent>` report an unknown source), and the CLI keeps the same
+ * one-source rule (`dsh-tui migrate a b` is a usage error there too).
+ *
+ * @param rawInput - arguments after `/migrate`, e.g. `" claude-code --dry-run"`.
+ * @param knownAgentIds - the adapter registry's ids (see MIGRATION_ADAPTERS).
+ */
+export function resolveMigrateCommand(rawInput, knownAgentIds) {
+    const words = rawInput.trim().split(/\s+/u).filter(Boolean);
+    const dryRun = words.includes('--dry-run');
+    const agents = words.filter(word => word !== '--dry-run');
+    // One source per invocation: the CLI rejects a second word, and silently
+    // importing only the first would hide which selection the user asked for.
+    if (agents.length > 1)
+        return { kind: 'usage' };
+    const wanted = agents[0];
+    if (wanted === undefined)
+        return dryRun ? { kind: 'dry-run-needs-source' } : { kind: 'picker' };
+    if (!knownAgentIds.includes(wanted))
+        return { kind: 'unknown', agentId: wanted };
+    return { kind: 'import', agentId: wanted, dryRun };
+}

package/lib/types/dsh-adapter/migrate/recent-agents.d.ts

@@ -0,0 +1,40 @@
+import type { MigrationAdapter } from './types.js';
+/** How recent the newest source activity must be to earn a hint. */
+export declare const RECENT_ACTIVITY_WINDOW_MS: number;
+/** One source's last-activity sample. `newestMtimeMs: null` = no data. */
+export interface ActivitySample {
+    readonly agentId: string;
+    readonly label: string;
+    readonly newestMtimeMs: number | null;
+}
+/** A source that was active inside the window. */
+export interface RecentAgent {
+    readonly agentId: string;
+    readonly label: string;
+    /** Minutes since the newest activity, rounded down (≥ 0). */
+    readonly minutesAgo: number;
+}
+/**
+ * Pure judgment: which samples count as recent, newest first.
+ * @param samples - one per source, `null` mtime = no data (never recent).
+ * @param nowMs - the current epoch milliseconds (injected for testability).
+ * @param windowMs - activity window, default 20 minutes.
+ */
+export declare function recentAgentsFrom(samples: readonly ActivitySample[], nowMs: number, windowMs?: number): RecentAgent[];
+/**
+ * Newest file mtime under one set of roots, name-matched only (the counter's
+ * walk shape — no parsing). Returns null when nothing matches or IO fails;
+ * failures must read as "no data", never as "long ago".
+ */
+export declare function collectNewestMtime(roots: readonly string[], fileMatch: (name: string) => boolean, maxDepth: number): number | null;
+/** The file-name matcher and walk depth an adapter's count() uses. */
+export interface AdapterScanSpec {
+    readonly maxDepth: number;
+    readonly fileMatch: (name: string) => boolean;
+}
+/**
+ * Collect one sample per adapter that can describe its scan; adapters
+ * without count() (no name-only scan shape) are skipped, not guessed.
+ */
+export declare function collectActivitySamples(adapters: readonly MigrationAdapter[], scanOf: (adapter: MigrationAdapter) => AdapterScanSpec | undefined): ActivitySample[];
+//# sourceMappingURL=recent-agents.d.ts.map

package/lib/types/dsh-adapter/migrate/recent-agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recent-agents.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/migrate/recent-agents.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD,oEAAoE;AACpE,eAAO,MAAM,yBAAyB,QAAiB,CAAA;AAEvD,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CACtC;AAED,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,KAAK,EAAE,MAAM,EACb,QAAQ,GAAE,MAAkC,GAC3C,WAAW,EAAE,CAUf;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,EACpC,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,IAAI,CA4Bf;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAA;CAC9C;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,MAAM,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,eAAe,GAAG,SAAS,GACjE,cAAc,EAAE,CAYlB"}

package/lib/types/dsh-adapter/migrate/recent-agents.js

@@ -0,0 +1,100 @@
+/**
+ * Recent foreign-agent activity detection for the migration hint.
+ *
+ * "Did the user just come from another coding agent?" is answered from file
+ * mtimes inside each source store: an active conversation appends to its
+ * log in real time (claude-code updates within the same minute), so the
+ * NEWEST file mtime per source is a faithful last-activity signal with good
+ * separation (measured on a real machine: 0min vs 117min vs 5867min across
+ * sources). Parent-directory mtimes would miss appends to existing
+ * conversations, so the scan is file-level — bounded by the same
+ * name-matching walk as the list-mode counter (sub-second at ~3000 files)
+ * and meant for a BACKGROUND pass, never the render path.
+ *
+ * Split: `recentAgentsFrom` is a pure judgment over collected samples
+ * (directly testable with fixture mtimes); `collectNewestMtime` is the IO
+ * collector; `detectRecentAgents` binds them for the TUI.
+ *
+ * @module @deepseek-harness-tui/dsh-tui/migrate/recent-agents
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/** How recent the newest source activity must be to earn a hint. */
+export const RECENT_ACTIVITY_WINDOW_MS = 20 * 60 * 1000;
+/**
+ * Pure judgment: which samples count as recent, newest first.
+ * @param samples - one per source, `null` mtime = no data (never recent).
+ * @param nowMs - the current epoch milliseconds (injected for testability).
+ * @param windowMs - activity window, default 20 minutes.
+ */
+export function recentAgentsFrom(samples, nowMs, windowMs = RECENT_ACTIVITY_WINDOW_MS) {
+    const recent = [];
+    for (const sample of samples) {
+        if (sample.newestMtimeMs === null)
+            continue;
+        const age = nowMs - sample.newestMtimeMs;
+        if (age < 0 || age > windowMs)
+            continue;
+        recent.push({ agentId: sample.agentId, label: sample.label, minutesAgo: Math.floor(age / 60_000) });
+    }
+    recent.sort((a, b) => a.minutesAgo - b.minutesAgo);
+    return recent;
+}
+/**
+ * Newest file mtime under one set of roots, name-matched only (the counter's
+ * walk shape — no parsing). Returns null when nothing matches or IO fails;
+ * failures must read as "no data", never as "long ago".
+ */
+export function collectNewestMtime(roots, fileMatch, maxDepth) {
+    const match = fileMatch;
+    let newest = null;
+    const walk = (dir, depth) => {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(path, depth + 1);
+                continue;
+            }
+            if (!entry.isFile() || !match(entry.name))
+                continue;
+            try {
+                const mtimeMs = statSync(path).mtimeMs;
+                if (newest === null || mtimeMs > newest)
+                    newest = mtimeMs;
+            }
+            catch {
+                // A stat race on one file costs that file, not the scan.
+            }
+        }
+    };
+    for (const root of roots)
+        walk(root, 0);
+    return newest;
+}
+/**
+ * Collect one sample per adapter that can describe its scan; adapters
+ * without count() (no name-only scan shape) are skipped, not guessed.
+ */
+export function collectActivitySamples(adapters, scanOf) {
+    const samples = [];
+    for (const adapter of adapters) {
+        const spec = scanOf(adapter);
+        if (spec === undefined)
+            continue;
+        samples.push({
+            agentId: adapter.id,
+            label: adapter.label,
+            newestMtimeMs: collectNewestMtime(adapter.roots(), spec.fileMatch, spec.maxDepth),
+        });
+    }
+    return samples;
+}

package/lib/types/dsh-adapter/migrate/sessionize.d.ts

@@ -0,0 +1,39 @@
+import { SessionId, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session';
+import type { MigrationSession } from './types.js';
+/** One migration turn's model-visible outcome, ready for persistence. */
+export interface SessionizedLog {
+    readonly header: SessionHeader;
+    readonly events: readonly SessionEvent[];
+}
+/**
+ * The empty system head an imported log opens with, in whichever shape the
+ * installed harness writes. `createSystemMessage` changed arity between the
+ * validated lines: 0.1.5-alpha.2 takes the owning plugin and stamps a plugin
+ * source, later lines take the text alone and stamp `system-prompt`. Calling
+ * it with both arguments lets each line build its own native head (the later
+ * one ignores the extra argument) instead of this module hard-coding either.
+ */
+/**
+ * The checkpoint framing the native compaction engine writes around a summary
+ * (dsh-compaction-basic `frameSummary`): a preamble, then the summary inside
+ * `<compacted-summary>` tags. The tags are how a LATER compaction recognises
+ * this node as a prior checkpoint and merges it instead of summarising the
+ * summary, so an imported checkpoint has to carry them exactly. The package
+ * does not export the constants; verify-migrate pins these against the
+ * installed engine's own source so a drift fails the regression.
+ */
+export declare const CHECKPOINT_PREAMBLE = "This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.";
+export declare const SUMMARY_OPEN_TAG = "<compacted-summary>";
+export declare const SUMMARY_CLOSE_TAG = "</compacted-summary>";
+/**
+ * Build one official DSH session log from a normalized foreign conversation.
+ *
+ * @param id - deterministic session id (see uuid.ts); the id IS the dedupe.
+ * @param agentId - source adapter id, stamped into assistant provenance as
+ *   `migrated:<agentId>` so the transcript can name where text came from.
+ * @param session - the normalized foreign conversation.
+ * @returns the official header plus the full event log, exactly as the
+ *   persistence backend expects them.
+ */
+export declare function sessionize(id: SessionId, agentId: string, session: MigrationSession): SessionizedLog;
+//# sourceMappingURL=sessionize.d.ts.map

package/lib/types/dsh-adapter/migrate/sessionize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionize.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/migrate/sessionize.ts"],"names":[],"mappings":"AA0DA,OAAO,EAGL,SAAS,EAET,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAA;AAGjC,OAAO,KAAK,EAAc,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAc9D,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;CACzC;AAgBD;;;;;;;GAOG;AACH;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,iTAAiT,CAAA;AACjV,eAAO,MAAM,gBAAgB,wBAAwB,CAAA;AACrD,eAAO,MAAM,iBAAiB,yBAAyB,CAAA;AAevD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,cAAc,CAmJpG"}

package/lib/types/dsh-adapter/migrate/sessionize.js

@@ -0,0 +1,271 @@
+/**
+ * Cross-agent conversation migration: MigrationSession → official DSH events.
+ *
+ * The sessionize step owns NO storage decisions. It drives the official
+ * `Session` logical-event API (`Session.create` + `append`), so envelope
+ * fields (seq/time/id), surface contract and format version come from the
+ * upstream implementation — the part the first iteration of this feature got
+ * wrong by hand-crafting physical log rows. Physical encoding, project
+ * layout, zstd and atomic writes belong to JsonlSessionPersistence (see
+ * index.ts), exactly as scripts/migrate-sessions-to-jsonl.mts does for the
+ * retired sqlite store.
+ *
+ * Turn shape follows the live loop: `turn/start`, then one step per
+ * {@link ImportStep} with the turn's prompt as the first step's user message,
+ * then `turn/end`. A turn with no prompt (source lost its head) carries no
+ * user message; a turn with no step is a legal step-less turn whose prompt
+ * sits directly inside the turn.
+ *
+ * Inside a step, events follow the live loop too: the step's user inputs
+ * (mid-turn context), the assistant message whose content carries the
+ * tool-call blocks, one `tool/call` per call, then one `tool/result` per
+ * call citing its call event. Parsing already closed every call
+ * (closeToolPairs), so no step leaves a call unanswered — the invariant the
+ * wire needs on resume: every tool call is followed by its tool message
+ * before any later assistant message.
+ *
+ * System head: the live loop reserves surface node 0 for the system prompt
+ * (an empty `system/message` in the first step, before any user message).
+ * An imported log gets the same empty head: it projects to no message, so
+ * re-reading is unchanged, and when the session is resumed the loop REPLACES
+ * it with the rendered prompt. Without it the loop appends its prompt after
+ * the imported history, where adapters that only lift a LEADING system
+ * message (pi-ai) send it as one more user message.
+ *
+ * Compaction: a turn carrying {@link ImportTurn.compaction} is preceded by
+ * one native compaction transaction — `compaction/start` (standalone,
+ * `turn: null`), `compaction/summary`, the checkpoint `user/message` that
+ * REPLACES every surface node after the head, `compaction/end` — the same
+ * shape `/compact` writes. The raw log keeps the shadowed events (replay
+ * stays exact) while the model sees the checkpoint plus what follows, which
+ * is the context the source agent itself continued with. The upstream
+ * compaction package is not a dependency here, so its event and source
+ * shapes are written structurally (see compactionEvents below).
+ *
+ * Title: only a title the SOURCE owns (`titleExplicit`) is written, as one
+ * trailing `session/title` — a first-prompt fallback is left out so DSH
+ * derives it from the first user message exactly as for a native session.
+ *
+ * @module @deepseek-harness-tui/dsh-tui/migrate/sessionize
+ */
+import { ToolCallId, createAssistantMessage, createSystemMessage, createToolResultMessage, createUserMessage, } from '@deepseek-ai/dsh-llm';
+import { SESSION_FORMAT_VERSION, Session, } from '@deepseek-ai/dsh-session';
+import { userTitleData } from '../compat/sessionLog.js';
+import { normalizeTitle } from './parse/title.js';
+/** Rough token estimate for shadowed text (the compaction metering field). */
+function estimateTokens(chars) {
+    return Math.ceil(chars / 4);
+}
+/** Blocks for one migrated step, in source order (reasoning before the text
+ *  it explains, tool calls where the model made them). A step with no
+ *  content keeps one empty text block so the assistant message stays
+ *  well-formed. */
+function assistantBlocks(step) {
+    const blocks = step.blocks.map(block => block.type === 'tool-call'
+        ? { type: 'tool-call', id: ToolCallId(block.id), name: block.name, arguments: block.arguments }
+        : { type: block.type, text: block.text });
+    if (blocks.length === 0)
+        blocks.push({ type: 'text', text: '' });
+    return blocks;
+}
+/**
+ * The empty system head an imported log opens with, in whichever shape the
+ * installed harness writes. `createSystemMessage` changed arity between the
+ * validated lines: 0.1.5-alpha.2 takes the owning plugin and stamps a plugin
+ * source, later lines take the text alone and stamp `system-prompt`. Calling
+ * it with both arguments lets each line build its own native head (the later
+ * one ignores the extra argument) instead of this module hard-coding either.
+ */
+/**
+ * The checkpoint framing the native compaction engine writes around a summary
+ * (dsh-compaction-basic `frameSummary`): a preamble, then the summary inside
+ * `<compacted-summary>` tags. The tags are how a LATER compaction recognises
+ * this node as a prior checkpoint and merges it instead of summarising the
+ * summary, so an imported checkpoint has to carry them exactly. The package
+ * does not export the constants; verify-migrate pins these against the
+ * installed engine's own source so a drift fails the regression.
+ */
+export const CHECKPOINT_PREAMBLE = 'This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.';
+export const SUMMARY_OPEN_TAG = '<compacted-summary>';
+export const SUMMARY_CLOSE_TAG = '</compacted-summary>';
+function frameCheckpoint(summary) {
+    return [
+        { type: 'text', text: `${CHECKPOINT_PREAMBLE}\n\n${SUMMARY_OPEN_TAG}` },
+        { type: 'text', text: summary },
+        { type: 'text', text: SUMMARY_CLOSE_TAG },
+    ];
+}
+function emptySystemHead() {
+    const create = createSystemMessage;
+    return create('', 'dsh-tui-migrate');
+}
+/**
+ * Build one official DSH session log from a normalized foreign conversation.
+ *
+ * @param id - deterministic session id (see uuid.ts); the id IS the dedupe.
+ * @param agentId - source adapter id, stamped into assistant provenance as
+ *   `migrated:<agentId>` so the transcript can name where text came from.
+ * @param session - the normalized foreign conversation.
+ * @returns the official header plus the full event log, exactly as the
+ *   persistence backend expects them.
+ */
+export function sessionize(id, agentId, session) {
+    const header = {
+        version: SESSION_FORMAT_VERSION,
+        id,
+        createdAt: session.startedAt,
+        cwd: session.cwd,
+        isSeeded: false,
+    };
+    const model = Session.create(id, undefined, header);
+    // Collect each append()'s RETURN (a fully enveloped event) instead of the
+    // deprecated snapshotEvents() bulk read — upstream forbids NEW callers of
+    // the latter, and append already returns seq/time-stamped events.
+    const events = [];
+    let headWritten = false;
+    const writeHead = (turn, step) => {
+        events.push(model.append('system/message', { turn, step, message: emptySystemHead() }, { surfaceOp: 'append' }));
+        headWritten = true;
+    };
+    const writePrompt = (prompt) => {
+        if (prompt === '')
+            return;
+        surfaceChars += prompt.length;
+        events.push(model.append('user/message', createUserMessage({
+            content: [{ type: 'text', text: prompt }],
+            source: { kind: 'user' },
+        }), { surfaceOp: 'append' }));
+    };
+    const writeTools = (turn, step, imported) => {
+        const callSeqs = new Map();
+        for (const block of imported.blocks) {
+            if (block.type !== 'tool-call')
+                continue;
+            const call = model.append('tool/call', { turn, step, callId: ToolCallId(block.id), name: block.name, arguments: block.arguments });
+            events.push(call);
+            callSeqs.set(block.id, call.seq);
+        }
+        for (const result of imported.results) {
+            const callSeq = callSeqs.get(result.callId);
+            if (callSeq === undefined)
+                continue;
+            events.push(model.append('tool/result', {
+                turn,
+                step,
+                message: createToolResultMessage({
+                    callId: ToolCallId(result.callId),
+                    content: result.text === '' ? [] : [{ type: 'text', text: result.text }],
+                    isError: result.isError,
+                }),
+            }, { surfaceOp: 'append', sourceEventSeqs: [callSeq] }));
+        }
+    };
+    let compactions = 0;
+    // Text volume on the surface since the last checkpoint, for the summary's
+    // shadowedTokenCount (an estimate, like the live engine's).
+    let surfaceChars = 0;
+    /** Fold every surface node after the head into one checkpoint; false when
+     *  there is nothing to fold (the upstream contract needs a non-empty span). */
+    const writeCompaction = (summary, summaryModel) => {
+        const shadowed = model.surface.nodes.filter(seq => model.eventAt(seq)?.type !== 'system/message');
+        if (shadowed.length === 0)
+            return false;
+        compactions += 1;
+        const compactionId = `import:${id}:c${compactions}`;
+        const untyped = model;
+        const range = { start: shadowed[0], end: shadowed[shadowed.length - 1] };
+        events.push(untyped.append('compaction/start', { compactionId, turn: null }));
+        events.push(untyped.append('compaction/summary', {
+            compactionId,
+            summary: [{ type: 'text', text: summary }],
+            shadowedRange: range,
+            shadowedSeqs: shadowed,
+            shadowedTokenCount: estimateTokens(surfaceChars),
+            provider: `migrated:${agentId}`,
+            model: summaryModel ?? agentId,
+        }));
+        events.push(untyped.append('user/message', createUserMessage({
+            content: frameCheckpoint(summary),
+            // The compaction package's checkpoint marker (COMPACT_CHECKPOINT_MARKER).
+            source: { kind: 'compact-checkpoint', compactionId },
+        }), { surfaceOp: { op: 'replace', startSeq: range.start, endSeq: range.end }, sourceEventSeqs: shadowed }));
+        events.push(untyped.append('compaction/end', { compactionId, turn: null }));
+        surfaceChars = summary.length;
+        return true;
+    };
+    let turnIndex = 0;
+    for (const turn of session.turns) {
+        // A summary with nothing before it to fold still reaches the model: it
+        // opens the turn as a plain user message instead.
+        let preface = '';
+        if (turn.compaction !== undefined && turn.compaction.summary !== '') {
+            if (!writeCompaction(turn.compaction.summary, turn.compaction.model))
+                preface = turn.compaction.summary;
+            // A boundary with no prompt and no step (the source stopped right at
+            // the compaction) needs no turn of its own.
+            if (turn.prompt === '' && turn.steps.length === 0 && preface === '')
+                continue;
+        }
+        turnIndex += 1;
+        events.push(model.append('turn/start', { turn: turnIndex }));
+        if (turn.steps.length === 0) {
+            if (headWritten) {
+                writePrompt(preface);
+                writePrompt(turn.prompt);
+            }
+            else {
+                // The head needs an open step; a step-less first turn gets one that
+                // carries only the head and the prompt (no model call).
+                events.push(model.append('step/start', { turn: turnIndex, step: 1 }));
+                writeHead(turnIndex, 1);
+                writePrompt(preface);
+                writePrompt(turn.prompt);
+                events.push(model.append('step/end', { turn: turnIndex, step: 1 }));
+            }
+        }
+        let step = 0;
+        for (const imported of turn.steps) {
+            step += 1;
+            events.push(model.append('step/start', { turn: turnIndex, step }));
+            if (!headWritten)
+                writeHead(turnIndex, step);
+            if (step === 1) {
+                writePrompt(preface);
+                writePrompt(turn.prompt);
+            }
+            for (const input of imported.inputs)
+                writePrompt(input);
+            for (const block of imported.blocks)
+                surfaceChars += block.type === 'tool-call' ? block.arguments.length : block.text.length;
+            for (const result of imported.results)
+                surfaceChars += result.text.length;
+            events.push(model.append('assistant/message', {
+                turn: turnIndex,
+                step,
+                message: createAssistantMessage({
+                    content: assistantBlocks(imported),
+                    // createAssistantMessage stamps `kind: 'model'` itself; the
+                    // caller-visible provenance is provider + model only.
+                    source: {
+                        provider: `migrated:${agentId}`,
+                        model: imported.model ?? agentId,
+                    },
+                }),
+                stream: [],
+            }, { surfaceOp: 'append' }));
+            writeTools(turnIndex, step, imported);
+            events.push(model.append('step/end', { turn: turnIndex, step }));
+        }
+        // A source-recorded interruption keeps its meaning. Sources record it
+        // coarsely (no user/hook/dispose distinction), which is exactly what the
+        // `legacy` cancel cause exists for.
+        events.push(model.append('turn/end', {
+            turn: turnIndex,
+            reason: turn.aborted === true ? { kind: 'aborted', reason: { kind: 'legacy' } } : { kind: 'completed' },
+        }));
+    }
+    const title = session.titleExplicit ? normalizeTitle(session.title) : '';
+    if (title !== '')
+        events.push(model.append('session/title', userTitleData(title)));
+    return { header: model.header, events };
+}