@opendash-ai/cli 0.1.0-beta.1

package/src/tool/notebook-edit.ts

@@ -0,0 +1,225 @@
+import z from "zod"
+import * as path from "path"
+import { Effect } from "effect"
+import { createTwoFilesPatch } from "diff"
+import * as Tool from "./tool"
+import DESCRIPTION from "./notebook-edit.txt"
+import { AppFileSystem } from "@opendash-ai/shared/filesystem"
+import { Bus } from "../bus"
+import { File } from "../file"
+import { FileWatcher } from "../file/watcher"
+import { Instance } from "../project/instance"
+import { SessionCwd } from "./session-cwd"
+import { assertWriteAllowed, askEditUnlessMemory } from "./external-directory"
+import { assertFileRead } from "./read-state"
+import { trimDiff } from "./edit"
+
+const Parameters = z.object({
+  notebook_path: z.string().describe("The absolute path to the .ipynb file to modify"),
+  cell_id: z
+    .string()
+    .optional()
+    .describe(
+      "Cell id from the Read tool's <cell id=\"...\"> output. Required for replace/delete; for insert, the new cell is added after this cell (or at the beginning if omitted).",
+    ),
+  new_source: z.string().optional().describe("The cell's new content. Required for replace and insert; ignored for delete."),
+  cell_type: z
+    .enum(["code", "markdown"])
+    .optional()
+    .describe("Cell type. Required for insert; for replace, defaults to the existing cell's type."),
+  edit_mode: z
+    .enum(["replace", "insert", "delete"])
+    .optional()
+    .describe("Operation to perform. Defaults to replace."),
+})
+
+type NotebookCell = {
+  cell_type: "code" | "markdown" | "raw"
+  id?: string
+  source: string | string[]
+  metadata?: Record<string, unknown>
+  outputs?: unknown[]
+  execution_count?: number | null
+}
+
+type Notebook = {
+  cells: NotebookCell[]
+  metadata?: Record<string, unknown>
+  nbformat?: number
+  nbformat_minor?: number
+}
+
+function stringToCellSource(content: string): string[] {
+  if (content === "") return []
+  const lines = content.split("\n")
+  return lines.map((line, i) => (i < lines.length - 1 ? line + "\n" : line)).filter((line) => line !== "")
+}
+
+function generateCellId(existing: Set<string>): string {
+  for (let i = 0; i < 1000; i++) {
+    const id = crypto.randomUUID().slice(0, 8)
+    if (!existing.has(id)) return id
+  }
+  return crypto.randomUUID()
+}
+
+function buildCell(cellType: "code" | "markdown", source: string, id: string): NotebookCell {
+  const sourceLines = stringToCellSource(source)
+  if (cellType === "code") {
+    return {
+      cell_type: "code",
+      id,
+      source: sourceLines,
+      metadata: {},
+      outputs: [],
+      execution_count: null,
+    }
+  }
+  return {
+    cell_type: "markdown",
+    id,
+    source: sourceLines,
+    metadata: {},
+  }
+}
+
+export const NotebookEditTool = Tool.define(
+  "notebook_edit",
+  Effect.gen(function* () {
+    const fs = yield* AppFileSystem.Service
+    const bus = yield* Bus.Service
+
+    return {
+      description: DESCRIPTION,
+      parameters: Parameters,
+      execute: (params: z.infer<typeof Parameters>, ctx: Tool.Context) =>
+        Effect.gen(function* () {
+          const editMode = params.edit_mode ?? "replace"
+
+          if (!params.notebook_path) throw new Error("notebook_path is required")
+          if (path.extname(params.notebook_path) !== ".ipynb") {
+            throw new Error("notebook_path must point to a .ipynb file")
+          }
+
+          const notebookPath = path.isAbsolute(params.notebook_path)
+            ? params.notebook_path
+            : path.join(SessionCwd.get(ctx.sessionID), params.notebook_path)
+
+          if (editMode !== "insert" && !params.cell_id) {
+            throw new Error(`cell_id is required when edit_mode is "${editMode}"`)
+          }
+          if ((editMode === "replace" || editMode === "insert") && params.new_source === undefined) {
+            throw new Error(`new_source is required when edit_mode is "${editMode}"`)
+          }
+          if (editMode === "insert" && !params.cell_type) {
+            throw new Error('cell_type is required when edit_mode is "insert"')
+          }
+
+          yield* assertWriteAllowed(ctx, notebookPath)
+          assertFileRead(ctx, notebookPath, "notebook_edit")
+
+          const exists = yield* fs.existsSafe(notebookPath)
+          if (!exists) throw new Error(`Notebook not found: ${notebookPath}`)
+
+          const contentOld = yield* fs.readFileString(notebookPath)
+          const notebook = ((): Notebook => {
+            try {
+              return JSON.parse(contentOld) as Notebook
+            } catch (err) {
+              throw new Error(`Failed to parse notebook JSON: ${(err as Error).message}`)
+            }
+          })()
+
+          if (!Array.isArray(notebook.cells)) {
+            throw new Error("Notebook is missing a `cells` array — file does not look like a valid Jupyter notebook")
+          }
+
+          // Older notebooks (nbformat_minor < 5) have no cell ids. Backfill UUIDs
+          // for any cell missing one so cellId lookup is stable, and bump
+          // nbformat_minor to 5 to match what Jupyter does on save.
+          const existingIds = new Set<string>()
+          for (const cell of notebook.cells) if (cell.id) existingIds.add(cell.id)
+          let backfilled = false
+          for (const cell of notebook.cells) {
+            if (cell.id) continue
+            const id = generateCellId(existingIds)
+            cell.id = id
+            existingIds.add(id)
+            backfilled = true
+          }
+          if (backfilled && (notebook.nbformat_minor ?? 0) < 5) {
+            notebook.nbformat_minor = 5
+          }
+
+          // Accept either the real cell id or a positional reference like "#0".
+          const findIndex = (ref: string) => {
+            if (ref.startsWith("#")) {
+              const idx = Number.parseInt(ref.slice(1), 10)
+              if (Number.isInteger(idx) && idx >= 0 && idx < notebook.cells.length) return idx
+              return -1
+            }
+            return notebook.cells.findIndex((c) => c.id === ref)
+          }
+          const cellNotFound = (ref: string) => {
+            const ids = notebook.cells.map((c, i) => c.id ?? `#${i}`).join(", ")
+            return new Error(`Cell not found: ${ref}. Available cells: ${ids || "(none)"}`)
+          }
+
+          let title = ""
+
+          if (editMode === "replace") {
+            const idx = findIndex(params.cell_id!)
+            if (idx === -1) throw cellNotFound(params.cell_id!)
+            const target = notebook.cells[idx]
+            const nextType = params.cell_type ?? (target.cell_type === "raw" ? "code" : target.cell_type)
+            const replaced = buildCell(nextType, params.new_source ?? "", target.id ?? params.cell_id!)
+            if (target.cell_type === "code" && nextType === "code") {
+              replaced.outputs = target.outputs ?? []
+              replaced.execution_count = target.execution_count ?? null
+              replaced.metadata = target.metadata ?? {}
+            } else {
+              replaced.metadata = target.metadata ?? {}
+            }
+            notebook.cells[idx] = replaced
+            title = `replace cell ${target.id ?? `#${idx}`}`
+          } else if (editMode === "delete") {
+            const idx = findIndex(params.cell_id!)
+            if (idx === -1) throw cellNotFound(params.cell_id!)
+            notebook.cells.splice(idx, 1)
+            title = `delete cell ${params.cell_id}`
+          } else {
+            // insert
+            const newId = generateCellId(existingIds)
+            const cell = buildCell(params.cell_type!, params.new_source ?? "", newId)
+            if (!params.cell_id) {
+              notebook.cells.unshift(cell)
+              title = `insert cell at start`
+            } else {
+              const idx = findIndex(params.cell_id)
+              if (idx === -1) throw cellNotFound(params.cell_id)
+              notebook.cells.splice(idx + 1, 0, cell)
+              title = `insert cell after ${params.cell_id}`
+            }
+          }
+
+          const contentNew = JSON.stringify(notebook, null, 1) + (contentOld.endsWith("\n") ? "\n" : "")
+
+          const diff = trimDiff(createTwoFilesPatch(notebookPath, notebookPath, contentOld, contentNew))
+          yield* askEditUnlessMemory(ctx, notebookPath, {
+            patterns: [path.relative(Instance.worktree, notebookPath)],
+            diff,
+          })
+
+          yield* fs.writeWithDirs(notebookPath, contentNew)
+          yield* bus.publish(File.Event.Edited, { file: notebookPath })
+          yield* bus.publish(FileWatcher.Event.Updated, { file: notebookPath, event: "change" })
+
+          return {
+            title: `${path.relative(Instance.worktree, notebookPath)} — ${title}`,
+            metadata: { diff, edit_mode: editMode, cell_id: params.cell_id },
+            output: `Notebook updated: ${editMode} on ${path.relative(Instance.worktree, notebookPath)}.`,
+          }
+        }).pipe(Effect.orDie),
+    }
+  }),
+)

package/src/tool/notebook-edit.txt

@@ -0,0 +1,10 @@
+Replaces, inserts, or deletes a single cell in a Jupyter notebook (.ipynb file).
+
+Usage:
+- You must use your `read` tool on the notebook in this conversation before editing — this tool will fail with a recoverable error if the file has not been Read in this session.
+- `notebook_path` should be an absolute path to a `.ipynb` file.
+- `cell_id` is the `id` attribute shown in the `read` tool's `<cell id="...">` output. It is required for `replace` and `delete`. For older notebooks (nbformat_minor < 5) where cells have no real `id`, you can pass a positional reference like `#0`, `#1`, etc. (0-based index). On first edit, missing ids are auto-generated and the notebook is upgraded to nbformat_minor 5.
+- `edit_mode` defaults to `replace`. Use `insert` to add a new cell after the cell with the given `cell_id` (or at the beginning of the notebook if `cell_id` is omitted) — `cell_type` is required when inserting. Use `delete` to remove the cell.
+- For `replace`, the cell type is preserved unless `cell_type` is explicitly provided.
+- `new_source` is the cell's full new content (required for `replace` and `insert`, ignored for `delete`).
+- This tool understands the Jupyter notebook cell structure and modifies cells in place — prefer it over `write`/`edit` for `.ipynb` files so the surrounding JSON, outputs, and metadata stay intact.

package/src/tool/plan-enter.txt

@@ -0,0 +1,16 @@
+Request to switch into plan mode for structured planning before implementation.
+
+This tool is always present regardless of current mode. It is only effective outside of plan mode — calling it while already in plan mode will return an error.
+
+If the user explicitly mentions wanting to create a plan, ALWAYS call this tool first.
+
+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:
+- If you are already in plan mode
+- For simple, straightforward tasks
+- When the user explicitly wants immediate implementation
+- If you are in compose mode (use compose:plan skill instead)

package/src/tool/plan-exit.txt

@@ -0,0 +1,14 @@
+Request to exit plan mode and switch to build agent for implementation.
+
+This tool is always present regardless of current mode. It is only effective in plan mode — calling it from any other mode will return an error.
+
+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:
+- If you are not currently in plan mode
+- 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,179 @@
+import z from "zod"
+import path from "path"
+import { Effect } from "effect"
+import * as Tool from "./tool"
+import { Question } from "../question"
+import { Session } from "../session"
+import { MessageV2 } from "../session/message-v2"
+import { Provider } from "../provider"
+import { Instance } from "../project/instance"
+import { type SessionID, MessageID, PartID } from "../session/schema"
+import ENTER_DESCRIPTION from "./plan-enter.txt"
+import EXIT_DESCRIPTION from "./plan-exit.txt"
+
+function getLastModel(sessionID: SessionID) {
+  for (const item of MessageV2.stream(sessionID, { agentID: "*" })) {
+    if (item.info.role === "user" && item.info.model) return item.info.model
+  }
+  return undefined
+}
+
+export const PlanEnterTool = Tool.define(
+  "plan_enter",
+  Effect.gen(function* () {
+    const session = yield* Session.Service
+    const question = yield* Question.Service
+    const provider = yield* Provider.Service
+
+    return {
+      description: ENTER_DESCRIPTION,
+      parameters: z.object({}),
+      execute: (_params: {}, ctx: Tool.Context) =>
+        Effect.gen(function* () {
+          if (ctx.agent === "plan") {
+            return {
+              title: "Already in plan mode",
+              output: "You are already in plan mode. This tool is only effective outside of plan mode.",
+              metadata: { switched: false, feedback: "" },
+            }
+          }
+
+          const info = yield* session.get(ctx.sessionID)
+          const plan = path.relative(Instance.worktree, Session.plan(info))
+          const answers = yield* question.ask({
+            sessionID: ctx.sessionID,
+            questions: [
+              {
+                key: "plan_enter",
+                params: { plan },
+                question: `Would you like to switch to plan mode for structured planning?`,
+                header: "Plan",
+                options: [
+                  { label: "Yes", description: "Switch to plan agent for read-only planning" },
+                  { label: "No", description: "Stay in current mode" },
+                ],
+              },
+            ],
+            tool: ctx.callID ? { messageID: ctx.messageID, callID: ctx.callID } : undefined,
+          })
+
+          const answer = answers[0]?.[0]
+          if (answer === "No") return yield* new Question.RejectedError()
+
+          if (answer !== "Yes") {
+            return {
+              title: "User provided feedback",
+              output: `User chose not to switch yet and provided feedback: ${answer}`,
+              metadata: { switched: false, feedback: answer },
+            }
+          }
+
+          const model = getLastModel(ctx.sessionID) ?? (yield* provider.defaultModel())
+
+          const msg: MessageV2.User = {
+            id: MessageID.ascending(),
+            sessionID: ctx.sessionID,
+            role: "user",
+            time: { created: Date.now() },
+            agent: "plan",
+            model,
+          }
+          yield* session.updateMessage(msg)
+          yield* session.updatePart({
+            id: PartID.ascending(),
+            messageID: msg.id,
+            sessionID: ctx.sessionID,
+            type: "text",
+            text: `Switched to plan mode. Create a plan at ${plan}`,
+            synthetic: true,
+          } satisfies MessageV2.TextPart)
+
+          return {
+            title: "Switching to plan agent",
+            output: "User approved switching to plan agent. Wait for further instructions.",
+            metadata: { switched: true, feedback: "" },
+          }
+        }).pipe(Effect.orDie),
+    }
+  }),
+)
+
+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: z.object({}),
+      execute: (_params: {}, ctx: Tool.Context) =>
+        Effect.gen(function* () {
+          if (ctx.agent !== "plan") {
+            return {
+              title: "Not in plan mode",
+              output: "You are not in plan mode. This tool is only effective in plan mode.",
+              metadata: { switched: false, feedback: "" },
+            }
+          }
+
+          const info = yield* session.get(ctx.sessionID)
+          const plan = path.relative(Instance.worktree, Session.plan(info))
+          const answers = yield* question.ask({
+            sessionID: ctx.sessionID,
+            questions: [
+              {
+                key: "plan_exit",
+                params: { plan },
+                question: `Plan at ${plan} is complete. Would you like to switch to the build agent and start implementing?`,
+                header: "Plan",
+                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") return yield* new Question.RejectedError()
+
+          if (answer !== "Yes") {
+            return {
+              title: "User provided feedback",
+              output: `User chose not to switch yet and provided feedback: ${answer}`,
+              metadata: { switched: false, feedback: answer },
+            }
+          }
+
+          const model = getLastModel(ctx.sessionID) ?? (yield* provider.defaultModel())
+
+          const msg: MessageV2.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 MessageV2.TextPart)
+
+          return {
+            title: "Switching to build agent",
+            output: "User approved switching to build agent. Wait for further instructions.",
+            metadata: { switched: true, feedback: "" },
+          }
+        }).pipe(Effect.orDie),
+    }
+  }),
+)

package/src/tool/question.ts

@@ -0,0 +1,67 @@
+import z from "zod"
+import { Effect } from "effect"
+import * as Tool from "./tool"
+import { Question } from "../question"
+import DESCRIPTION from "./question.txt"
+
+const parameters = z.object({
+  questions: z.array(Question.Prompt.zod).describe("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,
+      execute: (params: z.infer<typeof parameters>, ctx: Tool.Context<Metadata>) =>
+        Effect.gen(function* () {
+          // never-ask mode: the tool stays visible so the model keeps routing
+          // every decision through it, but instead of blocking for a human we
+          // hand the decision back to the model — it knows which option fits
+          // headless execution better than a hardcoded pick would.
+          if (yield* question.neverAsk()) {
+            const autoAnswer = "[Never-Ask] The model will decide autonomously"
+            return {
+              title: `Auto-resolved ${params.questions.length} question${params.questions.length > 1 ? "s" : ""}`,
+              output:
+                "[Never-Ask] No user is available to answer (never-ask mode is on). " +
+                "Re-evaluate the options you just proposed for unattended/headless execution — " +
+                "prefer text-only, non-interactive, minimal-scope paths and avoid anything that needs a GUI or the user to be present. " +
+                "Pick the best option yourself and continue. " +
+                "IMPORTANT: You MUST explicitly state which option you chose and why in your response text (not just in thinking) — " +
+                "the user will review the conversation history later and needs to see what you decided without expanding thinking blocks. " +
+                "This applies only to this question; never-ask may be turned off later, so keep using the question tool at future decision points (the user may have returned).",
+              metadata: {
+                answers: params.questions.map(() => [autoAnswer]),
+              },
+            }
+          }
+
+          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-state.ts

@@ -0,0 +1,44 @@
+import path from "path"
+import type * as Tool from "./tool"
+import { SessionCwd } from "./session-cwd"
+import { AppFileSystem } from "@opendash-ai/shared/filesystem"
+import { RecoverableError } from "./recoverable"
+import type { SessionID } from "../session/schema"
+
+// Same normalization both sides of the comparison go through so a Read on
+// a relative path lines up with an Edit on the absolute one.
+function canon(sessionID: SessionID, p: string): string {
+  const abs = path.isAbsolute(p) ? p : path.resolve(SessionCwd.get(sessionID), p)
+  if (process.platform === "win32") return AppFileSystem.normalizePath(abs).toLowerCase()
+  return abs
+}
+
+/**
+ * Throws RecoverableError if the given file was not previously read by the
+ * `read` tool in this conversation. Writes/edits to existing files must be
+ * preceded by a Read so the model sees the current contents — this turns the
+ * usage note in edit.txt into actual enforcement.
+ *
+ * RecoverableError is intentional: the failure is surfaced to the agent as a
+ * tool result it can act on (call Read, then retry) rather than as a hard
+ * system fault.
+ */
+export function assertFileRead(ctx: Tool.Context, targetPath: string, toolId: string): void {
+  const target = canon(ctx.sessionID, targetPath)
+
+  for (const msg of ctx.messages) {
+    for (const part of msg.parts) {
+      if (part.type !== "tool") continue
+      if (part.tool !== "read") continue
+      if (part.state.status !== "completed") continue
+      const input = part.state.input as { file_path?: unknown } | undefined
+      const fp = input?.file_path
+      if (typeof fp !== "string") continue
+      if (canon(ctx.sessionID, fp) === target) return
+    }
+  }
+
+  throw new RecoverableError(
+    `${toolId}: ${targetPath} has not been read in this conversation. Call the read tool on this file first, then retry.`,
+  )
+}