@miaws/miaw 1.18.3 → 1.18.5

package/src/tool/mcp-websearch.ts

@@ -0,0 +1,96 @@
+import { Duration, Effect, Schema } from "effect"
+import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+
+export const EXA_URL = process.env.EXA_API_KEY
+  ? `https://mcp.exa.ai/mcp?exaApiKey=${encodeURIComponent(process.env.EXA_API_KEY)}`
+  : "https://mcp.exa.ai/mcp"
+export const PARALLEL_URL = "https://search.parallel.ai/mcp"
+
+const McpResult = Schema.Struct({
+  result: Schema.Struct({
+    content: Schema.Array(
+      Schema.Struct({
+        type: Schema.String,
+        text: Schema.String,
+      }),
+    ),
+  }),
+})
+
+const decode = Schema.decodeUnknownEffect(Schema.fromJsonString(McpResult))
+
+const parsePayload = (payload: string) =>
+  Effect.gen(function* () {
+    const trimmed = payload.trim()
+    if (!trimmed.startsWith("{")) return undefined
+    const data = yield* decode(trimmed)
+    return data.result.content.find((item) => item.text)?.text
+  })
+
+export const parseResponse = Effect.fn("McpWebSearch.parseResponse")(function* (body: string) {
+  const trimmed = body.trim()
+  const direct = trimmed ? yield* parsePayload(trimmed) : undefined
+  if (direct) return direct
+
+  for (const line of body.split("\n")) {
+    if (!line.startsWith("data: ")) continue
+    const data = yield* parsePayload(line.substring(6))
+    if (data) return data
+  }
+  return undefined
+})
+
+export const SearchArgs = Schema.Struct({
+  query: Schema.String,
+  type: Schema.String,
+  numResults: Schema.Number,
+  livecrawl: Schema.String,
+  contextMaxCharacters: Schema.optional(Schema.Number),
+})
+
+export const ParallelSearchArgs = Schema.Struct({
+  objective: Schema.String,
+  search_queries: Schema.Array(Schema.String),
+  session_id: Schema.optional(Schema.String),
+  model_name: Schema.optional(Schema.String),
+})
+
+const McpRequest = <F extends Schema.Struct.Fields>(args: Schema.Struct<F>) =>
+  Schema.Struct({
+    jsonrpc: Schema.Literal("2.0"),
+    id: Schema.Literal(1),
+    method: Schema.Literal("tools/call"),
+    params: Schema.Struct({
+      name: Schema.String,
+      arguments: args,
+    }),
+  })
+
+export const call = <F extends Schema.Struct.Fields>(
+  http: HttpClient.HttpClient,
+  url: string,
+  tool: string,
+  args: Schema.Struct<F>,
+  value: Schema.Struct.Type<F>,
+  timeout: Duration.Input,
+  headers?: Record<string, string>,
+) =>
+  Effect.gen(function* () {
+    const request = yield* HttpClientRequest.post(url).pipe(
+      HttpClientRequest.accept("application/json, text/event-stream"),
+      HttpClientRequest.setHeaders(headers ?? {}),
+      HttpClientRequest.schemaBodyJson(McpRequest(args))({
+        jsonrpc: "2.0" as const,
+        id: 1 as const,
+        method: "tools/call" as const,
+        params: { name: tool, arguments: value },
+      }),
+    )
+    const response = yield* HttpClient.filterStatusOk(http)
+      .execute(request)
+      .pipe(
+        Effect.timeoutOrElse({ duration: timeout, orElse: () => Effect.die(new Error(`${tool} request timed out`)) }),
+      )
+    const body = yield* response.text
+    return yield* parseResponse(body)
+  })

package/src/tool/plan-enter.txt

@@ -0,0 +1,14 @@
+Use this tool to suggest switching to plan agent when the user's request would benefit from planning before implementation.
+
+If they explicitly mention wanting to create a plan ALWAYS call this tool first.
+
+This tool will ask the user if they want to switch to plan agent.
+
+Call this tool when:
+- The user's request is complex and would benefit from planning first
+- You want to research and design before making changes
+- The task involves multiple files or significant architectural decisions
+
+Do NOT call this tool:
+- For simple, straightforward tasks
+- When the user explicitly wants immediate implementation

package/src/tool/plan-exit.txt

@@ -0,0 +1,13 @@
+Use this tool when you have completed the planning phase and are ready to exit plan agent.
+
+This tool will ask the user if they want to switch to build agent to start implementing the plan.
+
+Call this tool:
+- After you have written a complete plan to the plan file
+- After you have clarified any questions with the user
+- When you are confident the plan is ready for implementation
+
+Do NOT call this tool:
+- Before you have created or finalized the plan
+- If you still have unanswered questions about the implementation
+- If the user has indicated they want to continue planning

package/src/tool/plan.ts

@@ -0,0 +1,79 @@
+import path from "path"
+import { SessionV1 } from "@miaw/core/v1/session"
+import { Effect, Schema } from "effect"
+import * as Tool from "./tool"
+import { Question } from "../question"
+import { Session } from "@/session/session"
+import { MessageV2 } from "../session/message-v2"
+import { Provider } from "@/provider/provider"
+import { InstanceState } from "@/effect/instance-state"
+import { MessageID, PartID } from "../session/schema"
+import EXIT_DESCRIPTION from "./plan-exit.txt"
+
+export const Parameters = Schema.Struct({})
+
+export const PlanExitTool = Tool.define(
+  "plan_exit",
+  Effect.gen(function* () {
+    const session = yield* Session.Service
+    const question = yield* Question.Service
+    const provider = yield* Provider.Service
+
+    return {
+      description: EXIT_DESCRIPTION,
+      parameters: Parameters,
+      execute: (_params: {}, ctx: Tool.Context) =>
+        Effect.gen(function* () {
+          const instance = yield* InstanceState.context
+          const info = yield* session.get(ctx.sessionID)
+          const plan = path.relative(instance.worktree, Session.plan(info, instance))
+          const answers = yield* question.ask({
+            sessionID: ctx.sessionID,
+            questions: [
+              {
+                question: `Plan at ${plan} is complete. Would you like to switch to the build agent and start implementing?`,
+                header: "Build Agent",
+                custom: false,
+                options: [
+                  { label: "Yes", description: "Switch to build agent and start implementing the plan" },
+                  { label: "No", description: "Stay with plan agent to continue refining the plan" },
+                ],
+              },
+            ],
+            tool: ctx.callID ? { messageID: ctx.messageID, callID: ctx.callID } : undefined,
+          })
+
+          if (answers[0]?.[0] === "No") yield* new Question.RejectedError()
+
+          const messages = yield* session.messages({ sessionID: ctx.sessionID }).pipe(Effect.orDie)
+          const lastUser = messages.findLast((item) => item.info.role === "user" && item.info.model)
+          const model =
+            lastUser?.info.role === "user" && lastUser.info.model ? lastUser.info.model : yield* provider.defaultModel()
+
+          const msg: SessionV1.User = {
+            id: MessageID.ascending(),
+            sessionID: ctx.sessionID,
+            role: "user",
+            time: { created: Date.now() },
+            agent: "build",
+            model,
+          }
+          yield* session.updateMessage(msg)
+          yield* session.updatePart({
+            id: PartID.ascending(),
+            messageID: msg.id,
+            sessionID: ctx.sessionID,
+            type: "text",
+            text: `The plan at ${plan} has been approved, you can now edit files. Execute the plan`,
+            synthetic: true,
+          } satisfies SessionV1.TextPart)
+
+          return {
+            title: "Switching to build agent",
+            output: "User approved switching to build agent. Wait for further instructions.",
+            metadata: {},
+          }
+        }).pipe(Effect.orDie),
+    }
+  }),
+)

package/src/tool/question.ts

@@ -0,0 +1,44 @@
+import { Effect, Schema } from "effect"
+import * as Tool from "./tool"
+import { Question } from "../question"
+import DESCRIPTION from "./question.txt"
+
+export const Parameters = Schema.Struct({
+  questions: Schema.mutable(Schema.Array(Question.Prompt)).annotate({ description: "Questions to ask" }),
+})
+
+type Metadata = {
+  answers: ReadonlyArray<Question.Answer>
+}
+
+export const QuestionTool = Tool.define<typeof Parameters, Metadata, Question.Service>(
+  "question",
+  Effect.gen(function* () {
+    const question = yield* Question.Service
+
+    return {
+      description: DESCRIPTION,
+      parameters: Parameters,
+      execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context<Metadata>) =>
+        Effect.gen(function* () {
+          const answers = yield* question.ask({
+            sessionID: ctx.sessionID,
+            questions: params.questions,
+            tool: ctx.callID ? { messageID: ctx.messageID, callID: ctx.callID } : undefined,
+          })
+
+          const formatted = params.questions
+            .map((q, i) => `"${q.question}"="${answers[i]?.length ? answers[i].join(", ") : "Unanswered"}"`)
+            .join(", ")
+
+          return {
+            title: `Asked ${params.questions.length} question${params.questions.length > 1 ? "s" : ""}`,
+            output: `User has answered your questions: ${formatted}. You can now continue with the user's answers in mind.`,
+            metadata: {
+              answers,
+            },
+          }
+        }).pipe(Effect.orDie),
+    }
+  }),
+)

package/src/tool/question.txt

@@ -0,0 +1,10 @@
+Use this tool when you need to ask the user questions during execution. This allows you to:
+1. Gather user preferences or requirements
+2. Clarify ambiguous instructions
+3. Get decisions on implementation choices as you work
+4. Offer choices to the user about what direction to take.
+
+Usage notes:
+- When `custom` is enabled (default), a "Type your own answer" option is added automatically; don't include "Other" or catch-all options
+- Answers are returned as arrays of labels; set `multiple: true` to allow selecting more than one
+- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label

package/src/tool/read.ts

@@ -0,0 +1,386 @@
+import { Effect, Option, Schema, Scope, Stream } from "effect"
+import { NonNegativeInt } from "@miaw/core/schema"
+import * as path from "path"
+import * as Tool from "./tool"
+import { FSUtil } from "@miaw/core/fs-util"
+import { LSP } from "@/lsp/lsp"
+import DESCRIPTION from "./read.txt"
+import { InstanceState } from "@/effect/instance-state"
+import { assertExternalDirectoryEffect } from "./external-directory"
+import { Instruction } from "../session/instruction"
+import { isPdfAttachment, sniffAttachmentMime } from "@/util/media"
+
+const DEFAULT_READ_LIMIT = 2000
+const MAX_LINE_LENGTH = 2000
+const MAX_LINE_SUFFIX = `... (line truncated to ${MAX_LINE_LENGTH} chars)`
+const MAX_BYTES = 50 * 1024
+const MAX_BYTES_LABEL = `${MAX_BYTES / 1024} KB`
+const SAMPLE_BYTES = 4096
+const SUPPORTED_IMAGE_MIMES = new Set(["image/jpeg", "image/png", "image/gif", "image/webp"])
+
+class ReadStop extends Schema.TaggedErrorClass<ReadStop>()("ReadStop", {}) {}
+
+// `offset` and `limit` were originally `z.coerce.number()` — the runtime
+// coercion was useful when the tool was called from a shell but serves no
+// purpose in the LLM tool-call path (the model emits typed JSON). The JSON
+// Schema output is identical (`type: "number"`), so the LLM view is
+// unchanged; purely CLI-facing uses must now send numbers rather than strings.
+export const Parameters = Schema.Struct({
+  filePath: Schema.String.annotate({ description: "The absolute path to the file or directory to read" }),
+  offset: Schema.optional(NonNegativeInt).annotate({
+    description: "The line number to start reading from (1-indexed)",
+  }),
+  limit: Schema.optional(NonNegativeInt).annotate({
+    description: "The maximum number of lines to read (defaults to 2000)",
+  }),
+})
+
+type Display =
+  | {
+      type: "directory"
+      path: string
+      entries: string[]
+      offset: number
+      totalEntries: number
+      truncated: boolean
+    }
+  | {
+      type: "file"
+      path: string
+      text: string
+      lineStart: number
+      lineEnd: number
+      totalLines: number
+      truncated: boolean
+    }
+
+type Metadata = {
+  preview: string
+  truncated: boolean
+  loaded: string[]
+  display?: Display
+}
+
+export const ReadTool = Tool.define<
+  typeof Parameters,
+  Metadata,
+  FSUtil.Service | Instruction.Service | LSP.Service | Scope.Scope
+>(
+  "read",
+  Effect.gen(function* () {
+    const fs = yield* FSUtil.Service
+    const instruction = yield* Instruction.Service
+    const lsp = yield* LSP.Service
+    const scope = yield* Scope.Scope
+
+    const miss = Effect.fn("ReadTool.miss")(function* (filepath: string) {
+      const dir = path.dirname(filepath)
+      const base = path.basename(filepath)
+      const items = yield* fs.readDirectory(dir).pipe(
+        Effect.map((items) =>
+          items
+            .filter(
+              (item) =>
+                item.toLowerCase().includes(base.toLowerCase()) || base.toLowerCase().includes(item.toLowerCase()),
+            )
+            .map((item) => path.join(dir, item))
+            .slice(0, 3),
+        ),
+        Effect.catch(() => Effect.succeed([] as string[])),
+      )
+
+      if (items.length > 0) {
+        return yield* Effect.fail(
+          new Error(`File not found: ${filepath}\n\nDid you mean one of these?\n${items.join("\n")}`),
+        )
+      }
+
+      return yield* Effect.fail(new Error(`File not found: ${filepath}`))
+    })
+
+    const list = Effect.fn("ReadTool.list")(function* (filepath: string) {
+      const items = yield* fs.readDirectoryEntries(filepath)
+      return yield* Effect.forEach(
+        items,
+        Effect.fnUntraced(function* (item) {
+          if (item.type === "directory") return item.name + "/"
+          if (item.type !== "symlink") return item.name
+
+          const target = yield* fs.stat(path.join(filepath, item.name)).pipe(Effect.catch(() => Effect.void))
+          if (target?.type === "Directory") return item.name + "/"
+          return item.name
+        }),
+        { concurrency: "unbounded" },
+      ).pipe(Effect.map((items: string[]) => items.sort((a, b) => a.localeCompare(b))))
+    })
+
+    const warm = Effect.fn("ReadTool.warm")(function* (filepath: string) {
+      // LSP warm-up is optional; do not let a background defect fail an otherwise successful read.
+      yield* lsp.touchFile(filepath).pipe(Effect.ignoreCause, Effect.forkIn(scope))
+    })
+
+    const readSample = Effect.fn("ReadTool.readSample")(function* (
+      filepath: string,
+      fileSize: number,
+      sampleSize: number,
+    ) {
+      if (fileSize === 0) return new Uint8Array()
+
+      return yield* Effect.scoped(
+        Effect.gen(function* () {
+          const file = yield* fs.open(filepath, { flag: "r" })
+          return Option.getOrElse(yield* file.readAlloc(Math.min(sampleSize, fileSize)), () => new Uint8Array())
+        }),
+      )
+    })
+
+    const lines = Effect.fn("ReadTool.lines")(function* (filepath: string, opts: { limit: number; offset: number }) {
+      const start = opts.offset - 1
+      const raw: string[] = []
+      const flags = { bytes: 0, count: 0, cut: false, more: false, done: false }
+
+      // Note: prefer manual TextDecoder over Stream.decodeText — when the source stream
+      // ends without flushing, decodeText drops the final unterminated line. We also
+      // avoid Stream.runForEachWhile (it currently swallows the final unterminated
+      // line of the upstream splitLines pipeline) and use a tagged error to stop the
+      // upstream file stream as soon as the byte cap is reached.
+      const decoder = new TextDecoder("utf-8")
+      yield* fs.stream(filepath).pipe(
+        Stream.map((bytes) => decoder.decode(bytes, { stream: true })),
+        Stream.splitLines,
+        Stream.runForEach((text) =>
+          Effect.gen(function* () {
+            if (flags.done) return yield* new ReadStop()
+            flags.count += 1
+            if (flags.count <= start) return
+
+            if (raw.length >= opts.limit) {
+              flags.more = true
+              return
+            }
+
+            const line = text.length > MAX_LINE_LENGTH ? text.substring(0, MAX_LINE_LENGTH) + MAX_LINE_SUFFIX : text
+            const size = Buffer.byteLength(line, "utf-8") + (raw.length > 0 ? 1 : 0)
+            if (flags.bytes + size <= MAX_BYTES) {
+              raw.push(line)
+              flags.bytes += size
+              return
+            }
+
+            flags.cut = true
+            flags.more = true
+            flags.done = true
+            return yield* new ReadStop()
+          }),
+        ),
+        Effect.catchTag("ReadStop", () => Effect.void),
+      )
+
+      return { raw, count: flags.count, cut: flags.cut, more: flags.more, offset: opts.offset }
+    })
+
+    const isBinaryFile = (filepath: string, bytes: Uint8Array) => {
+      const ext = path.extname(filepath).toLowerCase()
+      switch (ext) {
+        case ".zip":
+        case ".tar":
+        case ".gz":
+        case ".exe":
+        case ".dll":
+        case ".so":
+        case ".class":
+        case ".jar":
+        case ".war":
+        case ".7z":
+        case ".doc":
+        case ".docx":
+        case ".xls":
+        case ".xlsx":
+        case ".ppt":
+        case ".pptx":
+        case ".odt":
+        case ".ods":
+        case ".odp":
+        case ".bin":
+        case ".dat":
+        case ".obj":
+        case ".o":
+        case ".a":
+        case ".lib":
+        case ".wasm":
+        case ".pyc":
+        case ".pyo":
+          return true
+      }
+
+      if (bytes.length === 0) return false
+
+      let nonPrintableCount = 0
+      for (let i = 0; i < bytes.length; i++) {
+        if (bytes[i] === 0) return true
+        if (bytes[i] < 9 || (bytes[i] > 13 && bytes[i] < 32)) {
+          nonPrintableCount++
+        }
+      }
+
+      return nonPrintableCount / bytes.length > 0.3
+    }
+
+    const run = Effect.fn("ReadTool.execute")(function* (
+      params: Schema.Schema.Type<typeof Parameters>,
+      ctx: Tool.Context<Metadata>,
+    ) {
+      const instance = yield* InstanceState.context
+      let filepath = params.filePath
+      if (!path.isAbsolute(filepath)) {
+        filepath = path.resolve(instance.directory, filepath)
+      }
+      if (process.platform === "win32") {
+        filepath = FSUtil.normalizePath(filepath)
+      }
+      const title = path.relative(instance.worktree, filepath)
+
+      const stat = yield* fs.stat(filepath).pipe(
+        Effect.catchIf(
+          (err) => "reason" in err && err.reason._tag === "NotFound",
+          () => Effect.succeed(undefined),
+        ),
+      )
+
+      yield* assertExternalDirectoryEffect(ctx, filepath, {
+        bypass: Boolean(ctx.extra?.["bypassCwdCheck"]),
+        kind: stat?.type === "Directory" ? "directory" : "file",
+      })
+
+      yield* ctx.ask({
+        permission: "read",
+        patterns: [path.relative(instance.worktree, filepath)],
+        always: ["*"],
+        metadata: {},
+      })
+
+      if (!stat) return yield* miss(filepath)
+
+      if (stat.type === "Directory") {
+        const items = yield* list(filepath)
+        const limit = params.limit ?? DEFAULT_READ_LIMIT
+        const offset = params.offset || 1
+        const start = offset - 1
+        const sliced = items.slice(start, start + limit)
+        const truncated = start + sliced.length < items.length
+
+        return {
+          title,
+          output: [
+            `<path>${filepath}</path>`,
+            `<type>directory</type>`,
+            `<entries>`,
+            sliced.join("\n"),
+            truncated
+              ? `\n(Showing ${sliced.length} of ${items.length} entries. Use 'offset' parameter to read beyond entry ${offset + sliced.length})`
+              : `\n(${items.length} entries)`,
+            `</entries>`,
+          ].join("\n"),
+          metadata: {
+            preview: sliced.slice(0, 20).join("\n"),
+            truncated,
+            loaded: [] as string[],
+            display: {
+              type: "directory" as const,
+              path: filepath,
+              entries: sliced,
+              offset,
+              totalEntries: items.length,
+              truncated,
+            },
+          },
+        }
+      }
+
+      const loaded = yield* instruction.resolve(ctx.messages, filepath, ctx.messageID)
+      const sample = yield* readSample(filepath, Number(stat.size), SAMPLE_BYTES)
+
+      const mime = sniffAttachmentMime(sample, FSUtil.mimeType(filepath))
+      const isImage = SUPPORTED_IMAGE_MIMES.has(mime)
+
+      if (isImage || isPdfAttachment(mime)) {
+        const bytes = yield* fs.readFile(filepath)
+        const msg = isPdfAttachment(mime) ? "PDF read successfully" : "Image read successfully"
+        return {
+          title,
+          output: msg,
+          metadata: {
+            preview: msg,
+            truncated: false,
+            loaded: loaded.map((item) => item.filepath),
+          },
+          attachments: [
+            {
+              type: "file" as const,
+              mime,
+              url: `data:${mime};base64,${Buffer.from(bytes).toString("base64")}`,
+            },
+          ],
+        }
+      }
+
+      if (isBinaryFile(filepath, sample)) {
+        return yield* Effect.fail(new Error(`Cannot read binary file: ${filepath}`))
+      }
+
+      const file = yield* lines(filepath, { limit: params.limit ?? DEFAULT_READ_LIMIT, offset: params.offset || 1 })
+      if (file.count < file.offset && !(file.count === 0 && file.offset === 1)) {
+        return yield* Effect.fail(
+          new Error(`Offset ${file.offset} is out of range for this file (${file.count} lines)`),
+        )
+      }
+
+      let output = [`<path>${filepath}</path>`, `<type>file</type>`, "<content>\n"].join("\n")
+      output += file.raw.map((line, i) => `${i + file.offset}: ${line}`).join("\n")
+
+      const last = file.offset + file.raw.length - 1
+      const next = last + 1
+      const truncated = file.more || file.cut
+      if (file.cut) {
+        output += `\n\n(Output capped at ${MAX_BYTES_LABEL}. Showing lines ${file.offset}-${last}. Use offset=${next} to continue.)`
+      } else if (file.more) {
+        output += `\n\n(Showing lines ${file.offset}-${last} of ${file.count}. Use offset=${next} to continue.)`
+      } else {
+        output += `\n\n(End of file - total ${file.count} lines)`
+      }
+      output += "\n</content>"
+
+      yield* warm(filepath)
+
+      if (loaded.length > 0) {
+        output += `\n\n<system-reminder>\n${loaded.map((item) => item.content).join("\n\n")}\n</system-reminder>`
+      }
+
+      return {
+        title,
+        output,
+        metadata: {
+          preview: file.raw.slice(0, 20).join("\n"),
+          truncated,
+          loaded: loaded.map((item) => item.filepath),
+          display: {
+            type: "file" as const,
+            path: filepath,
+            text: file.raw.join("\n"),
+            lineStart: file.offset,
+            lineEnd: last,
+            totalLines: file.count,
+            truncated,
+          },
+        },
+      }
+    })
+
+    return {
+      description: DESCRIPTION,
+      parameters: Parameters,
+      execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context<Metadata>) =>
+        run(params, ctx).pipe(Effect.orDie),
+    }
+  }),
+)

package/src/tool/read.txt

@@ -0,0 +1,14 @@
+Read a file or directory from the local filesystem. If the path does not exist, an error is returned.
+
+Usage:
+- The filePath parameter should be an absolute path.
+- By default, this tool returns up to 2000 lines from the start of the file.
+- The offset parameter is the line number to start from (1-indexed).
+- To read later sections, call this tool again with a larger offset.
+- Use the grep tool to find specific content in large files or files with long lines.
+- If you are unsure of the correct file path, use the glob tool to look up filenames by glob pattern.
+- Contents are returned with each line prefixed by its line number as `<line>: <content>`. For example, if a file has contents "foo\n", you will receive "1: foo\n". For directories, entries are returned one per line (without line numbers) with a trailing `/` for subdirectories.
+- Any line longer than 2000 characters is truncated.
+- Call this tool in parallel when you know there are multiple files you want to read.
+- Avoid tiny repeated slices (30 line chunks). If you need more context, read a larger window.
+- This tool can read image files and PDFs and return them as file attachments.