agent-control-plane 0.1.0

package/tools/bin/sync-shared-agent-home.sh

@@ -0,0 +1,214 @@
+#!/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"
+
+HOME_DIR="${HOME:-$(eval printf '%s' ~)}"
+CANONICAL_FLOW_SKILL_NAME="${AGENT_CONTROL_PLANE_SKILL_NAME:-agent-control-plane}"
+COMPAT_FLOW_SKILL_ALIAS="${AGENT_CONTROL_PLANE_COMPAT_ALIAS:-}"
+DEPRECATED_FLOW_SKILL_ALIASES_RAW="${AGENT_CONTROL_PLANE_DEPRECATED_SKILL_ALIASES:-}"
+FLOW_SKILL_SOURCE="${AGENT_FLOW_SOURCE_ROOT:-$(resolve_flow_skill_dir "${BASH_SOURCE[0]}")}"
+SOURCE_HOME="${1:-$(resolve_shared_agent_home "${FLOW_SKILL_SOURCE}")}"
+AGENT_PLATFORM_HOME="${AGENT_PLATFORM_HOME:-${HOME_DIR}/.agent-runtime}"
+TARGET_HOME="${2:-${AGENT_PLATFORM_HOME}/runtime-home}"
+FLOW_SKILL_TARGET="${TARGET_HOME}/skills/openclaw/${CANONICAL_FLOW_SKILL_NAME}"
+SOURCE_FLOW_CANONICAL_ALIAS="${SOURCE_HOME}/skills/openclaw/${CANONICAL_FLOW_SKILL_NAME}"
+TARGET_FLOW_COMPAT_ALIAS=""
+SOURCE_FLOW_COMPAT_ALIAS=""
+
+if [[ -n "${COMPAT_FLOW_SKILL_ALIAS}" ]]; then
+  TARGET_FLOW_COMPAT_ALIAS="${TARGET_HOME}/skills/openclaw/${COMPAT_FLOW_SKILL_ALIAS}"
+  SOURCE_FLOW_COMPAT_ALIAS="${SOURCE_HOME}/skills/openclaw/${COMPAT_FLOW_SKILL_ALIAS}"
+fi
+
+if [[ ! -d "${FLOW_SKILL_SOURCE}" ]]; then
+  FLOW_SKILL_SOURCE="${SOURCE_HOME}/skills/openclaw/${CANONICAL_FLOW_SKILL_NAME}"
+fi
+
+if [[ ! -d "${FLOW_SKILL_SOURCE}" && -n "${COMPAT_FLOW_SKILL_ALIAS}" ]]; then
+  FLOW_SKILL_SOURCE="${SOURCE_HOME}/skills/openclaw/${COMPAT_FLOW_SKILL_ALIAS}"
+fi
+
+FLOW_SKILL_SOURCE="$(cd "${FLOW_SKILL_SOURCE}" && pwd -P)"
+
+sync_tree_copy_mode() {
+  local source_dir="${1:?source dir required}"
+  local target_dir="${2:?target dir required}"
+  [[ -d "${source_dir}" ]] || return 0
+  rm -rf "${target_dir}"
+  mkdir -p "${target_dir}"
+  (
+    cd "${source_dir}"
+    find . -mindepth 1 -maxdepth 1 ! -name '.git' -exec cp -R {} "${target_dir}/" \;
+  )
+}
+
+sync_tree_into_target() {
+  local source_dir="${1:?source dir required}"
+  local target_dir="${2:?target dir required}"
+  [[ -n "${target_dir}" ]] || return 0
+  if command -v rsync >/dev/null 2>&1; then
+    sync_tree_rsync "${source_dir}" "${target_dir}"
+  else
+    sync_tree_copy_mode "${source_dir}" "${target_dir}"
+  fi
+}
+
+sync_skill_copies() {
+  sync_tree_into_target "${FLOW_SKILL_SOURCE}" "${SOURCE_FLOW_CANONICAL_ALIAS}"
+  sync_tree_into_target "${FLOW_SKILL_SOURCE}" "${FLOW_SKILL_TARGET}"
+
+  if [[ -n "${SOURCE_FLOW_COMPAT_ALIAS}" ]]; then
+    sync_tree_into_target "${FLOW_SKILL_SOURCE}" "${SOURCE_FLOW_COMPAT_ALIAS}"
+  fi
+
+  if [[ -n "${TARGET_FLOW_COMPAT_ALIAS}" ]]; then
+    sync_tree_into_target "${FLOW_SKILL_SOURCE}" "${TARGET_FLOW_COMPAT_ALIAS}"
+  fi
+}
+
+remove_repo_local_profile_dirs() {
+  local candidate=""
+
+  for candidate in \
+    "${SOURCE_FLOW_CANONICAL_ALIAS}" \
+    "${FLOW_SKILL_TARGET}" \
+    "${SOURCE_FLOW_COMPAT_ALIAS}" \
+    "${TARGET_FLOW_COMPAT_ALIAS}"; do
+    [[ -n "${candidate}" ]] || continue
+    [[ -d "${candidate}" ]] || continue
+    rm -rf "${candidate}/profiles"
+  done
+}
+
+list_deprecated_skill_aliases() {
+  local alias_name=""
+  local raw_aliases="${DEPRECATED_FLOW_SKILL_ALIASES_RAW//,/ }"
+
+  for alias_name in ${raw_aliases}; do
+    [[ -n "${alias_name}" ]] || continue
+    [[ "${alias_name}" == "${CANONICAL_FLOW_SKILL_NAME}" ]] && continue
+    if [[ -n "${COMPAT_FLOW_SKILL_ALIAS}" && "${alias_name}" == "${COMPAT_FLOW_SKILL_ALIAS}" ]]; then
+      continue
+    fi
+    printf '%s\n' "${alias_name}"
+  done
+}
+
+is_flow_skill_copy_dir() {
+  local dir="${1:-}"
+  [[ -n "${dir}" ]] || return 1
+  [[ -f "${dir}/assets/workflow-catalog.json" ]] || return 1
+
+  if [[ ! -f "${dir}/SKILL.md" ]]; then
+    return 0
+  fi
+
+  [[ -f "${dir}/tools/bin/sync-shared-agent-home.sh" ]] || return 1
+  [[ -f "${dir}/tools/bin/flow-runtime-doctor.sh" ]] || return 1
+  return 0
+}
+
+cleanup_stale_flow_skill_dirs() {
+  local skills_root=""
+  local dir=""
+  local dir_name=""
+
+  for skills_root in "${SOURCE_HOME}/skills/openclaw" "${TARGET_HOME}/skills/openclaw"; do
+    [[ -d "${skills_root}" ]] || continue
+    for dir in "${skills_root}"/*; do
+      [[ -d "${dir}" ]] || continue
+      dir_name="$(basename "${dir}")"
+      [[ "${dir_name}" == "${CANONICAL_FLOW_SKILL_NAME}" ]] && continue
+      if [[ -n "${COMPAT_FLOW_SKILL_ALIAS}" && "${dir_name}" == "${COMPAT_FLOW_SKILL_ALIAS}" ]]; then
+        continue
+      fi
+      is_flow_skill_copy_dir "${dir}" || continue
+      rm -rf "${dir}"
+    done
+  done
+}
+
+reset_deprecated_skill_targets() {
+  local alias_name=""
+
+  while IFS= read -r alias_name; do
+    [[ -n "${alias_name}" ]] || continue
+    rm -rf "${SOURCE_HOME}/skills/openclaw/${alias_name}" "${TARGET_HOME}/skills/openclaw/${alias_name}"
+  done < <(list_deprecated_skill_aliases)
+}
+
+cleanup_legacy_flow_publication_dirs() {
+  local root=""
+
+  for root in "${SOURCE_HOME}" "${TARGET_HOME}"; do
+    [[ -d "${root}" ]] || continue
+    rm -rf "${root}/flows/project-adapters" "${root}/flows/profiles"
+  done
+}
+
+normalize_script_permissions() {
+  local root
+
+  for root in \
+    "${TARGET_HOME}/tools/bin" \
+    "${TARGET_HOME}/tools/vendor/codex-quota-manager/scripts" \
+    "${FLOW_SKILL_TARGET}/bin" \
+    "${FLOW_SKILL_TARGET}/hooks" \
+    "${FLOW_SKILL_TARGET}/tools/bin" \
+    "${FLOW_SKILL_TARGET}/tools/tests" \
+    "${FLOW_SKILL_TARGET}/tools/vendor/codex-quota-manager/scripts" \
+    "${TARGET_HOME}/skills/openclaw/codex-quota-manager/scripts"; do
+    [[ -d "${root}" ]] || continue
+    find "${root}" -type f -exec chmod +x {} + 2>/dev/null || true
+  done
+}
+
+sync_tree_rsync() {
+  local source_dir="${1:?source dir required}"
+  local target_dir="${2:?target dir required}"
+  [[ -d "${source_dir}" ]] || return 0
+  mkdir -p "${target_dir}"
+  rsync -a --delete --exclude='.git/' "${source_dir}/" "${target_dir}/"
+}
+
+reset_runtime_skill_targets() {
+  rm -rf "${FLOW_SKILL_TARGET}"
+  if [[ -n "${TARGET_FLOW_COMPAT_ALIAS}" ]]; then
+    rm -rf "${TARGET_FLOW_COMPAT_ALIAS}"
+  fi
+}
+
+reset_source_skill_targets() {
+  if [[ "${FLOW_SKILL_SOURCE}" != "${SOURCE_FLOW_CANONICAL_ALIAS}" ]]; then
+    rm -rf "${SOURCE_FLOW_CANONICAL_ALIAS}"
+  fi
+  if [[ -n "${SOURCE_FLOW_COMPAT_ALIAS}" && "${FLOW_SKILL_SOURCE}" != "${SOURCE_FLOW_COMPAT_ALIAS}" ]]; then
+    rm -rf "${SOURCE_FLOW_COMPAT_ALIAS}"
+  fi
+}
+
+mkdir -p "${TARGET_HOME}/tools" "${TARGET_HOME}/skills/openclaw"
+mkdir -p "${SOURCE_HOME}/skills/openclaw"
+reset_source_skill_targets
+reset_runtime_skill_targets
+reset_deprecated_skill_targets
+cleanup_stale_flow_skill_dirs
+cleanup_legacy_flow_publication_dirs
+
+if command -v rsync >/dev/null 2>&1; then
+  sync_tree_rsync "${SOURCE_HOME}/tools" "${TARGET_HOME}/tools"
+  sync_tree_rsync "${SOURCE_HOME}/skills/openclaw/codex-quota-manager" "${TARGET_HOME}/skills/openclaw/codex-quota-manager"
+else
+  mkdir -p "${TARGET_HOME}/tools" "${TARGET_HOME}/skills/openclaw"
+  sync_tree_copy_mode "${SOURCE_HOME}/tools" "${TARGET_HOME}/tools"
+  sync_tree_copy_mode "${SOURCE_HOME}/skills/openclaw/codex-quota-manager" "${TARGET_HOME}/skills/openclaw/codex-quota-manager"
+fi
+
+sync_skill_copies
+remove_repo_local_profile_dirs
+normalize_script_permissions
+
+printf 'SHARED_AGENT_HOME=%s\n' "${TARGET_HOME}"

package/tools/bin/sync-vscode-workspace.sh

@@ -0,0 +1,157 @@
+#!/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"
+
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+AGENT_REPO_ROOT="$(flow_resolve_agent_repo_root "${CONFIG_YAML}")"
+RETAINED_REPO_ROOT="$(flow_resolve_retained_repo_root "${CONFIG_YAML}")"
+VSCODE_WORKSPACE_FILE="$(flow_resolve_vscode_workspace_file "${CONFIG_YAML}")"
+DEFAULT_BRANCH="$(flow_resolve_default_branch "${CONFIG_YAML}")"
+PROJECT_LABEL="$(flow_resolve_project_label "${CONFIG_YAML}")"
+
+mkdir -p "$(dirname "$VSCODE_WORKSPACE_FILE")"
+
+AGENT_REPO_ROOT="$AGENT_REPO_ROOT" \
+RETAINED_REPO_ROOT="$RETAINED_REPO_ROOT" \
+VSCODE_WORKSPACE_FILE="$VSCODE_WORKSPACE_FILE" \
+DEFAULT_BRANCH="$DEFAULT_BRANCH" \
+PROJECT_LABEL="$PROJECT_LABEL" \
+node <<'EOF'
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const agentRepoRoot = process.env.AGENT_REPO_ROOT;
+const retainedRepoRoot = process.env.RETAINED_REPO_ROOT;
+const workspaceFile = process.env.VSCODE_WORKSPACE_FILE;
+const defaultBranch = process.env.DEFAULT_BRANCH || 'main';
+const projectLabel = process.env.PROJECT_LABEL || 'project';
+
+if (!workspaceFile) {
+  throw new Error('VSCODE_WORKSPACE_FILE is required');
+}
+
+function parseWorktrees(raw) {
+  const entries = [];
+  let current = null;
+
+  for (const line of raw.split('\n')) {
+    if (line.length === 0) {
+      if (current?.path) {
+        entries.push(current);
+      }
+      current = null;
+      continue;
+    }
+
+    if (line.startsWith('worktree ')) {
+      if (current?.path) {
+        entries.push(current);
+      }
+      current = { path: line.slice('worktree '.length) };
+      continue;
+    }
+
+    if (!current) {
+      continue;
+    }
+
+    if (line.startsWith('branch ')) {
+      current.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+      continue;
+    }
+  }
+
+  if (current?.path) {
+    entries.push(current);
+  }
+
+  return entries;
+}
+
+function titleCase(value) {
+  if (!value) return '';
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+function folderNameFor(entry) {
+  const branch = entry.branch || '';
+  const base = path.basename(entry.path);
+
+  if (branch === defaultBranch) {
+    return `${projectLabel} (Automation ${titleCase(defaultBranch)})`;
+  }
+
+  const prMatch = branch.match(/(?:^|\/)pr-(\d+)/);
+  if (prMatch) {
+    return `PR ${prMatch[1]} (${base})`;
+  }
+
+  const issueMatch = branch.match(/issue-(\d+)/);
+  if (issueMatch) {
+    return `Issue ${issueMatch[1]} (${base})`;
+  }
+
+  return branch ? `${branch} (${base})` : base;
+}
+
+const retainedResolved = retainedRepoRoot ? path.resolve(retainedRepoRoot) : '';
+const folders = [];
+const seen = new Set();
+const agentResolved = agentRepoRoot ? path.resolve(agentRepoRoot) : '';
+const agentIsGit =
+  !!agentRepoRoot && (
+    fs.existsSync(path.join(agentRepoRoot, '.git'))
+    || fs.existsSync(`${agentRepoRoot}.git`)
+    || fs.existsSync(path.join(agentRepoRoot, '.git', 'HEAD'))
+  );
+
+if (retainedResolved && fs.existsSync(retainedResolved)) {
+  folders.push({
+    name: `${projectLabel} (Main)`,
+    path: retainedResolved,
+  });
+  seen.add(retainedResolved);
+}
+
+if (agentResolved && fs.existsSync(agentResolved) && !seen.has(agentResolved)) {
+  folders.push({
+    name: `${projectLabel} (Automation ${titleCase(defaultBranch)})`,
+    path: agentResolved,
+  });
+  seen.add(agentResolved);
+}
+
+if (agentIsGit) {
+  const raw = execFileSync('git', ['-C', agentRepoRoot, 'worktree', 'list', '--porcelain'], {
+    encoding: 'utf8',
+  });
+
+  for (const entry of parseWorktrees(raw)) {
+    const resolved = path.resolve(entry.path);
+    if (resolved === agentResolved) {
+      continue;
+    }
+    if (!fs.existsSync(resolved) || seen.has(resolved)) {
+      continue;
+    }
+    folders.push({
+      name: folderNameFor(entry),
+      path: resolved,
+    });
+    seen.add(resolved);
+  }
+}
+
+const workspace = {
+  folders,
+  settings: {
+    'git.autoRepositoryDetection': 'subFolders',
+  },
+};
+
+fs.writeFileSync(workspaceFile, `${JSON.stringify(workspace, null, 2)}\n`, 'utf8');
+EOF

package/tools/bin/test-smoke.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FLOW_SKILL_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  test-smoke.sh [--help]
+
+Run the main smoke gates for the shared agent-control-plane package in one command.
+
+Steps:
+  1. check-skill-contracts.sh
+  2. tools/tests/test-profile-smoke.sh
+  3. tools/tests/test-project-runtimectl.sh
+
+Environment overrides:
+  ACP_TEST_SMOKE_CHECK_CONTRACTS_SCRIPT
+  ACP_TEST_SMOKE_PROFILE_TEST_SCRIPT
+  ACP_TEST_SMOKE_RUNTIMECTL_TEST_SCRIPT
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --help|-h) usage; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; usage >&2; exit 64 ;;
+  esac
+done
+
+check_contracts_script="${ACP_TEST_SMOKE_CHECK_CONTRACTS_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/check-skill-contracts.sh}"
+profile_test_script="${ACP_TEST_SMOKE_PROFILE_TEST_SCRIPT:-${FLOW_SKILL_DIR}/tools/tests/test-profile-smoke.sh}"
+runtimectl_test_script="${ACP_TEST_SMOKE_RUNTIMECTL_TEST_SCRIPT:-${FLOW_SKILL_DIR}/tools/tests/test-project-runtimectl.sh}"
+
+run_step() {
+  local label="${1:?label required}"
+  shift
+  local status=0
+
+  printf 'SMOKE_STEP=%s\n' "${label}"
+  set +e
+  "$@"
+  status=$?
+  set -e
+  if [[ "${status}" -eq 0 ]]; then
+    printf 'SMOKE_STEP_STATUS=ok\n'
+    return 0
+  fi
+
+  printf 'SMOKE_STEP_STATUS=failed\n'
+  printf 'FAILED_STEP=%s\n' "${label}"
+  printf 'EXIT_CODE=%s\n' "${status}"
+  printf 'SMOKE_TEST_STATUS=failed\n'
+  return "${status}"
+}
+
+run_step "check-skill-contracts" bash "${check_contracts_script}"
+run_step "test-profile-smoke" bash "${profile_test_script}"
+run_step "test-project-runtimectl" bash "${runtimectl_test_script}"
+
+printf 'SMOKE_TEST_STATUS=ok\n'

package/tools/bin/uninstall-project-launchd.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  uninstall-project-launchd.sh --profile-id <id> [options]
+
+Remove the per-user LaunchAgent for one ACP project runtime.
+
+Options:
+  --profile-id <id>  Installed profile id to manage
+  --label <label>    Override LaunchAgent label (default: ai.agent.project.<id>)
+  --help             Show this help
+EOF
+}
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+profile_id=""
+label_override=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --profile-id) profile_id="${2:-}"; shift 2 ;;
+    --label) label_override="${2:-}"; shift 2 ;;
+    --help|-h) usage; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; usage >&2; exit 64 ;;
+  esac
+done
+
+if [[ -z "${profile_id}" ]]; then
+  usage >&2
+  exit 64
+fi
+
+HOME_DIR="${ACP_PROJECT_RUNTIME_HOME_DIR:-${HOME:-}}"
+WORKSPACE_DIR="${ACP_PROJECT_RUNTIME_WORKSPACE_DIR:-${HOME_DIR}/.agent-runtime/control-plane/workspace}"
+LAUNCH_AGENTS_DIR="${ACP_PROJECT_RUNTIME_LAUNCH_AGENTS_DIR:-${HOME_DIR}/Library/LaunchAgents}"
+profile_slug="$(printf '%s' "${profile_id}" | tr -c 'A-Za-z0-9._-' '-')"
+LABEL="${label_override:-${ACP_PROJECT_RUNTIME_LAUNCHD_LABEL:-ai.agent.project.${profile_slug}}}"
+PLIST_PATH="${LAUNCH_AGENTS_DIR}/${LABEL}.plist"
+WRAPPER_PATH="${WORKSPACE_DIR}/bin/agent-project-${profile_slug}-launchd.sh"
+
+if [[ "${ACP_PROJECT_RUNTIME_SKIP_LAUNCHCTL:-0}" != "1" ]] && command -v launchctl >/dev/null 2>&1; then
+  launchctl bootout "gui/$(id -u)/${LABEL}" >/dev/null 2>&1 || true
+fi
+
+rm -f "${PLIST_PATH}" "${WRAPPER_PATH}"
+
+printf 'LAUNCHD_UNINSTALL_STATUS=ok\n'
+printf 'PROFILE_ID=%s\n' "${profile_id}"
+printf 'LABEL=%s\n' "${LABEL}"
+printf 'PLIST=%s\n' "${PLIST_PATH}"
+printf 'WRAPPER=%s\n' "${WRAPPER_PATH}"

package/tools/bin/update-github-labels.sh

@@ -0,0 +1,14 @@
+#!/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"
+
+NUMBER="${1:?usage: update-github-labels.sh NUMBER [--add LABEL]... [--remove LABEL]...}"
+shift
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+REPO_SLUG="$(flow_resolve_repo_slug "${CONFIG_YAML}")"
+UPDATE_LABELS_BIN="${SCRIPT_DIR}/agent-github-update-labels"
+
+bash "${UPDATE_LABELS_BIN}" --repo-slug "$REPO_SLUG" --number "$NUMBER" "$@"

package/tools/bin/worker-status.sh

@@ -0,0 +1,19 @@
+#!/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: worker-status.sh SESSION}"
+FLOW_SKILL_DIR="$(resolve_flow_skill_dir "${BASH_SOURCE[0]}")"
+if ! flow_require_explicit_profile_selection "${FLOW_SKILL_DIR}" "worker-status.sh"; then
+  exit 64
+fi
+CONFIG_YAML="$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")"
+RUNS_ROOT="$(flow_resolve_runs_root "${CONFIG_YAML}")"
+FLOW_TOOLS_DIR="${FLOW_SKILL_DIR}/tools/bin"
+
+exec bash "${FLOW_TOOLS_DIR}/agent-project-worker-status" \
+  --runs-root "$RUNS_ROOT" \
+  --session "$SESSION"

package/tools/bin/workflow-catalog.sh

@@ -0,0 +1,77 @@
+#!/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"
+
+FLOW_SKILL_DIR="$(resolve_flow_skill_dir "${BASH_SOURCE[0]}")"
+CATALOG_FILE="${FLOW_SKILL_DIR}/assets/workflow-catalog.json"
+COMMAND="${1:-list}"
+WORKFLOW_ID="${2:-}"
+AVAILABLE_PROFILES="$(flow_list_profile_ids "${FLOW_SKILL_DIR}" | paste -sd, -)"
+ACTIVE_PROFILE="$(flow_resolve_adapter_id "$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")")"
+PROFILE_SELECTION_MODE="$(flow_profile_selection_mode "${FLOW_SKILL_DIR}")"
+PROFILE_NOTES="$(flow_resolve_profile_notes_file "$(resolve_flow_config_yaml "${BASH_SOURCE[0]}")")"
+
+python3 - "$CATALOG_FILE" "$COMMAND" "$WORKFLOW_ID" "$AVAILABLE_PROFILES" "$ACTIVE_PROFILE" "$PROFILE_SELECTION_MODE" "$PROFILE_NOTES" <<'PY'
+import json
+import sys
+
+catalog_file, command, workflow_id, available_profiles, active_profile, profile_selection_mode, profile_notes = sys.argv[1:8]
+with open(catalog_file, "r", encoding="utf-8") as fh:
+    payload = json.load(fh)
+
+workflows = payload.get("workflows", [])
+profile_ids = [item for item in available_profiles.split(",") if item]
+
+if profile_ids:
+    payload["available_profiles"] = profile_ids
+
+payload["active_profile"] = active_profile
+payload["profile_selection_mode"] = profile_selection_mode
+payload["profile_notes"] = profile_notes
+
+if command == "json":
+    json.dump(payload, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    raise SystemExit(0)
+
+if command == "profiles":
+    for profile_id in profile_ids:
+        sys.stdout.write(f"{profile_id}\n")
+    raise SystemExit(0)
+
+if command == "ids":
+    for workflow in workflows:
+        sys.stdout.write(f"{workflow['id']}\n")
+    raise SystemExit(0)
+
+if command == "context":
+    sys.stdout.write(f"ACTIVE_PROFILE={active_profile}\n")
+    sys.stdout.write(f"PROFILE_SELECTION_MODE={profile_selection_mode}\n")
+    sys.stdout.write(f"PROFILE_NOTES={profile_notes}\n")
+    raise SystemExit(0)
+
+if command == "show":
+    match = next((wf for wf in workflows if wf["id"] == workflow_id), None)
+    if match is None:
+      raise SystemExit(f"unknown workflow id: {workflow_id}")
+    sys.stdout.write(f"ACTIVE_PROFILE={active_profile}\n")
+    sys.stdout.write(f"PROFILE_SELECTION_MODE={profile_selection_mode}\n")
+    for key in ("id", "kind", "trigger", "entrypoint", "summary"):
+        sys.stdout.write(f"{key.upper()}={match.get(key, '')}\n")
+    raise SystemExit(0)
+
+if command != "list":
+    raise SystemExit(f"unknown command: {command}")
+
+for workflow in workflows:
+    row = [
+        workflow.get("id", ""),
+        workflow.get("kind", ""),
+        workflow.get("entrypoint", ""),
+        workflow.get("trigger", ""),
+    ]
+    sys.stdout.write("\t".join(row) + "\n")
+PY