@herbertgao/pi-extensions 2026.8.8 → 2026.8.10

package/node_modules/resume-from/dist/host/index.js

@@ -0,0 +1,10 @@
+/**
+ * The composition root. It builds everything and drives nothing: `createHost` loads the
+ * configuration, the platform services and the agent list, and the two starts below run the one
+ * entry point the target agent's declared capability names.
+ */
+export { AGENTS } from "./agents.js";
+export { activatePiExtension, entryPointFor, runCommandBinary, } from "./entry.js";
+export { createTargetProfileBuilder } from "./profile.js";
+export { createAgentRegistry } from "./registry.js";
+export { createHost } from "./wiring.js";

package/node_modules/resume-from/dist/host/pi-extension/command.d.ts

@@ -0,0 +1,18 @@
+import type { PiResumeFromCommand, SessionPicker } from "./contract.js";
+import type { PiUi } from "./ui.js";
+/** The name Pi shows for the command (FR-7). */
+export declare const RESUME_FROM_COMMAND_NAME = "resume-from";
+export interface ResumeFromDeps {
+    /** The picker opened when no argument names a session (FR-9). */
+    picker: SessionPicker;
+    /** How lines reach the user and how a confirmation is taken. */
+    ui: PiUi;
+    /**
+     * The context window of the Pi the user is in, in tokens. Required, not
+     * defaulted: this module holds no capability knowledge, so the size comes
+     * from the composition root that builds the command.
+     */
+    windowTokens: number;
+}
+/** Builds the /resume-from command. `run` is the only path to the switch (C-10). */
+export declare function createResumeFromCommand(deps: ResumeFromDeps): PiResumeFromCommand;

package/node_modules/resume-from/dist/host/pi-extension/command.js

@@ -0,0 +1,103 @@
+/** The name Pi shows for the command (FR-7). */
+export const RESUME_FROM_COMMAND_NAME = "resume-from";
+const CONFIRM_QUESTION = "Import this session? (y/N)";
+const CANCELLED_LINE = "Cancelled. Nothing was imported.";
+const HELP_ARGUMENTS = new Set(["help", "-h", "--help"]);
+const HELP_LINES = [
+    `Usage: /${RESUME_FROM_COMMAND_NAME} [<session-id> | <file-path>]`,
+    "No argument opens the session selector.",
+    "<session-id> previews the matching session.",
+    "<file-path> previews an absolute or relative session file.",
+    "Pi asks for confirmation before importing anything.",
+];
+const USAGE_LINE = HELP_LINES[0] ?? `Usage: /${RESUME_FROM_COMMAND_NAME}`;
+const BLOCKED_FALLBACK = "The import is blocked.";
+/** Builds the /resume-from command. `run` is the only path to the switch (C-10). */
+export function createResumeFromCommand(deps) {
+    return {
+        run: (ctx, args, pipeline) => runResumeFrom(deps, ctx, args, pipeline),
+    };
+}
+async function runResumeFrom(deps, ctx, args, pipeline) {
+    const scope = {
+        repoRoot: ctx.cwd,
+        target: targetOf(deps, ctx),
+        onlyAgent: null,
+        onlyHome: null,
+    };
+    const selection = await resolveSelection(deps, args, pipeline, scope);
+    if (selection === null)
+        return;
+    const request = { ...scope, selection };
+    const report = await pipeline.preview(request);
+    deps.ui.show(report.lines); // Verbatim and unreordered (FR-21).
+    if (report.blocked) {
+        deps.ui.show([report.blockedReason ?? BLOCKED_FALLBACK]);
+        return; // A blocked preview is never offered for confirmation (FR-33).
+    }
+    if ((await deps.ui.confirm(CONFIRM_QUESTION)) !== "selected") {
+        deps.ui.show([CANCELLED_LINE]);
+        return; // Nothing is written before the user confirms (FR-16, FR-20).
+    }
+    // Pi's own context is the runtime handle the Pi adapter switches with (FR-44).
+    const landing = await pipeline.commit(request, ctx, report.confirmationToken);
+    if (!landing.switched)
+        present(deps.ui, landing);
+}
+/** The import target is always the Pi home the user is in (FR-1, FR-2). */
+function targetOf(deps, ctx) {
+    return { agent: "pi", home: ctx.home, windowTokens: deps.windowTokens };
+}
+/** The selection, or null when the user cancelled or there was nothing to pick. */
+async function resolveSelection(deps, args, pipeline, scope) {
+    const given = args.filter((argument) => argument.trim().length > 0);
+    if (given.length === 1 && HELP_ARGUMENTS.has(given[0] ?? "")) {
+        deps.ui.show(HELP_LINES);
+        return null;
+    }
+    if (given.length > 1) {
+        deps.ui.show([USAGE_LINE]);
+        return null;
+    }
+    const [only] = given;
+    if (only !== undefined)
+        return parseArgument(only); // An argument skips the picker (FR-12).
+    const listing = await pipeline.list(scope);
+    if (listing.failures.length > 0) {
+        deps.ui.show(listing.failures.map(formatFailure)); // Skipped homes are never silent.
+    }
+    if (listing.rows.length === 0) {
+        deps.ui.show([`No sessions to import for ${scope.repoRoot}.`]);
+        return null; // A picker over nothing is a trap.
+    }
+    const picked = await deps.picker.pick(listing);
+    if (picked.choice !== "selected" || picked.selected === null) {
+        deps.ui.show([CANCELLED_LINE]);
+        return null;
+    }
+    // The file path, not the session ID: an ID is unique only inside one home and
+    // a SelectionInput carries no home.
+    return { by: "file-path", path: picked.selected.filePath };
+}
+/** A session ID or a file path (FR-12). Resolving the path is the pipeline's job. */
+function parseArgument(argument) {
+    return argument.includes("/") || argument.includes("\\")
+        ? { by: "file-path", path: argument }
+        : { by: "session-id", id: argument };
+}
+function formatFailure(failure) {
+    return `Skipped ${failure.agent} home ${failure.home}: ${failure.message}`;
+}
+/**
+ * Shows the marker and handover when the switch did not happen (FR-45, FR-47).
+ * A successful switch invalidates the command context; the package shim renders
+ * the persisted provenance marker as a transcript entry in the replacement session instead.
+ */
+function present(ui, landing) {
+    ui.show(landing.marker.lines);
+    if (landing.handover !== null)
+        ui.show(formatHandover(landing.handover));
+}
+function formatHandover(handover) {
+    return [`The session is ready: ${handover.sessionId}`, `Open it with: ${handover.command}`];
+}

package/node_modules/resume-from/dist/host/pi-extension/contract.d.ts

@@ -0,0 +1,34 @@
+import type { PiSwitchContext, PiSwitchOptions, PiSwitchResult } from "../../adapters/pi/contract.js";
+export type { PiSwitchContext, PiSwitchOptions, PiSwitchResult };
+import type { AgentRuntime, HandoverInstruction, HomeFailure, ImportPipeline, ImportRequest, LandingResult, Listing, ListRequest, PreviewReport, PreviewWarning, SelectionError, SelectionInput, WarningKind } from "../../import/contract.js";
+export type { AgentRuntime, HandoverInstruction, HomeFailure, ImportPipeline, ImportRequest, LandingResult, Listing, ListRequest, PreviewReport, PreviewWarning, SelectionError, SelectionInput, WarningKind, };
+import type { AgentId, HomePath, ProvenanceMarker, SessionDescriptor, SessionId, SessionRef, TargetProfile } from "../../session/contract.js";
+export type { AgentId, HomePath, ProvenanceMarker, SessionDescriptor, SessionId, SessionRef, TargetProfile, };
+/** What the user did at the picker or the confirmation. */
+export type UserChoice = "selected" | "cancelled";
+/** The picker over the listing (FR-9). */
+export interface SessionPicker {
+    /** Resolves with the chosen row, or with "cancelled" when the user escaped. */
+    pick(listing: Listing): Promise<PickResult>;
+}
+/** The result of one picker interaction. */
+export interface PickResult {
+    choice: UserChoice;
+    /** Set when choice is "selected". */
+    selected: SessionDescriptor | null;
+}
+/** Pi's command context, as this module needs it. */
+export interface PiCommandContext extends PiSwitchContext {
+    /** The directory Pi is running in. Used to find the repository (FR-13). */
+    cwd: string;
+    /** The Pi home the user is running, which is the import target (FR-1, FR-2). */
+    home: HomePath;
+}
+/** The /resume-from command inside Pi (FR-7, FR-9, FR-44). */
+export interface PiResumeFromCommand {
+    /**
+     * Pi calls this when the user types /resume-from.
+     * It is a command handler, which is the only call site C-10 proved safe for switchSession.
+     */
+    run(ctx: PiCommandContext, args: string[], pipeline: ImportPipeline): Promise<void>;
+}

package/node_modules/resume-from/dist/host/pi-extension/contract.js

@@ -0,0 +1,4 @@
+// GENERATED from src/host/pi-extension/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/host/pi-extension/index.d.ts

@@ -0,0 +1,6 @@
+export { createResumeFromCommand, RESUME_FROM_COMMAND_NAME, type ResumeFromDeps, } from "./command.js";
+export type { PiCommandContext, PickResult, PiResumeFromCommand, SessionPicker, UserChoice, } from "./contract.js";
+export { createKeyPicker, formatRow, type KeyPickerDeps, type KeySource, type PickerKey, } from "./picker.js";
+export { safeLines, safeText } from "./presentation.js";
+export { type PiCommandDefinition, type PiCommandRegistrar, type RegisterDeps, registerResumeFrom, } from "./register.js";
+export type { PiUi } from "./ui.js";

package/node_modules/resume-from/dist/host/pi-extension/index.js

@@ -0,0 +1,4 @@
+export { createResumeFromCommand, RESUME_FROM_COMMAND_NAME, } from "./command.js";
+export { createKeyPicker, formatRow, } from "./picker.js";
+export { safeLines, safeText } from "./presentation.js";
+export { registerResumeFrom, } from "./register.js";

package/node_modules/resume-from/dist/host/pi-extension/picker.d.ts

@@ -0,0 +1,16 @@
+import type { SessionDescriptor, SessionPicker } from "./contract.js";
+import type { PiUi } from "./ui.js";
+/** The keys the picker understands (FR-9). */
+export type PickerKey = "up" | "down" | "enter" | "escape";
+/** Where the picker takes its keys from. Resolving with null ends the picker. */
+export interface KeySource {
+    next(): Promise<PickerKey | null>;
+}
+export interface KeyPickerDeps {
+    keys: KeySource;
+    ui: PiUi;
+}
+/** One row of the picker: agent, home, time, title and turn count (FR-11). */
+export declare function formatRow(row: SessionDescriptor): string;
+/** A picker driven by keys: arrow keys move, Enter selects, Escape cancels (FR-9). */
+export declare function createKeyPicker(deps: KeyPickerDeps): SessionPicker;

package/node_modules/resume-from/dist/host/pi-extension/picker.js

@@ -0,0 +1,35 @@
+import { safeText } from "./presentation.js";
+const HEADER = "Select a session — up/down to move, Enter to select, Escape to cancel:";
+/** One row of the picker: agent, home, time, title and turn count (FR-11). */
+export function formatRow(row) {
+    return `${safeText(row.ref.agent)}  ${safeText(row.updatedAt)}  ${safeText(row.title)}  (${row.turnCount} turns)  ${safeText(row.ref.home)}`;
+}
+function render(listing, cursor) {
+    return [
+        HEADER,
+        ...listing.rows.map((row, index) => `${index === cursor ? ">" : " "} ${formatRow(row)}`),
+    ];
+}
+const CANCELLED = { choice: "cancelled", selected: null };
+/** A picker driven by keys: arrow keys move, Enter selects, Escape cancels (FR-9). */
+export function createKeyPicker(deps) {
+    return {
+        async pick(listing) {
+            let cursor = 0;
+            for (;;) {
+                deps.ui.show(render(listing, cursor));
+                const key = await deps.keys.next();
+                if (key === null || key === "escape")
+                    return CANCELLED;
+                if (key === "up")
+                    cursor = Math.max(0, cursor - 1);
+                else if (key === "down")
+                    cursor = Math.min(listing.rows.length - 1, cursor + 1);
+                else if (key === "enter") {
+                    const selected = listing.rows[cursor];
+                    return selected === undefined ? CANCELLED : { choice: "selected", selected };
+                }
+            }
+        },
+    };
+}

package/node_modules/resume-from/dist/host/pi-extension/presentation.d.ts

@@ -0,0 +1,2 @@
+export declare function safeText(value: string): string;
+export declare function safeLines(lines: readonly string[]): string[];

package/node_modules/resume-from/dist/host/pi-extension/presentation.js

@@ -0,0 +1,11 @@
+function globalPattern(source) {
+    return new RegExp(source, "gu");
+}
+const ANSI_SEQUENCE = globalPattern(String.raw `\x1b(?:\][^\x07]*(?:\x07|\x1b\\)|\[[0-?]*[ -/]*[@-~])`);
+const UNSAFE_CONTROL = globalPattern(String.raw `[\x00-\x1f\x7f-\x9f\u2028\u2029\u202a-\u202e\u2066-\u2069]`);
+export function safeText(value) {
+    return value.replace(ANSI_SEQUENCE, " ").replace(UNSAFE_CONTROL, " ");
+}
+export function safeLines(lines) {
+    return lines.map(safeText);
+}

package/node_modules/resume-from/dist/host/pi-extension/register.d.ts

@@ -0,0 +1,25 @@
+import { type ResumeFromDeps } from "./command.js";
+import type { ImportPipeline, PiCommandContext } from "./contract.js";
+/**
+ * What Pi is given when the extension loads.
+ *
+ * `module.md` makes registration a responsibility of this module but names no
+ * API for it — Pi's extension surface is an internal of a moving application,
+ * measured once at 0.83.0 (C-10). The dependency is therefore structural: Pi
+ * passes anything that can register a command, and only this file knows the
+ * shape. When Pi's API changes, this file changes and nothing else does.
+ */
+export interface PiCommandDefinition {
+    name: string;
+    description: string;
+    /** Pi calls this when the user types the command. It is the only call site (C-10). */
+    run(ctx: PiCommandContext, args: string[]): Promise<void>;
+}
+export interface PiCommandRegistrar {
+    registerCommand(definition: PiCommandDefinition): void;
+}
+export interface RegisterDeps extends ResumeFromDeps {
+    pipeline: ImportPipeline;
+}
+/** Registers /resume-from with Pi. */
+export declare function registerResumeFrom(registrar: PiCommandRegistrar, deps: RegisterDeps): void;

package/node_modules/resume-from/dist/host/pi-extension/register.js

@@ -0,0 +1,11 @@
+import { createResumeFromCommand, RESUME_FROM_COMMAND_NAME, } from "./command.js";
+const DESCRIPTION = "Continue another session here. Use /resume-from --help for accepted arguments.";
+/** Registers /resume-from with Pi. */
+export function registerResumeFrom(registrar, deps) {
+    const command = createResumeFromCommand(deps);
+    registrar.registerCommand({
+        name: RESUME_FROM_COMMAND_NAME,
+        description: DESCRIPTION,
+        run: (ctx, args) => command.run(ctx, args, deps.pipeline),
+    });
+}

package/node_modules/resume-from/dist/host/pi-extension/ui.d.ts

@@ -0,0 +1,20 @@
+import type { UserChoice } from "./contract.js";
+/**
+ * The user-facing channel of the Pi extension.
+ *
+ * There is deliberately no model-facing method here. FR-47 and FR-48 require the
+ * provenance marker to reach the user and never the model context, and FR-46
+ * requires the prompt to stay empty after landing. An interface with no way to
+ * send anything makes both structural instead of a convention, the same way the
+ * command handler being the only call site makes C-10 structural.
+ *
+ * Pi supplies the implementation. `module.md` names showing and confirming as
+ * responsibilities of this module but gives no API for either, so the shape is
+ * declared here and injected, not taken from the command context.
+ */
+export interface PiUi {
+    /** Show one block of lines to the user, in the order given. */
+    show(lines: readonly string[]): void;
+    /** Ask the user to confirm. "selected" means confirmed, "cancelled" means not. */
+    confirm(question: string): Promise<UserChoice>;
+}

package/node_modules/resume-from/dist/host/pi-extension/ui.js

@@ -0,0 +1 @@
+export {};

package/node_modules/resume-from/dist/host/profile.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Where an import is going, and how much room it has (FR-3, FR-18).
+ *
+ * Three values, each from one source: the agent the entry point reported, the home the user named
+ * or the adapter declared, and the window the user configured or the adapter declared.
+ */
+import type { AgentRegistry, TargetProfileBuilder } from "./contract.js";
+export declare function createTargetProfileBuilder(registry: AgentRegistry): TargetProfileBuilder;

package/node_modules/resume-from/dist/host/profile.js

@@ -0,0 +1,31 @@
+/**
+ * Where an import is going, and how much room it has (FR-3, FR-18).
+ *
+ * Three values, each from one source: the agent the entry point reported, the home the user named
+ * or the adapter declared, and the window the user configured or the adapter declared.
+ */
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+/** A home is always absolute (FR-2). `~` is the user's, and everything else is resolved. */
+function resolveHome(home) {
+    if (home === "~")
+        return resolve(homedir());
+    if (home.startsWith("~/") || home.startsWith("~\\")) {
+        return join(resolve(homedir()), home.slice(2));
+    }
+    return resolve(home);
+}
+export function createTargetProfileBuilder(registry) {
+    return {
+        build(agent, home, config) {
+            // Rejects an agent with no adapter, rather than guessing one (FR-56).
+            const declared = registry.get(agent).capabilities();
+            const override = config.windowOverrides.find((entry) => entry.agent === agent);
+            return {
+                agent,
+                home: home === null ? declared.defaultHome : resolveHome(home),
+                windowTokens: override?.windowTokens ?? declared.defaultWindowTokens,
+            };
+        },
+    };
+}

package/node_modules/resume-from/dist/host/registry.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The registry over the agent list. It answers three questions and decides nothing: which
+ * adapters exist, which one is an agent's, and which of them fill a role (FR-59).
+ *
+ * Every answer comes from what an adapter declares. Nothing here reads a name.
+ */
+import type { AgentAdapter, AgentRegistry } from "./contract.js";
+export declare function createAgentRegistry(adapters: readonly AgentAdapter[]): AgentRegistry;

package/node_modules/resume-from/dist/host/registry.js

@@ -0,0 +1,33 @@
+/**
+ * The registry over the agent list. It answers three questions and decides nothing: which
+ * adapters exist, which one is an agent's, and which of them fill a role (FR-59).
+ *
+ * Every answer comes from what an adapter declares. Nothing here reads a name.
+ */
+const SOURCE = "source";
+const TARGET = "target";
+/** Adapters whose declaration includes a role (FR-59). */
+const withRole = (adapters, role) => adapters.filter((adapter) => adapter.capabilities().roles.includes(role));
+export function createAgentRegistry(adapters) {
+    const all = [...adapters];
+    const byAgent = new Map();
+    for (const adapter of all) {
+        const agent = adapter.capabilities().agent;
+        if (!byAgent.has(agent))
+            byAgent.set(agent, adapter);
+    }
+    return {
+        all: () => [...all],
+        get(agent) {
+            const found = byAgent.get(agent);
+            if (found === undefined) {
+                // Not defaulted: importing into the wrong agent is worse than not importing (FR-56).
+                throw new Error(`There is no adapter for "${agent}", so the tool cannot run inside it. ` +
+                    `The agents it knows are: ${[...byAgent.keys()].join(", ")}.`);
+            }
+            return found;
+        },
+        sources: () => withRole(all, SOURCE),
+        targets: () => withRole(all, TARGET),
+    };
+}

package/node_modules/resume-from/dist/host/wiring.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The construction order, as code (Internal Design, steps 1 to 5).
+ *
+ * 1. Configuration, once. Everything downstream reads the result, and a rejected configuration
+ *    stops the command before an adapter exists or a home is read (FR-56).
+ * 2. The platform services: the estimator factory, the repository reader, the committer.
+ * 3. The adapters of the list. `capabilities()` is cheap and pure, so it may be read at once.
+ * 4. The target profile, built by the caller from the agent the entry point is running in.
+ * 5. The pipeline, wired with the services and the adapters.
+ *
+ * Every step is injectable, because a composition root whose parts cannot be replaced cannot be
+ * tested — and because the deps are thunks, not values, "nothing is built before the
+ * configuration is loaded" is a property a test can observe rather than a promise.
+ */
+import { type AgentEntry } from "./agents.js";
+import type { AgentRegistry, ConfigLoader, EstimatorFactory, FileCommitter, HostWiring, ImportConfig, ImportPipeline, RepoReader, TargetProfile, TargetProfileBuilder } from "./contract.js";
+/** Everything the composition root builds, and what a test may replace. */
+export interface HostDeps {
+    /** The agent list. Defaults to the one list of the tree (FR-57). */
+    agents?: readonly AgentEntry[];
+    configLoader?: ConfigLoader;
+    createEstimators?: () => EstimatorFactory;
+    createRepo?: () => RepoReader;
+    createCommitter?: () => FileCommitter;
+    /** The directory the command runs in. The repository reader reads git state from it (FR-13). */
+    cwd?: string;
+    /** The import time written into the marker (FR-47). Injected so a preview and a commit agree. */
+    now?: () => string;
+}
+/**
+ * The wiring, plus the two things an entry point needs to reach step 4: the configuration that
+ * was loaded once, and the builder that turns an agent and a home into a profile.
+ */
+export interface Host extends HostWiring {
+    registry(): AgentRegistry;
+    profiles(): TargetProfileBuilder;
+    /** The one configuration of this process (Constraints: loaded once per process). */
+    config(): ImportConfig;
+    pipelineFor(target: TargetProfile): Promise<ImportPipeline>;
+}
+export declare function createHost(deps?: HostDeps): Promise<Host>;

package/node_modules/resume-from/dist/host/wiring.js

@@ -0,0 +1,67 @@
+/**
+ * The construction order, as code (Internal Design, steps 1 to 5).
+ *
+ * 1. Configuration, once. Everything downstream reads the result, and a rejected configuration
+ *    stops the command before an adapter exists or a home is read (FR-56).
+ * 2. The platform services: the estimator factory, the repository reader, the committer.
+ * 3. The adapters of the list. `capabilities()` is cheap and pure, so it may be read at once.
+ * 4. The target profile, built by the caller from the agent the entry point is running in.
+ * 5. The pipeline, wired with the services and the adapters.
+ *
+ * Every step is injectable, because a composition root whose parts cannot be replaced cannot be
+ * tested — and because the deps are thunks, not values, "nothing is built before the
+ * configuration is loaded" is a property a test can observe rather than a promise.
+ */
+import { createImportPipeline } from "../import/index.js";
+import { createConfigLoader } from "../platform/config/index.js";
+import { createRepoReader } from "../platform/repo/index.js";
+import { createFileCommitter } from "../platform/store/index.js";
+import { estimatorFactory } from "../platform/tokens/index.js";
+import { AGENTS } from "./agents.js";
+import { createTargetProfileBuilder } from "./profile.js";
+import { createAgentRegistry } from "./registry.js";
+/** The role an adapter must declare to receive an import (FR-59). */
+const TARGET_ROLE = "target";
+export async function createHost(deps = {}) {
+    // Step 1. It rejects before anything else exists, which is what FR-56 asks for.
+    const config = await (deps.configLoader ?? createConfigLoader()).load();
+    // Step 2.
+    const cwd = deps.cwd ?? process.cwd();
+    const estimators = (deps.createEstimators ?? (() => estimatorFactory))();
+    const repo = (deps.createRepo ?? (() => createRepoReader(cwd)))();
+    const committer = (deps.createCommitter ?? createFileCommitter)();
+    // Step 3. The list is the only place that knows which implementations exist. Each adapter
+    // names itself, so the family is keyed by what it declares and never by what the list assumed.
+    const families = new Map();
+    const adapters = (deps.agents ?? AGENTS).map((entry) => {
+        const adapter = entry.create();
+        const agent = adapter.capabilities().agent;
+        if (!families.has(agent))
+            families.set(agent, entry.family);
+        return adapter;
+    });
+    const registry = createAgentRegistry(adapters);
+    const profiles = createTargetProfileBuilder(registry);
+    return {
+        registry: () => registry,
+        profiles: () => profiles,
+        config: () => config,
+        // Step 5. Async so a refusal reaches the caller as a rejection, never as a throw.
+        async pipelineFor(target) {
+            const declared = registry.get(target.agent).capabilities();
+            if (!declared.roles.includes(TARGET_ROLE)) {
+                throw new Error(`The "${target.agent}" adapter cannot receive an import: it declares the role(s) ` +
+                    `${declared.roles.join(", ")} and not "${TARGET_ROLE}" (FR-59). ` +
+                    "Run the import from an agent whose adapter has that role.");
+            }
+            return createImportPipeline({
+                adapters,
+                config,
+                estimator: estimators.forFamily(families.get(target.agent) ?? "generic"),
+                committer,
+                repo,
+                ...(deps.now === undefined ? {} : { now: deps.now }),
+            });
+        },
+    };
+}

package/node_modules/resume-from/dist/import/confirmation.d.ts

@@ -0,0 +1,6 @@
+import type { SessionDescriptor } from "../session/contract.js";
+import type { PreviewContent } from "./preview/contract.js";
+import type { TransferPlan } from "./transfer/contract.js";
+/** Binds confirmation to every input that can affect the imported session or its preview. */
+export declare function confirmationToken(descriptor: SessionDescriptor, plan: TransferPlan, report: PreviewContent): string;
+export declare function confirmationMatches(expected: string, supplied: string): boolean;

package/node_modules/resume-from/dist/import/confirmation.js

@@ -0,0 +1,27 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+const TOKEN_PREFIX = "v1-sha256-";
+const TOKEN_PATTERN = /^v1-sha256-[0-9a-f]{64}$/;
+/** Binds confirmation to every input that can affect the imported session or its preview. */
+export function confirmationToken(descriptor, plan, report) {
+    const payload = stableJson({ descriptor, plan, report });
+    return `${TOKEN_PREFIX}${createHash("sha256").update(payload).digest("hex")}`;
+}
+export function confirmationMatches(expected, supplied) {
+    if (!TOKEN_PATTERN.test(expected) || !TOKEN_PATTERN.test(supplied))
+        return false;
+    return timingSafeEqual(Buffer.from(expected), Buffer.from(supplied));
+}
+/** JSON with recursively sorted object keys, so separate CLI processes derive the same token. */
+function stableJson(value) {
+    return JSON.stringify(normalize(value));
+}
+function normalize(value) {
+    if (Array.isArray(value))
+        return value.map(normalize);
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, item]) => item !== undefined)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([key, item]) => [key, normalize(item)]));
+}

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

@@ -0,0 +1,41 @@
+import type { AdapterRole, AgentAdapter, AgentCapabilities, AgentRuntime, LandingLevel, ProvenanceSupport, SelectionLevel, SerializedSession, StoredSessionFacts, SwitchOutcome, ValidationDefect } from "../adapters/contract.js";
+export type { AdapterRole, AgentAdapter, AgentCapabilities, AgentRuntime, LandingLevel, ProvenanceSupport, SelectionLevel, SerializedSession, StoredSessionFacts, SwitchOutcome, ValidationDefect, };
+import type { HomeFailure, Listing, SearchScope, SelectionError, SelectionInput, SessionFinder } from "./discovery/contract.js";
+export type { HomeFailure, Listing, SearchScope, SelectionError, SelectionInput, SessionFinder };
+import type { HandoverInstruction, LandingError, LandingResult, LandingStage, SessionLander } from "./landing/contract.js";
+export type { HandoverInstruction, LandingError, LandingResult, LandingStage, SessionLander };
+import type { PreviewBuilder, PreviewContent, PreviewReport, PreviewWarning, WarningKind } from "./preview/contract.js";
+export type { PreviewBuilder, PreviewContent, PreviewReport, PreviewWarning, WarningKind };
+import type { DropReason, PinReason, TransferPlan, TransferRules, TurnDrop, TurnPin } from "./transfer/contract.js";
+export type { DropReason, PinReason, TransferPlan, TransferRules, TurnDrop, TurnPin };
+import type { HomeEntry, ImportConfig, WindowOverride } from "../platform/config/contract.js";
+export type { HomeEntry, ImportConfig, WindowOverride };
+import type { Bytes, CommitError, CommitHandle, CommitRefusal, FileCommitter, PendingFile } from "../platform/store/contract.js";
+export type { Bytes, CommitError, CommitHandle, CommitRefusal, FileCommitter, PendingFile };
+import type { TokenEstimator } from "../platform/tokens/contract.js";
+export type { TokenEstimator };
+import type { AgentId, CanonicalSession, CanonicalTurn, HomePath, ProvenanceMarker, RepoSnapshot, SessionDescriptor, SessionId, SessionRef, SourceProvenance, TargetProfile, ToolCallRecord, ToolEffect, TurnKind, TurnRole } from "../session/contract.js";
+export type { AgentId, CanonicalSession, CanonicalTurn, HomePath, ProvenanceMarker, RepoSnapshot, SessionDescriptor, SessionId, SessionRef, SourceProvenance, TargetProfile, ToolCallRecord, ToolEffect, TurnKind, TurnRole, };
+/** What to list (FR-10, FR-15). */
+export interface ListRequest {
+    repoRoot: string;
+    target: TargetProfile;
+    onlyAgent: AgentId | null;
+    onlyHome: HomePath | null;
+}
+/** What to preview, and later what to commit (FR-16, FR-20). */
+export interface ImportRequest {
+    repoRoot: string;
+    target: TargetProfile;
+    selection: SelectionInput;
+    onlyAgent: AgentId | null;
+    onlyHome: HomePath | null;
+}
+/** One import, from listing to landing. Every host drives these three calls. */
+export interface ImportPipeline {
+    list(request: ListRequest): Promise<Listing>;
+    /** Writes nothing (FR-16). */
+    preview(request: ImportRequest): Promise<PreviewReport>;
+    /** Runs only after the user confirmed the preview (FR-20). */
+    commit(request: ImportRequest, runtime: AgentRuntime, confirmationToken: string): Promise<LandingResult>;
+}

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

@@ -0,0 +1,4 @@
+// GENERATED from src/import/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 {};