typeclaw 0.1.0

package/src/channels/membership-from-history.ts

@@ -0,0 +1,53 @@
+import { type MembershipResolverResult } from './membership'
+import type { ChannelHistoryMessage, FetchHistoryResult } from './types'
+
+// History-derived membership counts only the authors visible in the most
+// recent N history messages — explicitly NOT a full guild/workspace
+// membership snapshot. We mark `truncated: true` so the engagement layer
+// (`resolveEffectiveHumans`) treats it as a quieting hint rather than
+// ground truth and `Math.max`-folds it with persisted speakers.
+//
+// Used as a fallback when the platform's authoritative membership
+// endpoint is unavailable (Discord 403 from missing GUILD_MEMBERS
+// privileged intent, Slack `missing_scope` / `not_in_channel`, or any
+// future adapter that lacks an enumeration capability), and as the
+// preferred answer when the authoritative endpoint says "too many to
+// enumerate" — a 1000-member guild's "5 active speakers" is more useful
+// for engagement than "1000 members minus self".
+//
+// Returns a `transient` failure when history fetch itself fails, so the
+// cache retries soon. Returns a count of zero humans/bots (rather than a
+// failure) when history is empty — a brand-new channel is a legitimate
+// state, not an error.
+export const HISTORY_LOOKBACK_LIMIT = 100
+
+export type DeriveMembershipDeps = {
+  fetchHistory: (limit: number) => Promise<FetchHistoryResult>
+  now: () => number
+}
+
+export async function deriveMembershipFromHistory(deps: DeriveMembershipDeps): Promise<MembershipResolverResult> {
+  const result = await deps.fetchHistory(HISTORY_LOOKBACK_LIMIT)
+  if (!result.ok) return { kind: 'transient' }
+  return countAuthors(result.messages, deps.now())
+}
+
+export function countAuthors(messages: readonly ChannelHistoryMessage[], fetchedAt: number): MembershipResolverResult {
+  // Dedupe by author id; once we've classified an author as bot or human
+  // (via the adapter's `isBot` flag), keep that classification stable
+  // even if a later message disagrees. The first occurrence wins for
+  // determinism — Discord's `author.bot` and Slack's `subtype === 'bot_message'`
+  // are stable for a given user, so disagreement would indicate a data
+  // glitch we don't want to swing the count on.
+  const seen = new Map<string, boolean>()
+  for (const m of messages) {
+    if (!seen.has(m.authorId)) seen.set(m.authorId, m.isBot)
+  }
+  let humans = 0
+  let bots = 0
+  for (const isBot of seen.values()) {
+    if (isBot) bots++
+    else humans++
+  }
+  return { humans, bots, fetchedAt, truncated: true }
+}

package/src/channels/membership.ts

@@ -0,0 +1,30 @@
+import type { ChannelKey } from './types'
+
+export const MEMBERSHIP_ENUMERATION_CAP = 50
+// Engagement decisions read this every inbound but tolerate moderate
+// staleness — the count rarely changes between turns. The router
+// invalidates the cache when a previously-unseen author posts (see
+// router.ts), so the only practical sources of staleness this TTL
+// governs are: (1) silent leavers we don't notice until next refetch,
+// (2) lurkers with permission overwrites who never speak. Both are
+// quieting hints at most. 30min matches the upper bound of "session
+// idle" so the cache typically expires around the same time the
+// LiveSession would be GC'd anyway.
+export const MEMBERSHIP_CACHE_TTL_MS = 30 * 60 * 1000
+export const MEMBERSHIP_CACHE_PERMANENT_TTL_MS = 5 * 60 * 1000
+export const MEMBERSHIP_CACHE_TRANSIENT_TTL_MS = 30_000
+export const MEMBERSHIP_FRESHNESS_MS = 60_000
+export const MEMBERSHIP_COLD_FETCH_TIMEOUT_MS = 1500
+
+export type MembershipCount = {
+  humans: number
+  bots: number
+  fetchedAt: number
+  truncated: boolean
+}
+
+export type MembershipResolverFailure = { kind: 'transient' } | { kind: 'permanent' }
+
+export type MembershipResolverResult = MembershipCount | MembershipResolverFailure
+
+export type MembershipResolver = (key: ChannelKey) => Promise<MembershipResolverResult>

package/src/channels/participants.ts

@@ -0,0 +1,47 @@
+import type { ChannelParticipant } from '@/agent/session-origin'
+
+export const PARTICIPANTS_MAX_PERSISTED = 50
+export const PARTICIPANTS_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
+
+export function updateParticipants(
+  current: readonly ChannelParticipant[],
+  authorId: string,
+  authorName: string,
+  now: number,
+  isBot: boolean = false,
+): ChannelParticipant[] {
+  const map = new Map<string, ChannelParticipant>()
+  for (const p of current) map.set(p.authorId, p)
+
+  const existing = map.get(authorId)
+  if (existing) {
+    // Once an author is flagged as a bot, keep that flag sticky. A peer bot
+    // briefly behaving like a human (e.g. an admin posting via the bot's
+    // webhook from a DM) shouldn't reset the classification — engagement
+    // semantics rely on this being stable across a participant's lifetime.
+    map.set(authorId, {
+      ...existing,
+      authorName,
+      lastMessageAt: now,
+      messageCount: existing.messageCount + 1,
+      isBot: existing.isBot === true || isBot,
+    })
+  } else {
+    map.set(authorId, {
+      authorId,
+      authorName,
+      firstMessageAt: now,
+      lastMessageAt: now,
+      messageCount: 1,
+      isBot,
+    })
+  }
+
+  const cutoff = now - PARTICIPANTS_MAX_AGE_MS
+  const fresh = Array.from(map.values()).filter((p) => p.lastMessageAt >= cutoff)
+
+  if (fresh.length <= PARTICIPANTS_MAX_PERSISTED) return fresh
+
+  fresh.sort((a, b) => b.lastMessageAt - a.lastMessageAt)
+  return fresh.slice(0, PARTICIPANTS_MAX_PERSISTED)
+}

package/src/channels/persistence.ts

@@ -0,0 +1,209 @@
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+import type { ChannelParticipant } from '@/agent/session-origin'
+
+import type { AdapterId } from './schema'
+import type { ChannelKey } from './types'
+
+const FILE_VERSION = 3
+
+// `sessionFile` is the basename (not the full path) of the JSONL transcript
+// for this (adapter, workspace, chat, thread) tuple. pi-coding-agent writes
+// session files as `${ISO_TIMESTAMP}_${UUID}.jsonl`, where the UUID matches
+// `sessionId` but the timestamp prefix only exists at write time. Without
+// the basename persisted, reopen attempts can only guess the path from the
+// UUID, which never matches on disk — every restart silently creates a
+// fresh session and the channel loses its transcript memory.
+//
+// `sessionFile` is optional because v2 records (pre-fix) only carried the
+// UUID. Those are migrated in-place at load time by globbing the sessions
+// directory for `*_${sessionId}.jsonl`; if no match is found the file is
+// considered lost and reopen will fall back to a fresh session.
+export type ChannelSessionRecord = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  thread: string | null
+  sessionId: string
+  sessionFile?: string
+  participants: ChannelParticipant[]
+}
+
+type FileV3 = {
+  version: 3
+  sessions: ChannelSessionRecord[]
+}
+
+type FileV2 = {
+  version: 2
+  sessions: Array<Omit<ChannelSessionRecord, 'sessionFile'>>
+}
+
+export type ChannelSessionsLogger = {
+  warn: (msg: string) => void
+  error: (msg: string) => void
+}
+
+const consoleLogger: ChannelSessionsLogger = {
+  warn: (m) => console.warn(m),
+  error: (m) => console.error(m),
+}
+
+export function channelsSessionsPath(agentDir: string): string {
+  return join(agentDir, 'channels', 'sessions.json')
+}
+
+function sessionsDirOf(agentDir: string): string {
+  return join(agentDir, 'sessions')
+}
+
+export async function loadChannelSessions(
+  agentDir: string,
+  logger: ChannelSessionsLogger = consoleLogger,
+): Promise<ChannelSessionRecord[]> {
+  const path = channelsSessionsPath(agentDir)
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch {
+    return []
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (err) {
+    logger.error(`[channels] ${path} corrupted: ${describe(err)}; starting fresh`)
+    return []
+  }
+  if (!isObject(parsed)) {
+    logger.warn(`[channels] ${path} not an object; ignored`)
+    return []
+  }
+  const version = (parsed as { version?: unknown }).version
+  if (version === FILE_VERSION) {
+    const file = parsed as FileV3
+    if (!Array.isArray(file.sessions)) return []
+    return file.sessions.filter(isValidRecord)
+  }
+  if (version === 2) {
+    const file = parsed as FileV2
+    if (!Array.isArray(file.sessions)) return []
+    const v2Records = file.sessions.filter(isValidV2Record)
+    return await migrateV2Records(agentDir, v2Records, logger)
+  }
+  logger.warn(`[channels] ${path} version ${String(version)} not supported (expected 2 or ${FILE_VERSION}); ignored`)
+  return []
+}
+
+export async function saveChannelSessions(
+  agentDir: string,
+  sessions: readonly ChannelSessionRecord[],
+  logger: ChannelSessionsLogger = consoleLogger,
+): Promise<void> {
+  const path = channelsSessionsPath(agentDir)
+  const payload: FileV3 = { version: FILE_VERSION, sessions: dedupe(sessions) }
+  try {
+    await mkdir(dirname(path), { recursive: true })
+    const tmp = `${path}.tmp`
+    await writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`, 'utf8')
+    const { rename } = await import('node:fs/promises')
+    await rename(tmp, path)
+  } catch (err) {
+    logger.error(`[channels] failed to persist sessions: ${describe(err)}`)
+  }
+}
+
+// One-shot migration from v2 (sessionId only) to v3 (sessionId + sessionFile).
+// pi-coding-agent writes session files as `${ISO_TIMESTAMP}_${UUID}.jsonl`,
+// so we look for any file ending in `_${sessionId}.jsonl`. If a directory
+// scan fails we leave sessionFile undefined; the next reopen attempt will
+// fall back to a fresh session (the same broken behavior v2 had — but at
+// least the next successful create will populate sessionFile correctly and
+// we'll be migrated forward.)
+async function migrateV2Records(
+  agentDir: string,
+  v2Records: readonly Omit<ChannelSessionRecord, 'sessionFile'>[],
+  logger: ChannelSessionsLogger,
+): Promise<ChannelSessionRecord[]> {
+  if (v2Records.length === 0) return []
+  const sessionsDir = sessionsDirOf(agentDir)
+  let entries: string[]
+  try {
+    entries = await readdir(sessionsDir)
+  } catch {
+    logger.warn(`[channels] could not scan ${sessionsDir} for v2→v3 migration; sessionFile left empty`)
+    return v2Records.map((r) => ({ ...r }))
+  }
+  // pi-coding-agent writes files as `${ISO_TIMESTAMP}_${UUID}.jsonl` where
+  // the ISO timestamp uses `-` (no `_`) and the UUID may contain `-`. Split
+  // on the FIRST underscore so the trailing portion is the full UUID even
+  // when the UUID contains hyphens.
+  const bySessionIdSuffix = new Map<string, string>()
+  for (const entry of entries) {
+    if (!entry.endsWith('.jsonl')) continue
+    const underscore = entry.indexOf('_')
+    if (underscore < 0) continue
+    const trailing = entry.slice(underscore + 1, -'.jsonl'.length)
+    bySessionIdSuffix.set(trailing, entry)
+  }
+  return v2Records.map((r) => {
+    const matched = bySessionIdSuffix.get(r.sessionId)
+    if (matched === undefined) {
+      logger.warn(
+        `[channels] v2→v3: no session file matching *_${r.sessionId}.jsonl in ${sessionsDir}; ` +
+          `sessionFile left empty (next inbound will create a fresh session for ${r.adapter}:${r.chat}:${r.thread ?? ''})`,
+      )
+      return { ...r }
+    }
+    return { ...r, sessionFile: matched }
+  })
+}
+
+function dedupe(sessions: readonly ChannelSessionRecord[]): ChannelSessionRecord[] {
+  const seen = new Map<string, ChannelSessionRecord>()
+  for (const s of sessions) {
+    seen.set(`${s.adapter}:${s.workspace}:${s.chat}:${s.thread ?? ''}`, s)
+  }
+  return Array.from(seen.values())
+}
+
+export function findRecord(
+  sessions: readonly ChannelSessionRecord[],
+  key: ChannelKey,
+): ChannelSessionRecord | undefined {
+  return sessions.find(
+    (s) =>
+      s.adapter === key.adapter &&
+      s.workspace === key.workspace &&
+      s.chat === key.chat &&
+      (s.thread ?? null) === (key.thread ?? null),
+  )
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v)
+}
+
+function isValidV2Record(v: unknown): v is Omit<ChannelSessionRecord, 'sessionFile'> {
+  if (!isObject(v)) return false
+  const r = v as Record<string, unknown>
+  return (
+    typeof r.adapter === 'string' &&
+    typeof r.workspace === 'string' &&
+    typeof r.chat === 'string' &&
+    (r.thread === null || typeof r.thread === 'string') &&
+    typeof r.sessionId === 'string' &&
+    Array.isArray(r.participants)
+  )
+}
+
+function isValidRecord(v: unknown): v is ChannelSessionRecord {
+  if (!isValidV2Record(v)) return false
+  const r = v as Record<string, unknown>
+  return r.sessionFile === undefined || typeof r.sessionFile === 'string'
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}

package/src/channels/reloadable.ts

@@ -0,0 +1,28 @@
+import type { Reloadable, ReloadResult } from '@/reload'
+
+import type { ChannelManager } from './manager'
+
+export type CreateChannelsReloadableOptions = {
+  manager: ChannelManager
+}
+
+export function createChannelsReloadable({ manager }: CreateChannelsReloadableOptions): Reloadable {
+  return {
+    scope: 'channels',
+    description: 'channels adapters and live config',
+    reload: async (): Promise<ReloadResult> => {
+      try {
+        const diff = await manager.reload()
+        const parts: string[] = []
+        if (diff.started.length > 0) parts.push(`${diff.started.length} started`)
+        if (diff.stopped.length > 0) parts.push(`${diff.stopped.length} stopped`)
+        if (diff.restartRequired.length > 0) parts.push(`${diff.restartRequired.length} restart-required`)
+        const summary = parts.length === 0 ? 'no adapter changes' : parts.join(', ')
+        return { scope: 'channels', ok: true, summary, details: diff }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err)
+        return { scope: 'channels', ok: false, reason: message }
+      }
+    },
+  }
+}