@crvouga/mockingbird-service-hermes 0.1.0

package/oracle/sources.py

@@ -0,0 +1,71 @@
+"""Exact-source loading without importing gateway startup or inference."""
+import ast
+import hashlib
+import json
+import sys
+import types
+from pathlib import Path
+
+LOCK = json.loads(Path(__file__).with_name("source-lock.json").read_text())
+
+
+def verify(directory):
+    directory = Path(directory)
+    for name, expected in LOCK["sources"].items():
+        data = (directory / name).read_bytes()
+        if hashlib.sha256(data).hexdigest() != expected["sha256"]:
+            raise ValueError(f"Pinned source hash mismatch: {name}")
+    return LOCK
+
+
+def definitions(path, roots, namespace):
+    """Compile original AST nodes and their local definition dependencies.
+
+    Imports are explicitly supplied by the harness. No function body is rewritten;
+    future annotations avoid loading unrelated annotation-only dependencies.
+    Return selected names so provenance can disclose the exact loading boundary.
+    """
+    tree = ast.parse(Path(path).read_text(), filename=str(path))
+    definitions_by_name = {}
+    for node in tree.body:
+        candidates = node.body if isinstance(node, ast.ClassDef) and node.name == "APIServerAdapter" else [node]
+        for candidate in candidates:
+            if isinstance(candidate, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                definitions_by_name[candidate.name] = candidate
+            elif isinstance(candidate, (ast.Assign, ast.AnnAssign)):
+                targets = candidate.targets if isinstance(candidate, ast.Assign) else [candidate.target]
+                for target in targets:
+                    if isinstance(target, ast.Name):
+                        definitions_by_name[target.id] = candidate
+    selected = set()
+    pending = list(roots)
+    while pending:
+        name = pending.pop()
+        if name in selected or name in namespace:
+            continue
+        node = definitions_by_name.get(name)
+        if node is None:
+            if name in roots:
+                raise ValueError(f"Missing pinned definition: {name}")
+            continue
+        selected.add(name)
+        pending.extend(n.id for n in ast.walk(node) if isinstance(n, ast.Name) and isinstance(n.ctx, ast.Load))
+    nodes = {id(definitions_by_name[name]): definitions_by_name[name] for name in selected}
+    module = ast.Module(body=[ast.ImportFrom(module="__future__", names=[ast.alias(name="annotations")], level=0), *sorted(nodes.values(), key=lambda node: node.lineno)], type_ignores=[])
+    ast.fix_missing_locations(module)
+    exec(compile(module, str(path), "exec"), namespace)
+    return sorted(selected)
+
+
+def load_module(path, name):
+    module = types.ModuleType(name)
+    module.__file__ = str(path)
+    sys.modules[name] = module
+    exec(compile(Path(path).read_text(), str(path), "exec"), module.__dict__)
+    return module
+
+
+if __name__ == "__main__":
+    import sys
+    manifest = verify(sys.argv[1])
+    print(json.dumps({"commit": manifest["commit"], "verified_files": len(manifest["sources"])}))

package/oracle/test_sources.py

@@ -0,0 +1,50 @@
+"""Dependency-free checks: never start upstream code, services or databases."""
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+from sources import definitions, verify
+
+
+class SourceLoadingTests(unittest.TestCase):
+    def test_transitive_definitions_preserve_behavior_without_running_startup(self):
+        fixture = '''
+LIMIT = 3
+raise RuntimeError("unrelated gateway startup must not execute")
+def helper(value):
+    return value + LIMIT
+def handler(value):
+    return helper(value) if value else "invalid"
+'''
+        namespace = {}
+        with patch.object(Path, "read_text", return_value=fixture):
+            names = definitions("fixture.py", ["handler"], namespace)
+        self.assertEqual(names, ["LIMIT", "handler", "helper"])
+        self.assertEqual(namespace["handler"](4), 7)
+        self.assertEqual(namespace["handler"](0), "invalid")
+
+    def test_missing_required_definition_fails_closed(self):
+        with patch.object(Path, "read_text", return_value="def different(): pass"):
+            with self.assertRaisesRegex(ValueError, "Missing pinned definition: handler"):
+                definitions("fixture.py", ["handler"], {})
+
+    def test_source_tampering_fails_before_execution(self):
+        with patch.object(Path, "read_bytes", return_value=b"changed source"):
+            with self.assertRaisesRegex(ValueError, "Pinned source hash mismatch"):
+                verify("unread-fixture")
+
+    def test_selected_adapter_method_keeps_staticmethod_binding(self):
+        fixture = '''
+class APIServerAdapter:
+    @staticmethod
+    def header(request):
+        return request["value"]
+'''
+        namespace = {}
+        with patch.object(Path, "read_text", return_value=fixture):
+            definitions("fixture.py", ["header"], namespace)
+        adapter = type("Adapter", (), {"header": namespace["header"]})
+        self.assertEqual(adapter().header({"value": "synthetic"}), "synthetic")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/package.json

@@ -0,0 +1,117 @@
+{
+  "name": "@crvouga/mockingbird-service-hermes",
+  "version": "0.1.0",
+  "description": "Hermes peer-run API mock with portable scripted lifecycle controls.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "API_EVIDENCE.md",
+    "SUPPORT.md",
+    "oracle",
+    "evidence",
+    "DISCOVERY.md",
+    "openapi.yaml"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "bin": {
+    "mockingbird-hermes": "./dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crvouga/mockingbird.git",
+    "directory": "packages/service/hermes"
+  },
+  "homepage": "https://github.com/crvouga/mockingbird/tree/main/packages/service/hermes#readme",
+  "keywords": [
+    "mockingbird",
+    "service",
+    "hermes",
+    "peer-runs"
+  ],
+  "mockingbird": {
+    "runtime": "portable",
+    "entries": {
+      "server": "node",
+      "cli": "node"
+    },
+    "layer": "service",
+    "category": "infrastructure",
+    "displayName": "Hermes Agent",
+    "vendor": {
+      "website": "https://hermes-agent.nousresearch.com",
+      "docs": "https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server/",
+      "description": "Hermes Agent exposes asynchronous public peer-run APIs."
+    },
+    "status": "wip",
+    "playground": {
+      "operation": "RunCreate"
+    },
+    "parity": "Pinned Hermes run lifecycle and recovery",
+    "discovery": {
+      "guide": "DISCOVERY.md",
+      "behavior": "README.md",
+      "capabilities": "SUPPORT.md",
+      "contract": "openapi.yaml",
+      "types": "dist/index.d.ts",
+      "oracle": {
+        "kind": "Live vendor API or sandbox",
+        "command": "bun run parity:service -- hermes",
+        "note": "Run from a Mockingbird checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2."
+      },
+      "introspection": [
+        "GET /__admin/health",
+        "GET /__admin",
+        "GET /__admin/state",
+        "GET /__admin/requests",
+        "GET /__admin/metrics",
+        "GET /__admin/faults/presets",
+        "GET /__admin/ui"
+      ],
+      "reporting": "https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md"
+    }
+  },
+  "scripts": {
+    "generate": "bun ../../openapi/codegen/dist/cli.js",
+    "generate:check": "bun ../../openapi/codegen/dist/cli.js --check",
+    "openapi:check": "bun ../../openapi/codegen/dist/cli.js --validate",
+    "build": "bun ../../../scripts/bundle-service.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "biome check .",
+    "test": "bun test",
+    "portability": "bun ../../../scripts/portability.ts",
+    "pack:check": "bun ../../../scripts/pack-check.ts"
+  },
+  "dependencies": {
+    "@crvouga/mockingbird-service-sqlite": "2.1.1",
+    "hono": "4.11.9"
+  },
+  "devDependencies": {
+    "@crvouga/mockingbird-parity": "0.0.0-development",
+    "@crvouga/mockingbird-testing": "0.1.0",
+    "@crvouga/mockingbird-openapi-codegen": "0.1.0",
+    "@crvouga/mockingbird-core": "0.0.0-development",
+    "@crvouga/mockingbird-sqlite": "0.0.0-development",
+    "@crvouga/mockingbird-openapi": "0.0.0-development",
+    "@crvouga/mockingbird-service": "0.0.0-development",
+    "@crvouga/mockingbird-adapter-node": "0.0.0-development"
+  }
+}