English | 中文

OPL Relay

A private, evidence-backed communication layer for Codex and One Person Lab

Mail evidence · Relationship context · Approved memory · Obsidian context · Apple Mail review

OPL Relay helps Codex work with your academic and professional email without turning a source checkout or plugin cache into a personal-data folder. It keeps the original messages as evidence, builds reusable relationship context, and routes drafts through Apple Mail for human review before any send.

OPL Relay is a standalone communication product. It can be installed and used on its own, and it collaborates with OPL Persona through explicit, reviewed handoffs.

Relay has one public product, Package, Plugin, Skill, and CLI identity: opl-relay. The internal Python module name is not another user-facing mail entry point.

What You Can Ask It To Do

• "Review the last three days of mail and tell me what needs a decision."
• "Find my previous exchanges with this person and draft a reply in the same relationship context."
• "Create the reply in Apple Mail. Let me review it there, and do not send it."
• "Show the evidence behind this relationship memory before I approve it."
• "Use the approved Persona proposal to create a mail draft, without sending."

Core Capabilities

Evidence-first mail

Relay synchronizes configured IMAP folders into a private local SQLite store. Search results and context use stable email-store:// references so a draft can be traced back to the source message.

Relationship context with approval

Long-lived memory is proposed with source evidence. It becomes active drafting context only after explicit approval.

Read-only Obsidian context

Selected Markdown paths can be indexed as a read-only source. Relay never writes back to the vault.

Apple Mail review

Relay creates a real Apple Mail draft, reads it back, and binds approval to its current fingerprint. Editing the draft invalidates an earlier approval.

Persona handoff

OPL Persona can hand an approved, evidence-linked mail context to Relay. Relay still owns the account, recipients, Apple Mail draft, and separate send gate.

How The Pieces Fit

Surface	What it contains	Who manages it
Git repository	Source code, tests, Plugin files, Skills, and Package descriptor	Git / maintainers
Codex Plugin snapshot	Installed communication instructions and carrier metadata	Codex
Relay engine	The opl-relay CLI and local mail implementation	Embedded in the Codex Plugin native carrier; Relay keeps mail semantics and the carrier keeps physical installed state
Profile Workspace	Mail databases, account references, approved memory, policies, and Persona state	The user

The selected Profile Workspace is the only user-data root:

~/OPL/profiles/<profile>/
  profile/
  policies/
  context/
  templates/
  exports/
  data/
    relay/
    persona/

Relay always uses <profile>/data/relay. Reinstalling or updating code must not move, replace, or publish that directory.

Install The Codex Plugin From GitHub

The public repository can be added as a Git-backed Codex Marketplace:

codex plugin marketplace add gaofeng21cn/opl-relay --ref main --json
codex plugin list --marketplace opl-relay --available --json
codex plugin add opl-relay@opl-relay --json
codex plugin list --marketplace opl-relay --json

To refresh the Git marketplace and reinstall the current Plugin snapshot:

codex plugin marketplace upgrade opl-relay --json
codex plugin remove opl-relay@opl-relay --json
codex plugin add opl-relay@opl-relay --json

Start a new Codex task after installation so the new Plugin snapshot is loaded.

Distribution boundary: this command installs the Codex Plugin directly from GitHub. OPL App uses the separate GHCR Package channel described below; both deliver the same public Relay carrier but have independent lifecycle authorities.

Start With A New Profile

Requirements: macOS, Apple Mail for draft review, and an IMAP account.

export OPL_PROFILE_WORKSPACE="$HOME/OPL/profiles/my-profile"
opl-relay --json setup init
opl-relay --json account add \
  --id work --email you@example.com --host imap.example.com
opl-relay --json credential set --account work
opl-relay --json account check --account work --connect

setup init is idempotent and creates only missing Profile templates and empty configuration files. account add writes IMAP metadata only. The password prompt is separate and stores the secret in macOS Keychain, never in the conversation, command arguments, Profile Workspace, or Git.

The local-source developer path remains available:

git clone https://github.com/gaofeng21cn/opl-relay.git
cd opl-relay
make install-local

A Typical Workflow

opl-relay --json accounts
opl-relay --json sync --account work --mode incremental
opl-relay --json recent --account work --limit 20
opl-relay --json search "project or person" --account work
opl-relay --json read 'email-store://...'
opl-relay --json context build --person "Professor Example" --query "invitation"

Create and inspect an Apple Mail draft:

opl-relay --json draft create \
  --account work \
  --to 'Recipient <recipient@example.test>' \
  --subject 'Subject' \
  --body-file ./draft.txt

opl-relay --json draft inspect 'mail-draft://apple-mail/work/UUID'
opl-relay --json draft open 'mail-draft://apple-mail/work/UUID'

For an existing multi-recipient Apple Mail thread, Reply All is the default. Use Mail's native Reply All route instead of creating a new message or rebuilding recipients from the latest flattened record. The complete To/Cc route, quoted chain, and provider threading headers are part of the reply context. Do not remove existing participants unless the user explicitly requests a private reply or confidentiality clearly requires it. Use the exact account, numeric message id, and mailboxPath returned by the Apple Mail local screen:

opl-relay --json draft reply-all \
  --account work \
  --apple-mail-account 'Work' \
  --apple-mail-id 12345 \
  --mailbox-path 'INBOX/Conference' \
  --body-file ./reply.txt

Relay does not reconstruct recipients from a flattened mail record. It rejects self-addresses, duplicates, Bcc, empty recipient sets, and ambiguous source tuples before registering the stable review draft. The saved draft is the review surface; provider-native Reply All is the routing authority.

The body file contains only the new response, which is inserted above Apple Mail's configured signature. Do not duplicate the account signature or replace the quoted content. After saving, reread the draft and verify the complete To/Cc route, subject, exactly one signature, In-Reply-To/References, and at least one recognizable quoted-thread anchor. If any item is missing, restart from the source message with native Reply All instead of repairing the thread from memory.

Sending is a separate, explicit action. Inspect the current draft after review and use only the fingerprint returned by that readback. Any content change invalidates the earlier approval, and an unknown send result is never retried automatically.

OPL App Distribution Status

Relay declares an OPL Capability Package, while publication and physical installation remain separate authority surfaces:

Relay owner descriptor + immutable GHCR publication
  -> OPL Base download / verify / bytes handoff
  -> configured native carrier install / update / repair / uninstall
  -> native installed readback
  -> Framework discovery / carrier delegation / aggregation
  -> OPL App generic Package projection

The contracted stable Package source is ghcr.io/gaofeng21cn/one-person-lab-packages/opl-relay:latest-stable. Package publication must be read from the public immutable GHCR digest. Installed/current state must be read separately from the configured native carrier; Framework only delegates actions and aggregates that readback for App. GitHub remains the source and Codex Plugin Marketplace input; GitHub Releases are not part of Relay distribution. See Distribution for the authority and availability boundaries.

Safety Boundary

• User mail, account configuration, SQLite files, raw EML, sync cursors, private policies, Obsidian paths, and credentials never belong in Git or a Plugin cache.
• Relay is read-first. Delete, archive, move, and mark are not exposed.
• A Persona approval does not authorize mail sending.
• Apple Mail draft review and fingerprint-bound send approval remain separate.

Documentation

• Distribution and update model
• Architecture
• Profile Workspace
• Runtime contract
• Relay, Persona, and OPL App

Development

python3 -m pip install -e . pytest
make test
make validate-package

The repository CI also validates the Plugin structure and exercises discovery and installation through an isolated local Codex Marketplace.

License

Apache License 2.0