typeclaw 0.1.4 → 0.1.6

package/src/server/index.ts

@@ -12,6 +12,7 @@ import type { ChannelRouter } from '@/channels/router'
 import type { HookBus } from '@/plugin'
 import type { BrokerWsData, ContainerBroker } from '@/portbroker'
 import type { ReloadAllResult, ReloadRegistry } from '@/reload'
+import type { ClaimController, ClaimResultEvent } from '@/role-claim'
 import type { PluginRuntime, PluginRuntimeState } from '@/run/plugin-runtime'
 import type { SessionFactory } from '@/sessions'
 import type { ClientMessage, PromptDelivery, QueueStateItem, ReloadResultPayload, ServerMessage } from '@/shared'
@@ -20,6 +21,12 @@ import type { Stream, StreamMessage, StreamMessageId, Unsubscribe } from '@/stre
 export type ReloadAllFn = () => Promise<ReloadAllResult>
 export type CreateSessionFn = (options?: CreateSessionOptions) => Promise<AgentSession | CreateSessionResult>
 
+export type ServerLogger = {
+  info: (msg: string) => void
+  warn: (msg: string) => void
+  error: (msg: string) => void
+}
+
 export type ServerOptions = {
   port: number
   reloadAll?: ReloadAllFn
@@ -31,11 +38,28 @@ export type ServerOptions = {
   agentDir?: string
   pluginRuntime?: PluginRuntime
   containerName?: string
+  tuiToken?: string
   // Optional in-process portbroker handler. When provided, requests to the
   // /portbroker WS path are routed to it instead of being treated as TUI
   // sessions. Omit to keep TUI-only behavior (used by tests + non-container
   // dev runs).
   containerBroker?: ContainerBroker
+  // Optional logger for server-side events. Defaults to `consoleLogger`
+  // which writes to stdout/stderr so `typeclaw logs` surfaces every event.
+  // Tests inject a fake logger to assert on captured output.
+  logger?: ServerLogger
+  // Optional role-claim controller. When set, the server accepts
+  // `claim_start` / `claim_cancel` from TUI-class WS clients (the host
+  // CLI's `typeclaw role claim` command in particular), and pushes
+  // `claim_started` / `claim_completed` / `claim_error` back over the
+  // same connection. Omitted in tests that don't exercise the flow.
+  claimController?: ClaimController
+}
+
+const consoleLogger: ServerLogger = {
+  info: (m) => console.log(m),
+  warn: (m) => console.warn(m),
+  error: (m) => console.error(m),
 }
 
 export type Server = ReturnType<typeof createServer>
@@ -60,6 +84,8 @@ type SessionState = {
   draining: boolean
   unsubBroadcast: Unsubscribe | null
   unsubPrompts: Unsubscribe | null
+  unsubClaim: Unsubscribe | null
+  activeClaimCode: string | null
   // Captured at session open so close-time hooks fire against the same
   // generation that ran session.start. A plugin reload mid-connection does
   // not re-target this session's lifecycle hooks.
@@ -82,7 +108,10 @@ export function createServer({
   agentDir,
   pluginRuntime,
   containerName,
+  tuiToken,
   containerBroker,
+  logger = consoleLogger,
+  claimController,
 }: ServerOptions) {
   const sessionStates = new WeakMap<Ws, SessionState>()
 
@@ -97,6 +126,9 @@ export function createServer({
           if (server.upgrade(req, { data })) return
           return new Response('upgrade failed', { status: 400 })
         }
+        if (isWebSocketUpgrade(req) && tuiToken !== undefined && url.searchParams.get('token') !== tuiToken) {
+          return new Response('unauthorized', { status: 401 })
+        }
         const sessionId = crypto.randomUUID()
         const data: TuiWsData = { kind: 'tui', sessionId }
         if (server.upgrade(req, { data })) return
@@ -109,73 +141,82 @@ export function createServer({
             return
           }
           const ws = rawWs as Ws
-          const sessionManager = sessionFactory?.createPersisted()
-          const sessionFileId = sessionManager?.getSessionId() ?? ws.data.sessionId
-          // Snapshot the runtime once so the entire session lifecycle for this
-          // ws connection sees one consistent generation of registry+hooks. A
-          // reload landing mid-connection swaps the live pointer; this session
-          // keeps using the snapshot it was created with until close.
-          const runtimeSnapshot = pluginRuntime?.get()
-          const pluginsWiring =
-            runtimeSnapshot !== undefined && agentDir !== undefined
-              ? {
-                  registry: runtimeSnapshot.registry,
-                  hooks: runtimeSnapshot.hooks,
-                  sessionId: sessionFileId,
-                  agentDir,
-                }
-              : undefined
-          const origin: SessionOrigin = { kind: 'tui', sessionId: sessionFileId }
-          const result = await createSession({
-            reloadRegistry,
-            sessionManager,
-            origin,
-            ...(stream ? { stream } : {}),
-            ...(channelRouter ? { channelRouter } : {}),
-            ...(pluginsWiring ? { plugins: pluginsWiring } : {}),
-            ...(containerName !== undefined ? { containerName } : {}),
-          })
-          const session = 'session' in result ? result.session : result
-          const dispose = 'session' in result && result.dispose ? result.dispose : async () => {}
-
-          const state: SessionState = {
-            session,
-            sessionFileId,
-            origin,
-            sessionManager,
-            drainQueue: [],
-            draining: false,
-            unsubBroadcast: null,
-            unsubPrompts: null,
-            runtimeSnapshot: runtimeSnapshot ?? null,
-            dispose,
-          }
-          sessionStates.set(ws, state)
+          try {
+            const sessionManager = sessionFactory?.createPersisted()
+            const sessionFileId = sessionManager?.getSessionId() ?? ws.data.sessionId
+            // Snapshot the runtime once so the entire session lifecycle for this
+            // ws connection sees one consistent generation of registry+hooks. A
+            // reload landing mid-connection swaps the live pointer; this session
+            // keeps using the snapshot it was created with until close.
+            const runtimeSnapshot = pluginRuntime?.get()
+            const pluginsWiring =
+              runtimeSnapshot !== undefined && agentDir !== undefined
+                ? {
+                    registry: runtimeSnapshot.registry,
+                    hooks: runtimeSnapshot.hooks,
+                    sessionId: sessionFileId,
+                    agentDir,
+                  }
+                : undefined
+            const origin: SessionOrigin = { kind: 'tui', sessionId: sessionFileId }
+            const result = await createSession({
+              reloadRegistry,
+              sessionManager,
+              origin,
+              ...(stream ? { stream } : {}),
+              ...(channelRouter ? { channelRouter } : {}),
+              ...(pluginsWiring ? { plugins: pluginsWiring } : {}),
+              ...(containerName !== undefined ? { containerName } : {}),
+            })
+            const session = 'session' in result ? result.session : result
+            const dispose = 'session' in result && result.dispose ? result.dispose : async () => {}
+
+            const state: SessionState = {
+              session,
+              sessionFileId,
+              origin,
+              sessionManager,
+              drainQueue: [],
+              draining: false,
+              unsubBroadcast: null,
+              unsubPrompts: null,
+              unsubClaim: null,
+              activeClaimCode: null,
+              runtimeSnapshot: runtimeSnapshot ?? null,
+              dispose,
+            }
+            sessionStates.set(ws, state)
 
-          if (runtimeSnapshot !== undefined && agentDir !== undefined) {
-            await runtimeSnapshot.hooks.runSessionStart({ sessionId: sessionFileId, agentDir })
-          }
+            if (runtimeSnapshot !== undefined && agentDir !== undefined) {
+              await runtimeSnapshot.hooks.runSessionStart({ sessionId: sessionFileId, agentDir })
+            }
 
-          forwardSessionEvents(ws, session)
+            forwardSessionEvents(ws, session, logger, sessionFileId)
 
-          if (stream) {
-            state.unsubPrompts = stream.subscribe({ target: { kind: 'session', sessionId: sessionFileId } }, (msg) =>
-              enqueuePrompt(ws, state, msg, agentDir),
-            )
+            if (stream) {
+              state.unsubPrompts = stream.subscribe({ target: { kind: 'session', sessionId: sessionFileId } }, (msg) =>
+                enqueuePrompt(ws, state, msg, agentDir, logger),
+              )
+
+              state.unsubBroadcast = stream.subscribe({ target: { kind: 'broadcast' } }, (msg) => {
+                const payload: ServerMessage = {
+                  type: 'notification',
+                  payload: msg.payload,
+                  ...(msg.replyTo !== undefined ? { replyTo: msg.replyTo } : {}),
+                  ...(msg.meta !== undefined ? { meta: msg.meta } : {}),
+                }
+                send(ws, payload)
+              })
+            }
 
-            state.unsubBroadcast = stream.subscribe({ target: { kind: 'broadcast' } }, (msg) => {
-              const payload: ServerMessage = {
-                type: 'notification',
-                payload: msg.payload,
-                ...(msg.replyTo !== undefined ? { replyTo: msg.replyTo } : {}),
-                ...(msg.meta !== undefined ? { meta: msg.meta } : {}),
-              }
-              send(ws, payload)
-            })
+            send(ws, { type: 'connected', sessionId: sessionFileId })
+            console.log(`session ${sessionFileId}: open`)
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err)
+            console.error(`session ${ws.data.sessionId}: open failed: ${message}`)
+            send(ws, { type: 'error', message })
+            ws.close()
           }
-
-          send(ws, { type: 'connected', sessionId: sessionFileId })
-          console.log(`session ${sessionFileId}: open`)
         },
         async message(rawWs, raw) {
           if (rawWs.data.kind === 'portbroker') {
@@ -186,6 +227,73 @@ export function createServer({
           const msg = JSON.parse(String(raw)) as ClientMessage
           const state = sessionStates.get(ws)
 
+          if (msg.type === 'claim_start') {
+            if (!state) return
+            if (!claimController) {
+              send(ws, {
+                type: 'claim_error',
+                payload: { code: msg.code, reason: 'role-claim is not enabled on this agent' },
+              })
+              return
+            }
+            if (state.unsubClaim) {
+              state.unsubClaim()
+              state.unsubClaim = null
+            }
+            const result = claimController.startClaim({
+              code: msg.code,
+              role: msg.role,
+              ttlMs: msg.ttlMs,
+              ...(msg.channel !== undefined ? { channel: msg.channel } : {}),
+            })
+            if (!result.ok) {
+              send(ws, { type: 'claim_error', payload: { code: msg.code, reason: result.reason } })
+              return
+            }
+            state.activeClaimCode = msg.code
+            state.unsubClaim = claimController.onResult((event: ClaimResultEvent) => {
+              if (event.kind === 'completed' && event.code === msg.code) {
+                send(ws, {
+                  type: 'claim_completed',
+                  payload: {
+                    code: event.code,
+                    role: event.role,
+                    matchRule: event.matchRule,
+                    adapter: event.adapter,
+                    authorId: event.authorId,
+                  },
+                })
+              } else if (event.kind === 'error' && event.code === msg.code) {
+                send(ws, { type: 'claim_error', payload: { code: event.code, reason: event.reason } })
+              } else if (event.kind === 'cancelled' && event.code === msg.code) {
+                send(ws, { type: 'claim_error', payload: { code: event.code, reason: 'cancelled' } })
+              }
+            })
+            send(ws, {
+              type: 'claim_started',
+              payload: {
+                code: msg.code,
+                role: msg.role,
+                ...(msg.channel !== undefined ? { channel: msg.channel } : {}),
+                expiresAt: result.expiresAt,
+              },
+            })
+            return
+          }
+
+          if (msg.type === 'claim_cancel') {
+            if (!state || !claimController) return
+            if (state.activeClaimCode !== null) {
+              claimController.cancelClaim(state.activeClaimCode)
+              state.activeClaimCode = null
+            }
+            if (state.unsubClaim) {
+              state.unsubClaim()
+              state.unsubClaim = null
+            }
+            return
+          }
+
           if (msg.type === 'reload') {
             await handleReload(ws, reloadAll, reloadRegistry, msg.scope)
             return
@@ -238,7 +346,9 @@ export function createServer({
               await state.session.prompt(msg.text)
               send(ws, { type: 'done' })
             } catch (err) {
-              send(ws, { type: 'error', message: err instanceof Error ? err.message : String(err) })
+              const message = err instanceof Error ? err.message : String(err)
+              logger.error(`[server] ${state.sessionFileId}: prompt failed: ${message}`)
+              send(ws, { type: 'error', message })
             }
             if (fallbackHooks !== undefined && agentDir !== undefined) {
               await fallbackHooks.runSessionTurnEnd({
@@ -266,9 +376,13 @@ export function createServer({
           const state = sessionStates.get(ws)
           state?.unsubBroadcast?.()
           state?.unsubPrompts?.()
+          state?.unsubClaim?.()
+          if (state?.activeClaimCode !== null && state?.activeClaimCode !== undefined && claimController) {
+            claimController.cancelClaim(state.activeClaimCode)
+          }
           try {
             if (state && state.runtimeSnapshot !== null) {
-              await state.runtimeSnapshot.hooks.runSessionEnd({ sessionId: state.sessionFileId })
+              await state.runtimeSnapshot.hooks.runSessionEnd({ sessionId: state.sessionFileId, origin: state.origin })
             }
           } finally {
             if (state) {
@@ -289,7 +403,11 @@ export function createServer({
   return { start }
 }
 
-function forwardSessionEvents(ws: Ws, session: AgentSession): void {
+function isWebSocketUpgrade(req: Request): boolean {
+  return req.headers.get('upgrade')?.toLowerCase() === 'websocket'
+}
+
+function forwardSessionEvents(ws: Ws, session: AgentSession, logger: ServerLogger, sessionFileId: string): void {
   const toolStartedAt = new Map<string, number>()
 
   session.subscribe((event) => {
@@ -307,7 +425,7 @@ function forwardSessionEvents(ws: Ws, session: AgentSession): void {
         // because no text deltas were ever emitted, which looks like a freeze.
         // The server's existing try/catch around `session.prompt()` only
         // catches throws, so it never sees these.
-        forwardAssistantError(ws, event.message)
+        forwardAssistantError(ws, event.message, logger, sessionFileId)
         break
       case 'tool_execution_start':
         toolStartedAt.set(event.toolCallId, Date.now())
@@ -336,7 +454,7 @@ function forwardSessionEvents(ws: Ws, session: AgentSession): void {
   })
 }
 
-function forwardAssistantError(ws: Ws, message: unknown): void {
+function forwardAssistantError(ws: Ws, message: unknown, logger: ServerLogger, sessionFileId: string): void {
   if (typeof message !== 'object' || message === null) return
   const m = message as { role?: string; stopReason?: string; errorMessage?: string }
   if (m.role !== 'assistant') return
@@ -345,10 +463,17 @@ function forwardAssistantError(ws: Ws, message: unknown): void {
   // error message because the TUI already shows abort feedback elsewhere.
   if (m.stopReason === 'aborted') return
   const text = typeof m.errorMessage === 'string' && m.errorMessage.length > 0 ? m.errorMessage : 'LLM call failed'
+  logger.error(`[server] ${sessionFileId}: LLM call failed: ${text}`)
   send(ws, { type: 'error', message: text })
 }
 
-function enqueuePrompt(ws: Ws, state: SessionState, msg: StreamMessage, agentDir: string | undefined): void {
+function enqueuePrompt(
+  ws: Ws,
+  state: SessionState,
+  msg: StreamMessage,
+  agentDir: string | undefined,
+  logger: ServerLogger,
+): void {
   const payload = msg.payload as { kind?: string; text?: string; delivery?: PromptDelivery }
   if (payload?.kind !== 'prompt' || typeof payload.text !== 'string') return
   const delivery: PromptDelivery = payload.delivery ?? 'queue'
@@ -364,7 +489,7 @@ function enqueuePrompt(ws: Ws, state: SessionState, msg: StreamMessage, agentDir
     ts: msg.ts,
   })
   pushQueueState(ws, state)
-  void drain(ws, state, agentDir)
+  void drain(ws, state, agentDir, logger)
 }
 
 // `session.idle` semantically means "the agent finished a prompt and is now
@@ -400,7 +525,7 @@ function makeTurnHookCallers(
   }
 }
 
-async function drain(ws: Ws, state: SessionState, agentDir: string | undefined): Promise<void> {
+async function drain(ws: Ws, state: SessionState, agentDir: string | undefined, logger: ServerLogger): Promise<void> {
   if (state.draining) return
   state.draining = true
   const fireIdle = makeIdleHookCaller(state)
@@ -417,7 +542,9 @@ async function drain(ws: Ws, state: SessionState, agentDir: string | undefined):
         await state.session.prompt(item.text)
         send(ws, { type: 'done' })
       } catch (err) {
-        send(ws, { type: 'error', message: err instanceof Error ? err.message : String(err) })
+        const message = err instanceof Error ? err.message : String(err)
+        logger.error(`[server] ${state.sessionFileId}: prompt failed: ${message}`)
+        send(ws, { type: 'error', message })
       }
       await fireTurnEnd()
       await fireIdle()

package/src/shared/index.ts

@@ -1,4 +1,8 @@
 export {
+  type ClaimCompletedPayload,
+  type ClaimErrorPayload,
+  type ClaimRoleChoice,
+  type ClaimStartedPayload,
   type ClientMessage,
   type DoctorCheckPayload,
   type DoctorFixPayload,

package/src/shared/protocol.ts

@@ -22,6 +22,8 @@ export type DoctorFixPayload =
   | { ok: true; checkId: string; summary: string; changedPaths: string[] }
   | { ok: false; checkId: string; error: string }
 
+export type ClaimRoleChoice = 'owner' | 'member' | 'trusted' | (string & {})
+
 export type ClientMessage =
   | { type: 'prompt'; text: string; delivery?: PromptDelivery }
   | { type: 'reload'; scope?: string }
@@ -29,9 +31,31 @@ export type ClientMessage =
   | { type: 'queue_cancel'; messageId: string }
   | { type: 'doctor'; requestId: DoctorRequestId }
   | { type: 'doctor_fix'; requestId: DoctorRequestId; checkId: string }
+  | { type: 'claim_start'; code: string; role: ClaimRoleChoice; channel?: string; ttlMs: number }
+  | { type: 'claim_cancel' }
 
 export type QueueStateItem = { id: string; text: string; ts: number }
 
+export type ClaimStartedPayload = {
+  code: string
+  role: string
+  channel?: string
+  expiresAt: number
+}
+
+export type ClaimCompletedPayload = {
+  code: string
+  role: string
+  matchRule: string
+  adapter: string
+  authorId: string
+}
+
+export type ClaimErrorPayload = {
+  code: string
+  reason: string
+}
+
 export type ServerMessage =
   | { type: 'connected'; sessionId: string }
   | { type: 'text_delta'; delta: string }
@@ -45,3 +69,6 @@ export type ServerMessage =
   | { type: 'prompt_started'; messageId: string; text: string }
   | { type: 'doctor_result'; requestId: DoctorRequestId; checks: DoctorCheckPayload[] }
   | { type: 'doctor_fix_result'; requestId: DoctorRequestId; result: DoctorFixPayload }
+  | { type: 'claim_started'; payload: ClaimStartedPayload }
+  | { type: 'claim_completed'; payload: ClaimCompletedPayload }
+  | { type: 'claim_error'; payload: ClaimErrorPayload }

package/src/skills/typeclaw-channel-kakaotalk/SKILL.md

@@ -74,7 +74,7 @@ The adapter exposes three engagement triggers via `channels.kakaotalk.engagement
 
 Stickiness behaves the same as Slack/Discord: once you've engaged in a chat, follow-up messages within `engagement.stickiness.perReply.window` ms will route to you regardless of trigger.
 
-If you find yourself NOT receiving messages you expect to, the most likely cause is the `allow` list. KakaoTalk uses a different grammar from Slack/Discord:
+If you find yourself NOT receiving messages you expect to, the most likely cause is missing role coverage in `roles.<role>.match[]`. KakaoTalk's match-rule grammar:
 
 - `kakao:*` — every chat the account can see (use sparingly: this is every group and DM you are a member of)
 - `kakao:dm/*` — every 1:1 chat
@@ -82,7 +82,7 @@ If you find yourself NOT receiving messages you expect to, the most likely cause
 - `kakao:open/*` — every open chat
 - `kakao:<chat-id>` — a specific chat by numeric chat_id
 
-The init wizard's default is `kakao:dm/*` because group chats with personal accounts are sensitive — every member sees every reply. Only broaden the allow list when the user explicitly asks.
+Group chats with personal accounts are sensitive — every member sees every reply. Be conservative when widening match-rules: a `kakao:group/*` entry on a permissive role exposes the agent in every group the account is a member of. See the `typeclaw-permissions` skill.
 
 ## Mark read on every inbound
 
@@ -91,7 +91,7 @@ The adapter sends a LOCO `NOTIREAD` ack to KakaoTalk for every inbound message e
 Things to know about this behavior:
 
 - Auto-acking every received message is a distinct behavioral fingerprint compared to a human. A human reads messages when they open the chat; this adapter acks every received message instantly, even ones you never reply to. KakaoTalk's abuse detection may flag accounts that ack rapidly and unconditionally. **Run the kakaotalk adapter only on dedicated agent accounts you can afford to lose.**
-- Dropped messages are still acked. If classify drops the message (your own self-sent loopback, empty text, sender not in `allow`), the unread "1" still clears — the agent has observed the bytes, so the read indicator should match.
+- Dropped messages are still acked. If classify drops the message (your own self-sent loopback, empty text, unknown chat), or the router drops it on the `channel.respond` gate, the unread "1" still clears — the agent has observed the bytes, so the read indicator should match.
 - Open chats (오픈채팅) are skipped: the LOCO `NOTIREAD` packet needs a `linkId` for open chats and the adapter doesn't surface it yet. Unread counters in open chats will not decrement.
 - The phone's home-screen OS unread badge may lag until the phone client foregrounds; the in-chat counter and other participants' indicators update immediately. KakaoTalk client quirk, not a typeclaw bug.