@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/cloud/types.d.ts

@@ -1,73 +1,15 @@
-/**
- * Cloud dispatch type definitions.
- *
- * Defines the provider-agnostic interface that all cloud backends (Rush, Codex,
- * Factory) implement, plus the shared task and event types that flow through
- * the dispatch pipeline.
- */
 import type { JobTrigger } from '../scheduling/routines.js';
-/**
- * Identifier for a supported cloud dispatch backend.
- *
- * Each id is one agent's *own* cloud — plus your own machines:
- *   - `rush`        — Rush Cloud (runs Claude against a GitHub repo → PR)
- *   - `codex`       — OpenAI Codex Cloud (`codex cloud exec`)
- *   - `factory`     — Factory Droid Computers (`droid computer ssh` + remote `droid exec`)
- *   - `antigravity` — Google Gemini Managed Agents (Interactions API)
- *   - `cursor`      — Cursor Cloud Agents REST API
- *   - `host`        — a machine you own (`agents devices`), over SSH
- *
- * Agents route to their native cloud automatically (see `cloudProvider` in the
- * agent registry); `--provider` overrides. Nothing auto-routes to `host` — it
- * is always an explicit `--provider host` (or `--device <name>`) choice.
- */
 export type CloudProviderId = 'rush' | 'codex' | 'factory' | 'antigravity' | 'cursor' | 'host';
-/**
- * Lifecycle state of a cloud-dispatched task.
- *
- * `idle` represents a long-lived session that has stopped between turns and
- * can be resumed via `message()`. Distinct from the terminal `completed |
- * failed | cancelled` states, which cannot transition back to `running`.
- */
 export type CloudTaskStatus = 'queued' | 'allocating' | 'running' | 'idle' | 'input_required' | 'completed' | 'failed' | 'cancelled';
-/** Cloud backends whose wire status is normalized by `normalizeProviderStatus`. */
 type StatusNormalizingProvider = 'rush' | 'codex' | 'antigravity' | 'cursor';
-/**
- * Normalize a provider's raw wire status into the canonical `CloudTaskStatus`.
- *
- * Each cloud backend speaks its own status vocabulary and had its own copy of
- * this mapping, which had drifted. This dispatches per provider while keeping
- * provider-specific defaults explicit:
- *   - `rush`        — switch over the Factory Floor's known strings; includes
- *                     `allocating` and stopped/resumable `idle` states, has no
- *                     `queued`, default `running`.
- *   - `codex`       — substring match on the lowercased CLI status; default
- *                     `running`.
- *   - `antigravity` — substring match on the (possibly `undefined`) Interactions
- *                     API status; default `completed` (its synchronous response
- *                     is terminal), and `undefined`-safe.
- *
- * Factory's `mapResultStatus` is structurally different (it maps a droid *exit*
- * result, not a lifecycle string) and deliberately stays in `factory.ts`.
- */
 export declare function normalizeProviderStatus(provider: StatusNormalizingProvider, wireStatus: string | undefined): CloudTaskStatus;
-/** Snapshot of a dispatched task, stored locally and refreshed from the provider. */
 export interface CloudTask {
     id: string;
     provider: CloudProviderId;
     status: CloudTaskStatus;
     agent?: string;
     prompt: string;
-    /**
-     * First (or only) repo the task targets. Kept for back-compat with callers
-     * that treat one task as one repo. For multi-repo dispatches, see `repos`.
-     */
     repo?: string;
-    /**
-     * All repos the task targets, in dispatch order. Populated for multi-repo
-     * dispatches (Rush Cloud, and any provider that supports it). `repo`
-     * mirrors `repos[0]` when both are set.
-     */
     repos?: string[];
     branch?: string;
     prUrl?: string;
@@ -75,15 +17,6 @@ export interface CloudTask {
     updatedAt: string;
     summary?: string;
 }
-/**
- * Single event emitted by a running cloud task.
- *
- * Discriminated union mirroring the local `SessionEvent` taxonomy so cloud
- * streams can be rendered with the same UI primitives as local sessions. The
- * `unknown` variant catches event names the provider emits that the client
- * doesn't recognize — surfacing them rather than silently dropping is the
- * point.
- */
 export type CloudEvent = {
     type: 'text';
     content: string;
@@ -128,77 +61,31 @@ export type CloudEvent = {
     data: string;
     timestamp?: string;
 };
-/** Reference to a skill that should ride along with a cloud dispatch. */
 export interface SkillRef {
     id: string;
     version?: string;
 }
-/** A vision attachment carried along with a prompt (base64-encoded image bytes). */
 export interface ImageAttachment {
     data: string;
     mimeType: 'image/png' | 'image/jpeg' | 'image/webp';
 }
-/** Maximum images allowed per dispatch (matches Cursor Background Agents). */
 export declare const MAX_IMAGES_PER_DISPATCH = 5;
-/** Parameters for dispatching a new cloud task. */
 export interface DispatchOptions {
     prompt: string;
     agent?: string;
-    /**
-     * Event/webhook trigger to register with this dispatch. Set by
-     * `agents cloud run --on <event>`: instead of dispatching immediately, the
-     * dispatch is persisted as a trigger-bound routine so the local webhook
-     * receiver can fire it when the event arrives. Remote firing of the trigger
-     * is a follow-up; today the flag parses, validates, and persists.
-     */
     trigger?: JobTrigger;
-    /**
-     * Legacy single-repo target. Still honored: if `repos` is empty, this
-     * becomes the only repo. Providers that support multi-repo treat
-     * `repos = [repo]` and `repo` as equivalent.
-     */
     repo?: string;
-    /**
-     * One or more repos the dispatch targets. Repeatable on the CLI via
-     * `--repo`. Providers handle multi-repo differently:
-     *   - Rush Cloud clones each into /workspace/<owner>/<name>/
-     *   - Codex Cloud rejects (multi-repo requires an env that bundles them)
-     *   - Factory (local) clones each into the workspace before dispatch
-     */
     repos?: string[];
     branch?: string;
     timeout?: string;
     model?: string;
-    /**
-     * Skills to ship with the dispatch. Providers that support skills mount
-     * them in the pod's skills directory before the agent runs. Providers
-     * without skill support reject via `capabilities().skills === false`.
-     */
     skills?: SkillRef[];
-    /**
-     * Image attachments for vision-enabled dispatch (e.g., "fix this UI bug,
-     * here's the screenshot"). Capped at MAX_IMAGES_PER_DISPATCH.
-     */
     images?: ImageAttachment[];
-    /** Provider-specific options (e.g., codex env ID, factory computer name). */
     providerOptions?: Record<string, unknown>;
-    /** Runtime env vars to inject into the remote agent process when the provider supports it. */
     env?: Record<string, string>;
 }
-/**
- * Collapse `repo` + `repos` into a single deduped list. Exported so callers,
- * tests, and every provider share the same resolution — one source of truth
- * for "which repos does this dispatch target?".
- */
 export declare function resolveDispatchRepos(options: DispatchOptions): string[];
-/**
- * What a provider can actually do. Replaces the single-bool `supports()` so
- * callers can ask "does this provider support cancel?" without trying and
- * catching. The CLI gates feature-specific calls on these flags and surfaces
- * a typed error instead of letting throws bubble.
- */
 export interface ProviderCapabilities {
-    /** Configured + reachable (auth present, binary installed, etc.). */
     available: boolean;
     dispatch: boolean;
     status: boolean;
@@ -210,105 +97,50 @@ export interface ProviderCapabilities {
     skills: boolean;
     images: boolean;
 }
-/**
- * A pre-provisioned dispatch target a provider runs *inside* — a Codex
- * environment (`env_…`) or a Factory Droid Computer (a name). Surfaced by
- * `agents cloud envs` and the missing-target picker so users don't have to
- * copy opaque IDs out of a web UI.
- */
 export interface CloudTarget {
-    /** The value passed to dispatch (env id / computer name). */
     id: string;
-    /** Human label — repo, description, or status. */
     label?: string;
     kind: TargetKind;
 }
-/** Which dispatch option a provider's pre-provisioned target maps to. */
 export type TargetKind = 'env' | 'computer' | 'host';
-/**
- * Thrown by a provider's `dispatch()` when it needs a pre-provisioned target
- * (Codex env / Factory computer) and none was supplied. The CLI catches this
- * to offer a picker (`listTargets`) or actionable guidance, instead of a raw
- * error. `kind` names the missing flag; `guidance` is shown when the target
- * can't be enumerated.
- */
 export declare class MissingTargetError extends Error {
     kind: TargetKind;
     guidance?: string | undefined;
     constructor(kind: TargetKind, message: string, guidance?: string | undefined);
 }
-/**
- * Contract that every cloud backend must implement.
- *
- * Each provider translates between the unified dispatch interface and its
- * backend-specific API (Rush Factory Floor, Codex Cloud CLI, Droid daemon).
- *
- * `message()` may transition a task from `idle` back to `running`.
- */
 export interface CloudProvider {
     id: CloudProviderId;
     name: string;
-    /** Static capability map for this provider. Read before calling feature methods. */
     capabilities(): ProviderCapabilities;
     dispatch(options: DispatchOptions): Promise<CloudTask>;
     status(taskId: string): Promise<CloudTask>;
     list(filter?: {
         status?: CloudTaskStatus;
     }): Promise<CloudTask[]>;
-    /** Stream live output. Yields events until task completes or caller breaks. */
     stream(taskId: string): AsyncIterable<CloudEvent>;
     cancel(taskId: string): Promise<void>;
-    /** Send a follow-up message to a finished/idle/needs_review task. */
     message(taskId: string, content: string): Promise<void>;
-    /**
-     * The pre-provisioned target this provider runs inside, if any. Set for
-     * Codex (`env`) and Factory (`computer`); undefined for Rush (per-repo) and
-     * Antigravity (on-demand sandbox).
-     */
     targetKind?: TargetKind;
-    /**
-     * Enumerate selectable targets for `agents cloud envs` and the picker.
-     * Present only when the backend can list non-interactively (Factory via
-     * `droid computer list`). Codex has no such CLI — it omits this, and callers
-     * fall back to `MissingTargetError.guidance`. May throw (e.g. not signed in);
-     * callers surface that verbatim.
-     */
     listTargets?(): Promise<CloudTarget[]>;
 }
-/** Autonomy level passed to `droid exec --auto` for Factory cloud dispatches. */
 export type DroidAutonomy = 'low' | 'medium' | 'high';
-/** Per-provider configuration stored in the `cloud.providers` section of agents.yaml. */
 export interface CloudProviderConfig {
     rush?: Record<string, string>;
     codex?: {
         env?: string;
     };
-    /**
-     * Factory (Droid) cloud. `computer` is the pre-provisioned Droid Computer
-     * name (managed in Factory's UI, or BYOM via `droid computer register`) —
-     * the Factory analogue of Codex's pre-built `env`. `autonomy` is the default
-     * `droid exec --auto` level for cloud runs (defaults to `high`).
-     */
     factory?: {
         computer?: string;
         autonomy?: DroidAutonomy;
     };
-    /**
-     * Antigravity (Gemini Managed Agents) cloud. The Gemini API key is read from
-     * an `agents secrets` bundle named here (never stored in agents.yaml); if
-     * unset, the provider falls back to GEMINI_API_KEY / GOOGLE_API_KEY in the
-     * environment. `model` overrides the default managed-agent id.
-     */
     antigravity?: {
         secretsBundle?: string;
         model?: string;
     };
-    /** Cursor Cloud Agents API. The API key remains in the named secrets bundle. */
     cursor?: {
         secretsBundle?: string;
     };
 }
-/** Top-level `cloud` section of agents.yaml. */
 export interface CloudConfig {
     default_provider?: CloudProviderId;
     providers?: CloudProviderConfig;

package/dist/lib/cloud/types.js

@@ -1,28 +1,3 @@
-/**
- * Cloud dispatch type definitions.
- *
- * Defines the provider-agnostic interface that all cloud backends (Rush, Codex,
- * Factory) implement, plus the shared task and event types that flow through
- * the dispatch pipeline.
- */
-/**
- * Normalize a provider's raw wire status into the canonical `CloudTaskStatus`.
- *
- * Each cloud backend speaks its own status vocabulary and had its own copy of
- * this mapping, which had drifted. This dispatches per provider while keeping
- * provider-specific defaults explicit:
- *   - `rush`        — switch over the Factory Floor's known strings; includes
- *                     `allocating` and stopped/resumable `idle` states, has no
- *                     `queued`, default `running`.
- *   - `codex`       — substring match on the lowercased CLI status; default
- *                     `running`.
- *   - `antigravity` — substring match on the (possibly `undefined`) Interactions
- *                     API status; default `completed` (its synchronous response
- *                     is terminal), and `undefined`-safe.
- *
- * Factory's `mapResultStatus` is structurally different (it maps a droid *exit*
- * result, not a lifecycle string) and deliberately stays in `factory.ts`.
- */
 export function normalizeProviderStatus(provider, wireStatus) {
     switch (provider) {
         case 'rush':
@@ -35,7 +10,6 @@ export function normalizeProviderStatus(provider, wireStatus) {
             return normalizeCursorStatus(wireStatus ?? '');
     }
 }
-/** Cursor Cloud run status → canonical enum. Unknown non-terminal states remain running. */
 function normalizeCursorStatus(s) {
     switch (s.toUpperCase()) {
         case 'CREATING': return 'queued';
@@ -47,7 +21,6 @@ function normalizeCursorStatus(s) {
         default: return 'running';
     }
 }
-/** Rush Factory Floor status → canonical enum. Default `running`; no `queued`. */
 function normalizeRushStatus(s) {
     switch (s) {
         case 'allocating': return 'allocating';
@@ -62,7 +35,6 @@ function normalizeRushStatus(s) {
         default: return 'running';
     }
 }
-/** Codex Cloud CLI status → canonical enum. Substring match; default `running`. */
 function normalizeCodexStatus(s) {
     const lower = s.toLowerCase();
     if (lower.includes('queued') || lower.includes('pending'))
@@ -79,11 +51,6 @@ function normalizeCodexStatus(s) {
         return 'cancelled';
     return 'running';
 }
-/**
- * Antigravity Interactions API status → canonical enum. Substring match,
- * `undefined`-safe; default `completed` because the synchronous response is
- * already terminal.
- */
 function normalizeAntigravityStatus(s) {
     const lower = (s ?? '').toLowerCase();
     if (lower.includes('queue') || lower.includes('pending'))
@@ -100,13 +67,7 @@ function normalizeAntigravityStatus(s) {
         return 'cancelled';
     return 'completed';
 }
-/** Maximum images allowed per dispatch (matches Cursor Background Agents). */
 export const MAX_IMAGES_PER_DISPATCH = 5;
-/**
- * Collapse `repo` + `repos` into a single deduped list. Exported so callers,
- * tests, and every provider share the same resolution — one source of truth
- * for "which repos does this dispatch target?".
- */
 export function resolveDispatchRepos(options) {
     const out = [];
     const seen = new Set();
@@ -127,13 +88,6 @@ export function resolveDispatchRepos(options) {
     }
     return out;
 }
-/**
- * Thrown by a provider's `dispatch()` when it needs a pre-provisioned target
- * (Codex env / Factory computer) and none was supplied. The CLI catches this
- * to offer a picker (`listTargets`) or actionable guidance, instead of a raw
- * error. `kind` names the missing flag; `guidance` is shown when the target
- * can't be enumerated.
- */
 export class MissingTargetError extends Error {
     kind;
     guidance;

package/dist/lib/cloudflare/creds.d.ts

@@ -1,6 +1,4 @@
 export declare const DEFAULT_CF_BUNDLE = "cloudflare";
-/** Cloudflare API credentials for provisioning, read from `cloudflare` (or a
- * user-named bundle). Fuzzy-matches key names so it works across bundle layouts. */
 export declare function readCloudflareCreds(bundle?: string, override?: {
     apiToken?: string;
     accountId?: string;

package/dist/lib/cloudflare/creds.js

@@ -1,22 +1,9 @@
-// Cloudflare API credential glue, shared by the commands that provision or read
-// Cloudflare-backed endpoints (`agents traces`, `agents sessions backup`).
-//
-// This used to live in `lib/share/config.ts` alongside the embedded artifact
-// share engine. The share engine moved out to `@phnx-labs/artifacts-cli`
-// (PHNX-3992); `readCloudflareCreds` stayed because it is a generic Cloudflare
-// util that `traces`/`sessions backup` borrow, unrelated to sharing.
 import { bundleExistsSync as bundleExists, readAndResolveBundleEnvSync as readAndResolveBundleEnv, } from '../secrets-client.js';
 export const DEFAULT_CF_BUNDLE = 'cloudflare';
-/** Cloudflare API credentials for provisioning, read from `cloudflare` (or a
- * user-named bundle). Fuzzy-matches key names so it works across bundle layouts. */
 export function readCloudflareCreds(bundle = DEFAULT_CF_BUNDLE, override) {
-    // Explicit --token/--account bypass the bundle entirely (robust escape hatch).
     if (override?.apiToken) {
         return { apiToken: override.apiToken, accountId: override.accountId ?? '' };
     }
-    // Check existence first: resolving a missing bundle through the process client
-    // surfaces an opaque transport code (e.g. LOCKED), never naming the bundle the
-    // user typed — so name it here.
     if (!bundleExists(bundle)) {
         throw new Error(`The '${bundle}' bundle does not exist. ` +
             `Pass credentials directly with --token <t> [--account <id>], or create it: ` +
@@ -24,7 +11,6 @@ export function readCloudflareCreds(bundle = DEFAULT_CF_BUNDLE, override) {
     }
     const { env } = readAndResolveBundleEnv(bundle, {
         caller: 'cloudflare',
-        // Setup is still a read; only `agents secrets unlock` may authenticate.
         agentOnly: true,
     });
     const find = (re) => {

package/dist/lib/cloudflare/provision.d.ts

@@ -1,10 +1,8 @@
-/** One compiled non-JS Worker module (e.g. WASM) uploaded alongside the script. */
 export interface WorkerModule {
     name: string;
     contentType: string;
     contents: Uint8Array<ArrayBuffer>;
 }
-/** A Worker script plus any extra modules to upload with it. */
 export interface WorkerBundle {
     script: string;
     modules: WorkerModule[];
@@ -20,16 +18,10 @@ export type CloudflareRequester = <T = unknown>(request: CloudflareRequest) => P
 interface ProvisionOptions {
     request?: CloudflareRequester;
 }
-/** Create the R2 bucket (idempotent). */
 export declare function createBucket(apiToken: string, accountId: string, name: string, opts?: ProvisionOptions): Promise<void>;
-/** Upload the module Worker with an R2 binding (`BUCKET`). Secrets are set via the Workers Secrets API. */
 export declare function deployWorker(apiToken: string, accountId: string, workerName: string, worker: string | WorkerBundle, bucketName: string, opts?: ProvisionOptions): Promise<void>;
-/** Add/update a secret_text binding using Cloudflare's Workers Secrets API. */
 export declare function putWorkerSecret(apiToken: string, accountId: string, workerName: string, name: string, text: string, opts?: ProvisionOptions): Promise<void>;
-/** Enable the free `*.workers.dev` route for the script, and return the account subdomain. */
 export declare function enableWorkersDev(apiToken: string, accountId: string, workerName: string, opts?: ProvisionOptions): Promise<string>;
-/** Resolve a zone id for a domain the token can see, or null if not owned/visible. */
 export declare function findZoneId(apiToken: string, domain: string, opts?: ProvisionOptions): Promise<string | null>;
-/** Map a custom hostname (e.g. `share.getrush.ai`) to the Worker via Workers Custom Domains. */
 export declare function addCustomDomain(apiToken: string, accountId: string, workerName: string, zoneId: string, hostname: string, opts?: ProvisionOptions): Promise<void>;
 export {};

package/dist/lib/cloudflare/provision.js

@@ -1,19 +1,9 @@
-// Generic Cloudflare orchestration — plain `fetch` against the CF REST API (the
-// repo has no CF wrapper). Create an R2 bucket, upload a module Worker with an R2
-// binding, set secrets via the Workers Secrets API, enable the free
-// `*.workers.dev` subdomain, and map a custom domain when the token owns the zone.
-//
-// This was `lib/share/provision.ts`. The artifact share engine moved out to
-// `@phnx-labs/artifacts-cli` (PHNX-3992), but `agents traces` provisions its own
-// isolated Cloudflare-backed store with the SAME primitives — so the generic
-// layer relocated here (share-specific lifecycle/collab/managed helpers left
-// with the share engine). `traces/provision.ts` is now the only consumer.
 const CF_API = 'https://api.cloudflare.com/client/v4';
 async function cf(apiToken, method, pathname, body, form) {
     const headers = { authorization: `Bearer ${apiToken}` };
     let payload;
     if (form) {
-        payload = form; // fetch sets multipart boundary
+        payload = form;
     }
     else if (body !== undefined) {
         headers['content-type'] = 'application/json';
@@ -29,11 +19,9 @@ async function cf(apiToken, method, pathname, body, form) {
     return json.result;
 }
 const defaultCloudflareRequester = (request) => cf(request.apiToken, request.method, request.pathname, request.body, request.form);
-/** True if the CF error looks like "the thing already exists" (idempotent create). */
 function isAlreadyExists(e) {
     return /already exists|duplicate|10004|10014/i.test(String(e));
 }
-/** Create the R2 bucket (idempotent). */
 export async function createBucket(apiToken, accountId, name, opts = {}) {
     const request = opts.request ?? defaultCloudflareRequester;
     try {
@@ -49,7 +37,6 @@ export async function createBucket(apiToken, accountId, name, opts = {}) {
             throw e;
     }
 }
-/** Upload the module Worker with an R2 binding (`BUCKET`). Secrets are set via the Workers Secrets API. */
 export async function deployWorker(apiToken, accountId, workerName, worker, bucketName, opts = {}) {
     const request = opts.request ?? defaultCloudflareRequester;
     const metadata = {
@@ -73,7 +60,6 @@ export async function deployWorker(apiToken, accountId, workerName, worker, buck
         form,
     });
 }
-/** Add/update a secret_text binding using Cloudflare's Workers Secrets API. */
 export async function putWorkerSecret(apiToken, accountId, workerName, name, text, opts = {}) {
     const request = opts.request ?? defaultCloudflareRequester;
     await request({
@@ -83,7 +69,6 @@ export async function putWorkerSecret(apiToken, accountId, workerName, name, tex
         body: { name, text, type: 'secret_text' },
     });
 }
-/** Enable the free `*.workers.dev` route for the script, and return the account subdomain. */
 export async function enableWorkersDev(apiToken, accountId, workerName, opts = {}) {
     const request = opts.request ?? defaultCloudflareRequester;
     await request({
@@ -105,10 +90,8 @@ export async function enableWorkersDev(apiToken, accountId, workerName, opts = {
     }
     return sub.subdomain;
 }
-/** Resolve a zone id for a domain the token can see, or null if not owned/visible. */
 export async function findZoneId(apiToken, domain, opts = {}) {
     const request = opts.request ?? defaultCloudflareRequester;
-    // Try the exact name, then the registrable parent (share.getrush.ai -> getrush.ai).
     const candidates = [domain, domain.split('.').slice(-2).join('.')];
     for (const name of candidates) {
         const zones = await request({
@@ -121,7 +104,6 @@ export async function findZoneId(apiToken, domain, opts = {}) {
     }
     return null;
 }
-/** Map a custom hostname (e.g. `share.getrush.ai`) to the Worker via Workers Custom Domains. */
 export async function addCustomDomain(apiToken, accountId, workerName, zoneId, hostname, opts = {}) {
     const request = opts.request ?? defaultCloudflareRequester;
     try {

package/dist/lib/codex-home.d.ts

@@ -1,67 +1,7 @@
-/** macOS Unix-domain socket path cap: `sizeof(sockaddr_un.sun_path)` in <sys/un.h>. */
 export declare const SUN_LEN = 104;
-/** Suffix codex appends to CODEX_HOME to reach its app-server control socket. */
 export declare const CODEX_CONTROL_SOCKET_SUFFIX = "/app-server-control/app-server-control.sock";
-/**
- * True when this CODEX_HOME's derived control-socket path would overflow
- * SUN_LEN on macOS.
- */
 export declare function codexHomeOverflowsSunLen(home: string): boolean;
-/**
- * The short codex home used when an origin home overflows.
- * `~/.agents/.codex-homes/<key>/.codex` keeps the socket path well under
- * SUN_LEN while staying stable across reboots (unlike $TMPDIR) and isolated
- * per origin.
- */
 export declare function shortCodexHome(agentsUserDir: string, key: string): string;
-/**
- * The short-home key for a codex config home: the version for a version home,
- * `a-<accountId prefix>` for an account slot under `<historyDir>/accounts/codex/`.
- * Twelve hex characters keep the socket path under SUN_LEN for any home dir
- * (`~/.agents/.codex-homes/a-XXXXXXXXXXXX/.codex` + suffix = 99 bytes on a
- * `/Users/<user>` prefix); the origin-link check in {@link resolveCodexHome}
- * is what rules out two accounts sharing a prefix.
- */
 export declare function codexShortKey(home: string, version: string, historyDir: string): string;
-/**
- * Resolve a macOS SUN_LEN-safe CODEX_HOME for the given origin home, migrating
- * the home to a short real path (once, idempotently) when needed. `key` is the
- * short-home key from {@link codexShortKey} — it uniquely identifies the origin
- * (the version for a version home, `a-<accountId>` for a slot), so
- * `.codex-homes/<key>` can only ever be THIS origin's own short home. Two
- * different origins never map to one key, which is what makes every branch
- * below safe without guessing whose login a short home holds.
- *
- * On non-darwin platforms, or when the origin already fits, the origin is
- * returned unchanged. Otherwise the short home is authoritative for `key`, and
- * the origin is made a symlink onto it:
- *  - already linked onto it → return it (healthy, the common path).
- *  - linked onto a DIFFERENT target (a pre-fix layout where a slot's `.codex`
- *    was captured into a foreign version short home) → REPOINT to this key's own
- *    short home and warn; the foreign login is never run. The account may need a
- *    re-login, which is correct — its login was never isolated.
- *  - a real directory with the short home ALREADY present → a version/account
- *    reinstall recreated a fresh `.codex`; adopt the short home (which holds the
- *    real login), backing the fresh dir aside so freshly-synced resources are
- *    not lost. This is the case the earlier refuse-and-throw broke
- *    (`agents remove codex@x && agents add codex@x` then `agents run`).
- *  - a real directory with no short home yet → first migration: rename it into
- *    the short home and leave a symlink.
- *  - absent → create/adopt the short home and link the origin to it.
- * If any filesystem step fails the origin is returned (no worse than the pre-fix
- * behavior).
- */
 export declare function resolveCodexHome(originHome: string, agentsUserDir: string, key: string, platform?: NodeJS.Platform): string;
-/**
- * Emit the bash block that a generated codex shim uses to export a
- * SUN_LEN-safe CODEX_HOME. Mirrors {@link resolveCodexHome} for the one origin
- * a shim ever sees, the version home: an account-slot launch reaches the shim
- * with CODEX_HOME already pinned by `buildExecEnv`, and the block below keeps a
- * caller-provided CODEX_HOME, so the slot key never has to be derived in bash.
- *
- * @param homeExpr      shell expression for the versioned codex home
- *                      (e.g. `$VERSION_DIR/home/.codex`)
- * @param shortBaseExpr shell expression for the per-version short base dir
- *                      (e.g. `$AGENTS_USER_DIR/.codex-homes/$VERSION`)
- */
 export declare function codexHomeShimBash(homeExpr: string, shortBaseExpr: string): string;