From ed62885b4dcc847dc14bff129e1cc4f5addd226b Mon Sep 17 00:00:00 2001 From: Robert DeVore Date: Wed, 26 Aug 2026 10:54:25 -0400 Subject: [PATCH 1/3] refactor: clarify capability and evidence ownership --- src/adapters.kujo | 3 +- src/agent_bridge.kujo | 4 +- src/capabilities.kujo | 234 ++++++++++++++++++++++++++ src/cli.kujo | 178 ++++++++++++-------- src/common.kujo | 244 +--------------------------- src/doctor.kujo | 3 +- src/enterprise.kujo | 18 +- src/runtime.kujo | 7 +- src/store.kujo | 18 +- tests/relay_capability_fixture.kujo | 3 +- tests/relay_contract_tests.kujo | 3 +- 11 files changed, 381 insertions(+), 334 deletions(-) create mode 100644 src/capabilities.kujo diff --git a/src/adapters.kujo b/src/adapters.kujo index 732ecc2..e84033f 100644 --- a/src/adapters.kujo +++ b/src/adapters.kujo @@ -1,4 +1,5 @@ -from src.common import dict_get_or, env_or, env_bool, string_or, bool_or, int_or, safe_json, read_json_or, redact_text, process_options, safe_env_name, contains_any, path_is_symlink_safe, path_has_symlink_component, issue_agent_capability, revoke_agent_capability +from src.common import dict_get_or, env_or, env_bool, string_or, bool_or, int_or, safe_json, read_json_or, redact_text, process_options, safe_env_name, contains_any, path_is_symlink_safe, path_has_symlink_component +from src.capabilities import issue_agent_capability, revoke_agent_capability from src.policy import real_path, path_is_within_root from src.watchdog import watchdog_verify, safe_base, route_policy, safe_correlation_id diff --git a/src/agent_bridge.kujo b/src/agent_bridge.kujo index 499210d..f13ce18 100644 --- a/src/agent_bridge.kujo +++ b/src/agent_bridge.kujo @@ -1,7 +1,7 @@ # Agents SDK bridge executed with the Agents SDK checkout as its working # directory. The SDK owns registry, approval, and runner semantics; Relay owns # policy and repository authority through the bounded tools worker callback. -from src.common import path_is_symlink_safe, path_has_symlink_component, redact_text, safe_env_name +from src.common import JSONL_EVIDENCE_MAX_BYTES, path_is_symlink_safe, path_has_symlink_component, redact_text, safe_env_name from src.agents.ai.adapter import create_ai_sdk_adapter from src.agents.runner import create_agent_runner, run_agent from src.agents.core_types import create_agent, create_agent_run_request @@ -74,7 +74,7 @@ func process_options(extra_env, timeout_ms) { } env_map["PATH"] := "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin" if index_of(allowed, "PATH") < 0 { allowed := push(allowed, "PATH") } - return {"inherit_env": false, "timeout_ms": timeout_ms, "max_output_bytes": 8388608, "env": env_map, "env_allow": allowed} + return {"inherit_env": false, "timeout_ms": timeout_ms, "max_output_bytes": JSONL_EVIDENCE_MAX_BYTES, "env": env_map, "env_allow": allowed} } func call_relay_worker(tool_name, input_payload, context, payload) { diff --git a/src/capabilities.kujo b/src/capabilities.kujo new file mode 100644 index 0000000..1cc4435 --- /dev/null +++ b/src/capabilities.kujo @@ -0,0 +1,234 @@ +from src.common import CONTROL_RECORD_MAX_BYTES, JSON_DOCUMENT_MAX_BYTES, append_jsonl_bounded, bool_or, create_exclusive_dir, dict_get_or, ensure_safe_directory, env_or, int_or, path_has_symlink_component, path_is_symlink_safe, read_json_limited, string_or, write_json + +func relay_state_root(root) { + return env_or("RELAY_STATE_ROOT", trim(to_string(root)) + "/.relay") +} + +func capability_registry_path(root, run_id, session_id) { + base := relay_state_root(root) + if base == "" || path_is_symlink_safe(base) || path_has_symlink_component(base) { return "" } + return base + "/capabilities/" + sha256(to_string(run_id) + "|" + to_string(session_id)) + ".json" +} + +func capability_lock_owner_path(lock) { return lock + "/owner.json" } + +func capability_lock_acquire(lock, purpose, lease_ms) { + if path_is_symlink_safe(lock) { return {"ok": false, "error": "capability_lock_unsafe"} } + if create_exclusive_dir(lock) == false { return {"ok": false, "error": "capability_busy"} } + acquired_at := current_timestamp() + lease := int_or(lease_ms, 660000) + if lease < 1000 { lease = 1000 } + if lease > 900000 { lease = 900000 } + owner := {"contract_version": "relay-capability-lock-v1", "owner_id": "cap-owner-" + to_string(acquired_at) + "-" + to_string(random_int(1000, 999999)), "purpose": string_or(purpose, "capability"), "acquired_at_ms": acquired_at, "lease_expires_at_ms": acquired_at + lease} + if write_json(capability_lock_owner_path(lock), owner) == false { os_rmdir(lock); return {"ok": false, "error": "capability_lock_owner_write_failed"} } + return {"ok": true, "owner": owner} +} + +func capability_lock_release(lock) { + if path_is_dir(lock) == false || path_is_symlink_safe(lock) { return false } + owner_path := capability_lock_owner_path(lock) + if path_exists(owner_path) { delete_file(owner_path) } + os_rmdir(lock) + return path_exists(lock) == false +} + +func capability_lock_recovery_input(receipt) { + return to_string(dict_get_or(receipt, "contract_version", "")) + "|" + to_string(dict_get_or(receipt, "lock", "")) + "|" + to_string(dict_get_or(receipt, "previous_owner_id", "")) + "|" + to_string(dict_get_or(receipt, "purpose", "")) + "|" + to_string(dict_get_or(receipt, "lease_expires_at_ms", 0)) + "|" + to_string(dict_get_or(receipt, "recovered_at_ms", 0)) + "|" + to_string(dict_get_or(receipt, "reason", "")) +} + +func recover_expired_capability_lock(root, lock) { + if path_is_dir(lock) == false || path_is_symlink_safe(lock) { return {"ok": false, "recovered": false, "error": "capability lock is missing or unsafe"} } + owner := read_json_limited(capability_lock_owner_path(lock), null, CONTROL_RECORD_MAX_BYTES) + lease_expires := int_or(dict_get_or(owner, "lease_expires_at_ms", 0), 0) + if type(owner) != "dict" || string_or(dict_get_or(owner, "contract_version", ""), "") != "relay-capability-lock-v1" || string_or(dict_get_or(owner, "owner_id", ""), "") == "" || lease_expires <= 0 { return {"ok": false, "recovered": false, "error": "capability lock owner metadata is invalid"} } + if current_timestamp() <= lease_expires { return {"ok": true, "recovered": false, "active": true} } + receipt := {"contract_version": "relay-lock-recovery-v1", "lock": "capability", "previous_owner_id": owner["owner_id"], "purpose": string_or(dict_get_or(owner, "purpose", "capability"), "capability"), "lease_expires_at_ms": lease_expires, "recovered_at_ms": current_timestamp(), "reason": "expired_lease"} + receipt["integrity_sha256"] := sha256(capability_lock_recovery_input(receipt)) + recovery_path := relay_state_root(root) + "/lock-recovery.jsonl" + if append_jsonl_bounded(recovery_path, receipt, JSON_DOCUMENT_MAX_BYTES) == false { return {"ok": false, "recovered": false, "error": "capability lock recovery receipt could not be persisted"} } + if capability_lock_release(lock) == false { return {"ok": false, "recovered": false, "error": "expired capability lock could not be released"} } + return {"ok": true, "recovered": true, "receipt": receipt} +} + +func issue_agent_capability(root, run_id, session_id, workspace, nonce, max_calls, ttl_ms) { + path := capability_registry_path(root, run_id, session_id) + if path == "" { return {"ok": false, "error": {"code": "capability_registry_unsafe", "message": "Capability registry root is unsafe"}} } + directory := relay_state_root(root) + "/capabilities" + if path_is_symlink_safe(directory) || path_has_symlink_component(directory) { return {"ok": false, "error": {"code": "capability_registry_unsafe", "message": "Capability registry directory is unsafe"}} } + if ensure_safe_directory(directory) == false { return {"ok": false, "error": {"code": "capability_registry_unavailable", "message": "Capability registry directory could not be created safely"}} } + lock := path + ".lock" + if path_is_symlink_safe(path) || path_is_symlink_safe(lock) { return {"ok": false, "error": {"code": "capability_registry_unsafe", "message": "Capability registry record or lock is unsafe"}} } + if path_exists(path) { + if path_is_file(path) { return {"ok": false, "error": {"code": "capability_already_registered", "message": "Tool capability is already registered"}} } + return {"ok": false, "error": {"code": "capability_registry_unsafe", "message": "Capability registry record is not a regular file"}} + } + lock_result := capability_lock_acquire(lock, "issue", 30000) + if dict_get_or(lock_result, "ok", false) == false { + if path_exists(lock) && path_is_dir(lock) { return {"ok": false, "error": {"code": "capability_busy", "message": "Tool capability is already being issued or consumed"}} } + return {"ok": false, "error": {"code": "capability_lock_unsafe", "message": "Tool capability lock could not be acquired"}} + } + if path_exists(path) { + capability_lock_release(lock) + return {"ok": false, "error": {"code": "capability_already_registered", "message": "Tool capability is already registered"}} + } + calls := int_or(max_calls, 4) + if calls < 1 { calls = 1 } + if calls > 16 { calls = 16 } + lifetime := int_or(ttl_ms, 180000) + if lifetime < 1000 { lifetime = 1000 } + if lifetime > 600000 { lifetime = 600000 } + secret := sha256(to_string(run_id) + "|" + to_string(session_id) + "|" + to_string(nonce) + "|" + to_string(current_timestamp()) + "|" + to_string(random_int(1000, 999999))) + record := {"contract_version": "relay-agent-capability-v1", "run_id": to_string(run_id), "session_id": to_string(session_id), "workspace": to_string(workspace), "nonce": to_string(nonce), "capability": sha256(to_string(run_id) + "|" + to_string(session_id) + "|" + to_string(workspace) + "|" + to_string(nonce) + "|relay-agent-tools"), "secret_digest": sha256(secret), "issued_at_ms": current_timestamp(), "expires_at_ms": current_timestamp() + lifetime, "max_calls": calls, "used_calls": 0} + if write_json(path, record) == false { + capability_lock_release(lock) + return {"ok": false, "error": {"code": "capability_registry_write_failed", "message": "Capability registry record could not be persisted"}} + } + capability_lock_release(lock) + return {"ok": true, "secret": secret, "path": path, "expires_at_ms": record["expires_at_ms"], "max_calls": calls} +} + +func consume_agent_capability(root, request, supplied_secret) { + if type(request) != "dict" { return {"ok": false, "error": {"code": "capability_invalid", "message": "Capability request must be an object"}} } + run_id := to_string(dict_get_or(request, "run_id", "")) + session_id := to_string(dict_get_or(request, "session_id", "")) + path := capability_registry_path(root, run_id, session_id) + if path == "" || path_is_symlink_safe(path) || path_exists(path) == false { return {"ok": false, "error": {"code": "capability_not_registered", "message": "Tool capability is not registered"}} } + lock := path + ".lock" + if path_is_symlink_safe(lock) { return {"ok": false, "error": {"code": "capability_lock_unsafe", "message": "Tool capability lock is unsafe"}} } + if path_exists(lock) { + if path_is_dir(lock) { return {"ok": false, "error": {"code": "capability_busy", "message": "Tool capability is already being consumed"}} } + return {"ok": false, "error": {"code": "capability_lock_unsafe", "message": "Tool capability lock is not a directory"}} + } + lock_result := capability_lock_acquire(lock, "consume", 660000) + if dict_get_or(lock_result, "ok", false) == false { + if path_exists(lock) && path_is_dir(lock) { return {"ok": false, "error": {"code": "capability_busy", "message": "Tool capability is already being consumed"}} } + return {"ok": false, "error": {"code": "capability_lock_unsafe", "message": "Tool capability lock could not be acquired"}} + } + mut result := {"ok": false, "error": {"code": "capability_invalid", "message": "Tool capability is invalid"}} + try { + record := read_json_limited(path, null, CONTROL_RECORD_MAX_BYTES) + if type(record) != "dict" { result = {"ok": false, "error": {"code": "capability_invalid", "message": "Tool capability record is invalid"}} } + else if to_string(dict_get_or(record, "run_id", "")) != run_id || to_string(dict_get_or(record, "session_id", "")) != session_id || to_string(dict_get_or(record, "workspace", "")) != to_string(dict_get_or(request, "workspace", "")) || to_string(dict_get_or(record, "nonce", "")) != to_string(dict_get_or(request, "capability_nonce", "")) || to_string(dict_get_or(record, "capability", "")) != to_string(dict_get_or(request, "capability", "")) { result = {"ok": false, "error": {"code": "capability_invalid", "message": "Tool capability identity does not match"}} } + else if sha256(to_string(supplied_secret)) != to_string(dict_get_or(record, "secret_digest", "")) { result = {"ok": false, "error": {"code": "capability_invalid", "message": "Tool capability secret is invalid"}} } + else if current_timestamp() > int_or(dict_get_or(record, "expires_at_ms", 0), 0) { result = {"ok": false, "error": {"code": "capability_expired", "message": "Tool capability has expired"}} } + else { + used := int_or(dict_get_or(record, "used_calls", 0), 0) + maximum := int_or(dict_get_or(record, "max_calls", 0), 0) + if maximum < 1 || used >= maximum { result = {"ok": false, "error": {"code": "capability_replay_detected", "message": "Tool capability call budget is exhausted"}} } + else { + record["used_calls"] := used + 1 + record["last_used_at_ms"] := current_timestamp() + if write_json(path, record) == false { result = {"ok": false, "error": {"code": "capability_registry_write_failed", "message": "Tool capability usage could not be persisted"}} } + else { result = {"ok": true, "used_calls": used + 1, "remaining_calls": maximum - used - 1, "expires_at_ms": record["expires_at_ms"]} } + } + } + } except err { result = {"ok": false, "error": {"code": "capability_invalid", "message": "Tool capability could not be verified"}} } + capability_lock_release(lock) + return result +} + +func revoke_agent_capability(root, run_id, session_id) { + path := capability_registry_path(root, run_id, session_id) + if path == "" || path_is_symlink_safe(path) { return false } + lock := path + ".lock" + if path_is_symlink_safe(lock) { return false } + mut acquired := false + mut attempt := 1 + while attempt <= 4 { + if path_exists(lock) { + if path_is_dir(lock) { + if attempt < 4 { sleep(20 * attempt); attempt = attempt + 1; continue } + return false + } + return false + } + if dict_get_or(capability_lock_acquire(lock, "revoke", 30000), "ok", false) { acquired = true; break } + if path_exists(lock) && path_is_dir(lock) { + if attempt < 4 { sleep(20 * attempt); attempt = attempt + 1; continue } + return false + } + return false + } + if acquired == false { return false } + mut removed := true + try { + if path_exists(path) { + if path_is_symlink_safe(path) || path_is_file(path) == false { removed = false } + else { delete_file(path) } + } + } except err { removed = false } + capability_lock_release(lock) + return removed +} + +func capability_registry_posture(root, repair) { + directory := relay_state_root(root) + "/capabilities" + if path_is_symlink_safe(directory) || path_has_symlink_component(directory) { return {"ok": false, "safe": false, "present": true, "records": 0, "stale": 0, "invalid": 1, "cleaned": 0, "error": "capability registry path is unsafe"} } + if path_exists(directory) == false { return {"ok": true, "safe": true, "present": false, "records": 0, "stale": 0, "invalid": 0, "cleaned": 0} } + if path_is_dir(directory) == false { return {"ok": false, "safe": false, "present": true, "records": 0, "stale": 0, "invalid": 1, "cleaned": 0, "error": "capability registry path is not a directory"} } + names := list_dir(directory) + if len(names) > 1024 { return {"ok": false, "safe": false, "present": true, "records": 0, "stale": 0, "invalid": 1, "cleaned": 0, "error": "capability registry exceeds the 1024-entry limit"} } + mut records := 0 + mut stale := 0 + mut invalid := 0 + mut cleaned := 0 + mut locked := 0 + for name in names { + if ends_with(name, ".json") == false { continue } + path := directory + "/" + name + if path_is_symlink_safe(path) || path_is_file(path) == false { invalid = invalid + 1; continue } + record := read_json_limited(path, null, CONTROL_RECORD_MAX_BYTES) + if type(record) != "dict" || to_string(dict_get_or(record, "contract_version", "")) != "relay-agent-capability-v1" { invalid = invalid + 1; continue } + records = records + 1 + expired := current_timestamp() > int_or(dict_get_or(record, "expires_at_ms", 0), 0) + exhausted := int_or(dict_get_or(record, "used_calls", 0), 0) >= int_or(dict_get_or(record, "max_calls", 0), 0) + if bool_or(repair, false) { + lock := path + ".lock" + if path_is_symlink_safe(lock) { + invalid = invalid + 1 + continue + } + if path_exists(lock) && path_is_dir(lock) == false { + invalid = invalid + 1 + continue + } + acquired := false + if path_exists(lock) { + if path_is_dir(lock) { + recovery := recover_expired_capability_lock(root, lock) + if dict_get_or(recovery, "recovered", false) { acquired = dict_get_or(capability_lock_acquire(lock, "doctor-repair", 30000), "ok", false) } + else if dict_get_or(recovery, "ok", false) { locked = locked + 1 } + else { invalid = invalid + 1 } + } else { invalid = invalid + 1 } + } else if dict_get_or(capability_lock_acquire(lock, "doctor-repair", 30000), "ok", false) { acquired = true } else if path_exists(lock) && path_is_dir(lock) { locked = locked + 1 } else { invalid = invalid + 1 } + if acquired { + current := read_json_limited(path, null, CONTROL_RECORD_MAX_BYTES) + if type(current) != "dict" || to_string(dict_get_or(current, "contract_version", "")) != "relay-agent-capability-v1" { + invalid = invalid + 1 + } else { + current_expired := current_timestamp() > int_or(dict_get_or(current, "expires_at_ms", 0), 0) + current_exhausted := int_or(dict_get_or(current, "used_calls", 0), 0) >= int_or(dict_get_or(current, "max_calls", 0), 0) + if current_expired || current_exhausted { + stale = stale + 1 + try { delete_file(path); cleaned = cleaned + 1 } except err {} + } + } + capability_lock_release(lock) + } else if expired || exhausted { stale = stale + 1 } + } else if expired || exhausted { + stale = stale + 1 + } + } + return {"ok": invalid == 0, "safe": invalid == 0, "present": true, "records": records, "stale": stale, "invalid": invalid, "locked": locked, "cleaned": cleaned, "repair": bool_or(repair, false)} +} + +export capability_registry_path := capability_registry_path +export capability_lock_owner_path := capability_lock_owner_path +export capability_lock_acquire := capability_lock_acquire +export capability_lock_release := capability_lock_release +export capability_lock_recovery_input := capability_lock_recovery_input +export recover_expired_capability_lock := recover_expired_capability_lock +export issue_agent_capability := issue_agent_capability +export consume_agent_capability := consume_agent_capability +export revoke_agent_capability := revoke_agent_capability +export capability_registry_posture := capability_registry_posture diff --git a/src/cli.kujo b/src/cli.kujo index fcc48b9..72a3773 100644 --- a/src/cli.kujo +++ b/src/cli.kujo @@ -1,4 +1,4 @@ -from src.common import dict_get_or, env_or, env_bool, string_or, bool_or, int_or, read_json_limited, safe_json, write_json, now_iso, path_is_symlink_safe +from src.common import JSON_DOCUMENT_MAX_BYTES, JSONL_EVIDENCE_MAX_BYTES, dict_get_or, env_or, env_bool, string_or, bool_or, int_or, read_json_limited, safe_json, write_json, now_iso, path_is_symlink_safe from src.contracts import RELAY_VERSION, event_chain_integrity_valid, event_sequence_matches_state, receipt_sequence_valid, receipt_sequence_matches_state, state_integrity_valid from src.registry import agent_catalog, find_agent, agent_path from src.adapters import ai_chat, capsule_run @@ -21,10 +21,10 @@ func read_receipt_evidence(run_dir) { # A missing receipt file must not silently fall back to the copy embedded # in state.json. The file is the persisted evidence boundary; accepting the # state fallback would let an incomplete run appear fully receipted. - if path_is_symlink_safe(path) || path_exists(path) == false || path_is_file(path) == false || file_size(path) > 1048576 { + if path_is_symlink_safe(path) || path_exists(path) == false || path_is_file(path) == false || file_size(path) > JSON_DOCUMENT_MAX_BYTES { return {"ok": false, "receipts": [], "error": "run receipt evidence is missing, non-regular, symbolic-linked, or exceeds the 1 MiB runtime JSON limit"} } - receipts := read_json_limited(path, null, 1048576) + receipts := read_json_limited(path, null, JSON_DOCUMENT_MAX_BYTES) if type(receipts) != "array" { return {"ok": false, "receipts": [], "error": "run receipt evidence is invalid JSON"} } @@ -33,10 +33,10 @@ func read_receipt_evidence(run_dir) { func read_run_state_evidence(run_dir, run_id) { path := run_dir + "/state.json" - if path_is_symlink_safe(path) || path_exists(path) == false || path_is_file(path) == false || file_size(path) > 1048576 { + if path_is_symlink_safe(path) || path_exists(path) == false || path_is_file(path) == false || file_size(path) > JSON_DOCUMENT_MAX_BYTES { return {"ok": false, "state": {}, "error": "run state evidence is missing, non-regular, symbolic-linked, or exceeds the 1 MiB runtime JSON limit"} } - state := read_json_limited(path, null, 1048576) + state := read_json_limited(path, null, JSON_DOCUMENT_MAX_BYTES) if type(state) != "dict" { return {"ok": false, "state": {}, "error": "run state evidence is invalid JSON"} } @@ -49,14 +49,12 @@ func read_run_state_evidence(run_dir, run_id) { return {"ok": true, "state": state} } -func read_run_artifact_evidence(run_dir, name, expected_type, max_bytes) { +func read_run_artifact_evidence(run_dir, name, expected_type) { path := run_dir + "/" + name - limit := int_or(max_bytes, 1048576) - if limit > 1048576 { limit = 1048576 } - if path_is_symlink_safe(path) || path_exists(path) == false || path_is_file(path) == false || file_size(path) > limit { + if path_is_symlink_safe(path) || path_exists(path) == false || path_is_file(path) == false || file_size(path) > JSON_DOCUMENT_MAX_BYTES { return {"ok": false, "value": null, "error": "run artifact evidence is missing, non-regular, symbolic-linked, or exceeds its inspection limit: " + name} } - value := read_json_limited(path, null, limit) + value := read_json_limited(path, null, JSON_DOCUMENT_MAX_BYTES) if type(value) != expected_type { return {"ok": false, "value": null, "error": "run artifact evidence has an invalid JSON shape: " + name} } @@ -68,7 +66,7 @@ func provider_tool_result_evidence(run_dir, state, run_id) { if bool_or(dict_get_or(agent_sdk_tools, "provider_generated", false), false) == false { return {"required": false, "ok": true, "value": null, "error": ""} } - artifact := read_run_artifact_evidence(run_dir, "tool-results.json", "dict", 8388608) + artifact := read_run_artifact_evidence(run_dir, "tool-results.json", "dict") if dict_get_or(artifact, "ok", false) == false { return {"required": true, "ok": false, "value": null, "error": dict_get_or(artifact, "error", "provider tool-result evidence is invalid")} } @@ -93,7 +91,7 @@ func report_matches_state(report, state, run_id) { func report_markdown_valid(run_dir) { path := run_dir + "/report.md" - return path_is_symlink_safe(path) == false && path_exists(path) && path_is_file(path) && file_size(path) <= 8388608 + return path_is_symlink_safe(path) == false && path_exists(path) && path_is_file(path) && file_size(path) <= JSONL_EVIDENCE_MAX_BYTES } func positional(values, index, fallback) { @@ -310,7 +308,7 @@ func cmd_missions(tokens) { if dict_get_or(state_evidence, "ok", false) == false { return {"ok": false, "failure_class": "evidence_failure", "error": dict_get_or(state_evidence, "error", "run state evidence is invalid")} } state := state_evidence["state"] if sub == "report" { - report_evidence := read_run_artifact_evidence(record["run_dir"], "report.json", "dict", 8388608) + report_evidence := read_run_artifact_evidence(record["run_dir"], "report.json", "dict") report_ok := dict_get_or(report_evidence, "ok", false) && report_matches_state(dict_get_or(report_evidence, "value", {}), state, id) && report_markdown_valid(record["run_dir"]) if report_ok == false { return {"ok": false, "failure_class": "evidence_failure", "error": "report evidence is missing, malformed, or does not match authoritative state"} } return {"ok": true, "report_json": record["run_dir"] + "/report.json", "report_markdown": record["run_dir"] + "/report.md", "status": dict_get_or(state, "status", "unknown")} @@ -348,7 +346,7 @@ func watch_run_events(record, run_id, flags) { return {"ok": false, "_streamed": true} } } - if event_exists && file_size(events_path) > 8388608 { + if event_exists && file_size(events_path) > JSONL_EVIDENCE_MAX_BYTES { print(safe_json({"type": "relay_watch_error", "error": "run event log exceeds the 8 MiB inspection limit"})) return {"ok": false, "_streamed": true} } @@ -479,7 +477,7 @@ func run_artifact_sizes(record, run_id, flags) { if name == "workspace" { continue } - child := artifact_inventory(run_dir + "/" + name, name, 4096, 8388608, 0, has_flag(flags, "hashes")) + child := artifact_inventory(run_dir + "/" + name, name, 4096, JSONL_EVIDENCE_MAX_BYTES, 0, has_flag(flags, "hashes")) if dict_get_or(child, "ok", false) == false { return child } child_entries := dict_get_or(child, "entries", []) if type(child_entries) == "array" { @@ -489,7 +487,7 @@ func run_artifact_sizes(record, run_id, flags) { files := files + int_or(dict_get_or(child, "files", 0), 0) directories := directories + int_or(dict_get_or(child, "directories", 0), 0) if len(entries) > 4096 { return {"ok": false, "error": "run artifact inventory exceeds the entry limit"} } - if total_bytes > 8388608 { return {"ok": false, "error": "run artifact inventory exceeds the total byte limit"} } + if total_bytes > JSONL_EVIDENCE_MAX_BYTES { return {"ok": false, "error": "run artifact inventory exceeds the total byte limit"} } } return {"ok": true, "format": "relay-run-sizes-v1", "run_id": run_id, "run_dir": run_dir, "generated_at": now_iso(), "hashes_included": bool_or(has_flag(flags, "hashes"), false), "summary": {"bytes": total_bytes, "files": files, "directories": directories}, "entries": entries, "excluded": excluded} } @@ -569,6 +567,64 @@ func run_window(index, flags) { return {"ok": true, "runs": window, "run_count": len(run_ids), "offset": start, "has_more": end < len(run_ids), "next_after": next_after} } +func load_run_event_evidence(record, run_id) { + run_dir := record["run_dir"] + events_path := run_dir + "/events.jsonl" + if path_is_symlink_safe(events_path) || path_exists(events_path) == false || path_is_file(events_path) == false || file_size(events_path) > JSONL_EVIDENCE_MAX_BYTES { + return {"ok": false, "bundle": {"ok": false, "error": "run event log is missing, non-regular, symbolic-linked, or exceeds the 8 MiB inspection limit", "integrity_valid": false, "state_consistent": false}} + } + raw_events := read_file(events_path) + events := [] + for line in split(raw_events, "\n") { + if trim(line) == "" { continue } + try { events = push(events, parse_json(line)) } except err { + return {"ok": false, "bundle": {"ok": false, "error": "run event log contains invalid JSON", "integrity_valid": false}} + } + } + state_evidence := read_run_state_evidence(run_dir, run_id) + if dict_get_or(state_evidence, "ok", false) == false { + return {"ok": false, "bundle": {"ok": false, "error": dict_get_or(state_evidence, "error", "run state evidence is invalid"), "integrity_valid": false, "state_consistent": false, "receipts_valid": false, "receipts_consistent": false}} + } + state := state_evidence["state"] + chain_valid := event_chain_integrity_valid(events) + state_consistent := event_sequence_matches_state(dict_get_or(state, "events", []), events) + receipt_evidence := read_receipt_evidence(run_dir) + receipts := dict_get_or(receipt_evidence, "receipts", []) + receipts_valid := dict_get_or(receipt_evidence, "ok", false) && receipt_sequence_valid(receipts) + receipts_consistent := receipts_valid && receipt_sequence_matches_state(dict_get_or(state, "receipts", []), receipts) + valid := chain_valid && state_consistent && receipts_valid && receipts_consistent + bundle := {"ok": valid, "integrity_valid": valid, "chain_integrity_valid": chain_valid, "state_consistent": state_consistent, "receipts_valid": receipts_valid, "receipts_consistent": receipts_consistent, "receipt_error": dict_get_or(receipt_evidence, "error", ""), "events": events, "events_jsonl": raw_events, "event_count": len(events), "offset": 0, "has_more": false, "next_after": ""} + return {"ok": valid, "bundle": bundle, "state": state, "receipts": receipts} +} + +func load_required_run_artifacts(run_dir, state, run_id) { + changes := read_run_artifact_evidence(run_dir, "changes.json", "dict") + evaluations := read_run_artifact_evidence(run_dir, "evaluations.json", "array") + report := read_run_artifact_evidence(run_dir, "report.json", "dict") + tool_results := provider_tool_result_evidence(run_dir, state, run_id) + packet_manifest := verify_packet_manifest(run_dir, state) + changes_valid := dict_get_or(changes, "ok", false) + evaluations_valid := dict_get_or(evaluations, "ok", false) + report_valid := dict_get_or(report, "ok", false) && report_matches_state(dict_get_or(report, "value", {}), state, run_id) && report_markdown_valid(run_dir) + tool_results_valid := dict_get_or(tool_results, "ok", false) + packet_manifest_valid := dict_get_or(packet_manifest, "ok", false) + valid := changes_valid && evaluations_valid && report_valid && tool_results_valid && packet_manifest_valid + return { + "ok": valid, + "changes": changes, + "evaluations": evaluations, + "report": report, + "tool_results": tool_results, + "packet_manifest": packet_manifest, + "changes_valid": changes_valid, + "evaluations_valid": evaluations_valid, + "report_valid": report_valid, + "tool_results_valid": tool_results_valid, + "packet_manifest_valid": packet_manifest_valid, + "errors": [dict_get_or(changes, "error", ""), dict_get_or(evaluations, "error", ""), dict_get_or(report, "error", ""), dict_get_or(tool_results, "error", ""), dict_get_or(packet_manifest, "error", "")] + } +} + func cmd_runs(tokens) { parsed := parse_tokens(tokens) sub := positional(parsed["positionals"], 0, "list") @@ -590,7 +646,7 @@ func cmd_runs(tokens) { if store_check["ok"] == false { return store_check } id := positional(parsed["positionals"], 1, "") if sub == "verify-signature" { - signed_value := read_json_limited(id, {}, 1048576) + signed_value := read_json_limited(id, {}, JSON_DOCUMENT_MAX_BYTES) return verify_signed_export(id, signing_key(string_or(dict_get_or(signed_value, "key_id", ""), ""))) } if sub == "rebuild" { @@ -629,22 +685,14 @@ func cmd_runs(tokens) { if dict_get_or(state_evidence, "ok", false) == false { return {"ok": false, "format": "relay-run-verification-v1", "run_id": id, "integrity_valid": false, "state_valid": false, "error": dict_get_or(state_evidence, "error", "run state evidence is invalid")} } - events_result := cmd_runs(["events", id]) - if dict_get_or(events_result, "ok", false) == false { + event_evidence := load_run_event_evidence(record, id) + events_result := event_evidence["bundle"] + if dict_get_or(event_evidence, "ok", false) == false { return {"ok": false, "format": "relay-run-verification-v1", "run_id": id, "integrity_valid": false, "state_valid": true, "events_valid": dict_get_or(events_result, "integrity_valid", false), "receipts_valid": dict_get_or(events_result, "receipts_valid", false), "receipts_consistent": dict_get_or(events_result, "receipts_consistent", false), "error": dict_get_or(events_result, "error", "run event evidence is invalid")} } - changes := read_run_artifact_evidence(record["run_dir"], "changes.json", "dict", 8388608) - evaluations := read_run_artifact_evidence(record["run_dir"], "evaluations.json", "array", 8388608) - report := read_run_artifact_evidence(record["run_dir"], "report.json", "dict", 8388608) - tool_results := provider_tool_result_evidence(record["run_dir"], state_evidence["state"], id) - packet_manifest := verify_packet_manifest(record["run_dir"], state_evidence["state"]) - changes_valid := dict_get_or(changes, "ok", false) - evaluations_valid := dict_get_or(evaluations, "ok", false) - report_valid := dict_get_or(report, "ok", false) && report_matches_state(dict_get_or(report, "value", {}), state_evidence["state"], id) && report_markdown_valid(record["run_dir"]) - tool_results_valid := dict_get_or(tool_results, "ok", false) - packet_manifest_valid := dict_get_or(packet_manifest, "ok", false) - valid := changes_valid && evaluations_valid && report_valid && tool_results_valid && packet_manifest_valid - return {"ok": valid, "format": "relay-run-verification-v1", "run_id": id, "status": dict_get_or(state_evidence["state"], "status", "unknown"), "integrity_valid": valid, "state_valid": true, "events_valid": true, "receipts_valid": dict_get_or(events_result, "receipts_valid", false), "receipts_consistent": dict_get_or(events_result, "receipts_consistent", false), "changes_valid": changes_valid, "evaluations_valid": evaluations_valid, "report_valid": report_valid, "tool_results_required": dict_get_or(tool_results, "required", false), "tool_results_valid": tool_results_valid, "packet_manifest_required": dict_get_or(packet_manifest, "required", false), "packet_manifest_valid": packet_manifest_valid, "errors": [dict_get_or(changes, "error", ""), dict_get_or(evaluations, "error", ""), dict_get_or(report, "error", ""), dict_get_or(tool_results, "error", ""), dict_get_or(packet_manifest, "error", "")]} + artifacts := load_required_run_artifacts(record["run_dir"], state_evidence["state"], id) + valid := artifacts["ok"] + return {"ok": valid, "format": "relay-run-verification-v1", "run_id": id, "status": dict_get_or(state_evidence["state"], "status", "unknown"), "integrity_valid": valid, "state_valid": true, "events_valid": true, "receipts_valid": dict_get_or(events_result, "receipts_valid", false), "receipts_consistent": dict_get_or(events_result, "receipts_consistent", false), "changes_valid": artifacts["changes_valid"], "evaluations_valid": artifacts["evaluations_valid"], "report_valid": artifacts["report_valid"], "tool_results_required": dict_get_or(artifacts["tool_results"], "required", false), "tool_results_valid": artifacts["tool_results_valid"], "packet_manifest_required": dict_get_or(artifacts["packet_manifest"], "required", false), "packet_manifest_valid": artifacts["packet_manifest_valid"], "errors": artifacts["errors"]} } if sub == "watch" { return watch_run_events(record, id, parsed["flags"]) } if sub == "sizes" { return run_artifact_sizes(record, id, parsed["flags"]) } @@ -656,31 +704,12 @@ func cmd_runs(tokens) { return {"ok": true, "run": state_evidence["state"], "run_dir": record["run_dir"]} } if sub == "events" || sub == "export" { - events_path := record["run_dir"] + "/events.jsonl" - if path_is_symlink_safe(events_path) || path_exists(events_path) == false || path_is_file(events_path) == false || file_size(events_path) > 8388608 { return {"ok": false, "error": "run event log is missing, non-regular, symbolic-linked, or exceeds the 8 MiB inspection limit", "integrity_valid": false, "state_consistent": false} } - raw_events := read_file(events_path) - events := [] - for line in split(raw_events, "\n") { - if trim(line) == "" { continue } - try { events = push(events, parse_json(line)) } except err { return {"ok": false, "error": "run event log contains invalid JSON", "integrity_valid": false} } - } - state_evidence := read_run_state_evidence(record["run_dir"], id) - if dict_get_or(state_evidence, "ok", false) == false { - return {"ok": false, "error": dict_get_or(state_evidence, "error", "run state evidence is invalid"), "integrity_valid": false, "state_consistent": false, "receipts_valid": false, "receipts_consistent": false} - } - state := state_evidence["state"] - chain_valid := event_chain_integrity_valid(events) - state_consistent := event_sequence_matches_state(dict_get_or(state, "events", []), events) - receipt_evidence := read_receipt_evidence(record["run_dir"]) - receipts := dict_get_or(receipt_evidence, "receipts", []) - receipts_valid := dict_get_or(receipt_evidence, "ok", false) && receipt_sequence_valid(receipts) - receipts_consistent := receipts_valid && receipt_sequence_matches_state(dict_get_or(state, "receipts", []), receipts) - valid := chain_valid && state_consistent && receipts_valid && receipts_consistent - event_bundle := {"integrity_valid": valid, "chain_integrity_valid": chain_valid, "state_consistent": state_consistent, "receipts_valid": receipts_valid, "receipts_consistent": receipts_consistent, "receipt_error": dict_get_or(receipt_evidence, "error", ""), "events": events, "events_jsonl": raw_events, "event_count": len(events), "offset": 0, "has_more": false, "next_after": ""} + event_evidence := load_run_event_evidence(record, id) + event_bundle := event_evidence["bundle"] if sub == "events" { - if valid == false { event_bundle["ok"] := false; return event_bundle } - window := event_window(events, parsed["flags"]) - if dict_get_or(window, "ok", false) == false { return {"ok": false, "integrity_valid": true, "chain_integrity_valid": chain_valid, "state_consistent": state_consistent, "receipts_valid": receipts_valid, "receipts_consistent": receipts_consistent, "error": dict_get_or(window, "error", "event window is invalid")} } + if dict_get_or(event_evidence, "ok", false) == false { return event_bundle } + window := event_window(event_bundle["events"], parsed["flags"]) + if dict_get_or(window, "ok", false) == false { return {"ok": false, "integrity_valid": true, "chain_integrity_valid": event_bundle["chain_integrity_valid"], "state_consistent": event_bundle["state_consistent"], "receipts_valid": event_bundle["receipts_valid"], "receipts_consistent": event_bundle["receipts_consistent"], "error": dict_get_or(window, "error", "event window is invalid")} } event_bundle["events"] := window["events"] event_bundle["events_jsonl"] := "" event_bundle["event_count"] := window["event_count"] @@ -690,22 +719,29 @@ func cmd_runs(tokens) { event_bundle["ok"] := true return event_bundle } - if valid == false { event_bundle["ok"] := false; event_bundle["error"] := "run event integrity verification failed"; return event_bundle } - changes_evidence := read_run_artifact_evidence(record["run_dir"], "changes.json", "dict", 8388608) - evaluations_evidence := read_run_artifact_evidence(record["run_dir"], "evaluations.json", "array", 8388608) - report_evidence := read_run_artifact_evidence(record["run_dir"], "report.json", "dict", 8388608) - tool_results_evidence := provider_tool_result_evidence(record["run_dir"], state, id) - packet_manifest_evidence := verify_packet_manifest(record["run_dir"], state) - changes_valid := dict_get_or(changes_evidence, "ok", false) - evaluations_valid := dict_get_or(evaluations_evidence, "ok", false) - report_valid := dict_get_or(report_evidence, "ok", false) && report_matches_state(dict_get_or(report_evidence, "value", {}), state, id) && report_markdown_valid(record["run_dir"]) - tool_results_valid := dict_get_or(tool_results_evidence, "ok", false) - packet_manifest_valid := dict_get_or(packet_manifest_evidence, "ok", false) - if changes_valid == false || evaluations_valid == false || report_valid == false || tool_results_valid == false || packet_manifest_valid == false { + if dict_get_or(event_evidence, "ok", false) == false { + if has_key(event_bundle, "error") == false { event_bundle["error"] := "run event integrity verification failed" } + return event_bundle + } + state := event_evidence["state"] + events := event_bundle["events"] + receipts := event_evidence["receipts"] + artifacts := load_required_run_artifacts(record["run_dir"], state, id) + changes_evidence := artifacts["changes"] + evaluations_evidence := artifacts["evaluations"] + report_evidence := artifacts["report"] + tool_results_evidence := artifacts["tool_results"] + packet_manifest_evidence := artifacts["packet_manifest"] + changes_valid := artifacts["changes_valid"] + evaluations_valid := artifacts["evaluations_valid"] + report_valid := artifacts["report_valid"] + tool_results_valid := artifacts["tool_results_valid"] + packet_manifest_valid := artifacts["packet_manifest_valid"] + if artifacts["ok"] == false { partial_requested := has_flag(parsed["flags"], "partial") run_status := string_or(dict_get_or(state, "status", "unknown"), "unknown") if partial_requested && run_status != "completed" { - partial_bundle := {"format": "relay-run-export-partial-v1", "run_id": id, "integrity_valid": false, "completeness": "partial", "partial": true, "status": run_status, "state_valid": true, "events_valid": true, "receipts_valid": receipts_valid, "receipts_consistent": receipts_consistent, "artifact_presence": {"changes": changes_valid, "evaluations": evaluations_valid, "report": report_valid, "tool_results": tool_results_valid, "packet_manifest": packet_manifest_valid}, "artifact_errors": [dict_get_or(changes_evidence, "error", ""), dict_get_or(evaluations_evidence, "error", ""), dict_get_or(report_evidence, "error", ""), dict_get_or(tool_results_evidence, "error", ""), dict_get_or(packet_manifest_evidence, "error", "")], "run": state, "events": events, "receipts": receipts, "changes": dict_get_or(changes_evidence, "value", null), "evaluations": dict_get_or(evaluations_evidence, "value", null), "report": dict_get_or(report_evidence, "value", null), "tool_results": dict_get_or(tool_results_evidence, "value", null), "packet_manifest": dict_get_or(packet_manifest_evidence, "value", null)} + partial_bundle := {"format": "relay-run-export-partial-v1", "run_id": id, "integrity_valid": false, "completeness": "partial", "partial": true, "status": run_status, "state_valid": true, "events_valid": true, "receipts_valid": event_bundle["receipts_valid"], "receipts_consistent": event_bundle["receipts_consistent"], "artifact_presence": {"changes": changes_valid, "evaluations": evaluations_valid, "report": report_valid, "tool_results": tool_results_valid, "packet_manifest": packet_manifest_valid}, "artifact_errors": artifacts["errors"], "run": state, "events": events, "receipts": receipts, "changes": dict_get_or(changes_evidence, "value", null), "evaluations": dict_get_or(evaluations_evidence, "value", null), "report": dict_get_or(report_evidence, "value", null), "tool_results": dict_get_or(tool_results_evidence, "value", null), "packet_manifest": dict_get_or(packet_manifest_evidence, "value", null)} output_path := string_or(dict_get_or(parsed["flags"], "output", ""), "") if output_path != "" { if write_json(output_path, partial_bundle) == false { return {"ok": false, "error": "partial run export could not be written"} } @@ -720,12 +756,12 @@ func cmd_runs(tokens) { event_bundle["changes_valid"] := changes_valid event_bundle["evaluations_valid"] := evaluations_valid event_bundle["report_valid"] := report_valid - event_bundle["artifact_errors"] := [dict_get_or(changes_evidence, "error", ""), dict_get_or(evaluations_evidence, "error", ""), dict_get_or(report_evidence, "error", ""), dict_get_or(tool_results_evidence, "error", ""), dict_get_or(packet_manifest_evidence, "error", "")] + event_bundle["artifact_errors"] := artifacts["errors"] event_bundle["tool_results_valid"] := tool_results_valid event_bundle["packet_manifest_valid"] := packet_manifest_valid return event_bundle } - bundle := {"format": "relay-run-export-v1", "run_id": id, "integrity_valid": true, "chain_integrity_valid": chain_valid, "state_consistent": state_consistent, "receipts_valid": receipts_valid, "receipts_consistent": receipts_consistent, "changes_valid": true, "evaluations_valid": true, "report_valid": true, "tool_results_required": dict_get_or(tool_results_evidence, "required", false), "tool_results_valid": true, "packet_manifest_required": dict_get_or(packet_manifest_evidence, "required", false), "packet_manifest_valid": true, "run": state, "events": events, "receipts": receipts, "changes": changes_evidence["value"], "evaluations": evaluations_evidence["value"], "report": report_evidence["value"], "tool_results": dict_get_or(tool_results_evidence, "value", null), "packet_manifest": dict_get_or(packet_manifest_evidence, "value", null)} + bundle := {"format": "relay-run-export-v1", "run_id": id, "integrity_valid": true, "chain_integrity_valid": event_bundle["chain_integrity_valid"], "state_consistent": event_bundle["state_consistent"], "receipts_valid": event_bundle["receipts_valid"], "receipts_consistent": event_bundle["receipts_consistent"], "changes_valid": true, "evaluations_valid": true, "report_valid": true, "tool_results_required": dict_get_or(tool_results_evidence, "required", false), "tool_results_valid": true, "packet_manifest_required": dict_get_or(packet_manifest_evidence, "required", false), "packet_manifest_valid": true, "run": state, "events": events, "receipts": receipts, "changes": changes_evidence["value"], "evaluations": evaluations_evidence["value"], "report": report_evidence["value"], "tool_results": dict_get_or(tool_results_evidence, "value", null), "packet_manifest": dict_get_or(packet_manifest_evidence, "value", null)} if has_flag(parsed["flags"], "signed") { key_id := string_or(dict_get_or(parsed["flags"], "key-id", ""), "") signed := signed_export(bundle, key_id, signing_key(key_id)) @@ -748,7 +784,7 @@ func cmd_runs(tokens) { artifact_name := "changes.json" expected_type := "dict" if sub == "evaluations" { artifact_name = "evaluations.json"; expected_type = "array" } - artifact := read_run_artifact_evidence(record["run_dir"], artifact_name, expected_type, 8388608) + artifact := read_run_artifact_evidence(record["run_dir"], artifact_name, expected_type) if dict_get_or(artifact, "ok", false) == false { return {"ok": false, "failure_class": "evidence_failure", "error": dict_get_or(artifact, "error", "run artifact evidence is invalid")} } diff --git a/src/common.kujo b/src/common.kujo index e7faacb..a356dce 100644 --- a/src/common.kujo +++ b/src/common.kujo @@ -1,3 +1,7 @@ +export JSON_DOCUMENT_MAX_BYTES := 1048576 +export JSONL_EVIDENCE_MAX_BYTES := 8388608 +export CONTROL_RECORD_MAX_BYTES := 65536 + func dict_get_or(obj, key, fallback) { if type(obj) != "dict" || has_key(obj, key) == 0 { return fallback } return obj[key] @@ -252,13 +256,13 @@ func read_json_or(path, fallback) { } func read_json_limited(path, fallback, max_bytes) { - limit := int_or(max_bytes, 1048576) + limit := int_or(max_bytes, JSON_DOCUMENT_MAX_BYTES) if limit <= 0 || path_is_symlink_safe(path) || path_exists(path) == false { return fallback } if path_is_file(path) == false || file_size(path) > limit { return fallback } # Kujo's stable JSON parser rejects inputs above 1 MiB. Clamp the # effective boundary so callers fail before reading instead of advertising # a larger JSON limit that the runtime cannot parse. - if file_size(path) > 1048576 { return fallback } + if file_size(path) > JSON_DOCUMENT_MAX_BYTES { return fallback } return read_json_or(path, fallback) } @@ -269,7 +273,7 @@ func write_json(path, value) { func append_jsonl_bounded(path, value, max_bytes) { try { line := safe_json(value) + "\n" - limit := int_or(max_bytes, 8388608) + limit := int_or(max_bytes, JSONL_EVIDENCE_MAX_BYTES) if limit <= 0 || len(line) > limit { return false } # Check metadata before path_exists: writing through a dangling link # would otherwise turn an absent evidence file into an attacker- @@ -284,229 +288,7 @@ func append_jsonl_bounded(path, value, max_bytes) { } func append_jsonl(path, value) { - return append_jsonl_bounded(path, value, 8388608) -} - -func relay_state_root(root) { - return env_or("RELAY_STATE_ROOT", trim(to_string(root)) + "/.relay") -} - -func capability_registry_path(root, run_id, session_id) { - base := relay_state_root(root) - if base == "" || path_is_symlink_safe(base) || path_has_symlink_component(base) { return "" } - return base + "/capabilities/" + sha256(to_string(run_id) + "|" + to_string(session_id)) + ".json" -} - -func capability_lock_owner_path(lock) { return lock + "/owner.json" } - -func capability_lock_acquire(lock, purpose, lease_ms) { - if path_is_symlink_safe(lock) { return {"ok": false, "error": "capability_lock_unsafe"} } - if create_exclusive_dir(lock) == false { return {"ok": false, "error": "capability_busy"} } - acquired_at := current_timestamp() - lease := int_or(lease_ms, 660000) - if lease < 1000 { lease = 1000 } - if lease > 900000 { lease = 900000 } - owner := {"contract_version": "relay-capability-lock-v1", "owner_id": "cap-owner-" + to_string(acquired_at) + "-" + to_string(random_int(1000, 999999)), "purpose": string_or(purpose, "capability"), "acquired_at_ms": acquired_at, "lease_expires_at_ms": acquired_at + lease} - if write_json(capability_lock_owner_path(lock), owner) == false { os_rmdir(lock); return {"ok": false, "error": "capability_lock_owner_write_failed"} } - return {"ok": true, "owner": owner} -} - -func capability_lock_release(lock) { - if path_is_dir(lock) == false || path_is_symlink_safe(lock) { return false } - owner_path := capability_lock_owner_path(lock) - if path_exists(owner_path) { delete_file(owner_path) } - os_rmdir(lock) - return path_exists(lock) == false -} - -func capability_lock_recovery_input(receipt) { - return to_string(dict_get_or(receipt, "contract_version", "")) + "|" + to_string(dict_get_or(receipt, "lock", "")) + "|" + to_string(dict_get_or(receipt, "previous_owner_id", "")) + "|" + to_string(dict_get_or(receipt, "purpose", "")) + "|" + to_string(dict_get_or(receipt, "lease_expires_at_ms", 0)) + "|" + to_string(dict_get_or(receipt, "recovered_at_ms", 0)) + "|" + to_string(dict_get_or(receipt, "reason", "")) -} - -func recover_expired_capability_lock(root, lock) { - if path_is_dir(lock) == false || path_is_symlink_safe(lock) { return {"ok": false, "recovered": false, "error": "capability lock is missing or unsafe"} } - owner := read_json_limited(capability_lock_owner_path(lock), null, 65536) - lease_expires := int_or(dict_get_or(owner, "lease_expires_at_ms", 0), 0) - if type(owner) != "dict" || string_or(dict_get_or(owner, "contract_version", ""), "") != "relay-capability-lock-v1" || string_or(dict_get_or(owner, "owner_id", ""), "") == "" || lease_expires <= 0 { return {"ok": false, "recovered": false, "error": "capability lock owner metadata is invalid"} } - if current_timestamp() <= lease_expires { return {"ok": true, "recovered": false, "active": true} } - receipt := {"contract_version": "relay-lock-recovery-v1", "lock": "capability", "previous_owner_id": owner["owner_id"], "purpose": string_or(dict_get_or(owner, "purpose", "capability"), "capability"), "lease_expires_at_ms": lease_expires, "recovered_at_ms": current_timestamp(), "reason": "expired_lease"} - receipt["integrity_sha256"] := sha256(capability_lock_recovery_input(receipt)) - recovery_path := relay_state_root(root) + "/lock-recovery.jsonl" - if append_jsonl_bounded(recovery_path, receipt, 1048576) == false { return {"ok": false, "recovered": false, "error": "capability lock recovery receipt could not be persisted"} } - if capability_lock_release(lock) == false { return {"ok": false, "recovered": false, "error": "expired capability lock could not be released"} } - return {"ok": true, "recovered": true, "receipt": receipt} -} - -func issue_agent_capability(root, run_id, session_id, workspace, nonce, max_calls, ttl_ms) { - path := capability_registry_path(root, run_id, session_id) - if path == "" { return {"ok": false, "error": {"code": "capability_registry_unsafe", "message": "Capability registry root is unsafe"}} } - directory := relay_state_root(root) + "/capabilities" - if path_is_symlink_safe(directory) || path_has_symlink_component(directory) { return {"ok": false, "error": {"code": "capability_registry_unsafe", "message": "Capability registry directory is unsafe"}} } - if ensure_safe_directory(directory) == false { return {"ok": false, "error": {"code": "capability_registry_unavailable", "message": "Capability registry directory could not be created safely"}} } - lock := path + ".lock" - if path_is_symlink_safe(path) || path_is_symlink_safe(lock) { return {"ok": false, "error": {"code": "capability_registry_unsafe", "message": "Capability registry record or lock is unsafe"}} } - if path_exists(path) { - if path_is_file(path) { return {"ok": false, "error": {"code": "capability_already_registered", "message": "Tool capability is already registered"}} } - return {"ok": false, "error": {"code": "capability_registry_unsafe", "message": "Capability registry record is not a regular file"}} - } - lock_result := capability_lock_acquire(lock, "issue", 30000) - if dict_get_or(lock_result, "ok", false) == false { - if path_exists(lock) && path_is_dir(lock) { return {"ok": false, "error": {"code": "capability_busy", "message": "Tool capability is already being issued or consumed"}} } - return {"ok": false, "error": {"code": "capability_lock_unsafe", "message": "Tool capability lock could not be acquired"}} - } - if path_exists(path) { - capability_lock_release(lock) - return {"ok": false, "error": {"code": "capability_already_registered", "message": "Tool capability is already registered"}} - } - calls := int_or(max_calls, 4) - if calls < 1 { calls = 1 } - if calls > 16 { calls = 16 } - lifetime := int_or(ttl_ms, 180000) - if lifetime < 1000 { lifetime = 1000 } - if lifetime > 600000 { lifetime = 600000 } - secret := sha256(to_string(run_id) + "|" + to_string(session_id) + "|" + to_string(nonce) + "|" + to_string(current_timestamp()) + "|" + to_string(random_int(1000, 999999))) - record := {"contract_version": "relay-agent-capability-v1", "run_id": to_string(run_id), "session_id": to_string(session_id), "workspace": to_string(workspace), "nonce": to_string(nonce), "capability": sha256(to_string(run_id) + "|" + to_string(session_id) + "|" + to_string(workspace) + "|" + to_string(nonce) + "|relay-agent-tools"), "secret_digest": sha256(secret), "issued_at_ms": current_timestamp(), "expires_at_ms": current_timestamp() + lifetime, "max_calls": calls, "used_calls": 0} - if write_json(path, record) == false { - capability_lock_release(lock) - return {"ok": false, "error": {"code": "capability_registry_write_failed", "message": "Capability registry record could not be persisted"}} - } - capability_lock_release(lock) - return {"ok": true, "secret": secret, "path": path, "expires_at_ms": record["expires_at_ms"], "max_calls": calls} -} - -func consume_agent_capability(root, request, supplied_secret) { - if type(request) != "dict" { return {"ok": false, "error": {"code": "capability_invalid", "message": "Capability request must be an object"}} } - run_id := to_string(dict_get_or(request, "run_id", "")) - session_id := to_string(dict_get_or(request, "session_id", "")) - path := capability_registry_path(root, run_id, session_id) - if path == "" || path_is_symlink_safe(path) || path_exists(path) == false { return {"ok": false, "error": {"code": "capability_not_registered", "message": "Tool capability is not registered"}} } - lock := path + ".lock" - if path_is_symlink_safe(lock) { return {"ok": false, "error": {"code": "capability_lock_unsafe", "message": "Tool capability lock is unsafe"}} } - if path_exists(lock) { - if path_is_dir(lock) { return {"ok": false, "error": {"code": "capability_busy", "message": "Tool capability is already being consumed"}} } - return {"ok": false, "error": {"code": "capability_lock_unsafe", "message": "Tool capability lock is not a directory"}} - } - lock_result := capability_lock_acquire(lock, "consume", 660000) - if dict_get_or(lock_result, "ok", false) == false { - if path_exists(lock) && path_is_dir(lock) { return {"ok": false, "error": {"code": "capability_busy", "message": "Tool capability is already being consumed"}} } - return {"ok": false, "error": {"code": "capability_lock_unsafe", "message": "Tool capability lock could not be acquired"}} - } - mut result := {"ok": false, "error": {"code": "capability_invalid", "message": "Tool capability is invalid"}} - try { - record := read_json_limited(path, null, 65536) - if type(record) != "dict" { result = {"ok": false, "error": {"code": "capability_invalid", "message": "Tool capability record is invalid"}} } - else if to_string(dict_get_or(record, "run_id", "")) != run_id || to_string(dict_get_or(record, "session_id", "")) != session_id || to_string(dict_get_or(record, "workspace", "")) != to_string(dict_get_or(request, "workspace", "")) || to_string(dict_get_or(record, "nonce", "")) != to_string(dict_get_or(request, "capability_nonce", "")) || to_string(dict_get_or(record, "capability", "")) != to_string(dict_get_or(request, "capability", "")) { result = {"ok": false, "error": {"code": "capability_invalid", "message": "Tool capability identity does not match"}} } - else if sha256(to_string(supplied_secret)) != to_string(dict_get_or(record, "secret_digest", "")) { result = {"ok": false, "error": {"code": "capability_invalid", "message": "Tool capability secret is invalid"}} } - else if current_timestamp() > int_or(dict_get_or(record, "expires_at_ms", 0), 0) { result = {"ok": false, "error": {"code": "capability_expired", "message": "Tool capability has expired"}} } - else { - used := int_or(dict_get_or(record, "used_calls", 0), 0) - maximum := int_or(dict_get_or(record, "max_calls", 0), 0) - if maximum < 1 || used >= maximum { result = {"ok": false, "error": {"code": "capability_replay_detected", "message": "Tool capability call budget is exhausted"}} } - else { - record["used_calls"] := used + 1 - record["last_used_at_ms"] := current_timestamp() - if write_json(path, record) == false { result = {"ok": false, "error": {"code": "capability_registry_write_failed", "message": "Tool capability usage could not be persisted"}} } - else { result = {"ok": true, "used_calls": used + 1, "remaining_calls": maximum - used - 1, "expires_at_ms": record["expires_at_ms"]} } - } - } - } except err { result = {"ok": false, "error": {"code": "capability_invalid", "message": "Tool capability could not be verified"}} } - capability_lock_release(lock) - return result -} - -func revoke_agent_capability(root, run_id, session_id) { - path := capability_registry_path(root, run_id, session_id) - if path == "" || path_is_symlink_safe(path) { return false } - lock := path + ".lock" - if path_is_symlink_safe(lock) { return false } - mut acquired := false - mut attempt := 1 - while attempt <= 4 { - if path_exists(lock) { - if path_is_dir(lock) { - if attempt < 4 { sleep(20 * attempt); attempt = attempt + 1; continue } - return false - } - return false - } - if dict_get_or(capability_lock_acquire(lock, "revoke", 30000), "ok", false) { acquired = true; break } - if path_exists(lock) && path_is_dir(lock) { - if attempt < 4 { sleep(20 * attempt); attempt = attempt + 1; continue } - return false - } - return false - } - if acquired == false { return false } - mut removed := true - try { - if path_exists(path) { - if path_is_symlink_safe(path) || path_is_file(path) == false { removed = false } - else { delete_file(path) } - } - } except err { removed = false } - capability_lock_release(lock) - return removed -} - -func capability_registry_posture(root, repair) { - directory := relay_state_root(root) + "/capabilities" - if path_is_symlink_safe(directory) || path_has_symlink_component(directory) { return {"ok": false, "safe": false, "present": true, "records": 0, "stale": 0, "invalid": 1, "cleaned": 0, "error": "capability registry path is unsafe"} } - if path_exists(directory) == false { return {"ok": true, "safe": true, "present": false, "records": 0, "stale": 0, "invalid": 0, "cleaned": 0} } - if path_is_dir(directory) == false { return {"ok": false, "safe": false, "present": true, "records": 0, "stale": 0, "invalid": 1, "cleaned": 0, "error": "capability registry path is not a directory"} } - names := list_dir(directory) - if len(names) > 1024 { return {"ok": false, "safe": false, "present": true, "records": 0, "stale": 0, "invalid": 1, "cleaned": 0, "error": "capability registry exceeds the 1024-entry limit"} } - mut records := 0 - mut stale := 0 - mut invalid := 0 - mut cleaned := 0 - mut locked := 0 - for name in names { - if ends_with(name, ".json") == false { continue } - path := directory + "/" + name - if path_is_symlink_safe(path) || path_is_file(path) == false { invalid = invalid + 1; continue } - record := read_json_limited(path, null, 65536) - if type(record) != "dict" || to_string(dict_get_or(record, "contract_version", "")) != "relay-agent-capability-v1" { invalid = invalid + 1; continue } - records = records + 1 - expired := current_timestamp() > int_or(dict_get_or(record, "expires_at_ms", 0), 0) - exhausted := int_or(dict_get_or(record, "used_calls", 0), 0) >= int_or(dict_get_or(record, "max_calls", 0), 0) - if bool_or(repair, false) { - lock := path + ".lock" - if path_is_symlink_safe(lock) { - invalid = invalid + 1 - continue - } - if path_exists(lock) && path_is_dir(lock) == false { - invalid = invalid + 1 - continue - } - acquired := false - if path_exists(lock) { - if path_is_dir(lock) { - recovery := recover_expired_capability_lock(root, lock) - if dict_get_or(recovery, "recovered", false) { acquired = dict_get_or(capability_lock_acquire(lock, "doctor-repair", 30000), "ok", false) } - else if dict_get_or(recovery, "ok", false) { locked = locked + 1 } - else { invalid = invalid + 1 } - } else { invalid = invalid + 1 } - } else if dict_get_or(capability_lock_acquire(lock, "doctor-repair", 30000), "ok", false) { acquired = true } else if path_exists(lock) && path_is_dir(lock) { locked = locked + 1 } else { invalid = invalid + 1 } - if acquired { - current := read_json_limited(path, null, 65536) - if type(current) != "dict" || to_string(dict_get_or(current, "contract_version", "")) != "relay-agent-capability-v1" { - invalid = invalid + 1 - } else { - current_expired := current_timestamp() > int_or(dict_get_or(current, "expires_at_ms", 0), 0) - current_exhausted := int_or(dict_get_or(current, "used_calls", 0), 0) >= int_or(dict_get_or(current, "max_calls", 0), 0) - if current_expired || current_exhausted { - stale = stale + 1 - try { delete_file(path); cleaned = cleaned + 1 } except err {} - } - } - capability_lock_release(lock) - } else if expired || exhausted { stale = stale + 1 } - } else if expired || exhausted { - stale = stale + 1 - } - } - return {"ok": invalid == 0, "safe": invalid == 0, "present": true, "records": records, "stale": stale, "invalid": invalid, "locked": locked, "cleaned": cleaned, "repair": bool_or(repair, false)} + return append_jsonl_bounded(path, value, JSONL_EVIDENCE_MAX_BYTES) } func redact_text(value) { @@ -568,15 +350,5 @@ export read_json_limited := read_json_limited export write_json := write_json export append_jsonl_bounded := append_jsonl_bounded export append_jsonl := append_jsonl -export capability_registry_path := capability_registry_path -export capability_lock_owner_path := capability_lock_owner_path -export capability_lock_acquire := capability_lock_acquire -export capability_lock_release := capability_lock_release -export capability_lock_recovery_input := capability_lock_recovery_input -export recover_expired_capability_lock := recover_expired_capability_lock -export issue_agent_capability := issue_agent_capability -export consume_agent_capability := consume_agent_capability -export revoke_agent_capability := revoke_agent_capability -export capability_registry_posture := capability_registry_posture export contains_any := contains_any export redact_text := redact_text diff --git a/src/doctor.kujo b/src/doctor.kujo index 6856ec4..7d241c6 100644 --- a/src/doctor.kujo +++ b/src/doctor.kujo @@ -1,4 +1,5 @@ -from src.common import dict_get_or, env_or, env_bool, bool_or, safe_env_name, int_or, path_is_symlink_safe, path_has_symlink_component, capability_registry_posture +from src.common import dict_get_or, env_or, env_bool, bool_or, safe_env_name, int_or, path_is_symlink_safe, path_has_symlink_component +from src.capabilities import capability_registry_posture from src.adapters import kujo_bin, trusted_executable, trusted_file, ai_sdk_root, agents_sdk_root, ai_bridge_path, watchdog_url, run_process, safe_watchdog_upstream_profile from src.policy import real_path from src.watchdog import health_check, proxy_config_check, route_policy diff --git a/src/enterprise.kujo b/src/enterprise.kujo index 60a5676..f8b6598 100644 --- a/src/enterprise.kujo +++ b/src/enterprise.kujo @@ -1,4 +1,4 @@ -from src.common import dict_get_or, env_or, env_bool, string_or, bool_or, int_or, safe_json, read_json_limited, write_json, append_jsonl_bounded, redact_text, now_iso, path_is_symlink_safe, ensure_safe_directory +from src.common import CONTROL_RECORD_MAX_BYTES, JSON_DOCUMENT_MAX_BYTES, dict_get_or, env_or, env_bool, string_or, bool_or, int_or, safe_json, read_json_limited, write_json, append_jsonl_bounded, redact_text, now_iso, path_is_symlink_safe, ensure_safe_directory from src.contracts import state_integrity_valid export SPEC_IMPORT_CONTRACT := "relay-spec-import-v1" @@ -8,8 +8,8 @@ export FAILURE_HANDOFF_CONTRACT := "relay-failure-handoff-v1" export SIGNED_EXPORT_CONTRACT := "relay-signed-export-v1" func negotiate_contract(path) { - if path == "" || path_is_symlink_safe(path) || path_exists(path) == false || path_is_file(path) == false || file_size(path) > 1048576 { return {"ok": false, "error": "contract import must be a regular file no larger than 1 MiB"} } - value := read_json_limited(path, null, 1048576) + if path == "" || path_is_symlink_safe(path) || path_exists(path) == false || path_is_file(path) == false || file_size(path) > JSON_DOCUMENT_MAX_BYTES { return {"ok": false, "error": "contract import must be a regular file no larger than 1 MiB"} } + value := read_json_limited(path, null, JSON_DOCUMENT_MAX_BYTES) if type(value) != "dict" { return {"ok": false, "error": "contract import must be a JSON object"} } kind := string_or(dict_get_or(value, "kind", ""), "") version := string_or(dict_get_or(value, "version", ""), "") @@ -62,8 +62,8 @@ func failure_handoff(run_dir, run_id, output_path, confirmed) { if confirmed == false { return {"ok": false, "error": "failed-run handoff requires --confirm"} } if output_path == "" || path_is_symlink_safe(output_path) { return {"ok": false, "error": "failed-run handoff requires a safe --output path"} } state_path := run_dir + "/state.json" - if path_is_symlink_safe(state_path) || path_exists(state_path) == false || file_size(state_path) > 1048576 { return {"ok": false, "error": "run state is unavailable or exceeds 1 MiB"} } - state := read_json_limited(state_path, null, 1048576) + if path_is_symlink_safe(state_path) || path_exists(state_path) == false || file_size(state_path) > JSON_DOCUMENT_MAX_BYTES { return {"ok": false, "error": "run state is unavailable or exceeds 1 MiB"} } + state := read_json_limited(state_path, null, JSON_DOCUMENT_MAX_BYTES) if type(state) != "dict" || state_integrity_valid(state) == false || string_or(dict_get_or(state, "run_id", ""), "") != run_id { return {"ok": false, "error": "run state integrity or identity is invalid"} } status := string_or(dict_get_or(state, "status", ""), "") if status != "failed" && status != "cancelled" { return {"ok": false, "error": "handoff is limited to failed or cancelled runs"} } @@ -84,7 +84,7 @@ func signed_export(bundle, key_id, secret) { func signing_key(key_id) { raw := env_or("RELAY_SIGNING_KEYS", "") - if raw != "" && len(raw) <= 65536 { + if raw != "" && len(raw) <= CONTROL_RECORD_MAX_BYTES { keys_value := null try { keys_value = parse_json(raw) } except err { return "" } if type(keys_value) == "dict" { return string_or(dict_get_or(keys_value, key_id, ""), "") } @@ -94,8 +94,8 @@ func signing_key(key_id) { func verify_signed_export(path, secret) { if secret == "" { return {"ok": false, "error": "RELAY_SIGNING_KEY is required"} } - if path == "" || path_is_symlink_safe(path) || path_exists(path) == false || path_is_file(path) == false || file_size(path) > 1048576 { return {"ok": false, "error": "signed export is unavailable or exceeds 1 MiB"} } - value := read_json_limited(path, null, 1048576) + if path == "" || path_is_symlink_safe(path) || path_exists(path) == false || path_is_file(path) == false || file_size(path) > JSON_DOCUMENT_MAX_BYTES { return {"ok": false, "error": "signed export is unavailable or exceeds 1 MiB"} } + value := read_json_limited(path, null, JSON_DOCUMENT_MAX_BYTES) if type(value) != "dict" || string_or(dict_get_or(value, "format", ""), "") != SIGNED_EXPORT_CONTRACT || type(dict_get_or(value, "payload", null)) != "dict" { return {"ok": false, "error": "signed export contract is invalid"} } payload_sha := sha256(safe_json(value["payload"])) expected := hmac_sha256(secret, SIGNED_EXPORT_CONTRACT + "|" + string_or(dict_get_or(value, "key_id", ""), "") + "|" + payload_sha) @@ -117,7 +117,7 @@ func aggregate_metrics(index) { if runs >= 4096 { break } record := index[id] run_dir := string_or(dict_get_or(record, "run_dir", ""), "") - state := read_json_limited(run_dir + "/state.json", null, 1048576) + state := read_json_limited(run_dir + "/state.json", null, JSON_DOCUMENT_MAX_BYTES) if type(state) != "dict" || state_integrity_valid(state) == false { continue } runs = runs + 1 status := string_or(dict_get_or(state, "status", "unknown"), "unknown") diff --git a/src/runtime.kujo b/src/runtime.kujo index cf41d87..c402d96 100644 --- a/src/runtime.kujo +++ b/src/runtime.kujo @@ -1,4 +1,5 @@ -from src.common import dict_get_or, env_or, string_or, bool_or, int_or, now_iso, safe_id, read_json_or, read_json_limited, write_json, append_jsonl_bounded, safe_json, shell_quote_single, command_args, write_text_atomic, process_options, process_options_with_cancel, redact_text, path_is_symlink_safe, path_has_symlink_component, ensure_safe_directory, consume_agent_capability +from src.common import JSON_DOCUMENT_MAX_BYTES, JSONL_EVIDENCE_MAX_BYTES, dict_get_or, env_or, string_or, bool_or, int_or, now_iso, safe_id, read_json_or, read_json_limited, write_json, append_jsonl_bounded, safe_json, shell_quote_single, command_args, write_text_atomic, process_options, process_options_with_cancel, redact_text, path_is_symlink_safe, path_has_symlink_component, ensure_safe_directory +from src.capabilities import consume_agent_capability from src.contracts import run_state, event, event_integrity_input, receipt, receipt_integrity_input, event_chain_integrity_valid, receipt_sequence_valid, state_integrity_input, state_integrity_valid, MISSION_SPEC_VERSION, LEGACY_MISSION_SPEC_VERSION, mission_spec_version_supported from src.registry import find_agent from src.policy import tool_decision, classify_failure, repair_allowed, path_is_safe, path_is_within_workspace, command_is_allowed, script_hash_policy_valid @@ -8,7 +9,7 @@ from src.store import rebuild_run_index, rebuild_and_persist_run_index_result, l export MISSION_SPEC_MAX_BYTES := 1048576 export MISSION_COMMAND_MAX_BYTES := 16384 export TRACKED_FILE_DISCOVERY_MAX_BYTES := 16777216 -export JSON_EVIDENCE_MAX_BYTES := 1048576 +export JSON_EVIDENCE_MAX_BYTES := JSON_DOCUMENT_MAX_BYTES func ensure_dir(path) { return ensure_safe_directory(path) @@ -115,7 +116,7 @@ func add_event(state, run_dir, kind, step_id, agent_id, payload) { item["integrity_sha256"] := sha256(event_integrity_input(item)) if len(safe_json(state)) + len(safe_json(item)) + 2 > JSON_EVIDENCE_MAX_BYTES { return mark_evidence_failure(state, "run state event projection exceeds the 1 MiB runtime JSON limit") } state["events"] := push(state["events"], item) - if append_jsonl_bounded(run_dir + "/events.jsonl", item, 8388608) == false { state = mark_evidence_failure(state, "run event log could not be persisted or exceeded the 8 MiB evidence limit") } + if append_jsonl_bounded(run_dir + "/events.jsonl", item, JSONL_EVIDENCE_MAX_BYTES) == false { state = mark_evidence_failure(state, "run event log could not be persisted or exceeded the 8 MiB evidence limit") } return state } diff --git a/src/store.kujo b/src/store.kujo index 20617b5..e810fce 100644 --- a/src/store.kujo +++ b/src/store.kujo @@ -1,4 +1,4 @@ -from src.common import dict_get_or, env_or, int_or, bool_or, read_json_limited, write_json, append_jsonl_bounded, safe_json, string_or, path_is_symlink_safe, path_has_symlink_component, path_has_parent_component, create_exclusive_dir +from src.common import CONTROL_RECORD_MAX_BYTES, JSON_DOCUMENT_MAX_BYTES, dict_get_or, env_or, int_or, bool_or, read_json_limited, write_json, append_jsonl_bounded, safe_json, string_or, path_is_symlink_safe, path_has_symlink_component, path_has_parent_component, create_exclusive_dir from src.contracts import state_integrity_valid from src.store_sqlite import sqlite_write_index, sqlite_read_index, sqlite_store_posture @@ -86,7 +86,7 @@ func index_lock_recovery_input(receipt) { func record_index_lock_recovery(state_root, owner) { receipt := {"contract_version": "relay-lock-recovery-v1", "lock": "run-index", "previous_owner_id": string_or(dict_get_or(owner, "owner_id", ""), ""), "previous_token_digest": sha256(string_or(dict_get_or(owner, "token", ""), "")), "lease_expires_at_ms": int_or(dict_get_or(owner, "lease_expires_at_ms", 0), 0), "recovered_at_ms": current_timestamp(), "reason": "expired_lease"} receipt["integrity_sha256"] := sha256(index_lock_recovery_input(receipt)) - if append_jsonl_bounded(index_lock_recovery_path(state_root), receipt, 1048576) == false { return {"ok": false, "error": "Run index lock recovery receipt could not be persisted"} } + if append_jsonl_bounded(index_lock_recovery_path(state_root), receipt, JSON_DOCUMENT_MAX_BYTES) == false { return {"ok": false, "error": "Run index lock recovery receipt could not be persisted"} } return {"ok": true, "receipt": receipt} } @@ -96,7 +96,7 @@ func acquire_index_lock(state_root) { return {"ok": false, "error": "Run index lock path must not be a symbolic link"} } if path_is_dir(lock_path) { - owner := read_json_limited(index_lock_owner_path(state_root), {}, 65536) + owner := read_json_limited(index_lock_owner_path(state_root), {}, CONTROL_RECORD_MAX_BYTES) lease_expires := int_or(dict_get_or(owner, "lease_expires_at_ms", 0), 0) contract_valid := string_or(dict_get_or(owner, "contract_version", ""), "") == "relay-index-lock-v1" && string_or(dict_get_or(owner, "owner_id", ""), "") != "" && string_or(dict_get_or(owner, "token", ""), "") != "" && lease_expires > 0 if contract_valid && current_timestamp() > lease_expires { @@ -147,7 +147,7 @@ func acquire_index_lock_retry(state_root, max_attempts, delay_ms) { func release_index_lock(state_root, token) { lock_path := index_lock_path(state_root) if path_is_dir(lock_path) == false { return {"ok": true, "released": false} } - owner := read_json_limited(index_lock_owner_path(state_root), {}, 65536) + owner := read_json_limited(index_lock_owner_path(state_root), {}, CONTROL_RECORD_MAX_BYTES) if string_or(dict_get_or(owner, "contract_version", ""), "") != "relay-index-lock-v1" || string_or(dict_get_or(owner, "token", ""), "") != string_or(token, "") { return {"ok": false, "error": "Run index lock token mismatch"} } @@ -166,7 +166,7 @@ func rebuild_run_index(state_root) { if safe_run_key(name) == false { continue } run_dir := expected_run_dir(state_root, name) if path_is_dir(run_dir) == false || path_is_symlink_safe(run_dir) { continue } - state := read_json_limited(run_state_path(state_root, name), null, 1048576) + state := read_json_limited(run_state_path(state_root, name), null, JSON_DOCUMENT_MAX_BYTES) if type(state) != "dict" || string_or(dict_get_or(state, "run_id", ""), "") != name { continue } index[name] := index_record(state_root, name, state) } @@ -176,7 +176,7 @@ func rebuild_run_index(state_root) { func cached_index_is_safe(state_root, index) { if type(index) != "dict" { return false } index_path := state_root + "/index.json" - if path_is_symlink_safe(index_path) || (path_exists(index_path) && file_size(index_path) > 8388608) { return false } + if path_is_symlink_safe(index_path) || (path_exists(index_path) && file_size(index_path) > JSON_DOCUMENT_MAX_BYTES) { return false } for run_id in keys(index) { if safe_run_key(run_id) == false { return false } record := index[run_id] @@ -199,7 +199,7 @@ func run_directories_match_index(state_root, index) { if safe_run_key(name) && path_is_dir(run_dir) && path_is_symlink_safe(run_dir) == false { count = count + 1 if has_key(index, name) == 0 { return false } - state := read_json_limited(run_state_path(state_root, name), null, 1048576) + state := read_json_limited(run_state_path(state_root, name), null, JSON_DOCUMENT_MAX_BYTES) if type(state) != "dict" || string_or(dict_get_or(state, "run_id", ""), "") != name { return false } expected := index_record(state_root, name, state) record := index[name] @@ -227,7 +227,7 @@ func rebuild_and_persist_run_index_result(state_root) { return {"ok": false, "index": authoritative, "error": "Transactional SQLite run index could not be persisted", "attempts": lock["attempts"]} } } - persisted := read_json_limited(index_path, null, 8388608) + persisted := read_json_limited(index_path, null, JSON_DOCUMENT_MAX_BYTES) verified := type(persisted) == "dict" && cached_index_is_safe(state_root, persisted) && run_directories_match_index(state_root, persisted) release_index_lock(state_root, lock["token"]) if verified == false { return {"ok": false, "index": authoritative, "error": "Persisted run index failed verification", "attempts": lock["attempts"]} } @@ -244,7 +244,7 @@ func load_run_index_result(state_root) { if dict_get_or(rebuilt, "ok", false) == false { return {"ok": false, "index": dict_get_or(rebuilt, "index", {}), "source": "rebuild", "error": dict_get_or(rebuilt, "error", "Transactional SQLite run index could not be rebuilt")} } return {"ok": true, "index": dict_get_or(rebuilt, "index", {}), "source": "rebuild", "persisted": true} } - cached := read_json_limited(state_root + "/index.json", null, 8388608) + cached := read_json_limited(state_root + "/index.json", null, JSON_DOCUMENT_MAX_BYTES) if cached_index_is_safe(state_root, cached) && run_directories_match_index(state_root, cached) { return {"ok": true, "index": cached, "source": "json"} } diff --git a/tests/relay_capability_fixture.kujo b/tests/relay_capability_fixture.kujo index 046593f..5e80590 100644 --- a/tests/relay_capability_fixture.kujo +++ b/tests/relay_capability_fixture.kujo @@ -1,4 +1,5 @@ -from src.common import dict_get_or, issue_agent_capability, env_or, int_or +from src.common import dict_get_or, env_or, int_or +from src.capabilities import issue_agent_capability raw := env_or("RELAY_CAPABILITY_FIXTURE", "") payload := null diff --git a/tests/relay_contract_tests.kujo b/tests/relay_contract_tests.kujo index 7936a79..b29564f 100644 --- a/tests/relay_contract_tests.kujo +++ b/tests/relay_contract_tests.kujo @@ -1,7 +1,8 @@ from src.contracts import event, event_integrity_valid, event_chain_integrity_valid, event_sequence_matches_state, receipt, receipt_integrity_valid, receipt_sequence_valid, receipt_sequence_matches_state, state_integrity_input, state_integrity_valid, run_state, agent_profile, RELAY_VERSION, MISSION_SPEC_VERSION, LEGACY_MISSION_SPEC_VERSION, mission_spec_version_supported, EVENT_CONTRACT, RECEIPT_CONTRACT from src.policy import classify_failure, repair_allowed, path_is_safe, path_is_within_workspace, command_is_allowed, tool_decision from src.runtime import load_spec, resume_state_safe, cleanup_state_safe, control_state_safe, save_state, mark_evidence_failure, cancellation_request, cancellation_integrity_input, persist_required_json, report, provider_failure_message, provider_followup_token_ceiling, provider_synthesis_messages, provider_synthesis_tool, provider_synthesis_answer, preflight_failure_message, list_files_page -from src.common import safe_id, redact_text, shell_quote_single, command_args, process_options, process_options_with_cancel, safe_process_path, safe_env_name, path_is_symlink_safe, path_has_symlink_component, path_has_parent_component, read_json_limited, append_jsonl, append_jsonl_bounded, write_json, write_text_atomic, create_exclusive_dir, dict_get_or, bool_or, string_or, safe_json, issue_agent_capability, revoke_agent_capability +from src.common import safe_id, redact_text, shell_quote_single, command_args, process_options, process_options_with_cancel, safe_process_path, safe_env_name, path_is_symlink_safe, path_has_symlink_component, path_has_parent_component, read_json_limited, append_jsonl, append_jsonl_bounded, write_json, write_text_atomic, create_exclusive_dir, dict_get_or, bool_or, string_or, safe_json +from src.capabilities import issue_agent_capability, revoke_agent_capability from src.adapters import fallback_allowed, fallback_decision, watchdog_route_allowed, tool_definitions, normalize_provider_tool_calls, provider_payload_size, provider_payload_allowed, safe_watchdog_upstream_profile, bounded_max_tokens from src.store import safe_run_key, store_root_safe, run_store_posture, index_lock_owner_path, index_lock_recovery_path, index_lock_recovery_input, acquire_index_lock, acquire_index_lock_retry, release_index_lock, rebuild_and_persist_run_index, rebuild_and_persist_run_index_result from src.watchdog import safe_base, safe_correlation_id, route_policy, usage_reconciliation, usage_reconciliation_for_rows From 428688678683e296f05008a0b2472d0888477447 Mon Sep 17 00:00:00 2001 From: Robert DeVore Date: Wed, 26 Aug 2026 10:54:29 -0400 Subject: [PATCH 2/3] docs: add current Relay architecture map --- AGENTS.md | 1 + CHANGELOG.md | 1 + README.md | 2 +- SECURITY.md | 2 +- docs/architecture-decisions.md | 2 +- docs/architecture.md | 88 ++++++++++++++++++++++++++++++++++ 6 files changed, 93 insertions(+), 3 deletions(-) create mode 100644 docs/architecture.md diff --git a/AGENTS.md b/AGENTS.md index 4c9a278..96bcba4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,7 @@ Relay is a stable local-first composition and execution layer for bounded agent ## Required Reading - `README.md` +- `docs/architecture.md` - `docs/command-reference.md` - `docs/integration-matrix.md` - `docs/launch-checklist.md` diff --git a/CHANGELOG.md b/CHANGELOG.md index 7f6171b..701c7be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ All notable Relay changes are recorded here. Relay follows semantic versioning f - Added version-negotiated Spec/Dispatch envelopes, a disabled-by-default authenticated machine authorization/audit boundary, redacted CaseFile-compatible failed-run handoff, and rotated HMAC-signed exports without changing unsigned v1. - Added bounded aggregate run metrics, committed performance budgets and benchmark harness, and a generated evidence-linked showcase gallery. - Fixed retention ordering to use validated completion/update evidence across different mission IDs, and made selected SQLite index rebuild failures propagate instead of returning a healthy run-list result. +- Simplified maintenance by isolating agent capability state, centralizing evidence limits and read-side verification, and adding a current architecture and task-navigation map. ## [1.0.0] - 2026-08-08 diff --git a/README.md b/README.md index df9315d..7f922da 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ Supported v1 target hosts are Linux and macOS. The exact release candidate must ## Repository layout -Runtime implementation lives in `src/`. The small root `main.kujo` file is the conventional Kujo executable entrypoint, `kujo.toml` and `kennel.toml` are package manifests, and `bin/relay` resolves and launches the pinned Kujo runtime. Tests, schemas, examples, release metadata, scripts, and operator documentation remain in their named directories. The root review found no duplicate implementation files to move into `src/`. +Runtime implementation lives in `src/`. The small root `main.kujo` file is the conventional Kujo executable entrypoint, `kujo.toml` and `kennel.toml` are package manifests, and `bin/relay` resolves and launches the pinned Kujo runtime. Tests, schemas, examples, release metadata, scripts, and operator documentation remain in their named directories. Start with the concise [architecture map](docs/architecture.md) to locate subsystem ownership and the relevant tests. ## Quick start diff --git a/SECURITY.md b/SECURITY.md index f36ff20..784169d 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -16,7 +16,7 @@ Provider request payloads are bounded below the bridge transport limit, provider ## Local evidence and integrity -Run evidence is stored below `RELAY_STATE_ROOT` (default `.relay`). State, events, receipts, reports, tool-result bundles, and PackWrite manifests use bounded, symlink-safe reads and fail-closed writes. Event and receipt evidence is limited to 8 MiB per bounded artifact; state reads are limited to 64 MiB; packet and exported artifact inventories have file, depth, entry, and byte limits. +Run evidence is stored below `RELAY_STATE_ROOT` (default `.relay`). State, events, receipts, reports, tool-result bundles, and PackWrite manifests use bounded, symlink-safe reads and fail-closed writes. Every parsed JSON document is limited to the pinned runtime's 1 MiB parser ceiling. Event JSONL, Markdown reports, and exported artifact inventories have separate 8 MiB envelopes plus file, depth, and entry limits. SHA-256 integrity fields detect local mutation and sequence inconsistency. They are not cryptographic signatures, identity assertions, tenant authorization, non-repudiation, or proof that an operator controls a signing key. Exports must be verified before use and remain local unsigned evidence unless an external approved signing system is applied by the release owner. diff --git a/docs/architecture-decisions.md b/docs/architecture-decisions.md index 380a7dc..5349511 100644 --- a/docs/architecture-decisions.md +++ b/docs/architecture-decisions.md @@ -1,6 +1,6 @@ # Architecture Decision Records -These ADRs preserve the context and consequences recorded when each decision landed. Later ADRs and the current [command reference](command-reference.md), [compatibility policy](compatibility.md), and [integration matrix](integration-matrix.md) supersede earlier forward-looking statements where the implementation has since advanced. +These ADRs preserve the context and consequences recorded when each decision landed. Read the concise [current architecture map](architecture.md) first. Later ADRs and the current [command reference](command-reference.md), [compatibility policy](compatibility.md), and [integration matrix](integration-matrix.md) supersede earlier forward-looking statements where the implementation has since advanced. ## ADR-001: New composition repository diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..90133ed --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,88 @@ +# Relay architecture + +This page is the current implementation map. Read it before the historical +[architecture decision records](architecture-decisions.md); the ADRs explain +why individual decisions landed, while this page describes the system as it +exists now. + +## Runtime flow + +Relay has one executable path: + +```text +main.kujo + -> src/cli.kujo parse, validate, dispatch, render + -> src/runtime.kujo mission lifecycle and run state transitions + -> src/policy.kujo workspace, command, and tool authority + -> src/adapters.kujo bounded provider and ecosystem subprocesses + -> .relay/runs/... authoritative state and evidence + -> src/store*.kujo validated, rebuildable run index +``` + +A mission follows this sequence: + +```text +mission JSON -> bounded parse and validation -> workspace provisioning +-> provider planning -> policy-checked actions and agent tools +-> ChangeBucket and Eval -> sealed state, events, receipts, and report +``` + +Fixture mode stops at deterministic local adapters. Live model traffic must +pass through Watchdog; there is no direct live-provider fallback. + +Read-side commands follow a separate, fail-closed path: + +```text +validated run index -> authoritative state -> event and receipt verification +-> required artifact verification -> inspect, verify, watch, or export result +``` + +The index is a cache. Per-run state and evidence remain authoritative. + +## Source ownership + +| File | Owns | Does not own | +| --- | --- | --- | +| `src/cli.kujo` | CLI grammar, command dispatch, output shaping, read-side evidence presentation | Mission state transitions or provider calls | +| `src/runtime.kujo` | Mission validation, lifecycle transitions, action execution, evidence production, pause/cancel/resume/cleanup/retention | CLI rendering or provider implementation | +| `src/policy.kujo` | Path, command, script, and tool authorization | Filesystem mutation or subprocess orchestration | +| `src/adapters.kujo` | Trusted dependency paths, bounded subprocess calls, provider/tool normalization | Mission policy | +| `src/capabilities.kujo` | Agent-tool capability issuance, locking, consumption, revocation, and repair posture | General filesystem/process helpers | +| `src/common.kujo` | Shared value, JSON, path, process, atomic-write, and redaction primitives | Domain lifecycle state | +| `src/contracts.kujo` | Versioned state/event/receipt constructors and integrity inputs | Persistence | +| `src/store.kujo` | Safe run discovery, cache validation, locking, rebuild, backend selection | Authoritative run behavior | +| `src/store_sqlite.kujo` | Optional SQLite index implementation | Per-run evidence | +| `src/watchdog.kujo` | Route validation and telemetry reconciliation | Provider execution | +| `src/doctor.kujo` | Environment and dependency posture | Repair beyond explicitly supported local cleanup | +| `src/enterprise.kujo` | Experimental contract import, machine authorization, handoff, signed export, aggregate metrics | Hosted service transport or tenancy | +| `src/agent_bridge.kujo` / `src/ai_bridge.kujo` | Narrow subprocess entrypoints into sibling SDKs | Relay mission authority | + +## Safety invariants + +- Public CLI and JSON behavior is versioned; compatibility rules live in + [compatibility.md](compatibility.md). +- Mission writes require both declared write authority and approval. +- Commands are tokenized direct argv and checked against explicit profiles. +- External executables and environment forwarding are bounded and explicit. +- Parsed JSON documents are limited to 1 MiB by the pinned runtime. Event + JSONL and bounded artifact inventories use separate 8 MiB envelopes. +- State, event, receipt, capability, and required artifact persistence fails + closed. +- Symlink and real-path checks are authority controls, not optional validation. +- Cleanup and retention are confirmation-gated and revalidate exact targets. + +## Where to make common changes + +| Task | Start here | Usually verify with | +| --- | --- | --- | +| Add or change a CLI option | `src/cli.kujo` command function and `help_text` | `tests/relay_cli_smoke.sh`, `tests/relay_cli_contract_smoke.sh` | +| Change mission parsing or budgets | `src/runtime.kujo::load_spec` | `tests/relay_contract_tests.kujo`, mission/budget smoke tests | +| Add a mission action | `src/runtime.kujo::execute_action`, then `src/policy.kujo` | policy contract tests plus a focused mission smoke test | +| Add an agent tool | `src/adapters.kujo::tool_schema`, normalization, then runtime execution | `tests/relay_agents_tool_smoke.sh` | +| Change run inspection/export | read-side helpers and `cmd_runs` in `src/cli.kujo` | `tests/relay_store_smoke.sh`, schema smoke tests | +| Change persistence | `src/store.kujo`; use `src/store_sqlite.kujo` only for backend-specific behavior | store, SQLite, state-store safety, and lock stress tests | +| Change provider routing | `src/adapters.kujo`, `src/watchdog.kujo`, bridge files | Watchdog and provider-tool smoke tests | +| Change a machine contract | `src/contracts.kujo` or `src/enterprise.kujo`, matching schema and compatibility docs | contract and schema suites | + +The aggregate entrypoint is `tests/relay_acceptance.sh`; the complete release +gate is `scripts/release_gate.sh`. From 340b8497ba6bd41c4b90e643eb56449850b1be76 Mon Sep 17 00:00:00 2001 From: Robert DeVore Date: Wed, 26 Aug 2026 11:08:19 -0400 Subject: [PATCH 3/3] docs: link contributor architecture guide --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index caafae6..ff82614 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,8 @@ Relay is a local-first safety boundary for bounded agent missions. Keep `main.kujo` and `bin/relay` thin, put reusable implementation under `src/`, schemas under `schemas/`, deterministic examples under `examples/`, and regression coverage under `tests/`. +Use the [architecture map](docs/architecture.md) to find subsystem ownership and the focused verification path before editing. + ## Development setup Use the pinned Kujo runtime recorded in `RUNTIME_VERSION` and the exact sibling revisions in `release/dependencies.json`. Do not make tests depend on a developer-specific directory layout; CI checks out those repositories as siblings at immutable revisions.