typeclaw 0.1.0

package/src/markdown/chunk.ts

@@ -0,0 +1,299 @@
+// Splits a Markdown document into chunks of bounded length while preserving
+// the integrity of structural blocks that would render incorrectly if cut
+// in the middle: code fences, tables, and (best-effort) blockquotes. The
+// algorithm is intentionally a line-walker rather than a full Markdown
+// parser — round-tripping through an AST normalizes whitespace and list
+// markers, which would change the user-visible text and break byte-for-byte
+// fidelity.
+//
+// Atomicity rules:
+//   - Code fence (``` or ~~~): one atomic block. If a single fence exceeds
+//     `maxLen`, it splits with the fence reopened on the next chunk so each
+//     half is independently parseable.
+//   - Pipe table (|---| separator on second line): one atomic block. If a
+//     single table exceeds `maxLen`, it is emitted whole as one oversize
+//     chunk — splitting a table is worse than downstream rejecting one
+//     oversize message.
+//   - Blockquote: one atomic block. Partial blockquotes look visually wrong
+//     even when syntactically fine.
+//   - Lists: packed as one block but splittable BETWEEN items if a single
+//     list exceeds `maxLen`.
+//   - Plain paragraphs: split on `\n\n` → `\n` → sentence → hard cut.
+
+const FENCE_RE = /^(\s*)(```+|~~~+)(.*)$/
+const TABLE_SEP_RE = /^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|?\s*$/
+const BLOCKQUOTE_RE = /^\s{0,3}>\s?/
+const LIST_ITEM_RE = /^\s{0,3}(?:[-*+]|\d+[.)])\s+/
+const FENCE_OVERHEAD_NEWLINES = 2
+
+type Block = { kind: 'atomic' | 'list' | 'prose'; text: string }
+
+export function chunkMarkdown(text: string, maxLen: number): string[] {
+  if (!Number.isFinite(maxLen) || maxLen <= 0) {
+    throw new Error(`chunkMarkdown: maxLen must be a positive finite number, got ${maxLen}`)
+  }
+  if (text === '') return ['']
+  if (text.length <= maxLen) return [text]
+
+  const blocks = tokenize(text)
+  return packBlocks(blocks, maxLen)
+}
+
+function tokenize(text: string): Block[] {
+  const lines = text.split('\n')
+  const blocks: Block[] = []
+  let i = 0
+
+  while (i < lines.length) {
+    const line = lines[i]!
+
+    // Close fence must use the same character (` vs ~) and be at least as
+    // long as the opener; shorter closes are not closes per CommonMark.
+    const fenceOpen = FENCE_RE.exec(line)
+    if (fenceOpen !== undefined && fenceOpen !== null) {
+      const fenceChar = fenceOpen[2]![0]!
+      const fenceLen = fenceOpen[2]!.length
+      const start = i
+      i++
+      while (i < lines.length) {
+        const close = FENCE_RE.exec(lines[i]!)
+        if (close && close[2]![0] === fenceChar && close[2]!.length >= fenceLen) {
+          i++
+          break
+        }
+        i++
+      }
+      blocks.push({ kind: 'atomic', text: lines.slice(start, i).join('\n') })
+      continue
+    }
+
+    // We require the alignment row on line N+1 to disambiguate from prose
+    // paragraphs that happen to contain a leading `|`.
+    if (line.includes('|') && i + 1 < lines.length && TABLE_SEP_RE.test(lines[i + 1]!)) {
+      const start = i
+      i += 2
+      while (i < lines.length && lines[i]!.includes('|') && lines[i]!.trim() !== '') {
+        i++
+      }
+      blocks.push({ kind: 'atomic', text: lines.slice(start, i).join('\n') })
+      continue
+    }
+
+    if (BLOCKQUOTE_RE.test(line)) {
+      const start = i
+      while (i < lines.length && (BLOCKQUOTE_RE.test(lines[i]!) || lines[i]!.trim() === '')) {
+        // A blank line followed by a non-blockquote line ends the quote.
+        if (lines[i]!.trim() === '' && (i + 1 >= lines.length || !BLOCKQUOTE_RE.test(lines[i + 1]!))) {
+          break
+        }
+        i++
+      }
+      blocks.push({ kind: 'atomic', text: lines.slice(start, i).join('\n') })
+      continue
+    }
+
+    if (LIST_ITEM_RE.test(line)) {
+      const start = i
+      while (i < lines.length) {
+        const cur = lines[i]!
+        if (LIST_ITEM_RE.test(cur)) {
+          i++
+          continue
+        }
+        // Allow a single blank line inside a list (loose list); double blank ends.
+        if (cur.trim() === '') {
+          if (i + 1 < lines.length && LIST_ITEM_RE.test(lines[i + 1]!)) {
+            i++
+            continue
+          }
+          break
+        }
+        if (/^\s{2,}/.test(cur)) {
+          i++
+          continue
+        }
+        break
+      }
+      blocks.push({ kind: 'list', text: lines.slice(start, i).join('\n') })
+      continue
+    }
+
+    const start = i
+    while (i < lines.length && lines[i]!.trim() !== '') {
+      i++
+    }
+    blocks.push({ kind: 'prose', text: lines.slice(start, i).join('\n') })
+    while (i < lines.length && lines[i]!.trim() === '') {
+      i++
+    }
+  }
+
+  return blocks.filter((b) => b.text !== '')
+}
+
+function packBlocks(blocks: Block[], maxLen: number): string[] {
+  const chunks: string[] = []
+  let current = ''
+
+  const flush = () => {
+    if (current !== '') {
+      chunks.push(current.replace(/\n+$/, ''))
+      current = ''
+    }
+  }
+
+  for (const block of blocks) {
+    const sep = current === '' ? '' : '\n\n'
+    const candidateLen = current.length + sep.length + block.text.length
+
+    if (candidateLen <= maxLen) {
+      current += sep + block.text
+      continue
+    }
+
+    flush()
+
+    if (block.text.length <= maxLen) {
+      current = block.text
+      continue
+    }
+
+    const split = splitOversize(block, maxLen)
+    for (let i = 0; i < split.length - 1; i++) {
+      chunks.push(split[i]!)
+    }
+    current = split[split.length - 1] ?? ''
+  }
+
+  flush()
+  return chunks.length === 0 ? [''] : chunks
+}
+
+function splitOversize(block: Block, maxLen: number): string[] {
+  if (block.kind === 'atomic') {
+    return splitOversizeAtomic(block.text, maxLen)
+  }
+  if (block.kind === 'list') {
+    return splitList(block.text, maxLen)
+  }
+  return splitProse(block.text, maxLen)
+}
+
+function splitOversizeAtomic(text: string, maxLen: number): string[] {
+  // Fence splitting: re-emit the language tag on each chunk so syntax
+  // highlighting survives the split.
+  const openMatch = FENCE_RE.exec(text.split('\n')[0] ?? '')
+  if (openMatch !== undefined && openMatch !== null) {
+    const fenceMarker = openMatch[2]!
+    const lang = openMatch[3] ?? ''
+    const open = `${fenceMarker}${lang}`
+    const close = fenceMarker
+
+    const lines = text.split('\n')
+    const innerStart = 1
+    let innerEnd = lines.length
+    if (innerEnd > innerStart) {
+      const lastLine = lines[innerEnd - 1]!
+      const lastClose = FENCE_RE.exec(lastLine)
+      if (
+        lastClose !== undefined &&
+        lastClose !== null &&
+        lastClose[2]![0] === fenceMarker[0] &&
+        lastClose[2]!.length >= fenceMarker.length
+      ) {
+        innerEnd--
+      }
+    }
+    const inner = lines.slice(innerStart, innerEnd).join('\n')
+    const overhead = open.length + close.length + FENCE_OVERHEAD_NEWLINES
+    if (overhead >= maxLen) {
+      return [text]
+    }
+    const innerBudget = maxLen - overhead
+    const innerChunks = splitProse(inner, innerBudget)
+    return innerChunks.map((c) => `${open}\n${c}\n${close}`)
+  }
+
+  // Tables and other atomic blocks: keep whole, accept oversize.
+  return [text]
+}
+
+function splitList(text: string, maxLen: number): string[] {
+  const lines = text.split('\n')
+  const items: string[] = []
+  let current: string[] = []
+  for (const line of lines) {
+    if (LIST_ITEM_RE.test(line) && current.length > 0) {
+      items.push(current.join('\n'))
+      current = []
+    }
+    current.push(line)
+  }
+  if (current.length > 0) items.push(current.join('\n'))
+
+  const chunks: string[] = []
+  let buffer = ''
+  for (const item of items) {
+    const sep = buffer === '' ? '' : '\n'
+    const candidateLen = buffer.length + sep.length + item.length
+    if (candidateLen <= maxLen) {
+      buffer += sep + item
+      continue
+    }
+    if (buffer !== '') chunks.push(buffer)
+    if (item.length <= maxLen) {
+      buffer = item
+    } else {
+      const proseChunks = splitProse(item, maxLen)
+      for (let i = 0; i < proseChunks.length - 1; i++) {
+        chunks.push(proseChunks[i]!)
+      }
+      buffer = proseChunks[proseChunks.length - 1] ?? ''
+    }
+  }
+  if (buffer !== '') chunks.push(buffer)
+  return chunks
+}
+
+function splitProse(text: string, maxLen: number): string[] {
+  if (text.length <= maxLen) return [text]
+
+  // Splitter array uses capturing groups so separators stay in the output
+  // and we can rejoin without losing whitespace structure.
+  const splitters: Array<(s: string) => string[]> = [
+    (s) => s.split(/(\n\n+)/),
+    (s) => s.split(/(\n)/),
+    (s) => s.split(/(?<=[.!?])\s+/),
+  ]
+
+  for (const splitter of splitters) {
+    const pieces = splitter(text)
+    const merged = mergeWithBudget(pieces, maxLen)
+    if (merged !== null) return merged
+  }
+
+  // Hard cut last resort: only fires when a single unbroken token exceeds maxLen.
+  const out: string[] = []
+  for (let i = 0; i < text.length; i += maxLen) {
+    out.push(text.slice(i, i + maxLen))
+  }
+  return out
+}
+
+function mergeWithBudget(pieces: string[], maxLen: number): string[] | null {
+  for (const p of pieces) {
+    if (p.length > maxLen) return null
+  }
+  const chunks: string[] = []
+  let buffer = ''
+  for (const piece of pieces) {
+    if (buffer.length + piece.length <= maxLen) {
+      buffer += piece
+      continue
+    }
+    if (buffer !== '') chunks.push(buffer)
+    buffer = piece
+  }
+  if (buffer !== '') chunks.push(buffer)
+  return chunks.map((c) => c.replace(/^\n+|\n+$/g, '')).filter((c) => c !== '')
+}

package/src/markdown/index.ts

@@ -0,0 +1 @@
+export { chunkMarkdown } from './chunk'

package/src/plugin/context.ts

@@ -0,0 +1,40 @@
+import type { PluginContext, PluginLogger } from './types'
+
+export type SpawnSubagentFn = (name: string, payload?: unknown) => Promise<void>
+
+export type CreatePluginContextOptions<TConfig> = {
+  name: string
+  version: string | undefined
+  agentDir: string
+  config: TConfig
+  logger: PluginLogger
+  spawnSubagent: SpawnSubagentFn
+  isBooted: () => boolean
+}
+
+export function createPluginContext<TConfig>(opts: CreatePluginContextOptions<TConfig>): PluginContext<TConfig> {
+  return Object.freeze({
+    name: opts.name,
+    version: opts.version,
+    agentDir: opts.agentDir,
+    config: opts.config,
+    logger: opts.logger,
+    spawnSubagent: async (name: string, payload?: unknown) => {
+      if (!opts.isBooted()) {
+        throw new Error(
+          `plugin ${opts.name}: spawnSubagent("${name}") called before boot completed; subagent registry is not yet wired`,
+        )
+      }
+      await opts.spawnSubagent(name, payload)
+    },
+  })
+}
+
+export function createPluginLogger(name: string): PluginLogger {
+  const prefix = `[plugin:${name}]`
+  return {
+    info: (m) => console.log(`${prefix} ${m}`),
+    warn: (m) => console.warn(`${prefix} ${m}`),
+    error: (m) => console.error(`${prefix} ${m}`),
+  }
+}

package/src/plugin/define.ts

@@ -0,0 +1,35 @@
+import type { z } from 'zod'
+
+import type { BuiltinToolRef, DefinedPlugin, PluginContext, PluginExports, Subagent, Tool } from './types'
+
+type DefinePluginSpec<S extends z.ZodType<unknown> | undefined> =
+  S extends z.ZodType<infer T>
+    ? {
+        configSchema: S
+        plugin: (ctx: PluginContext<T>) => Promise<PluginExports>
+      }
+    : {
+        plugin: (ctx: PluginContext<unknown>) => Promise<PluginExports>
+      }
+
+export function definePlugin<S extends z.ZodType<unknown> | undefined = undefined>(
+  spec: DefinePluginSpec<S>,
+): DefinedPlugin<S extends z.ZodType<infer T> ? T : unknown> {
+  return spec as DefinedPlugin<S extends z.ZodType<infer T> ? T : unknown>
+}
+
+export function defineTool<P>(tool: Tool<P>): Tool<P> {
+  return tool
+}
+
+export function defineSubagent<P>(subagent: Subagent<P>): Subagent<P> {
+  return subagent
+}
+
+export const readTool: BuiltinToolRef = { __builtinTool: 'read' }
+export const bashTool: BuiltinToolRef = { __builtinTool: 'bash' }
+export const editTool: BuiltinToolRef = { __builtinTool: 'edit' }
+export const writeTool: BuiltinToolRef = { __builtinTool: 'write' }
+export const grepTool: BuiltinToolRef = { __builtinTool: 'grep' }
+export const findTool: BuiltinToolRef = { __builtinTool: 'find' }
+export const lsTool: BuiltinToolRef = { __builtinTool: 'ls' }

package/src/plugin/hooks.ts

@@ -0,0 +1,204 @@
+import type {
+  HookContext,
+  Hooks,
+  PluginLogger,
+  SessionEndEvent,
+  SessionIdleEvent,
+  SessionPromptEvent,
+  SessionStartEvent,
+  ToolAfterEvent,
+  ToolBeforeEvent,
+  ToolBeforeResult,
+} from './types'
+
+// Per-handler ceiling for session.idle. The channels-side router wraps the
+// whole chain at SESSION_IDLE_TIMEOUT_MS = 30s; this inner bound fires
+// first so the offending plugin gets named in the logs instead of the
+// chain-level timeout swallowing attribution. A handler that legitimately
+// needs longer (large transcript replay, dreaming subagent) is rare — and
+// `setTimeout`-driven plugins like memory-logger normally return in
+// milliseconds. 25s leaves headroom under the chain watchdog.
+export const IDLE_HANDLER_TIMEOUT_MS = 25_000
+
+// Per-handler ceiling for session.end. Cron consumer's runPrompt and the
+// subagent runner both await session.hooks.runSessionEnd inside their
+// finally blocks — a hung handler wedges inFlight forever, so the next
+// scheduler fire is silently coalesced and the cron job appears dead.
+// The memory plugin's session.end awaits a serialized memory-logger chain
+// that can stall on a half-open LLM stream; 60s is generous headroom for
+// legitimate transcript flush while still bounding the failure mode.
+export const END_HANDLER_TIMEOUT_MS = 60_000
+
+export type RegisteredHook<K extends keyof Hooks> = {
+  pluginName: string
+  agentDir: string
+  logger: PluginLogger
+  handler: NonNullable<Hooks[K]>
+}
+
+export type HookBus = {
+  registerAll: (pluginName: string, agentDir: string, logger: PluginLogger, hooks: Hooks) => void
+  unregisterAll: (pluginName: string) => void
+  runSessionStart: (event: SessionStartEvent) => Promise<void>
+  runSessionEnd: (event: SessionEndEvent) => Promise<void>
+  runSessionIdle: (event: SessionIdleEvent) => Promise<void>
+  runSessionPrompt: (event: SessionPromptEvent) => Promise<void>
+  runToolBefore: (event: ToolBeforeEvent) => Promise<{ block: true; reason: string } | undefined>
+  runToolAfter: (event: ToolAfterEvent) => Promise<void>
+  count: (name: keyof Hooks) => number
+}
+
+export type CreateHookBusOptions = {
+  // Test seam: per-handler ceiling for session.idle invocations. Lets the
+  // timeout path be exercised in tens of milliseconds instead of the 25s
+  // production default.
+  idleHandlerTimeoutMs?: number
+  // Test seam: per-handler ceiling for session.end invocations.
+  endHandlerTimeoutMs?: number
+}
+
+type Registries = {
+  'session.start': RegisteredHook<'session.start'>[]
+  'session.end': RegisteredHook<'session.end'>[]
+  'session.idle': RegisteredHook<'session.idle'>[]
+  'session.prompt': RegisteredHook<'session.prompt'>[]
+  'tool.before': RegisteredHook<'tool.before'>[]
+  'tool.after': RegisteredHook<'tool.after'>[]
+}
+
+export function createHookBus(options: CreateHookBusOptions = {}): HookBus {
+  const idleHandlerTimeoutMs = options.idleHandlerTimeoutMs ?? IDLE_HANDLER_TIMEOUT_MS
+  const endHandlerTimeoutMs = options.endHandlerTimeoutMs ?? END_HANDLER_TIMEOUT_MS
+  const r: Registries = {
+    'session.start': [],
+    'session.end': [],
+    'session.idle': [],
+    'session.prompt': [],
+    'tool.before': [],
+    'tool.after': [],
+  }
+
+  function ctx(reg: { pluginName: string; agentDir: string; logger: PluginLogger }): HookContext {
+    return { agentDir: reg.agentDir, pluginName: reg.pluginName, logger: reg.logger }
+  }
+
+  return {
+    registerAll(pluginName, agentDir, logger, hooks) {
+      const base = { pluginName, agentDir, logger }
+      if (hooks['session.start']) r['session.start'].push({ ...base, handler: hooks['session.start'] })
+      if (hooks['session.end']) r['session.end'].push({ ...base, handler: hooks['session.end'] })
+      if (hooks['session.idle']) r['session.idle'].push({ ...base, handler: hooks['session.idle'] })
+      if (hooks['session.prompt']) r['session.prompt'].push({ ...base, handler: hooks['session.prompt'] })
+      if (hooks['tool.before']) r['tool.before'].push({ ...base, handler: hooks['tool.before'] })
+      if (hooks['tool.after']) r['tool.after'].push({ ...base, handler: hooks['tool.after'] })
+    },
+
+    unregisterAll(pluginName) {
+      r['session.start'] = r['session.start'].filter((h) => h.pluginName !== pluginName)
+      r['session.end'] = r['session.end'].filter((h) => h.pluginName !== pluginName)
+      r['session.idle'] = r['session.idle'].filter((h) => h.pluginName !== pluginName)
+      r['session.prompt'] = r['session.prompt'].filter((h) => h.pluginName !== pluginName)
+      r['tool.before'] = r['tool.before'].filter((h) => h.pluginName !== pluginName)
+      r['tool.after'] = r['tool.after'].filter((h) => h.pluginName !== pluginName)
+    },
+
+    async runSessionStart(event) {
+      for (const reg of r['session.start']) {
+        try {
+          await reg.handler(event, ctx(reg))
+        } catch (err) {
+          reportHookError(reg, 'session.start', err)
+        }
+      }
+    },
+
+    async runSessionEnd(event) {
+      for (const reg of r['session.end']) {
+        try {
+          await raceWithTimeout(
+            Promise.resolve(reg.handler(event, ctx(reg))),
+            endHandlerTimeoutMs,
+            `plugin ${reg.pluginName} session.end`,
+          )
+        } catch (err) {
+          reportHookError(reg, 'session.end', err)
+        }
+      }
+    },
+
+    async runSessionIdle(event) {
+      for (const reg of r['session.idle']) {
+        try {
+          await raceWithTimeout(
+            Promise.resolve(reg.handler(event, ctx(reg))),
+            idleHandlerTimeoutMs,
+            `plugin ${reg.pluginName} session.idle`,
+          )
+        } catch (err) {
+          reportHookError(reg, 'session.idle', err)
+        }
+      }
+    },
+
+    async runSessionPrompt(event) {
+      for (const reg of r['session.prompt']) {
+        try {
+          await reg.handler(event, ctx(reg))
+        } catch (err) {
+          reportHookError(reg, 'session.prompt', err)
+        }
+      }
+    },
+
+    // First plugin to return `{ block: true, reason }` short-circuits. Earlier
+    // plugins' arg mutations remain visible to later plugins via the shared
+    // event.args object.
+    async runToolBefore(event) {
+      for (const reg of r['tool.before']) {
+        let result: ToolBeforeResult
+        try {
+          result = await reg.handler(event, ctx(reg))
+        } catch (err) {
+          reportHookError(reg, 'tool.before', err)
+          continue
+        }
+        if (result && typeof result === 'object' && (result as { block?: unknown }).block === true) {
+          const reason = (result as { reason?: unknown }).reason
+          return { block: true, reason: typeof reason === 'string' ? reason : 'blocked by plugin' }
+        }
+      }
+      return undefined
+    },
+
+    async runToolAfter(event) {
+      for (const reg of r['tool.after']) {
+        try {
+          await reg.handler(event, ctx(reg))
+        } catch (err) {
+          reportHookError(reg, 'tool.after', err)
+        }
+      }
+    },
+
+    count(name) {
+      return r[name].length
+    },
+  }
+}
+
+function reportHookError(reg: { logger: PluginLogger }, hook: keyof Hooks, err: unknown): void {
+  const message = err instanceof Error ? err.message : String(err)
+  reg.logger.error(`hook ${hook} threw: ${message}`)
+}
+
+async function raceWithTimeout<T>(work: Promise<T>, ms: number, label: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | null = null
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms)
+  })
+  try {
+    return await Promise.race([work, timeout])
+  } finally {
+    if (timer !== null) clearTimeout(timer)
+  }
+}

package/src/plugin/index.ts

@@ -0,0 +1,63 @@
+export {
+  bashTool,
+  defineTool,
+  definePlugin,
+  defineSubagent,
+  editTool,
+  findTool,
+  grepTool,
+  lsTool,
+  readTool,
+  writeTool,
+} from './define'
+
+export type {
+  BuiltinToolRef,
+  ContentPart,
+  DefinedPlugin,
+  HookContext,
+  HookName,
+  Hooks,
+  PluginContext,
+  PluginCronJob,
+  PluginExecCronJob,
+  PluginExports,
+  PluginLogger,
+  PluginPromptCronJob,
+  PluginSkill,
+  RunSession,
+  SessionEndEvent,
+  SessionIdleEvent,
+  SessionPromptEvent,
+  SessionStartEvent,
+  Subagent,
+  SubagentContext,
+  Tool,
+  ToolAfterEvent,
+  ToolBeforeEvent,
+  ToolBeforeResult,
+  ToolContext,
+  ToolLogger,
+  ToolResult,
+} from './types'
+
+export {
+  loadPlugins,
+  summarizeLoaded,
+  pluginCronJobs,
+  type LoadPluginsOptions,
+  type LoadPluginsResult,
+} from './manager'
+export type { LoadPluginEntryFn, ResolvedPlugin } from './loader'
+export { loadPluginEntry, derivePluginNameFromPackage } from './loader'
+export { materializeSkills, type MaterializedSkills, type SkillEntry } from './skills'
+export {
+  buildPluginCronGlobalId,
+  type PluginRegistry,
+  type RegisteredCronJob,
+  type RegisteredSubagent,
+  type RegisteredTool,
+  type RegisteredSkillEntry,
+  type RegisteredSkillDir,
+} from './registry'
+export { createHookBus, type HookBus } from './hooks'