jeopi-cli 16.2.14 → 16.2.17

package/dist/types/cli/update-cli.d.ts

@@ -0,0 +1,105 @@
+/** Result from running the installed binary and parsing its reported version. */
+export interface InstalledVersionVerification {
+    ok: boolean;
+    actual?: string;
+    path?: string;
+}
+/** Paths and verifier used while replacing a downloaded binary update. */
+export interface BinaryReplacementOptions {
+    targetPath: string;
+    tempPath: string;
+    backupPath: string;
+    expectedVersion: string;
+    verifyInstalledVersion: (expectedVersion: string) => Promise<InstalledVersionVerification>;
+}
+/**
+ * Parse update subcommand arguments.
+ * Returns undefined if not an update command.
+ */
+export declare function parseUpdateArgs(args: string[]): {
+    force: boolean;
+    check: boolean;
+} | undefined;
+type UpdateMethod = "brew" | "mise" | "bun" | "binary";
+interface UpdateMethodResolutionOptions {
+    homebrewPrefix?: string;
+    miseBinDirs?: readonly string[];
+    miseDataDir?: string;
+}
+export declare function resolveUpdateMethodForTest(jeopiPath: string, bunBinDir: string | undefined, options?: UpdateMethodResolutionOptions): UpdateMethod;
+interface BunInstallCachePruneResult {
+    scannedPackages: number;
+    removedEntries: number;
+}
+/**
+ * Prune Bun's package cache so each package keeps only its newest cached version.
+ *
+ * Bun stores package cache entries as both a package marker directory
+ * (`react/19.2.6@@@1`) and a materialized package directory
+ * (`react@19.2.6@@@1`). Global `jeopi` updates can leave one full copy per
+ * release. The marker and materialized entries are removed together so the
+ * cache stays internally consistent.
+ */
+export declare function pruneBunInstallCache(cacheDir: string, packageNames?: Set<string>): Promise<BunInstallCachePruneResult>;
+export declare function resolveBunGlobalNodeModulesDirFromLocations(globalBinDir: string | undefined, cacheDir: string | undefined): string | undefined;
+/**
+ * Best-effort removal of binary-update backups left by earlier runs.
+ *
+ * Each self-update moves the previous executable to `<binary>.<timestamp>.<pid>.bak`
+ * before swapping the new one in. On Windows that backup cannot be deleted
+ * while the updating process is alive, so it is left for a later run to reclaim
+ * once its owning process has exited. Also matches the legacy fixed
+ * `<binary>.bak` name produced before backups were timestamped, so users
+ * upgrading from a buggy release get the orphaned file cleaned up.
+ */
+export declare function sweepStaleBackups(targetPath: string): Promise<void>;
+/**
+ * Atomically replace the installed binary and roll back if version verification fails.
+ */
+export declare function replaceBinaryForUpdate(options: BinaryReplacementOptions): Promise<InstalledVersionVerification>;
+/**
+ * Build the bun argv used to globally install a specific jeopi version.
+ *
+ * The version is selected by hitting {@link NPM_REGISTRY} directly in
+ * {@link getLatestRelease}, so the install MUST observe the same catalog:
+ *
+ * - `--registry=${NPM_REGISTRY}` pins the install to the official registry
+ *   regardless of the user's bunfig/`.npmrc`. A mirror (corporate proxy,
+ *   Taobao, …) that hasn't yet replicated the release would otherwise reject
+ *   a version the upstream registry already advertises.
+ * - `--no-cache` tells bun to ignore its on-disk manifest snapshot so it
+ *   re-fetches metadata from that registry on every invocation.
+ *
+ * Together these two flags make `jeopi update` produce exactly the registry
+ * lookup the version check just performed. See #1686.
+ *
+ * Also pins {@link NATIVES_PACKAGE} and the platform-specific
+ * `jeopi-natives-<tag>` leaf to `expectedVersion`. `bun install -g`
+ * does not reliably refresh transitive `optionalDependencies` when the
+ * top-level package is the only one bumped, so the native addon and its
+ * version sentinel can drift out of sync with the freshly installed
+ * `jeopi` and the loader aborts at
+ * `validateLoadedBindings` on the next launch
+ * (`The .node file on disk is from a different release than this loader`).
+ * Listing the natives explicitly forces bun to replace them in lock-step.
+ * The leaf is added only on tags the release pipeline actually publishes
+ * ({@link SUPPORTED_NATIVE_TAGS}) so unsupported platforms still fail with
+ * the original "no matching version" message instead of `EBADPLATFORM`.
+ * See #1824.
+ */
+export declare function buildBunInstallArgs(expectedVersion: string, nativeTag?: string): string[];
+export declare function buildHomebrewUpdateArgs(force: boolean): string[];
+export declare function buildMiseUpgradeArgs(): string[];
+export declare function buildMiseForceInstallArgs(expectedVersion: string): string[];
+/**
+ * Run the update command.
+ */
+export declare function runUpdateCommand(opts: {
+    force: boolean;
+    check: boolean;
+}): Promise<void>;
+/**
+ * Print update command help.
+ */
+export declare function printUpdateHelp(): void;
+export {};

package/dist/types/cli/usage-cli.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Usage CLI command handler.
+ *
+ * Handles `jeopi usage` — fetches provider usage reports for every
+ * authenticated account and prints a detailed per-account breakdown
+ * (limits, windows, reset times, plan metadata). Accounts whose
+ * credentials produced no usage report are listed too, so the output
+ * always covers the full credential pool.
+ */
+import { type UsageHistoryEntry, type UsageReport } from "jeopi-ai";
+export interface UsageCommandArgs {
+    json?: boolean;
+    provider?: string;
+    redact?: boolean;
+    /** Show recorded usage-limit history instead of a live snapshot. */
+    history?: boolean;
+    /** History window in days (with `history`). */
+    days?: number;
+}
+/** Identity slice of a stored credential, for "every account" coverage. */
+export interface UsageAccountIdentity {
+    provider: string;
+    type: "api_key" | "oauth";
+    email?: string;
+    accountId?: string;
+    projectId?: string;
+    enterpriseUrl?: string;
+}
+/**
+ * Minimal-reveal masks for identity strings (`--redact`).
+ *
+ * Every mask shows a two-character anchor. When two identities share the
+ * anchor, the mask additionally reveals the shortest "middle-out"
+ * differentiator — the shortest substring (closest to the string's middle on
+ * ties) that no colliding identity contains — as `an*`, `ca*9*`, `ca*nb*`.
+ * Prefix growth is deliberately avoided: it leaks the start of the local
+ * part (`can.boluk@*`) when a couple of mid-string characters suffice.
+ * Duplicate strings (same account on two providers) share a mask.
+ */
+export declare function buildRedactionMap(values: Iterable<string>): Map<string, string>;
+/**
+ * Stored credentials that no usage report could be attributed to.
+ *
+ * Conservative on purpose: when a provider's reports carry no identity at
+ * all (or the credential is an API key alongside existing reports), we
+ * can't attribute, so we don't claim the account is missing.
+ */
+export declare function collectUnreportedAccounts(reports: UsageReport[], accounts: UsageAccountIdentity[]): UsageAccountIdentity[];
+/** Per-window capacity stat: how much account quota is burned and left. */
+export interface ProviderWindowStat {
+    /** Compact window label, e.g. "5h", "7d". */
+    window: string;
+    durationMs?: number;
+    /** Accounts reporting a limit in this window. */
+    accounts: number;
+    /** Sum of each account's binding used fraction — accounts' worth of quota burned. */
+    usedAccounts: number;
+    /** Accounts' worth of quota still available across reporting accounts. */
+    remainingAccounts: number;
+}
+/**
+ * Aggregate one provider's reports into per-window quota capacity stats.
+ *
+ * Limits are bucketed by window duration (5h, 7d, ...). Within a bucket each
+ * account contributes its single highest used fraction — when an account has
+ * several meters on the same window (tiered/metered limits), the most-burned
+ * one is what binds.
+ */
+export declare function computeProviderWindowStats(reports: UsageReport[]): ProviderWindowStat[];
+/**
+ * Render the full text breakdown: per provider, per account, every limit
+ * with a bar, amounts, and reset times; unattributed credentials trail
+ * each provider section as "no usage data" rows.
+ */
+export declare function formatUsageBreakdown(reports: UsageReport[], accounts: UsageAccountIdentity[], nowMs: number, redaction?: Map<string, string>): string;
+/**
+ * Render recorded usage-limit history: per provider, per account, one
+ * peak-per-bucket sparkline per limit window plus latest/peak percentages.
+ */
+export declare function formatUsageHistory(entries: UsageHistoryEntry[], sinceMs: number, nowMs: number, redaction?: Map<string, string>): string;
+/**
+ * Keep only accounts worth a usage row: those whose provider has a usage
+ * provider, so a missing report is a real gap rather than the absence of any
+ * usage concept. Providers with no usage endpoint (web-search keys, local /
+ * keyless servers, inference providers without a usage API) would only ever
+ * render as noise, so they are dropped.
+ *
+ * `hasUsageProvider` is injected (in practice {@link AuthStorage.usageProviderFor})
+ * so custom/broker resolvers stay authoritative — no provider list is duplicated
+ * here. An explicit `--provider` request bypasses the cull, so
+ * `jeopi usage --provider xai` can still confirm the stored credential has no
+ * usage endpoint.
+ */
+export declare function selectReportableAccounts(accounts: UsageAccountIdentity[], hasUsageProvider: (provider: string) => boolean, explicitProvider?: string): UsageAccountIdentity[];
+export declare function runUsageCommand(cmd: UsageCommandArgs): Promise<void>;

package/dist/types/cli/web-search-cli.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Web search CLI command handlers.
+ *
+ * Handles `jeopi q`/`jeopi web-search` subcommands for testing web search providers.
+ */
+import type { SearchProviderId } from "../web/search/types";
+export interface SearchCommandArgs {
+    query: string;
+    provider?: SearchProviderId | "auto";
+    recency?: "day" | "week" | "month" | "year";
+    limit?: number;
+    expanded: boolean;
+}
+/**
+ * Parse web search subcommand arguments.
+ * Returns undefined if not a web search command.
+ */
+export declare function parseSearchArgs(args: string[]): SearchCommandArgs | undefined;
+export declare function runSearchCommand(cmd: SearchCommandArgs): Promise<void>;
+export declare function printSearchHelp(): void;

package/dist/types/cli/worktree-cli.d.ts

@@ -0,0 +1,26 @@
+type WorktreeKind = "pr-checkout" | "task-isolation" | "empty" | "stray";
+export interface WorktreeEntry {
+    /** Absolute path to the worktree dir (or stray container) under `~/.jeopi/wt/`. */
+    path: string;
+    /** Classification of what we found on disk. */
+    kind: WorktreeKind;
+    /** Parent repo root, when this is a registered git worktree. */
+    parentRepo?: string;
+    /** Branch name extracted from the parent's tracking file, when available. */
+    branch?: string;
+    /** When set, the entry is unhealthy and `jeopi worktree clear` will remove it. */
+    orphanReason?: string;
+}
+export interface ListWorktreesOptions {
+    json: boolean;
+}
+export interface ClearWorktreesOptions {
+    /** Remove every entry, including live PR-checkout worktrees. */
+    all: boolean;
+    /** Print what would be removed without touching the filesystem. */
+    dryRun: boolean;
+    json: boolean;
+}
+export declare function listWorktrees(options: ListWorktreesOptions): Promise<void>;
+export declare function clearWorktrees(options: ClearWorktreesOptions): Promise<void>;
+export {};

package/dist/types/cli-commands.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Top-level CLI command table.
+ *
+ * Lives in its own module (importable without side effects) so that tests can
+ * inspect the registered subcommands without triggering the side-effectful
+ * top-level await in `cli.ts`. Adding a new subcommand here is enough to make
+ * `runCli` route to it instead of forwarding the argv as a prompt to
+ * `launch` — see #1496 for the original "args silently leak to the LLM"
+ * regression that motivated the split.
+ */
+import type { CommandEntry } from "jeopi-utils/cli";
+export declare const commands: CommandEntry[];
+export declare function reservedTopLevelWordMessage(first: string | undefined, argc?: number): string | undefined;
+/**
+ * Return true when `first` matches a registered subcommand name or alias.
+ *
+ * Flags (`-…`) and `@file` arguments are never subcommands; for those the CLI
+ * runner skips ahead to the default `launch` command.
+ */
+export declare function isSubcommand(first: string | undefined): boolean;
+export type ResolvedCliArgv = {
+    argv: string[];
+} | {
+    error: string;
+};
+/**
+ * Decide what the CLI runner should do with raw argv: reject bare reserved
+ * management words, pass help/version through untouched, route a recognized
+ * subcommand (even behind leading global flags like `--approval-mode=yolo`) to
+ * that command with the flags preserved, and forward everything else to
+ * `launch` (#2970).
+ */
+export declare function resolveCliArgv(argv: string[]): ResolvedCliArgv;

package/dist/types/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+/** Run the CLI with the given argv (no `process.argv` prefix). */
+export declare function runCli(argv: string[]): Promise<void>;

package/dist/types/collab/crypto.d.ts

@@ -0,0 +1,7 @@
+import type { CollabFrame } from "./protocol";
+export declare function generateRoomKey(): Uint8Array;
+export declare function generateWriteToken(): Uint8Array;
+export declare function importRoomKey(raw: Uint8Array): Promise<CryptoKey>;
+export declare function seal(key: CryptoKey, frame: CollabFrame): Promise<Uint8Array>;
+/** Inverse of {@link seal}. Throws on auth failure or malformed input. */
+export declare function open(key: CryptoKey, data: Uint8Array): Promise<CollabFrame>;

package/dist/types/collab/display-name.d.ts

@@ -0,0 +1,3 @@
+import type { InteractiveModeContext } from "../modes/types";
+/** Display name for this process's user in collab sessions. */
+export declare function collabDisplayName(ctx: InteractiveModeContext): string;

package/dist/types/collab/guest.d.ts

@@ -0,0 +1,52 @@
+import type { ImageContent } from "jeopi-ai";
+import type { AgentHubRemote } from "../modes/components/agent-hub";
+import type { InteractiveModeContext } from "../modes/types";
+import { AgentRegistry } from "../registry/agent-registry";
+import { type CollabSessionState } from "./protocol";
+/** Commands a guest may run locally; everything else is host-only. */
+export declare const COLLAB_GUEST_ALLOWED_COMMANDS: Record<string, true>;
+/** Minimal context surface the idle-state reconciler mutates. */
+export interface GuestIdleReconcilerCtx {
+    statusLine: {
+        markActivityEnd: () => void;
+    };
+    loadingAnimation: {
+        stop: () => void;
+    } | undefined;
+}
+/**
+ * Close the guest UI state held open by an earlier `agent_start` whose
+ * matching `agent_end` never reached us — most often because a reconnect
+ * dropped the event mid-stream. Triggered from {@link CollabGuestLink}'s
+ * `state` reconciler when the host reports `isStreaming === false`:
+ * folds the in-flight active-time window into the per-session meter (so
+ * `time_spent` stops ticking) and stops the `Working…` loader if one is
+ * still animating. No-op when the host is still streaming.
+ *
+ * Exported for direct unit testing; mutates the loader field on `ctx` so
+ * the same loader is not stopped twice on subsequent reconciliations.
+ */
+export declare function reconcileGuestIdleHostState(ctx: GuestIdleReconcilerCtx, isStreaming: boolean): void;
+/** Reconcile a welcome/resync snapshot's host activity state into the guest meter. */
+export interface GuestSnapshotActivityReconcilerCtx extends GuestIdleReconcilerCtx {
+    statusLine: GuestIdleReconcilerCtx["statusLine"] & {
+        markActivityStart: () => void;
+    };
+}
+export declare function reconcileGuestSnapshotHostState(ctx: GuestSnapshotActivityReconcilerCtx, isStreaming: boolean): void;
+export declare class CollabGuestLink {
+    #private;
+    state: CollabSessionState | null;
+    /** Local mirror of the host's agent ecosystem (refs carry `session: null`). */
+    readonly agentRegistry: AgentRegistry;
+    /** Agent Hub actions routed to the host over the wire. */
+    get hubRemote(): AgentHubRemote;
+    /** True when this guest joined through a read-only (view) link. */
+    get readOnly(): boolean;
+    constructor(ctx: InteractiveModeContext);
+    join(link: string): Promise<void>;
+    /** User-initiated leave (or post-disconnect cleanup): restore the previous session. */
+    leave(_reason: string): Promise<void>;
+    sendPrompt(text: string, images?: ImageContent[]): void;
+    sendAbort(): void;
+}

package/dist/types/collab/host.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Host side of a collab live session.
+ *
+ * Taps the host session's event stream and SessionManager append chokepoint,
+ * broadcasting entries/events/state to guests through the relay. Guests prompt
+ * and abort through us; the host machine runs the agent and tools. The host's
+ * subagent ecosystem is mirrored too: task EventBus traffic (observer HUD),
+ * agent-registry snapshots (Agent Hub table), hub chat/kill/revive commands,
+ * and incremental subagent-transcript reads.
+ */
+import type { CollabUiRequestDraft, CollabUiResponseValue } from "jeopi-wire";
+import type { InteractiveModeContext } from "../modes/types";
+import { type CollabParticipant } from "./protocol";
+/** Max bytes served per fetch-transcript reply (guest re-requests from `newSize`). */
+export declare const TRANSCRIPT_READ_CAP: number;
+/**
+ * Outcome of {@link CollabHost.requestGuestUi}. `answered` carries the guest's
+ * response (an `undefined` value is a genuine guest cancel); `unavailable`
+ * means the collab channel went away (teardown, relay drop) or the request was
+ * aborted before any guest answered — callers MUST NOT treat it as a cancel.
+ */
+export type CollabGuestUiResult = {
+    kind: "answered";
+    value: CollabUiResponseValue;
+} | {
+    kind: "unavailable";
+};
+export declare class CollabHost {
+    #private;
+    constructor(ctx: InteractiveModeContext);
+    get link(): string;
+    /** Browser deep link for the configured collab web UI. */
+    get webLink(): string;
+    /** Read-only variant of {@link link}: bare room key, no write token. */
+    get viewLink(): string;
+    /** Read-only variant of {@link webLink}. */
+    get webViewLink(): string;
+    get participants(): CollabParticipant[];
+    requestGuestUi(request: CollabUiRequestDraft, signal?: AbortSignal): Promise<CollabGuestUiResult> | null;
+    start(relayUrl: string, webUrl?: string): Promise<void>;
+    /** Broadcast a goodbye, detach all taps, and close the socket. */
+    stop(reason: string): Promise<void>;
+}

package/dist/types/collab/protocol.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Collab live-session wire protocol.
+ *
+ * Hub topology: the host is authoritative, guests never peer. All session
+ * payloads (`CollabFrame`) travel AES-256-GCM sealed; the relay only sees the
+ * plaintext envelope (`[4B uint32 BE peerId][sealed payload]`) plus TEXT JSON
+ * control messages that carry no session data.
+ */
+import type { ImageContent, Model } from "jeopi-ai";
+import type { BusChannel, CollabUiRequest, GuestFrame, ParsedCollabLink, Participant, SessionState, AgentSnapshot as WireAgentSnapshot } from "jeopi-wire";
+import { DEFAULT_RELAY_URL, ENVELOPE_HEADER_LENGTH, ROOM_ID_BYTES } from "jeopi-wire";
+import type { ContextUsage } from "../extensibility/extensions/types";
+import type { AgentSessionEvent } from "../session/agent-session";
+import type { SessionEntry, SessionHeader } from "../session/session-entries";
+export type { CollabPromptDetails, CollabUiRequest, CollabUiRequestDraft, CollabUiResponseValue, CollabUiSelectItem, ParsedCollabLink, RelayControlMessage, RelayControlToGuest, RelayControlToHost, } from "jeopi-wire";
+export { COLLAB_PROMPT_MESSAGE_TYPE, COLLAB_PROTO } from "jeopi-wire";
+export { DEFAULT_RELAY_URL, ENVELOPE_HEADER_LENGTH, ROOM_ID_BYTES };
+export type CollabParticipant = Participant;
+export type AgentSnapshot = WireAgentSnapshot;
+/** Debounced footer snapshot broadcast by the host. */
+export type CollabSessionState = SessionState & {
+    /**
+     * Host model (full catalog object). Guests apply it to their replica
+     * agent state so model display and context-window math are native.
+     */
+    model?: Model;
+    /** Host status-line context numbers (guest system prompt/tools differ, so local estimates drift). */
+    contextUsage?: ContextUsage;
+};
+/**
+ * Encrypted payload frames (inside AES-GCM, JSON). The wire package pins the
+ * JSON skeleton (`WireFrame`); host-side frames carry the rich session types
+ * that serialize into those shapes.
+ */
+export type CollabFrame = Exclude<GuestFrame, {
+    t: "prompt";
+}> | {
+    t: "prompt";
+    text: string;
+    images?: ImageContent[];
+} | {
+    t: "welcome";
+    proto: number;
+    header: SessionHeader;
+    state: CollabSessionState;
+    agents: AgentSnapshot[];
+    /**
+     * Total number of `SessionEntry` items the host will deliver in the
+     * `snapshot-chunk` frames that follow. The guest stays in the
+     * snapshot-loading phase until it has accumulated that many entries
+     * (or a chunk arrives with `final: true`).
+     */
+    entryCount: number;
+    /** True when this peer joined through a read-only (view) link. */
+    readOnly?: boolean;
+}
+/**
+ * Targeted snapshot fragment delivered after `welcome`. Splits a large
+ * transcript across many small frames so the guest's per-chunk progress
+ * timeout resets each time the relay delivers another batch; without
+ * chunking, a multi-MB session has to fit one giant frame inside the
+ * 30 s first-welcome budget. The last chunk carries `final: true` so the
+ * guest can finalize the replica session.
+ */
+ | {
+    t: "snapshot-chunk";
+    entries: SessionEntry[];
+    final: boolean;
+} | {
+    t: "entry";
+    entry: SessionEntry;
+} | {
+    t: "event";
+    event: AgentSessionEvent;
+} | {
+    t: "state";
+    state: CollabSessionState;
+}
+/** Mirrored EventBus traffic (task subagent lifecycle/progress channels only). */
+ | {
+    t: "bus";
+    channel: BusChannel;
+    data: unknown;
+}
+/** Full agent-registry snapshot (debounced on registry change). */
+ | {
+    t: "agents";
+    agents: AgentSnapshot[];
+} | {
+    t: "ui-request";
+    request: CollabUiRequest;
+} | {
+    t: "ui-request-end";
+    reqId: number;
+}
+/** Targeted reply to fetch-transcript; `error` marks a terminal read failure that guests must surface without hot retrying. */
+ | {
+    t: "transcript";
+    reqId: number;
+    text: string;
+    newSize: number;
+    error?: string;
+} | {
+    t: "bye";
+    reason: string;
+} | {
+    t: "error";
+    message: string;
+};
+export declare function packEnvelope(peerId: number, sealed: Uint8Array): Uint8Array;
+export declare function unpackEnvelope(data: Uint8Array): {
+    peerId: number;
+    payload: Uint8Array;
+} | null;
+/** Rewrite the peerId in place without copying the payload. */
+export declare function rewriteEnvelopePeer(data: Uint8Array, peerId: number): void;
+export declare function generateRoomId(): string;
+/**
+ * Render the shareable link. Compact forms: the default relay collapses to
+ * `<roomId>.<key>`, other wss relays drop the scheme (`host[:port]/r/…`);
+ * only localhost ws:// links keep their full URL so parsing cannot
+ * mis-infer wss.
+ *
+ * The room secret is dot-joined (`<roomId>.<key>`) rather than `#`-joined:
+ * RFC 3986 forbids a raw `#` inside a fragment, so strict URL stacks (macOS
+ * Foundation behind terminal click-to-open) percent-encode a second `#` to
+ * `%23` and break the link. Parsers still accept the legacy `#` form and the
+ * mangled `%23` form.
+ *
+ * Full links append the write token to the key
+ * (`base64url(key ∥ writeToken)`); read-only (view) links carry the bare
+ * 32-byte key, which is also the pre-token link format.
+ */
+export declare function formatCollabLink(relayUrl: string, roomId: string, key: Uint8Array, writeToken?: Uint8Array): string;
+/**
+ * Render the browser deep link. The browser UI may be hosted separately from
+ * the relay; the fragment always carries the relay-specific collab link, so
+ * room secrets stay out of HTTP path and query bytes.
+ */
+export declare function formatCollabWebLink(relayUrl: string, roomId: string, key: Uint8Array, writeToken?: Uint8Array, webUrl?: string): string;
+export declare function parseCollabLink(link: string): ParsedCollabLink | {
+    error: string;
+};

package/dist/types/collab/relay-client.d.ts

@@ -0,0 +1,22 @@
+import type { CollabFrame, RelayControlMessage } from "./protocol";
+export interface CollabSocketOptions {
+    /** wss://host[:port]/r/<roomId> — no query string. */
+    wsUrl: string;
+    role: "host" | "guest";
+    key: CryptoKey;
+}
+export declare class CollabSocket {
+    #private;
+    /** Fires after every successful (re)connect. */
+    onOpen?: () => void;
+    onFrame?: (frame: CollabFrame, fromPeer: number) => void;
+    onControl?: (msg: RelayControlMessage) => void;
+    /** Fires once per terminal close (intentional, fatal code, or bad key). willReconnect=true for transient drops that will retry. */
+    onClose?: (reason: string, willReconnect: boolean) => void;
+    constructor(opts: CollabSocketOptions);
+    get isOpen(): boolean;
+    connect(): void;
+    send(frame: CollabFrame, targetPeer?: number): void;
+    /** Intentional close: clears any retry timer, suppresses reconnect. A later connect() starts fresh. */
+    close(): void;
+}

package/dist/types/collab/replication-shrink.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Hard-cap helper for host→guest collab frames.
+ *
+ * The host wraps every {@link CollabFrame} in an AES-GCM envelope and ships it
+ * through the relay's WebSocket. WebSocket servers enforce a per-frame
+ * `maxPayloadLength` (Bun's default is 16 MB; many proxies cap lower). A
+ * single oversized payload — typically a `read`/`bash`/`search` tool result
+ * captured as one multi-megabyte string, or a tool result whose `content`
+ * array holds thousands of small blocks — would otherwise ship as its own
+ * oversized frame and trip that limit, killing the host's WebSocket with
+ * `1006 Received too big message`. `CollabSocket` treats 1006 as transient
+ * and reconnects, the next guest hello triggers the same oversized send, and
+ * the loop never breaks (issue #3739).
+ *
+ * This helper bounds any JSON-serializable payload below
+ * {@link MAX_REPLICATED_PAYLOAD_BYTES}. Already-small payloads pass through
+ * untouched; oversized ones are returned as a deep-cloned shadow where long
+ * strings are head-truncated AND long arrays are head-clipped, with
+ * `[…N chars elided for collab session]` / `[…N items elided for collab
+ * session]` markers. Both axes are needed: string truncation alone leaves
+ * the cap unenforced for a payload built of many short strings, where no
+ * field exceeds the per-string floor.
+ */
+/**
+ * Per-payload ceiling for host→guest frames. Bun's default WebSocket
+ * `maxPayloadLength` is 16 MB; we leave a generous margin so the AES-GCM
+ * envelope (+ IV + tag), the 4-byte peer header, and the outer wire wrapper
+ * fit comfortably under that on every reasonable relay.
+ */
+export declare const MAX_REPLICATED_PAYLOAD_BYTES: number;
+/**
+ * Return `value` unchanged when its JSON serialization already fits
+ * {@link MAX_REPLICATED_PAYLOAD_BYTES}; otherwise return a deep-cloned
+ * shadow shrunk along both string and array axes until the payload fits.
+ * The function is generic over `T` because the wire shape is preserved:
+ * only string leaves and array tails change; discriminator fields, ids, and
+ * other small metadata pass through untouched.
+ */
+export declare function shrinkForReplication<T>(value: T): T;

package/dist/types/commands/acp.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Run Oh My Pi as an ACP (Agent Client Protocol) server over stdio.
+ *
+ * Thin wrapper around the launch flow that forces `mode: "acp"` unless the
+ * ACP terminal-auth flag asks the same command to open the interactive TUI.
+ */
+import { Command } from "jeopi-utils/cli";
+export default class Acp extends Command {
+    static description: string;
+    static strict: boolean;
+    run(): Promise<void>;
+}

package/dist/types/commands/agents.d.ts

@@ -0,0 +1,31 @@
+import { Command } from "jeopi-utils/cli";
+export default class Agents extends Command {
+    static description: string;
+    static args: {
+        action: import("jeopi-utils/cli").ArgDescriptor & {
+            description: string;
+            required: false;
+            options: "unpack"[];
+        };
+    };
+    static flags: {
+        force: import("jeopi-utils/cli").FlagDescriptor<"boolean"> & {
+            char: string;
+            description: string;
+        };
+        json: import("jeopi-utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        dir: import("jeopi-utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        user: import("jeopi-utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        project: import("jeopi-utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+    };
+    static examples: string[];
+    run(): Promise<void>;
+}