panoma 0.9.0 → 0.10.0

package/app/node_modules/@panoma/handoff/dist/index.d.ts

@@ -0,0 +1,579 @@
+export { HANDOFF_FAULTS, HandoffFault, HandoffFaultCode, asHandoffFault, faultOf, isHandoffFaultCode } from './faults.js';
+import { posix } from 'node:path';
+
+/**
+ * The vocabulary of a handoff, shared by the engine, the catalog, the web and the CLI.
+ *
+ * A **conversation** is the transcript an agent keeps on disk for one chat. It is not a
+ * *session*: `agent_sessions` in the catalog are the logbook sessions of the agent channel, a
+ * different thing with a different owner. A **handoff** passes a conversation to another agent
+ * — or resumes it in the same agent after signing in — so it continues there.
+ *
+ * Everything here is data. Nothing in this file reads a disk, opens a database or talks to a
+ * model, and the shapes are frozen: the routes, the CLI and the tests all code against them.
+ */
+/** The canonical provider ids of `packages/ai/src/providers.ts` for the agents that run in a terminal. */
+declare const AGENT_IDS: readonly ["claude-cli", "codex-cli", "opencode", "gemini-cli", "cursor-agent", "copilot-cli", "aider", "amp-cli", "goose"];
+type AgentId = (typeof AGENT_IDS)[number];
+/** The agents whose store this package can read and write so that their own resume finds the file. */
+declare const NATIVE_AGENTS: readonly AgentId[];
+/**
+ * Where a conversation is read or continued: the terminal, or the vendor's desktop app.
+ *
+ * The app and the CLI of one vendor share one store — Claude.app's Code tab and `claude` both
+ * live in `~/.claude/projects`, the Codex app and `codex` in `$CODEX_HOME/sessions` — so the
+ * surface is not another agent: it is a marker on the file (`entrypoint` for Claude,
+ * `originator` for Codex) and a different way of opening it (a deep link instead of a command).
+ */
+declare const SURFACES: readonly ["cli", "app"];
+type Surface = (typeof SURFACES)[number];
+declare function isSurface(value: string): value is Surface;
+/** The desktop app of an agent, when one exists: its handoff id, its name, and the macOS bundle. */
+interface DesktopApp {
+    /** `claude-app` is the id the open-all family already uses for Claude.app; `codex-app` is new. */
+    id: "claude-app" | "codex-app";
+    name: string;
+    /** The `.app` bundle name under /Applications; the Codex app lives inside ChatGPT.app. */
+    bundle: "Claude" | "ChatGPT";
+}
+declare const APP_OF: Readonly<Partial<Record<AgentId, DesktopApp>>>;
+/** The plain words the terminal accepts for an app target: `--to claude-app`. */
+declare const APP_WORDS: Readonly<Record<string, AgentId>>;
+/** The agent behind an app id, or nothing. */
+declare function agentOfApp(appId: string): AgentId | undefined;
+/** What a person calls each agent, the way the terminal accepts it: `--to codex`. */
+declare const AGENT_WORDS: Readonly<Record<string, AgentId>>;
+/** The display names, one per id; the same ones the `Agents` screen paints. */
+declare const AGENT_NAMES: Readonly<Record<AgentId, string>>;
+/** A plain word or a canonical id, case-insensitively, or nothing. */
+declare function agentFromWord(word: string): AgentId | undefined;
+declare function isAgentId(value: string): value is AgentId;
+/** How much travels. */
+declare const TIERS: readonly ["full", "compact", "brief"];
+type Tier = (typeof TIERS)[number];
+declare function isTier(value: string): value is Tier;
+/**
+ * Where the stores are. Every function that touches a store takes this, and under test both
+ * `home` and `env` are mandatory: a forgotten default on a developer machine would read — and
+ * with `handoff()` write — the real stores.
+ */
+interface StoreOptions {
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+}
+/** The source ended on a usage limit. `resetsAt` is ISO when the agent recorded it. */
+interface LimitHit {
+    at: string;
+    resetsAt?: string;
+    /** The agent's own word for which limit: `five_hour`, `weekly`, `primary`, `secondary`… */
+    kind?: string;
+}
+/** One row of the list: what discovery learns without reading the whole file. */
+interface ConversationRef {
+    /** `${agent}:${sessionId}` — the handle the routes and the CLI resolve. */
+    id: string;
+    agent: AgentId;
+    sessionId: string;
+    /** The first characters of the session id, what a person types back. See `shortHandle`. */
+    handle: string;
+    /** The transcript file; for OpenCode, the database file. */
+    path: string;
+    cwd: string;
+    gitBranch?: string;
+    title?: string;
+    model?: string;
+    startedAt?: string;
+    updatedAt: string;
+    /** Exact when the file was read whole; `null` when only its head and tail were. */
+    turnCount: number | null;
+    bytes: number;
+    /** The source already carries a summary of its own beginning. */
+    compacted: boolean;
+    limit?: LimitHit;
+    /** Read from the file's own marker; absent means the reader could not tell (treated as `cli`). */
+    surface?: Surface;
+}
+interface Turn {
+    role: "user" | "assistant";
+    at?: string;
+    parts: Part[];
+}
+type Part = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "tool_call";
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    kind: "tool_result";
+    callId: string;
+    output: string;
+    isError?: boolean;
+}
+/** A compaction summary at the position it holds in the source. */
+ | {
+    kind: "summary";
+    text: string;
+};
+interface Compaction {
+    at?: string;
+    text: string;
+    tokensBefore?: number;
+}
+/** What could not travel, counted so the screen can say it before anything is written. */
+interface Dropped {
+    thinking: number;
+    images: number;
+    subagents: number;
+    /** Tool outputs the source kept in a side file that was too large to inline. */
+    offloaded: number;
+    /** Credential-shaped strings replaced by the redaction mark. */
+    secrets: number;
+    other: number;
+}
+declare const NOTHING_DROPPED: Readonly<Dropped>;
+/** A whole conversation, normalized. Thinking, signatures, encrypted reasoning and images never enter. */
+interface Conversation extends ConversationRef {
+    version: 1;
+    /** sha256 over the normalized turns, without timestamps: the fidelity contract and the re-handoff key. */
+    hash: string;
+    turns: Turn[];
+    compactions: Compaction[];
+    dropped: Dropped;
+}
+/** The mechanical summary, or the one a model wrote. Derived and regenerable; never memory. */
+interface Digest {
+    by: "panoma" | "model";
+    title: string;
+    goal: string;
+    /** The newest summary the source agent made, or the model's, when there is one. */
+    summary?: string;
+    decisions: string[];
+    filesTouched: string[];
+    commandsRun: string[];
+    openItems: string[];
+    lastExchange: {
+        user?: string;
+        assistant?: string;
+    };
+    stats: {
+        turns: number;
+        toolCalls: number;
+        estimatedTokens: number;
+    };
+}
+/** Written into every file this package produces, and stored in the receipt. */
+interface Provenance {
+    sourceAgent: AgentId;
+    sourceSessionId: string;
+    sourceHash: string;
+    tier: Tier;
+    at: string;
+    by: "panoma";
+}
+/** What a target keeps and what it leaves behind, stated before the write. */
+interface Fidelity {
+    agent: AgentId;
+    /** The target's own resume finds the file. */
+    native: boolean;
+    carries: string[];
+    leaves: string[];
+    /** The version the writer was checked against by hand. */
+    testedWith?: string;
+    /** How the target resumes, in words. */
+    resumeShape: string;
+}
+/** The command that resumes a conversation in its agent, and the one line a person pastes. */
+interface Resume {
+    command: string;
+    args: string[];
+    /** `cd '<cwd>' && <command> <args>`, so it works from any folder. */
+    line: string;
+}
+/**
+ * How the vendor's desktop app opens a conversation: a deep link the app registered, verified
+ * on 11-Sep-2026 (`claude://resume?session=<id>` adopts the file into the Code tab;
+ * `codex://threads/<id>` registers and opens the thread). macOS only: the apps exist nowhere else.
+ */
+interface ResumeInApp {
+    app: DesktopApp;
+    url: string;
+    /** `open '<url>'`, the line a person pastes. */
+    line: string;
+    /** What to do by hand when the link does not answer, in English. */
+    sentence: string;
+}
+interface WriteResult {
+    agent: AgentId;
+    /** Where the copy is meant to be opened; the file is the same either way. */
+    surface: Surface;
+    sessionId: string;
+    path: string;
+    resume: Resume | undefined;
+    /** Set when the target has a desktop app and this machine can open one. */
+    resumeInApp: ResumeInApp | undefined;
+    /** Extra steps, in English, that the person runs: e.g. the `opencode import` line. */
+    steps: string[];
+    fidelity: Fidelity;
+    provenance: Provenance;
+    turns: number;
+    bytes: number;
+    dropped: Dropped;
+}
+interface StoreReport {
+    agent: AgentId;
+    path: string;
+    found: boolean;
+    conversations: number;
+}
+interface Discovery {
+    conversations: ConversationRef[];
+    stores: StoreReport[];
+}
+/** Injectable randomness, so a writer test can snapshot a file byte for byte. */
+interface Random {
+    uuid(): string;
+    hex(bytes: number): string;
+}
+interface HandoffInput {
+    conversation: Conversation;
+    target: AgentId;
+    /** `app` when the person will open the copy in the vendor's desktop app. Default `cli`. */
+    surface?: Surface;
+    tier: Tier;
+    digest?: Digest;
+    /** The folder the target resumes in; defaults to the conversation's own. */
+    cwd?: string;
+    gitBranch?: string;
+    /**
+     * Another home for the same agent (a second `CLAUDE_CONFIG_DIR`, another `CODEX_HOME`).
+     * Absolute, and it must already contain the store: this package never creates a tree.
+     * CLI only — the web never sends a path.
+     */
+    targetHome?: string;
+    /** With `compact`: how many of the newest turns travel whole. Default 12. */
+    keepTurns?: number;
+    /** With `brief` and no native target: where the document goes. */
+    out?: string;
+    now?: Date;
+    random?: Random;
+    options?: StoreOptions;
+}
+/** The portable file: the conversation and its digest, for another machine. */
+interface Bundle {
+    format: "panoma-conversation";
+    version: 1;
+    exportedAt: string;
+    conversation: Conversation;
+    digest: Digest;
+}
+declare const KEEP_TURNS_DEFAULT = 12;
+declare const DISCOVERY_LIMIT_DEFAULT = 40;
+/** Files up to this size are read whole by discovery; larger ones only by head and tail. */
+declare const DISCOVERY_WHOLE_FILE_BYTES: number;
+declare const DISCOVERY_WINDOW_BYTES: number;
+/** Above this, the screen preselects `compact`. */
+declare const LARGE_CONVERSATION_BYTES: number;
+/** Above this, `handoff()` refuses with `too-large`. */
+declare const MAX_CONVERSATION_BYTES: number;
+
+declare function isSafeId(value: string): boolean;
+/** The shape of a session id in that agent's store, checked before any id reaches a command. */
+declare function isSessionIdOf(agent: AgentId, value: string): boolean;
+/** The first eight useful characters: what the list prints and what a person types back. */
+declare function shortHandle(agent: AgentId, sessionId: string): string;
+/** `${agent}:${sessionId}`, the handle the routes and the CLI resolve. */
+declare function conversationId(agent: AgentId, sessionId: string): string;
+declare function splitConversationId(id: string): {
+    agent: string;
+    sessionId: string;
+} | undefined;
+/** The default source of randomness; tests inject their own to snapshot a file. */
+declare const cryptoRandom: Random;
+/**
+ * An OpenCode id: `prefix_` + 12 hex digits of `ms * 4096 + counter` + 14 base62 characters,
+ * which is how `packages/opencode/src/id/id.ts` keeps its rows time-sortable.
+ */
+declare function opencodeId(prefix: "ses" | "msg" | "prt", at: Date, counter: number, random: Random): string;
+
+declare function fidelityOf(target: AgentId): Fidelity;
+declare function isNativeTarget(target: AgentId): boolean;
+/**
+ * The commands each agent uses to sign out and to sign in, for the same-agent flow: a person
+ * with two accounts signs out of one, signs in with the other, and resumes the same file,
+ * because every store here is per machine and folder and never per account. Panoma prints
+ * them and never runs them; it holds no credential and rotates nothing.
+ */
+declare const SIGN_OUT: Readonly<Partial<Record<AgentId, string>>>;
+declare const SIGN_IN: Readonly<Partial<Record<AgentId, string>>>;
+declare function quoteForShell(value: string, platform?: NodeJS.Platform): string;
+/** `cd '<cwd>' && <command> <args>` — one line that works from any folder, or nothing for a document-only agent. */
+declare function resumeOf(agent: AgentId, sessionId: string, cwd: string, platform?: NodeJS.Platform): Resume | undefined;
+declare function forkOf(agent: AgentId, sessionId: string, cwd: string, platform?: NodeJS.Platform): Resume | undefined;
+/**
+ * How the vendor's app opens a conversation, or nothing when there is no app for that agent or
+ * the id does not fit. The apps exist only on macOS, so any other platform gets nothing.
+ */
+declare function resumeInApp(agent: AgentId, sessionId: string, cwd: string, platform?: NodeJS.Platform): ResumeInApp | undefined;
+
+interface ResolvedStoreOptions {
+    home: string;
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+    /** `path.win32` or `path.posix`, so the Windows branch runs on any machine. */
+    path: typeof posix;
+}
+
+interface ClaudeStore {
+    /** `CLAUDE_CONFIG_DIR` or `~/.claude`. */
+    root: string;
+    projects: string;
+    resolved: ResolvedStoreOptions;
+}
+declare function claudeStore(options?: StoreOptions): ClaudeStore;
+/** The same store rooted somewhere else: a second config folder the person names. */
+declare function claudeStoreAt(root: string, options?: StoreOptions): ClaudeStore;
+declare function claudeStoreExists(store: ClaudeStore): boolean;
+/**
+ * The folder name Claude Code derives from a working directory.
+ *
+ * Every character outside `[A-Za-z0-9]` becomes `-`, which is why a slug starts with `-` on
+ * POSIX and with the drive letter on Windows (`C--Users-x-proj`). The rule is the same on both
+ * platforms; only the join differs.
+ */
+declare function claudeSlug(cwd: string): string;
+declare function claudeProjectDir(store: ClaudeStore, cwd: string): string;
+declare function claudeTranscriptPath(store: ClaudeStore, cwd: string, sessionId: string): string;
+
+interface CodexStore {
+    /** `CODEX_HOME` or `~/.codex`. */
+    root: string;
+    sessions: string;
+    index: string;
+    /** `config.toml`: read for its `model`, `model_reasoning_effort`, `approval_policy` and `sandbox_mode` lines, never written. */
+    config: string;
+    resolved: ResolvedStoreOptions;
+}
+declare function codexStore(options?: StoreOptions): CodexStore;
+declare function codexStoreAt(root: string, options?: StoreOptions): CodexStore;
+declare function codexStoreExists(store: CodexStore): boolean;
+/** The day folder and the file name a new rollout gets, both from the same instant in local time. */
+declare function codexRolloutPath(store: CodexStore, at: Date, sessionId: string): string;
+
+/**
+ * Where OpenCode keeps its conversations.
+ *
+ * Verified on OpenCode 1.2.6 (11-Sep-2026): `$XDG_DATA_HOME/opencode/opencode.db`, default
+ * `~/.local/share/opencode`, a SQLite file with the tables `session`, `message` and `part`
+ * whose `data` column holds JSON. Beside it, the legacy JSON store `storage/{session,message,
+ * part}/**` that older versions wrote and `opencode db migrate` folds in; it is the fallback
+ * when `node:sqlite` cannot open the file. Nothing else of OpenCode's in that folder is opened
+ * — `auth.json` lives there too.
+ *
+ * Writing goes through the official door, `opencode import <file>`: the envelope file,
+ * `panoma-import-<id>.json`, is written next to the database and the caller runs the import;
+ * the reader opens it again to preview the copy, so it is on the list below with the files
+ * OpenCode writes. On Windows the data folder is taken from `LOCALAPPDATA` by the same XDG
+ * resolution OpenCode uses; it is not verified there (docs/open-questions.md).
+ */
+
+interface OpencodeStore {
+    /** `$XDG_DATA_HOME/opencode` or `~/.local/share/opencode`. */
+    root: string;
+    db: string;
+    storage: string;
+    resolved: ResolvedStoreOptions;
+}
+declare function opencodeStore(options?: StoreOptions): OpencodeStore;
+declare function opencodeStoreAt(root: string, options?: StoreOptions): OpencodeStore;
+/** Either the database or the legacy JSON store counts: an old install has only the second. */
+declare function opencodeStoreExists(store: OpencodeStore): boolean;
+declare function opencodeEnvelopePath(store: OpencodeStore, sessionId: string): string;
+
+interface GeminiStore {
+    /** `~/.gemini`. */
+    root: string;
+    tmp: string;
+    registry: string;
+    resolved: ResolvedStoreOptions;
+}
+declare function geminiStore(options?: StoreOptions): GeminiStore;
+declare function geminiStoreAt(root: string, options?: StoreOptions): GeminiStore;
+declare function geminiStoreExists(store: GeminiStore): boolean;
+/** The project id Gemini CLI uses for a working directory on this store. */
+declare function geminiProjectId(store: GeminiStore, cwd: string): string;
+/**
+ * `session-2026-09-11T14-00-<id8>.jsonl`: the UTC instant, ISO to the minute, which is how
+ * Gemini's own `ChatRecordingService` names its files — the ones on this disk spell the `Z` hour
+ * of their `startTime`, not the local one. Until 12-Sep-2026 this sentence said «local time»
+ * while the code said UTC; the Codex store made the opposite slip and had to be corrected, so
+ * the sentence and the code now agree, and `stores.test.ts` pins the spelling.
+ */
+declare function geminiChatPath(store: GeminiStore, projectId: string, at: Date, sessionId: string): string;
+
+/** Per native agent, the relative globs under its store root this package may open. */
+declare const MAY_OPEN: Readonly<Partial<Record<AgentId, readonly string[]>>>;
+
+interface GeminiReadDeps {
+    /** Folders whose sha256 may be this chat's project id: the catalog roots, the current folder. */
+    cwds?: readonly string[];
+}
+declare function readGeminiConversation(path: string, options?: StoreOptions, deps?: GeminiReadDeps): Promise<Conversation>;
+
+/** What a test injects instead of `node:sqlite`; the real one is wrapped to this shape. */
+interface SqliteOpener {
+    open(path: string): SqliteHandle;
+}
+interface SqliteHandle {
+    all(sql: string, ...params: (string | number)[]): Record<string, unknown>[];
+    close(): void;
+}
+interface OpencodeReadDeps {
+    sqlite?: SqliteOpener;
+}
+interface OpencodeSource {
+    /** The database file, the data folder, or an envelope file. */
+    path: string;
+    sessionId: string;
+}
+declare function readOpencodeConversation(source: OpencodeSource, options?: StoreOptions, deps?: OpencodeReadDeps): Promise<Conversation>;
+
+interface ReadSource {
+    agent: AgentId;
+    /** The transcript file; for OpenCode, the database, the data folder, or an envelope file. */
+    path: string;
+    /** Needed for OpenCode, where one file holds every session. */
+    sessionId?: string;
+}
+interface ReadDeps extends OpencodeReadDeps, GeminiReadDeps {
+}
+declare function readConversation(source: ReadSource, options?: StoreOptions, deps?: ReadDeps): Promise<Conversation>;
+
+declare function readClaudeConversation(path: string, options?: StoreOptions): Promise<Conversation>;
+
+declare function readCodexConversation(path: string, options?: StoreOptions): Promise<Conversation>;
+
+declare function digestConversation(conversation: Conversation): Digest;
+/** The digest as the Markdown a `summary` part or a brief carries. */
+declare function digestMarkdown(digest: Digest): string;
+
+interface CompactOptions {
+    keepTurns?: number;
+}
+declare function compactConversation(conversation: Conversation, digest: Digest, options?: CompactOptions): Conversation;
+
+interface WriteRequest {
+    /** The turns already reduced to the tier: `full` as read, `compact` from `compactConversation`. */
+    conversation: Conversation;
+    tier: Tier;
+    /** The store root of the target: its config folder, `CODEX_HOME`, the data folder, `~/.gemini`. */
+    root: string;
+    cwd: string;
+    gitBranch?: string;
+    /** What the target lists it as; the digest title when there is one. */
+    title?: string;
+    now: Date;
+    random: Random;
+    platform: NodeJS.Platform;
+    /** Where the copy is meant to be opened. The file is the same; only the result's doors differ. */
+    surface?: Surface;
+}
+/** `redactSecrets` at the mouth, with the marks counted into `dropped.secrets`. */
+declare class Redactor {
+    count: number;
+    text(value: string): string;
+}
+
+interface BriefOptions {
+    keepTurns?: number;
+    now?: Date;
+    /** Filled with the number of secret marks the document carries. */
+    redactor?: Redactor;
+}
+declare function briefMarkdown(conversation: Conversation, digest: Digest, options?: BriefOptions): string;
+/** The document on disk, 0600, folders created. Returns the bytes written. */
+declare function writeBrief(path: string, markdown: string): Promise<number>;
+
+declare function writeClaudeConversation(request: WriteRequest): Promise<WriteResult>;
+
+declare function writeCodexConversation(request: WriteRequest): Promise<WriteResult>;
+
+declare function writeOpencodeConversation(request: WriteRequest): Promise<WriteResult>;
+
+declare function writeGeminiConversation(request: WriteRequest): Promise<WriteResult>;
+
+/**
+ * The folder as this disk spells it: absolute, with `.` and `..` and a trailing separator
+ * folded, and resolved through every link where it exists. An empty string stays empty —
+ * `resolve("")` would answer the process's own folder, and a conversation without a folder
+ * is not one that ran here.
+ */
+declare function realFolder(folder: string): Promise<string>;
+/** `cwd` equals or is inside `folder`; case-insensitive on Windows, separators normalized. */
+declare function insideFolder(cwd: string, folder: string, platform?: NodeJS.Platform): boolean;
+/** The two spellings name one folder; case-insensitive on Windows, separators normalized. */
+declare function sameFolder(a: string, b: string, platform?: NodeJS.Platform): boolean;
+
+interface DiscoverOptions extends StoreOptions {
+    /** Newest conversations per store. Default 40. With `cwd`, the newest of that folder's. */
+    limit?: number;
+    /** Keep only conversations whose `cwd` equals or is inside this folder, chosen before the cap. */
+    cwd?: string;
+    /** Which stores to read. Default: the four native agents. */
+    agents?: readonly AgentId[];
+    /** Folders whose sha256 may be a Gemini project id. */
+    cwds?: readonly string[];
+    /** Injected instead of `node:sqlite`, for tests. */
+    sqlite?: SqliteOpener;
+}
+declare function discoverConversations(options?: DiscoverOptions): Promise<Discovery>;
+/** The store reports alone: where each store is, whether it exists, how many candidates it holds. */
+declare function stores(options?: StoreOptions): Promise<StoreReport[]>;
+
+declare function resolveConversation(handleOrPrefix: string, discovery: Discovery): ConversationRef;
+/** Two conversations from different agents closer than this are not chosen between. */
+declare const SAME_HOUR_MS: number;
+/**
+ * The conversation a caller means when it names none: the newest of the folder — and the rival
+ * that stops the choice, when there is one. Two agents within the same hour is not a choice the
+ * machine makes: the person was in both, and the wrong one handed over is the one they were not
+ * looking at. Every row within the hour of the newest is looked at, not only the second: two
+ * Codex sessions ten minutes apart and a Claude one behind them are still two agents in one
+ * hour, and until 12-Sep-2026 both doors read the second row alone and handed the newest over.
+ * The rows come newest first, as discovery lists them; the rule is shared by `panoma handoff`
+ * and `POST /api/agent/handoff` so the two doors cannot drift apart.
+ */
+declare function newestOfFolder(refs: readonly ConversationRef[]): {
+    newest: ConversationRef | undefined;
+    rival: ConversationRef | undefined;
+};
+
+declare function toBundle(conversation: Conversation, digest: Digest, now?: Date): Bundle;
+/** A path, as opposed to a handle: it has a separator or ends with `.json`. */
+declare function isBundlePath(value: string): boolean;
+declare function fromBundle(value: unknown): Bundle;
+
+interface NormalTurn {
+    role: "user" | "assistant";
+    parts: string[];
+}
+declare function normalizeTurns(turns: readonly Turn[]): NormalTurn[];
+declare function hashTurns(turns: readonly Turn[]): string;
+
+/** Every part as the text a text-only agent would keep. */
+declare function textOfPart(part: Part): string;
+/** `Continued from Claude Code conversation <id> by panoma on 2026-09-11 · tier full`. */
+declare function provenanceLine(source: AgentId, sessionId: string, tier: Tier, at: Date): string;
+
+declare function handoff(input: HandoffInput): Promise<WriteResult>;
+/**
+ * The refusals `handoff()` would raise for this input, in its order, and no file: the same
+ * `prepare()`, thrown away. `now`, `random` and `out` are accepted and unused, so a caller can
+ * pass the very input it will write with.
+ */
+declare function checkHandoff(input: HandoffInput): Promise<void>;
+
+export { AGENT_IDS, AGENT_NAMES, AGENT_WORDS, APP_OF, APP_WORDS, type AgentId, type BriefOptions, type Bundle, type ClaudeStore, type CodexStore, type CompactOptions, type Compaction, type Conversation, type ConversationRef, DISCOVERY_LIMIT_DEFAULT, DISCOVERY_WHOLE_FILE_BYTES, DISCOVERY_WINDOW_BYTES, type DesktopApp, type Digest, type DiscoverOptions, type Discovery, type Dropped, type Fidelity, type GeminiReadDeps, type GeminiStore, type HandoffInput, KEEP_TURNS_DEFAULT, LARGE_CONVERSATION_BYTES, type LimitHit, MAX_CONVERSATION_BYTES, MAY_OPEN, NATIVE_AGENTS, NOTHING_DROPPED, type OpencodeReadDeps, type OpencodeSource, type OpencodeStore, type Part, type Provenance, type Random, type ReadDeps, type ReadSource, type Resume, type ResumeInApp, SAME_HOUR_MS, SIGN_IN, SIGN_OUT, SURFACES, type SqliteHandle, type SqliteOpener, type StoreOptions, type StoreReport, type Surface, TIERS, type Tier, type Turn, type WriteRequest, type WriteResult, agentFromWord, agentOfApp, briefMarkdown, checkHandoff, claudeProjectDir, claudeSlug, claudeStore, claudeStoreAt, claudeStoreExists, claudeTranscriptPath, codexRolloutPath, codexStore, codexStoreAt, codexStoreExists, compactConversation, conversationId, cryptoRandom, digestConversation, digestMarkdown, discoverConversations, fidelityOf, forkOf, fromBundle, geminiChatPath, geminiProjectId, geminiStore, geminiStoreAt, geminiStoreExists, handoff, hashTurns, insideFolder, isAgentId, isBundlePath, isNativeTarget, isSafeId, isSessionIdOf, isSurface, isTier, newestOfFolder, normalizeTurns, opencodeEnvelopePath, opencodeId, opencodeStore, opencodeStoreAt, opencodeStoreExists, provenanceLine, quoteForShell, readClaudeConversation, readCodexConversation, readConversation, readGeminiConversation, readOpencodeConversation, realFolder, resolveConversation, resumeInApp, resumeOf, sameFolder, shortHandle, splitConversationId, stores, textOfPart, toBundle, writeBrief, writeClaudeConversation, writeCodexConversation, writeGeminiConversation, writeOpencodeConversation };