typeclaw 0.1.0

package/src/channels/schema.ts

@@ -0,0 +1,273 @@
+import { z } from 'zod'
+
+export const ADAPTER_IDS = ['discord-bot', 'kakaotalk', 'slack-bot', 'telegram-bot'] as const
+
+export type AdapterId = (typeof ADAPTER_IDS)[number]
+
+const allowRuleSchema = z.string().min(1).refine(isValidAllowRule, {
+  message:
+    'allow rule must be one of: *, guild:*, guild:<id>, guild:<id>/<channel>, team:*, team:<id>, team:<id>/<channel>, tg:*, tg:<chat_id>, channel:<id>, dm:*, dm:<id>, im:*, im:<id>, kakao:*, kakao:<chat>, kakao:dm/*, kakao:group/*, kakao:open/*',
+})
+
+const engagementTriggerSchema = z.enum(['mention', 'reply', 'dm'])
+
+const stickinessSchema = z.union([
+  z.literal('off'),
+  z.object({
+    perReply: z.object({
+      window: z
+        .number()
+        .int()
+        .min(1)
+        .max(24 * 60 * 60_000),
+    }),
+  }),
+])
+
+export const STICKY_DEFAULT_WINDOW_MS = 5 * 60 * 1000
+
+const engagementSchema = z
+  .object({
+    trigger: z.array(engagementTriggerSchema).default(['mention', 'reply', 'dm']),
+    stickiness: stickinessSchema.default({ perReply: { window: STICKY_DEFAULT_WINDOW_MS } }),
+  })
+  .default({
+    trigger: ['mention', 'reply', 'dm'],
+    stickiness: { perReply: { window: STICKY_DEFAULT_WINDOW_MS } },
+  })
+
+// Cold-start prefetch windows. The router seeds `contextBuffer` once when a
+// brand-new channel session is created (no persisted sessionId for the
+// (workspace, chat, thread) tuple). Set any field to 0 to disable that side
+// of the prefetch. Non-fatal: if the upstream history fetch fails (missing
+// scopes, network error, adapter doesn't expose history), the session still
+// starts and the agent can call `channel_history` on demand.
+//
+// Reload semantics: `channels` is `applied` in FIELD_EFFECTS, but prefetch
+// only fires at session creation, so changes here only affect the *next*
+// cold start; in-flight live sessions are unaffected.
+export const PREFETCH_DEFAULTS = {
+  thread: { head: 3, tail: 10 },
+  channel: { tail: 10 },
+} as const
+
+export function defaultHistoryConfig(): {
+  prefetch: { thread: { head: number; tail: number }; channel: { tail: number } }
+} {
+  return {
+    prefetch: {
+      thread: { head: PREFETCH_DEFAULTS.thread.head, tail: PREFETCH_DEFAULTS.thread.tail },
+      channel: { tail: PREFETCH_DEFAULTS.channel.tail },
+    },
+  }
+}
+
+const prefetchWindowSchema = z.number().int().min(0).max(200)
+
+const historySchema = z
+  .object({
+    prefetch: z
+      .object({
+        thread: z
+          .object({
+            head: prefetchWindowSchema.default(PREFETCH_DEFAULTS.thread.head),
+            tail: prefetchWindowSchema.default(PREFETCH_DEFAULTS.thread.tail),
+          })
+          .default({ head: PREFETCH_DEFAULTS.thread.head, tail: PREFETCH_DEFAULTS.thread.tail }),
+        channel: z
+          .object({
+            tail: prefetchWindowSchema.default(PREFETCH_DEFAULTS.channel.tail),
+          })
+          .default({ tail: PREFETCH_DEFAULTS.channel.tail }),
+      })
+      .default({
+        thread: { head: PREFETCH_DEFAULTS.thread.head, tail: PREFETCH_DEFAULTS.thread.tail },
+        channel: { tail: PREFETCH_DEFAULTS.channel.tail },
+      }),
+  })
+  .default({
+    prefetch: {
+      thread: { head: PREFETCH_DEFAULTS.thread.head, tail: PREFETCH_DEFAULTS.thread.tail },
+      channel: { tail: PREFETCH_DEFAULTS.channel.tail },
+    },
+  })
+
+const adapterSchema = z.object({
+  allow: z.array(allowRuleSchema).default([]),
+  engagement: engagementSchema,
+  history: historySchema,
+  enabled: z.boolean().default(true),
+})
+
+// KakaoTalk uses the same shape as every other adapter. There used to be an
+// `autoMarkRead` opt-in here; the adapter now fires a LOCO NOTIREAD ack on
+// every inbound MSG event unconditionally (see kakaotalk.ts) so the sender's
+// unread "1" (노란숫자) clears as soon as the agent observes the message.
+// Existing configs with `autoMarkRead: <bool>` continue to parse — Zod's
+// default `.object()` strips unknown keys silently — but the field has no
+// effect. Risk note: auto-acking every received message is a distinct
+// behavioral fingerprint vs a human, so KakaoTalk's abuse detection may
+// flag accounts that ack rapidly and unconditionally. Run typeclaw with the
+// kakaotalk adapter only on dedicated agent accounts you can afford to lose.
+export const channelsSchema = z
+  .object({
+    'discord-bot': adapterSchema.optional(),
+    kakaotalk: adapterSchema.optional(),
+    'slack-bot': adapterSchema.optional(),
+    'telegram-bot': adapterSchema.optional(),
+  })
+  .default({})
+
+export type AllowRule = string
+export type EngagementConfig = z.infer<typeof engagementSchema>
+export type ChannelAdapterConfig = z.infer<typeof adapterSchema>
+export type KakaotalkAdapterConfig = ChannelAdapterConfig
+export type ChannelsConfig = z.infer<typeof channelsSchema>
+
+// Discord IDs are numeric snowflakes; Slack IDs start with a single uppercase
+// letter (T for teams, C/D/G for channels) followed by alphanumerics; Telegram
+// chat IDs are signed integers (negative for groups, `-100…` for supergroups
+// and channels); KakaoTalk chat IDs are LOCO-protocol decimal integers
+// (large enough to need BigInt at the protocol layer, but rendered as plain
+// decimal strings here). All shapes are accepted on every adapter so the
+// allow list stays declarative — the runtime ensures only the right adapter
+// ever sees its own IDs.
+const RULE_PATTERNS = [
+  /^\*$/,
+  // Discord
+  /^guild:\*$/,
+  /^guild:[0-9]+$/,
+  /^guild:[0-9]+\/[0-9]+$/,
+  /^dm:\*$/,
+  /^dm:[0-9]+$/,
+  // Slack
+  /^team:\*$/,
+  /^team:[A-Z0-9]+$/,
+  /^team:[A-Z0-9]+\/[A-Z0-9]+$/,
+  /^im:\*$/,
+  /^im:[A-Z0-9]+$/,
+  // Telegram (`tg:*` admits all chats; `tg:<chat_id>` scopes to one chat —
+  // numeric, may be negative). There is no team/guild concept; every chat is
+  // identified by its absolute id.
+  /^tg:\*$/,
+  /^tg:-?[0-9]+$/,
+  // KakaoTalk: a single workspace per logged-in account, so the rules scope
+  // by chat-type (1:1 / group / open) rather than by workspace. `kakao:*`
+  // admits every chat the account can see; `kakao:dm/*`, `kakao:group/*`,
+  // `kakao:open/*` admit one chat-type bucket; `kakao:<chat-id>` admits a
+  // single chat. The runtime classifies each chat into a bucket based on
+  // KakaoChat.type at chat-resolver time and surfaces the bucket via the
+  // workspace coordinate.
+  /^kakao:\*$/,
+  /^kakao:dm\/\*$/,
+  /^kakao:group\/\*$/,
+  /^kakao:open\/\*$/,
+  /^kakao:[0-9]+$/,
+  // Shared (channel ids are unique on both platforms)
+  /^channel:[A-Z0-9]+$/,
+  /^channel:-?[0-9]+$/,
+]
+
+function isValidAllowRule(rule: string): boolean {
+  return RULE_PATTERNS.some((p) => p.test(rule))
+}
+
+export function isAllowed(rules: readonly AllowRule[], workspace: string, chat: string): boolean {
+  for (const rule of rules) {
+    if (matchRule(rule, workspace, chat)) return true
+  }
+  return false
+}
+
+// `*`              → every workspace channel + every DM (catch-all)
+// `guild:*`        → every Discord guild channel (no DMs)
+// `guild:G`        → every channel in guild G
+// `guild:G/C`      → channel C in guild G only
+// `team:*`         → every Slack team channel (no DMs)
+// `team:T`         → every channel in team T
+// `team:T/C`       → channel C in team T only
+// `tg:*`           → every Telegram chat (DMs, groups, supergroups, channels)
+// `tg:C`           → Telegram chat C only (signed numeric chat id)
+// `channel:C`      → channel C in any workspace (IDs are globally unique on
+//                    Discord/Slack and Telegram chat ids are also globally
+//                    unique numeric values)
+// `dm:*`           → every Discord DM
+// `dm:C`           → Discord DM channel C only
+// `im:*`           → every Slack DM (im channel)
+// `im:D`           → Slack DM channel D only
+// `kakao:*`            → every KakaoTalk chat the account is in
+// `kakao:dm/*`         → every KakaoTalk 1:1 chat
+// `kakao:group/*`      → every KakaoTalk group chat
+// `kakao:open/*`       → every KakaoTalk open chat
+// `kakao:<id>`         → KakaoTalk chat with the given numeric chat_id
+//
+// `guild:`/`dm:`, `team:`/`im:`, `tg:`, and `kakao:` identify which adapter
+// the rule was written for, but the matcher applies any rule that the
+// (workspace, chat) pair satisfies. That keeps the adapter-side coupling at
+// the schema/UX layer (Slack users write `team:`, Discord users write
+// `guild:`, Telegram users write `tg:`, KakaoTalk users write `kakao:`)
+// without bloating the matching logic. Telegram has no workspace concept;
+// the adapter pins workspace to `'telegram'` so `tg:*` only ever admits
+// Telegram chats. KakaoTalk uses `@kakao-dm` / `@kakao-group` / `@kakao-open`
+// as workspace coordinates so the bucket-* rules are pure prefix matches
+// against `workspace`.
+function matchRule(rule: string, workspace: string, chat: string): boolean {
+  // KakaoTalk workspaces accept the global `*` catch-all or any `kakao:`
+  // rule. Adapter-specific non-kakao rules (`team:*`, `guild:*`, `dm:*`,
+  // `im:*`, `tg:*`) never admit kakao workspaces — those are scoped to
+  // their own adapter's coordinate space and would be meaningless here.
+  // The init wizard still defaults kakaotalk to the narrower `kakao:dm/*`
+  // (group chats with personal accounts are sensitive — every member sees
+  // every reply), so opting into `*` is an explicit, per-adapter decision
+  // made in `channels.kakaotalk.allow`.
+  if (KAKAO_WORKSPACES.has(workspace)) {
+    if (rule === '*') return true
+    if (rule.startsWith('kakao:')) return matchKakaoRule(rule.slice(6), workspace, chat)
+    return false
+  }
+
+  if (rule === '*') return true
+  if (rule.startsWith('kakao:')) return false
+
+  if (workspace === '@dm') {
+    if (rule === 'dm:*' || rule === 'im:*') return true
+    if (rule.startsWith('dm:')) return rule.slice(3) === chat
+    if (rule.startsWith('im:')) return rule.slice(3) === chat
+    if (rule.startsWith('channel:')) return rule.slice(8) === chat
+    return false
+  }
+
+  if (workspace === 'telegram') {
+    if (rule === 'tg:*') return true
+    if (rule.startsWith('tg:')) return rule.slice(3) === chat
+    if (rule.startsWith('channel:')) return rule.slice(8) === chat
+    return false
+  }
+
+  if (rule === 'guild:*' || rule === 'team:*') return true
+  if (rule.startsWith('channel:')) return rule.slice(8) === chat
+  if (rule.startsWith('guild:')) {
+    const body = rule.slice(6)
+    const slash = body.indexOf('/')
+    if (slash === -1) return body === workspace
+    return body.slice(0, slash) === workspace && body.slice(slash + 1) === chat
+  }
+  if (rule.startsWith('team:')) {
+    const body = rule.slice(5)
+    const slash = body.indexOf('/')
+    if (slash === -1) return body === workspace
+    return body.slice(0, slash) === workspace && body.slice(slash + 1) === chat
+  }
+  return false
+}
+
+const KAKAO_WORKSPACES = new Set(['@kakao-dm', '@kakao-group', '@kakao-open'])
+
+function matchKakaoRule(body: string, workspace: string, chat: string): boolean {
+  if (!KAKAO_WORKSPACES.has(workspace)) return false
+  if (body === '*') return true
+  if (body === 'dm/*') return workspace === '@kakao-dm'
+  if (body === 'group/*') return workspace === '@kakao-group'
+  if (body === 'open/*') return workspace === '@kakao-open'
+  return body === chat
+}

package/src/channels/types.ts

@@ -0,0 +1,160 @@
+import type { AdapterId } from './schema'
+
+export type ChannelKey = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  thread: string | null
+}
+
+export type InboundMessage = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  thread: string | null
+  text: string
+  externalMessageId: string
+  authorId: string
+  authorName: string
+  // Set true when the inbound is from another bot (NOT this typeclaw
+  // instance's own bot identity — the adapter still drops self-authored
+  // messages with `reason: 'self_author'`). The router treats peer bots
+  // identically to humans for engagement, but uses this flag to drive a
+  // bounded loop guard so two or more bots cannot ping-pong forever.
+  authorIsBot: boolean
+  isBotMention: boolean
+  replyToBotMessageId: string | null
+  // True when the message contains at least one user mention AND none of
+  // those mentions resolve to the bot. Used by the engagement layer to
+  // suppress the solo-human fallback: if the human is explicitly tagging
+  // someone else, the message almost certainly is not addressed to us.
+  // False when the message has no mentions at all (the fallback still
+  // applies in that case) or when one of the mentions IS the bot (which
+  // is already handled by `isBotMention`). Adapters that cannot reliably
+  // enumerate mentions MUST default this to false rather than true.
+  mentionsOthers: boolean
+  // Set to the parent message id when the inbound is a reply AND the
+  // parent was authored by someone other than the bot (or by an unknown
+  // author the adapter could not attribute). Mirrors `replyToBotMessageId`
+  // but for the inverse case. Used by the engagement layer to suppress
+  // the solo-human fallback on Discord-style replies that are clearly
+  // directed at another user. Null when the message is not a reply, or
+  // when the parent is the bot's own message (already covered by
+  // `replyToBotMessageId`). Adapters that cannot determine the parent's
+  // author MUST leave this null rather than guessing.
+  replyToOtherMessageId: string | null
+  isDm: boolean
+  // Original platform-side timestamp in milliseconds since epoch. Sourced
+  // from Slack's `event.ts` or Discord's `event.timestamp` (via the
+  // adapter classifier), NOT the local time the router observed it. Zero
+  // means "unknown" — the formatter renders such lines without a
+  // timestamp prefix instead of stamping them with the wrong clock.
+  ts: number
+}
+
+// File on disk that the agent wants to attach to an outbound message. The
+// agent runs inside a container with /agent bind-mounted from the host;
+// `path` should be an absolute path the container can `readFile`. The
+// optional `filename` overrides the basename of `path` when uploading
+// (useful when the on-disk name carries a tempdir suffix the user
+// shouldn't see in the chat). Adapters that cannot upload files MUST
+// fail loudly via `SendResult.ok = false` rather than silently dropping
+// the attachment.
+export type OutboundAttachment = {
+  path: string
+  filename?: string
+}
+
+export type OutboundMessage = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  thread?: string | null
+  // Optional when `attachments` is non-empty (file-only post is allowed).
+  // Adapters that always need text (e.g. some webhook backends in the
+  // future) must validate this themselves.
+  text?: string
+  // Each attachment is uploaded once. Order is preserved. For Slack, the
+  // first attachment carries `text` as the file's `initial_comment` so
+  // both arrive in a single API call; subsequent attachments are uploaded
+  // bare. For Discord, attachments are uploaded first (no text) and then
+  // `text` is posted as a separate message — Discord's upstream
+  // `uploadFile` does not accept a content body or a thread id, see the
+  // adapter for the workaround details.
+  attachments?: OutboundAttachment[]
+}
+
+export type SendResult = { ok: true } | { ok: false; error: string }
+
+export type OutboundCallback = (msg: OutboundMessage) => Promise<SendResult>
+
+export type TypingTarget = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  thread?: string | null
+  // 'tick' is the heartbeat fired during debouncing/generation; adapters
+  // should set the indicator visible. 'stop' is fired exactly once when the
+  // router decides the turn is over (drain finally, /stop command, or
+  // teardown); adapters should explicitly clear the indicator if their
+  // platform doesn't auto-expire it. Without 'stop', a 'tick' that lands
+  // after the agent's final reply but before the drain returns will leave
+  // the indicator on for Slack's full 2-minute server timeout.
+  phase: 'tick' | 'stop'
+}
+
+export type TypingCallback = (target: TypingTarget) => Promise<void>
+
+export type ResolvedChannelNames = {
+  chatName?: string
+  workspaceName?: string
+}
+
+export type ChannelNameResolver = (key: ChannelKey) => Promise<ResolvedChannelNames>
+
+// History entries are intentionally distinct from InboundMessage:
+// `InboundMessage` carries router-classification fields (`isBotMention`,
+// `isDm`) that are turn-delivery concerns, not history concerns. History
+// entries instead need `isBot` so the agent can tell its own past replies
+// from user messages, and a sortable `ts` for chronological rendering.
+export type ChannelHistoryMessage = {
+  externalMessageId: string
+  authorId: string
+  authorName: string
+  text: string
+  ts: number
+  isBot: boolean
+  replyToBotMessageId: string | null
+}
+
+export type FetchHistoryArgs = {
+  chat: string
+  thread: string | null
+  limit: number
+  cursor?: string
+}
+
+export type FetchHistoryResult =
+  | { ok: true; messages: ChannelHistoryMessage[]; nextCursor?: string }
+  | { ok: false; error: string }
+
+// Registered per-adapter on the ChannelRouter alongside outbound/typing
+// callbacks. Adapters that cannot fetch history (e.g. webhook-only future
+// adapters) simply do not register one; the router answers
+// 'history-not-supported' for those.
+export type HistoryCallback = (args: FetchHistoryArgs) => Promise<FetchHistoryResult>
+
+export type FetchAttachmentArgs = {
+  ref: string
+  filename?: string
+}
+
+export type FetchAttachmentResult =
+  | { ok: true; buffer: Buffer; filename: string; mimetype?: string; size: number }
+  | { ok: false; error: string }
+
+export type FetchAttachmentCallback = (args: FetchAttachmentArgs) => Promise<FetchAttachmentResult>
+
+export function channelKeyId(key: ChannelKey): string {
+  return `${key.adapter}:${key.workspace}:${key.chat}:${key.thread ?? ''}`
+}