typeclaw 0.1.0

package/src/agent/git-nudge.ts

@@ -0,0 +1,95 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+const MAX_LISTED_PATHS = 10
+
+// `sessions/` is auto-snapshotted and `memory/` is force-committed by the
+// dreaming subagent — both are runtime-owned, never agent-owned. Nudging the
+// agent to commit them would mislead it into staging files outside its remit.
+const RUNTIME_OWNED_PREFIXES = ['sessions/', 'memory/']
+
+export type GitNudgeDeps = {
+  readStatus: (agentDir: string) => Promise<readonly string[] | null>
+}
+
+// Returns "" (not a placeholder string) when there is nothing to nudge about.
+// The empty case must add zero bytes to the system prompt so cache prefixes
+// stay identical to a clean-worktree agent folder.
+export async function renderGitNudge(agentDir: string, deps: GitNudgeDeps = defaultDeps): Promise<string> {
+  if (!existsSync(join(agentDir, '.git'))) return ''
+  const status = await deps.readStatus(agentDir)
+  if (status === null) return ''
+  const dirty = filterAgentOwned(status)
+  if (dirty.length === 0) return ''
+  return formatNudge(dirty)
+}
+
+export function formatNudge(dirtyPaths: readonly string[]): string {
+  const total = dirtyPaths.length
+  const shown = dirtyPaths.slice(0, MAX_LISTED_PATHS)
+  const remaining = total - shown.length
+
+  const lines = [
+    '## Uncommitted changes at session start',
+    '',
+    `git reports ${total} uncommitted file${total === 1 ? '' : 's'} in your agent folder right now:`,
+    '',
+    ...shown.map((p) => `- ${p}`),
+  ]
+  if (remaining > 0) {
+    lines.push(`- … and ${remaining} more`)
+  }
+  lines.push(
+    '',
+    "These are real, current modifications — not advice. Before declaring this session's task done, commit any of these you're responsible for, with `git add <paths>` and `git commit -m \"…\"` per the version-control rules above. If a listed path is from earlier work you didn't touch, leave it alone.",
+  )
+  return lines.join('\n')
+}
+
+// Porcelain v1 line shape: "XY <path>" or, for renames, "XY <orig> -> <dest>".
+// We drop the status code and, on rename, return the destination because that
+// is the live file the agent would `git add`.
+export function parsePorcelain(stdout: string): string[] {
+  const out: string[] = []
+  for (const raw of stdout.split('\n')) {
+    if (raw.length < 4) continue
+    const rest = raw.slice(3)
+    const arrowIdx = rest.indexOf(' -> ')
+    out.push(arrowIdx === -1 ? rest : rest.slice(arrowIdx + 4))
+  }
+  return out
+}
+
+function filterAgentOwned(paths: readonly string[]): string[] {
+  return paths.filter((p) => !RUNTIME_OWNED_PREFIXES.some((prefix) => p.startsWith(prefix)))
+}
+
+// Mirrors the spawn pattern in `src/container/start.ts` `commitSystemFile`.
+const defaultDeps: GitNudgeDeps = {
+  async readStatus(agentDir) {
+    const bun = getBun()
+    if (!bun) return null
+    try {
+      const proc = bun.spawn({
+        cmd: ['git', 'status', '--porcelain=v1'],
+        cwd: agentDir,
+        stdout: 'pipe',
+        stderr: 'pipe',
+      })
+      const exit = await proc.exited
+      if (exit !== 0) return null
+      const text = await new Response(proc.stdout).text()
+      return parsePorcelain(text)
+    } catch {
+      return null
+    }
+  },
+}
+
+// Pieces of `@/agent` are exercised under Node in some tests where
+// `globalThis.Bun` is undefined; this fallback matches the helper in
+// `src/container/start.ts`.
+function getBun(): typeof Bun | null {
+  const g = globalThis as { Bun?: typeof Bun }
+  return g.Bun ?? null
+}

package/src/agent/index.ts

@@ -0,0 +1,451 @@
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { createAgentSession, DefaultResourceLoader, SessionManager } from '@mariozechner/pi-coding-agent'
+import type { AgentSession, ToolDefinition } from '@mariozechner/pi-coding-agent'
+
+import type { ChannelRouter } from '@/channels/router'
+import { getConfig, resolveModel } from '@/config'
+import type {
+  BuiltinToolRef,
+  HookBus,
+  MaterializedSkills,
+  PluginRegistry,
+  RegisteredTool as PluginRegisteredTool,
+  Tool as PluginTool,
+} from '@/plugin'
+import { materializeSkills } from '@/plugin'
+import type { ReloadRegistry } from '@/reload'
+import type { Stream } from '@/stream'
+
+import { getAuth } from './auth'
+import { createCompactionSettingsManager } from './compaction'
+import { renderGitNudge } from './git-nudge'
+import { resolveBuiltinToolRefs, wrapPluginTool, wrapSystemAgentTool, wrapSystemTool } from './plugin-tools'
+import { createReloadTool } from './reload-tool'
+import { loadSelf } from './self'
+import { renderSessionOrigin, type SessionOrigin } from './session-origin'
+import { DEFAULT_SYSTEM_PROMPT } from './system-prompt'
+import { createChannelFetchAttachmentTool } from './tools/channel-fetch-attachment'
+import { createChannelHistoryTool } from './tools/channel-history'
+import { createChannelReplyTool } from './tools/channel-reply'
+import { createChannelSendTool } from './tools/channel-send'
+import { createRestartTool } from './tools/restart'
+import { createStreamSnapshotTool } from './tools/stream-snapshot'
+import { webfetchTool } from './tools/webfetch'
+import { websearchTool } from './tools/websearch'
+
+export type { SessionOrigin } from './session-origin'
+
+export type { AgentSession }
+
+type AgentSessionTools = NonNullable<Parameters<typeof createAgentSession>[0]>['tools']
+
+export type PluginSessionWiring = {
+  registry: PluginRegistry
+  hooks: HookBus
+  sessionId: string
+  agentDir: string
+}
+
+export type PluginSubagentSelection = {
+  pluginName: string
+  toolRefs?: BuiltinToolRef[]
+  customTools?: PluginTool<any>[]
+  toolNamePrefix: string
+}
+
+export type CreateSessionOptions = {
+  reloadRegistry?: ReloadRegistry
+  sessionManager?: SessionManager
+  stream?: Stream
+  channelRouter?: ChannelRouter
+  // Bypass the file-based resource loader (IDENTITY.md, SOUL.md, MEMORY.md,
+  // memory/, bundled skills) and use this string verbatim as the system prompt.
+  systemPromptOverride?: string
+  // Identifies the kind of session and (for channels) its addressing fields.
+  // Rendered into the system prompt so the agent knows who's listening, where
+  // its output goes, and what to pass to channel_send.
+  origin?: SessionOrigin
+  tools?: AgentSessionTools
+  customTools?: ToolDefinition[]
+  plugins?: PluginSessionWiring
+  // When set, only the named plugin subagent's own tools are exposed; the
+  // wider plugin registry's tools are NOT injected. Used by plugin subagent
+  // session creation so subagents see exactly what they declared.
+  pluginSubagent?: PluginSubagentSelection
+  // Enables the `restart` tool. Set when the agent is running inside a
+  // typeclaw-managed container. Read from TYPECLAW_CONTAINER_NAME at the call site.
+  containerName?: string
+}
+
+export type CreateSessionResult = {
+  session: AgentSession
+  dispose: () => Promise<void>
+}
+
+export async function createSession(options: CreateSessionOptions = {}): Promise<AgentSession> {
+  const { session } = await createSessionWithDispose(options)
+  return session
+}
+
+export async function createSessionWithDispose(options: CreateSessionOptions = {}): Promise<CreateSessionResult> {
+  const { authStorage, modelRegistry } = getAuth()
+
+  const materializedSkills =
+    options.plugins && options.plugins.registry.skills.length > 0
+      ? await materializeSkills(
+          options.plugins.registry.skills.map((s) => ({
+            pluginName: s.pluginName,
+            localName: s.localName,
+            skill: s.skill,
+          })),
+        )
+      : null
+
+  const resourceLoader =
+    options.systemPromptOverride !== undefined
+      ? await createOverrideResourceLoader(options.systemPromptOverride, options.origin)
+      : await createResourceLoader({
+          ...(options.plugins ? { plugins: options.plugins, materializedSkills } : {}),
+          ...(options.origin ? { origin: options.origin } : {}),
+        })
+
+  const subagentBuiltinTools = options.pluginSubagent?.toolRefs
+    ? resolveBuiltinToolRefs(options.pluginSubagent.toolRefs)
+    : undefined
+  const pluginCustomTools = options.pluginSubagent
+    ? wrapSubagentCustomTools(options.pluginSubagent, options.plugins)
+    : wrapRegistryTools(options.plugins)
+
+  const tools = wrapSystemAgentTools(
+    options.tools ?? (subagentBuiltinTools as AgentSessionTools | undefined),
+    options.plugins,
+  )
+
+  // Hoisted above tool construction so the restart tool can be wired with the
+  // session's stable identity (sessionManager.getSessionId()). Subscribers use
+  // that ID to distinguish the originating session from siblings on the
+  // container-restarting broadcast.
+  const sessionManager = options.sessionManager ?? SessionManager.inMemory()
+
+  const customSystemTools =
+    options.customTools !== undefined
+      ? options.customTools
+      : options.pluginSubagent
+        ? []
+        : [
+            websearchTool,
+            webfetchTool,
+            ...(options.reloadRegistry ? [createReloadTool({ registry: options.reloadRegistry })] : []),
+            ...(options.stream ? [createStreamSnapshotTool({ stream: options.stream })] : []),
+            ...buildChannelTools(options.channelRouter, options.origin),
+            ...(options.containerName
+              ? [
+                  createRestartTool({
+                    containerName: options.containerName,
+                    originatingSessionId: sessionManager.getSessionId(),
+                    ...(options.stream ? { stream: options.stream } : {}),
+                  }),
+                ]
+              : []),
+          ]
+  const customTools = [...wrapSystemTools(customSystemTools, options.plugins), ...pluginCustomTools]
+
+  const model = resolveModel(getConfig().model)
+  const { session } = await createAgentSession({
+    model,
+    sessionManager,
+    settingsManager: createCompactionSettingsManager(model),
+    authStorage,
+    modelRegistry,
+    resourceLoader,
+    ...(tools ? { tools } : {}),
+    customTools,
+  })
+
+  const unsubRestart = subscribeRestartNotice(options.stream, sessionManager)
+
+  const dispose = async () => {
+    unsubRestart?.()
+    if (materializedSkills) await materializedSkills.dispose()
+  }
+  return { session, dispose }
+}
+
+// Subscribes the given session to the in-process broadcast that the `restart`
+// tool fires on a successful hostd ACK. The subscriber dispatches by identity:
+// the session whose tool execution fired the restart (originator) gets a
+// `typeclaw.restart-self` notice instructing the model to proactively confirm
+// restart completion in its very next reply. All other sessions (siblings) get
+// the `typeclaw.restart` notice instructing them not to mention the restart
+// unless directly asked. Two distinct customTypes let downstream consumers
+// distinguish the cases unambiguously. display:false keeps either entry out of
+// any TUI rendering that might inspect the JSONL later. Exported so unit tests
+// can verify the wiring without going through createAgentSession (which needs
+// auth and model registry); the composition test at the bottom of this
+// module's test file covers originator + siblings end to end.
+export function subscribeRestartNotice(
+  stream: Stream | undefined,
+  sessionManager: SessionManager,
+): (() => void) | null {
+  if (!stream) return null
+  const unsub = stream.subscribe({ target: { kind: 'broadcast' } }, (msg) => {
+    const payload = msg.payload as { kind?: unknown; restartedAt?: unknown; originatingSessionId?: unknown } | null
+    if (!payload || payload.kind !== 'container-restarting') return
+    if (typeof payload.restartedAt !== 'string') return
+    if (typeof payload.originatingSessionId !== 'string') return
+    if (payload.originatingSessionId === sessionManager.getSessionId()) {
+      sessionManager.appendCustomMessageEntry(
+        'typeclaw.restart-self',
+        formatRestartNoticeOriginating(payload.restartedAt),
+        false,
+      )
+    } else {
+      sessionManager.appendCustomMessageEntry('typeclaw.restart', formatRestartNotice(payload.restartedAt), false)
+    }
+  })
+  return unsub
+}
+
+// Convention documented in src/channels/router.ts:996-1013: runtime-injected
+// content in the user turn must use the `**[SYSTEM MESSAGE — not from a human]**`
+// framing fenced by `---`, plus an explicit "do not acknowledge or reply"
+// line. Without it, persona-rich models read the heading as a human-authored
+// instruction and reply to it on the next unrelated message.
+export function formatRestartNotice(restartedAt: string): string {
+  return [
+    '---',
+    '**[SYSTEM MESSAGE — not from a human]**',
+    '',
+    `The TypeClaw container was restarted at ${restartedAt}. The previous session`,
+    'state was preserved on disk and you have been resumed inside a new container',
+    'process. **Do not acknowledge or reply to this notice unless a human directly',
+    'asks whether the restart happened.**',
+    '',
+    'Guidance:',
+    '- If a human asks whether you actually restarted, you may confirm: yes, you',
+    `  did restart at ${restartedAt}.`,
+    '- Otherwise, continue the conversation normally.',
+    '',
+    '---',
+    '',
+  ].join('\n')
+}
+
+// Variant for the session that called the `restart` tool. The user explicitly
+// asked this conversation to restart; staying silent after the reboot is the
+// reported bug ("뭐야 너네 재시작 한 것도 모르냐"). This notice instructs the
+// model to acknowledge restart completion in its very next reply — once — then
+// stop mentioning it. Same SYSTEM MESSAGE framing as the sibling notice so
+// persona-rich models don't reply to the framing itself.
+export function formatRestartNoticeOriginating(restartedAt: string): string {
+  return [
+    '---',
+    '**[SYSTEM MESSAGE — not from a human]**',
+    '',
+    `The TypeClaw container was restarted at ${restartedAt} at the user's explicit`,
+    'request via the `restart` tool. The restart completed successfully and you',
+    'have been resumed inside a new container process with your previous',
+    'conversation memory intact.',
+    '',
+    '**Your very next reply must briefly confirm the restart completed** (e.g.',
+    '"restart finished, I\'m back" — or in whatever voice fits your persona),',
+    "even if the user's next message is about something unrelated. After that",
+    "single confirmation, address whatever the user's next message says, and do",
+    'not mention the restart again unless the user explicitly asks about it.',
+    '',
+    '---',
+    '',
+  ].join('\n')
+}
+
+// Builds the channel tool subset: channel_send (always when a router is
+// available), plus channel_reply + channel_history (only when the session
+// origin is a channel — those rely on origin-bound addressing). Extracted
+// from createSessionWithDispose so composition can be unit-tested without
+// going through createAgentSession / auth.
+export function buildChannelTools(
+  channelRouter: ChannelRouter | undefined,
+  origin: SessionOrigin | undefined,
+): ToolDefinition[] {
+  if (!channelRouter) return []
+  const tools: ToolDefinition[] = []
+  if (origin?.kind === 'channel') {
+    const channelOrigin = {
+      adapter: origin.adapter,
+      workspace: origin.workspace,
+      chat: origin.chat,
+      thread: origin.thread,
+    }
+    tools.push(createChannelReplyTool({ router: channelRouter, origin: channelOrigin }))
+    tools.push(createChannelHistoryTool({ router: channelRouter, origin: channelOrigin }))
+    tools.push(createChannelSendTool({ router: channelRouter, origin: channelOrigin }))
+    tools.push(
+      createChannelFetchAttachmentTool({
+        router: channelRouter,
+        origin: { adapter: origin.adapter },
+      }),
+    )
+  } else {
+    tools.push(createChannelSendTool({ router: channelRouter }))
+  }
+  return tools
+}
+
+function wrapRegistryTools(plugins: PluginSessionWiring | undefined): ToolDefinition[] {
+  if (!plugins) return []
+  return plugins.registry.tools.map((t: PluginRegisteredTool) =>
+    wrapPluginTool(t.tool, {
+      pluginName: t.pluginName,
+      toolName: t.toolName,
+      agentDir: plugins.agentDir,
+      sessionId: plugins.sessionId,
+      logger: t.logger,
+      hooks: plugins.hooks,
+    }),
+  )
+}
+
+function wrapSystemAgentTools(
+  tools: AgentSessionTools | undefined,
+  plugins: PluginSessionWiring | undefined,
+): AgentSessionTools | undefined {
+  if (!tools || !hasToolHooks(plugins)) return tools
+  return tools.map((tool) =>
+    wrapSystemAgentTool(tool, {
+      agentDir: plugins.agentDir,
+      sessionId: plugins.sessionId,
+      hooks: plugins.hooks,
+    }),
+  )
+}
+
+function wrapSystemTools(tools: ToolDefinition[], plugins: PluginSessionWiring | undefined): ToolDefinition[] {
+  if (!hasToolHooks(plugins)) return tools
+  return tools.map((tool) =>
+    wrapSystemTool(tool, {
+      agentDir: plugins.agentDir,
+      sessionId: plugins.sessionId,
+      hooks: plugins.hooks,
+    }),
+  )
+}
+
+function hasToolHooks(plugins: PluginSessionWiring | undefined): plugins is PluginSessionWiring {
+  if (!plugins) return false
+  return plugins.hooks.count('tool.before') > 0 || plugins.hooks.count('tool.after') > 0
+}
+
+function wrapSubagentCustomTools(
+  selection: PluginSubagentSelection,
+  plugins: PluginSessionWiring | undefined,
+): ToolDefinition[] {
+  if (!selection.customTools || !plugins) return []
+  const logger = makePluginLogger(selection.pluginName)
+  return selection.customTools.map((tool, i) =>
+    wrapPluginTool(tool, {
+      pluginName: selection.pluginName,
+      toolName: `${selection.toolNamePrefix}_${i}`,
+      agentDir: plugins.agentDir,
+      sessionId: plugins.sessionId,
+      logger,
+      hooks: plugins.hooks,
+    }),
+  )
+}
+
+function makePluginLogger(pluginName: string) {
+  const prefix = `[plugin:${pluginName}]`
+  return {
+    info: (m: string) => console.log(`${prefix} ${m}`),
+    warn: (m: string) => console.warn(`${prefix} ${m}`),
+    error: (m: string) => console.error(`${prefix} ${m}`),
+  }
+}
+
+export async function createOverrideResourceLoader(
+  systemPrompt: string,
+  origin?: SessionOrigin,
+): Promise<DefaultResourceLoader> {
+  const loader = new DefaultResourceLoader({
+    systemPromptOverride: () => withOrigin(systemPrompt, origin),
+    appendSystemPromptOverride: () => [],
+  })
+  await loader.reload()
+  return loader
+}
+
+export type CreateResourceLoaderOptions = {
+  agentDir?: string
+  plugins?: PluginSessionWiring
+  materializedSkills?: MaterializedSkills | null
+  origin?: SessionOrigin
+}
+
+export async function createResourceLoader(options: CreateResourceLoaderOptions = {}): Promise<DefaultResourceLoader> {
+  const agentDir = options.agentDir ?? process.cwd()
+  const self = await loadSelf(agentDir)
+  let systemPrompt = `${DEFAULT_SYSTEM_PROMPT}\n\n${self}`
+
+  if (options.plugins) {
+    const event = { prompt: systemPrompt, sessionId: options.plugins.sessionId, agentDir, origin: options.origin }
+    await options.plugins.hooks.runSessionPrompt(event)
+    systemPrompt = event.prompt
+  }
+
+  // Appended last so the dirty-files snapshot is the most-recent context the
+  // agent reads, and so its bytes sit in the cache-suffix region rather than
+  // splitting the cacheable prefix shared by clean-worktree sessions.
+  const gitNudge = await renderGitNudge(agentDir)
+  if (gitNudge !== '') {
+    systemPrompt = `${systemPrompt}\n\n${gitNudge}`
+  }
+
+  const additionalSkillPaths = [getBundledSkillsDir()]
+  // pi-coding-agent's DefaultResourceLoader auto-discovers <agentDir>/skills/
+  // but not <agentDir>/.agents/skills/. We do not scaffold <agentDir>/skills/
+  // and the system prompt no longer advertises it — the only skill directories
+  // a TypeClaw agent owns are .agents/skills/ (user-installed) and
+  // memory/skills/ (dreaming-owned). Both are wired in explicitly below;
+  // anything the upstream loader auto-discovers under <agentDir>/skills/ is
+  // outside our supported surface.
+  const userInstalledSkillsDir = join(agentDir, '.agents', 'skills')
+  if (existsSync(userInstalledSkillsDir)) {
+    additionalSkillPaths.push(userInstalledSkillsDir)
+  }
+  // Muscle-memory skills written by the dreaming subagent. Same auto-discover
+  // story as `.agents/skills/` — the loader doesn't walk arbitrary subtrees of
+  // the agent dir, so we wire this in explicitly. Existence-gated so a session
+  // that has never dreamed doesn't pay for an empty path.
+  const muscleMemorySkillsDir = join(agentDir, 'memory', 'skills')
+  if (existsSync(muscleMemorySkillsDir)) {
+    additionalSkillPaths.push(muscleMemorySkillsDir)
+  }
+  if (options.plugins) {
+    for (const dir of options.plugins.registry.skillsDirs) {
+      additionalSkillPaths.push(dir.path)
+    }
+  }
+  if (options.materializedSkills) {
+    additionalSkillPaths.push(options.materializedSkills.dir)
+  }
+
+  const loader = new DefaultResourceLoader({
+    systemPromptOverride: () => withOrigin(systemPrompt, options.origin),
+    appendSystemPromptOverride: () => [],
+    additionalSkillPaths,
+  })
+  await loader.reload()
+  return loader
+}
+
+function withOrigin(systemPrompt: string, origin: SessionOrigin | undefined): string {
+  if (!origin) return systemPrompt
+  return `${systemPrompt}\n\n${renderSessionOrigin(origin)}`
+}
+
+export function getBundledSkillsDir(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), '..', 'skills')
+}