@mty-coder/cli 0.1.1

package/src/tool/actor.txt

@@ -0,0 +1,103 @@
+Launch a new actor (subagent) to handle complex, multi-step tasks autonomously.
+
+JSON calls wrap the action payload inside an `operation` object; `action` is the discriminator field.
+
+Examples:
+{"operation":{"action":"run","subagent_type":"explore","description":"Find error recovery","prompt":"<full task>"}}
+{"operation":{"action":"run","subagent_type":"explore","description":"Investigate T4","prompt":"<full task>","task_id":"T4"}}
+{"operation":{"action":"spawn","subagent_type":"general","description":"Long-running search","prompt":"<full task>"}}
+{"operation":{"action":"status","actor_id":"<existing>"}}
+{"operation":{"action":"wait","actor_id":"<existing>"}}
+{"operation":{"action":"cancel","actor_id":"<existing>"}}
+{"operation":{"action":"send","to_actor_id":"<existing>","content":"<message>"}}
+
+## Operations (the `operation.action` field selects one)
+
+- run:    spawn a subagent and BLOCK until completion; result returned inline.
+          required: subagent_type, description, prompt
+          optional: actor_id, timeout_ms, command, context
+- spawn:  spawn a subagent and return actor_id IMMEDIATELY (background).
+          required: subagent_type, description, prompt
+          optional: actor_id, command, context
+- status: poll actor state without blocking. required: actor_id.
+          Returns: { status: "pending"|"running"|"idle"|"unknown", actor_id, turnCount, ... }
+- wait:   block until actor completes (success/failure/cancelled) or timeout (default 10 min).
+          required: actor_id. optional: timeout_ms.
+          Returns: { status, actor_id, result?, error? }
+- cancel: stop a running actor (graceful). required: actor_id. Idempotent.
+- send:   deliver message to another actor's inbox.
+          required: to_actor_id, content.
+          optional: to_session_id, type (default "text").
+          Receiver sees wrapped in <inbox from="..." sent_at="...">...</inbox> at next iteration.
+
+## When to use actor
+
+- **Parallelize**: spawn multiple independent searches/analyses concurrently; `wait` on each.
+- **Isolate heavy lifting**: delegate 10+ file reads to a subagent; you get only the synthesis.
+- **Specialized search**: use `explore` for read-only code discovery (finding definitions, callers).
+- **Custom review**: `general` subagent verifies implementation against spec without bias.
+- **Working on a tracked task**: when you spawn a subagent to do work for one of your active tasks (T1, T2, …) — investigation, focused review, dedicated implementation — pass `task_id` so the subagent's verbatim findings get captured to `tasks/<TID>/progress.md` and reconciled into the next checkpoint. Pass ONLY a task ID the `task` tool returned this session; never invent one. If you haven't created the task yet, create it with the `task` tool first, or omit `task_id` and run ad-hoc.
+- **Don't spawn for**: trivial single-file lookups, answers already in your context, or decisions on partial outputs.
+
+## Writing the prompt
+
+You are the subagent's only briefing — it hasn't seen this conversation.
+- Explain what you're trying to accomplish and why.
+- Say what you've already learned or ruled out.
+- Give enough context for judgment calls, not just narrow steps.
+- If you need short output, say so ("report in under 200 words").
+- For investigation: hand over the question; prescribed steps become dead weight.
+
+## Context inheritance
+
+- `context="full"`: subagent sees your full conversation history (for state writers, evaluators).
+- `context="state"`: subagent gets checkpoint summaries injected (background knowledge, no full detail).
+- `context="none"` (default): clean context, only the prompt.
+
+## Actor ID vs Task ID
+
+`actor_id` identifies a subagent session (resumable across turns). Task IDs (T1, T2, ...) come from the `task` tool — only pass a `task_id` you got from a `task` tool call this session. If the `task_id` is malformed or unknown, the binding is dropped: the subagent's findings won't be captured to any task, and the tool result tells you so.
+
+## Binding a subagent to a task
+
+When you `run` or `spawn` a subagent that's doing work for a specific task,
+pass the task's TID via `task_id` (e.g. `task_id: "T4"`) — but only a TID the
+`task` tool actually returned this session. After the subagent finishes, the
+system checks that `tasks/<task_id>/progress.md` exists with the required
+structure — if not, the subagent gets one more chance to write it before
+terminating. The next checkpoint writer then reads that file and integrates
+verbatim commands, outcome, and discoveries into the main checkpoint.
+
+If `task_id` is malformed or names no existing task, the binding is dropped —
+the subagent's findings won't be captured to that task, and the tool result
+says so. Leave `task_id` OFF for ad-hoc work that isn't bound to a task; the
+postStop check then becomes a no-op.
+
+## Usage notes
+
+- **Resume the same subagent**: pass `actor_id` to `run`/`spawn` and the call resumes that subagent's session (continues with its prior messages and tool outputs). Without `actor_id`, a fresh subagent is created.
+- **`run` vs `spawn` result delivery**: `run` blocks and returns the result inline. `spawn` returns the actor_id immediately; when the background actor finishes, its result appears as a notification in this conversation — your turn does NOT auto-wake to process it; you'll see it the next time you respond to the user. Use `wait` to block on the actor_id explicitly.
+- **`wait` on persistent peers caveat**: `wait` is designed for ephemeral subagents you spawned via `run`/`spawn`. Persistent peers idle between turns and never produce a "done" outcome on success — `wait` on a peer will block until that peer fails or is cancelled. Use `send` + `status` to coordinate with peers instead.
+- **`send` semantics**: fire-and-forget; returns within ~5 ms regardless of receiver load. The receiver picks the message up at the head of its next runLoop iteration. On unknown `to_actor_id`, `send` returns `{inboxID: null, error: "receiver not found"}` rather than throwing — handle the error path.
+- Trust the subagent's outputs generally, but the subagent doesn't see your full context (unless you pass `context="full"`); brief it accordingly.
+
+
+## Examples
+
+<example>
+user: "Find all places where parser.ts handles error recovery"
+assistant: I'll spawn an explore subagent to scan parser-related files.
+[actor({"operation":{"action":"run","subagent_type":"explore","description":"Find error recovery in parser","prompt":"Search src/parser.ts and adjacent files for error-recovery patterns. Return: each location's file:line + a one-sentence description of how it recovers. If you find catch blocks, panic-mode synchronization, or recovery sentinels, list them all."}})]
+</example>
+
+<example>
+user: "Verify the type checker is correct against spec.md §3"
+assistant: I'll spawn a general subagent to do an independent review.
+[actor({"operation":{"action":"run","subagent_type":"general","description":"Type checker spec review","prompt":"Read docs/spec.md §3 (Type System), then read src/types.ts and tests/types.test.ts. Report: (1) any §3 requirement not implemented; (2) any test that fails to cover a §3 requirement. Don't fix anything — just report findings."}})]
+</example>
+
+<example>
+user: "investigate T4's failing tests in the type checker"
+assistant: T4 is an active task in my tracker. I'll spawn an explore subagent bound to T4 so its findings end up in tasks/T4/progress.md and the next checkpoint can integrate them.
+[actor({"operation":{"action":"run","subagent_type":"explore","description":"Investigate T4 type checker failures","prompt":"Run `bun test src/types.test.ts` and report each failing case. For each failure: file:line of the assertion, the expected vs actual values, and the most likely root-cause hypothesis based on reading src/types.ts. Don't fix anything.","task_id":"T4"}})]
+</example>

package/src/tool/apply_patch.ts

@@ -0,0 +1,308 @@
+import z from "zod"
+import * as path from "path"
+import { Effect } from "effect"
+import * as Tool from "./tool"
+import { Bus } from "../bus"
+import { FileWatcher } from "../file/watcher"
+import { Instance } from "../project/instance"
+import { SessionCwd } from "./session-cwd"
+import { Patch } from "../patch"
+import { createTwoFilesPatch, diffLines } from "diff"
+import { assertWriteAllowed } from "./external-directory"
+import { trimDiff } from "./edit"
+import { LSP } from "../lsp"
+import { AppFileSystem } from "@mty-coder/shared/filesystem"
+import DESCRIPTION from "./apply_patch.txt"
+import { File } from "../file"
+import { Format } from "../format"
+import { Global } from "../global"
+
+const PatchParams = z.object({
+  patchText: z.string().describe("The full patch text that describes all changes to be made"),
+})
+
+export const ApplyPatchTool = Tool.define(
+  "apply_patch",
+  Effect.gen(function* () {
+    const lsp = yield* LSP.Service
+    const afs = yield* AppFileSystem.Service
+    const format = yield* Format.Service
+    const bus = yield* Bus.Service
+
+    const run = Effect.fn("ApplyPatchTool.execute")(function* (params: z.infer<typeof PatchParams>, ctx: Tool.Context) {
+      if (!params.patchText) {
+        return yield* Effect.fail(new Error("patchText is required"))
+      }
+
+      // Parse the patch to get hunks
+      let hunks: Patch.Hunk[]
+      try {
+        const parseResult = Patch.parsePatch(params.patchText)
+        hunks = parseResult.hunks
+      } catch (error) {
+        return yield* Effect.fail(new Error(`apply_patch verification failed: ${error}`))
+      }
+
+      if (hunks.length === 0) {
+        const normalized = params.patchText.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim()
+        if (normalized === "*** Begin Patch\n*** End Patch") {
+          return yield* Effect.fail(new Error("patch rejected: empty patch"))
+        }
+        return yield* Effect.fail(new Error("apply_patch verification failed: no hunks found"))
+      }
+
+      // Validate file paths and check permissions
+      const fileChanges: Array<{
+        filePath: string
+        oldContent: string
+        newContent: string
+        type: "add" | "update" | "delete" | "move"
+        movePath?: string
+        diff: string
+        additions: number
+        deletions: number
+      }> = []
+
+      let totalDiff = ""
+
+      for (const hunk of hunks) {
+        const filePath = path.resolve(SessionCwd.get(ctx.sessionID), hunk.path)
+        yield* assertWriteAllowed(ctx, filePath)
+
+        switch (hunk.type) {
+          case "add": {
+            const oldContent = ""
+            const newContent =
+              hunk.contents.length === 0 || hunk.contents.endsWith("\n") ? hunk.contents : `${hunk.contents}\n`
+            const diff = trimDiff(createTwoFilesPatch(filePath, filePath, oldContent, newContent))
+
+            let additions = 0
+            let deletions = 0
+            for (const change of diffLines(oldContent, newContent)) {
+              if (change.added) additions += change.count || 0
+              if (change.removed) deletions += change.count || 0
+            }
+
+            fileChanges.push({
+              filePath,
+              oldContent,
+              newContent,
+              type: "add",
+              diff,
+              additions,
+              deletions,
+            })
+
+            totalDiff += diff + "\n"
+            break
+          }
+
+          case "update": {
+            // Check if file exists for update
+            const stats = yield* afs.stat(filePath).pipe(Effect.catch(() => Effect.succeed(undefined)))
+            if (!stats || stats.type === "Directory") {
+              return yield* Effect.fail(
+                new Error(`apply_patch verification failed: Failed to read file to update: ${filePath}`),
+              )
+            }
+
+            const oldContent = yield* afs.readFileString(filePath)
+            let newContent = oldContent
+
+            // Apply the update chunks to get new content
+            try {
+              const fileUpdate = Patch.deriveNewContentsFromChunks(filePath, hunk.chunks)
+              newContent = fileUpdate.content
+            } catch (error) {
+              return yield* Effect.fail(new Error(`apply_patch verification failed: ${error}`))
+            }
+
+            const diff = trimDiff(createTwoFilesPatch(filePath, filePath, oldContent, newContent))
+
+            let additions = 0
+            let deletions = 0
+            for (const change of diffLines(oldContent, newContent)) {
+              if (change.added) additions += change.count || 0
+              if (change.removed) deletions += change.count || 0
+            }
+
+            const movePath = hunk.move_path ? path.resolve(SessionCwd.get(ctx.sessionID), hunk.move_path) : undefined
+            yield* assertWriteAllowed(ctx, movePath)
+
+            fileChanges.push({
+              filePath,
+              oldContent,
+              newContent,
+              type: hunk.move_path ? "move" : "update",
+              movePath,
+              diff,
+              additions,
+              deletions,
+            })
+
+            totalDiff += diff + "\n"
+            break
+          }
+
+          case "delete": {
+            const contentToDelete = yield* afs
+              .readFileString(filePath)
+              .pipe(
+                Effect.catch((error) =>
+                  Effect.fail(
+                    new Error(
+                      `apply_patch verification failed: ${error instanceof Error ? error.message : String(error)}`,
+                    ),
+                  ),
+                ),
+              )
+            const deleteDiff = trimDiff(createTwoFilesPatch(filePath, filePath, contentToDelete, ""))
+
+            const deletions = contentToDelete.split("\n").length
+
+            fileChanges.push({
+              filePath,
+              oldContent: contentToDelete,
+              newContent: "",
+              type: "delete",
+              diff: deleteDiff,
+              additions: 0,
+              deletions,
+            })
+
+            totalDiff += deleteDiff + "\n"
+            break
+          }
+        }
+      }
+
+      // Build per-file metadata for UI rendering (used for both permission and result)
+      const files = fileChanges.map((change) => ({
+        filePath: change.filePath,
+        relativePath: path.relative(Instance.worktree, change.movePath ?? change.filePath).replaceAll("\\", "/"),
+        type: change.type,
+        patch: change.diff,
+        additions: change.additions,
+        deletions: change.deletions,
+        movePath: change.movePath,
+      }))
+      const title = files.length === 1 ? files[0]!.relativePath : `${files.length} files`
+
+      // Check permissions if needed
+      const permissionChanges = fileChanges.filter(
+        (change) => !AppFileSystem.contains(path.join(Global.Path.data, "memory"), change.movePath ?? change.filePath),
+      )
+      // NOTE: permissionChanges already excludes memory-tree paths (filtered at
+      // the `permissionChanges` definition above), so this ask never fires for
+      // memory writes — the askEditUnlessMemory deferral used by write.ts/edit.ts
+      // is structurally already satisfied here. Left as a direct ctx.ask.
+      if (permissionChanges.length > 0) {
+        const relativePaths = permissionChanges.map((c) => path.relative(Instance.worktree, c.filePath).replaceAll("\\", "/"))
+        yield* ctx.ask({
+          permission: "edit",
+          patterns: relativePaths,
+          always: ["*"],
+          metadata: {
+            filepath: relativePaths.join(", "),
+            diff: permissionChanges.map((change) => change.diff).join("\n") + "\n",
+            files: files.filter(
+              (file) => !AppFileSystem.contains(path.join(Global.Path.data, "memory"), file.movePath ?? file.filePath),
+            ),
+          },
+        })
+      }
+
+      // Apply the changes
+      const updates: Array<{ file: string; event: "add" | "change" | "unlink" }> = []
+
+      for (const change of fileChanges) {
+        const edited = change.type === "delete" ? undefined : (change.movePath ?? change.filePath)
+        switch (change.type) {
+          case "add":
+            // Create parent directories (recursive: true is safe on existing/root dirs)
+
+            yield* afs.writeWithDirs(change.filePath, change.newContent)
+            updates.push({ file: change.filePath, event: "add" })
+            break
+
+          case "update":
+            yield* afs.writeWithDirs(change.filePath, change.newContent)
+            updates.push({ file: change.filePath, event: "change" })
+            break
+
+          case "move":
+            if (change.movePath) {
+              // Create parent directories (recursive: true is safe on existing/root dirs)
+
+              yield* afs.writeWithDirs(change.movePath!, change.newContent)
+              yield* afs.remove(change.filePath)
+              updates.push({ file: change.filePath, event: "unlink" })
+              updates.push({ file: change.movePath, event: "add" })
+            }
+            break
+
+          case "delete":
+            yield* afs.remove(change.filePath)
+            updates.push({ file: change.filePath, event: "unlink" })
+            break
+        }
+
+        if (edited) {
+          yield* format.file(edited)
+          yield* bus.publish(File.Event.Edited, { file: edited })
+        }
+      }
+
+      // Publish file change events
+      for (const update of updates) {
+        yield* bus.publish(FileWatcher.Event.Updated, update)
+      }
+
+      // Notify LSP of file changes and collect diagnostics
+      for (const change of fileChanges) {
+        if (change.type === "delete") continue
+        const target = change.movePath ?? change.filePath
+        yield* lsp.touchFile(target, true)
+      }
+      const diagnostics = yield* lsp.diagnostics()
+
+      // Generate output summary
+      const summaryLines = fileChanges.map((change) => {
+        if (change.type === "add") {
+          return `A ${path.relative(Instance.worktree, change.filePath).replaceAll("\\", "/")}`
+        }
+        if (change.type === "delete") {
+          return `D ${path.relative(Instance.worktree, change.filePath).replaceAll("\\", "/")}`
+        }
+        const target = change.movePath ?? change.filePath
+        return `M ${path.relative(Instance.worktree, target).replaceAll("\\", "/")}`
+      })
+      let output = `Success. Updated the following files:\n${summaryLines.join("\n")}`
+
+      for (const change of fileChanges) {
+        if (change.type === "delete") continue
+        const target = change.movePath ?? change.filePath
+        const block = LSP.Diagnostic.report(target, diagnostics[AppFileSystem.normalizePath(target)] ?? [])
+        if (!block) continue
+        const rel = path.relative(Instance.worktree, target).replaceAll("\\", "/")
+        output += `\n\nLSP errors detected in ${rel}, please fix:\n${block}`
+      }
+
+      return {
+        title,
+        metadata: {
+          diff: totalDiff,
+          files,
+          diagnostics,
+        },
+        output,
+      }
+    })
+
+    return {
+      description: DESCRIPTION,
+      parameters: PatchParams,
+      execute: (params: z.infer<typeof PatchParams>, ctx: Tool.Context) => run(params, ctx).pipe(Effect.orDie),
+    }
+  }),
+)

package/src/tool/apply_patch.txt

@@ -0,0 +1,33 @@
+Use the `apply_patch` tool to edit files. Your patch language is a stripped‑down, file‑oriented diff format designed to be easy to parse and safe to apply. You can think of it as a high‑level envelope:
+
+*** Begin Patch
+[ one or more file sections ]
+*** End Patch
+
+Within that envelope, you get a sequence of file operations.
+You MUST include a header to specify the action you are taking.
+Each operation starts with one of three headers:
+
+*** Add File: <path> - create a new file. Every following line is a + line (the initial contents).
+*** Delete File: <path> - remove an existing file. Nothing follows.
+*** Update File: <path> - patch an existing file in place (optionally with a rename).
+
+Example patch:
+
+```
+*** Begin Patch
+*** Add File: hello.txt
++Hello world
+*** Update File: src/app.py
+*** Move to: src/main.py
+@@ def greet():
+-print("Hi")
++print("Hello, world!")
+*** Delete File: obsolete.txt
+*** End Patch
+```
+
+It is important to remember:
+
+- You must include a header with your intended action (Add/Delete/Update)
+- You must prefix new lines with `+` even when creating a new file

package/src/tool/bash-interactive.ts

@@ -0,0 +1,183 @@
+import { Deferred, Effect, Layer, Context } from "effect"
+import { Bus } from "@/bus"
+import { BusEvent } from "@/bus/bus-event"
+import { InstanceState } from "@/effect"
+import { Log } from "@/util"
+import z from "zod"
+import crypto from "crypto"
+
+const log = Log.create({ service: "bash-interactive" })
+
+// Bus events
+
+export const Event = {
+  Asked: BusEvent.define(
+    "bash.interactive.asked",
+    z.object({
+      id: z.string(),
+      command: z.string(),
+      cwd: z.string(),
+      env: z.record(z.string(), z.string()).optional(),
+      description: z.string(),
+    }),
+  ),
+  Replied: BusEvent.define(
+    "bash.interactive.replied",
+    z.object({
+      id: z.string(),
+      output: z.string(),
+      exitCode: z.number(),
+    }),
+  ),
+}
+
+// Types
+
+export interface InteractiveRequest {
+  id: string
+  command: string
+  cwd: string
+  env?: Record<string, string>
+  description: string
+}
+
+export interface InteractiveResult {
+  output: string
+  exitCode: number
+}
+
+export class InteractiveError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "BashInteractiveError"
+  }
+}
+
+// Service
+
+interface PendingEntry {
+  request: InteractiveRequest
+  deferred: Deferred.Deferred<InteractiveResult, InteractiveError>
+}
+
+interface State {
+  pending: Map<string, PendingEntry>
+}
+
+export interface Interface {
+  readonly request: (input: {
+    command: string
+    cwd: string
+    env?: Record<string, string>
+    description: string
+  }) => Effect.Effect<InteractiveResult, InteractiveError>
+  readonly reply: (input: { id: string; output: string; exitCode: number }) => Effect.Effect<void>
+  readonly list: () => Effect.Effect<ReadonlyArray<InteractiveRequest>>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/BashInteractive") {}
+
+export const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const bus = yield* Bus.Service
+    const state = yield* InstanceState.make<State>(
+      Effect.fn("BashInteractive.state")(function* () {
+        const state: State = {
+          pending: new Map(),
+        }
+
+        yield* Effect.addFinalizer(() =>
+          Effect.gen(function* () {
+            for (const item of state.pending.values()) {
+              yield* Deferred.fail(item.deferred, new InteractiveError("Instance disposed"))
+            }
+            state.pending.clear()
+          }),
+        )
+
+        return state
+      }),
+    )
+
+    const request = Effect.fn("BashInteractive.request")(function* (input: {
+      command: string
+      cwd: string
+      env?: Record<string, string>
+      description: string
+    }) {
+      const pending = (yield* InstanceState.get(state)).pending
+      const id = crypto.randomUUID()
+      log.info("requesting interactive", { id, command: input.command })
+
+      const deferred = yield* Deferred.make<InteractiveResult, InteractiveError>()
+      const req: InteractiveRequest = {
+        id,
+        command: input.command,
+        cwd: input.cwd,
+        env: input.env,
+        description: input.description,
+      }
+      pending.set(id, { request: req, deferred })
+      yield* bus.publish(Event.Asked, req)
+
+      return yield* Effect.ensuring(
+        Deferred.await(deferred),
+        Effect.sync(() => {
+          pending.delete(id)
+        }),
+      )
+    })
+
+    const reply = Effect.fn("BashInteractive.reply")(function* (input: {
+      id: string
+      output: string
+      exitCode: number
+    }) {
+      const pending = (yield* InstanceState.get(state)).pending
+      const existing = pending.get(input.id)
+      if (!existing) {
+        log.warn("reply for unknown request", { id: input.id })
+        return
+      }
+      pending.delete(input.id)
+      log.info("replied", { id: input.id, exitCode: input.exitCode })
+      yield* bus.publish(Event.Replied, {
+        id: existing.request.id,
+        output: input.output,
+        exitCode: input.exitCode,
+      })
+      yield* Deferred.succeed(existing.deferred, {
+        output: input.output,
+        exitCode: input.exitCode,
+      })
+    })
+
+    const list = Effect.fn("BashInteractive.list")(function* () {
+      const pending = (yield* InstanceState.get(state)).pending
+      return Array.from(pending.values(), (x) => x.request)
+    })
+
+    return Service.of({ request, reply, list })
+  }),
+)
+
+export const defaultLayer = layer.pipe(Layer.provide(Bus.layer))
+
+// Standalone functions (uses the instance-scoped runtime, same pattern as Bus module)
+import { makeRuntime } from "@/effect/run-service"
+
+const { runPromise } = makeRuntime(Service, defaultLayer)
+
+export function request(input: {
+  command: string
+  cwd: string
+  env?: Record<string, string>
+  description: string
+}): Promise<InteractiveResult> {
+  return runPromise((svc) => svc.request(input))
+}
+
+export function reply(input: { id: string; output: string; exitCode: number }): Promise<void> {
+  return runPromise((svc) => svc.reply(input))
+}