agent-control-plane 0.1.0

package/tools/bin/provider-cooldown-state.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/flow-config-lib.sh"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  provider-cooldown-state.sh [backend] [model] get|schedule|clear [reason]
+
+Examples:
+  provider-cooldown-state.sh get
+  provider-cooldown-state.sh openclaw openrouter/stepfun/step-3.5-flash:free schedule provider-quota-limit
+EOF
+}
+
+backend=""
+model=""
+action=""
+reason=""
+
+case "$#" in
+  1)
+    action="${1:-}"
+    ;;
+  2)
+    action="${1:-}"
+    reason="${2:-}"
+    ;;
+  3)
+    backend="${1:-}"
+    model="${2:-}"
+    action="${3:-}"
+    ;;
+  4)
+    backend="${1:-}"
+    model="${2:-}"
+    action="${3:-}"
+    reason="${4:-}"
+    ;;
+  *)
+    usage >&2
+    exit 1
+    ;;
+esac
+
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+flow_export_execution_env "${CONFIG_YAML}"
+STATE_ROOT="$(flow_resolve_state_root "${CONFIG_YAML}")"
+COOLDOWNS="$(flow_resolve_provider_quota_cooldowns "${CONFIG_YAML}")"
+
+resolve_backend() {
+  local raw_backend="${1:-}"
+
+  if [[ -n "${raw_backend}" ]]; then
+    printf '%s\n' "${raw_backend}"
+    return 0
+  fi
+
+  if [[ -n "${CODING_WORKER:-}" ]]; then
+    printf '%s\n' "${CODING_WORKER}"
+    return 0
+  fi
+
+  if [[ -n "${ACP_ACTIVE_PROVIDER_BACKEND:-${F_LOSNING_ACTIVE_PROVIDER_BACKEND:-}}" ]]; then
+    printf '%s\n' "${ACP_ACTIVE_PROVIDER_BACKEND:-${F_LOSNING_ACTIVE_PROVIDER_BACKEND:-}}"
+    return 0
+  fi
+
+  if [[ -n "${ACP_CODING_WORKER:-${F_LOSNING_CODING_WORKER:-}}" ]]; then
+    printf '%s\n' "${ACP_CODING_WORKER:-${F_LOSNING_CODING_WORKER:-}}"
+    return 0
+  fi
+
+  flow_config_get "${CONFIG_YAML}" "execution.coding_worker"
+}
+
+resolve_model() {
+  local resolved_backend="${1:?backend required}"
+  local raw_model="${2:-}"
+  local active_provider_model="${ACP_ACTIVE_PROVIDER_MODEL:-${F_LOSNING_ACTIVE_PROVIDER_MODEL:-}}"
+
+  if [[ -n "${raw_model}" ]]; then
+    printf '%s\n' "${raw_model}"
+    return 0
+  fi
+
+  case "${resolved_backend}" in
+    openclaw)
+      if [[ -n "${OPENCLAW_MODEL:-}" ]]; then
+        printf '%s\n' "${OPENCLAW_MODEL}"
+      elif [[ -n "${active_provider_model}" ]]; then
+        printf '%s\n' "${active_provider_model}"
+      elif [[ -n "${ACP_OPENCLAW_MODEL:-${F_LOSNING_OPENCLAW_MODEL:-}}" ]]; then
+        printf '%s\n' "${ACP_OPENCLAW_MODEL:-${F_LOSNING_OPENCLAW_MODEL:-}}"
+      else
+        flow_config_get "${CONFIG_YAML}" "execution.openclaw.model"
+      fi
+      ;;
+    claude)
+      if [[ -n "${CLAUDE_MODEL:-}" ]]; then
+        printf '%s\n' "${CLAUDE_MODEL}"
+      elif [[ -n "${active_provider_model}" ]]; then
+        printf '%s\n' "${active_provider_model}"
+      elif [[ -n "${ACP_CLAUDE_MODEL:-${F_LOSNING_CLAUDE_MODEL:-}}" ]]; then
+        printf '%s\n' "${ACP_CLAUDE_MODEL:-${F_LOSNING_CLAUDE_MODEL:-}}"
+      else
+        flow_config_get "${CONFIG_YAML}" "execution.claude.model"
+      fi
+      ;;
+    codex)
+      if [[ -n "${CODEX_PROFILE_SAFE:-}" ]]; then
+        printf '%s\n' "${CODEX_PROFILE_SAFE}"
+      elif [[ -n "${active_provider_model}" ]]; then
+        printf '%s\n' "${active_provider_model}"
+      elif [[ -n "${ACP_CODEX_PROFILE_SAFE:-${F_LOSNING_CODEX_PROFILE_SAFE:-}}" ]]; then
+        printf '%s\n' "${ACP_CODEX_PROFILE_SAFE:-${F_LOSNING_CODEX_PROFILE_SAFE:-}}"
+      else
+        flow_config_get "${CONFIG_YAML}" "execution.safe_profile"
+      fi
+      ;;
+    *)
+      printf '\n'
+      ;;
+  esac
+}
+
+backend="$(resolve_backend "${backend}")"
+if [[ -z "${backend}" ]]; then
+  echo "provider backend is required" >&2
+  exit 1
+fi
+
+model="$(resolve_model "${backend}" "${model}")"
+if [[ -z "${model}" ]]; then
+  echo "provider model/profile is required for backend ${backend}" >&2
+  exit 1
+fi
+
+case "${action}" in
+  get|schedule|clear) ;;
+  *)
+    usage >&2
+    exit 1
+    ;;
+esac
+
+provider_key="$(flow_sanitize_provider_key "${backend}-${model}")"
+out="$(
+  ACP_STATE_ROOT="${STATE_ROOT}" \
+  ACP_PROVIDER_QUOTA_COOLDOWNS="${COOLDOWNS}" \
+  bash "${SCRIPT_DIR}/agent-project-retry-state" \
+    --state-root "${STATE_ROOT}" \
+    --kind provider \
+    --item-id "${provider_key}" \
+    --action "${action}" \
+    --reason "${reason}" \
+    --cooldowns "${COOLDOWNS}"
+)"
+
+printf 'BACKEND=%s\n' "${backend}"
+printf 'MODEL=%s\n' "${model}"
+printf 'PROVIDER_KEY=%s\n' "${provider_key}"
+printf '%s\n' "${out}"

package/tools/bin/publish-issue-worker.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/flow-config-lib.sh"
+
+SESSION="${1:?usage: publish-issue-worker.sh SESSION [--dry-run]}"
+DRY_RUN="${2:-}"
+FLOW_SKILL_DIR="$(resolve_flow_skill_dir "${BASH_SOURCE[0]}")"
+FLOW_TOOLS_DIR="${FLOW_SKILL_DIR}/tools/bin"
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+AGENT_ROOT="$(flow_resolve_agent_root "${CONFIG_YAML}")"
+RUNS_ROOT="$(flow_resolve_runs_root "${CONFIG_YAML}")"
+HISTORY_ROOT="$(flow_resolve_history_root "${CONFIG_YAML}")"
+REPO_SLUG="$(flow_resolve_repo_slug "${CONFIG_YAML}")"
+BASE_BRANCH="$(flow_resolve_default_branch "${CONFIG_YAML}")"
+
+ARGS=(
+  --repo-slug "$REPO_SLUG"
+  --runs-root "$RUNS_ROOT"
+  --history-root "$HISTORY_ROOT"
+  --session "$SESSION"
+  --base-branch "$BASE_BRANCH"
+  --remote "origin"
+)
+if [[ "$DRY_RUN" == "--dry-run" ]]; then
+  ARGS+=(--dry-run)
+fi
+
+bash "${FLOW_TOOLS_DIR}/agent-project-publish-issue-pr" "${ARGS[@]}"

package/tools/bin/reconcile-issue-worker.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/flow-shell-lib.sh"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/flow-config-lib.sh"
+
+SESSION="${1:?usage: reconcile-issue-worker.sh SESSION}"
+WORKSPACE_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+AGENT_ROOT="$(flow_resolve_agent_root "${CONFIG_YAML}")"
+RUNS_ROOT="$(flow_resolve_runs_root "${CONFIG_YAML}")"
+HISTORY_ROOT="$(flow_resolve_history_root "${CONFIG_YAML}")"
+REPO_SLUG="$(flow_resolve_repo_slug "${CONFIG_YAML}")"
+AGENT_REPO_ROOT="$(flow_resolve_agent_repo_root "${CONFIG_YAML}")"
+FLOW_SKILL_DIR="$(resolve_flow_skill_dir "${BASH_SOURCE[0]}")"
+FLOW_TOOLS_DIR="${FLOW_SKILL_DIR}/tools/bin"
+HOOK_FILE="${FLOW_SKILL_DIR}/hooks/issue-reconcile-hooks.sh"
+
+ACP_AGENT_ROOT="$AGENT_ROOT" \
+ACP_RUNS_ROOT="$RUNS_ROOT" \
+ACP_HISTORY_ROOT="$HISTORY_ROOT" \
+ACP_REPO_SLUG="$REPO_SLUG" \
+ACP_AGENT_REPO_ROOT="$AGENT_REPO_ROOT" \
+F_LOSNING_RUNS_ROOT="$RUNS_ROOT" \
+  bash "${FLOW_TOOLS_DIR}/agent-project-reconcile-issue-session" \
+    --session "$SESSION" \
+    --repo-slug "$REPO_SLUG" \
+    --repo-root "$AGENT_REPO_ROOT" \
+    --runs-root "$RUNS_ROOT" \
+    --history-root "$HISTORY_ROOT" \
+    --hook-file "$HOOK_FILE"

package/tools/bin/reconcile-pr-worker.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/flow-shell-lib.sh"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/flow-config-lib.sh"
+
+SESSION="${1:?usage: reconcile-pr-worker.sh SESSION}"
+WORKSPACE_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+AGENT_ROOT="$(flow_resolve_agent_root "${CONFIG_YAML}")"
+RUNS_ROOT="$(flow_resolve_runs_root "${CONFIG_YAML}")"
+HISTORY_ROOT="$(flow_resolve_history_root "${CONFIG_YAML}")"
+REPO_SLUG="$(flow_resolve_repo_slug "${CONFIG_YAML}")"
+AGENT_REPO_ROOT="$(flow_resolve_agent_repo_root "${CONFIG_YAML}")"
+FLOW_SKILL_DIR="$(resolve_flow_skill_dir "${BASH_SOURCE[0]}")"
+FLOW_TOOLS_DIR="${FLOW_SKILL_DIR}/tools/bin"
+HOOK_FILE="${FLOW_SKILL_DIR}/hooks/pr-reconcile-hooks.sh"
+
+ACP_AGENT_ROOT="$AGENT_ROOT" \
+ACP_RUNS_ROOT="$RUNS_ROOT" \
+ACP_HISTORY_ROOT="$HISTORY_ROOT" \
+ACP_REPO_SLUG="$REPO_SLUG" \
+ACP_AGENT_REPO_ROOT="$AGENT_REPO_ROOT" \
+F_LOSNING_RUNS_ROOT="$RUNS_ROOT" \
+  bash "${FLOW_TOOLS_DIR}/agent-project-reconcile-pr-session" \
+    --session "$SESSION" \
+    --repo-slug "$REPO_SLUG" \
+    --repo-root "$AGENT_REPO_ROOT" \
+    --runs-root "$RUNS_ROOT" \
+    --history-root "$HISTORY_ROOT" \
+    --hook-file "$HOOK_FILE"

package/tools/bin/record-verification.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  record-verification.sh --command <shell command> [--status pass|fail] [--run-dir <path>] [--note <text>]
+
+Append one structured verification entry to verification.jsonl for the current
+worker run. Defaults to the sandbox run directory exposed by the worker env.
+EOF
+}
+
+run_dir="${ACP_RUN_DIR:-${F_LOSNING_RUN_DIR:-${AGENT_PROJECT_RUN_DIR:-}}}"
+status="pass"
+command_text=""
+note=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --run-dir) run_dir="${2:-}"; shift 2 ;;
+    --status) status="${2:-}"; shift 2 ;;
+    --command) command_text="${2:-}"; shift 2 ;;
+    --note) note="${2:-}"; shift 2 ;;
+    --help|-h) usage; exit 0 ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$run_dir" || -z "$command_text" ]]; then
+  usage >&2
+  exit 1
+fi
+
+case "$status" in
+  pass|fail) ;;
+  *)
+    echo "Unsupported status: $status" >&2
+    exit 1
+    ;;
+esac
+
+mkdir -p "$run_dir"
+
+RUN_DIR="$run_dir" STATUS="$status" COMMAND_TEXT="$command_text" NOTE="$note" node <<'EOF'
+const fs = require('fs');
+const path = require('path');
+
+const runDir = process.env.RUN_DIR;
+const status = process.env.STATUS;
+const command = process.env.COMMAND_TEXT;
+const note = process.env.NOTE || '';
+
+const entry = {
+  timestamp: new Date().toISOString(),
+  status,
+  command,
+};
+
+if (note) {
+  entry.note = note;
+}
+
+const file = path.join(runDir, 'verification.jsonl');
+fs.appendFileSync(file, `${JSON.stringify(entry)}\n`);
+process.stdout.write(`${file}\n`);
+EOF

package/tools/bin/render-architecture-infographics.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+SOURCE_HTML="${ROOT_DIR}/tools/architecture/architecture-infographics.html"
+OUTPUT_DIR="${ROOT_DIR}/assets/architecture"
+PDF_OUT="${OUTPUT_DIR}/agent-control-plane-architecture.pdf"
+OVERVIEW_OUT="${OUTPUT_DIR}/overview-infographic.png"
+RUNTIME_OUT="${OUTPUT_DIR}/runtime-loop-infographic.png"
+LIFECYCLE_OUT="${OUTPUT_DIR}/worker-lifecycle-infographic.png"
+STATE_OUT="${OUTPUT_DIR}/state-dashboard-infographic.png"
+
+require_bin() {
+  local name="$1"
+  if ! command -v "$name" >/dev/null 2>&1; then
+    echo "missing required dependency: $name" >&2
+    exit 1
+  fi
+}
+
+require_bin python3
+require_bin playwright
+
+PLAYWRIGHT_CLI="$(command -v playwright)"
+PLAYWRIGHT_PACKAGE_ROOT="$(
+  python3 - "$PLAYWRIGHT_CLI" <<'PY'
+import os
+import sys
+
+print(os.path.dirname(os.path.realpath(sys.argv[1])))
+PY
+)"
+
+mkdir -p "${OUTPUT_DIR}"
+tmpdir="$(mktemp -d)"
+
+cleanup() {
+  rm -rf "${tmpdir}"
+}
+trap cleanup EXIT
+
+cat >"${tmpdir}/render-architecture.js" <<'EOF'
+const fs = require("fs");
+const path = require("path");
+const { chromium } = require(process.env.PLAYWRIGHT_PACKAGE_ROOT);
+
+async function screenshotSection(page, selector, filename) {
+  const element = await page.$(selector);
+  if (!element) {
+    throw new Error(`missing section for selector: ${selector}`);
+  }
+  await element.screenshot({ path: filename });
+}
+
+(async () => {
+  const sourceHtml = process.env.ACP_ARCH_SOURCE_HTML;
+  const pdfOut = process.env.ACP_ARCH_PDF_OUT;
+  const overviewOut = process.env.ACP_ARCH_OVERVIEW_OUT;
+  const runtimeOut = process.env.ACP_ARCH_RUNTIME_OUT;
+  const lifecycleOut = process.env.ACP_ARCH_LIFECYCLE_OUT;
+  const stateOut = process.env.ACP_ARCH_STATE_OUT;
+
+  const browser = await chromium.launch({ headless: true });
+  const page = await browser.newPage({
+    viewport: { width: 1664, height: 964 },
+    deviceScaleFactor: 1,
+    colorScheme: "light",
+  });
+
+  await page.goto(`file://${sourceHtml}`, { waitUntil: "load" });
+  await page.waitForTimeout(400);
+
+  await screenshotSection(page, "#overview-page", overviewOut);
+  await screenshotSection(page, "#runtime-loop-page", runtimeOut);
+  await screenshotSection(page, "#worker-lifecycle-page", lifecycleOut);
+  await screenshotSection(page, "#state-dashboard-page", stateOut);
+
+  await page.pdf({
+    path: pdfOut,
+    printBackground: true,
+    preferCSSPageSize: true,
+    margin: {
+      top: "0in",
+      right: "0in",
+      bottom: "0in",
+      left: "0in",
+    },
+  });
+
+  await browser.close();
+})().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+EOF
+
+PLAYWRIGHT_PACKAGE_ROOT="${PLAYWRIGHT_PACKAGE_ROOT}" \
+ACP_ARCH_SOURCE_HTML="${SOURCE_HTML}" \
+ACP_ARCH_PDF_OUT="${PDF_OUT}" \
+ACP_ARCH_OVERVIEW_OUT="${OVERVIEW_OUT}" \
+ACP_ARCH_RUNTIME_OUT="${RUNTIME_OUT}" \
+ACP_ARCH_LIFECYCLE_OUT="${LIFECYCLE_OUT}" \
+ACP_ARCH_STATE_OUT="${STATE_OUT}" \
+node "${tmpdir}/render-architecture.js"
+
+echo "ARCHITECTURE_PDF=${PDF_OUT}"
+echo "ARCHITECTURE_OVERVIEW_PNG=${OVERVIEW_OUT}"
+echo "ARCHITECTURE_RUNTIME_PNG=${RUNTIME_OUT}"
+echo "ARCHITECTURE_LIFECYCLE_PNG=${LIFECYCLE_OUT}"
+echo "ARCHITECTURE_STATE_PNG=${STATE_OUT}"