@sleepy-ai/cli 0.0.0-main-202607032053 → 0.1.4

package/src/tool/task.shell.txt

@@ -0,0 +1,57 @@
+Persistent work-item tool (shell form). Tasks form a tree (T1, T2, ...;
+subtasks T1.1, T1.2, ...) with lifecycle:
+open ⇄ in_progress, either → blocked → open, either → done | abandoned.
+
+# Script structure
+#   - Multi-line: one command per non-blank line, set-e on first failure
+#   - "double" quotes preserve literal LF and process \" \\ escapes
+#   - 'single' quotes are verbatim
+#   - # starts a line comment to end-of-line (quoted # is literal text)
+
+# create:
+    task create "Implement auth"
+    # subtask: pass the parent's TID via --parent; the subtask's id nests under it (e.g. T1.1)
+    task create "Email/password login" --parent T1
+
+# multi-line summary — heredoc body is verbatim (no escape needed for " \ $ #):
+    task create <<EOF
+    Implement auth
+    - email/password
+    - oauth (google, github)
+    - regex /\b[A-Z]+_TOKEN\b/ for env scan
+    EOF
+
+# inspect:
+    task list [<status>] [--include-terminal] [--include-archived]   # default: open+in_progress+blocked
+    task list open                     # filter by status
+    task get T1
+
+# state-machine transitions:
+    task start T1 [--reason "<note>"]  # mark in_progress (working on it now)
+    task block T1 "waiting on spec"
+    task unblock T1 "spec resolved"
+    task done T1 "all tests pass"
+    task abandon T1 "out of scope"
+
+# rename:
+    task rename T1 "Updated title"
+
+# every verb accepts --session <id> to act on another session (default: current).
+
+# multi-command (one per line, set-e on first failure):
+    task create "Lexer"
+    task create "Parser"
+    task create "Type checker"
+
+Status values for `task list <status>`: open | in_progress | blocked | done | abandoned
+
+# Removed verbs (use the listed equivalents instead):
+#   progress       — progress is maintained by the checkpoint writer in the
+#                    session-level progress.md; you do not journal events
+#   approve        — proposed state was removed; new tasks start in 'open'
+#   revise         — task is rename-only; long descriptions belong in §1
+#                    Active intent or main progress.md sections
+#   create_sub     — use 'create' with parent_id
+
+# Don't repeat the task tree in your reply — the UI already shows it.
+# Just summarize what you're working on or what changed.

package/src/tool/task.ts

@@ -0,0 +1,456 @@
+import * as Tool from "./tool"
+import DESCRIPTION from "./task.txt"
+import SHELL_DESCRIPTION from "./task.shell.txt"
+import { tokenize } from "./shell-tokenize"
+import z from "zod"
+import { Effect } from "effect"
+import { TaskRegistry } from "@/task/registry"
+import type { SessionID } from "../session/schema"
+
+const KNOWN_VERBS = [
+  "create",
+  "list",
+  "get",
+  "start",
+  "block",
+  "unblock",
+  "done",
+  "abandon",
+  "rename",
+]
+
+function levenshtein(a: string, b: string): number {
+  const m = a.length, n = b.length
+  if (m === 0) return n
+  if (n === 0) return m
+  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0))
+  for (let i = 0; i <= m; i++) dp[i][0] = i
+  for (let j = 0; j <= n; j++) dp[0][j] = j
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost)
+    }
+  }
+  return dp[m][n]
+}
+
+function suggestVerb(input: string): string | undefined {
+  const candidates = KNOWN_VERBS.map((v) => ({ v, d: levenshtein(input, v) })).filter((c) => c.d <= 2)
+  if (candidates.length !== 1) return undefined
+  return candidates[0].v
+}
+
+const id = "task"
+
+const statusSchema = z.enum(["open", "in_progress", "blocked", "done", "abandoned"])
+
+const createOperation = z.strictObject({
+  action: z.literal("create"),
+  summary: z.string().min(1).describe("Task summary for a single task."),
+  parent_id: z.string().min(1).optional().describe("Parent task id for sub-tasks."),
+  session_id: z.string().min(1).optional().describe("Session id to act on. Defaults to current session."),
+})
+
+const listOperation = z.strictObject({
+  action: z.literal("list"),
+  status: statusSchema.optional().describe("Filter by status."),
+  include_terminal: z.boolean().optional().describe("Include done/abandoned tasks. Default false."),
+  include_archived: z.boolean().optional().describe("Include archived tasks. Default false."),
+  session_id: z.string().min(1).optional().describe("Session id to act on. Defaults to current session."),
+})
+
+const getOperation = z.strictObject({
+  action: z.literal("get"),
+  id: z.string().min(1).describe("Task id, e.g. T1 or T1.1."),
+  session_id: z.string().min(1).optional().describe("Session id to act on. Defaults to current session."),
+})
+
+const startOperation = z.strictObject({
+  action: z.literal("start"),
+  id: z.string().min(1).describe("Task id, e.g. T1 or T1.1."),
+  event_summary: z.string().min(1).optional().describe("Short note on starting."),
+  session_id: z.string().min(1).optional().describe("Session id to act on. Defaults to current session."),
+})
+
+const blockOperation = z.strictObject({
+  action: z.literal("block"),
+  id: z.string().min(1).describe("Task id, e.g. T1 or T1.1."),
+  event_summary: z.string().min(1).optional().describe("Short reason for blocking."),
+  session_id: z.string().min(1).optional().describe("Session id to act on. Defaults to current session."),
+})
+
+const unblockOperation = z.strictObject({
+  action: z.literal("unblock"),
+  id: z.string().min(1).describe("Task id, e.g. T1 or T1.1."),
+  event_summary: z.string().min(1).optional().describe("Short reason for unblocking."),
+  session_id: z.string().min(1).optional().describe("Session id to act on. Defaults to current session."),
+})
+
+const doneOperation = z.strictObject({
+  action: z.literal("done"),
+  id: z.string().min(1).describe("Task id, e.g. T1 or T1.1."),
+  event_summary: z.string().min(1).optional().describe("Short summary of what was completed."),
+  session_id: z.string().min(1).optional().describe("Session id to act on. Defaults to current session."),
+})
+
+const abandonOperation = z.strictObject({
+  action: z.literal("abandon"),
+  id: z.string().min(1).describe("Task id, e.g. T1 or T1.1."),
+  event_summary: z.string().min(1).optional().describe("Short reason for abandoning."),
+  session_id: z.string().min(1).optional().describe("Session id to act on. Defaults to current session."),
+})
+
+const renameOperation = z.strictObject({
+  action: z.literal("rename"),
+  id: z.string().min(1).describe("Task id, e.g. T1 or T1.1."),
+  summary: z.string().min(1).describe("New task summary."),
+  session_id: z.string().min(1).optional().describe("Session id to act on. Defaults to current session."),
+})
+
+const parameters = z.strictObject({
+  // .meta({ type: "object" }) is REQUIRED — without it, the emitted JSON
+  // schema's `operation` node has only `anyOf`, no `type`. Some models
+  // (notably sleepy-v2.5-pro) then stringify the entire envelope, producing
+  // {"operation":"{\"action\":\"create\",...}"} which fails zod validation.
+  // See research-tool-call-schema/REPORT.md §2.5 "success-nested" warning.
+  operation: z
+    .discriminatedUnion("action", [
+      createOperation,
+      listOperation,
+      getOperation,
+      startOperation,
+      blockOperation,
+      unblockOperation,
+      doneOperation,
+      abandonOperation,
+      renameOperation,
+    ])
+    .meta({ type: "object" }),
+})
+
+type TaskInput = z.infer<typeof parameters>
+type TaskOperation = TaskInput
+type TaskStatus = z.infer<typeof statusSchema>
+
+type Metadata = {
+  id?: string
+  status?: string
+  ids?: string[]
+  count?: number
+}
+
+function parseTaskScript(script: string): Effect.Effect<TaskOperation[], unknown> {
+  return Effect.gen(function* () {
+    const argvList = yield* tokenize(script)
+    const out: TaskOperation[] = []
+    for (const argv of argvList) {
+      const [head, verb, ...rest] = argv.tokens
+      if (head !== "task") {
+        return yield* Effect.fail({
+          kind: "unknown-verb",
+          line: argv.line,
+          detail: `task: every command must start with 'task' (got '${head ?? ""}')`,
+        })
+      }
+      const parsed = yield* mapVerb(verb, rest, argv.line)
+      out.push(parsed)
+    }
+    return out
+  })
+}
+
+// Recover a shell-mode task call shaped like the JSON args (no `script`):
+// a stringified/nested `operation`, or the common bare `{summary}` create.
+// Conservative — only the unambiguous create-from-summary is synthesized;
+// anything else passes through (nested) or returns undefined (→ teach JSON).
+export function recoverTaskArgs(rawArgs: unknown): TaskOperation | undefined {
+  if (rawArgs == null || typeof rawArgs !== "object") return undefined
+  let obj = rawArgs as Record<string, unknown>
+  if (typeof obj.operation === "string") {
+    try {
+      const inner = JSON.parse(obj.operation)
+      if (inner && typeof inner === "object" && !Array.isArray(inner)) obj = { operation: inner }
+    } catch {}
+  }
+  if (obj.operation && typeof obj.operation === "object" && !Array.isArray(obj.operation))
+    return { operation: obj.operation } as TaskOperation
+  if (typeof obj.summary === "string") {
+    const op: Record<string, unknown> = { action: "create", summary: obj.summary }
+    if (typeof obj.parent_id === "string") op.parent_id = obj.parent_id
+    if (typeof obj.session_id === "string") op.session_id = obj.session_id
+    return { operation: op } as TaskOperation
+  }
+  return undefined
+}
+
+// Extract a fixed set of `--name value` / `--name=value` string flags and
+// boolean presence flags from a verb's args, leaving positionals in `rest`.
+// Synchronous (task's mapVerb is sync, unlike actor's Effect-returning extractor).
+// A value flag with no value (`--session` at end, or `--session=`) sets `error`
+// rather than silently dropping — mirrors actor's extractNamedFlags contract so a
+// dangling flag never swallows a positional into a confusing arity error.
+function extractTaskFlags(
+  args: string[],
+  valueFlags: string[],
+  boolFlags: string[],
+): { flags: Record<string, string>; bools: Record<string, boolean>; rest: string[]; error?: string } {
+  const rest: string[] = []
+  const flags: Record<string, string> = {}
+  const bools: Record<string, boolean> = {}
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    const boolName = boolFlags.find((n) => a === `--${n}`)
+    if (boolName) {
+      bools[boolName] = true
+      continue
+    }
+    const valName = valueFlags.find((n) => a === `--${n}`)
+    if (valName) {
+      const next = args[i + 1]
+      if (next === undefined) return { flags, bools, rest, error: `--${valName} requires a value` }
+      flags[valName] = next
+      i++
+      continue
+    }
+    const eq = valueFlags.find((n) => a.startsWith(`--${n}=`))
+    if (eq) {
+      const v = a.slice(`--${eq}=`.length)
+      if (v === "") return { flags, bools, rest, error: `--${eq} requires a value` }
+      flags[eq] = v
+      continue
+    }
+    rest.push(a)
+  }
+  return { flags, bools, rest }
+}
+
+function flagError(verb: string, detail: string, line: number) {
+  return Effect.fail({ kind: "flag", line, detail: `task: ${verb}: ${detail}` })
+}
+
+function mapVerb(verb: string | undefined, args: string[], line: number): Effect.Effect<TaskOperation, unknown> {
+  switch (verb) {
+    case "create": {
+      const { flags, rest, error } = extractTaskFlags(args, ["parent", "session"], [])
+      if (error) return flagError("create", error, line)
+      if (rest.length !== 1) return arityError("create", '<summary> [--parent <TID>] [--session <id>]', rest, line)
+      return Effect.succeed({
+        operation: {
+          action: "create" as const,
+          summary: rest[0],
+          ...(flags.parent ? { parent_id: flags.parent } : {}),
+          ...(flags.session ? { session_id: flags.session } : {}),
+        },
+      })
+    }
+    case "list": {
+      const { flags, bools, rest, error } = extractTaskFlags(args, ["session"], ["include-terminal", "include-archived"])
+      if (error) return flagError("list", error, line)
+      if (rest.length > 1) return arityError("list", "[<status>] [--include-terminal] [--include-archived] [--session <id>]", rest, line)
+      return Effect.succeed({
+        operation: {
+          action: "list" as const,
+          ...(rest.length === 1 ? { status: rest[0] as TaskStatus } : {}),
+          ...(bools["include-terminal"] ? { include_terminal: true } : {}),
+          ...(bools["include-archived"] ? { include_archived: true } : {}),
+          ...(flags.session ? { session_id: flags.session } : {}),
+        },
+      })
+    }
+    case "get": {
+      const { flags, rest, error } = extractTaskFlags(args, ["session"], [])
+      if (error) return flagError("get", error, line)
+      if (rest.length !== 1) return arityError("get", "<id> [--session <id>]", rest, line)
+      return Effect.succeed({ operation: { action: "get" as const, id: rest[0], ...(flags.session ? { session_id: flags.session } : {}) } })
+    }
+    case "start": {
+      const { flags, rest, error } = extractTaskFlags(args, ["reason", "session"], [])
+      if (error) return flagError("start", error, line)
+      if (rest.length !== 1) return arityError("start", "<id> [--reason <note>] [--session <id>]", rest, line)
+      return Effect.succeed({
+        operation: {
+          action: "start" as const,
+          id: rest[0],
+          ...(flags.reason ? { event_summary: flags.reason } : {}),
+          ...(flags.session ? { session_id: flags.session } : {}),
+        },
+      })
+    }
+    case "block": {
+      const { flags, rest, error } = extractTaskFlags(args, ["session"], [])
+      if (error) return flagError("block", error, line)
+      if (rest.length !== 2) return arityError("block", "<id> <reason> [--session <id>]", rest, line)
+      return Effect.succeed({ operation: { action: "block" as const, id: rest[0], event_summary: rest[1], ...(flags.session ? { session_id: flags.session } : {}) } })
+    }
+    case "unblock": {
+      const { flags, rest, error } = extractTaskFlags(args, ["session"], [])
+      if (error) return flagError("unblock", error, line)
+      if (rest.length !== 2) return arityError("unblock", "<id> <reason> [--session <id>]", rest, line)
+      return Effect.succeed({ operation: { action: "unblock" as const, id: rest[0], event_summary: rest[1], ...(flags.session ? { session_id: flags.session } : {}) } })
+    }
+    case "done": {
+      const { flags, rest, error } = extractTaskFlags(args, ["session"], [])
+      if (error) return flagError("done", error, line)
+      if (rest.length !== 2) return arityError("done", "<id> <summary> [--session <id>]", rest, line)
+      return Effect.succeed({ operation: { action: "done" as const, id: rest[0], event_summary: rest[1], ...(flags.session ? { session_id: flags.session } : {}) } })
+    }
+    case "abandon": {
+      const { flags, rest, error } = extractTaskFlags(args, ["session"], [])
+      if (error) return flagError("abandon", error, line)
+      if (rest.length !== 2) return arityError("abandon", "<id> <reason> [--session <id>]", rest, line)
+      return Effect.succeed({ operation: { action: "abandon" as const, id: rest[0], event_summary: rest[1], ...(flags.session ? { session_id: flags.session } : {}) } })
+    }
+    case "rename": {
+      const { flags, rest, error } = extractTaskFlags(args, ["session"], [])
+      if (error) return flagError("rename", error, line)
+      if (rest.length !== 2) return arityError("rename", "<id> <summary> [--session <id>]", rest, line)
+      return Effect.succeed({ operation: { action: "rename" as const, id: rest[0], summary: rest[1], ...(flags.session ? { session_id: flags.session } : {}) } })
+    }
+    default: {
+      const suggestion = suggestVerb(verb ?? "")
+      const detail =
+        `task: unknown verb "${verb ?? ""}"\n` +
+        `  available verbs: ${KNOWN_VERBS.join(", ")}` +
+        (suggestion ? `\n  did you mean: ${suggestion}?` : "")
+      return Effect.fail({ kind: "unknown-verb", line, detail })
+    }
+  }
+}
+
+function arityError(verb: string, expected: string, args: string[], line: number) {
+  return Effect.fail({
+    kind: "arity",
+    line,
+    detail: `task: ${verb}: arity mismatch\n  got:      task ${verb} ${args.join(" ")}\n  expected: task ${verb} ${expected}`,
+  })
+}
+
+export const TaskTool = Tool.define<typeof parameters, Metadata, TaskRegistry.Service>(
+  id,
+  Effect.gen(function* () {
+    const reg = yield* TaskRegistry.Service
+
+    const run = Effect.fn("TaskTool.execute")(function* (input: TaskInput, ctx: Tool.Context<Metadata>) {
+      const op = input.operation
+      const sessionID = (op.session_id || ctx.sessionID) as SessionID
+
+      if (op.action === "create") {
+        const t = yield* reg.create({
+          session_id: sessionID,
+          summary: op.summary,
+          parent_id: op.parent_id || undefined,
+          owner: ctx.actorID ?? ctx.agent,
+        })
+        return {
+          title: `Task created: ${t.id}`,
+          output: `Created ${t.id} (${t.status}): ${t.summary}`,
+          metadata: { id: t.id, status: t.status } as Metadata,
+        }
+      }
+
+      if (op.action === "list") {
+        const tasks = yield* reg.list({
+          session_id: sessionID,
+          status: op.status,
+          include_terminal: op.include_terminal,
+          include_archived: op.include_archived,
+        })
+        const lines =
+          tasks.length === 0
+            ? ["No tasks."]
+            : tasks.map((t) => {
+                return `${t.id} ${t.status} — ${t.summary}`
+              })
+        return {
+          title: `Tasks: ${tasks.length}`,
+          output: lines.join("\n"),
+          metadata: { count: tasks.length, ids: tasks.map((t) => t.id) } as Metadata,
+        }
+      }
+
+      if (op.action === "get") {
+        const t = yield* reg.get({ session_id: sessionID, id: op.id })
+        if (!t)
+          return {
+            title: `Task ${op.id}: not found`,
+            output: `No task ${op.id}. Use \`task list\` to see valid task IDs.`,
+            metadata: {} as Metadata,
+          }
+        return {
+          title: `Task ${op.id}: ${t.status}`,
+          output: JSON.stringify(t, null, 2),
+          metadata: { id: t.id, status: t.status } as Metadata,
+        }
+      }
+
+      if (op.action === "start") {
+        const result = yield* reg.start({ session_id: sessionID, id: op.id, owner: ctx.actorID ?? ctx.agent, event_summary: op.event_summary })
+        return {
+          title: `Task ${op.id}: ${result.status}`,
+          output: `start → ${result.status}`,
+          metadata: { id: result.id, status: result.status } as Metadata,
+        }
+      }
+
+      if (op.action === "block") {
+        const result = yield* reg.block({ session_id: sessionID, id: op.id, event_summary: op.event_summary })
+        return {
+          title: `Task ${op.id}: blocked`,
+          output: `block → ${result.status}`,
+          metadata: { id: result.id, status: result.status } as Metadata,
+        }
+      }
+
+      if (op.action === "unblock") {
+        const result = yield* reg.unblock({ session_id: sessionID, id: op.id, event_summary: op.event_summary })
+        return {
+          title: `Task ${op.id}: ${result.status}`,
+          output: `unblock → ${result.status}`,
+          metadata: { id: result.id, status: result.status } as Metadata,
+        }
+      }
+
+      if (op.action === "done") {
+        const result = yield* reg.done({ session_id: sessionID, id: op.id, event_summary: op.event_summary })
+        return {
+          title: `Task ${op.id}: done`,
+          output: `done → ${result.status}`,
+          metadata: { id: result.id, status: result.status } as Metadata,
+        }
+      }
+
+      if (op.action === "abandon") {
+        const result = yield* reg.abandon({ session_id: sessionID, id: op.id, event_summary: op.event_summary })
+        return {
+          title: `Task ${op.id}: abandoned`,
+          output: `abandon → ${result.status}`,
+          metadata: { id: result.id, status: result.status } as Metadata,
+        }
+      }
+
+      if (op.action === "rename") {
+        const result = yield* reg.rename({ session_id: sessionID, id: op.id, summary: op.summary })
+        return {
+          title: `Task ${op.id}: renamed`,
+          output: `rename → "${result.summary}"`,
+          metadata: { id: result.id, status: result.status } as Metadata,
+        }
+      }
+
+      return yield* Effect.fail(new Error(`Unknown operation: ${(op as { action: string }).action}`))
+    })
+
+    return {
+      description: DESCRIPTION,
+      parameters,
+      execute: (args: z.infer<typeof parameters>, ctx: Tool.Context<Metadata>) =>
+        run(args, ctx).pipe(Effect.orDie),
+      shell: {
+        description: SHELL_DESCRIPTION,
+        parse: parseTaskScript,
+        recover: recoverTaskArgs,
+      },
+    } satisfies Tool.DefWithoutID<typeof parameters, Metadata>
+  }),
+)

package/src/tool/task.txt

@@ -0,0 +1,56 @@
+Persistent work-item tool. Tasks are bounded, referenceable entities with
+IDs (T1, T2, ...; subtasks T1.1, T1.2, ...). This is the only work-item
+tool — use it to track every multi-step piece of work: what you're doing
+now, what's queued, what's blocked, what's done.
+
+JSON calls always wrap the action in an `operation` object — see examples below.
+
+## Operations
+
+- create:     register a new task. `summary` required. optional: `parent_id`.
+- list:       enumerate tasks. defaults to open+in_progress+blocked, excluding archived.
+              optional: `status` filter, `include_terminal`, `include_archived`.
+- get:        fetch one task by id.
+- start:      mark a task in_progress (you're working on it now). `id` required.
+- block:      transition → blocked. `id` required. optional: `event_summary`.
+- unblock:    transition blocked → open. `id` required. optional: `event_summary`.
+- done:       mark task complete. `id` required. optional: `event_summary`.
+- abandon:    drop task without completing. `id` required. optional: `event_summary`.
+- rename:     change a task's summary. `id` + `summary` required.
+
+Status lifecycle: open ⇄ in_progress, either → blocked → open, either → done | abandoned.
+Mark a task `start` before working it; `done` immediately after finishing.
+Terminal states clean up automatically after `checkpoint.task_archive_days` (default 7 days).
+
+## JSON examples
+
+{"operation":{"action":"create","summary":"Implement auth"}}
+{"operation":{"action":"create","summary":"Lexer","parent_id":"T1"}}
+{"operation":{"action":"list"}}
+{"operation":{"action":"get","id":"T1"}}
+{"operation":{"action":"start","id":"T1"}}
+{"operation":{"action":"block","id":"T1","event_summary":"waiting on spec"}}
+{"operation":{"action":"unblock","id":"T1","event_summary":"spec resolved"}}
+{"operation":{"action":"done","id":"T1","event_summary":"all tests pass"}}
+{"operation":{"action":"abandon","id":"T1","event_summary":"out of scope"}}
+{"operation":{"action":"rename","id":"T1","summary":"Updated title"}}
+
+## Discipline
+
+- Only mark `done` when the work is FULLY accomplished. If tests fail, the
+  implementation is partial, or you hit an unresolved error, keep it
+  in_progress or `block` it — never `done`.
+- If blocked, `block` the task or create a new task describing the blocker.
+- Keep one task in_progress at a time when working solo (not enforced —
+  parallel subagents may each have their own in_progress task).
+
+## When to use
+
+Use task whenever work has 3+ steps, spans multiple turns, will be referenced
+again (by you, the user, or a subagent), or needs to be visible in the session.
+Skip it for a single trivial action.
+
+## Don't repeat in your reply
+
+Do not list out the task tree in your reply — the UI already renders it.
+Summarize what task you're working on or what changed since the last call.