nikcli 0.0.6

package/src/tool/memory_search.ts

@@ -0,0 +1,141 @@
+import z from "zod"
+import { Tool } from "./tool"
+import DESCRIPTION from "./memory_search.txt"
+import { Storage } from "@/storage/storage"
+import { Instance } from "@/project/instance"
+import { MessageV2 } from "@/session/message-v2"
+
+const parameters = z.object({
+  query: z.string().describe("Search query"),
+  limit: z.number().int().min(1).max(50).optional().describe("Maximum results"),
+  sessionId: z.string().optional().describe("Restrict to a single session"),
+  maxSessions: z.number().int().min(1).max(50).optional().describe("Maximum sessions to scan"),
+  maxMessages: z.number().int().min(1).max(500).optional().describe("Maximum messages to scan"),
+})
+
+type Result = {
+  sessionID: string
+  messageID: string
+  score: number
+  role: string
+  snippet: string
+  time: number
+}
+
+export const MemorySearchTool = Tool.define<typeof parameters, { count: number }>("memory_search", {
+  description: DESCRIPTION,
+  parameters,
+  async execute(params, ctx) {
+    const limit = params.limit ?? 10
+    const maxSessions = params.maxSessions ?? 10
+    const maxMessages = params.maxMessages ?? 200
+    const terms = splitTerms(params.query)
+
+    await ctx.ask({
+      permission: "memory_search",
+      patterns: [params.query],
+      always: ["*"],
+      metadata: {
+        query: params.query,
+        limit,
+        sessionId: params.sessionId,
+        maxSessions,
+        maxMessages,
+      },
+    })
+
+    if (terms.length === 0) {
+      return {
+        title: "Memory search",
+        output: "No search terms provided.",
+        metadata: { count: 0 },
+      }
+    }
+
+    const sessions = await collectSessions(params.sessionId, maxSessions)
+    const results: Result[] = []
+    const counter = { value: 0 }
+
+    for (const sessionID of sessions) {
+      if (results.length >= limit) break
+      for await (const msg of MessageV2.stream(sessionID)) {
+        if (results.length >= limit) break
+        if (counter.value >= maxMessages) break
+        counter.value += 1
+
+        for (const part of msg.parts) {
+          if (part.type !== "text") continue
+          if (part.ignored) continue
+          const score = scoreText(part.text, terms)
+          if (score <= 0) continue
+          results.push({
+            sessionID: msg.info.sessionID,
+            messageID: msg.info.id,
+            score,
+            role: msg.info.role,
+            snippet: makeSnippet(part.text, terms),
+            time: msg.info.time.created,
+          })
+          if (results.length >= limit) break
+        }
+      }
+    }
+
+    if (results.length === 0) {
+      return {
+        title: "Memory search",
+        output: "No matches found.",
+        metadata: { count: 0 },
+      }
+    }
+
+    results.sort((a, b) => b.score - a.score || b.time - a.time)
+
+    const lines = results.slice(0, limit).map((item) => {
+      const score = item.score.toFixed(2)
+      return `- [${score}] ${item.role} ${item.sessionID} ${item.messageID}: ${item.snippet}`
+    })
+
+    return {
+      title: "Memory search",
+      output: lines.join("\n"),
+      metadata: { count: results.length },
+    }
+  },
+})
+
+function splitTerms(query: string) {
+  return query
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .split(/\s+/)
+    .filter(Boolean)
+}
+
+function scoreText(text: string, terms: string[]) {
+  const lower = text.toLowerCase()
+  const hits = terms.reduce((sum, term) => sum + (lower.includes(term) ? 1 : 0), 0)
+  if (hits === 0) return 0
+  return hits / terms.length
+}
+
+function makeSnippet(text: string, terms: string[]) {
+  const lower = text.toLowerCase()
+  const indexes = terms
+    .map((term) => lower.indexOf(term))
+    .filter((value) => value >= 0)
+    .sort((a, b) => a - b)
+  const idx = indexes[0]
+  if (idx === undefined) return text.slice(0, 180).replace(/\s+/g, " ").trim()
+  const start = Math.max(0, idx - 80)
+  const end = Math.min(text.length, idx + 120)
+  return text.slice(start, end).replace(/\s+/g, " ").trim()
+}
+
+async function collectSessions(sessionId: string | undefined, max: number) {
+  if (sessionId) return [sessionId]
+  const project = Instance.project
+  const items = await Storage.list(["session", project.id])
+  const ids = items.map((item) => item[item.length - 1]).filter(Boolean)
+  return ids.slice(0, max)
+}

package/src/tool/memory_search.txt

@@ -0,0 +1,8 @@
+Search past session messages for a query.
+
+Usage:
+- query: search phrase
+- limit: maximum results (default: 10)
+- sessionId: restrict to a session
+- maxSessions: maximum sessions to scan (default: 10)
+- maxMessages: maximum messages to scan (default: 200)

package/src/tool/multiedit.ts

@@ -0,0 +1,46 @@
+import z from "zod"
+import { Tool } from "./tool"
+import { EditTool } from "./edit"
+import DESCRIPTION from "./multiedit.txt"
+import path from "path"
+import { Instance } from "../project/instance"
+
+export const MultiEditTool = Tool.define("multiedit", {
+  description: DESCRIPTION,
+  parameters: z.object({
+    filePath: z.string().describe("The absolute path to the file to modify"),
+    edits: z
+      .array(
+        z.object({
+          filePath: z.string().describe("The absolute path to the file to modify"),
+          oldString: z.string().describe("The text to replace"),
+          newString: z.string().describe("The text to replace it with (must be different from oldString)"),
+          replaceAll: z.boolean().optional().describe("Replace all occurrences of oldString (default false)"),
+        }),
+      )
+      .describe("Array of edit operations to perform sequentially on the file"),
+  }),
+  async execute(params, ctx) {
+    const tool = await EditTool.init()
+    const results = []
+    for (const [, edit] of params.edits.entries()) {
+      const result = await tool.execute(
+        {
+          filePath: params.filePath,
+          oldString: edit.oldString,
+          newString: edit.newString,
+          replaceAll: edit.replaceAll,
+        },
+        ctx,
+      )
+      results.push(result)
+    }
+    return {
+      title: path.relative(Instance.worktree, params.filePath),
+      metadata: {
+        results: results.map((r) => r.metadata),
+      },
+      output: results.at(-1)!.output,
+    }
+  },
+})

package/src/tool/multiedit.txt

@@ -0,0 +1,41 @@
+This is a tool for making multiple edits to a single file in one operation. It is built on top of the Edit tool and allows you to perform multiple find-and-replace operations efficiently. Prefer this tool over the Edit tool when you need to make multiple edits to the same file.
+
+Before using this tool:
+
+1. Use the Read tool to understand the file's contents and context
+2. Verify the directory path is correct
+
+To make multiple file edits, provide the following:
+1. file_path: The absolute path to the file to modify (must be absolute, not relative)
+2. edits: An array of edit operations to perform, where each edit contains:
+   - oldString: The text to replace (must match the file contents exactly, including all whitespace and indentation)
+   - newString: The edited text to replace the oldString
+   - replaceAll: Replace all occurrences of oldString. This parameter is optional and defaults to false.
+
+IMPORTANT:
+- All edits are applied in sequence, in the order they are provided
+- Each edit operates on the result of the previous edit
+- All edits must be valid for the operation to succeed - if any edit fails, none will be applied
+- This tool is ideal when you need to make several changes to different parts of the same file
+
+CRITICAL REQUIREMENTS:
+1. All edits follow the same requirements as the single Edit tool
+2. The edits are atomic - either all succeed or none are applied
+3. Plan your edits carefully to avoid conflicts between sequential operations
+
+WARNING:
+- The tool will fail if edits.oldString doesn't match the file contents exactly (including whitespace)
+- The tool will fail if edits.oldString and edits.newString are the same
+- Since edits are applied in sequence, ensure that earlier edits don't affect the text that later edits are trying to find
+
+When making edits:
+- Ensure all edits result in idiomatic, correct code
+- Do not leave the code in a broken state
+- Always use absolute file paths (starting with /)
+- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+- Use replaceAll for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.
+
+If you want to create a new file, use:
+- A new file path, including dir name if needed
+- First edit: empty oldString and the new file's contents as newString
+- Subsequent edits: normal edit operations on the created content

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,130 @@
+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 { Identifier } from "../id/id"
+import { Provider } from "../provider/provider"
+import { Instance } from "../project/instance"
+import EXIT_DESCRIPTION from "./plan-exit.txt"
+import ENTER_DESCRIPTION from "./plan-enter.txt"
+
+async function getLastModel(sessionID: string) {
+  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: Identifier.ascending("message"),
+      sessionID: ctx.sessionID,
+      role: "user",
+      time: {
+        created: Date.now(),
+      },
+      agent: "build",
+      model,
+    }
+    await Session.updateMessage(userMsg)
+    await Session.updatePart({
+      id: Identifier.ascending("part"),
+      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: Identifier.ascending("message"),
+      sessionID: ctx.sessionID,
+      role: "user",
+      time: {
+        created: Date.now(),
+      },
+      agent: "plan",
+      model,
+    }
+    await Session.updateMessage(userMsg)
+    await Session.updatePart({
+      id: Identifier.ascending("part"),
+      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,33 @@
+import z from "zod"
+import { Tool } from "./tool"
+import { Question } from "../question"
+import DESCRIPTION from "./question.txt"
+
+export const QuestionTool = Tool.define("question", {
+  description: DESCRIPTION,
+  parameters: z.object({
+    questions: z.array(Question.Info.omit({ custom: true })).describe("Questions to ask"),
+  }),
+  async execute(params, ctx) {
+    const answers = await Question.ask({
+      sessionID: ctx.sessionID,
+      questions: params.questions,
+      tool: ctx.callID ? { messageID: ctx.messageID, callID: ctx.callID } : undefined,
+    })
+
+    function format(answer: Question.Answer | undefined) {
+      if (!answer?.length) return "Unanswered"
+      return answer.join(", ")
+    }
+
+    const formatted = params.questions.map((q, i) => `"${q.question}"="${format(answers[i])}"`).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,
+      },
+    }
+  },
+})

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/rag_index.ts

@@ -0,0 +1,77 @@
+import z from "zod"
+import { Tool } from "./tool"
+import DESCRIPTION from "./rag_index.txt"
+import { Rag } from "@/rag"
+import { Instance } from "@/project/instance"
+import path from "path"
+import { assertExternalDirectory } from "./external-directory"
+
+const parameters = z.object({
+  paths: z.array(z.string()).optional().describe("Files or directories to index"),
+  chunkLines: z.number().int().min(20).max(500).optional().describe("Lines per chunk"),
+  maxFiles: z.number().int().min(1).max(2000).optional().describe("Maximum files to index"),
+  maxChunks: z.number().int().min(1).max(20000).optional().describe("Maximum chunks to store"),
+  maxFileBytes: z.number().int().min(1).optional().describe("Maximum file size in bytes"),
+  model: z.string().optional().describe("Embedding model (default: openai/text-embedding-3-small)"),
+  provider: z.string().optional().describe("Embedding provider (default: openrouter)"),
+})
+
+export const RagIndexTool = Tool.define("rag_index", {
+  description: DESCRIPTION,
+  parameters,
+  async execute(params, ctx) {
+    const base = Instance.worktree === "/" ? Instance.directory : Instance.worktree
+    const root = path.join(base, ".nikcli")
+
+    await ctx.ask({
+      permission: "rag_index",
+      patterns: [root],
+      always: ["*"],
+      metadata: {
+        root,
+        paths: params.paths,
+        chunkLines: params.chunkLines,
+        maxFiles: params.maxFiles,
+        maxChunks: params.maxChunks,
+        maxFileBytes: params.maxFileBytes,
+        model: params.model,
+      },
+    })
+
+    await assertExternalDirectory(ctx, root, { kind: "directory" })
+
+    const result = await Rag.index({
+      paths: params.paths,
+      chunkLines: params.chunkLines,
+      maxFiles: params.maxFiles,
+      maxChunks: params.maxChunks,
+      maxFileBytes: params.maxFileBytes,
+      model: params.model,
+      provider: params.provider,
+    })
+
+    const output = [
+      `Index path: ${result.path}`,
+      `Model: ${result.model}`,
+      `Files: ${result.files}`,
+      `Chunks: ${result.chunks}`,
+      `Indexed chunks: ${result.indexed}`,
+      `Skipped files: ${result.skipped}`,
+      `Kept files: ${result.kept}`,
+    ].join("\n")
+
+    return {
+      title: "RAG index",
+      output,
+      metadata: {
+        path: result.path,
+        files: result.files,
+        chunks: result.chunks,
+        model: result.model,
+        indexed: result.indexed,
+        skipped: result.skipped,
+        kept: result.kept,
+      },
+    }
+  },
+})

package/src/tool/rag_index.txt

@@ -0,0 +1,10 @@
+Build a semantic RAG index for the current project.
+
+Usage:
+- paths: files or directories to index
+- chunkLines: lines per chunk (default: 200)
+- maxFiles: maximum files to index (default: 200)
+- maxChunks: maximum chunks to store (default: 5000)
+- maxFileBytes: maximum file size in bytes (default: 1000000)
+- model: embedding model (must be configured via nikcli rag-model)
+- provider: embedding provider (must be configured via nikcli rag-model)

package/src/tool/rag_reset.ts

@@ -0,0 +1,26 @@
+import z from "zod"
+import { Tool } from "./tool"
+import DESCRIPTION from "./rag_reset.txt"
+import { Rag } from "@/rag"
+
+const parameters = z.object({})
+
+export const RagResetTool = Tool.define("rag_reset", {
+  description: DESCRIPTION,
+  parameters,
+  async execute(_params, ctx) {
+    await ctx.ask({
+      permission: "rag_reset",
+      patterns: ["*"],
+      always: ["*"],
+      metadata: {},
+    })
+
+    const result = await Rag.reset()
+    return {
+      title: "RAG reset",
+      output: `Removed RAG index at ${result.path}`,
+      metadata: { path: result.path },
+    }
+  },
+})

package/src/tool/rag_reset.txt

@@ -0,0 +1,4 @@
+Remove the local RAG index.
+
+Usage:
+- no parameters

package/src/tool/rag_search.ts

@@ -0,0 +1,62 @@
+import z from "zod"
+import { Tool } from "./tool"
+import DESCRIPTION from "./rag_search.txt"
+import { Rag } from "@/rag"
+
+const parameters = z.object({
+  query: z.string().describe("Semantic search query"),
+  limit: z.number().int().min(1).max(50).optional().describe("Maximum results"),
+  minScore: z.number().min(0).max(1).optional().describe("Minimum similarity score"),
+  provider: z.string().optional().describe("Embedding provider"),
+})
+
+export const RagSearchTool = Tool.define("rag_search", {
+  description: DESCRIPTION,
+  parameters,
+  async execute(params, ctx) {
+    await ctx.ask({
+      permission: "rag_search",
+      patterns: [params.query],
+      always: ["*"],
+      metadata: {
+        query: params.query,
+        limit: params.limit,
+        minScore: params.minScore,
+      },
+    })
+
+    const result = await Rag.search({
+      query: params.query,
+      limit: params.limit,
+      minScore: params.minScore,
+      provider: params.provider,
+    })
+
+    if (!result.ready) {
+      return {
+        title: "RAG search",
+        output: "RAG index not found. Run rag_index first.",
+        metadata: { count: 0 },
+      }
+    }
+
+    if (result.results.length === 0) {
+      return {
+        title: "RAG search",
+        output: "No semantic matches found.",
+        metadata: { count: 0 },
+      }
+    }
+
+    const lines = result.results.map((item) => {
+      const score = item.score.toFixed(3)
+      return `- [${score}] ${item.file}:${item.start}-${item.end} ${item.snippet}`
+    })
+
+    return {
+      title: "RAG search",
+      output: lines.join("\n"),
+      metadata: { count: result.results.length },
+    }
+  },
+})

package/src/tool/rag_search.txt

@@ -0,0 +1,6 @@
+Search the RAG index semantically.
+
+Usage:
+- query: semantic search query
+- limit: maximum results (default: 8)
+- minScore: minimum similarity score (default: 0.2)

package/src/tool/rag_status.ts

@@ -0,0 +1,45 @@
+import z from "zod"
+import { Tool } from "./tool"
+import DESCRIPTION from "./rag_status.txt"
+import { Rag } from "@/rag"
+
+const parameters = z.object({})
+
+export const RagStatusTool = Tool.define("rag_status", {
+  description: DESCRIPTION,
+  parameters,
+  async execute(_params, ctx) {
+    await ctx.ask({
+      permission: "rag_status",
+      patterns: ["*"],
+      always: ["*"],
+      metadata: {},
+    })
+
+    const status = await Rag.status()
+    if (!status.ready) {
+      return {
+        title: "RAG status",
+        output: `No RAG index found at ${status.path}`,
+        metadata: { ready: false },
+      }
+    }
+
+    const state = status.state
+    const output = [
+      `Index path: ${status.path}`,
+      state?.model ? `Model: ${state.model}` : "",
+      state?.files !== undefined ? `Files: ${state.files}` : "",
+      state?.chunks !== undefined ? `Chunks: ${state.chunks}` : "",
+      state?.updated ? `Updated: ${new Date(state.updated).toISOString()}` : "",
+    ]
+      .filter(Boolean)
+      .join("\n")
+
+    return {
+      title: "RAG status",
+      output,
+      metadata: { ready: true },
+    }
+  },
+})