typeclaw 0.32.0 → 0.33.0

package/src/cli/provider.ts

@@ -2,10 +2,16 @@ import { cancel, intro, isCancel, log, password, select } from '@clack/prompts'
 import { defineCommand } from 'citty'
 
 import {
+  KNOWN_PROVIDER_VENDORS,
   KNOWN_PROVIDERS,
+  listKnownProviderVendorIds,
+  providerIdsForVendor,
   supportsApiKey as providerSupportsApiKey,
   supportsOAuth as providerSupportsOAuth,
+  variantHint,
+  variantLabel,
   type KnownProviderId,
+  type KnownProviderVendorId,
 } from '@/config/providers'
 import {
   addProvider,
@@ -270,15 +276,40 @@ function validateKnownProvider(input: string): KnownProviderId {
 
 async function resolveProviderForAdd(input: string | undefined): Promise<KnownProviderId> {
   if (input !== undefined) return validateKnownProvider(input)
-  const ids = Object.keys(KNOWN_PROVIDERS) as KnownProviderId[]
-  const choice = await select<KnownProviderId>({
+  const vendorId = await pickVendorToAdd()
+  return await pickVariantToAdd(vendorId)
+}
+
+async function pickVendorToAdd(): Promise<KnownProviderVendorId> {
+  const vendorIds = listKnownProviderVendorIds()
+  const choice = await select<KnownProviderVendorId>({
     message: 'Pick a provider to add',
-    options: ids.map((id) => ({
+    options: vendorIds.map((id) => ({
       value: id,
-      label: KNOWN_PROVIDERS[id].name,
-      hint: authHint(id),
+      label: KNOWN_PROVIDER_VENDORS[id].name,
+      hint: vendorAuthHint(id),
     })),
-    initialValue: ids[0],
+    initialValue: vendorIds[0],
+  })
+  if (isCancel(choice)) {
+    cancel('Aborted.')
+    process.exit(0)
+  }
+  return choice
+}
+
+async function pickVariantToAdd(vendorId: KnownProviderVendorId): Promise<KnownProviderId> {
+  const variants = providerIdsForVendor(vendorId)
+  if (variants.length === 1) return variants[0]!
+  const choice = await select<KnownProviderId>({
+    message: `Pick a ${KNOWN_PROVIDER_VENDORS[vendorId].name} option`,
+    options: variants.map((id) => {
+      const hint = variantHint(vendorId, id)
+      return hint !== undefined
+        ? { value: id, label: variantLabel(vendorId, id), hint }
+        : { value: id, label: variantLabel(vendorId, id) }
+    }),
+    initialValue: variants[0],
   })
   if (isCancel(choice)) {
     cancel('Aborted.')
@@ -378,10 +409,10 @@ async function runOAuthLogin(cwd: string, providerId: KnownProviderId): Promise<
   }
 }
 
-function authHint(id: KnownProviderId): string {
-  const provider = KNOWN_PROVIDERS[id]
-  const apiKey = providerSupportsApiKey(provider)
-  const oauth = providerSupportsOAuth(provider)
+function vendorAuthHint(vendorId: KnownProviderVendorId): string {
+  const providers = providerIdsForVendor(vendorId)
+  const apiKey = providers.some((id) => providerSupportsApiKey(KNOWN_PROVIDERS[id]))
+  const oauth = providers.some((id) => providerSupportsOAuth(KNOWN_PROVIDERS[id]))
   if (apiKey && oauth) return 'API key or OAuth'
   if (oauth) return 'OAuth only'
   return 'API key'

package/src/config/config.ts

@@ -338,17 +338,29 @@ export const networkSchema = z
 
 export type NetworkConfig = z.infer<typeof networkSchema>
 
-// `realProc` opts the per-tool bwrap sandbox into the 'real-proc' strategy
-// (src/sandbox/build.ts): a fresh procfs scoped to a new PID namespace so
-// external-package runners (`bunx`, `bun add <pkg>`, `bun run <pkg-bin>`) get a
-// working /proc/self/{fd,maps} and stop aborting with Bun's "NotDir". Default
-// `false` keeps the universally-portable '--tmpfs /proc' profile, under which
-// sandboxed external-package execution is unsupported by design. Turning it on
-// makes `typeclaw start` grant the container CAP_SYS_ADMIN (required to mount
-// proc for the new PID namespace), which is a deliberate posture change on the
-// single-tenant outer boundary — see docs/internals/sandbox.mdx. PID isolation
-// and the /proc/N/environ leak guard are both preserved; the trade is the
-// CAP_SYS_ADMIN grant, not sandbox strength.
+// `realProc` opts the per-tool bwrap sandbox (src/sandbox/build.ts) into the
+// stricter 'real-proc' /proc strategy: a fresh procfs scoped to a NEW PID
+// namespace via `unshare --pid --fork --mount --mount-proc`. It adds full PID
+// isolation (the agent runtime's pids are absent from the sandbox namespace),
+// but needs CAP_SYS_ADMIN to mount proc — so `typeclaw start` grants the
+// container `--cap-add=SYS_ADMIN` only when this is set.
+//
+// Default `false`, because external-package execution (`bunx agent-*`, `bun add
+// <pkg>`, `bun run <pkg-bin>` — the core subagent workflow) no longer needs it:
+// the default 'proc-bind' strategy `--ro-bind`s the container's already-real
+// procfs into the sandbox with NO CAP_SYS_ADMIN, giving the runner's child a
+// working /proc/self/{fd,maps} so it stops aborting with Bun's "NotDir". The
+// agent runtime's /proc/N/environ (FIREWORKS_API_KEY) stays unreadable because
+// bwrap's --unshare-user puts the sandbox in a child user namespace the kernel
+// won't let read a parent-userns process's environ — verified at runtime by a
+// probe before the strategy is selected (src/sandbox/availability.ts). Avoiding
+// the broad CAP_SYS_ADMIN grant by default is a smaller blast radius than the
+// non-secret PID metadata 'proc-bind' exposes — see docs/internals/sandbox.mdx.
+//
+// Set `true` only to add the PID-isolation posture on a host where the proc
+// mount actually works (bare-metal Linux, Docker Desktop — NOT OrbStack, which
+// rejects the mount even with the cap; there the runtime falls back to
+// 'proc-bind' regardless). The cost is the CAP_SYS_ADMIN grant on the container.
 export const sandboxSchema = z
   .object({
     realProc: z.boolean().default(false),

package/src/config/providers.ts

@@ -41,6 +41,17 @@ type KnownProvider = {
 // e.g. `OPENAI_API_KEY`). For `oauth` providers, `oauthProviderId` MUST match
 // a pi-ai OAuth provider id exactly, otherwise `authStorage.login()` will
 // throw "Unknown OAuth provider".
+//
+// Granularity rule (split vs merge): a provider id is the runtime API surface,
+// not the brand. Different API call => different provider id; same API call =>
+// same provider id. "Same API call" means same endpoint + same wire transport.
+// So `anthropic` is ONE id because api-key and oauth hit the same
+// /v1/messages endpoint (only the auth header differs), while `openai` /
+// `openai-codex` and `zai` / `zai-coding` are SEPARATE ids because each pair
+// targets different endpoints (and env vars). The user-facing brand grouping
+// lives in `KNOWN_PROVIDER_VENDORS` below — keep it out of this decision.
+// Renaming an id is a breaking change to secrets.json keys and typeclaw.json
+// model refs; only do it behind a migration in a dedicated major-version PR.
 export const KNOWN_PROVIDERS = {
   openai: {
     id: 'openai',
@@ -119,13 +130,12 @@ export const KNOWN_PROVIDERS = {
   // these ids work end-to-end as long as the Codex backend itself accepts
   // them, which it does for ChatGPT Plus/Pro accounts as of 2026-05-10.
   //
-  // Position-load-bearing: must stay adjacent to `openai`. The init wizard's
-  // provider picker, `provider --help`'s `id | id | ...` listing, and the
-  // generated JSON schema's model-ref enum all derive their ordering from
-  // Object.keys() iteration on this literal. Alphabetizing the registry
-  // would scatter `openai-codex` after `fireworks` and re-introduce the
-  // "OpenAI ... Anthropic ... OpenAI" picker order this comment exists to
-  // prevent.
+  // Position-load-bearing: must stay adjacent to `openai`. `provider --help`'s
+  // `id | id | ...` listing and the generated JSON schema's model-ref enum
+  // derive their ordering from Object.keys() iteration on this literal, so
+  // alphabetizing the registry would scatter `openai-codex` after `fireworks`.
+  // (The init wizard's picker no longer depends on this order — it groups by
+  // `KNOWN_PROVIDER_VENDORS` below.)
   'openai-codex': {
     id: 'openai-codex',
     name: 'OpenAI Codex (ChatGPT Plus/Pro)',
@@ -453,10 +463,297 @@ export const KNOWN_PROVIDERS = {
       },
     },
   },
+  // xAI (Grok). The native developer API at api.x.ai/v1 is OpenAI-compatible
+  // (Bearer auth + /chat/completions shape), so models go through pi-ai's
+  // `openai-completions` adapter with a custom baseUrl — same trick as
+  // Fireworks and Z.AI. This is a DUAL-AUTH provider like `anthropic`:
+  //   * api-key — XAI_API_KEY (the standard xAI env var), a plain Bearer token.
+  //   * oauth — Grok subscription login via xAI's OIDC server (auth.x.ai),
+  //     authorization-code + PKCE. pi-ai ships no built-in xAI OAuth provider,
+  //     so `oauthProviderId: 'xai'` resolves to the custom provider registered
+  //     in src/secrets/oauth-xai.ts (registered from createSecretsStoreForAgent
+  //     so both init-login and runtime-refresh see it). The dual-auth runtime
+  //     rule in src/agent/auth.ts applies: an OAuth credential on disk wins over
+  //     XAI_API_KEY in .env — remove it (`typeclaw provider remove xai`) to fall
+  //     back to the key.
+  //
+  // Costs and context windows mirror docs.x.ai/developers/models and the raw
+  // /v1/models price fields as of 2026-06-08 (xAI quotes prices in cents per
+  // 100M tokens; e.g. grok-4.3 prompt 12500 = $1.25/1M). grok-4.3 is the
+  // flagship default; grok-build-0.1 is the coding-tuned model. The
+  // grok-4.20-0309 snapshots are pinned weights for reproducible runs.
+  //
+  // The earlier grok-4 / grok-4-fast / grok-code-fast-1 ids were RETIRED on
+  // 2026-05-15 — they still resolve but silently redirect (and bill) at the
+  // grok-4.3 / grok-build-0.1 rates, so they are intentionally NOT listed.
+  //
+  // cacheWrite is 0: xAI publishes no cache-write price (caching is implicit,
+  // billed only at the cacheRead rate). Models 1-4 also carry a long-context
+  // tier (2x rates above a 200k-token request); pi-ai's Model shape can't
+  // express tiered pricing, so the standard rate is used and the breakpoint is
+  // noted here. When refreshing, rerun `scripts/generate-schema.ts`.
+  xai: {
+    id: 'xai',
+    name: 'xAI (Grok)',
+    baseUrl: 'https://api.x.ai/v1',
+    auth: ['api-key', 'oauth'],
+    apiKeyEnv: 'XAI_API_KEY',
+    oauthProviderId: 'xai',
+    models: {
+      'grok-4.3': {
+        id: 'grok-4.3',
+        name: 'Grok 4.3',
+        api: 'openai-completions',
+        provider: 'xai',
+        baseUrl: 'https://api.x.ai/v1',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+        contextWindow: 1000000,
+        maxTokens: 64000,
+      },
+      'grok-4.20-0309-reasoning': {
+        id: 'grok-4.20-0309-reasoning',
+        name: 'Grok 4.20 (Reasoning)',
+        api: 'openai-completions',
+        provider: 'xai',
+        baseUrl: 'https://api.x.ai/v1',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+        contextWindow: 1000000,
+        maxTokens: 64000,
+      },
+      'grok-4.20-0309-non-reasoning': {
+        id: 'grok-4.20-0309-non-reasoning',
+        name: 'Grok 4.20 (Non-Reasoning)',
+        api: 'openai-completions',
+        provider: 'xai',
+        baseUrl: 'https://api.x.ai/v1',
+        reasoning: false,
+        input: ['text', 'image'],
+        cost: { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 },
+        contextWindow: 1000000,
+        maxTokens: 64000,
+      },
+      'grok-build-0.1': {
+        id: 'grok-build-0.1',
+        name: 'Grok Build 0.1',
+        api: 'openai-completions',
+        provider: 'xai',
+        baseUrl: 'https://api.x.ai/v1',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 1.0, output: 2.0, cacheRead: 0.2, cacheWrite: 0 },
+        contextWindow: 256000,
+        maxTokens: 64000,
+      },
+    },
+  },
+  // MiniMax (minimax.io) pay-as-you-go API. OpenAI-compatible (Bearer auth +
+  // /chat/completions shape), so models go through pi-ai's `openai-completions`
+  // adapter with a custom baseUrl — same trick as Fireworks and Z.AI.
+  //
+  // Endpoint choice: the international endpoint (api.minimax.io) is the global
+  // surface; the China endpoint (api.minimaxi.com) is a regional alternative on
+  // the same protocol. We pin the international one here — operators who need the
+  // China gateway can front it with an OpenAI-compatible proxy.
+  //
+  // Model lineup mirrors the OpenAI-compatible model enum on
+  // platform.minimax.io as of 2026-06-08: MiniMax-M3 (flagship, 1M context,
+  // image input, controllable reasoning) plus the M2 reasoning series
+  // (204,800 context, reasoning always on, text-only). The `-highspeed`
+  // billing-tier variants and the native-only `M2-her` / `MiniMax-Text-01` /
+  // `abab*` models are intentionally omitted — the first are duplicate weights
+  // on a pricier surface, the rest don't serve the OpenAI-compatible
+  // /chat/completions route this adapter speaks. Costs are USD per 1M tokens
+  // from docs/guides/pricing-paygo (standard tier): M3 reflects the permanent
+  // 50%-off ≤512K-input rate (input 0.30 / output 1.20 / cacheRead 0.06; M3 has
+  // no separate cache-write rate). M2.7 caches at 0.06 read / 0.375 write; the
+  // M2.5/M2.1/M2 series at 0.03 read / 0.375 write.
+  //
+  // M3 tiered pricing is NOT modeled: this single cost record only encodes the
+  // ≤512K-input tier. The >512K tier (input 0.60 / output 2.40 / cacheRead 0.12)
+  // is a limited-availability surcharge that pi-ai's flat per-model cost shape
+  // can't represent, so long-context M3 sessions above 512K under-report cost.
+  minimax: {
+    id: 'minimax',
+    name: 'MiniMax',
+    baseUrl: 'https://api.minimax.io/v1',
+    auth: ['api-key'],
+    apiKeyEnv: 'MINIMAX_API_KEY',
+    oauthProviderId: null,
+    models: {
+      'MiniMax-M3': {
+        id: 'MiniMax-M3',
+        name: 'MiniMax M3',
+        api: 'openai-completions',
+        provider: 'minimax',
+        baseUrl: 'https://api.minimax.io/v1',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0 },
+        contextWindow: 1000000,
+        maxTokens: 524288,
+      },
+      'MiniMax-M2.7': {
+        id: 'MiniMax-M2.7',
+        name: 'MiniMax M2.7',
+        api: 'openai-completions',
+        provider: 'minimax',
+        baseUrl: 'https://api.minimax.io/v1',
+        reasoning: true,
+        input: ['text'],
+        cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
+        contextWindow: 204800,
+        maxTokens: 204800,
+      },
+      'MiniMax-M2.5': {
+        id: 'MiniMax-M2.5',
+        name: 'MiniMax M2.5',
+        api: 'openai-completions',
+        provider: 'minimax',
+        baseUrl: 'https://api.minimax.io/v1',
+        reasoning: true,
+        input: ['text'],
+        cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.375 },
+        contextWindow: 204800,
+        maxTokens: 204800,
+      },
+      'MiniMax-M2.1': {
+        id: 'MiniMax-M2.1',
+        name: 'MiniMax M2.1',
+        api: 'openai-completions',
+        provider: 'minimax',
+        baseUrl: 'https://api.minimax.io/v1',
+        reasoning: true,
+        input: ['text'],
+        cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.375 },
+        contextWindow: 204800,
+        maxTokens: 204800,
+      },
+      'MiniMax-M2': {
+        id: 'MiniMax-M2',
+        name: 'MiniMax M2',
+        api: 'openai-completions',
+        provider: 'minimax',
+        baseUrl: 'https://api.minimax.io/v1',
+        reasoning: true,
+        input: ['text'],
+        cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.375 },
+        contextWindow: 204800,
+        maxTokens: 204800,
+      },
+    },
+  },
 } as const satisfies Record<string, KnownProvider>
 
 export type KnownProviderId = keyof typeof KNOWN_PROVIDERS
 
+// UX-only grouping of provider ids under one vendor for the init/`provider
+// add` pickers. Deliberately does NOT touch the runtime contract:
+// `KnownProviderId`, `KnownModelRef`, secrets.json keys, auth resolution, and
+// the generated schema all stay keyed on the flat ids in `KNOWN_PROVIDERS`.
+// The follow-up "variant" prompt resolves a concrete provider id, then
+// `pickAuthMethod` runs as before; it is auto-resolved for single-provider
+// vendors (Fireworks, Anthropic). `variants` copy lets the prompt read as an
+// auth choice for OpenAI but a plan choice for Z.AI (both api-key, different
+// billing surfaces).
+type KnownProviderVendor = {
+  id: string
+  name: string
+  providers: ReadonlyArray<KnownProviderId>
+  variants?: Partial<Record<KnownProviderId, { label: string; hint?: string }>>
+}
+
+// Ordered by product priority for the picker — independent of the
+// `KNOWN_PROVIDERS` declaration order (which stays load-bearing for the schema
+// enum and `provider --help` listing). Every provider id below MUST appear in
+// exactly one vendor; `providers.test.ts` enforces the partition.
+export const KNOWN_PROVIDER_VENDORS = {
+  openai: {
+    id: 'openai',
+    name: 'OpenAI',
+    providers: ['openai', 'openai-codex'],
+    variants: {
+      openai: { label: 'API key', hint: 'OpenAI API platform' },
+      'openai-codex': { label: 'OAuth (ChatGPT Plus/Pro)', hint: 'ChatGPT subscription' },
+    },
+  },
+  anthropic: {
+    id: 'anthropic',
+    name: 'Anthropic',
+    providers: ['anthropic'],
+  },
+  fireworks: {
+    id: 'fireworks',
+    name: 'Fireworks',
+    providers: ['fireworks'],
+  },
+  zai: {
+    id: 'zai',
+    name: 'Z.AI',
+    providers: ['zai', 'zai-coding'],
+    variants: {
+      zai: { label: 'Pay-as-you-go', hint: 'standard API billing' },
+      'zai-coding': { label: 'Coding Plan', hint: 'GLM Coding Plan subscription' },
+    },
+  },
+  xai: {
+    id: 'xai',
+    name: 'xAI (Grok)',
+    providers: ['xai'],
+  },
+  // Single-provider vendor: pay-as-you-go and Token Plan are the SAME provider
+  // id (same /v1 endpoint, same Bearer transport — only the key prefix differs),
+  // so per the granularity rule above MiniMax is one id like Anthropic, not a
+  // zai-style split. The picker shows one row and skips the variant prompt; the
+  // pay-as-you-go-vs-Token-Plan dashboard hint is handled in the key-entry step.
+  minimax: {
+    id: 'minimax',
+    name: 'MiniMax',
+    providers: ['minimax'],
+  },
+} as const satisfies Record<string, KnownProviderVendor>
+
+export type KnownProviderVendorId = keyof typeof KNOWN_PROVIDER_VENDORS
+
+export function listKnownProviderVendorIds(): KnownProviderVendorId[] {
+  return Object.keys(KNOWN_PROVIDER_VENDORS) as KnownProviderVendorId[]
+}
+
+export function providerIdsForVendor(vendorId: KnownProviderVendorId): ReadonlyArray<KnownProviderId> {
+  return KNOWN_PROVIDER_VENDORS[vendorId].providers
+}
+
+export function vendorForProviderId(providerId: KnownProviderId): KnownProviderVendorId {
+  for (const vendorId of listKnownProviderVendorIds()) {
+    if ((KNOWN_PROVIDER_VENDORS[vendorId].providers as ReadonlyArray<KnownProviderId>).includes(providerId)) {
+      return vendorId
+    }
+  }
+  throw new Error(`Provider ${providerId} is not assigned to any vendor in KNOWN_PROVIDER_VENDORS`)
+}
+
+function variantCopy(
+  vendorId: KnownProviderVendorId,
+  providerId: KnownProviderId,
+): { label: string; hint?: string } | undefined {
+  const vendor: KnownProviderVendor = KNOWN_PROVIDER_VENDORS[vendorId]
+  return vendor.variants?.[providerId]
+}
+
+// Falls back to the provider's own name when a vendor supplies no variant copy
+// (single-provider vendors never render this prompt, so the fallback only
+// guards against an incomplete `variants` map on a multi-provider vendor).
+export function variantLabel(vendorId: KnownProviderVendorId, providerId: KnownProviderId): string {
+  return variantCopy(vendorId, providerId)?.label ?? KNOWN_PROVIDERS[providerId].name
+}
+
+export function variantHint(vendorId: KnownProviderVendorId, providerId: KnownProviderId): string | undefined {
+  return variantCopy(vendorId, providerId)?.hint
+}
+
 export type KnownModelRef = {
   [P in KnownProviderId]: `${P}/${Extract<keyof (typeof KNOWN_PROVIDERS)[P]['models'], string>}`
 }[KnownProviderId]

package/src/container/start.ts

@@ -514,16 +514,21 @@ export async function planStart({
     }
   }
 
-  // sandbox.realProc opts the per-tool bwrap sandbox into the 'real-proc'
-  // strategy (src/sandbox/build.ts), which prefixes the sandbox with
+  // sandbox.realProc (default FALSE) opts into the per-tool bwrap sandbox's
+  // 'real-proc' strategy (src/sandbox/build.ts), which prefixes the sandbox with
   // `unshare --pid --fork --mount --mount-proc`. Mounting a fresh procfs for the
   // new PID namespace needs real CAP_SYS_ADMIN — seccomp=unconfined alone is not
   // enough (it only unblocks the unshare/clone SYSCALLS; the kernel still
-  // rejects mount(2) of proc without the capability). This is the deliberate
-  // posture change documented in docs/internals/sandbox.mdx: the default keeps
-  // the narrower seccomp-only profile, and the operator grants the broad
-  // "new root" capability ONLY by opting into real-proc. Placed before the
-  // image tag (like --cap-add=NET_ADMIN) so docker applies it at run time.
+  // rejects mount(2) of proc without the capability). So the grant is gated on
+  // the flag and is OFF by default: external-package execution (`bunx agent-*`)
+  // no longer needs it — the default 'proc-bind' strategy gives the runner real
+  // /proc without any outer capability (see docs/internals/sandbox.mdx). Setting
+  // realProc:true adds the stricter PID-isolation posture at the cost of this
+  // broad "new root" grant. The container-side strategy resolution still probes
+  // whether the mount actually works (canMountRealProc) and falls back to
+  // proc-bind on runtimes where the cap is a no-op (e.g. OrbStack), so this grant
+  // is necessary-but-not-sufficient by design. Placed before the image tag (like
+  // --cap-add=NET_ADMIN) so docker applies it at run time.
   if (cfg.sandbox.realProc) {
     runArgs.push('--cap-add=SYS_ADMIN')
   }

package/src/init/find-agent-dir.ts

@@ -0,0 +1,44 @@
+import { existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+// Dependency-free agent-folder resolution. Kept out of `src/init/index.ts` so
+// the host CLI entry (`src/cli/index.ts`) can locate the agent folder at the
+// dispatch boundary WITHOUT pulling in the heavy init barrel (which statically
+// imports @/config, @/config/providers, @/container, @/secrets, @/tui — a
+// ~190ms module graph). This module MUST NOT import from the init barrel,
+// config, container, or plugin modules; keep the dependency direction one-way.
+
+export const CONFIG_FILE = 'typeclaw.json'
+
+export function isInitialized(dir: string): boolean {
+  return existsSync(join(dir, CONFIG_FILE))
+}
+
+// Walks upward from `start` looking for the agent folder (the dir containing
+// typeclaw.json). Returns the found dir, or null if nothing is found before
+// the walk hits a stop boundary.
+//
+// Stop boundaries (whichever comes first, checked at every level):
+//   1. The current dir contains typeclaw.json — return it.
+//   2. The current dir contains .git — return null. A .git boundary marks a
+//      project root; refusing to cross it prevents accidentally picking up an
+//      unrelated parent project, and matches how typeclaw itself initializes
+//      one .git per agent folder.
+//   3. We've reached the filesystem root — return null.
+//
+// The `.git` check fires AFTER the typeclaw.json check at the same level so
+// that walking up from a subdir of the agent (e.g. `<agent>/workspace/`) still
+// resolves to the agent root, even though the agent root itself contains both
+// typeclaw.json and .git.
+export function findAgentDir(start: string): string | null {
+  let dir = resolve(start)
+  const root = resolve(dir, '/')
+  while (true) {
+    if (existsSync(join(dir, CONFIG_FILE))) return dir
+    if (existsSync(join(dir, '.git'))) return null
+    if (dir === root) return null
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}

package/src/init/index.ts

@@ -19,6 +19,7 @@ import { createTui } from '@/tui'
 
 import { resolveBaseImageVersion, resolveScaffoldVersion } from './cli-version'
 import { buildDockerfile, DOCKERFILE } from './dockerfile'
+import { CONFIG_FILE, findAgentDir, isInitialized } from './find-agent-dir'
 import { installGithubWebhooksEagerly, type EagerGithubWebhookInstallResult } from './github-webhook-install'
 import { buildGitignore, GITIGNORE_FILE } from './gitignore'
 import { buildHatchingPrompt } from './hatching'
@@ -35,7 +36,8 @@ export { GITKEEP_FILE, PACKAGES_DIR, PUBLIC_DIR } from './paths'
 
 export { appendOrReplaceEnvKey, hasEnvKey, readEnvFile } from './env-file'
 
-const CONFIG_FILE = 'typeclaw.json'
+export { CONFIG_FILE, findAgentDir, isInitialized }
+
 const CRON_FILE = 'cron.json'
 const PACKAGE_FILE = 'package.json'
 
@@ -491,39 +493,6 @@ export function isDirectoryNonEmpty(dir: string): boolean {
   }
 }
 
-export function isInitialized(dir: string): boolean {
-  return existsSync(join(dir, CONFIG_FILE))
-}
-
-// Walks upward from `start` looking for the agent folder (the dir containing
-// typeclaw.json). Returns the found dir, or null if nothing is found before
-// the walk hits a stop boundary.
-//
-// Stop boundaries (whichever comes first, checked at every level):
-//   1. The current dir contains typeclaw.json — return it.
-//   2. The current dir contains .git — return null. A .git boundary marks a
-//      project root; refusing to cross it prevents accidentally picking up an
-//      unrelated parent project, and matches how typeclaw itself initializes
-//      one .git per agent folder.
-//   3. We've reached the filesystem root — return null.
-//
-// The `.git` check fires AFTER the typeclaw.json check at the same level so
-// that walking up from a subdir of the agent (e.g. `<agent>/workspace/`) still
-// resolves to the agent root, even though the agent root itself contains both
-// typeclaw.json and .git.
-export function findAgentDir(start: string): string | null {
-  let dir = resolve(start)
-  const root = resolve(dir, '/')
-  while (true) {
-    if (existsSync(join(dir, CONFIG_FILE))) return dir
-    if (existsSync(join(dir, '.git'))) return null
-    if (dir === root) return null
-    const parent = dirname(dir)
-    if (parent === dir) return null
-    dir = parent
-  }
-}
-
 const HATCHED_COMMIT_SUBJECT = 'Hatched 🐣'
 
 export async function isHatched(dir: string): Promise<boolean> {

package/src/init/models-dev.ts

@@ -20,6 +20,8 @@ const PROVIDER_TO_MODELS_DEV: Record<KnownProviderId, string> = {
   // catalog. models.dev tracks the underlying model metadata under `zai`,
   // so we route lookups there. The curated entries still get surfaced.
   'zai-coding': 'zai',
+  xai: 'xai',
+  minimax: 'minimax',
 }
 
 export type ModelOption = {

package/src/init/validate-api-key.ts

@@ -7,6 +7,8 @@ const PROVIDER_PROBE: Partial<Record<KnownProviderId, { url: string; authHeader:
   fireworks: { url: 'https://api.fireworks.ai/inference/v1/models', authHeader: 'bearer' },
   zai: { url: 'https://api.z.ai/api/paas/v4/models', authHeader: 'bearer' },
   'zai-coding': { url: 'https://api.z.ai/api/coding/paas/v4/models', authHeader: 'bearer' },
+  xai: { url: 'https://api.x.ai/v1/models', authHeader: 'bearer' },
+  minimax: { url: 'https://api.minimax.io/v1/models', authHeader: 'bearer' },
 }
 
 // When a base-URL override (ANTHROPIC_BASE_URL / OPENAI_BASE_URL) points at a
@@ -159,8 +161,19 @@ export const API_KEY_DASHBOARD_URL: Partial<Record<KnownProviderId, string>> = {
   fireworks: 'https://fireworks.ai/account/api-keys',
   zai: 'https://docs.z.ai/devpack/tool/claude#api-key',
   'zai-coding': 'https://docs.z.ai/devpack/tool/claude#api-key',
+  xai: 'https://console.x.ai',
+  minimax: 'https://platform.minimax.io/user-center/basic-information/interface-key',
 }
 
+// MiniMax sells the same `minimax` provider under two billing surfaces that
+// each hand out a key on a DIFFERENT dashboard page: pay-as-you-go API keys
+// (the API_KEY_DASHBOARD_URL above) and Token Plan "Subscription Keys"
+// (sk-cp-…, this URL). Both keys are Bearer tokens for the same api.minimax.io
+// endpoint and store in the same MINIMAX_API_KEY slot — the runtime doesn't
+// care which. The init wizard surfaces the choice only to deep-link the
+// correct dashboard, so a Token Plan subscriber isn't sent to the paygo page.
+export const MINIMAX_TOKEN_PLAN_DASHBOARD_URL = 'https://platform.minimax.io/user-center/payment/token-plan'
+
 export function providersWithApiKeyProbe(): KnownProviderId[] {
   return Object.keys(PROVIDER_PROBE) as KnownProviderId[]
 }