typeclaw 0.1.5 → 0.2.0

package/src/permissions/builtins.ts

@@ -0,0 +1,70 @@
+import type { MatchRule } from './match-rule'
+
+export type BuiltinRoleName = 'owner' | 'trusted' | 'member' | 'guest'
+
+export const BUILTIN_ROLE_NAMES: readonly BuiltinRoleName[] = ['owner', 'trusted', 'member', 'guest']
+
+// Core-owned permission strings; not contributed by plugins. The security
+// plugin's `security.bypass.*` strings are NOT listed here — they are
+// collected from plugin contributions and merged into `owner`'s permission
+// set at boot via expandOwnerWildcard.
+export const CORE_PERMISSIONS = {
+  channelRespond: 'channel.respond',
+  cronSchedule: 'cron.schedule',
+  cronModify: 'cron.modify',
+} as const
+
+// Sentinel that `expandOwnerWildcard` swaps for the concrete union of
+// plugin-registered `security.bypass.*` strings. Users cannot write `*` in
+// their own `permissions[]`; the sentinel exists only inside the built-in
+// `owner` spec.
+export const OWNER_SECURITY_WILDCARD = '__BUILTIN_OWNER_SECURITY_WILDCARD__'
+
+export type BuiltinRoleSpec = {
+  readonly match: readonly MatchRule[]
+  readonly permissions: readonly string[]
+}
+
+export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> = {
+  owner: {
+    match: [{ kind: 'tui' }],
+    permissions: [
+      CORE_PERMISSIONS.channelRespond,
+      CORE_PERMISSIONS.cronSchedule,
+      CORE_PERMISSIONS.cronModify,
+      OWNER_SECURITY_WILDCARD,
+    ],
+  },
+  trusted: {
+    match: [],
+    permissions: [CORE_PERMISSIONS.channelRespond, CORE_PERMISSIONS.cronSchedule, 'security.bypass.secretExfilBash'],
+  },
+  member: {
+    match: [],
+    permissions: [CORE_PERMISSIONS.channelRespond],
+  },
+  guest: {
+    match: [],
+    permissions: [],
+  },
+}
+
+export function expandOwnerWildcard(
+  ownerPermissions: readonly string[],
+  pluginContributed: readonly string[],
+): readonly string[] {
+  const bypass = pluginContributed.filter((p) => p.startsWith('security.bypass.'))
+  const out: string[] = []
+  for (const p of ownerPermissions) {
+    if (p === OWNER_SECURITY_WILDCARD) {
+      for (const b of bypass) if (!out.includes(b)) out.push(b)
+      continue
+    }
+    if (!out.includes(p)) out.push(p)
+  }
+  return out
+}
+
+export function isBuiltinRoleName(name: string): name is BuiltinRoleName {
+  return (BUILTIN_ROLE_NAMES as readonly string[]).includes(name)
+}

package/src/permissions/grant.ts

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parseMatchRule } from './match-rule'
+
+// Appends `rule` to `typeclaw.json#roles.<name>.match`, creating the role
+// block when missing. Idempotent: re-granting the same rule is a no-op.
+// Atomic: writes via temp+rename so a crashed write never leaves a partial
+// JSON file that would brick the next `typeclaw start`.
+//
+// Used by the role-claim flow (after a successful handshake) and by any
+// future operator-direct grant command. The match rule is validated
+// against the same parser that runs at config load, so a malformed rule
+// fails here instead of bricking the next start.
+
+const CONFIG_FILE = 'typeclaw.json'
+
+export type GrantResult = { ok: true; added: boolean } | { ok: false; reason: string }
+
+export type GrantOptions = {
+  cwd: string
+  roleName: string
+  matchRule: string
+}
+
+export function grantRole(opts: GrantOptions): GrantResult {
+  const validation = parseMatchRule(opts.matchRule)
+  if (!validation.ok) {
+    return { ok: false, reason: `invalid match rule '${opts.matchRule}': ${validation.error}` }
+  }
+
+  const path = join(opts.cwd, CONFIG_FILE)
+  if (!existsSync(path)) {
+    return { ok: false, reason: `${CONFIG_FILE} not found at ${opts.cwd}` }
+  }
+
+  let raw: string
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch (error) {
+    return { ok: false, reason: `failed to read ${CONFIG_FILE}: ${describeError(error)}` }
+  }
+
+  let json: unknown
+  try {
+    json = JSON.parse(raw)
+  } catch (error) {
+    return { ok: false, reason: `${CONFIG_FILE} is not valid JSON: ${describeError(error)}` }
+  }
+
+  if (typeof json !== 'object' || json === null || Array.isArray(json)) {
+    return { ok: false, reason: `${CONFIG_FILE} must be a JSON object` }
+  }
+
+  const obj = json as Record<string, unknown>
+  const roles = isPlainObject(obj.roles) ? { ...obj.roles } : {}
+  const role = isPlainObject(roles[opts.roleName]) ? { ...(roles[opts.roleName] as Record<string, unknown>) } : {}
+  const existingMatch = Array.isArray(role.match) ? [...(role.match as unknown[])] : []
+
+  // Dedup by exact string equality — match rules canonicalize during load,
+  // and a literal duplicate in the file is a noise source the schema doesn't
+  // currently dedupe for us.
+  if (existingMatch.includes(opts.matchRule)) {
+    return { ok: true, added: false }
+  }
+
+  role.match = [...existingMatch, opts.matchRule]
+  roles[opts.roleName] = role
+  obj.roles = roles
+
+  try {
+    writeAtomic(path, `${JSON.stringify(obj, null, 2)}\n`)
+  } catch (error) {
+    return { ok: false, reason: `failed to write ${CONFIG_FILE}: ${describeError(error)}` }
+  }
+
+  return { ok: true, added: true }
+}
+
+function writeAtomic(path: string, content: string): void {
+  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`
+  writeFileSync(tmp, content)
+  try {
+    renameSync(tmp, path)
+  } catch (error) {
+    try {
+      unlinkSync(tmp)
+    } catch {}
+    throw error
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/permissions/index.ts

@@ -0,0 +1,29 @@
+export {
+  BUILTIN_ROLE_NAMES,
+  BUILTIN_ROLES,
+  CORE_PERMISSIONS,
+  OWNER_SECURITY_WILDCARD,
+  expandOwnerWildcard,
+  isBuiltinRoleName,
+  type BuiltinRoleName,
+  type BuiltinRoleSpec,
+} from './builtins'
+export {
+  MATCH_RULE_REGEX_SOURCE,
+  PLATFORMS,
+  parseMatchRule,
+  type MatchRule,
+  type ParseMatchRuleResult,
+  type Platform,
+} from './match-rule'
+export {
+  createPermissionService,
+  findUnknownPermissions,
+  noopPermissionService,
+  type CreatePermissionServiceOptions,
+  type PermissionService,
+  type UnknownPermissionWarning,
+} from './permissions'
+export { grantRole, type GrantOptions, type GrantResult } from './grant'
+export { matchesOrigin, type MatchableOrigin } from './resolve'
+export { MATCH_RULE_JSON_SCHEMA_PATTERN, rolesConfigSchema, type RoleConfig, type RolesConfig } from './schema'

package/src/permissions/match-rule.ts

@@ -0,0 +1,305 @@
+// Compact string DSL for permissions match rules. Examples:
+//
+//   tui                                # any TUI session
+//   cron                               # any cron session (resolved by provenance, not match)
+//   subagent                           # any subagent session
+//   subagent:memory-logger             # specific subagent
+//   *                                  # any channel session, any platform
+//   slack:*                            # any Slack chat, any workspace
+//   slack:T0123                        # one Slack workspace, any chat
+//   slack:T0123/C0ABCDE                # one specific Slack chat
+//   slack:dm/*                         # any Slack DM
+//   slack:T0123 author:U_ME            # specific author across workspace
+//
+// Within one rule: all tokens AND'd. Across multiple rules: OR'd. The parser
+// is hand-rolled (not regex) because the rejection table demands precise
+// error messages with typo suggestions; a single big regex would only ever
+// say "didn't match".
+
+export const PLATFORMS = ['slack', 'discord', 'telegram', 'kakao'] as const
+export type Platform = (typeof PLATFORMS)[number]
+
+const SUBAGENT_NAME = /^[a-z][a-z0-9-]*$/
+
+export type MatchRule =
+  | { kind: 'tui' }
+  | { kind: 'cron' }
+  | { kind: 'subagent'; subagent?: string }
+  | { kind: 'wildcard' }
+  | {
+      kind: 'channel'
+      platform: Platform
+      // undefined when the rule wildcards across the whole platform (e.g. `slack:*`).
+      // '*' is never stored — it is collapsed to undefined at parse time so
+      // matchers stay shape-pure (presence == specificity).
+      workspace?: string
+      chat?: string
+      // Buckets for DM-style scopes. `slack:dm/*`, `discord:dm/*`,
+      // `kakao:dm/*`, `kakao:group/*`, `kakao:open/*` produce `bucket` only
+      // (no workspace, no chat).
+      bucket?: 'dm' | 'group' | 'open'
+      author?: string
+    }
+
+export type ParseMatchRuleResult = { ok: true; value: MatchRule } | { ok: false; error: string }
+
+// Regex used by the JSON Schema layer for editor-time validation. Kept here
+// next to the parser so divergence is harder. Deliberately permissive: it
+// matches any `<name>:<value>` qualifier shape so the parser still gets to
+// run and emit typo suggestions like `autor:` -> `author:`. If we tightened
+// this to `author:` only, the JSON schema would reject typos with a generic
+// "did not match pattern" error and the user would lose the actionable hint.
+export const MATCH_RULE_REGEX_SOURCE =
+  '^(tui|cron|subagent(:[a-z][a-z0-9-]*)?|\\*|(slack|discord|telegram|kakao):[^\\s]+)(\\s+[a-zA-Z][a-zA-Z0-9_]*:[^\\s]+)*$'
+
+export function parseMatchRule(input: string): ParseMatchRuleResult {
+  if (input !== input.trim() || input.length === 0) {
+    return { ok: false, error: 'match rule must not have leading or trailing whitespace' }
+  }
+
+  // The DSL allows ONLY single literal spaces as token separators. Any
+  // other whitespace (tabs, newlines, CR, vertical tab, NBSP, NUL, etc.)
+  // inside a rule is rejected -- both because the JSON Schema regex uses
+  // `\s` boundaries that would diverge from this parser otherwise, and
+  // because workspace/chat IDs containing whitespace are not a legitimate
+  // shape on any supported platform.
+  if (/[^\S ]|\u0000/.test(input)) {
+    return {
+      ok: false,
+      error: 'match rule must use only single ASCII spaces; no tabs, newlines, or control characters',
+    }
+  }
+  const tokens = input.split(' ')
+  if (tokens.some((t) => t.length === 0)) {
+    return { ok: false, error: 'match rule must use exactly one space between tokens' }
+  }
+  const [scope, ...qualifiers] = tokens
+  if (scope === undefined) return { ok: false, error: 'match rule is empty' }
+
+  const qualifierResult = parseQualifiers(qualifiers)
+  if (!qualifierResult.ok) return { ok: false, error: qualifierResult.error }
+  const { author } = qualifierResult.value
+
+  // Reject legacy shorthand prefixes with a hint to the canonical form.
+  const legacy = LEGACY_PREFIXES.find((p) => scope === p.from || scope.startsWith(`${p.from}:`))
+  if (legacy) {
+    const replaced = scope === legacy.from ? legacy.to : `${legacy.to}${scope.slice(legacy.from.length)}`
+    return {
+      ok: false,
+      error: `legacy prefix '${legacy.from}'; use '${replaced}' instead`,
+    }
+  }
+
+  // Top-level keyword scopes.
+  if (scope === 'tui') {
+    if (author !== undefined) return { ok: false, error: "qualifier 'author:' requires a channel scope" }
+    return { ok: true, value: { kind: 'tui' } }
+  }
+  if (scope === 'cron') {
+    if (author !== undefined) return { ok: false, error: "qualifier 'author:' requires a channel scope" }
+    return { ok: true, value: { kind: 'cron' } }
+  }
+  if (scope === 'subagent' || scope.startsWith('subagent:')) {
+    if (author !== undefined) return { ok: false, error: "qualifier 'author:' requires a channel scope" }
+    if (scope === 'subagent') return { ok: true, value: { kind: 'subagent' } }
+    const name = scope.slice('subagent:'.length)
+    if (!SUBAGENT_NAME.test(name)) {
+      return { ok: false, error: `subagent name '${name}' must match ${SUBAGENT_NAME.source}` }
+    }
+    return { ok: true, value: { kind: 'subagent', subagent: name } }
+  }
+  if (scope === '*') {
+    if (author !== undefined) return { ok: false, error: "qualifier 'author:' requires a specific channel scope" }
+    return { ok: true, value: { kind: 'wildcard' } }
+  }
+
+  // Channel scopes: `<platform>:<rest>`.
+  const colon = scope.indexOf(':')
+  if (colon === -1) {
+    return { ok: false, error: suggestUnknownScope(scope) }
+  }
+  const prefix = scope.slice(0, colon)
+  const rest = scope.slice(colon + 1)
+  if (!(PLATFORMS as readonly string[]).includes(prefix)) {
+    return { ok: false, error: suggestUnknownScope(scope) }
+  }
+  const platform = prefix as Platform
+
+  return parseChannelScope(platform, rest, author)
+}
+
+function parseChannelScope(platform: Platform, rest: string, author: string | undefined): ParseMatchRuleResult {
+  if (rest.length === 0) {
+    return { ok: false, error: `channel scope '${platform}:' is missing a coordinate` }
+  }
+
+  // Wildcards and redundant forms.
+  if (rest === '*') {
+    return { ok: true, value: buildChannelRule(platform, { author }) }
+  }
+
+  // Bucket scopes: `dm/*`, `dm/<id>`, `group/*`, `open/*`. Slack's `im` is
+  // renamed to `dm`; that mapping is enforced by the legacy-prefix table at
+  // the top of parseMatchRule for unprefixed forms — here we just refuse the
+  // bare `im` bucket.
+  const slash = rest.indexOf('/')
+  if (slash !== -1) {
+    const head = rest.slice(0, slash)
+    const tail = rest.slice(slash + 1)
+
+    if (head === 'im') {
+      return { ok: false, error: `bucket 'im' renamed; use '${platform}:dm/${tail}'` }
+    }
+
+    if (head === '*') {
+      // `slack:*/...` is always wrong — a chat ID is workspace-scoped, so any
+      // concrete chat ID under a wildcard workspace is logically impossible.
+      // Even `slack:*/*` simplifies to `slack:*`.
+      const suggestion = tail === '*' ? `${platform}:*` : `${platform}:*`
+      return {
+        ok: false,
+        error: `wildcard workspace combined with '/${tail}' is nonsensical; use '${suggestion}'`,
+      }
+    }
+
+    if (head === 'dm' || head === 'group' || head === 'open') {
+      if (platform !== 'kakao' && (head === 'group' || head === 'open')) {
+        return { ok: false, error: `bucket '${head}' is only valid for kakao` }
+      }
+      if (tail === '') {
+        return { ok: false, error: `bucket '${platform}:${head}/' requires '*' or a chat id` }
+      }
+      if (tail === '*') {
+        return { ok: true, value: buildChannelRule(platform, { bucket: head as 'dm' | 'group' | 'open', author }) }
+      }
+      // `slack:dm/<id>` — keep the bucket plus the specific chat. We omit a
+      // separate workspace field; DM IDs are globally unique within a
+      // platform's adapter.
+      return {
+        ok: true,
+        value: buildChannelRule(platform, {
+          bucket: head as 'dm' | 'group' | 'open',
+          chat: tail,
+          author,
+        }),
+      }
+    }
+
+    // `slack:T0123/*` is redundant — drop the trailing `/*`.
+    if (tail === '*') {
+      return { ok: false, error: `trailing '/*' is redundant; use '${platform}:${head}'` }
+    }
+    // `slack:T0123/C0ABCDE` — workspace + chat.
+    return {
+      ok: true,
+      value: buildChannelRule(platform, { workspace: head, chat: tail, author }),
+    }
+  }
+
+  // No slash: `slack:T0123` or `kakao:dm` (bare bucket — error).
+  if (rest === 'dm' || rest === 'group' || rest === 'open') {
+    return { ok: false, error: `bucket '${platform}:${rest}' requires a chat id or '*'` }
+  }
+  return { ok: true, value: buildChannelRule(platform, { workspace: rest, author }) }
+}
+
+function buildChannelRule(
+  platform: Platform,
+  parts: {
+    workspace?: string
+    chat?: string
+    bucket?: 'dm' | 'group' | 'open'
+    author?: string
+  },
+): MatchRule {
+  const rule: MatchRule = { kind: 'channel', platform }
+  if (parts.workspace !== undefined) rule.workspace = parts.workspace
+  if (parts.chat !== undefined) rule.chat = parts.chat
+  if (parts.bucket !== undefined) rule.bucket = parts.bucket
+  if (parts.author !== undefined) rule.author = parts.author
+  return rule
+}
+
+type ParsedQualifiers = { author?: string }
+function parseQualifiers(qualifiers: string[]): { ok: true; value: ParsedQualifiers } | { ok: false; error: string } {
+  const out: ParsedQualifiers = {}
+  for (const token of qualifiers) {
+    const eq = token.indexOf(':')
+    if (eq === -1) {
+      return { ok: false, error: `qualifier '${token}' must have form '<name>:<value>'` }
+    }
+    const name = token.slice(0, eq)
+    const value = token.slice(eq + 1)
+    if (value.length === 0) {
+      return { ok: false, error: `qualifier '${name}:' must have a value` }
+    }
+    if (name === 'author') {
+      if (out.author !== undefined) {
+        return { ok: false, error: `qualifier 'author:' may not appear more than once in a single rule` }
+      }
+      out.author = value
+      continue
+    }
+    return { ok: false, error: `unknown qualifier '${name}:'.${suggestQualifier(name)}` }
+  }
+  return { ok: true, value: out }
+}
+
+// Empirical typo distance: ed1 on the scope keyword catches `tem:` → `team:`
+// (which is itself a legacy form), `slak:` → `slack:`, etc.
+function suggestUnknownScope(scope: string): string {
+  const head = scope.split(':')[0] ?? scope
+  const candidates = ['tui', 'cron', 'subagent', ...PLATFORMS, '*']
+  const hit = closestEd1(head, candidates)
+  if (hit !== null) {
+    return `unknown scope '${scope}'; did you mean '${hit}'?`
+  }
+  return `unknown scope '${scope}'; expected one of: tui, cron, subagent, *, ${PLATFORMS.join(', ')}`
+}
+
+function suggestQualifier(name: string): string {
+  const hit = closestEd1(name, ['author'])
+  return hit !== null ? ` Did you mean '${hit}:'?` : ''
+}
+
+function closestEd1(input: string, candidates: readonly string[]): string | null {
+  for (const c of candidates) {
+    if (editDistanceAtMost1(input, c)) return c
+  }
+  return null
+}
+
+function editDistanceAtMost1(a: string, b: string): boolean {
+  if (a === b) return true
+  const la = a.length
+  const lb = b.length
+  if (Math.abs(la - lb) > 1) return false
+  let i = 0
+  let j = 0
+  let edits = 0
+  while (i < la && j < lb) {
+    if (a[i] === b[j]) {
+      i++
+      j++
+      continue
+    }
+    edits++
+    if (edits > 1) return false
+    if (la === lb) {
+      i++
+      j++
+    } else if (la > lb) {
+      i++
+    } else {
+      j++
+    }
+  }
+  if (i < la || j < lb) edits++
+  return edits <= 1
+}
+
+const LEGACY_PREFIXES: { from: string; to: string }[] = [
+  { from: 'team', to: 'slack' },
+  { from: 'guild', to: 'discord' },
+  { from: 'tg', to: 'telegram' },
+]

package/src/permissions/permissions.ts

@@ -0,0 +1,196 @@
+import type { SessionOrigin } from '@/agent/session-origin'
+
+import { BUILTIN_ROLE_NAMES, BUILTIN_ROLES, CORE_PERMISSIONS, expandOwnerWildcard, isBuiltinRoleName } from './builtins'
+import type { MatchRule } from './match-rule'
+import { matchesOrigin } from './resolve'
+import type { RoleConfig, RolesConfig } from './schema'
+
+export type PermissionService = {
+  has(origin: SessionOrigin | undefined, permission: string): boolean
+  resolveRole(origin: SessionOrigin | undefined): string
+  describe(origin: SessionOrigin | undefined): { role: string; permissions: readonly string[] }
+  // Rebuilds the resolved role table from the given roles config, preserving
+  // the same plugin-permission set captured at construction time. Used by
+  // the config reloadable so role match-rule edits (typeclaw role claim,
+  // hand-edits to typeclaw.json) take effect without a container restart.
+  replaceRoles(roles: RolesConfig | undefined): void
+}
+
+export type UnknownPermissionWarning = {
+  role: string
+  permission: string
+  hint: string
+}
+
+export const noopPermissionService: PermissionService = {
+  has: () => false,
+  resolveRole: () => 'guest',
+  describe: () => ({ role: 'guest', permissions: [] }),
+  replaceRoles: () => {},
+}
+
+type ResolvedRole = {
+  name: string
+  match: readonly MatchRule[]
+  permissions: readonly string[]
+}
+
+export type CreatePermissionServiceOptions = {
+  roles?: RolesConfig
+  pluginPermissions?: readonly string[]
+}
+
+// Returns warnings for user-declared `permissions[]` strings that aren't
+// in the known universe (core permissions ∪ plugin-declared). Non-fatal;
+// the runtime still resolves the role with the unknown string in its
+// permission list -- `has()` checks for that exact string and would return
+// true if someone happened to check for it. The warning surfaces typos
+// like `security.bypass.secretExfilBach` before they silently fail to
+// gate the corresponding guard.
+export function findUnknownPermissions(
+  roles: RolesConfig | undefined,
+  pluginPermissions: readonly string[],
+): UnknownPermissionWarning[] {
+  if (!roles) return []
+  const known = new Set<string>([...Object.values(CORE_PERMISSIONS), ...pluginPermissions])
+  const out: UnknownPermissionWarning[] = []
+  for (const [role, config] of Object.entries(roles)) {
+    if (config.permissions === undefined) continue
+    for (const perm of config.permissions) {
+      if (!known.has(perm)) {
+        out.push({ role, permission: perm, hint: closestPermission(perm, known) })
+      }
+    }
+  }
+  return out
+}
+
+function closestPermission(target: string, known: ReadonlySet<string>): string {
+  let best: { name: string; distance: number } | null = null
+  for (const name of known) {
+    const d = levenshtein(target, name)
+    if (best === null || d < best.distance) best = { name, distance: d }
+  }
+  if (best === null || best.distance > Math.max(3, Math.floor(target.length * 0.25))) {
+    return 'no close match in known permissions; check spelling'
+  }
+  return `did you mean '${best.name}'?`
+}
+
+function levenshtein(a: string, b: string): number {
+  const la = a.length
+  const lb = b.length
+  if (la === 0) return lb
+  if (lb === 0) return la
+  const prev = new Array<number>(lb + 1)
+  const curr = new Array<number>(lb + 1)
+  for (let j = 0; j <= lb; j++) prev[j] = j
+  for (let i = 1; i <= la; i++) {
+    curr[0] = i
+    for (let j = 1; j <= lb; j++) {
+      curr[j] = Math.min(prev[j]! + 1, curr[j - 1]! + 1, prev[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1))
+    }
+    for (let j = 0; j <= lb; j++) prev[j] = curr[j]!
+  }
+  return prev[lb]!
+}
+
+export function createPermissionService(opts: CreatePermissionServiceOptions = {}): PermissionService {
+  const pluginPermissions = opts.pluginPermissions ?? []
+  let resolved = buildRoleTable(opts.roles ?? {}, pluginPermissions)
+  let byName = new Map(resolved.map((r) => [r.name, r]))
+
+  function resolveRole(origin: SessionOrigin | undefined): string {
+    if (origin === undefined) return 'guest'
+
+    if (origin.kind === 'cron') {
+      const role = origin.scheduledByRole
+      if (role !== undefined && byName.has(role)) return role
+      return 'guest'
+    }
+    if (origin.kind === 'subagent') {
+      const role = origin.spawnedByRole
+      if (role !== undefined && byName.has(role)) return role
+      return 'guest'
+    }
+
+    const matchable = toMatchable(origin)
+    if (matchable === null) return 'guest'
+
+    for (const role of resolved) {
+      for (const rule of role.match) {
+        if (matchesOrigin(rule, matchable)) return role.name
+      }
+    }
+    return 'guest'
+  }
+
+  return {
+    has(origin, permission) {
+      const roleName = resolveRole(origin)
+      const role = byName.get(roleName)
+      if (!role) return false
+      return role.permissions.includes(permission)
+    },
+    resolveRole,
+    describe(origin) {
+      const name = resolveRole(origin)
+      const role = byName.get(name)
+      return { role: name, permissions: role?.permissions ?? [] }
+    },
+    replaceRoles(roles) {
+      resolved = buildRoleTable(roles ?? {}, pluginPermissions)
+      byName = new Map(resolved.map((r) => [r.name, r]))
+    },
+  }
+}
+
+function buildRoleTable(roles: RolesConfig, pluginPermissions: readonly string[]): ResolvedRole[] {
+  const out: ResolvedRole[] = []
+  const seen = new Set<string>()
+
+  for (const name of Object.keys(roles)) {
+    if (seen.has(name)) continue
+    seen.add(name)
+    out.push(resolveOne(name, roles[name], pluginPermissions))
+  }
+
+  for (const name of BUILTIN_ROLE_NAMES) {
+    if (seen.has(name)) continue
+    out.push(resolveOne(name, undefined, pluginPermissions))
+  }
+
+  return out
+}
+
+function resolveOne(name: string, user: RoleConfig | undefined, pluginPermissions: readonly string[]): ResolvedRole {
+  if (isBuiltinRoleName(name)) {
+    const builtin = BUILTIN_ROLES[name]
+    const match = [...builtin.match, ...(user?.match ?? [])]
+    const rawPerms = user?.permissions !== undefined ? user.permissions : [...builtin.permissions]
+    const permissions = name === 'owner' ? expandOwnerWildcard(rawPerms, pluginPermissions) : rawPerms
+    return { name, match, permissions }
+  }
+  return {
+    name,
+    match: user?.match ?? [],
+    permissions: user?.permissions ?? [],
+  }
+}
+
+function toMatchable(origin: SessionOrigin): Parameters<typeof matchesOrigin>[1] | null {
+  switch (origin.kind) {
+    case 'tui':
+      return { kind: 'tui', sessionId: origin.sessionId }
+    case 'channel':
+      return {
+        kind: 'channel',
+        adapter: origin.adapter,
+        workspace: origin.workspace,
+        chat: origin.chat,
+        ...(origin.lastInboundAuthorId !== undefined ? { lastInboundAuthorId: origin.lastInboundAuthorId } : {}),
+      }
+    default:
+      return null
+  }
+}