typeclaw 0.1.0

package/src/agent/tools/restart.ts

@@ -0,0 +1,122 @@
+import { Type } from '@mariozechner/pi-ai'
+import { defineTool } from '@mariozechner/pi-coding-agent'
+
+import { send, sendHttp } from '@/hostd/client'
+import { containerSocketPath } from '@/hostd/paths'
+import type { Stream } from '@/stream'
+
+const ACK_TIMEOUT_MS = 5_000
+const EXIT_DELAY_MS = 500
+
+export type CreateRestartToolOptions = {
+  containerName: string
+  exit?: (code: number) => void
+  socketPath?: string
+  hostdUrl?: string
+  hostdToken?: string
+  // Optional so unit tests and ad-hoc tool construction keep working without
+  // building a Stream. In production wiring, every live AgentSession's
+  // broadcast subscriber turns this signal into a transcript entry.
+  stream?: Stream
+  // Identifies the session whose `restart` tool execution fired the broadcast.
+  // Subscribers compare against their own SessionManager.getSessionId() to
+  // pick the right notice variant (proactive-confirmation for the originator,
+  // do-not-acknowledge for siblings). Required when stream is set; without it
+  // every session would get the sibling notice and the originator would never
+  // confirm restart completion proactively — the exact bug this dispatch
+  // fixes. Required even when stream is absent so the type stays simple and
+  // the field's presence documents the runtime contract.
+  originatingSessionId: string
+}
+
+export type RestartToolDetails = { ok: boolean; containerName: string; reason?: string }
+
+export type ContainerRestartingBroadcast = {
+  kind: 'container-restarting'
+  restartedAt: string
+  originatingSessionId: string
+}
+
+export function createRestartTool({
+  containerName,
+  exit,
+  socketPath,
+  hostdUrl,
+  hostdToken,
+  stream,
+  originatingSessionId,
+}: CreateRestartToolOptions) {
+  const doExit = exit ?? ((code: number) => process.exit(code))
+  const httpUrl = hostdUrl ?? process.env.TYPECLAW_HOSTD_URL
+  const httpToken = hostdToken ?? process.env.TYPECLAW_HOSTD_TOKEN
+
+  return defineTool({
+    name: 'restart',
+    label: 'Restart Container',
+    description:
+      'Restart the typeclaw container this agent is running in. The host daemon ACKs the request, ' +
+      'this process exits, and the host daemon then runs `typeclaw stop` followed by `typeclaw start` ' +
+      'for the agent folder. Use when on-disk source has changed in a way that `reload` cannot pick up — ' +
+      'e.g. the typeclaw CLI itself was updated, the Dockerfile template changed, or a boot-only config ' +
+      'field needs to take effect (port, mounts, plugins). The current session is lost; the ' +
+      'TUI must reconnect after the new container is up. Pass `build: true` to also rebuild the ' +
+      'Docker image (equivalent to `typeclaw restart --build`) — required when a dependency in the ' +
+      'Dockerfile template changed but the image already exists, since `start` only rebuilds if the ' +
+      'image is missing or `build` is set.',
+    parameters: Type.Object({
+      build: Type.Optional(
+        Type.Boolean({
+          description:
+            'When true, rebuild the Docker image (`docker build`) before starting the new container. ' +
+            'Default false (reuse the existing image if present). Set this when the Dockerfile template ' +
+            'or its inputs have changed since the image was last built.',
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      const build = params.build === true
+      const request = { kind: 'restart' as const, containerName, build }
+      const reply =
+        httpUrl && httpToken
+          ? await sendHttp(request, { timeoutMs: ACK_TIMEOUT_MS, url: httpUrl, token: httpToken })
+          : await send(request, { timeoutMs: ACK_TIMEOUT_MS, socket: socketPath ?? containerSocketPath() })
+      if (!reply.ok) {
+        const details: RestartToolDetails = { ok: false, containerName, reason: reply.reason }
+        return {
+          content: [{ type: 'text' as const, text: `restart denied: ${reply.reason}` }],
+          details,
+        }
+      }
+
+      // Hostd ACK == restart is committed. Fan out the notice to every live
+      // session BEFORE arming the exit timer. Stream broker delivery is
+      // synchronous (broker.ts deliver()) and SessionManager.appendCustomMessageEntry
+      // does a synchronous JSONL write, so the fan-out completes inside this
+      // tick — well before the EXIT_DELAY_MS timer fires.
+      const broadcast: ContainerRestartingBroadcast = {
+        kind: 'container-restarting',
+        restartedAt: new Date().toISOString(),
+        originatingSessionId,
+      }
+      stream?.publish({ target: { kind: 'broadcast' }, payload: broadcast })
+
+      // Schedule the exit on the next tick so the tool result is delivered to
+      // the model before the process dies. The host daemon polls for the
+      // container's removal before re-running `start`, so a small delay here
+      // does not gate the restart end-to-end.
+      setTimeout(() => doExit(0), EXIT_DELAY_MS)
+
+      const details: RestartToolDetails = { ok: true, containerName }
+      const buildSuffix = build ? ' (with image rebuild)' : ''
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `restart${buildSuffix} scheduled for ${containerName}; this process will exit shortly and a new container will be started by the host daemon.`,
+          },
+        ],
+        details,
+      }
+    },
+  })
+}

package/src/agent/tools/stream-snapshot.ts

@@ -0,0 +1,181 @@
+import { Type } from '@mariozechner/pi-ai'
+import { defineTool } from '@mariozechner/pi-coding-agent'
+
+import { formatLocalDateTime } from '@/shared'
+import type { ScanFilter, Stream, StreamMessage, TargetFilter } from '@/stream'
+
+const DEFAULT_LIMIT = 50
+const MAX_LIMIT = 100
+const MAX_PAYLOAD_SUMMARY_CHARS = 200
+
+const TARGET_KINDS = ['broadcast', 'session', 'new-session', 'cron'] as const
+type TargetKind = (typeof TARGET_KINDS)[number]
+
+export type CreateStreamSnapshotToolOptions = {
+  stream: Stream
+}
+
+export function createStreamSnapshotTool({ stream }: CreateStreamSnapshotToolOptions) {
+  return defineTool({
+    name: 'stream_snapshot',
+    label: 'Stream Snapshot',
+    description:
+      'Snapshot recent activity on the in-process message stream that connects the WS server, cron scheduler, and any subagents. ' +
+      'Useful for: confirming a cron job actually fired, seeing what user prompts arrived recently, observing broadcast notifications, ' +
+      'or debugging why something did not happen. Read-only — this tool cannot publish messages. Returns the most recent N events ' +
+      'matching the optional filter (target_kind, target_id, since_ms_ago).',
+    parameters: Type.Object({
+      target_kind: Type.Optional(
+        Type.Union(
+          TARGET_KINDS.map((k) => Type.Literal(k)),
+          { description: 'Filter to a specific target kind. Omit to see all targets.' },
+        ),
+      ),
+      target_id: Type.Optional(
+        Type.String({
+          description:
+            'Pin to a specific session id (session), subagent name (new-session), or job id (cron). Ignored for broadcast.',
+        }),
+      ),
+      since_ms_ago: Type.Optional(
+        Type.Integer({
+          description: 'Only return events from the last N milliseconds. Defaults to no time filter.',
+          minimum: 1,
+        }),
+      ),
+      limit: Type.Optional(
+        Type.Integer({
+          description: `Max number of events to return (1-${MAX_LIMIT}, default ${DEFAULT_LIMIT}). Most recent are kept.`,
+          minimum: 1,
+          maximum: MAX_LIMIT,
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const limit = clampLimit(params.limit)
+      const filter = buildFilter(params.target_kind, params.target_id, params.since_ms_ago, limit)
+      const events = stream.scan(filter)
+      return formatResult(events, params)
+    },
+  })
+}
+
+function clampLimit(value: number | undefined): number {
+  if (value === undefined) return DEFAULT_LIMIT
+  return Math.min(Math.max(1, Math.floor(value)), MAX_LIMIT)
+}
+
+function buildFilter(
+  kind: TargetKind | undefined,
+  id: string | undefined,
+  sinceMsAgo: number | undefined,
+  limit: number,
+): ScanFilter {
+  const filter: ScanFilter = { limit }
+  if (kind !== undefined) filter.target = buildTargetFilter(kind, id)
+  if (sinceMsAgo !== undefined) filter.sinceTs = Date.now() - sinceMsAgo
+  return filter
+}
+
+function buildTargetFilter(kind: TargetKind, id: string | undefined): TargetFilter {
+  switch (kind) {
+    case 'broadcast':
+      return { kind }
+    case 'session':
+      return id !== undefined ? { kind, sessionId: id } : { kind }
+    case 'new-session':
+      return id !== undefined ? { kind, subagent: id } : { kind }
+    case 'cron':
+      return id !== undefined ? { kind, jobId: id } : { kind }
+  }
+}
+
+function formatResult(
+  events: StreamMessage[],
+  params: { target_kind?: TargetKind; target_id?: string; since_ms_ago?: number; limit?: number },
+) {
+  const filterDesc = describeFilter(params)
+  const details = {
+    count: events.length,
+    filter: filterDesc,
+    events: events.map((e) => ({
+      id: e.id,
+      ts: e.ts,
+      target: e.target,
+      payload: e.payload,
+      ...(e.replyTo !== undefined ? { replyTo: e.replyTo } : {}),
+      ...(e.meta !== undefined ? { meta: e.meta } : {}),
+    })),
+  }
+
+  if (events.length === 0) {
+    return {
+      content: [{ type: 'text' as const, text: `No stream events matching ${filterDesc}.` }],
+      details,
+    }
+  }
+
+  const header = `${events.length} stream event(s) matching ${filterDesc} (oldest → newest):`
+  const lines = [header, '']
+  for (const event of events) {
+    lines.push(formatEventLine(event))
+  }
+  return {
+    content: [{ type: 'text' as const, text: lines.join('\n').trimEnd() }],
+    details,
+  }
+}
+
+function describeFilter(params: {
+  target_kind?: TargetKind
+  target_id?: string
+  since_ms_ago?: number
+  limit?: number
+}): string {
+  const parts: string[] = []
+  if (params.target_kind !== undefined) {
+    parts.push(
+      params.target_id !== undefined
+        ? `target=${params.target_kind}:${params.target_id}`
+        : `target=${params.target_kind}`,
+    )
+  }
+  if (params.since_ms_ago !== undefined) parts.push(`since=${params.since_ms_ago}ms`)
+  if (params.limit !== undefined) parts.push(`limit=${params.limit}`)
+  return parts.length === 0 ? 'all (default limit)' : parts.join(', ')
+}
+
+function formatEventLine(event: StreamMessage): string {
+  const time = formatLocalDateTime(new Date(event.ts))
+  const targetLabel = describeTarget(event.target)
+  const payloadSummary = summarizePayload(event.payload)
+  const replyMarker = event.replyTo !== undefined ? ` [reply→${event.replyTo}]` : ''
+  return `${time}  ${targetLabel}${replyMarker}  ${payloadSummary}`
+}
+
+function describeTarget(target: StreamMessage['target']): string {
+  switch (target.kind) {
+    case 'broadcast':
+      return 'broadcast'
+    case 'session':
+      return `session:${target.sessionId}`
+    case 'new-session':
+      return `new-session:${target.subagent}`
+    case 'cron':
+      return `cron:${target.jobId}`
+  }
+}
+
+function summarizePayload(payload: unknown): string {
+  let text: string
+  try {
+    text = typeof payload === 'string' ? payload : JSON.stringify(payload)
+  } catch {
+    text = '<unserializable>'
+  }
+  if (text.length > MAX_PAYLOAD_SUMMARY_CHARS) {
+    return `${text.slice(0, MAX_PAYLOAD_SUMMARY_CHARS)}… (${text.length} chars)`
+  }
+  return text
+}

package/src/agent/tools/webfetch/fetch.ts

@@ -0,0 +1,102 @@
+import { MAX_RESPONSE_BYTES } from './types'
+
+export type FetchResult = {
+  body: string
+  contentType: string
+  finalUrl: string
+  httpStatus: number
+  bytesIn: number
+}
+
+export class WebfetchError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'WebfetchError'
+  }
+}
+
+const DEFAULT_HEADERS: Record<string, string> = {
+  'User-Agent': 'typeclaw/0 (+https://github.com/code-yeongyu/typeclaw)',
+  Accept: 'text/html,application/xhtml+xml,application/json;q=0.9,text/plain;q=0.8,*/*;q=0.1',
+  'Accept-Language': 'en-US,en;q=0.9',
+}
+
+export function normalizeUrl(input: string): string {
+  const trimmed = input.trim()
+  if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) {
+    if (!trimmed.startsWith('http://') && !trimmed.startsWith('https://')) {
+      throw new WebfetchError('URL must use http:// or https://')
+    }
+    return trimmed
+  }
+  return `https://${trimmed}`
+}
+
+export async function fetchWithLimits(
+  url: string,
+  timeoutSeconds: number,
+  parentSignal?: AbortSignal,
+): Promise<FetchResult> {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(new Error('timeout')), timeoutSeconds * 1000)
+  const onAbort = () => controller.abort(parentSignal?.reason)
+  parentSignal?.addEventListener('abort', onAbort, { once: true })
+
+  try {
+    const response = await fetch(url, { headers: DEFAULT_HEADERS, signal: controller.signal, redirect: 'follow' })
+    if (!response.ok) {
+      throw new WebfetchError(`Fetch failed: HTTP ${response.status} ${response.statusText}`)
+    }
+
+    const contentLengthHeader = response.headers.get('content-length')
+    if (contentLengthHeader) {
+      const declared = Number(contentLengthHeader)
+      if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
+        throw new WebfetchError(
+          `Response too large (${formatBytes(declared)} exceeds ${formatBytes(MAX_RESPONSE_BYTES)} limit)`,
+        )
+      }
+    }
+
+    const buffer = await response.arrayBuffer()
+    if (buffer.byteLength > MAX_RESPONSE_BYTES) {
+      throw new WebfetchError(
+        `Response too large (${formatBytes(buffer.byteLength)} exceeds ${formatBytes(MAX_RESPONSE_BYTES)} limit)`,
+      )
+    }
+
+    const body = new TextDecoder('utf-8', { fatal: false }).decode(buffer)
+    return {
+      body,
+      contentType: response.headers.get('content-type') ?? '',
+      finalUrl: response.url || url,
+      httpStatus: response.status,
+      bytesIn: buffer.byteLength,
+    }
+  } catch (error) {
+    if (
+      controller.signal.aborted &&
+      controller.signal.reason instanceof Error &&
+      controller.signal.reason.message === 'timeout'
+    ) {
+      throw new WebfetchError(`Request timed out after ${timeoutSeconds}s`)
+    }
+    if (error instanceof WebfetchError) throw error
+    const message = error instanceof Error ? error.message : String(error)
+    throw new WebfetchError(`Fetch failed: ${message}`)
+  } finally {
+    clearTimeout(timeout)
+    parentSignal?.removeEventListener('abort', onAbort)
+  }
+}
+
+export function parseMimeType(contentType: string): string {
+  const semi = contentType.indexOf(';')
+  return (semi >= 0 ? contentType.slice(0, semi) : contentType).trim().toLowerCase()
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`
+}

package/src/agent/tools/webfetch/index.ts

@@ -0,0 +1 @@
+export { webfetchTool } from './tool'

package/src/agent/tools/webfetch/strategies/grep.ts

@@ -0,0 +1,70 @@
+export type GrepOptions = {
+  pattern: string
+  before?: number
+  after?: number
+  limit?: number
+  offset?: number
+}
+
+export class GrepError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'GrepError'
+  }
+}
+
+export function applyGrep(content: string, options: GrepOptions): string {
+  const before = Math.max(0, options.before ?? 0)
+  const after = Math.max(0, options.after ?? 0)
+  const limit = Math.max(1, options.limit ?? 100)
+  const offset = Math.max(0, options.offset ?? 0)
+
+  const matcher = compile(options.pattern)
+  const lines = content.split('\n')
+
+  const matchingIndices: number[] = []
+  for (let i = 0; i < lines.length; i++) {
+    if (matcher.test(lines[i] ?? '')) matchingIndices.push(i)
+  }
+
+  if (matchingIndices.length === 0) {
+    return `No matches for pattern: ${options.pattern}`
+  }
+
+  const contextIndices = new Set<number>()
+  for (const idx of matchingIndices) {
+    const start = Math.max(0, idx - before)
+    const end = Math.min(lines.length - 1, idx + after)
+    for (let i = start; i <= end; i++) contextIndices.add(i)
+  }
+  const sorted = Array.from(contextIndices).sort((a, b) => a - b)
+  const page = sorted.slice(offset, offset + limit)
+
+  const matching = new Set(matchingIndices)
+  const out: string[] = []
+  let prev = -2
+  for (const idx of page) {
+    if (prev !== -2 && idx > prev + 1) out.push('--')
+    prev = idx
+    const sep = matching.has(idx) ? ':' : '-'
+    out.push(`${idx + 1}${sep}${lines[idx] ?? ''}`)
+  }
+
+  const totalMatches = matchingIndices.length
+  const shown = page.length
+  const totalContext = sorted.length
+  const header = `Found ${totalMatches} matching line(s); showing ${shown} of ${totalContext} context line(s).`
+  return `${header}\n${out.join('\n')}`
+}
+
+// Always build a fresh, non-global RegExp. The `g` flag carries `lastIndex`
+// state across `.test()` calls, which silently skips matches when reused in a
+// loop (oh-my-openagent PR #195 hit this exact bug).
+function compile(pattern: string): RegExp {
+  try {
+    return new RegExp(pattern, 'i')
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new GrepError(`Invalid regex pattern: ${message}`)
+  }
+}

package/src/agent/tools/webfetch/strategies/jq.ts

@@ -0,0 +1,31 @@
+import { raw } from 'jq-wasm'
+
+export class JqError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'JqError'
+  }
+}
+
+export async function applyJq(content: string, query: string): Promise<string> {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(content)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new JqError(`Response is not valid JSON: ${message}`)
+  }
+
+  try {
+    const result = await raw(parsed as string | object, query)
+    if (result.exitCode !== 0 || result.stderr) {
+      const detail = result.stderr.trim() || `exit code ${result.exitCode}`
+      throw new JqError(`jq query failed: ${detail}`)
+    }
+    return result.stdout.replace(/\n+$/, '')
+  } catch (error) {
+    if (error instanceof JqError) throw error
+    const message = error instanceof Error ? error.message : String(error)
+    throw new JqError(`jq query failed: ${message}`)
+  }
+}

package/src/agent/tools/webfetch/strategies/raw.ts

@@ -0,0 +1,3 @@
+export function applyRaw(content: string): string {
+  return content
+}

package/src/agent/tools/webfetch/strategies/readability.ts

@@ -0,0 +1,30 @@
+import { Readability } from '@mozilla/readability'
+import { JSDOM } from 'jsdom'
+import TurndownService from 'turndown'
+
+const turndown = new TurndownService({
+  headingStyle: 'atx',
+  codeBlockStyle: 'fenced',
+  bulletListMarker: '-',
+  emDelimiter: '*',
+  hr: '---',
+})
+turndown.remove(['script', 'style', 'meta', 'link', 'noscript', 'iframe'])
+
+type ReadabilityDocument = ConstructorParameters<typeof Readability>[0]
+
+export function applyReadability(html: string, url: string): string {
+  const dom = new JSDOM(html, { url })
+  const document = dom.window.document.cloneNode(true) as unknown as ReadabilityDocument
+  const article = new Readability(document).parse()
+
+  const source = article?.content?.trim() ? article.content : html
+  const markdown = turndown.turndown(source).trim()
+
+  if (!markdown) return 'Readability extracted no content from this page.'
+
+  if (article?.title) {
+    return `# ${article.title}\n\n${markdown}`
+  }
+  return markdown
+}

package/src/agent/tools/webfetch/strategies/selector.ts

@@ -0,0 +1,41 @@
+import * as cheerio from 'cheerio'
+
+export class SelectorError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'SelectorError'
+  }
+}
+
+export function applySelector(html: string, selector: string): string {
+  let $: cheerio.CheerioAPI
+  try {
+    $ = cheerio.load(html)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new SelectorError(`Failed to parse HTML: ${message}`)
+  }
+
+  let matches: cheerio.Cheerio<unknown>
+  try {
+    matches = $(selector) as unknown as cheerio.Cheerio<unknown>
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new SelectorError(`Invalid CSS selector "${selector}": ${message}`)
+  }
+
+  if (matches.length === 0) {
+    return `No elements matched selector: ${selector}`
+  }
+
+  const blocks: string[] = []
+  matches.each((index, element) => {
+    const text = $(element as Parameters<cheerio.CheerioAPI>[0])
+      .text()
+      .replace(/\s+/g, ' ')
+      .trim()
+    blocks.push(`[${index + 1}] ${text}`)
+  })
+
+  return `Matched ${matches.length} element(s) for "${selector}":\n${blocks.join('\n')}`
+}