The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
import { writeLoginCleanup } from "./login-cleanup-notifications.js";
import { DELIVERY_QUEUES } from "./delivery-work-notifications.js";
import { randomUUID } from "node:crypto";
import { and, eq, inArray, isNotNull, isNull, lte, ne, or, sql } from "drizzle-orm";
import type { Db } from "@paperclipai/db";
import { adapterAuthSessions } from "@paperclipai/db";
import type {
AdapterAuthSessionFailure,
AdapterAuthSessionInternalStatus,
AdapterAuthSessionOwnerResponse,
AdapterAuthSessionResponse,
AdapterAuthSessionStatus,
AgentAdapterType,
Environment,
EnvironmentLease,
} from "@paperclipai/shared";
import { toPublicAdapterAuthSessionStatus } from "@paperclipai/shared";
import {
CODEX_DEVICE_LOGIN_COMMAND as DEFAULT_CODEX_LOGIN_COMMAND,
parseDeviceLoginPrompt,
runDeviceLogin,
type DeviceLoginOutcome as RunnerDeviceLoginOutcome,
type DeviceLoginPrompt,
type SandboxLoginDriver,
} from "@paperclipai/adapter-codex-local/server";
import {
GROK_DEVICE_LOGIN_COMMAND as DEFAULT_GROK_LOGIN_COMMAND,
parseGrokDeviceLoginPrompt,
} from "@paperclipai/adapter-grok-local/server";
import type { AdapterLoginPrompt } from "@paperclipai/adapter-utils";
import {
createLoginPtyTransport,
type LoginPtySessionOpener,
} from "@paperclipai/adapter-utils/login-pty-transport";
import type { EnvironmentRuntimeService } from "./environment-runtime.js";
import { buildLoginLeaseAcquireArgs } from "./adapter-login-lease.js";
import { environmentService } from "./environments.js";
import { runDescriptorBoundAuthRead } from "./device-login-credential-read.js";
import {
resolveLoginCommandKey,
validateLoginSessionHome,
type LoginCommandKey,
} from "./login-command.js";
import type { LoginPtyWorkerManagerLike } from "./setup-token-transport-binding.js";
// The login-session service. It creates a login session, acquires a fresh
// sandbox lease, runs `codex login --device-auth` through the runner, and owns
// the sandbox delete. The service holds the company credential slot through the
// whole flow, so a second start for the same company and adapter cannot run at
// the same time.
//
// Security: the service records no secret data. An activity record carries no
// URL, no code, no credential, no account identifier, and no lease identifier.
// The service keeps the one-time login prompt in memory and returns it only
// through the owner read path.
/** The host timeout for the sandbox login command. It is exactly five minutes. */
export const DEVICE_LOGIN_TIMEOUT_MS = 300_000;
// The fixed error for a sandbox provider that does not advertise the login
// pseudo-terminal capability. The Codex device login runs the login command on a
// real pseudo-terminal, so only a provider that advertises the capability can
// host the login. The route returns this specific, typed error and starts no
// session, so an unsupported provider never reaches a session row, a lease, or a
// pseudo-terminal.
export const DEVICE_LOGIN_PROVIDER_UNSUPPORTED =
"The sandbox provider does not support the Codex device login.";
export const DEVICE_LOGIN_PROVIDER_UNSUPPORTED_CODE =
"codex_device_login_provider_unsupported";
/**
* The lease-metadata key that tags a login sandbox lease with its session
* identifier. The runtime stamps it at acquisition. The reaper reads it to find
* an orphan lease that no live session references. It is not a public field.
*/
export const LOGIN_LEASE_SESSION_TAG_KEY = "adapterLoginSessionId";
/**
* The closed set of displayed-code adapter types. The shared
* `adapter_auth_sessions` table also holds a Claude setup-token row. That row
* uses a different login panel mode. So every store read and every reaper scan
* filters to this set, instead of trusting the raw row's own value. No route
* makes a row of an adapter type outside `codex_local` reachable yet. A later
* phase widens the set of reachable adapters, with no change to this filter.
*/
export const DISPLAYED_CODE_ADAPTER_TYPES: readonly AgentAdapterType[] = [
"codex_local",
"grok_local",
];
/**
* The provider delete result the service observes on a terminal path. The
* service treats both values as a confirmed delete. `not_found` is an idempotent
* confirmation: the sandbox is already gone. A rejected delete (a thrown error)
* is not a confirmed delete; the service records `cleanup_pending`.
*/
export type SandboxDeleteOutcome = "deleted" | "not_found";
export interface SandboxDeleteResult {
outcome: SandboxDeleteOutcome;
}
/**
* The sandbox lease for one login session. The runtime acquires it fresh with
* reuse disabled and archive-on-release disabled, and tags the provider lease
* with the session identifier. The service owns the delete seam and the release
* seam; the runner never deletes the sandbox.
*/
export interface LoginSessionLease {
/**
* The provider lease identifier. The reaper resolves an unlinked sandbox
* through it. The service persists it on the row, but it never puts it in an
* activity record.
*/
readonly providerLeaseId: string;
/** The driver that runs the login command and reads the credential. */
readonly driver: SandboxLoginDriver;
/** The fixed, session-specific sandbox path of the credential file. */
readonly authPath: string;
/**
* Delete the provider sandbox. The service owns this call. It awaits the
* provider and returns the provider result. A rejection means the delete
* failed, so the service records `cleanup_pending`.
*/
deleteSandbox(): Promise<SandboxDeleteResult>;
/**
* Release the environment lease at once. The service calls this when a session
* transition fails after acquisition, so no unlinked sandbox survives.
*/
release(): Promise<void>;
}
export interface AcquireLoginLeaseInput {
companyId: string;
environmentId: string;
adapterType: AgentAdapterType;
sessionId: string;
startedByUserId: string;
}
/** The sandbox side of a login session. A production runtime binds it to the
* environment runtime; a test binds it to a fake. */
export interface LoginSessionRuntime {
acquireLoginLease(input: AcquireLoginLeaseInput): Promise<LoginSessionLease>;
}
/** The per-session context the promotion seam needs. The service knows the
* session, the company, the owner, and the adapter, so the promotion resolves
* the company slot and the sole-active-owner check for this exact session. */
export interface CredentialPromotionContext {
sessionId: string;
companyId: string;
startedByUserId: string;
adapterType: AgentAdapterType;
}
/**
* The mandatory promotion of the credential for a successful login. It runs
* inside the internal `promoting` window on the success path. It validates the
* credential, runs an independent readiness check, gates the write, and persists
* the credential to the company credential slot. It must throw on any credential
* that is empty, malformed, an API key, a non-subscription, oversized, unready,
* or not the sole active owner. A throw turns the outcome into a failure, and
* the service writes nothing and still deletes the sandbox.
*/
export interface CredentialPromotion {
promote(authBytes: Buffer, context: CredentialPromotionContext): void | Promise<void>;
/**
* Wraps the service's terminal "authenticated" commit, immediately before
* the service runs it. A promotion that already bound and validated a
* value in `promote` can hold the SAME lock across this call, so a write
* that would invalidate that value cannot land in the gap between the
* earlier validation and this terminal commit. When the wrapper throws,
* the service records a failed login instead of `authenticated` and never
* runs `commit`. A promotion that omits this runs `commit` directly.
*/
runTerminalCommit?<T>(
commit: (resultClaim?: Record<string, unknown>) => Promise<T>,
context: CredentialPromotionContext,
): Promise<T>;
}
/** The redacted lifecycle phases. Each phase carries no secret data. */
export type LoginSessionActivityPhase =
| "session_created"
| "lease_acquired"
| "lease_released"
| "prompt_surfaced"
| "promoting"
| "sandbox_deleted"
| "cleanup_pending"
| "authenticated"
| "failed"
| "timed_out"
| "cancelled";
/**
* One redacted lifecycle record. It carries only non-secret fields: the session,
* the company, the environment, the adapter, and the phase. It never carries a
* URL, a code, a credential byte, an account identifier, or a lease identifier.
*/
export interface LoginSessionActivityEvent {
sessionId: string;
companyId: string;
environmentId: string;
adapterType: AgentAdapterType;
phase: LoginSessionActivityPhase;
}
export type LoginSessionActivityRecorder = (event: LoginSessionActivityEvent) => void;
export interface StartDeviceLoginInput {
aiConnection?: import("@paperclipai/shared").AiConnectionLoginIntent;
companyId: string;
environmentId: string;
adapterType: AgentAdapterType;
/** The immutable owner principal. The service returns the prompt only to it. */
startedByUserId: string;
/**
* The session time-to-live in seconds. It sets the expiring session intent at
* creation. It defaults so the expiry matches the five-minute host timeout.
*/
ttlSeconds?: number;
/** An optional cancellation signal that aborts the login run. */
signal?: AbortSignal;
}
export interface DeviceLoginOutcome {
sessionId: string;
/** The resolved public terminal status. */
status: AdapterAuthSessionStatus;
/**
* True when the provider delete failed and the row holds the durable internal
* `cleanup_pending` state.
*/
cleanupPending: boolean;
/** True when the service observed a provider delete on this terminal path. */
sandboxDeleteObserved: boolean;
}
export interface StartDeviceLoginResult {
/** The initial public response after the insert and the acquisition. */
session: AdapterAuthSessionResponse;
/**
* Resolves when the terminal handling ends. The terminal handling runs the
* readiness check, the promotion write, and the cleanup-state handoff, and
* then it records the terminal status.
*/
completed: Promise<DeviceLoginOutcome>;
}
/** The service throws this when the active company credential slot is taken. */
export class AdapterAuthSessionConflictError extends Error {
readonly statusCode = 409;
constructor(
message = "An adapter login session is already active for this company and adapter.",
) {
super(message);
this.name = "AdapterAuthSessionConflictError";
}
}
// ---------------------------------------------------------------------------
// The durable session store.
// ---------------------------------------------------------------------------
export interface AdapterAuthSessionRow {
aiConnection?: import("@paperclipai/shared").AiConnectionLoginIntent;
id: string;
/** The public, CSPRNG session identifier. The API returns and looks up this
* value. It never equals the internal primary-key `id`, so a caller cannot
* address a row by the internal id. */
publicSessionId: string;
companyId: string;
environmentId: string;
adapterType: AgentAdapterType;
startedByUserId: string;
providerLeaseId: string | null;
status: AdapterAuthSessionInternalStatus;
expiresAt: Date | null;
/** The promotion claim deadline. A future value means the claim is live, so
* the reaper leaves the `promoting` row alone. A null or past value means no
* live claim. */
promotionExpiresAt: Date | null;
finishedAt: Date | null;
failureReason: string | null;
/** The non-secret result claim of a terminal success, written atomically
* with the terminal status. Null for failures and claim-less flows. */
resultClaim: Record<string, unknown> | null;
}
export interface InsertAdapterAuthSessionInput {
aiConnection?: import("@paperclipai/shared").AiConnectionLoginIntent;
id: string;
/** The public, CSPRNG session identifier. The service builds it and returns it
* to the client; the store persists it in `public_session_id`. */
publicSessionId: string;
companyId: string;
environmentId: string;
adapterType: AgentAdapterType;
startedByUserId: string;
expiresAt: Date;
at: Date;
}
export interface SetAdapterAuthSessionStatusInput {
sessionId: string;
status: AdapterAuthSessionInternalStatus;
at: Date;
failureReason?: string | null;
finishedAt?: Date | null;
/**
* Set or clear the promotion claim deadline. `undefined` leaves the column
* unchanged. A `Date` sets a live claim; `null` clears the claim.
*/
promotionExpiresAt?: Date | null;
/**
* The non-secret result claim to record with a terminal-success write.
* `undefined` leaves the column unchanged. Writing it in the SAME
* conditional write as the terminal status means a claim can never exist
* for a session that did not authenticate, and a restart never loses it.
*/
resultClaim?: Record<string, unknown> | null;
}
/**
* The input for a conditional status write. The write updates the row only when
* the current status is one of `expectedStatuses`. The method reports whether it
* changed a row, so the caller can detect a lost race.
*/
export interface CompareAndSetAdapterAuthSessionStatusInput
extends SetAdapterAuthSessionStatusInput {
/** The write succeeds only when the current status is one of these. */
expectedStatuses: readonly AdapterAuthSessionInternalStatus[];
}
/** The store for the login-session rows. The service inserts, transitions, and
* reads through it. The insert maps the active-slot conflict to a `409`. */
export interface AdapterAuthSessionStore {
insert(input: InsertAdapterAuthSessionInput): Promise<void>;
recordLeaseAcquired(input: {
sessionId: string;
providerLeaseId: string;
at: Date;
}): Promise<void>;
setStatus(input: SetAdapterAuthSessionStatusInput): Promise<void>;
/** A conditional status write. It returns true only when it changed one row. */
compareAndSetStatus(input: CompareAndSetAdapterAuthSessionStatusInput): Promise<boolean>;
get(sessionId: string): Promise<AdapterAuthSessionRow | null>;
/**
* Read a session by its public session id, scoped to the company. The
* predicate carries the company id, so a query never keys on the public
* session id alone, and a foreign-company caller reads nothing. It never
* accepts the internal primary-key `id`. `adapterType` scopes the read to one
* requested adapter type. When the caller omits it, the read scopes to every
* displayed-code adapter type.
*/
getByPublicId(
publicSessionId: string,
companyId: string,
adapterType?: AgentAdapterType,
): Promise<AdapterAuthSessionRow | null>;
/**
* Read the active session for one company, owner, and adapter, with no
* session id. The predicate matches the same three columns as the active-slot
* partial unique index, so at most one row can match. It returns null when the
* owner holds no active session for the adapter.
*/
getActiveByOwner(
companyId: string,
startedByUserId: string,
adapterType: AgentAdapterType,
): Promise<AdapterAuthSessionRow | null>;
/** Run `fn` while the process holds the promotion critical-section lock for the
* company, owner, and adapter slot. The reaper reclaims a stale `promoting`
* row inside this lock, so a reclaim never interleaves with a live credential
* write for the same slot. */
withCompanyAdapterPromotionLock<T>(
companyId: string,
startedByUserId: string,
adapterType: AgentAdapterType,
fn: () => Promise<T>,
): Promise<T>;
}
/** Build the advisory-lock key for the promotion critical section. The key is
* scoped to the company, the owner, and the adapter, so two different slots
* never contend. The credential-promotion path and the reaper reclaim both
* derive the key from this function, so they take the exact same lock. */
export function adapterLoginPromotionLockKey(
companyId: string,
startedByUserId: string,
adapterType: AgentAdapterType,
): string {
return `paperclip:adapter-login-promotion:${companyId}:${startedByUserId}:${adapterType}`;
}
/**
* Run `fn` inside the promotion critical section for one company, owner, and
* adapter slot.
*
* The function opens a database transaction and takes a transaction-scoped
* PostgreSQL advisory lock. The lock serializes the credential-promotion path
* against the reaper reclaim, so a reaper never releases the slot while a
* credential write runs, and a stale promotion never writes after the reaper
* reclaims the slot. The transaction holds the lock through `fn`, so the caller
* runs the ownership check and the credential write in one mutually-exclusive
* section. A process crash drops the connection and releases the lock, so a
* stalled owner never blocks recovery.
*/
export async function withAdapterLoginPromotionLock<T>(
db: Db,
companyId: string,
startedByUserId: string,
adapterType: AgentAdapterType,
fn: () => Promise<T>,
): Promise<T> {
const key = adapterLoginPromotionLockKey(companyId, startedByUserId, adapterType);
return db.transaction(async (tx) => {
await tx.execute(sql`select pg_advisory_xact_lock(hashtextextended(${key}, 0))`);
return fn();
});
}
/** The three active statuses. A row in one of these states holds the company
* credential slot, so it is non-terminal and can time out. */
export const ADAPTER_AUTH_ACTIVE_STATUSES: readonly AdapterAuthSessionInternalStatus[] = [
"starting",
"waiting_for_user",
"promoting",
];
/**
* The promotion claim window. The service sets `promotion_expires_at` to this
* far in the future when it moves a row to `promoting`. While the deadline is in
* the future, the reaper leaves the row alone, so the credential write finishes
* without a slot release. The window is far longer than the filesystem writes,
* so a healthy promotion always finishes first. A crashed promotion lets the
* deadline pass, so the reaper reclaims the stalled row on a later sweep.
*/
export const ADAPTER_AUTH_PROMOTION_CLAIM_MS = 60_000;
/**
* The read side the reaper needs. The reaper sweeps three sets: the expired
* non-terminal sessions, the terminal `cleanup_pending` sessions, and the
* provider leases that no live session references. The db-backed store
* implements this next to {@link AdapterAuthSessionStore}.
*/
export interface AdapterAuthReaperStore {
/** The non-terminal sessions with an `expiresAt` at or before `now`. */
listExpiredActiveSessions(now: Date): Promise<AdapterAuthSessionRow[]>;
/** The terminal sessions left in the internal `cleanup_pending` state. */
listCleanupPendingSessions(): Promise<AdapterAuthSessionRow[]>;
/** Every provider lease reference a session row still holds. */
listLeaseReferences(): Promise<string[]>;
setStatus(input: SetAdapterAuthSessionStatusInput): Promise<void>;
/** A conditional status write. It returns true only when it changed one row. */
compareAndSetStatus(input: CompareAndSetAdapterAuthSessionStatusInput): Promise<boolean>;
get(sessionId: string): Promise<AdapterAuthSessionRow | null>;
/** Run `fn` while the process holds the promotion critical-section lock for the
* company, owner, and adapter slot. The reaper reclaims a stale `promoting`
* row inside this lock, so a reclaim never interleaves with a live credential
* write for the same slot. */
withCompanyAdapterPromotionLock<T>(
companyId: string,
startedByUserId: string,
adapterType: AgentAdapterType,
fn: () => Promise<T>,
): Promise<T>;
}
// The Postgres unique-violation code. The database driver sets it on the error,
// and the query builder can wrap that error, so read the code from the error and
// from its cause chain.
const POSTGRES_UNIQUE_VIOLATION_CODE = "23505";
function isUniqueViolation(error: unknown): boolean {
let current: unknown = error;
for (let depth = 0; depth < 5 && current != null; depth += 1) {
if (
typeof current === "object" &&
(current as { code?: unknown }).code === POSTGRES_UNIQUE_VIOLATION_CODE
) {
return true;
}
current = (current as { cause?: unknown }).cause;
}
return false;
}
function toRow(row: typeof adapterAuthSessions.$inferSelect): AdapterAuthSessionRow {
return {
id: row.id,
...(row.aiConnection ? { aiConnection: row.aiConnection } : {}),
publicSessionId: row.publicSessionId,
companyId: row.companyId,
environmentId: row.environmentId,
adapterType: row.adapterType,
startedByUserId: row.startedByUserId,
providerLeaseId: row.providerLeaseId ?? null,
// The unified `status` column type is the merged login-state union. A Codex
// device-login row only ever holds a Codex internal status, so narrow the
// read back to the internal union the service reasons about.
status: row.status as AdapterAuthSessionInternalStatus,
expiresAt: row.expiresAt ?? null,
promotionExpiresAt: row.promotionExpiresAt ?? null,
finishedAt: row.finishedAt ?? null,
failureReason: row.failureReason ?? null,
resultClaim: (row.resultClaim as Record<string, unknown> | null) ?? null,
};
}
/** Build the `update` patch for a status write. An omitted optional field stays
* unchanged; a present field writes its value, including a `null` clear. */
function buildStatusPatch(input: SetAdapterAuthSessionStatusInput) {
return {
status: input.status,
updatedAt: input.at,
...(input.failureReason !== undefined ? { failureReason: input.failureReason } : {}),
...(input.finishedAt !== undefined ? { finishedAt: input.finishedAt } : {}),
...(input.promotionExpiresAt !== undefined
? { promotionExpiresAt: input.promotionExpiresAt }
: {}),
...(input.resultClaim !== undefined ? { resultClaim: input.resultClaim } : {}),
};
}
/** Build the Postgres-backed store. The partial unique index on the active
* statuses serializes the company credential slot; the insert maps its conflict
* to {@link AdapterAuthSessionConflictError}. */
export function createDbAdapterAuthSessionStore(
db: Db,
): AdapterAuthSessionStore & AdapterAuthReaperStore {
return {
async insert(input) {
try {
await writeLoginCleanup(db, DELIVERY_QUEUES.adapterLoginCleanup, tx => tx.insert(adapterAuthSessions).values({
id: input.id,
companyId: input.companyId,
environmentId: input.environmentId,
adapterType: input.adapterType,
startedByUserId: input.startedByUserId,
aiConnection: input.aiConnection,
// The unified table requires a unique public session id. The service
// builds it from a CSPRNG and returns it to the client, so the store
// persists that value here. It never uses the internal id, a timestamp,
// or a counter.
publicSessionId: input.publicSessionId,
status: "starting",
expiresAt: input.expiresAt,
createdAt: input.at,
updatedAt: input.at,
}));
} catch (error) {
if (isUniqueViolation(error)) {
throw new AdapterAuthSessionConflictError();
}
throw error;
}
},
async recordLeaseAcquired(input) {
await writeLoginCleanup(db, DELIVERY_QUEUES.adapterLoginCleanup, tx => tx
.update(adapterAuthSessions)
.set({ providerLeaseId: input.providerLeaseId, updatedAt: input.at })
.where(eq(adapterAuthSessions.id, input.sessionId)));
},
async setStatus(input) {
await writeLoginCleanup(db, DELIVERY_QUEUES.adapterLoginCleanup, tx => tx
.update(adapterAuthSessions)
.set(buildStatusPatch(input))
.where(eq(adapterAuthSessions.id, input.sessionId)));
},
async compareAndSetStatus(input) {
// The conditional write. It changes the row only when the current status is
// one of `expectedStatuses`. The `returning` clause reports the changed
// rows, so a lost race returns an empty array. The active-slot partial
// unique index still serializes the company slot on the write.
const changed = await writeLoginCleanup(db, DELIVERY_QUEUES.adapterLoginCleanup, tx => tx
.update(adapterAuthSessions)
.set(buildStatusPatch(input))
.where(
and(
eq(adapterAuthSessions.id, input.sessionId),
inArray(adapterAuthSessions.status, [...input.expectedStatuses]),
),
)
.returning({ id: adapterAuthSessions.id }));
return changed.length > 0;
},
async get(sessionId) {
const rows = await db
.select()
.from(adapterAuthSessions)
.where(eq(adapterAuthSessions.id, sessionId))
.limit(1);
const row = rows[0];
return row ? toRow(row) : null;
},
async getByPublicId(publicSessionId, companyId, adapterType) {
// The predicate carries the company id, so a read never keys on the public
// session id alone. A foreign-company caller reads nothing. The internal
// primary-key `id` never matches, so a caller cannot address a row by the
// internal id. The adapter predicate scopes the read to the one requested
// type, or, when the caller omits it, to every displayed-code adapter type.
const rows = await db
.select()
.from(adapterAuthSessions)
.where(
and(
eq(adapterAuthSessions.publicSessionId, publicSessionId),
eq(adapterAuthSessions.companyId, companyId),
adapterType
? eq(adapterAuthSessions.adapterType, adapterType)
: inArray(adapterAuthSessions.adapterType, DISPLAYED_CODE_ADAPTER_TYPES),
),
)
.limit(1);
const row = rows[0];
return row ? toRow(row) : null;
},
async getActiveByOwner(companyId, startedByUserId, adapterType) {
// The predicate matches the same three columns as the active-slot partial
// unique index, plus the active-status set, so at most one row can match.
const rows = await db
.select()
.from(adapterAuthSessions)
.where(
and(
eq(adapterAuthSessions.companyId, companyId),
eq(adapterAuthSessions.startedByUserId, startedByUserId),
eq(adapterAuthSessions.adapterType, adapterType),
inArray(adapterAuthSessions.status, [...ADAPTER_AUTH_ACTIVE_STATUSES]),
),
)
.limit(1);
const row = rows[0];
return row ? toRow(row) : null;
},
async listExpiredActiveSessions(nowAt) {
// The partial index on the active statuses and the index on `expiresAt`
// both support this scan. The scan is bounded by the active-status set, so
// it never reads a terminal row. The scan skips a `promoting` row that
// still holds a live promotion claim, so the reaper never terminates a row
// whose credential write is in progress. It reclaims a `promoting` row only
// after the claim deadline passes.
const rows = await db
.select()
.from(adapterAuthSessions)
.where(
and(
// The shared table also holds the setup-token rows, so every reaper
// scan filters by the closed set of displayed-code adapter types.
inArray(adapterAuthSessions.adapterType, DISPLAYED_CODE_ADAPTER_TYPES),
sql`${adapterAuthSessions.connectionMethod} is distinct from 'local_subscription'`,
inArray(adapterAuthSessions.status, [...ADAPTER_AUTH_ACTIVE_STATUSES]),
isNotNull(adapterAuthSessions.expiresAt),
lte(adapterAuthSessions.expiresAt, nowAt),
or(
ne(adapterAuthSessions.status, "promoting"),
isNull(adapterAuthSessions.promotionExpiresAt),
lte(adapterAuthSessions.promotionExpiresAt, nowAt),
),
),
);
return rows.map(toRow);
},
async listCleanupPendingSessions() {
const rows = await db
.select()
.from(adapterAuthSessions)
.where(
and(
inArray(adapterAuthSessions.adapterType, DISPLAYED_CODE_ADAPTER_TYPES),
sql`${adapterAuthSessions.connectionMethod} is distinct from 'local_subscription'`,
eq(adapterAuthSessions.status, "cleanup_pending"),
),
);
return rows.map(toRow);
},
async listLeaseReferences() {
const rows = await db
.select({ providerLeaseId: adapterAuthSessions.providerLeaseId })
.from(adapterAuthSessions)
.where(
and(
inArray(adapterAuthSessions.adapterType, DISPLAYED_CODE_ADAPTER_TYPES),
isNotNull(adapterAuthSessions.providerLeaseId),
),
);
return rows
.map((row) => row.providerLeaseId)
.filter((value): value is string => value != null);
},
async withCompanyAdapterPromotionLock(companyId, startedByUserId, adapterType, fn) {
return withAdapterLoginPromotionLock(db, companyId, startedByUserId, adapterType, fn);
},
};
}
// ---------------------------------------------------------------------------
// The pending-terminal encoding for a `cleanup_pending` row.
// ---------------------------------------------------------------------------
// A delete failure records the durable internal `cleanup_pending` state before
// the terminal outcome. The row keeps the resolved terminal status and the
// failure code in the `failure_reason` column, so a reaper resolves the terminal
// status after it finishes the delete. The encoding is `<terminal>` or
// `<terminal>|<reason>`. The `cleanup_pending` state is internal, so this column
// value never reaches a public response before the reaper rewrites it.
function encodePendingTerminal(
terminal: AdapterAuthSessionStatus,
reason: string | null,
): string {
return reason ? `${terminal}|${reason}` : terminal;
}
export function decodePendingTerminal(value: string | null): {
terminal: AdapterAuthSessionStatus;
reason: string | null;
} {
if (!value) {
return { terminal: "failed", reason: null };
}
const separatorIndex = value.indexOf("|");
if (separatorIndex === -1) {
return { terminal: value as AdapterAuthSessionStatus, reason: null };
}
return {
terminal: value.slice(0, separatorIndex) as AdapterAuthSessionStatus,
reason: value.slice(separatorIndex + 1) || null,
};
}
// ---------------------------------------------------------------------------
// The shared terminal-cleanup transition. The timer path and the reaper path
// both delete the sandbox and then choose one durable write. This keeps one term
// for a confirmed delete and one encoding for a failed delete.
// ---------------------------------------------------------------------------
/**
* A confirmed delete. The service treats `deleted` and `not_found` as confirmed.
* `not_found` is the idempotent confirmation: the sandbox is already gone, so a
* repeated delete is safe. A rejected delete (a thrown error) is not confirmed.
*/
export function isConfirmedDelete(result: SandboxDeleteResult): boolean {
return result.outcome === "deleted" || result.outcome === "not_found";
}
/** The result of one sandbox delete attempt. */
export interface SandboxDeleteObservation {
/** True when the delete seam ran, whether or not it confirmed. */
observed: boolean;
/** True when the provider confirmed the delete. */
confirmed: boolean;
}
/**
* Run the delete seam once and observe the result. A rejection is an observed
* but unconfirmed delete; the caller records `cleanup_pending`.
*/
export async function observeSandboxDelete(
deleteSandbox: () => Promise<SandboxDeleteResult>,
): Promise<SandboxDeleteObservation> {
try {
const result = await deleteSandbox();
return { observed: true, confirmed: isConfirmedDelete(result) };
} catch {
return { observed: true, confirmed: false };
}
}
/** One durable status write for a terminal cleanup. */
export interface TerminalCleanupWrite {
status: AdapterAuthSessionInternalStatus;
failureReason: string | null;
}
/**
* Choose the durable write after a delete attempt. A confirmed delete writes the
* terminal public status. An unconfirmed delete writes the internal
* `cleanup_pending` state that keeps the terminal for a later reaper retry.
*/
export function terminalCleanupWrite(
confirmed: boolean,
terminal: AdapterAuthSessionStatus,
reason: string | null,
): TerminalCleanupWrite {
return confirmed
? { status: terminal, failureReason: reason }
: { status: "cleanup_pending", failureReason: encodePendingTerminal(terminal, reason) };
}
// ---------------------------------------------------------------------------
// The host-owned displayed-code login profile. `runLogin` resolves one profile
// per login from the trusted adapter type, so a host-owned map, not the runner
// package, chooses the command, the home variable name, the prompt parser, and
// the timeout for each displayed-code adapter.
// ---------------------------------------------------------------------------
/**
* The per-adapter values a displayed-code login run needs. `homeEnvVar` names
* the environment variable the sandbox login pseudo-terminal opener sets to the
* server-controlled session home, for example `CODEX_HOME`. The credential file
* name under that home stays the same for every adapter.
*/
export interface DisplayedCodeLoginProfile {
/** The login command the sandbox pseudo-terminal runs. */
command: string;
/** The environment variable name the login command reads its home from. */
homeEnvVar: string;
/** Parses the authorization prompt from the login output. Returns null when
* the output holds no prompt yet. */
parsePrompt(output: string): AdapterLoginPrompt | null;
/** The host timeout for the sandbox login command. */
timeoutMs: number;
/** The mandatory credential promotion for this adapter. */
promotion: CredentialPromotion;
}
/** A promotion placeholder for a profile map entry. The service always resolves
* the real promotion from {@link DeviceLoginServiceDeps.promotion} before it
* runs a login, so this value never runs in production. */
const UNCONFIGURED_PROMOTION: CredentialPromotion = {
promote() {
throw new Error("device login: no credential promotion is configured for this adapter.");
},
};
/**
* The host-owned profile for every displayed-code adapter type. `AgentAdapterType`
* covers every adapter, not only the displayed-code ones. So the map is a partial
* record: a lookup for an adapter type with no entry yields `undefined`. Both the
* `codex_local` entry and the `grok_local` entry are reachable today: the route
* admission gate in `agents.ts` and the `login-command.ts` closed key map now
* cover `grok_local` too.
*
* `homeEnvVar` names the environment variable the sandbox login pseudo-terminal
* opener sets, for documentation only: no code reads this member today. The
* opener (`composeLaunchLine` in the Daytona plugin) holds its own fixed
* `CODEX_HOME` / `GROK_HOME` mapping, keyed off the closed login command key,
* not off this profile. This matches the existing `codex_local` entry, whose
* `homeEnvVar` has been unread the same way since phase 1.
*/
export const DISPLAYED_CODE_PROFILES: Readonly<
Partial<Record<AgentAdapterType, DisplayedCodeLoginProfile>>
> = {
codex_local: {
command: DEFAULT_CODEX_LOGIN_COMMAND,
homeEnvVar: "CODEX_HOME",
parsePrompt: parseDeviceLoginPrompt,
timeoutMs: DEVICE_LOGIN_TIMEOUT_MS,
promotion: UNCONFIGURED_PROMOTION,
},
grok_local: {
command: DEFAULT_GROK_LOGIN_COMMAND,
homeEnvVar: "GROK_HOME",
parsePrompt: parseGrokDeviceLoginPrompt,
timeoutMs: DEVICE_LOGIN_TIMEOUT_MS,
promotion: UNCONFIGURED_PROMOTION,
},
};
// ---------------------------------------------------------------------------
// The service.
// ---------------------------------------------------------------------------
export interface DeviceLoginServiceDeps {
store: AdapterAuthSessionStore;
runtime: LoginSessionRuntime;
/**
* The mandatory credential promotion, keyed by adapter type. A successful
* login authenticates only after the promotion for its own adapter type
* resolves; a throw fails the session and writes nothing. An adapter type
* with no entry falls back to the `codex_local` entry, matching the profile
* map's own fallback below. Keying by adapter type keeps each adapter's
* promotion running only for its own logins: a `grok_local` login never
* runs the Codex promotion, and a `codex_local` login never runs the Grok
* one.
*/
promotionByAdapterType: Partial<Record<AgentAdapterType, CredentialPromotion>>;
recordActivity?: LoginSessionActivityRecorder;
now?: () => Date;
}
export function createDeviceLoginService(deps: DeviceLoginServiceDeps) {
const { store, runtime, promotionByAdapterType } = deps;
const now = deps.now ?? (() => new Date());
const recordActivity = deps.recordActivity ?? (() => {});
/**
* Resolve the displayed-code profile for one login, with this service
* instance's injected, adapter-scoped promotion in place of the map's
* placeholder. Falls back to the `codex_local` profile (and the
* `codex_local` promotion) for an adapter type with no entry of its own, so
* a login for an adapter type outside the map keeps running the same
* command, parser, and promotion it always did before the map existed.
* `codex_local` and `grok_local` are reachable through the route admission
* gate today; the fallback stays in place for a future adapter type with no
* profile entry.
*/
function resolveProfile(adapterType: AgentAdapterType): DisplayedCodeLoginProfile {
const staticProfile = DISPLAYED_CODE_PROFILES[adapterType] ?? DISPLAYED_CODE_PROFILES.codex_local!;
const promotion =
promotionByAdapterType[adapterType] ??
promotionByAdapterType.codex_local ??
UNCONFIGURED_PROMOTION;
return { ...staticProfile, promotion };
}
// The one-time prompt per session. The service holds it in memory only. The
// owner read path returns it; it never reaches the durable row or an activity
// record.
const promptsBySession = new Map<string, DeviceLoginPrompt>();
async function start(
input: StartDeviceLoginInput,
): Promise<StartDeviceLoginResult> {
const sessionId = randomUUID();
// The public session identifier the API returns and looks up. It is an
// independent CSPRNG value, so it never equals the internal `sessionId` and a
// caller cannot address the row by the internal id.
const publicSessionId = randomUUID();
const startedAt = now();
const ttlSeconds = input.ttlSeconds ?? resolveProfile(input.adapterType).timeoutMs / 1000;
const expiresAt = new Date(startedAt.getTime() + ttlSeconds * 1000);
const base = {
sessionId,
companyId: input.companyId,
environmentId: input.environmentId,
adapterType: input.adapterType,
};
const activity = (phase: LoginSessionActivityPhase) =>
recordActivity({ ...base, phase });
// Insert the session row and the expiring session intent before the
// acquisition. The owner and the expiry persist at creation. A conflict on
// the active company-adapter slot throws a 409, and the service never
// acquires a lease for a losing start.
await store.insert({
id: sessionId,
publicSessionId,
companyId: input.companyId,
environmentId: input.environmentId,
adapterType: input.adapterType,
startedByUserId: input.startedByUserId,
aiConnection: input.aiConnection,
expiresAt,
at: startedAt,
});
activity("session_created");
// Acquire a fresh lease. The runtime disables reuse and archive-on-release,
// applies the active custom-image template, binds the sandbox to a trusted
// image and runtime identity, and tags the provider lease with the session
// identifier.
let lease: LoginSessionLease;
try {
lease = await runtime.acquireLoginLease({
companyId: input.companyId,
environmentId: input.environmentId,
adapterType: input.adapterType,
sessionId,
startedByUserId: input.startedByUserId,
});
} catch (error) {
// The acquisition failed, so no lease exists to release. Free the slot: a
// `starting` row would hold it forever. Mark the row failed, then rethrow.
await store
.setStatus({
sessionId,
status: "failed",
at: now(),
failureReason: "lease_acquire_failed",
finishedAt: now(),
})
.catch(() => {});
activity("failed");
throw error;
}
// Record the lease acquisition. This is a transition after the acquisition.
// If it fails, release the lease at once, so no unlinked sandbox survives.
try {
await store.recordLeaseAcquired({
sessionId,
providerLeaseId: lease.providerLeaseId,
at: now(),
});
} catch (error) {
await lease.release();
activity("lease_released");
await store
.setStatus({
sessionId,
status: "failed",
at: now(),
failureReason: "session_transition_failed",
finishedAt: now(),
})
.catch(() => {});
activity("failed");
throw error;
}
activity("lease_acquired");
const session: AdapterAuthSessionResponse = {
// The API identifier is the public session id, never the internal `sessionId`.
sessionId: publicSessionId,
environmentId: input.environmentId,
status: "starting",
expiresAt: expiresAt.toISOString(),
failure: null,
};
const completed = runLogin({ input, sessionId, lease, base, activity });
return { session, completed };
}
async function runLogin(ctx: {
input: StartDeviceLoginInput;
sessionId: string;
lease: LoginSessionLease;
base: Omit<LoginSessionActivityEvent, "phase">;
activity: (phase: LoginSessionActivityPhase) => void;
}): Promise<DeviceLoginOutcome> {
const { input, sessionId, lease, activity } = ctx;
const profile = resolveProfile(input.adapterType);
// Serialize every status write for this session, so a late write from a
// callback never overwrites a later transition. Each write runs after the
// previous one settles, and a failed write never blocks the next one.
let statusTail: Promise<unknown> = Promise.resolve();
// The serialized conditional status write. It runs after the previous write
// and changes the row only when the current status is one of
// `expectedStatuses`. It returns whether it changed the row, so a caller can
// detect a lost race with the reaper. A failed write never blocks the next.
function conditionalTransition(
expectedStatuses: readonly AdapterAuthSessionInternalStatus[],
status: AdapterAuthSessionInternalStatus,
patch?: {
failureReason?: string | null;
finishedAt?: Date | null;
promotionExpiresAt?: Date | null;
resultClaim?: Record<string, unknown> | null;
},
): Promise<boolean> {
const run = statusTail.then(
() =>
store.compareAndSetStatus({ sessionId, expectedStatuses, status, at: now(), ...patch }),
() =>
store.compareAndSetStatus({ sessionId, expectedStatuses, status, at: now(), ...patch }),
);
statusTail = run.then(
() => {},
() => {},
);
return run;
}
let authBytes: Buffer | null = null;
let outcome: RunnerDeviceLoginOutcome;
try {
const result = await runDeviceLogin(lease.driver, {
command: profile.command,
timeoutMs: profile.timeoutMs,
// `RunDeviceLoginOptions.parsePrompt` keeps the runner's own required-code
// prompt shape. The profile parser returns the wider adapter-neutral
// shape, so this adapts one call's result without widening the runner's
// own `onPrompt` contract. Every `codex_local` prompt carries a code, so
// this is a no-op today.
parsePrompt: (output) => {
const prompt = profile.parsePrompt(output);
return prompt && prompt.code !== undefined ? { url: prompt.url, code: prompt.code } : null;
},
signal: input.signal,
authPath: lease.authPath,
onPrompt: (prompt) => {
// Move the row to the active `waiting_for_user` state with a
// conditional write from `starting`. Retain and surface the prompt only
// when the write wins. A lost write means the reaper already reclaimed
// the expired row, so the service never resurrects a reaped session and
// never surfaces a prompt for a slot it no longer owns.
void conditionalTransition(["starting"], "waiting_for_user").then((won) => {
if (!won) return;
promptsBySession.set(sessionId, prompt);
activity("prompt_surfaced");
});
},
onCredential: (bytes) => {
authBytes = bytes;
},
});
outcome = result.outcome;
} catch {
// The runner only throws on a driver error, and it never leaks the stream.
// Treat a driver error as a login failure.
outcome = "failure";
}
if (outcome === "success") {
// Claim the slot for the mandatory promotion. The claim is a conditional
// write from a pre-promotion active status to `promoting`, and it sets the
// promotion deadline. While the deadline is in the future, the reaper never
// terminates the row or releases the company slot, so the credential write
// finishes without a race. A lost claim means the reaper already reclaimed
// an expired row; the service then promotes nothing and authenticates
// nothing.
const claimDeadline = new Date(now().getTime() + ADAPTER_AUTH_PROMOTION_CLAIM_MS);
const claimed = await conditionalTransition(["starting", "waiting_for_user"], "promoting", {
promotionExpiresAt: claimDeadline,
});
if (!claimed) {
return await abandonAfterLostClaim({ sessionId, lease, activity });
}
activity("promoting");
try {
// Fail closed. A success outcome must carry a non-empty credential, and
// the mandatory promotion must accept it. Absent or empty bytes, or a
// rejected promotion, never authenticate.
// The `onCredential` callback assigns `authBytes`, so read it as the
// declared union. The cast keeps the null case, which the guard rejects.
const credential = authBytes as Buffer | null;
if (!credential || credential.length === 0) {
throw new Error("missing_credential");
}
await profile.promotion.promote(credential, {
sessionId,
companyId: input.companyId,
startedByUserId: input.startedByUserId,
adapterType: input.adapterType,
});
} catch {
// The promotion failed. The login did not finish, so fall through to the
// failed terminal. The service writes nothing and still deletes the
// sandbox. The terminal write is conditional on the held claim.
return await terminate({
sessionId,
lease,
terminal: "failed",
reason: "promotion_failed",
expectedStatuses: ["promoting"],
conditionalTransition,
activity,
});
}
// Publish `authenticated` only when the final conditional write still finds
// the held claim. A lost write means the claim expired and the reaper
// reclaimed the row, so the service never publishes `authenticated`.
const commitAuthenticated = (resultClaim?: Record<string, unknown>) =>
terminate({
sessionId,
lease,
terminal: "authenticated",
reason: null,
expectedStatuses: ["promoting"],
conditionalTransition,
activity,
resultClaim: resultClaim ?? null,
});
const promotionContext: CredentialPromotionContext = {
sessionId,
companyId: input.companyId,
startedByUserId: input.startedByUserId,
adapterType: input.adapterType,
};
try {
return profile.promotion.runTerminalCommit
? await profile.promotion.runTerminalCommit(commitAuthenticated, promotionContext)
: await commitAuthenticated();
} catch {
// The wrapped final check rejected the value `promote` bound earlier
// (for example, a rotation landed after that validation). The login
// did not finish, so fail closed the same way a `promote` rejection
// does: never publish `authenticated`, still delete the sandbox.
return await terminate({
sessionId,
lease,
terminal: "failed",
reason: "promotion_failed",
expectedStatuses: ["promoting"],
conditionalTransition,
activity,
});
}
}
const terminal: AdapterAuthSessionStatus =
outcome === "timeout"
? "timed_out"
: outcome === "cancelled"
? "cancelled"
: "failed";
const reason = terminal === "failed" ? "login_command_failed" : null;
// The pre-promotion terminal writes race the reaper at the expiry boundary.
// The conditional write on the active pre-promotion statuses lets the reaper
// win without a clobber; the service never revives a reaped row.
return await terminate({
sessionId,
lease,
terminal,
reason,
expectedStatuses: ["starting", "waiting_for_user"],
conditionalTransition,
activity,
});
}
// Abandon a success outcome whose promotion claim was lost. The reaper already
// terminated this session, so the service writes no status and no credential.
// It deletes the sandbox best-effort; the reaper delete is idempotent.
async function abandonAfterLostClaim(ctx: {
sessionId: string;
lease: LoginSessionLease;
activity: (phase: LoginSessionActivityPhase) => void;
}): Promise<DeviceLoginOutcome> {
const { sessionId, lease, activity } = ctx;
// The reaper already reclaimed the row, so this process no longer owns the
// slot. Delete a prompt this process may still hold for it.
promptsBySession.delete(sessionId);
const observation = await observeSandboxDelete(() => lease.deleteSandbox());
if (observation.confirmed) {
activity("sandbox_deleted");
}
activity("timed_out");
return {
sessionId,
status: "timed_out",
cleanupPending: false,
sandboxDeleteObserved: observation.observed,
};
}
async function terminate(ctx: {
sessionId: string;
lease: LoginSessionLease;
terminal: AdapterAuthSessionStatus;
reason: string | null;
/** The statuses the terminal write may replace. The write is conditional. */
expectedStatuses: readonly AdapterAuthSessionInternalStatus[];
conditionalTransition: (
expectedStatuses: readonly AdapterAuthSessionInternalStatus[],
status: AdapterAuthSessionInternalStatus,
patch?: {
failureReason?: string | null;
finishedAt?: Date | null;
promotionExpiresAt?: Date | null;
resultClaim?: Record<string, unknown> | null;
},
) => Promise<boolean>;
activity: (phase: LoginSessionActivityPhase) => void;
/** The non-secret claim to record atomically with a terminal success. */
resultClaim?: Record<string, unknown> | null;
}): Promise<DeviceLoginOutcome> {
const { sessionId, lease, terminal, reason, expectedStatuses, conditionalTransition, activity } =
ctx;
// Delete the in-memory prompt on every terminal transition this function
// handles: an authenticated success, a failure, a timeout, and a
// cancellation. A terminal response then always carries a null prompt.
promptsBySession.delete(sessionId);
// The cleanup-state handoff. The service owns and observes the provider
// delete on every terminal path. The reaper path shares the same delete
// observation and the same durable-write choice.
const observation = await observeSandboxDelete(() => lease.deleteSandbox());
if (observation.confirmed) {
activity("sandbox_deleted");
}
const finishedAt = now();
const write = terminalCleanupWrite(observation.confirmed, terminal, reason);
// A failed delete records the durable internal `cleanup_pending` state before
// the terminal outcome, so a reaper retries the delete. A confirmed delete
// records the terminal public status and releases the active claim. The write
// is conditional and clears the promotion claim, so a lost race leaves the
// reaper terminal in place.
const committed = await conditionalTransition(expectedStatuses, write.status, {
finishedAt,
failureReason: write.failureReason,
promotionExpiresAt: null,
...(ctx.resultClaim !== undefined ? { resultClaim: ctx.resultClaim } : {}),
});
if (!committed) {
// The reaper already terminated the row. Leave its terminal in place. The
// sandbox delete above is idempotent, so no sandbox survives.
activity("timed_out");
return {
sessionId,
status: "timed_out",
cleanupPending: false,
sandboxDeleteObserved: observation.observed,
};
}
activity(observation.confirmed ? (terminal as LoginSessionActivityPhase) : "cleanup_pending");
return {
sessionId,
status: terminal,
cleanupPending: !observation.confirmed,
sandboxDeleteObserved: observation.observed,
};
}
// Build the owner response for a row. The prompt survives every read while
// the session holds an active public status: the read never deletes it. A
// terminal transition deletes the prompt at its own write site instead (see
// `terminate`, `abandonAfterLostClaim`, and `cancelOwnerSession`), so a
// terminal response always carries a null prompt.
function buildOwnerResponse(
row: AdapterAuthSessionRow,
requestingUserId: string,
): AdapterAuthSessionOwnerResponse {
const isOwner = row.startedByUserId === requestingUserId;
const status = resolvePublicStatus(row);
// The prompt map keys on the internal id, so read it by `row.id`, not the
// public id. Only the owner principal ever reads the prompt.
const prompt = isOwner ? promptsBySession.get(row.id) ?? null : null;
return {
sessionId: row.publicSessionId,
...(isOwner && row.aiConnection ? { aiConnection: row.aiConnection } : {}),
environmentId: row.environmentId,
status,
expiresAt: row.expiresAt?.toISOString() ?? null,
failure: buildFailure(row, status),
prompt: prompt ? { url: prompt.url, code: prompt.code } : null,
};
}
async function readOwnerSession(
publicSessionId: string,
companyId: string,
requestingUserId: string,
): Promise<AdapterAuthSessionOwnerResponse | null> {
// Look the row up by its public session id, scoped to the company. A
// foreign-company caller reads nothing, and the internal id never matches.
const row = await store.getByPublicId(publicSessionId, companyId);
if (!row) return null;
return buildOwnerResponse(row, requestingUserId);
}
// Read the caller's active session for one company and adapter, with no
// session id. The browser rediscovers its own session after a reload with no
// local state. The store predicate matches only an active row for this exact
// owner, so this never surfaces a foreign owner's session.
async function readActiveOwnerSession(
companyId: string,
adapterType: AgentAdapterType,
requestingUserId: string,
): Promise<AdapterAuthSessionOwnerResponse | null> {
const row = await store.getActiveByOwner(companyId, requestingUserId, adapterType);
if (!row) return null;
return buildOwnerResponse(row, requestingUserId);
}
// Cancel a login session for its owner. The write is durable, so a cancel
// releases the company slot even when the calling process does not own the
// in-flight run. A cross-process cancel, or a cancel after a restart, has no
// in-memory controller to abort, so a process-local abort alone would leave the
// row in an active state until the expiry. The durable write closes that gap.
//
// The transition is a conditional write from a pre-promotion active status to
// the internal `cleanup_pending` state that encodes the `cancelled` terminal.
// This releases the slot at once and hands the sandbox delete and the terminal
// finalize to the reaper's cleanup-pending sweep. The write skips a `promoting`
// row, so a cancel never interrupts an in-flight credential write; that
// promotion runs to its own terminal.
async function cancelOwnerSession(
publicSessionId: string,
companyId: string,
requestingUserId: string,
): Promise<AdapterAuthSessionOwnerResponse | null> {
// Look the row up by its public session id, scoped to the company. The status
// write keys on the internal `row.id`, so a cancel never addresses a row by
// the public id alone.
const row = await store.getByPublicId(publicSessionId, companyId);
if (!row || row.startedByUserId !== requestingUserId) return null;
const write = terminalCleanupWrite(false, "cancelled", null);
await store.compareAndSetStatus({
sessionId: row.id,
expectedStatuses: ["starting", "waiting_for_user"],
status: write.status,
at: now(),
failureReason: write.failureReason,
finishedAt: now(),
promotionExpiresAt: null,
});
// Delete the in-memory prompt on every cancel, whether or not the write
// above won. A lost write means the row already left the cancellable
// states, so no fresh prompt exists for it either.
promptsBySession.delete(row.id);
return readOwnerSession(publicSessionId, companyId, requestingUserId);
}
return { start, readOwnerSession, readActiveOwnerSession, cancelOwnerSession };
}
export type DeviceLoginService = ReturnType<typeof createDeviceLoginService>;
/** Resolve the public status of a row. A `cleanup_pending` row resolves the
* retained terminal status; every other status maps through the shared helper. */
function resolvePublicStatus(row: AdapterAuthSessionRow): AdapterAuthSessionStatus {
if (row.status === "cleanup_pending") {
return decodePendingTerminal(row.failureReason).terminal;
}
return toPublicAdapterAuthSessionStatus(row.status);
}
function buildFailure(
row: AdapterAuthSessionRow,
status: AdapterAuthSessionStatus,
): AdapterAuthSessionFailure | null {
if (status !== "failed") return null;
const reason =
row.status === "cleanup_pending"
? decodePendingTerminal(row.failureReason).reason
: row.failureReason;
return { reason: reason ?? "unknown", message: null };
}
// ---------------------------------------------------------------------------
// The production runtime binding and the shared driver helper.
// ---------------------------------------------------------------------------
/** The fixed, session-specific Codex home template. The session identifier is
* server-generated, so no caller controls this path. */
export function sessionLoginHomePath(sessionId: string): string {
return `/tmp/paperclip-adapter-login/${sessionId}`;
}
/** The fixed, session-specific credential path. No caller controls it. */
export function sessionCredentialPath(sessionId: string): string {
return `${sessionLoginHomePath(sessionId)}/auth.json`;
}
/**
* Build the sandbox login driver. This is the one helper the production runtime
* and the tests share. It runs the login command over the shared login
* pseudo-terminal (PTY) transport and reads the credential with one
* descriptor-bound read.
*
* - `start` runs the fixed login command on a real pseudo-terminal through the
* shared {@link createLoginPtyTransport} and streams each terminal output chunk
* to the runner while the login command waits for the user. The login command
* needs a pseudo-terminal: pipe stdio emits no login prompt. The pseudo-terminal
* opener sets the session-specific `CODEX_HOME` to the same verified session
* home this driver reads.
* - `readFile` runs one descriptor-bound read. It opens the verified session home
* and the fixed credential file with no symlink follow, checks the opened
* descriptor, and reads only from that same descriptor. It ignores the path the
* runner passes, so no caller controls the read target. It reads the fixed
* `auth.json` under the server-controlled session home.
* - `dispose` releases the pseudo-terminal transport, so the host frees the login
* pseudo-terminal slot. The service owns the sandbox delete through a separate
* seam, so this dispose never deletes the sandbox.
*
* The session home is server-controlled and shared: the pseudo-terminal opener
* sets `CODEX_HOME` to it, and the descriptor-bound read opens it. So the login
* command writes `auth.json` into the exact directory the read opens.
*/
export function buildSandboxLoginDriver(deps: {
openPtySession: LoginPtySessionOpener;
environmentRuntime: Pick<EnvironmentRuntimeService, "execute">;
environment: Environment;
lease: EnvironmentLease;
sessionHome: string;
timeoutMs: number;
}): SandboxLoginDriver {
const { openPtySession, environmentRuntime, environment, lease, sessionHome, timeoutMs } = deps;
const transport = createLoginPtyTransport(openPtySession);
return {
async start(command, onData) {
return transport.start(command, onData);
},
async readFile(_path) {
// The read ignores the runner path. It runs one fixed, server-controlled,
// descriptor-bound operation against the verified session home. So a swap of
// the credential file between a check and the read cannot steer the read.
return runDescriptorBoundAuthRead({
environmentRuntime,
environment,
lease,
sessionHome,
timeoutMs,
});
},
async dispose() {
// Free the host pseudo-terminal slot before the service deletes the sandbox.
// The service owns the sandbox delete through a separate seam.
await transport.dispose();
},
};
}
/**
* The verified binding one login session hands to the live pseudo-terminal
* opener. The opener sets the sandbox `CODEX_HOME` to `sessionHome`, so the login
* command writes `auth.json` into the exact directory the descriptor-bound read
* opens.
*/
export interface LoginPtySessionBinding {
companyId: string;
environmentId: string;
adapterType: AgentAdapterType;
/** The provider lease that binds the sandbox worker. */
providerLeaseId: string;
/** The server-controlled session home. The opener sets `CODEX_HOME` to it. */
sessionHome: string;
/** The resolved environment for the acquired lease. */
environment: Environment;
/** The acquired environment lease. */
lease: EnvironmentLease;
}
/**
* Opens the live pseudo-terminal for one login session and returns the shared
* transport opener. The Daytona provider runs as a plugin worker, so the real
* opener binds inside the worker through the plugin worker manager route. A test
* injects a fake opener to drive the full session path.
*/
export type OpenLoginPtySession = (
binding: LoginPtySessionBinding,
) => Promise<LoginPtySessionOpener>;
/** The fixed, non-secret error the Codex live opener throws when it cannot bind
* the sandbox worker route. It carries no lease detail and no secret. */
const CODEX_LOGIN_PTY_BIND_FAILED =
"device login failed: the sandbox pseudo-terminal transport is not bound.";
/** The dependencies the worker-bound Codex live pseudo-terminal opener needs. */
export interface WorkerBoundLoginPtyOpenerDeps {
/** The plugin worker manager that owns the host route gate. */
workerManager: LoginPtyWorkerManagerLike;
/** A non-leaking status sink. It receives only fixed status lines. */
log?: (line: string) => void;
}
function readLeaseMetaString(value: unknown): string | null {
return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
}
/**
* Builds the production Codex `openLivePtySession`. It drives the sandbox worker
* through the manager route gate. The manager mints the host route identifier and
* owns the route lifecycle.
*
* The opener passes the binding's server-controlled `sessionHome` to the worker
* route. That home is the exact directory the descriptor-bound credential read
* opens, so the sandbox `CODEX_HOME` and the read target match. The opener never
* derives a fresh home: a fresh home would set `CODEX_HOME` to a directory the
* read never opens, and every Codex login would fail closed.
*
* The opener resolves the closed login command key from the trusted adapter type,
* never from the caller. It validates the session home shape before the worker
* RPC. It fails closed when the lease carries no sandbox worker binding.
*/
export function createWorkerBoundLoginPtyOpener(
deps: WorkerBoundLoginPtyOpenerDeps,
): OpenLoginPtySession {
const log = deps.log ?? (() => {});
return async (binding) => {
const metadata =
binding.lease.metadata && typeof binding.lease.metadata === "object"
? (binding.lease.metadata as Record<string, unknown>)
: {};
const pluginId = readLeaseMetaString(metadata.pluginId);
const driverKey =
readLeaseMetaString(metadata.provider) ?? readLeaseMetaString(metadata.driver);
if (!binding.providerLeaseId || !pluginId || !driverKey) {
log("[paperclip] Device login: the lease carries no sandbox worker binding.");
throw new Error(CODEX_LOGIN_PTY_BIND_FAILED);
}
// Resolve the closed command key from the trusted adapter type. An unmapped
// adapter fails closed before the worker RPC.
let loginCommandKey: LoginCommandKey;
try {
loginCommandKey = resolveLoginCommandKey(binding.adapterType);
} catch {
log("[paperclip] Device login: the adapter type has no login command key.");
throw new Error(CODEX_LOGIN_PTY_BIND_FAILED);
}
// Validate the server-controlled session home shape before the worker RPC.
// The runtime derived it from the session id; the manager revalidates it too.
validateLoginSessionHome(binding.sessionHome);
// The opener argument is the runner's fixed command string. It confers no
// command authority, so the opener ignores it and returns a host-bound opener.
return (_command: string) =>
deps.workerManager.openLoginPtySession(pluginId, {
driverKey,
companyId: binding.companyId,
environmentId: binding.environmentId,
providerLeaseId: binding.providerLeaseId,
loginCommandKey,
sessionHome: binding.sessionHome,
});
};
}
export interface ProductionLoginSessionRuntimeDeps {
db: Db;
environmentRuntime: EnvironmentRuntimeService;
/**
* Re-checks the provider login pseudo-terminal capability from current runtime
* state, immediately before the provider lease. The route gate already ran, so
* a managed reconciliation can rebind the environment to an unsupported
* provider between the route gate and this acquire. The check reads the current
* provider capability, not the stale route decision. It throws the fixed
* unsupported-provider error, so the runtime creates no lease and opens no
* pseudo-terminal for an unsupported provider.
*/
assertProviderSupportsLoginPty: (environmentId: string) => Promise<void>;
/**
* Opens the live pseudo-terminal for the acquired lease. When a caller omits
* it, the runtime binds a fail-closed opener: the login run then fails and the
* service deletes the sandbox. The live opener binds the sandbox worker route.
*/
openLivePtySession?: OpenLoginPtySession;
}
/** The fixed, non-secret error the fail-closed opener throws when no live
* pseudo-terminal opener is bound. */
const LOGIN_PTY_OPENER_UNBOUND = "device login failed: the sandbox pseudo-terminal transport is not bound.";
/**
* Build the production login-session runtime. It acquires a fresh lease with
* reuse disabled (no heartbeat run, no execution workspace) and the active
* custom-image template applied, binds the sandbox login driver over the shared
* pseudo-terminal transport, and owns the delete and release seams.
*/
export function createProductionLoginSessionRuntime(
deps: ProductionLoginSessionRuntimeDeps,
): LoginSessionRuntime {
const environmentsSvc = environmentService(deps.db);
return {
async acquireLoginLease(input) {
const environment = await environmentsSvc.getById(input.environmentId);
if (!environment) {
throw new Error(`Environment "${input.environmentId}" is not found.`);
}
// Re-check the provider login pseudo-terminal capability from current
// runtime state, immediately before the provider lease. A managed
// reconciliation can rebind the environment to an unsupported provider
// between the route gate and this acquire, so the check reads the current
// capability, not the stale route decision. It throws the fixed
// unsupported-provider error, so the runtime acquires no lease and opens no
// pseudo-terminal for an unsupported provider.
await deps.assertProviderSupportsLoginPty(input.environmentId);
const record = await deps.environmentRuntime.acquireRunLease(
buildLoginLeaseAcquireArgs({
metadata: {
companyId: input.companyId,
environment,
adapterType: input.adapterType,
},
}),
);
// Tag the lease with the session identifier, so the reaper resolves an
// orphan lease that no live session references. The tag carries no secret.
await writeLoginCleanup(deps.db, DELIVERY_QUEUES.adapterLoginCleanup, tx => environmentService(tx).updateLeaseMetadata(record.lease.id, {
...(record.lease.metadata ?? {}),
[LOGIN_LEASE_SESSION_TAG_KEY]: input.sessionId,
}));
const sessionHome = sessionLoginHomePath(input.sessionId);
const authPath = sessionCredentialPath(input.sessionId);
const providerLeaseId = record.lease.providerLeaseId ?? record.lease.id;
// Resolve the live pseudo-terminal opener for this lease. When no live
// opener is bound, use a fail-closed opener: the login run then fails and
// the service deletes the sandbox. The opener sets `CODEX_HOME` to the same
// `sessionHome` the descriptor-bound read opens.
const openPtySession: LoginPtySessionOpener = deps.openLivePtySession
? await deps.openLivePtySession({
companyId: input.companyId,
environmentId: input.environmentId,
adapterType: input.adapterType,
providerLeaseId,
sessionHome,
environment: record.environment,
lease: record.lease,
})
: () => Promise.reject(new Error(LOGIN_PTY_OPENER_UNBOUND));
const driver = buildSandboxLoginDriver({
openPtySession,
environmentRuntime: deps.environmentRuntime,
environment: record.environment,
lease: record.lease,
sessionHome,
timeoutMs: DEVICE_LOGIN_TIMEOUT_MS,
});
const driverKey = record.environment.driver;
return {
providerLeaseId,
driver,
authPath,
async deleteSandbox() {
const runtimeDriver = deps.environmentRuntime.getDriver(driverKey);
if (!runtimeDriver) {
throw new Error(`Environment driver "${driverKey}" is not registered.`);
}
const released = await runtimeDriver.releaseRunLease({
environment: record.environment,
lease: record.lease,
status: "released",
});
// A failed provider cleanup is not a confirmed delete. The service
// records `cleanup_pending` on the rejection.
if (released?.cleanupStatus === "failed") {
throw new Error("The sandbox delete did not confirm.");
}
return { outcome: "deleted" };
},
async release() {
const runtimeDriver = deps.environmentRuntime.getDriver(driverKey);
await runtimeDriver?.releaseRunLease({
environment: record.environment,
lease: record.lease,
status: "failed",
});
},
};
},
};
}