@naxodev/apnea 0.1.0

package/herdr-plugin/herdr-plugin.toml

@@ -0,0 +1,15 @@
+id = "apnea"
+name = "Apnea"
+version = "0.1.0"
+description = "Apnea floating-pane worker for oneshot role dispatches."
+min_herdr_version = "0.7.4"
+platforms = ["linux", "macos"]
+
+[[panes]]
+id = "worker"
+title = "Apnea worker"
+placement = "overlay"
+# Absolute bash + plugin-relative script. Bare `bash` fails on stripped plugin
+# PATH (exit 127). Do not pass a foreign --cwd to plugin pane open — relative
+# script paths resolve against that cwd, not plugin_root.
+command = ["/bin/bash", "scripts/run-task.sh"]

package/herdr-plugin/scripts/run-task.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+set -euo pipefail
+if [[ -z "${APNEA_TASK_SCRIPT:-}" ]]; then
+	echo "apnea: APNEA_TASK_SCRIPT not set (open this pane via apnea dispatch)" >&2
+	exit 64
+fi
+# Absolute bash: popup PATH may not resolve bare `bash` (exit 127).
+exec /bin/bash "$APNEA_TASK_SCRIPT"

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@naxodev/apnea",
+  "version": "0.1.0",
+  "description": "Host-neutral multi-role workflow engine and standalone Bun CLI",
+  "license": "MIT",
+  "author": "Nacho Vazquez",
+  "funding": "https://github.com/sponsors/NachoVazquez",
+  "homepage": "https://github.com/naxodev/ai/tree/main/packages/apnea#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/naxodev/ai.git",
+    "directory": "packages/apnea"
+  },
+  "bugs": {
+    "url": "https://github.com/naxodev/ai/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./extension/api.ts"
+  },
+  "bin": {
+    "apnea": "./dist/cli.js"
+  },
+  "keywords": [
+    "apnea",
+    "workflow",
+    "herdr",
+    "cli",
+    "agent"
+  ],
+  "files": [
+    "CONTEXT.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "README.md",
+    "SECURITY.md",
+    "briefs",
+    "dist",
+    "docs/adr",
+    "docs/protocol",
+    "extension",
+    "herdr-plugin",
+    "schemas",
+    "!extension/**/*.test.ts",
+    "!extension/test"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "packageManager": "bun@1.3.7",
+  "engines": {
+    "bun": ">=1.3.7"
+  },
+  "scripts": {
+    "build": "bun build ./extension/cli/main.ts --target=bun --outfile ./dist/cli.js",
+    "check": "bun run typecheck && bun run test && bun run format:check && bun run pack:check && bun run smoke:package",
+    "typecheck": "tsc --noEmit",
+    "test": "bun run build && bun test extension",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "pack:check": "bun run build && bun scripts/verify-pack.ts",
+    "smoke:package": "bun scripts/package-smoke.ts"
+  },
+  "dependencies": {
+    "effect": "4.0.0-beta.101",
+    "typebox": "^1.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.1.2",
+    "prettier": "^3.9.0",
+    "typescript": "^7.0.2"
+  }
+}

package/schemas/artifact-frontmatter.md

@@ -0,0 +1,38 @@
+# Artifact front-matter (v1)
+
+YAML between `---` lines at file start.
+
+## All artifacts
+
+```yaml
+status: done
+```
+
+`status` other than `done` is invalid in v1.
+
+## Review artifacts (plan-review, code-review)
+
+```yaml
+status: done
+verdict: APPROVED | CHANGES_REQUIRED
+rework: code | phase_package # code-review CHANGES_REQUIRED only
+nits: | # optional string; meaningful only with APPROVED
+  ...
+```
+
+- Missing `verdict` on a review artifact → invalid.
+- `nits` with `CHANGES_REQUIRED` is allowed but ignored by the commit gate.
+- A code-review `CHANGES_REQUIRED` may set `rework` to `code` or `phase_package`.
+- Missing `rework` means `code` for compatibility with existing reviews.
+- Omit `rework` from plan reviews and approved code reviews.
+- Commit gate cares only: `verdict == APPROVED` and verify commands exit 0.
+
+## Non-review artifacts
+
+plan, phase-package, coder-result, pr-description:
+
+```yaml
+status: done
+```
+
+No `verdict` field expected.

package/schemas/config.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://naxodev.com/apnea/config.schema.json",
+  "title": "ApneaConfig",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "profiles": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "cmd_oneshot": {
+            "type": "array",
+            "items": { "type": "string" },
+            "minItems": 1
+          },
+          "cmd_interactive": {
+            "type": "array",
+            "items": { "type": "string" },
+            "minItems": 1
+          }
+        }
+      }
+    },
+    "roles": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["profile"],
+        "properties": {
+          "profile": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "review_round_cap": { "type": "integer", "minimum": 1, "maximum": 20 },
+    "timeouts_ms": {
+      "type": "object",
+      "additionalProperties": { "type": "integer", "minimum": 1000 }
+    },
+    "pane_style": {
+      "type": "string",
+      "enum": ["regular", "floating"],
+      "default": "regular",
+      "description": "Herdr pane style for role dispatches. \"floating\" applies to oneshot roles only and requires herdr >= 0.7.4; interactive roles always use regular panes. Default: regular."
+    }
+  }
+}

package/schemas/state.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://naxodev.com/apnea/state.schema.json",
+  "title": "ApneaRunState",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "slug", "step", "phase_index", "rounds", "vcs"],
+  "properties": {
+    "version": { "const": 1 },
+    "slug": { "type": "string", "minLength": 1 },
+    "step": {
+      "type": "string",
+      "enum": [
+        "planning",
+        "plan_review",
+        "phase_packaging",
+        "coding",
+        "code_review",
+        "committing",
+        "finishing",
+        "done"
+      ]
+    },
+    "phase_index": { "type": "integer", "minimum": 0 },
+    "phase_count_hint": { "type": ["integer", "null"], "minimum": 0 },
+    "rounds": {
+      "type": "object",
+      "description": "Keys like phase-01/plan_review or phase-01/code_review",
+      "additionalProperties": { "type": "integer", "minimum": 1 }
+    },
+    "vcs": { "type": "string", "enum": ["jj", "git"] },
+    "allow_dirty": { "type": "boolean" },
+    "goal": { "type": "string" },
+    "last_error": { "type": ["string", "null"] },
+    "pending_artifact": { "type": ["string", "null"] },
+    "pending_role": { "type": ["string", "null"] },
+    "pending_pane_id": { "type": ["string", "null"] },
+    "pending_pane_label": { "type": ["string", "null"] },
+    "pending_floating_exit": { "type": ["string", "null"] },
+    "pending_started_at": { "type": ["integer", "null"] },
+    "pending_deadline_ms": { "type": ["integer", "null"] },
+    "pending_nudged_at": { "type": ["integer", "null"] },
+    "pending_final_grace": { "type": "boolean" },
+    "pending_extended": { "type": "boolean" },
+    "role_panes": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["pane_id", "label"],
+        "properties": {
+          "pane_id": { "type": "string" },
+          "label": { "type": "string" },
+          "profile_fingerprint": { "type": ["string", "null"] }
+        }
+      }
+    },
+    "package_root": { "type": "string" },
+    "reviewer_tree_fingerprint": { "type": ["string", "null"] },
+    "current_phase_package": { "type": ["string", "null"] },
+    "current_code_review": { "type": ["string", "null"] },
+    "phase_package_rework": { "type": "boolean" }
+  }
+}