@geminixiang/mikan 1.0.0-beta.7 → 1.0.0-beta.71

package/dist/sessions/migrate-v3.js

@@ -0,0 +1,419 @@
+/**
+ * One-time migration of legacy v3 session files to pi's v4 JSONL format.
+ *
+ * v3 is the entry family mikan wrote up to pi 0.83: a `{"type":"session"}`
+ * header followed by tree entries with string ISO timestamps and compaction
+ * entries that point at `firstKeptEntryId`. Current Pi v4 uses a
+ * `{"v":4,"kind":"header","storageVersion":1}` header followed by
+ * transactional writes with numeric timestamps and consecutive sequences.
+ *
+ * The migration preserves entry ids, parent links, and timestamps, converts
+ * `custom_message` entries into v4 `custom`-role messages, folds
+ * `session_info` into the v4 name fact, `label` entries into label facts,
+ * and rewrites each compaction's kept range into its inline `retainedTail`.
+ * Every migrated file is verified before it replaces the original: the v4
+ * file is re-opened with pi's reader and its built context must equal the
+ * v3 context computed by the reference converter below. The original file
+ * is kept beside the migrated one as `<name>.v3.bak`.
+ */
+import { readFileSync } from "node:fs";
+import { createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage, } from "@earendil-works/pi-agent-core";
+import { SessionStore } from "./session-store.js";
+import { commitMigration, findSessionFiles, optionalAnnotations, V4FileWriter, } from "./migrate-common.js";
+/** `session_info`, `label` and `leaf` become v4 values, not tree entries. */
+function isFactEntry(entry) {
+    return entry.type === "session_info" || entry.type === "label" || entry.type === "leaf";
+}
+/** Whether a file's first non-empty line is a v3 session header. */
+export function isV3SessionFile(filePath) {
+    try {
+        const content = readFileSync(filePath, "utf-8");
+        const firstLine = content.split("\n").find((line) => line.trim().length > 0);
+        if (!firstLine)
+            return false;
+        const parsed = JSON.parse(firstLine);
+        return parsed.type === "session";
+    }
+    catch {
+        return false;
+    }
+}
+/** Parse every non-empty line, tolerating a torn final line (crash tail). */
+function parseJsonLines(filePath) {
+    const lines = readFileSync(filePath, "utf-8")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    const records = [];
+    for (const [index, line] of lines.entries()) {
+        try {
+            records.push(JSON.parse(line));
+        }
+        catch (error) {
+            if (index === lines.length - 1 && index > 0)
+                continue;
+            throw new Error(`Invalid JSON on line ${index + 1} of ${filePath}`, { cause: error });
+        }
+    }
+    return records;
+}
+/**
+ * Crash-era v3 files can contain duplicated lines (a retried append wrote the
+ * header+entry pair twice). The v3 runtime read entries into a Map, so
+ * duplicates were silently collapsed; v4 rejects duplicate mutation ids.
+ * Reproduce the v3 Map semantics: a repeated id replaces its payload while
+ * retaining the id's original insertion position.
+ */
+function dedupeEntries(records) {
+    const entriesById = new Map();
+    for (const record of records) {
+        if (typeof record.type !== "string" || typeof record.id !== "string")
+            continue;
+        if (record.type === "session")
+            continue;
+        entriesById.set(record.id, record);
+    }
+    return [...entriesById.values()];
+}
+/** Read a v3 session file, ignoring a torn final line (crash tail). */
+function readV3SessionFile(filePath) {
+    const records = parseJsonLines(filePath);
+    const header = records[0];
+    if (!header || header.type !== "session" || typeof header.id !== "string") {
+        throw new Error(`Not a v3 session file: ${filePath}`);
+    }
+    return {
+        header: header,
+        entries: dedupeEntries(records.slice(1)),
+    };
+}
+function toEpochMillis(timestamp) {
+    const parsed = Date.parse(timestamp);
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+/** Walk a v3 tree from an entry to the root; returns root-first path order. */
+function v3Branch(entries, fromId) {
+    const byId = new Map(entries.map((entry) => [entry.id, entry]));
+    const path = [];
+    let currentId = fromId;
+    while (currentId) {
+        const entry = byId.get(currentId);
+        if (!entry)
+            break;
+        path.push(entry);
+        currentId = entry.parentId;
+    }
+    return path.toReversed();
+}
+function v3LeafId(entries) {
+    let leafId = null;
+    for (const entry of entries) {
+        leafId = entry.type === "leaf" ? entry.targetId : entry.id;
+    }
+    return leafId;
+}
+/** v3 kept `custom_message` payloads out of band; v4 stores a real message. */
+function customMessageOf(entry) {
+    return createCustomMessage(entry.customType, entry.content, entry.display, entry.details, toEpochMillis(entry.timestamp));
+}
+/** Convert one tree-shaping v3 entry to its v4 counterpart (facts excluded). */
+function convertEntry(entry, entries) {
+    const base = {
+        id: entry.id,
+        seq: 0, // assigned at mutation-encoding time
+        parentId: resolveV4Parent(entry, entries),
+        timestamp: toEpochMillis(entry.timestamp),
+    };
+    switch (entry.type) {
+        case "message":
+            return { ...base, type: "message", message: entry.message };
+        case "custom_message":
+            return { ...base, type: "message", message: customMessageOf(entry) };
+        case "thinking_level_change":
+        case "model_change":
+        case "active_tools_change": {
+            const { id: _id, parentId: _parentId, timestamp: _timestamp, type, ...data } = entry;
+            return {
+                ...base,
+                type: "custom",
+                customType: `mikan.legacy.${type}`,
+                data: data,
+            };
+        }
+        case "compaction":
+            return {
+                ...base,
+                type: "compaction",
+                summary: entry.summary,
+                retainedTail: entry.retainedTail ?? compactionKeptMessages(entry, entries),
+                tokensBefore: entry.tokensBefore,
+                fromHook: false,
+                ...optionalAnnotations(entry),
+            };
+        case "branch_summary":
+            return {
+                ...base,
+                type: "branch_summary",
+                fromId: entry.fromId ?? null,
+                summary: entry.summary,
+                fromHook: false,
+                ...optionalAnnotations(entry),
+            };
+        case "custom":
+            return {
+                ...base,
+                type: "custom",
+                customType: entry.customType,
+                ...(entry.data !== undefined ? { data: entry.data } : {}),
+            };
+        default:
+            // session_info / label / leaf become facts and the lane pointer.
+            return null;
+    }
+}
+/**
+ * Skip fact-only ancestors (session_info/label/leaf) when re-linking the v4
+ * tree: those entries disappear from the entry stream, so children re-attach
+ * to the nearest surviving ancestor.
+ */
+function resolveV4Parent(entry, entries) {
+    const byId = new Map(entries.map((item) => [item.id, item]));
+    let parentId = entry.parentId;
+    while (parentId !== null) {
+        const parent = byId.get(parentId);
+        if (!parent)
+            return null;
+        if (!isFactEntry(parent))
+            return parentId;
+        parentId = parent.parentId;
+    }
+    return null;
+}
+/**
+ * Messages of the v3 kept range (`firstKeptEntryId` .. compaction parent),
+ * which v4 stores inline on the compaction entry.
+ */
+function compactionKeptMessages(compaction, entries) {
+    if (!compaction.firstKeptEntryId)
+        return [];
+    const ancestors = v3Branch(entries, compaction.parentId);
+    const keptStart = ancestors.findIndex((entry) => entry.id === compaction.firstKeptEntryId);
+    if (keptStart === -1)
+        return [];
+    const messages = [];
+    for (const entry of ancestors.slice(keptStart)) {
+        if (entry.type === "message")
+            messages.push(entry.message);
+        else if (entry.type === "custom_message")
+            messages.push(customMessageOf(entry));
+    }
+    return messages;
+}
+// ── reference converter (verification oracle) ───────────────────────────────
+/**
+ * Reorder a v3 branch the way the pi-0.83 context shim did: the last
+ * compaction moves ahead of its kept range. The branch is returned unchanged
+ * when there is no such compaction or it already carries a `retainedTail`.
+ */
+function orderForReference(branch) {
+    const lastIndex = branch.findLastIndex((entry) => entry.type === "compaction");
+    const lastCompaction = branch[lastIndex];
+    const firstKeptId = lastCompaction?.retainedTail ? undefined : lastCompaction?.firstKeptEntryId;
+    const firstKeptIndex = firstKeptId === undefined ? -1 : branch.findIndex((entry) => entry.id === firstKeptId);
+    if (firstKeptIndex === -1 || !lastCompaction)
+        return { ordered: branch };
+    return {
+        ordered: [
+            ...branch.slice(0, firstKeptIndex),
+            lastCompaction,
+            ...branch.filter((_, index) => index >= firstKeptIndex && index !== lastIndex),
+        ],
+        repositioned: lastCompaction,
+    };
+}
+/** A repositioned compaction drops its kept range: the range now follows it. */
+function emptiedCompaction(entry) {
+    return {
+        type: "compaction",
+        id: entry.id,
+        seq: 0,
+        parentId: null,
+        timestamp: toEpochMillis(entry.timestamp),
+        summary: entry.summary,
+        retainedTail: [],
+        tokensBefore: entry.tokensBefore,
+        fromHook: false,
+    };
+}
+/**
+ * Convert a v3 branch to v4 entries with the pi-0.83 context semantics, so
+ * pi's v4 transform reproduces the v3 context exactly. This mirrors what the
+ * runtime shim did before mikan moved to native v4 files, and serves as the
+ * verification oracle for migrated output.
+ */
+function referenceContextEntries(branch) {
+    const { ordered, repositioned } = orderForReference(branch);
+    const converted = [];
+    for (const entry of ordered) {
+        const piEntry = repositioned === entry ? emptiedCompaction(repositioned) : convertEntry(entry, []);
+        if (piEntry)
+            converted.push(piEntry);
+    }
+    let previousId = null;
+    for (const [index, entry] of converted.entries()) {
+        entry.seq = index;
+        entry.parentId = previousId;
+        previousId = entry.id;
+    }
+    return converted;
+}
+function isCurrentContextMessage(message) {
+    return (message.role !== "assistant" ||
+        (message.stopReason !== "error" &&
+            message.stopReason !== "aborted" &&
+            message.stopReason !== "deferred"));
+}
+function contextMessagesOf(entry) {
+    if (entry.type === "message") {
+        return isCurrentContextMessage(entry.message) ? [entry.message] : [];
+    }
+    if (entry.type === "compaction") {
+        return [
+            createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp),
+            ...entry.retainedTail.filter(isCurrentContextMessage),
+        ];
+    }
+    if (entry.type === "branch_summary" && entry.summary) {
+        return [createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp)];
+    }
+    return [];
+}
+function referenceContextMessages(entries) {
+    const compactionIndex = entries.findLastIndex((entry) => entry.type === "compaction");
+    const visible = compactionIndex === -1 ? entries : entries.slice(compactionIndex);
+    return visible.flatMap(contextMessagesOf);
+}
+// ── v4 encoding ─────────────────────────────────────────────────────────────
+function buildV4Header(header) {
+    return {
+        v: 4,
+        kind: "header",
+        id: header.id,
+        storageVersion: 1,
+        createdAt: toEpochMillis(header.timestamp),
+        cwd: header.cwd,
+        ...(header.parentSessionId !== undefined ? { parentSessionId: header.parentSessionId } : {}),
+        ...(header.parentSession !== undefined
+            ? { legacyParentSessionPath: header.parentSession }
+            : {}),
+    };
+}
+/** Split a v3 entry stream into tree entries and the facts v4 stores as values. */
+function partitionEntries(entries) {
+    const tree = [];
+    const labels = [];
+    let name;
+    for (const entry of entries) {
+        switch (entry.type) {
+            case "session_info":
+                name = entry.name?.trim() || undefined;
+                break;
+            case "label":
+                labels.push({ targetId: entry.targetId, label: entry.label });
+                break;
+            case "leaf":
+                break;
+            default:
+                tree.push(entry);
+        }
+    }
+    return { tree, name, labels };
+}
+/** The v4 branch tip: the v3 leaf, walked back past fact-only entries. */
+function resolveV4Leaf(entries) {
+    const byId = new Map(entries.map((entry) => [entry.id, entry]));
+    let leafId = v3LeafId(entries);
+    while (leafId !== null) {
+        const target = byId.get(leafId);
+        if (!target)
+            return null;
+        if (!isFactEntry(target))
+            return leafId;
+        leafId = target.parentId;
+    }
+    return null;
+}
+/** Header fields v4 does not model survive as the durable `mikan/metadata` value. */
+function headerMetadata(header) {
+    const { type: _type, version: _version, id: _id, timestamp: _timestamp, cwd: _cwd, parentSession, parentSessionId: _parentSessionId, ...extras } = header;
+    const metadata = extras;
+    if (parentSession !== undefined)
+        metadata.parentSessionPath = parentSession;
+    return Object.keys(metadata).length > 0 ? metadata : undefined;
+}
+function encodeV4File(file) {
+    const writer = new V4FileWriter(buildV4Header(file.header));
+    const { tree, name, labels } = partitionEntries(file.entries);
+    for (const entry of tree) {
+        const converted = convertEntry(entry, file.entries);
+        if (converted)
+            writer.entry(converted);
+    }
+    writer.set("pi.branch.tip", "main", resolveV4Leaf(file.entries));
+    if (name !== undefined)
+        writer.set("pi.session.name", "", name);
+    for (const { targetId, label } of labels) {
+        if (label !== undefined)
+            writer.set("pi.entry.label", targetId, label);
+    }
+    const metadata = headerMetadata(file.header);
+    if (metadata)
+        writer.set("mikan", "metadata", metadata);
+    return writer.toString();
+}
+// ── migration driver ────────────────────────────────────────────────────────
+async function verifyMigratedFile(v4Path, source) {
+    const store = await SessionStore.inspect(v4Path);
+    const migratedContext = await store.buildSessionContext();
+    const branch = v3Branch(source.entries, v3LeafId(source.entries));
+    const migrated = JSON.stringify(migratedContext.messages);
+    const reference = JSON.stringify(referenceContextMessages(referenceContextEntries(branch)));
+    if (migrated !== reference) {
+        throw new Error("migrated context does not match the v3 reference context");
+    }
+    const migratedName = await store.getSessionName();
+    const v3Name = [...source.entries]
+        .toReversed()
+        .find((entry) => entry.type === "session_info")
+        ?.name?.trim();
+    if ((migratedName ?? "") !== (v3Name || "")) {
+        throw new Error("migrated session name does not match the v3 session name");
+    }
+}
+/**
+ * Migrate one session file in place. The migrated file is verified against
+ * the v3 reference semantics before it replaces the original; the original
+ * is preserved as `<file>.v3.bak`.
+ */
+export async function migrateSessionFile(filePath, options) {
+    if (!isV3SessionFile(filePath))
+        return { file: filePath, status: "already-v4" };
+    const sourceBytes = readFileSync(filePath);
+    const source = readV3SessionFile(filePath);
+    if (options?.dryRun)
+        return { file: filePath, status: "migrated", detail: "dry run" };
+    await commitMigration({
+        filePath,
+        sourceBytes,
+        encoded: encodeV4File(source),
+        tempPath: `${filePath}.v4.tmp`,
+        backupPath: `${filePath}.v3.bak`,
+        verify: (candidatePath) => verifyMigratedFile(candidatePath, source),
+    });
+    return { file: filePath, status: "migrated" };
+}
+/** Recursively find candidate session files (.jsonl with a v3 header). */
+export function findV3SessionFiles(root) {
+    return findSessionFiles(root, isV3SessionFile);
+}
+//# sourceMappingURL=migrate-v3.js.map

package/dist/sessions/migrate-v3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-v3.js","sourceRoot":"","sources":["../../src/sessions/migrate-v3.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * One-time migration of legacy v3 session files to pi's v4 JSONL format.\n *\n * v3 is the entry family mikan wrote up to pi 0.83: a `{\"type\":\"session\"}`\n * header followed by tree entries with string ISO timestamps and compaction\n * entries that point at `firstKeptEntryId`. Current Pi v4 uses a\n * `{\"v\":4,\"kind\":\"header\",\"storageVersion\":1}` header followed by\n * transactional writes with numeric timestamps and consecutive sequences.\n *\n * The migration preserves entry ids, parent links, and timestamps, converts\n * `custom_message` entries into v4 `custom`-role messages, folds\n * `session_info` into the v4 name fact, `label` entries into label facts,\n * and rewrites each compaction's kept range into its inline `retainedTail`.\n * Every migrated file is verified before it replaces the original: the v4\n * file is re-opened with pi's reader and its built context must equal the\n * v3 context computed by the reference converter below. The original file\n * is kept beside the migrated one as `<name>.v3.bak`.\n */\nimport { readFileSync } from \"node:fs\";\nimport {\n  createBranchSummaryMessage,\n  createCompactionSummaryMessage,\n  createCustomMessage,\n  type AgentMessage,\n  type Entry as PiEntry,\n  type JsonValue,\n} from \"@earendil-works/pi-agent-core\";\nimport { SessionStore } from \"./session-store.js\";\nimport {\n  commitMigration,\n  findSessionFiles,\n  optionalAnnotations,\n  V4FileWriter,\n} from \"./migrate-common.js\";\nimport type { MigrateResult } from \"./types.js\";\nexport type { MigrateResult } from \"./types.js\";\n\n// ── v3 shapes ────────────────────────────────────────────────────────────────\n\ninterface V3EntryBase {\n  type: string;\n  id: string;\n  parentId: string | null;\n  timestamp: string;\n}\n\ntype V3Entry = V3EntryBase &\n  (\n    | { type: \"message\"; message: AgentMessage }\n    | { type: \"thinking_level_change\"; thinkingLevel: string }\n    | { type: \"model_change\"; provider: string; modelId: string }\n    | { type: \"active_tools_change\"; activeToolNames: string[] }\n    | {\n        type: \"compaction\";\n        summary: string;\n        firstKeptEntryId?: string;\n        tokensBefore: number;\n        retainedTail?: AgentMessage[];\n        details?: unknown;\n        usage?: unknown;\n      }\n    | {\n        type: \"branch_summary\";\n        fromId: string;\n        summary: string;\n        details?: unknown;\n        usage?: unknown;\n      }\n    | { type: \"custom\"; customType: string; data?: unknown }\n    | {\n        type: \"custom_message\";\n        customType: string;\n        content: Parameters<typeof createCustomMessage>[1];\n        display: boolean;\n        details?: unknown;\n      }\n    | { type: \"label\"; targetId: string; label: string | undefined }\n    | { type: \"session_info\"; name?: string }\n    | { type: \"leaf\"; targetId: string | null }\n  );\n\ntype V3Compaction = Extract<V3Entry, { type: \"compaction\" }>;\ntype V3CustomMessage = Extract<V3Entry, { type: \"custom_message\" }>;\n\ninterface V3SessionHeader {\n  type: \"session\";\n  version?: number;\n  id: string;\n  timestamp: string;\n  cwd: string;\n  parentSession?: string;\n  parentSessionId?: string;\n  [extra: string]: unknown;\n}\n\ninterface V3SessionFile {\n  header: V3SessionHeader;\n  entries: V3Entry[];\n}\n\n/** `session_info`, `label` and `leaf` become v4 values, not tree entries. */\nfunction isFactEntry(entry: V3Entry): boolean {\n  return entry.type === \"session_info\" || entry.type === \"label\" || entry.type === \"leaf\";\n}\n\n/** Whether a file's first non-empty line is a v3 session header. */\nexport function isV3SessionFile(filePath: string): boolean {\n  try {\n    const content = readFileSync(filePath, \"utf-8\");\n    const firstLine = content.split(\"\\n\").find((line) => line.trim().length > 0);\n    if (!firstLine) return false;\n    const parsed = JSON.parse(firstLine) as { type?: unknown };\n    return parsed.type === \"session\";\n  } catch {\n    return false;\n  }\n}\n\n/** Parse every non-empty line, tolerating a torn final line (crash tail). */\nfunction parseJsonLines(filePath: string): Record<string, unknown>[] {\n  const lines = readFileSync(filePath, \"utf-8\")\n    .split(\"\\n\")\n    .map((line) => line.trim())\n    .filter((line) => line.length > 0);\n  const records: Record<string, unknown>[] = [];\n  for (const [index, line] of lines.entries()) {\n    try {\n      records.push(JSON.parse(line) as Record<string, unknown>);\n    } catch (error) {\n      if (index === lines.length - 1 && index > 0) continue;\n      throw new Error(`Invalid JSON on line ${index + 1} of ${filePath}`, { cause: error });\n    }\n  }\n  return records;\n}\n\n/**\n * Crash-era v3 files can contain duplicated lines (a retried append wrote the\n * header+entry pair twice). The v3 runtime read entries into a Map, so\n * duplicates were silently collapsed; v4 rejects duplicate mutation ids.\n * Reproduce the v3 Map semantics: a repeated id replaces its payload while\n * retaining the id's original insertion position.\n */\nfunction dedupeEntries(records: Record<string, unknown>[]): V3Entry[] {\n  const entriesById = new Map<string, V3Entry>();\n  for (const record of records) {\n    if (typeof record.type !== \"string\" || typeof record.id !== \"string\") continue;\n    if (record.type === \"session\") continue;\n    entriesById.set(record.id, record as unknown as V3Entry);\n  }\n  return [...entriesById.values()];\n}\n\n/** Read a v3 session file, ignoring a torn final line (crash tail). */\nfunction readV3SessionFile(filePath: string): V3SessionFile {\n  const records = parseJsonLines(filePath);\n  const header = records[0];\n  if (!header || header.type !== \"session\" || typeof header.id !== \"string\") {\n    throw new Error(`Not a v3 session file: ${filePath}`);\n  }\n  return {\n    header: header as unknown as V3SessionHeader,\n    entries: dedupeEntries(records.slice(1)),\n  };\n}\n\nfunction toEpochMillis(timestamp: string): number {\n  const parsed = Date.parse(timestamp);\n  return Number.isNaN(parsed) ? 0 : parsed;\n}\n\n/** Walk a v3 tree from an entry to the root; returns root-first path order. */\nfunction v3Branch(entries: V3Entry[], fromId: string | null): V3Entry[] {\n  const byId = new Map(entries.map((entry) => [entry.id, entry]));\n  const path: V3Entry[] = [];\n  let currentId = fromId;\n  while (currentId) {\n    const entry = byId.get(currentId);\n    if (!entry) break;\n    path.push(entry);\n    currentId = entry.parentId;\n  }\n  return path.toReversed();\n}\n\nfunction v3LeafId(entries: V3Entry[]): string | null {\n  let leafId: string | null = null;\n  for (const entry of entries) {\n    leafId = entry.type === \"leaf\" ? entry.targetId : entry.id;\n  }\n  return leafId;\n}\n\n/** v3 kept `custom_message` payloads out of band; v4 stores a real message. */\nfunction customMessageOf(entry: V3CustomMessage): AgentMessage {\n  return createCustomMessage(\n    entry.customType,\n    entry.content,\n    entry.display,\n    entry.details,\n    toEpochMillis(entry.timestamp),\n  );\n}\n\n/** Convert one tree-shaping v3 entry to its v4 counterpart (facts excluded). */\nfunction convertEntry(entry: V3Entry, entries: V3Entry[]): PiEntry | null {\n  const base = {\n    id: entry.id,\n    seq: 0, // assigned at mutation-encoding time\n    parentId: resolveV4Parent(entry, entries),\n    timestamp: toEpochMillis(entry.timestamp),\n  };\n  switch (entry.type) {\n    case \"message\":\n      return { ...base, type: \"message\", message: entry.message };\n    case \"custom_message\":\n      return { ...base, type: \"message\", message: customMessageOf(entry) };\n    case \"thinking_level_change\":\n    case \"model_change\":\n    case \"active_tools_change\": {\n      const { id: _id, parentId: _parentId, timestamp: _timestamp, type, ...data } = entry;\n      return {\n        ...base,\n        type: \"custom\",\n        customType: `mikan.legacy.${type}`,\n        data: data as JsonValue,\n      };\n    }\n    case \"compaction\":\n      return {\n        ...base,\n        type: \"compaction\",\n        summary: entry.summary,\n        retainedTail: entry.retainedTail ?? compactionKeptMessages(entry, entries),\n        tokensBefore: entry.tokensBefore,\n        fromHook: false,\n        ...optionalAnnotations(entry),\n      } as unknown as PiEntry;\n    case \"branch_summary\":\n      return {\n        ...base,\n        type: \"branch_summary\",\n        fromId: entry.fromId ?? null,\n        summary: entry.summary,\n        fromHook: false,\n        ...optionalAnnotations(entry),\n      } as unknown as PiEntry;\n    case \"custom\":\n      return {\n        ...base,\n        type: \"custom\",\n        customType: entry.customType,\n        ...(entry.data !== undefined ? { data: entry.data as JsonValue } : {}),\n      };\n    default:\n      // session_info / label / leaf become facts and the lane pointer.\n      return null;\n  }\n}\n\n/**\n * Skip fact-only ancestors (session_info/label/leaf) when re-linking the v4\n * tree: those entries disappear from the entry stream, so children re-attach\n * to the nearest surviving ancestor.\n */\nfunction resolveV4Parent(entry: V3Entry, entries: V3Entry[]): string | null {\n  const byId = new Map(entries.map((item) => [item.id, item]));\n  let parentId = entry.parentId;\n  while (parentId !== null) {\n    const parent = byId.get(parentId);\n    if (!parent) return null;\n    if (!isFactEntry(parent)) return parentId;\n    parentId = parent.parentId;\n  }\n  return null;\n}\n\n/**\n * Messages of the v3 kept range (`firstKeptEntryId` .. compaction parent),\n * which v4 stores inline on the compaction entry.\n */\nfunction compactionKeptMessages(compaction: V3Compaction, entries: V3Entry[]): AgentMessage[] {\n  if (!compaction.firstKeptEntryId) return [];\n  const ancestors = v3Branch(entries, compaction.parentId);\n  const keptStart = ancestors.findIndex((entry) => entry.id === compaction.firstKeptEntryId);\n  if (keptStart === -1) return [];\n  const messages: AgentMessage[] = [];\n  for (const entry of ancestors.slice(keptStart)) {\n    if (entry.type === \"message\") messages.push(entry.message);\n    else if (entry.type === \"custom_message\") messages.push(customMessageOf(entry));\n  }\n  return messages;\n}\n\n// ── reference converter (verification oracle) ───────────────────────────────\n\n/**\n * Reorder a v3 branch the way the pi-0.83 context shim did: the last\n * compaction moves ahead of its kept range. The branch is returned unchanged\n * when there is no such compaction or it already carries a `retainedTail`.\n */\nfunction orderForReference(branch: V3Entry[]): {\n  ordered: V3Entry[];\n  repositioned?: V3Compaction;\n} {\n  const lastIndex = branch.findLastIndex((entry) => entry.type === \"compaction\");\n  const lastCompaction = branch[lastIndex] as V3Compaction | undefined;\n  const firstKeptId = lastCompaction?.retainedTail ? undefined : lastCompaction?.firstKeptEntryId;\n  const firstKeptIndex =\n    firstKeptId === undefined ? -1 : branch.findIndex((entry) => entry.id === firstKeptId);\n  if (firstKeptIndex === -1 || !lastCompaction) return { ordered: branch };\n  return {\n    ordered: [\n      ...branch.slice(0, firstKeptIndex),\n      lastCompaction,\n      ...branch.filter((_, index) => index >= firstKeptIndex && index !== lastIndex),\n    ],\n    repositioned: lastCompaction,\n  };\n}\n\n/** A repositioned compaction drops its kept range: the range now follows it. */\nfunction emptiedCompaction(entry: V3Compaction): PiEntry {\n  return {\n    type: \"compaction\",\n    id: entry.id,\n    seq: 0,\n    parentId: null,\n    timestamp: toEpochMillis(entry.timestamp),\n    summary: entry.summary,\n    retainedTail: [],\n    tokensBefore: entry.tokensBefore,\n    fromHook: false,\n  };\n}\n\n/**\n * Convert a v3 branch to v4 entries with the pi-0.83 context semantics, so\n * pi's v4 transform reproduces the v3 context exactly. This mirrors what the\n * runtime shim did before mikan moved to native v4 files, and serves as the\n * verification oracle for migrated output.\n */\nfunction referenceContextEntries(branch: V3Entry[]): PiEntry[] {\n  const { ordered, repositioned } = orderForReference(branch);\n  const converted: PiEntry[] = [];\n  for (const entry of ordered) {\n    const piEntry =\n      repositioned === entry ? emptiedCompaction(repositioned) : convertEntry(entry, []);\n    if (piEntry) converted.push(piEntry);\n  }\n  let previousId: string | null = null;\n  for (const [index, entry] of converted.entries()) {\n    entry.seq = index;\n    entry.parentId = previousId;\n    previousId = entry.id;\n  }\n  return converted;\n}\n\nfunction isCurrentContextMessage(message: AgentMessage): boolean {\n  return (\n    message.role !== \"assistant\" ||\n    (message.stopReason !== \"error\" &&\n      message.stopReason !== \"aborted\" &&\n      message.stopReason !== \"deferred\")\n  );\n}\n\nfunction contextMessagesOf(entry: PiEntry): AgentMessage[] {\n  if (entry.type === \"message\") {\n    return isCurrentContextMessage(entry.message) ? [entry.message] : [];\n  }\n  if (entry.type === \"compaction\") {\n    return [\n      createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp),\n      ...entry.retainedTail.filter(isCurrentContextMessage),\n    ];\n  }\n  if (entry.type === \"branch_summary\" && entry.summary) {\n    return [createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp)];\n  }\n  return [];\n}\n\nfunction referenceContextMessages(entries: PiEntry[]): AgentMessage[] {\n  const compactionIndex = entries.findLastIndex((entry) => entry.type === \"compaction\");\n  const visible = compactionIndex === -1 ? entries : entries.slice(compactionIndex);\n  return visible.flatMap(contextMessagesOf);\n}\n\n// ── v4 encoding ─────────────────────────────────────────────────────────────\n\nfunction buildV4Header(header: V3SessionHeader): Record<string, unknown> {\n  return {\n    v: 4,\n    kind: \"header\",\n    id: header.id,\n    storageVersion: 1,\n    createdAt: toEpochMillis(header.timestamp),\n    cwd: header.cwd,\n    ...(header.parentSessionId !== undefined ? { parentSessionId: header.parentSessionId } : {}),\n    ...(header.parentSession !== undefined\n      ? { legacyParentSessionPath: header.parentSession }\n      : {}),\n  };\n}\n\n/** Split a v3 entry stream into tree entries and the facts v4 stores as values. */\nfunction partitionEntries(entries: V3Entry[]): {\n  tree: V3Entry[];\n  name?: string;\n  labels: Array<{ targetId: string; label: string | undefined }>;\n} {\n  const tree: V3Entry[] = [];\n  const labels: Array<{ targetId: string; label: string | undefined }> = [];\n  let name: string | undefined;\n  for (const entry of entries) {\n    switch (entry.type) {\n      case \"session_info\":\n        name = entry.name?.trim() || undefined;\n        break;\n      case \"label\":\n        labels.push({ targetId: entry.targetId, label: entry.label });\n        break;\n      case \"leaf\":\n        break;\n      default:\n        tree.push(entry);\n    }\n  }\n  return { tree, name, labels };\n}\n\n/** The v4 branch tip: the v3 leaf, walked back past fact-only entries. */\nfunction resolveV4Leaf(entries: V3Entry[]): string | null {\n  const byId = new Map(entries.map((entry) => [entry.id, entry]));\n  let leafId = v3LeafId(entries);\n  while (leafId !== null) {\n    const target = byId.get(leafId);\n    if (!target) return null;\n    if (!isFactEntry(target)) return leafId;\n    leafId = target.parentId;\n  }\n  return null;\n}\n\n/** Header fields v4 does not model survive as the durable `mikan/metadata` value. */\nfunction headerMetadata(header: V3SessionHeader): Record<string, JsonValue> | undefined {\n  const {\n    type: _type,\n    version: _version,\n    id: _id,\n    timestamp: _timestamp,\n    cwd: _cwd,\n    parentSession,\n    parentSessionId: _parentSessionId,\n    ...extras\n  } = header;\n  const metadata: Record<string, JsonValue> = extras as Record<string, JsonValue>;\n  if (parentSession !== undefined) metadata.parentSessionPath = parentSession;\n  return Object.keys(metadata).length > 0 ? metadata : undefined;\n}\n\nfunction encodeV4File(file: V3SessionFile): string {\n  const writer = new V4FileWriter(buildV4Header(file.header));\n  const { tree, name, labels } = partitionEntries(file.entries);\n  for (const entry of tree) {\n    const converted = convertEntry(entry, file.entries);\n    if (converted) writer.entry(converted);\n  }\n  writer.set(\"pi.branch.tip\", \"main\", resolveV4Leaf(file.entries));\n  if (name !== undefined) writer.set(\"pi.session.name\", \"\", name);\n  for (const { targetId, label } of labels) {\n    if (label !== undefined) writer.set(\"pi.entry.label\", targetId, label);\n  }\n  const metadata = headerMetadata(file.header);\n  if (metadata) writer.set(\"mikan\", \"metadata\", metadata);\n  return writer.toString();\n}\n\n// ── migration driver ────────────────────────────────────────────────────────\n\nasync function verifyMigratedFile(v4Path: string, source: V3SessionFile): Promise<void> {\n  const store = await SessionStore.inspect(v4Path);\n  const migratedContext = await store.buildSessionContext();\n  const branch = v3Branch(source.entries, v3LeafId(source.entries));\n  const migrated = JSON.stringify(migratedContext.messages);\n  const reference = JSON.stringify(referenceContextMessages(referenceContextEntries(branch)));\n  if (migrated !== reference) {\n    throw new Error(\"migrated context does not match the v3 reference context\");\n  }\n  const migratedName = await store.getSessionName();\n  const v3Name = [...source.entries]\n    .toReversed()\n    .find((entry) => entry.type === \"session_info\")\n    ?.name?.trim();\n  if ((migratedName ?? \"\") !== (v3Name || \"\")) {\n    throw new Error(\"migrated session name does not match the v3 session name\");\n  }\n}\n\n/**\n * Migrate one session file in place. The migrated file is verified against\n * the v3 reference semantics before it replaces the original; the original\n * is preserved as `<file>.v3.bak`.\n */\nexport async function migrateSessionFile(\n  filePath: string,\n  options?: { dryRun?: boolean },\n): Promise<MigrateResult> {\n  if (!isV3SessionFile(filePath)) return { file: filePath, status: \"already-v4\" };\n  const sourceBytes = readFileSync(filePath);\n  const source = readV3SessionFile(filePath);\n  if (options?.dryRun) return { file: filePath, status: \"migrated\", detail: \"dry run\" };\n\n  await commitMigration({\n    filePath,\n    sourceBytes,\n    encoded: encodeV4File(source),\n    tempPath: `${filePath}.v4.tmp`,\n    backupPath: `${filePath}.v3.bak`,\n    verify: (candidatePath) => verifyMigratedFile(candidatePath, source),\n  });\n  return { file: filePath, status: \"migrated\" };\n}\n\n/** Recursively find candidate session files (.jsonl with a v3 header). */\nexport function findV3SessionFiles(root: string): string[] {\n  return findSessionFiles(root, isV3SessionFile);\n}\n"]}

package/dist/sessions/session-key.d.ts

@@ -0,0 +1,33 @@
+import type { ConversationKind } from "../types.js";
+export type { ResolveSessionKeyOptions } from "./types.js";
+import type { ResolveSessionKeyOptions } from "./types.js";
+export declare function assertConversationId(conversationId: string): string;
+/** Validate the opaque scoped suffix without changing its platform value. */
+export declare function assertSessionSuffix(suffix: string): string;
+/** Build a scoped thread session key. */
+export declare function makeThreadSessionKey(conversationId: string, suffix: string): string;
+/**
+ * Validate that a platform-computed session key belongs to its conversation.
+ * The key may be the bare conversation id or one of that conversation's
+ * scoped keys; callers must not be able to select another conversation's
+ * runtime/cache entry.
+ */
+export declare function assertSessionKeyBelongsToConversation(sessionKey: string, conversationId: string): string;
+/**
+ * The runtime fallback: honor a platform-computed session key, otherwise
+ * scope the event to its thread (or to itself for thread-starting messages).
+ */
+export declare function deriveSessionKey(event: {
+    sessionKey?: string;
+    conversationId: string;
+    thread_ts?: string;
+    ts: string;
+}): string;
+export declare function isThreadSessionKey(sessionKey: string): boolean;
+/** The conversation a session key belongs to (identity for bare keys). */
+export declare function conversationIdOf(sessionKey: string): string;
+/** The thread suffix of a scoped key, or null for a bare conversation key. */
+export declare function threadSuffixOf(sessionKey: string): string | null;
+export declare function resolveChatSessionKey(options: ResolveSessionKeyOptions): string;
+export declare function inferConversationKind(platform: string, conversationId: string): ConversationKind;
+//# sourceMappingURL=session-key.d.ts.map

package/dist/sessions/session-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-key.d.ts","sourceRoot":"","sources":["../../src/sessions/session-key.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,YAAY,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAuC3D,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CASnE;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,yCAAyC;AACzC,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnF;AAED;;;;;GAKG;AACH,wBAAgB,qCAAqC,CACnD,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GACrB,MAAM,CAYR;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;CACZ,GAAG,MAAM,CAKT;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAG3D;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhE;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CAgB/E;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,gBAAgB,CAehG"}

package/dist/sessions/session-key.js

@@ -0,0 +1,115 @@
+/**
+ * The session-key grammar. A session key is the conversation-scoped runtime
+ * identity used to serialize and resume work (see CONTEXT.md):
+ *
+ *   `conversationId`            — the persistent conversation session
+ *   `conversationId:suffix`     — a scoped thread session (suffix = thread
+ *                                 ts / message id, opaque to this module)
+ *
+ * This module owns the convention; nothing else may split on ":". The grammar
+ * only works because conversation ids never contain ":" — that invariant is
+ * asserted here at every derivation instead of being assumed everywhere.
+ */
+/** Characters that can change host path structure or make identity logs ambiguous. */
+const PATH_SEPARATOR_PATTERN = /[\\/]/;
+function containsControlCharacter(value) {
+    for (const character of value) {
+        const codePoint = character.codePointAt(0);
+        if (codePoint <= 0x1f || codePoint === 0x7f)
+            return true;
+    }
+    return false;
+}
+function assertSafeIdentityPart(value, label) {
+    if (!value || value === "." || value === "..") {
+        throw new Error(`${label} must be a non-empty identity segment (got ${JSON.stringify(value)})`);
+    }
+    if (PATH_SEPARATOR_PATTERN.test(value)) {
+        throw new Error(`${label} must not contain path separators (got ${JSON.stringify(value)})`);
+    }
+    if (containsControlCharacter(value)) {
+        throw new Error(`${label} must not contain control characters (got ${JSON.stringify(value)})`);
+    }
+    return value;
+}
+export function assertConversationId(conversationId) {
+    assertSafeIdentityPart(conversationId, "Conversation id");
+    if (conversationId.includes(":")) {
+        throw new Error(`Conversation id must not contain ":" (got ${JSON.stringify(conversationId)}); ` +
+            "the session-key grammar reserves it for thread suffixes");
+    }
+    return conversationId;
+}
+/** Validate the opaque scoped suffix without changing its platform value. */
+export function assertSessionSuffix(suffix) {
+    return assertSafeIdentityPart(suffix, "Session suffix");
+}
+/** Build a scoped thread session key. */
+export function makeThreadSessionKey(conversationId, suffix) {
+    return `${assertConversationId(conversationId)}:${assertSessionSuffix(suffix)}`;
+}
+/**
+ * Validate that a platform-computed session key belongs to its conversation.
+ * The key may be the bare conversation id or one of that conversation's
+ * scoped keys; callers must not be able to select another conversation's
+ * runtime/cache entry.
+ */
+export function assertSessionKeyBelongsToConversation(sessionKey, conversationId) {
+    const expectedConversationId = assertConversationId(conversationId);
+    const actualConversationId = conversationIdOf(sessionKey);
+    if (actualConversationId !== expectedConversationId) {
+        throw new Error(`Session key ${JSON.stringify(sessionKey)} does not belong to conversation ` +
+            JSON.stringify(conversationId));
+    }
+    const suffix = threadSuffixOf(sessionKey);
+    if (suffix !== null)
+        assertSessionSuffix(suffix);
+    return sessionKey;
+}
+/**
+ * The runtime fallback: honor a platform-computed session key, otherwise
+ * scope the event to its thread (or to itself for thread-starting messages).
+ */
+export function deriveSessionKey(event) {
+    if (event.sessionKey !== undefined) {
+        return assertSessionKeyBelongsToConversation(event.sessionKey, event.conversationId);
+    }
+    return makeThreadSessionKey(event.conversationId, event.thread_ts ?? event.ts);
+}
+export function isThreadSessionKey(sessionKey) {
+    return sessionKey.includes(":");
+}
+/** The conversation a session key belongs to (identity for bare keys). */
+export function conversationIdOf(sessionKey) {
+    const separator = sessionKey.indexOf(":");
+    return separator === -1 ? sessionKey : sessionKey.slice(0, separator);
+}
+/** The thread suffix of a scoped key, or null for a bare conversation key. */
+export function threadSuffixOf(sessionKey) {
+    const separator = sessionKey.indexOf(":");
+    return separator === -1 ? null : sessionKey.slice(separator + 1);
+}
+export function resolveChatSessionKey(options) {
+    const { conversationId, conversationKind, messageId, persistentTopLevel, scopeDirectThreads, threadTs, } = options;
+    if (conversationKind === "direct" && (!threadTs || !scopeDirectThreads)) {
+        return assertConversationId(conversationId);
+    }
+    if (!threadTs && persistentTopLevel) {
+        return assertConversationId(conversationId);
+    }
+    return makeThreadSessionKey(conversationId, threadTs || messageId);
+}
+export function inferConversationKind(platform, conversationId) {
+    if (platform === "slack") {
+        return conversationId.startsWith("D") ? "direct" : "shared";
+    }
+    if (platform === "telegram") {
+        return conversationId.startsWith("-") ? "shared" : "direct";
+    }
+    if (platform === "discord") {
+        return conversationId.startsWith("DM") ? "direct" : "shared";
+    }
+    // github: issues/PRs are always shared within the repo; there are no DMs.
+    return "shared";
+}
+//# sourceMappingURL=session-key.js.map