typeclaw 0.1.5 → 0.2.0

package/src/secrets/storage.ts

@@ -175,6 +175,74 @@ export class SecretsBackend implements AuthStorageBackend {
     }
   }
 
+  // Returns a shallow snapshot of the `providers` slice. Used by post-init CLI
+  // commands (`typeclaw provider list/remove`, `typeclaw model list`) that need
+  // to inspect what's on disk without forcing AuthStorage's env-wins flatten —
+  // we want to show users which providers are file-backed vs env-overridden,
+  // and the flatten path collapses that distinction.
+  tryReadProvidersSync(): Providers {
+    if (!existsSync(this.secretsPath)) return {}
+    let release: (() => void) | undefined
+    try {
+      release = this.acquireSyncLockWithRetry()
+      return { ...this.readEnvelope().providers }
+    } finally {
+      release?.()
+    }
+  }
+
+  // Atomic provider credential write. Idempotent at the type level: callers
+  // pass the full `ProviderCredential` (api_key or oauth), and the entry is
+  // merged into `providers.<id>` verbatim — same shape the schema accepts on
+  // read. Used by `typeclaw provider add/set` to write api-key credentials
+  // without going through AuthStorage's flatten/unflatten round-trip.
+  // OAuth flows MUST continue to go through `AuthStorage.login()` so refresh
+  // tokens land in the correct shape; this method is api-key oriented.
+  writeProviderCredentialSync(providerId: string, credential: ProviderCredential): void {
+    this.ensureParentDir()
+    this.ensureFileExists()
+    let release: (() => void) | undefined
+    try {
+      release = this.acquireSyncLockWithRetry()
+      const envelope = this.readEnvelope()
+      const next: SecretsFile = {
+        ...envelope,
+        $schema: envelope.$schema ?? SCHEMA_REL,
+        version: SECRETS_FILE_VERSION,
+        providers: { ...envelope.providers, [providerId]: credential },
+      }
+      this.writeEnvelopeAtomic(next)
+    } finally {
+      release?.()
+    }
+  }
+
+  // Removes `providers.<id>` from the envelope. Returns `true` when the
+  // provider was present and removed, `false` when nothing changed (idempotent
+  // on the CLI side — `provider remove fireworks` twice should not error on
+  // the second call). The file is rewritten only when something changed so
+  // canonical-shape reads pay zero cost.
+  removeProviderCredentialSync(providerId: string): boolean {
+    if (!existsSync(this.secretsPath)) return false
+    let release: (() => void) | undefined
+    try {
+      release = this.acquireSyncLockWithRetry()
+      const envelope = this.readEnvelope()
+      if (!(providerId in envelope.providers)) return false
+      const { [providerId]: _removed, ...rest } = envelope.providers
+      const next: SecretsFile = {
+        ...envelope,
+        $schema: envelope.$schema ?? SCHEMA_REL,
+        version: SECRETS_FILE_VERSION,
+        providers: rest,
+      }
+      this.writeEnvelopeAtomic(next)
+      return true
+    } finally {
+      release?.()
+    }
+  }
+
   writeChannelsSync(next: Channels): void {
     this.ensureParentDir()
     this.ensureFileExists()

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
@@ -37,6 +44,22 @@ export type ServerOptions = {
   // 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>
@@ -61,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.
@@ -85,6 +110,8 @@ export function createServer({
   containerName,
   tuiToken,
   containerBroker,
+  logger = consoleLogger,
+  claimController,
 }: ServerOptions) {
   const sessionStates = new WeakMap<Ws, SessionState>()
 
@@ -153,6 +180,8 @@ export function createServer({
               draining: false,
               unsubBroadcast: null,
               unsubPrompts: null,
+              unsubClaim: null,
+              activeClaimCode: null,
               runtimeSnapshot: runtimeSnapshot ?? null,
               dispose,
             }
@@ -162,11 +191,11 @@ export function createServer({
               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),
+                enqueuePrompt(ws, state, msg, agentDir, logger),
               )
 
               state.unsubBroadcast = stream.subscribe({ target: { kind: 'broadcast' } }, (msg) => {
@@ -198,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
@@ -250,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({
@@ -278,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) {
@@ -305,7 +407,7 @@ function isWebSocketUpgrade(req: Request): boolean {
   return req.headers.get('upgrade')?.toLowerCase() === 'websocket'
 }
 
-function forwardSessionEvents(ws: Ws, session: AgentSession): void {
+function forwardSessionEvents(ws: Ws, session: AgentSession, logger: ServerLogger, sessionFileId: string): void {
   const toolStartedAt = new Map<string, number>()
 
   session.subscribe((event) => {
@@ -323,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())
@@ -352,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
@@ -361,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'
@@ -380,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
@@ -416,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)
@@ -433,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.