typeclaw 0.1.2 → 0.1.4

package/src/agent/tools/channel-fetch-attachment.ts

@@ -7,6 +7,8 @@ import { defineTool } from '@mariozechner/pi-coding-agent'
 import type { ChannelRouter } from '@/channels/router'
 import type { AdapterId } from '@/channels/schema'
 
+import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
+
 export type ChannelFetchAttachmentOrigin = {
   adapter: AdapterId
 }
@@ -15,6 +17,7 @@ export type CreateChannelFetchAttachmentToolOptions = {
   router: ChannelRouter
   origin: ChannelFetchAttachmentOrigin
   inboxDir?: string
+  logger?: ChannelToolLogger
 }
 
 export const DEFAULT_INBOX_DIR = '/agent/workspace/inbox'
@@ -23,6 +26,7 @@ export function createChannelFetchAttachmentTool({
   router,
   origin,
   inboxDir,
+  logger = consoleChannelLogger,
 }: CreateChannelFetchAttachmentToolOptions) {
   const baseDir = inboxDir ?? DEFAULT_INBOX_DIR
   const adapter = origin.adapter
@@ -60,6 +64,7 @@ export function createChannelFetchAttachmentTool({
         ...(params.filename !== undefined ? { filename: params.filename } : {}),
       })
       if (!result.ok) {
+        logger.warn(formatChannelToolFailure('channel_fetch_attachment', `${adapter}: ${result.error}`))
         const text = `channel_fetch_attachment error: ${result.error}`
         const details: Details = { ok: false, error: result.error }
         return { content: [{ type: 'text' as const, text }], details }
@@ -74,6 +79,7 @@ export function createChannelFetchAttachmentTool({
         await writeFile(targetPath, result.buffer)
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err)
+        logger.warn(formatChannelToolFailure('channel_fetch_attachment', `${adapter}: write failed: ${message}`))
         const text = `channel_fetch_attachment error: write failed: ${message}`
         const details: Details = { ok: false, error: `write failed: ${message}` }
         return { content: [{ type: 'text' as const, text }], details }

package/src/agent/tools/channel-history.ts

@@ -5,6 +5,8 @@ import type { ChannelRouter } from '@/channels/router'
 import type { AdapterId } from '@/channels/schema'
 import type { ChannelHistoryMessage } from '@/channels/types'
 
+import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
+
 export type ChannelHistoryOrigin = {
   adapter: AdapterId
   workspace: string
@@ -15,6 +17,7 @@ export type ChannelHistoryOrigin = {
 export type CreateChannelHistoryToolOptions = {
   router: ChannelRouter
   origin: ChannelHistoryOrigin
+  logger?: ChannelToolLogger
 }
 
 // channel_history is a lazy "look back" capability for channel-routed
@@ -27,7 +30,11 @@ export type CreateChannelHistoryToolOptions = {
 // `scope` defaults to thread when the origin has one, channel otherwise.
 // Thread scope on a channel-root session is rejected rather than silently
 // downgraded so the agent doesn't conflate the two views.
-export function createChannelHistoryTool({ router, origin }: CreateChannelHistoryToolOptions) {
+export function createChannelHistoryTool({
+  router,
+  origin,
+  logger = consoleChannelLogger,
+}: CreateChannelHistoryToolOptions) {
   return defineTool({
     name: 'channel_history',
     label: 'Channel History',
@@ -64,6 +71,7 @@ export function createChannelHistoryTool({ router, origin }: CreateChannelHistor
       type Details = { ok: boolean; error?: string; count?: number; nextCursor?: string }
 
       if (scope === 'thread' && origin.thread === null) {
+        logger.warn(formatChannelToolFailure('channel_history', 'thread-scope-requires-thread-session'))
         const text =
           'channel_history error: thread-scope-requires-thread-session — this session is not in a thread; pass `scope: "channel"` instead.'
         const details: Details = { ok: false, error: 'thread-scope-requires-thread-session' }
@@ -78,6 +86,7 @@ export function createChannelHistoryTool({ router, origin }: CreateChannelHistor
       })
 
       if (!result.ok) {
+        logger.warn(formatChannelToolFailure('channel_history', `${origin.adapter}:${origin.chat}: ${result.error}`))
         const details: Details = { ok: false, error: result.error }
         return {
           content: [{ type: 'text' as const, text: `channel_history error: ${result.error}` }],

package/src/agent/tools/channel-log.ts

@@ -0,0 +1,32 @@
+// Shared logger surface for the channel_* agent tools.
+//
+// Until now, channel_send / channel_reply / channel_history /
+// channel_fetch_attachment swallowed every failure into the model-visible
+// tool result and emitted nothing to the container's stdout/stderr. That
+// made operator-side debugging blind: a Slack send that 403'd, a
+// `thread-scope-requires-thread-session` denial, or a Discord attachment
+// fetch that timed out left no trace in `typeclaw logs`. The router layer
+// logs some of these (e.g. `fetchHistory` warns on caught exceptions) but
+// does NOT log `router.send` rejections, and pre-router validation errors
+// inside the tools (missing text, NO_REPLY misuse, thread-scope mismatch,
+// local write failures) never reached the router in the first place.
+//
+// One injectable logger per tool keeps the existing fake-router test
+// pattern intact: tests pass an array-collecting logger to assert the log
+// line, production code defaults to `consoleChannelLogger` which routes to
+// `console.warn` so it lands in `typeclaw logs` alongside the existing
+// `[channels]` lines from manager.ts / router.ts.
+export type ChannelToolLogger = {
+  warn: (msg: string) => void
+}
+
+export const consoleChannelLogger: ChannelToolLogger = {
+  warn: (m) => console.warn(m),
+}
+
+// Format a failure log line. Keeps the `[channels]` prefix used by
+// manager.ts and router.ts so operators can `grep '\[channels\]'` and see
+// the full stack of channel-related warnings in one pass.
+export function formatChannelToolFailure(tool: string, error: string): string {
+  return `[channels] ${tool} failed: ${error}`
+}

package/src/agent/tools/channel-reply.ts

@@ -4,6 +4,8 @@ import { defineTool } from '@mariozechner/pi-coding-agent'
 import { isNoReplySignal, type ChannelRouter } from '@/channels/router'
 import type { AdapterId } from '@/channels/schema'
 
+import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
+
 export type ChannelReplyOrigin = {
   adapter: AdapterId
   workspace: string
@@ -14,6 +16,7 @@ export type ChannelReplyOrigin = {
 export type CreateChannelReplyToolOptions = {
   router: ChannelRouter
   origin: ChannelReplyOrigin
+  logger?: ChannelToolLogger
 }
 
 // channel_reply is the happy-path companion to channel_send for channel-routed
@@ -25,7 +28,11 @@ export type CreateChannelReplyToolOptions = {
 // channel_reply takes only `text` and addresses the message from the origin.
 // channel_send remains for posting somewhere else (different chat, breaking
 // out of a thread, sending DMs from a channel session, etc.).
-export function createChannelReplyTool({ router, origin }: CreateChannelReplyToolOptions) {
+export function createChannelReplyTool({
+  router,
+  origin,
+  logger = consoleChannelLogger,
+}: CreateChannelReplyToolOptions) {
   return defineTool({
     name: 'channel_reply',
     label: 'Channel Reply',
@@ -64,6 +71,7 @@ export function createChannelReplyTool({ router, origin }: CreateChannelReplyToo
       const text = params.text
       const attachments = params.attachments
       if ((text === undefined || text === '') && (attachments === undefined || attachments.length === 0)) {
+        logger.warn(formatChannelToolFailure('channel_reply', 'missing text and attachments'))
         return {
           content: [
             { type: 'text' as const, text: 'channel_reply denied: must provide `text`, `attachments`, or both.' },
@@ -74,6 +82,7 @@ export function createChannelReplyTool({ router, origin }: CreateChannelReplyToo
 
       const noReplyError = noReplyMisuseError(text)
       if (noReplyError) {
+        logger.warn(formatChannelToolFailure('channel_reply', noReplyError))
         return {
           content: [{ type: 'text' as const, text: `channel_reply denied: ${noReplyError}` }],
           details: { ok: false, error: noReplyError },
@@ -89,6 +98,14 @@ export function createChannelReplyTool({ router, origin }: CreateChannelReplyToo
         ...(attachments !== undefined ? { attachments } : {}),
       })
 
+      if (!result.ok) {
+        logger.warn(
+          formatChannelToolFailure(
+            'channel_reply',
+            `${origin.adapter}:${origin.workspace}/${origin.chat}: ${result.error}`,
+          ),
+        )
+      }
       const details: { ok: boolean; error?: string } = result.ok ? { ok: true } : { ok: false, error: result.error }
       // Echo the delivered text back to the model. The adapter classifier
       // drops self-authored messages on the inbound path (`self_author`),

package/src/agent/tools/channel-send.ts

@@ -4,6 +4,7 @@ import { defineTool } from '@mariozechner/pi-coding-agent'
 import { isNoReplySignal, type ChannelRouter } from '@/channels/router'
 import { ADAPTER_IDS, type AdapterId } from '@/channels/schema'
 
+import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
 import { renderOutboundEcho } from './channel-reply'
 
 export type ChannelSendOrigin = {
@@ -21,9 +22,10 @@ export type CreateChannelSendToolOptions = {
   // the model can self-correct on its next turn. Absent for sessions whose
   // origin isn't a channel (e.g. cron prompts that send to channels).
   origin?: ChannelSendOrigin
+  logger?: ChannelToolLogger
 }
 
-export function createChannelSendTool({ router, origin }: CreateChannelSendToolOptions) {
+export function createChannelSendTool({ router, origin, logger = consoleChannelLogger }: CreateChannelSendToolOptions) {
   return defineTool({
     name: 'channel_send',
     label: 'Channel Send',
@@ -93,6 +95,7 @@ export function createChannelSendTool({ router, origin }: CreateChannelSendToolO
       const bodyText = params.text
       const attachments = params.attachments
       if ((bodyText === undefined || bodyText === '') && (attachments === undefined || attachments.length === 0)) {
+        logger.warn(formatChannelToolFailure('channel_send', 'missing text and attachments'))
         return {
           content: [
             { type: 'text' as const, text: 'channel_send denied: must provide `text`, `attachments`, or both.' },
@@ -103,6 +106,7 @@ export function createChannelSendTool({ router, origin }: CreateChannelSendToolO
 
       const noReplyError = noReplyMisuseError(bodyText)
       if (noReplyError) {
+        logger.warn(formatChannelToolFailure('channel_send', noReplyError))
         return {
           content: [{ type: 'text' as const, text: `channel_send denied: ${noReplyError}` }],
           details: { ok: false, error: noReplyError },
@@ -118,6 +122,14 @@ export function createChannelSendTool({ router, origin }: CreateChannelSendToolO
         ...(attachments !== undefined ? { attachments } : {}),
       })
 
+      if (!result.ok) {
+        logger.warn(
+          formatChannelToolFailure(
+            'channel_send',
+            `${params.adapter}:${params.workspace}/${params.chat}: ${result.error}`,
+          ),
+        )
+      }
       const details: { ok: boolean; error?: string } = result.ok ? { ok: true } : { ok: false, error: result.error }
       const echo = renderOutboundEcho(bodyText, attachments)
       const baseText = result.ok

package/src/bundled-plugins/tool-result-cap/README.md

@@ -0,0 +1,67 @@
+# typeclaw-plugin-tool-result-cap
+
+The bundled tool-result-cap plugin. Caps the size of `tool.after` results before they get persisted to the session JSONL, so a single oversized tool output cannot bloat the transcript and force the full payload to round-trip to the LLM on every subsequent turn.
+
+This plugin is **auto-loaded** by every TypeClaw agent. There is no `plugins[]` entry to add and no opt-out short of `tool-result-cap.enabled: false`. To configure it, add a `tool-result-cap` block to `typeclaw.json`.
+
+## Why it exists
+
+`pi-coding-agent`'s built-in tools occasionally return very large payloads that the model only needed once. Two empirically observed cases:
+
+1. **`read` on an image file** returns the base64-encoded image inline (e.g. `{type:"image", data:"<3.2MB of base64>"}`). The model uses it on the turn it was asked for, then sees the same 3.2MB of base64 as conversation context on every subsequent prompt — until compaction fires (which is token-driven, not byte-driven, so a single fat blob may sit in context for many turns before compaction is triggered).
+2. **`webfetch` on a binary URL** (PNG, ZIP, etc.) receives the raw response body, treats it as text, and stores raw binary as a JSON-encoded string. Same effect: 100KB+ of mojibake sits in the transcript permanently.
+
+The result is a session JSONL file that's tens of megabytes on disk but mostly one or two giant tool results, plus 3-minute first-prompt latencies after container restart because the full transcript gets re-shipped to the LLM as context.
+
+`tool-result-cap` registers a `tool.after` hook that inspects every tool's result and, in place, replaces oversized image/text parts with a short placeholder before pi-coding-agent appends the entry to the JSONL. The cap happens at the wire-format level, so the bloat never reaches disk or the LLM in the first place.
+
+## Config
+
+```json
+{
+  "tool-result-cap": {
+    "enabled": true,
+    "imageMaxBytes": 262144,
+    "textMaxBytes": 65536,
+    "exemptTools": []
+  }
+}
+```
+
+| Field                           | Default  | Effect                                                                                                                                                                                                                                                                                   |
+| ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tool-result-cap.enabled`       | `true`   | Master switch. When `false`, the plugin returns no hooks at all and tool results pass through untouched.                                                                                                                                                                                 |
+| `tool-result-cap.imageMaxBytes` | `262144` | Maximum size (in bytes of the base64 string, not the decoded binary) for any `{type:"image"}` part in a tool result. Parts above this are replaced with a short text placeholder naming the original mime type and size. Default is ~256KB of base64 ≈ ~190KB of binary. Minimum `1024`. |
+| `tool-result-cap.textMaxBytes`  | `65536`  | Maximum length (in characters) for any `{type:"text"}` part. Parts above this are truncated: the first `textMaxBytes` characters are kept (so the LLM sees the shape of the output), and an elision marker is appended naming the byte count dropped. Minimum `1024`.                    |
+| `tool-result-cap.exemptTools`   | `[]`     | List of tool names to skip entirely. Use when a specific tool genuinely needs to return large payloads and you can absorb the per-turn cost.                                                                                                                                             |
+
+All fields are **restart-required** — the plugin reads them once at boot.
+
+## How it works
+
+The plugin registers a single `tool.after` hook. The hook receives `event.result: ToolResult` by reference, walks `result.content`, and replaces each `ContentPart` in place when it exceeds its corresponding threshold. Mutation order is unspecified across plugins, but because the wrapper in `src/agent/plugin-tools.ts` reads the same `hookResult.content` reference after the hook chain finishes, mutations are seen by pi-coding-agent and persisted to JSONL.
+
+The cap is per-part, not per-result, so a result with one small text part and one giant image is partly preserved (small text untouched, image elided).
+
+Placeholders carry the literal substring `tool-result-cap:` so future agents (or human operators inspecting a session) can grep for them and recognize that the original payload was intentionally elided rather than truncated by some other layer.
+
+## What's not capped
+
+- `details` on tool results (an opaque structured payload provider-specific to each tool — generally small, and mutating it risks breaking tool-specific telemetry).
+- Tool calls themselves (`assistant` messages with `toolUse` content). These are bounded by the LLM's own output limits.
+- User messages and system prompts.
+
+## Ordering against other bundled plugins
+
+Plugin hook order is the order plugins are listed in `src/run/bundled-plugins.ts`. `tool-result-cap` is registered **before** `guard` so guard's `tool.after` advice (the uncommitted-changes warning) appends to the already-capped content. This means a guard advice that fires on the same call sees a small text part and a placeholder, never the original oversized payload — keeping the advice text immediately legible in the JSONL.
+
+## What it contributes
+
+| Kind | Name         | Notes                                                                                                                                  |
+| ---- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| Hook | `tool.after` | Walks `event.result.content` and replaces oversized image/text parts in place. Logs one `info` line per capped call, silent otherwise. |
+
+## Tests
+
+- `cap-result.test.ts` — pure-function unit tests for the capping logic (image replacement, text truncation, mixed parts, exempt tools, empty results, in-place mutation invariant).
+- `index.test.ts` — composition tests (config schema defaults and validation, hook registration, disabled-mode short-circuit, logging on cap, silence on no-op).

package/src/bundled-plugins/tool-result-cap/cap-result.ts

@@ -0,0 +1,56 @@
+import type { ContentPart, ToolResult } from '@/plugin'
+
+export type CapOptions = {
+  imageMaxBytes: number
+  textMaxBytes: number
+  exemptTools: ReadonlySet<string>
+}
+
+export type CapStats = {
+  imagesReplaced: number
+  textsTruncated: number
+  bytesElided: number
+}
+
+// Sentinel marker used in both image and text replacement payloads so a future
+// pass (or the LLM itself) can recognize that a value was capped rather than
+// truthfully short. Plain English on purpose — these strings get fed to the
+// model on every turn, and unfamiliar tokens cost reasoning bandwidth.
+const ELIDED_MARKER = '[tool-result-cap: '
+
+export function capToolResult(tool: string, result: ToolResult, options: CapOptions): CapStats {
+  const stats: CapStats = { imagesReplaced: 0, textsTruncated: 0, bytesElided: 0 }
+  if (options.exemptTools.has(tool)) return stats
+
+  for (let i = 0; i < result.content.length; i++) {
+    const part = result.content[i]
+    if (!part) continue
+    if (part.type === 'image') {
+      const size = part.data.length
+      if (size <= options.imageMaxBytes) continue
+      result.content[i] = {
+        type: 'text',
+        text: `${ELIDED_MARKER}image ${part.mimeType} elided, ${size} bytes of base64 exceeded imageMaxBytes=${options.imageMaxBytes}]`,
+      }
+      stats.imagesReplaced += 1
+      stats.bytesElided += size
+      continue
+    }
+    if (part.type === 'text') {
+      const size = part.text.length
+      if (size <= options.textMaxBytes) continue
+      // Keep a head slice of the original text so the LLM still has a hint of
+      // shape (e.g. "fetched HTML starts with <!DOCTYPE..."). Tail is dropped.
+      const head = part.text.slice(0, options.textMaxBytes)
+      const elided = size - options.textMaxBytes
+      const replacement: ContentPart = {
+        type: 'text',
+        text: `${head}\n\n${ELIDED_MARKER}${elided} bytes truncated from text part; original was ${size} bytes, textMaxBytes=${options.textMaxBytes}]`,
+      }
+      result.content[i] = replacement
+      stats.textsTruncated += 1
+      stats.bytesElided += elided
+    }
+  }
+  return stats
+}

package/src/bundled-plugins/tool-result-cap/index.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod'
+
+import { definePlugin } from '@/plugin'
+
+import { capToolResult } from './cap-result'
+
+const DEFAULT_IMAGE_MAX_BYTES = 262_144
+const DEFAULT_TEXT_MAX_BYTES = 65_536
+const MIN_IMAGE_MAX_BYTES = 1_024
+const MIN_TEXT_MAX_BYTES = 1_024
+
+const toolResultCapConfigSchema = z
+  .object({
+    enabled: z.boolean().default(true),
+    imageMaxBytes: z.number().int().min(MIN_IMAGE_MAX_BYTES).default(DEFAULT_IMAGE_MAX_BYTES),
+    textMaxBytes: z.number().int().min(MIN_TEXT_MAX_BYTES).default(DEFAULT_TEXT_MAX_BYTES),
+    exemptTools: z.array(z.string()).default([]),
+  })
+  .default({
+    enabled: true,
+    imageMaxBytes: DEFAULT_IMAGE_MAX_BYTES,
+    textMaxBytes: DEFAULT_TEXT_MAX_BYTES,
+    exemptTools: [],
+  })
+
+export default definePlugin({
+  configSchema: toolResultCapConfigSchema,
+  plugin: async (ctx) => {
+    const { enabled, imageMaxBytes, textMaxBytes, exemptTools } = ctx.config
+    if (!enabled) return {}
+
+    const options = {
+      imageMaxBytes,
+      textMaxBytes,
+      exemptTools: new Set(exemptTools),
+    }
+
+    return {
+      hooks: {
+        'tool.after': (event) => {
+          const stats = capToolResult(event.tool, event.result, options)
+          if (stats.imagesReplaced > 0 || stats.textsTruncated > 0) {
+            ctx.logger.info(
+              `[tool-result-cap] capped ${event.tool} call=${event.callId}: imagesReplaced=${stats.imagesReplaced} textsTruncated=${stats.textsTruncated} bytesElided=${stats.bytesElided}`,
+            )
+          }
+        },
+      },
+    }
+  },
+})

package/src/channels/adapters/kakaotalk.ts

@@ -11,6 +11,7 @@ import {
   type KakaoTalkPushEmoticonEvent,
   type KakaoTalkPushMessageEvent,
 } from 'agent-messenger/kakaotalk'
+import type { KakaoAccountCredentials, KakaoConfig, PendingLoginState } from 'agent-messenger/kakaotalk'
 
 import type { ChannelRouter } from '@/channels/router'
 import { isAllowed, type ChannelAdapterConfig, type KakaotalkAdapterConfig } from '@/channels/schema'
@@ -75,6 +76,19 @@ export interface KakaoTalkListener {
   ): this
 }
 
+export type KakaoCredentialStore = {
+  load(): Promise<KakaoConfig>
+  save(config: KakaoConfig): Promise<void>
+  getAccount(id?: string): Promise<KakaoAccountCredentials | null>
+  setAccount(account: KakaoAccountCredentials): Promise<void>
+  removeAccount(id: string): Promise<void>
+  listAccounts(): Promise<Array<KakaoAccountCredentials & { is_current: boolean }>>
+  setCurrentAccount(id: string): Promise<void>
+  savePendingLogin(state: PendingLoginState): Promise<void>
+  loadPendingLogin(): Promise<PendingLoginState | null>
+  clearPendingLogin(): Promise<void>
+}
+
 const KakaoTalkClient = RealKakaoTalkClient as unknown as new () => KakaoTalkClient
 const KakaoTalkListener = RealKakaoTalkListener as unknown as new (client: KakaoTalkClient) => KakaoTalkListener
 
@@ -95,13 +109,9 @@ export type KakaotalkAdapterOptions = {
   configRef: () => KakaotalkAdapterConfig
   logger?: KakaotalkAdapterLogger
   selfAliasesRef?: () => readonly string[]
-  // When set, the adapter loads KakaoTalk credentials from this directory
-  // (via KakaoCredentialManager(credentialsDir)) instead of relying on
-  // the SDK's AGENT_MESSENGER_CONFIG_DIR env-var fallback. Production
-  // wiring in src/channels/manager.ts passes the agent-folder workspace
-  // path here so the adapter's credential resolution does NOT depend on
-  // process.env state — easier to test, and removes a hidden coupling
-  // with whatever set the env var (Dockerfile, CLI shell, etc.).
+  credentialsStore?: KakaoCredentialStore
+  // Deprecated compatibility path for old tests/callers. Production uses
+  // credentialsStore so secrets.json remains the credential source of truth.
   credentialsDir?: string
   client?: KakaoTalkClient
   listenerFactory?: (client: KakaoTalkClient) => KakaoTalkListener
@@ -416,17 +426,16 @@ export function createKakaotalkAdapter(options: KakaotalkAdapterOptions): Kakaot
       lastConnectedAt = null
       resetRecoveryEpisode()
       try {
-        if (options.credentialsDir !== undefined) {
-          // Explicit credential path: read the file ourselves and pass the
-          // tokens directly to client.login(). This bypasses the SDK's
-          // ensureKakaoAuth() (which reads AGENT_MESSENGER_CONFIG_DIR or
-          // ~/.config/agent-messenger), making the adapter independent of
-          // process.env state.
-          const credManager = new KakaoCredentialManager(options.credentialsDir)
-          const account = await credManager.getAccount()
+        const credentialStore =
+          options.credentialsStore ??
+          (options.credentialsDir !== undefined ? new KakaoCredentialManager(options.credentialsDir) : null)
+        if (credentialStore !== null) {
+          const account = await credentialStore.getAccount()
           if (account === null) {
             throw new Error(
-              `no KakaoTalk account in ${options.credentialsDir}/kakaotalk-credentials.json (run typeclaw init to authenticate)`,
+              options.credentialsDir !== undefined
+                ? `no KakaoTalk account in ${options.credentialsDir}/kakaotalk-credentials.json (run typeclaw init to authenticate)`
+                : 'no KakaoTalk account in secrets.json#channels.kakaotalk (run typeclaw init to authenticate)',
             )
           }
           await client.login({

package/src/channels/manager.ts

@@ -1,7 +1,9 @@
 import { createHash } from 'node:crypto'
-import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
+import { SecretsKakaoCredentialStore } from '@/secrets/kakao-store'
+import { SecretsBackend } from '@/secrets/storage'
+
 import { createDiscordBotAdapter, type DiscordBotAdapter } from './adapters/discord-bot'
 import { createKakaotalkAdapter, type KakaotalkAdapter } from './adapters/kakaotalk'
 import { createSlackBotAdapter, type SlackBotAdapter } from './adapters/slack-bot'
@@ -62,10 +64,10 @@ type AnyAdapter = DiscordBotAdapter | KakaotalkAdapter | SlackBotAdapter | Teleg
 // Credential signature is the comparison key for credential-rotation
 // detection on reload. Discord and Telegram each use a single bot token;
 // Slack needs both a bot token and an app-level token (Socket Mode);
-// KakaoTalk authenticates via a credentials file under
-// AGENT_MESSENGER_CONFIG_DIR (workspace/), so its signature is the file's
-// content hash. The "credential" naming (vs "token") generalizes across the
-// env-var-based adapters and KakaoTalk's file-based credential pathway.
+// KakaoTalk authenticates via a structured multi-account block in
+// secrets.json#channels.kakaotalk, so its signature is that block's content
+// hash. The "credential" naming (vs "token") generalizes across the
+// env-var-based adapters and KakaoTalk's account credential pathway.
 type AdapterEntry = {
   adapter: AnyAdapter
   credentialSignature: string
@@ -89,7 +91,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
   const live = new Map<AdapterId, AdapterEntry>()
 
   const buildCredentialSignature = (name: AdapterId): { signature: string; missing: string[] } => {
-    if (name === 'kakaotalk') return buildKakaotalkSignature(options.agentDir, env)
+    if (name === 'kakaotalk') return buildKakaotalkSignature(options.agentDir)
     const requiredEnvs = TOKEN_ENV[name]
     const parts: string[] = []
     const missing: string[] = []
@@ -132,7 +134,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
         configRef: () => options.channelsConfigRef()[name] ?? cfg,
         logger,
         selfAliasesRef: () => router.getSelfAliases(),
-        credentialsDir: resolveKakaoConfigDir(options.agentDir, env),
+        credentialsStore: createContainerKakaoCredentialStore(options.agentDir, env),
       })
     }
     if (name === 'telegram-bot') {
@@ -223,7 +225,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
           const { signature, missing } = buildCredentialSignature(name)
           if (missing.length > 0) {
             // Required credentials disappeared (env vars removed from .env, or
-            // KakaoTalk credentials file deleted). Continuing to use the
+            // KakaoTalk credentials removed from secrets.json). Continuing to use the
             // in-memory credentials would silently honor a credential the
             // operator explicitly removed, so stop the adapter instead of
             // waiting for a manual restart.
@@ -244,49 +246,56 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
   }
 }
 
-// Token-based adapters only. KakaoTalk's credentials live in a file under
-// AGENT_MESSENGER_CONFIG_DIR (workspace/.agent-messenger/), not in env, so
-// it goes through buildKakaotalkSignature instead.
+// Token-based adapters only. KakaoTalk's credentials live in
+// secrets.json#channels.kakaotalk, not in env, so it goes through
+// buildKakaotalkSignature instead.
 const TOKEN_ENV: Record<Exclude<AdapterId, 'kakaotalk'>, readonly string[]> = {
   'discord-bot': ['DISCORD_BOT_TOKEN'],
   'slack-bot': ['SLACK_BOT_TOKEN', 'SLACK_APP_TOKEN'],
   'telegram-bot': ['TELEGRAM_BOT_TOKEN'],
 }
 
-const KAKAO_DEFAULT_SUBDIR = '.agent-messenger'
-const KAKAO_CREDENTIALS_FILE = 'kakaotalk-credentials.json'
-
-function resolveKakaoConfigDir(agentDir: string, env: NodeJS.ProcessEnv): string {
-  const override = env.AGENT_MESSENGER_CONFIG_DIR
-  if (override !== undefined && override.trim() !== '') return override
-  return join(agentDir, 'workspace', KAKAO_DEFAULT_SUBDIR)
-}
-
-function resolveKakaoCredentialsPath(agentDir: string, env: NodeJS.ProcessEnv): string {
-  return join(resolveKakaoConfigDir(agentDir, env), KAKAO_CREDENTIALS_FILE)
+function createContainerKakaoCredentialStore(agentDir: string, env: NodeJS.ProcessEnv): SecretsKakaoCredentialStore {
+  const hostdUrl = env.TYPECLAW_HOSTD_URL
+  const restartToken = env.TYPECLAW_HOSTD_TOKEN
+  const containerName = env.TYPECLAW_CONTAINER_NAME
+  if (!hostdUrl || !restartToken || !containerName) {
+    throw new Error(
+      'KakaoTalk credentials require TYPECLAW_HOSTD_URL, TYPECLAW_HOSTD_TOKEN, and TYPECLAW_CONTAINER_NAME',
+    )
+  }
+  return new SecretsKakaoCredentialStore({
+    mode: 'container',
+    secretsPath: join(agentDir, 'secrets.json'),
+    hostdUrl,
+    restartToken,
+    containerName,
+  })
 }
 
-function buildKakaotalkSignature(agentDir: string, env: NodeJS.ProcessEnv): { signature: string; missing: string[] } {
-  const path = resolveKakaoCredentialsPath(agentDir, env)
-  if (!existsSync(path)) {
-    return { signature: '', missing: [`kakaotalk credentials file at ${path}`] }
-  }
+function buildKakaotalkSignature(agentDir: string): { signature: string; missing: string[] } {
+  const path = join(agentDir, 'secrets.json')
   try {
-    // Content hash, not mtime+size: KakaoTalk's credential file is small
-    // (a few hundred bytes of JSON) and is rewritten on every OAuth token
-    // refresh. Hashing avoids two failure modes mtime+size could miss:
-    //   (a) a refresh that produces byte-identical content (rare but
-    //       possible when nothing actually rotated) — we correctly skip;
-    //   (b) a refresh that lands on the same mtime due to FS resolution
-    //       (some host filesystems quantize to seconds).
-    const buf = readFileSync(path)
-    const digest = createHash('sha256').update(buf).digest('hex')
-    return { signature: `${path}@sha256:${digest}`, missing: [] }
+    const block = new SecretsBackend(path).tryReadChannelsSync()?.kakaotalk
+    if (!isKakaoCredentialBlock(block)) {
+      return { signature: '', missing: ['secrets.json#channels.kakaotalk'] }
+    }
+    const digest = createHash('sha256').update(JSON.stringify(block)).digest('hex')
+    return { signature: `secrets.json#channels.kakaotalk@sha256:${digest}`, missing: [] }
   } catch (err) {
-    return { signature: '', missing: [`kakaotalk credentials file at ${path} (${describe(err)})`] }
+    return { signature: '', missing: [`secrets.json#channels.kakaotalk (${describe(err)})`] }
   }
 }
 
+function isKakaoCredentialBlock(value: unknown): value is { accounts: Record<string, unknown> } {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  if (!('accounts' in value)) return false
+  const accounts = value.accounts
+  return (
+    typeof accounts === 'object' && accounts !== null && !Array.isArray(accounts) && Object.keys(accounts).length > 0
+  )
+}
+
 function describe(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }

package/src/cli/channel.ts

@@ -336,7 +336,7 @@ function reportProgress(events: AddChannelStepEvent[]): (event: AddChannelStepEv
         s.stop('Updated typeclaw.json.')
         break
       case 'secrets':
-        s.stop('Appended credentials to .env.')
+        s.stop('Saved credentials to secrets.json.')
         break
     }
   }
@@ -345,11 +345,11 @@ function reportProgress(events: AddChannelStepEvent[]): (event: AddChannelStepEv
 const START_MESSAGES: Record<AddChannelStepEvent['step'], string> = {
   'kakaotalk-auth': 'Logging in to KakaoTalk...',
   config: 'Updating typeclaw.json...',
-  secrets: 'Appending credentials to .env...',
+  secrets: 'Saving credentials to secrets.json...',
 }
 
 function reportKakaotalkAuth(result: KakaotalkAuthResult): string {
-  if (result.ok) return 'KakaoTalk credentials saved to workspace/.agent-messenger/.'
+  if (result.ok) return 'KakaoTalk credentials saved to secrets.json.'
   return `KakaoTalk login failed: ${result.reason}`
 }