typeclaw 0.1.5 → 0.2.0

package/src/config/models-mutation.ts

@@ -0,0 +1,209 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { commitSystemFileSync } from '@/git/system-commit'
+
+import { configSchema, loadConfigSync, validateConfig } from './config'
+import {
+  KNOWN_PROVIDERS,
+  listKnownModelRefs,
+  providerForModelRef,
+  type KnownModelRef,
+  type KnownProviderId,
+} from './providers'
+import { isProviderConfigured } from './providers-mutation'
+
+const CONFIG_FILE = 'typeclaw.json'
+
+export type ModelProfileEntry = {
+  profile: string
+  ref: KnownModelRef
+  providerId: KnownProviderId
+  isDefault: boolean
+  credentialStatus: 'available' | 'missing-credentials'
+}
+
+export type ModelMutationResult = { ok: true } | { ok: false; reason: string }
+
+export function listModelProfiles(cwd: string, env: NodeJS.ProcessEnv = process.env): ModelProfileEntry[] {
+  const models = loadConfigSync(cwd).models
+  const out: ModelProfileEntry[] = []
+  for (const [profile, ref] of Object.entries(models)) {
+    const providerId = providerForModelRef(ref)
+    out.push({
+      profile,
+      ref,
+      providerId,
+      isDefault: profile === 'default',
+      credentialStatus: hasUsableCredential(cwd, providerId, env) ? 'available' : 'missing-credentials',
+    })
+  }
+  // `default` always first; remaining profiles alphabetical so output is stable.
+  out.sort((a, b) => {
+    if (a.isDefault) return -1
+    if (b.isDefault) return 1
+    return a.profile.localeCompare(b.profile)
+  })
+  return out
+}
+
+export function listAvailableModelRefs(): KnownModelRef[] {
+  return listKnownModelRefs()
+}
+
+export function isKnownModelRef(value: string): value is KnownModelRef {
+  return (listKnownModelRefs() as ReadonlyArray<string>).includes(value)
+}
+
+// `set` is the canonical mutation for both creating a new profile and updating
+// an existing one (mirrors how `models.<profile>` works in the schema).
+// Refuses unknown model refs and providers without credentials (unless
+// `force: true`) so a write can't leave the agent in a state where the next
+// session start crashes with a missing-credential error.
+export type SetProfileOptions = {
+  force?: boolean
+  env?: NodeJS.ProcessEnv
+}
+
+export function setProfile(
+  cwd: string,
+  profile: string,
+  ref: string,
+  options: SetProfileOptions = {},
+): ModelMutationResult {
+  const trimmed = profile.trim()
+  if (trimmed.length === 0) {
+    return { ok: false, reason: 'Profile name cannot be empty.' }
+  }
+  if (!isKnownModelRef(ref)) {
+    return {
+      ok: false,
+      reason: `Unknown model "${ref}". Run \`typeclaw model list --available\` to see valid options.`,
+    }
+  }
+  const providerId = providerForModelRef(ref)
+  if (options.force !== true && !hasUsableCredential(cwd, providerId, options.env ?? process.env)) {
+    return {
+      ok: false,
+      reason: `Provider "${providerId}" has no credentials. Run \`typeclaw provider add ${providerId}\` first, or pass --force to write anyway.`,
+    }
+  }
+
+  const existingBefore = readModelsRaw(cwd)
+  const verb = existingBefore !== null && trimmed in existingBefore ? 'set' : 'add'
+  return writeProfile(cwd, trimmed, ref, `model: ${verb} ${trimmed} → ${ref}`)
+}
+
+// `add` is just `set` with a uniqueness guard; users who want "update" should
+// reach for `set`. Keeping it separate so the CLI can route distinct error
+// messages without leaking force-overwrite as a happy path.
+export function addProfile(
+  cwd: string,
+  profile: string,
+  ref: string,
+  options: SetProfileOptions = {},
+): ModelMutationResult {
+  const existing = readModelsRaw(cwd)
+  if (existing !== null && profile in existing) {
+    return {
+      ok: false,
+      reason: `Profile "${profile}" already exists. Use \`typeclaw model set ${profile} ${ref}\` to update it.`,
+    }
+  }
+  return setProfile(cwd, profile, ref, options)
+}
+
+// `default` is required by the schema (`modelsSchema.refine`). Removing it
+// would make the file unparseable, so we reject with a precise hint instead of
+// letting the next `validateConfig` failure confuse the user. To change the
+// default model, the user runs `typeclaw model set default <ref>`.
+export function removeProfile(cwd: string, profile: string): ModelMutationResult {
+  if (profile === 'default') {
+    return {
+      ok: false,
+      reason:
+        'Cannot remove the `default` profile. Use `typeclaw model set default <ref>` to change the default model.',
+    }
+  }
+  const existing = readModelsRaw(cwd)
+  if (existing === null) {
+    return { ok: false, reason: `${CONFIG_FILE} not found at ${cwd}. Run \`typeclaw init\` first.` }
+  }
+  if (!(profile in existing)) {
+    return { ok: false, reason: `Profile "${profile}" not found in ${CONFIG_FILE}.` }
+  }
+  const next = { ...existing }
+  delete next[profile]
+  return writeModels(cwd, next, `model: remove ${profile}`)
+}
+
+function writeProfile(cwd: string, profile: string, ref: KnownModelRef, message: string): ModelMutationResult {
+  const existing = readModelsRaw(cwd)
+  const next = existing === null ? { default: ref } : { ...existing, [profile]: ref }
+  if (existing === null && profile !== 'default') {
+    next.default = ref
+  }
+  return writeModels(cwd, next, message)
+}
+
+function writeModels(cwd: string, models: Record<string, string>, commitMessage: string): ModelMutationResult {
+  const path = join(cwd, CONFIG_FILE)
+  let parsed: Record<string, unknown>
+  try {
+    const raw = readFileSync(path, 'utf8')
+    parsed = JSON.parse(raw) as Record<string, unknown>
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { ok: false, reason: `${CONFIG_FILE} not found at ${cwd}. Run \`typeclaw init\` first.` }
+    }
+    return { ok: false, reason: `Failed to read ${CONFIG_FILE}: ${(error as Error).message}` }
+  }
+  parsed.models = models
+  const check = configSchema.safeParse(parsed)
+  if (!check.success) {
+    return {
+      ok: false,
+      reason: `models block would be invalid: ${check.error.issues.map((i) => i.message).join('; ')}`,
+    }
+  }
+  try {
+    writeFileSync(path, `${JSON.stringify(parsed, null, 2)}\n`)
+  } catch (error) {
+    return { ok: false, reason: `Failed to write ${CONFIG_FILE}: ${(error as Error).message}` }
+  }
+  // Final schema-pass for parity with every other host-side mutation that runs
+  // through validateConfig. Mount checks etc. should never fail here because
+  // we only touched `models`, but if the file was already in a bad state we
+  // want to surface that instead of leaving the user wondering why `reload`
+  // fails.
+  const validation = validateConfig(cwd)
+  if (!validation.ok) {
+    return { ok: false, reason: validation.reason }
+  }
+  // Auto-commit so the agent folder is never silently dirty after a CLI
+  // config mutation. Same pattern as `persistMigratedConfig` and cron
+  // migrations: `commitSystemFileSync` no-ops on non-git folders, missing
+  // Bun, and clean files, so callers outside a git repo pay zero cost.
+  commitSystemFileSync(cwd, CONFIG_FILE, commitMessage)
+  return { ok: true }
+}
+
+function readModelsRaw(cwd: string): Record<string, string> | null {
+  try {
+    const raw = readFileSync(join(cwd, CONFIG_FILE), 'utf8')
+    const parsed = JSON.parse(raw) as { models?: Record<string, string> }
+    return parsed.models ?? null
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
+    throw error
+  }
+}
+
+function hasUsableCredential(cwd: string, providerId: KnownProviderId, env: NodeJS.ProcessEnv): boolean {
+  const provider = KNOWN_PROVIDERS[providerId]
+  if (provider.apiKeyEnv !== null) {
+    const fromEnv = env[provider.apiKeyEnv]
+    if (fromEnv !== undefined && fromEnv !== '') return true
+  }
+  return isProviderConfigured(cwd, providerId)
+}

package/src/config/providers-mutation.ts

@@ -0,0 +1,250 @@
+import { join } from 'node:path'
+
+import { SecretsBackend, type Secret } from '@/secrets'
+import { providerKeyDefaultEnv } from '@/secrets/defaults'
+import type { ProviderCredential, Providers } from '@/secrets/schema'
+
+import { type Models, loadConfigSync } from './config'
+import { KNOWN_PROVIDERS, type KnownModelRef, type KnownProviderId, providerForModelRef } from './providers'
+
+// Where a configured credential resolves from at runtime. Reported by
+// `typeclaw provider list` so users can tell whether their key is coming from
+// `secrets.json#providers.<id>.key.value`, from `process.env.<API_KEY_ENV>`, or
+// from an explicit `{ env: 'CUSTOM_NAME' }` binding. Drives the post-mutation
+// hints (e.g. "key is env-overridden — `provider remove` will not unset env").
+export type CredentialSource =
+  | { kind: 'file' }
+  | { kind: 'env-only'; envName: string }
+  | { kind: 'env-overridden'; envName: string }
+  | { kind: 'oauth' }
+
+export type ConfiguredProvider = {
+  id: KnownProviderId | string
+  known: boolean
+  type: 'api_key' | 'oauth' | 'unknown'
+  source: CredentialSource
+  envName: string | undefined
+  referencedByProfiles: string[]
+}
+
+export type ProviderAddCredential =
+  | { type: 'api_key'; key: string; envBinding?: string | undefined }
+  | { type: 'env-binding'; envBinding: string }
+
+export type ProviderMutationResult = { ok: true } | { ok: false; reason: string }
+
+const SECRETS_FILE = 'secrets.json'
+
+export function listConfiguredProviders(cwd: string, env: NodeJS.ProcessEnv = process.env): ConfiguredProvider[] {
+  const backend = new SecretsBackend(join(cwd, SECRETS_FILE))
+  const providers = backend.tryReadProvidersSync()
+  const models = readModelsOrNull(cwd)
+  const referencedByProfiles = buildProviderReferenceMap(models)
+
+  const ids = new Set<string>([...Object.keys(providers), ...Object.keys(KNOWN_PROVIDERS)])
+  const out: ConfiguredProvider[] = []
+  for (const id of ids) {
+    const credential = providers[id]
+    const known = id in KNOWN_PROVIDERS
+    if (credential === undefined) {
+      // Known provider with no file entry. Surface it only when an env var
+      // makes it usable; otherwise it's not "configured" and shouldn't appear
+      // in the list (would clutter output for the 5+ known providers users
+      // haven't touched).
+      const envName = providerKeyDefaultEnv(id)
+      if (envName !== undefined && readEnvKey(env, envName) !== undefined) {
+        out.push({
+          id: id as KnownProviderId,
+          known,
+          type: 'api_key',
+          source: { kind: 'env-only', envName },
+          envName,
+          referencedByProfiles: referencedByProfiles.get(id) ?? [],
+        })
+      }
+      continue
+    }
+    out.push({
+      id,
+      known,
+      type: credentialType(credential),
+      source: credentialSource(id, credential, env),
+      envName: effectiveEnvName(id, credential),
+      referencedByProfiles: referencedByProfiles.get(id) ?? [],
+    })
+  }
+  out.sort((a, b) => a.id.localeCompare(b.id))
+  return out
+}
+
+export function isProviderConfigured(cwd: string, providerId: string): boolean {
+  const backend = new SecretsBackend(join(cwd, SECRETS_FILE))
+  return providerId in backend.tryReadProvidersSync()
+}
+
+// Refuses to overwrite an existing provider — callers must use `setProvider`
+// for the rotate path. Keeps the "I'm adding fresh credentials" intent
+// distinct from the "I'm rotating an existing key" intent at the file-write
+// boundary, so an `add` typo can't silently displace a working key.
+export function addProvider(
+  cwd: string,
+  providerId: KnownProviderId,
+  credential: ProviderAddCredential,
+): ProviderMutationResult {
+  if (isProviderConfigured(cwd, providerId)) {
+    return {
+      ok: false,
+      reason: `Provider "${providerId}" is already configured in secrets.json. Use \`typeclaw provider set\` to rotate its credentials.`,
+    }
+  }
+  return writeApiKeyCredential(cwd, providerId, credential)
+}
+
+export function setProvider(
+  cwd: string,
+  providerId: KnownProviderId,
+  credential: ProviderAddCredential,
+): ProviderMutationResult {
+  return writeApiKeyCredential(cwd, providerId, credential)
+}
+
+// Refuses removal when any model profile in typeclaw.json references the
+// provider — clearing the credential out from under an active profile would
+// crash the next session start with a missing-credential error. Returns the
+// list of offending profiles so the CLI can name them in the error message.
+export type ProviderRemovalResult =
+  | { ok: true; existed: boolean }
+  | { ok: false; reason: 'referenced'; profiles: string[] }
+
+export function removeProvider(
+  cwd: string,
+  providerId: string,
+  options: { force?: boolean } = {},
+): ProviderRemovalResult {
+  if (options.force !== true) {
+    const profiles = findModelsReferencingProvider(cwd, providerId)
+    if (profiles.length > 0) {
+      return { ok: false, reason: 'referenced', profiles }
+    }
+  }
+  const backend = new SecretsBackend(join(cwd, SECRETS_FILE))
+  const existed = backend.removeProviderCredentialSync(providerId)
+  return { ok: true, existed }
+}
+
+export function findModelsReferencingProvider(cwd: string, providerId: string): string[] {
+  const models = readModelsOrNull(cwd)
+  if (models === null) return []
+  const out: string[] = []
+  for (const [profile, ref] of Object.entries(models)) {
+    if (refTargetsProvider(ref, providerId)) out.push(profile)
+  }
+  return out
+}
+
+function writeApiKeyCredential(
+  cwd: string,
+  providerId: KnownProviderId,
+  credential: ProviderAddCredential,
+): ProviderMutationResult {
+  if (!(providerId in KNOWN_PROVIDERS)) {
+    return { ok: false, reason: `Unknown provider "${providerId}".` }
+  }
+  const provider = KNOWN_PROVIDERS[providerId]
+  if (provider.apiKeyEnv === null) {
+    return {
+      ok: false,
+      reason: `Provider "${providerId}" does not support api-key authentication. Use \`typeclaw provider add ${providerId} --oauth\` instead.`,
+    }
+  }
+  const secret = buildSecret(credential)
+  if (secret === null) {
+    return { ok: false, reason: 'API key cannot be empty.' }
+  }
+  const backend = new SecretsBackend(join(cwd, SECRETS_FILE))
+  backend.writeProviderCredentialSync(providerId, { type: 'api_key', key: secret })
+  return { ok: true }
+}
+
+function buildSecret(credential: ProviderAddCredential): Secret | null {
+  if (credential.type === 'env-binding') {
+    return { env: credential.envBinding }
+  }
+  if (credential.key.length === 0) return null
+  if (credential.envBinding !== undefined && credential.envBinding.length > 0) {
+    return { value: credential.key, env: credential.envBinding }
+  }
+  return { value: credential.key }
+}
+
+function credentialType(credential: ProviderCredential): 'api_key' | 'oauth' | 'unknown' {
+  if (credential.type === 'api_key') return 'api_key'
+  if (credential.type === 'oauth') return 'oauth'
+  return 'unknown'
+}
+
+function credentialSource(
+  providerId: string,
+  credential: ProviderCredential,
+  env: NodeJS.ProcessEnv,
+): CredentialSource {
+  if (credential.type === 'oauth') return { kind: 'oauth' }
+  if (credential.type !== 'api_key') return { kind: 'file' }
+  const envName = credential.key.env ?? providerKeyDefaultEnv(providerId)
+  if (envName !== undefined && readEnvKey(env, envName) !== undefined) {
+    if (credential.key.value === undefined) return { kind: 'env-only', envName }
+    return { kind: 'env-overridden', envName }
+  }
+  return { kind: 'file' }
+}
+
+function effectiveEnvName(providerId: string, credential: ProviderCredential): string | undefined {
+  if (credential.type !== 'api_key') return undefined
+  return credential.key.env ?? providerKeyDefaultEnv(providerId)
+}
+
+function readEnvKey(env: NodeJS.ProcessEnv, key: string): string | undefined {
+  const value = env[key]
+  if (value === undefined || value === '') return undefined
+  return value
+}
+
+function buildProviderReferenceMap(models: Models | null): Map<string, string[]> {
+  const out = new Map<string, string[]>()
+  if (models === null) return out
+  for (const [profile, ref] of Object.entries(models)) {
+    const providerId = safeProviderForRef(ref)
+    if (providerId === null) continue
+    const existing = out.get(providerId) ?? []
+    existing.push(profile)
+    out.set(providerId, existing)
+  }
+  return out
+}
+
+function refTargetsProvider(ref: string, providerId: string): boolean {
+  return ref.startsWith(`${providerId}/`)
+}
+
+function safeProviderForRef(ref: KnownModelRef): KnownProviderId | null {
+  try {
+    return providerForModelRef(ref)
+  } catch {
+    return null
+  }
+}
+
+function readModelsOrNull(cwd: string): Models | null {
+  try {
+    return loadConfigSync(cwd).models
+  } catch {
+    return null
+  }
+}
+
+export type ProviderListEntry = ConfiguredProvider
+
+export type ProvidersSnapshot = {
+  providers: Providers
+  configuredIds: string[]
+}

package/src/config/providers.ts

@@ -22,8 +22,9 @@ type KnownProvider = {
 }
 
 // Curated allowlist of providers + models that are wired into the agent
-// runtime. The values here back the Zod enum on `configSchema.model`, so any
-// model the user can put in `typeclaw.json` MUST appear here verbatim. The
+// runtime. The values here back the Zod enum on every entry in
+// `configSchema.models`, so any model the user can put in `typeclaw.json`
+// (under any profile name) MUST appear here verbatim. The
 // init-time picker may surface additional models from models.dev, but it
 // resolves them through this list before scaffolding (anything missing falls
 // back to a curated default).
@@ -187,6 +188,144 @@ export const KNOWN_PROVIDERS = {
       },
     },
   },
+  // Z.AI (ZhipuAI / BigModel) general 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. Costs and context windows mirror docs.z.ai/guides/overview/
+  // pricing as of 2026-05-15.
+  //
+  // The split with `zai-coding` below mirrors how we model `openai` /
+  // `openai-codex`: same upstream vendor, two distinct billing surfaces
+  // (paygo vs subscription), two distinct base URLs, two distinct env vars
+  // so a user can hold both keys simultaneously without collisions.
+  zai: {
+    id: 'zai',
+    name: 'Z.AI',
+    baseUrl: 'https://api.z.ai/api/paas/v4',
+    auth: ['api-key'],
+    apiKeyEnv: 'ZAI_API_KEY',
+    oauthProviderId: null,
+    models: {
+      'glm-4.5-air': {
+        id: 'glm-4.5-air',
+        name: 'GLM-4.5-Air',
+        api: 'openai-completions',
+        provider: 'zai',
+        baseUrl: 'https://api.z.ai/api/paas/v4',
+        reasoning: true,
+        input: ['text'],
+        cost: { input: 0.2, output: 1.1, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 128000,
+        maxTokens: 96000,
+      },
+      'glm-4.6': {
+        id: 'glm-4.6',
+        name: 'GLM-4.6',
+        api: 'openai-completions',
+        provider: 'zai',
+        baseUrl: 'https://api.z.ai/api/paas/v4',
+        reasoning: true,
+        input: ['text'],
+        cost: { input: 0.6, output: 2.2, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 200000,
+        maxTokens: 128000,
+      },
+      'glm-4.7': {
+        id: 'glm-4.7',
+        name: 'GLM-4.7',
+        api: 'openai-completions',
+        provider: 'zai',
+        baseUrl: 'https://api.z.ai/api/paas/v4',
+        reasoning: true,
+        input: ['text'],
+        cost: { input: 0.6, output: 2.2, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 200000,
+        maxTokens: 128000,
+      },
+    },
+  },
+  // Z.AI GLM Coding Plan subscription. Same vendor, same key format, but a
+  // distinct base URL (/api/coding/paas/v4) and a separate billing surface
+  // — using a Coding Plan key against the paygo endpoint returns error 1113
+  // ("insufficient balance"). Distinct env var (`ZAI_CODING_API_KEY`) so a
+  // user can hold both a paygo and a Coding Plan key on different accounts.
+  //
+  // Model lineup is exactly the five models the Coding Plan docs name as
+  // "All plans support" plus GLM-5 (Pro/Max only per docs). Listing other
+  // GLM models here would silently bill against the wrong surface.
+  'zai-coding': {
+    id: 'zai-coding',
+    name: 'Z.AI (GLM Coding Plan)',
+    baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+    auth: ['api-key'],
+    apiKeyEnv: 'ZAI_CODING_API_KEY',
+    oauthProviderId: null,
+    models: {
+      'glm-4.5-air': {
+        id: 'glm-4.5-air',
+        name: 'GLM-4.5-Air',
+        api: 'openai-completions',
+        provider: 'zai-coding',
+        baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+        reasoning: true,
+        input: ['text'],
+        cost: { input: 0.2, output: 1.1, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 128000,
+        maxTokens: 96000,
+      },
+      'glm-4.7': {
+        id: 'glm-4.7',
+        name: 'GLM-4.7',
+        api: 'openai-completions',
+        provider: 'zai-coding',
+        baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+        reasoning: true,
+        input: ['text'],
+        cost: { input: 0.6, output: 2.2, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 200000,
+        maxTokens: 128000,
+      },
+      // GLM-5 access is Pro/Max tier only per docs.z.ai/devpack — Lite
+      // subscribers will see a quota error. We still list it because we
+      // can't introspect plan tier from the key alone.
+      'glm-5': {
+        id: 'glm-5',
+        name: 'GLM-5',
+        api: 'openai-completions',
+        provider: 'zai-coding',
+        baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+        reasoning: true,
+        input: ['text'],
+        cost: { input: 1.0, output: 3.2, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 200000,
+        maxTokens: 128000,
+      },
+      'glm-5-turbo': {
+        id: 'glm-5-turbo',
+        name: 'GLM-5-Turbo',
+        api: 'openai-completions',
+        provider: 'zai-coding',
+        baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+        reasoning: true,
+        input: ['text'],
+        cost: { input: 1.2, output: 4.0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 200000,
+        maxTokens: 128000,
+      },
+      'glm-5.1': {
+        id: 'glm-5.1',
+        name: 'GLM-5.1',
+        api: 'openai-completions',
+        provider: 'zai-coding',
+        baseUrl: 'https://api.z.ai/api/coding/paas/v4',
+        reasoning: true,
+        input: ['text'],
+        cost: { input: 1.4, output: 4.4, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 200000,
+        maxTokens: 128000,
+      },
+    },
+  },
 } as const satisfies Record<string, KnownProvider>
 
 export type KnownProviderId = keyof typeof KNOWN_PROVIDERS

package/src/config/reloadable.ts

@@ -1,20 +1,27 @@
+import type { PermissionService } from '@/permissions'
 import type { Reloadable, ReloadResult } from '@/reload'
 
-import { type ConfigReloadDiff, reloadConfig, validateConfig } from './config'
+import { getConfig, type ConfigReloadDiff, reloadConfig, validateConfig } from './config'
 
 export type CreateConfigReloadableOptions = {
   cwd: string
+  // Optional hook fired after a successful reload so the live permission
+  // service can rebuild its resolved role table from the new roles config.
+  // This is what makes `roles.<name>.match` edits (typeclaw role claim,
+  // hand-edits) take effect without a container restart. `roles.<name>.permissions`
+  // changes still require a restart — see FIELD_EFFECTS in config.ts.
+  permissions?: PermissionService
 }
 
-export function createConfigReloadable({ cwd }: CreateConfigReloadableOptions): Reloadable {
+export function createConfigReloadable({ cwd, permissions }: CreateConfigReloadableOptions): Reloadable {
   return {
     scope: 'config',
     description: 'typeclaw.json runtime config',
-    reload: async () => doReload(cwd),
+    reload: async () => doReload(cwd, permissions),
   }
 }
 
-async function doReload(cwd: string): Promise<ReloadResult> {
+async function doReload(cwd: string, permissions: PermissionService | undefined): Promise<ReloadResult> {
   // Mount accessibility belongs to the validation surface, not loadConfigSync —
   // validateConfig is the single gate that every host-side caller goes through.
   // Run it before swapping the live config pointer so a mount that vanished
@@ -34,6 +41,10 @@ async function doReload(cwd: string): Promise<ReloadResult> {
     return { scope: 'config', ok: false, reason: message }
   }
 
+  if (permissions !== undefined && diff.applied.some((c) => c.path === 'roles.match')) {
+    permissions.replaceRoles(getConfig().roles)
+  }
+
   return {
     scope: 'config',
     ok: true,

package/src/container/index.ts

@@ -1,5 +1,10 @@
 export { logs, planLogs, type LogsPlan, type LogsResult } from './logs'
 export { CONTAINER_PORT, TUI_TOKEN_LABEL, findFreePort, resolveHostPort, resolveTuiToken } from './port'
+export {
+  requireContainerRunning,
+  type RequireContainerRunningOptions,
+  type RequireContainerRunningResult,
+} from './require-running'
 export { planShell, shell, type ShellPlan, type ShellResult } from './shell'
 export { status, type ContainerStatus, type StatusOptions } from './status'
 export {