typeclaw 0.1.0

package/src/plugin/loader.ts

@@ -0,0 +1,111 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import type { DefinedPlugin } from './types'
+
+export type ResolvedPlugin = {
+  name: string
+  version: string | undefined
+  source: string
+  defined: DefinedPlugin<any>
+}
+
+export type LoadPluginEntryFn = (entry: string, agentDir: string) => Promise<ResolvedPlugin>
+
+export async function loadPluginEntry(entry: string, agentDir: string): Promise<ResolvedPlugin> {
+  if (isLocalPath(entry)) {
+    return loadLocal(entry, agentDir)
+  }
+  return loadNpm(entry, agentDir)
+}
+
+function isLocalPath(entry: string): boolean {
+  return entry.startsWith('./') || entry.startsWith('../') || isAbsolute(entry)
+}
+
+async function loadLocal(entry: string, agentDir: string): Promise<ResolvedPlugin> {
+  const resolved = resolve(agentDir, entry)
+  // Confine local plugin paths to within agentDir so a malicious typeclaw.json
+  // cannot point at arbitrary files on the host.
+  const rel = relative(agentDir, resolved)
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`plugin path escapes agent directory: ${entry} (resolved to ${resolved})`)
+  }
+  if (!existsSync(resolved)) {
+    throw new Error(`plugin path does not exist: ${entry} (resolved to ${resolved})`)
+  }
+  const url = pathToFileURL(resolved).href
+  const mod = (await import(url)) as { default?: unknown }
+  const defined = expectDefined(mod, entry)
+  const name = basename(resolved).replace(/\.(ts|tsx|js|mjs|cjs)$/i, '')
+  return { name, version: undefined, source: entry, defined }
+}
+
+async function loadNpm(entry: string, agentDir: string): Promise<ResolvedPlugin> {
+  const pkgJsonPath = findPackageJson(entry, agentDir)
+  let pkgName = entry
+  let version: string | undefined
+  let entryPath: string | null = null
+  if (pkgJsonPath !== null) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8')) as {
+        name?: unknown
+        version?: unknown
+        main?: unknown
+        module?: unknown
+      }
+      if (typeof pkg.name === 'string' && pkg.name.length > 0) pkgName = pkg.name
+      if (typeof pkg.version === 'string' && pkg.version.length > 0) version = pkg.version
+      const main = typeof pkg.module === 'string' ? pkg.module : typeof pkg.main === 'string' ? pkg.main : null
+      if (main !== null) {
+        const candidate = join(dirname(pkgJsonPath), main)
+        if (existsSync(candidate)) {
+          entryPath = candidate
+        }
+      }
+    } catch {
+      // Fall through to bare-import resolution.
+    }
+  }
+  // Falls back to bare-import resolution when entryPath cannot be located on
+  // disk. Modern packages with `exports` map (and no `main`/`module`) take
+  // this path so Bun's resolver can read `exports`.
+  const importTarget = entryPath !== null ? pathToFileURL(entryPath).href : entry
+  const mod = (await import(importTarget)) as { default?: unknown }
+  const defined = expectDefined(mod, entry)
+  const name = derivePluginNameFromPackage(pkgName)
+  return { name, version, source: entry, defined }
+}
+
+export function derivePluginNameFromPackage(packageName: string): string {
+  const PREFIX = 'typeclaw-plugin-'
+  const SCOPED_PREFIX_RE = /^@[^/]+\//
+  const stripped = packageName.replace(SCOPED_PREFIX_RE, '')
+  return stripped.startsWith(PREFIX) ? stripped.slice(PREFIX.length) : stripped
+}
+
+function findPackageJson(entry: string, agentDir: string): string | null {
+  const PACKAGE_JSON = 'package.json'
+  let cur = agentDir
+  while (true) {
+    const p = join(cur, 'node_modules', entry, PACKAGE_JSON)
+    if (existsSync(p)) return p
+    const parent = dirname(cur)
+    if (parent === cur) return null
+    cur = parent
+  }
+}
+
+function expectDefined(mod: { default?: unknown }, entry: string): DefinedPlugin<any> {
+  const def = mod.default
+  if (
+    def !== null &&
+    typeof def === 'object' &&
+    'plugin' in (def as Record<string, unknown>) &&
+    typeof (def as { plugin: unknown }).plugin === 'function'
+  ) {
+    return def as DefinedPlugin<any>
+  }
+  throw new Error(`plugin ${entry}: default export is not a definePlugin(...) result`)
+}

package/src/plugin/manager.ts

@@ -0,0 +1,136 @@
+import { z } from 'zod'
+
+import type { CronJob } from '@/cron'
+
+import { createPluginContext, createPluginLogger, type SpawnSubagentFn } from './context'
+import { createHookBus, type HookBus } from './hooks'
+import { loadPluginEntry, type LoadPluginEntryFn, type ResolvedPlugin } from './loader'
+import { discardRegistrationsBy, emptyRegistry, type PluginRegistry, registerContributions } from './registry'
+import type { PluginExports } from './types'
+
+export type LoadPluginsOptions = {
+  entries: string[]
+  agentDir: string
+  configsByName: Record<string, unknown>
+  loadEntry?: LoadPluginEntryFn
+  // Bundled plugins resolved by the runtime (not from typeclaw.json). Loaded
+  // before user-declared `entries` so a config block named after a bundled
+  // plugin (e.g. "memory") is consumed by the bundled plugin, and so plugin-
+  // name conflicts with a user-declared entry surface as a clear error.
+  bundled?: ResolvedPlugin[]
+}
+
+export type LoadPluginsResult = {
+  registry: PluginRegistry
+  hooks: HookBus
+  loadedPlugins: { name: string; version: string | undefined; source: string }[]
+  markBooted: () => void
+  setSpawnSubagent: (fn: SpawnSubagentFn) => void
+}
+
+export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPluginsResult> {
+  const registry = emptyRegistry()
+  const hooks = createHookBus()
+  const loaded: { name: string; version: string | undefined; source: string }[] = []
+  const loadEntry = opts.loadEntry ?? loadPluginEntry
+
+  let booted = false
+  let spawnSubagentImpl: SpawnSubagentFn = async () => {
+    throw new Error('plugin: spawnSubagent is not yet wired')
+  }
+
+  const allPlugins: { entry: string; resolved: ResolvedPlugin }[] = [
+    ...(opts.bundled?.map((resolved) => ({ entry: `<bundled:${resolved.name}>`, resolved })) ?? []),
+    ...(await Promise.all(
+      opts.entries.map(async (entry) => ({ entry, resolved: await loadEntry(entry, opts.agentDir) })),
+    )),
+  ]
+
+  for (const { entry, resolved } of allPlugins) {
+    if (loaded.find((l) => l.name === resolved.name)) {
+      throw new Error(`plugin name conflict: ${resolved.name} (entry ${entry}) already loaded`)
+    }
+
+    let validatedConfig: unknown = undefined
+    if (resolved.defined.configSchema) {
+      const raw = opts.configsByName[resolved.name]
+      const parsed = (resolved.defined.configSchema as z.ZodType<unknown>).safeParse(raw ?? {})
+      if (!parsed.success) {
+        throw new Error(`plugin ${resolved.name}: config invalid: ${formatZodIssues(parsed.error)}`)
+      }
+      validatedConfig = parsed.data
+    } else if (opts.configsByName[resolved.name] !== undefined) {
+      throw new Error(
+        `plugin ${resolved.name}: config block "${resolved.name}" present in typeclaw.json but plugin declares no configSchema`,
+      )
+    }
+
+    const logger = createPluginLogger(resolved.name)
+    const ctx = createPluginContext({
+      name: resolved.name,
+      version: resolved.version,
+      agentDir: opts.agentDir,
+      config: validatedConfig as never,
+      logger,
+      spawnSubagent: (name, payload) => spawnSubagentImpl(name, payload),
+      isBooted: () => booted,
+    })
+
+    let exports: PluginExports
+    try {
+      exports = await resolved.defined.plugin(ctx)
+    } catch (err) {
+      discardRegistrationsBy(resolved.name, registry, hooks)
+      const message = err instanceof Error ? err.message : String(err)
+      throw new Error(`plugin ${resolved.name}: factory threw: ${message}`)
+    }
+
+    try {
+      registerContributions({
+        pluginName: resolved.name,
+        logger,
+        exports,
+        registry,
+        hooks,
+        agentDir: opts.agentDir,
+      })
+    } catch (err) {
+      discardRegistrationsBy(resolved.name, registry, hooks)
+      throw err
+    }
+
+    loaded.push({ name: resolved.name, version: resolved.version, source: resolved.source })
+  }
+
+  return {
+    registry,
+    hooks,
+    loadedPlugins: loaded,
+    markBooted: () => {
+      booted = true
+    },
+    setSpawnSubagent: (fn) => {
+      spawnSubagentImpl = fn
+    },
+  }
+}
+
+export function summarizeLoaded(loaded: LoadPluginsResult['loadedPlugins'], registry: PluginRegistry): string {
+  const head = loaded.map((p) => (p.version !== undefined ? `${p.name} v${p.version}` : p.name)).join(', ')
+  const counts = [
+    `${registry.tools.length} tool(s)`,
+    `${registry.subagents.length} subagent(s)`,
+    `${registry.cronJobs.length} cron job(s)`,
+    `${registry.skills.length} skill(s)`,
+    `${registry.skillsDirs.length} skills dir(s)`,
+  ].join(', ')
+  return `${loaded.length} plugin(s): ${head} [${counts}]`
+}
+
+export function pluginCronJobs(registry: PluginRegistry): CronJob[] {
+  return registry.cronJobs.map((j) => j.job)
+}
+
+function formatZodIssues(error: z.ZodError): string {
+  return error.issues.map((i) => `${i.path.length > 0 ? i.path.join('.') : '<root>'}: ${i.message}`).join('; ')
+}

package/src/plugin/registry.ts

@@ -0,0 +1,145 @@
+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'
+
+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 PluginRegistry = {
+  tools: RegisteredTool[]
+  subagents: RegisteredSubagent[]
+  cronJobs: RegisteredCronJob[]
+  skills: RegisteredSkillEntry[]
+  skillsDirs: RegisteredSkillDir[]
+}
+
+export type RegisterContributionsOptions = {
+  pluginName: string
+  logger: PluginLogger
+  exports: PluginExports
+  registry: PluginRegistry
+  hooks: HookBus
+  agentDir: string
+}
+
+export function buildPluginCronGlobalId(pluginName: string, localId: string): string {
+  return `__plugin_${pluginName}_${localId}`
+}
+
+export function registerContributions(opts: RegisterContributionsOptions): void {
+  const { pluginName, logger, exports: ex, registry, hooks, agentDir } = opts
+
+  if (ex.tools) {
+    for (const [toolName, tool] of Object.entries(ex.tools)) {
+      assertNotEmpty('tool name', toolName, pluginName)
+      const conflict = registry.tools.find((t) => t.toolName === toolName)
+      if (conflict) {
+        throw new Error(`plugin ${pluginName}: tool "${toolName}" already registered by plugin ${conflict.pluginName}`)
+      }
+      registry.tools.push({ pluginName, toolName, tool, logger })
+    }
+  }
+
+  if (ex.subagents) {
+    for (const [subagentName, subagent] of Object.entries(ex.subagents)) {
+      assertNotEmpty('subagent name', subagentName, pluginName)
+      const conflict = registry.subagents.find((s) => s.subagentName === subagentName)
+      if (conflict) {
+        throw new Error(
+          `plugin ${pluginName}: subagent "${subagentName}" already registered by plugin ${conflict.pluginName}`,
+        )
+      }
+      registry.subagents.push({ pluginName, subagentName, subagent })
+    }
+  }
+
+  if (ex.cronJobs) {
+    for (const [localId, spec] of Object.entries(ex.cronJobs)) {
+      assertNotEmpty('cron job id', localId, pluginName)
+      const globalId = buildPluginCronGlobalId(pluginName, localId)
+      const conflict = registry.cronJobs.find((j) => j.globalId === globalId)
+      if (conflict) {
+        throw new Error(
+          `plugin ${pluginName}: cron job "${localId}" globalId "${globalId}" conflicts with plugin ${conflict.pluginName}`,
+        )
+      }
+      const job = toCronJob(globalId, spec)
+      registry.cronJobs.push({ pluginName, localId, globalId, job })
+    }
+  }
+
+  if (ex.skills) {
+    for (const [localName, skill] of Object.entries(ex.skills)) {
+      assertNotEmpty('skill name', localName, pluginName)
+      const conflict = registry.skills.find((s) => s.localName === localName)
+      if (conflict) {
+        throw new Error(
+          `plugin ${pluginName}: skill "${localName}" already registered by plugin ${conflict.pluginName}`,
+        )
+      }
+      registry.skills.push({ pluginName, localName, skill })
+    }
+  }
+
+  if (ex.skillsDirs) {
+    for (const path of ex.skillsDirs) {
+      if (!existsSync(path)) {
+        logger.warn(`skillsDirs entry does not exist on disk: ${path}`)
+      }
+      registry.skillsDirs.push({ pluginName, path })
+    }
+  }
+
+  if (ex.hooks) {
+    hooks.registerAll(pluginName, agentDir, logger, ex.hooks)
+  }
+}
+
+export function discardRegistrationsBy(pluginName: string, registry: PluginRegistry, hooks: HookBus): void {
+  registry.tools = registry.tools.filter((t) => t.pluginName !== pluginName)
+  registry.subagents = registry.subagents.filter((s) => s.pluginName !== pluginName)
+  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)
+  hooks.unregisterAll(pluginName)
+}
+
+export function emptyRegistry(): PluginRegistry {
+  return { tools: [], subagents: [], cronJobs: [], skills: [], skillsDirs: [] }
+}
+
+function assertNotEmpty(kind: string, value: string, pluginName: string): void {
+  if (value.length === 0) {
+    throw new Error(`plugin ${pluginName}: empty ${kind}`)
+  }
+}
+
+function toCronJob(globalId: string, spec: PluginCronJob): CronJob {
+  if (spec.kind === 'prompt') {
+    const job: PromptJob = {
+      id: globalId,
+      schedule: spec.schedule,
+      enabled: spec.enabled ?? true,
+      kind: 'prompt',
+      prompt: spec.prompt,
+      ...(spec.timezone !== undefined ? { timezone: spec.timezone } : {}),
+      ...(spec.subagent !== undefined ? { subagent: spec.subagent } : {}),
+      ...(spec.payload !== undefined ? { payload: spec.payload } : {}),
+    }
+    return job
+  }
+  return {
+    id: globalId,
+    schedule: spec.schedule,
+    enabled: spec.enabled ?? true,
+    kind: 'exec',
+    command: spec.command,
+    ...(spec.timezone !== undefined ? { timezone: spec.timezone } : {}),
+  }
+}

package/src/plugin/skills.ts

@@ -0,0 +1,62 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import type { PluginSkill } from './types'
+
+export type SkillEntry = { pluginName: string; localName: string; skill: PluginSkill }
+
+export type MaterializedSkills = {
+  dir: string
+  dispose: () => Promise<void>
+}
+
+const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9-_]*$/
+
+export async function materializeSkills(skills: SkillEntry[]): Promise<MaterializedSkills> {
+  const root = await mkdtemp(join(tmpdir(), 'typeclaw-plugin-skills-'))
+
+  try {
+    const seen = new Set<string>()
+    for (const entry of skills) {
+      const sanitized = sanitizeSkillName(entry.localName)
+      if (seen.has(sanitized)) {
+        throw new Error(`plugin ${entry.pluginName}: duplicate skill name after sanitization: ${entry.localName}`)
+      }
+      seen.add(sanitized)
+
+      const skillDir = join(root, sanitized)
+      await mkdir(skillDir, { recursive: true })
+      const body = renderSkillFile(entry.skill)
+      await writeFile(join(skillDir, 'SKILL.md'), body, 'utf8')
+    }
+  } catch (err) {
+    await rm(root, { recursive: true, force: true })
+    throw err
+  }
+
+  return {
+    dir: root,
+    dispose: async () => {
+      await rm(root, { recursive: true, force: true })
+    },
+  }
+}
+
+function sanitizeSkillName(name: string): string {
+  if (SKILL_NAME_PATTERN.test(name)) return name
+  return name.toLowerCase().replace(/[^a-z0-9_-]/g, '-')
+}
+
+function renderSkillFile(skill: PluginSkill): string {
+  const fm = skill.frontmatter ?? {}
+  const fmEntries = Object.entries({ ...fm, description: skill.description })
+  if (fmEntries.length === 0) return skill.content
+  const lines = ['---']
+  for (const [key, value] of fmEntries) {
+    lines.push(`${key}: ${JSON.stringify(value)}`)
+  }
+  lines.push('---', '')
+  lines.push(skill.content)
+  return lines.join('\n')
+}

package/src/plugin/types.ts

@@ -0,0 +1,172 @@
+import type { z } from 'zod'
+
+import type { SessionOrigin } from '@/agent/session-origin'
+
+export type ContentPart = { type: 'text'; text: string } | { type: 'image'; mimeType: string; data: string }
+
+export type ToolResult = {
+  content: ContentPart[]
+  details?: unknown
+}
+
+export type ToolLogger = {
+  info: (msg: string) => void
+  warn: (msg: string) => void
+  error: (msg: string) => void
+}
+
+export type ToolContext = {
+  signal: AbortSignal | undefined
+  sessionId: string
+  agentDir: string
+  logger: ToolLogger
+}
+
+export type Tool<P = unknown> = {
+  description: string
+  parameters: z.ZodType<P>
+  execute: (args: P, ctx: ToolContext) => Promise<ToolResult>
+}
+
+export type BuiltinToolRef = { readonly __builtinTool: string }
+
+export type SubagentContext<P = unknown> = {
+  userPrompt: string
+  agentDir: string
+  payload: P
+}
+
+export type RunSession = (override?: { userPrompt?: string }) => Promise<void>
+
+export type Subagent<P = unknown> = {
+  systemPrompt: string
+  tools?: BuiltinToolRef[]
+  customTools?: Tool<any>[]
+  payloadSchema?: z.ZodType<P>
+  handler?: (ctx: SubagentContext<P>, runSession: RunSession) => Promise<void>
+  // Coalescing key for the SubagentConsumer's in-flight set. Default is the
+  // subagent name alone (only one instance of the subagent runs at a time).
+  // Override to allow per-payload concurrency, e.g. memory-logger keyed by
+  // parentSessionId so different parent sessions run in parallel while
+  // duplicate runs against the same session deduplicate.
+  inFlightKey?: (payload: P) => string
+}
+
+// Cron job map keys are local; the runtime prefixes with `__plugin_<plugin-name>_`
+// to form the global cron id, guaranteeing no collision with cron.json user
+// jobs (no underscore prefix) or across plugins.
+export type PluginPromptCronJob = {
+  schedule: string
+  kind: 'prompt'
+  prompt: string
+  enabled?: boolean
+  timezone?: string
+  subagent?: string
+  payload?: unknown
+}
+
+export type PluginExecCronJob = {
+  schedule: string
+  kind: 'exec'
+  command: string[]
+  enabled?: boolean
+  timezone?: string
+}
+
+export type PluginCronJob = PluginPromptCronJob | PluginExecCronJob
+
+export type PluginSkill = {
+  description: string
+  content: string
+  frontmatter?: Record<string, unknown>
+}
+
+export type SessionStartEvent = {
+  sessionId: string
+  agentDir: string
+}
+
+export type SessionEndEvent = {
+  sessionId: string
+}
+
+export type SessionIdleEvent = {
+  sessionId: string
+  parentTranscriptPath: string | undefined
+  idleMs: number
+  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.
+export type SessionPromptEvent = {
+  prompt: string
+  sessionId: string
+  agentDir: string
+  origin?: SessionOrigin
+}
+
+// Fired for plugin-defined tools and TypeClaw-exposed system tools, including
+// built-in pi tools (read/bash/edit/write/grep/find/ls) when plugins are wired.
+export type ToolBeforeEvent = {
+  tool: string
+  sessionId: string
+  callId: string
+  args: Record<string, unknown>
+}
+
+export type ToolBeforeResult = void | undefined | { block: true; reason: string }
+
+export type ToolAfterEvent = {
+  tool: string
+  sessionId: string
+  callId: string
+  result: ToolResult
+}
+
+export type HookContext = {
+  agentDir: string
+  pluginName: string
+  logger: PluginLogger
+}
+
+export type Hooks = {
+  'session.start'?: (event: SessionStartEvent, ctx: HookContext) => Promise<void> | void
+  '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
+  'tool.before'?: (event: ToolBeforeEvent, ctx: HookContext) => Promise<ToolBeforeResult> | ToolBeforeResult
+  'tool.after'?: (event: ToolAfterEvent, ctx: HookContext) => Promise<void> | void
+}
+
+export type HookName = keyof Hooks
+
+export type PluginLogger = {
+  info: (msg: string) => void
+  warn: (msg: string) => void
+  error: (msg: string) => void
+}
+
+export type PluginContext<TConfig = never> = {
+  readonly name: string
+  readonly version: string | undefined
+  readonly agentDir: string
+  readonly config: TConfig
+  readonly logger: PluginLogger
+  spawnSubagent: (name: string, payload?: unknown) => Promise<void>
+}
+
+export type PluginExports = {
+  tools?: Record<string, Tool<any>>
+  subagents?: Record<string, Subagent<any>>
+  cronJobs?: Record<string, PluginCronJob>
+  skills?: Record<string, PluginSkill>
+  skillsDirs?: string[]
+  hooks?: Hooks
+}
+
+export type DefinedPlugin<TConfig = never> = {
+  readonly configSchema?: z.ZodType<TConfig>
+  readonly plugin: (ctx: PluginContext<TConfig>) => Promise<PluginExports>
+}