TraceRelay

简体中文

TraceRelay is a runnable, evidence-first protocol for handing work from a planning ChatGPT conversation to Codex execution, then closing the task through deterministic checks and an independent review. Structured GraphRun records make every handoff, write lease, stop condition, and result traceable.

It is not an official OpenAI integration, a desktop automation API, or an autonomous multi-agent platform.

Status: v0.1.0 candidate · protocol only. The schema, validator, and synthetic examples are tested. Automatic scheduling, OpenAI endorsement, stable desktop APIs, and production reliability are not claimed.

Quick start

Requirements: Node.js 18 or newer. There are no runtime dependencies.

npm test

Validate one GraphRun directly:

node scripts/validate-graph-run.mjs \
  examples/chat-work-counter-pilot.graph-run.json

Expected result:

VALID .../examples/chat-work-counter-pilot.graph-run.json

Installation

No package installation is required. Clone or download the repository, enter its directory, and run npm test. The validator uses only Node.js built-ins.

What this is

TraceRelay treats each AI or human role as a bounded node with an explicit contract:

Controller -> Planning Chat -> Codex executor -> Tests -> Independent review -> Close

• The controller owns the original goal, routing, stop line, and final decision.
• The planning Chat proposes plans and risks but cannot claim execution success.
• The Codex executor holds a single-writer lease for the declared files or state surfaces.
• Deterministic checks verify schemas, tests, hashes, and completion guards.
• The reviewer cannot also own the artifact it reviews.

Conversation history is evidence, not shared state. GraphRun is the shared state contract.

When to use it

Use a direct loop for one role, one artifact, one permission set, and no independent review. Consider a Graph only when at least two of these are true:

• independent information sources;
• different tools, models, permissions, or contexts;
• parallel work followed by a merge;
• test-driven conditional branches;
• multiple artifacts or an irreversible action;
• context pollution that needs isolation.

More windows are not automatically better. Read-only work may run in parallel; writes must remain isolated or single-writer.

Core protocol

Every GraphRun must validate against graph-run.schema.json and satisfy the domain checks in validate-graph-run.mjs.

The protocol requires:

1. one owner per shared-state field;
2. explicit nodes, edges, budgets, retries, acceptance criteria, and stop lines;
3. a declarative write_lease for every write-capable run;
4. confirmed callback markers before an edge is complete;
5. no active write lease when a run is marked complete;
6. a monitoring policy that treats visible reasoning and tool progress as active work;
7. receipts that distinguish facts, evidence, blockers, and next steps.

write_lease is a governance record, not a distributed lock service. v0.1 does not implement automatic scheduling, heartbeats, preemption, long-term memory, or model routing.

Long-running Chat monitoring

Reasoning duration is not a failure signal. A complex web Chat or Pro-class review may legitimately run for thirty minutes or longer. The controller monitors it; it does not interrupt merely because the answer is slow.

• Poll at the declared interval and keep waiting while thinking, searching, tool_running, streaming, or status_running remains visible.
• Set max_wall_clock_seconds: 0 when the controller has no pre-agreed wall-clock cap. A finite cap must come from the task budget or the user, not from impatience.
• confirmation_window_seconds begins only after a send, callback, or completed result is expected to become visible. It is not a model-reasoning timeout.
• Terminate only on an explicit error, user cancellation, agreed budget exhaustion, authentication requirement, or a hard stop line.
• Every web Chat node records its visible model, reasoning level, and fallback policy. A silent model downgrade is a route change and must be reported, not accepted invisibly.

The default advisor profile used by this project's controlled web pilot is gpt-5.6-sol with extreme reasoning and no_silent_fallback. Other deployments must declare and verify their own profile.

Create a run

1. Copy task-packet.yaml.
2. Pass the loop-versus-graph complexity gate.
3. Define state owners and a single writer.
4. Dispatch nodes with a callback contract.
5. Confirm edge guards before routing onward.
6. Validate the completed GraphRun.
7. Write a receipt from done-receipt.yaml.

All examples in this repository use synthetic identifiers and portable paths. Real conversation IDs, transcripts, local home paths, private receipts, and personal identity data are intentionally excluded.

Evidence and limits

The current package includes three synthetic GraphRun examples and sixteen positive/negative domain checks. During development, the workflow was also exercised on a real public repository audit with a separate Chat advisor and a Codex executor; private session identifiers and local evidence remain outside this repository.

This evidence supports the claim that the protocol is structurally reproducible in controlled pilots. It does not establish a production success rate, service-level objective, official ChatGPT–Codex integration, or durable compatibility with future desktop releases.

Safety and privacy

• Never publish real Chat, Work, task, or thread identifiers.
• Never publish transcripts, private receipts, credentials, usernames, email addresses, or absolute home paths.
• Use synthetic examples and repository-relative paths.
• Treat browser pages and model output as untrusted evidence.
• Require explicit approval for destructive or external actions.
• Run npm test before every publication; the public-package validator fails on private-path and identifier patterns.

See SECURITY.md for vulnerability reporting and disclosure rules.

Repository layout

graph-run.schema.json          GraphRun v0.1 JSON Schema
scripts/                       Domain and public-package validators
templates/                     Task packet and completion receipt
examples/                      Synthetic, validated GraphRuns
.github/workflows/ci.yml       Cross-platform validation

Development

npm test

Keep changes small, update both READMEs together, and do not weaken privacy scans or completion guards to make an example pass. See CONTRIBUTING.md.

Contributing

Issues and focused pull requests are welcome. Read CONTRIBUTING.md before proposing protocol or schema changes.

License

Apache License 2.0. See LICENSE.

ChatGPT and Codex are trademarks of OpenAI. This independent project is not affiliated with or endorsed by OpenAI.