@modelprofile.com/authswitch 2.1.2

package/ts/classes.tui.ts

@@ -0,0 +1,138 @@
+import * as plugins from './plugins.js';
+import type { IAuthHarness, IHarnessOutcome, IHarnessState } from './interfaces.harness.js';
+import { accountDetails, accountPlan, accountQuotaSummary, accountResets, accountState, accountUsageWindows, usagePeriod, until, readAccountRows, type IAccountRow } from './accounts.js';
+import { plainText } from './formatting.js';
+import { AuthSwitchOperations } from './classes.operations.js';
+
+/** Owns account-management actions; terminal rendering and interaction belong to smartconsole. */
+export class AuthSwitchTui {
+  constructor(private readonly harnesses: readonly IAuthHarness[], private readonly out: plugins.smartconsole.SmartConsole, private readonly operations = new AuthSwitchOperations()) {}
+
+  public async run(preferredArg?: IAuthHarness): Promise<number> {
+    let harness = preferredArg ?? this.harnesses[0];
+    if (!harness) { await this.out.warn('No harnesses registered.'); return 2; }
+    const ui = this.out.tui;
+    let state: IHarnessState | undefined;
+    let rows: IAccountRow[] = [];
+    const footer = ui.text('Loading account status…', { height: 2 });
+    const details = ui.viewer('Select an account to inspect its status.');
+    const table = ui.table<IAccountRow>({
+      rows: [], rowKey: row => JSON.stringify([row.harness.id, row.account.id]),
+      columns: [
+        { key: 'account', title: 'Account', value: row => plainText(row.account.label) },
+        { key: 'state', title: 'State', value: accountState },
+        { key: 'plan', title: 'Plan', value: accountPlan },
+        { key: 'usage', title: 'Usage / reset', value: row => accountQuotaSummary(row, Date.now()).replaceAll('\n', ' / ') },
+        { key: 'resets', title: 'Resets', value: row => row.status?.summary?.resets?.available, render: accountResets, align: 'right' },
+      ],
+      onSelect: () => updateDetails(),
+      onActivate: async (_row, screen) => { await perform(screen, () => switchSelected(screen)); },
+    });
+    const updateDetails = (): void => { details.setText(table.selected ? accountDetails(table.selected) : state?.saveUnavailableReason ?? harness.loginHint); };
+    const showOutcome = (outcomeArg: IHarnessOutcome): boolean => {
+      for (const line of outcomeArg.lines) ui.logs.append(plainText(line));
+      for (const problem of outcomeArg.problems) ui.logs.append('Incomplete: ' + plainText(problem));
+      footer.setText(outcomeArg.problems.length ? 'Incomplete: ' + outcomeArg.problems.map(plainText).join('; ') : outcomeArg.lines.map(plainText).join(' · ') || 'Done.');
+      return outcomeArg.problems.length === 0;
+    };
+    const refresh = async (screen: plugins.smartconsole.ITuiContext): Promise<void> => {
+      footer.setText(`Loading ${plainText(harness.label)} accounts and live status…`);
+      await screen.invalidate();
+      try {
+        const result = await readAccountRows(harness, { signal: screen.signal, onUpdate: async (updatedArg, stateArg) => {
+          if (screen.signal.aborted) return;
+          rows = updatedArg; state = stateArg; table.setRows(rows); updateDetails(); await screen.invalidate();
+        } });
+        if (screen.signal.aborted) return;
+        state = result.state; rows = result.rows;
+        const failures = rows.filter(row => row.status?.problems.length).length;
+        footer.setText(`${rows.length} account(s) · ${failures ? `${failures} with unavailable status sections` : 'Status refreshed'}${state.saveUnavailableReason ? ' · ' + plainText(state.saveUnavailableReason) : ''}`);
+      } catch {
+        state = undefined; rows = []; table.setRows([]);
+        footer.setText(`Could not read ${plainText(harness.label)} accounts. Run authswitch ${harness.id} doctor.`);
+      }
+      updateDetails();
+    };
+    const perform = async (screen: plugins.smartconsole.ITuiContext, action: () => Promise<void>): Promise<void> => {
+      if (screen.signal.aborted) return;
+      try { await action(); }
+      catch { footer.setText(`Operation failed. Run authswitch ${harness.id} doctor for diagnostics.`); }
+      updateDetails();
+    };
+    const save = async (screen: plugins.smartconsole.ITuiContext, keepActiveArg: boolean): Promise<void> => {
+      const latest = await harness.readState();
+      const activeAccounts = latest.accounts.filter(account => account.isActive);
+      const active = activeAccounts.find(account => account.id === table.selected?.account.id) ?? (activeAccounts.length === 1 ? activeAccounts[0] : undefined);
+      if (!active && activeAccounts.length > 1) { footer.setText('Select the active account you want to save.'); return; }
+      if (!active || latest.saveUnavailableReason) { footer.setText(latest.saveUnavailableReason ?? 'No active login to save.'); return; }
+      if (!await screen.confirm(`Save ${plainText(active.label)}${keepActiveArg ? ' and keep it active' : ' and clear the active login'}?`)) return;
+      if (screen.signal.aborted) return;
+      const outcome = await this.operations.run(harness, { harnessId: harness.id, action: 'save', keepActive: keepActiveArg, accountId: active.id }, message => screen.confirm(message));
+      await refresh(screen); showOutcome(outcome);
+    };
+    const switchSelected = async (screen: plugins.smartconsole.ITuiContext): Promise<void> => {
+      const selected = table.selected;
+      if (!selected) return;
+      const latest = await harness.readState();
+      const target = latest.accounts.find(account => account.id === selected.account.id && account.isStashed);
+      if (!target) { footer.setText('Select an account with a verified saved login.'); return; }
+      const active = latest.accounts.find(account => account.isActive && account.slotId === target.slotId);
+      if (active && !active.isStashed) {
+        if (latest.saveUnavailableReason) { footer.setText(latest.saveUnavailableReason); return; }
+        if (!await screen.confirm(`${plainText(active.label)} is not saved. Save this login before switching?`, { confirmLabel: 'Save first' })) return;
+        if (screen.signal.aborted) return;
+        if (!showOutcome(await this.operations.run(harness, { harnessId: harness.id, action: 'save', keepActive: true, accountId: active.id }, message => screen.confirm(message)))) return;
+        const verified = await harness.readState();
+        if (!verified.accounts.some(account => account.isActive && account.isStashed && account.id === active.id)) { footer.setText('The current login could not be verified as saved. Switching was cancelled.'); return; }
+      }
+      if (!await screen.confirm(`Switch ${plainText(harness.label)} to ${plainText(target.label)}?`, { confirmLabel: 'Switch' })) return;
+      if (screen.signal.aborted) return;
+      const outcome = await this.operations.run(harness, { harnessId: harness.id, action: 'switch', accountId: target.id }, message => screen.confirm(message));
+      await refresh(screen); showOutcome(outcome);
+    };
+    const remove = async (screen: plugins.smartconsole.ITuiContext): Promise<void> => {
+      const selected = table.selected;
+      if (!selected || (!selected.account.isStashed && selected.account.savedAt === null)) { footer.setText('Select an account with a saved copy.'); return; }
+      if (!await screen.confirm(`Remove the saved login for ${plainText(selected.account.label)}? The active login stays as it is.`, { confirmLabel: 'Remove saved copy' })) return;
+      if (screen.signal.aborted) return;
+      const outcome = await harness.removeAccount(selected.account.id);
+      await refresh(screen); showOutcome(outcome);
+    };
+    const harnessTable = ui.table({
+      rows: this.harnesses, rowKey: item => item.id, selectedKey: harness.id,
+      columns: [{ key: 'harness', title: 'Harness', value: item => item.label }],
+      onActivate: async (selected, screen) => {
+        harness = selected; state = undefined; table.setRows([]);
+        await refresh(screen); screen.focus(table);
+      },
+    });
+    const tabs = ui.tabs([{ title: 'Account details', content: details }, { title: 'Activity log', content: ui.logs }]);
+    await ui.run({
+      view: () => {
+        const usage = accountUsageWindows({ status: table.selected?.status })?.slice(0, 2).map(window => ui.progress(
+          `${usagePeriod(window)} (${window.usedPercent}% used; reset in ${until(window.resetAt, Date.now())})`, Math.min(100, window.usedPercent), 100,
+        )) ?? [];
+        const accountView = ui.column([
+          ui.panel(`${plainText(harness.label)} accounts`, table),
+          ui.panel('Status and diagnostics', ui.column([...usage, tabs])),
+        ]);
+        return ui.column([
+          ui.text('authswitch · account management', { height: 1 }),
+          this.harnesses.length > 1 ? ui.row([ui.panel('Harnesses', harnessTable, { width: 23 }), accountView]) : accountView,
+          ui.text('Enter switch · a save · c save+clear · d remove · r refresh · g diagnose · Tab focus · q quit', { height: 2 }),
+          footer,
+        ]);
+      },
+      onReady: async screen => { screen.focus(table); await refresh(screen); },
+      keys: {
+        q: screen => screen.close(),
+        r: screen => refresh(screen),
+        a: screen => perform(screen, () => save(screen, true)),
+        c: screen => perform(screen, () => save(screen, false)),
+        d: screen => perform(screen, () => remove(screen)),
+        g: screen => perform(screen, async () => { showOutcome(await harness.diagnose()); }),
+      },
+    });
+    return 0;
+  }
+}

package/ts/formatting.ts

@@ -0,0 +1,14 @@
+import * as plugins from './plugins.js';
+
+const styled = (): boolean => process.stdout.isTTY === true && !Object.hasOwn(process.env, 'NO_COLOR');
+const render = (textArg: string, styleArg: plugins.smartconsole.ITextStyle): string =>
+  styled() ? plugins.smartconsole.color.toAnsi(plugins.smartconsole.color.text(textArg, styleArg)) : plainText(textArg);
+export const dim = (textArg: string): string => render(textArg, { dim: true });
+export const bold = (textArg: string): string => render(textArg, { bold: true });
+const paint = (textArg: string, colorArg: plugins.smartconsole.TColorName): string => render(textArg, { foreground: colorArg });
+export const green = (textArg: string): string => paint(textArg, 'green');
+export const red = (textArg: string): string => paint(textArg, 'red');
+export const orange = (textArg: string): string => paint(textArg, 'orange');
+export const cyan = (textArg: string): string => paint(textArg, 'cyan');
+/** Remote labels cannot inject terminal control sequences or extra output rows. */
+export const plainText = (textArg: string): string => textArg.replace(/[\u0000-\u001f\u007f-\u009f]/g, '').slice(0, 500);

package/ts/helpers.ts

@@ -0,0 +1,109 @@
+import * as plugins from './plugins.js';
+import type { IRemoteControlEnrollment, TEnrollmentState } from './interfaces.js';
+
+/**
+ * Writes a secret to `destinationPathArg` atomically and owner-only.
+ *
+ * Three things matter here, and none of them are free with a plain
+ * `writeFileSync`:
+ *
+ * - The temp file is created with the `wx` flag, so a leftover file from an
+ *   interrupted run cannot silently receive a credential at whatever mode that
+ *   run left behind.
+ * - Its mode is set explicitly after creation, because `writeFileSync`'s `mode`
+ *   option only applies when the file is created.
+ * - It is removed on every failure path, so a complete credential is never left
+ *   at a predictable path that nothing lists, cleans, or reports.
+ *
+ * The rename is atomic within a filesystem, so a reader sees either the old
+ * content or the new one, never a partial write.
+ */
+export const writeSecretFileAtomically = (
+  destinationPathArg: string,
+  contentArg: string,
+): void => {
+  const tempPath = `${destinationPathArg}.authswitch-tmp`;
+  // A stale temp file means an earlier run died mid-write. Its content is
+  // superseded by what we are about to write, so clearing it is safe -- and
+  // necessary, since `wx` would otherwise fail forever.
+  if (plugins.fs.existsSync(tempPath)) {
+    plugins.fs.rmSync(tempPath, { force: true });
+  }
+
+  let handle: number | null = null;
+  try {
+    handle = plugins.fs.openSync(tempPath, 'wx', 0o600);
+    plugins.fs.fchmodSync(handle, 0o600);
+    plugins.fs.writeFileSync(handle, contentArg, { encoding: 'utf8' });
+    plugins.fs.fsyncSync(handle);
+    plugins.fs.closeSync(handle);
+    handle = null;
+    plugins.fs.renameSync(tempPath, destinationPathArg);
+  } catch (errorArg) {
+    if (handle !== null) {
+      try {
+        plugins.fs.closeSync(handle);
+      } catch {
+        // The handle is being discarded either way.
+      }
+    }
+    plugins.fs.rmSync(tempPath, { force: true });
+    throw errorArg;
+  }
+  plugins.fs.chmodSync(destinationPathArg, 0o600);
+};
+
+/**
+ * Trims third-party process output down to something safe to put in an error
+ * message: one line, length-capped, and never empty.
+ */
+export const summariseProcessOutput = (
+  stdoutArg: string,
+  stderrArg: string,
+  spawnErrorArg: string | null,
+): string => {
+  const candidate = (spawnErrorArg ?? stderrArg.trim() ?? '') || stdoutArg.trim();
+  if (!candidate) {
+    return 'no output';
+  }
+  const firstLine = candidate.split('\n').find((lineArg) => lineArg.trim().length > 0) ?? '';
+  const collapsed = firstLine.trim();
+  return collapsed.length > 200 ? `${collapsed.slice(0, 200)}...` : collapsed;
+};
+
+/**
+ * Classifies an enrollment row. See TEnrollmentState for why NULL and 0 are not
+ * the same answer.
+ */
+export const enrollmentState = (enrollmentArg: IRemoteControlEnrollment): TEnrollmentState => {
+  if (enrollmentArg.remoteControlEnabled === null) {
+    return 'unpaired';
+  }
+  return enrollmentArg.remoteControlEnabled === 0 ? 'disabled' : 'paired';
+};
+
+/** How many of these enrollments carry a working pairing. */
+export const countPaired = (enrollmentsArg: IRemoteControlEnrollment[]): number =>
+  enrollmentsArg.filter((enrollmentArg) => enrollmentState(enrollmentArg) === 'paired').length;
+
+/**
+ * Turns a failed Codex invocation into a diagnosis rather than an errno.
+ *
+ * A timeout and a missing binary are different problems with different fixes,
+ * and neither is "the stop command failed" -- surfacing the raw spawn error
+ * leaves the user to guess which one they hit.
+ */
+export const describeCodexFailure = (
+  binaryArg: string,
+  stdoutArg: string,
+  stderrArg: string,
+  spawnErrorArg: string | null,
+): string => {
+  if (spawnErrorArg && /ETIMEDOUT/i.test(spawnErrorArg)) {
+    return `the Codex app-server did not respond in time - it is running but unresponsive. Try \`codex app-server daemon restart\`, then run this again`;
+  }
+  if (spawnErrorArg && /ENOENT/i.test(spawnErrorArg)) {
+    return `the Codex CLI "${binaryArg}" was not found - put it on PATH or set AUTHSWITCH_CODEX_BIN to its full path`;
+  }
+  return summariseProcessOutput(stdoutArg, stderrArg, spawnErrorArg);
+};

package/ts/index.ts

@@ -0,0 +1,28 @@
+export * from './interfaces.js';
+export * from './interfaces.harness.js';
+export * from './interfaces.list.js';
+export * from './classes.codexharness.js';
+export * from './classes.opencodeharness.js';
+export * from './classes.claudecodeharness.js';
+export * from './classes.claudestatus.js';
+export * from './classes.codexstatus.js';
+export * from './classes.codexpreuse.js';
+export * from './preuse.js';
+export * from './helpers.js';
+export * from './classes.codexhome.js';
+export * from './classes.codexauth.js';
+export * from './classes.remotecontrol.js';
+export * from './classes.stashstore.js';
+export * from './classes.codexdaemon.js';
+export * from './classes.codexswitcher.js';
+export * from './classes.cli.js';
+export * from './classes.login.js';
+export * from './classes.operations.js';
+export * from './classes.service.js';
+
+import { AuthSwitchCli } from './classes.cli.js';
+
+export const runCli = async (argvArg: string[] = process.argv.slice(2)): Promise<void> => {
+  const exitCode = await new AuthSwitchCli().run(argvArg);
+  process.exitCode = exitCode;
+};

package/ts/interfaces.harness.ts

@@ -0,0 +1,112 @@
+import type { TAuthLoginPrompt, TAuthLoginFlow } from './classes.login.js';
+
+export interface IHarnessLoginProvider { providerId: string; label: string; flows: TAuthLoginFlow[]; }
+export interface IHarnessLoginOptions { providerId: string; flow: TAuthLoginFlow; }
+export interface IHarnessLoginResult { outcome: IHarnessOutcome; account?: Pick<IHarnessAccount, 'id' | 'label' | 'slotId'>; }
+
+export interface IHarnessLoginHandle {
+  readonly prompt: TAuthLoginPrompt;
+  /** Completion saves the new account without activating it. No credentials cross this interface. */
+  readonly completion: Promise<IHarnessLoginResult>;
+  cancel(): Promise<void>;
+  close(): Promise<void>;
+}
+
+/** Account IDs are opaque and scoped to one harness. Credentials never cross this interface. */
+export interface IHarnessAccount {
+  id: string;
+  label: string;
+  /** Accounts in different slots can be active together (for example OpenCode providers). */
+  slotId?: string;
+  isActive: boolean;
+  isStashed: boolean;
+  savedAt: string | null;
+  details: string[];
+}
+
+export interface IHarnessState {
+  accounts: IHarnessAccount[];
+  /** Explains why an active login cannot be saved, when applicable. */
+  saveUnavailableReason: string | null;
+}
+
+export interface IHarnessAccountStatus {
+  /** Provider-reported facts, already labelled with their units and provenance. */
+  facts: IHarnessStatusFact[];
+  /** Missing/failed information is explicit and never represented as zero usage. */
+  problems: string[];
+  /** Optional structured data for shared presentation; never parse the display facts. */
+  summary?: IHarnessStatusSummary;
+}
+
+export interface IHarnessStatusFact {
+  label: string;
+  value: string;
+  /** Optional display group; ungrouped adapters use Additional information. */
+  section?: string;
+  /** The fact duplicates this structured field; omit it only when that field is displayed. */
+  summaryKey?: 'subscription' | 'billing' | 'usageWindows' | 'resets' | 'resetDetails';
+}
+
+export interface IHarnessStatusSummary {
+  /** A plan name does not imply an active billing status. */
+  subscription?: { plan: string; source: 'live' | 'stored' };
+  /** Live billing information only. Never infer these fields from a plan or entitlement expiry. */
+  billing?: { hasActiveSubscription?: boolean; autoRenew?: boolean; renewsAt?: string; cancelsAt?: string; expiresAt?: string };
+  /** Missing windows are unknown, not unused. Times are ISO 8601 UTC. */
+  usageWindows?: {
+    label: string;
+    /** Feature-specific quotas do not determine the general account summary. Omission means account. */
+    scope?: 'account' | 'feature';
+    durationSeconds: number;
+    usedPercent: number;
+    resetAt: string | null;
+  }[];
+  resets?: {
+    available: number;
+    /** May be a partial list. Omission means the detail lookup was unavailable. */
+    details?: { status: string; kind: string; expiresAt: string | null }[];
+  };
+}
+
+export interface IHarnessOutcome {
+  lines: string[];
+  problems: string[];
+}
+
+/** A single text-only inference request. Credentials remain inside the adapter. */
+export interface IHarnessPreuseOptions {
+  prompt: string;
+  model?: string;
+  signal?: AbortSignal;
+}
+
+export interface IHarnessPreuseResult {
+  model: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+}
+
+export type THarnessResult<T> = T | Promise<T>;
+
+/** Each adapter owns its credential storage, account matching, status API and process lifecycle. */
+export interface IAuthHarness {
+  readonly id: string;
+  readonly label: string;
+  readonly loginHint: string;
+  readonly diagnosticsLabel: string;
+  readState(): THarnessResult<IHarnessState>;
+  readAccountStatus(accountIdArg: string): Promise<IHarnessAccountStatus>;
+  readonly loginProviders?: IHarnessLoginProvider[];
+  beginLogin?(options: IHarnessLoginOptions): Promise<IHarnessLoginHandle>;
+  /** Optional quota-consuming capability; never changes the active login. */
+  preuseAccount?(accountIdArg: string, optionsArg: IHarnessPreuseOptions): Promise<IHarnessPreuseResult>;
+  resolveAccount(referenceArg: string): THarnessResult<{ id: string } | { candidates: string[] }>;
+  saveCurrent(optionsArg: { keepActive: boolean; accountId?: string }): THarnessResult<IHarnessOutcome>;
+  /** Preserve and verify the outgoing credential even when invoked without the interactive guide. */
+  switchAccount(accountIdArg: string): THarnessResult<IHarnessOutcome>;
+  /** Remove the saved copy only, preserving the active login. */
+  removeAccount(accountIdArg: string): THarnessResult<IHarnessOutcome>;
+  diagnose(): THarnessResult<IHarnessOutcome>;
+}

package/ts/interfaces.list.ts

@@ -0,0 +1,19 @@
+import type { IHarnessAccount, IHarnessAccountStatus } from './interfaces.harness.js';
+
+/** Credential-free, versioned output of list --json. Missing status fields stay omitted. */
+export interface IAccountList {
+  schemaVersion: 2;
+  generatedAt: string;
+  complete: boolean;
+  harnesses: IHarnessAccountList[];
+}
+
+export interface IHarnessAccountList {
+  id: string;
+  label: string;
+  loginHint: string;
+  saveUnavailableReason: string | null;
+  accounts: (IHarnessAccount & { status: IHarnessAccountStatus })[];
+  /** A state lookup failure is distinct from an empty account list. */
+  problems: string[];
+}

package/ts/interfaces.ts

@@ -0,0 +1,158 @@
+/**
+ * Lowercase harness namespace. Adapters are registered independently of the CLI.
+ */
+export type THarnessName = string;
+
+/**
+ * Where the currently active Codex credential lives.
+ * - 'file'    -> $CODEX_HOME/auth.json
+ * - 'keyring' -> an OS keyring entry (authswitch cannot move these)
+ * - 'none'    -> no credential is active
+ */
+export type TAuthSource = 'file' | 'keyring' | 'none';
+
+/**
+ * How a stashed credential identifies its account.
+ * - 'chatgpt' -> ChatGPT OAuth login, identified by the id_token email claim
+ * - 'apikey'  -> plain API key login, which carries no email
+ */
+export type TAccountKind = 'chatgpt' | 'apikey';
+
+/**
+ * Identity extracted from a Codex credential without ever exposing the token.
+ */
+export interface ICodexIdentity {
+  kind: TAccountKind;
+  /** The account email, or a synthetic `apikey:<fingerprint>` label for API-key logins. */
+  email: string;
+  accountId: string | null;
+  planType: string | null;
+  userId: string | null;
+}
+
+/**
+ * The active credential as found on disk, plus its decoded identity.
+ * `raw` is the verbatim file content and is never logged.
+ */
+export interface IActiveAuth {
+  source: TAuthSource;
+  authFilePath: string;
+  identity: ICodexIdentity | null;
+  raw: string | null;
+}
+
+/**
+ * One row of the `remote_control_enrollments` table in Codex' state database.
+ * This is the record that binds a Codex app-server to a paired ChatGPT client.
+ */
+export interface IRemoteControlEnrollment {
+  websocketUrl: string;
+  accountId: string;
+  appServerClientName: string;
+  serverId: string;
+  environmentId: string;
+  serverName: string;
+  updatedAt: number;
+  remoteControlEnabled: number | null;
+}
+
+/**
+ * Metadata stored alongside a stashed credential.
+ */
+export interface IStashEntry {
+  email: string;
+  kind: TAccountKind;
+  accountId: string | null;
+  planType: string | null;
+  userId: string | null;
+  stashedAt: string;
+  codexHome: string;
+  enrollments: IRemoteControlEnrollment[];
+}
+
+/**
+ * How far along an enrollment row is.
+ *
+ * Codex writes the row when an account registers a server, but its upsert
+ * deliberately leaves `remote_control_enabled` alone, so a freshly logged-in
+ * account starts at NULL. A row is therefore not the same thing as a working
+ * pairing, and the three states have to stay distinguishable:
+ * - 'paired'      -> remote_control_enabled = 1, reachable from the ChatGPT app
+ * - 'disabled'    -> remote_control_enabled = 0, deliberately turned off
+ * - 'unpaired'    -> remote_control_enabled IS NULL, registered but never paired
+ */
+export type TEnrollmentState = 'paired' | 'disabled' | 'unpaired';
+
+/**
+ * A stash entry plus the derived facts the CLI needs for display.
+ */
+export interface IStashListing extends IStashEntry {
+  slug: string;
+  isActive: boolean;
+  /** Rows stashed for this account, paired or not. */
+  enrollmentsTotal: number;
+  /** Rows that actually carry a working pairing. */
+  enrollmentsPaired: number;
+  /**
+   * True only when at least one enrollment is paired. A registered-but-unpaired
+   * row is not remote control, and reporting it as such would tell the user the
+   * account is reachable when it is not.
+   */
+  hasRemoteControl: boolean;
+}
+
+/**
+ * The outcome of running a Codex subcommand.
+ */
+export interface ICommandResult {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  /** Set when the process could not be spawned at all, or timed out. */
+  spawnError: string | null;
+}
+
+/**
+ * What `codex app-server daemon version` reports about the managed daemon.
+ */
+export interface IDaemonStatus {
+  running: boolean;
+  backend: string | null;
+  appServerVersion: string | null;
+  cliVersion: string | null;
+  socketPath: string | null;
+}
+
+export interface ICodexSwitcherOptions {
+  codexHome?: string;
+  stashRoot?: string;
+  codexBinary?: string;
+}
+
+/**
+ * Result of stashing the active credential.
+ *
+ * `complete` is false when the credential was saved but something the user
+ * cares about did not finish -- the app-server failing to come back, say.
+ */
+export interface IStashResult {
+  entry: IStashEntry;
+  daemonRestarted: boolean;
+  complete: boolean;
+  notes: string[];
+  problems: string[];
+}
+
+/**
+ * Result of a switch, used for reporting and for the CLI exit code.
+ */
+export interface ISwitchResult {
+  from: string | null;
+  to: string;
+  enrollmentsRestored: number;
+  daemonRestarted: boolean;
+  complete: boolean;
+  notes: string[];
+  problems: string[];
+}

package/ts/plugins.ts

@@ -0,0 +1,20 @@
+// Node native modules
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as childProcess from 'node:child_process';
+import * as crypto from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+
+export { childProcess, crypto, fs, os, path, DatabaseSync };
+
+// @push.rocks modules
+import * as smartconsole from '@push.rocks/smartconsole';
+export { smartconsole };
+
+// @modelprofile.com modules
+import * as flexModels from '@modelprofile.com/flexharness-models';
+import * as flexOpenAi from '@modelprofile.com/flexharness-providers/openai';
+import * as flexAuth from '@modelprofile.com/flexharness-providers/auth';
+import * as flexAccounts from '@modelprofile.com/flexharness-providers/accounts';
+export { flexModels, flexOpenAi, flexAuth, flexAccounts };

package/ts/preuse.ts

@@ -0,0 +1,15 @@
+import type { IHarnessPreuseOptions } from './interfaces.harness.js';
+
+export const defaultPreusePrompt = 'Write 2000 words about strawberries.';
+
+/** Only fixed local messages may cross the inference error boundary. */
+export class PreuseError extends Error {}
+
+export const validatePreuseOptions = (optionsArg: IHarnessPreuseOptions): void => {
+  if (typeof optionsArg.prompt !== 'string' || !optionsArg.prompt.trim() || Buffer.byteLength(optionsArg.prompt, 'utf8') > 16_384) {
+    throw new PreuseError('The preuse prompt must contain between 1 and 16384 UTF-8 bytes.');
+  }
+  if (optionsArg.model !== undefined && (typeof optionsArg.model !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,127}$/.test(optionsArg.model))) {
+    throw new PreuseError('The preuse model must be a valid model identifier of at most 128 characters.');
+  }
+};