typeclaw 0.1.0 → 0.1.2

package/src/plugin/registry.ts

@@ -3,13 +3,28 @@ import { existsSync } from 'node:fs'
 import type { CronJob, PromptJob } from '@/cron'
 
 import type { HookBus } from './hooks'
-import type { PluginCronJob, PluginExports, PluginLogger, PluginSkill, Subagent, Tool } from './types'
+import type {
+  PluginCronJob,
+  PluginDoctorCheck,
+  PluginExports,
+  PluginLogger,
+  PluginSkill,
+  Subagent,
+  Tool,
+} from './types'
 
 export type RegisteredTool = { pluginName: string; toolName: string; tool: Tool<any>; logger: PluginLogger }
 export type RegisteredSubagent = { pluginName: string; subagentName: string; subagent: Subagent<any> }
 export type RegisteredCronJob = { pluginName: string; localId: string; globalId: string; job: CronJob }
 export type RegisteredSkillEntry = { pluginName: string; localName: string; skill: PluginSkill }
 export type RegisteredSkillDir = { pluginName: string; path: string }
+export type RegisteredDoctorCheck = {
+  pluginName: string
+  checkName: string
+  pluginConfig: unknown
+  logger: PluginLogger
+  check: PluginDoctorCheck
+}
 
 export type PluginRegistry = {
   tools: RegisteredTool[]
@@ -17,6 +32,7 @@ export type PluginRegistry = {
   cronJobs: RegisteredCronJob[]
   skills: RegisteredSkillEntry[]
   skillsDirs: RegisteredSkillDir[]
+  doctorChecks: RegisteredDoctorCheck[]
 }
 
 export type RegisterContributionsOptions = {
@@ -26,6 +42,7 @@ export type RegisterContributionsOptions = {
   registry: PluginRegistry
   hooks: HookBus
   agentDir: string
+  pluginConfig: unknown
 }
 
 export function buildPluginCronGlobalId(pluginName: string, localId: string): string {
@@ -33,7 +50,7 @@ export function buildPluginCronGlobalId(pluginName: string, localId: string): st
 }
 
 export function registerContributions(opts: RegisterContributionsOptions): void {
-  const { pluginName, logger, exports: ex, registry, hooks, agentDir } = opts
+  const { pluginName, logger, exports: ex, registry, hooks, agentDir, pluginConfig } = opts
 
   if (ex.tools) {
     for (const [toolName, tool] of Object.entries(ex.tools)) {
@@ -99,6 +116,17 @@ export function registerContributions(opts: RegisterContributionsOptions): void
   if (ex.hooks) {
     hooks.registerAll(pluginName, agentDir, logger, ex.hooks)
   }
+
+  if (ex.doctorChecks) {
+    for (const [checkName, check] of Object.entries(ex.doctorChecks)) {
+      assertNotEmpty('doctor check name', checkName, pluginName)
+      const conflict = registry.doctorChecks.find((c) => c.pluginName === pluginName && c.checkName === checkName)
+      if (conflict) {
+        throw new Error(`plugin ${pluginName}: doctor check "${checkName}" already registered`)
+      }
+      registry.doctorChecks.push({ pluginName, checkName, pluginConfig, logger, check })
+    }
+  }
 }
 
 export function discardRegistrationsBy(pluginName: string, registry: PluginRegistry, hooks: HookBus): void {
@@ -107,11 +135,12 @@ export function discardRegistrationsBy(pluginName: string, registry: PluginRegis
   registry.cronJobs = registry.cronJobs.filter((j) => j.pluginName !== pluginName)
   registry.skills = registry.skills.filter((s) => s.pluginName !== pluginName)
   registry.skillsDirs = registry.skillsDirs.filter((d) => d.pluginName !== pluginName)
+  registry.doctorChecks = registry.doctorChecks.filter((d) => d.pluginName !== pluginName)
   hooks.unregisterAll(pluginName)
 }
 
 export function emptyRegistry(): PluginRegistry {
-  return { tools: [], subagents: [], cronJobs: [], skills: [], skillsDirs: [] }
+  return { tools: [], subagents: [], cronJobs: [], skills: [], skillsDirs: [], doctorChecks: [] }
 }
 
 function assertNotEmpty(kind: string, value: string, pluginName: string): void {

package/src/plugin/types.ts

@@ -97,6 +97,24 @@ export type SessionIdleEvent = {
   origin?: SessionOrigin
 }
 
+// Brackets every `session.prompt(...)` invocation. Distinct from
+// `session.start`/`session.end` (which bracket session lifetime) so that
+// long-lived TUI or channel sessions, which can sit idle between turns,
+// don't wedge a turn-counter forever. `origin` carries the session's origin
+// so observers can exclude their own induced turns when counting (e.g. the
+// backup plugin excludes `subagent: 'backup'` to avoid self-gating).
+export type SessionTurnStartEvent = {
+  sessionId: string
+  agentDir: string
+  origin?: SessionOrigin
+}
+
+export type SessionTurnEndEvent = {
+  sessionId: string
+  agentDir: string
+  origin?: SessionOrigin
+}
+
 // Provider prompt caching requires byte-identical prefixes. Mutations near the
 // end of `event.prompt` preserve cache hits across sessions; mutations near
 // the start invalidate the cache on every LLM call.
@@ -136,6 +154,8 @@ export type Hooks = {
   'session.end'?: (event: SessionEndEvent, ctx: HookContext) => Promise<void> | void
   'session.idle'?: (event: SessionIdleEvent, ctx: HookContext) => Promise<void> | void
   'session.prompt'?: (event: SessionPromptEvent, ctx: HookContext) => Promise<void> | void
+  'session.turn.start'?: (event: SessionTurnStartEvent, ctx: HookContext) => Promise<void> | void
+  'session.turn.end'?: (event: SessionTurnEndEvent, ctx: HookContext) => Promise<void> | void
   'tool.before'?: (event: ToolBeforeEvent, ctx: HookContext) => Promise<ToolBeforeResult> | ToolBeforeResult
   'tool.after'?: (event: ToolAfterEvent, ctx: HookContext) => Promise<void> | void
 }
@@ -164,6 +184,51 @@ export type PluginExports = {
   skills?: Record<string, PluginSkill>
   skillsDirs?: string[]
   hooks?: Hooks
+  doctorChecks?: Record<string, PluginDoctorCheck>
+}
+
+// `typeclaw doctor` plugin extension surface. Each check is read-only by
+// default; declaring `fix.apply` opts the check into `typeclaw doctor --fix`,
+// where the host serializes plugin fixes, validates their `changedPaths`
+// against the agent folder, and commits the union of all fixes in a single
+// commit.
+export type PluginDoctorCheck = {
+  description: string
+  category?: string
+  run: (ctx: PluginDoctorContext) => Promise<PluginCheckResult>
+}
+
+export type PluginDoctorContext = {
+  readonly pluginName: string
+  readonly agentDir: string
+  readonly config: unknown
+  readonly logger: PluginLogger
+}
+
+export type PluginCheckStatus = 'ok' | 'warning' | 'error'
+
+export type PluginCheckResult = {
+  status: PluginCheckStatus
+  message: string
+  details?: string[]
+  fix?: PluginFixSuggestion
+}
+
+export type PluginFixSuggestion = {
+  description: string
+  // When omitted, the fix is advisory-only. `typeclaw doctor --fix` only
+  // attempts to remediate checks whose suggestion includes an `apply`.
+  apply?: (ctx: PluginDoctorContext) => Promise<PluginFixResult>
+}
+
+export type PluginFixResult = {
+  // One-line description that appears in the commit body as a bullet.
+  summary: string
+  // POSIX paths relative to agentDir; the host validates each one stays
+  // inside agentDir before `git add`ing. Absolute paths and `..` segments
+  // are rejected to keep plugin fixes from staging files outside the agent
+  // folder. Empty array is valid (e.g. a fix that only logs).
+  changedPaths: string[]
 }
 
 export type DefinedPlugin<TConfig = never> = {

package/src/run/bundled-plugins.ts

@@ -1,4 +1,5 @@
 import agentBrowserPlugin from '@/bundled-plugins/agent-browser'
+import backupPlugin from '@/bundled-plugins/backup'
 import guardPlugin from '@/bundled-plugins/guard'
 import memoryPlugin from '@/bundled-plugins/memory'
 import securityPlugin from '@/bundled-plugins/security'
@@ -16,9 +17,16 @@ import type { ResolvedPlugin } from '@/plugin'
 // Letting `guard` run first would still work today since the two plugins
 // guard disjoint surfaces, but seeding the order now means future overlap
 // (e.g. a security policy on writes) blocks before guard's softer advice.
+//
+// `memory` is registered before `backup` so memory's dreaming commits always
+// land in the same git index window before backup's commit-and-push cycle.
+// They commit disjoint paths today (memory/ vs sessions/ + agent changes),
+// but if either ever holds .git/index.lock the deterministic order makes the
+// contention easier to reason about.
 export const BUNDLED_PLUGINS: ResolvedPlugin[] = [
   { name: 'security', version: undefined, source: '<bundled>', defined: securityPlugin },
   { name: 'guard', version: undefined, source: '<bundled>', defined: guardPlugin },
   { name: 'memory', version: undefined, source: '<bundled>', defined: memoryPlugin },
+  { name: 'backup', version: undefined, source: '<bundled>', defined: backupPlugin },
   { name: 'agent-browser', version: undefined, source: '<bundled>', defined: agentBrowserPlugin },
 ]

package/src/run/index.ts

@@ -142,14 +142,15 @@ export async function startAgent({
     const entry = snap.pluginSubagentByShim.get(subagent)
     if (entry) {
       const sessionId = `subagent-${entry.pluginName}-${crypto.randomUUID()}`
+      const origin = {
+        kind: 'subagent' as const,
+        subagent: subagentOptions?.name ?? entry.subagentName,
+        parentSessionId: subagentOptions?.parentSessionId ?? '<unknown>',
+      }
       const created = await createSessionWithDispose({
         systemPromptOverride: entry.pluginSubagent.systemPrompt,
         channelRouter: channelManager.router,
-        origin: {
-          kind: 'subagent',
-          subagent: subagentOptions?.name ?? entry.subagentName,
-          parentSessionId: subagentOptions?.parentSessionId ?? '<unknown>',
-        },
+        origin,
         plugins: {
           registry: snap.registry,
           hooks: snap.hooks,
@@ -167,6 +168,8 @@ export async function startAgent({
         ...created,
         hooks: snap.hooks,
         sessionId,
+        agentDir: cwd,
+        origin,
       }
     }
     return defaultCreateSessionForSubagent(subagent, subagentOptions)
@@ -221,6 +224,8 @@ export async function startAgent({
         prompt: (text) => session.prompt(text),
         dispose: () => session.dispose(),
         sessionId,
+        agentDir: cwd,
+        origin: { kind: 'cron' as const, jobId: job.id, jobKind: 'prompt' as const },
         ...(snap.hasAnyPluginContent ? { hooks: snap.hooks } : {}),
         getTranscriptPath: () => sessionManager.getSessionFile(),
       }

package/src/secrets/env.ts

@@ -0,0 +1,43 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+
+// No-op when the file is missing or the key is absent: the caller has
+// already persisted to `secrets.json` and just wants `.env` to stop being a
+// second source of truth. Parsing matches `parseEnvKeys` in
+// `src/init/index.ts` — line-based, trim, skip blanks/comments, split on the
+// first `=`. Duplicate assignments to the same key are all removed because
+// dotenv resolves "last wins" so every duplicate carries the value we just
+// promoted.
+export function stripEnvKey(path: string, key: string): void {
+  let original: string
+  try {
+    original = readFileSync(path, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return
+    throw error
+  }
+
+  const next = removeKeyFromEnvText(original, key)
+  if (next === original) return
+  writeFileSync(path, next)
+}
+
+export function removeKeyFromEnvText(content: string, key: string): string {
+  const lines = content.split('\n')
+  const kept: string[] = []
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (trimmed === '' || trimmed.startsWith('#')) {
+      kept.push(line)
+      continue
+    }
+    const eq = trimmed.indexOf('=')
+    if (eq <= 0) {
+      kept.push(line)
+      continue
+    }
+    const lineKey = trimmed.slice(0, eq).trim()
+    if (lineKey === key) continue
+    kept.push(line)
+  }
+  return kept.join('\n')
+}

package/src/secrets/index.ts

@@ -11,3 +11,5 @@ export {
 } from './schema'
 
 export { createSecretsStoreForAgent, SecretsBackend } from './storage'
+
+export { stripEnvKey } from './env'

package/src/server/index.ts

@@ -6,6 +6,7 @@ import {
   type CreateSessionOptions,
   type CreateSessionResult,
 } from '@/agent'
+import { runPluginDoctorChecks, runPluginDoctorFix } from '@/agent/doctor'
 import type { SessionOrigin } from '@/agent/session-origin'
 import type { ChannelRouter } from '@/channels/router'
 import type { HookBus } from '@/plugin'
@@ -159,7 +160,7 @@ export function createServer({
 
           if (stream) {
             state.unsubPrompts = stream.subscribe({ target: { kind: 'session', sessionId: sessionFileId } }, (msg) =>
-              enqueuePrompt(ws, state, msg),
+              enqueuePrompt(ws, state, msg, agentDir),
             )
 
             state.unsubBroadcast = stream.subscribe({ target: { kind: 'broadcast' } }, (msg) => {
@@ -190,6 +191,16 @@ export function createServer({
             return
           }
 
+          if (msg.type === 'doctor') {
+            await handleDoctor(ws, msg.requestId, pluginRuntime, agentDir)
+            return
+          }
+
+          if (msg.type === 'doctor_fix') {
+            await handleDoctorFix(ws, msg.requestId, msg.checkId, pluginRuntime, agentDir)
+            return
+          }
+
           if (msg.type === 'abort') {
             if (!state) return
             await state.session.abort()
@@ -215,13 +226,27 @@ export function createServer({
               return
             }
             send(ws, { type: 'prompt_started', messageId: `local-${crypto.randomUUID()}`, text: msg.text })
+            const fallbackHooks = state.runtimeSnapshot?.hooks
+            if (fallbackHooks !== undefined && agentDir !== undefined) {
+              await fallbackHooks.runSessionTurnStart({
+                sessionId: state.sessionFileId,
+                agentDir,
+                origin: state.origin,
+              })
+            }
             try {
               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 fallbackHooks = state.runtimeSnapshot?.hooks
+            if (fallbackHooks !== undefined && agentDir !== undefined) {
+              await fallbackHooks.runSessionTurnEnd({
+                sessionId: state.sessionFileId,
+                agentDir,
+                origin: state.origin,
+              })
+            }
             if (fallbackHooks !== undefined) {
               await fallbackHooks.runSessionIdle({
                 sessionId: state.sessionFileId,
@@ -323,7 +348,7 @@ function forwardAssistantError(ws: Ws, message: unknown): void {
   send(ws, { type: 'error', message: text })
 }
 
-function enqueuePrompt(ws: Ws, state: SessionState, msg: StreamMessage): void {
+function enqueuePrompt(ws: Ws, state: SessionState, msg: StreamMessage, agentDir: string | undefined): 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'
@@ -339,7 +364,7 @@ function enqueuePrompt(ws: Ws, state: SessionState, msg: StreamMessage): void {
     ts: msg.ts,
   })
   pushQueueState(ws, state)
-  void drain(ws, state)
+  void drain(ws, state, agentDir)
 }
 
 // `session.idle` semantically means "the agent finished a prompt and is now
@@ -360,10 +385,26 @@ function makeIdleHookCaller(state: SessionState): () => Promise<void> {
   }
 }
 
-async function drain(ws: Ws, state: SessionState): Promise<void> {
+function makeTurnHookCallers(
+  state: SessionState,
+  agentDir: string | undefined,
+): { fireTurnStart: () => Promise<void>; fireTurnEnd: () => Promise<void> } {
+  const hooks: HookBus | undefined = state.runtimeSnapshot?.hooks
+  if (hooks === undefined || agentDir === undefined) {
+    return { fireTurnStart: async () => {}, fireTurnEnd: async () => {} }
+  }
+  const event = { sessionId: state.sessionFileId, agentDir, origin: state.origin }
+  return {
+    fireTurnStart: () => hooks.runSessionTurnStart(event),
+    fireTurnEnd: () => hooks.runSessionTurnEnd(event),
+  }
+}
+
+async function drain(ws: Ws, state: SessionState, agentDir: string | undefined): Promise<void> {
   if (state.draining) return
   state.draining = true
   const fireIdle = makeIdleHookCaller(state)
+  const { fireTurnStart, fireTurnEnd } = makeTurnHookCallers(state, agentDir)
   try {
     while (state.drainQueue.length > 0) {
       const item = state.drainQueue.shift()
@@ -371,12 +412,14 @@ async function drain(ws: Ws, state: SessionState): Promise<void> {
       pushQueueState(ws, state)
       send(ws, { type: 'prompt_started', messageId: item.streamMessageId, text: item.text })
 
+      await fireTurnStart()
       try {
         await state.session.prompt(item.text)
         send(ws, { type: 'done' })
       } catch (err) {
         send(ws, { type: 'error', message: err instanceof Error ? err.message : String(err) })
       }
+      await fireTurnEnd()
       await fireIdle()
     }
   } finally {
@@ -393,6 +436,61 @@ function pushQueueState(ws: Ws, state: SessionState): void {
   send(ws, { type: 'queue_state', pending })
 }
 
+async function handleDoctor(
+  ws: Ws,
+  requestId: string,
+  pluginRuntime: PluginRuntime | undefined,
+  agentDir: string | undefined,
+): Promise<void> {
+  if (pluginRuntime === undefined || agentDir === undefined) {
+    send(ws, { type: 'doctor_result', requestId, checks: [] })
+    return
+  }
+  const snapshot = pluginRuntime.get()
+  if (snapshot === undefined) {
+    send(ws, { type: 'doctor_result', requestId, checks: [] })
+    return
+  }
+  try {
+    const checks = await runPluginDoctorChecks({ registry: snapshot.registry, agentDir })
+    send(ws, { type: 'doctor_result', requestId, checks })
+  } catch (err) {
+    send(ws, { type: 'error', message: err instanceof Error ? err.message : String(err) })
+  }
+}
+
+async function handleDoctorFix(
+  ws: Ws,
+  requestId: string,
+  checkId: string,
+  pluginRuntime: PluginRuntime | undefined,
+  agentDir: string | undefined,
+): Promise<void> {
+  if (pluginRuntime === undefined || agentDir === undefined) {
+    send(ws, {
+      type: 'doctor_fix_result',
+      requestId,
+      result: { ok: false, checkId, error: 'plugin runtime not configured' },
+    })
+    return
+  }
+  const snapshot = pluginRuntime.get()
+  if (snapshot === undefined) {
+    send(ws, {
+      type: 'doctor_fix_result',
+      requestId,
+      result: { ok: false, checkId, error: 'plugin runtime not configured' },
+    })
+    return
+  }
+  const outcome = await runPluginDoctorFix({ registry: snapshot.registry, agentDir, checkId })
+  const result =
+    outcome.ok === true
+      ? { ok: true as const, checkId, summary: outcome.summary, changedPaths: outcome.changedPaths }
+      : { ok: false as const, checkId, error: outcome.error }
+  send(ws, { type: 'doctor_fix_result', requestId, result })
+}
+
 async function handleReload(
   ws: Ws,
   reloadAll: ReloadAllFn | undefined,

package/src/shared/index.ts

@@ -1,5 +1,8 @@
 export {
   type ClientMessage,
+  type DoctorCheckPayload,
+  type DoctorFixPayload,
+  type DoctorRequestId,
   type PromptDelivery,
   type QueueStateItem,
   type ReloadResultPayload,

package/src/shared/protocol.ts

@@ -4,11 +4,31 @@ export type ReloadResultPayload =
 
 export type PromptDelivery = 'queue' | 'steer' | 'interrupt'
 
+export type DoctorRequestId = string
+
+export type DoctorCheckPayload = {
+  id: string
+  pluginName: string
+  checkName: string
+  description: string
+  category: string
+  status: 'ok' | 'warning' | 'error'
+  message: string
+  details?: string[]
+  fix?: { description: string; hasApply: boolean }
+}
+
+export type DoctorFixPayload =
+  | { ok: true; checkId: string; summary: string; changedPaths: string[] }
+  | { ok: false; checkId: string; error: string }
+
 export type ClientMessage =
   | { type: 'prompt'; text: string; delivery?: PromptDelivery }
   | { type: 'reload'; scope?: string }
   | { type: 'abort' }
   | { type: 'queue_cancel'; messageId: string }
+  | { type: 'doctor'; requestId: DoctorRequestId }
+  | { type: 'doctor_fix'; requestId: DoctorRequestId; checkId: string }
 
 export type QueueStateItem = { id: string; text: string; ts: number }
 
@@ -23,3 +43,5 @@ export type ServerMessage =
   | { type: 'notification'; payload: unknown; replyTo?: string; meta?: Record<string, string> }
   | { type: 'queue_state'; pending: QueueStateItem[] }
   | { type: 'prompt_started'; messageId: string; text: string }
+  | { type: 'doctor_result'; requestId: DoctorRequestId; checks: DoctorCheckPayload[] }
+  | { type: 'doctor_fix_result'; requestId: DoctorRequestId; result: DoctorFixPayload }

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

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-channel-kakaotalk
-description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `kakaotalk`. KakaoTalk renders messages as plain text — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and other markdown all appear literally. There is no `@mention` syntax, no message threads, no replies-with-quote, and no file attachments. Read it before composing anything for KakaoTalk so you don't dump markdown into a chat window.
+description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `kakaotalk`, AND before calling `channel_fetch_attachment` against a KakaoTalk URL. KakaoTalk renders messages as plain text — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and other markdown all appear literally. There is no `@mention` syntax, no message threads, no replies-with-quote, and no outbound file attachments or stickers. Inbound photos / files / video / audio CAN be downloaded via `channel_fetch_attachment` (the placeholder text includes the URL); inbound stickers are metadata-only and cannot be fetched. URLs expire ~3 days after the message arrives. Read this skill before composing or fetching anything on KakaoTalk.
 ---
 
 # typeclaw-channel-kakaotalk
@@ -21,9 +21,9 @@ If you produce any of the following, KakaoTalk will render it literally and the
 - **Links with display text** — `[label](url)` becomes the literal string. Send the bare URL on its own; the KakaoTalk client will auto-link it.
 - **Mentions** — there is no `@user` syntax that the protocol surfaces. Address people by name in the message body.
 - **Threads / replies-with-quote** — every message is a top-level chat post. There is no per-message reply UI.
-- **Attachments** — the adapter is text-only. If the user asks you to send a file, say so and offer an alternative (paste a link, summarize the file, ship it via another channel).
+- **Outbound attachments / stickers** — agent-messenger's KakaoTalk SDK exposes no upload API. The adapter is outbound text-only. If the user asks you to send a file or sticker, say so and offer an alternative (paste a link, summarize the file, ship it via another channel).
 
-The adapter logs a warning the first time you try to send attachments and then drops them. The user-visible result is "your message arrived without the file."
+The adapter rejects outbound attachments via `ok: false` rather than partially sending the text — the agent contract is "ok=true means the whole request succeeded", so a silent drop would let you confidently report "I sent your file" when the file never arrived.
 
 ## What KakaoTalk DOES support
 
@@ -31,6 +31,29 @@ The adapter logs a warning the first time you try to send attachments and then d
 - URLs auto-linkify in the client. Send them bare — `https://example.com/foo`, no markdown wrapping.
 - Newlines render as line breaks. You can use `\n\n` to space paragraphs.
 
+## Inbound attachments and stickers
+
+Even though you cannot SEND attachments or stickers, you DO receive them. The adapter surfaces incoming non-text content by appending a `[KakaoTalk message with ...]` placeholder to the inbound text (same convention as Slack/Discord/Telegram). Examples of what you'll see:
+
+- A photo (with no caption): `[KakaoTalk message with photo 1320x2868 (image/jpeg) https://talk.kakaocdn.net/...]`
+- A photo with a caption: `look at this\n[KakaoTalk message with photo 1320x2868 (image/jpeg) https://...]`
+- A file: `[KakaoTalk message with file spec.pdf (application/pdf) size=12345 https://...]`
+- A video / audio (with a usable URL): `[KakaoTalk message with video (keys=[dur,url]) https://talk.kakaocdn.net/...]`. The SDK leaves video / audio / multiphoto payloads opaque, so we list the keys that were present alongside the URL when one exists; when no URL is present the placeholder is just `[KakaoTalk message with video keys=[...]]` and there is nothing for you to fetch.
+- A sticker / emoticon: `[KakaoTalk message with sticker (sticker) pack=4412724 path=4412724.emot_001.webp]`
+- An animated sticker: `[KakaoTalk message with sticker (sticker_ani) pack=... path=...]`
+
+### Fetching attachment bytes
+
+For photos, files, and any video / audio / multiphoto whose placeholder includes a `https://...kakaocdn.net/...` URL, call `channel_fetch_attachment` with that URL as the `ref` to download the bytes. The adapter validates the host (only `*.kakaocdn.net` is accepted — you cannot use this tool as a generic web fetcher) and returns the raw buffer plus mimetype.
+
+Use this when you actually need to look at the content — e.g. the user sends a screenshot and asks "what's in this?". The download lands in your inbox directory and you can pass it to a vision-capable inspection tool or read it directly depending on the file type.
+
+**Expiry caveat**: KakaoCDN URLs are pre-signed with an `expires=` timestamp baked into the query string — empirically ~3 days after the message arrived. Fetch promptly. If the URL has expired you will get a `403` error with the hint _"likely an expired pre-signed URL; ask the sender to re-share"_ — relay that to the user verbatim rather than guessing the cause.
+
+**Stickers cannot be fetched** as bytes through this tool. The sticker placeholder carries `pack=` and `path=` identifiers (KakaoTalk sticker pack metadata), not a downloadable URL. Treat stickers as descriptive metadata only — acknowledge them ("cute sticker") without trying to "see" them.
+
+If the inbound text is JUST a sticker (no accompanying text), the agent still gets a routed event — stickers count as engagement under `reply` and `dm` triggers (group chats with only sticker activity will not trigger `mention` because aliases require text matching).
+
 ## Message length & cadence
 
 KakaoTalk is mobile-first. The reading surface is small and the user is on their phone. Keep messages **short and conversational**, not essay-length. If you have a long answer:

package/src/skills/typeclaw-config/SKILL.md

@@ -403,7 +403,7 @@ RUN apt-get install ... <baseline + enabled toggle packages>   ← toggles fan o
 ENV NODE_ENV=production
 # Custom lines from typeclaw.json#dockerfile.append.   ← only emitted when append is non-empty
 <your appended lines>
-ENTRYPOINT ["bun", "run", "typeclaw"]
+ENTRYPOINT ["/usr/local/bin/typeclaw-entrypoint"]
 CMD ["run"]
 ```
 

package/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "target": "ES2025",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "moduleResolution": "bundler",
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    "lib": ["ESNext"],
+    "types": ["bun"],
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false,
+
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src", "scripts"]
+}