@bosun-sh/logbook 1.0.0

package/src/mcp/tool-edit-task.ts

@@ -0,0 +1,40 @@
+import { Effect, Either, type Layer } from "effect"
+import { z } from "zod"
+import type { EditTaskInput } from "../task/edit-task.js"
+import { editTask } from "../task/edit-task.js"
+import type { TaskRepository } from "../task/ports.js"
+
+const InputSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  definition_of_done: z.string().optional(),
+  predictedKTokens: z.number().positive().optional(),
+  priority: z.number().int().min(0).optional(),
+})
+
+export const toolEditTask = (
+  rawInput: unknown,
+  layer: Layer.Layer<TaskRepository>
+): Promise<{ task: unknown }> => {
+  const parsed = InputSchema.parse(rawInput)
+  const { id } = parsed
+  // Build updates by omitting undefined fields (exact optional property types compliance)
+  const updates: EditTaskInput = {}
+  if (parsed.title !== undefined) updates.title = parsed.title
+  if (parsed.description !== undefined) updates.description = parsed.description
+  if (parsed.definition_of_done !== undefined)
+    updates.definition_of_done = parsed.definition_of_done
+  if (parsed.predictedKTokens !== undefined) updates.predictedKTokens = parsed.predictedKTokens
+  if (parsed.priority !== undefined) updates.priority = parsed.priority
+
+  return Effect.runPromise(
+    Effect.provide(
+      Effect.either(editTask(id, updates).pipe(Effect.map((task) => ({ task })))),
+      layer
+    )
+  ).then((either) => {
+    if (Either.isLeft(either)) throw either.left
+    return either.right
+  })
+}

package/src/mcp/tool-list-tasks.ts

@@ -0,0 +1,34 @@
+import { Effect, Either, type Layer } from "effect"
+import { z } from "zod"
+import { StatusSchema } from "../domain/types.js"
+import { listTasks } from "../task/list-tasks.js"
+import type { TaskRepository } from "../task/ports.js"
+
+const InputSchema = z.object({
+  status: z.union([StatusSchema, z.literal("*")]).default("in_progress"),
+  project: z.string().optional(),
+  milestone: z.string().optional(),
+})
+
+export const toolListTasks = (
+  rawInput: unknown,
+  layer: Layer.Layer<TaskRepository>
+): Promise<{ tasks: unknown[] }> => {
+  const input = InputSchema.parse(rawInput)
+  const options = {
+    status: input.status,
+    ...(input.project !== undefined ? { project: input.project } : {}),
+    ...(input.milestone !== undefined ? { milestone: input.milestone } : {}),
+  }
+  return Effect.runPromise(
+    Effect.provide(
+      Effect.either(
+        listTasks(options).pipe(Effect.map((tasks) => ({ tasks: tasks as unknown[] })))
+      ),
+      layer
+    )
+  ).then((either) => {
+    if (Either.isLeft(either)) throw either.left
+    return either.right
+  })
+}

package/src/mcp/tool-update-task.ts

@@ -0,0 +1,55 @@
+import { Effect, Either, type Layer } from "effect"
+import { z } from "zod"
+import { CommentKindSchema, StatusSchema } from "../domain/types.js"
+import type { HookRunner } from "../hook/ports.js"
+import type { TaskRepository } from "../task/ports.js"
+import type { SessionRegistry } from "../task/session-registry.js"
+import { updateTask } from "../task/update-task.js"
+
+const CommentInputSchema = z
+  .object({
+    id: z.string().uuid().optional(), // provided only when replying to an existing comment
+    title: z.string().min(1),
+    content: z.string(),
+    reply: z.string().optional(), // reply text; only meaningful when id is provided
+    kind: CommentKindSchema,
+  })
+  .optional()
+
+const InputSchema = z.object({
+  id: z.string().min(1),
+  new_status: StatusSchema,
+  comment: CommentInputSchema,
+})
+
+export const toolUpdateTask = (
+  rawInput: unknown,
+  sessionId: string,
+  layer: Layer.Layer<TaskRepository | HookRunner | SessionRegistry>
+): Promise<{ ok: boolean }> => {
+  const input = InputSchema.parse(rawInput)
+  const comment = input.comment
+    ? {
+        id: input.comment.id ?? crypto.randomUUID(),
+        timestamp: new Date(),
+        title: input.comment.title,
+        content: input.comment.content,
+        reply: input.comment.reply ?? "",
+        kind: input.comment.kind,
+      }
+    : null
+
+  return Effect.runPromise(
+    Effect.provide(
+      Effect.either(
+        updateTask(input.id, input.new_status, comment, sessionId).pipe(
+          Effect.map(() => ({ ok: true }))
+        )
+      ),
+      layer
+    )
+  ).then((either) => {
+    if (Either.isLeft(either)) throw either.left
+    return either.right
+  })
+}

package/src/task/create-task.ts

@@ -0,0 +1,67 @@
+import { Effect } from "effect"
+import { estimateFromKTokens } from "../domain/kTokens.js"
+import type { Task, TaskError } from "../domain/types.js"
+import { TaskRepository } from "./ports.js"
+
+export interface CreateTaskInput {
+  project: string
+  milestone: string
+  title: string
+  definition_of_done: string
+  description: string
+  predictedKTokens: number
+  priority?: number
+}
+
+/**
+ * Creates a new task in `backlog` status with no assignee.
+ * Validates all fields and derives a Fibonacci estimation from predictedKTokens.
+ */
+export const createTask = (
+  input: CreateTaskInput
+): Effect.Effect<Task, TaskError, TaskRepository> => {
+  // Validate required string fields
+  const requiredStringFields: Array<keyof CreateTaskInput> = [
+    "project",
+    "milestone",
+    "title",
+    "definition_of_done",
+    "description",
+  ]
+
+  for (const field of requiredStringFields) {
+    if (typeof input[field] !== "string" || input[field] === "") {
+      return Effect.fail({
+        _tag: "validation_error" as const,
+        message: `${field} is required`,
+      })
+    }
+  }
+
+  // Validate predictedKTokens is defined and a number
+  if (input.predictedKTokens === undefined || input.predictedKTokens === null) {
+    return Effect.fail({
+      _tag: "validation_error" as const,
+      message: "predictedKTokens is required",
+    })
+  }
+
+  // Derive Fibonacci estimation from kTokens
+  return Effect.flatMap(estimateFromKTokens(input.predictedKTokens), (estimation) => {
+    const id = crypto.randomUUID()
+    const task: Task = {
+      project: input.project,
+      milestone: input.milestone,
+      id,
+      title: input.title,
+      definition_of_done: input.definition_of_done,
+      description: input.description,
+      estimation,
+      comments: [],
+      status: "backlog" as const,
+      priority: input.priority ?? 0,
+    }
+
+    return Effect.flatMap(TaskRepository, (repo) => repo.save(task)).pipe(Effect.map(() => task))
+  })
+}

package/src/task/current-task.ts

@@ -0,0 +1,111 @@
+import { Effect } from "effect"
+import type { Agent, Task, TaskError } from "../domain/types.js"
+import type { TaskRepository as TaskRepositoryType } from "./ports.js"
+import { TaskRepository } from "./ports.js"
+import { SessionRegistry } from "./session-registry.js"
+
+/**
+ * Returns the best available task for the given session, claiming it if needed.
+ *
+ * Priority chain:
+ *   1. Own in_progress  — already assigned to this session → return highest-priority
+ *   2. Unassigned in_progress — no assignee → claim highest-priority, return
+ *   3. Orphaned in_progress — dead-session assignee → claim highest-priority, return
+ *   4. Highest-priority todo — auto-transition to in_progress, claim, return
+ *   5. Nothing → fail `no_current_task`
+ *
+ * Ties in priority are broken by in_progress_since ASC (oldest first).
+ * Claiming is a direct repo.update — no hooks, no HookRunner dependency.
+ */
+export const currentTask = (
+  sessionId: string
+): Effect.Effect<Task, TaskError, TaskRepository | SessionRegistry> =>
+  Effect.flatMap(TaskRepository, (repo) =>
+    Effect.flatMap(repo.findByStatus("in_progress"), (inProgress) => {
+      const own = inProgress.filter((t) => t.assignee?.id === sessionId)
+      if (own.length > 0) return Effect.succeed(pickHighestPriority(own))
+
+      return stepUnassigned(inProgress, sessionId, repo).pipe(
+        Effect.catchTag("no_current_task", () =>
+          stepOrphan(sessionId, inProgress, repo).pipe(
+            Effect.catchTag("no_current_task", () => stepTodo(sessionId, repo))
+          )
+        )
+      )
+    })
+  )
+
+const pickHighestPriority = <T extends Task>(tasks: readonly T[]): T => {
+  const sorted = [...tasks].sort((a, b) => {
+    if (b.priority !== a.priority) return b.priority - a.priority
+    const aTime = a.in_progress_since?.getTime() ?? Infinity
+    const bTime = b.in_progress_since?.getTime() ?? Infinity
+    return aTime - bTime
+  })
+  // biome-ignore lint/style/noNonNullAssertion: caller guarantees non-empty
+  return sorted[0]!
+}
+
+const claimTask = (
+  task: Task,
+  newAssignee: Agent,
+  repo: TaskRepositoryType
+): Effect.Effect<Task, TaskError, never> => {
+  const claimed = { ...task, assignee: newAssignee }
+  return Effect.map(repo.update(claimed), () => claimed)
+}
+
+const stepUnassigned = (
+  inProgress: readonly Task[],
+  sessionId: string,
+  repo: TaskRepositoryType
+): Effect.Effect<Task, TaskError, never> => {
+  const unassigned = inProgress.filter((t) => t.assignee === undefined)
+  if (unassigned.length === 0) return Effect.fail({ _tag: "no_current_task" as const })
+  const oldest = pickHighestPriority(unassigned)
+  return claimTask(oldest, { id: sessionId, title: "Agent", description: "" }, repo)
+}
+
+const stepOrphan = (
+  sessionId: string,
+  candidates: readonly Task[],
+  repo: TaskRepositoryType
+): Effect.Effect<Task, TaskError, SessionRegistry> => {
+  const foreign = candidates.filter(
+    (t): t is Task & { assignee: Agent } => t.assignee !== undefined && t.assignee.id !== sessionId
+  )
+  if (foreign.length === 0) return Effect.fail({ _tag: "no_current_task" as const })
+  return Effect.flatMap(SessionRegistry, (registry) =>
+    Effect.flatMap(
+      Effect.forEach(foreign, (t) =>
+        registry.isAlive(t.assignee.id).pipe(Effect.map((alive) => ({ task: t, alive })))
+      ),
+      (results) => {
+        const orphans = results.filter((r) => !r.alive).map((r) => r.task)
+        if (orphans.length === 0) return Effect.fail({ _tag: "no_current_task" as const })
+        const oldest = pickHighestPriority(orphans)
+        return claimTask(oldest, { ...oldest.assignee, id: sessionId }, repo)
+      }
+    )
+  )
+}
+
+const stepTodo = (
+  sessionId: string,
+  repo: TaskRepositoryType
+): Effect.Effect<Task, TaskError, never> =>
+  Effect.flatMap(repo.findByStatus("todo"), (todos) => {
+    if (todos.length === 0) return Effect.fail({ _tag: "no_current_task" as const })
+    // biome-ignore lint/style/noNonNullAssertion: length guard above
+    const best = [...todos].sort((a, b) => b.priority - a.priority)[0]!
+    const claimed: Task = {
+      ...best,
+      status: "in_progress",
+      assignee: {
+        ...(best.assignee ?? { title: "Agent", description: "" }),
+        id: sessionId,
+      },
+      in_progress_since: new Date(),
+    }
+    return Effect.map(repo.update(claimed), () => claimed)
+  })

package/src/task/edit-task.ts

@@ -0,0 +1,59 @@
+import { Effect } from "effect"
+import { estimateFromKTokens } from "../domain/kTokens.js"
+import type { Task, TaskError } from "../domain/types.js"
+import { TaskRepository } from "./ports.js"
+
+export interface EditTaskInput {
+  title?: string
+  description?: string
+  definition_of_done?: string
+  predictedKTokens?: number
+  priority?: number
+}
+
+/**
+ * Edits mutable fields of an existing task without changing its status.
+ * Derives Fibonacci estimation from predictedKTokens when provided.
+ * Fails with `not_found` for unknown id.
+ * Fails with `validation_error` when a `status` field is attempted via EditTaskInput.
+ */
+export const editTask = (
+  id: string,
+  updates: EditTaskInput
+): Effect.Effect<Task, TaskError, TaskRepository> => {
+  // Check for attempted status modification (runtime guard against type system bypass)
+  if ("status" in updates) {
+    return Effect.fail({
+      _tag: "validation_error" as const,
+      message: "status field cannot be edited",
+    })
+  }
+
+  // Derive estimation from predictedKTokens if present
+  if (updates.predictedKTokens !== undefined) {
+    return Effect.flatMap(estimateFromKTokens(updates.predictedKTokens), (estimation) =>
+      Effect.flatMap(TaskRepository, (repo) =>
+        Effect.flatMap(repo.findById(id), (task) => {
+          const { predictedKTokens: _, ...rest } = updates
+          const updatedTask: Task = {
+            ...task,
+            ...rest,
+            estimation,
+          }
+          return Effect.flatMap(repo.update(updatedTask), () => Effect.succeed(updatedTask))
+        })
+      )
+    )
+  }
+
+  // No estimation to derive, proceed directly with find and update
+  return Effect.flatMap(TaskRepository, (repo) =>
+    Effect.flatMap(repo.findById(id), (task) => {
+      const updatedTask: Task = {
+        ...task,
+        ...updates,
+      }
+      return Effect.flatMap(repo.update(updatedTask), () => Effect.succeed(updatedTask))
+    })
+  )
+}

package/src/task/list-tasks.ts

@@ -0,0 +1,35 @@
+import { Effect } from "effect"
+import type { Status, Task, TaskError } from "../domain/types.js"
+import { TaskRepository } from "./ports.js"
+
+type ListTasksOptions = {
+  status: Status | "*"
+  project?: string
+  milestone?: string
+}
+
+const applyFilters = (tasks: readonly Task[], options: ListTasksOptions): readonly Task[] => {
+  let result = tasks
+  if (options.project !== undefined) {
+    result = result.filter((t) => t.project === options.project)
+  }
+  if (options.milestone !== undefined) {
+    result = result.filter((t) => t.milestone === options.milestone)
+  }
+  return result
+}
+
+/**
+ * Returns tasks matching the given status (and optional project/milestone), or all tasks when status is '*'.
+ * Filters compose: all provided filters must match.
+ * Results are ordered by priority DESC.
+ * Fails with `validation_error` when the underlying data is malformed.
+ */
+export const listTasks = (
+  options: ListTasksOptions
+): Effect.Effect<readonly Task[], TaskError, TaskRepository> =>
+  Effect.flatMap(TaskRepository, (repo) =>
+    Effect.map(repo.findByStatus(options.status), (tasks) =>
+      [...applyFilters(tasks, options)].sort((a, b) => b.priority - a.priority)
+    )
+  )

package/src/task/ports.ts

@@ -0,0 +1,15 @@
+import { Context, type Effect } from "effect"
+import type { Status, Task, TaskError } from "../domain/types.js"
+
+export interface TaskRepository {
+  /** Fails with `not_found` if id is absent. */
+  findById(id: string): Effect.Effect<Task, TaskError>
+  /** Returns empty array when nothing matches; fails with `validation_error` on malformed data. */
+  findByStatus(status: Status | "*"): Effect.Effect<readonly Task[], TaskError>
+  /** Fails with `conflict` if a task with the same id already exists. */
+  save(task: Task): Effect.Effect<void, TaskError>
+  /** Fails with `not_found` if id is absent. */
+  update(task: Task): Effect.Effect<void, TaskError>
+}
+
+export const TaskRepository = Context.GenericTag<TaskRepository>("TaskRepository")

package/src/task/session-registry.ts

@@ -0,0 +1,9 @@
+import { Context, type Effect } from "effect"
+
+export interface SessionRegistry {
+  isAlive(sessionId: string): Effect.Effect<boolean, never>
+  register(sessionId: string, pid: number): Effect.Effect<void, never>
+  deregister(sessionId: string): Effect.Effect<void, never>
+}
+
+export const SessionRegistry = Context.GenericTag<SessionRegistry>("SessionRegistry")

package/src/task/update-task.ts

@@ -0,0 +1,160 @@
+import { Effect } from "effect"
+import { guardTransition } from "../domain/status-machine.js"
+import type { Comment, Status, TaskError } from "../domain/types.js"
+import { HookRunner } from "../hook/ports.js"
+import { TaskRepository } from "./ports.js"
+import { SessionRegistry } from "./session-registry.js"
+
+/**
+ * Transitions a task to a new status, optionally attaching or replying to a comment.
+ * Enforces transition rules, comment requirements, need_info reply cycle,
+ * and concurrent in_progress justification.
+ * Fires HookRunner after a successful status change.
+ */
+export const updateTask = (
+  id: string,
+  newStatus: Status,
+  comment: Comment | null,
+  sessionId: string
+): Effect.Effect<void, TaskError, TaskRepository | HookRunner | SessionRegistry> =>
+  Effect.gen(function* () {
+    const repo = yield* TaskRepository
+    const hookRunner = yield* HookRunner
+
+    // Step 1: find task or fail with not_found
+    const task = yield* repo.findById(id)
+
+    // Step 2: guard transition (same→same is allowed by guardTransition too)
+    // Pass task id so review tasks can skip pending_review and go directly to done
+    yield* guardTransition(task.status, newStatus, task.id)
+
+    // Step 4: reply handling — comment id matches an existing comment
+    // Must run before the no-op check because a reply update is meaningful
+    // even when the status is not changing.
+    if (comment !== null) {
+      const existing = task.comments.find((c) => c.id === comment.id)
+      if (existing !== undefined) {
+        if (existing.kind === "regular") {
+          return yield* Effect.fail<TaskError>({
+            _tag: "validation_error",
+            message: "reply is only valid on need_info comments",
+            context: { commentId: existing.id, commentKind: existing.kind },
+          })
+        }
+        // existing.kind === 'need_info': merge reply and persist, no hook, no status change
+        const updatedComments = task.comments.map((c) =>
+          c.id === comment.id ? { ...c, reply: comment.reply } : c
+        )
+        const updatedTask = { ...task, comments: updatedComments }
+        yield* repo.update(updatedTask)
+        return
+      }
+    }
+
+    // Step 3: no-op when status unchanged (and no reply was handled above)
+    if (task.status === newStatus) return
+
+    // Step 5: need_info requires a comment
+    if (newStatus === "need_info" && comment === null) {
+      return yield* Effect.fail<TaskError>({
+        _tag: "missing_comment",
+        from: task.status,
+        to: newStatus,
+      })
+    }
+
+    // Step 6: blocked requires a non-empty comment
+    if (newStatus === "blocked") {
+      if (comment === null) {
+        return yield* Effect.fail<TaskError>({
+          _tag: "missing_comment",
+          from: task.status,
+          to: newStatus,
+        })
+      }
+      if (comment.content.trim() === "") {
+        return yield* Effect.fail<TaskError>({
+          _tag: "validation_error",
+          message: "blocked requires a non-empty comment",
+          context: { from: task.status, to: newStatus },
+        })
+      }
+    }
+
+    // Step 7: transitioning FROM need_info — all need_info comments must have a reply
+    if (task.status === "need_info") {
+      const blocking = task.comments.find((c) => c.kind === "need_info" && c.reply === "")
+      if (blocking !== undefined) {
+        return yield* Effect.fail<TaskError>({
+          _tag: "validation_error",
+          message: `blocking comment ${blocking.id} has no reply`,
+          context: {
+            commentId: blocking.id,
+            commentTitle: blocking.title,
+            commentContent: blocking.content,
+            commentTimestamp: blocking.timestamp,
+          },
+        })
+      }
+    }
+
+    // Step 8b: ownership check — reject if a live foreign session owns this task
+    if (
+      newStatus === "in_progress" &&
+      task.assignee !== undefined &&
+      task.assignee.id !== sessionId
+    ) {
+      const registry = yield* SessionRegistry
+      const alive = yield* registry.isAlive(task.assignee.id)
+      if (alive) {
+        return yield* Effect.fail<TaskError>({
+          _tag: "validation_error",
+          message: `task is owned by an active session (${task.assignee.id})`,
+          context: { task },
+        })
+      }
+      // dead session — fall through and let step 9 reassign
+    }
+
+    // Step 8: concurrent in_progress — second task for same session requires justification
+    if (newStatus === "in_progress") {
+      const inProgressTasks = yield* repo.findByStatus("in_progress")
+      const sessionInProgress = inProgressTasks.filter(
+        (t) => t.assignee?.id === sessionId && t.id !== task.id
+      )
+      if (sessionInProgress.length > 0) {
+        if (comment === null || comment.content.trim() === "") {
+          return yield* Effect.fail<TaskError>({
+            _tag: "validation_error",
+            message: "moving a second task to in_progress requires a justification comment",
+            context: {
+              inProgressTasks: sessionInProgress.map((t) => ({ id: t.id, title: t.title })),
+            },
+          })
+        }
+      }
+    }
+
+    // Step 9: apply changes
+    const oldStatus = task.status
+    const updatedComments = comment !== null ? [...task.comments, comment] : task.comments
+    const updatedTask = {
+      ...task,
+      status: newStatus,
+      comments: updatedComments,
+      ...(newStatus === "in_progress"
+        ? {
+            in_progress_since: new Date(),
+            assignee: { id: sessionId, title: "Agent", description: "" },
+          }
+        : {}),
+    }
+    yield* repo.update(updatedTask)
+    yield* hookRunner.run({
+      task_id: id,
+      old_status: oldStatus,
+      new_status: newStatus,
+      comment,
+      session_id: sessionId,
+    })
+  })