@naxodev/apnea 0.1.0

package/extension/errors.ts

@@ -0,0 +1,247 @@
+import { Schema } from "effect"
+import { err, type ToolErr } from "./result.ts"
+
+/** No `.apnea/state.json` for the current project root. */
+export class NoRunState extends Schema.TaggedErrorClass<NoRunState>()(
+  "NoRunState",
+  {},
+) {}
+
+/** Tool call refused by the step → legal-tools table. */
+export class IllegalTool extends Schema.TaggedErrorClass<IllegalTool>()(
+  "IllegalTool",
+  {
+    step: Schema.String,
+    tool: Schema.String,
+    legal: Schema.Array(Schema.String),
+  },
+) {}
+
+/** Dispatch kind refused at the current step. */
+export class IllegalKind extends Schema.TaggedErrorClass<IllegalKind>()(
+  "IllegalKind",
+  {
+    step: Schema.String,
+    kind: Schema.String,
+    allowed: Schema.Array(Schema.String),
+  },
+) {}
+
+/** Global or project config missing, invalid, or untrusted. */
+export class ConfigError extends Schema.TaggedErrorClass<ConfigError>()(
+  "ConfigError",
+  {
+    message: Schema.String,
+    path: Schema.optional(Schema.String),
+    details: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+  },
+) {}
+
+/** `state.json` present but not decodable / inconsistent. */
+export class StateCorrupt extends Schema.TaggedErrorClass<StateCorrupt>()(
+  "StateCorrupt",
+  {
+    path: Schema.String,
+    message: Schema.String,
+  },
+) {}
+
+/** VCS detect / dirty / commit / bookmark failure. */
+export class VcsError extends Schema.TaggedErrorClass<VcsError>()("VcsError", {
+  message: Schema.String,
+  command: Schema.optional(Schema.String),
+}) {}
+
+/** Herdr CLI / pane / floating failure. */
+export class HerdrError extends Schema.TaggedErrorClass<HerdrError>()(
+  "HerdrError",
+  {
+    message: Schema.String,
+    command: Schema.optional(Schema.String),
+    details: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+  },
+) {}
+
+/** Commit/review gate refused (e.g. verdict not APPROVED). */
+export class GateRefused extends Schema.TaggedErrorClass<GateRefused>()(
+  "GateRefused",
+  {
+    gate: Schema.String,
+    message: Schema.String,
+    details: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+  },
+) {}
+
+/** `workflow_wait` hit its timeout without a complete artifact. */
+export class WaitTimeout extends Schema.TaggedErrorClass<WaitTimeout>()(
+  "WaitTimeout",
+  {
+    artifact: Schema.String,
+    timeoutMs: Schema.Number,
+    details: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+  },
+) {}
+
+/** `workflow_wait` aborted (Esc / cancel signal). */
+export class WaitAborted extends Schema.TaggedErrorClass<WaitAborted>()(
+  "WaitAborted",
+  {
+    artifact: Schema.String,
+    details: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+  },
+) {}
+
+/** Artifact exists but front-matter / shape is invalid. */
+export class ArtifactInvalid extends Schema.TaggedErrorClass<ArtifactInvalid>()(
+  "ArtifactInvalid",
+  {
+    artifact: Schema.String,
+    message: Schema.String,
+  },
+) {}
+
+/** Phase-package verify commands failed — commit refused. */
+export class VerifyFailed extends Schema.TaggedErrorClass<VerifyFailed>()(
+  "VerifyFailed",
+  {
+    commands: Schema.Array(Schema.String),
+    /** Tail of the verify log — truncated; `verify_log` has the full text. */
+    outputs: Schema.Array(Schema.String),
+    /** Repo-relative path of the full verify log. */
+    verify_log: Schema.String,
+  },
+) {}
+
+export type AppError =
+  | NoRunState
+  | IllegalTool
+  | IllegalKind
+  | ConfigError
+  | StateCorrupt
+  | VcsError
+  | HerdrError
+  | GateRefused
+  | WaitTimeout
+  | WaitAborted
+  | ArtifactInvalid
+  | VerifyFailed
+
+const APP_ERROR_TAG_LIST = [
+  "NoRunState",
+  "IllegalTool",
+  "IllegalKind",
+  "ConfigError",
+  "StateCorrupt",
+  "VcsError",
+  "HerdrError",
+  "GateRefused",
+  "WaitTimeout",
+  "WaitAborted",
+  "ArtifactInvalid",
+  "VerifyFailed",
+] as const satisfies readonly AppError["_tag"][]
+
+/**
+ * Compile-time guard: an `AppError` member missing from `APP_ERROR_TAG_LIST`
+ * would make `isAppError` return false for it, silently degrading a designed
+ * refusal into `bug: …`. Unlike the `toToolResult` switch, a `Set<string>`
+ * cannot be checked by exhaustiveness alone — so assert it here.
+ */
+type AssertNever<T extends never> = T
+type _AllAppErrorTagsCovered = AssertNever<
+  Exclude<AppError["_tag"], (typeof APP_ERROR_TAG_LIST)[number]>
+>
+
+const APP_ERROR_TAGS: ReadonlySet<string> = new Set(APP_ERROR_TAG_LIST)
+
+export function isAppError(u: unknown): u is AppError {
+  return (
+    typeof u === "object" &&
+    u !== null &&
+    "_tag" in u &&
+    typeof (u as { _tag: unknown })._tag === "string" &&
+    APP_ERROR_TAGS.has((u as { _tag: string })._tag)
+  )
+}
+
+/** Map a tagged app error to the stable ToolErr boundary shape. */
+export function toToolResult(e: AppError): ToolErr {
+  switch (e._tag) {
+    case "NoRunState":
+      return err("no run state; call workflow_start first", {
+        legal_next: ["workflow_start"],
+      })
+    case "IllegalTool":
+      return err(
+        `illegal tool ${e.tool} at step=${e.step}. legal: ${e.legal.join(", ") || "(none)"}`,
+        {
+          legal_next: [...e.legal],
+          data: { step: e.step, tool: e.tool },
+        },
+      )
+    case "IllegalKind":
+      return err(
+        `kind=${e.kind} not allowed at step=${e.step}. allowed: ${e.allowed.join(", ")}`,
+        {
+          legal_next: ["dispatch_role with allowed kind", "workflow_status"],
+          data: { step: e.step, kind: e.kind, allowed: e.allowed },
+        },
+      )
+    case "ConfigError": {
+      const data = {
+        ...(e.path !== undefined ? { path: e.path } : {}),
+        ...(e.details ?? {}),
+      }
+      return err(e.message, {
+        data: Object.keys(data).length > 0 ? data : undefined,
+      })
+    }
+    case "StateCorrupt":
+      return err(`corrupt state at ${e.path}: ${e.message}`, {
+        data: { path: e.path },
+      })
+    case "VcsError":
+      return err(e.message, {
+        data: e.command !== undefined ? { command: e.command } : undefined,
+      })
+    case "HerdrError":
+      return err(e.message, {
+        data:
+          e.command !== undefined || e.details !== undefined
+            ? {
+                ...(e.command !== undefined ? { command: e.command } : {}),
+                ...(e.details ?? {}),
+              }
+            : undefined,
+      })
+    case "GateRefused":
+      return err(e.message, {
+        data: {
+          gate: e.gate,
+          ...(e.details ?? {}),
+        },
+      })
+    case "WaitTimeout":
+      return err(`timeout after ${e.timeoutMs}ms waiting for ${e.artifact}`, {
+        data: {
+          artifact: e.artifact,
+          timeout_ms: e.timeoutMs,
+          ...(e.details ?? {}),
+        },
+      })
+    case "WaitAborted":
+      return err("workflow_wait aborted (Esc / cancel)", {
+        data: { artifact: e.artifact, ...(e.details ?? {}) },
+      })
+    case "ArtifactInvalid":
+      return err(e.message, { data: { artifact: e.artifact } })
+    case "VerifyFailed":
+      return err("verify commands failed — commit refused", {
+        data: {
+          commands: e.commands,
+          outputs: e.outputs,
+          verify_log: e.verify_log,
+        },
+      })
+  }
+}

package/extension/host-adapter.ts

@@ -0,0 +1,8 @@
+/** Host-specific behavior used while launching interactive role harnesses. */
+export type ApneaHostAdapter = {
+  readonly materializeRoleAgentDir?: () => string
+  readonly prepareInteractiveCommand?: (command: string[]) => string[]
+  readonly beforeInteractivePrompt?: (command: string[]) => string | null
+}
+
+export const neutralHostAdapter: ApneaHostAdapter = {}

package/extension/registry.ts

@@ -0,0 +1,323 @@
+import { Type, type TSchema } from "typebox"
+import { Check, Errors } from "typebox/value"
+import { workflowCommitPhase } from "./adapters/commit.ts"
+import { workflowDispatch } from "./adapters/dispatch.ts"
+import { apneaSetup } from "./adapters/setup.ts"
+import { workflowStart } from "./adapters/start.ts"
+import { workflowResetRounds, workflowStatus } from "./adapters/status.ts"
+import { workflowWait } from "./adapters/wait.ts"
+import { DISPATCH_KINDS } from "./domain/state-machine.ts"
+import type { ToolResult } from "./result.ts"
+import { neutralHostAdapter, type ApneaHostAdapter } from "./host-adapter.ts"
+import {
+  DEAD_POLLS_NEEDED,
+  DEFAULT_BUDGET_MS,
+  GRACE_MS,
+  HOST_SHELL_TIMEOUT_MS,
+  IDLE_NUDGE_AFTER_MS,
+  MAX_AUTO_POLL_MS,
+  MIN_POLL_MS,
+  type WaitParams,
+  type WaitHooks,
+} from "./workflows/wait.ts"
+
+export type Operation = {
+  /** Pi tool name, or null when the operation is not model-facing. */
+  readonly tool: string | null
+  /** CLI verb and `/apnea` subcommand. */
+  readonly verb: string
+  /**
+   * Argument syntax shown next to the verb in `/apnea help`, e.g.
+   * `"<goal> [--allow-dirty] [--slug=name]"`. Empty string for verbs that
+   * take no arguments (e.g. `status`). Required so a new operation can't
+   * silently omit the human-facing usage the old hand-written helpText()
+   * used to carry.
+   */
+  readonly usage: string
+  /** One line, shared by the tool description and `--help`. */
+  readonly summary: string
+  /** Extra prose for the model only; omitted from `--help`. */
+  readonly guidance?: string
+  readonly params: TSchema
+  /** Gated behind the TTY check in the CLI; never registered as a tool. */
+  readonly humanOnly?: true
+}
+
+type RegisteredOperation = Operation & {
+  readonly run: (
+    params: Record<string, unknown>,
+    hooks?: WaitHooks,
+  ) => Promise<ToolResult>
+}
+
+export type ExecuteOperation = (
+  verb: string,
+  params: Record<string, unknown>,
+  hooks?: WaitHooks,
+) => Promise<ToolResult>
+
+// Sourced from domain/state-machine.ts (not hardcoded here) so a new kind
+// added there can't silently drift out of sync with the registry — the same
+// pattern extension/index.ts already uses.
+const DispatchKind = Type.Union(
+  DISPATCH_KINDS.map((kind) => Type.Literal(kind)),
+)
+
+function operationParams(properties: Record<string, TSchema>): TSchema {
+  return Type.Object(properties, { additionalProperties: false })
+}
+
+// Workflow order, not alphabetical or tool-name order: setup is the natural
+// first step for a new checkout, then the start → dispatch → wait → commit
+// loop, then the always-available status, then the human-only escape hatch.
+// `/apnea help` and autocomplete (SUBS) both derive their order from this
+// array, so ordering it once here keeps every rendering in sync for free.
+function createRegisteredOperations(
+  hostAdapter: ApneaHostAdapter = neutralHostAdapter,
+): readonly RegisteredOperation[] {
+  return [
+    {
+      tool: null,
+      verb: "setup",
+      usage: "[--project] [--force] [--agents-md]",
+      summary: "Write global profiles and optional project role bindings.",
+      params: operationParams({
+        project: Type.Optional(Type.Boolean()),
+        force: Type.Optional(Type.Boolean()),
+        agents_md: Type.Optional(Type.Boolean()),
+      }),
+      run: (p) =>
+        apneaSetup(p as Parameters<typeof apneaSetup>[0], hostAdapter),
+    },
+    {
+      tool: "workflow_start",
+      verb: "start",
+      usage: "<goal> [--allow-dirty] [--slug=name]",
+      summary: "Start, resume, or abandon an Apnea run.",
+      guidance:
+        "Start only writes state (step=planning) — it does NOT launch roles. After start succeeds you MUST immediately call dispatch_role kind=plan then workflow_wait. Resume never auto-dispatches. Refuses if state exists or tree dirty (unless allow_dirty).",
+      params: operationParams({
+        goal: Type.Optional(
+          Type.String({ description: "Run goal (required for action=start)" }),
+        ),
+        slug: Type.Optional(
+          Type.String({ description: "Run slug for branch/bookmark" }),
+        ),
+        allow_dirty: Type.Optional(Type.Boolean()),
+        action: Type.Optional(
+          Type.Union([
+            Type.Literal("start"),
+            Type.Literal("resume"),
+            Type.Literal("abandon"),
+          ]),
+        ),
+      }),
+      // Mirrors the guard in index.ts's execute(): without it, action=start
+      // with no goal reaches slugify(undefined) in workflows/start.ts and
+      // throws instead of returning a clean refusal.
+      run: (p) => {
+        const params = p as Parameters<typeof workflowStart>[0]
+        const action = params.action ?? "start"
+        if (action === "start" && !params.goal?.trim()) {
+          return Promise.resolve({
+            ok: false,
+            error: "goal is required when action=start",
+          })
+        }
+        return workflowStart(
+          {
+            goal: params.goal ?? "",
+            slug: params.slug,
+            allow_dirty: params.allow_dirty,
+            action,
+          },
+          hostAdapter,
+        )
+      },
+    },
+    {
+      tool: "dispatch_role",
+      verb: "dispatch",
+      usage: "<kind> [--rework]",
+      summary: "Write the task file and launch a role in a Herdr pane.",
+      guidance:
+        "One outstanding dispatch at a time. Pass rework=true for plan/code after CHANGES_REQUIRED. Phase-package rework advances its round automatically from review frontmatter.",
+      params: operationParams({
+        kind: DispatchKind,
+        task_markdown: Type.Optional(
+          Type.String({ description: "Extra task body details" }),
+        ),
+        rework: Type.Optional(
+          Type.Boolean({
+            description: "Increment round after CHANGES_REQUIRED",
+          }),
+        ),
+      }),
+      run: (p) =>
+        workflowDispatch(
+          p as Parameters<typeof workflowDispatch>[0],
+          hostAdapter,
+        ),
+    },
+    {
+      tool: "workflow_wait",
+      verb: "wait",
+      usage: "[--poll=<ms>] [--budget=<ms>|--timeout=<ms>]",
+      summary: "Wait for the pending artifact's front-matter to be complete.",
+      guidance:
+        "Blocks until the artifact is ready or the role times out. Exit is non-fatal when the call's budget is spent but the role still has time — call again. Omit both parameters unless you have a reason.",
+      // `timeout_ms` was dropped in Task 3: dispatch always stamps the deadline,
+      // so it no-opped for every real run. The role timeout lives in config.
+      //
+      // Only `minimum` is a schema-level bound, because only it is
+      // unconditional. The poll ceiling applies solely when budget_ms is
+      // absent, and a `maximum` here would have declared a limit the runtime
+      // does not enforce — rejecting the legal large-poll-with-explicit-budget
+      // call at the boundary, or lying to a model that never hits it.
+      //
+      // The floor is interpolated from the constants, not spelled out. A
+      // hardcoded formula here goes stale the moment IDLE_NUDGE_AFTER_MS
+      // moves, and then the schema promises a budget the runtime refuses.
+      params: operationParams({
+        poll_ms: Type.Optional(
+          Type.Number({
+            minimum: MIN_POLL_MS,
+            description:
+              `Milliseconds between polls. At least ${MIN_POLL_MS} — each poll spawns two herdr subprocesses. ` +
+              `Keep it at or under ${MAX_AUTO_POLL_MS} unless you also pass budget_ms: above that, the floor ` +
+              `below forces a budget past the ${HOST_SHELL_TIMEOUT_MS}ms an agent shell commonly allows, and the call is refused.`,
+          }),
+        ),
+        budget_ms: Type.Optional(
+          Type.Number({
+            description:
+              `How long THIS call may block — not the role's deadline, which comes from config. ` +
+              `Must be at least ${GRACE_MS} + max(${IDLE_NUDGE_AFTER_MS}, ${DEAD_POLLS_NEEDED} x poll_ms), so the call ` +
+              `can contain a whole recovery rung. Omitting it is usually right: this tool then blocks until the ` +
+              `role finishes, streaming progress and interruptible, because it has no host shell timeout to fit inside. ` +
+              `The apnea CLI, which does, defaults to ${DEFAULT_BUDGET_MS}ms instead and returns exit 3 to be called again.`,
+          }),
+        ),
+      }),
+      // The Pi driver bypasses this handler entirely — Task 5 special-cases
+      // workflow_wait and calls workflowWait directly with its own streaming
+      // hooks, supplying its own budget (see extension/index.ts). This run is
+      // reached only by the CLI, which must not block forever, so params pass
+      // through unchanged and DEFAULT_BUDGET_MS applies when budget_ms
+      // is absent. No hooks parameter here — nothing calls op.run with one.
+      run: (p, hooks) => workflowWait(p as WaitParams, hostAdapter, hooks),
+    },
+    {
+      tool: "workflow_commit_phase",
+      verb: "commit",
+      usage: "[--done] [message]",
+      summary: "Verify and commit the current phase, then advance.",
+      guidance:
+        "Requires an APPROVED code review. Runs the phase package's verify commands and refuses on non-zero exit. Pass no_remaining_phases=true to move to the PR description instead of the next phase.",
+      params: operationParams({
+        message: Type.Optional(Type.String()),
+        no_remaining_phases: Type.Optional(
+          Type.Boolean({
+            description:
+              "If true, go to finishing (PR description) after commit",
+          }),
+        ),
+      }),
+      run: (p) =>
+        workflowCommitPhase(
+          p as Parameters<typeof workflowCommitPhase>[0],
+          hostAdapter,
+        ),
+    },
+    {
+      tool: "workflow_status",
+      verb: "status",
+      usage: "",
+      summary: "Read-only snapshot of run state and legal next calls.",
+      guidance: "Never mutates. Safe to call at any point.",
+      params: operationParams({}),
+      run: () => workflowStatus(hostAdapter),
+    },
+    {
+      tool: null,
+      verb: "reset-rounds",
+      // `--i-am-human` is deliberately not listed here: it's a CLI-only TTY
+      // bypass (the slash handler doesn't accept it — see main.ts's own usage()
+      // and README.md), and this string feeds both `/apnea help` and the CLI's
+      // per-verb line, so listing it here would advertise it on the slash
+      // command too.
+      usage: "<gate>",
+      summary: "Reset the rework counter for a gate. Human only.",
+      humanOnly: true,
+      params: operationParams({
+        gate: Type.String({
+          description: "Round key, e.g. plan_review or phase-01/code_review",
+        }),
+      }),
+      run: (p) =>
+        workflowResetRounds(
+          p as Parameters<typeof workflowResetRounds>[0],
+          hostAdapter,
+        ),
+    },
+  ]
+}
+
+function publicOperation(operation: RegisteredOperation): Operation {
+  const { run: _run, ...metadata } = operation
+  return metadata
+}
+
+function executorFor(
+  operations: readonly RegisteredOperation[],
+): ExecuteOperation {
+  return async (verb, params, hooks) => {
+    const operation = operations.find((candidate) => candidate.verb === verb)
+    if (!operation) {
+      return { ok: false, error: `unknown operation: ${verb}` }
+    }
+    if (!Check(operation.params, params)) {
+      return {
+        ok: false,
+        error: `invalid parameters for ${verb}`,
+        data: {
+          verb,
+          issues: [...Errors(operation.params, params)].map((issue) => ({
+            path: issue.instancePath,
+            message: issue.message,
+          })),
+        },
+      }
+    }
+    return operation.run(params, hooks)
+  }
+}
+
+export function createOperations(
+  hostAdapter: ApneaHostAdapter = neutralHostAdapter,
+): readonly Operation[] {
+  return createRegisteredOperations(hostAdapter).map(publicOperation)
+}
+
+export function createExecutor(
+  hostAdapter: ApneaHostAdapter = neutralHostAdapter,
+): ExecuteOperation {
+  return executorFor(createRegisteredOperations(hostAdapter))
+}
+
+const REGISTERED_OPERATIONS = createRegisteredOperations()
+export const OPERATIONS = REGISTERED_OPERATIONS.map(publicOperation)
+export const executeOperation = executorFor(REGISTERED_OPERATIONS)
+
+export function findByVerb(verb: string): Operation | undefined {
+  return OPERATIONS.find((o) => o.verb === verb)
+}
+
+export function findByTool(tool: string): Operation | undefined {
+  return OPERATIONS.find((o) => o.tool === tool)
+}
+
+/** Canonical tool name → CLI verb, or null when not model-facing. */
+export function toolToVerb(tool: string): string | null {
+  return findByTool(tool)?.verb ?? null
+}

package/extension/result.ts

@@ -0,0 +1,55 @@
+export interface ToolOk {
+  ok: true
+  message: string
+  data?: Record<string, unknown>
+  legal_next?: string[]
+}
+
+export interface ToolErr {
+  ok: false
+  error: string
+  legal_next?: string[]
+  data?: Record<string, unknown>
+}
+
+export type ToolResult = ToolOk | ToolErr
+
+export function ok(
+  message: string,
+  data?: Record<string, unknown>,
+  legal_next?: string[],
+): ToolResult {
+  const r: ToolOk = { ok: true, message }
+  if (data) r.data = data
+  if (legal_next?.length) r.legal_next = legal_next
+  return r
+}
+
+export function err(
+  error: string,
+  opts?: { legal_next?: string[]; data?: Record<string, unknown> },
+): ToolErr {
+  return {
+    ok: false,
+    error,
+    legal_next: opts?.legal_next,
+    data: opts?.data,
+  }
+}
+
+export function formatResult(r: ToolResult): string {
+  const legal = r.legal_next?.length
+    ? `\nlegal_next: ${r.legal_next.join(", ")}`
+    : ""
+  const extra = r.data ? `\n${JSON.stringify(r.data, null, 2)}` : ""
+  return r.ok
+    ? `OK: ${r.message}${legal}${extra}`
+    : `ERROR: ${r.error}${legal}${extra}`
+}
+
+export function toolContent(r: ToolResult) {
+  return {
+    content: [{ type: "text" as const, text: formatResult(r) }],
+    details: r,
+  }
+}

package/extension/run-tool.ts

@@ -0,0 +1,43 @@
+import { Cause, Effect, Exit, Layer, Option, Result } from "effect"
+import { isAppError, toToolResult } from "./errors.ts"
+import type { ToolResult } from "./result.ts"
+
+/**
+ * Per-call runner (no toolContent wrap): provide `layer`, map AppError →
+ * ToolResult, defects → bug:. No module-level ManagedRuntime.
+ */
+export async function runToolResult<E, R>(
+  effect: Effect.Effect<ToolResult, E, R>,
+  // Required: a defaulted `Layer.empty as Layer.Layer<R>` erases R, so calling
+  // without the layer would type-check and then die as a service-not-found
+  // defect on every invocation. Pass `Layer.empty` explicitly when R is never.
+  layer: Layer.Layer<R, never, never>,
+): Promise<ToolResult> {
+  const provided = Effect.provide(effect, layer) as Effect.Effect<ToolResult, E>
+  const exit = await Effect.runPromiseExit(provided)
+
+  if (Exit.isSuccess(exit)) {
+    return exit.value
+  }
+
+  const error = Exit.findErrorOption(exit)
+  if (Option.isSome(error) && isAppError(error.value)) {
+    return toToolResult(error.value)
+  }
+
+  const defect = Cause.findDefect(exit.cause)
+  const msg = Result.isSuccess(defect)
+    ? defectMessage(defect.success)
+    : defectMessage(Cause.squash(exit.cause))
+  return { ok: false, error: `bug: ${msg}` }
+}
+
+function defectMessage(defect: unknown): string {
+  if (defect instanceof Error) return defect.message || defect.name
+  if (typeof defect === "string") return defect
+  try {
+    return JSON.stringify(defect)
+  } catch {
+    return String(defect)
+  }
+}