@chllming/wave-orchestration 0.8.5 → 0.8.6

package/scripts/wave-status.sh

@@ -0,0 +1,200 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+lane="main"
+wave=""
+agent=""
+run_id=""
+dry_run="0"
+json_output="0"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  scripts/wave-status.sh [--lane <lane>] [--wave <n>] [--agent <id>] [--run <id>] [--dry-run] [--json]
+
+Exit codes:
+  0   completed
+  10  waiting or running
+  20  input required
+  40  failed
+EOF
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --lane)
+      lane="${2:-}"
+      shift 2
+      ;;
+    --wave)
+      wave="${2:-}"
+      shift 2
+      ;;
+    --agent)
+      agent="${2:-}"
+      shift 2
+      ;;
+    --run)
+      run_id="${2:-}"
+      shift 2
+      ;;
+    --dry-run)
+      dry_run="1"
+      shift
+      ;;
+    --json)
+      json_output="1"
+      shift
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+run_wave_cli() {
+  if [ -n "${WAVE_WRAPPER_ENTRY:-}" ]; then
+    node "$WAVE_WRAPPER_ENTRY" "$@"
+    return
+  fi
+  if [ -f "scripts/wave.mjs" ]; then
+    node "scripts/wave.mjs" "$@"
+    return
+  fi
+  if [ -f "node_modules/@chllming/wave-orchestration/scripts/wave.mjs" ]; then
+    node "node_modules/@chllming/wave-orchestration/scripts/wave.mjs" "$@"
+    return
+  fi
+  if command -v pnpm >/dev/null 2>&1; then
+    pnpm exec wave "$@"
+    return
+  fi
+  echo "Unable to locate Wave CLI. Set WAVE_WRAPPER_ENTRY or install the package locally." >&2
+  exit 2
+}
+
+infer_wave() {
+  node - "$lane" "$run_id" "$dry_run" <<'NODE'
+const fs = require("node:fs");
+const path = require("node:path");
+
+const lane = process.argv[2] || "main";
+const runId = process.argv[3] || "";
+const dryRun = process.argv[4] === "1";
+const stateDir = runId
+  ? path.join(process.cwd(), ".tmp", `${lane}-wave-launcher`, "adhoc", runId, dryRun ? "dry-run" : "")
+  : path.join(process.cwd(), ".tmp", `${lane}-wave-launcher`, dryRun ? "dry-run" : "");
+const runStatePath = path.join(stateDir, "run-state.json");
+let payload = null;
+try {
+  payload = JSON.parse(fs.readFileSync(runStatePath, "utf8"));
+} catch {
+  payload = null;
+}
+const waves = Object.values(payload?.waves || {})
+  .filter((entry) => entry && typeof entry === "object")
+  .map((entry) => ({
+    wave: Number.parseInt(String(entry.wave ?? ""), 10),
+    state: String(entry.currentState || "").trim().toLowerCase(),
+  }))
+  .filter((entry) => Number.isFinite(entry.wave))
+  .sort((left, right) => left.wave - right.wave);
+const active = waves.findLast(
+  (entry) => !["completed", "failed", "timed_out", "timed-out"].includes(entry.state),
+);
+if (active) {
+  process.stdout.write(String(active.wave));
+  process.exit(0);
+}
+const completed = Array.isArray(payload?.completedWaves)
+  ? payload.completedWaves
+      .map((value) => Number.parseInt(String(value), 10))
+      .filter((value) => Number.isFinite(value))
+      .sort((left, right) => left - right)
+  : [];
+process.stdout.write(String(completed.at(-1) ?? 0));
+NODE
+}
+
+if [ -z "$wave" ]; then
+  wave="$(infer_wave)"
+fi
+
+status_args=(control status --lane "$lane" --wave "$wave" --json)
+if [ -n "$agent" ]; then
+  status_args+=(--agent "$agent")
+fi
+if [ -n "$run_id" ]; then
+  status_args+=(--run "$run_id")
+fi
+if [ "$dry_run" = "1" ]; then
+  status_args+=(--dry-run)
+fi
+
+payload="$(run_wave_cli "${status_args[@]}")"
+
+if [ "$json_output" = "1" ]; then
+  printf '%s\n' "$payload"
+  exit 0
+fi
+
+PAYLOAD="$payload" node - "$lane" "$wave" "$agent" <<'NODE'
+const fs = require("node:fs");
+
+const lane = process.argv[2] || "main";
+const wave = Number.parseInt(String(process.argv[3] || "0"), 10) || 0;
+const agentId = String(process.argv[4] || "").trim();
+const payload = JSON.parse(process.env.PAYLOAD || "{}");
+const signals = payload?.signals || {};
+const snapshot = agentId
+  ? (Array.isArray(signals.agents) ? signals.agents.find((entry) => entry.agentId === agentId) : null)
+  : signals.wave;
+const effective = snapshot || {
+  signal: payload?.blockingEdge?.kind === "human-input" ? "feedback-requested" : "waiting",
+  lane,
+  wave,
+  phase: payload?.phase || "unknown",
+  status: payload?.blockingEdge ? "blocked" : "running",
+  blocking: payload?.blockingEdge || null,
+  attempt: payload?.activeAttempt?.attemptNumber || 0,
+  targetAgentIds: agentId ? [agentId] : [],
+  shouldWake: agentId ? true : null,
+  version: 0,
+};
+const targetKey = agentId ? "agent" : "agents";
+const targetValue = agentId || (effective.targetAgentIds || []).join(",") || "none";
+const blocking = effective?.blocking?.kind || "none";
+const shouldWake =
+  typeof effective.shouldWake === "boolean" ? (effective.shouldWake ? "yes" : "no") : "n/a";
+console.log(
+  [
+    `signal=${effective.signal || "waiting"}`,
+    `lane=${lane}`,
+    `wave=${wave}`,
+    `phase=${effective.phase || "unknown"}`,
+    `status=${effective.status || "running"}`,
+    `blocking=${blocking}`,
+    `attempt=${effective.attempt || 0}`,
+    `${targetKey}=${targetValue}`,
+    `version=${effective.version || 0}`,
+    `should_wake=${shouldWake}`,
+  ].join(" "),
+);
+if (String(effective.signal || "").trim().toLowerCase() === "completed") {
+  process.exit(0);
+}
+if (String(effective.signal || "").trim().toLowerCase() === "failed") {
+  process.exit(40);
+}
+if (String(effective.signal || "").trim().toLowerCase() === "feedback-requested") {
+  process.exit(20);
+}
+process.exit(10);
+NODE

package/scripts/wave-watch.sh

@@ -0,0 +1,200 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+lane="main"
+wave=""
+agent=""
+run_id=""
+dry_run="0"
+mode="follow"
+refresh_ms="2000"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  scripts/wave-watch.sh [--lane <lane>] [--wave <n>] [--agent <id>] [--run <id>] [--dry-run] [--refresh-ms <n>] [--follow|--until-change]
+
+Exit codes:
+  0   completed
+  20  input required
+  30  watched signal changed while the wave remained active
+  40  failed
+EOF
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --lane)
+      lane="${2:-}"
+      shift 2
+      ;;
+    --wave)
+      wave="${2:-}"
+      shift 2
+      ;;
+    --agent)
+      agent="${2:-}"
+      shift 2
+      ;;
+    --run)
+      run_id="${2:-}"
+      shift 2
+      ;;
+    --dry-run)
+      dry_run="1"
+      shift
+      ;;
+    --refresh-ms)
+      refresh_ms="${2:-}"
+      shift 2
+      ;;
+    --follow)
+      mode="follow"
+      shift
+      ;;
+    --until-change)
+      mode="until-change"
+      shift
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+status_script="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/wave-status.sh"
+common_args=(--lane "$lane")
+if [ -n "$wave" ]; then
+  common_args+=(--wave "$wave")
+fi
+if [ -n "$agent" ]; then
+  common_args+=(--agent "$agent")
+fi
+if [ -n "$run_id" ]; then
+  common_args+=(--run "$run_id")
+fi
+if [ "$dry_run" = "1" ]; then
+  common_args+=(--dry-run)
+fi
+
+extract_field() {
+  local payload="$1"
+  local field="$2"
+  PAYLOAD="$payload" node - "$agent" "$field" <<'NODE'
+const agentId = String(process.argv[2] || "").trim();
+const field = String(process.argv[3] || "").trim();
+const payload = JSON.parse(process.env.PAYLOAD || "{}");
+const signals = payload?.signals || {};
+const snapshot = agentId
+  ? (Array.isArray(signals.agents) ? signals.agents.find((entry) => entry.agentId === agentId) : null)
+  : signals.wave;
+const value = snapshot?.[field];
+process.stdout.write(value === undefined || value === null ? "" : String(value));
+NODE
+}
+
+print_line() {
+  local payload="$1"
+  PAYLOAD="$payload" node - "$lane" "${wave:-0}" "$agent" <<'NODE'
+const lane = process.argv[2] || "main";
+const wave = Number.parseInt(String(process.argv[3] || "0"), 10) || 0;
+const agentId = String(process.argv[4] || "").trim();
+const payload = JSON.parse(process.env.PAYLOAD || "{}");
+const signals = payload?.signals || {};
+const snapshot = agentId
+  ? (Array.isArray(signals.agents) ? signals.agents.find((entry) => entry.agentId === agentId) : null)
+  : signals.wave;
+const effective = snapshot || {
+  signal: payload?.blockingEdge?.kind === "human-input" ? "feedback-requested" : "waiting",
+  phase: payload?.phase || "unknown",
+  status: payload?.blockingEdge ? "blocked" : "running",
+  blocking: payload?.blockingEdge || null,
+  attempt: payload?.activeAttempt?.attemptNumber || 0,
+  version: 0,
+  shouldWake: agentId ? true : null,
+  targetAgentIds: agentId ? [agentId] : [],
+};
+const targetKey = agentId ? "agent" : "agents";
+const targetValue = agentId || (effective.targetAgentIds || []).join(",") || "none";
+const shouldWake =
+  typeof effective.shouldWake === "boolean" ? (effective.shouldWake ? "yes" : "no") : "n/a";
+console.log(
+  [
+    `signal=${effective.signal || "waiting"}`,
+    `lane=${lane}`,
+    `wave=${wave}`,
+    `phase=${effective.phase || "unknown"}`,
+    `status=${effective.status || "running"}`,
+    `blocking=${effective?.blocking?.kind || "none"}`,
+    `attempt=${effective.attempt || 0}`,
+    `${targetKey}=${targetValue}`,
+    `version=${effective.version || 0}`,
+    `should_wake=${shouldWake}`,
+  ].join(" "),
+);
+NODE
+}
+
+exit_code_for_payload() {
+  local payload="$1"
+  PAYLOAD="$payload" node - "$agent" <<'NODE'
+const agentId = String(process.argv[2] || "").trim();
+const payload = JSON.parse(process.env.PAYLOAD || "{}");
+const signals = payload?.signals || {};
+const snapshot = agentId
+  ? (Array.isArray(signals.agents) ? signals.agents.find((entry) => entry.agentId === agentId) : null)
+  : signals.wave;
+const signal = String(snapshot?.signal || "").trim().toLowerCase();
+if (signal === "completed") {
+  process.exit(0);
+}
+if (signal === "failed") {
+  process.exit(40);
+}
+if (signal === "feedback-requested") {
+  process.exit(20);
+}
+process.exit(10);
+NODE
+}
+
+payload="$("$status_script" "${common_args[@]}" --json)"
+version="$(extract_field "$payload" "version")"
+print_line "$payload"
+
+if exit_code_for_payload "$payload"; then
+  exit 0
+else
+  status=$?
+  if [ "$status" -eq 20 ] || [ "$status" -eq 40 ]; then
+    exit "$status"
+  fi
+fi
+
+while true; do
+  sleep "$(awk "BEGIN { printf \"%.3f\", ${refresh_ms}/1000 }")"
+  payload="$("$status_script" "${common_args[@]}" --json)"
+  next_version="$(extract_field "$payload" "version")"
+  if [ "$next_version" = "$version" ]; then
+    continue
+  fi
+  version="$next_version"
+  print_line "$payload"
+  if exit_code_for_payload "$payload"; then
+    exit 0
+  else
+    status=$?
+    if [ "$status" -eq 20 ] || [ "$status" -eq 40 ]; then
+      exit "$status"
+    fi
+  fi
+  if [ "$mode" = "until-change" ]; then
+    exit 30
+  fi
+done

package/skills/README.md

@@ -180,6 +180,7 @@ Runtime:
 Design reference:
 
 - `tui-design`
+- `signal-hygiene`
 
 Provider:
 
@@ -205,6 +206,8 @@ Provider skills are configured by deploy kind, but the shipped manifests further
 
 For terminal or operator-surface design work, keep `role-design` as the packet contract and add `tui-design` explicitly in the wave's `### Skills`.
 
+For long-running watcher agents, add `signal-hygiene` explicitly in the wave's `### Skills`. Do not attach it to normal one-shot implementation agents. For the wrapper and ack-loop contract, read [../docs/guides/signal-wrappers.md](../docs/guides/signal-wrappers.md).
+
 ## Further Reading
 
 - [Skills Reference](../docs/reference/skills.md)

package/skills/signal-hygiene/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: signal-hygiene
+description: Use for long-running resident or waiting agents that must stay idle until the orchestrator writes a new signal version, then acknowledge that change before acting.
+---
+
+# Signal Hygiene
+
+Use this skill only when the agent is intentionally long-running.
+
+This is not a generic polling skill for normal one-shot implementation work.
+
+## Core loop
+
+- Treat the signal state file as the orchestrator-controlled wakeup surface.
+- Treat the signal ack file as your durable confirmation that you observed a specific signal version.
+- Stay idle while the signal version is unchanged.
+- Act once when the signal version increases and the new signal is actionable.
+
+## Required behavior
+
+- Read the signal state path provided in the prompt before deciding whether to keep waiting or resume work.
+- If the signal file is missing, assume the orchestrator has not published a new signal yet and keep waiting.
+- Compare the signal file's `version` to the version already recorded in the signal ack file.
+- When the signal version increases, write the ack file immediately before you act on the change.
+- Write the ack file as JSON with exactly these keys:
+  - `agentId`
+  - `version`
+  - `signal`
+  - `observedAt`
+- After acknowledging the new version, re-read the inbox, shared summary, message board, and any explicitly referenced artifacts before taking action.
+- If the signal kind is `completed` or `failed`, stop the waiting loop and finish cleanly.
+
+## Do not do this
+
+- Do not busy-loop or emit repeated status chatter while the signal version is unchanged.
+- Do not keep re-processing the same signal version.
+- Do not invent your own wakeup surface when the orchestrator already provided signal and ack paths.
+- Do not stay resident forever once the signal clearly becomes terminal.
+
+## Actionability rule
+
+Treat these signal kinds as actionable by default:
+
+- `feedback-requested`
+- `feedback-answered`
+- `coordination-action`
+- `resume-ready`
+- `completed`
+- `failed`
+
+Treat `waiting` and `stable` as non-actionable until the version changes again.

package/skills/signal-hygiene/skill.json

@@ -0,0 +1,20 @@
+{
+  "id": "signal-hygiene",
+  "title": "Long-Running Signal Hygiene",
+  "description": "Use for long-running resident or waiting agents that must stay idle until the orchestrator writes a new signal version, then acknowledge that change before acting.",
+  "activation": {
+    "when": "Attach explicitly when an agent is expected to stay resident, wait for human feedback or coordination changes, and react only when the orchestrator updates the signal state file.",
+    "roles": [],
+    "runtimes": [],
+    "deployKinds": []
+  },
+  "termination": "Stop when the signal reaches a terminal state or the agent is no longer expected to stay resident and wait for follow-up work.",
+  "permissions": {
+    "network": [],
+    "shell": [],
+    "mcpServers": []
+  },
+  "trust": {
+    "tier": "repo-owned"
+  }
+}