@epoch-ai/cli 2.2.4

package/src/tool/tool.ts

@@ -0,0 +1,112 @@
+import z from "zod"
+import { Effect } from "effect"
+import type { MessageV2 } from "../session/message-v2"
+import type { Agent } from "../agent/agent"
+import type { Permission } from "../permission"
+import type { SessionID, MessageID } from "../session/schema"
+import { Truncate } from "./truncate"
+
+export namespace Tool {
+  interface Metadata {
+    [key: string]: any
+  }
+
+  export interface InitContext {
+    agent?: Agent.Info
+  }
+
+  export type Context<M extends Metadata = Metadata> = {
+    sessionID: SessionID
+    messageID: MessageID
+    agent: string
+    abort: AbortSignal
+    callID?: string
+    extra?: { [key: string]: any }
+    messages: MessageV2.WithParts[]
+    metadata(input: { title?: string; metadata?: M }): void
+    ask(input: Omit<Permission.Request, "id" | "sessionID" | "tool">): Promise<void>
+  }
+  export interface Def<Parameters extends z.ZodType = z.ZodType, M extends Metadata = Metadata> {
+    description: string
+    parameters: Parameters
+    execute(
+      args: z.infer<Parameters>,
+      ctx: Context,
+    ): Promise<{
+      title: string
+      metadata: M
+      output: string
+      attachments?: Omit<MessageV2.FilePart, "id" | "sessionID" | "messageID">[]
+    }>
+    formatValidationError?(error: z.ZodError): string
+  }
+
+  export interface Info<Parameters extends z.ZodType = z.ZodType, M extends Metadata = Metadata> {
+    id: string
+    init: (ctx?: InitContext) => Promise<Def<Parameters, M>>
+  }
+
+  export type InferParameters<T> =
+    T extends Info<infer P, any>
+      ? z.infer<P>
+      : T extends Effect.Effect<Info<infer P, any>, any, any>
+        ? z.infer<P>
+        : never
+  export type InferMetadata<T> =
+    T extends Info<any, infer M> ? M : T extends Effect.Effect<Info<any, infer M>, any, any> ? M : never
+
+  function wrap<Parameters extends z.ZodType, Result extends Metadata>(
+    id: string,
+    init: ((ctx?: InitContext) => Promise<Def<Parameters, Result>>) | Def<Parameters, Result>,
+  ) {
+    return async (initCtx?: InitContext) => {
+      const toolInfo = init instanceof Function ? await init(initCtx) : { ...init }
+      const execute = toolInfo.execute
+      toolInfo.execute = async (args, ctx) => {
+        try {
+          toolInfo.parameters.parse(args)
+        } catch (error) {
+          if (error instanceof z.ZodError && toolInfo.formatValidationError) {
+            throw new Error(toolInfo.formatValidationError(error), { cause: error })
+          }
+          throw new Error(
+            `The ${id} tool was called with invalid arguments: ${error}.\nPlease rewrite the input so it satisfies the expected schema.`,
+            { cause: error },
+          )
+        }
+        const result = await execute(args, ctx)
+        if (result.metadata.truncated !== undefined) {
+          return result
+        }
+        const truncated = await Truncate.output(result.output, {}, initCtx?.agent)
+        return {
+          ...result,
+          output: truncated.content,
+          metadata: {
+            ...result.metadata,
+            truncated: truncated.truncated,
+            ...(truncated.truncated && { outputPath: truncated.outputPath }),
+          },
+        }
+      }
+      return toolInfo
+    }
+  }
+
+  export function define<Parameters extends z.ZodType, Result extends Metadata>(
+    id: string,
+    init: ((ctx?: InitContext) => Promise<Def<Parameters, Result>>) | Def<Parameters, Result>,
+  ): Info<Parameters, Result> {
+    return {
+      id,
+      init: wrap(id, init),
+    }
+  }
+
+  export function defineEffect<Parameters extends z.ZodType, Result extends Metadata, R>(
+    id: string,
+    init: Effect.Effect<((ctx?: InitContext) => Promise<Def<Parameters, Result>>) | Def<Parameters, Result>, never, R>,
+  ): Effect.Effect<Info<Parameters, Result>, never, R> {
+    return Effect.map(init, (next) => ({ id, init: wrap(id, next) }))
+  }
+}

package/src/tool/truncate.ts

@@ -0,0 +1,144 @@
+import { NodePath } from "@effect/platform-node"
+import { Cause, Duration, Effect, Layer, Schedule, ServiceMap } from "effect"
+import path from "path"
+import type { Agent } from "../agent/agent"
+import { makeRuntime } from "@/effect/run-service"
+import { AppFileSystem } from "@/filesystem"
+import { evaluate } from "@/permission/evaluate"
+import { Identifier } from "../id/id"
+import { Log } from "../util/log"
+import { ToolID } from "./schema"
+import { TRUNCATION_DIR } from "./truncation-dir"
+
+export namespace Truncate {
+  const log = Log.create({ service: "truncation" })
+  const RETENTION = Duration.days(7)
+
+  export const MAX_LINES = 2000
+  export const MAX_BYTES = 50 * 1024
+  export const DIR = TRUNCATION_DIR
+  export const GLOB = path.join(TRUNCATION_DIR, "*")
+
+  export type Result = { content: string; truncated: false } | { content: string; truncated: true; outputPath: string }
+
+  export interface Options {
+    maxLines?: number
+    maxBytes?: number
+    direction?: "head" | "tail"
+  }
+
+  function hasTaskTool(agent?: Agent.Info) {
+    if (!agent?.permission) return false
+    return evaluate("task", "*", agent.permission).action !== "deny"
+  }
+
+  export interface Interface {
+    readonly cleanup: () => Effect.Effect<void>
+    /**
+     * Returns output unchanged when it fits within the limits, otherwise writes the full text
+     * to the truncation directory and returns a preview plus a hint to inspect the saved file.
+     */
+    readonly output: (text: string, options?: Options, agent?: Agent.Info) => Effect.Effect<Result>
+  }
+
+  export class Service extends ServiceMap.Service<Service, Interface>()("@epochcli/Truncate") {}
+
+  export const layer = Layer.effect(
+    Service,
+    Effect.gen(function* () {
+      const fs = yield* AppFileSystem.Service
+
+      const cleanup = Effect.fn("Truncate.cleanup")(function* () {
+        const cutoff = Identifier.timestamp(Identifier.create("tool", false, Date.now() - Duration.toMillis(RETENTION)))
+        const entries = yield* fs.readDirectory(TRUNCATION_DIR).pipe(
+          Effect.map((all) => all.filter((name) => name.startsWith("tool_"))),
+          Effect.catch(() => Effect.succeed([])),
+        )
+        for (const entry of entries) {
+          if (Identifier.timestamp(entry) >= cutoff) continue
+          yield* fs.remove(path.join(TRUNCATION_DIR, entry)).pipe(Effect.catch(() => Effect.void))
+        }
+      })
+
+      const output = Effect.fn("Truncate.output")(function* (text: string, options: Options = {}, agent?: Agent.Info) {
+        const maxLines = options.maxLines ?? MAX_LINES
+        const maxBytes = options.maxBytes ?? MAX_BYTES
+        const direction = options.direction ?? "head"
+        const lines = text.split("\n")
+        const totalBytes = Buffer.byteLength(text, "utf-8")
+
+        if (lines.length <= maxLines && totalBytes <= maxBytes) {
+          return { content: text, truncated: false } as const
+        }
+
+        const out: string[] = []
+        let i = 0
+        let bytes = 0
+        let hitBytes = false
+
+        if (direction === "head") {
+          for (i = 0; i < lines.length && i < maxLines; i++) {
+            const size = Buffer.byteLength(lines[i], "utf-8") + (i > 0 ? 1 : 0)
+            if (bytes + size > maxBytes) {
+              hitBytes = true
+              break
+            }
+            out.push(lines[i])
+            bytes += size
+          }
+        } else {
+          for (i = lines.length - 1; i >= 0 && out.length < maxLines; i--) {
+            const size = Buffer.byteLength(lines[i], "utf-8") + (out.length > 0 ? 1 : 0)
+            if (bytes + size > maxBytes) {
+              hitBytes = true
+              break
+            }
+            out.unshift(lines[i])
+            bytes += size
+          }
+        }
+
+        const removed = hitBytes ? totalBytes - bytes : lines.length - out.length
+        const unit = hitBytes ? "bytes" : "lines"
+        const preview = out.join("\n")
+        const file = path.join(TRUNCATION_DIR, ToolID.ascending())
+
+        yield* fs.ensureDir(TRUNCATION_DIR).pipe(Effect.orDie)
+        yield* fs.writeFileString(file, text).pipe(Effect.orDie)
+
+        const hint = hasTaskTool(agent)
+          ? `The tool call succeeded but the output was truncated. Full output saved to: ${file}\nUse the Task tool to have explore agent process this file with Grep and Read (with offset/limit). Do NOT read the full file yourself - delegate to save context.`
+          : `The tool call succeeded but the output was truncated. Full output saved to: ${file}\nUse Grep to search the full content or Read with offset/limit to view specific sections.`
+
+        return {
+          content:
+            direction === "head"
+              ? `${preview}\n\n...${removed} ${unit} truncated...\n\n${hint}`
+              : `...${removed} ${unit} truncated...\n\n${hint}\n\n${preview}`,
+          truncated: true,
+          outputPath: file,
+        } as const
+      })
+
+      yield* cleanup().pipe(
+        Effect.catchCause((cause) => {
+          log.error("truncation cleanup failed", { cause: Cause.pretty(cause) })
+          return Effect.void
+        }),
+        Effect.repeat(Schedule.spaced(Duration.hours(1))),
+        Effect.delay(Duration.minutes(1)),
+        Effect.forkScoped,
+      )
+
+      return Service.of({ cleanup, output })
+    }),
+  )
+
+  export const defaultLayer = layer.pipe(Layer.provide(AppFileSystem.defaultLayer), Layer.provide(NodePath.layer))
+
+  const { runPromise } = makeRuntime(Service, defaultLayer)
+
+  export async function output(text: string, options: Options = {}, agent?: Agent.Info): Promise<Result> {
+    return runPromise((s) => s.output(text, options, agent))
+  }
+}

package/src/tool/truncation-dir.ts

@@ -0,0 +1,4 @@
+import path from "path"
+import { Global } from "../global"
+
+export const TRUNCATION_DIR = path.join(Global.Path.data, "tool-output")

package/src/tool/webfetch.ts

@@ -0,0 +1,206 @@
+import z from "zod"
+import { Tool } from "./tool"
+import TurndownService from "turndown"
+import DESCRIPTION from "./webfetch.txt"
+import { abortAfterAny } from "../util/abort"
+
+const MAX_RESPONSE_SIZE = 5 * 1024 * 1024 // 5MB
+const DEFAULT_TIMEOUT = 30 * 1000 // 30 seconds
+const MAX_TIMEOUT = 120 * 1000 // 2 minutes
+
+export const WebFetchTool = Tool.define("webfetch", {
+  description: DESCRIPTION,
+  parameters: z.object({
+    url: z.string().describe("The URL to fetch content from"),
+    format: z
+      .enum(["text", "markdown", "html"])
+      .default("markdown")
+      .describe("The format to return the content in (text, markdown, or html). Defaults to markdown."),
+    timeout: z.number().describe("Optional timeout in seconds (max 120)").optional(),
+  }),
+  async execute(params, ctx) {
+    // Validate URL
+    if (!params.url.startsWith("http://") && !params.url.startsWith("https://")) {
+      throw new Error("URL must start with http:// or https://")
+    }
+
+    await ctx.ask({
+      permission: "webfetch",
+      patterns: [params.url],
+      always: ["*"],
+      metadata: {
+        url: params.url,
+        format: params.format,
+        timeout: params.timeout,
+      },
+    })
+
+    const timeout = Math.min((params.timeout ?? DEFAULT_TIMEOUT / 1000) * 1000, MAX_TIMEOUT)
+
+    const { signal, clearTimeout } = abortAfterAny(timeout, ctx.abort)
+
+    // Build Accept header based on requested format with q parameters for fallbacks
+    let acceptHeader = "*/*"
+    switch (params.format) {
+      case "markdown":
+        acceptHeader = "text/markdown;q=1.0, text/x-markdown;q=0.9, text/plain;q=0.8, text/html;q=0.7, */*;q=0.1"
+        break
+      case "text":
+        acceptHeader = "text/plain;q=1.0, text/markdown;q=0.9, text/html;q=0.8, */*;q=0.1"
+        break
+      case "html":
+        acceptHeader = "text/html;q=1.0, application/xhtml+xml;q=0.9, text/plain;q=0.8, text/markdown;q=0.7, */*;q=0.1"
+        break
+      default:
+        acceptHeader =
+          "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8"
+    }
+    const headers = {
+      "User-Agent":
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
+      Accept: acceptHeader,
+      "Accept-Language": "en-US,en;q=0.9",
+    }
+
+    const initial = await fetch(params.url, { signal, headers })
+
+    // Retry with honest UA if blocked by Cloudflare bot detection (TLS fingerprint mismatch)
+    const response =
+      initial.status === 403 && initial.headers.get("cf-mitigated") === "challenge"
+        ? await fetch(params.url, { signal, headers: { ...headers, "User-Agent": "epochcli" } })
+        : initial
+
+    clearTimeout()
+
+    if (!response.ok) {
+      throw new Error(`Request failed with status code: ${response.status}`)
+    }
+
+    // Check content length
+    const contentLength = response.headers.get("content-length")
+    if (contentLength && parseInt(contentLength) > MAX_RESPONSE_SIZE) {
+      throw new Error("Response too large (exceeds 5MB limit)")
+    }
+
+    const arrayBuffer = await response.arrayBuffer()
+    if (arrayBuffer.byteLength > MAX_RESPONSE_SIZE) {
+      throw new Error("Response too large (exceeds 5MB limit)")
+    }
+
+    const contentType = response.headers.get("content-type") || ""
+    const mime = contentType.split(";")[0]?.trim().toLowerCase() || ""
+    const title = `${params.url} (${contentType})`
+
+    // Check if response is an image
+    const isImage = mime.startsWith("image/") && mime !== "image/svg+xml" && mime !== "image/vnd.fastbidsheet"
+
+    if (isImage) {
+      const base64Content = Buffer.from(arrayBuffer).toString("base64")
+      return {
+        title,
+        output: "Image fetched successfully",
+        metadata: {},
+        attachments: [
+          {
+            type: "file",
+            mime,
+            url: `data:${mime};base64,${base64Content}`,
+          },
+        ],
+      }
+    }
+
+    const content = new TextDecoder().decode(arrayBuffer)
+
+    // Handle content based on requested format and actual content type
+    switch (params.format) {
+      case "markdown":
+        if (contentType.includes("text/html")) {
+          const markdown = convertHTMLToMarkdown(content)
+          return {
+            output: markdown,
+            title,
+            metadata: {},
+          }
+        }
+        return {
+          output: content,
+          title,
+          metadata: {},
+        }
+
+      case "text":
+        if (contentType.includes("text/html")) {
+          const text = await extractTextFromHTML(content)
+          return {
+            output: text,
+            title,
+            metadata: {},
+          }
+        }
+        return {
+          output: content,
+          title,
+          metadata: {},
+        }
+
+      case "html":
+        return {
+          output: content,
+          title,
+          metadata: {},
+        }
+
+      default:
+        return {
+          output: content,
+          title,
+          metadata: {},
+        }
+    }
+  },
+})
+
+async function extractTextFromHTML(html: string) {
+  let text = ""
+  let skipContent = false
+
+  const rewriter = new HTMLRewriter()
+    .on("script, style, noscript, iframe, object, embed", {
+      element() {
+        skipContent = true
+      },
+      text() {
+        // Skip text content inside these elements
+      },
+    })
+    .on("*", {
+      element(element) {
+        // Reset skip flag when entering other elements
+        if (!["script", "style", "noscript", "iframe", "object", "embed"].includes(element.tagName)) {
+          skipContent = false
+        }
+      },
+      text(input) {
+        if (!skipContent) {
+          text += input.text
+        }
+      },
+    })
+    .transform(new Response(html))
+
+  await rewriter.text()
+  return text.trim()
+}
+
+function convertHTMLToMarkdown(html: string): string {
+  const turndownService = new TurndownService({
+    headingStyle: "atx",
+    hr: "---",
+    bulletListMarker: "-",
+    codeBlockStyle: "fenced",
+    emDelimiter: "*",
+  })
+  turndownService.remove(["script", "style", "meta", "link"])
+  return turndownService.turndown(html)
+}

package/src/tool/webfetch.txt

@@ -0,0 +1 @@
+Fetch content from a URL. Supported formats: markdown, text, html.

package/src/tool/websearch.ts

@@ -0,0 +1,150 @@
+import z from "zod"
+import { Tool } from "./tool"
+import DESCRIPTION from "./websearch.txt"
+import { abortAfterAny } from "../util/abort"
+
+const API_CONFIG = {
+  BASE_URL: "https://mcp.exa.ai",
+  ENDPOINTS: {
+    SEARCH: "/mcp",
+  },
+  DEFAULT_NUM_RESULTS: 8,
+} as const
+
+interface McpSearchRequest {
+  jsonrpc: string
+  id: number
+  method: string
+  params: {
+    name: string
+    arguments: {
+      query: string
+      numResults?: number
+      livecrawl?: "fallback" | "preferred"
+      type?: "auto" | "fast" | "deep"
+      contextMaxCharacters?: number
+    }
+  }
+}
+
+interface McpSearchResponse {
+  jsonrpc: string
+  result: {
+    content: Array<{
+      type: string
+      text: string
+    }>
+  }
+}
+
+export const WebSearchTool = Tool.define("websearch", async () => {
+  return {
+    get description() {
+      return DESCRIPTION.replace("{{year}}", new Date().getFullYear().toString())
+    },
+    parameters: z.object({
+      query: z.string().describe("Websearch query"),
+      numResults: z.number().optional().describe("Number of search results to return (default: 8)"),
+      livecrawl: z
+        .enum(["fallback", "preferred"])
+        .optional()
+        .describe(
+          "Live crawl mode - 'fallback': use live crawling as backup if cached content unavailable, 'preferred': prioritize live crawling (default: 'fallback')",
+        ),
+      type: z
+        .enum(["auto", "fast", "deep"])
+        .optional()
+        .describe(
+          "Search type - 'auto': balanced search (default), 'fast': quick results, 'deep': comprehensive search",
+        ),
+      contextMaxCharacters: z
+        .number()
+        .optional()
+        .describe("Maximum characters for context string optimized for LLMs (default: 10000)"),
+    }),
+    async execute(params, ctx) {
+      await ctx.ask({
+        permission: "websearch",
+        patterns: [params.query],
+        always: ["*"],
+        metadata: {
+          query: params.query,
+          numResults: params.numResults,
+          livecrawl: params.livecrawl,
+          type: params.type,
+          contextMaxCharacters: params.contextMaxCharacters,
+        },
+      })
+
+      const searchRequest: McpSearchRequest = {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: {
+          name: "web_search_exa",
+          arguments: {
+            query: params.query,
+            type: params.type || "auto",
+            numResults: params.numResults || API_CONFIG.DEFAULT_NUM_RESULTS,
+            livecrawl: params.livecrawl || "fallback",
+            contextMaxCharacters: params.contextMaxCharacters,
+          },
+        },
+      }
+
+      const { signal, clearTimeout } = abortAfterAny(25000, ctx.abort)
+
+      try {
+        const headers: Record<string, string> = {
+          accept: "application/json, text/event-stream",
+          "content-type": "application/json",
+        }
+
+        const response = await fetch(`${API_CONFIG.BASE_URL}${API_CONFIG.ENDPOINTS.SEARCH}`, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(searchRequest),
+          signal,
+        })
+
+        clearTimeout()
+
+        if (!response.ok) {
+          const errorText = await response.text()
+          throw new Error(`Search error (${response.status}): ${errorText}`)
+        }
+
+        const responseText = await response.text()
+
+        // Parse SSE response
+        const lines = responseText.split("\n")
+        for (const line of lines) {
+          if (line.startsWith("data: ")) {
+            const data: McpSearchResponse = JSON.parse(line.substring(6))
+            if (data.result && data.result.content && data.result.content.length > 0) {
+              return {
+                output: data.result.content[0].text,
+                title: `Web search: ${params.query}`,
+                metadata: {},
+              }
+            }
+          }
+        }
+
+        return {
+          output: "No search results found. Please try a different query.",
+          title: `Web search: ${params.query}`,
+          metadata: {},
+        }
+      } catch (error) {
+        clearTimeout()
+
+        if (error instanceof Error && error.name === "AbortError") {
+          throw new Error("Search request timed out")
+        }
+
+        throw error
+      }
+    },
+  }
+})

package/src/tool/websearch.txt

@@ -0,0 +1 @@
+Search the web for technical information and documentation.