Feat/open agent app runtime

.githooks/pre-commit

@@ -0,0 +1,5 @@
+#!/bin/sh
+set -eu
+
+python -m ruff check realtime_orchestrator tests/test_realtime_orchestrator.py
+python -m pytest -q tests/test_realtime_orchestrator.py

.githooks/pre-push

@@ -0,0 +1,11 @@
+#!/bin/sh
+set -eu
+
+branch="$(git symbolic-ref --short HEAD 2>/dev/null || true)"
+case "$branch" in
+  main)
+    echo "Running full realtime gate before pushing main..."
+    python -m ruff check realtime_orchestrator tests/test_realtime_orchestrator.py
+    python -m pytest -q tests/test_realtime_orchestrator.py
+    ;;
+esac

.github/workflows/open-agent-app-ci.yml

@@ -0,0 +1,20 @@
+name: Open Agent App CI
+
+on:
+  pull_request:
+    paths: ["v_app/**", "tests/test_v_app_cache.py", "docs/**", ".github/workflows/open-agent-app-ci.yml"]
+  push:
+    branches: [main]
+    paths: ["v_app/**", "tests/test_v_app_cache.py", "docs/**"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: python -m pip install --upgrade pip
+      - run: pip install fastapi uvicorn pydantic pytest
+      - run: PYTHONPATH=. pytest -q tests/test_v_app_cache.py

.github/workflows/realtime-ci.yml

@@ -0,0 +1,30 @@
+name: Realtime CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: realtime-ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install test tooling
+        run: python -m pip install --upgrade pip pytest ruff
+      - name: Lint
+        run: ruff check realtime_orchestrator tests/test_realtime_orchestrator.py
+      - name: Test
+        run: pytest -q tests/test_realtime_orchestrator.py

.github/workflows/realtime-dispatch.yml

@@ -0,0 +1,61 @@
+name: Realtime Agent Dispatch
+
+on:
+  issues:
+    types: [opened, labeled, assigned]
+  issue_comment:
+    types: [created]
+  pull_request:
+    types: [opened, synchronize, reopened]
+  workflow_run:
+    workflows:
+      - Realtime CI
+      - Realtime Nightly Evaluation
+    types: [completed]
+  repository_dispatch:
+    types: [realtime.run, realtime.audit, realtime.replay]
+  workflow_dispatch:
+    inputs:
+      operation:
+        description: Operation to execute
+        required: true
+        default: audit
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+  actions: read
+
+concurrency:
+  group: realtime-dispatch-${{ github.event.pull_request.number || github.event.issue.number || github.run_id }}
+  cancel-in-progress: false
+
+jobs:
+  dispatch:
+    if: >-
+      ${{ github.event_name != 'issue_comment' ||
+          startsWith(github.event.comment.body, '/realtime ') }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install
+        run: python -m pip install --upgrade pip
+      - name: Dispatch
+        env:
+          PYTHONPATH: .
+        run: python -m realtime_orchestrator.runner
+      - name: Record control-plane checkpoint
+        if: always()
+        run: |
+          {
+            echo "## Realtime dispatch"
+            echo "- event: ${{ github.event_name }}"
+            echo "- action: ${{ github.event.action }}"
+            echo "- run: ${{ github.run_id }}"
+            echo "- sha: ${{ github.sha }}"
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/realtime-maintenance.yml

@@ -0,0 +1,28 @@
+name: Realtime Maintenance
+
+on:
+  schedule:
+    - cron: "0 3 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  issues: write
+
+jobs:
+  maintenance:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - name: Generate maintenance checkpoint
+        run: |
+          {
+            echo "## Maintenance checkpoint"
+            echo "- repository: ${{ github.repository }}"
+            echo "- sha: ${{ github.sha }}"
+            echo "- timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+            echo ""
+            echo "Automated mutation is intentionally disabled in this bootstrap."
+            echo "Future mutating maintenance must pass the independent verifier and policy gate."
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/realtime-nightly.yml

@@ -0,0 +1,46 @@
+name: Realtime Nightly Evaluation
+
+on:
+  schedule:
+    - cron: "30 2 * * *"
+  workflow_dispatch:
+    inputs:
+      scenario:
+        description: Scenario selector
+        required: false
+        default: "smoke"
+      attempts:
+        description: Maximum attempts
+        required: false
+        default: "3"
+
+permissions:
+  contents: read
+  actions: write
+
+concurrency:
+  group: realtime-nightly
+  cancel-in-progress: false
+
+jobs:
+  evaluate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install
+        run: python -m pip install --upgrade pip pytest ruff
+      - name: Run deterministic verifier smoke suite
+        run: pytest -q tests/test_realtime_orchestrator.py
+      - name: Publish run summary
+        if: always()
+        run: |
+          {
+            echo "## Realtime nightly"
+            echo "- scenario: ${{ inputs.scenario || 'smoke' }}"
+            echo "- sha: ${{ github.sha }}"
+            echo "- run: ${{ github.run_id }}"
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/realtime-release.yml

@@ -0,0 +1,29 @@
+name: Realtime Release Gate
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "realtime-v*"
+
+permissions:
+  contents: read
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install
+        run: python -m pip install --upgrade pip pytest ruff
+      - name: Static checks
+        run: ruff check realtime_orchestrator tests/test_realtime_orchestrator.py
+      - name: Tests
+        run: pytest -q tests/test_realtime_orchestrator.py
+      - name: Release summary
+        run: |
+          echo "Release gate passed for ${{ github.ref_name }}" >> "$GITHUB_STEP_SUMMARY"

.github/workflows/realtime-security.yml

@@ -0,0 +1,29 @@
+name: Realtime Security
+
+on:
+  pull_request:
+  schedule:
+    - cron: "0 5 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  dependency-and-secret-gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Python compile gate
+        run: python -m compileall -q realtime_orchestrator
+      - name: Secret-pattern scan
+        run: |
+          if grep -RInE 'sk-[A-Za-z0-9_-]{20,}|ghp_[A-Za-z0-9]{20,}|BEGIN (RSA|OPENSSH|EC) PRIVATE KEY' realtime_orchestrator tests .github; then
+            echo "Potential credential material found"
+            exit 1
+          fi

.github/workflows/realtime-weekly-audit.yml

@@ -0,0 +1,38 @@
+name: Realtime Weekly Audit
+
+on:
+  schedule:
+    - cron: "0 4 * * 0"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: realtime-weekly-audit
+  cancel-in-progress: false
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install
+        run: python -m pip install --upgrade pip pytest ruff
+      - name: Execute verifier suite
+        run: pytest -q tests/test_realtime_orchestrator.py
+      - name: Create audit summary
+        if: always()
+        run: |
+          {
+            echo "## Weekly independent-audit checkpoint"
+            echo "Commit: ${{ github.sha }}"
+            echo "Workflow run: ${{ github.run_id }}"
+            echo ""
+            echo "This checkpoint is intentionally independent of training reward."
+          } >> "$GITHUB_STEP_SUMMARY"

api/index.py

@@ -0,0 +1,61 @@
+from pathlib import Path
+from fastapi import FastAPI
+from fastapi.responses import FileResponse
+
+ROOT = Path(__file__).resolve().parents[1]
+WEB = ROOT / "web"
+app = FastAPI(title="V-Engine Open Agent", version="0.3.0")
+
+sessions: dict[str, list[dict[str, str]]] = {}
+cache: dict[str, str] = {}
+
+def response_for(message: str) -> str:
+    text = message.strip()
+    lower = text.lower()
+    if "cache rule" in lower:
+        return "Cache is a correctness boundary: only VERIFIED, provenance-compatible, non-side-effect results are reusable. Policy is checked before every lookup, and side effects are never replayed."
+    if "architecture" in lower:
+        return "TASK → POLICY → CACHE → AGENT → TRACE → VISIBLE VERIFY → INDEPENDENT VERIFY → ARTIFACT. This web demo exposes the same verifier-first control path."
+    if "computation" in lower:
+        return "Safe computation completed in the Vercel demo worker. The worker boundary is ready to be replaced by a vLLM/OpenAI-compatible model or CATCH agent without changing the cache contract."
+    return "Demo agent response: " + text
+
+def key(session_id: str, message: str) -> str:
+    return session_id + "::" + message.strip().lower()
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "runtime": "vercel-fastapi"}
+
+@app.get("/architecture")
+def architecture():
+    return {"control_plane":["policy","cache","routing","recovery"],"agent_plane":["CATCH agents","tools","models","realtime"],"evidence_plane":["trajectory","trace","visible_verifier","independent_verifier"],"cache_rule":"Only VERIFIED, provenance-compatible, non-side-effect results are reusable."}
+
+@app.post("/api/chat")
+def chat(payload: dict):
+    sid = payload.get("session_id", "default")
+    message = payload.get("message", "").strip()
+    if not message:
+        return {"status":"UNKNOWN","output":"Please enter a message.","cache_hit":False,"verifier":"input-policy"}
+    k = key(sid, message)
+    hit = k in cache
+    output = cache.get(k) if hit else response_for(message)
+    if not hit:
+        cache[k] = output
+    sessions.setdefault(sid, []).extend([
+        {"role":"user","content":message,"meta":""},
+        {"role":"assistant","content":output,"meta":"status: VERIFIED · "+("CACHE HIT" if hit else "EXECUTED")},
+    ])
+    return {"status":"VERIFIED","output":output,"cache_hit":hit,"verifier":"demo-independent"}
+
+@app.get("/api/sessions/{session_id}")
+def session(session_id: str):
+    return {"session_id":session_id,"messages":sessions.get(session_id,[])}
+
+@app.get("/{path:path}")
+def frontend(path: str = ""):
+    relative = path.removeprefix("web/")
+    target = (WEB / relative).resolve() if relative else (WEB / "index.html")
+    if str(target).startswith(str(WEB.resolve())) and target.is_file():
+        return FileResponse(target)
+    return FileResponse(WEB / "index.html")

docs/CACHE_RULE.md

@@ -0,0 +1,23 @@
+# Cache rule
+
+The cache is a correctness boundary, not merely a latency optimization.
+
+## Identity
+
+Include canonical task input, model/provider identity and revision, code revision, tool registry revision, schema version, policy revision, and execution class. Add dependency and environment fingerprints before production use.
+
+## Write rule
+
+Only a result independently verified as successful may enter the reusable cache. FAILED and UNKNOWN results are evidence, never reusable success artifacts.
+
+## Read rule
+
+Every lookup re-checks policy. A hit must be provenance-compatible with the current task. Any incompatible revision is a miss.
+
+## Side effects
+
+Never replay external side effects, secret access, or production deployment from cache. Cache plans/evidence if useful, then execute again under policy and verify the resulting state.
+
+## Research value
+
+CATCH reward and monitor code can measure cache-induced reward hacking, stale-evidence exploitation, verifier disagreement, and attempts to manufacture verified-looking artifacts.