typeclaw 0.1.5 → 0.2.0

package/src/permissions/resolve.ts

@@ -0,0 +1,80 @@
+import type { AdapterId } from '@/channels/schema'
+
+import type { MatchRule, Platform } from './match-rule'
+
+const ADAPTER_TO_PLATFORM: Record<AdapterId, Platform> = {
+  'slack-bot': 'slack',
+  'discord-bot': 'discord',
+  'telegram-bot': 'telegram',
+  kakaotalk: 'kakao',
+}
+
+export type MatchableOrigin =
+  | { kind: 'tui'; sessionId?: string }
+  | { kind: 'cron'; jobId?: string }
+  | { kind: 'subagent'; subagent?: string }
+  | {
+      kind: 'channel'
+      adapter: AdapterId
+      workspace: string
+      chat: string
+      lastInboundAuthorId?: string
+    }
+
+export function matchesOrigin(rule: MatchRule, origin: MatchableOrigin): boolean {
+  switch (rule.kind) {
+    case 'wildcard':
+      return origin.kind === 'channel'
+    case 'tui':
+      return origin.kind === 'tui'
+    case 'cron':
+      return origin.kind === 'cron'
+    case 'subagent':
+      if (origin.kind !== 'subagent') return false
+      if (rule.subagent === undefined) return true
+      return origin.subagent === rule.subagent
+    case 'channel':
+      return matchesChannel(rule, origin)
+  }
+}
+
+function matchesChannel(rule: Extract<MatchRule, { kind: 'channel' }>, origin: MatchableOrigin): boolean {
+  if (origin.kind !== 'channel') return false
+  if (ADAPTER_TO_PLATFORM[origin.adapter] !== rule.platform) return false
+
+  if (rule.bucket !== undefined) {
+    if (!matchesBucket(rule.bucket, origin)) return false
+    if (rule.chat !== undefined && rule.chat !== origin.chat) return false
+  } else {
+    if (rule.workspace !== undefined && rule.workspace !== origin.workspace) return false
+    if (rule.chat !== undefined && rule.chat !== origin.chat) return false
+  }
+
+  if (rule.author !== undefined && rule.author !== origin.lastInboundAuthorId) return false
+  return true
+}
+
+// DM and group buckets are inferred from the workspace/chat shape of the
+// inbound origin. Different adapters mark DMs differently — Slack uses an
+// `@dm` workspace marker today, Discord uses a `dm` workspace marker, and
+// KakaoTalk preserves group/open/dm explicitly in its workspace field. We
+// keep the heuristic narrow: a rule that says `slack:dm/*` matches only when
+// the origin's workspace is `@dm` (Slack) or `dm` (Discord). KakaoTalk uses
+// the workspace prefix itself.
+function matchesBucket(
+  bucket: 'dm' | 'group' | 'open',
+  origin: Extract<MatchableOrigin, { kind: 'channel' }>,
+): boolean {
+  const platform = ADAPTER_TO_PLATFORM[origin.adapter]
+  if (platform === 'kakao') {
+    if (bucket === 'dm') return origin.workspace === '@kakao-dm'
+    if (bucket === 'group') return origin.workspace === '@kakao-group'
+    if (bucket === 'open') return origin.workspace === '@kakao-open'
+    return false
+  }
+  if (bucket !== 'dm') return false
+  if (platform === 'slack') return origin.workspace === '@dm'
+  if (platform === 'discord') return origin.workspace === 'dm' || origin.workspace === '@dm'
+  if (platform === 'telegram') return origin.workspace === 'dm' || origin.workspace.startsWith('@')
+  return false
+}

package/src/permissions/schema.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod'
+
+import { isBuiltinRoleName } from './builtins'
+import { type MatchRule, MATCH_RULE_REGEX_SOURCE, parseMatchRule } from './match-rule'
+
+// The `.regex()` is added so the generated JSON Schema emits a `pattern`
+// for editor-time validation (catches typos like `tem:T0123` before the
+// agent ever boots). The pattern is intentionally a permissive
+// over-approximation of what `parseMatchRule` accepts; the parser owns
+// the precise semantic errors (typo suggestions, redundant-form rejection,
+// etc.) at boot time. Layering the two means editors flag obvious shape
+// mistakes immediately and the parser flags the rest with actionable
+// messages.
+const matchRuleSchema: z.ZodType<MatchRule> = z
+  .string()
+  .regex(new RegExp(MATCH_RULE_REGEX_SOURCE), {
+    message: "match rule must look like 'tui' / 'slack:T0123' / 'discord:9999 author:U_X'",
+  })
+  .transform((raw, ctx) => {
+    const parsed = parseMatchRule(raw)
+    if (!parsed.ok) {
+      ctx.addIssue({ code: 'custom', message: parsed.error })
+      return z.NEVER
+    }
+    return parsed.value
+  })
+
+export const MATCH_RULE_JSON_SCHEMA_PATTERN = MATCH_RULE_REGEX_SOURCE
+
+const PERMISSION_NAME = /^[a-z][a-z0-9]*(\.[a-z][a-zA-Z0-9]*)+$/
+
+const permissionSchema = z.string().min(1).regex(PERMISSION_NAME, {
+  message: "permission must be lowercase dotted form like 'cron.schedule' or 'security.bypass.foo'",
+})
+
+const roleConfigSchema = z
+  .object({
+    match: z.array(matchRuleSchema).default([]),
+    permissions: z.array(permissionSchema).optional(),
+  })
+  .strict()
+
+export type RoleConfig = z.infer<typeof roleConfigSchema>
+
+export const rolesConfigSchema = z.record(z.string(), roleConfigSchema).superRefine((roles, ctx) => {
+  for (const [name, role] of Object.entries(roles)) {
+    if (!isValidRoleName(name)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: [name],
+        message: `role name '${name}' must match /^[a-z][a-z0-9-]*$/`,
+      })
+      continue
+    }
+    if (!isBuiltinRoleName(name)) {
+      if (role.permissions === undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [name, 'permissions'],
+          message: `custom role '${name}' must declare 'permissions' (built-in defaults apply only to built-in role names)`,
+        })
+      }
+      if (role.match.length === 0) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [name, 'match'],
+          message: `custom role '${name}' must declare at least one 'match' rule`,
+        })
+      }
+    }
+  }
+})
+
+export type RolesConfig = z.infer<typeof rolesConfigSchema>
+
+const ROLE_NAME = /^[a-z][a-z0-9-]*$/
+function isValidRoleName(name: string): boolean {
+  return ROLE_NAME.test(name)
+}

package/src/plugin/context.ts

@@ -1,6 +1,8 @@
-import type { PluginContext, PluginLogger } from './types'
+import type { PermissionService } from '@/permissions'
 
-export type SpawnSubagentFn = (name: string, payload?: unknown) => Promise<void>
+import type { PluginContext, PluginLogger, SpawnSubagentOptions } from './types'
+
+export type SpawnSubagentFn = (name: string, payload?: unknown, options?: SpawnSubagentOptions) => Promise<void>
 
 export type CreatePluginContextOptions<TConfig> = {
   name: string
@@ -8,6 +10,7 @@ export type CreatePluginContextOptions<TConfig> = {
   agentDir: string
   config: TConfig
   logger: PluginLogger
+  permissions: PermissionService
   spawnSubagent: SpawnSubagentFn
   isBooted: () => boolean
 }
@@ -19,13 +22,14 @@ export function createPluginContext<TConfig>(opts: CreatePluginContextOptions<TC
     agentDir: opts.agentDir,
     config: opts.config,
     logger: opts.logger,
-    spawnSubagent: async (name: string, payload?: unknown) => {
+    permissions: opts.permissions,
+    spawnSubagent: async (name: string, payload?: unknown, options?: SpawnSubagentOptions) => {
       if (!opts.isBooted()) {
         throw new Error(
           `plugin ${opts.name}: spawnSubagent("${name}") called before boot completed; subagent registry is not yet wired`,
         )
       }
-      await opts.spawnSubagent(name, payload)
+      await opts.spawnSubagent(name, payload, options)
     },
   })
 }

package/src/plugin/define.ts

@@ -6,9 +6,11 @@ type DefinePluginSpec<S extends z.ZodType<unknown> | undefined> =
   S extends z.ZodType<infer T>
     ? {
         configSchema: S
+        permissions?: readonly string[]
         plugin: (ctx: PluginContext<T>) => Promise<PluginExports>
       }
     : {
+        permissions?: readonly string[]
         plugin: (ctx: PluginContext<unknown>) => Promise<PluginExports>
       }
 

package/src/plugin/index.ts

@@ -36,6 +36,7 @@ export type {
   SessionIdleEvent,
   SessionPromptEvent,
   SessionStartEvent,
+  SpawnSubagentOptions,
   Subagent,
   SubagentContext,
   Tool,
@@ -54,6 +55,7 @@ export {
   type LoadPluginsOptions,
   type LoadPluginsResult,
 } from './manager'
+export type { PermissionService } from '@/permissions'
 export type { LoadPluginEntryFn, ResolvedPlugin } from './loader'
 export { loadPluginEntry, derivePluginNameFromPackage } from './loader'
 export { materializeSkills, type MaterializedSkills, type SkillEntry } from './skills'

package/src/plugin/manager.ts

@@ -1,6 +1,12 @@
 import { z } from 'zod'
 
 import type { CronJob } from '@/cron'
+import {
+  createPermissionService,
+  findUnknownPermissions,
+  type PermissionService,
+  type RolesConfig,
+} from '@/permissions'
 
 import { createPluginContext, createPluginLogger, type SpawnSubagentFn } from './context'
 import { createHookBus, type HookBus } from './hooks'
@@ -13,6 +19,7 @@ export type LoadPluginsOptions = {
   agentDir: string
   configsByName: Record<string, unknown>
   loadEntry?: LoadPluginEntryFn
+  roles?: RolesConfig
   // Bundled plugins resolved by the runtime (not from typeclaw.json). Loaded
   // before user-declared `entries` so a config block named after a bundled
   // plugin (e.g. "memory") is consumed by the bundled plugin, and so plugin-
@@ -23,6 +30,8 @@ export type LoadPluginsOptions = {
 export type LoadPluginsResult = {
   registry: PluginRegistry
   hooks: HookBus
+  permissions: PermissionService
+  declaredPermissions: readonly string[]
   loadedPlugins: { name: string; version: string | undefined; source: string }[]
   markBooted: () => void
   setSpawnSubagent: (fn: SpawnSubagentFn) => void
@@ -46,6 +55,23 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
     )),
   ]
 
+  const declaredPermissions = collectDeclaredPermissions(allPlugins)
+  const permissions = createPermissionService({
+    ...(opts.roles !== undefined ? { roles: opts.roles } : {}),
+    pluginPermissions: declaredPermissions,
+  })
+
+  // Non-fatal: surface user-declared `permissions[]` strings that aren't in
+  // the known set, so a typo like `security.bypass.secretExfilBach` is
+  // visible at boot rather than silently failing to bypass the matching
+  // guard. We log instead of throw because the runtime still functions --
+  // the unknown string just never matches anything.
+  for (const warning of findUnknownPermissions(opts.roles, declaredPermissions)) {
+    console.warn(
+      `[permissions] role "${warning.role}" declares unknown permission "${warning.permission}" — ${warning.hint}`,
+    )
+  }
+
   for (const { entry, resolved } of allPlugins) {
     if (loaded.find((l) => l.name === resolved.name)) {
       throw new Error(`plugin name conflict: ${resolved.name} (entry ${entry}) already loaded`)
@@ -72,6 +98,7 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
       agentDir: opts.agentDir,
       config: validatedConfig as never,
       logger,
+      permissions,
       spawnSubagent: (name, payload) => spawnSubagentImpl(name, payload),
       isBooted: () => booted,
     })
@@ -106,6 +133,8 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
   return {
     registry,
     hooks,
+    permissions,
+    declaredPermissions,
     loadedPlugins: loaded,
     markBooted: () => {
       booted = true
@@ -116,6 +145,18 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
   }
 }
 
+function collectDeclaredPermissions(
+  plugins: readonly { entry: string; resolved: ResolvedPlugin }[],
+): readonly string[] {
+  const out: string[] = []
+  for (const { resolved } of plugins) {
+    for (const perm of resolved.defined.permissions ?? []) {
+      if (!out.includes(perm)) out.push(perm)
+    }
+  }
+  return out
+}
+
 export function summarizeLoaded(loaded: LoadPluginsResult['loadedPlugins'], registry: PluginRegistry): string {
   const head = loaded.map((p) => (p.version !== undefined ? `${p.name} v${p.version}` : p.name)).join(', ')
   const counts = [

package/src/plugin/registry.ts

@@ -150,6 +150,13 @@ function assertNotEmpty(kind: string, value: string, pluginName: string): void {
 }
 
 function toCronJob(globalId: string, spec: PluginCronJob): CronJob {
+  // Plugin-contributed jobs default to `owner` because they are part of the
+  // agent's bundled (or operator-installed) runtime, not user-channel
+  // schedules. Without this default they would resolve to `guest` and the
+  // bundled memory dreaming cron (which writes MEMORY.md, runs git, etc.)
+  // would lose every security bypass. Hand-authored cron.json entries take
+  // a different path and must declare scheduledByRole explicitly.
+  const scheduledByRole: PromptJob['scheduledByRole'] = 'owner'
   if (spec.kind === 'prompt') {
     const job: PromptJob = {
       id: globalId,
@@ -157,6 +164,7 @@ function toCronJob(globalId: string, spec: PluginCronJob): CronJob {
       enabled: spec.enabled ?? true,
       kind: 'prompt',
       prompt: spec.prompt,
+      scheduledByRole,
       ...(spec.timezone !== undefined ? { timezone: spec.timezone } : {}),
       ...(spec.subagent !== undefined ? { subagent: spec.subagent } : {}),
       ...(spec.payload !== undefined ? { payload: spec.payload } : {}),
@@ -169,6 +177,7 @@ function toCronJob(globalId: string, spec: PluginCronJob): CronJob {
     enabled: spec.enabled ?? true,
     kind: 'exec',
     command: spec.command,
+    scheduledByRole,
     ...(spec.timezone !== undefined ? { timezone: spec.timezone } : {}),
   }
 }

package/src/plugin/types.ts

@@ -1,6 +1,8 @@
 import type { z } from 'zod'
 
 import type { SessionOrigin } from '@/agent/session-origin'
+import type { ToolResultBudget } from '@/agent/tool-result-budget'
+import type { PermissionService } from '@/permissions'
 
 export type ContentPart = { type: 'text'; text: string } | { type: 'image'; mimeType: string; data: string }
 
@@ -40,6 +42,13 @@ export type RunSession = (override?: { userPrompt?: string }) => Promise<void>
 
 export type Subagent<P = unknown> = {
   systemPrompt: string
+  // Model profile this subagent prefers. Resolved against `models` in
+  // typeclaw.json at session construction. Unknown profile names fall back to
+  // `default` with a warning. Well-known names: `default`, `fast`, `deep`,
+  // `vision`. Subagents that want a specific tier (e.g. memory-logger wants
+  // `fast`, dreaming wants `deep`) declare it here so the user only has to
+  // map tier → model in config rather than wire each subagent individually.
+  profile?: string
   tools?: BuiltinToolRef[]
   customTools?: Tool<any>[]
   payloadSchema?: z.ZodType<P>
@@ -50,6 +59,16 @@ export type Subagent<P = unknown> = {
   // parentSessionId so different parent sessions run in parallel while
   // duplicate runs against the same session deduplicate.
   inFlightKey?: (payload: P) => string
+  // Defensive ceiling on cumulative bytes of tool-result text per subagent
+  // run, applied to the named tools only. Once exceeded, subsequent calls to
+  // those tools short-circuit with a fixed message instructing the agent to
+  // stop reading. See `src/agent/tool-result-budget.ts` for the full
+  // rationale; the short version is: a single broken tool (e.g. find_entry
+  // failing because of a schema mismatch) can cause an agent to fall back to
+  // chunked reads of huge files, ballooning subagent token cost. The budget
+  // bounds the blast radius without changing per-call semantics for healthy
+  // runs.
+  toolResultBudget?: ToolResultBudget
 }
 
 // Cron job map keys are local; the runtime prefixes with `__plugin_<plugin-name>_`
@@ -88,6 +107,7 @@ export type SessionStartEvent = {
 
 export type SessionEndEvent = {
   sessionId: string
+  origin?: SessionOrigin
 }
 
 export type SessionIdleEvent = {
@@ -132,6 +152,7 @@ export type ToolBeforeEvent = {
   sessionId: string
   callId: string
   args: Record<string, unknown>
+  origin?: SessionOrigin
 }
 
 export type ToolBeforeResult = void | undefined | { block: true; reason: string }
@@ -168,13 +189,25 @@ export type PluginLogger = {
   error: (msg: string) => void
 }
 
+export type SpawnSubagentOptions = {
+  // Identifies the spawning session so the subagent's session origin carries
+  // parent provenance. Hook handlers that own this context (e.g. session.idle,
+  // session.turn.end) should pass at minimum `parentSessionId` and
+  // `spawnedByOrigin: event.origin`. The runtime resolves `spawnedByRole`
+  // from the origin via the PermissionService, so the spawning session's
+  // role is inherited rather than forged from outside.
+  parentSessionId?: string
+  spawnedByOrigin?: SessionOrigin
+}
+
 export type PluginContext<TConfig = never> = {
   readonly name: string
   readonly version: string | undefined
   readonly agentDir: string
   readonly config: TConfig
   readonly logger: PluginLogger
-  spawnSubagent: (name: string, payload?: unknown) => Promise<void>
+  readonly permissions: PermissionService
+  spawnSubagent: (name: string, payload?: unknown, options?: SpawnSubagentOptions) => Promise<void>
 }
 
 export type PluginExports = {
@@ -233,5 +266,6 @@ export type PluginFixResult = {
 
 export type DefinedPlugin<TConfig = never> = {
   readonly configSchema?: z.ZodType<TConfig>
+  readonly permissions?: readonly string[]
   readonly plugin: (ctx: PluginContext<TConfig>) => Promise<PluginExports>
 }

package/src/role-claim/client.ts

@@ -0,0 +1,182 @@
+import type {
+  ClaimCompletedPayload,
+  ClaimErrorPayload,
+  ClaimStartedPayload,
+  ClientMessage,
+  ServerMessage,
+} from '@/shared'
+
+import { generateClaimCode } from './code'
+
+export type ClaimSessionOptions = {
+  url: string
+  role: string
+  channel?: string
+  ttlMs?: number
+  connectTimeoutMs?: number
+  onStarted?: (payload: ClaimStartedPayload) => void
+}
+
+export type ClaimSessionResult =
+  | { kind: 'completed'; payload: ClaimCompletedPayload }
+  | { kind: 'error'; payload: ClaimErrorPayload }
+  | { kind: 'timeout' }
+
+const DEFAULT_TTL_MS = 10 * 60 * 1000
+const DEFAULT_CONNECT_TIMEOUT_MS = 30_000
+
+export async function runClaimSession(opts: ClaimSessionOptions): Promise<ClaimSessionResult> {
+  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS
+  const connectTimeoutMs = opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS
+  const code = generateClaimCode()
+
+  const ws = new WebSocket(opts.url)
+  const displayUrl = redactUrl(opts.url)
+  await waitForOpen(ws, displayUrl, connectTimeoutMs)
+  await waitForConnected(ws, displayUrl, connectTimeoutMs)
+
+  try {
+    const request: ClientMessage = {
+      type: 'claim_start',
+      code,
+      role: opts.role,
+      ttlMs,
+      ...(opts.channel !== undefined ? { channel: opts.channel } : {}),
+    }
+    ws.send(JSON.stringify(request))
+
+    return await waitForOutcome(ws, code, ttlMs, opts.onStarted)
+  } finally {
+    try {
+      const cancel: ClientMessage = { type: 'claim_cancel' }
+      ws.send(JSON.stringify(cancel))
+    } catch {}
+    ws.close()
+  }
+}
+
+async function waitForOpen(ws: WebSocket, displayUrl: string, timeoutMs: number): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      cleanup()
+      ws.close()
+      reject(new Error(`timed out connecting to ${displayUrl} after ${timeoutMs}ms`))
+    }, timeoutMs)
+    const onOpen = () => {
+      cleanup()
+      resolve()
+    }
+    const onError = (err: unknown) => {
+      cleanup()
+      reject(new Error(`failed to connect to ${displayUrl}: ${err instanceof Error ? err.message : String(err)}`))
+    }
+    const onClose = () => {
+      cleanup()
+      reject(new Error(`connection to ${displayUrl} closed before opening`))
+    }
+    const cleanup = () => {
+      clearTimeout(timer)
+      ws.removeEventListener('open', onOpen)
+      ws.removeEventListener('error', onError)
+      ws.removeEventListener('close', onClose)
+    }
+    ws.addEventListener('open', onOpen, { once: true })
+    ws.addEventListener('error', onError, { once: true })
+    ws.addEventListener('close', onClose, { once: true })
+  })
+}
+
+// The server's WS `open` handler is async (it awaits createSession) and only
+// registers per-ws state and sends `connected` after that resolves. Bun
+// delivers any client messages received before `open` completes, but the
+// server's `claim_start` handler silently drops messages when state is null.
+// Waiting here mirrors what the TUI client does (see src/tui/index.ts) and
+// fixes the hatching-time hang where the spinner stayed on "Generating your
+// claim code..." until the ttl expired.
+async function waitForConnected(ws: WebSocket, displayUrl: string, timeoutMs: number): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      cleanup()
+      ws.close()
+      reject(new Error(`timed out waiting for connected message from ${displayUrl} after ${timeoutMs}ms`))
+    }, timeoutMs)
+    const onMessage = (event: MessageEvent): void => {
+      let msg: ServerMessage
+      try {
+        msg = JSON.parse(String(event.data)) as ServerMessage
+      } catch {
+        return
+      }
+      if (msg.type === 'connected') {
+        cleanup()
+        resolve()
+        return
+      }
+      if (msg.type === 'error') {
+        cleanup()
+        reject(new Error(`server rejected connection to ${displayUrl}: ${msg.message}`))
+      }
+    }
+    const onClose = () => {
+      cleanup()
+      reject(new Error(`connection to ${displayUrl} closed before the session was ready`))
+    }
+    const cleanup = () => {
+      clearTimeout(timer)
+      ws.removeEventListener('message', onMessage)
+      ws.removeEventListener('close', onClose)
+    }
+    ws.addEventListener('message', onMessage)
+    ws.addEventListener('close', onClose, { once: true })
+  })
+}
+
+async function waitForOutcome(
+  ws: WebSocket,
+  code: string,
+  ttlMs: number,
+  onStarted?: (payload: ClaimStartedPayload) => void,
+): Promise<ClaimSessionResult> {
+  return new Promise<ClaimSessionResult>((resolve) => {
+    const timer = setTimeout(() => {
+      ws.removeEventListener('message', onMessage)
+      resolve({ kind: 'timeout' })
+    }, ttlMs + 5_000)
+
+    const onMessage = (event: MessageEvent): void => {
+      let msg: ServerMessage
+      try {
+        msg = JSON.parse(String(event.data)) as ServerMessage
+      } catch {
+        return
+      }
+      if (msg.type === 'claim_started' && msg.payload.code === code) {
+        onStarted?.(msg.payload)
+        return
+      }
+      if (msg.type === 'claim_completed' && msg.payload.code === code) {
+        clearTimeout(timer)
+        ws.removeEventListener('message', onMessage)
+        resolve({ kind: 'completed', payload: msg.payload })
+        return
+      }
+      if (msg.type === 'claim_error' && msg.payload.code === code) {
+        clearTimeout(timer)
+        ws.removeEventListener('message', onMessage)
+        resolve({ kind: 'error', payload: msg.payload })
+        return
+      }
+    }
+    ws.addEventListener('message', onMessage)
+  })
+}
+
+function redactUrl(url: string): string {
+  try {
+    const parsed = new URL(url)
+    if (parsed.searchParams.has('token')) parsed.searchParams.set('token', '<redacted>')
+    return parsed.toString()
+  } catch {
+    return url
+  }
+}

package/src/role-claim/code.ts

@@ -0,0 +1,53 @@
+import { randomBytes } from 'node:crypto'
+
+// Role-claim codes are short, human-typeable tokens the operator sends from
+// their host CLI to the bot via a channel DM to prove ownership of that
+// channel identity. Shape: `claim-XXXX-YYYY` where each block is 4 chars
+// from a Crockford-style base32 alphabet (0-9 + A-Z minus I, L, O, U to
+// dodge OCR-confusable / profane shapes). 8 chars * 5 bits = 40 bits of
+// entropy, which is overkill for a TTL'd in-memory window but cheap to
+// display and dictate over voice.
+//
+// The `claim-` prefix lets the channel router recognize potential claim
+// attempts in a DM body without scanning the whole text for hex blocks,
+// and distinguishes claim DMs from normal first-message text like "hi"
+// which would otherwise need a regex of its own to disambiguate.
+
+export const CLAIM_CODE_PREFIX = 'claim-'
+
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
+const BLOCK_SIZE = 4
+const BLOCK_COUNT = 2
+
+export function generateClaimCode(): string {
+  const bytes = randomBytes(BLOCK_SIZE * BLOCK_COUNT)
+  const chars: string[] = []
+  for (let i = 0; i < bytes.length; i++) {
+    chars.push(ALPHABET[bytes[i]! % ALPHABET.length]!)
+  }
+  const blocks: string[] = []
+  for (let b = 0; b < BLOCK_COUNT; b++) {
+    blocks.push(chars.slice(b * BLOCK_SIZE, (b + 1) * BLOCK_SIZE).join(''))
+  }
+  return `${CLAIM_CODE_PREFIX}${blocks.join('-')}`
+}
+
+// Extracts the first claim-code-shaped token from inbound text. Returns
+// the canonical-case (upper) code, or null. Tolerates surrounding
+// whitespace, punctuation, and case — chat clients may auto-correct case
+// or surround pastes with quotes/backticks.
+export function extractClaimCode(text: string): string | null {
+  const pattern = new RegExp(
+    `${CLAIM_CODE_PREFIX}([0-9a-zA-Z]{${BLOCK_SIZE}}(?:-[0-9a-zA-Z]{${BLOCK_SIZE}}){${BLOCK_COUNT - 1}})`,
+    'i',
+  )
+  const match = pattern.exec(text)
+  if (!match) return null
+  return `${CLAIM_CODE_PREFIX}${match[1]!.toUpperCase()}`
+}
+
+export function normalizeClaimCode(code: string): string {
+  const trimmed = code.trim()
+  if (!trimmed.toLowerCase().startsWith(CLAIM_CODE_PREFIX)) return trimmed.toUpperCase()
+  return `${CLAIM_CODE_PREFIX}${trimmed.slice(CLAIM_CODE_PREFIX.length).toUpperCase()}`
+}