@herbertgao/pi-extensions 2026.8.8 → 2026.8.10

package/node_modules/resume-from/dist/platform/store/file-committer.js

@@ -0,0 +1,391 @@
+// The only place in the system that creates files. It adds files to a target home, never touches a
+// file that already exists (FR-49), and atomically publishes at most one file (FR-53).
+//
+// Strategy: stage the file under a temporary name in its destination directory, then place it with
+// `link`, which fails rather than overwrites. Staging first is what makes an interrupted
+// commit leave no destination file at all; `link` instead of `rename` is what makes the check-then-
+// place race fail the commit instead of destroying a file that appeared (C-3).
+//
+// This file has no runtime import of its own siblings on purpose: the interrupt test loads it in a
+// bare Node child process.
+import { randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { access, link, lstat, mkdir, open, realpath, stat, unlink } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+/** Leading dot and no session-like suffix: a leftover is a name no agent will read (T-STO-17). */
+const TEMPORARY_PREFIX = ".resume-from-";
+const TEMPORARY_SUFFIX = ".tmp";
+class CommitFailure extends Error {
+    refusal;
+    path;
+    remainingPaths;
+    constructor(refusal, path, message, remainingPaths) {
+        super(message);
+        this.name = "CommitError";
+        this.refusal = refusal;
+        this.path = path;
+        if (remainingPaths !== undefined)
+            this.remainingPaths = remainingPaths;
+    }
+}
+/** Creates the guarded store. It holds no state between commits. */
+export function createFileCommitter() {
+    return { commit };
+}
+async function commit(root, files) {
+    checkCardinality(files);
+    checkPaths(root, files);
+    const createdDirs = [];
+    const createdFiles = [];
+    const staged = [];
+    if (files.length === 0) {
+        return { createdPaths: [] };
+    }
+    let resolvedRoot;
+    try {
+        await createTargetRoot(root, createdDirs);
+        await verifyOwnedDirectories(createdDirs);
+        resolvedRoot = await checkDestinations(root, files);
+        await verifyOwnedDirectories(createdDirs);
+    }
+    catch (error) {
+        const remainingPaths = [
+            ...remainingFrom(error),
+            ...createdPathNames(createdFiles, createdDirs),
+        ];
+        throw asCommitFailure(error, remainingPaths);
+    }
+    try {
+        for (const file of files) {
+            await createParents(dirname(file.absolutePath), resolvedRoot, createdDirs);
+            await checkResolvedInside(resolvedRoot, dirname(file.absolutePath));
+            staged.push(await stage(file, resolvedRoot));
+        }
+        for (const item of staged) {
+            await place(item);
+            createdFiles.push({ path: item.destination, ...item.identity });
+        }
+    }
+    catch (error) {
+        const temporaryPaths = await discard(staged);
+        const remainingPaths = [
+            ...remainingFrom(error),
+            ...temporaryPaths,
+            ...createdPathNames(createdFiles, createdDirs),
+        ];
+        throw asCommitFailure(error, remainingPaths);
+    }
+    const remainingTemporaryPaths = await discard(staged);
+    if (remainingTemporaryPaths.length > 0) {
+        // Placement succeeded: the published destination is real. Only the temporary staging file(s)
+        // could not be removed. Pass them separately so the message is honest about what happened.
+        const publishedPaths = createdPathNames(createdFiles, createdDirs);
+        throw cleanupFailure(remainingTemporaryPaths, publishedPaths);
+    }
+    return { createdPaths: createdFiles.map(({ path }) => path) };
+}
+function checkCardinality(files) {
+    if (files.length <= 1)
+        return;
+    throw new CommitFailure("write-failed", null, `Refused to create ${files.length} files in one commit. A session must serialize to one file so placement is atomic across process interruption.`);
+}
+/** Creates a missing target root as part of this commit and records it for failure reporting. */
+async function createTargetRoot(root, createdDirs) {
+    const missing = [];
+    let current = root;
+    while (!(await exists(current))) {
+        missing.push(current);
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    for (const missingDir of missing.reverse()) {
+        try {
+            await mkdir(missingDir, { mode: 0o700 });
+            const info = await lstat(missingDir);
+            createdDirs.push({ path: missingDir, dev: info.dev, ino: info.ino });
+        }
+        catch (error) {
+            if (codeOf(error) === "EEXIST")
+                continue;
+            throw new CommitFailure("write-failed", missingDir, writeFailed(missingDir, error));
+        }
+    }
+}
+async function verifyOwnedDirectories(directories) {
+    for (const owned of directories) {
+        const info = await lstat(owned.path).catch(() => null);
+        if (info === null || !info.isDirectory() || !sameIdentity(owned, info)) {
+            throw new CommitFailure("write-failed", owned.path, `Refused to use target root "${owned.path}": it changed while it was being created.`);
+        }
+    }
+}
+/** Refuses what no filesystem call could tell us: a relative path, or the same path listed twice. */
+function checkPaths(root, files) {
+    if (!isAbsolute(root)) {
+        throw new CommitFailure("write-failed", root, `Refused to use target root "${root}": the root is not absolute.`);
+    }
+    const normalizedRoot = resolve(root);
+    const seen = new Set();
+    for (const file of files) {
+        const path = file.absolutePath;
+        if (!isAbsolute(path)) {
+            throw new CommitFailure("write-failed", path, `Refused to write "${path}": the path is not absolute. Pass an absolute path — a relative path is never resolved against the current directory.`);
+        }
+        const key = resolve(path);
+        if (!isInside(normalizedRoot, key)) {
+            throw new CommitFailure("write-failed", path, `Refused to write "${path}": it is outside the target root "${root}".`);
+        }
+        if (seen.has(key)) {
+            throw new CommitFailure("write-failed", path, `Refused to write "${path}": the same path is listed twice in one commit. Remove the duplicate — this store never overwrites a file, not even one it just created.`);
+        }
+        seen.add(key);
+    }
+}
+/** Runs before the first byte is written: nothing may exist, and every destination must be reachable. */
+async function checkDestinations(root, files) {
+    let resolvedRoot;
+    try {
+        const rootInfo = await stat(root);
+        if (!rootInfo.isDirectory()) {
+            throw new CommitFailure("not-writable", root, `Refused to use target root "${root}": it is not a directory.`);
+        }
+        resolvedRoot = await realpath(root);
+    }
+    catch (error) {
+        if (error instanceof CommitFailure)
+            throw error;
+        throw new CommitFailure("not-writable", root, notWritable(root));
+    }
+    for (const file of files) {
+        if (await exists(file.absolutePath)) {
+            throw new CommitFailure("path-exists", file.absolutePath, alreadyExists(file.absolutePath));
+        }
+    }
+    const checked = new Set();
+    for (const file of files) {
+        const parent = dirname(file.absolutePath);
+        if (checked.has(parent))
+            continue;
+        checked.add(parent);
+        const anchor = await nearestExisting(parent);
+        // No ancestor at all, or an ancestor that is not a directory: only the write can say what is
+        // wrong there, and it reports it as a failed write.
+        if (anchor === null || !anchor.isDirectory)
+            continue;
+        await checkResolvedInside(resolvedRoot, anchor.path);
+        try {
+            await access(anchor.path, constants.W_OK | constants.X_OK);
+        }
+        catch {
+            throw new CommitFailure("not-writable", anchor.path, notWritable(anchor.path));
+        }
+    }
+    return resolvedRoot;
+}
+/** Opens an empty temporary file, proves where its inode lives, then writes through the stable FD. */
+async function stage(file, resolvedRoot) {
+    const destination = file.absolutePath;
+    const temporary = join(dirname(destination), `${TEMPORARY_PREFIX}${randomBytes(8).toString("hex")}${TEMPORARY_SUFFIX}`);
+    let identity = null;
+    try {
+        const handle = await open(temporary, "wx", 0o600);
+        try {
+            const info = await handle.stat();
+            identity = { dev: info.dev, ino: info.ino };
+            await verifyFileInside(resolvedRoot, temporary, identity);
+            await handle.writeFile(file.bytes);
+            return {
+                temporary,
+                destination,
+                identity,
+            };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (identity !== null && !(await removeOwnedFile({ path: temporary, ...identity }))) {
+            throw new CommitFailure("write-failed", destination, `${writeFailed(destination, error)} Cleanup was incomplete. This path may still exist; inspect it before retrying: ${temporary}.`, [temporary]);
+        }
+        throw new CommitFailure("write-failed", destination, writeFailed(destination, error));
+    }
+}
+async function verifyFileInside(resolvedRoot, path, identity) {
+    const resolvedPath = await realpath(path).catch((error) => {
+        throw new CommitFailure("write-failed", path, writeFailed(path, error));
+    });
+    const current = await lstat(path).catch(() => null);
+    if (current === null || !current.isFile() || !sameIdentity(identity, current)) {
+        throw new CommitFailure("write-failed", path, `Refused to stage through "${path}": it changed after the file was opened.`);
+    }
+    if (!isInside(resolvedRoot, resolvedPath)) {
+        throw new CommitFailure("write-failed", path, `Refused to stage through "${path}": it resolves outside the target root.`);
+    }
+}
+/** Publishes a staged file at its destination. Never overwrites: `link` fails if the path exists. */
+async function place({ temporary, destination }) {
+    try {
+        await link(temporary, destination);
+    }
+    catch (error) {
+        if (codeOf(error) === "EEXIST") {
+            throw new CommitFailure("path-exists", destination, alreadyExists(destination));
+        }
+        throw new CommitFailure("write-failed", destination, writeFailed(destination, error));
+    }
+}
+/** Creates the missing directories of a chain, recording only the ones this commit created. */
+async function createParents(directory, resolvedRoot, createdDirs) {
+    const missing = [];
+    let current = directory;
+    while (!(await exists(current))) {
+        missing.push(current);
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    for (const missingDir of missing.reverse()) {
+        try {
+            await mkdir(missingDir, { mode: 0o700 });
+            await checkResolvedInside(resolvedRoot, missingDir);
+            const info = await lstat(missingDir);
+            createdDirs.push({ path: missingDir, dev: info.dev, ino: info.ino });
+        }
+        catch (error) {
+            if (codeOf(error) === "EEXIST")
+                continue; // someone else created it; not ours to remove
+            throw new CommitFailure("write-failed", missingDir, writeFailed(missingDir, error));
+        }
+    }
+}
+/** Removes leftover staged files and returns the exact paths that could not be removed. */
+async function discard(staged) {
+    const remaining = [];
+    for (const item of staged) {
+        const owned = { path: item.temporary, ...item.identity };
+        if (!(await removeOwnedFile(owned)))
+            remaining.push(item.temporary);
+    }
+    return remaining;
+}
+/** Lists paths created by the commit, with directories ordered deepest first. */
+function createdPathNames(files, directories) {
+    return [...files.map(({ path }) => path), ...[...directories].reverse().map(({ path }) => path)];
+}
+async function removeOwnedFile(owned) {
+    const current = await identityAt(owned.path);
+    if (current === null)
+        return true;
+    if (!sameIdentity(owned, current))
+        return false;
+    try {
+        await unlink(owned.path);
+        return true;
+    }
+    catch (error) {
+        return isAbsent(error);
+    }
+}
+async function identityAt(path) {
+    try {
+        const info = await lstat(path);
+        return { dev: info.dev, ino: info.ino };
+    }
+    catch (error) {
+        if (isAbsent(error))
+            return null;
+        return { dev: Number.NaN, ino: Number.NaN };
+    }
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+async function checkResolvedInside(resolvedRoot, path) {
+    const resolvedPath = await realpath(path).catch((error) => {
+        throw new CommitFailure("not-writable", path, writeFailed(path, error));
+    });
+    if (!isInside(resolvedRoot, resolvedPath)) {
+        throw new CommitFailure("write-failed", path, `Refused to write through "${path}": it resolves outside the target root.`);
+    }
+}
+function isInside(root, path) {
+    const fromRoot = relative(root, path);
+    return (fromRoot === "" ||
+        (!isAbsolute(fromRoot) && !fromRoot.startsWith(`..${sep}`) && fromRoot !== ".."));
+}
+/** True when the path is taken, symlinks included — a dangling symlink is still a taken path. */
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        const code = codeOf(error);
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return false;
+        throw new CommitFailure("not-writable", path, notWritable(dirname(path)));
+    }
+}
+/** The closest ancestor of `directory` that exists, or null at the root. */
+async function nearestExisting(directory) {
+    let current = directory;
+    for (;;) {
+        const info = await stat(current).catch(() => null);
+        if (info !== null)
+            return { path: current, isDirectory: info.isDirectory() };
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function asCommitFailure(error, remainingPaths) {
+    if (remainingPaths.length > 0) {
+        const original = error instanceof Error ? `${error.message} ` : "";
+        return new CommitFailure("write-failed", null, `${original}Cleanup was incomplete. These paths were retained or may still exist; inspect them before retrying: ${remainingPaths.join(", ")}.`, remainingPaths);
+    }
+    if (error instanceof CommitFailure)
+        return error;
+    return new CommitFailure("write-failed", null, `Failed to write the requested file: ${reasonOf(error)}. No destination was published. Check the target and the free space, then run the command again.`);
+}
+function remainingFrom(error) {
+    if (typeof error !== "object" ||
+        error === null ||
+        !("remainingPaths" in error) ||
+        !Array.isArray(error.remainingPaths)) {
+        return [];
+    }
+    return error.remainingPaths.filter((path) => typeof path === "string");
+}
+// FR-53: after successful placement the temporary staging file(s) failed to remove. The published
+// destination is already on disk — only the temps need manual removal. `remainingPaths` carries
+// only the temps so callers do not list a successfully committed file as a leftover.
+function cleanupFailure(temporaryPaths, publishedPaths) {
+    return new CommitFailure("write-failed", null, `The file was placed successfully, but the temporary staging file could not be removed. Only these paths need inspection or manual removal: ${temporaryPaths.join(", ")}. The destination was published successfully: ${publishedPaths.join(", ")}. A retry will report path-exists because the import already landed.`, temporaryPaths);
+}
+function alreadyExists(path) {
+    return `Refused to write "${path}": that path already exists. This tool only adds files. Remove or rename the existing file, or choose a different target, then run the command again.`;
+}
+function notWritable(directory) {
+    return `Refused to write into "${directory}": the directory is not writable. Check its permissions, or choose a different target, then run the command again.`;
+}
+function writeFailed(path, cause) {
+    return `Failed to write "${path}": ${reasonOf(cause)}. Check the path and the free space, then run the command again.`;
+}
+function codeOf(error) {
+    if (typeof error === "object" && error !== null && "code" in error) {
+        return String(error.code);
+    }
+    return "";
+}
+function isAbsent(error) {
+    const code = codeOf(error);
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+function reasonOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/node_modules/resume-from/dist/platform/store/index.d.ts

@@ -0,0 +1,2 @@
+export type { Bytes, CommitError, CommitHandle, CommitRefusal, FileCommitter, PendingFile, } from "./contract.js";
+export { createFileCommitter } from "./file-committer.js";

package/node_modules/resume-from/dist/platform/store/index.js

@@ -0,0 +1,2 @@
+// Guarded file store — the only module that creates files at runtime.
+export { createFileCommitter } from "./file-committer.js";

package/node_modules/resume-from/dist/platform/tokens/contract.d.ts

@@ -0,0 +1,12 @@
+/** Which counting rule to use. One value per model family the targets use. */
+export type EstimatorFamily = "claude" | "gpt" | "generic";
+/** Estimates how many tokens a piece of text costs. */
+export interface TokenEstimator {
+    /** Deterministic: the same text always returns the same count. Never negative. */
+    estimate(text: string): number;
+}
+/** Chooses an estimator. */
+export interface EstimatorFactory {
+    /** Returns the estimator for a family. Falls back to "generic" for an unknown family. */
+    forFamily(family: EstimatorFamily): TokenEstimator;
+}

package/node_modules/resume-from/dist/platform/tokens/contract.js

@@ -0,0 +1,4 @@
+// GENERATED from src/platform/tokens/module.md — the Public Contract section is the normative home.
+// Declarations only: no behaviour, no defaults. If this file and module.md disagree,
+// the document wins and this file is corrected.
+export {};

package/node_modules/resume-from/dist/platform/tokens/estimator.d.ts

@@ -0,0 +1,12 @@
+import type { EstimatorFactory } from "./contract.js";
+/**
+ * Counts the tokens of one piece of text. The whole of what this module knows about a
+ * tokenizer library: replacing the library is replacing this function.
+ */
+export type EncodeCount = (text: string) => number;
+/**
+ * Builds a factory over a given encoder. The parameter is the seam the tests use to stand a
+ * failing encoder up; every caller outside this module wants `estimatorFactory`.
+ */
+export declare const createEstimatorFactory: (count?: EncodeCount) => EstimatorFactory;
+export declare const estimatorFactory: EstimatorFactory;

package/node_modules/resume-from/dist/platform/tokens/estimator.js

@@ -0,0 +1,111 @@
+import { encode } from "gpt-tokenizer/encoding/o200k_base";
+/** How much text a segment holds before the next word start closes it. */
+const SEGMENT_CHARS = 64;
+/** Where a segment is cut when no word start follows — a run of text with no space in it. */
+const SEGMENT_LIMIT_CHARS = 128;
+/**
+ * The exact counter calls the encoder once per character, so it is bounded by an offset:
+ * text past this point is charged with the byte upper bound (`utf8UpperBound`) instead.
+ * 256 kB is already far past every target's context window, and the switch is by position
+ * rather than by content, which is what keeps the estimate monotone.
+ *
+ * Measured cost of the exact path: ≈ 760 ms at this ceiling (≈ 0.003 ms/char, ≈ 42× a
+ * single encode() call on the same text). Text beyond this offset is free by comparison:
+ * utf8UpperBound adds < 1 ms/MB. Revisit if a target's context window grows past 256 kB
+ * and exact counting at full length becomes necessary.
+ */
+const EXACT_BUDGET_CHARS = 262_144;
+/** UTF-8 bytes per token. The rule of thumb the heuristic families are built on. */
+const BYTES_PER_TOKEN = 4;
+/** A byte-level tokenizer cannot emit more tokens than the UTF-8 bytes it consumes. */
+const utf8UpperBound = (text) => Buffer.byteLength(text, "utf8");
+const isWhitespace = (code) => code === 32 || (code >= 9 && code <= 13);
+/** Characters outside the BMP — emoji, mostly — cost far more tokens per byte than text does. */
+const astralCount = (text) => {
+    let count = 0;
+    for (let index = 0; index < text.length; index++) {
+        const unit = text.charCodeAt(index);
+        if (unit >= 0xd800 && unit <= 0xdbff)
+            count++;
+    }
+    return count;
+};
+/**
+ * The counting rule for every family without an exact encoder, and the fallback for the one
+ * that has one. Monotone by construction: both terms only grow as text is appended.
+ */
+const heuristicCount = (text) => Math.ceil(Buffer.byteLength(text, "utf8") / BYTES_PER_TOKEN) + astralCount(text);
+/**
+ * Where the segment starting at `start` ends: the first word start past `SEGMENT_CHARS`, or
+ * the hard limit if the text runs on without one.
+ *
+ * The scan only ever moves forward, so a boundary is decided by the text before it and
+ * nothing appended later can move it. Earlier segments are therefore frozen, which is half
+ * of why the estimate cannot fall.
+ */
+const segmentEnd = (text, start) => {
+    const end = Math.min(start + SEGMENT_LIMIT_CHARS, text.length);
+    for (let index = start + SEGMENT_CHARS; index < end; index++) {
+        const startsWord = !isWhitespace(text.charCodeAt(index)) && isWhitespace(text.charCodeAt(index - 1));
+        if (startsWord)
+            return index;
+    }
+    return end;
+};
+/**
+ * The largest count of any prefix of `segment`.
+ *
+ * Encoding is not monotone: appending a character can merge two tokens into one, so the raw
+ * count of a longer text is sometimes lower. Taking the envelope over the prefixes removes
+ * that, at the cost of over-counting by the size of the dip it absorbs.
+ */
+const prefixEnvelope = (segment, count) => {
+    let largest = 0;
+    for (let end = 1; end <= segment.length; end++) {
+        const tokens = count(segment.slice(0, end));
+        if (tokens > largest)
+            largest = tokens;
+    }
+    return largest;
+};
+const exactCount = (text, count) => {
+    let total = 0;
+    let start = 0;
+    while (start < text.length) {
+        const end = segmentEnd(text, start);
+        const segment = text.slice(start, end);
+        total += start < EXACT_BUDGET_CHARS ? prefixEnvelope(segment, count) : utf8UpperBound(segment);
+        start = end;
+    }
+    return total;
+};
+const heuristicEstimator = { estimate: heuristicCount };
+const exactEstimator = (count) => ({
+    estimate(text) {
+        try {
+            return exactCount(text, count);
+        }
+        catch {
+            return utf8UpperBound(text);
+        }
+    },
+});
+const encodeCount = (text) => encode(text).length;
+/**
+ * Builds a factory over a given encoder. The parameter is the seam the tests use to stand a
+ * failing encoder up; every caller outside this module wants `estimatorFactory`.
+ */
+export const createEstimatorFactory = (count = encodeCount) => {
+    const byFamily = new Map([
+        ["gpt", exactEstimator(count)],
+        // No public JavaScript tokenizer counts the Claude family, so it shares the heuristic.
+        ["claude", heuristicEstimator],
+        ["generic", heuristicEstimator],
+    ]);
+    return {
+        forFamily(family) {
+            return byFamily.get(family) ?? heuristicEstimator;
+        },
+    };
+};
+export const estimatorFactory = createEstimatorFactory();

package/node_modules/resume-from/dist/platform/tokens/index.d.ts

@@ -0,0 +1,2 @@
+export type { EstimatorFactory, EstimatorFamily, TokenEstimator } from "./contract.js";
+export { createEstimatorFactory, estimatorFactory } from "./estimator.js";

package/node_modules/resume-from/dist/platform/tokens/index.js

@@ -0,0 +1 @@
+export { createEstimatorFactory, estimatorFactory } from "./estimator.js";

package/node_modules/resume-from/dist/session/contract.d.ts

@@ -0,0 +1,109 @@
+/** Which agent produced or receives a session. Adding an agent adds one value (FR-57). */
+export type AgentId = "pi" | "codex" | "claude-code";
+/** Absolute path of an agent profile directory, for example "/Users/me/.claude-team" (FR-2). */
+export type HomePath = string;
+/** The agent's own identifier for a session. Unique inside one home. */
+export type SessionId = string;
+/** A session is identified by three values (FR-1). */
+export interface SessionRef {
+    agent: AgentId;
+    home: HomePath;
+    id: SessionId;
+}
+/** One row of the selection list (FR-11). */
+export interface SessionDescriptor {
+    ref: SessionRef;
+    /** Short human title. Derived from the first user message when the format has none. */
+    title: string;
+    /** ISO-8601 UTC. */
+    startedAt: string;
+    /** ISO-8601 UTC. Sort key of the listing, newest first (FR-14). */
+    updatedAt: string;
+    /** Turns the source holds, before any rule of section D or E runs. */
+    turnCount: number;
+    /** Absolute path of the repository the session ran in, or null when unknown (FR-13). */
+    repoPath: string | null;
+    /** Absolute path of the source file. Lets the user select by path (FR-12). */
+    filePath: string;
+}
+/** Who produced a turn. */
+export type TurnRole = "user" | "agent";
+/** Why the turn exists. Decides pinning and drop order (FR-22, FR-31, FR-32). */
+export type TurnKind = "message" | "summary" | "tool-call";
+/** Did the call change the repository? (FR-26) */
+export type ToolEffect = "read-only" | "mutating" | "unknown";
+/**
+ * A tool call that crossed over (FR-23).
+ * There is deliberately no field for the result body: FR-24 and FR-60 are
+ * enforced by this shape, not by adapter discipline.
+ */
+export interface ToolCallRecord {
+    /** The original tool name. Never translated (FR-27). */
+    toolName: string;
+    /** The source arguments after deterministic credential redaction. */
+    argumentsText: string;
+    /** Exactly one line about the outcome (FR-23). */
+    outcomeLine: string;
+    effect: ToolEffect;
+    /** True when the source had a result body and it was dropped (FR-25). */
+    bodyDropped: boolean;
+    /**
+     * True when the source recorded any answer to this call (even an empty or error result).
+     * False when no result entry exists at all — the broken-tail signal (FR-54).
+     * This is a presence flag, not a content field; it cannot hold a result body.
+     */
+    resultRecorded?: boolean;
+}
+/** One turn of the canonical session. */
+export interface CanonicalTurn {
+    /** Zero-based position in the source session. Stable across re-reads. */
+    index: number;
+    role: TurnRole;
+    kind: TurnKind;
+    /** Visible text. Empty when kind is "tool-call". */
+    text: string;
+    /** Set when kind is "tool-call", null otherwise. */
+    toolCall: ToolCallRecord | null;
+    /** ISO-8601 UTC when the source recorded one, null otherwise. */
+    timestamp: string | null;
+}
+/** Repository state of the source session (FR-36). */
+export interface RepoSnapshot {
+    /** Commit the source ran at, or null when the source format does not record it. */
+    commit: string | null;
+    branch: string | null;
+    /** Files the source changed, derived from its mutating tool calls. */
+    changedPaths: string[];
+}
+/** Where a session came from (FR-22 metadata, FR-47 provenance). */
+export interface SourceProvenance {
+    ref: SessionRef;
+    title: string;
+    startedAt: string;
+    updatedAt: string;
+    repo: RepoSnapshot;
+}
+/** A source session in the neutral vocabulary. Every rule of sections D to I runs on this. */
+export interface CanonicalSession {
+    provenance: SourceProvenance;
+    turns: CanonicalTurn[];
+}
+/** Where the import is going, and how much room it has (FR-18, FR-29). */
+export interface TargetProfile {
+    agent: AgentId;
+    home: HomePath;
+    /** Context window of the target, in tokens. */
+    windowTokens: number;
+}
+/** The import marker the user sees. It never enters the model context (FR-47, FR-48). */
+export interface ProvenanceMarker {
+    sourceAgent: AgentId;
+    sourceHome: HomePath;
+    sourceSessionId: SessionId;
+    /** ISO-8601 UTC. */
+    importedAt: string;
+    /** One line naming what the rules dropped. */
+    droppedSummary: string;
+    /** The rendered marker, in the order it must be shown. */
+    lines: string[];
+}

package/node_modules/resume-from/dist/session/contract.js

@@ -0,0 +1,4 @@
+// GENERATED from src/session/module.md — the Public Contract section is the normative home.
+// Declarations only: no behaviour, no defaults. If this file and module.md disagree,
+// the document wins and this file is corrected.
+export {};