koro-ai 1.0.0

package/src/tool/plan.ts

@@ -0,0 +1,131 @@
+import z from "zod"
+import path from "path"
+import { Tool } from "./tool"
+import { Question } from "../question"
+import { Session } from "../session"
+import { MessageV2 } from "../session/message-v2"
+import { Provider } from "../provider/provider"
+import { Instance } from "../project/instance"
+import { type SessionID, MessageID, PartID } from "../session/schema"
+import EXIT_DESCRIPTION from "./plan-exit.txt"
+
+async function getLastModel(sessionID: SessionID) {
+  for await (const item of MessageV2.stream(sessionID)) {
+    if (item.info.role === "user" && item.info.model) return item.info.model
+  }
+  return Provider.defaultModel()
+}
+
+export const PlanExitTool = Tool.define("plan_exit", {
+  description: EXIT_DESCRIPTION,
+  parameters: z.object({}),
+  async execute(_params, ctx) {
+    const session = await Session.get(ctx.sessionID)
+    const plan = path.relative(Instance.worktree, Session.plan(session))
+    const answers = await 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,
+    })
+
+    const answer = answers[0]?.[0]
+    if (answer === "No") throw new Question.RejectedError()
+
+    const model = await getLastModel(ctx.sessionID)
+
+    const userMsg: MessageV2.User = {
+      id: MessageID.ascending(),
+      sessionID: ctx.sessionID,
+      role: "user",
+      time: {
+        created: Date.now(),
+      },
+      agent: "build",
+      model,
+    }
+    await Session.updateMessage(userMsg)
+    await Session.updatePart({
+      id: PartID.ascending(),
+      messageID: userMsg.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 MessageV2.TextPart)
+
+    return {
+      title: "Switching to build agent",
+      output: "User approved switching to build agent. Wait for further instructions.",
+      metadata: {},
+    }
+  },
+})
+
+/*
+export const PlanEnterTool = Tool.define("plan_enter", {
+  description: ENTER_DESCRIPTION,
+  parameters: z.object({}),
+  async execute(_params, ctx) {
+    const session = await Session.get(ctx.sessionID)
+    const plan = path.relative(Instance.worktree, Session.plan(session))
+
+    const answers = await Question.ask({
+      sessionID: ctx.sessionID,
+      questions: [
+        {
+          question: `Would you like to switch to the plan agent and create a plan saved to ${plan}?`,
+          header: "Plan Mode",
+          custom: false,
+          options: [
+            { label: "Yes", description: "Switch to plan agent for research and planning" },
+            { label: "No", description: "Stay with build agent to continue making changes" },
+          ],
+        },
+      ],
+      tool: ctx.callID ? { messageID: ctx.messageID, callID: ctx.callID } : undefined,
+    })
+
+    const answer = answers[0]?.[0]
+
+    if (answer === "No") throw new Question.RejectedError()
+
+    const model = await getLastModel(ctx.sessionID)
+
+    const userMsg: MessageV2.User = {
+      id: MessageID.ascending(),
+      sessionID: ctx.sessionID,
+      role: "user",
+      time: {
+        created: Date.now(),
+      },
+      agent: "plan",
+      model,
+    }
+    await Session.updateMessage(userMsg)
+    await Session.updatePart({
+      id: PartID.ascending(),
+      messageID: userMsg.id,
+      sessionID: ctx.sessionID,
+      type: "text",
+      text: "User has requested to enter plan mode. Switch to plan mode and begin planning.",
+      synthetic: true,
+    } satisfies MessageV2.TextPart)
+
+    return {
+      title: "Switching to plan agent",
+      output: `User confirmed to switch to plan mode. A new message has been created to switch you to plan mode. The plan file will be at ${plan}. Begin planning.`,
+      metadata: {},
+    }
+  },
+})
+*/

package/src/tool/question.ts

@@ -0,0 +1,46 @@
+import z from "zod"
+import { Effect } from "effect"
+import { Tool } from "./tool"
+import { Question } from "../question"
+import DESCRIPTION from "./question.txt"
+
+const parameters = z.object({
+  questions: z.array(Question.Info.omit({ custom: true })).describe("Questions to ask"),
+})
+
+type Metadata = {
+  answers: Question.Answer[]
+}
+
+export const QuestionTool = Tool.defineEffect<typeof parameters, Metadata, Question.Service>(
+  "question",
+  Effect.gen(function* () {
+    const question = yield* Question.Service
+
+    return {
+      description: DESCRIPTION,
+      parameters,
+      async execute(params: z.infer<typeof parameters>, ctx: Tool.Context<Metadata>) {
+        const answers = await question
+          .ask({
+            sessionID: ctx.sessionID,
+            questions: params.questions,
+            tool: ctx.callID ? { messageID: ctx.messageID, callID: ctx.callID } : undefined,
+          })
+          .pipe(Effect.runPromise)
+
+        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,
+          },
+        }
+      },
+    } satisfies Tool.Def<typeof parameters, Metadata>
+  }),
+)

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,296 @@
+import z from "zod"
+import { createReadStream } from "fs"
+import * as fs from "fs/promises"
+import * as path from "path"
+import { createInterface } from "readline"
+import { Tool } from "./tool"
+import { LSP } from "../lsp"
+import { FileTime } from "../file/time"
+import DESCRIPTION from "./read.txt"
+import { Instance } from "../project/instance"
+import { assertExternalDirectory } from "./external-directory"
+import { Instruction } from "../session/instruction"
+import { Filesystem } from "../util/filesystem"
+
+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`
+
+export const ReadTool = Tool.define("read", {
+  description: DESCRIPTION,
+  parameters: z.object({
+    filePath: z.string().describe("The absolute path to the file or directory to read"),
+    offset: z.coerce.number().describe("The line number to start reading from (1-indexed)").optional(),
+    limit: z.coerce.number().describe("The maximum number of lines to read (defaults to 2000)").optional(),
+  }),
+  async execute(params, ctx) {
+    if (params.offset !== undefined && params.offset < 1) {
+      throw new Error("offset must be greater than or equal to 1")
+    }
+    let filepath = params.filePath
+    if (!path.isAbsolute(filepath)) {
+      filepath = path.resolve(Instance.directory, filepath)
+    }
+    if (process.platform === "win32") {
+      filepath = Filesystem.normalizePath(filepath)
+    }
+    const title = path.relative(Instance.worktree, filepath)
+
+    const stat = Filesystem.stat(filepath)
+
+    await assertExternalDirectory(ctx, filepath, {
+      bypass: Boolean(ctx.extra?.["bypassCwdCheck"]),
+      kind: stat?.isDirectory() ? "directory" : "file",
+    })
+
+    await ctx.ask({
+      permission: "read",
+      patterns: [filepath],
+      always: ["*"],
+      metadata: {},
+    })
+
+    if (!stat) {
+      const dir = path.dirname(filepath)
+      const base = path.basename(filepath)
+
+      const suggestions = await fs
+        .readdir(dir)
+        .then((entries) =>
+          entries
+            .filter(
+              (entry) =>
+                entry.toLowerCase().includes(base.toLowerCase()) || base.toLowerCase().includes(entry.toLowerCase()),
+            )
+            .map((entry) => path.join(dir, entry))
+            .slice(0, 3),
+        )
+        .catch(() => [])
+
+      if (suggestions.length > 0) {
+        throw new Error(`File not found: ${filepath}\n\nDid you mean one of these?\n${suggestions.join("\n")}`)
+      }
+
+      throw new Error(`File not found: ${filepath}`)
+    }
+
+    if (stat.isDirectory()) {
+      const dirents = await fs.readdir(filepath, { withFileTypes: true })
+      const entries = await Promise.all(
+        dirents.map(async (dirent) => {
+          if (dirent.isDirectory()) return dirent.name + "/"
+          if (dirent.isSymbolicLink()) {
+            const target = await fs.stat(path.join(filepath, dirent.name)).catch(() => undefined)
+            if (target?.isDirectory()) return dirent.name + "/"
+          }
+          return dirent.name
+        }),
+      )
+      entries.sort((a, b) => a.localeCompare(b))
+
+      const limit = params.limit ?? DEFAULT_READ_LIMIT
+      const offset = params.offset ?? 1
+      const start = offset - 1
+      const sliced = entries.slice(start, start + limit)
+      const truncated = start + sliced.length < entries.length
+
+      const output = [
+        `<path>${filepath}</path>`,
+        `<type>directory</type>`,
+        `<entries>`,
+        sliced.join("\n"),
+        truncated
+          ? `\n(Showing ${sliced.length} of ${entries.length} entries. Use 'offset' parameter to read beyond entry ${offset + sliced.length})`
+          : `\n(${entries.length} entries)`,
+        `</entries>`,
+      ].join("\n")
+
+      return {
+        title,
+        output,
+        metadata: {
+          preview: sliced.slice(0, 20).join("\n"),
+          truncated,
+          loaded: [] as string[],
+        },
+      }
+    }
+
+    const instructions = await Instruction.resolve(ctx.messages, filepath, ctx.messageID)
+
+    // Exclude SVG (XML-based) and vnd.fastbidsheet (.fbs extension, commonly FlatBuffers schema files)
+    const mime = Filesystem.mimeType(filepath)
+    const isImage = mime.startsWith("image/") && mime !== "image/svg+xml" && mime !== "image/vnd.fastbidsheet"
+    const isPdf = mime === "application/pdf"
+    if (isImage || isPdf) {
+      const msg = `${isImage ? "Image" : "PDF"} read successfully`
+      return {
+        title,
+        output: msg,
+        metadata: {
+          preview: msg,
+          truncated: false,
+          loaded: instructions.map((i) => i.filepath),
+        },
+        attachments: [
+          {
+            type: "file",
+            mime,
+            url: `data:${mime};base64,${Buffer.from(await Filesystem.readBytes(filepath)).toString("base64")}`,
+          },
+        ],
+      }
+    }
+
+    const isBinary = await isBinaryFile(filepath, Number(stat.size))
+    if (isBinary) throw new Error(`Cannot read binary file: ${filepath}`)
+
+    const stream = createReadStream(filepath, { encoding: "utf8" })
+    const rl = createInterface({
+      input: stream,
+      // Note: we use the crlfDelay option to recognize all instances of CR LF
+      // ('\r\n') in file as a single line break.
+      crlfDelay: Infinity,
+    })
+
+    const limit = params.limit ?? DEFAULT_READ_LIMIT
+    const offset = params.offset ?? 1
+    const start = offset - 1
+    const raw: string[] = []
+    let bytes = 0
+    let lines = 0
+    let truncatedByBytes = false
+    let hasMoreLines = false
+    try {
+      for await (const text of rl) {
+        lines += 1
+        if (lines <= start) continue
+
+        if (raw.length >= limit) {
+          hasMoreLines = true
+          continue
+        }
+
+        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 (bytes + size > MAX_BYTES) {
+          truncatedByBytes = true
+          hasMoreLines = true
+          break
+        }
+
+        raw.push(line)
+        bytes += size
+      }
+    } finally {
+      rl.close()
+      stream.destroy()
+    }
+
+    if (lines < offset && !(lines === 0 && offset === 1)) {
+      throw new Error(`Offset ${offset} is out of range for this file (${lines} lines)`)
+    }
+
+    const content = raw.map((line, index) => {
+      return `${index + offset}: ${line}`
+    })
+    const preview = raw.slice(0, 20).join("\n")
+
+    let output = [`<path>${filepath}</path>`, `<type>file</type>`, "<content>"].join("\n")
+    output += content.join("\n")
+
+    const totalLines = lines
+    const lastReadLine = offset + raw.length - 1
+    const nextOffset = lastReadLine + 1
+    const truncated = hasMoreLines || truncatedByBytes
+
+    if (truncatedByBytes) {
+      output += `\n\n(Output capped at ${MAX_BYTES_LABEL}. Showing lines ${offset}-${lastReadLine}. Use offset=${nextOffset} to continue.)`
+    } else if (hasMoreLines) {
+      output += `\n\n(Showing lines ${offset}-${lastReadLine} of ${totalLines}. Use offset=${nextOffset} to continue.)`
+    } else {
+      output += `\n\n(End of file - total ${totalLines} lines)`
+    }
+    output += "\n</content>"
+
+    // just warms the lsp client
+    LSP.touchFile(filepath, false)
+    await FileTime.read(ctx.sessionID, filepath)
+
+    if (instructions.length > 0) {
+      output += `\n\n<system-reminder>\n${instructions.map((i) => i.content).join("\n\n")}\n</system-reminder>`
+    }
+
+    return {
+      title,
+      output,
+      metadata: {
+        preview,
+        truncated,
+        loaded: instructions.map((i) => i.filepath),
+      },
+    }
+  },
+})
+
+async function isBinaryFile(filepath: string, fileSize: number): Promise<boolean> {
+  const ext = path.extname(filepath).toLowerCase()
+  // binary check for common non-text extensions
+  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
+    default:
+      break
+  }
+
+  if (fileSize === 0) return false
+
+  const fh = await fs.open(filepath, "r")
+  try {
+    const sampleSize = Math.min(4096, fileSize)
+    const bytes = Buffer.alloc(sampleSize)
+    const result = await fh.read(bytes, 0, sampleSize, 0)
+    if (result.bytesRead === 0) return false
+
+    let nonPrintableCount = 0
+    for (let i = 0; i < result.bytesRead; i++) {
+      if (bytes[i] === 0) return true
+      if (bytes[i] < 9 || (bytes[i] > 13 && bytes[i] < 32)) {
+        nonPrintableCount++
+      }
+    }
+    // If >30% non-printable characters, consider it binary
+    return nonPrintableCount / result.bytesRead > 0.3
+  } finally {
+    await fh.close()
+  }
+}

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.