diff --git a/scripts/corporate_pilot.py b/scripts/corporate_pilot.py new file mode 100644 index 00000000..4fc82f3f --- /dev/null +++ b/scripts/corporate_pilot.py @@ -0,0 +1,98 @@ +#!/usr/bin/env python3 +"""Explicit local integration pilot. Requires disposable migrated PostgreSQL :55441.""" +import json +import os +from pathlib import Path +import secrets +import subprocess +import sys +import time +import urllib.request +import corporate_runtime as r + + +def main(): + root = Path(__file__).resolve().parent.parent + scratch = Path(os.environ['CORPORATE_PILOT_DIR']).resolve() + if not str(scratch).startswith('/opt/data/cache/scratch/'): + raise ValueError('Scratch pilot output required') + scratch.mkdir(parents=True, exist_ok=True, mode=0o700) + env = dict(os.environ, CORPORATE_API_KEY=secrets.token_hex(32), CORPORATE_QA_API_KEY=secrets.token_hex(32), + CORPORATE_TEST_DATABASE_URL='postgresql://hermes@127.0.0.1:55441/corporate_test') + server = subprocess.Popen(['node', str(root/'scripts/corporate_pilot_server.cjs')], env=env, stdout=subprocess.PIPE, stderr=subprocess.STDOUT) + base = 'http://127.0.0.1:55442/api/admin/hermes' + transcript = [] + def cli(command, *args, key=None): + cmd = [sys.executable,str(root/'scripts/corporate_runtime.py'),'--api',base,'--store',str(scratch/'store')] + if key: cmd += ['--key',key] + result = subprocess.run(cmd+[command,*args],env=env,text=True,capture_output=True,timeout=90) + if result.returncode: + raise ValueError(command + ' failed: ' + result.stderr) + value = json.loads(result.stdout) + transcript.append({'command':command,'result':value}) + return value + def manifest(name, value): + path=scratch/(name+'.json');path.write_text(json.dumps(value));return str(path) + try: + for _ in range(100): + try: + req = urllib.request.Request(base+'/runtime', headers={'x-api-key':env['CORPORATE_API_KEY']}) + with urllib.request.urlopen(req,timeout=1): break + except Exception: + if server.poll() is not None: raise ValueError('Nest pilot host failed') + time.sleep(.1) + else: raise ValueError('Nest readiness timeout') + assert cli('status')['schedulesEnabled'] is False + insight=cli('ingest',manifest('research',{ + 'title':'Manual official Hermes documentation source inventory pilot','category':'TREND', + 'source':'Official Hermes documentation fetched over verified HTTPS', + 'opportunity':'Validate read-only source provenance, not a clinical or market claim', + 'impact':'LOW','recommendedAction':'Independent exact-byte inventory QA only', 'cadence':'EVENT', + 'provenance':{'method':'manual HTTPS GET + SHA256','collector':'manual CLI pilot','context':'disposable local integration, not production analytics'}, + 'fetchSources':[{'url':'https://hermes-agent.nousresearch.com/docs/llms.txt','title':'Official Hermes docs index'}] + }),'--hosts','hermes-agent.nousresearch.com',key='pilot-research') + replay=cli('replay-ingest',insight['requestDigest'],key='pilot-research') + assert replay['id']==insight['research']['id'] + roadmap=cli('roadmap',manifest('roadmap',{ + 'researchId':replay['id'],'cycleName':'Manual local pilot','month':r.now()[:7], + 'seasonalTheme':'No seasonal inference','strategicGoals':['Verify read-only evidence'], + 'plannedArticlesCount':0,'plannedRefreshesCount':0,'plannedCatalogEnrichments':0,'isActive':False, + 'goals':[{'title':'Inventory fetched official docs source','department':'CONTENT_SEO', + 'acceptanceCriteria':'Exact source byte digests match persisted provenance','metric':'source_inventory_verified'}] + }),key='pilot-roadmap') + tasks=cli('fanout',roadmap['id'],key='pilot-fanout') + assert cli('fanout',roadmap['id'],key='pilot-fanout')[0]['id']==tasks[0]['id'] + execution=cli('execute','--department','CONTENT_SEO',key='pilot-execution') + task_id=execution['taskId']; evidence=execution['evidence'] + # Executor identity cannot self-review; exercise real backend denial. + own_env=os.environ.copy() + try: + os.environ['CORPORATE_API_KEY']=env['CORPORATE_API_KEY'] + c=r.Client(base,'CORPORATE_API_KEY') + try: r.review(c,r.Store(scratch/'store'),task_id,evidence['id'],'self-review-denied') + except ValueError as e: assert '409' in str(e) + else: raise AssertionError('self-review unexpectedly allowed') + finally: + os.environ.clear();os.environ.update(own_env) + cli('qa',task_id,evidence['id'],key='pilot-independent-qa') + cli('effect',task_id,manifest('effect',{'metric':'production_engagement','availability':'UNINSTRUMENTED', + 'source':'Local pilot has no production analytics instrumentation','observedAt':r.now()}),key='pilot-effect') + cli('report',manifest('report',{'day':r.now()[:10], 'summary':'Manual local source-inventory pilot only; no publishing, deployment or measured production effect.'}),key='pilot-report') + req=urllib.request.Request(base+'/tasks/'+task_id,headers={'x-api-key':env['CORPORATE_QA_API_KEY']}) + with urllib.request.urlopen(req) as response: detail=json.load(response) + assert detail['status']=='DONE' and len(detail['effects'])==1 and len(detail['reviews'])==1 + assert detail['evidence'][0]['sha256']==evidence['sha256'] + assert detail['reviews'][0]['reviewer'] != detail['evidence'][0]['executor'] + transcript.append({'persistedReadback':{'taskId':task_id,'status':detail['status'], + 'logs':[x['step'] for x in detail['logs']], 'effects':detail['effects'], + 'sha256':evidence['sha256'],'independentSubjects':True,'selfReviewDenied':True}}) + (scratch/'transcript.json').write_text(json.dumps(transcript,indent=2)) + print(json.dumps({'status':'PASS','taskId':task_id,'artifactDigest':evidence['sha256'], + 'transcript':str(scratch/'transcript.json')})) + finally: + server.terminate() + try: server.communicate(timeout=10) + except subprocess.TimeoutExpired: server.kill();server.communicate() + + +if __name__=='__main__': main() diff --git a/scripts/corporate_pilot_server.cjs b/scripts/corporate_pilot_server.cjs new file mode 100644 index 00000000..066d82e2 --- /dev/null +++ b/scripts/corporate_pilot_server.cjs @@ -0,0 +1,24 @@ +// Disposable loopback Nest feature host; test-auth only, never runtime deployment. +process.env.TS_NODE_PROJECT = require('path').resolve(__dirname, '../backend/tsconfig.json'); +require('../backend/node_modules/ts-node/register/transpile-only'); +const { Test } = require('../backend/node_modules/@nestjs/testing'); +const { PrismaClient } = require('../backend/node_modules/@prisma/client'); +const { CorporateController } = require('../backend/src/admin/hermes/corporate.controller'); +const { CorporateService } = require('../backend/src/admin/hermes/corporate.service'); +const { PrismaService } = require('../backend/src/prisma/prisma.service'); +const { ApiKeysService } = require('../backend/src/admin/api-keys.service'); +(async () => { + const u = new URL(process.env.CORPORATE_TEST_DATABASE_URL); + if (u.hostname !== '127.0.0.1' || u.port !== '55441' || u.pathname !== '/corporate_test') throw Error('disposable DB required'); + const db = new PrismaClient({datasources:{db:{url:u.href}}}); + const module = await Test.createTestingModule({controllers:[CorporateController], providers:[CorporateService, + {provide:PrismaService,useValue:db}, {provide:ApiKeysService,useValue:{validateKey:async key => { + const role = key === process.env.CORPORATE_API_KEY ? 'executor' : key === process.env.CORPORATE_QA_API_KEY ? 'reviewer' : null; + return role ? {id:'pilot-' + role,isApiKey:true,role:'Admin',scopes:['admin']} : null; + }}}]}).compile(); + const app = module.createNestApplication({logger:false}); + app.setGlobalPrefix('api'); + await app.listen(55442,'127.0.0.1'); + console.log('READY loopback test-auth Nest corporate feature'); + for (const signal of ['SIGTERM','SIGINT']) process.on(signal,async()=>{await app.close();await db.$disconnect();process.exit(0);}); +})().catch(()=>{console.error('Pilot server failed (no secrets logged)');process.exit(1);}); diff --git a/scripts/corporate_runtime.py b/scripts/corporate_runtime.py new file mode 100644 index 00000000..7b8fd635 --- /dev/null +++ b/scripts/corporate_runtime.py @@ -0,0 +1,312 @@ +#!/usr/bin/env python3 +"""Dormant manual Hermes terminal adapter. No model, scheduler or shell execution.""" +import argparse +import hashlib +import http.client +import ipaddress +import json +import os +from pathlib import Path +import re +import socket +import ssl +import sys +from datetime import datetime, timezone +from urllib.parse import urlsplit, quote +import urllib.request +import urllib.error + +MAX_BYTES = 2_000_000 + + +def canonical(value): + return json.dumps(value, sort_keys=True, separators=(',', ':'), ensure_ascii=False).encode() + + +def sha(data): + return hashlib.sha256(data).hexdigest() + + +def now(): + return datetime.now(timezone.utc).isoformat() + + +class Store: + def __init__(self, root): + self.root = Path(root).resolve() + self.root.mkdir(parents=True, exist_ok=True, mode=0o700) + + def path(self, digest): + if not re.fullmatch('[a-f0-9]{64}', digest): + raise ValueError('Invalid digest') + path = self.root / digest + if path.is_symlink(): + raise ValueError('Symlink forbidden') + return path + + def put(self, data): + digest = sha(data) + path = self.path(digest) + try: + fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600) + except FileExistsError: + self.get(digest) + else: + with os.fdopen(fd, 'wb') as f: + f.write(data) + return digest + + def get(self, digest): + data = self.path(digest).read_bytes() + if sha(data) != digest: + raise ValueError('Artifact digest mismatch') + return data + + +def source_target(url, hosts): + p = urlsplit(url) + if (p.scheme != 'https' or p.hostname not in hosts or p.username or p.password + or p.port not in (None, 443) or p.fragment): + raise ValueError('Source must be allowlisted public HTTPS on port 443') + addresses = sorted({row[4][0] for row in socket.getaddrinfo(p.hostname, 443, type=socket.SOCK_STREAM)}) + if not addresses or any(not ipaddress.ip_address(x).is_global for x in addresses): + raise ValueError('Non-public source address') + return p, addresses[0] + + +def fetch(url, hosts): + p, address = source_target(url, hosts) + # Pin resolved public address; keep hostname for TLS certificate/SNI validation. + class PinnedHTTPS(http.client.HTTPSConnection): + def connect(self): + raw = socket.create_connection((address, 443), timeout=20) + self.sock = ssl.create_default_context().wrap_socket(raw, server_hostname=p.hostname) + conn = PinnedHTTPS(p.hostname, timeout=20) + try: + conn.request('GET', p.path + ('?' + p.query if p.query else '') or '/', + headers={'User-Agent': 'Canina-Manual-Research/1.0', 'Accept-Encoding': 'identity'}) + response = conn.getresponse() + if response.status != 200: + raise ValueError('Source HTTP status ' + str(response.status) + '; redirects forbidden') + data = response.read(MAX_BYTES + 1) + if not data or len(data) > MAX_BYTES: + raise ValueError('Empty or oversized source') + return data, {'url': url, 'sha256': sha(data), 'retrievedAt': now(), + 'status': response.status, 'bytes': len(data), + 'contentType': response.getheader('Content-Type', '')} + finally: + conn.close() + + +def api_target(url, allow_stage): + p = urlsplit(url) + if p.username or p.password or p.query or p.fragment or p.path.rstrip('/') != '/api/admin/hermes': + raise ValueError('Invalid API base') + if not (p.scheme == 'http' and p.hostname == '127.0.0.1'): + if not (allow_stage and p.scheme == 'https' and p.hostname): + raise ValueError('API is loopback-only unless --allow-stage-https explicitly supplied') + return url.rstrip('/') + + +class NoRedirect(urllib.request.HTTPRedirectHandler): + def redirect_request(self, req, fp, code, msg, headers, newurl): + raise ValueError('API redirects forbidden') + + +class Client: + def __init__(self, base, credential_env, allow_stage=False): + self.base = api_target(base, allow_stage) + self.secret = os.environ.get(credential_env) + if not self.secret or '\n' in self.secret or '\r' in self.secret: + raise ValueError('Required credential environment variable missing/invalid') + # Avoid ambient cookie/netrc/proxy credentials; never follow redirects. + self.opener = urllib.request.build_opener(urllib.request.ProxyHandler({}), NoRedirect()) + + def checkpoint(self, store, key, path, body): + """Save immutable request before network mutation, enable explicit safe replay.""" + return store.put(canonical({'path': path, 'body': body, 'key': key})) + + def replay(self, store, digest): + saved = json.loads(store.get(digest)) + path = saved['path'] + if not re.fullmatch(r'tasks/[a-f0-9-]{36}/evidence', path): + raise ValueError('Only an evidence checkpoint may be replayed') + return self.call(path, saved['body'], saved['key']) + + # All requests use fixed adapter routes, not source-provided paths. + + def call(self, path, body=None, key=None): + headers = {'x-api-key': self.secret, 'Accept': 'application/json'} + if body is not None: + if not key: + raise ValueError('Explicit idempotency key required') + headers.update({'Idempotency-Key': key, 'Content-Type': 'application/json'}) + req = urllib.request.Request(self.base + '/' + path, data=canonical(body) if body is not None else None, headers=headers) + try: + with self.opener.open(req, timeout=30) as response: + value = json.load(response) + except urllib.error.HTTPError as e: + # Do not reflect response body, URL or credentials into logs. + raise ValueError('Corporate API HTTP ' + str(e.code)) from None + return value + + def research(self, research_id): + page = 1 + while True: + response = self.call('market-insights?limit=100&page=' + str(page)) + for item in response['data']: + if item['id'] == research_id: + return item + if not response['meta']['hasNextPage']: + raise ValueError('Research not found') + page += 1 + + +def operation(description): + try: + op = json.loads(description) + except (ValueError, TypeError): + raise ValueError('Structured source inventory operation required') from None + if not isinstance(op, dict) or set(op) != {'operation', 'researchId'} or op['operation'] != 'source_inventory_v1': + raise ValueError('Only source_inventory_v1 is executable') + if not isinstance(op['researchId'], str) or not op['researchId']: + raise ValueError('Research ID required') + return op + + +def inventory(task_id, research, store): + sources = [] + for source in research['sources']: + raw = store.get(source['sha256']) + sources.append({k: source[k] for k in ('url', 'sha256', 'retrievedAt')} | {'bytes': len(raw)}) + if not sources: + raise ValueError('No persisted sources') + return {'operation': 'source_inventory_v1', 'taskId': task_id, 'researchId': research['id'], + 'sources': sorted(sources, key=lambda s: (s['url'], s['sha256']))} + + +def ingest(client, store, manifest, hosts, key): + body = dict(manifest) + sources = [] + for source in body.pop('fetchSources'): + raw, receipt = fetch(source['url'], hosts) + store.put(raw) + store.put(canonical(receipt)) + sources.append({k: receipt[k] for k in ('url', 'sha256', 'retrievedAt')} | + {'title': source['title'], 'excerpt': raw.decode('utf-8', errors='replace')[:1500]}) + body['sources'] = sources + # Persist exact immutable request before HTTP so an operator can retry without refetching. + request_digest = store.put(canonical(body)) + print('Research request checkpoint: ' + request_digest, file=sys.stderr) + result = client.call('market-insights', body, key) + return {'research': result, 'requestDigest': request_digest} + + +def fanout(client, roadmap, key): + tasks = [] + for goal in roadmap['goals']: + body = {'title': goal['title'], 'department': goal['department'], 'goalId': goal['id'], + 'actionType': 'RESEARCH', 'description': json.dumps({'operation': 'source_inventory_v1', 'researchId': roadmap['researchId']})} + tasks.append(client.call('tasks', body, key + ':' + goal['id'])) + return tasks + + +def execute(client, store, department, key): + task = client.call('claims', {'department': department, 'leaseSeconds': 300}, key + ':claim')['task'] + if task is None: + return {'task': None} + # Nothing from title/description is evaluated as Python, shell, or LLM instructions. + if task['actionType'] != 'RESEARCH': + raise ValueError('Claimed task is not RESEARCH; left leased, no evidence submitted') + op = operation(task['description']) + started = now() + artifact = inventory(task['id'], client.research(op['researchId']), store) + digest = store.put(canonical(artifact)) + result = {'startedAt': started, 'finishedAt': now(), 'operation': op['operation'], + 'bytes': len(canonical(artifact)), 'sourceCount': len(artifact['sources']), 'sha256': digest} + receipt_digest = store.put(canonical(result)) + body = {'claimToken': task['claimToken'], 'artifactUri': 'urn:sha256:' + digest, 'sha256': digest, + 'summary': 'Read-only persisted source inventory; no publishing or production action', + 'tool': 'python:source_inventory_v1', 'result': json.dumps(result)} + checkpoint = client.checkpoint(store, key + ':evidence', 'tasks/' + task['id'] + '/evidence', body) + print('Evidence checkpoint: ' + checkpoint, file=sys.stderr) + evidence = client.call('tasks/' + task['id'] + '/evidence', body, key + ':evidence') + return {'taskId': task['id'], 'evidence': evidence, 'toolReceiptDigest': receipt_digest} + + +def review(client, store, task_id, evidence_id, key): + task = client.call('tasks/' + task_id) + evidence = next(e for e in task['evidence'] if e['id'] == evidence_id) + raw = store.get(evidence['sha256']) + op = operation(task['description']) + expected = inventory(task_id, client.research(op['researchId']), store) + if raw != canonical(expected) or evidence['artifactUri'] != 'urn:sha256:' + sha(raw): + raise ValueError('Exact artifact/source inventory verification failed; no pass submitted') + return client.call('tasks/' + task_id + '/reviews', { + 'evidenceId': evidence_id, 'passed': True, + 'findings': 'Reopened content-addressed bytes, recomputed exact deterministic inventory from API provenance and source bytes', + 'verification': {'artifactUri': evidence['artifactUri'], 'sha256': sha(raw), + 'method': 'independent local bytes + persisted provenance recomputation', + 'result': json.dumps({'verifiedAt': now(), 'sourceCount': len(expected['sources']), 'bytes': len(raw)})}}, key) + + +def main(): + p = argparse.ArgumentParser(description=__doc__) + p.add_argument('--api', default='http://127.0.0.1:3000/api/admin/hermes') + p.add_argument('--allow-stage-https', action='store_true') + p.add_argument('--store', required=True) + p.add_argument('--key', help='Stable operation key; retain for retries') + sub = p.add_subparsers(dest='command', required=True) + i = sub.add_parser('ingest'); i.add_argument('manifest'); i.add_argument('--hosts', required=True) + i = sub.add_parser('replay-ingest'); i.add_argument('request_digest') + i = sub.add_parser('replay-evidence'); i.add_argument('checkpoint_digest') + i = sub.add_parser('roadmap'); i.add_argument('manifest') + i = sub.add_parser('fanout'); i.add_argument('roadmap_id') + i = sub.add_parser('execute'); i.add_argument('--department', required=True) + i = sub.add_parser('qa'); i.add_argument('task_id'); i.add_argument('evidence_id') + i = sub.add_parser('effect'); i.add_argument('task_id'); i.add_argument('manifest') + i = sub.add_parser('report'); i.add_argument('manifest') + sub.add_parser('status') + a = p.parse_args() + if a.command != 'status' and not a.key: + p.error('--key required for mutations') + c = Client(a.api, 'CORPORATE_QA_API_KEY' if a.command == 'qa' else 'CORPORATE_API_KEY', a.allow_stage_https) + s = Store(a.store) + load = lambda: json.loads(Path(a.manifest).read_text()) + if a.command == 'ingest': result = ingest(c, s, load(), set(a.hosts.split(',')), a.key) + elif a.command == 'replay-ingest': result = c.call('market-insights', json.loads(s.get(a.request_digest)), a.key) + elif a.command == 'replay-evidence': result = c.replay(s, a.checkpoint_digest) + elif a.command == 'roadmap': + body = load() + if body.get('isActive') is not False: raise ValueError('Manual roadmap must explicitly be inactive') + result = c.call('monthly-roadmap', body, a.key) + elif a.command == 'fanout': + page = 1 + while True: + collection = c.call('monthly-roadmap?limit=100&page=' + str(page)) + road = next((x for x in collection['data'] if x['id'] == a.roadmap_id), None) + if road: break + if not collection['meta']['hasNextPage']: raise ValueError('Roadmap not found') + page += 1 + result = fanout(c, road, a.key) + elif a.command == 'execute': result = execute(c, s, a.department, a.key) + elif a.command == 'qa': result = review(c, s, a.task_id, a.evidence_id, a.key) + elif a.command == 'effect': result = c.call('tasks/' + a.task_id + '/effects', load(), a.key) + elif a.command == 'report': result = c.call('reports', load(), a.key) + else: result = c.call('runtime') + # Claim tokens may appear inside raw tasks: redact capability material from stdout. + def clean(v): + if isinstance(v, dict): return {k: clean(x) for k, x in v.items() if k != 'claimToken'} + if isinstance(v, list): return [clean(x) for x in v] + return v + print(json.dumps(clean(result), ensure_ascii=False)) + + +if __name__ == '__main__': + try: + main() + except Exception as error: + # Only known validation/status messages; transport exceptions can contain secrets. + print(str(error) if isinstance(error, ValueError) and not isinstance(error, json.JSONDecodeError) + else 'Operation failed; inspect local store/API safely (no credentials logged)', file=sys.stderr) + sys.exit(1) diff --git a/scripts/corporate_runtime_test.py b/scripts/corporate_runtime_test.py new file mode 100644 index 00000000..3138834f --- /dev/null +++ b/scripts/corporate_runtime_test.py @@ -0,0 +1,48 @@ +import importlib.util +import pathlib +import tempfile +import unittest + +spec = importlib.util.spec_from_file_location('runtime', pathlib.Path(__file__).with_name('corporate_runtime.py')) +r = importlib.util.module_from_spec(spec) +spec.loader.exec_module(r) + +class Safety(unittest.TestCase): + def test_urls_fail_closed(self): + for url in ['http://example.com/', 'https://localhost/', 'https://127.0.0.1/', 'https://example.com:444/', 'https://user:pass@example.com/', 'file:///etc/passwd']: + with self.subTest(url=url), self.assertRaises(ValueError): + r.source_target(url, {'example.com'}) + def test_only_exact_operation(self): + for desc in ['rm -rf /', '{"operation":"publish"}', '{"operation":"source_inventory_v1","researchId":"x","command":"id"}']: + with self.assertRaises(ValueError): + r.operation(desc) + def test_store_digest_tamper(self): + with tempfile.TemporaryDirectory() as tmp: + store = r.Store(tmp) + digest = store.put(b'actual bytes') + self.assertEqual(store.get(digest), b'actual bytes') + (pathlib.Path(tmp) / digest).write_bytes(b'changed') + with self.assertRaises(ValueError): store.get(digest) + def test_artifact_recomputed(self): + research = {'id':'research', 'sources':[{'url':'https://example.com/', 'sha256':r.sha(b'hello'), 'retrievedAt':'now'}]} + with tempfile.TemporaryDirectory() as tmp: + store = r.Store(tmp); store.put(b'hello') + artifact = r.inventory('task', research, store) + self.assertEqual(artifact['sources'][0]['bytes'],5) + self.assertEqual(artifact, r.inventory('task',research,store)) + def test_checkpoint_replays_exact_receipt(self): + client = object.__new__(r.Client) + calls = [] + client.call = lambda path, body, key: calls.append((path, body, key)) or {'id': 'persisted'} + with tempfile.TemporaryDirectory() as tmp: + store = r.Store(tmp) + path = 'tasks/618a6800-d241-41e2-b093-969164c83cfa/evidence' + digest = client.checkpoint(store, 'stable-key', path, {'result': 'original timestamp'}) + self.assertEqual(client.replay(store, digest), {'id': 'persisted'}) + self.assertEqual(calls, [(path, {'result':'original timestamp'}, 'stable-key')]) + def test_api_target(self): + with self.assertRaises(ValueError): r.api_target('http://example.com/api/admin/hermes',False) + with self.assertRaises(ValueError): r.api_target('https://example.com/api/admin/hermes',False) + self.assertEqual(r.api_target('http://127.0.0.1:1234/api/admin/hermes',False),'http://127.0.0.1:1234/api/admin/hermes') + +if __name__ == '__main__': unittest.main() diff --git a/specs/corporate-runtime/README.md b/specs/corporate-runtime/README.md new file mode 100644 index 00000000..4cf068d5 --- /dev/null +++ b/specs/corporate-runtime/README.md @@ -0,0 +1,30 @@ +# Manual Hermes terminal adapter (dormant) + +Python 3.9+ stdlib; no install or runtime configuration. Run explicitly from Hermes's terminal tool or an operator terminal: + +``` +python3 scripts/corporate_runtime.py --store /private/corporate-artifacts status +python3 scripts/corporate_runtime.py --store /private/corporate-artifacts --key research-unique ingest research.json --hosts hermes-agent.nousresearch.com +python3 scripts/corporate_runtime.py --store /private/corporate-artifacts --key research-unique replay-ingest REQUEST_DIGEST +python3 scripts/corporate_runtime.py --store /private/corporate-artifacts --key roadmap-unique roadmap roadmap.json +python3 scripts/corporate_runtime.py --store /private/corporate-artifacts --key fanout-unique fanout ROADMAP_UUID +python3 scripts/corporate_runtime.py --store /private/corporate-artifacts --key execution-unique execute --department CONTENT_SEO +python3 scripts/corporate_runtime.py --store /private/corporate-artifacts --key unused-required replay-evidence CHECKPOINT_DIGEST +python3 scripts/corporate_runtime.py --store /private/corporate-artifacts --key review-unique qa TASK_UUID EVIDENCE_UUID +python3 scripts/corporate_runtime.py --store /private/corporate-artifacts --key effect-unique effect TASK_UUID effect.json +python3 scripts/corporate_runtime.py --store /private/corporate-artifacts --key report-unique report report.json +``` + +Credentials must already be provisioned securely in environment: CORPORATE_API_KEY for execution/operator; CORPORATE_QA_API_KEY for QA under a distinct authenticated subject. Do not paste secrets into chat, command arguments, manifests or source. QA command reads only QA env. Backend rejects self-review. Private store (directory 0700/files 0600) includes lease-bearing replay checkpoint; transfer only source/artifact bytes required by a reviewer securely. Avoid shared writable or symlinked stores. No credentials are stored in the artifact store. + +Default API http://127.0.0.1:3000/api/admin/hermes. An authorized stage endpoint requires both `--api https://STAGE/api/admin/hermes` and explicit `--allow-stage-https`; this is not a production-target detector or authorization to use production. No gateway/config/cron/plugin modifications. Do not schedule this adapter. No automatic retries. + +Research JSON: API market-insights fields except sources, replaced by fetchSources `[ {"url":"https://...","title":"..."} ]`; provenance and interpretation are attributed operator text, not automatically validated scientific claims. Hash/excerpt/retrievedAt are obtained from actual fetched bytes. Source text is untrusted inert data. Only public allowlisted HTTPS hosts, pinned IP/TLS hostname verification, no redirect/proxy, port443, 2MB cap, bounded timeouts. Downloaded excerpt may be raw HTML/index text; adapter does not invent research conclusions. Keep source set small (API 1..30). + +Roadmap JSON follows API contract, must set isActive:false; goals should target source_inventory_v1 research acceptance. Fanout creates one deterministic goal-linked RESEARCH task per goal, description exactly `{"operation":"source_inventory_v1","researchId":"UUID"}`. No other operation, prompt execution or arbitrary commands supported. Dedicated department/queue recommended: claim API cannot filter actionType/goal, so unsupported claimed task is rejected locally and remains leased until 300s expiry; adapter never marks it successful. Never re-use a claim operation key for a new execution attempt. + +Retain mutation keys. On ingest network uncertainty, replay exact saved request via emitted request digest with original key (do not refetch/re-ingest with same key: retrieval timestamp changes). On evidence uncertainty replay emitted checkpoint; it carries original claim/evidence key, bytes and timing, so no fabricated new receipt. Re-running execute with same claim key after submission is NOT recovery; use replay-evidence. Roadmap/effect/report require unchanged manifests for retry. Fanout uses stable goal keys, safely resumes partial fanout. API conflict fails closed. + +QA reopens exact original source bytes and content-addressed artifact, recomputes inventory using persisted API provenance, then posts verification for exact evidence ID/digest/URI. Does not prove clinical validity, network source immutability or independent human review. Tampered/missing bytes fail without QA submission; backend permits manual explicit rejection via contract, adapter has no automatic rejection command. Effects follow API availability semantics; do not use zero as unavailable. Report summary is attributed operator text; snapshot is server-built from persisted records. + +See scripts/corporate_pilot.py for executable manifest examples and disposable test-auth Nest host. Pilot requires local private backend node_modules with ts-node/Prisma generated from current schema, migrated corporate_test on loopback :55441, and CORPORATE_PILOT_DIR under scratch; it spawns/stops its own feature host on :55442, never the full production app. Run once per empty disposable DB (daily report day is unique). Unit checks: `python3 scripts/corporate_runtime_test.py`. No cron or Hermes CLI installed/configured by these scripts. diff --git a/specs/corporate-runtime/pilot-receipt.json b/specs/corporate-runtime/pilot-receipt.json new file mode 100644 index 00000000..05db4c2d --- /dev/null +++ b/specs/corporate-runtime/pilot-receipt.json @@ -0,0 +1,30 @@ +{ + "persistedReadback": { + "taskId": "618a6800-d241-41e2-b093-969164c83cfa", + "status": "DONE", + "logs": [ + "CREATED", + "CLAIMED", + "EVIDENCE_SUBMITTED", + "QA_PASSED", + "EFFECT_RECORDED" + ], + "effects": [ + { + "id": "3c460ee4-9fb5-45e9-845f-f00abde2a796", + "taskId": "618a6800-d241-41e2-b093-969164c83cfa", + "metric": "production_engagement", + "availability": "UNINSTRUMENTED", + "baseline": null, + "observed": null, + "source": "Local pilot has no production analytics instrumentation", + "observedAt": "2026-10-28T12:21:29.732Z", + "recordedBy": "apikey:pilot-executor", + "createdAt": "2026-10-28T12:21:30.966Z" + } + ], + "sha256": "cd8527d3e9b2812e15b60af0a80bba3255a52d739ec431dab1b6fa296e74d2b2", + "independentSubjects": true, + "selfReviewDenied": true + } +} \ No newline at end of file diff --git a/specs/corporate-runtime/plan.md b/specs/corporate-runtime/plan.md new file mode 100644 index 00000000..0dc31f92 --- /dev/null +++ b/specs/corporate-runtime/plan.md @@ -0,0 +1,4 @@ +# Plan +Use Python stdlib explicit subcommands as a manual Hermes terminal adapter, not a model subprocess or background agent. API contract specs/corporate-backend/api.md; existing JwtAuthGuard/RolesGuard remain unchanged. Content-addressed private store outside repo. Default API loopback only; stage HTTPS requires explicit opt-in; source host allowlist plus public IP pinning, no proxy/redirect, bounded fetch. All mutations require caller operation key; fanout derives stable per-goal keys. QA requires its own env credential; backend enforces different authenticated subject. Deterministic source-inventory operation only; task description is structured untrusted data, never a command/prompt. + +Graphify query at base returned unrelated preexisting graph (4304 nodes); graph binding unknown, navigation only. Direct controller/service/policy and integration test inspected as authoritative. No frontend/backend edits. Record graph SHA256 in verification. Existing spec baseline not copied/overwritten; scoped artifacts authored explicitly, specify 1.2.3 checked. Hermes CLI absent on PATH: document adapter invocation, do not claim native tool registration. diff --git a/specs/corporate-runtime/spec.md b/specs/corporate-runtime/spec.md new file mode 100644 index 00000000..8c6877b7 --- /dev/null +++ b/specs/corporate-runtime/spec.md @@ -0,0 +1,6 @@ +# Manual corporate runtime +Base cc365bcda265c7b86bd495d8428f85eea2b72081. Dormant opt-in CLI, never scheduler/config/restart/publish/deploy. + +An authenticated operator ingests real public HTTPS bytes with SHA256 and retrieval time, creates a research-backed roadmap and retry-safe goal task fanout, manually claims one read-only RESEARCH task and produces an immutable local artifact and actual tool receipt. A separate authenticated reviewer reopens exact artifact and source bytes, verifies against persisted research and submits independent QA. Effects must distinguish unavailable from measured zero; reports use persisted state. + +Acceptance: unsafe URLs/commands/unknown operations and changed artifacts fail closed; secrets only env and never output; stable idempotency keys; real Nest HTTP + disposable PostgreSQL pilot using actually fetched source; no production data or automation claims. Authentication pilot boundaries explicit. diff --git a/specs/corporate-runtime/tasks.md b/specs/corporate-runtime/tasks.md new file mode 100644 index 00000000..c0ef35ee --- /dev/null +++ b/specs/corporate-runtime/tasks.md @@ -0,0 +1,5 @@ +# Tasks +- [x] RED unit safety/operation/digest contract +- [x] Implement explicit manual API/source/artifact adapter +- [x] GREEN unit tests and real fetched-source PostgreSQL/Nest pilot +- [x] Document commands, boundaries, verification and commit (no push) diff --git a/specs/corporate-runtime/verification.md b/specs/corporate-runtime/verification.md new file mode 100644 index 00000000..55c386e5 --- /dev/null +++ b/specs/corporate-runtime/verification.md @@ -0,0 +1,10 @@ +# Verification +Base cc365bcda265c7b86bd495d8428f85eea2b72081; isolated branch corporate-runtime. Only scripts/corporate* and specs/corporate-runtime committed. No push, deployment, cron/config edits, Hermes restart or production mutation. + +- RED: python3 scripts/corporate_runtime_test.py failed FileNotFoundError before adapter implementation. +- GREEN: same command PASS 6 tests (URL/API restrictions, unknown operation rejection, tamper detection, exact deterministic inventory and immutable evidence checkpoint replay). Replay test added after implementation, not claimed RED-first. Python py_compile and git diff --check also PASS. These unit checks do not prove network behavior. +- Real manual pilot PASS: CORPORATE_PILOT_DIR=/opt/data/cache/scratch/corporate-runtime-pilot-final python3 scripts/corporate_pilot.py. Actually fetched https://hermes-agent.nousresearch.com/docs/llms.txt via pinned public HTTPS/TLS, no proxy or redirect. Real PostgreSQL port 55441 database corporate_test initialized under scratch; schema applied using Prisma db push, private generated Prisma client. Real Nest controller/service/shared guards over loopback port 55442 (global /api prefix), not a fake receiver. Test API-key validator accepts two ephemeral random credentials, mapped to separate authenticated subjects; not production credential validation or full AdminModule boot. +- Actual CLI subprocesses: dormant status, ingest + immutable idempotent replay, inactive roadmap, goal task fanout + idempotent repeat, claim/read-only artifact/evidence, independent QA, explicit UNINSTRUMENTED effect, daily snapshot. Executor self-QA rejected HTTP 409. API detail readback DONE with persisted events/evidence/review/effect; receipt in pilot-receipt.json. Full scratch transcript contains source digest, actual retrieval timestamps, raw fetched excerpt, request digest and tool timestamps; private store retains source/artifact/checkpoint bytes. Not fabricated market/clinical research or measured production impact. +- Graphify existing graph SHA256 6a73473cee9e207543fdeeb668bea544f766200a1b16b8a3a9ce18d4e42e51af; binding to base unknown and query irrelevant to new backend. Verified direct controller/service/policy/tests instead. Query cache stamp restored before commit. specify 1.2.3 checked; scoped SDD authored without replacing project config. +- Hermes executable absent from PATH (`hermes chat --help` exit 127). This is an executable manual terminal adapter suitable for a Hermes terminal tool invocation, not a registered native Hermes plugin/tool, model execution or proof of autonomous runtime. CLI reference loaded; no unsupported Hermes commands invented. +- No full backend/frontend regression/build, production auth, stage acceptance, scheduler, native Hermes tool registration, publishing or deployment claimed. PostgreSQL stopped after verification; data retained only in isolated scratch cluster. Unsupported claimed tasks remain leased until expiry (no backend release route). No source redirection or refresh-based QA: QA validates retained original bytes against original persisted provenance, not current network content. QA credentials prove separate subjects, not independent people.