Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 2 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion docs/architecture-decisions.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down
88 changes: 88 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
@@ -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`.
3 changes: 2 additions & 1 deletion src/adapters.kujo
Original file line number Diff line number Diff line change
@@ -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

Expand Down
4 changes: 2 additions & 2 deletions src/agent_bridge.kujo
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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) {
Expand Down
Loading
Loading