@herbertgao/pi-extensions 2026.8.9 → 2026.8.11

package/node_modules/@herbertgao/resume-from/dist/host/cli/args.js

@@ -0,0 +1,187 @@
+// The flag and argument grammar of the command binary (FR-10, FR-12, FR-15).
+// It parses; it decides nothing about sessions.
+import { homedir } from "node:os";
+import { join, resolve, win32 } from "node:path";
+export const USAGE = "Usage: /resume-from [<agent>] [<row> | <session-id> | <file-path>] [--home <path>] [--agent <name>] [--confirm <token>]";
+/** The agent names the user may type, and the agent they mean (FR-15). */
+const AGENT_NAMES = {
+    pi: "pi",
+    codex: "codex",
+    claude: "claude-code",
+    "claude-code": "claude-code",
+};
+const KNOWN_AGENTS = Object.keys(AGENT_NAMES).join(", ");
+/** The one confirmation flag. `runner.ts` strips it from re-run hints with the same predicate. */
+export const CONFIRM_FLAG = "--confirm";
+/** True for both accepted forms: `--confirm <token>` and `--confirm=<token>`. */
+export function isConfirmFlag(arg) {
+    return arg === CONFIRM_FLAG || arg.startsWith(`${CONFIRM_FLAG}=`);
+}
+export function parseArgs(argv, cwd) {
+    const positionals = [];
+    let onlyAgent = null;
+    let onlyHome = null;
+    let confirmationToken = null;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === undefined)
+            continue;
+        if (isConfirmFlag(arg)) {
+            if (confirmationToken !== null) {
+                return {
+                    ok: false,
+                    problem: "--confirm was given twice. Use the token from one preview.",
+                };
+            }
+            const value = arg.startsWith(`${CONFIRM_FLAG}=`)
+                ? arg.slice(CONFIRM_FLAG.length + 1)
+                : argv[index + 1];
+            if (value === undefined || !/^v1-sha256-[0-9a-f]{64}$/.test(value)) {
+                return {
+                    ok: false,
+                    problem: "--confirm needs the exact token printed by the preview. Preview the session again.",
+                };
+            }
+            confirmationToken = value;
+            if (!arg.startsWith(`${CONFIRM_FLAG}=`))
+                index += 1;
+            continue;
+        }
+        if (arg === "--home" || arg.startsWith("--home=")) {
+            if (onlyHome !== null) {
+                return {
+                    ok: false,
+                    problem: "--home was given twice. Name one source home.",
+                };
+            }
+            const value = arg.startsWith("--home=") ? arg.slice("--home=".length) : argv[index + 1];
+            if (value === undefined || value === "" || value.startsWith("-")) {
+                return {
+                    ok: false,
+                    problem: "--home needs a path. Correct form: --home <path>.",
+                };
+            }
+            if (!arg.startsWith("--home="))
+                index += 1;
+            onlyHome = resolvePath(value, cwd);
+            continue;
+        }
+        if (arg === "--agent" || arg.startsWith("--agent=")) {
+            if (onlyAgent !== null) {
+                return {
+                    ok: false,
+                    problem: "The agent was given twice. Name it once.",
+                };
+            }
+            const value = arg.startsWith("--agent=") ? arg.slice("--agent=".length) : argv[index + 1];
+            if (value === undefined || value === "" || value.startsWith("-")) {
+                return {
+                    ok: false,
+                    problem: `--agent needs a name. Correct form: --agent <name>, one of: ${KNOWN_AGENTS}.`,
+                };
+            }
+            if (!arg.startsWith("--agent="))
+                index += 1;
+            const agent = AGENT_NAMES[value];
+            if (agent === undefined) {
+                return {
+                    ok: false,
+                    problem: `"${value}" is not an agent this command knows. Use one of: ${KNOWN_AGENTS}.`,
+                };
+            }
+            onlyAgent = agent;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            if (/^-\d/.test(arg)) {
+                return {
+                    ok: false,
+                    problem: `"${arg}" is not a row. Rows start at 1 and are whole numbers.`,
+                };
+            }
+            return {
+                ok: false,
+                problem: `"${arg}" is not a flag this command knows. Known flags: --home, --agent, --confirm.`,
+            };
+        }
+        positionals.push(arg);
+    }
+    let rest = positionals;
+    const first = positionals[0];
+    if (first !== undefined) {
+        const named = AGENT_NAMES[first];
+        if (named !== undefined) {
+            if (onlyAgent !== null) {
+                return {
+                    ok: false,
+                    problem: "The agent was given twice. Name it once.",
+                };
+            }
+            onlyAgent = named;
+            rest = positionals.slice(1);
+        }
+    }
+    if (rest.length > 1) {
+        return {
+            ok: false,
+            problem: `Too many arguments: ${rest.join(" ")}. Give one row, session ID or file path.`,
+        };
+    }
+    let selection = null;
+    const token = rest[0];
+    if (token !== undefined) {
+        const classified = classify(token, cwd);
+        if (!classified.ok)
+            return classified;
+        selection = classified.value;
+    }
+    if (selection === null && confirmationToken !== null) {
+        return {
+            ok: false,
+            problem: "--confirm needs the row, session ID or file path you previewed.",
+        };
+    }
+    return {
+        ok: true,
+        args: { selection, onlyAgent, onlyHome, confirmationToken },
+    };
+}
+/** A row, a session ID or a file path — told apart by shape alone (FR-12). */
+function classify(token, cwd) {
+    if (/^\d+$/.test(token)) {
+        const row = Number(token);
+        if (row < 1) {
+            return {
+                ok: false,
+                problem: `"${token}" is not a row. Rows start at 1.`,
+            };
+        }
+        return { ok: true, value: { by: "row", row } };
+    }
+    // Numeric but not a row: caught here so a session ID that starts with a digit
+    // (a UUID, for example) is still read as a session ID.
+    if (/^[+-]?\d+(\.\d+)?$/.test(token)) {
+        return {
+            ok: false,
+            problem: `"${token}" is not a row. A row is a whole number, 1 or greater.`,
+        };
+    }
+    if (token.startsWith("~") || token.includes("/") || token.includes("\\")) {
+        return {
+            ok: true,
+            value: { by: "file-path", path: resolvePath(token, cwd) },
+        };
+    }
+    return { ok: true, value: { by: "session-id", id: token } };
+}
+function resolvePath(value, cwd) {
+    if (value === "~")
+        return homedir();
+    if (/^[A-Za-z]:[\\/]/.test(value) || value.startsWith("\\\\")) {
+        return win32.normalize(value);
+    }
+    const expanded = value.startsWith("~/") || value.startsWith("~\\")
+        ? join(homedir(), value.slice(2).replaceAll("\\", "/"))
+        : value.replaceAll("\\", "/");
+    return resolve(cwd, expanded);
+}

package/node_modules/@herbertgao/resume-from/dist/host/cli/contract.d.ts

@@ -0,0 +1,27 @@
+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, };
+/** One invocation of the command binary (FR-10). */
+export interface CliInvocation {
+    /** Arguments after the command name. */
+    argv: string[];
+    /** The directory the agent is running in. Used to find the repository (FR-13). */
+    cwd: string;
+    /** The agent the binary is running inside. The shim states it; the binary never guesses. */
+    targetAgent: AgentId;
+    /** The target home, when the shim knows it. Otherwise the adapter default is used (FR-3). */
+    targetHome: HomePath | null;
+}
+/** 0 success, 1 refused, 2 error (FR-56). */
+export type CliExit = 0 | 1 | 2;
+/** What one invocation produced. */
+export interface CliOutcome {
+    stdout: string[];
+    stderr: string[];
+    exitCode: CliExit;
+}
+/** Runs one invocation of the command binary. */
+export interface CliRunner {
+    run(invocation: CliInvocation, pipeline: ImportPipeline): Promise<CliOutcome>;
+}

package/node_modules/@herbertgao/resume-from/dist/host/cli/contract.js

@@ -0,0 +1,4 @@
+// GENERATED from src/host/cli/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/@herbertgao/resume-from/dist/host/cli/index.d.ts

@@ -0,0 +1,2 @@
+export type { CliExit, CliInvocation, CliOutcome, CliRunner } from "./contract.js";
+export { createCliRunner } from "./runner.js";

package/node_modules/@herbertgao/resume-from/dist/host/cli/index.js

@@ -0,0 +1 @@
+export { createCliRunner } from "./runner.js";

package/node_modules/@herbertgao/resume-from/dist/host/cli/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/@herbertgao/resume-from/dist/host/cli/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/@herbertgao/resume-from/dist/host/cli/render.d.ts

@@ -0,0 +1,3 @@
+import type { LandingResult, Listing } from "./contract.js";
+export declare function renderListing(listing: Listing, repoRoot: string): string[];
+export declare function renderLanding(result: LandingResult): string[];

package/node_modules/@herbertgao/resume-from/dist/host/cli/render.js

@@ -0,0 +1,70 @@
+// The text layout of the numbered list and of the landing outcome.
+// Nothing here decides anything: it prints what the pipeline returned.
+import { safeText } from "./presentation.js";
+const COLUMN_GAP = "  ";
+export function renderListing(listing, repoRoot) {
+    const lines = listing.rows.length === 0
+        ? [`No session of ${safeText(repoRoot)} was found.`]
+        : renderRows(listing.rows);
+    // Homes that could not be read are printed, never hidden.
+    if (listing.failures.length > 0) {
+        const count = listing.failures.length;
+        lines.push("", `${count} home${count === 1 ? "" : "s"} could not be read:`);
+        for (const failure of listing.failures) {
+            lines.push(`  ${safeText(failure.agent)}${COLUMN_GAP}${safeText(failure.home)}${COLUMN_GAP}${safeText(failure.message)}`);
+        }
+    }
+    if (listing.rows.length > 0) {
+        lines.push("", 'Run "/resume-from <n>" to preview a session.');
+    }
+    return lines;
+}
+export function renderLanding(result) {
+    const lines = [
+        `Imported into ${safeText(result.ref.agent)} (${safeText(result.ref.home)}) as session ${safeText(result.ref.id)}.`,
+        `${result.itemsSent} items sent, ${result.itemsStored} stored.`,
+    ];
+    if (result.switched) {
+        lines.push("You are now in the imported session.");
+    }
+    else if (result.handover !== null) {
+        lines.push(`Open it with: ${safeText(result.handover.command)}`);
+    }
+    // The marker is always printed: this host has no way to know whether the
+    // target can show one itself (FR-47, FR-48), and hiding it would be a rule.
+    lines.push("", ...result.marker.lines.map(safeText));
+    return lines;
+}
+/** Rows are 1-based and keep the order the pipeline produced (FR-10, FR-14). */
+function renderRows(rows) {
+    const cells = rows.map((row, index) => [
+        `${index + 1}`,
+        safeText(row.ref.agent),
+        safeText(row.ref.home),
+        formatTime(row.updatedAt),
+        `${row.turnCount} turns`,
+        safeText(row.title),
+    ]);
+    const widths = cells.reduce((widest, cell) => {
+        cell.forEach((value, column) => {
+            widest[column] = Math.max(widest[column] ?? 0, value.length);
+        });
+        return widest;
+    }, []);
+    return cells.map((cell) => cell
+        .map((value, column) => {
+        if (column === cell.length - 1)
+            return value;
+        const width = widths[column] ?? value.length;
+        return column === 0 ? value.padStart(width) : value.padEnd(width);
+    })
+        .join(COLUMN_GAP));
+}
+/** ISO-8601 UTC, shortened to the minute. Unknown shapes are printed as they came. */
+function formatTime(updatedAt) {
+    const safe = safeText(updatedAt);
+    const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(safe);
+    if (match === null)
+        return safe;
+    return `${match[1]} ${match[2]}Z`;
+}

package/node_modules/@herbertgao/resume-from/dist/host/cli/runner.d.ts

@@ -0,0 +1,8 @@
+import type { CliRunner, TargetProfile } from "./contract.js";
+/**
+ * @param target the profile the pipeline was built for, when the caller knows it.
+ * The shim-stated home wins, but only through the profile builder, which resolves "~/x" and
+ * relative paths to absolute form (FR-3, T-CLI-18). The resolved profile is the fallback;
+ * preferring it over the raw string ensures the pipeline never sees an unresolved path.
+ */
+export declare function createCliRunner(target?: TargetProfile): CliRunner;

package/node_modules/@herbertgao/resume-from/dist/host/cli/runner.js

@@ -0,0 +1,125 @@
+// One invocation of the command binary: parse, call the pipeline, print.
+// Every decision this file appears to make is a decision the pipeline made (FR-60).
+import { CONFIRM_FLAG, isConfirmFlag, parseArgs, USAGE } from "./args.js";
+import { safeLines, safeText } from "./presentation.js";
+import { renderLanding, renderListing } from "./render.js";
+/**
+ * The shim may state the target home; it never states the window size.
+ * These stand for "not stated": the pipeline was built for this target and
+ * applies the adapter default (FR-3).
+ */
+const HOME_NOT_STATED = "";
+const WINDOW_NOT_STATED = 0;
+/**
+ * @param target the profile the pipeline was built for, when the caller knows it.
+ * The shim-stated home wins, but only through the profile builder, which resolves "~/x" and
+ * relative paths to absolute form (FR-3, T-CLI-18). The resolved profile is the fallback;
+ * preferring it over the raw string ensures the pipeline never sees an unresolved path.
+ */
+export function createCliRunner(target) {
+    return {
+        run: (invocation, pipeline) => run(invocation, pipeline, target),
+    };
+}
+async function run(invocation, pipeline, fallback) {
+    const parsed = parseArgs(invocation.argv, invocation.cwd);
+    if (!parsed.ok) {
+        return { stdout: [], stderr: [parsed.problem, USAGE], exitCode: 2 };
+    }
+    const { selection, onlyAgent, onlyHome, confirmationToken } = parsed.args;
+    const target = {
+        // The shim states the agent. The binary never guesses it.
+        agent: invocation.targetAgent,
+        home: fallback?.home ?? invocation.targetHome ?? HOME_NOT_STATED,
+        windowTokens: fallback?.windowTokens ?? WINDOW_NOT_STATED,
+    };
+    if (selection === null) {
+        const request = {
+            repoRoot: invocation.cwd,
+            target,
+            onlyAgent,
+            onlyHome,
+        };
+        try {
+            const listing = await pipeline.list(request);
+            return {
+                stdout: renderListing(listing, invocation.cwd),
+                stderr: [],
+                exitCode: 0,
+            };
+        }
+        catch (error) {
+            return failure(`The listing failed: ${messageOf(error)}`, "Fix that, then run /resume-from again.");
+        }
+    }
+    const request = {
+        repoRoot: invocation.cwd,
+        target,
+        selection,
+        onlyAgent,
+        onlyHome,
+    };
+    // Confirming still previews first: a blocked import must not be committed (FR-33).
+    const preview = await pipeline.preview(request).then((report) => ({ ok: true, report }), (error) => ({ ok: false, error }));
+    if (!preview.ok) {
+        return failure(`Could not open the preview: ${messageOf(preview.error)}`, 'Run "/resume-from" to see the numbered list again.');
+    }
+    const report = preview.report;
+    if (report.blocked) {
+        return {
+            stdout: safeLines(report.lines),
+            stderr: [
+                `The import cannot run: ${safeText(report.blockedReason ?? "the preview did not say why.")}`,
+            ],
+            exitCode: 1,
+        };
+    }
+    if (confirmationToken === null) {
+        return {
+            stdout: [
+                ...safeLines(report.lines),
+                "",
+                `Run ${renderCommand([...invocation.argv, "--confirm", report.confirmationToken])} to import it.`,
+            ],
+            stderr: [],
+            exitCode: 0,
+        };
+    }
+    try {
+        // Neither Codex nor Claude Code can move the user, so there is no runtime (C-2).
+        const result = await pipeline.commit(request, null, confirmationToken);
+        return { stdout: renderLanding(result), stderr: [], exitCode: 0 };
+    }
+    catch (error) {
+        return failure(`The import failed: ${messageOf(error)}`, `Run ${renderCommand(withoutConfirmation(invocation.argv))} to see the preview again.`);
+    }
+}
+function failure(what, nextStep) {
+    return { stdout: [], stderr: [what, nextStep], exitCode: 2 };
+}
+function withoutConfirmation(argv) {
+    const index = argv.findIndex(isConfirmFlag);
+    if (index < 0)
+        return argv;
+    // "--confirm <token>" consumes two slots; "--confirm=<token>" consumes one.
+    const consumed = argv[index] === CONFIRM_FLAG ? 2 : 1;
+    return [...argv.slice(0, index), ...argv.slice(index + consumed)];
+}
+function renderCommand(argv) {
+    return ["/resume-from", ...argv].map(quoteArgument).join(" ");
+}
+function quoteArgument(argument) {
+    if (/^[A-Za-z0-9_./:=+-]+$/.test(argument))
+        return argument;
+    return `'${argument.replaceAll("'", `'"'"'`)}'`;
+}
+function messageOf(error) {
+    if (typeof error === "string")
+        return safeText(error);
+    if (typeof error === "object" && error !== null && "message" in error) {
+        const message = error.message;
+        if (typeof message === "string")
+            return safeText(message);
+    }
+    return safeText(String(error));
+}

package/node_modules/@herbertgao/resume-from/dist/host/contract.d.ts

@@ -0,0 +1,42 @@
+import type { AdapterRole, AgentAdapter, AgentCapabilities, LandingLevel, ProvenanceSupport, SelectionLevel, SerializedSession, StoredSessionFacts, SwitchOutcome, ValidationDefect } from "../adapters/contract.js";
+export type { AdapterRole, AgentAdapter, AgentCapabilities, LandingLevel, ProvenanceSupport, SelectionLevel, SerializedSession, StoredSessionFacts, SwitchOutcome, ValidationDefect, };
+import type { CliExit, CliInvocation, CliOutcome, CliRunner } from "./cli/contract.js";
+export type { CliExit, CliInvocation, CliOutcome, CliRunner };
+import type { PiCommandContext, PiResumeFromCommand, PiSwitchContext, PiSwitchOptions, PiSwitchResult } from "./pi-extension/contract.js";
+export type { PiCommandContext, PiResumeFromCommand, 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 { ConfigError, ConfigLoader, HomeEntry, ImportConfig, WindowOverride } from "../platform/config/contract.js";
+export type { ConfigError, ConfigLoader, HomeEntry, ImportConfig, WindowOverride };
+import type { CommitDistance, RepoIdentity, RepoReader } from "../platform/repo/contract.js";
+export type { CommitDistance, RepoIdentity, RepoReader };
+import type { Bytes, CommitError, CommitHandle, CommitRefusal, FileCommitter, PendingFile } from "../platform/store/contract.js";
+export type { Bytes, CommitError, CommitHandle, CommitRefusal, FileCommitter, PendingFile };
+import type { EstimatorFactory, EstimatorFamily, TokenEstimator } from "../platform/tokens/contract.js";
+export type { EstimatorFactory, EstimatorFamily, 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, };
+/** The agent list. Adding an agent adds one line here (FR-57). */
+export interface AgentRegistry {
+    /** Every adapter, in the order they were listed. */
+    all(): AgentAdapter[];
+    /** Rejects when the agent has no adapter (FR-56). */
+    get(agent: AgentId): AgentAdapter;
+    /** Adapters whose roles include "source" (FR-59). */
+    sources(): AgentAdapter[];
+    /** Adapters whose roles include "target" (FR-59). */
+    targets(): AgentAdapter[];
+}
+/** Builds one pipeline for one target agent. */
+export interface HostWiring {
+    registry(): AgentRegistry;
+    pipelineFor(target: TargetProfile): Promise<ImportPipeline>;
+}
+/** Builds the target profile for the agent the user is in (FR-3, FR-18). */
+export interface TargetProfileBuilder {
+    /**
+     * Uses the adapter's declared default home when home is null (FR-3),
+     * and the user's window override when there is one (FR-18).
+     */
+    build(agent: AgentId, home: HomePath | null, config: ImportConfig): TargetProfile;
+}

package/node_modules/@herbertgao/resume-from/dist/host/contract.js

@@ -0,0 +1,4 @@
+// GENERATED from src/host/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/@herbertgao/resume-from/dist/host/entry.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Which entry point runs, and starting it.
+ *
+ * C-1 forces two mechanisms: Codex and Claude Code cannot host the command, so they call a
+ * binary; Pi can, and its switch needs a live command context (C-10), so it loads an extension
+ * in-process. Exactly one of them runs per process, and which one is read from the target
+ * adapter's declared `selection` level — never from its name (FR-43, FR-58).
+ *
+ * The two starts are not symmetrical, and that is the design rather than an omission: the binary
+ * is handed an invocation and answers with an outcome, while the extension is handed the live
+ * context C-10 proved the switch needs and answers by registering a command.
+ */
+import type { AgentCapabilities, AgentId, CliInvocation, CliOutcome, HomePath } from "./contract.js";
+import { type KeySource, type PiCommandRegistrar, type PiUi, type SessionPicker } from "./pi-extension/index.js";
+import { type HostDeps } from "./wiring.js";
+export type { KeySource, PiCommandRegistrar, PiUi };
+/** The two mechanisms C-1 forces. */
+export type EntryPointKind = "command-binary" | "interactive-picker";
+/** Which entry point hosts an agent (FR-43, FR-58). */
+export declare function entryPointFor(capabilities: AgentCapabilities): EntryPointKind;
+/**
+ * One invocation of the command binary, from configuration to printed lines.
+ *
+ * Every failure is an outcome rather than a rejection: the binary's contract is an exit code and
+ * two streams, so a configuration error reaches the user as exit 2 and a sentence (FR-56).
+ */
+export declare function runCommandBinary(invocation: CliInvocation, deps?: HostDeps): Promise<CliOutcome>;
+/** What the agent's own process supplies when it loads the extension. */
+export interface PiActivation {
+    /** The agent the extension is loaded inside. The host states it; this module never guesses. */
+    agent: AgentId;
+    /** The command surface of the agent that loaded the extension. */
+    registrar: PiCommandRegistrar;
+    /** How lines reach the user, and how a confirmation is taken. */
+    ui: PiUi;
+    /** A host-native picker. When present it replaces the lower-level key source. */
+    picker?: SessionPicker;
+    /** Where the picker's keys come from (FR-9) when the host has no native picker. */
+    keys?: KeySource;
+    /** The home the agent is running, or null to use the adapter's declared default (FR-3). */
+    home: HomePath | null;
+    /** The directory the agent is running in. Used to find the repository (FR-13). */
+    cwd?: string;
+}
+/**
+ * Registers /resume-from inside an agent that hosts it itself.
+ *
+ * Unlike the binary this rejects rather than returning an outcome: there is no exit code to
+ * carry the failure, and an extension that registered a command it cannot drive would be worse
+ * than one that failed to load.
+ */
+export declare function activatePiExtension(activation: PiActivation, deps?: HostDeps): Promise<void>;

package/node_modules/@herbertgao/resume-from/dist/host/entry.js

@@ -0,0 +1,91 @@
+/**
+ * Which entry point runs, and starting it.
+ *
+ * C-1 forces two mechanisms: Codex and Claude Code cannot host the command, so they call a
+ * binary; Pi can, and its switch needs a live command context (C-10), so it loads an extension
+ * in-process. Exactly one of them runs per process, and which one is read from the target
+ * adapter's declared `selection` level — never from its name (FR-43, FR-58).
+ *
+ * The two starts are not symmetrical, and that is the design rather than an omission: the binary
+ * is handed an invocation and answers with an outcome, while the extension is handed the live
+ * context C-10 proved the switch needs and answers by registering a command.
+ */
+import { createCliRunner } from "./cli/index.js";
+import { createKeyPicker, registerResumeFrom, } from "./pi-extension/index.js";
+import { createHost } from "./wiring.js";
+/**
+ * Exhaustive by construction: a new selection level fails to compile here until it is placed,
+ * which is the whole reason this is a table and not a branch on the agent.
+ */
+const ENTRY_POINTS = {
+    "interactive-picker": "interactive-picker",
+    "numbered-list": "command-binary",
+};
+/** Which entry point hosts an agent (FR-43, FR-58). */
+export function entryPointFor(capabilities) {
+    return ENTRY_POINTS[capabilities.selection];
+}
+const messageOf = (cause) => cause instanceof Error ? cause.message : String(cause);
+/**
+ * One invocation of the command binary, from configuration to printed lines.
+ *
+ * Every failure is an outcome rather than a rejection: the binary's contract is an exit code and
+ * two streams, so a configuration error reaches the user as exit 2 and a sentence (FR-56).
+ */
+export async function runCommandBinary(invocation, deps = {}) {
+    try {
+        const host = await createHost(deps);
+        const declared = host.registry().get(invocation.targetAgent).capabilities();
+        if (entryPointFor(declared) !== "command-binary") {
+            return {
+                stdout: [],
+                stderr: [
+                    `The "${invocation.targetAgent}" adapter declares selection ` +
+                        `"${declared.selection}", so it hosts /resume-from in-process and not through this ` +
+                        "binary. Type /resume-from inside the agent itself.",
+                ],
+                exitCode: 2,
+            };
+        }
+        const target = host
+            .profiles()
+            .build(invocation.targetAgent, invocation.targetHome, host.config());
+        const pipeline = await host.pipelineFor(target);
+        return await createCliRunner(target).run(invocation, pipeline);
+    }
+    catch (cause) {
+        return { stdout: [], stderr: [messageOf(cause)], exitCode: 2 };
+    }
+}
+/**
+ * Registers /resume-from inside an agent that hosts it itself.
+ *
+ * Unlike the binary this rejects rather than returning an outcome: there is no exit code to
+ * carry the failure, and an extension that registered a command it cannot drive would be worse
+ * than one that failed to load.
+ */
+export async function activatePiExtension(activation, deps = {}) {
+    const host = await createHost(activation.cwd === undefined ? deps : { cwd: activation.cwd, ...deps });
+    const declared = host.registry().get(activation.agent).capabilities();
+    if (entryPointFor(declared) !== "interactive-picker") {
+        throw new Error(`The "${activation.agent}" adapter declares selection "${declared.selection}", so it ` +
+            "cannot host the picker in-process. It is driven by the command binary instead.");
+    }
+    const target = host.profiles().build(activation.agent, activation.home, host.config());
+    const pipeline = await host.pipelineFor(target);
+    registerResumeFrom(activation.registrar, {
+        pipeline,
+        picker: pickerFor(activation),
+        ui: activation.ui,
+        // The extension holds no capability knowledge, so the window comes from here (FR-18).
+        windowTokens: target.windowTokens,
+    });
+}
+function pickerFor(activation) {
+    if (activation.picker !== undefined)
+        return activation.picker;
+    if (activation.keys !== undefined) {
+        return createKeyPicker({ keys: activation.keys, ui: activation.ui });
+    }
+    throw new Error("Pi activation requires either a native picker or a key source.");
+}

package/node_modules/@herbertgao/resume-from/dist/host/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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, type AgentEntry } from "./agents.js";
+export type { AgentAdapter, AgentCapabilities, AgentId, AgentRegistry, AgentRuntime, CliInvocation, CliOutcome, HomePath, HostWiring, ImportConfig, ImportPipeline, ImportRequest, Listing, ListRequest, PreviewReport, TargetProfile, TargetProfileBuilder, } from "./contract.js";
+export { activatePiExtension, type EntryPointKind, entryPointFor, type KeySource, type PiActivation, type PiCommandRegistrar, type PiUi, runCommandBinary, } from "./entry.js";
+export { createTargetProfileBuilder } from "./profile.js";
+export { createAgentRegistry } from "./registry.js";
+export { createHost, type Host, type HostDeps } from "./wiring.js";