open-research-protocol 0.4.2 → 0.4.4

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "open-research-protocol",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "ORP CLI (Open Research Protocol): agent-friendly research workflows, runtime, reports, and pack tooling.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/SproutSeeds/orp.git"
+    "url": "git+https://github.com/SproutSeeds/orp.git"
   },
   "homepage": "https://github.com/SproutSeeds/orp#readme",
   "bugs": {
@@ -37,6 +37,7 @@
   },
   "scripts": {
     "postinstall": "node scripts/npm-postinstall-check.js",
+    "prepublishOnly": "node scripts/npm-prepublish-guard.js",
     "test": "python3 -m unittest discover -s tests -v"
   },
   "keywords": [

package/scripts/npm-prepublish-guard.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("child_process");
+
+function git(args) {
+  return spawnSync("git", args, { encoding: "utf8" });
+}
+
+function fail(message, details = "") {
+  console.error(`[orp] prepublish blocked: ${message}`);
+  if (details.trim()) {
+    console.error(details.trim());
+  }
+  process.exit(1);
+}
+
+const inside = git(["rev-parse", "--is-inside-work-tree"]);
+if (inside.error || inside.status !== 0 || inside.stdout.trim() !== "true") {
+  fail("npm publish must run from inside a git worktree.");
+}
+
+const status = git(["status", "--short"]);
+if (status.error || status.status !== 0) {
+  fail("unable to inspect git working tree state.", status.stderr || status.stdout);
+}
+
+if (status.stdout.trim()) {
+  const preview = status.stdout
+    .trim()
+    .split("\n")
+    .slice(0, 10)
+    .join("\n");
+  fail(
+    "working tree is not clean. Commit, stash, or remove local-only files before publishing so npm and GitHub stay aligned.",
+    preview,
+  );
+}
+
+if (process.env.GITHUB_ACTIONS === "true") {
+  process.exit(0);
+}
+
+const remoteContains = git(["branch", "-r", "--contains", "HEAD"]);
+if (remoteContains.error || remoteContains.status !== 0) {
+  fail("unable to confirm that HEAD exists on a remote branch.", remoteContains.stderr || remoteContains.stdout);
+}
+
+const remoteBranches = remoteContains.stdout
+  .split("\n")
+  .map((line) => line.trim())
+  .filter(Boolean);
+
+if (remoteBranches.length === 0) {
+  fail("current HEAD is not present on any remote branch. Push the release commit to GitHub before publishing.");
+}

package/scripts/orp-release-smoke.sh

@@ -0,0 +1,234 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+RUN_HOSTED=0
+RUN_WORKER=0
+RUN_TESTS=1
+KEEP_TEMP=0
+CODEX_SESSION_ID="${CODEX_THREAD_ID:-}"
+IDEA_ID=""
+TMP_ROOT=""
+ORP_BIN=""
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/orp-release-smoke.sh [options]
+
+Local release smoke:
+  - runs unit tests
+  - verifies npm pack / publish dry runs
+  - installs the packed tarball into a clean temp prefix
+  - exercises init/status/branch/checkpoint/gate/ready on a fresh repo
+
+Optional hosted smoke:
+  --hosted            run hosted whoami/ideas/add/show/world/checkpoint smoke
+  --worker            after --hosted, run `orp agent work --once`
+  --codex-session-id  Codex session id used for hosted world binding
+
+Other options:
+  --skip-tests        skip the unit test pass
+  --keep-temp         keep temp install/repo directories for inspection
+  -h, --help          show this help
+EOF
+}
+
+note() {
+  printf '\n[%s] %s\n' "$(date '+%H:%M:%S')" "$*"
+}
+
+json_field() {
+  python3 - "$1" "$2" <<'PY'
+import json
+import sys
+
+path = sys.argv[1]
+field = sys.argv[2]
+value = json.loads(open(path, encoding="utf-8").read())
+for part in field.split("."):
+    if isinstance(value, dict):
+        value = value.get(part)
+    elif isinstance(value, list) and part.isdigit():
+        idx = int(part)
+        value = value[idx] if 0 <= idx < len(value) else None
+    else:
+        value = None
+        break
+if value is None:
+    print("")
+elif isinstance(value, bool):
+    print("true" if value else "false")
+else:
+    print(value)
+PY
+}
+
+cleanup() {
+  local exit_code=$?
+  if [[ -n "${IDEA_ID}" && -n "${ORP_BIN}" ]]; then
+    note "Cleaning up hosted smoke idea ${IDEA_ID}"
+    "${ORP_BIN}" idea remove "${IDEA_ID}" --purge --json >/dev/null 2>&1 || true
+  fi
+  if [[ "${KEEP_TEMP}" != "1" && -n "${TMP_ROOT}" && -d "${TMP_ROOT}" ]]; then
+    rm -rf "${TMP_ROOT}" >/dev/null 2>&1 || true
+  fi
+  exit "${exit_code}"
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --hosted)
+      RUN_HOSTED=1
+      shift
+      ;;
+    --worker)
+      RUN_HOSTED=1
+      RUN_WORKER=1
+      shift
+      ;;
+    --skip-tests)
+      RUN_TESTS=0
+      shift
+      ;;
+    --keep-temp)
+      KEEP_TEMP=1
+      shift
+      ;;
+    --codex-session-id)
+      CODEX_SESSION_ID="${2:-}"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      printf 'Unknown argument: %s\n' "$1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+trap cleanup EXIT
+
+command -v python3 >/dev/null
+command -v npm >/dev/null
+command -v node >/dev/null
+command -v git >/dev/null
+
+TMP_ROOT="$(mktemp -d /tmp/orp-release-smoke.XXXXXX)"
+PACK_DIR="${TMP_ROOT}/pack"
+PREFIX_DIR="${TMP_ROOT}/prefix"
+REPO_DIR="${TMP_ROOT}/repo"
+mkdir -p "${PACK_DIR}" "${PREFIX_DIR}" "${REPO_DIR}"
+
+if [[ "${RUN_TESTS}" == "1" ]]; then
+  note "Running unit tests"
+  (
+    cd "${ROOT_DIR}"
+    env PYTHONPYCACHEPREFIX=/tmp/orp-pyc python3 -m unittest discover -s tests -v
+  )
+fi
+
+note "Checking published npm version"
+(
+  cd "${ROOT_DIR}"
+  npm view open-research-protocol version dist-tags --json
+)
+
+note "Verifying npm pack and publish dry runs"
+(
+  cd "${ROOT_DIR}"
+  npm pack --dry-run --cache /tmp/orp-npm-cache
+  npm publish --dry-run
+)
+
+note "Packing local release candidate"
+(
+  cd "${PACK_DIR}"
+  npm pack "${ROOT_DIR}" --json > pack.json
+)
+TARBALL="${PACK_DIR}/$(json_field "${PACK_DIR}/pack.json" "0.filename")"
+
+note "Installing tarball into temp prefix"
+npm install -g --prefix "${PREFIX_DIR}" "${TARBALL}" >/dev/null
+ORP_BIN="${PREFIX_DIR}/bin/orp"
+
+note "Checking installed binary"
+"${ORP_BIN}" -h >/dev/null
+
+note "Running fresh-repo governance smoke"
+(
+  cd "${REPO_DIR}"
+  "${ORP_BIN}" init --json >/dev/null
+  git config user.name "ORP Release Smoke"
+  git config user.email "orp-release@example.com"
+  "${ORP_BIN}" status --json >/dev/null
+  "${ORP_BIN}" branch start work/bootstrap --allow-dirty --json >/dev/null
+  "${ORP_BIN}" checkpoint create -m "bootstrap governance" --json >/dev/null
+  "${ORP_BIN}" backup -m "backup bootstrap governance" --json >/dev/null
+  "${ORP_BIN}" gate run --profile default --json >/dev/null
+  "${ORP_BIN}" checkpoint create -m "capture passing validation" --json >/dev/null
+  "${ORP_BIN}" ready --json >/dev/null
+  "${ORP_BIN}" packet emit --profile default --json >/dev/null
+  "${ORP_BIN}" report summary --json >/dev/null
+)
+
+if [[ "${RUN_HOSTED}" == "1" ]]; then
+  note "Running hosted workspace smoke"
+  "${ORP_BIN}" whoami --json >/dev/null
+  "${ORP_BIN}" ideas list --limit 5 --json >/dev/null
+
+  local_idea_json="${TMP_ROOT}/idea-add.json"
+  "${ORP_BIN}" idea add \
+    --title "ORP release smoke $(date '+%Y-%m-%d %H:%M:%S')" \
+    --notes "Temporary hosted smoke test for ORP CLI release readiness. Safe to purge." \
+    --json > "${local_idea_json}"
+  IDEA_ID="$(json_field "${local_idea_json}" "idea.id")"
+  if [[ -z "${IDEA_ID}" ]]; then
+    printf 'Hosted smoke failed: could not create idea.\n' >&2
+    exit 1
+  fi
+
+  "${ORP_BIN}" idea show "${IDEA_ID}" --json >/dev/null
+
+  if [[ -z "${CODEX_SESSION_ID}" ]]; then
+    printf 'Hosted smoke requires --codex-session-id or CODEX_THREAD_ID for world binding.\n' >&2
+    exit 1
+  fi
+
+  "${ORP_BIN}" world bind "${IDEA_ID}" \
+    --name "ORP release smoke" \
+    --project-root "${ROOT_DIR}" \
+    --github-url "https://github.com/SproutSeeds/orp" \
+    --codex-session-id "${CODEX_SESSION_ID}" \
+    --json >/dev/null
+
+  world_ok=0
+  for _ in 1 2 3 4 5; do
+    local_world_json="${TMP_ROOT}/world-show.json"
+    "${ORP_BIN}" world show "${IDEA_ID}" --json > "${local_world_json}"
+    if [[ "$(json_field "${local_world_json}" "world.id")" != "" ]]; then
+      world_ok=1
+      break
+    fi
+    sleep 1
+  done
+  if [[ "${world_ok}" != "1" ]]; then
+    printf 'Hosted smoke failed: world show did not return a bound world.\n' >&2
+    exit 1
+  fi
+
+  "${ORP_BIN}" checkpoint queue --idea-id "${IDEA_ID}" --json >/dev/null
+
+  if [[ "${RUN_WORKER}" == "1" ]]; then
+    note "Running hosted worker smoke"
+    "${ORP_BIN}" agent work --once --json >/dev/null
+  fi
+fi
+
+note "Release smoke passed"
+if [[ "${KEEP_TEMP}" == "1" ]]; then
+  note "Temp files kept at ${TMP_ROOT}"
+fi

package/spec/v1/link-project.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openresearchprotocol.com/spec/v1/link-project.schema.json",
+  "title": "ORP Linked Project",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "idea_id",
+    "project_root",
+    "linked_at_utc"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "idea_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "idea_title": {
+      "type": "string"
+    },
+    "world_id": {
+      "type": "string"
+    },
+    "world_name": {
+      "type": "string"
+    },
+    "project_root": {
+      "type": "string",
+      "minLength": 1
+    },
+    "github_url": {
+      "type": "string"
+    },
+    "linked_at_utc": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "linked_email": {
+      "type": "string"
+    },
+    "source": {
+      "type": "string",
+      "enum": [
+        "cli",
+        "rust-app",
+        "import-rust"
+      ]
+    },
+    "notes": {
+      "type": "string"
+    }
+  }
+}

package/spec/v1/link-session.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openresearchprotocol.com/spec/v1/link-session.schema.json",
+  "title": "ORP Linked Session",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "orp_session_id",
+    "label",
+    "state",
+    "project_root",
+    "created_at_utc",
+    "last_active_at_utc",
+    "archived",
+    "primary"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "orp_session_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "label": {
+      "type": "string",
+      "minLength": 1
+    },
+    "project_root": {
+      "type": "string",
+      "minLength": 1
+    },
+    "codex_session_id": {
+      "type": "string"
+    },
+    "role": {
+      "type": "string",
+      "enum": [
+        "primary",
+        "secondary",
+        "review",
+        "exploration",
+        "other"
+      ]
+    },
+    "state": {
+      "type": "string",
+      "enum": [
+        "active",
+        "closed"
+      ]
+    },
+    "created_at_utc": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "last_active_at_utc": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "archived": {
+      "type": "boolean"
+    },
+    "primary": {
+      "type": "boolean"
+    },
+    "terminal_target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "window_id",
+        "tab_number"
+      ],
+      "properties": {
+        "window_id": {
+          "type": "integer"
+        },
+        "tab_number": {
+          "type": "integer"
+        }
+      }
+    },
+    "source": {
+      "type": "string",
+      "enum": [
+        "cli",
+        "rust-app",
+        "import-rust"
+      ]
+    },
+    "notes": {
+      "type": "string"
+    }
+  }
+}

package/spec/v1/runner-machine.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openresearchprotocol.com/spec/v1/runner-machine.schema.json",
+  "title": "ORP Runner Machine",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "machine_id",
+    "machine_name",
+    "platform",
+    "runner_enabled"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "machine_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "machine_name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "platform": {
+      "type": "string"
+    },
+    "app_version": {
+      "type": "string"
+    },
+    "runner_enabled": {
+      "type": "boolean"
+    },
+    "linked_email": {
+      "type": "string"
+    },
+    "last_heartbeat_at_utc": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "last_sync_at_utc": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

package/spec/v1/runner-runtime.schema.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openresearchprotocol.com/spec/v1/runner-runtime.schema.json",
+  "title": "ORP Runner Runtime",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "status",
+    "active_job",
+    "last_job",
+    "recent_events"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "idle",
+        "claimed",
+        "running"
+      ]
+    },
+    "updated_at_utc": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "active_job": {
+      "$ref": "#/$defs/jobState"
+    },
+    "last_job": {
+      "$ref": "#/$defs/jobState"
+    },
+    "recent_events": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/runtimeEvent"
+      }
+    }
+  },
+  "$defs": {
+    "jobState": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "job_id": {
+          "type": "string"
+        },
+        "job_kind": {
+          "type": "string"
+        },
+        "lease_id": {
+          "type": "string"
+        },
+        "idea_id": {
+          "type": "string"
+        },
+        "world_id": {
+          "type": "string"
+        },
+        "project_root": {
+          "type": "string"
+        },
+        "repo_root": {
+          "type": "string"
+        },
+        "orp_session_id": {
+          "type": "string"
+        },
+        "codex_session_id": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string"
+        },
+        "summary": {
+          "type": "string"
+        },
+        "error": {
+          "type": "string"
+        },
+        "claimed_at_utc": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "started_at_utc": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "last_heartbeat_at_utc": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "lease_expires_at_utc": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "finished_at_utc": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "runtimeEvent": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "timestamp_utc": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "status": {
+          "type": "string"
+        },
+        "job_id": {
+          "type": "string"
+        },
+        "lease_id": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}