typeclaw 0.1.5 → 0.2.0

package/src/cli/model.ts

@@ -0,0 +1,244 @@
+import { cancel, intro, isCancel, select } from '@clack/prompts'
+import { defineCommand } from 'citty'
+
+import { addProfile, listModelProfiles, removeProfile, setProfile } from '@/config/models-mutation'
+import {
+  KNOWN_PROVIDERS,
+  listKnownModelRefs,
+  providerForModelRef,
+  type KnownModelRef,
+  type KnownProviderId,
+} from '@/config/providers'
+import { findAgentDir, isInitialized } from '@/init'
+
+import { c, done, errorLine } from './ui'
+
+const setSub = defineCommand({
+  meta: {
+    name: 'set',
+    description: 'set or update a model profile (default | fast | vision | <custom>)',
+  },
+  args: {
+    profile: {
+      type: 'positional',
+      description: 'profile name (typically `default`); omit to pick interactively',
+      required: false,
+    },
+    ref: {
+      type: 'positional',
+      description: '<provider>/<model> ref; omit to pick interactively',
+      required: false,
+    },
+    force: {
+      type: 'boolean',
+      description: 'write even when the target provider has no credentials configured',
+      required: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = ensureAgentDir()
+    const profile = args.profile ?? (await pickProfileName())
+    const ref = args.ref ?? (await pickModelRef())
+
+    intro(`Setting model profile: ${profile} → ${ref}`)
+
+    const result = setProfile(cwd, profile, ref, { force: args.force === true })
+    if (!result.ok) {
+      console.error(errorLine(result.reason))
+      process.exit(1)
+    }
+    done({
+      title: c.green(`Profile "${profile}" set to ${ref}.`),
+      hints: [{ label: 'If the agent is running:', command: 'typeclaw reload' }],
+    })
+  },
+})
+
+const addSub = defineCommand({
+  meta: {
+    name: 'add',
+    description: 'create a new (non-default) model profile; refuses when the profile already exists',
+  },
+  args: {
+    profile: {
+      type: 'positional',
+      description: 'profile name (must not already exist)',
+      required: true,
+    },
+    ref: {
+      type: 'positional',
+      description: '<provider>/<model> ref; omit to pick interactively',
+      required: false,
+    },
+    force: {
+      type: 'boolean',
+      description: 'write even when the target provider has no credentials configured',
+      required: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = ensureAgentDir()
+    const ref = args.ref ?? (await pickModelRef())
+
+    intro(`Adding model profile: ${args.profile} → ${ref}`)
+
+    const result = addProfile(cwd, args.profile, ref, { force: args.force === true })
+    if (!result.ok) {
+      console.error(errorLine(result.reason))
+      process.exit(1)
+    }
+    done({
+      title: c.green(`Profile "${args.profile}" → ${ref}.`),
+      hints: [{ label: 'If the agent is running:', command: 'typeclaw reload' }],
+    })
+  },
+})
+
+const removeSub = defineCommand({
+  meta: {
+    name: 'remove',
+    description: 'remove a non-default model profile (cannot remove `default`)',
+  },
+  args: {
+    profile: {
+      type: 'positional',
+      description: 'profile name to remove',
+      required: true,
+    },
+  },
+  async run({ args }) {
+    const cwd = ensureAgentDir()
+    intro(`Removing model profile: ${args.profile}`)
+    const result = removeProfile(cwd, args.profile)
+    if (!result.ok) {
+      console.error(errorLine(result.reason))
+      process.exit(1)
+    }
+    done({
+      title: c.green(`Profile "${args.profile}" removed.`),
+      hints: [{ label: 'If the agent is running:', command: 'typeclaw reload' }],
+    })
+  },
+})
+
+const listSub = defineCommand({
+  meta: {
+    name: 'list',
+    description: 'list configured model profiles (or all known model refs with --available)',
+  },
+  args: {
+    available: {
+      type: 'boolean',
+      description: 'list every <provider>/<model> ref typeclaw recognizes (not just configured profiles)',
+      required: false,
+    },
+  },
+  async run({ args }) {
+    if (args.available === true) {
+      printAvailableRefs()
+      return
+    }
+    const cwd = ensureAgentDir()
+    const entries = listModelProfiles(cwd)
+    if (entries.length === 0) {
+      console.log(c.dim('No models configured.'))
+      return
+    }
+
+    const profileWidth = Math.max(7, ...entries.map((e) => e.profile.length))
+    const refWidth = Math.max(3, ...entries.map((e) => e.ref.length))
+
+    const header = `${'PROFILE'.padEnd(profileWidth)}  ${'REF'.padEnd(refWidth)}  PROVIDER  STATUS`
+    console.log(c.dim(header))
+    for (const e of entries) {
+      const star = e.isDefault ? c.cyan('*') : ' '
+      const status = e.credentialStatus === 'available' ? c.green('ok') : c.yellow('missing-credentials')
+      const line = `${star}${e.profile.padEnd(profileWidth - 1)}  ${e.ref.padEnd(refWidth)}  ${e.providerId.padEnd(12)}  ${status}`
+      console.log(line)
+    }
+  },
+})
+
+export const modelCommand = defineCommand({
+  meta: {
+    name: 'model',
+    description: 'manage model profiles in typeclaw.json (models.default, models.fast, …)',
+  },
+  subCommands: {
+    set: setSub,
+    add: addSub,
+    remove: removeSub,
+    list: listSub,
+  },
+})
+
+function ensureAgentDir(): string {
+  const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+  if (!isInitialized(cwd)) {
+    console.error(errorLine('TypeClaw config file not found. Run `typeclaw init` first, or cd into an agent folder.'))
+    process.exit(1)
+  }
+  return cwd
+}
+
+async function pickProfileName(): Promise<string> {
+  const choice = await select<string>({
+    message: 'Pick a profile to set',
+    options: [
+      { value: 'default', label: 'default', hint: 'active model for new sessions' },
+      { value: 'fast', label: 'fast', hint: 'optional alias used by some subagents' },
+      { value: 'vision', label: 'vision', hint: 'optional alias used by some subagents' },
+    ],
+    initialValue: 'default',
+  })
+  if (isCancel(choice)) {
+    cancel('Aborted.')
+    process.exit(0)
+  }
+  return choice
+}
+
+async function pickModelRef(): Promise<string> {
+  const refs = listKnownModelRefs()
+  const choice = await select<KnownModelRef>({
+    message: 'Pick a model',
+    options: refs.map((ref) => ({
+      value: ref,
+      label: describeRef(ref),
+      hint: ref,
+    })),
+    initialValue: refs[0],
+  })
+  if (isCancel(choice)) {
+    cancel('Aborted.')
+    process.exit(0)
+  }
+  return choice
+}
+
+function describeRef(ref: KnownModelRef): string {
+  const providerId = providerForModelRef(ref)
+  const modelId = ref.slice(providerId.length + 1)
+  const provider = KNOWN_PROVIDERS[providerId]
+  const model = (provider.models as Record<string, { name: string }>)[modelId]
+  return model ? `${provider.name} · ${model.name}` : ref
+}
+
+function printAvailableRefs(): void {
+  const refs = listKnownModelRefs()
+  if (refs.length === 0) {
+    console.log(c.dim('No models registered.'))
+    return
+  }
+  console.log(c.dim('Use `typeclaw model set <profile> <ref>` to apply.'))
+  let lastProvider: KnownProviderId | null = null
+  for (const ref of refs) {
+    const providerId = providerForModelRef(ref)
+    if (providerId !== lastProvider) {
+      console.log('')
+      console.log(c.cyan(KNOWN_PROVIDERS[providerId].name))
+      lastProvider = providerId
+    }
+    console.log(`  ${ref}`)
+  }
+}

package/src/cli/provider.ts

@@ -0,0 +1,404 @@
+import { cancel, intro, isCancel, log, note, password, select, text } from '@clack/prompts'
+import { defineCommand } from 'citty'
+
+import {
+  KNOWN_PROVIDERS,
+  supportsApiKey as providerSupportsApiKey,
+  supportsOAuth as providerSupportsOAuth,
+  type KnownProviderId,
+} from '@/config/providers'
+import {
+  addProvider,
+  listConfiguredProviders,
+  removeProvider,
+  setProvider,
+  type CredentialSource,
+} from '@/config/providers-mutation'
+import { findAgentDir, isInitialized } from '@/init'
+import { makeOAuthLoginRunner } from '@/init/oauth-login'
+
+import { c, done, errorLine } from './ui'
+
+const addSub = defineCommand({
+  meta: {
+    name: 'add',
+    description: 'add LLM provider credentials (api key or OAuth) to an existing agent',
+  },
+  args: {
+    provider: {
+      type: 'positional',
+      description: `provider id (${Object.keys(KNOWN_PROVIDERS).join(' | ')}); omit to pick interactively`,
+      required: false,
+    },
+    key: {
+      type: 'string',
+      description: 'api key value (non-interactive); incompatible with --oauth',
+      required: false,
+    },
+    env: {
+      type: 'string',
+      description: 'bind to a custom env-var name (writes { env: NAME } into secrets.json)',
+      required: false,
+    },
+    oauth: {
+      type: 'boolean',
+      description: 'force OAuth flow (browser login) for providers that support both methods',
+      required: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = ensureAgentDir()
+    const providerId = await resolveProviderForAdd(args.provider)
+    const provider = KNOWN_PROVIDERS[providerId]
+
+    intro(`Adding provider: ${provider.name}`)
+
+    const method = await resolveAuthMethod(provider, args)
+    if (method === 'oauth') {
+      const result = await runOAuthLogin(cwd, providerId)
+      if (!result.ok) {
+        console.error(errorLine(`OAuth login failed: ${result.reason}`))
+        process.exit(1)
+      }
+      done({
+        title: c.green(`Logged in to ${provider.name}.`),
+        hints: nextStepHints({ credentialChanged: true }),
+      })
+      return
+    }
+
+    const credential = await resolveApiKeyInputs(provider, args)
+    const result = addProvider(cwd, providerId, credential)
+    if (!result.ok) {
+      console.error(errorLine(result.reason))
+      process.exit(1)
+    }
+    done({
+      title: c.green(`Added ${provider.name} credentials to secrets.json.`),
+      hints: nextStepHints({ credentialChanged: true }),
+    })
+  },
+})
+
+const setSub = defineCommand({
+  meta: {
+    name: 'set',
+    description: 'rotate/update credentials for an already-configured provider',
+  },
+  args: {
+    provider: {
+      type: 'positional',
+      description: `provider id (${Object.keys(KNOWN_PROVIDERS).join(' | ')})`,
+      required: true,
+    },
+    key: {
+      type: 'string',
+      description: 'new api key value (non-interactive); incompatible with --oauth',
+      required: false,
+    },
+    env: {
+      type: 'string',
+      description: 'bind to a custom env-var name (writes { env: NAME } into secrets.json)',
+      required: false,
+    },
+    oauth: {
+      type: 'boolean',
+      description: 're-run OAuth flow (browser login)',
+      required: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = ensureAgentDir()
+    const providerId = validateKnownProvider(args.provider)
+    const provider = KNOWN_PROVIDERS[providerId]
+
+    intro(`Updating provider: ${provider.name}`)
+
+    const method = await resolveAuthMethod(provider, args)
+    if (method === 'oauth') {
+      const result = await runOAuthLogin(cwd, providerId)
+      if (!result.ok) {
+        console.error(errorLine(`OAuth login failed: ${result.reason}`))
+        process.exit(1)
+      }
+      done({
+        title: c.green(`Refreshed OAuth credentials for ${provider.name}.`),
+        hints: nextStepHints({ credentialChanged: true }),
+      })
+      return
+    }
+
+    const credential = await resolveApiKeyInputs(provider, args)
+    const result = setProvider(cwd, providerId, credential)
+    if (!result.ok) {
+      console.error(errorLine(result.reason))
+      process.exit(1)
+    }
+    done({
+      title: c.green(`Updated ${provider.name} credentials in secrets.json.`),
+      hints: nextStepHints({ credentialChanged: true }),
+    })
+  },
+})
+
+const removeSub = defineCommand({
+  meta: {
+    name: 'remove',
+    description: 'remove a provider entry from secrets.json (refuses when a model profile references it)',
+  },
+  args: {
+    provider: {
+      type: 'positional',
+      description: 'provider id to remove',
+      required: true,
+    },
+    force: {
+      type: 'boolean',
+      description: 'remove even when a model profile references this provider',
+      required: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = ensureAgentDir()
+    const providerId = args.provider
+    const provider = providerId in KNOWN_PROVIDERS ? KNOWN_PROVIDERS[providerId as KnownProviderId] : null
+    const label = provider?.name ?? providerId
+
+    intro(`Removing provider: ${label}`)
+
+    const result = removeProvider(cwd, providerId, { force: args.force === true })
+    if (!result.ok) {
+      const list = result.profiles.join(', ')
+      console.error(
+        errorLine(
+          `Cannot remove "${providerId}": referenced by model profile(s) [${list}]. Update those profiles first, or rerun with --force.`,
+        ),
+      )
+      process.exit(1)
+    }
+    if (!result.existed) {
+      log.info(`No "${providerId}" entry in secrets.json — nothing to remove.`)
+    }
+    done({
+      title: c.green(`Removed ${label} from secrets.json.`),
+      hints: nextStepHints({ credentialChanged: true }),
+    })
+  },
+})
+
+const listSub = defineCommand({
+  meta: {
+    name: 'list',
+    description: 'show configured providers and how each credential resolves (file / env / oauth)',
+  },
+  async run() {
+    const cwd = ensureAgentDir()
+    const entries = listConfiguredProviders(cwd)
+    if (entries.length === 0) {
+      console.log(c.dim('No providers configured. Run `typeclaw provider add <id>` to wire one up.'))
+      return
+    }
+
+    const rows = entries.map((entry) => {
+      const refs =
+        entry.referencedByProfiles.length === 0 ? c.dim('(no profile)') : entry.referencedByProfiles.join(',')
+      const name = entry.id in KNOWN_PROVIDERS ? KNOWN_PROVIDERS[entry.id as KnownProviderId].name : entry.id
+      return {
+        id: entry.id,
+        name,
+        type: entry.type,
+        source: describeSource(entry.source),
+        refs,
+      }
+    })
+
+    const idWidth = Math.max(2, ...rows.map((r) => r.id.length))
+    const typeWidth = Math.max(4, ...rows.map((r) => r.type.length))
+    const sourceWidth = Math.max(6, ...rows.map((r) => r.source.length))
+
+    const header = `${'ID'.padEnd(idWidth)}  ${'TYPE'.padEnd(typeWidth)}  ${'SOURCE'.padEnd(sourceWidth)}  PROFILES`
+    console.log(c.dim(header))
+    for (const r of rows) {
+      const line = `${r.id.padEnd(idWidth)}  ${r.type.padEnd(typeWidth)}  ${r.source.padEnd(sourceWidth)}  ${r.refs}  ${c.dim(`(${r.name})`)}`
+      console.log(line)
+    }
+  },
+})
+
+export const providerCommand = defineCommand({
+  meta: {
+    name: 'provider',
+    description: 'manage LLM provider credentials in secrets.json',
+  },
+  subCommands: {
+    add: addSub,
+    set: setSub,
+    remove: removeSub,
+    list: listSub,
+  },
+})
+
+function ensureAgentDir(): string {
+  const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+  if (!isInitialized(cwd)) {
+    console.error(errorLine('TypeClaw config file not found. Run `typeclaw init` first, or cd into an agent folder.'))
+    process.exit(1)
+  }
+  return cwd
+}
+
+function validateKnownProvider(input: string): KnownProviderId {
+  if (input in KNOWN_PROVIDERS) return input as KnownProviderId
+  console.error(errorLine(`Unknown provider "${input}". Available: ${Object.keys(KNOWN_PROVIDERS).join(', ')}.`))
+  process.exit(1)
+}
+
+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>({
+    message: 'Pick a provider to add',
+    options: ids.map((id) => ({
+      value: id,
+      label: KNOWN_PROVIDERS[id].name,
+      hint: authHint(id),
+    })),
+    initialValue: ids[0],
+  })
+  if (isCancel(choice)) {
+    cancel('Aborted.')
+    process.exit(0)
+  }
+  return choice
+}
+
+type AuthArgs = { oauth?: boolean | undefined; key?: string | undefined; env?: string | undefined }
+
+async function resolveAuthMethod(
+  provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+  args: AuthArgs,
+): Promise<'api-key' | 'oauth'> {
+  const apiKeyOk = providerSupportsApiKey(provider)
+  const oauthOk = providerSupportsOAuth(provider)
+  if (args.oauth === true) {
+    if (!oauthOk) {
+      console.error(errorLine(`Provider ${provider.name} does not support OAuth.`))
+      process.exit(1)
+    }
+    return 'oauth'
+  }
+  if (args.key !== undefined || args.env !== undefined) {
+    if (!apiKeyOk) {
+      console.error(errorLine(`Provider ${provider.name} does not support api-key auth. Re-run with --oauth instead.`))
+      process.exit(1)
+    }
+    return 'api-key'
+  }
+  if (apiKeyOk && oauthOk) {
+    const choice = await select<'api-key' | 'oauth'>({
+      message: `How do you want to authenticate to ${provider.name}?`,
+      options: [
+        { value: 'api-key', label: 'API key', hint: 'saved to secrets.json' },
+        { value: 'oauth', label: 'OAuth (browser login)', hint: 'saved to secrets.json' },
+      ],
+      initialValue: 'api-key',
+    })
+    if (isCancel(choice)) {
+      cancel('Aborted.')
+      process.exit(0)
+    }
+    return choice
+  }
+  return oauthOk ? 'oauth' : 'api-key'
+}
+
+async function resolveApiKeyInputs(
+  provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+  args: AuthArgs,
+): Promise<
+  { type: 'api_key'; key: string; envBinding?: string | undefined } | { type: 'env-binding'; envBinding: string }
+> {
+  if (args.env !== undefined && args.key === undefined) {
+    return { type: 'env-binding', envBinding: args.env }
+  }
+  if (args.key !== undefined) {
+    const result: { type: 'api_key'; key: string; envBinding?: string } = { type: 'api_key', key: args.key }
+    if (args.env !== undefined) result.envBinding = args.env
+    return result
+  }
+  return { type: 'api_key', key: await promptApiKey(provider) }
+}
+
+async function promptApiKey(provider: (typeof KNOWN_PROVIDERS)[KnownProviderId]): Promise<string> {
+  const value = await password({
+    message: `Put your ${provider.name} API key (will be saved to secrets.json)`,
+    validate: (v) => (v && v.length > 0 ? undefined : 'API key is required'),
+  })
+  if (isCancel(value)) {
+    cancel('Aborted.')
+    process.exit(0)
+  }
+  return value
+}
+
+async function runOAuthLogin(cwd: string, providerId: KnownProviderId): Promise<{ ok: boolean; reason?: string }> {
+  const provider = KNOWN_PROVIDERS[providerId]
+  // Pick any model ref for the provider; OAuth login only uses the ref to
+  // discover the provider's `oauthProviderId`, which is the same regardless
+  // of which model the user later selects via `typeclaw model set`.
+  const ref = Object.keys(provider.models)[0]
+  if (ref === undefined) {
+    return { ok: false, reason: `Provider ${provider.name} has no registered models.` }
+  }
+  const modelRef = `${providerId}/${ref}` as const
+
+  const callbacks = {
+    onAuth: (url: string, instructions?: string) => {
+      const preamble = [`Open this URL in your browser to authorize ${provider.name}.`]
+      if (instructions) preamble.push('', instructions)
+      note(preamble.join('\n'), 'Browser login')
+      console.log(url)
+      console.log('')
+    },
+    onProgress: (message: string) => {
+      log.info(message)
+    },
+    onPrompt: async (message: string, placeholder?: string): Promise<string | null> => {
+      const value = await text({ message, ...(placeholder !== undefined ? { placeholder } : {}) })
+      if (isCancel(value)) return null
+      return value
+    },
+  }
+
+  const runner = makeOAuthLoginRunner(callbacks)
+  const result = await runner({ cwd, model: modelRef as Parameters<typeof runner>[0]['model'] })
+  if (!result.ok) return { ok: false, reason: result.reason }
+  return { ok: true }
+}
+
+function authHint(id: KnownProviderId): string {
+  const provider = KNOWN_PROVIDERS[id]
+  const apiKey = providerSupportsApiKey(provider)
+  const oauth = providerSupportsOAuth(provider)
+  if (apiKey && oauth) return 'API key or OAuth'
+  if (oauth) return 'OAuth only'
+  return 'API key'
+}
+
+function describeSource(source: CredentialSource): string {
+  switch (source.kind) {
+    case 'file':
+      return 'file'
+    case 'env-only':
+      return `env (${source.envName})`
+    case 'env-overridden':
+      return `env (${source.envName}, overrides file)`
+    case 'oauth':
+      return 'oauth'
+  }
+}
+
+function nextStepHints(opts: { credentialChanged: boolean }): { label: string; command: string }[] {
+  if (!opts.credentialChanged) return []
+  return [{ label: 'If the agent is running:', command: 'typeclaw reload' }]
+}

package/src/cli/reload.ts

@@ -1,6 +1,6 @@
 import { defineCommand } from 'citty'
 
-import { resolveHostPort, resolveTuiToken } from '@/container'
+import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir } from '@/init'
 import { requestReload, type ReloadResult } from '@/reload'
 
@@ -63,6 +63,11 @@ export const reload = defineCommand({
 
 async function defaultUrl(): Promise<string> {
   const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+  const precheck = await requireContainerRunning({ cwd })
+  if (!precheck.ok) {
+    console.error(errorLine(precheck.reason))
+    process.exit(1)
+  }
   const port = await resolveHostPort({ cwd })
   const token = await resolveTuiToken({ cwd })
   const url = new URL(`ws://127.0.0.1:${port}`)