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
2 changes: 1 addition & 1 deletion .codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "lossless-openclaw-orchestrator",
"version": "1.6.1",
"version": "1.7.0",
"description": "Index, search, and prepare local Codex sessions with LCO, including one-shot thread title aliases for easier recall.",
"author": {
"name": "100yenadmin",
Expand Down
22 changes: 20 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -310,8 +310,10 @@ For an agent or MCP client, start with the normal operator path:
| 5 | `lco_recent_sessions` | Recent and active Codex work as compact cards. |
| 6 | `lco_attention_inbox` | Blocked, waiting, stale, approval-needed, or ready-for-review work. |
| 7 | `lco_project_digest` | A project-level handoff brief. |
| 8 | `lco_codex_control_dry_run` | A preview packet for the exact Codex action. |
| 9 | `lco_codex_resume_thread` | Resume a Codex thread after the dry-run packet is approved. |
| 8 | `lco_codex_control_route` | An expiring opaque reference for one daemon-owned Codex task, or an explicit Desktop-observation blocker. |
| 9 | `lco_codex_deliver` | A dry-run-first delivery that sends when idle or steers the matching active turn. |
| 10 | `lco_codex_control_dry_run` | A preview packet for a lower-level exact Codex action. |
| 11 | `lco_codex_resume_thread` | Resume a Codex thread after the dry-run packet is approved. |

The packaged agent playbook is
[skills/lossless-openclaw-orchestrator/SKILL.md](skills/lossless-openclaw-orchestrator/SKILL.md).
Expand Down Expand Up @@ -377,12 +379,28 @@ mcp_servers:
enabled: true
env:
LCO_TOOL_PROFILE: standard
LCO_CODEX_TRANSPORT: daemon
```

Omitting `LCO_DB_PATH` uses LCO's home-based default. If you set it explicitly,
use an expanded absolute path because Hermes does not shell-expand `~` inside an
environment-variable value.

`LCO_CODEX_TRANSPORT` defaults to `stdio` for compatibility. The opt-in
`daemon` mode connects only to the already-running local Codex managed daemon
through its Unix socket. LCO does not start or restart the daemon and does not
enable Codex Remote Control. Set `LCO_CODEX_DAEMON_SOCKET` only for an explicit
absolute local override; `LCO_CODEX_APP_SERVER_ARGS` remains stdio-only.

For remote operation, Eva should call `lco_codex_control_route` first. A
selected `app_server` route is safe for LCO daemon/CLI task control. A
`desktop_observation_required` result means Hermes must use its own
`computer_use` integration to identify and operate the Codex Desktop task;
LCO must not silently redirect that task to the managed daemon. Telegram
direction is user to Eva for instructions and Eva to the same user for results.
An operator should not type a bot message into Telegram as though it came from
Eva.

Before a release, verify the candidate without changing a Hermes profile:

```bash
Expand Down
2 changes: 1 addition & 1 deletion docs/BETA_RELEASE_RUNBOOK.md
Original file line number Diff line number Diff line change
Expand Up @@ -445,7 +445,7 @@ Record `npm dist-tag ls lossless-codex-orchestrator` in the release evidence
after every npm publication. Stable releases publish with
`npm publish --tag latest`; public betas publish with `npm publish --tag beta`;
release candidates publish with `npm publish --tag next`. The stable channel
target for this package version is `1.6.1`; npm `latest` must move only after
target for this package version is `1.7.0`; npm `latest` must move only after
the separate stable-promotion gate proves the exact candidate. Keep beta and
other prereleases on prerelease tags. Do not publish a fake stable package just
to move a dist-tag. Release candidates must publish with `npm publish --tag next`;
Expand Down
14 changes: 10 additions & 4 deletions docs/CLAIM_AUDIT.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,16 @@
# Public Claim Audit

## Allowed 1.6.1 Stable Claim
## Allowed 1.7.0 Stable Claim

This wording becomes allowed only after npm, Git tag, and GitHub Release
publication truth agree for the exact candidate. The current source version
alone does not authorize it.

Coordinate local Codex work through Hermes/MCP, with OpenClaw compatibility,
using bounded recall and session diffs, audited review-then-drive dry-runs,
approved disposable-target Codex controls, and read-only LCM prepared state;
Claude targeting remains dry-run only.
approval-bound daemon/CLI task routing and delivery, Hermes Computer Use for
Desktop-owned tasks, and read-only LCM prepared state; Claude targeting remains
dry-run only.

This claim covers the stable local recall and control-plane paths with tests and smoke coverage: Codex indexing/search/describe/expand, session-diff cursors, review-then-drive dry-run packets with budgets, Claude Code read/recall and dry-run adapter states, prepared cards/inbox and summary leaves, read-only LCM peer DAG expansion and peer diagnostics, and approval-bound Codex scratch controls with post-action refresh proof where the release evidence records them.

Expand Down Expand Up @@ -56,6 +57,11 @@ across the orchestrator surfaces that share the same local index.
through `lco hermes smoke` plus `lco release hermes-readiness`.
- A Hermes readiness pass is candidate evidence. It is not publication, an
active profile install, live Eva runtime safety, or native-adapter proof.
- Daemon control is opt-in, local-only, and binds an expiring opaque target to
an already-running managed Codex daemon. It does not start or restart Codex,
enable Remote Control, expose raw identifiers, or own Desktop turns.
- Desktop-owned tasks remain on Hermes Computer Use and require window,
composer, and direction verification in the named Eva runtime canary.
- Live Codex control is approval-gated by a dry-run audit id; the public demo stops at dry-run unless the user explicitly approves a target thread.
- CUA Driver is the preferred fallback backend, but no no-focus behavior is claimed without local proof.
- Peekaboo is a secondary macOS fallback for permission diagnostics and guarded snapshots; desktop action remains dry-run-only.
Expand Down Expand Up @@ -102,7 +108,7 @@ blockers instead of allowing a working-app claim.

Install stable releases through the `latest` dist-tag, public betas through the
`beta` dist-tag, and release candidates through `next`. The stable channel
target for this package version is `1.6.1`; npm `latest` must move only after
target for this package version is `1.7.0`; npm `latest` must move only after
the separate stable-promotion gate proves the exact candidate. Keep beta and
other prereleases on prerelease tags. Do not publish a fake stable package just
to move a dist-tag.
Expand Down
19 changes: 17 additions & 2 deletions docs/HERMES_ADAPTER_BOUNDARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ index, safe-summary recall, and approval/audit patterns used by other
MCP-capable harnesses. OpenClaw remains a supported compatibility surface.

This document does not prove a native Hermes adapter, Hermes-specific indexing,
Hermes control surfaces, parity, GUI mutation, or cloud sync.
unrestricted control parity, generic GUI mutation, or cloud sync.

## What "Hermes support" means today

Expand All @@ -27,6 +27,20 @@ mounts LCO exactly as any generic MCP client does:
proof) with the same approval-gated dry-run/control boundaries Codex and
OpenClaw get.

For Eva-owned CLI tasks, set `LCO_CODEX_TRANSPORT=daemon`. The MCP server then
connects to the already-running local managed Codex daemon over its Unix socket.
`lco_codex_control_route` returns an expiring opaque target and
`lco_codex_deliver` chooses idle send or matching active-turn steer. The public
result never returns raw thread or turn identifiers, transcript items, or the
socket path. LCO does not start or restart Codex, enable Remote Control, or
silently fall back to stdio when daemon mode is requested.

Codex Desktop remains a separate ownership boundary. When LCO returns
`desktop_observation_required`, Hermes uses its existing `computer_use`
integration for window identification, visual verification, composer input,
and the Desktop-owned turn. LCO does not claim the managed daemon owns that
turn and does not enable generic `lco_desktop_act`.

This is the primary first-class supported path: the Hermes and
generic-MCP mounting recipes are covered by [SETUP.md](SETUP.md). Release candidates exercise
initialization, silent notifications, tool listing and calls, structured-result
Expand All @@ -38,7 +52,8 @@ is not is a Hermes-native integration with Hermes-specific ergonomics.
- No native Hermes adapter, plugin manifest, or Hermes-side install command.
- No Hermes session indexing. LCO indexes Codex sessions; Hermes agents read
that Codex index through LCO, they are not themselves an indexed source.
- No Hermes-specific control, GUI mutation, or remote-control surface.
- No native Hermes control protocol or generic GUI mutation. Hermes can invoke
the shared LCO daemon-control tools and its own Computer Use integration.
- No claim that Hermes-specific auth, scopes, or lifecycle events are wired.
- The generic-MCP protocol boundary applies: only `initialize`, `tools/list`,
and `tools/call` are implemented; no MCP resources, prompts, or sampling.
Expand Down
37 changes: 33 additions & 4 deletions docs/SETUP.md
Original file line number Diff line number Diff line change
Expand Up @@ -345,12 +345,38 @@ mcp_servers:
enabled: true
env:
LCO_TOOL_PROFILE: standard
LCO_CODEX_TRANSPORT: daemon
Comment thread
100yenadmin marked this conversation as resolved.
```

Omitting `LCO_DB_PATH` uses LCO's home-based default. If you set it explicitly,
use an expanded absolute path because Hermes does not shell-expand `~` inside an
environment-variable value.

`LCO_CODEX_TRANSPORT` defaults to `stdio`. Set it to `daemon` only when the
local managed Codex daemon is already running. LCO connects through the
standard socket under `CODEX_HOME`, or an explicit absolute
`LCO_CODEX_DAEMON_SOCKET`. It never starts or restarts Codex, never enables
Codex Remote Control, and never falls back from a requested daemon to stdio.
`LCO_CODEX_APP_SERVER_ARGS` applies only to stdio mode.

The remote-control loop is:

1. Call `lco_codex_control_route`, optionally with a title hint.
2. If it selects `app_server`, call `lco_codex_deliver` in its default dry-run
mode and show the approval packet.
3. Repeat the exact call with `dry_run:false` and the matching
`approval_audit_id`. LCO sends to an idle task or steers the matching active
turn after revalidating ownership and state.
4. Use `lco_codex_interrupt_thread` with the same opaque `target_ref` for an
approved interrupt.
5. If the route is `desktop_observation_required`, use Hermes
`computer_use` to verify and operate the Codex Desktop window. Do not assume
the managed daemon owns a Desktop task.

For Telegram, the remote instruction must originate from the user and arrive
at Eva. Eva returns the result to that same conversation. Typing a Telegram
message as Eva is not a valid inbound-control test.

`lco_find` queries the existing index by default. It does not synchronously
reindex unless the call explicitly passes `index:true`; `lco_index_sessions`
remains the explicit refresh tool.
Expand Down Expand Up @@ -384,7 +410,7 @@ lco release hermes-readiness \
```

The smoke checks initialization, notification silence, Eva's required
14-tool registration set, object-valid structured results, default search
16-tool registration set, object-valid structured results, default search
behavior, and bounded latency. The readiness report binds that smoke to the
candidate package probe. Both reports are public-safe candidate evidence only:
they do not prove publication, an active profile install, or live Eva runtime
Expand Down Expand Up @@ -565,10 +591,13 @@ The safe loop is:
4. `lco_codex_extract` with `kind: "plans"`, `kind: "final_messages"`, and
`kind: "touched_files"`
5. `lco_expand_session` or `lco_expand_query`
6. `lco_codex_control_dry_run` only when action is needed
7. `lco_codex_start_thread` only after dry-run approval when a new Codex thread
6. `lco_codex_control_route` for the current daemon-owned task
7. `lco_codex_deliver` in dry-run mode, then live with the exact matching
approval id
8. `lco_codex_control_dry_run` for lower-level explicit actions
9. `lco_codex_start_thread` only after dry-run approval when a new Codex thread
is needed
8. live action only with a matching `approval_audit_id`
10. live action only with a matching `approval_audit_id`

Live start/send/steer/interrupt results distinguish `accepted_by_transport`,
`started`, `completed`, `persisted`, and `unverified_pending`. If a result is
Expand Down
3 changes: 2 additions & 1 deletion docs/releases/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@ One line per released version, newest first. Each line links to the full
release notes for that version. Draft notes stay outside the released list
until npm, tag, and GitHub Release truth agree.

Draft candidate notes: [1.6.1](RELEASE_NOTES_1.6.1.md)
Draft candidate notes: [1.7.0](RELEASE_NOTES_1.7.0.md)

- [1.6.1](RELEASE_NOTES_1.6.1.md)
- [1.6.0](RELEASE_NOTES_1.6.0.md)
- [1.5.0](RELEASE_NOTES_1.5.0.md)
- [1.4.5](RELEASE_NOTES_1.4.5.md)
Expand Down
53 changes: 53 additions & 0 deletions docs/releases/RELEASE_NOTES_1.7.0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Release Notes 1.7.0

`1.7.0` is the Eva remote control candidate for local Codex sessions. These
notes describe the candidate; npm `latest` and GitHub Releases remain the
publication authorities.

## Highlights

- Opt-in `LCO_CODEX_TRANSPORT=daemon` support for WebSocket JSON-RPC over the
already-running local Codex managed daemon Unix socket.
- `lco_codex_control_route`, which selects one daemon-owned active or idle task
and returns an expiring opaque target, or explicitly requires Desktop
observation.
- `lco_codex_deliver`, which uses the existing approval audit to send to an
idle task or steer the matching active turn after revalidating ownership,
state, and turn identity.
- Opaque-target interrupt support on `lco_codex_interrupt_thread` while keeping
the existing raw-ID compatibility form.
- Hermes smoke registration coverage for the two new first-class tools.

## Upgrade

```bash
npm install -g lossless-codex-orchestrator@latest
lco doctor
```

Existing installations keep stdio behavior unless
`LCO_CODEX_TRANSPORT=daemon` is set explicitly.

## Validation

The release checks cover Unix-socket reconnects, opaque target selection,
idle-send and active-steer delivery, stale-target rejection, notification
silence, structured MCP results, and package installation.

## Safety boundary

- Stdio remains the public compatibility default.
- Daemon mode never starts or restarts Codex, enables Remote Control, or falls
back silently to stdio.
- Raw transcript items may be transiently projected by Codex only to identify
the current active turn; LCO immediately discards the items and never returns
or logs them.
- Codex Desktop tasks stay on Hermes Computer Use. The managed daemon is not
treated as the owner of Desktop turns, and generic GUI control stays off.
- Every live delivery or interrupt still requires the matching unexpired
dry-run approval audit.

## Availability

Until npm `latest` and GitHub Releases list 1.7.0, this file describes upcoming
behavior rather than an available stable package.
Loading