typeclaw 0.9.1 → 0.10.0

package/src/permissions/builtins.ts

@@ -29,21 +29,27 @@ export type BuiltinRoleSpec = {
   readonly permissions: readonly string[]
 }
 
-// Owner carries low + medium tier strings explicitly AND the wildcard
-// sentinel. The sentinel expands to plugin-contributed `security.bypass.*`
-// strings minus the security plugin's `ownerWildcardExclusions` (today:
-// `security.bypass.high` plus high-tier per-guard strings). Net effect:
-// owner auto-bypasses every low- and medium-tier guard, and high-tier
-// guards require per-call ack from owner too (the audience-leak rule —
-// owner-in-public-channel must not silently post credentials).
+// Role-to-tier defaults form a strict tower:
+//   owner   → bypass.low + bypass.medium + bypass.high
+//   trusted → bypass.low + bypass.medium
+//   member  → bypass.low
+//   guest   → no bypass
 //
-// Trusted carries only `security.bypass.low`. Trusted does NOT carry the
-// pre-PR per-guard grants (`bypassSecretExfilBash`, `bypassGitExfil`):
-// those guards are medium/high under the audience-leak axis and per-guard
-// grants would re-introduce exactly the bypass holes the tier system
-// exists to prevent. Operators who want the pre-PR ergonomics can add the
-// per-guard strings explicitly to `roles.trusted.permissions[]` in
-// typeclaw.json — that path stays alive forever.
+// `canBypass` in the bundled security plugin checks the specific tier
+// string for the guard's severity, so each role must carry every tier
+// string at or below its cap (tiers do not cascade implicitly).
+//
+// Owner also carries the wildcard sentinel: the sentinel expands to every
+// plugin-contributed `security.bypass.*` string minus
+// `ownerWildcardExclusions`. The bundled security plugin no longer excludes
+// high-tier strings (owner is meant to bypass them by default under this
+// model), so the sentinel covers per-guard high-tier strings too.
+//
+// Tradeoff: this gives owner audience-leak bypass without per-call ack.
+// The owner-in-public-channel risk is now load-bearing on the operator
+// scoping `roles.owner.match[]` tightly. Default match is TUI-only, where
+// a human is present; configs that widen owner to a channel author should
+// understand they have re-opened audience-leak for that author.
 export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> = {
   owner: {
     match: [{ kind: 'tui' }],
@@ -57,6 +63,7 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
       CORE_PERMISSIONS.subagentSpawnOperator,
       'security.bypass.low',
       'security.bypass.medium',
+      'security.bypass.high',
       OWNER_SECURITY_WILDCARD,
     ],
   },
@@ -70,6 +77,7 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
       CORE_PERMISSIONS.subagentOutput,
       CORE_PERMISSIONS.subagentSpawnOperator,
       'security.bypass.low',
+      'security.bypass.medium',
     ],
   },
   member: {
@@ -79,6 +87,7 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
       CORE_PERMISSIONS.subagentSpawn,
       CORE_PERMISSIONS.subagentCancel,
       CORE_PERMISSIONS.subagentOutput,
+      'security.bypass.low',
     ],
   },
   guest: {
@@ -88,13 +97,12 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
 }
 
 // Expands the owner wildcard sentinel against plugin-contributed
-// `security.bypass.*` strings. `wildcardExclusions` is an optional set of
-// permission strings the sentinel must NOT expand to — used by the
-// bundled security plugin to exclude `security.bypass.high` AND the
-// per-guard strings for high-tier guards, so the wildcard does not
-// auto-grant audience-leak bypass to owner. Explicit operator grants of
-// those strings in `roles.owner.permissions[]` still take effect (they
-// flow through the non-sentinel branch).
+// `security.bypass.*` strings. `wildcardExclusions` lets plugins opt
+// specific strings OUT of the wildcard expansion. The bundled security
+// plugin no longer excludes any high-tier strings — owner bypasses every
+// security tier by default under the current role-tower model. The
+// parameter is preserved for third-party plugins that want a different
+// shape (e.g. a future audit-only plugin that never auto-flows to owner).
 export function expandOwnerWildcard(
   ownerPermissions: readonly string[],
   pluginContributed: readonly string[],

package/src/permissions/permissions.ts

@@ -152,6 +152,29 @@ export function createPermissionService(opts: CreatePermissionServiceOptions = {
   }
 }
 
+// Walk order: owner, trusted, custom roles (in REVERSE declaration order),
+// member, guest. First role whose `match[]` covers the origin wins.
+//
+// Built-in tower: owner > trusted > member > guest. Pinning the tower
+// ahead of any user-declared rule closes a load-bearing footgun in the
+// previous pure-declaration-order resolver: declaring
+// `member.match: ["*"]` before `owner.match: [...]` resolved every
+// channel session — INCLUDING the owner's — to `member`, because the
+// wildcard matched first. The rolePromotion guard then made it
+// un-fixable from inside the demoted session (a member-resolved speaker
+// cannot rewrite `roles` without a TUI-issued ack).
+//
+// Custom roles use REVERSE declaration order: later declarations override
+// earlier ones. This matches the standard "later config wins" mental
+// model — when an operator adds a new role with the same match-scope as
+// an existing one (or appends a new author-pinned override to an existing
+// broad rule), the newer entry takes precedence. The previous "earlier
+// wins" was an arbitrary consequence of map iteration order rather than
+// a deliberate semantic.
+//
+// Custom roles cannot self-promote above trusted (no inherent severity
+// guarantee) and cannot demote themselves below member (declaring a custom
+// role implies the operator wants it to win against bottom catch-alls).
 function buildRoleTable(
   roles: RolesConfig,
   pluginPermissions: readonly string[],
@@ -160,16 +183,20 @@ function buildRoleTable(
   const out: ResolvedRole[] = []
   const seen = new Set<string>()
 
-  for (const name of Object.keys(roles)) {
-    if (seen.has(name)) continue
+  const emit = (name: string): void => {
+    if (seen.has(name)) return
     seen.add(name)
     out.push(resolveOne(name, roles[name], pluginPermissions, ownerWildcardExclusions))
   }
 
-  for (const name of BUILTIN_ROLE_NAMES) {
-    if (seen.has(name)) continue
-    out.push(resolveOne(name, undefined, pluginPermissions, ownerWildcardExclusions))
+  emit('owner')
+  emit('trusted')
+  const customRoles = Object.keys(roles).filter((name) => !isBuiltinRoleName(name))
+  for (let i = customRoles.length - 1; i >= 0; i--) {
+    emit(customRoles[i]!)
   }
+  emit('member')
+  emit('guest')
 
   return out
 }

package/src/role-claim/code.ts

@@ -1,17 +1,17 @@
 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.
+// their host CLI to the bot in any chat (DM, group, channel) 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.
+// attempts in inbound text without scanning the whole body for hex blocks,
+// and distinguishes claim messages from normal first-message text like
+// "hi" which would otherwise need a regex of its own to disambiguate.
 
 export const CLAIM_CODE_PREFIX = 'claim-'
 

package/src/role-claim/controller.ts

@@ -10,8 +10,9 @@ import { createPendingClaimRegistry, type PendingClaim, type PendingClaimRegistr
 //
 //   1. The host CLI (typeclaw role claim) opens a WS and sends `claim_start`.
 //   2. The WS server forwards that to controller.startClaim().
-//   3. The channel router's claimHandler (also wired here) intercepts DMs
-//      bearing the code and calls controller.tryConsumeInbound().
+//   3. The channel router's claimHandler (also wired here) intercepts any
+//      inbound bearing the code (DM, group, or channel) and calls
+//      controller.tryConsumeInbound().
 //   4. On consume, the controller writes to typeclaw.json#roles.<role>.match
 //      via grantRole, then reloads the live PermissionService so the new
 //      match rule takes effect without a container restart.

package/src/role-claim/match-rule.ts

@@ -1,15 +1,19 @@
 // Builds a canonical match-rule DSL string from an inbound channel origin,
-// for the role table. Output shapes:
+// for the role table. Output shape is always platform-wide + author:
 //
-//   slack:T0123 author:U_ALICE
-//   discord:9999 author:U_ALICE
-//   telegram:42 author:U_ALICE
-//   kakao:dm/<chatId> author:<authorId>
+//   slack:* author:<authorId>
+//   discord:* author:<authorId>
+//   telegram:* author:<authorId>
+//   kakao:* author:<authorId>
 //
-// The author qualifier is always emitted so a claim grants the specific
-// human, not the whole workspace. To grant the whole workspace, the
-// operator edits typeclaw.json by hand or runs a future `typeclaw role grant`
-// without --claim.
+// "Platform-wide" means every chat the adapter sees on that platform —
+// DMs, group chats, and threads alike — gated by the author qualifier so
+// only this specific human is matched. The intent is: once an operator
+// proves they control a channel identity (by sending a code to the bot),
+// they keep their role wherever they speak from on the same platform. To
+// scope tighter (e.g. one workspace, one chat), the operator edits
+// typeclaw.json by hand; the claim flow is deliberately broad because
+// re-claiming on every new chat would be tedious for the common case.
 
 import type { ChannelKey } from '@/channels/types'
 
@@ -31,14 +35,5 @@ const ADAPTER_TO_PLATFORM: Record<ChannelKey['adapter'], 'slack' | 'discord' | '
 
 export function formatClaimMatchRule(origin: PartialChannelOrigin): string {
   const platform = ADAPTER_TO_PLATFORM[origin.adapter]
-  const authorQual = ` author:${origin.authorId}`
-  if (origin.adapter === 'kakaotalk') {
-    // Kakao has no workspace; routes use dm/group/open buckets. We can't
-    // know which bucket from a partial origin alone (adapter-side classifies
-    // it), so claim flows are restricted to DM and we emit the specific
-    // chat-id form so the rule grants only this 1:1 conversation, not every
-    // DM the agent is in.
-    return `${platform}:dm/${origin.chat}${authorQual}`
-  }
-  return `${platform}:${origin.workspace}${authorQual}`
+  return `${platform}:* author:${origin.authorId}`
 }

package/src/role-claim/pending.ts

@@ -21,8 +21,8 @@ export type PendingClaimRegistry = {
   cancel: (code: string) => boolean
   current: () => PendingClaim | null
   // Snapshot of consumption result without actually committing the grant.
-  // The router calls this on every DM-shaped inbound; the grant only fires
-  // when the result is 'consumed'.
+  // The router calls this on every claim-code-bearing inbound; the grant
+  // only fires when the result is 'consumed'.
   tryConsume: (
     code: string,
     origin: PartialChannelOrigin,

package/src/run/index.ts

@@ -214,6 +214,7 @@ export async function startAgent({
     }),
     permissions: pluginsLoaded.permissions,
     claimHandler: claimController.claimHandler,
+    stream,
   })
 
   const createSessionForSubagent: import('@/agent/subagents').CreateSessionForSubagent = async (

package/src/server/index.ts

@@ -1062,15 +1062,7 @@ function handleInspectMessage(
 
   if (stream !== undefined && typeof msg.sinceMs === 'number') {
     for (const event of stream.scan({ sinceTs: msg.sinceMs, target: { kind: 'broadcast' } })) {
-      sendInspect(ws, {
-        type: 'frame',
-        ts: event.ts,
-        payload: {
-          kind: 'broadcast',
-          payload: event.payload,
-          ...(event.meta !== undefined ? { meta: event.meta } : {}),
-        },
-      })
+      sendInspect(ws, { type: 'frame', ts: event.ts, payload: broadcastEventToFrame(event) })
     }
     for (const event of stream.scan({ sinceTs: msg.sinceMs, target: { kind: 'cron' } })) {
       sendInspect(ws, {
@@ -1092,15 +1084,7 @@ function handleInspectMessage(
 
   if (stream !== undefined) {
     ws.data.unsubBroadcast = stream.subscribe({ target: { kind: 'broadcast' } }, (event) => {
-      sendInspect(ws, {
-        type: 'frame',
-        ts: event.ts,
-        payload: {
-          kind: 'broadcast',
-          payload: event.payload,
-          ...(event.meta !== undefined ? { meta: event.meta } : {}),
-        },
-      })
+      sendInspect(ws, { type: 'frame', ts: event.ts, payload: broadcastEventToFrame(event) })
     })
     ws.data.unsubCron = stream.subscribe({ target: { kind: 'cron' } }, (event) => {
       sendInspect(ws, {
@@ -1118,6 +1102,52 @@ function extractJobId(target: StreamMessage['target']): string {
   return target.kind === 'cron' ? target.jobId : ''
 }
 
+function broadcastEventToFrame(event: StreamMessage): InspectFramePayload {
+  const inbound = readChannelInboundBroadcast(event.payload)
+  if (inbound !== null) return inbound
+  return {
+    kind: 'broadcast',
+    payload: event.payload,
+    ...(event.meta !== undefined ? { meta: event.meta } : {}),
+  }
+}
+
+function readChannelInboundBroadcast(payload: unknown): InspectFramePayload | null {
+  if (typeof payload !== 'object' || payload === null) return null
+  const p = payload as Record<string, unknown>
+  if (p.kind !== 'channel-inbound') return null
+  if (typeof p.adapter !== 'string') return null
+  if (typeof p.workspace !== 'string') return null
+  if (typeof p.chat !== 'string') return null
+  if (!(p.thread === null || typeof p.thread === 'string')) return null
+  if (typeof p.authorId !== 'string') return null
+  if (typeof p.authorName !== 'string') return null
+  if (typeof p.authorIsBot !== 'boolean') return null
+  if (typeof p.isDm !== 'boolean') return null
+  if (typeof p.isBotMention !== 'boolean') return null
+  if (typeof p.text !== 'string') return null
+  if (typeof p.externalMessageId !== 'string') return null
+  if (typeof p.ts !== 'number') return null
+  const decision = p.decision
+  if (decision !== 'engage' && decision !== 'observe' && decision !== 'denied' && decision !== 'claim') return null
+  return {
+    kind: 'channel_inbound',
+    adapter: p.adapter,
+    workspace: p.workspace,
+    chat: p.chat,
+    thread: p.thread,
+    authorId: p.authorId,
+    authorName: p.authorName,
+    authorIsBot: p.authorIsBot,
+    isDm: p.isDm,
+    isBotMention: p.isBotMention,
+    text: p.text,
+    externalMessageId: p.externalMessageId,
+    ts: p.ts,
+    decision,
+  }
+}
+
 function forwardAgentEventToInspect(
   ws: InspectWs,
   event: unknown,
@@ -1128,10 +1158,20 @@ function forwardAgentEventToInspect(
   const e = event as { type?: unknown }
   const now = Date.now()
   if (e.type === 'message_update') {
-    const ev = event as { assistantMessageEvent?: { type?: unknown; delta?: unknown } }
+    const ev = event as { assistantMessageEvent?: { type?: unknown; delta?: unknown; content?: unknown } }
     const ame = ev.assistantMessageEvent
     if (ame?.type === 'text_delta' && typeof ame.delta === 'string') {
       sendInspect(ws, { type: 'frame', ts: now, payload: { kind: 'text_delta', sessionId, delta: ame.delta } })
+      return
+    }
+    if (ame?.type === 'thinking_delta' && typeof ame.delta === 'string') {
+      sendInspect(ws, { type: 'frame', ts: now, payload: { kind: 'thinking_delta', sessionId, delta: ame.delta } })
+      return
+    }
+    if (ame?.type === 'thinking_end') {
+      const text = typeof ame.content === 'string' ? ame.content : ''
+      sendInspect(ws, { type: 'frame', ts: now, payload: { kind: 'thinking_end', sessionId, text } })
+      return
     }
     return
   }

package/src/shared/protocol.ts

@@ -57,6 +57,12 @@ export type InspectClientMessage = {
 
 export type InspectFramePayload =
   | { kind: 'text_delta'; sessionId: string; delta: string }
+  // Reasoning trace from the model, streamed as deltas like text. `thinking_end`
+  // closes a thinking block; `text` is the joined deltas (empty when redacted).
+  // `redacted: true` means the upstream provider hid the content behind a
+  // safety filter and only the opaque continuation payload survives.
+  | { kind: 'thinking_delta'; sessionId: string; delta: string }
+  | { kind: 'thinking_end'; sessionId: string; text: string; redacted?: boolean }
   | { kind: 'tool_start'; sessionId: string; toolCallId: string; name: string; args: unknown }
   | {
       kind: 'tool_end'
@@ -87,6 +93,30 @@ export type InspectFramePayload =
     }
   | { kind: 'broadcast'; payload: unknown; meta?: Record<string, string> }
   | { kind: 'cron-fire'; jobId: string; payload: unknown }
+  // Channel inbound message observed by the router. Surfaced regardless
+  // of the engagement decision so inspect can show what the agent saw,
+  // not just what it chose to act on. `decision` mirrors the router's
+  // EngagementDecision plus 'denied' (channel.respond gate) and 'claim'
+  // (role-claim intercept) for completeness. `text` is the raw inbound
+  // text — no batching, no compose-prompt wrapping.
+  | {
+      kind: 'channel_inbound'
+      adapter: string
+      workspace: string
+      chat: string
+      thread: string | null
+      authorId: string
+      authorName: string
+      authorIsBot: boolean
+      isDm: boolean
+      isBotMention: boolean
+      text: string
+      externalMessageId: string
+      // 0 = platform timestamp unknown; the renderer uses the frame's
+      // wall-clock ts instead.
+      ts: number
+      decision: 'engage' | 'observe' | 'denied' | 'claim'
+    }
 
 export type InspectServerMessage =
   | { type: 'subscribed'; sessionId: string; sessionLive: boolean }