open-research-protocol 0.4.8 → 0.4.10

package/README.md

@@ -33,6 +33,7 @@ verification remains independent of framing. See `modules/instruments/README.md`
 - `docs/ORP_REASONING_KERNEL_CANONICAL_CONTINUATION_PILOT.md` — harder live downstream benchmark where the agent must produce the next canonical task artifact
 - `docs/ORP_REASONING_KERNEL_EVIDENCE_MATRIX.md` — honest map of what the kernel proves, only suggests, or still leaves unproven
 - `docs/ORP_REASONING_KERNEL_EVALUATION_PLAN.md` — comparative experiment plan for upgrading kernel evidence beyond implementation validity
+- `docs/ORP_YOUTUBE_INSPECT.md` — first-class YouTube metadata/transcript ingestion surface for agent-readable external source context
 - `docs/EXTERNAL_CONTRIBUTION_GOVERNANCE.md` — canonical local-first workflow for external OSS PR work
 - `docs/OSS_CONTRIBUTION_AGENT_LOOP.md` — agent operating rhythm for external contribution workflows
 - `templates/` — claim, verification, failure, and issue templates
@@ -51,11 +52,13 @@ verification remains independent of framing. See `modules/instruments/README.md`
 ORP should feel like one CLI with built-in abilities:
 
 - `workspace` for hosted auth, idea, feature, world, checkpoint, and worker operations
+- `youtube` for public video metadata and transcript ingestion
 - `governance` for local-first repo initialization, branch safety, checkpoint commits, backup refs, readiness, repair, and cleanup
 - `discover` for profile-based GitHub scanning and opportunity selection
 - `collaborate` for repository collaboration setup and workflow execution
 - `erdos` for Erdos-specific data and workflow support
 - `report` and `packet` for ORP artifacts
+- `compute` for targeted compute admission, local execution, and paid approval gating
 
 The `pack` layer still exists, but it is now an advanced/internal surface rather
 than the main product story.
@@ -118,6 +121,8 @@ orp home --json
 orp about --json
 orp auth login
 orp whoami --json
+orp youtube inspect https://www.youtube.com/watch?v=<video_id> --json
+orp youtube inspect https://www.youtube.com/watch?v=<video_id> --save --json
 orp ideas list --json
 orp world bind --idea-id <idea-id> --project-root /abs/path --codex-session-id <session-id> --json
 orp checkpoint queue --idea-id <idea-id> --json
@@ -141,6 +146,8 @@ orp pack install --pack-id erdos-open-problems --json
 orp pack fetch --source <git-url> --pack-id <pack-id> --install-target . --json
 orp gate run --profile default --json
 orp packet emit --profile default --json
+orp compute decide --input orp.compute.json --json
+orp compute run-local --input orp.compute.json --task orp.compute.task.json --json
 orp report summary --json
 ```
 
@@ -149,6 +156,8 @@ These surfaces are meant to help automated systems discover ORP quickly:
 - bare `orp` opens a home screen with repo/runtime status, available packs, and next commands
 - `orp home --json` returns the same landing context in machine-readable form
 - `orp auth ...`, `orp ideas ...`, `orp world ...`, `orp checkpoint ...`, `orp runner ...`, and `orp agent ...` expose the hosted workspace surface directly through ORP
+- `orp compute ...` exposes targeted-compute admission, local execution, and paid-approval gating through a stable ORP wrapper surface
+- `orp youtube inspect ...` exposes public YouTube metadata plus full transcript ingestion through a stable ORP artifact shape for agent use when caption tracks are available
 - `orp init`, `orp status`, `orp branch start`, `orp checkpoint create`, `orp backup`, `orp ready`, `orp doctor`, and `orp cleanup` expose the local-first repo governance surface directly through ORP
 - `orp discover ...` exposes profile-based GitHub scanning as a built-in ORP ability
 - `orp collaborate ...` exposes built-in collaboration setup and workflow execution without asking users to think in terms of separate governance packs
@@ -212,6 +221,7 @@ Minimal CLI skeleton:
 
 ```bash
 orp auth login
+orp youtube inspect https://www.youtube.com/watch?v=<video_id> --json
 orp ideas list --json
 orp world bind --idea-id <idea-id> --project-root /abs/path --codex-session-id <session-id> --json
 orp checkpoint queue --idea-id <idea-id> --json

package/bin/orp-compute.mjs

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import {
+  buildOrpComputeGateResult,
+  buildOrpComputePacket,
+  defineComputePacket,
+  defineDecision,
+  defineImpactRead,
+  definePolicy,
+  defineResultBundle,
+  defineRung,
+  evaluateDispatch,
+  runLocalShellPacket,
+} from "breakthroughs";
+
+function printHelp() {
+  console.log(`ORP compute
+
+Usage:
+  orp compute decide --input <path> [--packet-out <path>] [--json]
+  orp compute run-local --input <path> --task <path> [--receipt-out <path>] [--packet-out <path>] [--json]
+
+Input JSON shape:
+  {
+    "decision": { ... },
+    "rung": { ... },
+    "policy": { ... },
+    "packet": { ... },
+    "repo": {
+      "rootPath": "/abs/path",
+      "git": { "branch": "main", "commit": "abc123" }
+    },
+    "orp": {
+      "boardId": "targeted_compute",
+      "problemId": "adult-vs-developmental-rgc",
+      "artifactRoot": "orp/artifacts"
+    }
+  }
+
+Task JSON shape for run-local:
+  {
+    "command": "node",
+    "args": ["-e", "console.log('hello')"],
+    "cwd": "/abs/path",
+    "timeoutMs": 30000,
+    "env": {}
+  }
+
+Policy semantics:
+- local admitted rungs can resolve to run_local
+- paid admitted rungs resolve to request_paid_approval unless the rung is explicitly approved in policy.paid.approvedRungs
+`);
+}
+
+function parseArgs(argv) {
+  const options = {
+    json: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (arg === "-h" || arg === "--help") {
+      options.help = true;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2).replace(/-([a-z])/g, (_, ch) => ch.toUpperCase());
+      const value = argv[i + 1];
+      if (value == null || value.startsWith("--")) {
+        throw new Error(`missing value for ${arg}`);
+      }
+      options[key] = value;
+      i += 1;
+      continue;
+    }
+
+    if (!options.command) {
+      options.command = arg;
+    } else {
+      throw new Error(`unexpected argument: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+async function readJson(filePath) {
+  const raw = await fs.readFile(filePath, "utf8");
+  return JSON.parse(raw);
+}
+
+async function writeJson(filePath, payload) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+
+function buildContext(raw) {
+  if (!raw || typeof raw !== "object") {
+    throw new Error("input must be a JSON object");
+  }
+
+  return {
+    raw,
+    decision: defineDecision(raw.decision),
+    rung: defineRung(raw.rung),
+    policy: definePolicy(raw.policy),
+    packet: defineComputePacket(raw.packet),
+  };
+}
+
+function commandLabel(subcommand, options) {
+  const parts = ["orp", "compute", subcommand];
+  if (options.input) {
+    parts.push("--input", options.input);
+  }
+  if (options.task) {
+    parts.push("--task", options.task);
+  }
+  return parts.join(" ");
+}
+
+function gateStatusForDispatch(action) {
+  if (action === "hold_packet") {
+    return "fail";
+  }
+  if (action === "request_paid_approval") {
+    return "hold";
+  }
+  return "pass";
+}
+
+function summarizeDispatch(dispatchResult) {
+  if (dispatchResult.action === "request_paid_approval") {
+    return `compute packet requires explicit paid approval for rung ${dispatchResult.rungId}`;
+  }
+  if (dispatchResult.action === "hold_packet") {
+    return `compute packet is being held because ${dispatchResult.reason}`;
+  }
+  return `compute packet admitted with action ${dispatchResult.action}`;
+}
+
+async function runDecide(options) {
+  if (!options.input) {
+    throw new Error("compute decide requires --input <path>");
+  }
+
+  const context = buildContext(await readJson(options.input));
+  const dispatchResult = evaluateDispatch(context);
+  const gateResult = buildOrpComputeGateResult({
+    gateId: context.packet.rungId,
+    command: commandLabel("decide", options),
+    status: gateStatusForDispatch(dispatchResult.action),
+    evidenceNote: summarizeDispatch(dispatchResult),
+  });
+
+  const payload = {
+    ok: dispatchResult.action !== "hold_packet",
+    command: "compute decide",
+    dispatch_result: dispatchResult,
+    gate_result: gateResult,
+  };
+
+  if (options.packetOut) {
+    const orpPacket = buildOrpComputePacket({
+      repoRoot: context.raw.repo?.rootPath || process.cwd(),
+      repoGit: context.raw.repo?.git,
+      decision: context.decision,
+      packet: context.packet,
+      dispatchResult,
+      gateResults: [gateResult],
+      artifactRoot: context.raw.orp?.artifactRoot,
+      boardId: context.raw.orp?.boardId,
+      problemId: context.raw.orp?.problemId,
+      stateNote: summarizeDispatch(dispatchResult),
+    });
+    await writeJson(options.packetOut, orpPacket);
+    payload.orp_packet_path = path.resolve(options.packetOut);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(`${dispatchResult.action}: ${summarizeDispatch(dispatchResult)}`);
+  }
+
+  return dispatchResult.action === "hold_packet" ? 1 : 0;
+}
+
+async function runLocal(options) {
+  if (!options.input) {
+    throw new Error("compute run-local requires --input <path>");
+  }
+  if (!options.task) {
+    throw new Error("compute run-local requires --task <path>");
+  }
+
+  const context = buildContext(await readJson(options.input));
+  const task = await readJson(options.task);
+  const dispatchResult = evaluateDispatch(context);
+
+  if (dispatchResult.action !== "run_local") {
+    const message = `compute packet is not locally runnable; dispatch action is ${dispatchResult.action}`;
+    if (options.json) {
+      console.log(JSON.stringify({ ok: false, error: message, dispatch_result: dispatchResult }, null, 2));
+    } else {
+      console.error(message);
+    }
+    return 1;
+  }
+
+  const executionReceipt = await runLocalShellPacket({
+    decision: context.decision,
+    rung: context.rung,
+    packet: context.packet,
+    dispatchResult,
+    task,
+  });
+
+  const gateResult = buildOrpComputeGateResult({
+    gateId: context.packet.rungId,
+    command: `${executionReceipt.command} ${executionReceipt.args.join(" ")}`.trim(),
+    status: executionReceipt.status === "pass" ? "pass" : "fail",
+    exitCode: executionReceipt.exitCode == null ? 1 : executionReceipt.exitCode,
+    durationMs: executionReceipt.durationMs,
+    evidenceNote: `local shell execution completed with status ${executionReceipt.status}`,
+  });
+
+  const resultBundle = defineResultBundle({
+    id: `${context.packet.id}-result`,
+    packetId: context.packet.id,
+    outputs: context.packet.requiredOutputs,
+    status: executionReceipt.status,
+    metrics: {
+      exitCode: executionReceipt.exitCode,
+      durationMs: executionReceipt.durationMs,
+      timedOut: executionReceipt.timedOut,
+    },
+  });
+
+  const impactRead = defineImpactRead({
+    id: `${context.packet.id}-impact`,
+    bundleId: resultBundle.id,
+    nextAction: executionReceipt.status === "pass" ? "review_result_bundle" : "reroute_or_debug",
+    summary:
+      executionReceipt.status === "pass"
+        ? `local compute packet ${context.packet.id} completed successfully`
+        : `local compute packet ${context.packet.id} failed and needs follow-up`,
+  });
+
+  const payload = {
+    ok: executionReceipt.status === "pass",
+    command: "compute run-local",
+    dispatch_result: dispatchResult,
+    execution_receipt: executionReceipt,
+    gate_result: gateResult,
+    result_bundle: resultBundle,
+    impact_read: impactRead,
+  };
+
+  if (options.receiptOut) {
+    await writeJson(options.receiptOut, executionReceipt);
+    payload.execution_receipt_path = path.resolve(options.receiptOut);
+  }
+
+  if (options.packetOut) {
+    const orpPacket = buildOrpComputePacket({
+      repoRoot: context.raw.repo?.rootPath || process.cwd(),
+      repoGit: context.raw.repo?.git,
+      decision: context.decision,
+      packet: context.packet,
+      dispatchResult,
+      resultBundle,
+      impactRead,
+      gateResults: [gateResult],
+      artifactRoot: context.raw.orp?.artifactRoot,
+      boardId: context.raw.orp?.boardId,
+      problemId: context.raw.orp?.problemId,
+      extraPaths: options.receiptOut ? [path.resolve(options.receiptOut)] : [],
+      stateNote: impactRead.summary,
+    });
+    await writeJson(options.packetOut, orpPacket);
+    payload.orp_packet_path = path.resolve(options.packetOut);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(`${executionReceipt.status}: ${impactRead.summary}`);
+  }
+
+  if (executionReceipt.exitCode == null) {
+    return 1;
+  }
+  return executionReceipt.exitCode;
+}
+
+export async function runComputeCli(argv = process.argv.slice(2)) {
+  let options;
+  try {
+    options = parseArgs(argv);
+  } catch (error) {
+    console.error(String(error.message || error));
+    printHelp();
+    return 1;
+  }
+
+  if (options.help || !options.command) {
+    printHelp();
+    return 0;
+  }
+
+  try {
+    if (options.command === "decide") {
+      return await runDecide(options);
+    }
+    if (options.command === "run-local") {
+      return await runLocal(options);
+    }
+    throw new Error(`unknown compute command: ${options.command}`);
+  } catch (error) {
+    if (options.json) {
+      console.log(JSON.stringify({ ok: false, error: String(error.message || error) }, null, 2));
+    } else {
+      console.error(String(error.message || error));
+    }
+    return 1;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const code = await runComputeCli(process.argv.slice(2));
+  process.exit(code == null ? 0 : code);
+}

package/bin/orp.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 
 const path = require("path");
+const { pathToFileURL } = require("url");
 const { spawnSync } = require("child_process");
 
 const cliPath = path.resolve(__dirname, "..", "cli", "orp.py");
+const computeCliUrl = pathToFileURL(path.resolve(__dirname, "orp-compute.mjs")).href;
 const argv = process.argv.slice(2);
 
 const candidates = [];
@@ -15,24 +17,65 @@ if (process.platform === "win32") {
 }
 candidates.push("python3", "python");
 
-let lastErr = null;
+function isTopLevelHelp(args) {
+  return args.length === 0 || args.includes("-h") || args.includes("--help");
+}
+
+async function runCompute(args) {
+  const mod = await import(computeCliUrl);
+  const code = await mod.runComputeCli(args);
+  process.exit(code == null ? 0 : code);
+}
 
-for (const py of candidates) {
-  const args = py === "py" ? ["-3", cliPath, ...argv] : [cliPath, ...argv];
-  const result = spawnSync(py, args, { stdio: "inherit" });
-  if (!result.error) {
-    process.exit(result.status == null ? 1 : result.status);
+async function main() {
+  if (argv[0] === "compute") {
+    await runCompute(argv.slice(1));
+    return;
   }
-  if (result.error && result.error.code === "ENOENT") {
-    continue;
+
+  const captureOutput = isTopLevelHelp(argv);
+  let lastErr = null;
+
+  for (const py of candidates) {
+    const args = py === "py" ? ["-3", cliPath, ...argv] : [cliPath, ...argv];
+    const result = spawnSync(
+      py,
+      args,
+      captureOutput
+        ? { encoding: "utf8" }
+        : { stdio: "inherit" },
+    );
+
+    if (!result.error) {
+      if (captureOutput) {
+        if (result.stdout) {
+          process.stdout.write(result.stdout);
+        }
+        if (result.stderr) {
+          process.stderr.write(result.stderr);
+        }
+        if (result.status === 0) {
+          process.stdout.write("\nAdditional wrapper surface:\n  orp compute -h\n");
+        }
+      }
+      process.exit(result.status == null ? 1 : result.status);
+    }
+
+    if (result.error && result.error.code === "ENOENT") {
+      continue;
+    }
+    lastErr = result.error;
   }
-  lastErr = result.error;
-}
 
-console.error("ORP CLI requires Python 3 on PATH.");
-console.error("Tried: " + candidates.join(", "));
-if (lastErr) {
-  console.error(String(lastErr));
+  console.error("ORP CLI requires Python 3 on PATH.");
+  console.error("Tried: " + candidates.join(", "));
+  if (lastErr) {
+    console.error(String(lastErr));
+  }
+  process.exit(1);
 }
-process.exit(1);
 
+main().catch((error) => {
+  console.error(String(error && error.stack ? error.stack : error));
+  process.exit(1);
+});