typeclaw 0.10.0 → 0.11.0

package/src/cli/tunnel.ts

@@ -1,24 +1,35 @@
 import { readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
-import { select, text, isCancel, cancel, log } from '@clack/prompts'
+import { select, text, password, isCancel, cancel, log } from '@clack/prompts'
 import { defineCommand } from 'citty'
 
 import { loadConfigSync, validateConfig } from '@/config'
 import { resolveHostPort, resolveTuiToken } from '@/container'
-import { findAgentDir, isInitialized } from '@/init'
+import { appendOrReplaceEnvKey, findAgentDir, hasEnvKey, isInitialized } from '@/init'
 import type { ClientMessage, ServerMessage, TunnelLogsServerMessage, TunnelSnapshot } from '@/shared'
 import type { TunnelConfig, TunnelFor, TunnelProvider } from '@/tunnels'
 
 import { c, errorLine } from './ui'
 
 type AddArgs = {
-  name: string
+  name?: string
   provider?: string
   forChannel?: string
   forManual?: boolean
   upstreamPort?: string
   externalUrl?: string
+  hostname?: string
+  tokenEnv?: string
+}
+
+type SetArgs = {
+  name?: string
+  provider?: string
+  upstreamPort?: string
+  externalUrl?: string
+  hostname?: string
+  tokenEnv?: string
 }
 
 type RemoveArgs = { name: string }
@@ -31,12 +42,32 @@ type LiveResult<T> = { ok: true; value: T } | { ok: false; reason: string }
 
 export type TextValidator = (value: string) => string | undefined
 
+export type TunnelSetField = 'provider' | 'externalUrl' | 'hostname' | 'tokenEnv' | 'upstreamPort'
+
 export type TunnelPrompts = {
   selectProvider: () => Promise<TunnelProvider | symbol>
   selectOwner: () => Promise<'channel' | 'manual' | symbol>
+  // Only `runTunnelSetFlow` uses this; `runTunnelAddFlow` callers can omit it.
+  selectSetField?: (
+    choices: readonly { value: TunnelSetField; label: string; hint?: string }[],
+  ) => Promise<TunnelSetField | symbol>
+  // Only `runTunnelSetFlow` uses this when the positional `name` is omitted
+  // and more than one tunnel is configured. Optional so existing callers
+  // (especially `runTunnelAddFlow` tests) don't have to stub it.
+  selectExistingTunnel?: (
+    choices: readonly { value: string; label: string; hint?: string }[],
+  ) => Promise<string | symbol>
   text: (message: string, validate?: TextValidator) => Promise<string | symbol>
+  // Only fires when the user picks `cloudflare-named` AND the resolved
+  // `tokenEnv` is missing from the agent's `.env`. Optional so existing
+  // callers/tests don't have to stub it; flows that need it but don't get
+  // one fall back to skipping the token write (the user can still set
+  // `.env` by hand). Same compat pattern as `selectSetField`.
+  password?: (message: string, validate?: TextValidator) => Promise<string | symbol>
 }
 
+const DEFAULT_TUNNEL_TOKEN_ENV = 'CLOUDFLARE_TUNNEL_TOKEN'
+
 const DEFAULT_TIMEOUT_MS = 15_000
 
 const defaultPrompts: TunnelPrompts = {
@@ -45,6 +76,11 @@ const defaultPrompts: TunnelPrompts = {
       message: 'Tunnel provider',
       options: [
         { value: 'cloudflare-quick', label: 'Cloudflare Quick Tunnel', hint: 'no signup, URL rotates on restart' },
+        {
+          value: 'cloudflare-named',
+          label: 'Cloudflare Named Tunnel',
+          hint: 'stable URL, needs Cloudflare account + domain',
+        },
         { value: 'external', label: 'External URL', hint: 'bring your own reverse proxy' },
       ],
     }),
@@ -56,28 +92,55 @@ const defaultPrompts: TunnelPrompts = {
         { value: 'manual', label: 'Manual upstream' },
       ],
     }),
+  selectSetField: (choices) =>
+    select<TunnelSetField>({
+      message: 'Which field do you want to change?',
+      options: choices.map((choice) => ({
+        value: choice.value,
+        label: choice.label,
+        ...(choice.hint !== undefined ? { hint: choice.hint } : {}),
+      })),
+    }),
+  selectExistingTunnel: (choices) =>
+    select<string>({
+      message: 'Pick a tunnel to edit',
+      options: choices.map((choice) => ({
+        value: choice.value,
+        label: choice.label,
+        ...(choice.hint !== undefined ? { hint: choice.hint } : {}),
+      })),
+    }),
   text: (message, validate) =>
     text({ message, ...(validate !== undefined ? { validate: (v) => validate(v ?? '') } : {}) }),
+  password: (message, validate) =>
+    password({ message, ...(validate !== undefined ? { validate: (v) => validate(v ?? '') } : {}) }),
 }
 
 const addSub = defineCommand({
   meta: { name: 'add', description: 'add a public tunnel entry to typeclaw.json' },
   args: {
-    name: { type: 'positional', required: true, description: 'tunnel name' },
-    provider: { type: 'string', description: 'external | cloudflare-quick' },
+    name: { type: 'positional', required: false, description: 'tunnel name (omit to prompt interactively)' },
+    provider: { type: 'string', description: 'external | cloudflare-quick | cloudflare-named' },
     'for-channel': { type: 'string', description: 'own this tunnel from a channel adapter' },
     'for-manual': { type: 'boolean', description: 'create a manually-owned tunnel' },
     'upstream-port': { type: 'string', description: 'container-local upstream port for manual tunnels' },
     'external-url': { type: 'string', description: 'https URL for provider=external' },
+    hostname: { type: 'string', description: 'https URL for provider=cloudflare-named (dashboard Public Hostname)' },
+    'token-env': {
+      type: 'string',
+      description: 'env var name holding the cloudflared token (provider=cloudflare-named)',
+    },
   },
   async run({ args }) {
     const result = await runTunnelAddFlow(ensureAgentDir(), {
-      name: String(args.name),
+      ...(args.name !== undefined ? { name: String(args.name) } : {}),
       ...(args.provider !== undefined ? { provider: String(args.provider) } : {}),
       ...(args['for-channel'] !== undefined ? { forChannel: String(args['for-channel']) } : {}),
       ...(args['for-manual'] === true ? { forManual: true } : {}),
       ...(args['upstream-port'] !== undefined ? { upstreamPort: String(args['upstream-port']) } : {}),
       ...(args['external-url'] !== undefined ? { externalUrl: String(args['external-url']) } : {}),
+      ...(args.hostname !== undefined ? { hostname: String(args.hostname) } : {}),
+      ...(args['token-env'] !== undefined ? { tokenEnv: String(args['token-env']) } : {}),
     })
     if (!result.ok) {
       console.error(errorLine(result.reason))
@@ -131,6 +194,50 @@ const removeSub = defineCommand({
   },
 })
 
+const setSub = defineCommand({
+  meta: {
+    name: 'set',
+    description: 'edit an existing tunnel entry in typeclaw.json (symmetric with `typeclaw channel set`)',
+  },
+  args: {
+    name: { type: 'positional', required: false, description: 'tunnel name (omit to pick interactively)' },
+    provider: { type: 'string', description: 'external | cloudflare-quick | cloudflare-named' },
+    'upstream-port': { type: 'string', description: 'container-local upstream port (manual non-named tunnels)' },
+    'external-url': { type: 'string', description: 'https URL for provider=external' },
+    hostname: { type: 'string', description: 'https URL for provider=cloudflare-named (dashboard Public Hostname)' },
+    'token-env': {
+      type: 'string',
+      description: 'env var name holding the cloudflared token (provider=cloudflare-named)',
+    },
+  },
+  async run({ args }) {
+    const result = await runTunnelSetFlow(ensureAgentDir(), {
+      ...(args.name !== undefined ? { name: String(args.name) } : {}),
+      ...(args.provider !== undefined ? { provider: String(args.provider) } : {}),
+      ...(args['upstream-port'] !== undefined ? { upstreamPort: String(args['upstream-port']) } : {}),
+      ...(args['external-url'] !== undefined ? { externalUrl: String(args['external-url']) } : {}),
+      ...(args.hostname !== undefined ? { hostname: String(args.hostname) } : {}),
+      ...(args['token-env'] !== undefined ? { tokenEnv: String(args['token-env']) } : {}),
+    })
+    if (!result.ok) {
+      console.error(errorLine(result.reason))
+      process.exit(1)
+    }
+    log.success(`Updated tunnel "${result.value.name}" in typeclaw.json.`)
+    if (result.value.for.kind === 'channel') {
+      // The container-side adapter (see src/channels/adapters/github/index.ts)
+      // re-runs webhook registration on every start. A restart is required
+      // anyway because `tunnels` is restart-required (FIELD_EFFECTS in
+      // src/config/config.ts), so on the next start the adapter picks up the
+      // new URL and re-points its managed webhooks at it. No CLI-side
+      // eager re-install needed.
+      log.info(`Run typeclaw restart to apply (the ${result.value.for.name} adapter will re-register its webhooks).`)
+    } else {
+      log.info('Run typeclaw restart to apply.')
+    }
+  },
+})
+
 const logsSub = defineCommand({
   meta: { name: 'logs', description: 'print or follow a tunnel log ring' },
   args: {
@@ -160,7 +267,7 @@ const logsSub = defineCommand({
 
 export const tunnelCommand = defineCommand({
   meta: { name: 'tunnel', description: 'manage public tunnels for channels and manual upstreams' },
-  subCommands: { add: addSub, list: listSub, status: statusSub, remove: removeSub, logs: logsSub },
+  subCommands: { add: addSub, set: setSub, list: listSub, status: statusSub, remove: removeSub, logs: logsSub },
 })
 
 export async function runTunnelAddFlow(
@@ -178,13 +285,15 @@ export async function runTunnelAddFlow(
   const validation = validateConfig(cwd)
   if (!validation.ok) return { ok: false, reason: validation.reason }
   const config = loadConfigSync(cwd)
-  if (config.tunnels.some((entry) => entry.name === args.name))
-    return { ok: false, reason: `tunnel "${args.name}" already exists` }
+  const existingNames = new Set(config.tunnels.map((entry) => entry.name))
+  const name = args.name ?? (await promptText('Tunnel name', prompts, makeTunnelNameValidator(existingNames)))
+  const nameError = validateTunnelName(name, existingNames)
+  if (nameError !== undefined) return { ok: false, reason: nameError }
 
   const provider = await resolveProvider(args.provider, prompts)
   const tunnelFor = await resolveFor(args, prompts)
   let upstreamPort: number | undefined
-  if (tunnelFor.kind === 'manual') {
+  if (tunnelFor.kind === 'manual' && provider !== 'cloudflare-named') {
     const raw = args.upstreamPort ?? (await promptText('Upstream port', prompts, validateUpstreamPort))
     const portError = validateUpstreamPort(raw)
     if (portError !== undefined) return { ok: false, reason: `upstream port: ${portError}` }
@@ -196,17 +305,42 @@ export async function runTunnelAddFlow(
     const urlError = validateHttpsUrl(externalUrl)
     if (urlError !== undefined) return { ok: false, reason: `external URL: ${urlError}` }
   }
+  let hostname: string | undefined
+  let tokenEnv: string | undefined
+  if (provider === 'cloudflare-named') {
+    hostname =
+      args.hostname ??
+      (await promptText(
+        'Public hostname configured in the Cloudflare dashboard (https://...)',
+        prompts,
+        validateHttpsUrl,
+      ))
+    const hostnameError = validateHttpsUrl(hostname)
+    if (hostnameError !== undefined) return { ok: false, reason: `hostname: ${hostnameError}` }
+    tokenEnv = args.tokenEnv ?? DEFAULT_TUNNEL_TOKEN_ENV
+    const tokenError = validateTokenEnv(tokenEnv)
+    if (tokenError !== undefined) return { ok: false, reason: `token-env: ${tokenError}` }
+    // Only prompt for the token VALUE in interactive mode. `--provider` on
+    // the CLI signals scripted invocation; bombarding a script with a
+    // password prompt it can't satisfy would deadlock CI runs.
+    if (args.provider === undefined) {
+      const tokenPromptResult = await maybePromptTunnelTokenValue(cwd, tokenEnv, prompts)
+      if (!tokenPromptResult.ok) return tokenPromptResult
+    }
+  }
 
   const tunnel: TunnelConfig = {
-    name: args.name,
+    name,
     provider,
     for: tunnelFor,
     ...(externalUrl !== undefined ? { externalUrl } : {}),
     ...(upstreamPort !== undefined ? { upstreamPort } : {}),
+    ...(hostname !== undefined ? { hostname } : {}),
+    ...(tokenEnv !== undefined ? { tokenEnv } : {}),
   }
   const raw = readRawConfig(cwd)
   raw.tunnels = [...config.tunnels, tunnel]
-  if (provider === 'cloudflare-quick') {
+  if (provider === 'cloudflare-quick' || provider === 'cloudflare-named') {
     raw.docker = { ...asRecord(raw.docker), file: { ...asRecord(asRecord(raw.docker).file), cloudflared: true } }
   }
   writeRawConfig(cwd, raw)
@@ -224,7 +358,7 @@ export function runTunnelRemoveFlow(cwd: string, args: RemoveArgs): LiveResult<{
   if (tunnel.for.kind === 'channel') {
     return {
       ok: false,
-      reason: `tunnel "${args.name}" is owned by channel "${tunnel.for.name}"; run typeclaw channel remove ${tunnel.for.name}`,
+      reason: `tunnel "${args.name}" is owned by channel "${tunnel.for.name}". Use \`typeclaw tunnel set ${args.name}\` to change its provider/URL, or hand-edit typeclaw.json to remove both the channel block and the tunnel.`,
     }
   }
   const raw = readRawConfig(cwd)
@@ -234,6 +368,243 @@ export function runTunnelRemoveFlow(cwd: string, args: RemoveArgs): LiveResult<{
   return { ok: true, value: { removed: tunnel } }
 }
 
+export async function runTunnelSetFlow(
+  cwd: string,
+  args: SetArgs,
+  prompts: TunnelPrompts = defaultPrompts,
+): Promise<LiveResult<TunnelConfig>> {
+  const validation = validateConfig(cwd)
+  if (!validation.ok) return { ok: false, reason: validation.reason }
+  const config = loadConfigSync(cwd)
+  if (config.tunnels.length === 0) {
+    return { ok: false, reason: 'no tunnels configured. Run `typeclaw tunnel add` first.' }
+  }
+  const nameResult =
+    args.name !== undefined
+      ? { ok: true as const, value: args.name }
+      : await resolveExistingTunnelName(config.tunnels, prompts)
+  if (!nameResult.ok) return nameResult
+  const existing = config.tunnels.find((entry) => entry.name === nameResult.value)
+  if (existing === undefined) return { ok: false, reason: `unknown tunnel: ${nameResult.value}` }
+
+  const flagFields = collectSetFlagFields(args)
+  const interactive = flagFields.length === 0
+
+  let nextProvider = existing.provider
+  let nextExternalUrl = existing.externalUrl
+  let nextHostname = existing.hostname
+  let nextTokenEnv = existing.tokenEnv
+  let nextUpstreamPort = existing.upstreamPort
+
+  if (args.provider !== undefined) {
+    const resolved = await resolveProvider(args.provider, prompts)
+    nextProvider = resolved
+  } else if (interactive) {
+    const choices = buildSetFieldChoices(existing)
+    if (choices.length === 0) {
+      return {
+        ok: false,
+        reason: `tunnel "${existing.name}" has no editable fields for provider "${existing.provider}"`,
+      }
+    }
+    if (prompts.selectSetField === undefined) {
+      return { ok: false, reason: 'interactive set requires selectSetField prompt (pass a flag, e.g. --provider)' }
+    }
+    const field = await prompts.selectSetField(choices)
+    if (isCancel(field)) {
+      cancel('Aborted.')
+      process.exit(0)
+    }
+    if (field === 'provider') {
+      nextProvider = await resolveProvider(undefined, prompts)
+    } else {
+      const interactivePatch = await collectInteractiveFieldPatch(field, prompts)
+      if (!interactivePatch.ok) return interactivePatch
+      nextExternalUrl = interactivePatch.value.externalUrl ?? nextExternalUrl
+      nextHostname = interactivePatch.value.hostname ?? nextHostname
+      nextTokenEnv = interactivePatch.value.tokenEnv ?? nextTokenEnv
+      nextUpstreamPort = interactivePatch.value.upstreamPort ?? nextUpstreamPort
+    }
+  }
+
+  if (args.externalUrl !== undefined) {
+    const err = validateHttpsUrl(args.externalUrl)
+    if (err !== undefined) return { ok: false, reason: `external URL: ${err}` }
+    nextExternalUrl = args.externalUrl
+  }
+  if (args.hostname !== undefined) {
+    const err = validateHttpsUrl(args.hostname)
+    if (err !== undefined) return { ok: false, reason: `hostname: ${err}` }
+    nextHostname = args.hostname
+  }
+  if (args.tokenEnv !== undefined) {
+    const err = validateTokenEnv(args.tokenEnv)
+    if (err !== undefined) return { ok: false, reason: `token-env: ${err}` }
+    nextTokenEnv = args.tokenEnv
+  }
+  if (args.upstreamPort !== undefined) {
+    const err = validateUpstreamPort(args.upstreamPort)
+    if (err !== undefined) return { ok: false, reason: `upstream port: ${err}` }
+    nextUpstreamPort = Number(args.upstreamPort)
+  }
+
+  // On a provider switch, drop fields the new provider forbids and require
+  // fields the new provider needs. This mirrors the per-provider refinements
+  // in tunnelEntrySchema (src/config/config.ts) so the schema-validation
+  // round-trip after write doesn't fail on stale fields from the old shape.
+  if (nextProvider !== existing.provider) {
+    if (nextProvider !== 'external') nextExternalUrl = undefined
+    if (nextProvider !== 'cloudflare-named') {
+      nextHostname = undefined
+      nextTokenEnv = undefined
+    }
+    if (nextProvider === 'cloudflare-named') nextUpstreamPort = undefined
+    if (nextProvider === 'external' && nextExternalUrl === undefined) {
+      const raw =
+        args.externalUrl ??
+        (interactive ? await promptText('External HTTPS URL', prompts, validateHttpsUrl) : undefined)
+      if (raw === undefined) return { ok: false, reason: "provider 'external' requires --external-url" }
+      const err = validateHttpsUrl(raw)
+      if (err !== undefined) return { ok: false, reason: `external URL: ${err}` }
+      nextExternalUrl = raw
+    }
+    if (nextProvider === 'cloudflare-named') {
+      if (nextHostname === undefined) {
+        const raw =
+          args.hostname ??
+          (interactive
+            ? await promptText(
+                'Public hostname configured in the Cloudflare dashboard (https://...)',
+                prompts,
+                validateHttpsUrl,
+              )
+            : undefined)
+        if (raw === undefined) return { ok: false, reason: "provider 'cloudflare-named' requires --hostname" }
+        const err = validateHttpsUrl(raw)
+        if (err !== undefined) return { ok: false, reason: `hostname: ${err}` }
+        nextHostname = raw
+      }
+      if (nextTokenEnv === undefined) {
+        const raw = args.tokenEnv ?? DEFAULT_TUNNEL_TOKEN_ENV
+        const err = validateTokenEnv(raw)
+        if (err !== undefined) return { ok: false, reason: `token-env: ${err}` }
+        nextTokenEnv = raw
+      }
+    }
+    if (existing.for.kind === 'manual' && nextProvider !== 'cloudflare-named' && nextUpstreamPort === undefined) {
+      const raw = interactive ? await promptText('Upstream port', prompts, validateUpstreamPort) : undefined
+      if (raw === undefined)
+        return { ok: false, reason: 'manual tunnels require --upstream-port (except cloudflare-named)' }
+      const err = validateUpstreamPort(raw)
+      if (err !== undefined) return { ok: false, reason: `upstream port: ${err}` }
+      nextUpstreamPort = Number(raw)
+    }
+  }
+
+  const next: TunnelConfig = {
+    name: existing.name,
+    provider: nextProvider,
+    for: existing.for,
+    ...(nextExternalUrl !== undefined ? { externalUrl: nextExternalUrl } : {}),
+    ...(nextUpstreamPort !== undefined ? { upstreamPort: nextUpstreamPort } : {}),
+    ...(nextHostname !== undefined ? { hostname: nextHostname } : {}),
+    ...(nextTokenEnv !== undefined ? { tokenEnv: nextTokenEnv } : {}),
+  }
+
+  if (interactive && next.provider === 'cloudflare-named' && next.tokenEnv !== undefined) {
+    const tokenPromptResult = await maybePromptTunnelTokenValue(cwd, next.tokenEnv, prompts)
+    if (!tokenPromptResult.ok) return tokenPromptResult
+  }
+
+  const raw = readRawConfig(cwd)
+  raw.tunnels = config.tunnels.map((entry) => (entry.name === existing.name ? next : entry))
+  if (nextProvider === 'cloudflare-quick' || nextProvider === 'cloudflare-named') {
+    raw.docker = { ...asRecord(raw.docker), file: { ...asRecord(asRecord(raw.docker).file), cloudflared: true } }
+  }
+  writeRawConfig(cwd, raw)
+  // The strict gate above already validated the on-disk shape; calling
+  // validateConfig again here catches any post-write schema violation (e.g.
+  // a provider/field combination the explicit checks above missed) and
+  // surfaces it as a clean LiveResult instead of a thrown error on the next
+  // `loadConfigSync`. We roll back the file on failure so the user's
+  // typeclaw.json doesn't end up in an invalid state.
+  const postWrite = validateConfig(cwd)
+  if (!postWrite.ok) {
+    raw.tunnels = config.tunnels
+    writeRawConfig(cwd, raw)
+    return { ok: false, reason: postWrite.reason }
+  }
+  loadConfigSync(cwd)
+  return { ok: true, value: next }
+}
+
+function collectSetFlagFields(args: SetArgs): TunnelSetField[] {
+  const out: TunnelSetField[] = []
+  if (args.provider !== undefined) out.push('provider')
+  if (args.externalUrl !== undefined) out.push('externalUrl')
+  if (args.hostname !== undefined) out.push('hostname')
+  if (args.tokenEnv !== undefined) out.push('tokenEnv')
+  if (args.upstreamPort !== undefined) out.push('upstreamPort')
+  return out
+}
+
+function buildSetFieldChoices(existing: TunnelConfig): { value: TunnelSetField; label: string; hint?: string }[] {
+  const choices: { value: TunnelSetField; label: string; hint?: string }[] = [
+    { value: 'provider', label: 'Provider', hint: `currently ${existing.provider}` },
+  ]
+  if (existing.provider === 'external') {
+    choices.push({ value: 'externalUrl', label: 'External URL', hint: existing.externalUrl ?? '-' })
+  }
+  if (existing.provider === 'cloudflare-named') {
+    choices.push({ value: 'hostname', label: 'Hostname', hint: existing.hostname ?? '-' })
+    choices.push({ value: 'tokenEnv', label: 'Token env var name', hint: existing.tokenEnv ?? '-' })
+  }
+  if (existing.for.kind === 'manual' && existing.provider !== 'cloudflare-named') {
+    choices.push({
+      value: 'upstreamPort',
+      label: 'Upstream port',
+      hint: existing.upstreamPort !== undefined ? String(existing.upstreamPort) : '-',
+    })
+  }
+  return choices
+}
+
+async function collectInteractiveFieldPatch(
+  field: Exclude<TunnelSetField, 'provider'>,
+  prompts: TunnelPrompts,
+): Promise<LiveResult<{ externalUrl?: string; hostname?: string; tokenEnv?: string; upstreamPort?: number }>> {
+  switch (field) {
+    case 'externalUrl': {
+      const value = await promptText('External HTTPS URL', prompts, validateHttpsUrl)
+      const err = validateHttpsUrl(value)
+      if (err !== undefined) return { ok: false, reason: `external URL: ${err}` }
+      return { ok: true, value: { externalUrl: value } }
+    }
+    case 'hostname': {
+      const value = await promptText(
+        'Public hostname configured in the Cloudflare dashboard (https://...)',
+        prompts,
+        validateHttpsUrl,
+      )
+      const err = validateHttpsUrl(value)
+      if (err !== undefined) return { ok: false, reason: `hostname: ${err}` }
+      return { ok: true, value: { hostname: value } }
+    }
+    case 'tokenEnv': {
+      const value = await promptText('Env var name holding the tunnel token', prompts, validateTokenEnv)
+      const err = validateTokenEnv(value)
+      if (err !== undefined) return { ok: false, reason: `token-env: ${err}` }
+      return { ok: true, value: { tokenEnv: value } }
+    }
+    case 'upstreamPort': {
+      const value = await promptText('Upstream port', prompts, validateUpstreamPort)
+      const err = validateUpstreamPort(value)
+      if (err !== undefined) return { ok: false, reason: `upstream port: ${err}` }
+      return { ok: true, value: { upstreamPort: Number(value) } }
+    }
+  }
+}
+
 export async function fetchTunnelList(opts: {
   cwd: string
   url?: string
@@ -378,8 +749,50 @@ function parseLiveArgs(args: LiveArgs): { url?: string; timeoutMs: number } {
   return { ...(args.url !== undefined ? { url: args.url } : {}), timeoutMs }
 }
 
+async function resolveExistingTunnelName(
+  tunnels: readonly TunnelConfig[],
+  prompts: TunnelPrompts,
+): Promise<LiveResult<string>> {
+  if (tunnels.length === 1) return { ok: true, value: tunnels[0]!.name }
+  if (prompts.selectExistingTunnel === undefined) {
+    return {
+      ok: false,
+      reason: 'interactive set requires selectExistingTunnel prompt (pass the tunnel name positionally)',
+    }
+  }
+  const choices = tunnels.map((entry) => ({
+    value: entry.name,
+    label: entry.name,
+    hint: `${entry.provider} · ${entry.for.kind === 'channel' ? `channel:${entry.for.name}` : 'manual'}`,
+  }))
+  const choice = await prompts.selectExistingTunnel(choices)
+  if (isCancel(choice)) {
+    cancel('Aborted.')
+    process.exit(0)
+  }
+  return { ok: true, value: choice }
+}
+
+async function maybePromptTunnelTokenValue(
+  cwd: string,
+  tokenEnv: string,
+  prompts: TunnelPrompts,
+): Promise<LiveResult<void>> {
+  if (hasEnvKey(cwd, tokenEnv)) return { ok: true, value: undefined }
+  if (prompts.password === undefined) return { ok: true, value: undefined }
+  const value = await prompts.password(`Cloudflare tunnel token (will be written to .env as ${tokenEnv})`, (v) =>
+    v.length > 0 ? undefined : 'Token is required',
+  )
+  if (isCancel(value)) {
+    cancel('Aborted.')
+    process.exit(0)
+  }
+  appendOrReplaceEnvKey(cwd, tokenEnv, value)
+  return { ok: true, value: undefined }
+}
+
 async function resolveProvider(input: string | undefined, prompts: TunnelPrompts): Promise<TunnelProvider> {
-  if (input === 'external' || input === 'cloudflare-quick') return input
+  if (input === 'external' || input === 'cloudflare-quick' || input === 'cloudflare-named') return input
   if (input !== undefined) throw new Error(`unknown tunnel provider: ${input}`)
   const choice = await prompts.selectProvider()
   if (isCancel(choice)) {
@@ -419,6 +832,24 @@ function validateNonEmpty(requiredMessage: string): TextValidator {
   return (value) => (value.trim().length > 0 ? undefined : requiredMessage)
 }
 
+// Mirrors the regex on `tunnelEntrySchema.name` in src/config/config.ts so
+// the interactive prompt rejects shapes the post-write schema validation
+// would reject anyway, but with a clear inline error instead of a Zod dump.
+const TUNNEL_NAME_REGEX = /^[a-z0-9][a-z0-9-_]*$/
+
+function validateTunnelName(value: string, existing: ReadonlySet<string>): string | undefined {
+  if (value.trim().length === 0) return 'Tunnel name is required'
+  if (!TUNNEL_NAME_REGEX.test(value)) {
+    return 'Tunnel name must match /^[a-z0-9][a-z0-9-_]*$/ (lowercase, digits, dashes, underscores)'
+  }
+  if (existing.has(value)) return `tunnel "${value}" already exists`
+  return undefined
+}
+
+function makeTunnelNameValidator(existing: ReadonlySet<string>): TextValidator {
+  return (value) => validateTunnelName(value, existing)
+}
+
 function validateUpstreamPort(value: string): string | undefined {
   if (value.trim().length === 0) return 'Upstream port is required'
   const port = Number(value)
@@ -437,6 +868,14 @@ function validateHttpsUrl(value: string): string | undefined {
   }
 }
 
+function validateTokenEnv(value: string): string | undefined {
+  if (value.trim().length === 0) return 'Env var name is required'
+  if (!/^[A-Z_][A-Z0-9_]*$/.test(value)) {
+    return 'Must be an env var name like CLOUDFLARE_TUNNEL_TOKEN (uppercase, digits, underscore)'
+  }
+  return undefined
+}
+
 function ensureAgentDir(): string {
   const cwd = findAgentDir(process.cwd()) ?? process.cwd()
   if (!isInitialized(cwd)) {

package/src/config/config.ts

@@ -250,16 +250,24 @@ export type NetworkConfig = z.infer<typeof networkSchema>
 
 // Reverse-proxy tunnels expose a container-private port to the public internet
 // via a managed subprocess (cloudflared) or a user-supplied external URL.
-// See AGENTS.md `## Tunnels`. PR 2 ships `cloudflare-quick`; `cloudflare-named`
-// remains deferred to PR 3. Keeping the enum scoped to what's implemented means
-// validateConfig() rejects unsupported providers at `typeclaw start` time,
-// before the container is torn down and rebuilt. `restart-required` because
-// the tunnel manager reads this list once at boot.
+// See AGENTS.md `## Tunnels`. Keeping the enum scoped to what's implemented
+// means validateConfig() rejects unsupported providers at `typeclaw start`
+// time, before the container is torn down and rebuilt. `restart-required`
+// because the tunnel manager reads this list once at boot.
 const tunnelForSchema = z.discriminatedUnion('kind', [
   z.object({ kind: z.literal('channel'), name: z.string().trim().min(1) }),
   z.object({ kind: z.literal('manual') }),
 ])
 
+// `tokenEnv` is the NAME of an env var, not the token itself. Restrict to the
+// shell-portable identifier shape (uppercase + digits + underscore, leading
+// non-digit) so a value typed here can't break `--env-file` parsing or shell
+// expansion inside the container. Matches the convention every other env var
+// in the codebase already follows (TYPECLAW_*, OPENAI_*, etc.).
+const tokenEnvNameSchema = z.string().regex(/^[A-Z_][A-Z0-9_]*$/, {
+  message: 'tokenEnv must be an env var name like CLOUDFLARE_TUNNEL_TOKEN (uppercase, digits, underscore)',
+})
+
 const tunnelEntrySchema = z
   .object({
     name: z
@@ -268,7 +276,7 @@ const tunnelEntrySchema = z
       .regex(/^[a-z0-9][a-z0-9-_]*$/, {
         message: 'tunnel name must match /^[a-z0-9][a-z0-9-_]*$/ (lowercase, digits, dashes, underscores)',
       }),
-    provider: z.enum(['external', 'cloudflare-quick']),
+    provider: z.enum(['external', 'cloudflare-quick', 'cloudflare-named']),
     for: tunnelForSchema,
     externalUrl: z
       .string()
@@ -276,11 +284,31 @@ const tunnelEntrySchema = z
       .refine((u) => u.startsWith('https://'), { message: 'externalUrl must use https://' })
       .optional(),
     upstreamPort: z.number().int().min(1).max(65535).optional(),
+    hostname: z
+      .string()
+      .url()
+      .refine((u) => u.startsWith('https://'), { message: 'hostname must use https://' })
+      .optional(),
+    tokenEnv: tokenEnvNameSchema.optional(),
   })
   .refine((v) => v.provider !== 'external' || (v.externalUrl !== undefined && v.externalUrl.trim() !== ''), {
     message: "tunnels[].externalUrl is required when provider is 'external'",
   })
-  .refine((v) => v.for.kind !== 'manual' || v.upstreamPort !== undefined, {
+  .refine((v) => v.provider !== 'cloudflare-named' || (v.hostname !== undefined && v.hostname.trim() !== ''), {
+    message: "tunnels[].hostname is required when provider is 'cloudflare-named'",
+  })
+  .refine((v) => v.provider !== 'cloudflare-named' || (v.tokenEnv !== undefined && v.tokenEnv.trim() !== ''), {
+    message: "tunnels[].tokenEnv is required when provider is 'cloudflare-named'",
+  })
+  // cloudflared learns the upstream from the Cloudflare dashboard's Public
+  // Hostname mapping, not from typeclaw. An `upstreamPort` here would be
+  // silently ignored; reject at parse time so the contradiction surfaces in
+  // the config file rather than as a debugging surprise.
+  .refine((v) => v.provider !== 'cloudflare-named' || v.upstreamPort === undefined, {
+    message:
+      "tunnels[].upstreamPort must not be set when provider is 'cloudflare-named' (cloudflared reads the upstream from the Cloudflare dashboard)",
+  })
+  .refine((v) => v.for.kind !== 'manual' || v.provider === 'cloudflare-named' || v.upstreamPort !== undefined, {
     message: "tunnels[].upstreamPort is required when for.kind is 'manual'",
   })