diff --git a/.github/workflows/verify.yml b/.github/workflows/verify.yml index 95070fda..33561404 100644 --- a/.github/workflows/verify.yml +++ b/.github/workflows/verify.yml @@ -26,7 +26,7 @@ jobs: node-version: "22" cache: npm - name: Install isolation test dependencies - run: sudo apt-get update && sudo apt-get install -y bubblewrap tmux + run: sudo apt-get update && sudo apt-get install -y bubblewrap tmux python3-yaml - name: Verify isolation support run: bwrap --unshare-all --die-with-parent --ro-bind / / /bin/true - name: Install diff --git a/docs/design/plexus-architecture.mmd b/docs/design/plexus-architecture.mmd new file mode 100644 index 00000000..63a9c4f8 --- /dev/null +++ b/docs/design/plexus-architecture.mmd @@ -0,0 +1,34 @@ +flowchart LR + Client["Client or waker"] -- "channel mode" --> Channel["Stable channel"] + Channel --> Queue["Channel queue"] + Channel --> Session["Current session"] + Queue --> Journal["Graph event journal"] + Session --> Journal + Wake["Codex queued wake evidence"] --> Journal + Wake -. "planned waker integration" .-> Queue + Compaction["Codex compaction evidence"] --> Journal + Module["Registered module"] --> Contract["Versioned JSON contract"] + Contract --> Journal + Queue -- "bound receipt" --> Session + CloudAccount["Cloud account binding"] -. "planned routing" .-> Queue + Yaml["Bounded YAML decoder"] --> Restart + Restart["Restart state contract"] --> StatePrep["Reserved state preparation"] + Restart --> RoleProfile["Role-scoped launch plan"] + RoleProfile -. "synthetic rehearsal" .-> Rehearsal["In-memory handover rehearsal"] + RoleProfile -. "isolated assessment" .-> IsolatedRollback["Owned isolated rollback"] + IsolatedRollback -. "live handover blocked" .-> Handover + RoleProfile -. "planned runtime launch" .-> Handover + StatePrep --> Journal + StatePrep --> Revalidate["Restart state revalidation"] + Revalidate -. "planned lifecycle exclusion" .-> Handover + TriggerTxn["Trigger transaction engine"] --> TriggerJournal["Private trigger journal"] + TriggerRecovery["Explicit uncertain recovery"] --> TriggerJournal + TriggerTxn -. "planned scheduler adapters" .-> Handover + Notice["Successor notice formatter"] -. "planned publication" .-> Handover + Observation["Codex notice snapshot"] -. "planned finality check" .-> Handover + Handover["Handover"] -. "planned verified cutover" .-> Channel + Channel -. "pure switch model" .-> Drain["Observe queued deliveries"] + Drain -. "then reserve" .-> Notice + AutoWake["Auto-wake observation disabled"] -. "consumption unproven" .-> Wake + Wake -. "bound native proof" .-> Drain + ClaudeReadback["Local Claude transcript observer"] -. "observed inbox record" .-> Drain diff --git a/docs/design/plexus-channels.md b/docs/design/plexus-channels.md new file mode 100644 index 00000000..116c5c03 --- /dev/null +++ b/docs/design/plexus-channels.md @@ -0,0 +1,325 @@ +# Channel transition prototype + +The public [architecture diagram](plexus-architecture.mmd) distinguishes +implemented components from planned links. Keep its source in +`scripts/plexus-diagram.mjs` synchronized; the readiness check compares them. + +`channel-state.mjs` defines pure JSON transitions for a stable channel, its +current session and a queue. An in-flight message is bound to a session and +generation. A handover stops new dispatch and cannot finish while a delivery is +unresolved. Only a matching acceptance receipt resolves an in-flight message. +Channel identifiers may start with `#`; the prefix is part of the identifier. + +The graph command now persists channel creation, enqueue and handover start as +events under the graph writer lock. Queued messages survive replay and +compaction. The graph and event log contain message bodies and must remain +private; this is not a scoped remote API. +Channel operations reject a non-private or non-canonical graph directory and +reject existing graph, checkpoint, snapshot or event files with unsafe owner, +permissions, links or file type. They do not silently repair existing state. + +The graph command can also reserve a pending message and record a matching +acceptance receipt. Reservation is durable before transport; a crash or +uncertain outcome leaves the item in flight and blocks handover. A local +caller is responsible for verifying transport receipts before recording them. +For a local Claude in-flight item, the waker may recover without resending only +after a stable transcript independently proves the correlated enqueue and user +message. The graph rechecks the session, generation, payload and phase before +settling, and rechecks transcript file identity and metadata under the graph +lock; missing, changed or ambiguous evidence leaves the item unresolved. This +narrows a race but does not exclude a transcript writer after the check or +provide an immutable audit copy. It does not establish delivery for cloud or +Codex recipients. + +Handover completion is disabled until an adapter can verify that the old +session wrote its state. A path or caller assertion is not sufficient proof. +`handover-state-proof.mjs` prepares the file-verification part: it binds a +correlated actor response to a session, nonce, filename and SHA-256, and checks +the private file without following a final symlink. `requestStateProof` obtains +the response through the existing native correlated-result transport; Codex +resume remains disabled. The verifier decodes and validates the restart block, +but does not reconcile its triggers or make a graph cutover. +`channel prepare-state` durably reserves a single correlated request before +contacting the current session, then records the validated state digest only if +the same handover, session and generation remain current. Messages may still be +queued while the request runs. A failure or lost response leaves the request +unresolved and prevents an automatic resend; recovery is not yet implemented. +The proof does not authorize cutover, archive, or final-message publication. + +`trigger-transaction.mjs` supplies a generic transaction engine, not a live +scheduler adapter. Its injected journal must atomically reserve overlapping +trigger sets and durably record intent before each move. Its adapter must +compare the original target and a never-reused state version atomically and +expose the operation ID on readback. Definite refusal rolls back earlier verified moves using the same +compare-and-set contract; an ambiguous result stays unresolved and is not +retried. A failed preflight read records a terminal not-applied receipt before +releasing its reservation; no trigger move has been attempted. Dry-run reads +and journals a plan without moving triggers. Concrete +timer and cloud adapters are not yet provided; this +engine is not authorization to change live triggers. + +`trigger-journal.mjs` implements the local journal in an explicitly selected, +private canonical directory. It reserves overlapping trigger sets atomically, +persists snapshots using fsync and atomic replacement, and rejects reused +transaction IDs. Uncertain transactions keep their reservation after restart. +A leftover lock requires operator reconciliation; it is never removed as stale +automatically. The journal is a trusted local operator component and does not +itself prove a scheduler change. Explicit recovery of an `uncertain` receipt +first inspects every trigger and rolls back only versions linked to the original +operation; other changes remain unresolved. A recovery lock prevents concurrent +recovery. Abrupt process loss while an operation is still `applying` or +`rolling-back`, or an abandoned lock, requires separate operator reconciliation. +The prepared Codex path additionally requires a fresh unarchived native-thread +observation and exactly one detected writer. Claude and cloud successors are +not yet supported by this operation. + +`cloud-account-binding.mjs` prepares an opt-in Claude CLI account check. A +private operator profile binds an account scope to a CLI configuration directory +and a digest of its reported account and organization; the helper checks the +same profile before and after an operation and treats changes as uncertain. +The native cloud transport can opt into this binding with an explicitly scoped, +private `agent-mesh.cloud-account.v1` profile. The queued comms replay binds the +profile digest and scope, refusing a changed profile. Its provider acknowledgement +still proves queue acceptance only; it does not prove that the recipient read it. +The channel waker can opt in with a private profile directory; it routes a scoped +cloud session once and keeps the message in flight until independently verified. +There is no cloud readback reconciliation yet, so this route is not operational +for handover and deliberately blocks subsequent delivery. Account checks +cannot exclude a non-cooperating concurrent switch that is changed and restored +between the checks; the profile and account directory require operator control. +Profile configuration and digests are private. This check relies on a trusted +CLI and configuration directory, does not prevent a concurrent credential +switch, and is not provider readback or proof of delivery. The route is disabled +by default. + +This is not yet a complete handover workflow: it does not write state for the +old session, publish or verify the old session's final notice, archive anything, +or reconcile uncertain transport outcomes. It must not be used for a live +handover until those steps and their failure recovery are implemented and +verified. The local graph is a trusted operator interface, not a remote API. + +`handover-notice.mjs` builds a notice from already resolved identifiers. It +supports same-project cloud anchors, cross-project cloud URLs and Codex thread +URLs. Its transcript comparison is only a predicate: an authenticated adapter +must independently supply a complete observation and prove the successor's +identity. Formatting or matching caller-supplied data alone is not evidence of +publication, finality or authorization to archive. + +`handover-codex-observation.mjs` can inspect a bounded local Codex transcript +snapshot for a correlated request followed by the exact final notice and a +matching completed turn. It fails closed for ambiguous files, malformed or +partial records, and identity mismatches. It returns hashes, never transcript +contents. This observation is local evidence at the instant read, not proof +that no later turn can arrive; safe finality still requires exclusive lifecycle +control and an authenticated source. + +`handover-claude-observation.mjs` performs a comparable local Claude snapshot +check bound to session, request nonce, exact notice and completed turn. It +rejects later user turns and tool calls. Both observers return evidence only; +neither sends a message, proves remote cloud delivery, or enables a cutover. + +`handover-notice-transport.mjs` can enqueue a correlated final-notice request +through the existing local native transport and independently inspect the +resulting local transcript. Queue acceptance is not publication proof. The +caller must first durably reserve the request, verify the successor, and hold +exclusive lifecycle control; a failed or held enqueue must not be retried +blindly. These prerequisites are not yet connected, and this adapter is not +wired to cutover or cloud delivery. A graph `channel reserve-notice` transition +requires verified state and a freshly verified Codex successor, binds the +notice digest and nonce, and survives replay. The adapter can bind an enqueue +to that reservation. `channel observe-notice` records a matching local +transcript snapshot against the reservation, but does not acquire lifecycle +exclusion or establish that a later turn cannot occur. The actual cutover +remains disabled. +# Role-scoped restart preparation + +The `agent-mesh.restart.v1` YAML handover block requires `role_profile` when +used as a state proof. Its schema `agent-mesh.role-profile.v1` contains `role` +and unique identifier arrays `permissions`, `mcp`, and `plugins`. These are +references, not commands or grants. A trusted private authority must resolve +them and reject out-of-scope or human-gated permissions. A missing profile +fails handover preparation; legacy readers may still parse old state. + +The isolated role-launch planner probes only the configured MCP names. An +unreachable MCP is omitted and listed in the receipt without blocking startup. +The launch assessor reports the observed MCP count and startup tokens, or null +when tokens are unavailable; an unexpected permission prompt or component +requires rollback. These are preparation primitives only: no provider startup, +permission enforcement, live rollback or token collector is connected yet. The approved handover remains disabled until native evidence +and those adapters are present. + +`handover-dry-run.mjs` rehearses only in memory; it never contacts native +sessions, MCPs or timers. Its synthetic fault tests cover two roles, offline MCP, +permission prompt, interrupted start, quota exhaustion and a queued message. +It does not verify native delivery, rollback or the real pilot. + +An optional stdio probe resolves MCP names exclusively through a trusted +operator-supplied allowlist and launches without a shell. On Linux the probe +uses bubblewrap with a separate PID namespace and a strict stdin gate; it checks +the namespace init owner, parent and namespace identity before releasing the +command. The gate requires an explicit permit and rejects EOF or partial input; +a missing gate acknowledgement is a containment error, not an offline result. +It requires an MCP initialization response and ping, bounds output and time, +then terminates the owned process group and waits for wrapper closure. Missing +or unverified containment stops planning instead of classifying the MCP offline. +A synthetic detached-child test checks for a delayed local effect after closure. +This is not a security boundary: the authorized command retains its configured +filesystem and network access, and remote effects and all runtime environments +remain unverified. It supports protocol `2024-11-05` only; a successful probe +does not prove that an MCP started in the successor. It is not scheduled or +wired to live handover. Other probes must honor cancellation themselves; an +unconfirmed cancellation stops the plan. + +`codex-mcp-observation.mjs` prepares an opt-in, bounded app-server connection +sample for a requested thread. It discards server names and endpoint data, fails +on ambiguous pagination, and reports an observed connection count separately +from the unknown number of processes started and unknown startup tokens. Its +profile and generation bindings are caller claims, the server does not echo the +thread identifier in each page, and pagination is not atomic. An isolated Codex CLI 0.169.0 experiment showed that listing after the +fixture MCP process was stopped restarted it; a control without listing did +not restart it during the observation window. This is an active discovery +operation, not a read-only health check. There is no default live connector; do +not call it on a live thread or treat it as launch evidence. Unit tests use +only a synthetic app-server callback. + +`codex-mcp-startup-notifications.mjs` can accumulate the app-server's native +startup notifications on an already established connection without issuing an +inventory request. In an isolated Codex CLI 0.169.0 experiment, a synthetic +thread emitted `starting` and `ready` notifications bound to that thread. The +observer keeps names only in memory, bounds its buffer and reports only counts; +its completeness is unverified and it never claims a process-start or token +count. Integration must attach before the authorized isolated startup, bind the +actual thread response, and independently establish session, profile and event +coverage before using the result as a receipt. It is not enabled for live use. + +`codex-role-mcp-overrides.mjs` prepares explicit disabled entries for servers +outside a role launch plan from a supplied effective inventory, without copying +server commands or enabling a previously disabled server. In isolated Codex CLI +0.169.0 experiments, an empty `mcp_servers` override inherited both configured +fixture servers, while an explicit disabled entry suppressed the excluded +fixture. The generated override produced the same result in that fixture. This +is not proof of complete isolation: the inventory may change or omit dynamic +plugin servers, and permissions and plugins require independent enforcement. +No live launch is wired to this planner. + +`codex-role-start-assessment.mjs` compares the complete native permission +profile and sandbox objects against a trusted expected policy and flags observed +approval or elicitation requests for rollback, including the legacy Codex +approval requests identified by conversation ID. It does not perform rollback or +prove that no prompt was missed. A matching response remains incomplete while +plugin isolation, MCP event coverage and startup token evidence are unknown. +The Codex CLI 0.169.0 generated schema says its `disabledPluginIds` response +field does not yet filter plugin capabilities; it must not be treated as proof +that excluded plugins are inactive. No live launch uses this assessment. + +`namespace-exec-gate.py` is a coordination gate for a future dedicated +launcher: it executes only after an explicit `GO` record on an owner-private +FIFO and fails closed on EOF, a different record or an unsafe FIFO. It does not +authenticate a same-user writer, establish process ownership, or implement +rollback. Isolated tests covered coordinator exit and a child that changes +process group inside a PID namespace; production launcher ownership, pidfd +recovery, runtime compatibility and remote effects remain unverified. The gate +is not connected to live handover. + +`isolated-pid-namespace.py` prepares a network-isolated experimental child +behind that gate. It checks the namespace init's parent, owner, namespace ID +and pidfd identity before opening the gate. Its stop operation targets only +the pinned init and reports local init exit with descendant and remote effects +still unverified. Preparation failure closes the gate without releasing it; if +ownership or cleanup cannot be established it reports uncertainty. The lease +must remain in the creating process and is not a persistent recovery mechanism, +an authorization boundary or an integrated live session launcher. Isolated +tests cover abrupt supervisor exit both before and after release, including a +child that changes process group; neither case proves behavior for external +services or other runtime configurations. The sandbox uses a read-only host +filesystem with a private writable workspace and is for isolated fixtures only. + +The optional `codex-native-rollback.integration.py` exercise accepts an absolute +Codex executable through `AGENT_MESH_TEST_CODEX_BIN`. It creates only temporary +state, two dedicated network-isolated app servers and synthetic MCP/provider +processes. A synthetic interactive approval request causes the test supervisor +to stop the successor namespace, then check that the predecessor accepts a new +turn. This does not wire rollback into handover, prove remote cleanup or permit +interactive approvals in a live role. Without the variable the test reports a +skip; an unavailable or incompatible runtime with the variable set is a failure. + +`isolated-role-rollback.py` connects a caller-bound Codex role assessment to +one stop of a caller-owned isolated successor. An incomplete assessment blocks +handover without stopping; an unsafe one reserves a session-keyed intent in an +owned private journal and syncs it before the stop callback. A second coordinator +using that same journal refuses to retry after a crash or uncertain response; +results are recorded separately. Even a confirmed namespace init exit leaves +descendant and remote effects unverified and handover blocked. The caller must +use a stable journal root, authenticate the assessment and bind it to the correct +native connection and namespace lease; this primitive does not establish those +facts, move a channel, or provide a live rollback controller. + +The pure handover model separates switching to a successor from observing the +messages queued before the switch, then reserving the final notice for the +predecessor. Provider queue acceptance is not recipient observation. The +observation argument is a host-supplied contract, not an authenticated adapter; +no graph operation accepts it or enables live cutover. The rehearsal stops at +the switched-and-awaiting-delivery phase and cannot prove notice finality. + +A new Codex wake proof binds the native queued payload to the channel, +generation, queue ID and correlation before starting it, then reads back the +exact native message. When this proof is verified and settled in a draining +channel, it marks that backlog message observed. Older proof schemas remain +valid wake evidence but cannot establish this stronger delivery binding. +When a start response has no timestamp, the producer polls only the readback +for a bounded interval and accepts a timestamp only with the same turn and exact +correlated message. It never repeats the native start after acceptance. +If a native start outcome is uncertain, readback-only recovery is disabled: a +steered message can match while the submission remains queued. Recovery evidence +schemas v3 and v4 with the correlated-recovery source are rejected. Reservations +remain unresolved until an independently verified consumption source exists. +This is not a cloud or Claude delivery adapter; native cutover remains disabled. + +The channel waker can opt in to explicit Codex backlog wake with absolute +private graph and evidence roots, and without resume. It persists an attempt +after a read-only native idle/queue preflight and before calling the producer, +checks the graph settlement, and never retries an +uncertain attempt automatically. A submission that already left the native +queue remains unverified; this route does not provide complete wake coverage. +The producer repeats the preflight before reserving a wake. Status may change +after either read; a raced or uncertain start remains unresolved rather than +being retried. +The option is disabled unless explicitly supplied and does not enable timers. + +For a draining local Claude channel, `observe-claude-delivery` checks one +managed inbox record in a stable local user transcript snapshot, binding its +correlation, payload, session and generation before marking the backlog item +observed. It requires a unique matching native enqueue preceding the user +record; an enqueue-only record is insufficient. Native inbox user records can +carry the `isMeta` flag and remain eligible when this correlation is proven. +The channel waker attempts observation for an accepted local Claude backlog item +before dispatching another item. Missing evidence blocks the run without a +resend; later runs may inspect the graph and transcript again. An opt-in test +has qualified the native transport and transcript shape in an isolated local +fixture. This source does not prove execution, attention, finality or cloud +delivery. Operational cutover remains disabled. + +The graph stores the observed prefix length and digest, without copying the +transcript. `verify-claude-delivery` can recheck the same prefix after ordinary +appends. If the prefix is changed, truncated or unavailable, verification +fails; a digest alone is not an immutable copy or proof of later finality. +Older observations without this metadata cannot be reverified by this command. + +A previously verified restart-state receipt can be revalidated against the +current private file before a future cutover. Revalidation checks generation, +session, digest, size and YAML, and rejects path replacement during the read. +It is a snapshot, not an exclusion lock: the host must bind it to the later +operation. The graph `channel revalidate-state` command binds the snapshot to the +persisted preparation and checks the channel again after reading without changing +the graph. The live cutover does not yet call it and remains disabled. + +A network-isolated experiment with Codex CLI 0.169.0 and a temporary home +observed a queued submission leave the queue and a turn start before an +explicit queue/start call. Without model connectivity, the full turn readback +did not expose a correlated user item in the observation window. The existing +explicit-start producer refuses an empty queue and does not retry the start. +An isolated counterexample shows that a native turn may start with empty input +and then accept a steer with the same client ID and payload while the queued +submission is still pending. Therefore `--observe-auto` is disabled and v5 +proofs are rejected: readback alone does not establish queue consumption. +No waker invokes this path and a trustworthy consumption source is still needed. diff --git a/docs/design/plexus-modules.md b/docs/design/plexus-modules.md new file mode 100644 index 00000000..9e52a4a1 --- /dev/null +++ b/docs/design/plexus-modules.md @@ -0,0 +1,146 @@ +# Plexus external modules + +Status: design in progress. This document does not authorize a live rollout. + +Plexus provides a generic extension boundary. Module commands, configuration and +private data belong to the operator; Plexus does not embed the policy of a module. +An external module must be invoked without a shell and must identify itself with +`describe`. A module keeps its own durable event cursor and may only write +attributes and events in its registered namespace. The registry is private and +must be explicitly configured; absence of configuration enables no modules. + +## Lifecycle evidence + +The lifecycle vocabulary is `session.started`, `session.woken`, `session.idle`, +`session.compacted`, `session.stopped`, and `session.handover`. A producer may +record one of these only when it has evidence for that transition. Discovery, +quietness, a queued message, or an expired lease alone are not proof that a +process stopped, compacted or handed over. Event ids must be stable on retry. + +`session.woken` means that a wake-caused turn was actually observed for the +named session, with source evidence that binds the wake to that turn. Starting +a process, scheduling or accepting a message, or a generic unrelated turn is +not proof of a wake. Use a stable observation id across retries and deduplicate +the feed by `eventId`. A missing wake event is not evidence of zero wakes; +consumers must establish source and time-window coverage separately. This +contract does not itself install or enable a wake-event producer. + +An experimental, explicitly invoked Codex adapter can bind an exact queued +submission and waker correlation to the turn returned by `thread/queue/start`. +It requires a full native thread readback with the same turn, start time, +message client id and input; incomplete or mismatched readback is unknown. +It first reserves the queue identity durably in a private evidence directory; +an ambiguous response leaves that identity reserved and requires manual +reconciliation rather than an automatic retry. Evidence records the session, +queue id, correlation, turn id and native start time, without message content; +its content-addressed reference can be checked locally with `--verify`. +Publishing a retained proof is idempotent. The operator must use one protected +evidence root and trust the local socket and waker's correlation: the file is +not an attestation against a local writer. `--apply` actually starts a queued +turn. Nothing schedules or enables this adapter, and its native behavior has +only been exercised with a synthetic server, not verified against a live runtime. +It is not connected to the waker or Limen and does not prove historical coverage. +For the native Codex stdin queue path, the transport receipt exposes the native +queue id alongside its session and correlation. The channel waker persists this +id in the same accepted queue item and generation when supplied. This proves +queue acceptance only; the waker does not yet invoke the wake-evidence adapter. +An ambiguous send remains inflight and cannot be automatically retried. +The channel journal can reserve an accepted wake by exact session, generation, +correlation and native queue id. An outstanding reservation blocks handover +and survives replay; it has no expiry. The graph refuses another channel's +reservation for that same session and queue id, and refuses already recorded +wakes. The experimental wake adapter acquires +the reservation before starting a turn and settles it only after the evidence +and lifecycle receipt are verified. Re-publishing the same proof with its +channel can recover a crash after the proof was written. An explicit recovery +may instead read the native thread, find a unique correlated user message that +matches the protected channel item, and verify the durable intent before +recording a distinct recovery proof. It never starts or resumes a thread. +Missing, partial, duplicate or mismatched observations remain unresolved; +there is no automatic retry. This path is not ready for operational use. + +For a specific known Codex compaction, `codex-compaction-evidence.mjs` performs +an on-demand read of the configured local app server. It requires the exact +thread, turn and `contextCompaction` item, a full turn view and a recorded item +completion timestamp. It writes a private, content-addressed evidence record +before idempotently recording `session.compacted` in an explicitly selected +graph; the command never defaults to the live graph. A local +consumer can resolve it with `--verify --session +--evidence-root `, which checks the private file, digest and session. +This relies on an operator-controlled root and local app-server socket; the +record is not a cryptographic attestation against an untrusted local writer. +The feed's `at` +is the recording time; the evidence's `completedAtMs` is the native item time. +An absent item, partial view, unavailable timestamp, failed read or graph error +is unknown, never zero. This tool does not discover items, establish complete +history coverage, observe Claude, schedule collection or authenticate an +untrusted local socket. The operator must protect the socket and evidence root. +Older graph readers must understand the new lifecycle event before use. + +Events use the graph's existing ordered, append-only store. Their consumers must +detect the retention watermark and report an expired cursor rather than silently +skip events. Graph projection, checkpoints, snapshots and compaction must remain +replayable with these events; deployments must account for older readers that +reject unknown event types before any producer is enabled. +The local unscoped change feed includes the opaque evidence reference so a +trusted registered module can inspect it. Scoped feeds omit that reference; +visibility of a session does not grant access to its evidence source. A +reference is not itself proof that its target has been verified. + +## Isolation requirements + +Namespacing must be enforced by the graph writer, not trusted to an executable. +A module must not change session identity, ownership, another module's state, or +core graph facts. Configuration is an authority boundary: arbitrary commands are +not accepted from events, graph attributes, user text or remote clients. Invocation +must be bounded by a timeout and an output limit; diagnostics must not leak +private inputs. A crash, invalid response or partial write must not advance the +module's cursor. Retry semantics must not duplicate committed changes. + +Module conformance tests must cover protocol identity, namespace enforcement, +independent cursors, retries, malformed responses, timeout, and retention gaps. +The example module and all fixtures use synthetic data only. + +## Proposed process protocol + +The host invokes a configured argument vector followed by an operation; no shell +expansion is involved. Requests and responses are single JSON objects on stdin +and stdout. Every response identifies protocol `agent-mesh.plexus-module.v1`. +`describe` receives `{}` and returns the module name, its exact namespaces and +supported operations. The registry must reject duplicate names or namespaces. +The registry is an operator-owned allowlist, not a marketplace or code sandbox. + +The initial read-only discovery surface is `mesh-graph module list` and +`mesh-graph module describe --name `. It reads the operator-owned +`$XDG_CONFIG_HOME/agent-mesh/modules.json` (or `--config `). The registry +has `schemaVersion: 1` and a `modules` array containing `name`, `command` as an +argument array, optional `namespaces` (default: the module name), and optional +`timeoutMs`. One command may own several namespaces. A missing file +registers no modules; malformed files and duplicate names fail closed. Describe +does not update a cursor or write graph state. stderr is not returned to callers. +Process requests are capped at 32 MiB; responses and configuration at 1 MiB. +Oversized requests fail without advancing the cursor rather than silently +truncating the graph. These limits are not a substitute for future pagination. + +`module run --name ` observes the graph and a page from the module's +cursor without holding the writer lock during feed replay. If the graph moves +during observation or before commit, the run fails without advancing its cursor. +The host invokes `process` outside the lock, validates its response and commits +the bounded batch and cursor as one graph event under the lock. An intervening +run for the same module causes a cursor conflict. The request contains `schema`, `graph`, `cursor`, and `events`; the +response contains `schema`, `name`, `batchId`, `attributes`, and `events`. +Attributes identify a session and a namespaced key; they are projected under +that namespace on its node. Events identify a session, a namespaced type, and JSON data. +The cursor is host-owned, not selected by a module. An initial run starts at the +current head; an expired cursor fails closed and requires reconciliation. A +no-change run does not append a new batch solely to observe its own events. + +`module apply` is an operator-level interface for an already computed batch; +the configured name determines its permitted namespaces. Both paths check the cursor and +the last batch id while holding the graph lock. An identical retry of the last +batch returns a duplicate receipt, while a reused id with different content or +an older cursor fails. No exactly-once guarantee is claimed for arbitrary +external effects made by an executable. `module conformance` checks a synthetic +description and process response with `mode: "conformance"` and synthetic graph +data; a module must not contact live sources in that mode. This command is not a sandbox or a proof of side-effect +isolation. Configuration and OS access remain under the operator's control. diff --git a/docs/design/plexus-restart-state.md b/docs/design/plexus-restart-state.md new file mode 100644 index 00000000..6cc83504 --- /dev/null +++ b/docs/design/plexus-restart-state.md @@ -0,0 +1,35 @@ +# Restart state contract + +A state file may carry a `RIAVVIO` YAML block. Its versioned content records +the session being replaced, its stable channel, harness, working directory, +skills, triggers and goal. Trigger configuration is opaque to Plexus and is +interpreted only by the responsible adapter. The block may contain private +paths and prompts and belongs in a private state file, not in the public repo. + +```yaml +schema: agent-mesh.restart.v1 +session: codex:example +channel: '#example' +harness: codex +working_directory: /workspace +skills: [example-skill] +triggers: + - id: trigger-1 + kind: timer + config: + prompt: Perform the next check. +goal: + objective: Finish the task. + status: active +``` + +`skills` and `triggers` are arrays, including when empty; `goal` is either an +object or null. Trigger `(kind, id)` pairs are unique. A trusted adapter must +bind the block to the correlated old session and channel, and independently +reconcile every trigger with its source before using it. The `restart-yaml.py` +decoder requires PyYAML and rejects duplicate keys, aliases, anchors, explicit +tags, oversized input and non-JSON values. It accepts either a standalone YAML +file or a single `## RIAVVIO` section immediately followed by a fenced `yaml` +block. `validateRestartState` checks the decoded object; neither component is +a scheduler or authorization to recreate anything. Handover remains disabled +until trigger reconciliation and final-notice verification are implemented. diff --git a/docs/design/plexus.md b/docs/design/plexus.md index 8a3984b8..199f010d 100644 --- a/docs/design/plexus.md +++ b/docs/design/plexus.md @@ -29,7 +29,7 @@ In practice few nodes carry refs: nothing feeds them automatically, so linking i storage. `agent` is also unvalidated, so test harnesses can leave nodes with arbitrary agent names. Ledgers have no shared store. A file-based ledger and a database-backed work-item store are both -reachable only through opaque refs such as `management:MGT-0239`, which is the right boundary. +reachable only through opaque refs such as `ledger:item-1`, which is the right boundary. ## 2. Data model diff --git a/packages/tmux-bridge/README.md b/packages/tmux-bridge/README.md index 6b50f303..f6c9655c 100644 --- a/packages/tmux-bridge/README.md +++ b/packages/tmux-bridge/README.md @@ -182,7 +182,7 @@ node $BIN/mesh-graph.mjs show --json The graph command atomically writes only `/graph.json`; launch provenance is the separate append-only stream described above. Neither path calls context or work-item systems. Nodes may carry explicit opaque `--refs source:record,...` values, such as -`management:MGT-0239` or `amf:record-id`. The graph validates their shape but never resolves or +`ledger:item-1` or `amf:record-id`. The graph validates their shape but never resolves or infers them. A work-orchestration or recall consumer may read `graph.json` and compose its own projection. Keep `summary` to one compact line; session context belongs behind a ref. diff --git a/packages/tmux-bridge/bin/agent-native-call.mjs b/packages/tmux-bridge/bin/agent-native-call.mjs index 558bb24f..1bcc339c 100755 --- a/packages/tmux-bridge/bin/agent-native-call.mjs +++ b/packages/tmux-bridge/bin/agent-native-call.mjs @@ -4,6 +4,7 @@ import { commsLease } from "./comms-client.mjs"; import { createHash } from "node:crypto"; import { execFile } from "node:child_process"; +import { readSync } from "node:fs"; import { access, open, readdir, stat } from "node:fs/promises"; import { homedir } from "node:os"; import { join, resolve } from "node:path"; @@ -12,6 +13,8 @@ import { parseArgs } from "node:util"; import { inspectClaudeSessionOwnership } from "./claude-session-ownership.mjs"; import { goalCommand, liveClaudeSessions, typeClaudeGoal } from "./claude-goal.mjs"; import { GOAL_RESUME_MODES, reconcileCodexGoal } from "./codex-goal.mjs"; +import { withCodexAppServer } from "./codex-app-server.mjs"; +import { loadClaudeAccountProfile, withClaudeAccount } from "./cloud-account-binding.mjs"; let activeComms; let enqueueStarted = false; @@ -24,12 +27,16 @@ const { values } = parseArgs({ timeout: { type: "string", default: "120" }, "delivery-only": { type: "boolean", default: false }, cloud: { type: "boolean", default: false }, + "cloud-profile": { type: "string" }, + "cloud-scope": { type: "string" }, + "cloud-profile-digest": { type: "string" }, "steer-or-queue": { type: "boolean", default: false }, resume: { type: "boolean", default: false }, "no-resume": { type: "boolean", default: false }, goal: { type: "string" }, "goal-resume": { type: "string", default: "blocked" }, message: { type: "string" }, + "message-stdin": { type: "boolean", default: false }, "managed-inbox-root": { type: "string" }, help: { type: "boolean", short: "h", default: false } }, @@ -37,14 +44,15 @@ const { values } = parseArgs({ }); if (values.help) { - console.log("Usage: agent-native-call.mjs --agent codex|claude --session --correlation-id --message [--timeout ] [--resume (Codex only)] [--cloud --delivery-only (Claude cloud only)] [--steer-or-queue (Codex only)] [--goal TEXT (Codex, local Claude)] [--goal-resume blocked|any|off (Codex only)] [--delivery-only]"); + console.log("Usage: agent-native-call.mjs --agent codex|claude --session --correlation-id (--message | --message-stdin) [--timeout ] [--resume (Codex only)] [--cloud --delivery-only (Claude cloud only)] [--steer-or-queue (Codex only)] [--goal TEXT (Codex, local Claude)] [--goal-resume blocked|any|off (Codex only)] [--delivery-only]"); process.exit(0); } const agent = required(values.agent, "--agent"); const sessionId = required(values.session, "--session"); const correlationId = required(values["correlation-id"], "--correlation-id"); -const message = required(values.message, "--message"); +if (values["message-stdin"] && values.message !== undefined) fail("--message and --message-stdin are mutually exclusive", 2); +const message = values["message-stdin"] ? required(readMessageStdin(), "--message-stdin") : required(values.message, "--message"); const timeoutSeconds = Number(values.timeout); if (agent !== "codex" && agent !== "claude") fail(`native active-session calls are not implemented for agent ${agent}`, 2); if (values.resume && values["no-resume"]) fail("--resume and --no-resume are mutually exclusive", 2); @@ -64,6 +72,8 @@ const goalOptions = agent === "codex" ? { objective: values.goal?.trim(), resume if (values.cloud && (agent !== "claude" || !values["delivery-only"] || values.resume || values["managed-inbox-root"])) { fail("--cloud requires --agent claude --delivery-only, without --resume or --managed-inbox-root", 2); } +if ((!values.cloud && (values["cloud-profile"] || values["cloud-scope"] || values["cloud-profile-digest"])) || Boolean(values["cloud-profile"]) !== Boolean(values["cloud-scope"]) || (values["cloud-profile-digest"] && !values["cloud-profile"])) fail("cloud profile and scope must be supplied together for cloud transport", 2); +const cloudProfile = values["cloud-profile"] ? await loadClaudeAccountProfile(values["cloud-profile"], values["cloud-scope"], values["cloud-profile-digest"]) : undefined; if (values.cloud ? !/^(session|cse)_[A-Za-z0-9]{1,128}$/.test(sessionId) : !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(sessionId)) { fail(values.cloud ? "--session must be an exact session_ or cse_ cloud ID" : "--session must be a complete UUID", 2); @@ -83,6 +93,7 @@ const protocolMessage = values["delivery-only"] ? message : `${anchor} Use the r const comms = await commsLease({ kind: 'native', runtime: agent, destination: sessionId, correlation: correlationId, message: protocolMessage, inbox_root: values['managed-inbox-root'], resume, ...(values.cloud ? { cloud: true } : {}), + ...(cloudProfile ? { cloud_profile: values['cloud-profile'], cloud_scope: values['cloud-scope'], cloud_profile_digest: cloudProfile.digest } : {}), ...(values["steer-or-queue"] ? { steer_first: true } : {}), ...(goalOptions?.objective ? { goal: goalOptions.objective } : {}), ...(goalOptions?.resume && goalOptions.resume !== "blocked" ? { goal_resume: goalOptions.resume } : {}) }); @@ -96,10 +107,17 @@ if (comms.status !== 'send') { // Cloud follow-ups have a provider queue acknowledgement, but no local transcript. // All failures after invoking the provider retain the gate's unknown receipt. if (values.cloud) { - enqueueStarted = true; - const sent = await run(process.env.CLAUDE_BIN || "claude", [ - "-p", "--cloud", sessionId, "--output-format", "json" - ], timeoutSeconds * 1000, message); + let sent; + if (cloudProfile) { + sent = await withClaudeAccount(cloudProfile.profile, async binding => { + enqueueStarted = true; + return run(binding.command, ["-p", "--cloud", sessionId, "--output-format", "json"], timeoutSeconds * 1000, message, { ...process.env, CLAUDE_CONFIG_DIR: binding.configDir }); + }); + await loadClaudeAccountProfile(values["cloud-profile"], values["cloud-scope"], cloudProfile.digest); + } else { + enqueueStarted = true; + sent = await run(process.env.CLAUDE_BIN || "claude", ["-p", "--cloud", sessionId, "--output-format", "json"], timeoutSeconds * 1000, message); + } let receipt; try { receipt = JSON.parse(sent.stdout); } catch { /* Unproven acceptance. */ } if (sent.code !== 0 || receipt?.ok !== true || receipt.session_id !== sessionId) { @@ -124,6 +142,7 @@ let resumeDiagnostic = false; let transportAccepted = false; let deliveryMethod; let steeredTurnId; +let nativeQueueId; try { if (agent === "codex") { if (values["steer-or-queue"]) { @@ -150,16 +169,35 @@ if (agent === "codex") { } if (deliveryMethod !== "steer") { enqueueStarted = true; - const queued = await run(process.env.CODEX_BIN || "codex", [ - "queue", "--thread", sessionId, "--message", protocolMessage, ...(resume ? ["--resume"] : []) - ], (timeoutSeconds + 15) * 1000); - if (queued.code !== 0) { - if (codexSessionIsNotDirectlyWritable(queued)) { - fail("Codex spawned sub-agent sessions are readable but do not accept direct queued turns.", 79); + if (values["message-stdin"] && !values["steer-or-queue"]) { + try { + await withCodexAppServer({ clientName: "agent-mesh-channel-queue", timeout: (timeoutSeconds + 15) * 1000, + timeoutMessage: "queue outcome unknown; inspect before retrying" }, async (request) => { + const input = [{ type: "text", text: protocolMessage, text_elements: [] }]; + const response = await request("thread/queue/add", { threadId: sessionId, clientUserMessageId: correlationId, input }); + const entry = response?.queuedSubmission; + if (typeof entry?.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(entry.id) || entry.clientUserMessageId !== correlationId || JSON.stringify(entry.input) !== JSON.stringify(input)) throw new Error("queue receipt mismatch"); + nativeQueueId = entry.id; + if (resume) { + try { await request("thread/resume", { threadId: sessionId }); } + catch { resumeDiagnostic = true; } + } + }); + } catch { + fail("Codex queue outcome uncertain; inspect before retrying", 70); } - fail(safeError("Codex native queue failed", queued), 1); + } else { + const queued = await run(process.env.CODEX_BIN || "codex", [ + "queue", "--thread", sessionId, "--message", protocolMessage, ...(resume ? ["--resume"] : []) + ], (timeoutSeconds + 15) * 1000); + if (queued.code !== 0) { + if (codexSessionIsNotDirectlyWritable(queued)) { + fail("Codex spawned sub-agent sessions are readable but do not accept direct queued turns.", 79); + } + fail(safeError("Codex native queue failed", queued), 1); + } + resumeDiagnostic = Boolean(resume && queued.stderr?.trim()); } - resumeDiagnostic = Boolean(resume && queued.stderr?.trim()); deliveryMethod = "queue"; } } else { @@ -185,6 +223,7 @@ const goal = goalOptions ? await applyGoal(agent, sessionId, goalOptions) : unde // Queue acknowledgement is transport proof, never proof that the turn ran. if (values["delivery-only"]) { console.log(JSON.stringify({ status: deliveryMethod === "steer" ? "steered" : "queued", agent, sessionId, correlationId, + ...(nativeQueueId ? { nativeQueueId } : {}), ...(values["steer-or-queue"] ? { deliveryMethod, ...(steeredTurnId ? { turnId: steeredTurnId } : {}) } : {}), ...(goal ? { goal } : {}), ...(resume && deliveryMethod === "queue" ? { resumeRequested: true, resumeVerified: false, resumeDiagnostic } : {}) })); @@ -272,6 +311,20 @@ function finish(bodies, begin, end) { process.exit(0); } +function readMessageStdin() { + const max = 65536, chunks = []; + let total = 0; + for (;;) { + const chunk = Buffer.allocUnsafe(Math.min(4096, max + 1 - total)); + const count = readSync(0, chunk, 0, chunk.length, null); + if (!count) break; + total += count; + if (total > max) fail("stdin message too large", 2); + chunks.push(chunk.subarray(0, count)); + } + return Buffer.concat(chunks).toString("utf8"); +} + function messageText(record, role) { const payload = record?.payload; if (record?.type === "event_msg") { @@ -354,9 +407,9 @@ async function consumeTranscript(path, start) { } } -function run(command, args, timeoutMs, input) { +function run(command, args, timeoutMs, input, env = process.env) { return new Promise((resolveRun) => { - const child = execFile(command, args, { timeout: timeoutMs, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => { + const child = execFile(command, args, { timeout: timeoutMs, maxBuffer: 1024 * 1024, env }, (error, stdout, stderr) => { resolveRun({ code: error && typeof error.code === "number" ? error.code : error ? 1 : 0, stdout: typeof stdout === "string" ? stdout : "", diff --git a/packages/tmux-bridge/bin/agent-session-inbox.py b/packages/tmux-bridge/bin/agent-session-inbox.py index 3dc205cd..fc161036 100755 --- a/packages/tmux-bridge/bin/agent-session-inbox.py +++ b/packages/tmux-bridge/bin/agent-session-inbox.py @@ -23,6 +23,10 @@ DUPLICATE = "AGENT_MESH_INBOX_DUPLICATE do-not-relaunch" +class HookBudgetExpired(TimeoutError): + pass + + def process_identity(pid): """Use kernel start ticks as well as PID, so PID reuse is not ownership.""" if not isinstance(pid, int) or pid <= 1: @@ -434,7 +438,7 @@ def main(): return if args.mode in {'hook', 'status'}: def expire(_signum, _frame): - raise TimeoutError('hook budget expired') + raise HookBudgetExpired('hook budget expired') previous = signal.signal(signal.SIGALRM, expire) signal.setitimer(signal.ITIMER_REAL, 0.2) try: @@ -446,6 +450,11 @@ def expire(_signum, _frame): if not active: raise ValueError('no live owner-bound supervisor') print(json.dumps(active)) + except HookBudgetExpired: + if os.environ.get('AGENT_MESH_INBOX_DIAGNOSTICS') == '1': + print('agent-session-inbox: hook budget expired', file=sys.stderr, flush=True) + if args.mode == 'status': + raise SystemExit(1) except Exception: if args.mode == 'status': raise SystemExit(1) diff --git a/packages/tmux-bridge/bin/agent-waker.py b/packages/tmux-bridge/bin/agent-waker.py index 612af5cd..10db0928 100755 --- a/packages/tmux-bridge/bin/agent-waker.py +++ b/packages/tmux-bridge/bin/agent-waker.py @@ -11,6 +11,8 @@ import hashlib import json import os +import re +import stat from pathlib import Path import subprocess import sys @@ -116,24 +118,33 @@ def compose(job: str, pending: list[dict[str, Any]], errors: list[Any]) -> str: return "\n".join(lines) -def deliver(agent: str, session: str, correlation: str, message: str, inbox_root: str | None, delivery_only: bool = False, resume: bool = False) -> int: +def deliver(agent: str, session: str, correlation: str, message: str, inbox_root: str | None, delivery_only: bool = False, resume: bool = False, message_stdin: bool = False, receipt_out: dict | None = None, cloud_profile: str | None = None, cloud_scope: str | None = None) -> int: command = ["node", str(BIN / "agent-native-call.mjs"), "--agent", agent, "--session", session, - "--correlation-id", correlation, "--timeout", "5", "--message", message] + "--correlation-id", correlation, "--timeout", "5"] + command += ["--message-stdin"] if message_stdin else ["--message", message] + if cloud_profile or cloud_scope: + if not (cloud_profile and cloud_scope and agent == "claude" and delivery_only and message_stdin and not resume and not inbox_root): + raise ValueError("invalid cloud delivery options") + command += ["--cloud", "--cloud-profile", cloud_profile, "--cloud-scope", cloud_scope] if resume: if agent != "codex": raise ValueError("waker resume is supported only for Codex") command += ["--resume"] + elif message_stdin and agent == "codex": + command += ["--no-resume"] if delivery_only: command += ["--delivery-only"] if inbox_root: command += ["--managed-inbox-root", inbox_root] - result = subprocess.run(command, text=True, capture_output=True) + result = subprocess.run(command, text=True, capture_output=True, **({"input": message} if message_stdin else {})) try: receipt = json.loads(result.stdout) except (ValueError, TypeError): receipt = None bound = (isinstance(receipt, dict) and receipt.get("agent") == agent and receipt.get("sessionId") == session and receipt.get("correlationId") == correlation) + if cloud_profile and isinstance(receipt, dict) and receipt.get("status") == "queued" and (receipt.get("transport") != "claude-cloud" or receipt.get("readBack") is not False): + return 78 if delivery_only and isinstance(receipt, dict) and receipt.get("status") == "queued" and not bound: return 78 # A comms hold can exit zero: process success is not native queue acceptance. @@ -149,6 +160,12 @@ def deliver(agent: str, session: str, correlation: str, message: str, inbox_root return 78 if delivery_only and (not isinstance(receipt, dict) or receipt.get("status") != "queued"): return 78 + if delivery_only and receipt_out is not None and result.returncode == 0 and bound: + native_id = receipt.get('nativeQueueId') + if native_id is not None: + if agent != 'codex' or not isinstance(native_id, str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._:-]{0,127}', native_id): + return 78 + receipt_out['nativeQueueId'] = native_id return result.returncode @@ -158,7 +175,213 @@ def record(job: str, outcome: str, session: str, note: str) -> None: capture_output=True) +def channel_call(args: argparse.Namespace, operation: str, *options: str) -> dict[str, Any]: + command = ['node', str(BIN / 'mesh-graph.mjs')] + if args.graph_state: + command += ['--state', args.graph_state] + arguments = list(options) + payload = None + if '--input' in arguments: + index = arguments.index('--input') + 1 + payload = arguments[index] + arguments[index] = '-' + command += ['channel', operation, '--name', args.channel, *arguments] + result = subprocess.run(command, input=payload, text=True, capture_output=True, timeout=30, check=True) + value = json.loads(result.stdout) + if not isinstance(value, dict) or not isinstance(value.get('channel'), dict): + raise ValueError('invalid channel response') + return value['channel'] + + +def observe_claude_channel_delivery(args: argparse.Namespace, message_id: str, recovery: bool = False) -> None: + command = ['node', str(BIN / 'mesh-graph.mjs')] + if args.graph_state: + command += ['--state', args.graph_state] + operation = 'recover-claude-delivery' if recovery else 'observe-claude-delivery' + command += ['channel', operation, '--name', args.channel, '--id', message_id] + result = subprocess.run(command, text=True, capture_output=True, timeout=30, check=True) + value = json.loads(result.stdout) + allowed = ('accepted', 'observed') if recovery else ('observed',) + if not isinstance(value, dict) or value.get('status') not in allowed or value.get('channel') != args.channel or value.get('messageId') != message_id: + raise ValueError('invalid delivery observation') + + +def preflight_codex_channel_wake(item: dict[str, Any], channel: dict[str, Any]) -> bool: + session = channel['session'] + if not session.startswith('codex:'): + raise ValueError('invalid Codex wake target') + command = ['node', str(BIN / 'codex-wake-evidence.mjs'), '--preflight', '--thread', session[6:], + '--queue-id', item['nativeQueueId'], '--correlation', item['id']] + result = subprocess.run(command, text=True, capture_output=True, timeout=20, check=True) + value = json.loads(result.stdout) + if not isinstance(value, dict) or value.get('schema') != 'agent-mesh.wake-preflight.v1' or value.get('session') != session or value.get('queueId') != item['nativeQueueId'] or value.get('correlation') != item['id'] or value.get('status') not in ('ready', 'not-ready'): + raise ValueError('invalid wake preflight') + return value['status'] == 'ready' + + +def start_codex_channel_wake(args: argparse.Namespace, item: dict[str, Any], channel: dict[str, Any]) -> str: + session = channel['session'] + if not session.startswith('codex:') or not args.graph_state or not os.path.isabs(args.graph_state) or not os.path.isabs(args.wake_evidence_root): + raise ValueError('explicit private wake and graph roots required') + command = ['node', str(BIN / 'codex-wake-evidence.mjs'), '--apply', '--thread', session[6:], + '--queue-id', item['nativeQueueId'], '--correlation', item['id'], '--channel', args.channel, + '--generation', str(channel['generation']), '--evidence-root', args.wake_evidence_root, + '--graph-state', args.graph_state] + result = subprocess.run(command, text=True, capture_output=True, timeout=45, check=True) + value = json.loads(result.stdout) + if not isinstance(value, dict) or value.get('schema') != 'agent-mesh.wake-record.v1' or value.get('session') != session or value.get('settled') is not True or not re.fullmatch(r'codex-wake:[a-f0-9]{64}', str(value.get('evidence', ''))): + raise ValueError('wake proof not verified') + return value['evidence'] + + +def cloud_target(target: str, root: str | None) -> tuple[str, str, str]: + match = re.fullmatch(r'claude-cloud:([a-z][a-z0-9-]{0,63}):((?:session|cse)_[A-Za-z0-9]{1,128})', target) + if not match or not root: + raise ValueError('unsupported cloud recipient') + directory = Path(root) + if not directory.is_absolute() or directory.resolve() != directory: + raise ValueError('invalid cloud profile root') + info = directory.lstat() + if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077: + raise ValueError('insecure cloud profile root') + scope, session = match.groups() + profile = directory / f'{scope}.json' + info = profile.lstat() + if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1 or info.st_uid != os.getuid() or info.st_mode & 0o077: + raise ValueError('insecure cloud profile') + return session, str(profile), scope + + +def run_channel(args: argparse.Namespace) -> int: + path = Path(args.state) if args.state else state_dir() / f'{args.job}.json' + with locked(path) as acquired: + if not acquired: + print(json.dumps({'job': args.job, 'outcome': 'noop', 'reason': 'previous run still active'})) + return 0 + state, state_errors = load_state(path) + if state_errors: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'unreadable waker state'})) + return 3 + new, errors = run_producer(args.producer, args.producer_timeout) + errors = state_errors + errors + known = {entry['key'] for entry in state['pending']} + for item in new: + key = item_key(item) + if key not in known: + known.add(key) + state['pending'].append({'key': key, 'item': item}) + signature = error_signature(errors) + wake_errors = errors if signature and signature != state.get('errorSignature') else [] + if not errors: + state['errorSignature'] = None + flight = state.get('inFlight') + recipient = {'channel': args.channel} + if flight and flight.get('recipient') != recipient: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'in-flight recipient changed'})) + return 3 + if not flight and (state['pending'] or wake_errors): + flight = {'correlationId': f'waker-{uuid.uuid4()}', 'recipient': recipient, + 'message': compose(args.job, state['pending'], wake_errors), + 'itemKeys': [entry['key'] for entry in state['pending'][:MAX_LISTED]], 'errorSignature': signature} + state['inFlight'] = flight + save_state(path, state) + try: + if flight: + channel_call(args, 'enqueue', '--id', flight['correlationId'], '--input', flight['message']) + accepted = set(flight['itemKeys']) + state['pending'] = [entry for entry in state['pending'] if entry['key'] not in accepted] + state['lastDelivery'] = {'correlationId': flight['correlationId'], 'at': time.time(), + 'itemKeys': flight['itemKeys'], 'status': 'channel-queued'} + if flight['errorSignature']: + state['errorSignature'] = flight['errorSignature'] + state.pop('inFlight', None) + save_state(path, state) + channel = channel_call(args, 'get') + if channel.get('phase') not in ('active', 'draining'): + print(json.dumps({'job': args.job, 'outcome': 'queued', 'reason': 'handover'})) + return 0 + inflight = next((item for item in channel['queue'] if item.get('state') == 'inflight'), None) + if inflight and channel.get('session', '').startswith('claude:'): + observe_claude_channel_delivery(args, inflight['id'], recovery=True) + print(json.dumps({'job': args.job, 'outcome': 'acted', 'reason': 'delivery recovered'})) + return 0 + if inflight: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'unresolved delivery'})) + return 3 + if channel.get('phase') == 'draining' and channel.get('session', '').startswith('claude:'): + backlog = channel.get('handover', {}).get('backlog', []) + awaiting = next((item for item in channel['queue'] if item.get('id') in backlog and item.get('state') == 'accepted'), None) + if awaiting: + observe_claude_channel_delivery(args, awaiting['id']) + print(json.dumps({'job': args.job, 'outcome': 'acted', 'reason': 'delivery observed'})) + return 0 + if channel.get('phase') == 'draining' and channel.get('session', '').startswith('codex:') and getattr(args, 'wake_evidence_root', None): + backlog = channel.get('handover', {}).get('backlog', []) + awaiting = next((item for item in channel['queue'] if item.get('id') in backlog and item.get('state') == 'accepted'), None) + if awaiting: + identity = {'channel': args.channel, 'session': channel['session'], 'generation': channel['generation'], 'id': awaiting['id'], 'queueId': awaiting.get('nativeQueueId')} + if channel.get('wakeReservation') or state.get('wakeAttempt', {}).get('identity') == identity: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'wake attempt unresolved; inspect before retry'})) + return 3 + if not isinstance(identity['queueId'], str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._:-]{0,127}', identity['queueId']): + raise ValueError('native queue identity unavailable') + if not preflight_codex_channel_wake(awaiting, channel): + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'wake not ready'})) + return 3 + state['wakeAttempt'] = {'identity': identity, 'status': 'attempted'} + save_state(path, state) + evidence = start_codex_channel_wake(args, awaiting, channel) + current = channel_call(args, 'get') + matched = [item for item in current['queue'] if item.get('id') == identity['id'] and item.get('session') == identity['session'] and item.get('generation') == identity['generation'] and item.get('state') == 'observed' and item.get('wakeEvidence') == evidence] + if current.get('session') != identity['session'] or current.get('generation') != identity['generation'] or len(matched) != 1: + raise ValueError('wake settlement not observed') + state['wakeAttempt']['status'] = 'verified' + save_state(path, state) + print(json.dumps({'job': args.job, 'outcome': 'acted', 'reason': 'wake verified'})) + return 0 + pending = next((item for item in channel['queue'] if item.get('state') == 'pending'), None) + if not pending: + print(json.dumps({'job': args.job, 'outcome': 'noop'})) + return 0 + target = channel['session'] + generation = channel['generation'] + if isinstance(generation, bool) or not isinstance(generation, int) or generation < 1: + raise ValueError('invalid channel generation') + cloud_profile = cloud_scope = None + if target.startswith('claude-cloud:'): + session, cloud_profile, cloud_scope = cloud_target(target, getattr(args, 'cloud_profile_root', None)) + agent = 'claude' + else: + agent, sep, session = target.partition(':') + if not sep or agent not in ('codex', 'claude'): + raise ValueError('unsupported channel recipient') + channel = channel_call(args, 'begin-delivery', '--id', pending['id'], '--session', target, '--generation', str(generation)) + item = next(item for item in channel['queue'] if item['id'] == pending['id']) + if item['session'] != target or item['generation'] != generation: + raise ValueError('unsupported channel recipient') + transport_receipt = {} + options = {'cloud_profile': cloud_profile, 'cloud_scope': cloud_scope} if cloud_profile else {} + code = deliver(agent, session, item['id'], item['payload'], None if cloud_profile else args.managed_inbox_root, + True, resume=args.resume and agent == 'codex', message_stdin=True, receipt_out=transport_receipt, **options) + if code != 0: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'delivery unconfirmed'})) + return 3 + if cloud_profile: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'cloud queued; receipt unverified'})) + return 3 + receipt = {'status': 'accepted', 'messageId': item['id'], 'session': item['session'], 'generation': item['generation']} + receipt.update(transport_receipt) + channel_call(args, 'acknowledge', '--id', item['id'], '--input', json.dumps(receipt, separators=(',', ':'))) + print(json.dumps({'job': args.job, 'outcome': 'acted', 'correlationId': item['id']})) + return 0 + except (OSError, subprocess.SubprocessError, ValueError, KeyError, TypeError, StopIteration): + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'channel unavailable or delivery unresolved'})) + return 3 + + def run(args: argparse.Namespace) -> int: + if getattr(args, 'channel', None): + return run_channel(args) path = Path(args.state) if args.state else state_dir() / f"{args.job}.json" with locked(path) as acquired: if not acquired: @@ -225,7 +448,12 @@ def main(argv: list[str] | None = None) -> int: runner = sub.add_parser("run", help="run the producer once and deliver anything new") runner.add_argument("--job", required=True) runner.add_argument("--agent", default="claude", choices=("claude", "codex")) - runner.add_argument("--session", required=True, help="owning session UUID") + recipient = runner.add_mutually_exclusive_group(required=True) + recipient.add_argument("--session", help="owning session UUID") + recipient.add_argument("--channel", help="stable channel identifier") + runner.add_argument("--graph-state", help="override graph state for isolated tests") + runner.add_argument("--wake-evidence-root", help="opt in to explicit Codex backlog wake with a private evidence root") + runner.add_argument("--cloud-profile-root", help="private directory for scoped cloud account profiles") runner.add_argument("--managed-inbox-root", help="required for Claude sessions") runner.add_argument("--delivery-only", action="store_true", help="acknowledge the native queue, without waiting for a result") runner.add_argument("--resume", action="store_true", help="opt in to native Codex resume when idle") @@ -233,7 +461,11 @@ def main(argv: list[str] | None = None) -> int: runner.add_argument("--producer-timeout", type=int, default=280) runner.add_argument("producer", nargs=argparse.REMAINDER, help="-- command that prints the JSON report") args = parser.parse_args(argv) - if args.resume and args.agent != "codex": + if args.wake_evidence_root and (not args.channel or not args.graph_state or not os.path.isabs(args.graph_state) or not os.path.isabs(args.wake_evidence_root) or args.resume): + parser.error('--wake-evidence-root requires --channel, absolute --graph-state, and no --resume') + if args.channel and not args.delivery_only: + parser.error("--channel requires --delivery-only") + if args.resume and not args.channel and args.agent != "codex": parser.error("--resume requires --agent codex") if args.producer[:1] == ["--"]: args.producer = args.producer[1:] diff --git a/packages/tmux-bridge/bin/channel-state.mjs b/packages/tmux-bridge/bin/channel-state.mjs new file mode 100644 index 00000000..4ae54186 --- /dev/null +++ b/packages/tmux-bridge/bin/channel-state.mjs @@ -0,0 +1,148 @@ +/** Pure channel transitions. A host must persist each transition atomically. */ +import { createHash } from 'node:crypto'; +const identifier = (value) => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value); +const channelIdentifier = (value) => typeof value === 'string' && /^#?[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value); +const copy = (state) => structuredClone(state); + +export function createChannel(id, session) { + if (!channelIdentifier(id) || !identifier(session)) throw new Error('invalid channel or session'); + return { schema: 'agent-mesh.channel.v1', id, session, generation: 1, phase: 'active', queue: [] }; +} + +export function enqueue(state, id, payload) { + if (!identifier(id) || typeof payload !== 'string' || !payload || Buffer.byteLength(payload) > 65536) throw new Error('invalid message'); + const prior = state.queue.find((item) => item.id === id); + if (prior) { + if (prior.payload !== payload) throw new Error('message id conflict'); + return copy(state); + } + const next = copy(state); + next.queue.push({ id, payload, state: 'pending' }); + return next; +} + +export function beginDelivery(state, id, expectedSession, expectedGeneration) { + if (!['active', 'draining'].includes(state.phase)) throw new Error('handover in progress'); + if (expectedSession !== undefined && state.session !== expectedSession) throw new Error('channel recipient changed'); + if (expectedGeneration !== undefined && (!Number.isSafeInteger(expectedGeneration) || expectedGeneration < 1 || state.generation !== expectedGeneration)) throw new Error('channel generation changed'); + if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); + if (state.queue.find((item) => item.state === 'pending')?.id !== id) throw new Error('message is not first pending'); + const next = copy(state), item = next.queue.find((row) => row.id === id); + if (!item || item.state !== 'pending') throw new Error('message not pending'); + item.state = 'inflight'; + item.session = state.session; + item.generation = state.generation; + return next; +} + +export function acknowledge(state, id, receipt) { + const next = copy(state), item = next.queue.find((row) => row.id === id); + if (!item || item.state !== 'inflight' || !receipt || receipt.status !== 'accepted' || receipt.messageId !== id || receipt.session !== item.session || receipt.generation !== item.generation) throw new Error('unverified delivery receipt'); + if (receipt.nativeQueueId !== undefined) { + if (!item.session.startsWith('codex:') || !identifier(receipt.nativeQueueId)) throw new Error('invalid native queue receipt'); + item.nativeQueueId = receipt.nativeQueueId; + } + item.state = 'accepted'; + return next; +} + +export function beginHandover(state) { + if (state.phase !== 'active') throw new Error('handover already in progress'); + if (state.wakeReservation) throw new Error('wake reservation unresolved'); + const next = copy(state); + next.phase = 'handover'; + delete next.statePreparation; + return next; +} + +// A reservation is durable and has no expiry: a crashed native call is unknown. +export function reserveWake(state, id, session, generation, nativeQueueId, mode = 'start') { + if (mode !== 'start' || !['active', 'draining'].includes(state.phase) || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); + const matches = state.queue.filter(item => item.id === id && item.state === 'accepted' && !item.wakeEvidence && item.session === session && item.generation === generation && item.nativeQueueId === nativeQueueId); + if (matches.length !== 1 || !session.startsWith('codex:')) throw new Error('wake identity unavailable'); + const next = copy(state); + next.wakeReservation = { id, session, generation, nativeQueueId, mode }; + return next; +} + +export function settleWake(state, proof) { + const reservation = state.wakeReservation; + if (!reservation || (reservation.mode === 'auto-readback' || ['codex-app-server.auto-start-bound-readback', 'codex-app-server.correlated-recovery', 'codex-app-server.correlated-recovery-bound'].includes(proof?.source)) || !['active', 'draining'].includes(state.phase) || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); + const next = copy(state), item = next.queue.find(row => row.id === reservation.id && row.session === reservation.session && row.generation === reservation.generation && row.nativeQueueId === reservation.nativeQueueId && row.state === 'accepted' && !row.wakeEvidence); + if (!item) throw new Error('wake item unavailable'); + item.wakeEvidence = proof.evidence; + const boundWake = proof.schema === 'agent-mesh.codex-wake-evidence.v4' && proof.source === 'codex-app-server.queue-start-bound-readback'; + if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && boundWake && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { + item.state = 'observed'; item.observation = proof.evidence; + } + delete next.wakeReservation; + return next; +} + +// A reserved request is intentionally not retried automatically after a crash. +export function reserveStatePreparation(state, id) { + if (state.phase !== 'handover' || state.statePreparation || !identifier(id)) throw new Error('state preparation unavailable or unresolved'); + if (state.queue.some(item => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); + const next = copy(state); + next.statePreparation = { id, session: state.session, generation: state.generation, status: 'requested' }; + return next; +} + +export function completeStatePreparation(state, proof) { + const pending = state.statePreparation; + if (state.phase !== 'handover' || !pending || pending.status !== 'requested' || pending.session !== state.session || pending.generation !== state.generation || !proof || proof.schema !== 'agent-mesh.handover-state.v1' || proof.nonce !== pending.id || proof.session !== pending.session || !/^[0-9a-f]{64}$/.test(proof.sha256) || typeof proof.filename !== 'string' || !Number.isSafeInteger(proof.bytes) || proof.bytes < 1) throw new Error('state preparation changed or proof invalid'); + const next = copy(state); + next.statePreparation = { ...pending, status: 'verified', filename: proof.filename, sha256: proof.sha256, bytes: proof.bytes }; + return next; +} + +// The durable reservation survives crashes; only authenticated evidence can +// settle it. It does not itself verify the successor or send a notice. +export function reserveFinalNotice(state, id, successor, noticeSha256) { + const handover = state.handover; + if (state.phase !== 'draining' || !handover || state.finalNotice || successor !== state.session || handover.successor !== successor || !identifier(id) || !/^[a-f0-9]{64}$/.test(noticeSha256 || '') || handover.backlog.some(id => !state.queue.some(item => item.id === id && item.state === 'observed' && item.session === successor && item.generation === state.generation))) throw new Error('final notice reservation unavailable'); + const next = copy(state); + next.finalNotice = { id, session: handover.predecessor, generation: handover.previousGeneration, successor, noticeSha256, status: 'requested' }; + return next; +} + +export function recordNoticeQueued(state, receipt) { + const pending = state.finalNotice; + if (state.phase !== 'draining' || !pending || pending.status !== 'requested' || pending.session !== state.handover?.predecessor || pending.generation !== state.handover?.previousGeneration || !receipt || receipt.schema !== 'agent-mesh.notice-queue.v1' || receipt.status !== 'queued-unverified' || receipt.session !== pending.session || receipt.nonce !== pending.id || receipt.noticeSha256 !== pending.noticeSha256) throw new Error('notice queue receipt does not match reservation'); + const next = copy(state); + next.finalNotice.status = 'queued-unverified'; + return next; +} + +// A transcript snapshot is evidence of a completed message at read time, +// not exclusive finality and not authorization to finish a handover. +export function recordNoticeObservation(state, proof) { + const pending = state.finalNotice; + if (state.phase !== 'draining' || !pending || !['requested', 'queued-unverified'].includes(pending.status) || pending.session !== state.handover?.predecessor || pending.generation !== state.handover?.previousGeneration || !proof || proof.schema !== 'agent-mesh.final-notice-observation.v1' || proof.session !== pending.session || proof.nonce !== pending.id || proof.messageSha256 !== pending.noticeSha256 || !/^[a-f0-9]{64}$/.test(proof.transcriptSha256 || '') || !Number.isSafeInteger(proof.bytes) || proof.bytes < 1) throw new Error('notice observation does not match reservation'); + const next = copy(state); + next.finalNotice = { ...pending, status: 'observed-snapshot', transcriptSha256: proof.transcriptSha256, transcriptBytes: proof.bytes }; + return next; +} + +// These are pure transitions. The host must independently authenticate the successor +// and delivery evidence before applying them; the operational cutover stays disabled. +export function switchHandover(state, session, verified) { + if (state.phase !== 'handover' || !identifier(session) || session === state.session || verified !== true) throw new Error('unverified successor'); + if (state.finalNotice || state.queue.some(item => item.state === 'inflight')) throw new Error('unresolved inflight delivery or notice'); + if (state.statePreparation?.status !== 'verified' || state.statePreparation.session !== state.session || state.statePreparation.generation !== state.generation) throw new Error('state preparation unresolved'); + const next = copy(state); + next.handover = { predecessor: state.session, previousGeneration: state.generation, successor: session, backlog: state.queue.filter(item => item.state === 'pending').map(item => item.id) }; + next.session = session; + next.generation += 1; + next.phase = 'draining'; + return next; +} + +// An accepted provider queue receipt is not proof of recipient observation. +export function observeDelivery(state, id, proof) { + const item = state.queue.find(row => row.id === id); + if (state.phase !== 'draining' || !state.handover?.backlog.includes(id) || !item || item.state !== 'accepted' || item.session !== state.session || item.generation !== state.generation || !proof || proof.schema !== 'agent-mesh.delivery-observation.v1' || proof.messageId !== id || proof.session !== item.session || proof.generation !== item.generation || typeof proof.evidence !== 'string' || !identifier(proof.evidence)) throw new Error('delivery observation does not match backlog'); + const next = copy(state), observed = next.queue.find(row => row.id === id); + observed.state = 'observed'; observed.observation = proof.evidence; + return next; +} diff --git a/packages/tmux-bridge/bin/claude-delivery-observation.mjs b/packages/tmux-bridge/bin/claude-delivery-observation.mjs new file mode 100644 index 00000000..cab69f8d --- /dev/null +++ b/packages/tmux-bridge/bin/claude-delivery-observation.mjs @@ -0,0 +1,72 @@ +/** Read-only observation of one managed inbox record in a local Claude transcript. */ +import { constants, lstatSync, realpathSync } from 'node:fs'; +import { lstat, open, realpath, readdir } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { isAbsolute, join, resolve } from 'node:path'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/; +const hash = data => createHash('sha256').update(data).digest('hex'); + +export async function observeClaudeDelivery({ root, session, generation, messageId, payload, snapshotBytes }) { + if (typeof root !== 'string' || !isAbsolute(root) || typeof session !== 'string' || !session.startsWith('claude:') || !UUID.test(session.slice(7)) || !Number.isSafeInteger(generation) || generation < 1 || typeof messageId !== 'string' || !TOKEN.test(messageId) || typeof payload !== 'string' || !payload || Buffer.byteLength(payload) > 65536) throw new Error('invalid delivery observation request'); + if (snapshotBytes !== undefined && (!Number.isSafeInteger(snapshotBytes) || snapshotBytes < 1 || snapshotBytes > 128 * 1024 * 1024)) throw new Error('invalid transcript snapshot size'); + root = resolve(root); + const directory = await lstat(root); + if (!directory.isDirectory() || directory.isSymbolicLink() || directory.uid !== process.getuid() || await realpath(root) !== root) throw new Error('invalid transcript root'); + const entries = await readdir(root, { recursive: true, withFileTypes: true }); + const matches = entries.filter(entry => entry.isFile() && entry.name.toLowerCase() === `${session.slice(7).toLowerCase()}.jsonl`).map(entry => join(entry.parentPath, entry.name)); + if (matches.length !== 1 || await realpath(matches[0]) !== matches[0]) throw new Error('transcript identity unavailable or ambiguous'); + const path = matches[0], file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let bytes, snapshotIdentity; + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o022) !== 0 || before.size < 1 || before.size > 128 * 1024 * 1024) throw new Error('invalid transcript file'); + bytes = await file.readFile(); + const after = await file.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('transcript changed during observation'); + snapshotIdentity = { path, dev: after.dev, ino: after.ino, size: after.size, mtimeMs: after.mtimeMs, ctimeMs: after.ctimeMs }; + } finally { await file.close(); } + if (snapshotBytes !== undefined) { + if (snapshotBytes > bytes.length) throw new Error('transcript snapshot truncated'); + bytes = bytes.subarray(0, snapshotBytes); + } + let text; + try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } + if (!text.endsWith('\n')) throw new Error('partial transcript record'); + let found = 0, queued = 0, queuedLine = null; + for (const line of text.split('\n')) { + if (!line) continue; + let record; try { record = JSON.parse(line); } catch { throw new Error('invalid transcript record'); } + if (!record || typeof record !== 'object' || Array.isArray(record)) throw new Error('invalid transcript record'); + const isQueue = record.type === 'queue-operation' && record.operation === 'enqueue'; + const isUser = record.type === 'user' && !record.isSidechain && record.message?.role === 'user'; + if (!isQueue && !isUser) continue; + const content = isQueue ? record.content : record.message?.content; + const parts = typeof content === 'string' ? [content] : Array.isArray(content) ? content.filter(part => part?.type === 'text' && typeof part.text === 'string').map(part => part.text) : []; + for (const part of parts) for (const entry of part.split('\n')) { + if (!entry.startsWith('AGENT_MESH_INBOX ')) continue; + let inbox; try { inbox = JSON.parse(entry.slice('AGENT_MESH_INBOX '.length)); } catch { throw new Error('invalid inbox record'); } + if (inbox?.deliveryId === messageId || inbox?.meshId === messageId) { + if (record.sessionId !== session.slice(7)) throw new Error('transcript session mismatch'); + if (inbox.schema !== 'agent-mesh.monitor-inbox.v1' || inbox.deliveryId !== messageId || inbox.meshId !== messageId || inbox.prompt !== payload) throw new Error('inbox correlation mismatch'); + if (isQueue) { queued++; queuedLine = entry; } + else { if (queued !== 1 || queuedLine !== entry) throw new Error('matching prior enqueue unavailable'); found++; } + } + } + } + if (queued !== 1 || found !== 1) throw new Error('delivery not uniquely observed'); + const payloadSha256 = hash(payload), transcriptSha256 = hash(bytes); + const evidence = `claude-transcript:${hash(JSON.stringify([session, generation, messageId, payloadSha256, transcriptSha256]))}`; + return { schema: 'agent-mesh.delivery-observation.v1', session, generation, messageId, payloadSha256, transcriptSha256, transcriptBytes: bytes.length, evidence, snapshotIdentity }; +} + +// Narrows the snapshot-to-graph race; it cannot exclude a writer after this check. +export function assertClaudeDeliverySnapshotCurrent(proof) { + const snapshot = proof?.snapshotIdentity; + if (!snapshot || typeof snapshot.path !== 'string' || !isAbsolute(snapshot.path)) throw new Error('transcript snapshot identity unavailable'); + let current; + try { current = lstatSync(snapshot.path); if (realpathSync(snapshot.path) !== snapshot.path) throw new Error(); } + catch { throw new Error('transcript snapshot unavailable'); } + if (!current.isFile() || current.isSymbolicLink() || current.uid !== process.getuid() || current.nlink !== 1 || (current.mode & 0o022) !== 0 || current.dev !== snapshot.dev || current.ino !== snapshot.ino || current.size !== snapshot.size || current.mtimeMs !== snapshot.mtimeMs || current.ctimeMs !== snapshot.ctimeMs) throw new Error('transcript changed after observation'); +} diff --git a/packages/tmux-bridge/bin/cloud-account-binding.mjs b/packages/tmux-bridge/bin/cloud-account-binding.mjs new file mode 100644 index 00000000..8391a3f1 --- /dev/null +++ b/packages/tmux-bridge/bin/cloud-account-binding.mjs @@ -0,0 +1,62 @@ +/** Bind an operator-selected Claude CLI profile to an account scope. */ +import { createHash } from 'node:crypto'; +import { execFile } from 'node:child_process'; +import { constants } from 'node:fs'; +import { lstat, open, realpath } from 'node:fs/promises'; +import { dirname, isAbsolute } from 'node:path'; +import { promisify } from 'node:util'; + +const execute = promisify(execFile); +const SCOPE = /^[a-z][a-z0-9-]{0,63}$/; + +export async function loadClaudeAccountProfile(path, scope, expectedDigest) { + if (typeof path !== 'string' || !isAbsolute(path) || !SCOPE.test(scope || '') || (expectedDigest !== undefined && !/^[0-9a-f]{64}$/.test(expectedDigest))) throw new Error('invalid cloud profile reference'); + const parent = dirname(path), dir = await lstat(parent); + if (!dir.isDirectory() || dir.isSymbolicLink() || dir.uid !== process.getuid() || (dir.mode & 0o077) !== 0 || await realpath(parent) !== parent) throw new Error('cloud profile directory not private'); + const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let bytes; + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 8192) throw new Error('invalid cloud profile file'); + bytes = await file.readFile(); + const after = await file.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('cloud profile changed'); + } finally { await file.close(); } + const digest = createHash('sha256').update(bytes).digest('hex'); + if (expectedDigest !== undefined && digest !== expectedDigest) throw new Error('cloud profile changed'); + let profile; try { profile = JSON.parse(bytes.toString('utf8')); } catch { throw new Error('invalid cloud profile'); } + if (!profile || Object.keys(profile).sort().join(',') !== 'command,configDir,expectedSubjectHash,schema,scope' || profile.schema !== 'agent-mesh.cloud-account.v1' || profile.scope !== scope) throw new Error('cloud profile scope mismatch'); + return { profile, digest }; +} + +// Only a digest is returned. Raw identity and credentials are never returned +// or copied to a receipt; the operator must protect the configured profile. +export function claudeSubjectHash(status) { + if (!status || status.loggedIn !== true || status.apiProvider !== 'firstParty' || status.authMethod !== 'claude.ai' || status.storedClaudeAiLogin !== true || typeof status.email !== 'string' || !status.email.trim() || typeof status.orgId !== 'string' || !status.orgId.trim()) throw new Error('Claude account identity unavailable'); + return createHash('sha256').update(JSON.stringify([status.email.trim().toLowerCase(), status.orgId.trim()])).digest('hex'); +} + +export async function verifyClaudeAccount(profile, run = execute) { + if (!profile || typeof profile.scope !== 'string' || !SCOPE.test(profile.scope) || typeof profile.expectedSubjectHash !== 'string' || !/^[0-9a-f]{64}$/.test(profile.expectedSubjectHash) || typeof profile.configDir !== 'string' || !isAbsolute(profile.configDir) || typeof profile.command !== 'string' || !isAbsolute(profile.command)) throw new Error('invalid cloud account profile'); + const info = await lstat(profile.configDir); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || await realpath(profile.configDir) !== profile.configDir) throw new Error('cloud profile must be private and canonical'); + let output; + try { output = await run(profile.command, ['auth', 'status', '--json'], { env: { ...process.env, CLAUDE_CONFIG_DIR: profile.configDir }, timeout: 10000, maxBuffer: 8192 }); } + catch { throw new Error('Claude account check unavailable'); } + let status; + try { status = JSON.parse(output.stdout); } catch { throw new Error('invalid Claude account response'); } + if (status.configDirectory !== profile.configDir || claudeSubjectHash(status) !== profile.expectedSubjectHash) throw new Error('Claude account scope mismatch'); + return { scope: profile.scope, subjectHash: profile.expectedSubjectHash }; +} + +// Check the same profile before and after an operation. A changed or unreadable +// profile after invocation leaves its result uncertain; callers must not resend. +export async function withClaudeAccount(profile, action, run = execute) { + const binding = await verifyClaudeAccount(profile, run); + let result; + try { result = await action({ scope: binding.scope, configDir: profile.configDir, command: profile.command }); } + catch { throw new Error('cloud operation outcome uncertain'); } + try { await verifyClaudeAccount(profile, run); } + catch { throw new Error('cloud operation outcome uncertain'); } + return result; +} diff --git a/packages/tmux-bridge/bin/codex-app-server.mjs b/packages/tmux-bridge/bin/codex-app-server.mjs index 1027b662..fbc65a14 100644 --- a/packages/tmux-bridge/bin/codex-app-server.mjs +++ b/packages/tmux-bridge/bin/codex-app-server.mjs @@ -64,7 +64,8 @@ function readFrame(buffer) { return { fin: Boolean(buffer[0] & 0x80), opcode: buffer[0] & 0x0f, payload: buffer.subarray(offset, offset + size), end: offset + size }; } -export async function withCodexAppServer({ clientName, timeout, timeoutMessage }, work) { +export async function withCodexAppServer({ clientName, timeout, timeoutMessage, onNotification }, work) { + if (onNotification !== undefined && typeof onNotification !== "function") throw new Error("invalid notification handler"); const path = codexSocket(); const key = randomBytes(16).toString("base64"); const accept = createHash("sha1").update(key + WS_GUID).digest("base64"); @@ -86,7 +87,13 @@ export async function withCodexAppServer({ clientName, timeout, timeoutMessage } let parsed; try { parsed = JSON.parse(text); } catch { rejectAll(new Error("invalid JSON from app-server")); return; } - if (parsed.method) return; + if (parsed.method) { + if (onNotification) { + try { onNotification(parsed); } + catch { rejectAll(new Error("notification handler failed")); socket.destroy(); } + } + return; + } const waiter = pending.get(parsed.id); if (!waiter) return; pending.delete(parsed.id); @@ -163,7 +170,9 @@ export async function withCodexAppServer({ clientName, timeout, timeoutMessage } capabilities: { experimentalApi: true }, }); sendText({ method: "initialized" }); - return await work(request); + const result = await work(request); + if (failure) throw failure; + return result; } finally { clearTimeout(timer); socket.destroy(); diff --git a/packages/tmux-bridge/bin/codex-compaction-evidence.mjs b/packages/tmux-bridge/bin/codex-compaction-evidence.mjs new file mode 100644 index 00000000..b5018086 --- /dev/null +++ b/packages/tmux-bridge/bin/codex-compaction-evidence.mjs @@ -0,0 +1,101 @@ +#!/usr/bin/env node +/** Observe one native compaction and commit an idempotent local evidence reference. */ +import { parseArgs } from 'node:util'; +import { constants } from 'node:fs'; +import { lstat, open, realpath } from 'node:fs/promises'; +import { spawnSync } from 'node:child_process'; +import { createHash } from 'node:crypto'; +import { dirname, isAbsolute, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { withCodexAppServer } from './codex-app-server.mjs'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/; +const hash = text => createHash('sha256').update(text).digest('hex'); +const here = dirname(fileURLToPath(import.meta.url)); + +export function compactionFromThread(response, { thread, turn, item }) { + if (typeof thread !== 'string' || !UUID.test(thread) || typeof turn !== 'string' || !TOKEN.test(turn) || typeof item !== 'string' || !TOKEN.test(item) || response?.thread?.id !== thread || !Array.isArray(response.thread.turns)) throw new Error('native thread identity unavailable'); + const turns = response.thread.turns.filter(value => value?.id === turn); + // The native Turn schema defaults an omitted itemsView to "full". + if (turns.length !== 1 || (turns[0].itemsView !== undefined && turns[0].itemsView !== 'full') || !Array.isArray(turns[0].items) || !['completed', 'interrupted', 'failed', 'inProgress'].includes(turns[0].status)) throw new Error('native turn unavailable or incomplete'); + const items = turns[0].items.filter(value => value?.id === item); + if (items.length !== 1 || items[0].type !== 'contextCompaction' || !Number.isSafeInteger(items[0].completedAtMs) || items[0].completedAtMs <= 0) throw new Error('completed compaction unavailable'); + return { schema: 'agent-mesh.codex-compaction-evidence.v1', source: 'codex-app-server.thread-read', session: `codex:${thread}`, turn, item, completedAtMs: items[0].completedAtMs }; +} + +async function privateRoot(root) { + if (!isAbsolute(root)) throw new Error('invalid evidence root'); + const info = await lstat(root); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('evidence root must be private and canonical'); +} + +async function persistEvidence(root, body) { + await privateRoot(root); + const digest = hash(body), path = join(root, `${digest}.json`); + let file; + try { + file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); + await file.writeFile(body); + await file.sync(); + } catch (error) { + if (error.code !== 'EEXIST') throw error; + file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + const info = await file.stat(); + if (!info.isFile() || info.uid !== process.getuid() || info.nlink !== 1 || (info.mode & 0o077) !== 0 || info.size !== Buffer.byteLength(body) || await file.readFile('utf8') !== body) throw new Error('existing evidence mismatch'); + } finally { if (file) await file.close(); } + const directory = await open(root, constants.O_RDONLY); + try { await directory.sync(); } finally { await directory.close(); } + return `codex-compaction:${digest}`; +} + +/** Verify a record from the operator's trusted private evidence root. */ +export async function verifyCodexCompactionEvidence({ evidenceRoot, reference, session }) { + if (typeof reference !== 'string' || !/^codex-compaction:[a-f0-9]{64}$/.test(reference) || typeof session !== 'string' || !session.startsWith('codex:') || !UUID.test(session.slice(6))) throw new Error('invalid evidence request'); + await privateRoot(evidenceRoot); + const path = join(evidenceRoot, `${reference.slice('codex-compaction:'.length)}.json`); + const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let body; + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 4096) throw new Error('invalid evidence file'); + body = await file.readFile('utf8'); + const after = await file.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('evidence changed during verification'); + } finally { await file.close(); } + if (`codex-compaction:${hash(body)}` !== reference) throw new Error('evidence digest mismatch'); + let value; + try { value = JSON.parse(body); } catch { throw new Error('invalid evidence record'); } + if (!value || Object.keys(value).sort().join(',') !== 'completedAtMs,item,schema,session,source,turn' || `${JSON.stringify(value)}\n` !== body || value.schema !== 'agent-mesh.codex-compaction-evidence.v1' || value.source !== 'codex-app-server.thread-read' || value.session !== session || typeof value.turn !== 'string' || !TOKEN.test(value.turn) || typeof value.item !== 'string' || !TOKEN.test(value.item) || !Number.isSafeInteger(value.completedAtMs) || value.completedAtMs <= 0) throw new Error('evidence identity mismatch'); + return { schema: value.schema, session, turn: value.turn, item: value.item, completedAtMs: value.completedAtMs, evidence: reference }; +} + +export async function recordCodexCompaction({ thread, turn, item, evidenceRoot, graphState }) { + if (typeof thread !== 'string' || !UUID.test(thread) || typeof turn !== 'string' || !TOKEN.test(turn) || typeof item !== 'string' || !TOKEN.test(item) || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('invalid observation identity or graph state'); + await privateRoot(evidenceRoot); + const response = await withCodexAppServer({ clientName: 'agent-mesh-compaction-evidence', timeout: 30000, timeoutMessage: 'native observation timed out' }, request => request('thread/read', { threadId: thread, includeTurns: true })); + const evidence = compactionFromThread(response, { thread, turn, item }); + const reference = await persistEvidence(evidenceRoot, `${JSON.stringify(evidence)}\n`); + const observation = `codex-compaction-${hash(JSON.stringify([thread, turn, item]))}`; + const args = [join(here, 'mesh-graph.mjs'), '--state', graphState]; + args.push('lifecycle', 'record', '--type', 'session.compacted', '--session', evidence.session, '--id', observation, '--evidence', reference); + const result = spawnSync(process.execPath, args, { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (result.error || result.status !== 0) throw new Error('graph recording failed; retain evidence and retry with the same identity'); + let receipt; + try { receipt = JSON.parse(result.stdout); } catch { throw new Error('graph receipt unavailable'); } + if (receipt?.observation !== observation || typeof receipt.duplicate !== 'boolean') throw new Error('graph receipt mismatch'); + return { schema: 'agent-mesh.compaction-record.v1', session: evidence.session, evidence: reference, duplicate: receipt.duplicate }; +} + +if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { + try { + const { values } = parseArgs({ options: { thread: { type: 'string' }, turn: { type: 'string' }, item: { type: 'string' }, verify: { type: 'string' }, session: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' } }, strict: true }); + if (values.verify !== undefined) { + if (values.thread || values.turn || values.item || values['graph-state']) throw new Error('invalid verify options'); + console.log(JSON.stringify(await verifyCodexCompactionEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }))); + } else { + if (values.session) throw new Error('invalid record options'); + console.log(JSON.stringify(await recordCodexCompaction({ thread: values.thread, turn: values.turn, item: values.item, evidenceRoot: values['evidence-root'], graphState: values['graph-state'] }))); + } + } catch { console.error('compaction observation or recording failed; inspect locally before retry'); process.exitCode = 1; } +} diff --git a/packages/tmux-bridge/bin/codex-mcp-observation.mjs b/packages/tmux-bridge/bin/codex-mcp-observation.mjs new file mode 100644 index 00000000..108ad5d9 --- /dev/null +++ b/packages/tmux-bridge/bin/codex-mcp-observation.mjs @@ -0,0 +1,39 @@ +/** Bounded, opt-in app-server sample. It does not start or resume a thread. */ + +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const statuses = new Set(['notStarted', 'starting', 'connected', 'authenticationRequired', 'failed', 'cancelled', 'disabled']); +const validName = name => typeof name === 'string' && name.length > 0 && name.length <= 512 && !/[\x00-\x1f\x7f]/.test(name); + +/** + * Do not treat this as launch or process evidence. Pagination is not an atomic + * snapshot, and the provider does not echo the requested thread in a response. + * A real provider call can restart an MCP; connect only to an isolated fixture. + */ +export async function sampleCodexMcpConnections({ threadId, generation, profileSha256 }, connect) { + if (typeof threadId !== 'string' || !uuid.test(threadId) || !Number.isSafeInteger(generation) || generation < 1 || typeof profileSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(profileSha256) || typeof connect !== 'function') throw new Error('invalid MCP sample request'); + return connect({ clientName: 'agent-mesh-mcp-sample', timeout: 30000, timeoutMessage: 'MCP sample timed out' }, async request => { + const startedAt = new Date().toISOString(), cursors = new Set(), names = new Set(); + let cursor = null, pages = 0, connected = 0, unavailable = 0; + for (;;) { + if (++pages > 32) throw new Error('MCP pagination limit exceeded'); + const result = await request('mcpServerStatus/list', { threadId, cursor, limit: 100, detail: 'toolsAndAuthOnly' }); + if (!result || !Array.isArray(result.data) || !Object.hasOwn(result, 'nextCursor') || !(result.nextCursor === null || (typeof result.nextCursor === 'string' && result.nextCursor.length > 0 && result.nextCursor.length <= 4096))) throw new Error('invalid MCP page'); + for (const item of result.data) { + if (!item || !validName(item.name) || names.has(item.name)) throw new Error('invalid or duplicate MCP identity'); + names.add(item.name); + if (names.size > 4096) throw new Error('MCP sample limit exceeded'); + const status = item.runtimeStatus ?? null; + if (status !== null && !statuses.has(status)) throw new Error('invalid MCP runtime status'); + if (status === 'connected') connected++; + if (status === null) unavailable++; + } + if (result.nextCursor === null) break; + if (cursors.has(result.nextCursor)) throw new Error('MCP cursor loop'); + cursors.add(result.nextCursor); cursor = result.nextCursor; + } + return { schema: 'agent-mesh.codex-mcp-sample.v1', requestedThreadId: threadId, claimedGeneration: generation, + claimedProfileSha256: profileSha256, profileBinding: 'unverified', startedAt, endedAt: new Date().toISOString(), pages, + serversReturned: names.size, connectedObserved: connected, unavailableStatus: unavailable, + completeness: 'unverified-non-atomic', mcpStarted: null, startupTokens: null }; + }); +} diff --git a/packages/tmux-bridge/bin/codex-mcp-startup-notifications.mjs b/packages/tmux-bridge/bin/codex-mcp-startup-notifications.mjs new file mode 100644 index 00000000..5a85201d --- /dev/null +++ b/packages/tmux-bridge/bin/codex-mcp-startup-notifications.mjs @@ -0,0 +1,47 @@ +/** Passive, bounded sampling of already delivered native startup notifications. */ +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const statuses = new Set(['starting', 'ready', 'failed', 'cancelled']); +const legacyApprovalMethods = new Set(['applyPatchApproval', 'execCommandApproval']); +const permissionMethods = new Set(['item/commandExecution/requestApproval', 'item/fileChange/requestApproval', 'item/permissions/requestApproval', 'mcpServer/elicitation/request', ...legacyApprovalMethods]); +const validName = name => typeof name === 'string' && name.length > 0 && name.length <= 512 && !/[\x00-\x1f\x7f]/.test(name); + +// Attach before starting the thread. The native response can bind the thread +// after notifications arrive. Captured names never leave this in-memory object. +export function createCodexMcpStartupObserver() { + const buffered = []; let threadId = null, invalid = false; + return { + onNotification(event) { + const permission = permissionMethods.has(event?.method); + if (!permission && event?.method !== 'mcpServer/startupStatus/updated') return; + const p = event.params; + if (permission) { + const requestId = event.id, subject = legacyApprovalMethods.has(event.method) ? p?.conversationId : p?.threadId; + if (!(typeof requestId === 'string' || (typeof requestId === 'number' && Number.isFinite(requestId))) || typeof subject !== 'string' || !uuid.test(subject)) { invalid = true; return; } + if (threadId && subject !== threadId) return; + if (buffered.length >= 4096) { invalid = true; return; } + buffered.push({ threadId: subject, permission: true }); + return; + } + if (!p || typeof p.threadId !== 'string' || !uuid.test(p.threadId) || !validName(p.name) || !statuses.has(p.status)) { invalid = true; return; } + if (threadId && p.threadId !== threadId) return; + if (buffered.length >= 4096) { invalid = true; return; } + buffered.push({ threadId: p.threadId, name: p.name, status: p.status }); + }, + bindThread(id) { + if (threadId !== null || typeof id !== 'string' || !uuid.test(id)) throw new Error('invalid startup thread binding'); + threadId = id; + }, + snapshot() { + if (!threadId) throw new Error('startup thread is not bound'); + const latest = new Map(); let permissionRequestObserved = null; + for (const row of buffered) if (row.threadId === threadId) { + if (row.permission) permissionRequestObserved = true; + else latest.set(row.name, row.status); + } + const counts = { starting: 0, ready: 0, failed: 0, cancelled: 0 }; + for (const status of latest.values()) counts[status]++; + return { schema: 'agent-mesh.codex-mcp-notification-sample.v1', requestedThreadId: threadId, counts, + completeness: 'unverified', invalidOrOverflow: invalid, permissionRequestObserved, mcpStarted: null, startupTokens: null }; + } + }; +} diff --git a/packages/tmux-bridge/bin/codex-role-mcp-overrides.mjs b/packages/tmux-bridge/bin/codex-role-mcp-overrides.mjs new file mode 100644 index 00000000..1cab0d2e --- /dev/null +++ b/packages/tmux-bridge/bin/codex-role-mcp-overrides.mjs @@ -0,0 +1,21 @@ +/** Prepare explicit exclusions from an operator-supplied effective Codex config. */ +const name = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); +const names = value => Array.isArray(value) && value.length <= 256 && value.every(name) && new Set(value).size === value.length; +const object = value => value !== null && typeof value === 'object' && !Array.isArray(value); + +// This is only a candidate override. Dynamic/plugin servers, changes between +// reading and launching, and permission enforcement require separate evidence. +export function planCodexMcpOverrides({ launchPlan, effectiveServers }) { + if (!object(launchPlan) || launchPlan.schema !== 'agent-mesh.role-launch-plan.v1' || !names(launchPlan.mcpToStart) || !names(launchPlan.mcpUnavailable) || launchPlan.mcpToStart.some(item => launchPlan.mcpUnavailable.includes(item)) || !object(effectiveServers)) throw new Error('invalid MCP override inputs'); + const keys = Object.keys(effectiveServers); + if (keys.length > 4096 || keys.some(key => !name(key) || !object(effectiveServers[key]) || (effectiveServers[key].enabled !== undefined && typeof effectiveServers[key].enabled !== 'boolean'))) throw new Error('invalid effective MCP inventory'); + for (const requested of launchPlan.mcpToStart) { + if (!Object.hasOwn(effectiveServers, requested)) throw new Error('requested MCP missing from effective inventory'); + if (effectiveServers[requested].enabled === false) throw new Error('requested MCP is disabled'); + } + const allowed = new Set(launchPlan.mcpToStart); + const excluded = keys.filter(key => !allowed.has(key)).sort(); + const servers = Object.create(null); + for (const key of excluded) servers[key] = { enabled: false }; + return { schema: 'agent-mesh.codex-mcp-overrides.v1', config: { mcp_servers: servers }, excludedCount: excluded.length, isolation: 'unverified' }; +} diff --git a/packages/tmux-bridge/bin/codex-role-start-assessment.mjs b/packages/tmux-bridge/bin/codex-role-start-assessment.mjs new file mode 100644 index 00000000..6b89ff56 --- /dev/null +++ b/packages/tmux-bridge/bin/codex-role-start-assessment.mjs @@ -0,0 +1,23 @@ +/** Compare a native start response and passive observations to trusted policy. */ +import { isDeepStrictEqual } from 'node:util'; + +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const object = value => value !== null && typeof value === 'object' && !Array.isArray(value); + +// Neither argument authenticates itself. The caller must bind the start response +// and events to the same trusted native connection and authorized role policy. +export function assessCodexRoleStart({ startResponse, sample, expected }) { + if (!object(startResponse) || !object(sample) || sample.schema !== 'agent-mesh.codex-mcp-notification-sample.v1' || !object(expected) || !object(expected.profile) || typeof expected.profile.id !== 'string' || !expected.profile.id || !object(expected.sandbox) || expected.approvalPolicy !== 'never' || typeof startResponse.thread?.id !== 'string' || !uuid.test(startResponse.thread.id) || sample.requestedThreadId !== startResponse.thread.id || ![true, null].includes(sample.permissionRequestObserved) || typeof sample.invalidOrOverflow !== 'boolean' || !object(sample.counts) || !Number.isSafeInteger(sample.counts.ready) || sample.counts.ready < 0) throw new Error('invalid role start observation'); + const failures = []; + if (sample.permissionRequestObserved === true) failures.push('unexpected-permission-request'); + if (startResponse.approvalPolicy !== expected.approvalPolicy) failures.push('approval-policy-mismatch'); + if (startResponse.activePermissionProfile != null && !isDeepStrictEqual(startResponse.activePermissionProfile, expected.profile)) failures.push('permission-profile-mismatch'); + if (startResponse.sandbox != null && !isDeepStrictEqual(startResponse.sandbox, expected.sandbox)) failures.push('sandbox-mismatch'); + const unknown = ['plugin-isolation', 'mcp-coverage', 'startup-tokens']; + if (startResponse.activePermissionProfile == null) unknown.push('permission-profile'); + if (startResponse.sandbox == null) unknown.push('sandbox'); + if (sample.invalidOrOverflow) unknown.push('notification-integrity'); + return { schema: 'agent-mesh.codex-role-start-assessment.v1', session: `codex:${startResponse.thread.id}`, + status: failures.length ? 'rollback-required' : 'observed-incomplete', failures, unknown, + readyObserved: sample.counts.ready, mcpStarted: null, startupTokens: null }; +} diff --git a/packages/tmux-bridge/bin/codex-wake-evidence.mjs b/packages/tmux-bridge/bin/codex-wake-evidence.mjs new file mode 100644 index 00000000..1cb59bd2 --- /dev/null +++ b/packages/tmux-bridge/bin/codex-wake-evidence.mjs @@ -0,0 +1,165 @@ +#!/usr/bin/env node +/** Explicitly start one queued waker turn and record private native evidence. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { spawnSync } from 'node:child_process'; +import { dirname, isAbsolute, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { parseArgs } from 'node:util'; +import { withCodexAppServer } from './codex-app-server.mjs'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/; +const hash = value => createHash('sha256').update(value).digest('hex'); +const here = dirname(fileURLToPath(import.meta.url)); + +async function privateRoot(root) { + if (typeof root !== 'string' || !isAbsolute(root)) throw new Error('invalid evidence root'); + const info = await lstat(root); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('evidence root must be private and canonical'); +} + +async function createDurable(root, name, body) { + const fd = await open(join(root, name), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); + try { await fd.writeFile(body); await fd.sync(); } finally { await fd.close(); } + const directory = await open(root, constants.O_RDONLY); + try { await directory.sync(); } finally { await directory.close(); } +} + +// A readback can contain a steered message while the submission is still queued. +// Keep the durable reservation unresolved until queue consumption is provable. +export async function reconcileCodexWake() { + throw new Error('wake reconciliation disabled: queue consumption is unproven'); +} + +// Disabled: a matching client ID can also come from a steer while the queued +// submission remains pending. Readback alone cannot prove queue consumption. +export async function observeAutoCodexWake() { + throw new Error('auto wake observation disabled: queue consumption is unproven'); +} + +async function wakeReadiness(request, thread, queueId, correlation) { + const read = await request('thread/read', { threadId: thread, includeTurns: false }); + if (read?.thread?.id !== thread || !['idle', 'active', 'notLoaded', 'systemError'].includes(read.thread.status?.type)) throw new Error('native thread status unavailable'); + if (read.thread.status.type !== 'idle') return false; + const queue = await request('thread/queue/list', { threadId: thread, limit: 100 }); + if (!Array.isArray(queue?.data) || queue.nextCursor != null) throw new Error('native queue inventory incomplete'); + return queue.data.filter(item => item?.id === queueId && item.clientUserMessageId === correlation && Array.isArray(item.input)).length === 1; +} + +export async function preflightCodexWake({ thread, queueId, correlation }) { + if (typeof thread !== 'string' || !UUID.test(thread) || typeof queueId !== 'string' || !TOKEN.test(queueId) || typeof correlation !== 'string' || !correlation.startsWith('waker-') || !UUID.test(correlation.slice(6))) throw new Error('invalid wake preflight identity'); + thread = thread.toLowerCase(); + const ready = await withCodexAppServer({ clientName: 'agent-mesh-wake-preflight', timeout: 15000, timeoutMessage: 'native preflight unavailable' }, request => wakeReadiness(request, thread, queueId, correlation)); + return { schema: 'agent-mesh.wake-preflight.v1', session: `codex:${thread}`, queueId, correlation, status: ready ? 'ready' : 'not-ready' }; +} + +export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session }) { + if (typeof reference !== 'string' || !/^codex-wake:[a-f0-9]{64}$/.test(reference) || typeof session !== 'string' || !session.startsWith('codex:') || !UUID.test(session.slice(6))) throw new Error('invalid wake verification request'); + await privateRoot(evidenceRoot); + const path = join(evidenceRoot, `wake-${reference.slice('codex-wake:'.length)}.json`), file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let body; + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 4096) throw new Error('invalid wake evidence file'); + body = await file.readFile('utf8'); + const after = await file.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('wake evidence changed'); + } finally { await file.close(); } + if (`codex-wake:${hash(body)}` !== reference) throw new Error('wake digest mismatch'); + let value; + try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } + const legacy = value && Object.keys(value).sort().join(',') === 'correlation,queueId,schema,session,source,startedAt,turn' && (value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback'); + const bound = value && Object.keys(value).sort().join(',') === 'channel,correlation,generation,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v4' && value.source === 'codex-app-server.queue-start-bound-readback' && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256); + if (!value || `${JSON.stringify(value)}\n` !== body || !(legacy || bound) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); + return { ...value, evidence: reference }; +} + +export async function publishCodexWake({ evidenceRoot, reference, session, graphState, channel }) { + if (typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit graph state required'); + const proof = await verifyCodexWakeEvidence({ evidenceRoot, reference, session }); + const observation = `codex-wake-${hash(JSON.stringify([session, proof.queueId]))}`; + const result = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'lifecycle', 'record', '--type', 'session.woken', '--session', session, '--id', observation, '--evidence', reference], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (result.error || result.status !== 0) throw new Error('graph recording failed; retain evidence for explicit publication'); + let receipt; try { receipt = JSON.parse(result.stdout); } catch { throw new Error('graph receipt unavailable'); } + if (receipt?.observation !== observation || typeof receipt.duplicate !== 'boolean') throw new Error('graph receipt mismatch'); + if (channel !== undefined) { + const settled = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'settle-wake', '--name', channel, '--session', session, '--state-root', evidenceRoot, '--input', reference], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (settled.error || settled.status !== 0) throw new Error('wake settlement unavailable; retain evidence for recovery'); + let status; try { status = JSON.parse(settled.stdout); } catch { throw new Error('wake settlement receipt unavailable'); } + const item = status?.channel?.queue?.find(row => row.id === proof.correlation && row.session === session && row.nativeQueueId === proof.queueId); + if (item?.wakeEvidence !== reference) throw new Error('wake settlement receipt mismatch'); + } + return { schema: 'agent-mesh.wake-record.v1', session, evidence: reference, duplicate: receipt.duplicate, ...(channel !== undefined ? { settled: true } : {}) }; +} + +export async function startCodexWake({ thread, queueId, correlation, channel, generation, evidenceRoot, graphState, apply }) { + if (apply !== true || typeof thread !== 'string' || !UUID.test(thread) || typeof queueId !== 'string' || !TOKEN.test(queueId) || typeof correlation !== 'string' || !correlation.startsWith('waker-') || !UUID.test(correlation.slice(6)) || typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel) || !Number.isSafeInteger(generation) || generation < 1 || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit wake identity, channel, generation, graph and apply required'); + await privateRoot(evidenceRoot); + await privateRoot(graphState); + thread = thread.toLowerCase(); + const session = `codex:${thread}`; + const result = await spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'show', '--json'], { encoding: 'utf8', timeout: 30000, maxBuffer: 32 * 1024 * 1024 }); + let graph; try { graph = JSON.parse(result.stdout); } catch { throw new Error('graph unavailable'); } + const matches = Array.isArray(graph.nodes) ? graph.nodes.filter(node => node.agent === 'codex' && node.runtimeUuid === thread) : []; + if (result.error || result.status !== 0 || !graph.migrated || matches.length !== 1 || matches[0].status === 'closed' || matches[0].surface?.archived === true) throw new Error('wake session not registered or closed'); + const intent = hash(JSON.stringify([session, queueId])); + const evidence = await withCodexAppServer({ clientName: 'agent-mesh-wake-evidence', timeout: 30000, timeoutMessage: 'native wake outcome uncertain' }, async request => { + if (!await wakeReadiness(request, thread, queueId, correlation)) throw new Error('native wake not ready'); + const listed = await request('thread/queue/list', { threadId: thread, limit: 100 }); + if (!Array.isArray(listed?.data) || listed.nextCursor != null || listed.data.filter(item => item?.id === queueId && item.clientUserMessageId === correlation && Array.isArray(item.input)).length !== 1) throw new Error('queued waker identity unavailable'); + const reserved = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'reserve-wake', '--name', channel, '--id', correlation, '--session', session, '--generation', String(generation), '--input', queueId], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (reserved.error || reserved.status !== 0) throw new Error('wake reservation unavailable or uncertain'); + let reservedChannel; try { reservedChannel = JSON.parse(reserved.stdout)?.channel; } catch { throw new Error('wake reservation receipt unavailable'); } + const reservation = reservedChannel?.wakeReservation; + if (!reservation || reservation.id !== correlation || reservation.session !== session || reservation.generation !== generation || reservation.nativeQueueId !== queueId) throw new Error('wake reservation receipt mismatch'); + const queued = listed.data.find(item => item?.id === queueId && item.clientUserMessageId === correlation); + const boundItems = Array.isArray(reservedChannel.queue) ? reservedChannel.queue.filter(item => item.id === correlation && item.session === session && item.generation === generation && item.nativeQueueId === queueId && item.state === 'accepted' && typeof item.payload === 'string') : []; + if (reservedChannel.id !== channel || reservedChannel.session !== session || reservedChannel.generation !== generation || boundItems.length !== 1 || JSON.stringify(queued.input) !== JSON.stringify([{ type: 'text', text: boundItems[0].payload, text_elements: [] }])) throw new Error('native queue payload does not match channel reservation'); + await createDurable(evidenceRoot, `intent-${intent}.json`, `${JSON.stringify({ schema: 'agent-mesh.codex-wake-intent.v1', session, queueId, correlation })}\n`); + const started = await request('thread/queue/start', { threadId: thread, queuedSubmissionId: queueId }); + const turn = started?.turn; + if (!turn || typeof turn.id !== 'string' || !UUID.test(turn.id) || turn.status !== 'inProgress' || (turn.startedAt != null && (!Number.isSafeInteger(turn.startedAt) || turn.startedAt <= 0))) throw new Error('native wake outcome uncertain'); + // Some runtimes return a valid start with startedAt=null before the turn is + // persisted. Poll only readback; never repeat queue/start after acceptance. + const attempts = turn.startedAt == null ? 21 : 1; + let startedAt; + for (let i = 0; i < attempts; i++) { + const readback = await request('thread/read', { threadId: thread, includeTurns: true }); + const observed = readback?.thread; + if (observed?.id !== thread || !Array.isArray(observed.turns)) throw new Error('wake readback unavailable; outcome uncertain'); + const turns = observed.turns.filter(item => item?.id === turn.id); + if (turns.length > 1) throw new Error('wake readback ambiguous'); + const observedTurn = turns[0]; + const messages = Array.isArray(observedTurn?.items) ? observedTurn.items.filter(item => item?.type === 'userMessage' && item.clientId === correlation) : []; + if (messages.length > 1 || (messages.length === 1 && (!Array.isArray(messages[0].content) || JSON.stringify(messages[0].content) !== JSON.stringify(queued.input)))) throw new Error('wake readback mismatch'); + if (observedTurn && (observedTurn.itemsView === undefined || observedTurn.itemsView === 'full') && Number.isSafeInteger(observedTurn.startedAt) && observedTurn.startedAt > 0 && messages.length === 1) { + if (turn.startedAt != null && observedTurn.startedAt !== turn.startedAt) throw new Error('wake readback timestamp mismatch'); + startedAt = observedTurn.startedAt; break; + } + if (i + 1 < attempts) await new Promise(resolve => setTimeout(resolve, 200)); + } + if (!startedAt) throw new Error('wake readback unavailable; outcome uncertain'); + return { schema: 'agent-mesh.codex-wake-evidence.v4', source: 'codex-app-server.queue-start-bound-readback', session, queueId, correlation, turn: turn.id, startedAt, channel, generation, payloadSha256: hash(boundItems[0].payload) }; + }); + const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; + await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); + return publishCodexWake({ evidenceRoot, reference, session, graphState, channel }); +} + +if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { + try { + const { values } = parseArgs({ options: { apply: { type: 'boolean' }, preflight: { type: 'boolean' }, reconcile: { type: 'boolean' }, 'observe-auto': { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); + if (values.preflight && (values.apply || values.reconcile || values['observe-auto'] || values.verify || values.publish)) throw new Error('conflicting wake operations'); + if (values['observe-auto'] && (values.reconcile || values.verify || values.publish)) throw new Error('conflicting wake operations'); + let result; + if (values.preflight) result = await preflightCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation }); + else if (values['observe-auto']) result = await observeAutoCodexWake({ channel: values.channel, thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + else if (values.reconcile) result = await reconcileCodexWake({ channel: values.channel, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + else if (values.verify) result = await verifyCodexWakeEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }); + else if (values.publish) result = await publishCodexWake({ evidenceRoot: values['evidence-root'], reference: values.publish, session: values.session, graphState: values['graph-state'], channel: values.channel }); + else result = await startCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, channel: values.channel, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + console.log(JSON.stringify(result)); + } catch { console.error('wake observation failed or outcome uncertain; inspect before retry'); process.exitCode = 1; } +} diff --git a/packages/tmux-bridge/bin/handover-claude-observation.mjs b/packages/tmux-bridge/bin/handover-claude-observation.mjs new file mode 100644 index 00000000..2123c009 --- /dev/null +++ b/packages/tmux-bridge/bin/handover-claude-observation.mjs @@ -0,0 +1,63 @@ +/** Read-only final-notice evidence from one stable local Claude transcript snapshot. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath, readdir } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { isAbsolute, join, resolve } from 'node:path'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const MAX_TRANSCRIPT = 128 * 1024 * 1024; + +/** Proves only the stable snapshot read; later turns can invalidate the notice. */ +export async function observeClaudeFinalNotice({ root, id, nonce, message }) { + if (typeof root !== 'string' || !isAbsolute(root) || typeof id !== 'string' || !UUID.test(id) || + typeof nonce !== 'string' || !nonce.startsWith('handover-') || !UUID.test(nonce.slice('handover-'.length)) || + typeof message !== 'string' || !message || Buffer.byteLength(message) > 8192) throw new Error('invalid notice observation request'); + root = resolve(root); + const directory = await lstat(root); + if (!directory.isDirectory() || directory.isSymbolicLink() || await realpath(root) !== root) throw new Error('invalid transcript root'); + const entries = await readdir(root, { recursive: true, withFileTypes: true }); + const candidates = entries.filter(entry => entry.isFile() && entry.name.toLowerCase() === `${id.toLowerCase()}.jsonl`) + .map(entry => join(entry.parentPath, entry.name)); + if (candidates.length !== 1) throw new Error('transcript identity unavailable or ambiguous'); + const path = candidates[0]; + if (await realpath(path) !== path) throw new Error('non-canonical transcript'); + const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let bytes; + try { + const before = await handle.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o022) !== 0 || before.size < 1 || before.size > MAX_TRANSCRIPT) throw new Error('invalid transcript file'); + bytes = await handle.readFile(); + const after = await handle.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('transcript changed during observation'); + } finally { await handle.close(); } + let text; + try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } + if (!text.endsWith('\n')) throw new Error('partial transcript record'); + let anchored = false, responseId = null, answer = '', completed = false; + for (const line of text.split('\n')) { + if (!line) continue; + let record; + try { record = JSON.parse(line); } catch { throw new Error('invalid transcript record'); } + if (!record || typeof record !== 'object' || Array.isArray(record)) throw new Error('invalid transcript record'); + if (record.isSidechain || record.isMeta || !['user', 'assistant'].includes(record.type)) continue; + if (record.sessionId !== id) throw new Error('transcript session mismatch'); + const content = record.message?.content; + if (record.type === 'user') { + const parts = typeof content === 'string' ? [content] : Array.isArray(content) ? content.filter(part => part?.type === 'text' && typeof part.text === 'string').map(part => part.text) : []; + if (parts.length) { anchored = parts.join('\n').includes(`[HANDOVER:${nonce}]`); responseId = null; answer = ''; completed = false; } + continue; + } + if (!anchored) continue; + const native = record.message; + if (!native || typeof native.id !== 'string' || !native.id || !Array.isArray(content)) throw new Error('invalid assistant record'); + if (native.id !== responseId) { responseId = native.id; answer = ''; completed = false; } + const toolUse = content.some(part => part?.type === 'tool_use'); + const parts = content.filter(part => part?.type === 'text' && typeof part.text === 'string').map(part => part.text); + if (parts.length) answer += parts.join('\n'); + if (native.stop_reason === 'end_turn' && !toolUse) completed = true; + else if (native.stop_reason !== null && native.stop_reason !== undefined) completed = false; + } + if (!anchored || !completed || answer !== message) throw new Error('final notice not proven in transcript snapshot'); + return { schema: 'agent-mesh.final-notice-observation.v1', session: `claude:${id}`, nonce, + messageSha256: createHash('sha256').update(message).digest('hex'), transcriptSha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length }; +} diff --git a/packages/tmux-bridge/bin/handover-codex-observation.mjs b/packages/tmux-bridge/bin/handover-codex-observation.mjs new file mode 100644 index 00000000..00712de5 --- /dev/null +++ b/packages/tmux-bridge/bin/handover-codex-observation.mjs @@ -0,0 +1,75 @@ +/** Read-only final-notice evidence from a local Codex transcript snapshot. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath, readdir } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { isAbsolute, join, resolve } from 'node:path'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const MAX_TRANSCRIPT = 128 * 1024 * 1024; + +function textOf(record, role) { + const payload = record?.payload; + if (record?.type === 'event_msg' && payload?.type === (role === 'user' ? 'user_message' : 'agent_message')) return typeof payload.message === 'string' ? payload.message : null; + if (record?.type !== 'response_item' || payload?.type !== 'message' || payload.role !== role || !Array.isArray(payload.content)) return null; + const type = role === 'user' ? 'input_text' : 'output_text'; + const parts = payload.content.filter(item => item?.type === type && typeof item.text === 'string').map(item => item.text); + return parts.length ? parts.join('\n') : null; +} + +/** An observation proves only the snapshot read; a later turn may still arrive. */ +export async function observeCodexFinalNotice({ root, id, nonce, message }) { + if (!isAbsolute(root) || typeof id !== 'string' || !UUID.test(id) || typeof nonce !== 'string' || !nonce.startsWith('handover-') || !UUID.test(nonce.slice('handover-'.length)) || + typeof message !== 'string' || !message || Buffer.byteLength(message) > 8192) throw new Error('invalid notice observation request'); + root = resolve(root); + const directory = await lstat(root); + if (!directory.isDirectory() || directory.isSymbolicLink() || await realpath(root) !== root) throw new Error('invalid transcript root'); + const entries = await readdir(root, { recursive: true, withFileTypes: true }); + const candidates = entries.filter(entry => entry.isFile() && entry.name.toLowerCase().endsWith(`${id.toLowerCase()}.jsonl`)) + .map(entry => join(entry.parentPath, entry.name)); + if (candidates.length !== 1) throw new Error('transcript identity unavailable or ambiguous'); + const path = candidates[0]; + if (await realpath(path) !== path) throw new Error('non-canonical transcript'); + const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let bytes; + try { + const before = await handle.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o022) !== 0 || before.size < 1 || before.size > MAX_TRANSCRIPT) throw new Error('invalid transcript file'); + bytes = await handle.readFile(); + const after = await handle.stat(); + const current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('transcript changed during observation'); + } finally { await handle.close(); } + let text; + try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } + if (!text.endsWith('\n')) throw new Error('partial transcript record'); + let meta = false, anchored = false, lastAssistant = null, completed = false; + for (const line of text.split('\n')) { + if (!line) continue; + let record; + try { record = JSON.parse(line); } catch { throw new Error('invalid transcript record'); } + if (!record || typeof record !== 'object' || Array.isArray(record)) throw new Error('invalid transcript record'); + if (record.type === 'session_meta') { + if (meta || record?.payload?.id !== id) throw new Error('transcript session mismatch'); + meta = true; + continue; + } + if (!meta) throw new Error('transcript session metadata missing'); + const user = textOf(record, 'user'); + if (user !== null) { + const newAnchor = user.includes(`[HANDOVER:${nonce}]`); + // Native transcripts can repeat the same user message in two formats. + if (!(anchored && newAnchor && lastAssistant === null && !completed)) { anchored = newAnchor; lastAssistant = null; completed = false; } + continue; + } + if (record.type === 'event_msg' && record?.payload?.type === 'task_started' && completed) { anchored = false; completed = false; lastAssistant = null; } + if (anchored && record.type === 'response_item' && ['function_call', 'custom_tool_call'].includes(record?.payload?.type)) { lastAssistant = null; completed = false; } + const assistant = textOf(record, 'assistant'); + if (assistant !== null && anchored) { if (completed) completed = false; lastAssistant = assistant; } + if (record.type === 'event_msg' && record?.payload?.type === 'task_complete' && anchored) { + completed = lastAssistant === message && record.payload.last_agent_message === message; + } + } + if (!meta || !anchored || !completed) throw new Error('final notice not proven in transcript snapshot'); + return { schema: 'agent-mesh.final-notice-observation.v1', session: `codex:${id}`, nonce, + messageSha256: createHash('sha256').update(message).digest('hex'), transcriptSha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length }; +} diff --git a/packages/tmux-bridge/bin/handover-dry-run.mjs b/packages/tmux-bridge/bin/handover-dry-run.mjs new file mode 100644 index 00000000..c37ca21b --- /dev/null +++ b/packages/tmux-bridge/bin/handover-dry-run.mjs @@ -0,0 +1,20 @@ +/** In-memory rehearsal only. No native session, service, timer or graph is changed. */ +import { beginHandover, createChannel, enqueue, switchHandover, reserveStatePreparation, completeStatePreparation } from './channel-state.mjs'; +import { planRoleLaunch, assessRoleLaunch } from './role-launch-profile.mjs'; + +export async function rehearseHandover({ role, oldSession, newSession, profile, authority, offlineMcp = [], fault = 'none', messageDuringHandover = false }) { + if (typeof role !== 'string' || profile?.role !== role || !['none', 'interrupted', 'quota', 'permission'].includes(fault) || !Array.isArray(offlineMcp) || !offlineMcp.every(name => typeof name === 'string') || typeof messageDuringHandover !== 'boolean') throw new Error('invalid rehearsal'); + let channel = beginHandover(createChannel(`fixture-${role}`, oldSession)); + if (messageDuringHandover) channel = enqueue(channel, 'fixture-message', 'synthetic message'); + const plan = await planRoleLaunch({ profile, authority, probe: async name => !offlineMcp.includes(name) }); + const observed = { mcpStarted: [...plan.mcpToStart], pluginsStarted: [...plan.plugins], permissionPrompt: fault === 'permission', startupTokens: null }; + const launch = assessRoleLaunch({ plan, observed }); + if (fault === 'interrupted' || fault === 'quota' || launch.status !== 'ready') { + channel = { ...channel, phase: 'active' }; + return { schema: 'agent-mesh.handover-rehearsal.v1', simulated: true, outcome: 'rolled-back', reason: fault === 'none' ? launch.reason : fault, channel, launch }; + } + channel = reserveStatePreparation(channel, 'fixture-state'); + channel = completeStatePreparation(channel, { schema: 'agent-mesh.handover-state.v1', session: oldSession, nonce: 'fixture-state', filename: 'fixture.yaml', sha256: 'a'.repeat(64), bytes: 1 }); + channel = switchHandover(channel, newSession, true); + return { schema: 'agent-mesh.handover-rehearsal.v1', simulated: true, outcome: 'switched-awaiting-delivery', reason: null, channel, launch }; +} diff --git a/packages/tmux-bridge/bin/handover-notice-transport.mjs b/packages/tmux-bridge/bin/handover-notice-transport.mjs new file mode 100644 index 00000000..455f37df --- /dev/null +++ b/packages/tmux-bridge/bin/handover-notice-transport.mjs @@ -0,0 +1,54 @@ +/** Native queue adapter; this module does not authorize or perform a cutover. */ +import { execFile } from 'node:child_process'; +import { createHash } from 'node:crypto'; +import { dirname, isAbsolute, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { formatFinalNotice } from './handover-notice.mjs'; +import { observeCodexFinalNotice } from './handover-codex-observation.mjs'; +import { observeClaudeFinalNotice } from './handover-claude-observation.mjs'; + +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const nativeBin = join(dirname(fileURLToPath(import.meta.url)), 'agent-native-call.mjs'); +const digest = value => createHash('sha256').update(value).digest('hex'); +const exec = (command, args, { input, ...options }) => new Promise((resolve, reject) => { + const child = execFile(command, args, options, (error, stdout) => error ? reject(new Error('native notice delivery uncertain')) : resolve({ stdout })); + child.stdin.on('error', () => {}); + child.stdin.end(input); +}); + +/** The caller must first durably reserve this nonce and verify the successor. */ +export async function queueLocalFinalNotice({ session, nonce, target, label, prefix, managedInboxRoot }, runNative = exec) { + if (typeof session !== 'string') throw new Error('invalid local notice session'); + const [agent, id, ...extra] = session.split(':'); + if (!['codex', 'claude'].includes(agent) || !uuid.test(id || '') || extra.length || typeof nonce !== 'string' || !nonce.startsWith('handover-') || !uuid.test(nonce.slice('handover-'.length))) throw new Error('invalid local notice request'); + if (agent === 'claude' && (typeof managedInboxRoot !== 'string' || !isAbsolute(managedInboxRoot))) throw new Error('managed inbox required'); + if (agent === 'codex' && managedInboxRoot !== undefined) throw new Error('managed inbox only for Claude'); + const notice = formatFinalNotice({ target, label, prefix }); + const prompt = `[HANDOVER:${nonce}] The successor has been verified. As your final message, output exactly the following notice and nothing else. Do not call any tools after writing it.\n${notice}`; + const args = [nativeBin, '--agent', agent, '--session', id, '--correlation-id', nonce, '--timeout', '5', '--message-stdin', '--delivery-only']; + if (agent === 'codex') args.push('--no-resume'); + else args.push('--managed-inbox-root', managedInboxRoot); + let result; + try { result = await runNative(process.execPath, args, { input: prompt, timeout: 10000, maxBuffer: 8192 }); } + catch { throw new Error('native notice delivery uncertain; do not resend'); } + let receipt; + try { receipt = JSON.parse(result?.stdout); } catch { throw new Error('native notice delivery uncertain; do not resend'); } + if (!receipt || receipt.agent !== agent || receipt.sessionId !== id || receipt.correlationId !== nonce || receipt.held === true || receipt.status !== 'queued') throw new Error('native notice delivery unconfirmed; do not resend'); + return { schema: 'agent-mesh.notice-queue.v1', session, nonce, noticeSha256: digest(notice), status: 'queued-unverified' }; +} + +/** Call only after reserving in the trusted graph and acquiring lifecycle exclusion. */ +export async function queueReservedFinalNotice({ reservation, target, label, prefix, managedInboxRoot }, runNative = exec) { + if (!reservation || reservation.status !== 'requested' || typeof reservation.session !== 'string' || typeof reservation.id !== 'string' || !target || target.kind !== 'codex' || reservation.successor !== `codex:${target.id}` || reservation.noticeSha256 !== digest(formatFinalNotice({ target, label, prefix }))) throw new Error('final notice reservation does not match request'); + return queueLocalFinalNotice({ session: reservation.session, nonce: reservation.id, target, label, prefix, managedInboxRoot }, runNative); +} + +/** Obtain local native transcript evidence independently from the queue receipt. */ +export async function observeLocalFinalNotice({ session, nonce, target, label, prefix, transcriptRoot }) { + if (typeof session !== 'string') throw new Error('invalid local notice session'); + const [agent, id, ...extra] = session.split(':'); + if (!['codex', 'claude'].includes(agent) || !uuid.test(id || '') || extra.length) throw new Error('invalid local notice session'); + const message = formatFinalNotice({ target, label, prefix }); + const observe = agent === 'codex' ? observeCodexFinalNotice : observeClaudeFinalNotice; + return observe({ root: transcriptRoot, id, nonce, message }); +} diff --git a/packages/tmux-bridge/bin/handover-notice.mjs b/packages/tmux-bridge/bin/handover-notice.mjs new file mode 100644 index 00000000..8ab384c4 --- /dev/null +++ b/packages/tmux-bridge/bin/handover-notice.mjs @@ -0,0 +1,32 @@ +/** Build a successor link from resolved identifiers, never from a guessed URL. */ +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const projectId = /^[A-Za-z0-9_-]{1,256}$/; +const threadId = /^cmsg_[A-Za-z0-9_-]{1,250}$/; + +export function successorLink(target) { + if (!target || typeof target !== 'object') throw new Error('invalid successor'); + if (target.kind === 'codex' && typeof target.id === 'string' && uuid.test(target.id)) return `codex://threads/${target.id}`; + if (target.kind === 'cloud' && typeof target.sourceProject === 'string' && projectId.test(target.sourceProject) && + typeof target.targetProject === 'string' && projectId.test(target.targetProject) && + typeof target.thread === 'string' && threadId.test(target.thread)) { + return target.sourceProject === target.targetProject ? `#${target.thread}` : + `https://claude.ai/code/project/${target.targetProject}?thread=${target.thread}`; + } + throw new Error('invalid successor link identifiers'); +} + +export function formatFinalNotice({ target, label, prefix }) { + if (typeof label !== 'string' || !label.trim() || label.length > 300 || /[\r\n\x00-\x1f\x7f]/.test(label) || + typeof prefix !== 'string' || !prefix.trim() || prefix.length > 500 || /[\r\n\x00-\x1f\x7f]/.test(prefix)) throw new Error('invalid notice text'); + const escaped = label.replace(/[\\\[\]]/g, '\\$&'); + return `${prefix} [${escaped}](${successorLink(target)})`; +} + +/** Compare a trusted, complete transcript observation; this does not obtain one. */ +export function matchesFinalNotice(observation, { session, message }) { + if (!observation || observation.complete !== true || observation.session !== session || + typeof session !== 'string' || !session || typeof message !== 'string' || !message || + !Array.isArray(observation.messages) || !observation.messages.length) return false; + const last = observation.messages.at(-1); + return Boolean(last && last.role === 'assistant' && last.text === message); +} diff --git a/packages/tmux-bridge/bin/handover-state-proof.mjs b/packages/tmux-bridge/bin/handover-state-proof.mjs new file mode 100644 index 00000000..c3c247e8 --- /dev/null +++ b/packages/tmux-bridge/bin/handover-state-proof.mjs @@ -0,0 +1,90 @@ +/** Verify an actor's correlated response against a private state file. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { randomUUID } from 'node:crypto'; +import { execFile, spawnSync } from 'node:child_process'; +import { dirname, isAbsolute, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { validateRestartState } from './restart-state.mjs'; + +const nativeBin = join(dirname(fileURLToPath(import.meta.url)), 'agent-native-call.mjs'); +const yamlBin = join(dirname(fileURLToPath(import.meta.url)), 'restart-yaml.py'); +const exec = (command, args, { input, ...options }) => new Promise((resolve, reject) => { + const child = execFile(command, args, options, (error, stdout) => { + if (error) reject(new Error('native state request failed')); + else resolve({ stdout }); + }); + child.stdin.on('error', () => {}); + child.stdin.end(input); +}); + +// reserve and complete are atomic host mutations; a failed request deliberately +// leaves the reservation unresolved so a caller cannot silently resend it. +export async function prepareState({ reserve, request, complete }) { + const reservation = reserve(); + const pending = reservation?.statePreparation; + if (!pending || pending.status !== 'requested' || typeof pending.session !== 'string' || typeof pending.id !== 'string') throw new Error('state preparation reservation unavailable'); + const proof = await request(pending); + return complete(proof); +} + +/** Obtain a correlated native-session result, then bind it to file bytes. */ +export async function requestStateProof({ session, channel, root, filename, managedInboxRoot, nonce = `handover-${randomUUID()}` }, runNative = exec) { + if (!/^(codex|claude):[0-9a-f-]{36}$/.test(session) || !isAbsolute(root) || /[\r\n\x00]/.test(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error('invalid state proof request'); + const rootInfo = await lstat(root); + if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink() || rootInfo.uid !== process.getuid() || (rootInfo.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('state root must be private and canonical'); + const [agent, nativeId] = session.split(':'); + if (agent === 'claude' && (typeof managedInboxRoot !== 'string' || !isAbsolute(managedInboxRoot))) throw new Error('managed inbox required'); + if (typeof nonce !== 'string' || !/^[a-zA-Z0-9._:-]{1,128}$/.test(nonce)) throw new Error('invalid request nonce'); + if (typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel)) throw new Error('invalid state proof channel'); + const message = `Write your handover state with a RIAVVIO YAML block using agent-mesh.restart.v1 to ${join(root, filename)} with private permissions. Bind the block to session ${session} and channel ${channel}, and include harness, working_directory, skills, triggers, goal and role_profile with schema agent-mesh.role-profile.v1, role and exact identifier lists permissions, mcp, plugins. List only existing grants; do not grant anything. Return only JSON with schema agent-mesh.handover-state.v1, session ${session}, nonce ${nonce}, filename ${filename}, and sha256 containing the lowercase SHA-256 of the completed file.`; + const argv = [nativeBin, '--agent', agent, '--session', nativeId, '--correlation-id', nonce, '--timeout', '120', '--message-stdin']; + if (agent === 'codex') argv.push('--no-resume'); + if (agent === 'claude') argv.push('--managed-inbox-root', managedInboxRoot); + const result = await runNative(process.execPath, argv, { input: message, timeout: 125000, maxBuffer: 8192 }); + if (!result || typeof result.stdout !== 'string') throw new Error('native result unavailable'); + return verifyStateResponse({ session, channel, nonce, response: result.stdout, root, filename }); +} + +// The caller must obtain response from the native correlated-result transport, +// bound to session and nonce. This function cannot authenticate arbitrary text. +export async function verifyStateResponse({ session, channel, nonce, response, root, filename }) { + if (!/^(codex|claude):[0-9a-f-]{36}$/.test(session) || !/^[a-zA-Z0-9._:-]{1,128}$/.test(nonce) || !isAbsolute(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error('invalid state proof request'); + const rootInfo = await lstat(root); + if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink() || rootInfo.uid !== process.getuid() || (rootInfo.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('state root must be private and canonical'); + if (typeof response !== 'string' || Buffer.byteLength(response) > 8192) throw new Error('invalid state response'); + let attestation; + try { attestation = JSON.parse(response); } catch { throw new Error('invalid state response'); } + if (!attestation || attestation.schema !== 'agent-mesh.handover-state.v1' || attestation.session !== session || attestation.nonce !== nonce || attestation.filename !== filename || !/^[0-9a-f]{64}$/.test(attestation.sha256)) throw new Error('state response binding mismatch'); + const file = await open(join(root, filename), constants.O_RDONLY | constants.O_NOFOLLOW); + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 1024 * 1024) throw new Error('invalid state file'); + const bytes = await file.readFile(); + const after = await file.stat(), current = await lstat(join(root, filename)), currentRoot = await lstat(root); + if (!current.isFile() || current.isSymbolicLink() || current.ino !== after.ino || current.dev !== after.dev || current.size !== after.size || current.mtimeMs !== after.mtimeMs || current.ctimeMs !== after.ctimeMs || !currentRoot.isDirectory() || currentRoot.isSymbolicLink() || currentRoot.ino !== rootInfo.ino || currentRoot.dev !== rootInfo.dev || before.ino !== after.ino || before.dev !== after.dev || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('state file changed during verification'); + const digest = createHash('sha256').update(bytes).digest('hex'); + if (digest !== attestation.sha256) throw new Error('state file digest mismatch'); + if (typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel)) throw new Error('invalid state proof channel'); + const decoded = spawnSync(process.env.PYTHON || 'python3', ['-I', yamlBin], { input: bytes, encoding: 'utf8', timeout: 10000, maxBuffer: 2 * 1024 * 1024 }); + if (decoded.error || decoded.status !== 0) throw new Error('restart YAML unavailable or invalid'); + let restart; + try { restart = JSON.parse(decoded.stdout); } catch { throw new Error('invalid restart YAML result'); } + validateRestartState(restart, { session, channel, requireRoleProfile: true }); + const final = await lstat(join(root, filename)), finalRoot = await lstat(root); + if (!final.isFile() || final.isSymbolicLink() || final.dev !== after.dev || final.ino !== after.ino || final.size !== after.size || final.mtimeMs !== after.mtimeMs || final.ctimeMs !== after.ctimeMs || !finalRoot.isDirectory() || finalRoot.isSymbolicLink() || finalRoot.dev !== rootInfo.dev || finalRoot.ino !== rootInfo.ino) throw new Error('state file changed during verification'); + return { schema: attestation.schema, session, nonce, filename, sha256: digest, bytes: bytes.length }; + } finally { await file.close(); } +} + +// Revalidate the bytes referenced by a previously authenticated graph receipt. +// The caller owns lifecycle exclusion and must also bind this check to its +// subsequent action; a snapshot cannot prevent later file replacement. +export async function revalidateStateProof({ root, channel, session, generation, statePreparation }) { + if (!statePreparation || statePreparation.status !== 'verified' || statePreparation.session !== session || !Number.isSafeInteger(generation) || generation < 1 || statePreparation.generation !== generation || typeof statePreparation.id !== 'string' || typeof statePreparation.filename !== 'string' || !/^[0-9a-f]{64}$/.test(statePreparation.sha256 || '') || !Number.isSafeInteger(statePreparation.bytes) || statePreparation.bytes < 1) throw new Error('state preparation receipt mismatch'); + const response = JSON.stringify({ schema: 'agent-mesh.handover-state.v1', session, nonce: statePreparation.id, filename: statePreparation.filename, sha256: statePreparation.sha256 }); + const result = await verifyStateResponse({ session, channel, nonce: statePreparation.id, response, root, filename: statePreparation.filename }); + if (result.bytes !== statePreparation.bytes) throw new Error('state preparation size mismatch'); + return result; +} diff --git a/packages/tmux-bridge/bin/isolated-pid-namespace.py b/packages/tmux-bridge/bin/isolated-pid-namespace.py new file mode 100644 index 00000000..002b6e93 --- /dev/null +++ b/packages/tmux-bridge/bin/isolated-pid-namespace.py @@ -0,0 +1,199 @@ +#!/usr/bin/env python3 +"""Experimental, network-isolated PID namespace lease for owned processes. + +No handover or session lifecycle uses this module. It is not an authorization +boundary and cannot undo remote effects. A caller must keep the lease alive. +""" +import errno +import json +import os +from pathlib import Path +import select +import signal +import stat +import subprocess +import sys +import time +import uuid + +BWRAP = '/usr/bin/bwrap' +GATE = str(Path(__file__).resolve().with_name('namespace-exec-gate.py')) + + +def _identity(pid): + proc = Path('/proc') / str(pid) + meta = proc.stat() + fields = (proc / 'stat').read_text().rsplit(')', 1)[1].split() + status = (proc / 'status').read_text().splitlines() + nested = next(line for line in status if line.startswith('NSpid:')).split()[1:] + return meta.st_uid, int(fields[1]), fields[19], nested, (proc / 'ns/pid').stat().st_ino + + +def _pidfd_pid(fd): + lines = Path(f'/proc/self/fdinfo/{fd}').read_text().splitlines() + return int(next(line for line in lines if line.startswith('Pid:')).split()[1]) + + +class IsolatedNamespace: + """An owned lease, prepared but not released; do not target external PIDs.""" + def __init__(self, process, pidfd, gatefd): + self.process = process + self._pidfd = pidfd + self._gatefd = gatefd + self._released = False + self._stopped = False + + @classmethod + def prepare(cls, workspace, command, *, timeout=5): + if not hasattr(os, 'pidfd_open') or not hasattr(signal, 'pidfd_send_signal'): + raise RuntimeError('pidfd support unavailable') + root = Path(workspace) + if not root.is_absolute() or root.resolve(strict=True) != root: + raise ValueError('workspace must be canonical') + info = root.lstat() + if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077: + raise ValueError('workspace must be private') + if not isinstance(command, list) or not command or len(command) > 64 or not os.path.isabs(command[0]) or any(not isinstance(item, str) or not item or len(item) > 8192 or '\x00' in item for item in command) or isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not 0 < timeout <= 30: + raise ValueError('invalid isolated command') + fifo = root / f'.namespace-gate-{uuid.uuid4().hex}' + os.mkfifo(fifo, 0o600) + before = fifo.lstat() + readfd, writefd = os.pipe() + process = None + pidfd = None + gatefd = None + verified = False + try: + args = [BWRAP, '--ro-bind', '/', '/', '--tmpfs', '/tmp', '--bind', str(root), str(root), + '--proc', '/proc', '--dev', '/dev', '--unshare-pid', '--unshare-net', '--die-with-parent', + '--info-fd', str(writefd), '--clearenv', '--setenv', 'PATH', '/usr/bin:/bin', + '--chdir', str(root), sys.executable, '-B', GATE, str(fifo), '--', *command] + process = subprocess.Popen(args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, + pass_fds=(writefd,), start_new_session=True) + os.close(writefd) + writefd = None + deadline = time.monotonic() + timeout + raw = b'' + while True: + remaining = deadline - time.monotonic() + if remaining <= 0 or not select.select([readfd], [], [], remaining)[0]: + raise RuntimeError('namespace information unavailable') + chunk = os.read(readfd, 8193 - len(raw)) + if not chunk: + raise RuntimeError('incomplete namespace information') + raw += chunk + if len(raw) > 8192: + raise RuntimeError('invalid namespace information') + try: + record = json.loads(raw) + break + except json.JSONDecodeError: + continue + pid, inode = record.get('child-pid'), record.get('pid-namespace') + if isinstance(pid, bool) or not isinstance(pid, int) or pid < 2 or isinstance(inode, bool) or not isinstance(inode, int): + raise RuntimeError('invalid namespace identity') + first = _identity(pid) + if first[0] != os.getuid() or first[1] != process.pid or first[3][-1:] != ['1'] or first[4] != inode or inode == Path('/proc/self/ns/pid').stat().st_ino: + raise RuntimeError('namespace ownership unverified') + pidfd = os.pidfd_open(pid) + if _pidfd_pid(pidfd) != pid or _identity(pid) != first: + raise RuntimeError('namespace identity changed') + verified = True + deadline = time.monotonic() + timeout + while True: + try: + gatefd = os.open(fifo, os.O_WRONLY | os.O_NONBLOCK | os.O_NOFOLLOW) + break + except OSError as exc: + if exc.errno != errno.ENXIO or time.monotonic() >= deadline: + raise + time.sleep(.01) + opened = os.fstat(gatefd) + if not stat.S_ISFIFO(opened.st_mode) or opened.st_uid != os.getuid() or opened.st_mode & 0o077 or opened.st_nlink != 1 or (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino): + raise RuntimeError('gate identity changed') + result = cls(process, pidfd, gatefd) + pidfd = None + return result + except Exception as exc: + # Never release the gate on error. If ownership was verified, the + # pinned namespace init can be stopped without targeting another PID. + if pidfd is not None: + if verified: + try: + signal.pidfd_send_signal(pidfd, signal.SIGKILL) + except ProcessLookupError: + pass + os.close(pidfd) + if gatefd is not None: + os.close(gatefd) + elif process is not None and not verified: + # An empty writer makes the trusted gate refuse execution. Do + # not touch a FIFO that no longer has the original identity. + deadline = time.monotonic() + 2 + while time.monotonic() < deadline: + abortfd = None + try: + abortfd = os.open(fifo, os.O_WRONLY | os.O_NONBLOCK | os.O_NOFOLLOW) + opened = os.fstat(abortfd) + if not stat.S_ISFIFO(opened.st_mode) or (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino): + break + break + except OSError as abort_error: + if abort_error.errno != errno.ENXIO: + break + time.sleep(.01) + finally: + if abortfd is not None: + os.close(abortfd) + if process is not None: + try: + process.wait(timeout=2) + except subprocess.TimeoutExpired: + # An unverified namespace may need operator reconciliation. + pass + for stream in (process.stdin, process.stdout, process.stderr): + if stream: + stream.close() + raise RuntimeError('isolated preparation failed; cleanup may be unverified') from exc + finally: + os.close(readfd) + if writefd is not None: + os.close(writefd) + + def release(self): + if self._stopped or self._released or self._gatefd is None: + raise RuntimeError('gate unavailable') + try: + if os.write(self._gatefd, b'GO\n') != 3: + raise RuntimeError('gate release uncertain') + finally: + os.close(self._gatefd) + self._gatefd = None + self._released = True + + def stop(self, *, timeout=5): + if self._stopped or self._pidfd is None or isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not 0 < timeout <= 30: + raise RuntimeError('namespace lease unavailable') + try: + signal.pidfd_send_signal(self._pidfd, signal.SIGKILL) + except ProcessLookupError: + pass + poller = select.poll() + poller.register(self._pidfd, select.POLLIN) + if not poller.poll(int(timeout * 1000)): + raise RuntimeError('namespace init exit unverified') + try: + self.process.wait(timeout=timeout) + except subprocess.TimeoutExpired as exc: + raise RuntimeError('namespace wrapper exit unverified') from exc + if self._gatefd is not None: + os.close(self._gatefd) + self._gatefd = None + os.close(self._pidfd) + self._pidfd = None + self._stopped = True + for stream in (self.process.stdin, self.process.stdout, self.process.stderr): + if stream: + stream.close() + return {'schema': 'agent-mesh.isolated-namespace-stop.v1', 'status': 'init-exited', + 'descendants': 'unverified', 'remoteEffects': 'unverified'} diff --git a/packages/tmux-bridge/bin/isolated-role-rollback.py b/packages/tmux-bridge/bin/isolated-role-rollback.py new file mode 100644 index 00000000..516df67e --- /dev/null +++ b/packages/tmux-bridge/bin/isolated-role-rollback.py @@ -0,0 +1,118 @@ +#!/usr/bin/env python3 +"""Crash-conservative stop of an owned isolated successor. + +This is not a handover controller or an authorization boundary. The caller +must bind the native assessment and owned stop callback to the same successor, +and consistently use the same private journal root for that session. +""" +import copy +import hashlib +import json +import os +from pathlib import Path +import re +import stat +import threading + + +SESSION = re.compile(r'^codex:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$', re.I) + + +def _open_private_root(root): + if not isinstance(root, str) or not os.path.isabs(root) or str(Path(root).resolve(strict=True)) != root: + raise ValueError('journal root must be absolute and canonical') + before = os.lstat(root) + if not stat.S_ISDIR(before.st_mode) or before.st_uid != os.getuid() or before.st_mode & 0o077: + raise ValueError('journal root must be private and owned') + fd = os.open(root, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW) + opened = os.fstat(fd) + if (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino): + os.close(fd) + raise ValueError('journal root changed') + return fd + + +def _verify_root(root, fd): + current = os.lstat(root) + opened = os.fstat(fd) + if (not stat.S_ISDIR(current.st_mode) or current.st_uid != os.getuid() or current.st_mode & 0o077 + or (current.st_dev, current.st_ino) != (opened.st_dev, opened.st_ino)): + raise ValueError('journal root changed') + + +def _write_once(directory_fd, name, record): + body = (json.dumps(record, separators=(',', ':'), sort_keys=True) + '\n').encode() + fd = os.open(name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=directory_fd) + try: + view = memoryview(body) + while view: + written = os.write(fd, view) + if written <= 0: + raise OSError('journal write incomplete') + view = view[written:] + os.fsync(fd) + finally: + os.close(fd) + os.fsync(directory_fd) + + +class IsolatedRoleRollback: + def __init__(self, expected_session, stop_owned_successor, journal_root): + if not isinstance(expected_session, str) or not SESSION.fullmatch(expected_session) or expected_session != expected_session.lower() or not callable(stop_owned_successor): + raise ValueError('invalid isolated successor binding') + self._session = expected_session + self._stop = stop_owned_successor + self._journal_root = journal_root + self._key = hashlib.sha256(expected_session.encode()).hexdigest() + self._lock = threading.Lock() + self._receipt = None + + def apply(self, assessment): + if (not isinstance(assessment, dict) or assessment.get('schema') != 'agent-mesh.codex-role-start-assessment.v1' + or assessment.get('session') != self._session or assessment.get('status') not in ('observed-incomplete', 'rollback-required') + or not isinstance(assessment.get('failures'), list) + or any(not isinstance(item, str) or not item for item in assessment['failures'])): + raise ValueError('invalid or mismatched role assessment') + if assessment['status'] == 'rollback-required' and not assessment['failures']: + raise ValueError('rollback requires a stated failure') + if assessment['status'] == 'observed-incomplete' and assessment['failures']: + raise ValueError('inconsistent incomplete assessment') + with self._lock: + if self._receipt is not None: + return copy.deepcopy(self._receipt) + if assessment['status'] == 'observed-incomplete': + return {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'blocked-incomplete', + 'session': self._session, 'handover': 'blocked'} + directory_fd = _open_private_root(self._journal_root) + try: + intent = {'schema': 'agent-mesh.isolated-role-stop-intent.v1', 'session': self._session} + try: + _write_once(directory_fd, f'stop-{self._key}.intent.json', intent) + except FileExistsError: + self._receipt = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'stop-uncertain', + 'session': self._session, 'handover': 'blocked'} + return copy.deepcopy(self._receipt) + _verify_root(self._journal_root, directory_fd) + # Persist and fsync the attempt before the side effect. Never retry + # automatically after a crash or an ambiguous callback result. + self._receipt = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'stop-uncertain', + 'session': self._session, 'handover': 'blocked'} + try: + receipt = self._stop() + except Exception: + receipt = None + result = copy.deepcopy(self._receipt) + if (isinstance(receipt, dict) and receipt.get('schema') == 'agent-mesh.isolated-namespace-stop.v1' + and receipt.get('status') == 'init-exited' and receipt.get('descendants') == 'unverified' + and receipt.get('remoteEffects') == 'unverified'): + result = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'local-init-exited', + 'session': self._session, 'handover': 'blocked', + 'namespaceStop': {key: receipt[key] for key in ('schema', 'status', 'descendants', 'remoteEffects')}} + try: + _write_once(directory_fd, f'stop-{self._key}.result.json', result) + except OSError: + return copy.deepcopy(self._receipt) + self._receipt = result + return copy.deepcopy(self._receipt) + finally: + os.close(directory_fd) diff --git a/packages/tmux-bridge/bin/mesh-comms.py b/packages/tmux-bridge/bin/mesh-comms.py index b5af653d..fc3e3485 100755 --- a/packages/tmux-bridge/bin/mesh-comms.py +++ b/packages/tmux-bridge/bin/mesh-comms.py @@ -107,6 +107,10 @@ def validate(spec): not re.fullmatch(r'(session|cse)_[A-Za-z0-9]{1,128}', spec['destination']) or spec.get('resume') or spec.get('inbox_root')): raise ValueError('invalid Claude cloud destination') + profile_keys = ('cloud_profile', 'cloud_scope', 'cloud_profile_digest') + if any(key in spec for key in profile_keys): + if not spec.get('cloud') or not all(isinstance(spec.get(key), str) for key in profile_keys) or not Path(spec['cloud_profile']).is_absolute() or not re.fullmatch(r'[a-z][a-z0-9-]{0,63}', spec['cloud_scope']) or not re.fullmatch(r'[0-9a-f]{64}', spec['cloud_profile_digest']): + raise ValueError('invalid cloud account profile') if 'steer_first' in spec and (spec['steer_first'] is not True or spec['kind'] != 'native' or spec['runtime'] != 'codex' or spec.get('cloud')): raise ValueError('invalid steer-or-queue destination') claude_goal = spec['runtime'] == 'claude' and not spec.get('cloud') and 'goal_resume' not in spec @@ -244,6 +248,8 @@ def observe_inbox(spec, ident, confirmed): def identity(spec): destination = [spec['kind'], spec['runtime'], spec['destination'], spec.get('socket'), spec.get('correlation') or encode(spec)] + if spec.get('cloud_profile'): + destination.append(spec['cloud_scope']) return hashlib.sha256(encode(destination).encode()).hexdigest() @@ -253,6 +259,8 @@ def command(spec): '--correlation-id', spec['correlation'], '--message', spec['message'], '--delivery-only'] if spec.get('cloud'): args += ['--cloud'] + if spec.get('cloud_profile'): + args += ['--cloud-profile', spec['cloud_profile'], '--cloud-scope', spec['cloud_scope'], '--cloud-profile-digest', spec['cloud_profile_digest']] if spec.get('steer_first'): args += ['--steer-or-queue'] if spec.get('inbox_root'): diff --git a/packages/tmux-bridge/bin/mesh-graph.mjs b/packages/tmux-bridge/bin/mesh-graph.mjs index 034563c1..9093c826 100755 --- a/packages/tmux-bridge/bin/mesh-graph.mjs +++ b/packages/tmux-bridge/bin/mesh-graph.mjs @@ -18,6 +18,7 @@ import { readFileSync, readSync, readlinkSync, + realpathSync, renameSync, rmSync, statSync, @@ -25,7 +26,7 @@ import { writeSync, } from "node:fs"; import { homedir } from "node:os"; -import { dirname, join, resolve } from "node:path"; +import { dirname, isAbsolute, join, resolve } from "node:path"; import { randomUUID, createHash } from "node:crypto"; import { spawn, spawnSync } from "node:child_process"; import { fileURLToPath } from "node:url"; @@ -34,6 +35,14 @@ import * as plexus from "./plexus.mjs"; import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from "./session-catalog.mjs"; import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; +import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; +import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, observeDelivery, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeObservation } from "./channel-state.mjs"; +import { observeClaudeDelivery, assertClaudeDeliverySnapshotCurrent } from "./claude-delivery-observation.mjs"; +import { verifyCodexWakeEvidence } from "./codex-wake-evidence.mjs"; +import { prepareState, requestStateProof, revalidateStateProof } from "./handover-state-proof.mjs"; +import { formatFinalNotice } from "./handover-notice.mjs"; +import { observeLocalFinalNotice } from "./handover-notice-transport.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -61,6 +70,10 @@ const { values, positionals } = parseArgs({ options: { state: { type: "string" }, session: { type: "string" }, + generation: { type: "string" }, + "state-root": { type: "string" }, + filename: { type: "string" }, + "managed-inbox-root": { type: "string" }, project: { type: "string" }, archive: { type: "string" }, ttl: { type: "string" }, @@ -93,6 +106,7 @@ const { values, positionals } = parseArgs({ evidence: { type: "string" }, input: { type: "string" }, config: { type: "string" }, + name: { type: "string" }, sort: { type: "string" }, filter: { type: "string", multiple: true }, format: { type: "string" }, @@ -119,7 +133,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "observe-claude-delivery", "recover-claude-delivery", "verify-claude-delivery", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "revalidate-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -131,6 +145,306 @@ const stateDir = resolve(values.state || GRAPH_DIR); try { switch (command) { + case "channel": { + const name = requiredSingleLine(values.name, "--name"); + const channelInput = values.input === "-" ? readBoundedChannelInput() : values.input; + assertPrivateChannelState(stateDir); + if (subcommand === "get") { + const channel = (loadGraph(stateDir).channels || []).find((item) => item.id === name); + if (!channel) throw new Error("unknown channel"); + printResult({ channel }, { json: true }); + break; + } + if (subcommand === "verify-claude-delivery") { + const id = requiredSingleLine(values.id, "--id"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); + const items = channel?.queue?.filter(item => item.id === id && ['accepted', 'observed'].includes(item.state) && item.session?.startsWith('claude:')); + const item = items?.length === 1 ? items[0] : undefined, saved = item?.deliveryProof; + if (!saved || typeof saved.evidence !== 'string' || !/^[0-9a-f]{64}$/.test(saved.transcriptSha256 || '') || !Number.isSafeInteger(saved.transcriptBytes)) throw new Error('Claude delivery proof unavailable'); + const root = process.env.CLAUDE_SESSION_ROOT || join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'projects'); + if (!isAbsolute(root)) throw new Error('invalid configured transcript root'); + const proof = await observeClaudeDelivery({ root, session: item.session, generation: item.generation, messageId: id, payload: item.payload, snapshotBytes: saved.transcriptBytes }); + assertClaudeDeliverySnapshotCurrent(proof); + if (proof.evidence !== saved.evidence || proof.transcriptSha256 !== saved.transcriptSha256) throw new Error('Claude delivery proof mismatch'); + const latest = (loadGraph(stateDir).channels || []).find(row => row.id === name)?.queue?.find(row => row.id === id); + if (!latest || latest.session !== item.session || latest.generation !== item.generation || latest.payload !== item.payload || JSON.stringify(latest.deliveryProof) !== JSON.stringify(saved)) throw new Error('delivery changed during verification'); + printResult({ channel: name, messageId: id, status: 'verified', evidence: proof.evidence }, { json: true }); + break; + } + if (subcommand === "recover-claude-delivery") { + const id = requiredSingleLine(values.id, "--id"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); + const pending = channel?.queue?.filter(item => item.id === id && item.state === "inflight" && item.session === channel.session && item.generation === channel.generation); + if (!['active', 'draining'].includes(channel?.phase) || pending?.length !== 1 || !channel.session.startsWith("claude:")) throw new Error("Claude delivery recovery unavailable"); + const root = process.env.CLAUDE_SESSION_ROOT || join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "projects"); + if (!isAbsolute(root)) throw new Error("invalid configured transcript root"); + const proof = await observeClaudeDelivery({ root, session: channel.session, generation: channel.generation, messageId: id, payload: pending[0].payload }); + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + const item = current?.queue?.find(row => row.id === id); + if (!item || current.phase !== channel.phase || item.state !== 'inflight' || item.session !== proof.session || item.generation !== proof.generation || current.session !== proof.session || current.generation !== proof.generation || typeof item.payload !== 'string' || createHash('sha256').update(item.payload).digest('hex') !== proof.payloadSha256) throw new Error('delivery changed during recovery'); + assertClaudeDeliverySnapshotCurrent(proof); + let next = acknowledge(current, id, { status: 'accepted', messageId: id, session: proof.session, generation: proof.generation }); + if (next.phase === 'draining' && next.handover?.backlog?.includes(id)) next = observeDelivery(next, id, proof); + next.queue.find(row => row.id === id).deliveryProof = { evidence: proof.evidence, transcriptSha256: proof.transcriptSha256, transcriptBytes: proof.transcriptBytes }; + return { graph, event: event('channel.updated', { channel: next }), result: { channel: name, messageId: id, evidence: proof.evidence, status: next.queue.find(row => row.id === id).state } }; + }); + printResult(result, { json: true }); + break; + } + if (subcommand === "observe-claude-delivery") { + const id = requiredSingleLine(values.id, "--id"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); + const pending = channel?.queue?.filter(item => item.id === id && item.state === "accepted" && item.session === channel.session && item.generation === channel.generation); + if (channel?.phase !== "draining" || !channel.handover?.backlog?.includes(id) || pending?.length !== 1 || !channel.session.startsWith("claude:")) throw new Error("Claude delivery observation unavailable"); + const root = process.env.CLAUDE_SESSION_ROOT || join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "projects"); + if (!isAbsolute(root)) throw new Error("invalid configured transcript root"); + const proof = await observeClaudeDelivery({ root, session: channel.session, generation: channel.generation, messageId: id, payload: pending[0].payload }); + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + const item = current?.queue?.find(row => row.id === id); + if (!item || typeof item.payload !== "string" || createHash("sha256").update(item.payload).digest("hex") !== proof.payloadSha256) throw new Error("delivery changed during observation"); + assertClaudeDeliverySnapshotCurrent(proof); + const next = observeDelivery(current, id, proof); + next.queue.find(row => row.id === id).deliveryProof = { evidence: proof.evidence, transcriptSha256: proof.transcriptSha256, transcriptBytes: proof.transcriptBytes }; + return { graph, event: event("channel.updated", { channel: next }), result: { channel: name, messageId: id, evidence: proof.evidence, status: "observed" } }; + }); + printResult(result, { json: true }); + break; + } + if (subcommand === "observe-notice") { + const content = JSON.parse(requiredSingleLine(channelInput, "--input")); + if (!content || typeof content !== "object" || Array.isArray(content) || Object.keys(content).sort().join(",") !== "label,prefix") throw new Error("invalid notice content"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name), pending = channel?.finalNotice; + const target = /^codex:([0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/i.exec(pending?.successor || ""); + const agent = pending?.session?.split(":")[0]; + if (!pending || !["requested", "queued-unverified"].includes(pending.status) || !target || !["codex", "claude"].includes(agent)) throw new Error("local notice reservation unavailable"); + const root = agent === "codex" ? process.env.CODEX_SESSION_ROOT || join(process.env.CODEX_HOME || join(homedir(), ".codex"), "sessions") : process.env.CLAUDE_SESSION_ROOT || join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "projects"); + if (!isAbsolute(root)) throw new Error("invalid configured transcript root"); + const proof = await observeLocalFinalNotice({ session: pending.session, nonce: pending.id, target: { kind: "codex", id: target[1] }, label: content.label, prefix: content.prefix, transcriptRoot: root }); + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + if (!current) throw new Error("unknown channel"); + const next = recordNoticeObservation(current, proof); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: next } }; + }); + printResult(result, { json: true }); + break; + } + if (subcommand === "settle-wake") { + const session = requiredSingleLine(values.session, "--session"); + const evidence = requiredSingleLine(channelInput, "--input"); + const proof = await verifyCodexWakeEvidence({ evidenceRoot: requiredSingleLine(values["state-root"], "--state-root"), reference: evidence, session }); + const sourceId = `codex-wake-${createHash("sha256").update(JSON.stringify([session, proof.queueId])).digest("hex")}`; + const receiptId = createHash("sha256").update(sourceId).digest("hex"); + const digest = createHash("sha256").update(JSON.stringify({ type: "session.woken", session, evidence, to: null })).digest("hex"); + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + if (!current || !(graph.lifecycleReceipts || []).some(item => item.id === receiptId && item.digest === digest)) throw new Error("recorded wake proof unavailable"); + if (!current.wakeReservation && current.queue.some(item => item.id === proof.correlation && item.session === session && item.nativeQueueId === proof.queueId && item.wakeEvidence === evidence)) return { graph, result: { channel: current, duplicate: true } }; + const next = settleWake(current, proof); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: next, duplicate: false } }; + }); + printResult(result, { json: true }); + break; + } + if (subcommand === "revalidate-state") { + const root = requiredSingleLine(values["state-root"], "--state-root"); + if (!isAbsolute(root)) throw new Error("absolute state root required"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); + if (!channel || channel.phase !== "handover" || channel.wakeReservation || channel.queue?.some(item => item.state === "inflight")) throw new Error("state revalidation unavailable"); + const proof = await revalidateStateProof({ root, channel: name, session: channel.session, generation: channel.generation, statePreparation: channel.statePreparation }); + assertPrivateChannelState(stateDir); + const current = (loadGraph(stateDir).channels || []).find(item => item.id === name); + if (!current || current.phase !== "handover" || current.session !== channel.session || current.generation !== channel.generation || current.wakeReservation || current.queue?.some(item => item.state === "inflight") || JSON.stringify(current.statePreparation) !== JSON.stringify(channel.statePreparation)) throw new Error("channel changed during state revalidation"); + printResult({ schema: "agent-mesh.state-revalidation.v1", channel: name, session: channel.session, generation: channel.generation, filename: proof.filename, sha256: proof.sha256, bytes: proof.bytes, status: "verified-snapshot" }, { json: true }); + break; + } + if (subcommand === "prepare-state") { + const root = requiredSingleLine(values["state-root"], "--state-root"), filename = requiredSingleLine(values.filename, "--filename"); + if (!isAbsolute(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error("invalid state preparation path"); + const info = lstatSync(root); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || realpathSync(root) !== root) throw new Error("state root must be private and canonical"); + const nonce = `handover-${randomUUID()}`; + const result = await prepareState({ reserve: () => mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + if (!graph.migrated || graph.unnumbered) throw new Error("channels require a migrated graph"); + const current = (graph.channels || []).find(item => item.id === name); + if (!current) throw new Error("unknown channel"); + if (!/^(codex|claude):[0-9a-f-]{36}$/.test(current.session) || (current.session.startsWith("claude:") && (!values["managed-inbox-root"] || !isAbsolute(values["managed-inbox-root"])))) throw new Error("unsupported state preparation recipient"); + const next = reserveStatePreparation(current, nonce); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: name, statePreparation: next.statePreparation } }; + }), request: pending => requestStateProof({ session: pending.session, channel: name, root, filename, managedInboxRoot: values["managed-inbox-root"], nonce: pending.id }), complete: proof => mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + if (!current) throw new Error("unknown channel"); + const next = completeStatePreparation(current, proof); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: name, statePreparation: next.statePreparation } }; + }) }); + printResult(result, { json: true }); + break; + } + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + if (!graph.migrated || graph.unnumbered) throw new Error("channels require a migrated graph"); + const current = (graph.channels || []).find((item) => item.id === name); + let next; + if (subcommand === "create") { + if (current) throw new Error("channel already exists"); + const session = requiredSingleLine(values.session, "--session"); + if (graph.nodes.filter(node => plexus.sessionIdOf(node) === session).length !== 1) throw new Error("unknown or ambiguous session"); + next = createChannel(name, session); + } else { + if (!current) throw new Error("unknown channel"); + if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), channelInput); + else if (subcommand === "begin-delivery") { + if (values.generation !== undefined && !/^[1-9][0-9]*$/.test(values.generation)) throw new Error("invalid channel generation"); + const messageId = requiredSingleLine(values.id, "--id"); + next = beginDelivery(current, messageId, values.session === undefined ? undefined : requiredSingleLine(values.session, "--session"), values.generation === undefined ? undefined : Number(values.generation)); + next.queue.find(item => item.id === messageId).dispatchReservedAtMs = Date.now(); + } + else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(channelInput, "--input"))); + else if (subcommand === "reserve-wake") { + if (!/^[1-9][0-9]*$/.test(values.generation || "")) throw new Error("invalid channel generation"); + const session = requiredSingleLine(values.session, "--session"), queueId = requiredSingleLine(channelInput, "--input"); + const sourceId = `codex-wake-${createHash("sha256").update(JSON.stringify([session, queueId])).digest("hex")}`; + const receiptId = createHash("sha256").update(sourceId).digest("hex"); + if ((graph.lifecycleReceipts || []).some(item => item.id === receiptId) || (graph.channels || []).some(item => item.id !== name && item.wakeReservation?.session === session && item.wakeReservation?.nativeQueueId === queueId)) throw new Error("wake identity already reserved or recorded"); + next = reserveWake(current, requiredSingleLine(values.id, "--id"), session, Number(values.generation), queueId, values.source === undefined ? 'start' : requiredSingleLine(values.source, '--source')); + } + else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; + else if (subcommand === "reserve-notice") { + const target = requiredSingleLine(values.to, "--to"); + const match = /^codex:([0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/i.exec(target); + if (!match) throw new Error("successor native verification unavailable"); + const content = JSON.parse(requiredSingleLine(channelInput, "--input")); + if (!content || typeof content !== "object" || Array.isArray(content) || Object.keys(content).sort().join(",") !== "label,prefix") throw new Error("invalid notice content"); + const notice = formatFinalNotice({ target: { kind: "codex", id: match[1] }, label: content.label, prefix: content.prefix }); + const matches = graph.nodes.filter(node => plexus.sessionIdOf(node) === target), node = matches[0], proof = node?.sessionLink; + const started = Date.parse(current.handoverStartedAt), checked = Date.parse(proof?.checkedAt); + if (matches.length !== 1 || node.status === "closed" || node.surface?.archived === true || proof?.status !== "ok" || proof.resolvedSession !== target || proof.source !== "codex-threads" || proof.link !== target || proof.lastKnown === true || !Number.isFinite(started) || !Number.isFinite(checked) || checked < started || checked > Date.now()) throw new Error("successor requires fresh verified link"); + const writer = probeWriter({ harness: "codex", nativeId: match[1] }); + if (writer?.agent !== "codex" || writer.sessionId !== match[1] || !Array.isArray(writer.writers) || writer.writers.length !== 1 || !Number.isSafeInteger(writer.writers[0]?.pid) || writer.writers[0].pid <= 0 || writer.writers[0].kind !== "codex") throw new Error("successor requires one verified writer"); + next = reserveFinalNotice(current, `handover-${randomUUID()}`, target, createHash("sha256").update(notice).digest("hex")); + } + else if (subcommand === "finish-handover") { + const target = requiredSingleLine(values.to, "--to"); + if (current.phase === "active" && current.session === target && current.handoverReceipt?.successor === target) return { graph, result: { channel: current, duplicate: true } }; + const matches = graph.nodes.filter(node => plexus.sessionIdOf(node) === target); + const node = matches[0], proof = node?.sessionLink; + const started = Date.parse(current.handoverStartedAt), checked = Date.parse(proof?.checkedAt); + if (matches.length !== 1 || node.status === "closed" || node.surface?.archived === true || proof?.status !== "ok" || proof.resolvedSession !== target || proof.lastKnown === true || !Number.isFinite(started) || !Number.isFinite(checked) || checked < started || checked > Date.now()) throw new Error("successor requires fresh verified link"); + // Current native link discovery can prove an unarchived Codex thread. + // Claude link observations explicitly leave remote reachability unverified. + if (!/^codex:[0-9a-f-]{36}$/.test(target) || proof.source !== "codex-threads" || proof.link !== target) throw new Error("successor native verification unavailable"); + const writer = probeWriter({ harness: "codex", nativeId: target.slice(6) }); + if (writer?.agent !== "codex" || writer.sessionId !== target.slice(6) || !Array.isArray(writer.writers) || writer.writers.length !== 1 || !Number.isSafeInteger(writer.writers[0]?.pid) || writer.writers[0].pid <= 0 || writer.writers[0].kind !== "codex") throw new Error("successor requires one verified writer"); + // A caller assertion or a file path is not proof that the old + // session wrote its state; no verified adapter exists yet. + throw new Error("old-session state verification unavailable; cutover disabled"); + } + else throw new Error("unknown channel operation"); + } + if (current && JSON.stringify(current) === JSON.stringify(next)) return { graph, result: { channel: next, duplicate: true } }; + return { graph, event: event("channel.updated", { channel: next }), result: { channel: next, duplicate: false } }; + }); + printResult(result, { json: true }); + break; + } + case "lifecycle": { + if (subcommand !== "record") throw new Error("unknown lifecycle operation"); + if (!plexus.LIFECYCLE_EVENTS.has(values.type)) throw new Error("invalid lifecycle type"); + const session = requiredSingleLine(values.session, "--session"); + const evidence = requiredSingleLine(values.evidence, "--evidence"); + if (!OPAQUE_REF.test(evidence)) throw new Error("--evidence must be an opaque evidence reference"); + const sourceId = requiredSingleLine(values.id, "--id"); + if (!/^[A-Za-z0-9._:-]{1,128}$/.test(sourceId)) throw new Error("invalid lifecycle observation id"); + const to = values.to; + if (values.type === "session.handover" ? typeof to !== "string" || to === session : to !== undefined) throw new Error("handover alone requires a distinct --to session"); + const digest = createHash("sha256").update(JSON.stringify({ type: values.type, session, evidence, to: to ?? null })).digest("hex"); + const receiptId = createHash("sha256").update(sourceId).digest("hex"); + const result = mutate(stateDir, graph => { + if (!graph.migrated || graph.unnumbered) throw new Error("lifecycle events require a migrated graph"); + if (graph.nodes.filter(node => plexus.sessionIdOf(node) === session).length !== 1 || (to && graph.nodes.filter(node => plexus.sessionIdOf(node) === to).length !== 1)) throw new Error("unknown or ambiguous session"); + const prior = (graph.lifecycleReceipts || []).find(item => item.id === receiptId); + if (prior) { + if (prior.digest !== digest) throw new Error("observation id reused with different contents"); + return { graph, result: { observation: sourceId, duplicate: true } }; + } + return { graph, event: event(values.type, { session, evidence, ...(to ? { to } : {}), receiptId, digest }), result: { observation: sourceId, duplicate: false } }; + }); + printResult(result, { json: true }); + break; + } + case "module": { + const configPath = values.config || join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "agent-mesh", "modules.json"); + const entries = await readModuleRegistry(configPath); + if (subcommand === "list") printResult({ modules: entries.map(entry => ({ name: entry.name })) }, { json: true }); + else if (subcommand === "describe") { + const entry = entries.find(item => item.name === values.name); + if (!entry) throw new Error("module is not registered"); + printResult(await describeModule(entry), { json: true }); + } else if (subcommand === "conformance") { + const entry = entries.find(item => item.name === values.name); + if (!entry) throw new Error("module is not registered"); + const desc = await describeModule(entry); + if (!desc.operations.includes("process")) throw new Error("module does not support process"); + const graph = { nodes: [{ id: "synthetic-node", agent: "codex", runtimeUuid: "22222222-2222-4222-8222-222222222222" }], moduleStates: [] }; + const result = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", mode: "conformance", graph, cursor: null, events: [] }); + if (Object.keys(result).some(key => !["schema", "name", "batchId", "attributes", "events"].includes(key))) throw new Error("invalid module process response"); + validateModuleBatch(entry.name, entry.namespaces, { id: result.batchId, cursor: null, nextCursor: "synthetic-cursor", attributes: result.attributes, events: result.events }, graph, plexus.sessionIdOf); + printResult({ module: entry.name, conformance: "pass", scope: "synthetic protocol response only" }, { json: true }); + } else if (subcommand === "run") { + const entry = entries.find(item => item.name === values.name); + if (!entry) throw new Error("module is not registered"); + const description = await describeModule(entry); + if (!description.operations.includes("process")) throw new Error("module does not support process"); + // Feed replay can be large. Never hold the shared writer lock while + // scanning it; reject if the graph moved during observation instead. + const graph = loadGraph(stateDir); + if (!graph.migrated || graph.unnumbered) throw new Error("module runs require a migrated graph"); + const cursor = graph.moduleStates?.find(item => item.name === entry.name)?.cursor ?? null; + const query = cursor === null ? { initial: "head" } : { sinceCursor: cursor }; + const feed = runQuery(stateDir, "changes", { input: JSON.stringify(query) }); + if (feed.reset) throw new Error("module cursor expired; reconciliation required"); + const observed = loadGraph(stateDir); + if (observed.lastSeq !== graph.lastSeq || plexus.decodeCursor(feed.cursor, "changes").seq > graph.lastSeq) throw new Error("graph changed during module observation"); + const snapshot = { graph, cursor, feed }; + const events = snapshot.feed.events.filter(item => !entry.namespaces.some(namespace => item.type.startsWith(`${namespace}.`))); + const output = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", graph: snapshot.graph, cursor: snapshot.cursor, events }); + if (Object.keys(output).some(key => !["schema", "name", "batchId", "attributes", "events"].includes(key))) throw new Error("invalid module process response"); + if (snapshot.cursor !== null && events.length === 0 && Array.isArray(output.attributes) && output.attributes.length === 0 && Array.isArray(output.events) && output.events.length === 0) { + printResult({ module: entry.name, unchanged: true }, { json: true }); + break; + } + const batch = { id: output.batchId, cursor: snapshot.cursor, nextCursor: snapshot.feed.cursor, attributes: output.attributes, events: output.events }; + const result = mutate(stateDir, graph => { + if (graph.lastSeq !== snapshot.graph.lastSeq) throw new Error("graph changed during module processing"); + const checked = validateModuleBatch(entry.name, entry.namespaces, batch, graph, plexus.sessionIdOf); + if (checked.duplicate) return { graph, result: { module: entry.name, batchId: batch.id, duplicate: true } }; + return { graph, event: event("module.batch", { module: entry.name, batch, digest: checked.digest }), result: { module: entry.name, batchId: batch.id, duplicate: false } }; + }); + printResult(result, { json: true }); + } else if (subcommand === "apply") { + const entry = entries.find(item => item.name === values.name); + if (!entry) throw new Error("module is not registered"); + const raw = values.input === "-" ? readFileSync(0, "utf8") : values.input; + if (typeof raw !== "string" || Buffer.byteLength(raw) > 1024 * 1024) throw new Error("invalid module input"); + const batch = JSON.parse(raw); + const result = mutate(stateDir, graph => { + if (!graph.migrated || graph.unnumbered) throw new Error("module batches require a migrated graph"); + const checked = validateModuleBatch(entry.name, entry.namespaces, batch, graph, plexus.sessionIdOf); + if (checked.duplicate) return { graph, result: { module: values.name, batchId: batch.id, duplicate: true } }; + return { graph, event: event("module.batch", { module: values.name, batch, digest: checked.digest }), result: { module: values.name, batchId: batch.id, duplicate: false } }; + }); + printResult(result, { json: true }); + } else throw new Error("unknown module operation"); + break; + } case "links": { if (subcommand !== "verify") throw new Error("unknown links operation"); const verify = graph => { @@ -1108,7 +1422,7 @@ function readCheckpoint(statePath) { if (checkpoint.schema !== GRAPH_SCHEMA || checkpoint.graph?.schema !== GRAPH_SCHEMA || !Array.isArray(checkpoint.graph.nodes) || !Array.isArray(checkpoint.graph.edges) || // Older binaries rewrite the checkpoint without Plexus state; replaying from the file is the only safe answer. - !Array.isArray(checkpoint.graph.roleClaims) || !Array.isArray(checkpoint.graph.links) || !Number.isSafeInteger(checkpoint.graph.lastSeq) || + !Array.isArray(checkpoint.graph.roleClaims) || !Array.isArray(checkpoint.graph.links) || !Array.isArray(checkpoint.graph.moduleStates) || !Array.isArray(checkpoint.graph.lifecycleReceipts) || !Array.isArray(checkpoint.graph.channels) || !Number.isSafeInteger(checkpoint.graph.lastSeq) || !cursor || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0 || !Number.isSafeInteger(cursor.dev) || !Number.isSafeInteger(cursor.ino)) { return null; @@ -1197,7 +1511,7 @@ function* readEventRecords(statePath, offset = 0) { function deriveGraph(events, base = null) { const nodes = new Map((base?.nodes || []).map((node) => [node.id, node])); const edges = new Map((base?.edges || []).map((edge) => [edge.id, edge])); - const state = { nodes, roleClaims: new Map((base?.roleClaims || []).map(c => [c.id, c])), links: new Map((base?.links || []).map((link) => [link.id, link])), edges, renewals: [...(base?.renewals || [])], migrated: base?.migrated === true }; + const state = { nodes, channels: new Map((base?.channels || []).map(item => [item.id, item])), moduleStates: new Map((base?.moduleStates || []).map(item => [item.name, item])), lifecycleReceipts: new Map((base?.lifecycleReceipts || []).map(item => [item.id, item])), roleClaims: new Map((base?.roleClaims || []).map(c => [c.id, c])), links: new Map((base?.links || []).map((link) => [link.id, link])), edges, renewals: [...(base?.renewals || [])], migrated: base?.migrated === true }; const baseSeq = base?.lastSeq || 0; let lastSeq = baseSeq; let unnumbered = base?.unnumbered === true; @@ -1209,8 +1523,13 @@ function deriveGraph(events, base = null) { lastSeq = Math.max(lastSeq, item.seq); } else if (state.migrated) unnumbered = true; generatedAt = item.at || generatedAt; + if (item.type === "module.batch") { + applyModuleBatch(state, item, plexus.sessionIdOf); + continue; + } if (plexus.PLEXUS_EVENTS.has(item.type)) { plexus.applyPlexusEvent(state, item); + if (plexus.LIFECYCLE_EVENTS.has(item.type) && item.receiptId) state.lifecycleReceipts.set(item.receiptId, { id: item.receiptId, digest: item.digest }); continue; } if (item.type === "node.upserted") { @@ -1239,7 +1558,10 @@ function deriveGraph(events, base = null) { nodes: state.migrated ? plexus.projectNodeRefs(sortedNodes, links) : sortedNodes, edges: [...edges.values()].sort((left, right) => left.id.localeCompare(right.id)), links, + channels: [...state.channels.values()], renewals: state.renewals, + moduleStates: [...state.moduleStates.values()], + lifecycleReceipts: [...state.lifecycleReceipts.values()], roleClaims: [...state.roleClaims.values()], migrated: state.migrated, lastSeq, @@ -1332,6 +1654,30 @@ function ensureStateDir(statePath) { mkdirSync(statePath, { recursive: true, mode: 0o700 }); } +function readBoundedChannelInput() { + const max = 65536, chunks = []; + let total = 0; + while (true) { + const chunk = Buffer.allocUnsafe(Math.min(4096, max + 1 - total)); + const count = readSync(0, chunk, 0, chunk.length, null); + if (!count) break; + total += count; + if (total > max) throw new Error("channel input too large"); + chunks.push(chunk.subarray(0, count)); + } + return Buffer.concat(chunks).toString("utf8"); +} + +function assertPrivateChannelState(statePath) { + const root = lstatSync(statePath); + if (!root.isDirectory() || root.isSymbolicLink() || root.uid !== process.getuid() || (root.mode & 0o077) !== 0 || realpathSync(statePath) !== resolve(statePath)) throw new Error("channel graph directory must be private and canonical"); + for (const name of ["events.jsonl", "graph.json", "checkpoint.json", "snapshot.json"]) { + const file = join(statePath, name); + const info = lstatSync(file, { throwIfNoEntry: false }); + if (info && (!info.isFile() || info.isSymbolicLink() || info.uid !== process.getuid() || info.nlink !== 1 || (info.mode & 0o077) !== 0)) throw new Error(`channel graph file must be private: ${name}`); + } +} + function acquireLock(statePath) { const lock = join(statePath, "graph.lock"); const deadline = Date.now() + 5_000; diff --git a/packages/tmux-bridge/bin/module-batches.mjs b/packages/tmux-bridge/bin/module-batches.mjs new file mode 100644 index 00000000..6c0e0c50 --- /dev/null +++ b/packages/tmux-bridge/bin/module-batches.mjs @@ -0,0 +1,47 @@ +import { createHash } from "node:crypto"; + +const NAME = /^[a-z][a-z0-9-]{0,63}$/; +const KEY = /^[a-z][a-z0-9_-]{0,63}$/; + +// A batch is one event, so graph changes and its checkpoint commit together. +export function validateModuleBatch(name, namespaces, batch, graph, sessionIdOf) { + if (typeof name !== "string" || !NAME.test(name)) throw new Error("invalid module name"); + if (!batch || typeof batch !== "object" || Array.isArray(batch) || Object.keys(batch).some(k => !["id", "cursor", "nextCursor", "attributes", "events"].includes(k))) throw new Error("invalid module batch"); + if (typeof batch.id !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(batch.id)) throw new Error("invalid batch id"); + for (const c of [batch.cursor, batch.nextCursor]) if (!(c === null || (typeof c === "string" && c.length <= 4096))) throw new Error("invalid module cursor"); + if (batch.nextCursor === null) throw new Error("next cursor is required"); + if (!Array.isArray(batch.attributes) || batch.attributes.length > 200 || !Array.isArray(batch.events) || batch.events.length > 200) throw new Error("invalid batch contents"); + if (Buffer.byteLength(JSON.stringify(batch)) > 1024 * 1024) throw new Error("module batch too large"); + const seen = new Set(); + for (const attr of batch.attributes) { + if (!attr || Object.keys(attr).some(k => !["session", "key", "value"].includes(k)) || typeof attr.session !== "string" || typeof attr.key !== "string" || attr.key.split(".").length !== 2 || !namespaces.includes(attr.key.split(".")[0]) || !KEY.test(attr.key.split(".")[1]) || !Object.hasOwn(attr, "value")) throw new Error("invalid namespaced module attribute"); + if (graph.nodes.filter(node => sessionIdOf(node) === attr.session).length !== 1) throw new Error("unknown or ambiguous session"); + const identity = `${attr.session}\0${attr.key}`; + if (seen.has(identity)) throw new Error("duplicate module attribute"); + seen.add(identity); + } + for (const ev of batch.events) { + if (!ev || Object.keys(ev).some(k => !["type", "session", "data"].includes(k)) || typeof ev.type !== "string" || ev.type.split(".").length !== 2 || !namespaces.includes(ev.type.split(".")[0]) || !KEY.test(ev.type.split(".")[1]) || typeof ev.session !== "string" || graph.nodes.filter(node => sessionIdOf(node) === ev.session).length !== 1 || !Object.hasOwn(ev, "data")) throw new Error("invalid namespaced event"); + } + const digest = createHash("sha256").update(JSON.stringify(batch)).digest("hex"); + const previous = (graph.moduleStates || []).find(item => item.name === name); + if (previous?.batchId === batch.id) { + if (previous.digest !== digest) throw new Error("batch id reused with different contents"); + return { duplicate: true, digest }; + } + if ((previous?.cursor ?? null) !== batch.cursor) throw new Error("module cursor conflict"); + return { duplicate: false, digest }; +} + +export function applyModuleBatch(state, event, sessionIdOf) { + if (!state.moduleStates) state.moduleStates = new Map(); + for (const attr of event.batch.attributes) { + const node = [...state.nodes.values()].find(item => sessionIdOf(item) === attr.session); + if (!node) throw new Error("module batch names unknown session"); + const modules = { ...(node.moduleAttributes || {}) }; + const [namespace, key] = attr.key.split("."); + modules[namespace] = { ...(Object.hasOwn(modules, namespace) ? modules[namespace] : {}), [key]: attr.value }; + state.nodes.set(node.id, { ...node, moduleAttributes: modules }); + } + state.moduleStates.set(event.module, { name: event.module, cursor: event.batch.nextCursor, batchId: event.batch.id, digest: event.digest }); +} diff --git a/packages/tmux-bridge/bin/namespace-exec-gate.py b/packages/tmux-bridge/bin/namespace-exec-gate.py new file mode 100644 index 00000000..5fea1f1c --- /dev/null +++ b/packages/tmux-bridge/bin/namespace-exec-gate.py @@ -0,0 +1,43 @@ +#!/usr/bin/env python3 +"""Execute a trusted command only after an explicit private FIFO release. + +This gate is a fail-closed coordination primitive, not an authorization boundary. +The caller owns the namespace, FIFO, command, environment and lifecycle. +""" +import os +from pathlib import Path +import stat +import sys + + +def main(argv): + if len(argv) < 3 or argv[1] != '--' or not os.path.isabs(argv[0]) or not os.path.isabs(argv[2]): + return 125 + fifo = Path(argv[0]) + try: + parent = fifo.parent + directory = parent.lstat() + entry = fifo.lstat() + if (not stat.S_ISDIR(directory.st_mode) or directory.st_uid != os.getuid() or directory.st_mode & 0o077 or + parent.resolve(strict=True) != parent or not stat.S_ISFIFO(entry.st_mode) or + entry.st_uid != os.getuid() or entry.st_mode & 0o077 or entry.st_nlink != 1): + return 125 + fd = os.open(fifo, os.O_RDONLY | os.O_NOFOLLOW) + try: + opened = os.fstat(fd) + if (not stat.S_ISFIFO(opened.st_mode) or opened.st_uid != os.getuid() or opened.st_mode & 0o077 or opened.st_nlink != 1 or + opened.st_dev != entry.st_dev or opened.st_ino != entry.st_ino): + return 125 + permit = os.read(fd, 4) + finally: + os.close(fd) + if permit != b'GO\n': + return 125 + os.execv(argv[2], argv[2:]) + except OSError: + return 125 + return 125 + + +if __name__ == '__main__': + raise SystemExit(main(sys.argv[1:])) diff --git a/packages/tmux-bridge/bin/plexus-modules.mjs b/packages/tmux-bridge/bin/plexus-modules.mjs new file mode 100644 index 00000000..389d5be1 --- /dev/null +++ b/packages/tmux-bridge/bin/plexus-modules.mjs @@ -0,0 +1,65 @@ +import { readFile } from "node:fs/promises"; +import { spawn } from "node:child_process"; + +export const MODULE_PROTOCOL = "agent-mesh.plexus-module.v1"; +const NAME = /^[a-z][a-z0-9-]{0,63}$/; +const MAX_BYTES = 1024 * 1024; +// Graph snapshots can be substantially larger than module responses. This is a +// hard bound, not permission to truncate a graph silently. +const MAX_REQUEST_BYTES = 32 * 1024 * 1024; + +// This is an operator allowlist, not a sandbox for untrusted programs. +export async function readModuleRegistry(path) { + let text; + try { text = await readFile(path, "utf8"); } + catch (error) { if (error.code === "ENOENT") return []; throw error; } + if (Buffer.byteLength(text) > MAX_BYTES) throw new Error("module registry is too large"); + const config = JSON.parse(text); + if (!config || config.schemaVersion !== 1 || !Array.isArray(config.modules)) throw new Error("invalid module registry"); + const names = new Set(), namespaces = new Set(); + return config.modules.map((entry) => { + if (!entry || typeof entry.name !== "string" || !NAME.test(entry.name) || names.has(entry.name)) throw new Error("invalid or duplicate module name"); + const owned = entry.namespaces ?? [entry.name]; + if (!Array.isArray(owned) || !owned.length || owned.length > 32 || owned.some(ns => typeof ns !== "string" || !NAME.test(ns) || namespaces.has(ns)) || new Set(owned).size !== owned.length) throw new Error("invalid or duplicate module namespace"); + if (!Array.isArray(entry.command) || !entry.command.length || entry.command.some(v => typeof v !== "string" || !v || v.includes("\0"))) throw new Error("invalid module command"); + const timeoutMs = entry.timeoutMs ?? 10000; + if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120000) throw new Error("invalid module timeout"); + names.add(entry.name); + for (const namespace of owned) namespaces.add(namespace); + return { name: entry.name, namespaces: [...owned], command: [...entry.command], timeoutMs }; + }); +} + +export async function invokeModule(entry, operation, request) { + if (!["describe", "process"].includes(operation)) throw new Error("invalid module operation"); + const input = JSON.stringify(request); + if (Buffer.byteLength(input) > MAX_REQUEST_BYTES) throw new Error("module request too large"); + const result = await new Promise((resolve, reject) => { + const child = spawn(entry.command[0], [...entry.command.slice(1), operation], { stdio: ["pipe", "pipe", "ignore"], shell: false }); + let output = [], bytes = 0, finished = false; + const finish = (error, value) => { if (finished) return; finished = true; clearTimeout(timer); error ? reject(error) : resolve(value); }; + const timer = setTimeout(() => { child.kill("SIGKILL"); finish(new Error("module timed out")); }, entry.timeoutMs); + child.on("error", () => finish(new Error("module failed"))); + child.stdout.on("data", chunk => { + bytes += chunk.length; + if (bytes > MAX_BYTES) { child.kill("SIGKILL"); finish(new Error("module response too large")); } + else output.push(chunk); + }); + child.stdin.on("error", () => {}); + child.on("close", code => { + if (code !== 0) return finish(new Error("module failed")); + try { finish(null, JSON.parse(Buffer.concat(output).toString("utf8"))); } + catch { finish(new Error("invalid module response")); } + }); + child.stdin.end(`${input}\n`); + }); + if (!result || result.schema !== MODULE_PROTOCOL || result.name !== entry.name) throw new Error("invalid module response"); + return result; +} + +export async function describeModule(entry) { + const result = await invokeModule(entry, "describe", {}); + const owned = entry.namespaces ?? [entry.name]; + if (!result || result.schema !== MODULE_PROTOCOL || result.name !== entry.name || !Array.isArray(result.namespaces) || result.namespaces.length !== owned.length || owned.some(ns => !result.namespaces.includes(ns)) || new Set(result.namespaces).size !== owned.length || !Array.isArray(result.operations) || !result.operations.includes("describe") || result.operations.some(op => typeof op !== "string")) throw new Error("invalid module description"); + return result; +} diff --git a/packages/tmux-bridge/bin/plexus.mjs b/packages/tmux-bridge/bin/plexus.mjs index 4706a3df..1ccf49b6 100644 --- a/packages/tmux-bridge/bin/plexus.mjs +++ b/packages/tmux-bridge/bin/plexus.mjs @@ -7,6 +7,7 @@ import { createHmac, randomUUID } from "node:crypto"; import { posix } from "node:path"; import { createHash } from "node:crypto"; +import { applyModuleBatch } from "./module-batches.mjs"; import { LEDGER_VIEW_SCHEMA, LEDGER_VIEW_SORT, buildLedgerViewRows, ledgerViewProfileRevision, ledgerViewValue, validateLedgerViewProfile @@ -18,7 +19,8 @@ export const LINK_SOURCES = /^(bridge-launch|hook|ledger-write|reconciler|operat export const ROLE_WEIGHTS = { owns: 1, "works-on": 1, coordinates: 0.8, reviews: 0.7, discusses: 0.6, observes: 0.3, mentioned: 0.2 }; export const HALF_LIFE_DAYS = 7; export const TOUCH_COALESCE_MS = 10 * 60 * 1000; -export const PLEXUS_EVENTS = new Set(["role.changed", "link.opened", "link.touched", "link.closed", "link.resolved", "edge.ended", "session.renewed", "store.migrated"]); +export const LIFECYCLE_EVENTS = new Set(["session.started", "session.woken", "session.idle", "session.compacted", "session.stopped", "session.handover"]); +export const PLEXUS_EVENTS = new Set(["channel.updated", "role.changed", "link.opened", "link.touched", "link.closed", "link.resolved", "edge.ended", "session.renewed", "store.migrated", ...LIFECYCLE_EVENTS]); const HARNESSES = new Set(["codex", "claude"]); const UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i; const SESSION_ID = /^(codex|claude):[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/; @@ -84,6 +86,30 @@ export function applyPlexusEvent(state, item) { const effects = []; const openLinks = () => [...state.links.values()].filter((link) => link.until === null); switch (item.type) { + case "channel.updated": + if (!item.channel || item.channel.schema !== "agent-mesh.channel.v1" || typeof item.channel.id !== "string" || !Array.isArray(item.channel.queue)) throw new Error("invalid channel event"); + if (!state.channels) state.channels = new Map(); + state.channels.set(item.channel.id, item.channel); + break; + case "session.started": + case "session.woken": + case "session.idle": + case "session.compacted": + case "session.stopped": + case "session.handover": + parseGraphSessionId(item.session); + if (typeof item.evidence !== "string" || !item.evidence || item.evidence.length > 512 || /[\r\n\x00]/.test(item.evidence)) throw new Error("lifecycle event requires an evidence reference"); + if (item.type === "session.handover") { + parseGraphSessionId(item.to); + if (item.to === item.session) throw new Error("handover target must differ"); + if (item.channel !== undefined) { + if (!item.channel || item.channel.schema !== "agent-mesh.channel.v1" || item.channel.session !== item.to) throw new Error("invalid handover channel"); + if (!state.channels) state.channels = new Map(); + state.channels.set(item.channel.id, item.channel); + } + } else if (item.to !== undefined) throw new Error("unexpected lifecycle target"); + effects.push({ kind: item.type, session: item.session, evidence: item.evidence, ...(item.to ? { to: item.to } : {}) }); + break; case "role.changed": if (!state.roleClaims) state.roleClaims = new Map(); if (item.previous) state.roleClaims.set(item.previous.id, item.previous); @@ -777,6 +803,7 @@ export function changes(snapshotGraph, events, input = {}, scope = null) { nodes: new Map((snapshotGraph?.nodes || []).map((node) => [node.id, node])), links: new Map((snapshotGraph?.links || []).map((link) => [link.id, link])), edges: new Map((snapshotGraph?.edges || []).map((edge) => [edge.id, edge])), + moduleStates: new Map((snapshotGraph?.moduleStates || []).map(item => [item.name, item])), renewals: [...(snapshotGraph?.renewals || [])], migrated: snapshotGraph?.migrated === true, }; const seen = new Set([...state.nodes.values()].map(sessionIdOf).filter(Boolean)); @@ -790,7 +817,7 @@ export function changes(snapshotGraph, events, input = {}, scope = null) { continue; } if (output.length >= limit) break; - const emitted = feedFor(state, seen, item); + const emitted = feedFor(state, seen, item, scope); applyReplay(state, item, emitted); scanned = item.seq; if (!emitted.length) continue; @@ -808,6 +835,10 @@ export function changes(snapshotGraph, events, input = {}, scope = null) { } function applyReplay(state, item, emitted) { + if (item.type === "module.batch") { + if (!emitted) applyModuleBatch(state, item, sessionIdOf); + return; + } if (item.type === "node.upserted") { state.nodes.set(item.node.id, item.node); return; @@ -824,8 +855,12 @@ function applyReplay(state, item, emitted) { if (PLEXUS_EVENTS.has(item.type) && !emitted) applyPlexusEvent(state, item); } -function feedFor(state, seen, item) { +function feedFor(state, seen, item, scope) { const out = []; + if (item.type === "module.batch") { + applyModuleBatch(state, item, sessionIdOf); + return item.batch.events.map((entry, index) => ({ type: entry.type, session: entry.session, data: entry.data, subject: `${item.id}:${index}` })); + } if (item.type === "node.upserted") { const id = sessionIdOf(item.node); const previous = state.nodes.get(item.node.id); @@ -886,6 +921,8 @@ function feedFor(state, seen, item) { if (from && to) out.push({ type: effect.kind, edgeId: effect.edge.id, kind: effect.edge.type, from, to, subject: effect.edge.id }); } else if (effect.kind === "session.renewed") { out.push({ type: "session.renewed", from: effect.from, to: effect.to, subject: effect.to }); + } else if (LIFECYCLE_EVENTS.has(effect.kind)) { + out.push({ type: effect.kind, session: effect.session, ...(scope === null ? { evidence: effect.evidence } : {}), ...(effect.to ? { to: effect.to } : {}), subject: effect.session }); } } return out; diff --git a/packages/tmux-bridge/bin/restart-state.mjs b/packages/tmux-bridge/bin/restart-state.mjs new file mode 100644 index 00000000..8cbb5800 --- /dev/null +++ b/packages/tmux-bridge/bin/restart-state.mjs @@ -0,0 +1,34 @@ +/** Validate a parsed restart block; never execute its instructions. */ +const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype; +const nonempty = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 8192 && !value.includes('\0'); +const profileId = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); + +export function validateRoleProfile(profile) { + if (!isObject(profile) || Object.keys(profile).sort().join(',') !== 'mcp,permissions,plugins,role,schema' || profile.schema !== 'agent-mesh.role-profile.v1' || !profileId(profile.role)) throw new Error('invalid role profile'); + for (const key of ['permissions', 'mcp', 'plugins']) { + const values = profile[key]; + if (!Array.isArray(values) || values.length > 256 || !values.every(profileId) || new Set(values).size !== values.length) throw new Error(`invalid role profile ${key}`); + } + return true; +} + +export function validateRestartState(block, { session, channel, requireRoleProfile = false } = {}) { + if (!isObject(block) || block.schema !== 'agent-mesh.restart.v1') throw new Error('invalid restart schema'); + for (const field of ['session', 'channel', 'harness', 'working_directory']) { + if (!nonempty(block[field])) throw new Error(`invalid restart ${field}`); + } + if (session !== undefined && block.session !== session) throw new Error('restart session mismatch'); + if (channel !== undefined && block.channel !== channel) throw new Error('restart channel mismatch'); + if (requireRoleProfile || block.role_profile !== undefined) validateRoleProfile(block.role_profile); + if (!Array.isArray(block.skills) || block.skills.length > 256 || !block.skills.every(nonempty)) throw new Error('invalid restart skills'); + if (!Array.isArray(block.triggers) || block.triggers.length > 256) throw new Error('invalid restart triggers'); + const ids = new Set(); + for (const trigger of block.triggers) { + if (!isObject(trigger) || !nonempty(trigger.id) || !nonempty(trigger.kind) || !isObject(trigger.config)) throw new Error('invalid restart trigger'); + const key = JSON.stringify([trigger.kind, trigger.id]); + if (ids.has(key)) throw new Error('duplicate restart trigger'); + ids.add(key); + } + if (block.goal !== null && (!isObject(block.goal) || !nonempty(block.goal.objective) || !nonempty(block.goal.status))) throw new Error('invalid restart goal'); + return true; +} diff --git a/packages/tmux-bridge/bin/restart-yaml.py b/packages/tmux-bridge/bin/restart-yaml.py new file mode 100644 index 00000000..46144e51 --- /dev/null +++ b/packages/tmux-bridge/bin/restart-yaml.py @@ -0,0 +1,67 @@ +#!/usr/bin/env python3 +"""Decode a bounded restart block; do not emit state contents on errors.""" +import json +import math +import re +import sys + +try: + import yaml +except ImportError: + print('restart YAML parser unavailable: PyYAML is required', file=sys.stderr) + sys.exit(2) + + +class UniqueLoader(yaml.SafeLoader): + def construct_mapping(self, node, deep=False): + result = {} + for key_node, value_node in node.value: + key = self.construct_object(key_node, deep=deep) + if not isinstance(key, str) or key in result: + raise ValueError('non-string or duplicate key') + result[key] = self.construct_object(value_node, deep=deep) + return result + + +def json_value(value, depth=0, count=None): + count = count if count is not None else [0] + count[0] += 1 + if depth > 32 or count[0] > 20000: + raise ValueError('restart structure too large') + if value is None or isinstance(value, (bool, str, int)): + return value + if isinstance(value, float) and math.isfinite(value): + return value + if isinstance(value, list): + return [json_value(item, depth + 1, count) for item in value] + if isinstance(value, dict): + return {key: json_value(item, depth + 1, count) for key, item in value.items()} + raise ValueError('restart value is not JSON-compatible') + + +def decode(data): + text = data.decode('utf-8').replace('\r\n', '\n') + headings = list(re.finditer(r'^## RIAVVIO[ \t]*$', text, re.MULTILINE)) + if headings: + if len(headings) != 1: + raise ValueError('ambiguous restart section') + rest = text[headings[0].end():] + match = re.match(r'\n[ \t\n]*```ya?ml[ \t]*\n(.*?)^```[ \t]*$', rest, re.MULTILINE | re.DOTALL | re.IGNORECASE) + if not match: + raise ValueError('missing restart YAML block') + text = match.group(1) + for token in yaml.scan(text, Loader=UniqueLoader): + if isinstance(token, (yaml.tokens.AliasToken, yaml.tokens.AnchorToken, yaml.tokens.TagToken)): + raise ValueError('aliases, anchors and explicit tags are not allowed') + return json_value(yaml.load(text, Loader=UniqueLoader)) + + +try: + raw = sys.stdin.buffer.read(1024 * 1024 + 1) + if not raw or len(raw) > 1024 * 1024: + raise ValueError('invalid state size') + result = decode(raw) + print(json.dumps(result, ensure_ascii=True, allow_nan=False, separators=(',', ':'))) +except (ValueError, TypeError, UnicodeError, yaml.YAMLError, RecursionError): + print('invalid restart YAML', file=sys.stderr) + sys.exit(1) diff --git a/packages/tmux-bridge/bin/role-launch-profile.mjs b/packages/tmux-bridge/bin/role-launch-profile.mjs new file mode 100644 index 00000000..33abcad6 --- /dev/null +++ b/packages/tmux-bridge/bin/role-launch-profile.mjs @@ -0,0 +1,36 @@ +/** Build a role-scoped launch plan without granting capabilities or starting services. */ +import { validateRoleProfile } from './restart-state.mjs'; + +const id = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); +const list = value => Array.isArray(value) && value.length <= 256 && value.every(id) && new Set(value).size === value.length; + +export async function planRoleLaunch({ profile, authority, probe, timeoutMs = 3000 }) { + validateRoleProfile(profile); + if (!authority || authority.role !== profile.role || !list(authority.permissions) || !list(authority.mcp) || !list(authority.plugins) || !list(authority.humanGatedPermissions) || typeof probe !== 'function' || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw new Error('invalid role authority'); + for (const field of ['permissions', 'mcp', 'plugins']) if (profile[field].some(value => !authority[field].includes(value))) throw new Error('role profile exceeds authority'); + if (profile.permissions.some(value => authority.humanGatedPermissions.includes(value))) throw new Error('human-gated permission cannot be pregranted'); + const available = [], unavailable = []; + for (const name of profile.mcp) { + let timer, cleanupTimer; const controller = new AbortController(), timedOut = Symbol('timeout'), cleanupTimedOut = Symbol('cleanup-timeout'); + const pending = Promise.resolve().then(() => probe(name, { signal: controller.signal })); + try { + const result = await Promise.race([pending, new Promise(resolve => { timer = setTimeout(() => { controller.abort(); resolve(timedOut); }, timeoutMs); })]); + if (result === timedOut) { + const cleanup = await Promise.race([pending.then(() => true, () => true), new Promise(resolve => { cleanupTimer = setTimeout(() => resolve(cleanupTimedOut), 1500); })]); + if (cleanup === cleanupTimedOut) throw new Error('probe cancellation unconfirmed'); + unavailable.push(name); continue; + } + (result === true ? available : unavailable).push(name); + } catch (error) { if (error?.message === 'probe cancellation unconfirmed' || error?.code === 'MCP_PROBE_CONFIGURATION') throw error; unavailable.push(name); } + finally { clearTimeout(timer); clearTimeout(cleanupTimer); controller.abort(); } + } + return { schema: 'agent-mesh.role-launch-plan.v1', role: profile.role, permissions: [...profile.permissions], plugins: [...profile.plugins], mcpToStart: available, mcpUnavailable: unavailable }; +} + +/** Assess observed startup; the caller owns rollback and native observation. */ +export function assessRoleLaunch({ plan, observed }) { + if (!plan || plan.schema !== 'agent-mesh.role-launch-plan.v1' || !list(plan.permissions) || !list(plan.plugins) || !list(plan.mcpToStart) || !list(plan.mcpUnavailable) || !observed || !list(observed.mcpStarted) || !list(observed.pluginsStarted) || typeof observed.permissionPrompt !== 'boolean' || !(observed.startupTokens === null || (Number.isSafeInteger(observed.startupTokens) && observed.startupTokens >= 0))) throw new Error('invalid launch observation'); + const unexpected = observed.mcpStarted.some(value => !plan.mcpToStart.includes(value)) || observed.pluginsStarted.some(value => !plan.plugins.includes(value)); + const failed = observed.permissionPrompt || unexpected; + return { schema: 'agent-mesh.role-launch-receipt.v1', status: failed ? 'rollback-required' : 'ready', reason: observed.permissionPrompt ? 'unexpected-permission' : unexpected ? 'unexpected-component' : null, mcpStarted: observed.mcpStarted.length, mcpUnavailable: [...new Set([...plan.mcpUnavailable, ...plan.mcpToStart.filter(value => !observed.mcpStarted.includes(value))])], startupTokens: observed.startupTokens }; +} diff --git a/packages/tmux-bridge/bin/role-mcp-exec-gate.py b/packages/tmux-bridge/bin/role-mcp-exec-gate.py new file mode 100644 index 00000000..b3eddf44 --- /dev/null +++ b/packages/tmux-bridge/bin/role-mcp-exec-gate.py @@ -0,0 +1,27 @@ +#!/usr/bin/env python3 +"""Fail-closed stdin gate for an owned experimental MCP probe process.""" +import os +import sys + + +def main(argv): + if len(argv) < 2 or argv[0] != '--' or not os.path.isabs(argv[1]): + return 125 + permit = b'' + try: + while len(permit) < 3: + part = os.read(0, 3 - len(permit)) + if not part: + return 125 + permit += part + if permit != b'GO\n': + return 125 + os.write(1, b'{"agentMeshMcpGate":"released"}\n') + os.execv(argv[1], argv[1:]) + except OSError: + return 125 + return 125 + + +if __name__ == '__main__': + raise SystemExit(main(sys.argv[1:])) diff --git a/packages/tmux-bridge/bin/role-mcp-probe.mjs b/packages/tmux-bridge/bin/role-mcp-probe.mjs new file mode 100644 index 00000000..f2d56b3a --- /dev/null +++ b/packages/tmux-bridge/bin/role-mcp-probe.mjs @@ -0,0 +1,96 @@ +/** Probe one authorized stdio MCP in a verified PID namespace. */ +import { spawn } from 'node:child_process'; +import { readFileSync, statSync } from 'node:fs'; +import { isAbsolute } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const gateProgram = fileURLToPath(new URL('./role-mcp-exec-gate.py', import.meta.url)); +const configurationError = message => Object.assign(new Error(message), { code: 'MCP_PROBE_CONFIGURATION' }); + +// The launcher is not an authorization boundary: the command is still trusted +// and retains the caller's filesystem and network access. Verify that bubblewrap +// created a separate PID namespace with an owned init before accepting a probe. +function verifyNamespace(raw, child) { + const info = JSON.parse(raw), pid = info?.['child-pid'], inode = info?.['pid-namespace']; + if (!Number.isSafeInteger(pid) || pid < 2 || !Number.isSafeInteger(inode) || !child.pid) throw new Error('invalid namespace identity'); + const path = `/proc/${pid}`, proc = statSync(path), ns = statSync(`${path}/ns/pid`); + const stat = readFileSync(`${path}/stat`, 'utf8').split(') ').at(-1).split(' '); + const status = readFileSync(`${path}/status`, 'utf8'); + const nested = status.match(/^NSpid:\s*(.*)$/m)?.[1].trim().split(/\s+/); + if (proc.uid !== process.getuid() || Number(stat[1]) !== child.pid || ns.ino !== inode || ns.ino === statSync('/proc/self/ns/pid').ino || nested?.at(-1) !== '1') throw new Error('namespace ownership unverified'); +} + +export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { + if (!allowlist || typeof allowlist !== 'object' || Array.isArray(allowlist)) throw configurationError('invalid MCP allowlist'); + return (name, { signal } = {}) => { + if (typeof name !== 'string' || !Object.hasOwn(allowlist, name)) throw configurationError('MCP is not allowlisted'); + const entry = allowlist[name]; + if (!entry || typeof entry !== 'object' || Array.isArray(entry)) throw configurationError('invalid MCP allowlist entry'); + return probeStdioMcp({ command: entry.command, env: entry.env, timeoutMs, signal }); + }; +} + +// The profile contains identifiers only. Callers must resolve them using a +// trusted private allowlist; never construct this command from session text. +export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signal, spawnProcess = spawn }) { + if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || (signal !== undefined && !(signal instanceof AbortSignal))) throw configurationError('invalid MCP probe configuration'); + return new Promise((resolve, reject) => { + let child, timer, reapTimer, buffer = '', info = '', phase = 'gate', finished = false, closed = false, desired = false, resolved = false, namespaceVerified = false, gateAcknowledged = false, protocolReady = false; + let onAbort; + const done = result => { if (!resolved) { resolved = true; clearTimeout(reapTimer); if (!namespaceVerified || !gateAcknowledged) reject(configurationError('MCP probe containment or gate unverified')); else resolve(result); } }; + const finish = result => { + if (finished) return; + finished = true; desired = result; clearTimeout(timer); + if (signal && onAbort) signal.removeEventListener('abort', onAbort); + if (!closed && child?.pid && child.exitCode == null && child.signalCode == null) { try { process.kill(-child.pid, 'SIGKILL'); } catch {} } + if (!child || closed) done(child ? desired : false); + else reapTimer = setTimeout(() => { if (!resolved) { resolved = true; reject(new Error('probe cancellation unconfirmed')); } }, 1000); + }; + if (signal?.aborted) { resolved = true; resolve(false); return; } + try { child = spawnProcess('/usr/bin/bwrap', ['--info-fd', '3', '--die-with-parent', '--bind', '/', '/', '--proc', '/proc', '--dev-bind', '/dev', '/dev', '--unshare-pid', '--', '/usr/bin/python3', '-B', gateProgram, '--', ...command], { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore', 'pipe'], env }); } + catch { finish(false); return; } + timer = setTimeout(() => finish(false), timeoutMs); + onAbort = () => finish(false); + signal?.addEventListener('abort', onAbort, { once: true }); + if (signal?.aborted) { finish(false); return; } + if (!child.stdio?.[3]) { finish(false); return; } + child.stdio[3].setEncoding('utf8'); + child.stdio[3].on('data', data => { info += data; if (Buffer.byteLength(info) > 8192) finish(false); }); + child.stdio[3].on('end', () => { + if (finished) return; + try { verifyNamespace(info, child); namespaceVerified = true; child.stdin.write('GO\n'); } + catch { finish(false); } + }); + child.once('error', () => finish(false)); + child.once('close', () => { closed = true; if (!finished) finish(false); else done(desired); }); + child.stdin.on('error', () => finish(false)); + child.stdout.setEncoding('utf8'); + const write = message => child.stdin.write(`${JSON.stringify(message)}\n`); + child.stdout.on('data', data => { + if (finished) return; + buffer += data; + if (Buffer.byteLength(buffer) > 1024 * 1024) return finish(false); + let index; + while (!finished && (index = buffer.indexOf('\n')) >= 0) { + const line = buffer.slice(0, index); buffer = buffer.slice(index + 1); + let reply; try { reply = JSON.parse(line); } catch { return finish(false); } + if (phase === 'gate') { + if (!namespaceVerified || Object.keys(reply || {}).join(',') !== 'agentMeshMcpGate' || reply.agentMeshMcpGate !== 'released') return finish(false); + gateAcknowledged = true; phase = 'initialize'; + write({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'role-profile-probe', version: '1' } } }); + continue; + } + if (reply?.jsonrpc !== '2.0') return finish(false); + if (phase === 'initialize' && reply.id === 1) { + if (reply.error || !reply.result || reply.result.protocolVersion !== '2024-11-05' || !reply.result.capabilities || typeof reply.result.capabilities !== 'object' || Array.isArray(reply.result.capabilities) || typeof reply.result.serverInfo?.name !== 'string' || !reply.result.serverInfo.name || typeof reply.result.serverInfo.version !== 'string' || !reply.result.serverInfo.version) return finish(false); + phase = 'ping'; + write({ jsonrpc: '2.0', method: 'notifications/initialized' }); + write({ jsonrpc: '2.0', id: 2, method: 'ping', params: {} }); + } else if (phase === 'ping' && reply.id === 2) { + if (reply.error || !reply.result || typeof reply.result !== 'object' || Array.isArray(reply.result)) finish(false); + else { protocolReady = true; if (namespaceVerified) finish(true); } + } else if (reply.id !== undefined) return finish(false); + } + }); + }); +} diff --git a/packages/tmux-bridge/bin/trigger-journal.mjs b/packages/tmux-bridge/bin/trigger-journal.mjs new file mode 100644 index 00000000..665872ee --- /dev/null +++ b/packages/tmux-bridge/bin/trigger-journal.mjs @@ -0,0 +1,103 @@ +/** Private crash-conservative journal for trigger transactions. */ +import { constants, closeSync, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'; +import { createHash, randomUUID } from 'node:crypto'; +import { isAbsolute, join } from 'node:path'; + +const token = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); +const terminal = new Set(['verified', 'rolled-back', 'dry-run', 'not-applied']); +const statuses = new Set(['planning', 'applying', 'rolling-back', 'uncertain', ...terminal]); +const key = trigger => JSON.stringify([trigger.kind, trigger.id]); + +export function triggerJournal(root) { + if (typeof root !== 'string' || !isAbsolute(root)) throw new Error('invalid journal root'); + const checkRoot = () => { + const info = lstatSync(root); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || realpathSync(root) !== root) throw new Error('journal root must be private and canonical'); + }; + const file = join(root, 'trigger-transactions.json'), lock = join(root, '.trigger-transactions.lock'); + const syncRoot = () => { const fd = openSync(root, constants.O_RDONLY | constants.O_DIRECTORY); try { fsyncSync(fd); } finally { closeSync(fd); } }; + const load = () => { + let fd; + try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW); } + catch (error) { if (error.code === 'ENOENT') return { schema: 'agent-mesh.trigger-journal.v1', entries: [] }; throw error; } + try { + const info = fstatSync(fd); + if (!info.isFile() || info.uid !== process.getuid() || info.nlink !== 1 || (info.mode & 0o077) !== 0 || info.size > 8 * 1024 * 1024) throw new Error('invalid journal file'); + const data = JSON.parse(readFileSync(fd, 'utf8')); + if (data?.schema !== 'agent-mesh.trigger-journal.v1' || !Array.isArray(data.entries) || new Set(data.entries.map(entry => entry?.id)).size !== data.entries.length || data.entries.some(entry => !token(entry?.id) || typeof entry.dryRun !== 'boolean' || !Array.isArray(entry.triggers) || entry.triggers.some(t => !token(t?.kind) || !token(t?.id)) || new Set(entry.triggers.map(key)).size !== entry.triggers.length || !statuses.has(entry.status) || (entry.epoch !== undefined && (!Number.isSafeInteger(entry.epoch) || entry.epoch < 0)))) throw new Error('invalid journal content'); + return data; + } finally { closeSync(fd); } + }; + const save = data => { + const body = `${JSON.stringify(data)}\n`; + if (Buffer.byteLength(body) > 8 * 1024 * 1024) throw new Error('journal is too large'); + const temporary = join(root, `.trigger-journal-${randomUUID()}.tmp`); + const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); + try { writeFileSync(fd, body); fsyncSync(fd); } finally { closeSync(fd); } + renameSync(temporary, file); syncRoot(); + }; + const transaction = operation => { + checkRoot(); + let fd; + try { fd = openSync(lock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); } + catch (error) { if (error.code === 'EEXIST') throw new Error('journal lock held or requires recovery'); throw error; } + try { fsyncSync(fd); syncRoot(); const data = load(); const result = operation(data); save(data); return result; } + finally { + const owned = fstatSync(fd); closeSync(fd); + const current = lstatSync(lock); + if (current.dev !== owned.dev || current.ino !== owned.ino) throw new Error('journal lock changed'); + unlinkSync(lock); syncRoot(); + } + }; + return { + async begin({ id, triggers, dryRun }) { + if (!token(id) || !Array.isArray(triggers) || typeof dryRun !== 'boolean' || triggers.some(t => !token(t?.kind) || !token(t?.id)) || new Set(triggers.map(key)).size !== triggers.length) throw new Error('invalid journal reservation'); + return transaction(data => { + if (data.entries.some(entry => entry.id === id)) throw new Error('transaction already reserved'); + const requested = new Set(triggers.map(key)); + if (data.entries.some(entry => !terminal.has(entry.status) && entry.triggers.some(trigger => requested.has(key(trigger))))) throw new Error('overlapping transaction unresolved'); + data.entries.push({ id, dryRun, status: 'planning', triggers: structuredClone(triggers), receipt: null, epoch: 0 }); + return 0; + }); + }, + async write(receipt, epoch = 0) { + return transaction(data => { + const entry = data.entries.find(item => item.id === receipt?.id); + if (!entry || (entry.epoch ?? 0) !== epoch || terminal.has(entry.status) || receipt.schema !== 'agent-mesh.trigger-transaction.v1' || receipt.dryRun !== entry.dryRun || !statuses.has(receipt.status) || !Array.isArray(receipt.triggers) || JSON.stringify(receipt.triggers.map(key)) !== JSON.stringify(entry.triggers.map(key))) throw new Error('invalid journal update'); + entry.status = receipt.status; entry.receipt = structuredClone(receipt); + }); + }, + async get(id) { + checkRoot(); + if (!token(id)) throw new Error('invalid transaction id'); + const entry = load().entries.find(item => item.id === id); + return entry ? structuredClone(entry) : null; + }, + async withRecovery(id, callback) { + checkRoot(); + if (!token(id) || typeof callback !== 'function') throw new Error('invalid recovery request'); + const recoveryLock = join(root, `.trigger-recovery-${createHash('sha256').update(id).digest('hex')}.lock`); + let fd; + try { fd = openSync(recoveryLock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); } + catch (error) { if (error.code === 'EEXIST') throw new Error('recovery lock held or requires reconciliation'); throw error; } + try { + fsyncSync(fd); syncRoot(); + const journal = triggerJournal(root); + const takeover = transaction(data => { + const entry = data.entries.find(item => item.id === id); + if (!entry || entry.dryRun || !['uncertain', 'applying', 'rolling-back'].includes(entry.status) || !entry.receipt) throw new Error('transaction not recoverable'); + const epoch = (entry.epoch ?? 0) + 1; + if (!Number.isSafeInteger(epoch)) throw new Error('transaction epoch exhausted'); + entry.epoch = epoch; entry.status = 'uncertain'; entry.receipt.status = 'uncertain'; + return { epoch, receipt: structuredClone(entry.receipt) }; + }); + return await callback(takeover.receipt, receipt => journal.write(receipt, takeover.epoch)); + } finally { + const owned = fstatSync(fd); closeSync(fd); + const current = lstatSync(recoveryLock); + if (current.dev !== owned.dev || current.ino !== owned.ino) throw new Error('recovery lock changed'); + unlinkSync(recoveryLock); syncRoot(); + } + } + }; +} diff --git a/packages/tmux-bridge/bin/trigger-transaction.mjs b/packages/tmux-bridge/bin/trigger-transaction.mjs new file mode 100644 index 00000000..87fd0d93 --- /dev/null +++ b/packages/tmux-bridge/bin/trigger-transaction.mjs @@ -0,0 +1,104 @@ +/** Reconcile session-bound triggers through an operator-provided CAS adapter. */ +const token = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); + +// begin must atomically reserve this ID and trigger set, rejecting unresolved +// overlapping transactions. Each write must be durable before it resolves. +// The adapter atomically compares target AND version and stores operationId. +// Every applied move, including a same-target move, must produce a fresh version. +// Versions must never be reused: recovery fences delayed in-flight moves with CAS. +export async function reconcileTriggers({ triggers, from, to, transactionId, adapter, journal, dryRun = true }) { + if (!Array.isArray(triggers) || triggers.length > 256 || !token(from) || !token(to) || from === to || !token(transactionId) || transactionId.length > 90 || typeof dryRun !== 'boolean' || typeof adapter?.read !== 'function' || typeof adapter?.move !== 'function' || typeof journal?.begin !== 'function' || typeof journal?.write !== 'function') throw new Error('invalid trigger transaction'); + const seen = new Set(); + for (const trigger of triggers) { + if (!token(trigger?.kind) || !token(trigger?.id) || seen.has(`${trigger.kind}\0${trigger.id}`)) throw new Error('invalid or duplicate trigger'); + seen.add(`${trigger.kind}\0${trigger.id}`); + } + const receipt = { schema: 'agent-mesh.trigger-transaction.v1', id: transactionId, from, to, dryRun, status: 'planning', triggers: triggers.map(({ kind, id }) => ({ kind, id, status: 'pending' })) }; + const epoch = await journal.begin({ id: transactionId, triggers: structuredClone(triggers), dryRun }); + const save = () => journal.write(structuredClone(receipt), epoch); + for (let i = 0; i < triggers.length; i++) { + let current; + try { current = await adapter.read(triggers[i]); } catch { /* No mutation has been attempted. */ } + if (!current || current.target !== from || !token(current.version)) { + receipt.triggers[i].status = 'unverified'; + receipt.status = 'not-applied'; + receipt.reason = 'trigger source or version not verified'; + await save(); + return receipt; + } + receipt.triggers[i].before = current.version; + receipt.triggers[i].status = 'planned'; + } + receipt.status = dryRun ? 'dry-run' : 'applying'; + await save(); + if (dryRun) return receipt; + for (let i = 0; i < receipt.triggers.length; i++) { + const row = receipt.triggers[i], operationId = `${transactionId}:${i}`; + row.status = 'applying'; row.operationId = operationId; await save(); + let response; + try { response = await adapter.move({ kind: row.kind, id: row.id, expectedTarget: from, expectedVersion: row.before, target: to, operationId }); } + catch { row.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + if (response?.status !== 'applied' || !token(response.version) || response.version === row.before) { + row.status = response?.status === 'not-applied' ? 'not-applied' : 'uncertain'; + receipt.status = row.status === 'uncertain' ? 'uncertain' : 'rolling-back'; await save(); + if (row.status === 'uncertain') return receipt; + for (let j = i - 1; j >= 0; j--) { + const prior = receipt.triggers[j], rollbackId = `${transactionId}:rollback:${j}`; + prior.status = 'rolling-back'; await save(); + let rollback; + try { rollback = await adapter.move({ kind: prior.kind, id: prior.id, expectedTarget: to, expectedVersion: prior.after, target: from, operationId: rollbackId }); } + catch { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + if (rollback?.status !== 'applied' || !token(rollback.version) || rollback.version === prior.after) { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + let observed; + try { observed = await adapter.read(prior); } catch { /* The rollback may have applied. */ } + if (observed?.target !== from || observed.version !== rollback.version || observed.lastOperationId !== rollbackId) { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + prior.status = 'rolled-back'; prior.rollbackVersion = rollback.version; await save(); + } + receipt.status = 'rolled-back'; await save(); return receipt; + } + let observed; + try { observed = await adapter.read(row); } catch { /* The move may have applied. */ } + if (observed?.target !== to || observed.version !== response.version || observed.lastOperationId !== operationId) { row.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + row.after = response.version; row.status = 'verified'; await save(); + } + receipt.status = 'verified'; await save(); return receipt; +} + +/** Explicitly roll back an uncertain transaction after inspecting all targets. */ +export async function recoverUncertainTriggers({ transactionId, adapter, journal }) { + if (!token(transactionId) || typeof adapter?.read !== 'function' || typeof adapter?.move !== 'function' || typeof journal?.withRecovery !== 'function') throw new Error('invalid trigger recovery'); + return journal.withRecovery(transactionId, async (receipt, save) => { + if (receipt.id !== transactionId || receipt.status !== 'uncertain' || receipt.dryRun !== false || !Array.isArray(receipt.triggers)) throw new Error('invalid uncertain receipt'); + const observations = []; + for (let i = 0; i < receipt.triggers.length; i++) { + const row = receipt.triggers[i], observed = await adapter.read(row); + if (!observed || !token(observed.version)) throw new Error('trigger observation unavailable'); + const forwardId = `${transactionId}:${i}`, rollbackId = `${transactionId}:rollback:${i}`; + if (observed.target === receipt.from && observed.version === row.before) observations.push({ kind: 'unchanged', observed }); + else if (observed.target === receipt.from && observed.lastOperationId === rollbackId && (!row.rollbackVersion || row.rollbackVersion === observed.version)) observations.push({ kind: 'rolled-back', observed }); + else if (observed.target === receipt.to && observed.lastOperationId === forwardId && (!row.after || row.after === observed.version)) observations.push({ kind: 'moved', observed }); + else throw new Error('trigger changed outside transaction'); + } + for (let i = receipt.triggers.length - 1; i >= 0; i--) { + const row = receipt.triggers[i], { kind, observed } = observations[i]; + if (kind === 'rolled-back') { + if (observed.version === row.before) throw new Error('rollback version is not a fence'); + row.status = 'rolled-back'; row.rollbackVersion = observed.version; + continue; + } + const operationId = `${transactionId}:rollback:${i}`; + if (kind === 'moved') row.after = observed.version; + row.status = 'rolling-back'; receipt.status = 'rolling-back'; await save(receipt); + let result, confirmed; + try { + result = await adapter.move({ kind: row.kind, id: row.id, expectedTarget: kind === 'moved' ? receipt.to : receipt.from, expectedVersion: observed.version, target: receipt.from, operationId }); + if (result?.status === 'applied' && token(result.version)) confirmed = await adapter.read(row); + } catch { /* The outcome may have been applied. */ } + if (confirmed?.target !== receipt.from || confirmed.version !== result?.version || confirmed.version === observed.version || confirmed.lastOperationId !== operationId) { + row.status = 'uncertain'; receipt.status = 'uncertain'; await save(receipt); return receipt; + } + row.status = 'rolled-back'; row.rollbackVersion = result.version; await save(receipt); + } + receipt.status = 'rolled-back'; await save(receipt); return receipt; + }); +} diff --git a/packages/tmux-bridge/docs/agent-waker.md b/packages/tmux-bridge/docs/agent-waker.md index 86564efd..d7a6887e 100644 --- a/packages/tmux-bridge/docs/agent-waker.md +++ b/packages/tmux-bridge/docs/agent-waker.md @@ -30,6 +30,18 @@ For an idle Codex owner, explicit `--agent codex --resume` forwards native `--resume` through the existing transport and communications gate. It is opt-in; Claude resume is rejected. A queue receipt still does not prove an actor response. +In channel mode, `--channel --delivery-only` persists the notification +in the graph queue before acknowledging the producer. A handover keeps it +queued. The first pending message is reserved before invoking the native +transport; an unconfirmed delivery stays in flight and requires reconciliation. +The native bound queue receipt is checked before the graph records acceptance. +Channel delivery does not establish that the receiving actor read the message. +Channel payloads reach the graph and native transport adapter on standard input. +The Codex channel path queues via the local app-server protocol, without a +downstream message argument. An uncertain queue outcome is not retried +automatically. Queue acceptance still does not prove the actor read the message. +The channel mode and handover are not yet enabled in existing timers. + Delivery-only acknowledgement requires native JSON `status: queued`, matching agent/session/correlation and no `held: true`. Except for the bound delivered duplicate described below, held, refused, malformed or missing receipts retain pending items diff --git a/packages/tmux-bridge/docs/lifecycle.md b/packages/tmux-bridge/docs/lifecycle.md index b9221610..3c522d04 100644 --- a/packages/tmux-bridge/docs/lifecycle.md +++ b/packages/tmux-bridge/docs/lifecycle.md @@ -439,3 +439,9 @@ Semantic skips do not consume the eligible-action target. For example, a hook budget of 200 can process 100 refusals and then prepare ten eligible summaries; it stops before creating an eleventh summary or expanding the review pool. Existing larger frozen plans still retain the ten-confirmed-success apply cap. + +### Trigger recovery contract + +Trigger reconciliation is inactive unless an operator supplies an adapter and a private journal. The adapter must atomically compare both target and version, record the operation ID, and issue a fresh, never-reused version on every applied move, including a same-target move. A backend that cannot enforce this contract must not be used for recovery. + +Recovery takes over an `applying`, `rolling-back`, or `uncertain` journal entry by advancing its durable epoch. Stale journal writers are rejected. It reads all targets and uses CAS to restore or fence each one before recording rollback; an unverified response remains uncertain. A process can die while holding a journal or recovery lock: these locks fail closed and require separate reconciliation; this mechanism does not automatically clear them. A successful synthetic test does not establish that any real trigger backend meets the contract. diff --git a/packages/tmux-bridge/examples/plexus-example-module.mjs b/packages/tmux-bridge/examples/plexus-example-module.mjs new file mode 100644 index 00000000..76de23df --- /dev/null +++ b/packages/tmux-bridge/examples/plexus-example-module.mjs @@ -0,0 +1,20 @@ +#!/usr/bin/env node +// Synthetic protocol example; it never writes attributes or events. +import { createHash } from "node:crypto"; +import { readFileSync } from "node:fs"; + +if (process.argv[2] === "process") { + const input = JSON.parse(readFileSync(0, "utf8")); + const batchId = createHash("sha256").update(JSON.stringify(input.cursor)).digest("hex"); + process.stdout.write(JSON.stringify({ schema: "agent-mesh.plexus-module.v1", name: "example", batchId, attributes: [], events: [] }) + "\n"); +} else if (process.argv[2] !== "describe") { + process.stderr.write("unsupported operation\n"); + process.exitCode = 1; +} else { + process.stdout.write(JSON.stringify({ + schema: "agent-mesh.plexus-module.v1", + name: "example", + namespaces: ["example"], + operations: ["describe", "process"], + }) + "\n"); +} diff --git a/packages/tmux-bridge/scripts/test-isolation-regression.sh b/packages/tmux-bridge/scripts/test-isolation-regression.sh index 7dd27af5..15ac22ee 100644 --- a/packages/tmux-bridge/scripts/test-isolation-regression.sh +++ b/packages/tmux-bridge/scripts/test-isolation-regression.sh @@ -62,6 +62,12 @@ python3 test/mesh-groups.test.py python3 test/session-inbox.test.py python3 test/run-receipt.test.py python3 test/agent-waker.test.py +python3 test/agent-waker-channel.test.py +python3 test/namespace-exec-gate.test.py +python3 test/isolated-pid-namespace.test.py +python3 -B test/isolated-role-rollback.test.py +python3 -B test/codex-native-rollback.integration.py +python3 -B test/claude-native-mailbox.integration.py python3 test/session-controller.test.py python3 test/owner-notify.test.py scripts/socket-isolation-test.sh diff --git a/packages/tmux-bridge/test/agent-waker-channel.test.py b/packages/tmux-bridge/test/agent-waker-channel.test.py new file mode 100644 index 00000000..9ce7312c --- /dev/null +++ b/packages/tmux-bridge/test/agent-waker-channel.test.py @@ -0,0 +1,309 @@ +import contextlib +import importlib.util +import io +import json +import os +from pathlib import Path +import subprocess +import tempfile +from types import SimpleNamespace +import unittest +from unittest.mock import patch + +root = Path(__file__).resolve().parents[1] +spec = importlib.util.spec_from_file_location('channel_waker', root / 'bin' / 'agent-waker.py') +waker = importlib.util.module_from_spec(spec) +spec.loader.exec_module(waker) +uuid = '22222222-2222-4222-8222-222222222222' + + +class ChannelWakerTest(unittest.TestCase): + def test_codex_backlog_wake_is_opt_in_and_uncertainty_is_not_retried(self): + with tempfile.TemporaryDirectory() as directory: + args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(Path(directory) / 'graph'), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False, wake_evidence_root=str(Path(directory) / 'evidence')) + channel = {'phase': 'draining', 'session': f'codex:{uuid}', 'generation': 2, 'handover': {'backlog': ['one']}, 'queue': [{'id': 'one', 'state': 'accepted', 'session': f'codex:{uuid}', 'generation': 2, 'nativeQueueId': 'queue-1'}]} + with patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'channel_call', return_value=channel), patch.object(waker, 'preflight_codex_channel_wake', return_value=True), patch.object(waker, 'start_codex_channel_wake', side_effect=ValueError('uncertain')) as start, patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + self.assertEqual(waker.run(args), 3) + self.assertEqual(start.call_count, 1) + deliver.assert_not_called() + self.assertEqual(json.loads(Path(args.state).read_text())['wakeAttempt']['status'], 'attempted') + + def test_codex_backlog_wake_requires_graph_settlement(self): + with tempfile.TemporaryDirectory() as directory: + args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(Path(directory) / 'graph'), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False, wake_evidence_root=str(Path(directory) / 'evidence')) + evidence = 'codex-wake:' + 'a' * 64 + channel = {'phase': 'draining', 'session': f'codex:{uuid}', 'generation': 2, 'handover': {'backlog': ['one']}, 'queue': [{'id': 'one', 'state': 'accepted', 'session': f'codex:{uuid}', 'generation': 2, 'nativeQueueId': 'queue-1'}]} + observed = {**channel, 'queue': [{**channel['queue'][0], 'state': 'observed', 'wakeEvidence': evidence}]} + with patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'channel_call', side_effect=[channel, observed]), patch.object(waker, 'preflight_codex_channel_wake', return_value=True), patch.object(waker, 'start_codex_channel_wake', return_value=evidence), patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 0) + deliver.assert_not_called() + self.assertEqual(json.loads(Path(args.state).read_text())['wakeAttempt']['status'], 'verified') + + def test_codex_busy_preflight_does_not_record_or_start_attempt(self): + with tempfile.TemporaryDirectory() as directory: + args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(Path(directory) / 'graph'), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False, wake_evidence_root=str(Path(directory) / 'evidence')) + channel = {'phase': 'draining', 'session': f'codex:{uuid}', 'generation': 2, 'handover': {'backlog': ['one']}, 'queue': [{'id': 'one', 'state': 'accepted', 'session': f'codex:{uuid}', 'generation': 2, 'nativeQueueId': 'queue-1'}]} + with patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'channel_call', return_value=channel), patch.object(waker, 'preflight_codex_channel_wake', return_value=False), patch.object(waker, 'start_codex_channel_wake') as start, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + start.assert_not_called() + self.assertNotIn('wakeAttempt', json.loads(Path(args.state).read_text())) + + def test_lost_claude_receipt_recovers_from_correlated_transcript_without_resend(self): + with tempfile.TemporaryDirectory() as directory: + tmp = Path(directory) + state, sessions = tmp / 'graph', tmp / 'sessions' + project = sessions / 'project' + project.mkdir(parents=True, mode=0o700) + sessions.chmod(0o700) + target = f'claude:{uuid}' + def call(*parts): + proc = subprocess.run(['node', str(root / 'bin' / 'mesh-graph.mjs'), '--state', str(state), *parts], capture_output=True, text=True, check=True) + return json.loads(proc.stdout) + call('add', '--agent', 'claude', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json') + call('migrate', '--apply', '--json') + call('channel', 'create', '--name', 'example', '--session', target) + call('channel', 'enqueue', '--name', 'example', '--id', 'one', '--input', 'fixture') + call('channel', 'begin-delivery', '--name', 'example', '--id', 'one', '--session', target, '--generation', '1') + record = {'schema': 'agent-mesh.monitor-inbox.v1', 'deliveryId': 'one', 'meshId': 'one', 'prompt': 'fixture'} + message = 'AGENT_MESH_INBOX ' + json.dumps(record) + transcript = project / (uuid + '.jsonl') + transcript.write_text(json.dumps({'type': 'queue-operation', 'operation': 'enqueue', 'sessionId': uuid, 'content': message}) + '\n') + transcript.chmod(0o600) + args = SimpleNamespace(state=str(tmp / 'waker.json'), graph_state=str(state), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) + with patch.dict(os.environ, {'CLAUDE_SESSION_ROOT': str(sessions)}), patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + self.assertEqual(call('channel', 'get', '--name', 'example')['channel']['queue'][0]['state'], 'inflight') + with transcript.open('a') as stream: + stream.write(json.dumps({'type': 'user', 'sessionId': uuid, 'message': {'role': 'user', 'content': message}}) + '\n') + self.assertEqual(waker.run(args), 0) + self.assertEqual(waker.run(args), 0) + deliver.assert_not_called() + self.assertEqual(call('channel', 'get', '--name', 'example')['channel']['queue'][0]['state'], 'accepted') + + def test_draining_claude_backlog_waits_for_observation_without_resending(self): + with tempfile.TemporaryDirectory() as directory: + tmp = Path(directory) + state, sessions = tmp / 'graph', tmp / 'sessions' + project = sessions / 'project' + project.mkdir(parents=True, mode=0o700) + sessions.chmod(0o700) + successor = '33333333-3333-4333-8333-333333333333' + target = f'claude:{successor}' + def call(*parts): + proc = subprocess.run(['node', str(root / 'bin' / 'mesh-graph.mjs'), '--state', str(state), *parts], capture_output=True, text=True, check=True) + return json.loads(proc.stdout) + call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json') + call('migrate', '--apply', '--json') + call('channel', 'create', '--name', 'example', '--session', f'codex:{uuid}') + graph = call('show', '--json') + channel = graph['channels'][0] + channel.update(session=target, generation=2, phase='draining', handover={'predecessor': f'codex:{uuid}', 'previousGeneration': 1, 'successor': target, 'backlog': ['one']}, queue=[{'id': 'one', 'payload': 'fixture', 'state': 'accepted', 'session': target, 'generation': 2}]) + event = {'schema': 'agent-mesh.session-graph-event.v1', 'id': 'fixture-draining', 'type': 'channel.updated', 'at': '2026-01-01T00:00:00Z', 'channel': channel, 'seq': graph['lastSeq'] + 1, 'host': 'local'} + with (state / 'events.jsonl').open('a') as stream: + stream.write(json.dumps(event) + '\n') + args = SimpleNamespace(state=str(tmp / 'waker.json'), graph_state=str(state), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) + record = {'schema': 'agent-mesh.monitor-inbox.v1', 'deliveryId': 'one', 'meshId': 'one', 'prompt': 'fixture'} + message = 'AGENT_MESH_INBOX ' + json.dumps(record) + transcript = project / (successor + '.jsonl') + transcript.write_text(json.dumps({'type': 'queue-operation', 'operation': 'enqueue', 'sessionId': successor, 'content': message}) + '\n') + transcript.chmod(0o600) + with patch.dict(os.environ, {'CLAUDE_SESSION_ROOT': str(sessions)}), patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + with transcript.open('a') as stream: + stream.write(json.dumps({'type': 'user', 'sessionId': successor, 'message': {'role': 'user', 'content': message}}) + '\n') + self.assertEqual(waker.run(args), 0) + self.assertEqual(waker.run(args), 0) + deliver.assert_not_called() + self.assertEqual(call('channel', 'get', '--name', 'example')['channel']['queue'][0]['state'], 'observed') + + def test_wake_reservation_survives_reload_and_blocks_handover(self): + with tempfile.TemporaryDirectory() as directory: + state = Path(directory) / 'graph' + def call(*args): + return subprocess.run(['node', str(root / 'bin' / 'mesh-graph.mjs'), '--state', str(state), *args], capture_output=True, text=True) + def ok(*args): + result = call(*args) + self.assertEqual(result.returncode, 0, result.stderr) + return json.loads(result.stdout) + session = f'codex:{uuid}' + ok('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json') + ok('migrate', '--apply', '--json') + ok('channel', 'create', '--name', 'example', '--session', session) + ok('channel', 'enqueue', '--name', 'example', '--id', 'message-1', '--input', 'fixture') + ok('channel', 'begin-delivery', '--name', 'example', '--id', 'message-1', '--session', session, '--generation', '1') + receipt = {'status': 'accepted', 'messageId': 'message-1', 'session': session, 'generation': 1, 'nativeQueueId': 'queue-1'} + ok('channel', 'acknowledge', '--name', 'example', '--id', 'message-1', '--input', json.dumps(receipt)) + ok('channel', 'reserve-wake', '--name', 'example', '--id', 'message-1', '--session', session, '--generation', '1', '--input', 'queue-1') + observed = ok('channel', 'get', '--name', 'example')['channel'] + self.assertEqual(observed['wakeReservation']['nativeQueueId'], 'queue-1') + self.assertNotEqual(call('channel', 'begin-handover', '--name', 'example').returncode, 0) + self.assertEqual(ok('channel', 'get', '--name', 'example')['channel']['phase'], 'active') + + def test_unsupported_recipient_does_not_reserve_delivery(self): + with tempfile.TemporaryDirectory() as directory: + args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state='fixture', channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) + queued = {'phase': 'active', 'session': 'claude-cloud:fixture:session_Test', 'generation': 1, 'queue': [{'id': 'one', 'state': 'pending', 'payload': 'fixture'}]} + reserved = {**queued, 'queue': [{**queued['queue'][0], 'state': 'inflight', 'session': queued['session'], 'generation': 1}]} + def call(args, operation, *options): + return reserved if operation == 'begin-delivery' else queued + with patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'channel_call', side_effect=call) as channel_call, patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + deliver.assert_not_called() + self.assertNotIn('begin-delivery', [call.args[1] for call in channel_call.call_args_list]) + + def test_native_adapter_receives_message_on_stdin(self): + from unittest.mock import Mock + receipt = {'status': 'queued', 'agent': 'codex', 'sessionId': uuid, 'correlationId': 'message-1', 'nativeQueueId': 'queue-1'} + output = {} + with patch.object(waker.subprocess, 'run', return_value=Mock(returncode=0, stdout=json.dumps(receipt))) as run: + self.assertEqual(waker.deliver('codex', uuid, 'message-1', 'private fixture', None, True, message_stdin=True, receipt_out=output), 0) + self.assertEqual(output, {'nativeQueueId': 'queue-1'}) + self.assertNotIn('private fixture', run.call_args.args[0]) + self.assertIn('--message-stdin', run.call_args.args[0]) + self.assertIn('--no-resume', run.call_args.args[0]) + self.assertEqual(run.call_args.kwargs['input'], 'private fixture') + + def test_cloud_queue_stays_inflight_and_is_not_resent(self): + with tempfile.TemporaryDirectory() as directory: + rootdir = Path(directory) + profiles = rootdir / 'profiles' + profiles.mkdir(mode=0o700) + profile = profiles / 'fixture.json' + profile.write_text('{}') + profile.chmod(0o600) + state = rootdir / 'graph' + def call(*args): + result = subprocess.run(['node', str(root / 'bin' / 'mesh-graph.mjs'), '--state', str(state), *args], capture_output=True, text=True) + self.assertEqual(result.returncode, 0, result.stderr) + return json.loads(result.stdout) + target = 'claude-cloud:fixture:session_Test' + call('cloud', 'register', '--session', target, '--evidence', 'test:fixture') + call('migrate', '--apply', '--json') + call('channel', 'create', '--name', 'example', '--session', target) + args = SimpleNamespace(state=str(rootdir / 'waker.json'), graph_state=str(state), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False, cloud_profile_root=str(profiles)) + with patch.object(waker, 'run_producer', return_value=([{'event': 'one'}], [])), patch.object(waker, 'deliver', return_value=0) as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + self.assertEqual(waker.run(args), 3) + self.assertEqual(deliver.call_count, 1) + self.assertEqual(deliver.call_args.kwargs['cloud_scope'], 'fixture') + self.assertEqual(deliver.call_args.kwargs['cloud_profile'], str(profile)) + item = call('channel', 'get', '--name', 'example')['channel']['queue'][0] + self.assertEqual(item['state'], 'inflight') + + def test_cloud_adapter_requires_bound_queue_receipt(self): + from unittest.mock import Mock + receipt = {'status': 'queued', 'agent': 'claude', 'sessionId': 'session_Test', 'correlationId': 'message-1', 'transport': 'claude-cloud', 'readBack': False} + with patch.object(waker.subprocess, 'run', return_value=Mock(returncode=0, stdout=json.dumps(receipt))) as run: + self.assertEqual(waker.deliver('claude', 'session_Test', 'message-1', 'fixture', None, True, message_stdin=True, cloud_profile='/fixture/profile.json', cloud_scope='fixture'), 0) + self.assertIn('--cloud', run.call_args.args[0]) + self.assertEqual(run.call_args.kwargs['input'], 'fixture') + receipt['readBack'] = True + with patch.object(waker.subprocess, 'run', return_value=Mock(returncode=0, stdout=json.dumps(receipt))): + self.assertEqual(waker.deliver('claude', 'session_Test', 'message-1', 'fixture', None, True, message_stdin=True, cloud_profile='/fixture/profile.json', cloud_scope='fixture'), 78) + + def test_lost_reservation_response_does_not_send_or_retry(self): + with tempfile.TemporaryDirectory() as directory: + state = Path(directory) / 'graph' + def call(*args): + return json.loads(subprocess.run(['node', str(root / 'bin' / 'mesh-graph.mjs'), '--state', str(state), *args], check=True, capture_output=True, text=True).stdout) + call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json') + call('migrate', '--apply', '--json') + call('channel', 'create', '--name', 'example', '--session', f'codex:{uuid}') + args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(state), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) + original = waker.channel_call + def lost_response(args, operation, *options): + result = original(args, operation, *options) + if operation == 'begin-delivery': + raise subprocess.TimeoutExpired('fixture', 1) + return result + with patch.object(waker, 'run_producer', return_value=([{'event': 'one'}], [])), patch.object(waker, 'channel_call', side_effect=lost_response), patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + deliver.assert_not_called() + with patch.object(waker, 'run_producer', return_value=([], [])), patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + deliver.assert_not_called() + self.assertEqual(call('channel', 'get', '--name', 'example')['channel']['queue'][0]['state'], 'inflight') + + def test_lost_enqueue_response_retries_same_message_without_duplication(self): + with tempfile.TemporaryDirectory() as directory: + state = Path(directory) / 'graph' + def call(*args): + return json.loads(subprocess.run(['node', str(root / 'bin' / 'mesh-graph.mjs'), '--state', str(state), *args], check=True, capture_output=True, text=True).stdout) + call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json') + call('migrate', '--apply', '--json') + call('channel', 'create', '--name', 'example', '--session', f'codex:{uuid}') + call('channel', 'begin-handover', '--name', 'example') + args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(state), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) + original = waker.channel_call + def lost_response(args, operation, *options): + result = original(args, operation, *options) + if operation == 'enqueue': + raise subprocess.TimeoutExpired('fixture', 1) + return result + with patch.object(waker, 'run_producer', return_value=([{'event': 'one'}], [])), patch.object(waker, 'channel_call', side_effect=lost_response), contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + with patch.object(waker, 'run_producer', return_value=([], [])), contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 0) + self.assertEqual(len(call('channel', 'get', '--name', 'example')['channel']['queue']), 1) + self.assertEqual(json.loads(Path(args.state).read_text())['pending'], []) + + def test_unreadable_state_stops_before_producer_advances(self): + with tempfile.TemporaryDirectory() as directory: + state = Path(directory) / 'waker.json' + state.write_text('{broken') + args = SimpleNamespace(state=str(state), graph_state=str(Path(directory) / 'graph'), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) + with patch.object(waker, 'run_producer') as producer, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + producer.assert_not_called() + self.assertEqual(state.read_text(), '{broken') + + def test_enqueue_during_handover_and_uncertain_delivery_blocks_retry(self): + with tempfile.TemporaryDirectory() as directory: + state = Path(directory) / 'graph' + def call(*args): + return json.loads(subprocess.run(['node', str(root / 'bin' / 'mesh-graph.mjs'), '--state', str(state), *args], check=True, capture_output=True, text=True).stdout) + call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json') + call('migrate', '--apply', '--json') + call('channel', 'create', '--name', '#example', '--session', f'codex:{uuid}') + call('channel', 'begin-handover', '--name', '#example') + args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(state), channel='#example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) + with patch.object(waker, 'run_producer', return_value=([{'event': 'one'}], [])), patch.object(waker, 'deliver') as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 0) + deliver.assert_not_called() + channel = call('channel', 'get', '--name', '#example')['channel'] + self.assertEqual(channel['phase'], 'handover') + self.assertEqual(channel['queue'][0]['state'], 'pending') + self.assertEqual(json.loads(Path(args.state).read_text())['pending'], []) + + def test_accepted_delivery_is_bound_and_uncertainty_is_not_retried(self): + with tempfile.TemporaryDirectory() as directory: + state = Path(directory) / 'graph' + def call(*args): + return json.loads(subprocess.run(['node', str(root / 'bin' / 'mesh-graph.mjs'), '--state', str(state), *args], check=True, capture_output=True, text=True).stdout) + call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json') + call('migrate', '--apply', '--json') + call('channel', 'create', '--name', 'example', '--session', f'codex:{uuid}') + args = SimpleNamespace(state=str(Path(directory) / 'waker.json'), graph_state=str(state), channel='example', job='test', producer=['fixture'], producer_timeout=1, managed_inbox_root=None, delivery_only=True, resume=False) + def accepted(*args, **kwargs): + kwargs['receipt_out']['nativeQueueId'] = 'queue-1' + return 0 + with patch.object(waker, 'run_producer', return_value=([{'event': 'one'}], [])), patch.object(waker, 'channel_call', wraps=waker.channel_call) as channel_call, patch.object(waker, 'deliver', side_effect=accepted) as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 0) + self.assertEqual(deliver.call_args.args[0:2], ('codex', uuid)) + reservation = next(call.args for call in channel_call.call_args_list if call.args[1] == 'begin-delivery') + self.assertEqual(reservation[-2:], ('--generation', '1')) + item = call('channel', 'get', '--name', 'example')['channel']['queue'][0] + self.assertEqual(item['state'], 'accepted') + self.assertEqual(item['nativeQueueId'], 'queue-1') + self.assertEqual(item['session'], f'codex:{uuid}') + self.assertEqual(item['generation'], 1) + with patch.object(waker, 'run_producer', return_value=([{'event': 'two'}], [])), patch.object(waker, 'deliver', return_value=78) as deliver, contextlib.redirect_stdout(io.StringIO()): + self.assertEqual(waker.run(args), 3) + self.assertEqual(waker.run(args), 3) + self.assertEqual(deliver.call_count, 1) + self.assertEqual(call('channel', 'get', '--name', 'example')['channel']['queue'][1]['state'], 'inflight') + + +if __name__ == '__main__': + unittest.main() diff --git a/packages/tmux-bridge/test/capacity-dispatch.test.mjs b/packages/tmux-bridge/test/capacity-dispatch.test.mjs index 781aa19f..780670df 100644 --- a/packages/tmux-bridge/test/capacity-dispatch.test.mjs +++ b/packages/tmux-bridge/test/capacity-dispatch.test.mjs @@ -303,7 +303,7 @@ test("agent-spawn uses a routed native rendering and closes its lease after the await mkdir(bin); await mkdir(agents); await writeFile(limen, `#!/bin/sh\nif [ "$1" = route ]; then echo '{"decision":"route","provider":"codex","model":"governed-model","nativeModel":"native-model","effort":"high","decisionId":"route-1","configHash":"cfg","lease":{"expiresAt":999,"candidate":{"key":"0123456789abcdef0123456789abcdef","model":"governed-model","effort":"high","capacityCostBase":null}}}'; exit 0; fi\nif [ "$1" = renew ]; then echo '{"status":"renewed","expiresAt":999}'; exit 0; fi\nif [ "$1" = complete ]; then echo '{"status":"completed","candidate":{"key":"0123456789abcdef0123456789abcdef","model":"governed-model","effort":"high","capacityCostBase":null}}'; exit 0; fi\nexit 2\n`); await writeFile(join(agents, "codex.conf"), `AGENT_BIN="fake-codex"\nAGENT_ALIVE_PROCESS_PATTERN="^(fake-codex|sleep)$"\nAGENT_SUBMIT_KEY="Enter"\nAGENT_PROMPT_CHAR="FAKE>"\nAGENT_WORKING_PATTERN="WORKING"\nAGENT_IDLE_PATTERN="FAKE>"\nAGENT_RESUME_CMD="fake-codex"\nAGENT_HAS_CWD_PICKER="false"\nAGENT_PICKER_PATTERN=""\nAGENT_NEW_CMD="fake-codex"\nAGENT_SESSION_DIR="${dir}"\nAGENT_SESSION_CWD_EXTRACTOR='printf "?\\n"'\nAGENT_SUPPORTS_MODEL="true"\nAGENT_MODEL_ARGS=(--model "{VALUE}")\nAGENT_MODEL_PASSTHRU_PATTERNS=()\nAGENT_SUPPORTS_EFFORT="true"\nAGENT_EFFORT_ARGS=(--effort "{VALUE}")\nAGENT_EFFORT_PASSTHRU_PATTERNS=()\n`); - await writeFile(codex, `#!/bin/sh\nprintf '%s\\n' "$*" > '${launchArgs}'\nprintf 'FAKE>\\n'\nsleep 2\n`); + await writeFile(codex, `#!/bin/sh\nprintf '%s\\n' "$*" > '${launchArgs}'\nprintf 'FAKE>\\n'\nsleep 10\n`); await chmod(limen, 0o700); await chmod(codex, 0o700); const env = { ...process.env, PATH: `${bin}:${process.env.PATH}`, LIMEN_BIN: limen, MESH_CAPACITY_STATE: state, MESH_TMUX_SOCKET: socket, MESH_LEASE_RENEW_MS: "10", AGENT_MESH_AGENTS_DIR: agents }; try { @@ -315,8 +315,10 @@ test("agent-spawn uses a routed native rendering and closes its lease after the assert.match(await readFile(launchArgs, "utf8"), /--effort high/); const opened = JSON.parse(await readFile(state, "utf8")); assert.deepEqual(opened.sessions[0].candidate, { key: "0123456789abcdef0123456789abcdef", model: "governed-model", effort: "high", capacityCostBase: null }); - await waitFor(async () => (await readFile(`${state}.events.ndjson`, "utf8")).includes("lease_renewed")); - await waitFor(async () => JSON.parse(await readFile(state, "utf8")).sessions[0]?.status === "completed", 3_000); + await waitFor(async () => (await readFile(`${state}.events.ndjson`, "utf8")).includes("lease_renewed"), 8_000); + // The fixture sleeps for ten seconds; allow the observer to be scheduled + // on a loaded runner while still requiring the lease to complete. + await waitFor(async () => JSON.parse(await readFile(state, "utf8")).sessions[0]?.status === "completed", 20_000); assert.equal((await runCommand("tmux", ["-L", socket, "has-session", "-t", target], env)).code, 0, "the tmux shell remains after the agent process exits"); const events = await readFile(`${state}.events.ndjson`, "utf8"); assert.match(events, /session_active/); diff --git a/packages/tmux-bridge/test/channel-state.test.mjs b/packages/tmux-bridge/test/channel-state.test.mjs new file mode 100644 index 00000000..834f3e28 --- /dev/null +++ b/packages/tmux-bridge/test/channel-state.test.mjs @@ -0,0 +1,116 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { acknowledge, beginDelivery, beginHandover, createChannel, enqueue, switchHandover, observeDelivery, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeQueued } from '../bin/channel-state.mjs'; + +test('a wake reservation prevents handover and requires exact accepted queue identity', () => { + const session = 'codex:22222222-2222-4222-8222-222222222222'; + let channel = createChannel('example', session); + channel = beginDelivery(enqueue(channel, 'message-1', 'fixture'), 'message-1', session, 1); + channel = acknowledge(channel, 'message-1', { status: 'accepted', messageId: 'message-1', session, generation: 1, nativeQueueId: 'queue-1' }); + assert.throws(() => reserveWake(channel, 'message-1', session, 2, 'queue-1'), /reservation/); + assert.throws(() => reserveWake(channel, 'message-1', session, 1, 'queue-2'), /identity/); + const reserved = reserveWake(channel, 'message-1', session, 1, 'queue-1'); + assert.throws(() => beginHandover(reserved), /wake reservation/); + assert.throws(() => reserveWake(reserved, 'message-1', session, 1, 'queue-1'), /reservation/); + assert.throws(() => reserveWake(beginHandover(channel), 'message-1', session, 1, 'queue-1'), /reservation/); +}); + +test('native queue identity is scoped to its accepted Codex delivery', () => { + const session = 'codex:22222222-2222-4222-8222-222222222222'; + let channel = createChannel('example', session); + channel = beginDelivery(enqueue(channel, 'message-1', 'fixture'), 'message-1', session, 1); + const receipt = { status: 'accepted', messageId: 'message-1', session, generation: 1, nativeQueueId: 'queue-1' }; + assert.throws(() => acknowledge(channel, 'message-1', { ...receipt, nativeQueueId: '../unsafe' }), /queue receipt/); + assert.throws(() => acknowledge(channel, 'message-1', { ...receipt, generation: 2 }), /receipt/); + assert.equal(acknowledge(channel, 'message-1', receipt).queue[0].nativeQueueId, 'queue-1'); + let other = createChannel('other', 'claude:22222222-2222-4222-8222-222222222222'); + other = beginDelivery(enqueue(other, 'message-1', 'fixture'), 'message-1', other.session, 1); + assert.throws(() => acknowledge(other, 'message-1', { ...receipt, session: other.session }), /queue receipt/); +}); + +test('state preparation reserves once and binds proof to the channel generation', () => { + let channel = beginHandover(createChannel('example', 'codex:old')); + channel = reserveStatePreparation(channel, 'handover-1'); + assert.throws(() => reserveStatePreparation(channel, 'handover-2'), /unresolved/); + assert.throws(() => switchHandover(channel, 'codex:new', true), /unresolved/); + channel = enqueue(channel, 'queued', 'fixture'); + const proof = { schema: 'agent-mesh.handover-state.v1', session: 'codex:old', nonce: 'handover-1', filename: 'state.yaml', sha256: 'a'.repeat(64), bytes: 42 }; + assert.throws(() => completeStatePreparation(channel, { ...proof, nonce: 'other' }), /invalid/); + assert.throws(() => completeStatePreparation({ ...channel, generation: 2 }, proof), /changed/); + assert.throws(() => completeStatePreparation({ ...channel, session: 'codex:other' }, proof), /changed/); + channel = completeStatePreparation(channel, proof); + assert.equal(channel.statePreparation.status, 'verified'); + assert.equal(channel.queue[0].state, 'pending'); + assert.throws(() => completeStatePreparation(channel, proof), /invalid/); +}); + +test('handover queues work and never reroutes an uncertain delivery', () => { + assert.equal(createChannel('#example', 'session:one').id, '#example'); + assert.throws(() => createChannel('#', 'session:one'), /invalid/); + let channel = createChannel('example', 'session:one'); + channel = enqueue(channel, 'message-1', 'hello'); + channel = enqueue(channel, 'message-0', 'second'); + assert.throws(() => beginDelivery(channel, 'message-0'), /first pending/); + channel = beginDelivery(channel, 'message-1'); + assert.throws(() => beginDelivery(channel, 'message-0'), /inflight/); + channel = beginHandover(channel); + channel = enqueue(channel, 'message-2', 'queued'); + assert.throws(() => beginDelivery(channel, 'message-2'), /handover/); + assert.throws(() => switchHandover(channel, 'session:two', true), /inflight/); + assert.throws(() => acknowledge(channel, 'message-1', { status: 'accepted', messageId: 'message-1', session: 'session:two', generation: 1 }), /receipt/); + channel = acknowledge(channel, 'message-1', { status: 'accepted', messageId: 'message-1', session: 'session:one', generation: 1 }); + assert.throws(() => switchHandover(channel, 'session:two', false), /successor/); + channel = reserveStatePreparation(channel, 'state-1'); + channel = completeStatePreparation(channel, { schema: 'agent-mesh.handover-state.v1', session: 'session:one', nonce: 'state-1', filename: 'state.yaml', sha256: 'a'.repeat(64), bytes: 1 }); + channel = switchHandover(channel, 'session:two', true); + channel = beginDelivery(channel, 'message-0'); + assert.equal(channel.queue[1].session, 'session:two'); + assert.equal(channel.queue[1].generation, 2); + assert.deepEqual(enqueue(channel, 'message-2', 'queued'), channel); + assert.throws(() => enqueue(channel, 'message-2', 'different'), /conflict/); +}); + +test('switch drains observed backlog before reserving a predecessor notice', () => { + let state = beginHandover(createChannel('example', 'codex:old')); + state = enqueue(state, 'message-1', 'fixture'); + assert.throws(() => switchHandover(state, 'codex:new', true), /state preparation/); + state = reserveStatePreparation(state, 'state-1'); + state = completeStatePreparation(state, { schema: 'agent-mesh.handover-state.v1', session: 'codex:old', nonce: 'state-1', filename: 'state.yaml', sha256: 'b'.repeat(64), bytes: 2 }); + state = switchHandover(state, 'codex:new', true); + assert.equal(state.phase, 'draining'); assert.equal(state.handover.predecessor, 'codex:old'); + assert.throws(() => reserveFinalNotice(state, 'handover-1', 'codex:new', 'a'.repeat(64)), /unavailable/); + state = beginDelivery(state, 'message-1'); + state = acknowledge(state, 'message-1', { status: 'accepted', messageId: 'message-1', session: 'codex:new', generation: 2 }); + assert.throws(() => reserveFinalNotice(state, 'handover-1', 'codex:new', 'a'.repeat(64)), /unavailable/); + const proof = { schema: 'agent-mesh.delivery-observation.v1', messageId: 'message-1', session: 'codex:new', generation: 2, evidence: 'fixture-proof' }; + assert.throws(() => observeDelivery(state, 'message-1', { ...proof, session: 'codex:old' }), /observation/); + state = observeDelivery(state, 'message-1', proof); + assert.throws(() => reserveFinalNotice(state, 'handover-1', 'codex:other', 'a'.repeat(64)), /unavailable/); + state = reserveFinalNotice(state, 'handover-1', 'codex:new', 'a'.repeat(64)); + assert.equal(state.finalNotice.session, 'codex:old'); assert.equal(state.finalNotice.generation, 1); + const receipt = { schema: 'agent-mesh.notice-queue.v1', status: 'queued-unverified', session: 'codex:old', nonce: 'handover-1', noticeSha256: 'a'.repeat(64) }; + assert.throws(() => recordNoticeQueued(state, { ...receipt, nonce: 'other' }), /reservation/); + state = recordNoticeQueued(state, receipt); + assert.equal(state.finalNotice.status, 'queued-unverified'); + assert.equal(state.phase, 'draining'); +}); + + +test('bound native wake evidence observes only its exact draining backlog', async () => { + const { createHash } = await import('node:crypto'); + let state = beginHandover(createChannel('example', 'codex:old')); + state = enqueue(state, 'message-1', 'fixture'); + state = reserveStatePreparation(state, 'state-1'); + state = completeStatePreparation(state, { schema: 'agent-mesh.handover-state.v1', session: 'codex:old', nonce: 'state-1', filename: 'state.yaml', sha256: 'b'.repeat(64), bytes: 2 }); + state = switchHandover(state, 'codex:new', true); + state = beginDelivery(state, 'message-1'); + state = acknowledge(state, 'message-1', { status: 'accepted', messageId: 'message-1', session: 'codex:new', generation: 2, nativeQueueId: 'queue-1' }); + state = reserveWake(state, 'message-1', 'codex:new', 2, 'queue-1'); + const proof = { session: 'codex:new', correlation: 'message-1', queueId: 'queue-1', evidence: `codex-wake:${'a'.repeat(64)}`, schema: 'agent-mesh.codex-wake-evidence.v4', source: 'codex-app-server.queue-start-bound-readback', channel: 'example', generation: 2, payloadSha256: createHash('sha256').update('fixture').digest('hex') }; + const mismatch = settleWake(state, { ...proof, channel: 'other' }); + assert.equal(mismatch.queue[0].state, 'accepted'); + assert.throws(() => reserveFinalNotice(mismatch, 'notice', 'codex:new', 'a'.repeat(64)), /unavailable/); + state = settleWake(state, proof); + assert.equal(state.queue[0].state, 'observed'); + assert.equal(reserveFinalNotice(state, 'notice', 'codex:new', 'a'.repeat(64)).finalNotice.session, 'codex:old'); +}); diff --git a/packages/tmux-bridge/test/claude-delivery-observation.test.mjs b/packages/tmux-bridge/test/claude-delivery-observation.test.mjs new file mode 100644 index 00000000..8b1c9835 --- /dev/null +++ b/packages/tmux-bridge/test/claude-delivery-observation.test.mjs @@ -0,0 +1,41 @@ +import assert from 'node:assert/strict'; +import { mkdtemp, mkdir, writeFile, rm, rename } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import test from 'node:test'; +import { observeClaudeDelivery, assertClaudeDeliverySnapshotCurrent } from '../bin/claude-delivery-observation.mjs'; + +const id = '22222222-2222-4222-8222-222222222222', session = `claude:${id}`; +const inbox = { schema: 'agent-mesh.monitor-inbox.v1', deliveryId: 'message-1', meshId: 'message-1', prompt: 'fixture' }; +const options = { session, generation: 2, messageId: 'message-1', payload: 'fixture' }; +const user = entry => ({ type: 'user', isMeta: true, sessionId: id, message: { role: 'user', content: `Agent Mesh inbox records\nAGENT_MESH_INBOX ${JSON.stringify(entry)}` } }); + +test('only a unique correlated user transcript record proves local inbox observation', async t => { + const root = await mkdtemp(join(tmpdir(), 'claude-observation-')); + t.after(() => rm(root, { recursive: true, force: true })); + const project = join(root, 'project'); await mkdir(project, { mode: 0o700 }); + const path = join(project, `${id}.jsonl`); + const put = rows => writeFile(path, rows.map(row => JSON.stringify(row)).join('\n') + '\n', { mode: 0o600 }); + const message = user(inbox).message.content; + const queued = { type: 'queue-operation', operation: 'enqueue', sessionId: id, content: message }; + await put([queued]); + await assert.rejects(observeClaudeDelivery({ root, ...options }), /not uniquely observed/); + await put([queued, user(inbox)]); + const proof = await observeClaudeDelivery({ root, ...options }); + assert.equal(proof.session, session); assert.equal(proof.generation, 2); + assert.match(proof.evidence, /^claude-transcript:[a-f0-9]{64}$/); + assert.doesNotThrow(() => assertClaudeDeliverySnapshotCurrent(proof)); + await writeFile(path + '.new', JSON.stringify(queued) + '\n', { mode: 0o600 }); + await rename(path + '.new', path); + assert.throws(() => assertClaudeDeliverySnapshotCurrent(proof), /transcript changed after observation/); + await put([queued, user(inbox)]); + await assert.rejects(observeClaudeDelivery({ root, ...options, payload: 'changed' }), /correlation mismatch/); + await put([queued, user(inbox), user(inbox)]); + await assert.rejects(observeClaudeDelivery({ root, ...options }), /not uniquely observed/); + await put([queued, { ...user(inbox), sessionId: '33333333-3333-4333-8333-333333333333' }]); + await assert.rejects(observeClaudeDelivery({ root, ...options }), /session mismatch/); + await put([user(inbox), queued]); + await assert.rejects(observeClaudeDelivery({ root, ...options }), /prior enqueue/); + await put([queued, queued, user(inbox)]); + await assert.rejects(observeClaudeDelivery({ root, ...options }), /prior enqueue|uniquely/); +}); diff --git a/packages/tmux-bridge/test/claude-native-mailbox.integration.py b/packages/tmux-bridge/test/claude-native-mailbox.integration.py new file mode 100644 index 00000000..b4324dc5 --- /dev/null +++ b/packages/tmux-bridge/test/claude-native-mailbox.integration.py @@ -0,0 +1,98 @@ +import json,os,pathlib,subprocess,sys,tempfile,threading,time,uuid +from http.server import HTTPServer,BaseHTTPRequestHandler +BINARY=os.environ.get('AGENT_MESH_TEST_CLAUDE_BIN') +if not BINARY: + print('SKIP: set AGENT_MESH_TEST_CLAUDE_BIN to an absolute Claude binary path');sys.exit(0) +if not os.path.isabs(BINARY) or not os.path.isfile(BINARY) or not os.access(BINARY,os.X_OK): + raise RuntimeError('test Claude binary must be an absolute executable file') +BASE=pathlib.Path(__file__).resolve().parents[1]/'bin' +NODE=os.environ.get('AGENT_MESH_TEST_NODE_BIN','/usr/local/bin/node') +if not os.path.isabs(NODE) or not os.access(NODE,os.X_OK):raise RuntimeError('test Node binary must be absolute and executable') +if len(sys.argv)>1: + root=pathlib.Path(sys.argv[1]); count=[0] + class H(BaseHTTPRequestHandler): + def do_POST(self): + self.rfile.read(int(self.headers.get('Content-Length',0))); count[0]+=1; time.sleep(2 if count[0]==1 else 0) + es=[('message_start',{'type':'message_start','message':{'id':'msg_fixture','type':'message','role':'assistant','model':'fixture','content':[],'stop_reason':None,'stop_sequence':None,'usage':{'input_tokens':1,'output_tokens':1}}}),('content_block_start',{'type':'content_block_start','index':0,'content_block':{'type':'text','text':''}}),('content_block_delta',{'type':'content_block_delta','index':0,'delta':{'type':'text_delta','text':'fixture reply'}}),('content_block_stop',{'type':'content_block_stop','index':0}),('message_delta',{'type':'message_delta','delta':{'stop_reason':'end_turn','stop_sequence':None},'usage':{'output_tokens':2}}),('message_stop',{'type':'message_stop'})] + body=''.join('event: '+n+'\ndata: '+json.dumps(v)+'\n\n' for n,v in es).encode(); self.send_response(200); self.send_header('Content-Type','text/event-stream'); self.send_header('Content-Length',str(len(body))); self.end_headers(); self.wfile.write(body) + def log_message(self,*args): pass + server=HTTPServer(('127.0.0.1',18984),H);threading.Thread(target=server.serve_forever,daemon=True).start(); sid=str(uuid.uuid4()) + cmd=[BINARY,'--print','--input-format','stream-json','--output-format','stream-json','--verbose','--model','claude-sonnet-4-5','--permission-mode','dontAsk','--session-id',sid,'--name','fixture-peer','--tools','','--strict-mcp-config','--mcp-config','{"mcpServers":{}}','--disable-slash-commands','--settings','{"disableAllHooks":true}'] + p=subprocess.Popen(cmd,stdin=subprocess.PIPE,stdout=subprocess.PIPE,stderr=subprocess.PIPE,text=True) + rec={'schema':'agent-mesh.monitor-inbox.v1','deliveryId':'fixture-1','meshId':'fixture-1','prompt':'synthetic delivery'} + def send(content):p.stdin.write(json.dumps({'type':'user','message':{'role':'user','content':content}})+'\n');p.stdin.flush() + send('first synthetic turn');time.sleep(.7) + import importlib.util + native=str(BASE/'agent-inbox-native.py') + spec=importlib.util.spec_from_file_location('native',native); m=importlib.util.module_from_spec(spec);spec.loader.exec_module(m) + os.environ['CLAUDE_BIN']=BINARY + try: + owner=m.identity(p.pid); match=m.registration(sid,owner) + with m.NativeClient() as client: listing=m.tool_json(client.request('tools/call',{'name':'ListAgents','arguments':{}})) + native_result={'registrationFound':bool(match),'sections':[(x.get('kind'),len(x.get('rows',[]))) for x in listing.get('sections',[])]} + except Exception as e:native_result={'errorType':type(e).__name__,'error':str(e)[:180]} + inbox_script=native.replace('agent-inbox-native.py','agent-session-inbox.py') + inbox_spec=importlib.util.spec_from_file_location('mailbox',inbox_script); inbox_mod=importlib.util.module_from_spec(inbox_spec); inbox_spec.loader.exec_module(inbox_mod) + inbox_root=root/'inbox'; inbox=inbox_mod.prepare(inbox_root,sid) + os.environ['MESH_COMMS_STATE']=str(root/'comms'); os.environ['XDG_STATE_HOME']=str(root/'state') + watcher=subprocess.Popen(['/usr/bin/python3',inbox_script,'serve','--root',str(inbox_root),'--session',sid,'--owner-pid',str(p.pid),'--owner-start',owner['start'],'--batch-seconds','0.1','--retry-seconds','0.05'],stdout=subprocess.DEVNULL,stderr=subprocess.PIPE,text=True) + deadline=time.monotonic()+5 + while time.monotonic() rm(root, { recursive: true, force: true })); + const status = { loggedIn: true, apiProvider: 'firstParty', authMethod: 'claude.ai', storedClaudeAiLogin: true, email: 'fixture@example.invalid', orgId: 'synthetic-org', configDirectory: root }; + const profile = { scope: 'fixture', configDir: root, command: '/synthetic/claude', expectedSubjectHash: claudeSubjectHash(status) }; + return { root, status, profile }; +} + +test('matching provider, profile and account produce only a bound digest', async t => { + const f = await fixture(t); + const run = async (command, args, options) => { + assert.equal(command, f.profile.command); assert.deepEqual(args, ['auth', 'status', '--json']); + assert.equal(options.env.CLAUDE_CONFIG_DIR, f.root); + return { stdout: JSON.stringify(f.status) }; + }; + const value = await verifyClaudeAccount(f.profile, run); + assert.deepEqual(value, { scope: 'fixture', subjectHash: f.profile.expectedSubjectHash }); + assert.ok(!JSON.stringify(value).includes(f.status.email)); + let invoked = false; + assert.equal(await withClaudeAccount(f.profile, async context => { invoked = true; assert.equal(context.configDir, f.root); return 'receipt'; }, run), 'receipt'); + assert.equal(invoked, true); +}); + +test('profile file is private, scoped and digest-bound across replay', async t => { + const f = await fixture(t), path = join(f.root, 'profile.json'); + await writeFile(path, JSON.stringify({ schema: 'agent-mesh.cloud-account.v1', ...f.profile }), { mode: 0o600 }); + const loaded = await loadClaudeAccountProfile(path, 'fixture'); + assert.equal((await loadClaudeAccountProfile(path, 'fixture', loaded.digest)).digest, loaded.digest); + await assert.rejects(loadClaudeAccountProfile(path, 'other'), /scope/); + await chmod(path, 0o644); + await assert.rejects(loadClaudeAccountProfile(path, 'fixture'), /file/); + await chmod(path, 0o600); + await writeFile(path, '{}'); + await assert.rejects(loadClaudeAccountProfile(path, 'fixture', loaded.digest), /changed/); + await symlink(path, join(f.root, 'link.json')); + await assert.rejects(loadClaudeAccountProfile(join(f.root, 'link.json'), 'fixture')); +}); + +test('wrong account or profile fails before the action', async t => { + const f = await fixture(t); let invoked = false; + const run = async () => ({ stdout: JSON.stringify({ ...f.status, orgId: 'other' }) }); + await assert.rejects(withClaudeAccount(f.profile, async () => { invoked = true; }, run), /scope mismatch/); + assert.equal(invoked, false); + await assert.rejects(verifyClaudeAccount(f.profile, async () => ({ stdout: JSON.stringify({ ...f.status, configDirectory: '/other' }) })), /scope mismatch/); + await assert.rejects(verifyClaudeAccount(f.profile, async () => ({ stdout: JSON.stringify({ ...f.status, loggedIn: false }) })), /identity unavailable/); + await chmod(f.root, 0o755); + await assert.rejects(verifyClaudeAccount(f.profile, run), /private/); +}); + +test('account changes or transport errors after invocation stay uncertain', async t => { + const f = await fixture(t); let count = 0, actions = 0; + const run = async () => ({ stdout: JSON.stringify(++count === 1 ? f.status : { ...f.status, email: 'other@example.invalid' }) }); + await assert.rejects(withClaudeAccount(f.profile, async () => { actions++; return 'accepted'; }, run), /outcome uncertain/); + assert.equal(actions, 1); + await assert.rejects(withClaudeAccount(f.profile, async () => { throw new Error('transport'); }, async () => ({ stdout: JSON.stringify(f.status) })), /outcome uncertain/); +}); diff --git a/packages/tmux-bridge/test/cloud-native-call.test.mjs b/packages/tmux-bridge/test/cloud-native-call.test.mjs index e3b33fd1..461d6034 100644 --- a/packages/tmux-bridge/test/cloud-native-call.test.mjs +++ b/packages/tmux-bridge/test/cloud-native-call.test.mjs @@ -6,6 +6,7 @@ import { dirname, join } from 'node:path'; import { fileURLToPath } from 'node:url'; import { promisify } from 'node:util'; import test from 'node:test'; +import { claudeSubjectHash } from '../bin/cloud-account-binding.mjs'; const exec = promisify(execFile); const bin = join(dirname(dirname(fileURLToPath(import.meta.url))), 'bin'); @@ -16,8 +17,15 @@ async function fixture(t, mode = 'success') { t.after(() => rm(root, { recursive: true, force: true })); const provider = join(root, 'fake-claude.mjs'); const calls = join(root, 'calls.jsonl'); + const profilePath = join(root, 'profile.json'); await writeFile(provider, `#!/usr/bin/env node -import { appendFile } from 'node:fs/promises'; +import { appendFile, readFile, writeFile } from 'node:fs/promises'; +if (process.argv[2] === 'auth') { + let count = 0; try { count = Number(await readFile(process.env.CLOUD_TEST_AUTH_COUNT, 'utf8')); } catch {} + await writeFile(process.env.CLOUD_TEST_AUTH_COUNT, String(++count)); + console.log(JSON.stringify({loggedIn:true,apiProvider:'firstParty',authMethod:'claude.ai',storedClaudeAiLogin:true,email:process.env.CLOUD_TEST_MODE === 'wrong-account' || (process.env.CLOUD_TEST_MODE === 'account-changed' && count > 1) ? 'other@example.invalid' : 'fixture@example.invalid',orgId:'fixture-org',configDirectory:process.env.CLAUDE_CONFIG_DIR})); + process.exit(0); +} let message = ''; for await (const chunk of process.stdin) message += chunk; await appendFile(process.env.CLOUD_TEST_CALLS, JSON.stringify({ args: process.argv.slice(2), message }) + '\\n'); const mode = process.env.CLOUD_TEST_MODE; @@ -28,7 +36,10 @@ else console.log(JSON.stringify({ ok: mode !== 'refused', session_id: mode === ' if (mode === 'nonzero') process.exitCode = 1; `); await chmod(provider, 0o755); + const status = { loggedIn: true, apiProvider: 'firstParty', authMethod: 'claude.ai', storedClaudeAiLogin: true, email: 'fixture@example.invalid', orgId: 'fixture-org' }; + await writeFile(profilePath, JSON.stringify({ schema: 'agent-mesh.cloud-account.v1', scope: 'fixture', configDir: root, command: provider, expectedSubjectHash: claudeSubjectHash(status) }), { mode: 0o600 }); const env = { ...process.env, CLAUDE_BIN: provider, CLOUD_TEST_CALLS: calls, CLOUD_TEST_MODE: mode, + CLOUD_TEST_AUTH_COUNT: join(root, 'auth-count'), MESH_COMMS_STATE: join(root, 'comms'), AGENT_FALLBACK_STATE: join(root, 'fallback') }; // A host replay capability must never enter an isolated test invocation. delete env.MESH_COMMS_REPLAY_FD; @@ -43,9 +54,51 @@ if (mode === 'nonzero') process.exitCode = 1; gate: (action) => command('python3', [join(bin, 'mesh-comms.py'), action, '--scope', 'claude', '--reason', 'synthetic test', '--by', 'test']), status: () => command('python3', [join(bin, 'mesh-comms.py'), 'status']), calls: async () => { try { return (await readFile(calls, 'utf8')).trim().split('\n').filter(Boolean).map(JSON.parse); } catch (error) { if (error.code === 'ENOENT') return []; throw error; } }, + profileArgs: ['--cloud-profile', profilePath, '--cloud-scope', 'fixture'], + profilePath, }; } +test('scoped cloud transport checks the selected account before and after enqueue', async t => { + const f = await fixture(t); + const result = await f.invoke(f.profileArgs); + assert.equal(result.code, 0, result.stderr); + assert.equal(JSON.parse(result.stdout).readBack, false); + assert.equal((await f.calls()).length, 1); +}); + +test('wrong account refuses before sending; account change after send remains unknown', async t => { + const wrong = await fixture(t, 'wrong-account'); + assert.notEqual((await wrong.invoke(wrong.profileArgs)).code, 0); + assert.equal((await wrong.calls()).length, 0); + const changed = await fixture(t, 'account-changed'); + assert.notEqual((await changed.invoke(changed.profileArgs)).code, 0); + assert.equal((await changed.calls()).length, 1); + assert.notEqual((await changed.invoke(changed.profileArgs)).code, 0); + assert.equal((await changed.calls()).length, 1); + assert.equal(JSON.parse((await changed.status()).stdout).counts.unknown, 1); +}); + +test('queued scoped replay preserves profile and refuses a changed profile', async t => { + const f = await fixture(t); + assert.equal((await f.gate('queue')).code, 0); + assert.equal(JSON.parse((await f.invoke(f.profileArgs)).stdout).held, true); + await writeFile(f.profilePath, '{}', { mode: 0o600 }); + await f.gate('on'); + assert.equal((await f.calls()).length, 0); + assert.equal(JSON.parse((await f.status()).stdout).counts.unknown, 1); +}); + +test('queued scoped replay uses the same private account profile', async t => { + const f = await fixture(t); + assert.equal((await f.gate('queue')).code, 0); + assert.equal(JSON.parse((await f.invoke(f.profileArgs)).stdout).held, true); + const flushed = await f.gate('on'); + assert.equal(flushed.code, 0, flushed.stderr); + assert.equal(JSON.parse(flushed.stdout).counts.delivered, 1); + assert.equal((await f.calls()).length, 1); +}); + test('cloud delivery verifies exact provider JSON and needs no local transcript', async t => { const f = await fixture(t); const result = await f.invoke(); diff --git a/packages/tmux-bridge/test/codex-compaction-evidence.test.mjs b/packages/tmux-bridge/test/codex-compaction-evidence.test.mjs new file mode 100644 index 00000000..a451227d --- /dev/null +++ b/packages/tmux-bridge/test/codex-compaction-evidence.test.mjs @@ -0,0 +1,81 @@ +import assert from 'node:assert/strict'; +import { execFile } from 'node:child_process'; +import { chmod, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { promisify } from 'node:util'; +import test from 'node:test'; +import { compactionFromThread, verifyCodexCompactionEvidence } from '../bin/codex-compaction-evidence.mjs'; +import { createAppServer } from './fixtures/fake-app-server.mjs'; + +const exec = promisify(execFile), thread = '22222222-2222-4222-8222-222222222222', turn = 'turn-fixture', item = 'item-fixture'; +const bin = fileURLToPath(new URL('../bin/codex-compaction-evidence.mjs', import.meta.url)); +const graph = fileURLToPath(new URL('../bin/mesh-graph.mjs', import.meta.url)); +const response = () => ({ thread: { id: thread, turns: [{ id: turn, status: 'completed', itemsView: 'full', items: [{ id: item, type: 'contextCompaction', completedAtMs: 123456789 }] }] } }); + +test('only an exact completed native compaction in a full turn is accepted', () => { + const identity = { thread, turn, item }; + assert.equal(compactionFromThread(response(), identity).completedAtMs, 123456789); + const implicitFull = response(); delete implicitFull.thread.turns[0].itemsView; + assert.equal(compactionFromThread(implicitFull, identity).completedAtMs, 123456789); + const missingTime = response(); missingTime.thread.turns[0].items[0].completedAtMs = null; + const summary = response(); summary.thread.turns[0].itemsView = 'summary'; + const invalidView = response(); invalidView.thread.turns[0].itemsView = null; + const missingStatus = response(); delete missingStatus.thread.turns[0].status; + const wrongType = response(); wrongType.thread.turns[0].items[0].type = 'agentMessage'; + const duplicate = response(); duplicate.thread.turns.push(duplicate.thread.turns[0]); + const duplicateItem = response(); duplicateItem.thread.turns[0].items.push(duplicateItem.thread.turns[0].items[0]); + for (const value of [missingTime, summary, invalidView, missingStatus, wrongType, duplicate, duplicateItem, { thread: { id: 'other', turns: [] } }]) assert.throws(() => compactionFromThread(value, identity)); +}); + +test('native read records private evidence before an idempotent graph event', async t => { + const root = await mkdtemp(join(tmpdir(), 'compaction-evidence-')); + t.after(() => rm(root, { recursive: true, force: true })); + const state = join(root, 'graph'), evidence = join(root, 'evidence'), socket = join(root, 'fake.sock'); + await mkdir(state, { mode: 0o700 }); await mkdir(evidence, { mode: 0o700 }); + const call = async (...args) => JSON.parse((await exec(process.execPath, [graph, '--state', state, ...args])).stdout); + const requests = []; let completedAtMs = 123456789; + const server = createAppServer((request, peer) => { + if (!request.id) return; + if (request.method === 'thread/read') { requests.push(request); const data = response(); data.thread.turns[0].items[0].completedAtMs = completedAtMs; peer.send({ id: request.id, result: data }); } + else peer.send({ id: request.id, result: {} }); + }); + await new Promise(resolve => server.listen(socket, resolve)); + t.after(() => new Promise(resolve => server.close(resolve))); + const env = { ...process.env, CODEX_REMOTE_SOCK: socket, CODEX_NO_REMOTE: '' }; + const run = async () => JSON.parse((await exec(process.execPath, [bin, '--thread', thread, '--turn', turn, '--item', item, '--evidence-root', evidence, '--graph-state', state], { env })).stdout); + await assert.rejects(exec(process.execPath, [bin, '--thread', thread, '--turn', turn, '--item', item, '--evidence-root', evidence], { env })); + assert.equal(requests.length, 0, 'no native observation without an explicit graph'); + assert.deepEqual(await readdir(evidence), []); + await assert.rejects(run()); + assert.equal((await readdir(evidence)).length, 1, 'proof remains after graph rejection'); + await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', thread, '--json'); + await call('migrate', '--apply', '--json'); + const cursor = (await call('query', 'changes', '--input', JSON.stringify({ initial: 'head' }))).cursor; + const first = await run(), second = await run(); + assert.equal(first.duplicate, false); assert.equal(second.duplicate, true); + assert.equal(first.evidence, second.evidence); + assert.deepEqual(requests.map(r => r.params), Array(3).fill({ threadId: thread, includeTurns: true })); + const files = await readdir(evidence); assert.equal(files.length, 1); + const saved = JSON.parse(await readFile(join(evidence, files[0]), 'utf8')); + assert.equal(saved.session, `codex:${thread}`); assert.equal(saved.completedAtMs, 123456789); + const verified = await verifyCodexCompactionEvidence({ evidenceRoot: evidence, reference: first.evidence, session: `codex:${thread}` }); + assert.equal(verified.completedAtMs, 123456789); + const cliVerified = JSON.parse((await exec(process.execPath, [bin, '--verify', first.evidence, '--session', `codex:${thread}`, '--evidence-root', evidence], { env })).stdout); + assert.equal(cliVerified.completedAtMs, 123456789); + assert.equal(requests.length, 3, 'verification does not contact the native app server'); + await assert.rejects(verifyCodexCompactionEvidence({ evidenceRoot: evidence, reference: first.evidence, session: 'codex:33333333-3333-4333-8333-333333333333' }), /identity/); + const feed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); + assert.deepEqual(feed.events.filter(e => e.type === 'session.compacted').map(e => e.evidence), [first.evidence]); + completedAtMs += 1; + await assert.rejects(run(), /compaction observation or recording failed/); + const afterConflict = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); + assert.equal(afterConflict.events.filter(e => e.type === 'session.compacted').length, 1); + const evidenceFile = join(evidence, files[0]); + await chmod(evidenceFile, 0o644); + await assert.rejects(verifyCodexCompactionEvidence({ evidenceRoot: evidence, reference: first.evidence, session: `codex:${thread}` }), /invalid evidence file/); + await chmod(evidenceFile, 0o600); + await writeFile(evidenceFile, JSON.stringify({ ...saved, completedAtMs: 123456780 }) + '\n'); + await assert.rejects(verifyCodexCompactionEvidence({ evidenceRoot: evidence, reference: first.evidence, session: `codex:${thread}` }), /digest/); +}); diff --git a/packages/tmux-bridge/test/codex-mcp-observation.test.mjs b/packages/tmux-bridge/test/codex-mcp-observation.test.mjs new file mode 100644 index 00000000..52bfcd60 --- /dev/null +++ b/packages/tmux-bridge/test/codex-mcp-observation.test.mjs @@ -0,0 +1,45 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { sampleCodexMcpConnections } from '../bin/codex-mcp-observation.mjs'; + +const input = { threadId: '22222222-2222-4222-8222-222222222222', generation: 1, profileSha256: 'a'.repeat(64) }; +const connect = fn => async (_options, work) => work(fn); + +test('pagination returns a partial connection sample with no names or claimed startup count', async () => { + const requests = []; + const result = await sampleCodexMcpConnections(input, connect(async (method, params) => { + requests.push({ method, params }); + return params.cursor === null ? { data: [{ name: 'first', runtimeStatus: 'connected', httpOrigin: 'private-fixture' }], nextCursor: 'page-2' } : { data: [{ name: 'second', runtimeStatus: null }], nextCursor: null }; + })); + assert.equal(requests.length, 2); + assert.ok(requests.every(item => item.method === 'mcpServerStatus/list' && item.params.threadId === input.threadId)); + assert.equal(result.connectedObserved, 1); + assert.equal(result.unavailableStatus, 1); + assert.equal(result.mcpStarted, null); + assert.equal(result.startupTokens, null); + assert.equal(result.profileBinding, 'unverified'); + assert.equal(result.completeness, 'unverified-non-atomic'); + assert.ok(!JSON.stringify(result).includes('first')); + assert.ok(!JSON.stringify(result).includes('private-fixture')); +}); + +test('cursor loops, duplicate identities, omitted pagination and invalid status fail closed', async () => { + for (const page of [ + { data: [], nextCursor: 'again' }, + { data: [{ name: 'same', runtimeStatus: 'connected' }, { name: 'same', runtimeStatus: 'failed' }], nextCursor: null }, + { data: [] }, + { data: [{ name: 'one', runtimeStatus: 'invented' }], nextCursor: null } + ]) await assert.rejects(sampleCodexMcpConnections(input, connect(async () => page))); + await assert.rejects(sampleCodexMcpConnections({ ...input, threadId: 'invalid' }, connect(async () => { throw new Error('must not call'); })), /invalid/); +}); + +test('an empty response does not claim a zero startup count', async () => { + const result = await sampleCodexMcpConnections(input, connect(async () => ({ data: [], nextCursor: null }))); + assert.equal(result.connectedObserved, 0); + assert.equal(result.mcpStarted, null); + assert.equal(result.completeness, 'unverified-non-atomic'); +}); + +test('there is no default live app-server connection', async () => { + await assert.rejects(sampleCodexMcpConnections(input), /invalid MCP sample request/); +}); diff --git a/packages/tmux-bridge/test/codex-mcp-startup-notifications.test.mjs b/packages/tmux-bridge/test/codex-mcp-startup-notifications.test.mjs new file mode 100644 index 00000000..461e68c0 --- /dev/null +++ b/packages/tmux-bridge/test/codex-mcp-startup-notifications.test.mjs @@ -0,0 +1,126 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { mkdtemp, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { createAppServer } from './fixtures/fake-app-server.mjs'; +import { withCodexAppServer } from '../bin/codex-app-server.mjs'; +import { createCodexMcpStartupObserver } from '../bin/codex-mcp-startup-notifications.mjs'; +import { assessCodexRoleStart } from '../bin/codex-role-start-assessment.mjs'; + +const id = '22222222-2222-4222-8222-222222222222'; +const other = '33333333-3333-4333-8333-333333333333'; +const event = (threadId, name, status) => ({ method: 'mcpServer/startupStatus/updated', params: { threadId, name, status } }); + +test('passive notifications are bound after native thread response without exposing names', () => { + const observer = createCodexMcpStartupObserver(); + observer.onNotification(event(id, 'private-fixture', 'starting')); + observer.onNotification(event(other, 'other-fixture', 'ready')); + observer.bindThread(id); + observer.onNotification(event(id, 'private-fixture', 'ready')); + observer.onNotification(event(other, 'other-fixture', 'failed')); + const receipt = observer.snapshot(); + assert.deepEqual(receipt.counts, { starting: 0, ready: 1, failed: 0, cancelled: 0 }); + assert.equal(receipt.completeness, 'unverified'); + assert.equal(receipt.mcpStarted, null); + assert.equal(receipt.startupTokens, null); + assert.ok(!JSON.stringify(receipt).includes('private-fixture')); + assert.throws(() => observer.bindThread(other), /binding/); +}); + +test('missing identity and notification overflow make the sample explicitly incomplete', () => { + const observer = createCodexMcpStartupObserver(); + observer.onNotification(event(null, 'fixture', 'ready')); + observer.bindThread(id); + for (let i = 0; i < 4097; i++) observer.onNotification(event(id, 'fixture', 'ready')); + const receipt = observer.snapshot(); + assert.equal(receipt.invalidOrOverflow, true); + assert.equal(receipt.mcpStarted, null); +}); + +test('existing app-server client forwards notifications without issuing an inventory request', async t => { + const root = await mkdtemp(join(tmpdir(), 'passive-notify-')); + const socket = join(root, 'test.sock'); + const requests = []; + const server = createAppServer((msg, peer) => { + if (msg.method === 'initialize') peer.send({ id: msg.id, result: {} }); + else if (msg.method === 'thread/start') { + requests.push(msg.method); + peer.send(event(id, 'fixture-server', 'starting')); + peer.send({ id: msg.id, result: { thread: { id } } }); + peer.send(event(id, 'fixture-server', 'ready')); + } else if (msg.id !== undefined) requests.push(msg.method); + }); + await new Promise((resolve, reject) => server.listen(socket, resolve).once('error', reject)); + const old = process.env.CODEX_REMOTE_SOCK; process.env.CODEX_REMOTE_SOCK = socket; + t.after(async () => { if (old === undefined) delete process.env.CODEX_REMOTE_SOCK; else process.env.CODEX_REMOTE_SOCK = old; await new Promise(resolve => server.close(resolve)); await rm(root, { recursive: true, force: true }); }); + const observer = createCodexMcpStartupObserver(); + const receipt = await withCodexAppServer({ clientName: 'test', timeout: 3000, timeoutMessage: 'timeout', onNotification: observer.onNotification }, async request => { + const result = await request('thread/start', { ephemeral: true }); + observer.bindThread(result.thread.id); + await new Promise(resolve => setTimeout(resolve, 30)); + return observer.snapshot(); + }); + assert.deepEqual(requests, ['thread/start']); + assert.equal(receipt.counts.ready, 1); + assert.equal(receipt.mcpStarted, null); +}); + +test('a native permission request for the bound thread is observed without retaining content', () => { + const observer = createCodexMcpStartupObserver(); + observer.onNotification({ id: 12, method: 'item/permissions/requestApproval', params: { threadId: id, permissions: 'private-fixture' } }); + observer.onNotification({ id: 13, method: 'item/fileChange/requestApproval', params: { threadId: other } }); + observer.bindThread(id); + const sample = observer.snapshot(); + assert.equal(sample.permissionRequestObserved, true); + assert.ok(!JSON.stringify(sample).includes('private-fixture')); + const empty = createCodexMcpStartupObserver(); empty.bindThread(id); + assert.equal(empty.snapshot().permissionRequestObserved, null); +}); + + +test('legacy approval requests bind by conversation and fail closed without leaking fields', () => { + for (const method of ['applyPatchApproval', 'execCommandApproval']) { + const observer = createCodexMcpStartupObserver(); + observer.onNotification({ id: 'legacy-request', method, params: { conversationId: id, reason: 'private-fixture' } }); + observer.bindThread(id); + const sample = observer.snapshot(); + assert.equal(sample.permissionRequestObserved, true); + assert.equal(sample.invalidOrOverflow, false); + const expected = { profile: { id: ':read-only', extends: null }, approvalPolicy: 'never', sandbox: { type: 'readOnly', networkAccess: false } }; + const response = { thread: { id }, activePermissionProfile: expected.profile, approvalPolicy: 'never', sandbox: expected.sandbox }; + const assessment = assessCodexRoleStart({ startResponse: response, sample, expected }); + assert.equal(assessment.status, 'rollback-required'); + assert.ok(assessment.failures.includes('unexpected-permission-request')); + assert.ok(!JSON.stringify(sample).includes('private-fixture')); + const otherObserver = createCodexMcpStartupObserver(); otherObserver.bindThread(id); + otherObserver.onNotification({ id: 0, method, params: { conversationId: other } }); + assert.equal(otherObserver.snapshot().permissionRequestObserved, null); + const malformed = createCodexMcpStartupObserver(); malformed.bindThread(id); + malformed.onNotification({ id: null, method, params: { conversationId: id } }); + assert.equal(malformed.snapshot().invalidOrOverflow, true); + } +}); + +test('app-server client forwards legacy approval requests without answering them', async t => { + const root = await mkdtemp(join(tmpdir(), 'legacy-approval-')), socket = join(root, 'test.sock'), received = []; + const server = createAppServer((msg, peer) => { + received.push(msg); + if (msg.method === 'initialize') peer.send({ id: msg.id, result: {} }); + else if (msg.method === 'thread/start') { + peer.send({ id: 'server-request', method: 'execCommandApproval', params: { conversationId: id, command: ['private-fixture'] } }); + peer.send({ id: msg.id, result: { thread: { id } } }); + } + }); + await new Promise((resolve, reject) => server.listen(socket, resolve).once('error', reject)); + const old = process.env.CODEX_REMOTE_SOCK; process.env.CODEX_REMOTE_SOCK = socket; + t.after(async () => { if (old === undefined) delete process.env.CODEX_REMOTE_SOCK; else process.env.CODEX_REMOTE_SOCK = old; await new Promise(resolve => server.close(resolve)); await rm(root, { recursive: true, force: true }); }); + const observer = createCodexMcpStartupObserver(); + const sample = await withCodexAppServer({ clientName: 'test', timeout: 3000, timeoutMessage: 'timeout', onNotification: observer.onNotification }, async request => { + const result = await request('thread/start', { ephemeral: true }); observer.bindThread(result.thread.id); + await new Promise(resolve => setTimeout(resolve, 30)); return observer.snapshot(); + }); + assert.equal(sample.permissionRequestObserved, true); + assert.ok(!received.some(msg => msg.id === 'server-request')); + assert.ok(!JSON.stringify(sample).includes('private-fixture')); +}); diff --git a/packages/tmux-bridge/test/codex-native-rollback.integration.py b/packages/tmux-bridge/test/codex-native-rollback.integration.py new file mode 100644 index 00000000..08509444 --- /dev/null +++ b/packages/tmux-bridge/test/codex-native-rollback.integration.py @@ -0,0 +1,139 @@ +#!/usr/bin/env python3 +"""Opt-in isolated Codex rollback integration test. Never uses live state.""" +import importlib.util, json, os, pathlib, selectors, subprocess, tempfile, time +base = pathlib.Path(__file__).resolve().parents[1] / 'bin' +spec = importlib.util.spec_from_file_location('owned', base / 'isolated-pid-namespace.py') +module = importlib.util.module_from_spec(spec) +spec.loader.exec_module(module) +rollback_spec = importlib.util.spec_from_file_location('isolated_rollback', base / 'isolated-role-rollback.py') +rollback_module = importlib.util.module_from_spec(rollback_spec) +rollback_spec.loader.exec_module(rollback_module) +binary = os.environ.get('AGENT_MESH_TEST_CODEX_BIN') +if not binary: + print('SKIP: set AGENT_MESH_TEST_CODEX_BIN to an absolute Codex binary path') + raise SystemExit(0) +if not os.path.isabs(binary) or not os.path.isfile(binary) or (not os.access(binary, os.X_OK)): + raise RuntimeError('test Codex binary must be an absolute executable file') + +class Client: + + def __init__(self, lease): + self.lease = lease + self.seq = 0 + self.buffer = b'' + self.events = [] + self.sel = selectors.DefaultSelector() + self.sel.register(lease.process.stdout, selectors.EVENT_READ) + + def write(self, entry): + self.lease.process.stdin.write((json.dumps(entry) + '\n').encode()) + self.lease.process.stdin.flush() + + def request(self, method, params, timeout=15): + self.seq += 1 + rid = self.seq + self.write({'id': rid, 'method': method, 'params': params}) + deadline = time.monotonic() + timeout + while time.monotonic() < deadline: + if b'\n' not in self.buffer: + if not self.sel.select(max(0, deadline - time.monotonic())): + break + data = os.read(self.lease.process.stdout.fileno(), 65536) + if not data: + break + self.buffer += data + while b'\n' in self.buffer: + line, self.buffer = self.buffer.split(b'\n', 1) + try: + row = json.loads(line) + except ValueError: + continue + if row.get('method'): + self.events.append(row) + continue + if row.get('id') == rid: + if 'error' in row: + raise RuntimeError('RPC error ' + str(row['error'].get('code'))) + return row['result'] + raise RuntimeError('RPC timeout') + + def init(self): + self.request('initialize', {'clientInfo': {'name': 'rollback-isolated', 'version': '1'}, 'capabilities': {'experimentalApi': True}}) + self.write({'method': 'initialized', 'params': {}}) +with tempfile.TemporaryDirectory(prefix='permission-rollback-isolated-') as td: + root = pathlib.Path(td) + (root / 'home').mkdir(mode=448) + for name in ['old', 'new']: + (root / name).mkdir(mode=448) + fixture = root / 'elicitation.py' + beat = root / 'heartbeat' + fixture.write_text('import json,sys,pathlib,threading,time\np=pathlib.Path(sys.argv[1])\ndef tick():\n n=0\n while True:\n n+=1;p.write_text(str(n));time.sleep(.1)\nthreading.Thread(target=tick,daemon=True).start()\nfor line in sys.stdin:\n try:req=json.loads(line)\n except:continue\n m=req.get("method")\n if m=="initialize":result={"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"fixture","version":"1"}}\n elif m=="tools/list":result={"tools":[]}\n elif m=="notifications/initialized":\n print(json.dumps({"jsonrpc":"2.0","id":"synthetic","method":"elicitation/create","params":{"message":"synthetic","requestedSchema":{"type":"object","properties":{}}}}),flush=True);continue\n else:continue\n if "id" in req:print(json.dumps({"jsonrpc":"2.0","id":req["id"],"result":result}),flush=True)\n') + (root / 'old' / 'config.toml').write_text('model_provider = "fixture"\nmodel = "fixture"\n[model_providers.fixture]\nname = "fixture"\nbase_url = "http://127.0.0.1:18765/v1"\nwire_api = "responses"\nrequires_openai_auth = false\n') + provider = root / 'provider.py' + provider.write_text('from http.server import HTTPServer,BaseHTTPRequestHandler\nfrom pathlib import Path\nclass H(BaseHTTPRequestHandler):\n def do_POST(self):\n self.rfile.read(int(self.headers.get("content-length",0)));Path(' + repr(str(root / 'provider-seen')) + ').write_text("seen");self.send_response(503);self.end_headers();self.wfile.write(b"{}")\n def log_message(self,*a):pass\nHTTPServer(("127.0.0.1",18765),H).serve_forever()\n') + launcher = root / 'launcher.py' + launcher.write_text('import os,subprocess,sys\nsubprocess.Popen([sys.executable,sys.argv[1]],stdin=subprocess.DEVNULL,stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL)\nos.execv(sys.argv[2],sys.argv[2:])\n') + (root / 'new' / 'config.toml').write_text('[mcp_servers.fixture]\ncommand = "/usr/bin/python3"\nargs = [' + json.dumps(str(fixture)) + ', ' + json.dumps(str(beat)) + ']\n') + + def open_server(name): + command = ['/usr/bin/env', 'HOME=' + str(root / 'home'), 'CODEX_HOME=' + str(root / name), 'PATH=/usr/bin:/bin'] + (['/usr/bin/python3', str(launcher), str(provider)] if name == 'old' else []) + [binary, 'app-server', '--listen', 'stdio://'] + lease = module.IsolatedNamespace.prepare(td, command) + leases.append(lease) + lease.release() + client = Client(lease) + client.init() + return (lease, client) + leases = [] + try: + old, oldc = open_server('old') + oldthread = oldc.request('thread/start', {'ephemeral': True, 'cwd': td, 'approvalPolicy': 'never', 'sandbox': 'read-only'})['thread']['id'] + new, newc = open_server('new') + started = newc.request('thread/start', {'ephemeral': True, 'cwd': td, 'approvalPolicy': 'on-request', 'sandbox': 'read-only'}) + newthread = started['thread']['id'] + deadline = time.monotonic() + 8 + req = None + while time.monotonic() < deadline: + newc.request('thread/loaded/list', {'limit': 100}) + req = next((x for x in newc.events if x.get('method') == 'mcpServer/elicitation/request' and x.get('params', {}).get('threadId') == newthread), None) + if req and beat.exists(): + break + time.sleep(0.1) + if not req or not beat.exists(): + raise RuntimeError('expected isolated elicitation unavailable') + js = "import {createCodexMcpStartupObserver} from OBS;import {assessCodexRoleStart} from ASSESS;const x=JSON.parse(await new Promise(r=>{let s='';process.stdin.on('data',c=>s+=c);process.stdin.on('end',()=>r(s))}));const o=createCodexMcpStartupObserver();o.onNotification(x.event);o.bindThread(x.started.thread.id);const expected={profile:{id:':read-only',extends:null},approvalPolicy:'never',sandbox:{type:'readOnly',networkAccess:false}};const a=assessCodexRoleStart({startResponse:x.started,sample:o.snapshot(),expected});console.log(JSON.stringify(a));" + js = js.replace('OBS', json.dumps((base / 'codex-mcp-startup-notifications.mjs').as_uri())).replace('ASSESS', json.dumps((base / 'codex-role-start-assessment.mjs').as_uri())) + assessed = json.loads(subprocess.check_output(['/usr/bin/node', '--input-type=module', '-e', js], input=json.dumps({'started': started, 'event': req}).encode(), timeout=5)) + if assessed['status'] != 'rollback-required' or 'unexpected-permission-request' not in assessed['failures']: + raise RuntimeError('assessment did not require rollback') + first = beat.read_text() + time.sleep(0.35) + observed_before = beat.read_text() + if observed_before == first: + raise RuntimeError('fixture heartbeat was not active') + journal = root / 'rollback-journal' + journal.mkdir(mode=0o700) + rollback = rollback_module.IsolatedRoleRollback('codex:' + newthread, new.stop, str(journal)) + decision = rollback.apply(assessed) + if decision['status'] != 'local-init-exited' or decision['handover'] != 'blocked': + raise RuntimeError('owned rollback did not verify namespace init exit') + if rollback.apply(assessed) != decision: + raise RuntimeError('replayed rollback changed its receipt') + receipt = decision['namespaceStop'] + time.sleep(0.8) + observed_after = beat.read_text() + oldRead = oldc.request('thread/loaded/list', {'limit': 100}) + turn = oldc.request('turn/start', {'threadId': oldthread, 'input': [{'type': 'text', 'text': 'synthetic recovery check', 'text_elements': []}]}) + deadline = time.monotonic() + 3 + while time.monotonic() < deadline and (not (root / 'provider-seen').exists()): + time.sleep(0.05) + if turn.get('turn', {}).get('status') != 'inProgress' or not (root / 'provider-seen').exists(): + raise RuntimeError('predecessor did not accept isolated turn') + if observed_before != observed_after or oldthread not in oldRead.get('data', []): + raise RuntimeError('rollback isolation check failed') + if receipt.get('status') != 'init-exited': + raise RuntimeError('namespace init exit not verified') + print(json.dumps({'predecessorAcceptedNewTurn': turn.get('turn', {}).get('status') == 'inProgress', 'localProviderObserved': (root / 'provider-seen').exists(), 'isolatedNetwork': True, 'temporaryHome': True, 'realSuccessorElicitation': True, 'permissionResponseSent': False, 'assessment': assessed['status'], 'permissionFailure': True, 'namespaceStop': receipt, 'successorFixtureHeartbeatStopped': observed_before == observed_after, 'predecessorStillLoaded': oldthread in oldRead.get('data', []), 'syntheticSessionsOnly': True})) + finally: + for lease in reversed(leases): + if not lease._stopped: + lease.stop() diff --git a/packages/tmux-bridge/test/codex-role-mcp-overrides.test.mjs b/packages/tmux-bridge/test/codex-role-mcp-overrides.test.mjs new file mode 100644 index 00000000..4a82e26b --- /dev/null +++ b/packages/tmux-bridge/test/codex-role-mcp-overrides.test.mjs @@ -0,0 +1,27 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { planCodexMcpOverrides } from '../bin/codex-role-mcp-overrides.mjs'; + +const launchPlan = { schema: 'agent-mesh.role-launch-plan.v1', mcpToStart: ['allowed'], mcpUnavailable: ['offline'] }; +const inventory = { allowed: { enabled: true }, offline: { enabled: true }, extra: { command: 'private-fixture' } }; + +test('explicitly disables each excluded effective server without copying its config', () => { + const result = planCodexMcpOverrides({ launchPlan, effectiveServers: inventory }); + assert.deepEqual(JSON.parse(JSON.stringify(result.config)), { mcp_servers: { extra: { enabled: false }, offline: { enabled: false } } }); + assert.equal(result.excludedCount, 2); + assert.equal(result.isolation, 'unverified'); + assert.ok(!JSON.stringify(result).includes('private-fixture')); +}); + +test('missing, disabled, malformed and overlapping inputs fail closed', () => { + assert.throws(() => planCodexMcpOverrides({ launchPlan, effectiveServers: { other: {} } }), /missing/); + assert.throws(() => planCodexMcpOverrides({ launchPlan, effectiveServers: { allowed: { enabled: false } } }), /disabled/); + assert.throws(() => planCodexMcpOverrides({ launchPlan, effectiveServers: { allowed: { enabled: 'yes' } } }), /invalid/); + assert.throws(() => planCodexMcpOverrides({ launchPlan: { ...launchPlan, mcpUnavailable: ['allowed'] }, effectiveServers: inventory }), /invalid/); +}); + +test('an empty allowed role disables every server in the supplied inventory', () => { + const result = planCodexMcpOverrides({ launchPlan: { ...launchPlan, mcpToStart: [] }, effectiveServers: inventory }); + assert.equal(result.excludedCount, 3); + assert.ok(Object.values(result.config.mcp_servers).every(item => item.enabled === false)); +}); diff --git a/packages/tmux-bridge/test/codex-role-start-assessment.test.mjs b/packages/tmux-bridge/test/codex-role-start-assessment.test.mjs new file mode 100644 index 00000000..24c0e260 --- /dev/null +++ b/packages/tmux-bridge/test/codex-role-start-assessment.test.mjs @@ -0,0 +1,34 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { assessCodexRoleStart } from '../bin/codex-role-start-assessment.mjs'; + +const id = '22222222-2222-4222-8222-222222222222'; +const expected = { profile: { id: ':read-only', extends: null }, approvalPolicy: 'never', sandbox: { type: 'readOnly', networkAccess: false } }; +const startResponse = { thread: { id }, activePermissionProfile: expected.profile, approvalPolicy: 'never', sandbox: expected.sandbox }; +const sample = { schema: 'agent-mesh.codex-mcp-notification-sample.v1', requestedThreadId: id, permissionRequestObserved: null, invalidOrOverflow: false, counts: { ready: 1 } }; + +test('matching native fields remain incomplete without plugin and event coverage', () => { + const receipt = assessCodexRoleStart({ startResponse, sample, expected }); + assert.equal(receipt.status, 'observed-incomplete'); + assert.equal(receipt.readyObserved, 1); + assert.equal(receipt.mcpStarted, null); + assert.equal(receipt.startupTokens, null); + assert.ok(receipt.unknown.includes('plugin-isolation')); +}); + +test('permission request or exact-policy mismatch demands rollback', () => { + const pending = assessCodexRoleStart({ startResponse, sample: { ...sample, permissionRequestObserved: true }, expected }); + assert.equal(pending.status, 'rollback-required'); + assert.ok(pending.failures.includes('unexpected-permission-request')); + const wrong = assessCodexRoleStart({ startResponse: { ...startResponse, sandbox: { type: 'readOnly', networkAccess: true } }, sample, expected }); + assert.equal(wrong.status, 'rollback-required'); + assert.ok(wrong.failures.includes('sandbox-mismatch')); + assert.throws(() => assessCodexRoleStart({ startResponse, sample: { ...sample, requestedThreadId: 'different' }, expected }), /invalid/); +}); + +test('unobserved fields and broken event coverage cannot prove readiness', () => { + const receipt = assessCodexRoleStart({ startResponse: { ...startResponse, activePermissionProfile: null }, sample: { ...sample, invalidOrOverflow: true }, expected }); + assert.equal(receipt.status, 'observed-incomplete'); + assert.ok(receipt.unknown.includes('permission-profile')); + assert.ok(receipt.unknown.includes('notification-integrity')); +}); diff --git a/packages/tmux-bridge/test/codex-wake-evidence.test.mjs b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs new file mode 100644 index 00000000..79ee06cd --- /dev/null +++ b/packages/tmux-bridge/test/codex-wake-evidence.test.mjs @@ -0,0 +1,192 @@ +import assert from 'node:assert/strict'; +import { execFile } from 'node:child_process'; +import { createHash } from 'node:crypto'; +import { appendFile, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { promisify } from 'node:util'; +import test from 'node:test'; +import { verifyCodexWakeEvidence } from '../bin/codex-wake-evidence.mjs'; +import { createAppServer } from './fixtures/fake-app-server.mjs'; + +const exec = promisify(execFile); +const thread = '22222222-2222-4222-8222-222222222222'; +const turn = '33333333-3333-4333-8333-333333333333'; +const correlation = 'waker-44444444-4444-4444-8444-444444444444'; +const bin = fileURLToPath(new URL('../bin/codex-wake-evidence.mjs', import.meta.url)); +const graph = fileURLToPath(new URL('../bin/mesh-graph.mjs', import.meta.url)); + +test('queued wake needs explicit apply, a native start and durable correlated proof', async t => { + const root = await mkdtemp(join(tmpdir(), 'wake-evidence-')); + t.after(() => rm(root, { recursive: true, force: true })); + const state = join(root, 'graph'), evidence = join(root, 'evidence'), socket = join(root, 'fake.sock'); + await mkdir(state, { mode: 0o700 }); await mkdir(evidence, { mode: 0o700 }); + const call = async (...args) => JSON.parse((await exec(process.execPath, [graph, '--state', state, ...args])).stdout); + await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', thread, '--json'); + await call('migrate', '--apply', '--json'); + const session = `codex:${thread}`; + async function prepareChannel(name, nativeId = 'queued-1') { + await call('channel', 'create', '--name', name, '--session', session); + await call('channel', 'enqueue', '--name', name, '--id', correlation, '--input', 'fixture'); + await call('channel', 'begin-delivery', '--name', name, '--id', correlation, '--session', session, '--generation', '1'); + await call('channel', 'acknowledge', '--name', name, '--id', correlation, '--input', JSON.stringify({ status: 'accepted', messageId: correlation, session, generation: 1, nativeQueueId: nativeId })); + } + await prepareChannel('success'); + const cursor = (await call('query', 'changes', '--input', JSON.stringify({ initial: 'head' }))).cursor; + const requests = []; let mode = 'success', nativeId = 'queued-1', autoReservedMs = 0, delayedReads = 0; + const server = createAppServer((request, peer) => { + if (!request.id) return; + requests.push(request); + if (request.method === 'thread/queue/list') peer.send({ id: request.id, result: { data: mode === 'auto-drained' ? [] : [{ id: nativeId, clientUserMessageId: mode === 'wrong' ? 'wrong' : correlation, input: [{ type: 'text', text: mode === 'wrong-queue-payload' ? 'different' : 'fixture', text_elements: [] }] }], nextCursor: null } }); + else if (request.method === 'thread/queue/start') peer.send({ id: request.id, result: { turn: { id: turn, status: mode === 'uncertain' ? 'completed' : 'inProgress', startedAt: mode === 'null-start' ? null : 123456789, items: [] } } }); + else if (request.method === 'thread/read' && request.params.includeTurns === false) peer.send({ id: request.id, result: { thread: { id: thread, status: { type: mode === 'busy' ? 'active' : 'idle' } } } }); + else if (request.method === 'thread/read' && mode === 'null-start' && delayedReads++ === 0) peer.send({ id: request.id, result: { thread: { id: thread, turns: [{ id: turn, startedAt: null, itemsView: 'full', items: [] }] } } }); + else if (request.method === 'thread/read') peer.send({ id: request.id, result: { thread: { id: mode === 'wrong-thread' ? turn : thread, turns: [{ id: mode === 'wrong-turn' ? thread : turn, status: 'completed', startedAt: mode === 'wrong-time' ? 123456788 : mode === 'auto-same-second' ? Math.floor(autoReservedMs / 1000) : nativeId === 'queued-auto-proof' && mode !== 'auto-old-turn' ? Math.floor(Date.now() / 1000) : 123456789, itemsView: mode === 'partial' ? 'summary' : 'full', items: [{ type: 'userMessage', id: 'msg-1', startedAtMs: nativeId === 'queued-auto-proof' ? Date.now() : 123456789001, clientId: mode === 'wrong-client' ? 'other' : correlation, content: [{ type: 'text', text: mode === 'wrong-input' ? 'different' : 'fixture', text_elements: [] }] }] }] } } }); + else peer.send({ id: request.id, result: {} }); + }); + await new Promise(resolve => server.listen(socket, resolve)); + t.after(() => new Promise(resolve => server.close(resolve))); + const env = { ...process.env, CODEX_REMOTE_SOCK: socket, CODEX_NO_REMOTE: '' }; + const args = ['--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--channel', 'success', '--generation', '1', '--evidence-root', evidence, '--graph-state', state]; + mode = 'busy'; + const busy = JSON.parse((await exec(process.execPath, [bin, '--preflight', '--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation], { env })).stdout); + assert.equal(busy.status, 'not-ready'); + const beforeBusy = requests.filter(r => r.method === 'thread/queue/start').length; + await assert.rejects(exec(process.execPath, [bin, '--apply', ...args], { env })); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, beforeBusy); + assert.equal((await call('channel', 'get', '--name', 'success')).channel.wakeReservation, undefined); + mode = 'success'; requests.length = 0; + await assert.rejects(exec(process.execPath, [bin, ...args], { env })); + assert.equal(requests.length, 0); + await prepareChannel('handover'); + await call('channel', 'begin-handover', '--name', 'handover'); + await assert.rejects(exec(process.execPath, [bin, '--apply', '--thread', thread, '--queue-id', 'queued-1', '--correlation', correlation, '--channel', 'handover', '--generation', '1', '--evidence-root', evidence, '--graph-state', state], { env })); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, 0); + mode = 'wrong'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...args], { env })); + assert.deepEqual(await readdir(evidence), []); + nativeId = 'queued-auto'; await prepareChannel('auto-drained', nativeId); + mode = 'auto-drained'; + await assert.rejects(exec(process.execPath, [bin, '--apply', '--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'auto-drained', '--generation', '1', '--evidence-root', evidence, '--graph-state', state], { env })); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, 0); + const auto = (await call('channel', 'get', '--name', 'auto-drained')).channel; + assert.equal(auto.queue[0].state, 'accepted'); assert.equal(auto.wakeReservation, undefined); + assert.deepEqual(await readdir(evidence), []); + nativeId = 'queued-payload'; await prepareChannel('payload', nativeId); + mode = 'wrong-queue-payload'; + await assert.rejects(exec(process.execPath, [bin, '--apply', '--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'payload', '--generation', '1', '--evidence-root', evidence, '--graph-state', state], { env })); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, 0); + assert.equal((await call('channel', 'get', '--name', 'payload')).channel.wakeReservation.nativeQueueId, nativeId); + assert.deepEqual(await readdir(evidence), []); + nativeId = 'queued-1'; mode = 'success'; + const first = JSON.parse((await exec(process.execPath, [bin, '--apply', ...args], { env })).stdout); + assert.equal(first.duplicate, false); + const success = (await call('channel', 'get', '--name', 'success')).channel; + assert.equal(success.wakeReservation, undefined); + assert.equal(success.queue[0].wakeEvidence, first.evidence); + assert.equal(first.settled, true); + const verified = await verifyCodexWakeEvidence({ evidenceRoot: evidence, reference: first.evidence, session: `codex:${thread}` }); + assert.equal(verified.turn, turn); + assert.equal(verified.correlation, correlation); + assert.equal(verified.schema, 'agent-mesh.codex-wake-evidence.v4'); + assert.equal(verified.channel, 'success'); assert.equal(verified.generation, 1); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, 1); + await assert.rejects(exec(process.execPath, [bin, '--apply', ...args], { env })); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, 1); + const again = JSON.parse((await exec(process.execPath, [bin, '--publish', first.evidence, '--session', `codex:${thread}`, '--channel', 'success', '--evidence-root', evidence, '--graph-state', state], { env })).stdout); + assert.equal(again.duplicate, true); + assert.equal(again.settled, true); + await prepareChannel('duplicate'); + await assert.rejects(call('channel', 'reserve-wake', '--name', 'duplicate', '--id', correlation, '--session', session, '--generation', '1', '--input', 'queued-1')); + const feed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); + assert.deepEqual(feed.events.filter(e => e.type === 'session.woken').map(e => e.evidence), [first.evidence]); + const uncertainRoot = join(root, 'uncertain'); await mkdir(uncertainRoot, { mode: 0o700 }); + nativeId = 'queued-uncertain'; await prepareChannel('uncertain', nativeId); + const uncertainArgs = ['--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'uncertain', '--generation', '1', '--evidence-root', uncertainRoot, '--graph-state', state]; + mode = 'uncertain'; + await assert.rejects(exec(process.execPath, [bin, '--apply', ...uncertainArgs], { env })); + await assert.rejects(call('channel', 'begin-handover', '--name', 'uncertain')); + await prepareChannel('competing', nativeId); + await assert.rejects(call('channel', 'reserve-wake', '--name', 'competing', '--id', correlation, '--session', session, '--generation', '1', '--input', nativeId)); + assert.deepEqual((await readdir(uncertainRoot)).map(name => name.split('-')[0]), ['intent']); + const starts = requests.filter(r => r.method === 'thread/queue/start').length; + await assert.rejects(exec(process.execPath, [bin, '--apply', ...uncertainArgs], { env })); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, starts); + const recoverArgs = ['--reconcile', '--channel', 'uncertain', '--evidence-root', uncertainRoot, '--graph-state', state]; + await assert.rejects(exec(process.execPath, [bin, ...recoverArgs], { env })); + const callsBeforeReconcile = requests.length; + mode = 'success'; + await assert.rejects(exec(process.execPath, [bin, '--apply', ...recoverArgs], { env })); + assert.equal(requests.length, callsBeforeReconcile); + assert.ok((await call('channel', 'get', '--name', 'uncertain')).channel.wakeReservation); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, starts); + const uncertainFeed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); + assert.equal(uncertainFeed.events.filter(e => e.type === 'session.woken').length, 1); + const partialRoot = join(root, 'partial'); await mkdir(partialRoot, { mode: 0o700 }); + nativeId = 'queued-partial'; await prepareChannel('partial', nativeId); + const partialArgs = ['--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'partial', '--generation', '1', '--evidence-root', partialRoot, '--graph-state', state]; + mode = 'partial'; + await assert.rejects(exec(process.execPath, [bin, '--apply', ...partialArgs], { env })); + assert.deepEqual((await readdir(partialRoot)).map(name => name.split('-')[0]), ['intent']); + const partialFeed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); + assert.equal(partialFeed.events.filter(e => e.type === 'session.woken').length, 1); + for (const mismatch of ['wrong-thread', 'wrong-turn', 'wrong-time', 'wrong-client', 'wrong-input']) { + const mismatchRoot = join(root, mismatch); await mkdir(mismatchRoot, { mode: 0o700 }); + nativeId = `queued-${mismatch}`; await prepareChannel(mismatch, nativeId); + const mismatchArgs = ['--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', mismatch, '--generation', '1', '--evidence-root', mismatchRoot, '--graph-state', state]; + mode = mismatch; + await assert.rejects(exec(process.execPath, [bin, '--apply', ...mismatchArgs], { env })); + assert.deepEqual((await readdir(mismatchRoot)).map(name => name.split('-')[0]), ['intent']); + } + const mismatchFeed = await call('query', 'changes', '--input', JSON.stringify({ sinceCursor: cursor })); + assert.equal(mismatchFeed.events.filter(e => e.type === 'session.woken').length, 1); + // Simulate persisted draining state only; no operational cutover is enabled. + const drainRoot = join(root, 'drain'); await mkdir(drainRoot, { mode: 0o700 }); + nativeId = 'queued-drain'; await prepareChannel('drain', nativeId); + let graphState = await call('show', '--json'); + const draining = graphState.channels.find(item => item.id === 'drain'); + draining.phase = 'draining'; draining.handover = { predecessor: 'codex:old-fixture', previousGeneration: 0, successor: session, backlog: [correlation] }; + await appendFile(join(state, 'events.jsonl'), `${JSON.stringify({ schema: 'agent-mesh.session-graph-event.v1', id: 'fixture-drain', type: 'channel.updated', at: new Date().toISOString(), channel: draining, seq: graphState.lastSeq + 1, host: 'local' })}\n`); + const drainArgs = ['--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'drain', '--generation', '1', '--evidence-root', drainRoot, '--graph-state', state]; + mode = 'uncertain'; await assert.rejects(exec(process.execPath, [bin, '--apply', ...drainArgs], { env })); + const callsBeforeRecovery = requests.filter(r => r.method === 'thread/queue/start').length; + mode = 'success'; + await assert.rejects(exec(process.execPath, [bin, '--apply', '--reconcile', '--channel', 'drain', '--evidence-root', drainRoot, '--graph-state', state], { env })); + const drained = (await call('channel', 'get', '--name', 'drain')).channel; + assert.equal(drained.queue[0].state, 'accepted'); assert.ok(drained.wakeReservation); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, callsBeforeRecovery); + // Both unbound v3 and bound v4 recovery receipts fail closed, even with a valid digest. + for (const bound of [false, true]) { + const old = { schema: `agent-mesh.codex-wake-evidence.v${bound ? 4 : 3}`, source: `codex-app-server.correlated-recovery${bound ? '-bound' : ''}`, session, queueId: nativeId, correlation, turn, startedAt: 123456789, ...(bound ? { channel: 'drain', generation: 1, payloadSha256: createHash('sha256').update('fixture').digest('hex') } : {}) }; + const body = `${JSON.stringify(old)}\n`, digest = createHash('sha256').update(body).digest('hex'); + await writeFile(join(drainRoot, `wake-${digest}.json`), body, { mode: 0o600 }); + await assert.rejects(verifyCodexWakeEvidence({ evidenceRoot: drainRoot, reference: `codex-wake:${digest}`, session }), /identity mismatch/); + } + // Readback alone cannot distinguish a queued item from a steered message. + const autoRoot = join(root, 'auto-proof'); await mkdir(autoRoot, { mode: 0o700 }); + nativeId = 'queued-auto-proof'; await prepareChannel('auto-proof', nativeId); + const autoArgs = ['--observe-auto', '--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'auto-proof', '--generation', '1', '--evidence-root', autoRoot, '--graph-state', state]; + const callsBeforeAuto = requests.length; + await assert.rejects(exec(process.execPath, [bin, '--apply', ...autoArgs], { env })); + assert.equal(requests.length, callsBeforeAuto); + const autoState = (await call('channel', 'get', '--name', 'auto-proof')).channel; + assert.equal(autoState.queue[0].state, 'accepted'); + assert.equal(autoState.wakeReservation, undefined); + assert.deepEqual(await readdir(autoRoot), []); + await assert.rejects(call('channel', 'reserve-wake', '--name', 'auto-proof', '--id', correlation, '--session', session, '--generation', '1', '--input', nativeId, '--source', 'auto-readback')); + const oldProof = { schema: 'agent-mesh.codex-wake-evidence.v5', source: 'codex-app-server.auto-start-bound-readback', session, queueId: nativeId, correlation, turn, startedAt: 123456789, channel: 'auto-proof', generation: 1, payloadSha256: createHash('sha256').update('fixture').digest('hex') }; + const oldBody = `${JSON.stringify(oldProof)}\n`, oldDigest = createHash('sha256').update(oldBody).digest('hex'); + await writeFile(join(autoRoot, `wake-${oldDigest}.json`), oldBody, { mode: 0o600 }); + await assert.rejects(verifyCodexWakeEvidence({ evidenceRoot: autoRoot, reference: `codex-wake:${oldDigest}`, session }), /identity mismatch/); + const delayedRoot = join(root, 'delayed'); await mkdir(delayedRoot, { mode: 0o700 }); + nativeId = 'queued-delayed'; await prepareChannel('delayed', nativeId); mode = 'null-start'; + const beforeDelayed = requests.filter(r => r.method === 'thread/queue/start').length; + const delayed = JSON.parse((await exec(process.execPath, [bin, '--apply', '--thread', thread, '--queue-id', nativeId, '--correlation', correlation, '--channel', 'delayed', '--generation', '1', '--evidence-root', delayedRoot, '--graph-state', state], { env })).stdout); + assert.equal((await verifyCodexWakeEvidence({ evidenceRoot: delayedRoot, reference: delayed.evidence, session })).startedAt, 123456789); + assert.equal(requests.filter(r => r.method === 'thread/queue/start').length, beforeDelayed + 1); + assert.ok(delayedReads >= 2); + const file = join(evidence, `wake-${first.evidence.slice('codex-wake:'.length)}.json`); + const saved = JSON.parse(await readFile(file, 'utf8')); saved.startedAt++; + await writeFile(file, `${JSON.stringify(saved)}\n`); + await assert.rejects(verifyCodexWakeEvidence({ evidenceRoot: evidence, reference: first.evidence, session: `codex:${thread}` }), /digest/); +}); diff --git a/packages/tmux-bridge/test/handover-claude-observation.test.mjs b/packages/tmux-bridge/test/handover-claude-observation.test.mjs new file mode 100644 index 00000000..efe8ec0d --- /dev/null +++ b/packages/tmux-bridge/test/handover-claude-observation.test.mjs @@ -0,0 +1,53 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { mkdtemp, mkdir, writeFile, rm, link } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { observeClaudeFinalNotice } from '../bin/handover-claude-observation.mjs'; + +const id = '22222222-2222-4222-8222-222222222222'; +const nonce = 'handover-33333333-3333-4333-8333-333333333333'; +const message = 'Sleeping. Continue [here](codex://threads/22222222-2222-4222-8222-222222222222)'; +const request = { type: 'user', sessionId: id, message: { content: `[HANDOVER:${nonce}] fixture` } }; +const assistant = (content, stop = 'end_turn', nativeId = 'message-1') => ({ type: 'assistant', sessionId: id, message: { id: nativeId, stop_reason: stop, content } }); +const answer = assistant([{ type: 'text', text: message }]); +async function fixture(t, records) { + const root = await mkdtemp(join(tmpdir(), 'claude-notice-')); + t.after(() => rm(root, { recursive: true, force: true })); + const project = join(root, 'project'); await mkdir(project); + const path = join(project, `${id}.jsonl`); + await writeFile(path, records.map(value => JSON.stringify(value)).join('\n') + '\n', { mode: 0o600 }); + return { root, path, observe: () => observeClaudeFinalNotice({ root, id, nonce, message }) }; +} + +test('a completed exact local Claude response is bound to its session and anchor', async t => { + const f = await fixture(t, [request, assistant([{ type: 'thinking', thinking: 'synthetic' }]), answer]); + const proof = await f.observe(); + assert.equal(proof.session, `claude:${id}`); + assert.match(proof.transcriptSha256, /^[a-f0-9]{64}$/); + assert.equal(proof.nonce, nonce); +}); + +test('later turns, tool use, incomplete answers and session mismatch fail closed', async t => { + for (const records of [ + [request, answer, { ...request, message: { content: 'later turn' } }], + [request, answer, assistant([{ type: 'tool_use', id: 'fixture', name: 'fixture' }], 'tool_use', 'message-2')], + [request, assistant([{ type: 'text', text: message }], 'tool_use')], + [request, assistant([{ type: 'text', text: message }, { type: 'tool_use', id: 'fixture' }], 'end_turn')], + [request, { ...answer, sessionId: '44444444-4444-4444-8444-444444444444' }], + [{ ...request, message: { content: 'wrong anchor' } }, answer], + [request, assistant([{ type: 'text', text: `${message} extra` }])], + ]) { + const f = await fixture(t, records); + await assert.rejects(f.observe()); + } +}); + +test('incomplete or hard-linked transcript is rejected', async t => { + const f = await fixture(t, [request, answer]); + await writeFile(f.path, JSON.stringify(request), { mode: 0o600 }); + await assert.rejects(f.observe(), /partial/); + await writeFile(f.path, `${JSON.stringify(request)}\n${JSON.stringify(answer)}\n`); + await link(f.path, join(f.root, 'other-link')); + await assert.rejects(f.observe(), /invalid transcript file/); +}); diff --git a/packages/tmux-bridge/test/handover-codex-observation.test.mjs b/packages/tmux-bridge/test/handover-codex-observation.test.mjs new file mode 100644 index 00000000..1ce7bdc0 --- /dev/null +++ b/packages/tmux-bridge/test/handover-codex-observation.test.mjs @@ -0,0 +1,57 @@ +import assert from 'node:assert/strict'; +import { appendFile, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import test from 'node:test'; +import { observeCodexFinalNotice } from '../bin/handover-codex-observation.mjs'; + +const id = '22222222-2222-4222-8222-222222222222', nonce = 'handover-44444444-4444-4444-8444-444444444444', message = 'Continue: [next](codex://threads/33333333-3333-4333-8333-333333333333)'; +const line = value => JSON.stringify(value) + '\n'; +const meta = () => line({ type: 'session_meta', payload: { id } }); +const input = () => line({ type: 'event_msg', payload: { type: 'user_message', message: `[HANDOVER:${nonce}] Write the final notice.` } }); +const output = () => line({ type: 'response_item', payload: { type: 'message', role: 'assistant', phase: 'final_answer', content: [{ type: 'output_text', text: message }] } }); +const complete = () => line({ type: 'event_msg', payload: { type: 'task_complete', last_agent_message: message } }); + +async function fixture(t) { + const root = await mkdtemp(join(tmpdir(), 'notice-observation-')); + t.after(() => rm(root, { recursive: true, force: true })); + const path = join(root, `rollout-${id}.jsonl`); + await writeFile(path, meta() + input() + output() + complete(), { mode: 0o600 }); + return { root, path, run: () => observeCodexFinalNotice({ root, id, nonce, message }) }; +} +test('a correlated final Codex notice is observed without returning transcript text', async t => { + const f = await fixture(t), result = await f.run(); + assert.equal(result.session, `codex:${id}`); + assert.match(result.messageSha256, /^[a-f0-9]{64}$/); + assert.ok(!JSON.stringify(result).includes(message)); +}); +test('a later user turn or malformed trailing record rejects the observation', async t => { + const f = await fixture(t); + await appendFile(f.path, line({ type: 'event_msg', payload: { type: 'user_message', message: 'later' } })); + await assert.rejects(f.run(), /not proven/); + await writeFile(f.path, meta() + input() + output() + complete() + '{bad}\n'); + await assert.rejects(f.run(), /invalid transcript record/); + await writeFile(f.path, meta() + input() + output() + complete() + '{partial'); + await assert.rejects(f.run(), /partial transcript/); +}); +test('identity, exact completion, and an unambiguous native transcript are required', async t => { + const f = await fixture(t); + await writeFile(f.path, line({ type: 'session_meta', payload: { id: 'other' } }) + input() + output() + complete()); + await assert.rejects(f.run(), /session mismatch/); + await writeFile(f.path, meta() + input() + output() + line({ type: 'event_msg', payload: { type: 'task_complete', last_agent_message: 'different' } })); + await assert.rejects(f.run(), /not proven/); + await writeFile(f.path, meta() + input() + output() + line({ type: 'response_item', payload: { type: 'function_call' } }) + complete()); + await assert.rejects(f.run(), /not proven/); + await writeFile(f.path, meta() + input() + output() + complete() + line({ type: 'event_msg', payload: { type: 'task_started' } })); + await assert.rejects(f.run(), /not proven/); + await writeFile(f.path, meta() + input() + output() + complete()); + await writeFile(join(f.root, `duplicate-${id}.jsonl`), meta() + input() + output() + complete()); + await assert.rejects(f.run(), /ambiguous/); +}); +test('a symlinked transcript is not accepted', async t => { + const f = await fixture(t), other = join(f.root, 'unrelated'); + await writeFile(other, meta() + input() + output() + complete()); + await rm(f.path); + await symlink(other, f.path); + await assert.rejects(f.run(), /unavailable or ambiguous/); +}); diff --git a/packages/tmux-bridge/test/handover-dry-run.test.mjs b/packages/tmux-bridge/test/handover-dry-run.test.mjs new file mode 100644 index 00000000..0cea9a82 --- /dev/null +++ b/packages/tmux-bridge/test/handover-dry-run.test.mjs @@ -0,0 +1,26 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { rehearseHandover } from '../bin/handover-dry-run.mjs'; + +const role = name => ({ role: name, oldSession: `codex:${name}-old`, newSession: `codex:${name}-new`, profile: { schema: 'agent-mesh.role-profile.v1', role: name, permissions: ['read'], mcp: ['core', 'optional'], plugins: ['plugin'] }, authority: { role: name, permissions: ['read'], humanGatedPermissions: ['external'], mcp: ['core', 'optional'], plugins: ['plugin'] } }); + +test('two synthetic roles preserve messages and rollback on isolated faults', async () => { + for (const name of ['one', 'two']) { + const fixture = role(name); + const offline = await rehearseHandover({ ...fixture, offlineMcp: ['optional'], messageDuringHandover: true }); + assert.equal(offline.simulated, true); + assert.equal(offline.outcome, 'switched-awaiting-delivery'); + assert.equal(offline.channel.session, fixture.newSession); + assert.equal(offline.channel.queue[0].state, 'pending'); + assert.equal(offline.launch.mcpStarted, 1); + assert.deepEqual(offline.launch.mcpUnavailable, ['optional']); + assert.equal(offline.launch.startupTokens, null); + for (const fault of ['permission', 'interrupted', 'quota']) { + const result = await rehearseHandover({ ...fixture, fault, messageDuringHandover: true }); + assert.equal(result.outcome, 'rolled-back'); + assert.equal(result.channel.session, fixture.oldSession); + assert.equal(result.channel.phase, 'active'); + assert.equal(result.channel.queue[0].state, 'pending'); + } + } +}); diff --git a/packages/tmux-bridge/test/handover-notice-transport.test.mjs b/packages/tmux-bridge/test/handover-notice-transport.test.mjs new file mode 100644 index 00000000..390150af --- /dev/null +++ b/packages/tmux-bridge/test/handover-notice-transport.test.mjs @@ -0,0 +1,68 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { queueLocalFinalNotice, queueReservedFinalNotice, observeLocalFinalNotice } from '../bin/handover-notice-transport.mjs'; +import { formatFinalNotice } from '../bin/handover-notice.mjs'; + +const id = '22222222-2222-4222-8222-222222222222'; +const nonce = 'handover-33333333-3333-4333-8333-333333333333'; +const options = { session: `claude:${id}`, nonce, target: { kind: 'codex', id }, prefix: 'Sleeping.', label: 'Continue here', managedInboxRoot: '/synthetic/inbox' }; +const notice = formatFinalNotice(options); +const response = { status: 'queued', agent: 'claude', sessionId: id, correlationId: nonce }; + +test('native adapter sends the correlated notice request on stdin and reports queue only', async () => { + let called = 0; + const queued = await queueLocalFinalNotice(options, async (command, args, config) => { + called++; + assert.equal(command, process.execPath); + assert.ok(args.includes('--delivery-only')); + assert.ok(args.includes('--managed-inbox-root')); + assert.ok(args.includes('--message-stdin')); + assert.ok(!args.includes(notice)); + assert.ok(config.input.includes(`[HANDOVER:${nonce}]`)); + assert.ok(config.input.endsWith(notice)); + return { stdout: JSON.stringify(response) }; + }); + assert.equal(called, 1); + assert.equal(queued.status, 'queued-unverified'); + assert.equal(queued.session, options.session); + assert.match(queued.noticeSha256, /^[a-f0-9]{64}$/); +}); + +test('a held, mismatched or failed enqueue is never declared delivered', async () => { + for (const value of [{ ...response, held: true }, { ...response, correlationId: 'other' }, { ...response, status: 'delivered' }, null]) { + await assert.rejects(queueLocalFinalNotice(options, async () => ({ stdout: JSON.stringify(value) })), /unconfirmed/); + } + await assert.rejects(queueLocalFinalNotice(options, async () => { throw new Error('fixture'); }), /uncertain; do not resend/); + await assert.rejects(queueLocalFinalNotice({ ...options, session: 'claude:broken' }, async () => { throw new Error('should not run'); }), /invalid/); +}); + +test('queue is followed by separately observed Claude transcript evidence', async t => { + const root = await mkdtemp(join(tmpdir(), 'notice-route-')); + t.after(() => rm(root, { recursive: true, force: true })); + const project = join(root, 'project'); await mkdir(project); + const records = [ + { type: 'user', sessionId: id, message: { content: `[HANDOVER:${nonce}] synthetic request` } }, + { type: 'assistant', sessionId: id, message: { id: 'response-1', stop_reason: 'end_turn', content: [{ type: 'text', text: notice }] } } + ]; + await writeFile(join(project, `${id}.jsonl`), records.map(item => JSON.stringify(item)).join('\n') + '\n', { mode: 0o600 }); + const queue = await queueLocalFinalNotice(options, async () => ({ stdout: JSON.stringify(response) })); + const proof = await observeLocalFinalNotice({ ...options, transcriptRoot: root }); + assert.equal(proof.session, queue.session); + assert.equal(proof.messageSha256, queue.noticeSha256); + assert.equal(proof.nonce, queue.nonce); +}); + +test('reserved delivery binds session, successor and exact content before native call', async () => { + const { createHash } = await import('node:crypto'); + const reservation = { status: 'requested', session: options.session, id: nonce, successor: `codex:${id}`, noticeSha256: createHash('sha256').update(notice).digest('hex') }; + const args = { reservation, target: options.target, label: options.label, prefix: options.prefix, managedInboxRoot: options.managedInboxRoot }; + let calls = 0; + const run = async () => { calls++; return { stdout: JSON.stringify(response) }; }; + assert.equal((await queueReservedFinalNotice(args, run)).status, 'queued-unverified'); + await assert.rejects(queueReservedFinalNotice({ ...args, label: 'different' }, run), /does not match/); + await assert.rejects(queueReservedFinalNotice({ ...args, reservation: { ...reservation, successor: 'codex:other' } }, run), /does not match/); + assert.equal(calls, 1); +}); diff --git a/packages/tmux-bridge/test/handover-notice.test.mjs b/packages/tmux-bridge/test/handover-notice.test.mjs new file mode 100644 index 00000000..6578b046 --- /dev/null +++ b/packages/tmux-bridge/test/handover-notice.test.mjs @@ -0,0 +1,23 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { successorLink, formatFinalNotice, matchesFinalNotice } from '../bin/handover-notice.mjs'; + +test('successor links preserve same-project anchors, cross-project links and Codex threads', () => { + assert.equal(successorLink({ kind: 'cloud', sourceProject: 'chan_a', targetProject: 'chan_a', thread: 'cmsg_abc' }), '#cmsg_abc'); + assert.equal(successorLink({ kind: 'cloud', sourceProject: 'chan_a', targetProject: 'chan_b', thread: 'cmsg_abc' }), 'https://claude.ai/code/project/chan_b?thread=cmsg_abc'); + assert.equal(successorLink({ kind: 'codex', id: '22222222-2222-4222-8222-222222222222' }), 'codex://threads/22222222-2222-4222-8222-222222222222'); + for (const target of [{ kind: 'codex', id: 'short' }, { kind: 'cloud', sourceProject: 'a', targetProject: 'b?evil', thread: 'cmsg_abc' }, { kind: 'cloud', sourceProject: 'a', targetProject: 'a', thread: 'wrong' }]) assert.throws(() => successorLink(target)); +}); +test('notice text escapes labels and rejects injected lines', () => { + const target = { kind: 'cloud', sourceProject: 'a', targetProject: 'a', thread: 'cmsg_abc' }; + assert.equal(formatFinalNotice({ target, label: 'Next [session]', prefix: 'Continue:' }), 'Continue: [Next \\[session\\]](#cmsg_abc)'); + assert.throws(() => formatFinalNotice({ target, label: 'next\nextra', prefix: 'Continue:' })); +}); +test('a notice must be the observed final assistant message in the original session', () => { + const expected = { session: 'codex:old', message: 'Continue here.' }; + const observation = { complete: true, session: expected.session, messages: [{ role: 'assistant', text: expected.message }] }; + assert.equal(matchesFinalNotice(observation, expected), true); + assert.equal(matchesFinalNotice({ ...observation, complete: false }, expected), false); + assert.equal(matchesFinalNotice({ ...observation, session: 'codex:other' }, expected), false); + assert.equal(matchesFinalNotice({ ...observation, messages: [...observation.messages, { role: 'user', text: 'later' }] }, expected), false); +}); diff --git a/packages/tmux-bridge/test/handover-state-proof.test.mjs b/packages/tmux-bridge/test/handover-state-proof.test.mjs new file mode 100644 index 00000000..2ac2021c --- /dev/null +++ b/packages/tmux-bridge/test/handover-state-proof.test.mjs @@ -0,0 +1,98 @@ +import assert from 'node:assert/strict'; +import { createHash } from 'node:crypto'; +import { chmod, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import test from 'node:test'; +import { prepareState, requestStateProof, verifyStateResponse, revalidateStateProof } from '../bin/handover-state-proof.mjs'; +import { beginHandover, completeStatePreparation, createChannel, enqueue, reserveStatePreparation } from '../bin/channel-state.mjs'; + +test('preparation reserves before transport, retains a lost response, and binds concurrent queue changes', async () => { + let channel = beginHandover(createChannel('example', 'codex:old')); + const proof = { schema: 'agent-mesh.handover-state.v1', session: 'codex:old', nonce: 'handover-1', filename: 'state.yaml', sha256: 'a'.repeat(64), bytes: 42 }; + let sends = 0; + const reserve = () => { channel = reserveStatePreparation(channel, 'handover-1'); return { statePreparation: channel.statePreparation }; }; + const complete = value => { channel = completeStatePreparation(channel, value); return channel; }; + await assert.rejects(prepareState({ reserve, request: async () => { sends++; throw new Error('lost response'); }, complete }), /lost response/); + assert.equal(channel.statePreparation.status, 'requested'); + await assert.rejects(prepareState({ reserve, request: async () => { sends++; return proof; }, complete }), /unresolved/); + assert.equal(sends, 1); + channel = beginHandover(createChannel('example', 'codex:old')); + const result = await prepareState({ reserve, request: async pending => { assert.equal(pending.id, proof.nonce); channel = enqueue(channel, 'one', 'fixture'); return proof; }, complete }); + assert.equal(result.statePreparation.status, 'verified'); + assert.equal(result.queue[0].state, 'pending'); +}); + +test('state proof binds correlated response to private file bytes', async (t) => { + const root = await mkdtemp(join(tmpdir(), 'state-proof-')); + t.after(() => rm(root, { recursive: true, force: true })); + const session = 'codex:22222222-2222-4222-8222-222222222222', channel = '#example', filename = 'state.yaml', nonce = 'attempt-1'; + const content = `schema: agent-mesh.restart.v1\nsession: ${session}\nchannel: '#example'\nharness: codex\nworking_directory: /workspace\nskills: []\ntriggers: []\ngoal: null\nrole_profile:\n schema: agent-mesh.role-profile.v1\n role: operator\n permissions: []\n mcp: []\n plugins: []\n`; + await writeFile(join(root, filename), content, { mode: 0o600 }); + const response = { schema: 'agent-mesh.handover-state.v1', session, nonce, filename, sha256: createHash('sha256').update(content).digest('hex') }; + const verify = (overrides = {}) => verifyStateResponse({ session, channel, nonce, filename, root, response: JSON.stringify(response), ...overrides }); + assert.equal((await verify()).bytes, Buffer.byteLength(content)); + const prepared = { status: 'verified', session, generation: 1, id: nonce, filename, sha256: response.sha256, bytes: Buffer.byteLength(content) }; + const revalidate = (overrides = {}) => revalidateStateProof({ root, channel, session, generation: 1, statePreparation: prepared, ...overrides }); + assert.equal((await revalidate()).sha256, response.sha256); + await assert.rejects(revalidate({ generation: 2 }), /receipt mismatch/); + await assert.rejects(revalidate({ statePreparation: { ...prepared, bytes: prepared.bytes + 1 } }), /size mismatch/); + await writeFile(join(root, filename), content.replace('operator', 'operatOr'), { mode: 0o600 }); + await assert.rejects(revalidate(), /digest mismatch/); + await writeFile(join(root, filename), content, { mode: 0o600 }); + await assert.rejects(verify({ channel: '#other' }), /channel mismatch/); + await assert.rejects(verify({ nonce: 'other' }), /binding/); + const malformed = content + 'harness: other\n'; + await writeFile(join(root, filename), malformed, { mode: 0o600 }); + const malformedResponse = JSON.stringify({ ...response, sha256: createHash('sha256').update(malformed).digest('hex') }); + await assert.rejects(verify({ response: malformedResponse }), /restart YAML/); + await writeFile(join(root, filename), 'changed', { mode: 0o600 }); + await assert.rejects(verify(), /digest/); + await chmod(join(root, filename), 0o644); + await assert.rejects(verify(), /invalid state file/); + await symlink(filename, join(root, 'alias.yaml')); + await assert.rejects(verify({ filename: 'alias.yaml', response: JSON.stringify({ ...response, filename: 'alias.yaml' }) })); +}); + +test('native request binds response to its own correlation without resuming', async (t) => { + const root = await mkdtemp(join(tmpdir(), 'state-native-')); + t.after(() => rm(root, { recursive: true, force: true })); + const session = 'codex:22222222-2222-4222-8222-222222222222', filename = 'state.yaml'; + const fake = async (binary, argv, options) => { + assert.equal(binary, process.execPath); + assert.ok(argv.includes('--no-resume')); + assert.ok(argv.includes('--message-stdin')); + assert.ok(!argv.some(value => value.includes(root))); + assert.ok(options.input.includes(join(root, filename))); + const nonce = argv[argv.indexOf('--correlation-id') + 1]; + const content = `schema: agent-mesh.restart.v1\nsession: ${session}\nchannel: '#example'\nharness: codex\nworking_directory: /workspace\nskills: []\ntriggers: []\ngoal: null\nrole_profile:\n schema: agent-mesh.role-profile.v1\n role: operator\n permissions: []\n mcp: []\n plugins: []\n`; + await writeFile(join(root, filename), content, { mode: 0o600 }); + return { stdout: JSON.stringify({ schema: 'agent-mesh.handover-state.v1', session, nonce, filename, sha256: createHash('sha256').update(content).digest('hex') }) }; + }; + const proof = await requestStateProof({ session, channel: '#example', root, filename }, fake); + assert.equal(proof.session, session); + assert.ok(proof.nonce.startsWith('handover-')); + assert.equal((await requestStateProof({ session, channel: '#example', root, filename, nonce: 'handover-fixed' }, fake)).nonce, 'handover-fixed'); + await assert.rejects(requestStateProof({ session, channel: '#example', root, filename, nonce: 'unsafe nonce' }, fake), /nonce/); + await assert.rejects(requestStateProof({ session, channel: '#example', root, filename }, async () => ({ stdout: JSON.stringify({ status: 'held' }) })), /binding/); + await assert.rejects(requestStateProof({ session, channel: '#example', root, filename }, async () => { throw new Error('timeout'); }), /timeout/); +}); + +test('state verification rejects path replacement during YAML decoding', async t => { + const root = await mkdtemp(join(tmpdir(), 'state-replacement-')); + t.after(() => rm(root, { recursive: true, force: true })); + const session = 'codex:22222222-2222-4222-8222-222222222222', channel = '#example', filename = 'state.yaml', nonce = 'attempt-1'; + const content = `schema: agent-mesh.restart.v1\nsession: ${session}\nchannel: '#example'\nharness: codex\nworking_directory: /workspace\nskills: []\ntriggers: []\ngoal: null\nrole_profile:\n schema: agent-mesh.role-profile.v1\n role: operator\n permissions: []\n mcp: []\n plugins: []\n`; + const state = join(root, filename), shim = join(root, 'decoder-shim'); + await writeFile(state, content, { mode: 0o600 }); + await writeFile(shim, '#!/bin/sh\npython3 "$@"\ncp -- "$TEST_STATE_FILE" "$TEST_STATE_FILE.swap"\nmv -- "$TEST_STATE_FILE.swap" "$TEST_STATE_FILE"\n', { mode: 0o700 }); + const oldPython = process.env.PYTHON, oldState = process.env.TEST_STATE_FILE; + process.env.PYTHON = shim; process.env.TEST_STATE_FILE = state; + try { + const response = JSON.stringify({ schema: 'agent-mesh.handover-state.v1', session, nonce, filename, sha256: createHash('sha256').update(content).digest('hex') }); + await assert.rejects(verifyStateResponse({ root, channel, session, nonce, filename, response }), /state file changed/); + } finally { + if (oldPython === undefined) delete process.env.PYTHON; else process.env.PYTHON = oldPython; + if (oldState === undefined) delete process.env.TEST_STATE_FILE; else process.env.TEST_STATE_FILE = oldState; + } +}); diff --git a/packages/tmux-bridge/test/isolated-pid-namespace.test.py b/packages/tmux-bridge/test/isolated-pid-namespace.test.py new file mode 100644 index 00000000..690f8f86 --- /dev/null +++ b/packages/tmux-bridge/test/isolated-pid-namespace.test.py @@ -0,0 +1,112 @@ +import importlib.util +import os +from pathlib import Path +import subprocess +import sys +import tempfile +import time +import unittest +from unittest.mock import patch + +BIN = Path(__file__).resolve().parents[1] / 'bin' +spec = importlib.util.spec_from_file_location('isolated_namespace', BIN / 'isolated-pid-namespace.py') +module = importlib.util.module_from_spec(spec) +spec.loader.exec_module(module) + + +def supported(): + if not hasattr(os, 'pidfd_open') or not Path('/usr/bin/bwrap').exists(): + return False + result = subprocess.run(['/usr/bin/bwrap', '--ro-bind', '/', '/', '--proc', '/proc', '--dev', '/dev', + '--unshare-pid', '--unshare-net', '--', '/usr/bin/true'], + stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=5) + return result.returncode == 0 + + +@unittest.skipUnless(supported(), 'isolated PID namespaces or pidfd unavailable') +class IsolatedPidNamespaceTest(unittest.TestCase): + def wait_for(self, path): + for _ in range(200): + if path.exists(): + return + time.sleep(.01) + self.fail('fixture did not start') + + def test_stop_before_release_does_not_execute_command(self): + with tempfile.TemporaryDirectory() as directory: + marker = Path(directory) / 'ran' + code = 'import pathlib,sys;pathlib.Path(sys.argv[1]).write_text("ran")' + lease = module.IsolatedNamespace.prepare(directory, [sys.executable, '-c', code, str(marker)]) + self.assertFalse(marker.exists()) + receipt = lease.stop() + self.assertEqual(receipt['status'], 'init-exited') + self.assertEqual(receipt['descendants'], 'unverified') + self.assertEqual(receipt['remoteEffects'], 'unverified') + self.assertFalse(marker.exists()) + with self.assertRaises(RuntimeError): + lease.release() + + def test_release_and_stop_own_namespace_with_escaped_fixture(self): + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + marker, child_started, late = root / 'ran', root / 'child-started', root / 'late' + escaped = root / 'escaped.py' + escaped.write_text('import os,pathlib,signal,sys,time\nos.setsid()\nsignal.signal(signal.SIGTERM,signal.SIG_IGN)\npathlib.Path(sys.argv[1]).write_text("started")\ntime.sleep(2)\npathlib.Path(sys.argv[2]).write_text("late")\n') + payload = root / 'payload.py' + payload.write_text('import pathlib,subprocess,sys,time\nsubprocess.Popen([sys.executable,sys.argv[1],sys.argv[3],sys.argv[4]])\npathlib.Path(sys.argv[2]).write_text("ran")\nwhile True: time.sleep(1)\n') + lease = module.IsolatedNamespace.prepare(directory, [sys.executable, str(payload), str(escaped), str(marker), str(child_started), str(late)]) + try: + self.assertFalse(marker.exists()) + lease.release() + self.wait_for(marker) + self.wait_for(child_started) + with self.assertRaises(RuntimeError): + lease.release() + self.assertEqual(lease.stop()['status'], 'init-exited') + time.sleep(2.2) + self.assertFalse(late.exists()) + finally: + if not lease._stopped: + lease.stop() + + def test_supervisor_death_before_and_after_release(self): + for phase in ('before', 'after'): + with self.subTest(phase=phase), tempfile.TemporaryDirectory() as directory: + root = Path(directory) + escaped, payload, supervisor = root / 'escaped.py', root / 'payload.py', root / 'supervisor.py' + escaped.write_text('import os,pathlib,signal,sys,time\nos.setsid()\nsignal.signal(signal.SIGTERM,signal.SIG_IGN)\npathlib.Path(sys.argv[1]).write_text("started")\ntime.sleep(2)\npathlib.Path(sys.argv[2]).write_text("late")\n') + payload.write_text('import subprocess,sys,time\nsubprocess.Popen([sys.executable,sys.argv[1],sys.argv[2],sys.argv[3]])\nwhile True:time.sleep(1)\n') + supervisor.write_text('import importlib.util,os,pathlib,sys,time\nspec=importlib.util.spec_from_file_location("owned",sys.argv[1]);m=importlib.util.module_from_spec(spec);spec.loader.exec_module(m)\nroot=pathlib.Path(sys.argv[2]);lease=m.IsolatedNamespace.prepare(str(root),[sys.executable,str(root/"payload.py"),str(root/"escaped.py"),str(root/"started"),str(root/"late")])\nif sys.argv[3]=="before":os._exit(0)\nlease.release()\nfor _ in range(500):\n if (root/"started").exists():os._exit(0)\n time.sleep(.01)\nos._exit(2)\n') + result = subprocess.run([sys.executable, '-B', str(supervisor), str(BIN / 'isolated-pid-namespace.py'), directory, phase], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=12) + self.assertEqual(result.returncode, 0) + time.sleep(2.4) + self.assertEqual((root / 'started').exists(), phase == 'after') + self.assertFalse((root / 'late').exists()) + listing = subprocess.run(['ps', '-eo', 'args'], capture_output=True, text=True, check=True).stdout + self.assertNotIn(directory, listing) + + def test_unverified_identity_closes_gate_without_running_fixture(self): + with tempfile.TemporaryDirectory() as directory: + marker = Path(directory) / 'ran' + code = 'import pathlib,sys;pathlib.Path(sys.argv[1]).write_text("ran")' + with patch.object(module, '_identity', return_value=(-1, -1, '0', ['1'], -1)): + with self.assertRaisesRegex(RuntimeError, 'cleanup may be unverified'): + module.IsolatedNamespace.prepare(directory, [sys.executable, '-c', code, str(marker)]) + self.assertFalse(marker.exists()) + listing = subprocess.run(['ps', '-eo', 'args'], capture_output=True, text=True, check=True).stdout + self.assertNotIn(directory, listing) + + def test_invalid_workspace_or_command_does_not_launch(self): + with tempfile.TemporaryDirectory() as directory: + with self.assertRaises(ValueError): + module.IsolatedNamespace.prepare(directory, ['relative-command']) + os.chmod(directory, 0o755) + try: + with self.assertRaises(ValueError): + module.IsolatedNamespace.prepare(directory, ['/usr/bin/true']) + finally: + os.chmod(directory, 0o700) + + +if __name__ == '__main__': + unittest.main() diff --git a/packages/tmux-bridge/test/isolated-role-rollback.test.py b/packages/tmux-bridge/test/isolated-role-rollback.test.py new file mode 100644 index 00000000..d58f3f89 --- /dev/null +++ b/packages/tmux-bridge/test/isolated-role-rollback.test.py @@ -0,0 +1,166 @@ +import importlib.util +import hashlib +import json +from pathlib import Path +import threading +import tempfile +import os +import subprocess +import sys +from unittest.mock import patch +import unittest + + +BIN = Path(__file__).resolve().parents[1] / 'bin' +spec = importlib.util.spec_from_file_location('isolated_role_rollback', BIN / 'isolated-role-rollback.py') +module = importlib.util.module_from_spec(spec) +spec.loader.exec_module(module) +SESSION = 'codex:22222222-2222-4222-8222-222222222222' +ASSESSMENT = {'schema': 'agent-mesh.codex-role-start-assessment.v1', 'session': SESSION, + 'status': 'rollback-required', 'failures': ['unexpected-permission-request']} +STOP = {'schema': 'agent-mesh.isolated-namespace-stop.v1', 'status': 'init-exited', + 'descendants': 'unverified', 'remoteEffects': 'unverified'} + + +class IsolatedRoleRollbackTest(unittest.TestCase): + def setUp(self): + self.directory = tempfile.TemporaryDirectory(prefix='rollback-journal-test-') + self.addCleanup(self.directory.cleanup) + self.root = self.directory.name + + def test_incomplete_observation_keeps_handover_blocked_without_stop(self): + calls = [] + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True), self.root) + assessment = {**ASSESSMENT, 'status': 'observed-incomplete', 'failures': []} + self.assertEqual(coordinator.apply(assessment)['status'], 'blocked-incomplete') + self.assertEqual(calls, []) + + def test_wrong_session_or_invalid_assessment_never_stops(self): + with self.assertRaises(ValueError): + module.IsolatedRoleRollback(SESSION.upper(), lambda: STOP, self.root) + calls = [] + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True), self.root) + for assessment in ({**ASSESSMENT, 'session': 'codex:33333333-3333-4333-8333-333333333333'}, + {**ASSESSMENT, 'failures': []}, {**ASSESSMENT, 'status': 'ready'}): + with self.assertRaises(ValueError): + coordinator.apply(assessment) + self.assertEqual(calls, []) + + def test_unsafe_assessment_stops_once_and_preserves_uncertainty(self): + calls = [] + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, self.root) + first = coordinator.apply(ASSESSMENT) + self.assertEqual(first['status'], 'local-init-exited') + self.assertEqual(first['handover'], 'blocked') + self.assertEqual(first['namespaceStop']['descendants'], 'unverified') + first['namespaceStop']['status'] = 'altered' + self.assertEqual(coordinator.apply(ASSESSMENT)['namespaceStop']['status'], 'init-exited') + self.assertEqual(calls, [True]) + + def test_persisted_receipts_exclude_extra_callback_fields(self): + coordinator = module.IsolatedRoleRollback(SESSION, lambda: {**STOP, 'extra': 'private-fixture'}, self.root) + receipt = coordinator.apply(ASSESSMENT) + key = hashlib.sha256(SESSION.encode()).hexdigest() + intent = json.loads((Path(self.root) / f'stop-{key}.intent.json').read_text()) + saved = json.loads((Path(self.root) / f'stop-{key}.result.json').read_text()) + self.assertEqual(intent['session'], SESSION) + self.assertEqual(saved, receipt) + self.assertNotIn('private-fixture', json.dumps(saved)) + + def test_lost_or_invalid_stop_receipt_stays_uncertain_without_retry(self): + for index, stop in enumerate((lambda: (_ for _ in ()).throw(RuntimeError('lost')), lambda: {'status': 'ok'})): + root = Path(self.root) / str(index) + root.mkdir(mode=0o700) + calls = [] + def wrapped(): + calls.append(True) + return stop() + coordinator = module.IsolatedRoleRollback(SESSION, wrapped, str(root)) + self.assertEqual(coordinator.apply(ASSESSMENT)['status'], 'stop-uncertain') + self.assertEqual(coordinator.apply(ASSESSMENT)['status'], 'stop-uncertain') + self.assertEqual(calls, [True]) + + def test_concurrent_assessments_do_not_repeat_stop(self): + calls, receipts = [], [] + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, self.root) + threads = [threading.Thread(target=lambda: receipts.append(coordinator.apply(ASSESSMENT))) for _ in range(8)] + for thread in threads: + thread.start() + for thread in threads: + thread.join() + self.assertEqual(calls, [True]) + self.assertEqual([receipt['status'] for receipt in receipts], ['local-init-exited'] * 8) + + + def test_distinct_coordinators_share_a_single_durable_reservation(self): + calls, receipts = [], [] + coordinators = [module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, self.root) for _ in range(8)] + threads = [threading.Thread(target=lambda c=c: receipts.append(c.apply(ASSESSMENT))) for c in coordinators] + for thread in threads: + thread.start() + for thread in threads: + thread.join() + self.assertEqual(calls, [True]) + self.assertEqual(sum(item['status'] == 'local-init-exited' for item in receipts), 1) + self.assertTrue(all(item['handover'] == 'blocked' for item in receipts)) + + def test_process_death_after_reservation_blocks_retry(self): + path = str(BIN / 'isolated-role-rollback.py') + code = "import importlib.util,json,os,sys;spec=importlib.util.spec_from_file_location('r',sys.argv[1]);m=importlib.util.module_from_spec(spec);spec.loader.exec_module(m);c=m.IsolatedRoleRollback(sys.argv[2],lambda:os._exit(43),sys.argv[3]);c.apply(json.loads(sys.argv[4]))" + result = subprocess.run([sys.executable, '-B', '-c', code, path, SESSION, self.root, json.dumps(ASSESSMENT)], timeout=5) + self.assertEqual(result.returncode, 43) + calls = [] + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, self.root) + self.assertEqual(coordinator.apply(ASSESSMENT)['status'], 'stop-uncertain') + self.assertEqual(calls, []) + + def test_unwritable_or_invalid_journal_never_invokes_stop(self): + calls = [] + os.chmod(self.root, 0o755) + try: + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, self.root) + with self.assertRaises(ValueError): + coordinator.apply(ASSESSMENT) + finally: + os.chmod(self.root, 0o700) + self.assertEqual(calls, []) + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, self.root) + with patch.object(module, '_write_once', side_effect=OSError('intent unavailable')): + with self.assertRaises(OSError): + coordinator.apply(ASSESSMENT) + self.assertEqual(calls, []) + + def test_replaced_journal_root_blocks_before_stop(self): + root = Path(self.root) / 'journal' + root.mkdir(mode=0o700) + renamed = Path(self.root) / 'renamed' + original = module._write_once + calls = [] + def replace_after_reservation(directory_fd, name, value): + original(directory_fd, name, value) + root.rename(renamed) + root.mkdir(mode=0o700) + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, str(root)) + with patch.object(module, '_write_once', side_effect=replace_after_reservation): + with self.assertRaisesRegex(ValueError, 'root changed'): + coordinator.apply(ASSESSMENT) + self.assertEqual(calls, []) + self.assertEqual(len(list(renamed.glob('*.intent.json'))), 1) + + def test_lost_result_persistence_remains_uncertain_without_retry(self): + calls = [] + original = module._write_once + def write(directory_fd, name, value): + if name.endswith('.result.json'): + raise OSError('result unavailable') + return original(directory_fd, name, value) + coordinator = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, self.root) + with patch.object(module, '_write_once', side_effect=write): + self.assertEqual(coordinator.apply(ASSESSMENT)['status'], 'stop-uncertain') + restarted = module.IsolatedRoleRollback(SESSION, lambda: calls.append(True) or STOP, self.root) + self.assertEqual(restarted.apply(ASSESSMENT)['status'], 'stop-uncertain') + self.assertEqual(calls, [True]) + + +if __name__ == '__main__': + unittest.main() diff --git a/packages/tmux-bridge/test/mesh-graph.test.mjs b/packages/tmux-bridge/test/mesh-graph.test.mjs index 491e0e75..93e478f3 100644 --- a/packages/tmux-bridge/test/mesh-graph.test.mjs +++ b/packages/tmux-bridge/test/mesh-graph.test.mjs @@ -28,13 +28,13 @@ test("mesh-graph derives an inspectable graph from append-only events", async () const first = await run(state, [ "add", "--agent", "codex", "--tmux-target", "mesh-codex-main", "--cwd", "/workspace/mesh", "--role-profile", "developer", "--title", "Graph work", "--summary", "initial implementation", - "--refs", "management:MGT-0239,amf:record-id", "--json", + "--refs", "ledger:item-1,amf:record-id", "--json", ]); assert.equal(first.code, 0, first.stderr); const firstNode = JSON.parse(first.stdout).node; assert.match(firstNode.id, /^node-[0-9a-f-]{36}$/); assert.equal(firstNode.runtimeUuid, null); - assert.deepEqual(firstNode.refs, ["management:MGT-0239", "amf:record-id"]); + assert.deepEqual(firstNode.refs, ["ledger:item-1", "amf:record-id"]); const reconciled = await run(state, [ "add", "--tmux-target", "mesh-codex-main", "--runtime-uuid", "11111111-1111-4111-8111-111111111111", "--json", @@ -67,7 +67,7 @@ test("mesh-graph derives an inspectable graph from append-only events", async () assert.equal(graph.nodes.length, 2); assert.equal(graph.edges.length, 1); assert.equal(graph.nodes.find((node) => node.id === firstNode.id).runtimeUuid, "11111111-1111-4111-8111-111111111111"); - assert.deepEqual(graph.nodes.find((node) => node.id === firstNode.id).refs, ["management:MGT-0239", "amf:record-id"]); + assert.deepEqual(graph.nodes.find((node) => node.id === firstNode.id).refs, ["ledger:item-1", "amf:record-id"]); assert.equal(graph.nodes.find((node) => node.id === secondNode.id).status, "closed"); const projection = JSON.parse(await readFile(join(state, "graph.json"), "utf8")); diff --git a/packages/tmux-bridge/test/namespace-exec-gate.test.py b/packages/tmux-bridge/test/namespace-exec-gate.test.py new file mode 100644 index 00000000..85f85cad --- /dev/null +++ b/packages/tmux-bridge/test/namespace-exec-gate.test.py @@ -0,0 +1,66 @@ +import os +from pathlib import Path +import subprocess +import sys +import tempfile +import time +import unittest + +GATE = Path(__file__).resolve().parents[1] / 'bin' / 'namespace-exec-gate.py' + + +class NamespaceExecGateTest(unittest.TestCase): + def launch(self, fifo, marker): + code = 'import pathlib,sys;pathlib.Path(sys.argv[1]).write_text("executed")' + return subprocess.Popen([sys.executable, '-B', str(GATE), str(fifo), '--', sys.executable, '-c', code, str(marker)], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL) + + def writer(self, fifo): + for _ in range(200): + try: + return os.open(fifo, os.O_WRONLY | os.O_NONBLOCK) + except OSError as exc: + if exc.errno != 6: + raise + time.sleep(.01) + self.fail('fixture reader unavailable') + + def test_eof_and_wrong_permit_never_execute(self): + for permit in (b'', b'NO\n', b'GO\nX'): + with self.subTest(permit=permit), tempfile.TemporaryDirectory() as root: + fifo, marker = Path(root) / 'gate', Path(root) / 'ran' + os.mkfifo(fifo, 0o600) + process = self.launch(fifo, marker) + fd = self.writer(fifo) + if permit: + os.write(fd, permit) + os.close(fd) + self.assertEqual(process.wait(timeout=5), 125) + self.assertFalse(marker.exists()) + + def test_explicit_permit_executes_only_fixture(self): + with tempfile.TemporaryDirectory() as root: + fifo, marker = Path(root) / 'gate', Path(root) / 'ran' + os.mkfifo(fifo, 0o600) + process = self.launch(fifo, marker) + fd = self.writer(fifo) + os.write(fd, b'GO\n'); os.close(fd) + self.assertEqual(process.wait(timeout=5), 0) + self.assertTrue(marker.exists()) + + def test_regular_file_symlink_and_public_directory_are_rejected(self): + with tempfile.TemporaryDirectory() as root: + root = Path(root) + real, link, marker = root / 'real', root / 'link', root / 'ran' + real.write_text('GO\n') + self.assertEqual(self.launch(real, marker).wait(timeout=5), 125) + link.symlink_to(real) + self.assertEqual(self.launch(link, marker).wait(timeout=5), 125) + os.mkfifo(root / 'fifo', 0o600) + os.chmod(root, 0o755) + self.assertEqual(self.launch(root / 'fifo', marker).wait(timeout=5), 125) + os.chmod(root, 0o700) + self.assertFalse(marker.exists()) + + +if __name__ == '__main__': + unittest.main() diff --git a/packages/tmux-bridge/test/native-private-queue.test.mjs b/packages/tmux-bridge/test/native-private-queue.test.mjs new file mode 100644 index 00000000..273547c2 --- /dev/null +++ b/packages/tmux-bridge/test/native-private-queue.test.mjs @@ -0,0 +1,52 @@ +import assert from 'node:assert/strict'; +import { spawn } from 'node:child_process'; +import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import test from 'node:test'; +import { createAppServer } from './fixtures/fake-app-server.mjs'; +const bin = fileURLToPath(new URL('../bin/agent-native-call.mjs', import.meta.url)); +const session = '33333333-3333-4333-8333-333333333333'; + +for (const badReceipt of [false, true]) { + test(`private native queue ${badReceipt ? 'rejects mismatched' : 'accepts bound'} receipt`, async (t) => { + const root = await mkdtemp(join(tmpdir(), 'private-native-')); + t.after(() => rm(root, { recursive: true, force: true })); + const sessions = join(root, 'sessions'); await mkdir(sessions); + await writeFile(join(sessions, `rollout-${session}.jsonl`), JSON.stringify({ type: 'session_meta', payload: { id: session } }) + '\n'); + const seen = []; + const server = createAppServer((message, peer) => { + if (!message.id) return; + if (message.method === 'thread/queue/add') { + seen.push(message); + peer.send({ id: message.id, result: { queuedSubmission: { id: 'queue-1', clientUserMessageId: badReceipt ? 'wrong' : message.params.clientUserMessageId, input: message.params.input } } }); + } else peer.send({ id: message.id, result: {} }); + }); + const socket = join(root, 'server.sock'); + await new Promise(resolve => server.listen(socket, resolve)); + t.after(() => new Promise(resolve => server.close(resolve))); + const env = { ...process.env, CODEX_SESSION_ROOT: sessions, CODEX_REMOTE_SOCK: socket, CODEX_NO_REMOTE: '', CODEX_BIN: '/not-a-real-cli', MESH_COMMS_STATE: join(root, 'comms'), AGENT_FALLBACK_STATE: join(root, 'fallback') }; + delete env.MESH_COMMS_REPLAY_FD; + const child = spawn(process.execPath, [bin, '--agent', 'codex', '--session', session, '--correlation-id', 'fixture-1', '--message-stdin', '--no-resume', '--delivery-only', '--timeout', '3'], { env, stdio: ['pipe', 'pipe', 'pipe'] }); + let stdout = '', stderr = ''; + child.stdout.on('data', data => stdout += data); child.stderr.on('data', data => stderr += data); + child.stdin.end('private fixture'); + const code = await new Promise(resolve => child.on('close', resolve)); + assert.equal(seen.length, 1); + assert.equal(seen[0].params.threadId, session); + assert.equal(seen[0].params.input[0].text, 'private fixture'); + assert.equal(seen[0].params.clientUserMessageId, 'fixture-1'); + assert.ok(!stderr.includes('private fixture')); + if (badReceipt) { assert.notEqual(code, 0); assert.match(stderr, /uncertain/); } + else { + assert.equal(code, 0, stderr); + const receipt = JSON.parse(stdout); + assert.equal(receipt.status, 'queued'); + assert.equal(receipt.nativeQueueId, 'queue-1'); + assert.equal(receipt.sessionId, session); + assert.equal(receipt.correlationId, 'fixture-1'); + assert.ok(!stdout.includes('private fixture')); + } + }); +} diff --git a/packages/tmux-bridge/test/native-stdin.test.mjs b/packages/tmux-bridge/test/native-stdin.test.mjs new file mode 100644 index 00000000..b71e2f09 --- /dev/null +++ b/packages/tmux-bridge/test/native-stdin.test.mjs @@ -0,0 +1,16 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { fileURLToPath } from 'node:url'; +import test from 'node:test'; +const bin = fileURLToPath(new URL('../bin/agent-native-call.mjs', import.meta.url)); + +test('native transport parses bounded stdin before rejecting unsupported agent', () => { + const args = [bin, '--agent', 'fixture', '--session', 'fixture', '--correlation-id', 'fixture', '--message-stdin']; + const valid = spawnSync(process.execPath, args, { input: 'private fixture', encoding: 'utf8' }); + assert.notEqual(valid.status, 0); + assert.match(valid.stderr, /not implemented/); + assert.ok(!valid.stderr.includes('private fixture')); + const oversized = spawnSync(process.execPath, args, { input: 'x'.repeat(65537), encoding: 'utf8' }); + assert.notEqual(oversized.status, 0); + assert.match(oversized.stderr, /stdin message too large/); +}); diff --git a/packages/tmux-bridge/test/plexus-channel-store.test.mjs b/packages/tmux-bridge/test/plexus-channel-store.test.mjs new file mode 100644 index 00000000..770f6435 --- /dev/null +++ b/packages/tmux-bridge/test/plexus-channel-store.test.mjs @@ -0,0 +1,235 @@ +import assert from 'node:assert/strict'; +import { execFile } from 'node:child_process'; +import { appendFile, chmod, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { promisify } from 'node:util'; +import test from 'node:test'; +const exec = promisify(execFile); +const bin = fileURLToPath(new URL('../bin/mesh-graph.mjs', import.meta.url)); + +test('failed native state request stays reserved across replay and is never resent', async (t) => { + const root = await mkdtemp(join(tmpdir(), 'channel-prepare-')); + t.after(() => rm(root, { recursive: true, force: true })); + const state = join(root, 'graph'), files = join(root, 'files'), sessions = join(root, 'sessions'); + await mkdir(files, { mode: 0o700 }); await mkdir(sessions, { mode: 0o700 }); + const env = { ...process.env, XDG_STATE_HOME: join(root, 'xdg'), XDG_CONFIG_HOME: join(root, 'config'), CODEX_SESSION_ROOT: sessions, MESH_COMMS_STATE: join(root, 'comms'), MESH_GRAPH_STATE: state, AGENT_FALLBACK_STATE: join(root, 'fallback') }; + delete env.MESH_COMMS_REPLAY_FD; + const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args], { env, timeout: 30000 })).stdout); + const uuid = '22222222-2222-4222-8222-222222222222'; + await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json'); + await call('migrate', '--apply', '--json'); + await call('channel', 'create', '--name', 'example', '--session', `codex:${uuid}`); + await call('channel', 'begin-handover', '--name', 'example'); + await call('channel', 'enqueue', '--name', 'example', '--id', 'one', '--input', 'fixture'); + const args = ['channel', 'prepare-state', '--name', 'example', '--state-root', files, '--filename', 'state.yaml']; + await assert.rejects(call(...args)); + await rm(join(state, 'checkpoint.json'), { force: true }); + const first = (await call('channel', 'get', '--name', 'example')).channel; + assert.equal(first.statePreparation.status, 'requested'); + assert.equal(first.queue[0].state, 'pending'); + await assert.rejects(call(...args), /unresolved/); + const second = (await call('channel', 'get', '--name', 'example')).channel; + assert.deepEqual(second.statePreparation, first.statePreparation); + assert.equal(second.queue[0].state, 'pending'); +}); + +test('channel operations reject a graph with non-private persisted files', async (t) => { + const state = await mkdtemp(join(tmpdir(), 'channel-permissions-')); + t.after(() => rm(state, { recursive: true, force: true })); + const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args])).stdout); + const uuid = '22222222-2222-4222-8222-222222222222'; + await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json'); + await call('migrate', '--apply', '--json'); + await call('channel', 'create', '--name', 'example', '--session', `codex:${uuid}`); + await chmod(join(state, 'events.jsonl'), 0o644); + await assert.rejects(call('channel', 'enqueue', '--name', 'example', '--id', 'one', '--input', 'private'), /must be private/); + await assert.rejects(call('channel', 'get', '--name', 'example'), /must be private/); + await chmod(join(state, 'events.jsonl'), 0o600); + assert.equal((await call('channel', 'get', '--name', 'example')).channel.queue.length, 0); +}); + +test('channel and queued messages survive concurrent writers, replay and compaction', async (t) => { + const state = await mkdtemp(join(tmpdir(), 'channel-store-')); + t.after(() => rm(state, { recursive: true, force: true })); + const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args])).stdout); + const uuid = '22222222-2222-4222-8222-222222222222'; + await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json'); + await call('migrate', '--apply', '--json'); + await call('channel', 'create', '--name', '#example', '--session', `codex:${uuid}`); + await call('channel', 'begin-handover', '--name', '#example'); + await Promise.all(['one', 'two'].map(id => call('channel', 'enqueue', '--name', '#example', '--id', id, '--input', id))); + assert.equal((await call('channel', 'enqueue', '--name', '#example', '--id', 'one', '--input', 'one')).duplicate, true); + await assert.rejects(call('channel', 'enqueue', '--name', '#example', '--id', 'one', '--input', 'changed'), /conflict/); + await rm(join(state, 'checkpoint.json')); + let channel = (await call('channel', 'get', '--name', '#example')).channel; + assert.equal(channel.phase, 'handover'); + assert.deepEqual(channel.queue.map(row => row.id).sort(), ['one', 'two']); + await call('compact', '--all-history', '--apply', '--json'); + await rm(join(state, 'checkpoint.json'), { force: true }); + channel = (await call('channel', 'get', '--name', '#example')).channel; + assert.deepEqual(channel.queue.map(row => row.id).sort(), ['one', 'two']); +}); + +test('cutover fails closed until old-session state authorship is verified', async (t) => { + const state = await mkdtemp(join(tmpdir(), 'channel-cutover-')); + t.after(() => rm(state, { recursive: true, force: true })); + const writer = join(state, 'writer-fixture.mjs'); + await writeFile(writer, `console.log(JSON.stringify({agent:'codex',sessionId:'33333333-3333-4333-8333-333333333333',writers:[]}))`); + const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args], {env: {...process.env, MESH_PLEXUS_WRITER_STATUS: writer}})).stdout); + const one = '22222222-2222-4222-8222-222222222222', two = '33333333-3333-4333-8333-333333333333'; + for (const uuid of [one, two]) await call('add', '--agent', 'codex', '--tmux-target', `test-${uuid}`, '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json'); + await call('migrate', '--apply', '--json'); + await call('channel', 'create', '--name', 'example', '--session', `codex:${one}`); + await call('channel', 'begin-handover', '--name', 'example'); + const target = `codex:${two}`; + await assert.rejects(call('channel', 'finish-handover', '--name', 'example', '--to', target), /fresh verified link/); + const graph = await call('show', '--json'); + const node = graph.nodes.find(row => row.runtimeUuid === two); + const checkedAt = new Date().toISOString(); + node.sessionLink = { status: 'ok', resolvedSession: target, link: target, source: 'codex-threads', checkedAt, lastKnown: false }; + const fixture = { schema: 'agent-mesh.session-graph-event.v1', id: 'fixture-proof', type: 'node.upserted', at: checkedAt, node, seq: graph.lastSeq + 1, host: 'local' }; + await appendFile(join(state, 'events.jsonl'), `${JSON.stringify(fixture)}\n`); + await assert.rejects(call('channel', 'finish-handover', '--name', 'example', '--to', target), /one verified writer/); + await writeFile(writer, `console.log(JSON.stringify({agent:'codex',sessionId:'33333333-3333-4333-8333-333333333333',writers:[{pid:123,kind:'codex'}]}))`); + await assert.rejects(call('channel', 'finish-handover', '--name', 'example', '--to', target), /old-session state verification unavailable/); + await rm(join(state, 'checkpoint.json')); + assert.equal((await call('channel', 'get', '--name', 'example')).channel.session, `codex:${one}`); + assert.equal((await call('channel', 'get', '--name', 'example')).channel.phase, 'handover'); +}); + +test('delivery reservation and matching receipt survive graph replay', async (t) => { + const state = await mkdtemp(join(tmpdir(), 'channel-delivery-')); + t.after(() => rm(state, { recursive: true, force: true })); + const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args])).stdout); + const uuid = '22222222-2222-4222-8222-222222222222', session = `codex:${uuid}`; + await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', uuid, '--json'); + await call('migrate', '--apply', '--json'); + await call('channel', 'create', '--name', 'example', '--session', session); + await call('channel', 'enqueue', '--name', 'example', '--id', 'one', '--input', 'payload'); + await assert.rejects(call('channel', 'begin-delivery', '--name', 'example', '--id', 'one', '--session', 'codex:other'), /recipient changed/); + await assert.rejects(call('channel', 'begin-delivery', '--name', 'example', '--id', 'one', '--session', session, '--generation', '2'), /generation changed/); + await assert.rejects(call('channel', 'begin-delivery', '--name', 'example', '--id', 'one', '--generation', '1.0'), /invalid channel generation/); + await assert.rejects(call('channel', 'begin-delivery', '--name', 'example', '--id', 'one', '--generation', '9007199254740992'), /generation changed/); + assert.equal((await call('channel', 'get', '--name', 'example')).channel.queue[0].state, 'pending'); + await call('channel', 'begin-delivery', '--name', 'example', '--id', 'one', '--session', session, '--generation', '1'); + await rm(join(state, 'checkpoint.json')); + assert.equal((await call('channel', 'get', '--name', 'example')).channel.queue[0].state, 'inflight'); + await assert.rejects(call('channel', 'acknowledge', '--name', 'example', '--id', 'one', '--input', JSON.stringify({ status: 'accepted', messageId: 'one', session: 'codex:wrong', generation: 1 })), /receipt/); + await call('channel', 'acknowledge', '--name', 'example', '--id', 'one', '--input', JSON.stringify({ status: 'accepted', messageId: 'one', session, generation: 1 })); + assert.equal((await call('channel', 'get', '--name', 'example')).channel.queue[0].state, 'accepted'); +}); + +test('predecessor notice after a synthetic draining transition persists across replay', async t => { + const state = await mkdtemp(join(tmpdir(), 'notice-reserve-')); + t.after(() => rm(state, { recursive: true, force: true })); + const writer = join(state, 'writer.mjs'), sessions = join(state, 'sessions'), oldId = '22222222-2222-4222-8222-222222222222', nextId = '33333333-3333-4333-8333-333333333333'; + await mkdir(sessions, { mode: 0o700 }); + await writeFile(writer, `console.log(JSON.stringify({agent:'codex',sessionId:'${nextId}',writers:[{pid:123,kind:'codex'}]}))`); + const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args], { env: { ...process.env, MESH_PLEXUS_WRITER_STATUS: writer, CODEX_SESSION_ROOT: sessions } })).stdout); + for (const id of [oldId, nextId]) await call('add', '--agent', 'codex', '--tmux-target', `test-${id}`, '--cwd', '/synthetic', '--runtime-uuid', id, '--json'); + await call('migrate', '--apply', '--json'); + await call('channel', 'create', '--name', 'example', '--session', `codex:${oldId}`); + await call('channel', 'begin-handover', '--name', 'example'); + const args = ['channel', 'reserve-notice', '--name', 'example', '--to', `codex:${nextId}`, '--input', JSON.stringify({ prefix: 'Sleeping.', label: 'Continue' })]; + await assert.rejects(call(...args), /fresh verified link/); + let graph = await call('show', '--json'); + const node = graph.nodes.find(row => row.runtimeUuid === nextId), checkedAt = new Date().toISOString(); + node.sessionLink = { status: 'ok', resolvedSession: `codex:${nextId}`, link: `codex:${nextId}`, source: 'codex-threads', checkedAt, lastKnown: false }; + await appendFile(join(state, 'events.jsonl'), `${JSON.stringify({ schema: 'agent-mesh.session-graph-event.v1', id: 'fixture-link', type: 'node.upserted', at: checkedAt, node, seq: graph.lastSeq + 1, host: 'local' })}\n`); + await assert.rejects(call(...args), /reservation unavailable/); + graph = await call('show', '--json'); + const channel = graph.channels.find(row => row.id === 'example'); + channel.statePreparation = { status: 'verified', session: `codex:${oldId}`, generation: channel.generation, id: 'state-1', filename: 'state.yaml', sha256: 'b'.repeat(64), bytes: 2 }; + await appendFile(join(state, 'events.jsonl'), `${JSON.stringify({ schema: 'agent-mesh.session-graph-event.v1', id: 'fixture-state', type: 'channel.updated', at: new Date().toISOString(), channel, seq: graph.lastSeq + 1, host: 'local' })}\n`); + // The operational cutover is disabled. Inject only a synthetic graph event to + // exercise the following durable state; this is not a native cutover proof. + await assert.rejects(call(...args), /reservation unavailable/); + graph = await call('show', '--json'); + const draining = graph.channels.find(row => row.id === 'example'); + draining.handover = { predecessor: `codex:${oldId}`, previousGeneration: 1, successor: `codex:${nextId}`, backlog: [] }; + draining.session = `codex:${nextId}`; draining.generation = 2; draining.phase = 'draining'; + await appendFile(join(state, 'events.jsonl'), `${JSON.stringify({ schema: 'agent-mesh.session-graph-event.v1', id: 'fixture-draining', type: 'channel.updated', at: new Date().toISOString(), channel: draining, seq: graph.lastSeq + 1, host: 'local' })}\n`); + const first = (await call(...args)).channel.finalNotice; + assert.equal(first.status, 'requested'); + assert.equal(first.successor, `codex:${nextId}`); + await rm(join(state, 'checkpoint.json'), { force: true }); + assert.deepEqual((await call('channel', 'get', '--name', 'example')).channel.finalNotice, first); + await assert.rejects(call(...args), /reservation unavailable/); + const notice = `Sleeping. [Continue](codex://threads/${nextId})`; + const records = [ + { type: 'session_meta', payload: { id: oldId } }, + { type: 'event_msg', payload: { type: 'user_message', message: `[HANDOVER:${first.id}] synthetic request` } }, + { type: 'response_item', payload: { type: 'message', role: 'assistant', phase: 'final_answer', content: [{ type: 'output_text', text: notice }] } }, + { type: 'event_msg', payload: { type: 'task_complete', last_agent_message: notice } } + ]; + await writeFile(join(sessions, `rollout-${oldId}.jsonl`), records.map(row => JSON.stringify(row)).join('\n') + '\n', { mode: 0o600 }); + const observe = ['channel', 'observe-notice', '--name', 'example', '--input', JSON.stringify({ prefix: 'Sleeping.', label: 'Continue' })]; + await assert.rejects(call('channel', 'observe-notice', '--name', 'example', '--input', JSON.stringify({ prefix: 'wrong', label: 'Continue' })), /not proven/); + const observed = (await call(...observe)).channel.finalNotice; + assert.equal(observed.status, 'observed-snapshot'); + assert.match(observed.transcriptSha256, /^[a-f0-9]{64}$/); + await rm(join(state, 'checkpoint.json'), { force: true }); + assert.equal((await call('channel', 'get', '--name', 'example')).channel.finalNotice.status, 'observed-snapshot'); + await assert.rejects(call('channel', 'finish-handover', '--name', 'example', '--to', `codex:${nextId}`), /old-session state verification unavailable/); +}); + +test('local Claude delivery is observed only from a matching user transcript and persists', async t => { + const root = await mkdtemp(join(tmpdir(), 'claude-channel-observe-')); + t.after(() => rm(root, { recursive: true, force: true })); + const state = join(root, 'graph'), sessions = join(root, 'sessions'), project = join(sessions, 'project'); + await mkdir(sessions, { mode: 0o700 }); await mkdir(project, { mode: 0o700 }); + const oldId = '22222222-2222-4222-8222-222222222222', newId = '33333333-3333-4333-8333-333333333333', target = `claude:${newId}`; + const env = { ...process.env, CLAUDE_SESSION_ROOT: sessions }; + const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args], { env })).stdout); + await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', oldId, '--json'); + await call('migrate', '--apply', '--json'); + await call('channel', 'create', '--name', 'example', '--session', `codex:${oldId}`); + const graph = await call('show', '--json'), channel = graph.channels.find(row => row.id === 'example'); + channel.session = target; channel.generation = 2; channel.phase = 'draining'; + channel.handover = { predecessor: `codex:${oldId}`, previousGeneration: 1, successor: target, backlog: ['one'] }; + channel.queue = [{ id: 'one', payload: 'fixture', state: 'accepted', session: target, generation: 2 }]; + await appendFile(join(state, 'events.jsonl'), `${JSON.stringify({ schema: 'agent-mesh.session-graph-event.v1', id: 'fixture-draining', type: 'channel.updated', at: new Date().toISOString(), channel, seq: graph.lastSeq + 1, host: 'local' })}\n`); + const inbox = { schema: 'agent-mesh.monitor-inbox.v1', deliveryId: 'one', meshId: 'one', prompt: 'fixture' }; + const text = `AGENT_MESH_INBOX ${JSON.stringify(inbox)}`, path = join(project, `${newId}.jsonl`); + await writeFile(path, JSON.stringify({ type: 'queue-operation', operation: 'enqueue', sessionId: newId, content: text }) + '\n', { mode: 0o600 }); + await assert.rejects(call('channel', 'observe-claude-delivery', '--name', 'example', '--id', 'one'), /not uniquely observed/); + await appendFile(path, JSON.stringify({ type: 'user', isMeta: true, sessionId: newId, message: { role: 'user', content: text } }) + '\n'); + const result = await call('channel', 'observe-claude-delivery', '--name', 'example', '--id', 'one'); + assert.equal(result.status, 'observed'); assert.match(result.evidence, /^claude-transcript:[a-f0-9]{64}$/); + await appendFile(path, JSON.stringify({ type: 'assistant', sessionId: newId }) + '\n'); + assert.equal((await call('channel', 'verify-claude-delivery', '--name', 'example', '--id', 'one')).status, 'verified'); + const original = await readFile(path, 'utf8'); + await writeFile(path, original.replace('fixture', 'changed')); + await assert.rejects(call('channel', 'verify-claude-delivery', '--name', 'example', '--id', 'one')); + await writeFile(path, original); + await rm(join(state, 'checkpoint.json'), { force: true }); + assert.equal((await call('channel', 'get', '--name', 'example')).channel.queue[0].state, 'observed'); +}); + +test('graph revalidates the bound restart file without advancing handover', async t => { + const { createHash } = await import('node:crypto'); + const root = await mkdtemp(join(tmpdir(), 'handover-revalidate-')); + t.after(() => rm(root, { recursive: true, force: true })); + const state = join(root, 'graph'), files = join(root, 'files'); await mkdir(files, { mode: 0o700 }); + const id = '22222222-2222-4222-8222-222222222222', session = `codex:${id}`, filename = 'state.yaml'; + const content = `schema: agent-mesh.restart.v1\nsession: ${session}\nchannel: '#example'\nharness: codex\nworking_directory: /workspace\nskills: []\ntriggers: []\ngoal: null\nrole_profile:\n schema: agent-mesh.role-profile.v1\n role: operator\n permissions: []\n mcp: []\n plugins: []\n`; + await writeFile(join(files, filename), content, { mode: 0o600 }); + const call = async (...args) => JSON.parse((await exec(process.execPath, [bin, '--state', state, ...args])).stdout); + await call('add', '--agent', 'codex', '--tmux-target', 'fixture', '--cwd', '/synthetic', '--runtime-uuid', id, '--json'); + await call('migrate', '--apply', '--json'); await call('channel', 'create', '--name', '#example', '--session', session); + await call('channel', 'begin-handover', '--name', '#example'); + let graph = await call('show', '--json'); + const channel = graph.channels.find(row => row.id === '#example'); + channel.statePreparation = { status: 'verified', session, generation: 1, id: 'fixture-state', filename, sha256: createHash('sha256').update(content).digest('hex'), bytes: Buffer.byteLength(content) }; + await appendFile(join(state, 'events.jsonl'), `${JSON.stringify({ schema: 'agent-mesh.session-graph-event.v1', id: 'fixture-state', type: 'channel.updated', at: new Date().toISOString(), channel, seq: graph.lastSeq + 1, host: 'local' })}\n`); + graph = await call('show', '--json'); const seq = graph.lastSeq; + const args = ['channel', 'revalidate-state', '--name', '#example', '--state-root', files]; + const proof = await call(...args); + assert.equal(proof.status, 'verified-snapshot'); assert.equal(proof.generation, 1); + assert.equal((await call('show', '--json')).lastSeq, seq); + await writeFile(join(files, filename), content.replace('operator', 'operatOr'), { mode: 0o600 }); + await assert.rejects(call(...args), /digest mismatch/); + assert.equal((await call('channel', 'get', '--name', '#example')).channel.phase, 'handover'); +}); diff --git a/packages/tmux-bridge/test/plexus-lifecycle.test.mjs b/packages/tmux-bridge/test/plexus-lifecycle.test.mjs new file mode 100644 index 00000000..f99f1c95 --- /dev/null +++ b/packages/tmux-bridge/test/plexus-lifecycle.test.mjs @@ -0,0 +1,23 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { applyPlexusEvent, LIFECYCLE_EVENTS, PLEXUS_EVENTS } from "../bin/plexus.mjs"; + +const session = "codex:11111111-1111-4111-8111-111111111111"; +const state = () => ({ nodes: new Map(), links: new Map(), edges: new Map(), renewals: [] }); + +test("lifecycle evidence is replayable without mutating session ownership", () => { + for (const type of LIFECYCLE_EVENTS) { + const graph = state(); + assert.ok(PLEXUS_EVENTS.has(type)); + const extra = type === "session.handover" ? { to: "claude:33333333-3333-4333-8333-333333333333" } : {}; + assert.deepEqual(applyPlexusEvent(graph, { type, session, evidence: "source:example", ...extra }), [{ kind: type, session, evidence: "source:example", ...extra }]); + assert.equal(graph.nodes.size, 0); + assert.equal(graph.links.size, 0); + } +}); + +test("lifecycle events reject missing evidence and malformed identities", () => { + assert.throws(() => applyPlexusEvent(state(), { type: "session.idle", session }), /evidence/); + assert.throws(() => applyPlexusEvent(state(), { type: "session.started", session: "codex:bad", evidence: "source:example" }), /session/); + assert.throws(() => applyPlexusEvent(state(), { type: "session.stopped", session, evidence: "one\ntwo" }), /evidence/); +}); diff --git a/packages/tmux-bridge/test/plexus-module-batch.test.mjs b/packages/tmux-bridge/test/plexus-module-batch.test.mjs new file mode 100644 index 00000000..4c5c7e9f --- /dev/null +++ b/packages/tmux-bridge/test/plexus-module-batch.test.mjs @@ -0,0 +1,105 @@ +import assert from "node:assert/strict"; +import { execFile } from "node:child_process"; +import { mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { promisify } from "node:util"; +import test from "node:test"; + +const exec = promisify(execFile); +const graph = fileURLToPath(new URL("../bin/mesh-graph.mjs", import.meta.url)); +const uuid = "22222222-2222-4222-8222-222222222222"; +const session = `codex:${uuid}`; + +test("module batches atomically update their own state and survive replay and compaction", async (t) => { + const dir = await mkdtemp(join(tmpdir(), "plexus-batch-")); + t.after(() => rm(dir, { recursive: true, force: true })); + const state = join(dir, "state"), config = join(dir, "modules.json"); + await writeFile(config, JSON.stringify({ schemaVersion: 1, modules: [{ name: "example", namespaces: ["example", "sleep", "cost"], command: ["example"] }, { name: "other", command: ["example"] }] })); + const call = async (...args) => JSON.parse((await exec(process.execPath, [graph, "--state", state, ...args])).stdout); + await call("add", "--agent", "codex", "--tmux-target", "test", "--cwd", "/synthetic", "--runtime-uuid", uuid, "--json"); + await call("migrate", "--apply", "--json"); + const start = await call("query", "changes", "--input", JSON.stringify({ initial: "head" })); + const batch = { id: "a1", cursor: null, nextCursor: "one", attributes: [{ session, key: "example.count", value: 1 }, { session, key: "sleep.count", value: 2 }, { session, key: "cost.count", value: 3 }], events: [{ type: "example.changed", session, data: { count: 1 } }] }; + const apply = (name, input) => call("module", "apply", "--config", config, "--name", name, "--input", JSON.stringify(input)); + assert.equal((await apply("example", batch)).duplicate, false); + assert.equal((await apply("example", batch)).duplicate, true); + await assert.rejects(apply("example", { ...batch, attributes: [] }), /batch id reused/); + await assert.rejects(apply("other", batch), /namespaced/); + await assert.rejects(apply("example", { ...batch, id: "a2" }), /cursor conflict/); + const feed = await call("query", "changes", "--input", JSON.stringify({ sinceCursor: start.cursor })); + assert.equal(feed.events.filter(item => item.type === "example.changed").length, 1); + await rm(join(state, "checkpoint.json")); + let projection = await call("show", "--json"); + assert.equal(projection.nodes[0].moduleAttributes.example.count, 1); + assert.equal(projection.nodes[0].moduleAttributes.sleep.count, 2); + assert.equal(projection.nodes[0].moduleAttributes.cost.count, 3); + assert.equal(projection.moduleStates[0].cursor, "one"); + await call("compact", "--all-history", "--apply", "--json"); + await rm(join(state, "checkpoint.json"), { force: true }); + projection = await call("show", "--json"); + assert.equal(projection.nodes[0].moduleAttributes.example.count, 1); + assert.equal(projection.moduleStates[0].cursor, "one"); + assert.equal((await apply("example", batch)).duplicate, true); + const racing = await Promise.allSettled([ + apply("example", { id: "race-a", cursor: "one", nextCursor: "two-a", attributes: [], events: [] }), + apply("example", { id: "race-b", cursor: "one", nextCursor: "two-b", attributes: [], events: [] }), + ]); + assert.equal(racing.filter(item => item.status === "fulfilled").length, 1); + assert.equal(racing.filter(item => item.status === "rejected").length, 1); +}); + +test("a registered module can initialize once and an idle run does not create events", async (t) => { + const dir = await mkdtemp(join(tmpdir(), "plexus-run-")); + t.after(() => rm(dir, { recursive: true, force: true })); + const state = join(dir, "state"), config = join(dir, "modules.json"); + const fixture = fileURLToPath(new URL("../examples/plexus-example-module.mjs", import.meta.url)); + await writeFile(config, JSON.stringify({ schemaVersion: 1, modules: [{ name: "example", command: [process.execPath, fixture] }] })); + const call = async (...args) => JSON.parse((await exec(process.execPath, [graph, "--state", state, ...args])).stdout); + await call("add", "--agent", "codex", "--tmux-target", "test", "--cwd", "/synthetic", "--runtime-uuid", uuid, "--json"); + await call("migrate", "--apply", "--json"); + assert.equal((await call("module", "conformance", "--config", config, "--name", "example")).conformance, "pass"); + assert.equal((await call("module", "run", "--config", config, "--name", "example")).duplicate, false); + const before = await call("show", "--json"); + assert.equal((await call("module", "run", "--config", config, "--name", "example")).unchanged, true); + const after = await call("show", "--json"); + assert.equal(after.lastSeq, before.lastSeq); +}); + +test("lifecycle observations are idempotent across replay and compaction", async (t) => { + const dir = await mkdtemp(join(tmpdir(), "plexus-life-")); + t.after(() => rm(dir, { recursive: true, force: true })); + const state = join(dir, "state"); + const call = async (...args) => JSON.parse((await exec(process.execPath, [graph, "--state", state, ...args])).stdout); + await call("add", "--agent", "codex", "--tmux-target", "test", "--cwd", "/synthetic", "--runtime-uuid", uuid, "--json"); + await call("migrate", "--apply", "--json"); + const head = await call("query", "changes", "--input", JSON.stringify({ initial: "head" })); + const args = ["lifecycle", "record", "--session", session, "--type", "session.idle", "--id", "source-observation-1", "--evidence", "observation:sample"]; + assert.equal((await call(...args)).duplicate, false); + assert.equal((await call(...args)).duplicate, true); + await assert.rejects(call(...args.slice(0, -1), "observation:different"), /different contents/); + const feed = await call("query", "changes", "--input", JSON.stringify({ sinceCursor: head.cursor })); + assert.equal(feed.events.filter(item => item.type === "session.idle").length, 1); + await call("compact", "--all-history", "--apply", "--json"); + await rm(join(state, "checkpoint.json"), { force: true }); + assert.equal((await call(...args)).duplicate, true); +}); + +test("a concurrent graph change rejects a stale module result without advancing its cursor", async (t) => { + const dir = await mkdtemp(join(tmpdir(), "plexus-race-")); + t.after(() => rm(dir, { recursive: true, force: true })); + const state = join(dir, "state"), config = join(dir, "modules.json"), fixture = join(dir, "fixture.mjs"); + const script = `import { spawnSync } from 'node:child_process'; +if (process.argv[2] === 'describe') console.log(JSON.stringify({schema:'agent-mesh.plexus-module.v1',name:'example',namespaces:['example'],operations:['describe','process']})); +else { const p=spawnSync(process.execPath,[${JSON.stringify(graph)},'--state',${JSON.stringify(state)},'add','--agent','codex','--tmux-target','concurrent','--cwd','/synthetic','--runtime-uuid','33333333-3333-4333-8333-333333333333','--json']); if(p.status!==0) process.exit(1); console.log(JSON.stringify({schema:'agent-mesh.plexus-module.v1',name:'example',batchId:'race',attributes:[],events:[]})); }`; + await writeFile(fixture, script); + await writeFile(config, JSON.stringify({ schemaVersion: 1, modules: [{ name: "example", command: [process.execPath, fixture] }] })); + const call = async (...args) => JSON.parse((await exec(process.execPath, [graph, "--state", state, ...args])).stdout); + await call("add", "--agent", "codex", "--tmux-target", "test", "--cwd", "/synthetic", "--runtime-uuid", uuid, "--json"); + await call("migrate", "--apply", "--json"); + await assert.rejects(call("module", "run", "--config", config, "--name", "example"), /graph changed during module processing/); + const after = await call("show", "--json"); + assert.equal(after.nodes.length, 2); + assert.deepEqual(after.moduleStates, []); +}); diff --git a/packages/tmux-bridge/test/plexus-modules.test.mjs b/packages/tmux-bridge/test/plexus-modules.test.mjs new file mode 100644 index 00000000..c6812dda --- /dev/null +++ b/packages/tmux-bridge/test/plexus-modules.test.mjs @@ -0,0 +1,56 @@ +import assert from "node:assert/strict"; +import { mkdtemp, writeFile, rm } from "node:fs/promises"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import test from "node:test"; +import { execFile } from "node:child_process"; +import { promisify } from "node:util"; +import { fileURLToPath } from "node:url"; +import { readModuleRegistry, describeModule, invokeModule } from "../bin/plexus-modules.mjs"; + +test("registry is private configuration and duplicate names fail closed", async () => { + const dir = await mkdtemp(join(tmpdir(), "plexus-modules-")); + try { + const file = join(dir, "config.json"); + assert.deepEqual(await readModuleRegistry(file), []); + const entry = { name: "example", command: [process.execPath, "fixture.mjs"] }; + await writeFile(file, JSON.stringify({ schemaVersion: 1, modules: [entry, entry] })); + await assert.rejects(readModuleRegistry(file), /duplicate/); + await writeFile(file, JSON.stringify({ schemaVersion: 1, modules: [{ ...entry, namespaces: ["shared"] }, { ...entry, name: "other", namespaces: ["shared"] }] })); + await assert.rejects(readModuleRegistry(file), /namespace/); + await writeFile(file, "{"); + await assert.rejects(readModuleRegistry(file)); + } finally { await rm(dir, { recursive: true, force: true }); } +}); + +test("graph discovers and describes only registered modules", async () => { + const dir = await mkdtemp(join(tmpdir(), "plexus-modules-cli-")); + try { + const config = join(dir, "config.json"); + const fixture = fileURLToPath(new URL("../examples/plexus-example-module.mjs", import.meta.url)); + const graph = fileURLToPath(new URL("../bin/mesh-graph.mjs", import.meta.url)); + await writeFile(config, JSON.stringify({ schemaVersion: 1, modules: [{ name: "example", command: [process.execPath, fixture] }] })); + const exec = promisify(execFile); + const list = await exec(process.execPath, [graph, "module", "list", "--config", config]); + assert.deepEqual(JSON.parse(list.stdout), { modules: [{ name: "example" }] }); + const describe = await exec(process.execPath, [graph, "module", "describe", "--config", config, "--name", "example"]); + assert.deepEqual(JSON.parse(describe.stdout).namespaces, ["example"]); + await assert.rejects(exec(process.execPath, [graph, "module", "describe", "--config", config, "--name", "unknown"])); + } finally { await rm(dir, { recursive: true, force: true }); } +}); + +test("describe verifies identity and enforces timeouts", async () => { + const good = "process.stdout.write(JSON.stringify({schema:'agent-mesh.plexus-module.v1',name:'example',namespaces:['example'],operations:['describe']}))"; + const entry = { name: "example", command: [process.execPath, "-e", good], timeoutMs: 1000 }; + assert.deepEqual((await describeModule(entry)).namespaces, ["example"]); + await assert.rejects(describeModule({ ...entry, name: "other" }), /invalid module response/); + await assert.rejects(describeModule({ ...entry, command: [process.execPath, "-e", "setTimeout(()=>{}, 10000)"], timeoutMs: 20 }), /timed out/); +}); + +test("large graph requests are bounded independently from module responses", async () => { + const fixture = fileURLToPath(new URL("../examples/plexus-example-module.mjs", import.meta.url)); + const entry = { name: "example", command: [process.execPath, fixture], timeoutMs: 5000 }; + const response = await invokeModule(entry, "process", { cursor: null, graph: { synthetic: "x".repeat(2 * 1024 * 1024) } }); + assert.deepEqual(response.attributes, []); + await assert.rejects(invokeModule(entry, "process", { graph: "x".repeat(33 * 1024 * 1024) }), /too large/); +}); diff --git a/packages/tmux-bridge/test/plexus-privacy.test.mjs b/packages/tmux-bridge/test/plexus-privacy.test.mjs new file mode 100644 index 00000000..e6ad027a --- /dev/null +++ b/packages/tmux-bridge/test/plexus-privacy.test.mjs @@ -0,0 +1,27 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { containsPrivatePlexusPolicy, isGeneratedPythonBytecode, isPlexusMechanismFile } from '../../../scripts/plexus-privacy.mjs'; + +test('only interpreter bytecode in cache directories is excluded from text scanning', () => { + const tracked = new Set(['pkg/__pycache__/tracked.cpython-312.pyc']); + assert.equal(isGeneratedPythonBytecode('pkg/__pycache__/example.cpython-312.pyc', tracked), true); + assert.equal(isGeneratedPythonBytecode('pkg/__pycache__/example.cpython-312.opt-1.pyc', tracked), true); + assert.equal(isGeneratedPythonBytecode('pkg/__pycache__/tracked.cpython-312.pyc', tracked), false); + assert.equal(isGeneratedPythonBytecode('pkg/__pycache__/example.cpython-312.pyc', null), false); + assert.equal(isGeneratedPythonBytecode('pkg/__pycache__/example.py', tracked), false); + assert.equal(isGeneratedPythonBytecode('pkg/example.cpython-312.pyc', tracked), false); + assert.equal(isGeneratedPythonBytecode('pkg/__pycache__/other.pyc', tracked), false); +}); + +test('Plexus public mechanism paths and private references are classified', () => { + assert.equal(isPlexusMechanismFile('packages/tmux-bridge/bin/codex-compaction-evidence.mjs'), true); + assert.equal(isPlexusMechanismFile('packages/tmux-bridge/test/codex-compaction-evidence.test.mjs'), true); + assert.equal(isPlexusMechanismFile('skills/agent-tmux/bin/codex-compaction-evidence.mjs'), true); + for (const path of ['packages/tmux-bridge/bin/codex-wake-evidence.mjs', 'packages/tmux-bridge/test/codex-wake-evidence.test.mjs', 'skills/agent-tmux/bin/codex-wake-evidence.mjs']) assert.equal(isPlexusMechanismFile(path), true, path); + assert.equal(isPlexusMechanismFile('packages/tmux-bridge/bin/restart-state.mjs'), true); + assert.equal(isPlexusMechanismFile('packages/tmux-bridge/test/restart-state.test.mjs'), true); + assert.equal(isPlexusMechanismFile('skills/agent-tmux/bin/restart-state.mjs'), true); + for (const path of ['docs/design/plexus.md', 'docs/design/plexus-modules.md', 'packages/tmux-bridge/README.md', 'packages/tmux-bridge/bin/plexus.mjs', 'packages/tmux-bridge/bin/mesh-graph.mjs', 'packages/tmux-bridge/bin/plexus-modules.mjs', 'packages/tmux-bridge/examples/plexus-example-module.mjs', 'packages/tmux-bridge/test/plexus-privacy.test.mjs', 'skills/agent-tmux/bin/agent-waker.py']) assert.equal(isPlexusMechanismFile(path), true, path); + for (const value of ['gale' + 'haut', 'management:' + 'MGT-123', '/home/' + 'administrator/private']) assert.equal(containsPrivatePlexusPolicy(value), true); + assert.equal(containsPrivatePlexusPolicy('A configurable policy uses a synthetic session.'), false); +}); diff --git a/packages/tmux-bridge/test/plexus.test.mjs b/packages/tmux-bridge/test/plexus.test.mjs index 68b2fa4d..5219def8 100644 --- a/packages/tmux-bridge/test/plexus.test.mjs +++ b/packages/tmux-bridge/test/plexus.test.mjs @@ -47,6 +47,41 @@ const scopeA = { handleKey: "space-a-handle-key-0123456789", }; +test("lifecycle feed exposes evidence locally but not to scoped consumers", async (t) => { + const state = await mkdtemp(join(tmpdir(), "plexus-life-scope-")); + t.after(() => rm(state, { recursive: true, force: true })); + await seed(state); + await ok(state, ["migrate", "--apply"]); + const start = (await query(state, "changes", { initial: "head" })).cursor; + await ok(state, ["lifecycle", "record", "--session", `codex:${CODEX}`, "--type", "session.idle", "--id", "scope-example", "--evidence", "private:example"]); + const local = await query(state, "changes", { sinceCursor: start }); + const scoped = await query(state, "changes", { sinceCursor: start, scope: scopeA }); + assert.equal(local.events[0].evidence, "private:example"); + assert.equal(scoped.events[0].type, "session.idle"); + assert.ok(!("evidence" in scoped.events[0])); +}); + +test("observed wake events are session-bound and retries do not double count", async (t) => { + const state = await mkdtemp(join(tmpdir(), "plexus-wake-")); + t.after(() => rm(state, { recursive: true, force: true })); + await seed(state); + await ok(state, ["migrate", "--apply"]); + const cursor = (await query(state, "changes", { initial: "head" })).cursor; + const args = ["lifecycle", "record", "--session", `codex:${CODEX}`, "--type", "session.woken", "--id", "wake-example", "--evidence", "native:turn-example"]; + assert.equal((await ok(state, args)).duplicate, false); + assert.equal((await ok(state, args)).duplicate, true); + assert.notEqual((await run(state, [...args.slice(0, -1), "native:other"])).code, 0); + const feed = await query(state, "changes", { sinceCursor: cursor }); + const wake = feed.events.filter(event => event.type === "session.woken"); + assert.equal(wake.length, 1); + assert.equal(wake[0].session, `codex:${CODEX}`); + assert.equal(wake[0].evidence, "native:turn-example"); + assert.ok(wake[0].eventId && Number.isSafeInteger(wake[0].seq) && wake[0].at && wake[0].host); + const scoped = await query(state, "changes", { sinceCursor: cursor, scope: scopeA }); + assert.equal(scoped.events.filter(event => event.type === "session.woken").length, 1); + assert.ok(!('evidence' in scoped.events.find(event => event.type === "session.woken"))); +}); + test("cloud registration has exact account-qualified identity and survives graph replay", async (t) => { const state = await mkdtemp(join(tmpdir(), "plexus-cloud-")); t.after(() => rm(state, { recursive: true, force: true })); diff --git a/packages/tmux-bridge/test/restart-state.test.mjs b/packages/tmux-bridge/test/restart-state.test.mjs new file mode 100644 index 00000000..055d48de --- /dev/null +++ b/packages/tmux-bridge/test/restart-state.test.mjs @@ -0,0 +1,18 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { validateRestartState } from '../bin/restart-state.mjs'; + +const sample = () => ({ schema: 'agent-mesh.restart.v1', session: 'codex:example', channel: '#example', harness: 'codex', working_directory: '/workspace', skills: ['example-skill'], triggers: [{ id: 'trigger-1', kind: 'timer', config: { prompt: 'Perform the next check.' } }], goal: { objective: 'Finish the task.', status: 'active' } }); +test('restart block is bound to its original session and stable channel', () => { + assert.equal(validateRestartState(sample(), { session: 'codex:example', channel: '#example' }), true); + assert.throws(() => validateRestartState(sample(), { session: 'codex:other' }), /session mismatch/); + assert.throws(() => validateRestartState(sample(), { channel: '#other' }), /channel mismatch/); +}); +test('restart block rejects incomplete or ambiguous configuration', () => { + for (const [key, value] of [['schema', 'other'], ['harness', ''], ['working_directory', null], ['skills', [null]], ['triggers', [{ id: 'x', kind: 'timer' }]], ['goal', {}]]) { + assert.throws(() => validateRestartState({ ...sample(), [key]: value }), undefined, key); + } + const item = { id: 'x', kind: 'timer', config: {} }; + assert.throws(() => validateRestartState({ ...sample(), triggers: [item, item] }), /duplicate/); + assert.equal(validateRestartState({ ...sample(), triggers: [], skills: [], goal: null }), true); +}); diff --git a/packages/tmux-bridge/test/restart-yaml.test.mjs b/packages/tmux-bridge/test/restart-yaml.test.mjs new file mode 100644 index 00000000..49633dae --- /dev/null +++ b/packages/tmux-bridge/test/restart-yaml.test.mjs @@ -0,0 +1,21 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { fileURLToPath } from 'node:url'; +import test from 'node:test'; + +const parser = fileURLToPath(new URL('../bin/restart-yaml.py', import.meta.url)); +const parse = text => spawnSync('python3', ['-I', parser], { input: text, encoding: 'utf8' }); +test('restart YAML accepts a single fenced block and standalone documents', () => { + assert.deepEqual(JSON.parse(parse('schema: example\nskills: [one, two]\n').stdout), { schema: 'example', skills: ['one', 'two'] }); + const result = parse('# State\n\n## RIAVVIO\n\n```yaml\nschema: example\n```\n\n## Notes\nhello\n'); + assert.equal(result.status, 0, result.stderr); + assert.deepEqual(JSON.parse(result.stdout), { schema: 'example' }); +}); +test('restart YAML rejects ambiguous or unsafe inputs without exposing contents', () => { + for (const input of ['key: first\nkey: second\n', 'key: &anchor first\nother: *anchor\n', 'key: !!str value\n', 'a: 1\n---\na: 2\n', '## RIAVVIO\nnot a block\n', '## RIAVVIO\n```yaml\na: 1\n```\n## RIAVVIO\n```yaml\na: 2\n```\n', 'secret: fixture\n'.repeat(80000)]) { + const result = parse(input); + assert.notEqual(result.status, 0); + assert.equal(result.stdout, ''); + assert.ok(!result.stderr.includes('fixture')); + } +}); diff --git a/packages/tmux-bridge/test/role-launch-profile.test.mjs b/packages/tmux-bridge/test/role-launch-profile.test.mjs new file mode 100644 index 00000000..6603581a --- /dev/null +++ b/packages/tmux-bridge/test/role-launch-profile.test.mjs @@ -0,0 +1,33 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { validateRestartState } from '../bin/restart-state.mjs'; +import { planRoleLaunch, assessRoleLaunch } from '../bin/role-launch-profile.mjs'; + +const profile = { schema: 'agent-mesh.role-profile.v1', role: 'operator', permissions: ['read'], mcp: ['alpha', 'beta'], plugins: ['example'] }; +const authority = { role: 'operator', permissions: ['read', 'publish'], humanGatedPermissions: ['publish'], mcp: ['alpha', 'beta'], plugins: ['example'] }; + +test('restart role profile is explicit, bounded and never creates grants', () => { + const state = { schema: 'agent-mesh.restart.v1', session: 'codex:example', channel: '#example', harness: 'codex', working_directory: '/workspace', skills: [], triggers: [], goal: null }; + assert.throws(() => validateRestartState(state, { requireRoleProfile: true }), /profile/); + assert.equal(validateRestartState({ ...state, role_profile: profile }, { requireRoleProfile: true }), true); + assert.throws(() => validateRestartState({ ...state, role_profile: { ...profile, permissions: ['read', 'read'] } }), /permissions/); + assert.throws(() => validateRestartState({ ...state, role_profile: { ...profile, mcp: ['*'] } }), /mcp/); +}); + +test('unreachable MCP is excluded while unexpected permission requires rollback', async () => { + const seen = []; + const plan = await planRoleLaunch({ profile, authority, probe: async name => { seen.push(name); if (name === 'beta') throw new Error('offline'); return true; }, timeoutMs: 50 }); + assert.deepEqual(seen, ['alpha', 'beta']); + assert.deepEqual(plan.mcpToStart, ['alpha']); + assert.deepEqual(plan.mcpUnavailable, ['beta']); + const observed = { mcpStarted: ['alpha'], pluginsStarted: ['example'], permissionPrompt: false, startupTokens: null }; + const receipt = assessRoleLaunch({ plan, observed }); + assert.equal(receipt.status, 'ready'); + assert.equal(receipt.mcpStarted, 1); + assert.deepEqual(receipt.mcpUnavailable, ['beta']); + assert.equal(receipt.startupTokens, null); + assert.equal(assessRoleLaunch({ plan, observed: { ...observed, permissionPrompt: true } }).status, 'rollback-required'); + assert.equal(assessRoleLaunch({ plan, observed: { ...observed, mcpStarted: ['alpha', 'other'] } }).status, 'rollback-required'); + await assert.rejects(planRoleLaunch({ profile: { ...profile, permissions: ['publish'] }, authority, probe: async () => true }), /human-gated/); + await assert.rejects(planRoleLaunch({ profile: { ...profile, mcp: ['other'] }, authority, probe: async () => true }), /exceeds/); +}); diff --git a/packages/tmux-bridge/test/role-mcp-probe.test.mjs b/packages/tmux-bridge/test/role-mcp-probe.test.mjs new file mode 100644 index 00000000..aed61a52 --- /dev/null +++ b/packages/tmux-bridge/test/role-mcp-probe.test.mjs @@ -0,0 +1,150 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { mkdtemp, access, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { probeStdioMcp, roleProbeFromAllowlist } from '../bin/role-mcp-probe.mjs'; +import { planRoleLaunch } from '../bin/role-launch-profile.mjs'; + +const fixture = `let buffer = ''; process.stdin.setEncoding('utf8'); process.stdin.on('data', data => { buffer += data; let index; while ((index = buffer.indexOf('\\n')) >= 0) { const line = buffer.slice(0, index); buffer = buffer.slice(index + 1); const request = JSON.parse(line); if (request.method === 'initialize') console.log(JSON.stringify({jsonrpc:'2.0',id:1,result:{protocolVersion:'2024-11-05',capabilities:{},serverInfo:{name:'fixture',version:'1'}}})); if (request.method === 'ping') console.log(JSON.stringify({jsonrpc:'2.0',id:2,result:{}})); } });`; + +test('only an initialized and responsive MCP is accepted by role planning', async () => { + const good = { command: [process.execPath, '--input-type=module', '-e', fixture], timeoutMs: 5000 }; + const offline = { command: ['/bin/false'], timeoutMs: 5000 }; + assert.equal(await probeStdioMcp(good), true); + assert.equal(await probeStdioMcp(offline), false); + const profile = { schema: 'agent-mesh.role-profile.v1', role: 'fixture', permissions: [], mcp: ['good', 'offline'], plugins: [] }; + const authority = { role: 'fixture', permissions: [], humanGatedPermissions: [], mcp: ['good', 'offline'], plugins: [] }; + const allowlist = { good, offline }; + const probe = roleProbeFromAllowlist(allowlist, 3000); + const plan = await planRoleLaunch({ profile, authority, probe, timeoutMs: 5000 }); + assert.deepEqual(plan.mcpToStart, ['good']); + assert.deepEqual(plan.mcpUnavailable, ['offline']); + assert.throws(() => probe('unlisted'), /allowlisted/); + await assert.rejects(probeStdioMcp({ command: ['relative-program'] }), /configuration/); +}); + +test('a cancelled probe terminates its temporary MCP process', async t => { + const root = await mkdtemp(join(tmpdir(), 'mcp-cancel-')); + t.after(() => rm(root, { recursive: true, force: true })); + const started = join(root, 'started'), late = join(root, 'late'); + const code = "import {writeFileSync} from 'node:fs'; writeFileSync(process.argv[1], String(process.pid)); setTimeout(() => writeFileSync(process.argv[2], 'late'), 500); setInterval(() => {}, 1000);"; + const controller = new AbortController(); + const probe = probeStdioMcp({ command: [process.execPath, '--input-type=module', '-e', code, started, late], timeoutMs: 5000, signal: controller.signal }); + let seen = false; + for (let i = 0; i < 300 && !seen; i++) { + try { await access(started); seen = true; } catch { await new Promise(resolve => setTimeout(resolve, 10)); } + } + assert.equal(seen, true, 'fixture process started'); + controller.abort(); + assert.equal(await probe, false); + await new Promise(resolve => setTimeout(resolve, 600)); + await assert.rejects(access(late)); +}); + +test('planner aborts its trusted probe when its deadline expires', async () => { + const profile = { schema: 'agent-mesh.role-profile.v1', role: 'fixture', permissions: [], mcp: ['slow'], plugins: [] }; + const authority = { role: 'fixture', permissions: [], humanGatedPermissions: [], mcp: ['slow'], plugins: [] }; + let aborted = false; + const plan = await planRoleLaunch({ profile, authority, timeoutMs: 20, probe: (_name, { signal }) => new Promise(resolve => signal.addEventListener('abort', () => { aborted = true; resolve(false); }, { once: true })) }); + assert.equal(aborted, true); + assert.deepEqual(plan.mcpUnavailable, ['slow']); +}); + +test('planner refuses to continue if cancellation is not acknowledged', async () => { + const profile = { schema: 'agent-mesh.role-profile.v1', role: 'fixture', permissions: [], mcp: ['slow'], plugins: [] }; + const authority = { role: 'fixture', permissions: [], humanGatedPermissions: [], mcp: ['slow'], plugins: [] }; + await assert.rejects(planRoleLaunch({ profile, authority, timeoutMs: 5, probe: () => new Promise(() => {}) }), /cancellation unconfirmed/); +}); + +test('unobserved process closure fails planning instead of treating MCP as offline', async () => { + const { EventEmitter } = await import('node:events'); + const child = new EventEmitter(); + child.stdin = new EventEmitter(); child.stdin.write = () => true; + child.stdout = new EventEmitter(); child.stdout.setEncoding = () => {}; + child.stdio = [child.stdin, child.stdout, null, new EventEmitter(), new EventEmitter()]; child.stdio[3].setEncoding = () => {}; child.stdio[4].end = () => {}; + const profile = { schema: 'agent-mesh.role-profile.v1', role: 'fixture', permissions: [], mcp: ['stuck'], plugins: [] }; + const authority = { role: 'fixture', permissions: [], humanGatedPermissions: [], mcp: ['stuck'], plugins: [] }; + const probe = (_name, { signal }) => probeStdioMcp({ command: [process.execPath], timeoutMs: 5, signal, spawnProcess: () => child }); + await assert.rejects(planRoleLaunch({ profile, authority, probe, timeoutMs: 1400 }), /probe cancellation unconfirmed/); +}); + +test('missing or invalid private MCP configuration stops planning', async () => { + const profile = { schema: 'agent-mesh.role-profile.v1', role: 'fixture', permissions: [], mcp: ['wanted'], plugins: [] }; + const authority = { role: 'fixture', permissions: [], humanGatedPermissions: [], mcp: ['wanted'], plugins: [] }; + await assert.rejects(planRoleLaunch({ profile, authority, probe: roleProbeFromAllowlist({}) }), /not allowlisted/); + await assert.rejects(planRoleLaunch({ profile, authority, probe: roleProbeFromAllowlist({ wanted: { command: ['relative-program'] } }) }), /invalid MCP probe configuration/); +}); + +test('the contained probe stops a detached descendant before returning', async t => { + const root = await mkdtemp(join(tmpdir(), 'mcp-contained-')); + t.after(() => rm(root, { recursive: true, force: true })); + const late = join(root, 'late'), started = join(root, 'started'); + const childCode = `require('node:fs').writeFileSync(process.argv[1], 'started'); setTimeout(() => require('node:fs').writeFileSync(process.argv[2], 'late'), 600); setInterval(() => {}, 1000)`; + const server = `const {spawn}=require('node:child_process'); const c=spawn(process.execPath,['-e',${JSON.stringify(childCode)},${JSON.stringify(started)},${JSON.stringify(late)}],{detached:true,stdio:'ignore'});c.unref(); let b='';process.stdin.on('data',d=>{b+=d;let n;while((n=b.indexOf('\\n'))>=0){const x=JSON.parse(b.slice(0,n));b=b.slice(n+1);if(x.method==='initialize')console.log(JSON.stringify({jsonrpc:'2.0',id:1,result:{protocolVersion:'2024-11-05',capabilities:{},serverInfo:{name:'fixture',version:'1'}}}));if(x.method==='ping'){const timer=setInterval(()=>{if(require('node:fs').existsSync(${JSON.stringify(started)})){clearInterval(timer);console.log(JSON.stringify({jsonrpc:'2.0',id:2,result:{}}));}},10);}}});`; + assert.equal(await probeStdioMcp({ command: [process.execPath, '-e', server], timeoutMs: 5000 }), true); + await access(started); + await new Promise(resolve => setTimeout(resolve, 900)); + await assert.rejects(access(late)); +}); + +test('unavailable namespace containment stops planning before command release', async () => { + const { EventEmitter } = await import('node:events'); + const child = new EventEmitter(); + child.stdin = new EventEmitter(); child.stdin.write = () => true; + child.stdout = new EventEmitter(); child.stdout.setEncoding = () => {}; + const info = new EventEmitter(); info.setEncoding = () => {}; + const gate = new EventEmitter(); let released = false; gate.end = () => { released = true; }; + child.stdio = [child.stdin, child.stdout, null, info, gate]; + const result = probeStdioMcp({ command: [process.execPath], timeoutMs: 1000, spawnProcess: () => child }); + queueMicrotask(() => { info.emit('data', '{}'); info.emit('end'); child.emit('close'); }); + await assert.rejects(result, error => error.code === 'MCP_PROBE_CONFIGURATION'); + assert.equal(released, false); +}); + +test('the execution gate rejects EOF, partial and invalid permits', async t => { + const { spawn } = await import('node:child_process'); + const { fileURLToPath } = await import('node:url'); + const root = await mkdtemp(join(tmpdir(), 'mcp-gate-')); + t.after(() => rm(root, { recursive: true, force: true })); + const gate = fileURLToPath(new URL('../bin/role-mcp-exec-gate.py', import.meta.url)); + const execute = (input, marker) => new Promise((resolve, reject) => { + const child = spawn('/usr/bin/python3', ['-B', gate, '--', '/usr/bin/touch', marker], { stdio: ['pipe', 'pipe', 'ignore'] }); + let output = ''; child.stdout.on('data', chunk => { output += chunk; }); + child.on('error', reject); child.on('close', code => resolve({ code, output })); + child.stdin.end(input); + }); + for (const input of ['', 'G', 'NO\n']) { + const marker = join(root, `no-${input.length}`); + const result = await execute(input, marker); + assert.equal(result.code, 125); assert.equal(result.output, ''); + await assert.rejects(access(marker)); + } + const marker = join(root, 'yes'); + const result = await execute('GO\n', marker); + assert.equal(result.code, 0); assert.equal(result.output, '{"agentMeshMcpGate":"released"}\n'); + await access(marker); +}); + +test('an already cancelled probe never starts a process', async () => { + const controller = new AbortController(); controller.abort(); + let spawned = false; + const result = await probeStdioMcp({ command: [process.execPath], signal: controller.signal, spawnProcess: () => { spawned = true; } }); + assert.equal(result, false); assert.equal(spawned, false); +}); + + +test('missing gate acknowledgement is a configuration error, not an offline MCP', async t => { + const { spawn } = await import('node:child_process'); + const root = await mkdtemp(join(tmpdir(), 'mcp-no-ack-')); + t.after(() => rm(root, { recursive: true, force: true })); + const fakeGate = join(root, 'no-ack.py'), marker = join(root, 'target-started'); + await writeFile(fakeGate, 'import os\nos.read(0, 3)\n'); + const spawnWithoutAcknowledgement = (command, args, options) => { + const modified = [...args], index = modified.findIndex(value => value.endsWith('/role-mcp-exec-gate.py')); + assert.notEqual(index, -1); modified[index] = fakeGate; + return spawn(command, modified, options); + }; + await assert.rejects(probeStdioMcp({ command: ['/usr/bin/touch', marker], timeoutMs: 2000, spawnProcess: spawnWithoutAcknowledgement }), error => error.code === 'MCP_PROBE_CONFIGURATION'); + await assert.rejects(access(marker)); +}); diff --git a/packages/tmux-bridge/test/session-inbox.test.py b/packages/tmux-bridge/test/session-inbox.test.py index 3bec63f3..95ac0d35 100644 --- a/packages/tmux-bridge/test/session-inbox.test.py +++ b/packages/tmux-bridge/test/session-inbox.test.py @@ -49,8 +49,21 @@ def tearDown(self): proc.communicate(timeout=5) self.temp.cleanup() + def test_hook_timeout_reports_fixed_diagnostic_without_context(self): + spec = importlib.util.spec_from_file_location('hook_timeout_test', SCRIPT) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + stdout, stderr = io.StringIO(), io.StringIO() + with patch.dict(os.environ, {'AGENT_MESH_INBOX_DIAGNOSTICS': '1'}), \ + patch.object(module, 'hook', side_effect=module.HookBudgetExpired()), \ + patch.object(sys, 'argv', [str(SCRIPT), 'hook', '--root', str(self.root)]), \ + contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr): + module.main() + self.assertEqual(stdout.getvalue(), '') + self.assertEqual(stderr.getvalue(), 'agent-session-inbox: hook budget expired\n') + def hook(self, agent='claude', session=SESSION, event='SessionStart', owner=None, extra_env=None, payload=None): - env = {**os.environ, 'AGENT_MESH_HARNESS_PID': str(owner or os.getpid()), **(extra_env or {})} + env = {**os.environ, 'AGENT_MESH_INBOX_DIAGNOSTICS': '1', 'AGENT_MESH_HARNESS_PID': str(owner or os.getpid()), **(extra_env or {})} return subprocess.run([sys.executable, str(SCRIPT), 'hook', '--root', str(self.root), '--agent', agent], input=json.dumps(payload if payload is not None else {'session_id': session, 'hook_event_name': event}), env=env, text=True, capture_output=True, check=True) @@ -208,7 +221,7 @@ def test_detached_service_survives_hook_exit_and_delivers_only_real_batches(self while time.monotonic() JSON.parse(execFileSync('python3', [script, db, op, ...(arg ? [JSON.stringify(arg)] : [])], {encoding:'utf8'})); +const adapter = { read: async () => call('read'), move: async args => { + if (mode === 'delayed' && args.operationId === 'tx:0') { process.send('waiting'); await new Promise(resolve => process.once('message', resolve)); } + const result = call('cas', args); + if (mode === 'crash' && args.operationId === 'tx:0') { process.send('applied'); await new Promise(() => {}); } + return result; +} }; +try { await reconcileTriggers({triggers:[{kind:'fixture',id:'one'}],from:'old',to:'new',transactionId:'tx',adapter,journal:triggerJournal(root),dryRun:false}); process.send('completed'); } +catch { process.send('fenced'); } +`; + +for (const mode of ['delayed', 'crash']) test(`cross-process ${mode} trigger recovery`, { timeout: 15000 }, async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-cross-')); + t.after(() => rm(root, { recursive: true, force: true })); + const script = join(root, 'cas.py'), workerFile = join(root, 'worker.mjs'), db = join(root, 'fixture.db'); + await writeFile(script, python); await writeFile(workerFile, worker); + execFileSync('python3', [script, db, 'init']); + const call = (op, arg) => JSON.parse(execFileSync('python3', [script, db, op, ...(arg ? [JSON.stringify(arg)] : [])], { encoding: 'utf8' })); + const adapter = { read: async () => call('read'), move: async args => call('cas', args) }; + const child = fork(workerFile, [root, script, db, mode], { stdio: ['ignore', 'ignore', 'pipe', 'ipc'] }); + t.after(() => { if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL'); }); + const message = () => new Promise((resolve, reject) => { child.once('message', resolve); child.once('error', reject); }); + assert.equal(await message(), mode === 'delayed' ? 'waiting' : 'applied'); + if (mode === 'crash') { + const exited = new Promise(resolve => child.once('exit', resolve)); child.kill('SIGKILL'); await exited; + } + const journal = triggerJournal(root); + assert.equal((await journal.get('tx')).status, 'applying'); + const result = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal }); + assert.equal(result.status, 'rolled-back'); + if (mode === 'delayed') { const ended = message(); child.send('continue'); assert.equal(await ended, 'fenced'); } + const final = call('read'); + assert.equal(final.target, 'old'); assert.equal(final.lastOperationId, 'tx:rollback:0'); + assert.equal((await journal.get('tx')).status, 'rolled-back'); +}); diff --git a/packages/tmux-bridge/test/trigger-journal.test.mjs b/packages/tmux-bridge/test/trigger-journal.test.mjs new file mode 100644 index 00000000..06582e89 --- /dev/null +++ b/packages/tmux-bridge/test/trigger-journal.test.mjs @@ -0,0 +1,239 @@ +import assert from 'node:assert/strict'; +import { execFile } from 'node:child_process'; +import { chmod, mkdtemp, rm, writeFile } from 'node:fs/promises'; +import { join } from 'node:path'; +import { tmpdir } from 'node:os'; +import test from 'node:test'; +import { promisify } from 'node:util'; +import { triggerJournal } from '../bin/trigger-journal.mjs'; +import { reconcileTriggers, recoverUncertainTriggers } from '../bin/trigger-transaction.mjs'; +const exec = promisify(execFile); + +test('concurrent processes cannot reserve the same trigger', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-journal-')); + t.after(() => rm(root, { recursive: true, force: true })); + const moduleUrl = new URL('../bin/trigger-journal.mjs', import.meta.url).href; + const script = `import { triggerJournal } from ${JSON.stringify(moduleUrl)}; await triggerJournal(process.argv[1]).begin({id: process.argv[2], triggers:[{kind:'timer',id:'one'}], dryRun:false});`; + const results = await Promise.allSettled(['first', 'second'].map(id => exec(process.execPath, ['--input-type=module', '-e', script, root, id]))); + assert.equal(results.filter(result => result.status === 'fulfilled').length, 1); + const rejected = results.find(result => result.status === 'rejected'); + assert.match(rejected.reason.stderr, /overlapping transaction unresolved|journal lock held/); +}); + +test('uncertain move remains reserved after journal re-open', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-journal-')); + t.after(() => rm(root, { recursive: true, force: true })); + const trigger = { kind: 'timer', id: 'one' }, journal = triggerJournal(root); + let calls = 0; + const adapter = { read: async () => ({ target: 'codex:old', version: 'v1' }), move: async () => { calls++; throw new Error('lost'); } }; + const receipt = await reconcileTriggers({ triggers: [trigger], from: 'codex:old', to: 'codex:new', transactionId: 'first', adapter, journal, dryRun: false }); + assert.equal(receipt.status, 'uncertain'); assert.equal(calls, 1); + const reopened = triggerJournal(root); + assert.equal((await reopened.get('first')).status, 'uncertain'); + await assert.rejects(reopened.begin({ id: 'second', triggers: [trigger], dryRun: false }), /overlapping/); + await assert.rejects(reopened.begin({ id: 'first', triggers: [trigger], dryRun: false }), /already reserved/); + assert.equal(calls, 1); +}); + +test('explicit recovery rolls back only a proven move after a lost response', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-recovery-')); + t.after(() => rm(root, { recursive: true, force: true })); + let state = { target: 'codex:old', version: 'v1' }, lose = true, calls = 0; + const adapter = { read: async () => structuredClone(state), move: async args => { + calls++; + if (state.target !== args.expectedTarget || state.version !== args.expectedVersion) return { status: 'not-applied' }; + state = { target: args.target, version: `v${calls + 1}`, lastOperationId: args.operationId }; + if (lose) { lose = false; throw new Error('response lost'); } + return { status: 'applied', version: state.version }; + } }; + const journal = triggerJournal(root), triggers = [{ kind: 'timer', id: 'one' }]; + const first = await reconcileTriggers({ triggers, from: 'codex:old', to: 'codex:new', transactionId: 'tx', adapter, journal, dryRun: false }); + assert.equal(first.status, 'uncertain'); assert.equal(state.target, 'codex:new'); + const recovered = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal: triggerJournal(root) }); + assert.equal(recovered.status, 'rolled-back'); assert.equal(state.target, 'codex:old'); assert.equal(calls, 2); + assert.equal((await triggerJournal(root).get('tx')).status, 'rolled-back'); +}); + +test('recovery refuses another writer before attempting any rollback', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-recovery-')); + t.after(() => rm(root, { recursive: true, force: true })); + let state = { target: 'codex:old', version: 'v1' }, calls = 0; + const adapter = { read: async () => structuredClone(state), move: async args => { calls++; state = { target: args.target, version: 'v2', lastOperationId: args.operationId }; throw new Error('lost'); } }; + const journal = triggerJournal(root); + await reconcileTriggers({ triggers: [{ kind: 'timer', id: 'one' }], from: 'codex:old', to: 'codex:new', transactionId: 'tx', adapter, journal, dryRun: false }); + state = { target: 'codex:new', version: 'v3', lastOperationId: 'other' }; + await assert.rejects(recoverUncertainTriggers({ transactionId: 'tx', adapter, journal }), /outside transaction/); + assert.equal(calls, 1); assert.equal((await journal.get('tx')).status, 'uncertain'); +}); + +test('recovery restores two proven moves in reverse order', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-recovery-')); + t.after(() => rm(root, { recursive: true, force: true })); + const state = new Map(['one', 'two'].map(id => [id, { target: 'codex:old', version: 'v1' }])); + const operations = []; let counter = 1, lose = true; + const adapter = { read: async ({ id }) => structuredClone(state.get(id)), move: async args => { + const current = state.get(args.id); + if (current.target !== args.expectedTarget || current.version !== args.expectedVersion) return { status: 'not-applied' }; + operations.push(args.operationId); + const next = { target: args.target, version: `v${++counter}`, lastOperationId: args.operationId }; + state.set(args.id, next); + if (args.id === 'two' && lose) { lose = false; throw new Error('response lost'); } + return { status: 'applied', version: next.version }; + } }; + const journal = triggerJournal(root), triggers = ['one', 'two'].map(id => ({ kind: 'timer', id })); + const uncertain = await reconcileTriggers({ triggers, from: 'codex:old', to: 'codex:new', transactionId: 'tx', adapter, journal, dryRun: false }); + assert.equal(uncertain.status, 'uncertain'); + const recovered = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal }); + assert.equal(recovered.status, 'rolled-back'); + assert.deepEqual(operations, ['tx:0', 'tx:1', 'tx:rollback:1', 'tx:rollback:0']); + assert.equal(state.get('one').target, 'codex:old'); assert.equal(state.get('two').target, 'codex:old'); +}); + +test('completed dry run releases scope, but not its transaction ID', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-journal-')); + t.after(() => rm(root, { recursive: true, force: true })); + const trigger = { kind: 'timer', id: 'one' }, journal = triggerJournal(root); + const adapter = { read: async () => ({ target: 'codex:old', version: 'v1' }), move: async () => { throw new Error('must not move'); } }; + const receipt = await reconcileTriggers({ triggers: [trigger], from: 'codex:old', to: 'codex:new', transactionId: 'dry', adapter, journal }); + assert.equal(receipt.status, 'dry-run'); + await journal.begin({ id: 'next', triggers: [trigger], dryRun: false }); + await assert.rejects(journal.begin({ id: 'dry', triggers: [trigger], dryRun: false }), /already reserved/); +}); + +test('journal refuses unsafe permissions, invalid state and abandoned locks', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-journal-')); + t.after(() => rm(root, { recursive: true, force: true })); + const journal = triggerJournal(root), reservation = { id: 'one', triggers: [], dryRun: true }; + await chmod(root, 0o755); + await assert.rejects(journal.begin(reservation), /private/); + await chmod(root, 0o700); + await writeFile(join(root, 'trigger-transactions.json'), '{broken', { mode: 0o600 }); + await assert.rejects(journal.begin(reservation)); + await writeFile(join(root, '.trigger-transactions.lock'), 'fixture', { mode: 0o600 }); + await assert.rejects(journal.begin(reservation), /lock held/); +}); + +test('preflight read failure is durably not-applied and releases the reservation', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-preflight-')); + t.after(() => rm(root, { recursive: true, force: true })); + const triggers = [{ kind: 'timer', id: 'one' }, { kind: 'timer', id: 'two' }]; + let moves = 0; + const adapter = { read: async ({ id }) => { if (id === 'two') throw new Error('offline'); return { target: 'codex:old', version: 'v1' }; }, move: async () => { moves++; } }; + const journal = triggerJournal(root); + const receipt = await reconcileTriggers({ triggers, from: 'codex:old', to: 'codex:new', transactionId: 'first', adapter, journal, dryRun: false }); + assert.equal(receipt.status, 'not-applied'); + assert.equal(receipt.triggers[1].status, 'unverified'); + assert.equal(moves, 0); + const stored = await triggerJournal(root).get('first'); + assert.equal(stored.status, 'not-applied'); + assert.equal(stored.receipt.reason, 'trigger source or version not verified'); + await triggerJournal(root).begin({ id: 'second', triggers, dryRun: true }); +}); + +test('lost forward readback is durable and can recover the proven move', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-readback-')); + t.after(() => rm(root, { recursive: true, force: true })); + let state = { target: 'codex:old', version: 'v1' }, reads = 0, moves = 0; + const adapter = { + read: async () => { if (++reads === 2) throw new Error('read unavailable'); return structuredClone(state); }, + move: async args => { + moves++; + assert.equal(state.target, args.expectedTarget); assert.equal(state.version, args.expectedVersion); + state = { target: args.target, version: `v${moves + 1}`, lastOperationId: args.operationId }; + return { status: 'applied', version: state.version }; + } + }; + const journal = triggerJournal(root), triggers = [{ kind: 'timer', id: 'one' }]; + const result = await reconcileTriggers({ triggers, from: 'codex:old', to: 'codex:new', transactionId: 'tx', adapter, journal, dryRun: false }); + assert.equal(result.status, 'uncertain'); assert.equal((await triggerJournal(root).get('tx')).status, 'uncertain'); + await assert.rejects(triggerJournal(root).begin({ id: 'other', triggers, dryRun: false }), /overlapping/); + const recovered = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal: triggerJournal(root) }); + assert.equal(recovered.status, 'rolled-back'); assert.equal(state.target, 'codex:old'); assert.equal(moves, 2); +}); + +test('lost rollback readback stays uncertain until the rollback is observed', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-readback-')); + t.after(() => rm(root, { recursive: true, force: true })); + const state = new Map(['one', 'two'].map(id => [id, { target: 'codex:old', version: 'v1' }])); + let failRead = false, moves = 0; + const adapter = { + read: async ({ id }) => { if (failRead) { failRead = false; throw new Error('read unavailable'); } return structuredClone(state.get(id)); }, + move: async args => { + moves++; + if (args.id === 'two' && args.target === 'codex:new') return { status: 'not-applied' }; + const current = state.get(args.id); + assert.equal(current.target, args.expectedTarget); assert.equal(current.version, args.expectedVersion); + const next = { target: args.target, version: `v${moves + 1}`, lastOperationId: args.operationId }; + state.set(args.id, next); + if (args.id === 'one' && args.operationId.includes(':rollback:')) failRead = true; + return { status: 'applied', version: next.version }; + } + }; + const journal = triggerJournal(root), triggers = ['one', 'two'].map(id => ({ kind: 'timer', id })); + const result = await reconcileTriggers({ triggers, from: 'codex:old', to: 'codex:new', transactionId: 'tx', adapter, journal, dryRun: false }); + assert.equal(result.status, 'uncertain'); assert.equal(state.get('one').target, 'codex:old'); + assert.equal((await triggerJournal(root).get('tx')).status, 'uncertain'); + const recovered = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal: triggerJournal(root) }); + assert.equal(recovered.status, 'rolled-back'); assert.equal(moves, 4); +}); + + +test('recovery fences a delayed forward CAS before declaring rollback', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-fence-')); + t.after(() => rm(root, { recursive: true, force: true })); + let state = { target: 'old', version: 'v1' }, release, entered; + const reached = new Promise(resolve => { entered = resolve; }); + const gate = new Promise(resolve => { release = resolve; }); + const adapter = { + read: async () => structuredClone(state), + move: async args => { + if (args.operationId === 'tx:0') { entered(); await gate; } + if (state.target !== args.expectedTarget || state.version !== args.expectedVersion) return { status: 'not-applied' }; + state = { target: args.target, version: 'v2', lastOperationId: args.operationId }; + return { status: 'applied', version: state.version }; + } + }; + const journal = triggerJournal(root), triggers = [{ kind: 'fixture', id: 'one' }]; + const writer = reconcileTriggers({ triggers, from: 'old', to: 'new', transactionId: 'tx', adapter, journal, dryRun: false }).catch(error => error); + await reached; + assert.equal((await journal.get('tx')).status, 'applying'); + const recovered = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal }); + assert.equal(recovered.status, 'rolled-back'); assert.equal(state.version, 'v2'); + release(); const staleWriter = await writer; + assert.match(staleWriter.message, /invalid journal update/); + assert.equal(state.target, 'old'); assert.equal(state.lastOperationId, 'tx:rollback:0'); + assert.equal((await journal.get('tx')).status, 'rolled-back'); +}); + +test('recovery refuses an adapter which reuses a version for the fence', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-fence-')); + t.after(() => rm(root, { recursive: true, force: true })); + const journal = triggerJournal(root), triggers = [{ kind: 'fixture', id: 'one' }]; + await journal.begin({ id: 'tx', triggers, dryRun: false }); + await journal.write({ schema: 'agent-mesh.trigger-transaction.v1', id: 'tx', from: 'old', to: 'new', dryRun: false, status: 'uncertain', triggers: [{ ...triggers[0], before: 'v1', status: 'uncertain' }] }); + let operation; + const adapter = { read: async () => ({ target: 'old', version: 'v1', lastOperationId: operation }), move: async args => { operation = args.operationId; return { status: 'applied', version: 'v1' }; } }; + const result = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal }); + assert.equal(result.status, 'uncertain'); + await assert.rejects(journal.begin({ id: 'other', triggers, dryRun: false }), /overlapping/); +}); + + +test('takeover of a crashed applying transaction rolls back a proven move', async t => { + const root = await mkdtemp(join(tmpdir(), 'trigger-crash-')); + t.after(() => rm(root, { recursive: true, force: true })); + const journal = triggerJournal(root), triggers = [{ kind: 'fixture', id: 'one' }]; + await journal.begin({ id: 'tx', triggers, dryRun: false }); + const interrupted = { schema: 'agent-mesh.trigger-transaction.v1', id: 'tx', from: 'old', to: 'new', dryRun: false, status: 'applying', triggers: [{ ...triggers[0], before: 'v1', status: 'applying', operationId: 'tx:0' }] }; + await journal.write(interrupted); + let state = { target: 'new', version: 'v2', lastOperationId: 'tx:0' }; + const adapter = { read: async () => structuredClone(state), move: async args => { + assert.equal(args.expectedTarget, state.target); assert.equal(args.expectedVersion, state.version); + state = { target: args.target, version: 'v3', lastOperationId: args.operationId }; + return { status: 'applied', version: state.version }; + } }; + const recovered = await recoverUncertainTriggers({ transactionId: 'tx', adapter, journal }); + assert.equal(recovered.status, 'rolled-back'); assert.equal(state.target, 'old'); + await assert.rejects(journal.write(interrupted, 0), /invalid journal update/); + assert.equal((await journal.get('tx')).epoch, 1); +}); diff --git a/packages/tmux-bridge/test/trigger-transaction.test.mjs b/packages/tmux-bridge/test/trigger-transaction.test.mjs new file mode 100644 index 00000000..92de450d --- /dev/null +++ b/packages/tmux-bridge/test/trigger-transaction.test.mjs @@ -0,0 +1,54 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { reconcileTriggers } from '../bin/trigger-transaction.mjs'; + +function fixture() { + const state = new Map(['one', 'two'].map(id => [id, { target: 'codex:old', version: 'v1' }])); + const records = []; let counter = 1, calls = 0, refuse = false, lose = false; + const adapter = { + read: async ({ id }) => structuredClone(state.get(id)), + move: async ({ id, expectedTarget, expectedVersion, target, operationId }) => { + calls++; + if (refuse && id === 'two') return { status: 'not-applied' }; + const old = state.get(id); + if (old.target !== expectedTarget || old.version !== expectedVersion) return { status: 'not-applied' }; + const next = { target, version: `v${++counter}`, lastOperationId: operationId }; + state.set(id, next); + if (lose && id === 'two') throw new Error('lost response'); + return { status: 'applied', version: next.version }; + } + }; + let reserved = false; + const journal = { begin: async () => { if (reserved) throw new Error('transaction already reserved'); reserved = true; }, write: async receipt => records.push(structuredClone(receipt)) }; + const run = (dryRun = false) => reconcileTriggers({ triggers: ['one', 'two'].map(id => ({ kind: 'timer', id })), from: 'codex:old', to: 'codex:new', transactionId: 'fixture', adapter, journal, dryRun }); + return { state, records, run, calls: () => calls, refuse: () => { refuse = true; }, lose: () => { lose = true; } }; +} + +test('dry run reads sources and records plan without moving triggers', async () => { + const f = fixture(), receipt = await f.run(true); + assert.equal(receipt.status, 'dry-run'); assert.equal(f.calls(), 0); + assert.equal(f.state.get('one').target, 'codex:old'); +}); + +test('each move is recorded before invocation and verified by operation identity', async () => { + const f = fixture(), receipt = await f.run(); + assert.equal(receipt.status, 'verified'); + assert.deepEqual(receipt.triggers.map(row => row.status), ['verified', 'verified']); + assert.ok(f.records.some(item => item.triggers[0].status === 'applying')); + assert.equal(f.state.get('two').target, 'codex:new'); +}); + +test('a definite refusal rolls back earlier verified moves', async () => { + const f = fixture(); f.refuse(); const receipt = await f.run(); + assert.equal(receipt.status, 'rolled-back'); + assert.equal(receipt.triggers[0].status, 'rolled-back'); + assert.equal(f.state.get('one').target, 'codex:old'); +}); + +test('a lost response is uncertain and is never retried or falsely rolled back', async () => { + const f = fixture(); f.lose(); const receipt = await f.run(); + assert.equal(receipt.status, 'uncertain'); assert.equal(f.calls(), 2); + await assert.rejects(f.run(), /already reserved/); + assert.equal(receipt.triggers[1].status, 'uncertain'); + assert.equal(f.state.get('one').target, 'codex:new'); +}); diff --git a/scripts/mesh-readiness.mjs b/scripts/mesh-readiness.mjs index 654f1d9e..d021df83 100755 --- a/scripts/mesh-readiness.mjs +++ b/scripts/mesh-readiness.mjs @@ -2,9 +2,14 @@ import { readFileSync, readdirSync, statSync } from "node:fs"; import path from "node:path"; import { fileURLToPath } from "node:url"; +import { execFileSync } from "node:child_process"; import { parseMeshV1Envelope, planMeshV1Dispatch } from "../packages/core/src/policy.js"; +import { containsPrivatePlexusPolicy, isGeneratedPythonBytecode, isPlexusMechanismFile } from "./plexus-privacy.mjs"; +import { plexusDiagram } from "./plexus-diagram.mjs"; const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); +let trackedFiles = null; +try { trackedFiles = new Set(execFileSync("git", ["ls-files", "-z"], { cwd: root, encoding: "utf8" }).split("\0")); } catch { /* Without Git, scan every file. */ } const checks = []; const agentTmuxBundleFiles = [ "bin/agent-mesh", @@ -19,10 +24,13 @@ const agentTmuxBundleFiles = [ "bin/agent-read.sh", "bin/agent-follow.py", "bin/agent-watch.py", + "bin/agent-waker.py", "bin/agent-send.sh", "bin/agent-spawn.sh", "bin/agent-session.sh", "bin/agent-native-call.mjs", + "bin/cloud-account-binding.mjs", + "bin/codex-app-server.mjs", "bin/codex-goal.mjs", "bin/agent-goal.mjs", "bin/claude-goal.mjs", @@ -37,6 +45,18 @@ const agentTmuxBundleFiles = [ "bin/mesh-capacity-dispatch.mjs", "bin/mesh-graph.mjs", "bin/plexus.mjs", + "bin/channel-state.mjs", + "bin/claude-delivery-observation.mjs", + "bin/handover-state-proof.mjs", + "bin/handover-notice.mjs", + "bin/handover-dry-run.mjs", + "bin/handover-codex-observation.mjs", + "bin/codex-compaction-evidence.mjs", + "bin/codex-wake-evidence.mjs", + "bin/restart-state.mjs", + "bin/role-launch-profile.mjs", + "bin/role-mcp-probe.mjs", + "bin/restart-yaml.py", "bin/ledger-view.mjs", "bin/session-catalog.mjs", "bin/session-links.mjs", @@ -61,6 +81,7 @@ const agentTmuxBundleFiles = [ const snowflakeIdPattern = /\b(?!([0-9])\1{16,19}\b)\d{17,20}\b/; function check(name, fn) { try { fn(); checks.push({ name, ok: true }); } catch (error) { checks.push({ name, ok: false, error: error.message }); } } function assert(condition, message) { if (!condition) throw new Error(message); } +check("Plexus architecture diagram sync", () => { assert(readFileSync(path.join(root, "docs/design/plexus-architecture.mmd"), "utf8") === plexusDiagram, "Plexus architecture diagram differs from its source"); }); check("parse Mesh v1 headers", () => { const envelope = parseMeshV1Envelope("cc-mesh: alpha\ncc-mesh-from: beta\ncc-mesh-id: ready-1\ncc-mesh-turn: alpha\ncc-mesh-final: false\nhop-limit: 2\n\nhello"); assert(envelope.valid, `expected valid envelope: ${envelope.errors.join(",")}`); assert(envelope.final === false, "expected partial final flag"); assert(envelope.hopLimit === 2, "expected hop limit parse"); }); check("parse compact ccm:v1 headers", () => { const envelope = parseMeshV1Envelope("<@123>\nccm:v1 id=ready-compact from=beta turn=alpha final=1 seen=beta hop=2\n\nhello"); assert(envelope.valid, `expected valid compact envelope: ${envelope.errors.join(",")}`); assert(envelope.format === "ccm:v1", "expected compact format marker"); assert(envelope.final === true, "expected compact final flag"); assert(envelope.to[0] === "alpha", "expected compact turn to become recipient"); assert(envelope.body === "hello", "expected compact body parse"); }); check("partial buffers only", () => { const plan = planMeshV1Dispatch({ localParticipant: "alpha" }, { messageId: "ready-m1", text: "cc-mesh: alpha\ncc-mesh-from: beta\ncc-mesh-id: ready-2\ncc-mesh-turn: alpha\ncc-mesh-final: false\n\npart" }); assert(plan.nextAction === "buffer_only", `expected buffer_only got ${plan.nextAction}`); assert(!plan.dispatchText, "partial must not dispatch text"); }); @@ -69,7 +90,8 @@ check("duplicate final suppressed", () => { const final = planMeshV1Dispatch({ l check("turn gate fails closed", () => { const plan = planMeshV1Dispatch({ localParticipant: "alpha" }, { text: "cc-mesh: alpha\ncc-mesh-from: beta\ncc-mesh-id: ready-5\ncc-mesh-turn: gamma\ncc-mesh-final: true\n\nhello" }); assert(plan.reason === "mesh_v1_not_local_turn", `expected turn gate got ${plan.reason}`); }); check("seen loop guard fails closed", () => { const plan = planMeshV1Dispatch({ localParticipant: "alpha" }, { text: "cc-mesh: alpha\ncc-mesh-from: beta\ncc-mesh-id: ready-6\ncc-mesh-turn: alpha\ncc-mesh-final: true\ncc-mesh-seen: beta,alpha\n\nhello" }); assert(plan.reason === "mesh_v1_loop_guard_seen", `expected loop guard got ${plan.reason}`); }); check("privacy snowflake rule ignores repeated placeholders", () => { assert(!snowflakeIdPattern.test("111111111111111111"), "repeated-digit placeholder must not be flagged"); assert(!snowflakeIdPattern.test("222222222222222222"), "repeated-digit placeholder must not be flagged"); assert(snowflakeIdPattern.test("123456789" + "012345678"), "mixed-digit snowflake-shaped ID must be flagged"); }); -check("public-tree privacy sanity", () => { const deny = [snowflakeIdPattern, new RegExp("/home/operator/env/workspace/iter" + "modus/"), /(api[_-]?key|secret|password|token)\s*[:=]\s*["'][^"']{6,}["']/i]; const privateIdentifiers = ["ti" + "rrenia", "od" + "ino", "iter" + "modus"]; const skipDirs = new Set([".git", "node_modules", "dist"]); const skipPaths = new Set([".syncwheel/ledger"]); const hits = []; function walk(dir) { if (skipPaths.has(path.relative(root, dir))) return; for (const entry of readdirSync(dir)) { if (skipDirs.has(entry)) continue; const full = path.join(dir, entry); const stat = statSync(full); if (stat.isDirectory()) walk(full); else if (stat.isFile()) { const text = readFileSync(full, "utf8"); for (const pattern of deny) if (pattern.test(text)) hits.push(path.relative(root, full)); if (privateIdentifiers.some((identifier) => text.toLowerCase().includes(identifier))) hits.push(path.relative(root, full)); } } } walk(root); assert(hits.length === 0, `privacy scan hits: ${[...new Set(hits)].join(", ")}`); }); +check("public-tree privacy sanity", () => { const deny = [snowflakeIdPattern, new RegExp("/home/operator/env/workspace/iter" + "modus/"), /(api[_-]?key|secret|password|token)\s*[:=]\s*["'][^"']{6,}["']/i]; const privateIdentifiers = ["ti" + "rrenia", "od" + "ino", "iter" + "modus"]; const skipDirs = new Set([".git", "node_modules", "dist"]); const skipPaths = new Set([".syncwheel/ledger"]); const hits = []; function walk(dir) { if (skipPaths.has(path.relative(root, dir))) return; for (const entry of readdirSync(dir)) { if (skipDirs.has(entry)) continue; const full = path.join(dir, entry); const stat = statSync(full); if (stat.isDirectory()) walk(full); else if (stat.isFile() && !isGeneratedPythonBytecode(path.relative(root, full), trackedFiles)) { const text = readFileSync(full, "utf8"); for (const pattern of deny) if (pattern.test(text)) hits.push(path.relative(root, full)); if (privateIdentifiers.some((identifier) => text.toLowerCase().includes(identifier))) hits.push(path.relative(root, full)); } } } walk(root); assert(hits.length === 0, `privacy scan hits: ${[...new Set(hits)].join(", ")}`); }); +check("Plexus mechanism privacy", () => { const hits = []; const skip = new Set([".git", "node_modules", "dist", "var"]); function walk(dir) { for (const entry of readdirSync(dir)) { if (skip.has(entry)) continue; const full = path.join(dir, entry), stat = statSync(full); if (stat.isDirectory()) walk(full); else if (stat.isFile()) { const relative = path.relative(root, full); if (isPlexusMechanismFile(relative) && containsPrivatePlexusPolicy(readFileSync(full, "utf8"))) hits.push(relative); } } } walk(root); assert(hits.length === 0, `Plexus privacy scan hits: ${hits.join(", ")}`); }); check("agent-tmux skill bundle sync", () => { const drifted = agentTmuxBundleFiles.filter((relativePath) => { try { return !readFileSync(path.join(root, "packages/tmux-bridge", relativePath)).equals(readFileSync(path.join(root, "skills/agent-tmux", relativePath))); } catch { return true; } }); assert(drifted.length === 0, `agent-tmux skill bundle drift: ${drifted.join(", ")}`); }); for (const result of checks) console.log(`${result.ok ? "PASS" : "FAIL"} ${result.name}${result.ok ? "" : `: ${result.error}`}`); if (checks.some((result) => !result.ok)) process.exit(1); diff --git a/scripts/plexus-diagram.mjs b/scripts/plexus-diagram.mjs new file mode 100644 index 00000000..00ece577 --- /dev/null +++ b/scripts/plexus-diagram.mjs @@ -0,0 +1,36 @@ +// Update this diagram together with the public architecture when it changes. +export const plexusDiagram = `flowchart LR + Client["Client or waker"] -- "channel mode" --> Channel["Stable channel"] + Channel --> Queue["Channel queue"] + Channel --> Session["Current session"] + Queue --> Journal["Graph event journal"] + Session --> Journal + Wake["Codex queued wake evidence"] --> Journal + Wake -. "planned waker integration" .-> Queue + Compaction["Codex compaction evidence"] --> Journal + Module["Registered module"] --> Contract["Versioned JSON contract"] + Contract --> Journal + Queue -- "bound receipt" --> Session + CloudAccount["Cloud account binding"] -. "planned routing" .-> Queue + Yaml["Bounded YAML decoder"] --> Restart + Restart["Restart state contract"] --> StatePrep["Reserved state preparation"] + Restart --> RoleProfile["Role-scoped launch plan"] + RoleProfile -. "synthetic rehearsal" .-> Rehearsal["In-memory handover rehearsal"] + RoleProfile -. "isolated assessment" .-> IsolatedRollback["Owned isolated rollback"] + IsolatedRollback -. "live handover blocked" .-> Handover + RoleProfile -. "planned runtime launch" .-> Handover + StatePrep --> Journal + StatePrep --> Revalidate["Restart state revalidation"] + Revalidate -. "planned lifecycle exclusion" .-> Handover + TriggerTxn["Trigger transaction engine"] --> TriggerJournal["Private trigger journal"] + TriggerRecovery["Explicit uncertain recovery"] --> TriggerJournal + TriggerTxn -. "planned scheduler adapters" .-> Handover + Notice["Successor notice formatter"] -. "planned publication" .-> Handover + Observation["Codex notice snapshot"] -. "planned finality check" .-> Handover + Handover["Handover"] -. "planned verified cutover" .-> Channel + Channel -. "pure switch model" .-> Drain["Observe queued deliveries"] + Drain -. "then reserve" .-> Notice + AutoWake["Auto-wake observation disabled"] -. "consumption unproven" .-> Wake + Wake -. "bound native proof" .-> Drain + ClaudeReadback["Local Claude transcript observer"] -. "observed inbox record" .-> Drain +`; diff --git a/scripts/plexus-privacy.mjs b/scripts/plexus-privacy.mjs new file mode 100644 index 00000000..1a2a8542 --- /dev/null +++ b/scripts/plexus-privacy.mjs @@ -0,0 +1,20 @@ +// Public mechanism files must not embed private deployment policy or identifiers. +const privatePatterns = [ + new RegExp('gale' + 'haut', 'i'), + new RegExp('management:' + 'MGT-[0-9]+', 'i'), + new RegExp('/home/' + 'administrator(?:/|\\b)', 'i'), +]; + +export function isPlexusMechanismFile(relativePath) { + return /^(?:docs\/design\/plexus[-.]|packages\/tmux-bridge\/README\.md$|(?:packages\/tmux-bridge\/(?:bin|examples|test)|skills\/agent-tmux\/bin)\/(?:plexus[-.]|channel-|claude-delivery-|cloud-(?:account|native)-|codex-(?:compaction|wake)-|module-batches|mesh-(?:graph|channel)|agent-waker|role-(?:launch|mcp)-|session-(?:sleep|handover)|(?:sleep|handover|restart)-))/.test(relativePath); +} + +export function containsPrivatePlexusPolicy(text) { + return privatePatterns.some((pattern) => pattern.test(text)); +} + +// Python writes interpreter-specific binary caches while the test suite runs. +// Keep scanning any source files placed in such directories. +export function isGeneratedPythonBytecode(relativePath, trackedFiles) { + return trackedFiles instanceof Set && !trackedFiles.has(relativePath) && /(?:^|\/)__pycache__\/[^/]+\.cpython-\d+(?:\.opt-\d+)?\.pyc$/.test(relativePath); +} diff --git a/skills/agent-tmux/bin/agent-native-call.mjs b/skills/agent-tmux/bin/agent-native-call.mjs index 558bb24f..1bcc339c 100755 --- a/skills/agent-tmux/bin/agent-native-call.mjs +++ b/skills/agent-tmux/bin/agent-native-call.mjs @@ -4,6 +4,7 @@ import { commsLease } from "./comms-client.mjs"; import { createHash } from "node:crypto"; import { execFile } from "node:child_process"; +import { readSync } from "node:fs"; import { access, open, readdir, stat } from "node:fs/promises"; import { homedir } from "node:os"; import { join, resolve } from "node:path"; @@ -12,6 +13,8 @@ import { parseArgs } from "node:util"; import { inspectClaudeSessionOwnership } from "./claude-session-ownership.mjs"; import { goalCommand, liveClaudeSessions, typeClaudeGoal } from "./claude-goal.mjs"; import { GOAL_RESUME_MODES, reconcileCodexGoal } from "./codex-goal.mjs"; +import { withCodexAppServer } from "./codex-app-server.mjs"; +import { loadClaudeAccountProfile, withClaudeAccount } from "./cloud-account-binding.mjs"; let activeComms; let enqueueStarted = false; @@ -24,12 +27,16 @@ const { values } = parseArgs({ timeout: { type: "string", default: "120" }, "delivery-only": { type: "boolean", default: false }, cloud: { type: "boolean", default: false }, + "cloud-profile": { type: "string" }, + "cloud-scope": { type: "string" }, + "cloud-profile-digest": { type: "string" }, "steer-or-queue": { type: "boolean", default: false }, resume: { type: "boolean", default: false }, "no-resume": { type: "boolean", default: false }, goal: { type: "string" }, "goal-resume": { type: "string", default: "blocked" }, message: { type: "string" }, + "message-stdin": { type: "boolean", default: false }, "managed-inbox-root": { type: "string" }, help: { type: "boolean", short: "h", default: false } }, @@ -37,14 +44,15 @@ const { values } = parseArgs({ }); if (values.help) { - console.log("Usage: agent-native-call.mjs --agent codex|claude --session --correlation-id --message [--timeout ] [--resume (Codex only)] [--cloud --delivery-only (Claude cloud only)] [--steer-or-queue (Codex only)] [--goal TEXT (Codex, local Claude)] [--goal-resume blocked|any|off (Codex only)] [--delivery-only]"); + console.log("Usage: agent-native-call.mjs --agent codex|claude --session --correlation-id (--message | --message-stdin) [--timeout ] [--resume (Codex only)] [--cloud --delivery-only (Claude cloud only)] [--steer-or-queue (Codex only)] [--goal TEXT (Codex, local Claude)] [--goal-resume blocked|any|off (Codex only)] [--delivery-only]"); process.exit(0); } const agent = required(values.agent, "--agent"); const sessionId = required(values.session, "--session"); const correlationId = required(values["correlation-id"], "--correlation-id"); -const message = required(values.message, "--message"); +if (values["message-stdin"] && values.message !== undefined) fail("--message and --message-stdin are mutually exclusive", 2); +const message = values["message-stdin"] ? required(readMessageStdin(), "--message-stdin") : required(values.message, "--message"); const timeoutSeconds = Number(values.timeout); if (agent !== "codex" && agent !== "claude") fail(`native active-session calls are not implemented for agent ${agent}`, 2); if (values.resume && values["no-resume"]) fail("--resume and --no-resume are mutually exclusive", 2); @@ -64,6 +72,8 @@ const goalOptions = agent === "codex" ? { objective: values.goal?.trim(), resume if (values.cloud && (agent !== "claude" || !values["delivery-only"] || values.resume || values["managed-inbox-root"])) { fail("--cloud requires --agent claude --delivery-only, without --resume or --managed-inbox-root", 2); } +if ((!values.cloud && (values["cloud-profile"] || values["cloud-scope"] || values["cloud-profile-digest"])) || Boolean(values["cloud-profile"]) !== Boolean(values["cloud-scope"]) || (values["cloud-profile-digest"] && !values["cloud-profile"])) fail("cloud profile and scope must be supplied together for cloud transport", 2); +const cloudProfile = values["cloud-profile"] ? await loadClaudeAccountProfile(values["cloud-profile"], values["cloud-scope"], values["cloud-profile-digest"]) : undefined; if (values.cloud ? !/^(session|cse)_[A-Za-z0-9]{1,128}$/.test(sessionId) : !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(sessionId)) { fail(values.cloud ? "--session must be an exact session_ or cse_ cloud ID" : "--session must be a complete UUID", 2); @@ -83,6 +93,7 @@ const protocolMessage = values["delivery-only"] ? message : `${anchor} Use the r const comms = await commsLease({ kind: 'native', runtime: agent, destination: sessionId, correlation: correlationId, message: protocolMessage, inbox_root: values['managed-inbox-root'], resume, ...(values.cloud ? { cloud: true } : {}), + ...(cloudProfile ? { cloud_profile: values['cloud-profile'], cloud_scope: values['cloud-scope'], cloud_profile_digest: cloudProfile.digest } : {}), ...(values["steer-or-queue"] ? { steer_first: true } : {}), ...(goalOptions?.objective ? { goal: goalOptions.objective } : {}), ...(goalOptions?.resume && goalOptions.resume !== "blocked" ? { goal_resume: goalOptions.resume } : {}) }); @@ -96,10 +107,17 @@ if (comms.status !== 'send') { // Cloud follow-ups have a provider queue acknowledgement, but no local transcript. // All failures after invoking the provider retain the gate's unknown receipt. if (values.cloud) { - enqueueStarted = true; - const sent = await run(process.env.CLAUDE_BIN || "claude", [ - "-p", "--cloud", sessionId, "--output-format", "json" - ], timeoutSeconds * 1000, message); + let sent; + if (cloudProfile) { + sent = await withClaudeAccount(cloudProfile.profile, async binding => { + enqueueStarted = true; + return run(binding.command, ["-p", "--cloud", sessionId, "--output-format", "json"], timeoutSeconds * 1000, message, { ...process.env, CLAUDE_CONFIG_DIR: binding.configDir }); + }); + await loadClaudeAccountProfile(values["cloud-profile"], values["cloud-scope"], cloudProfile.digest); + } else { + enqueueStarted = true; + sent = await run(process.env.CLAUDE_BIN || "claude", ["-p", "--cloud", sessionId, "--output-format", "json"], timeoutSeconds * 1000, message); + } let receipt; try { receipt = JSON.parse(sent.stdout); } catch { /* Unproven acceptance. */ } if (sent.code !== 0 || receipt?.ok !== true || receipt.session_id !== sessionId) { @@ -124,6 +142,7 @@ let resumeDiagnostic = false; let transportAccepted = false; let deliveryMethod; let steeredTurnId; +let nativeQueueId; try { if (agent === "codex") { if (values["steer-or-queue"]) { @@ -150,16 +169,35 @@ if (agent === "codex") { } if (deliveryMethod !== "steer") { enqueueStarted = true; - const queued = await run(process.env.CODEX_BIN || "codex", [ - "queue", "--thread", sessionId, "--message", protocolMessage, ...(resume ? ["--resume"] : []) - ], (timeoutSeconds + 15) * 1000); - if (queued.code !== 0) { - if (codexSessionIsNotDirectlyWritable(queued)) { - fail("Codex spawned sub-agent sessions are readable but do not accept direct queued turns.", 79); + if (values["message-stdin"] && !values["steer-or-queue"]) { + try { + await withCodexAppServer({ clientName: "agent-mesh-channel-queue", timeout: (timeoutSeconds + 15) * 1000, + timeoutMessage: "queue outcome unknown; inspect before retrying" }, async (request) => { + const input = [{ type: "text", text: protocolMessage, text_elements: [] }]; + const response = await request("thread/queue/add", { threadId: sessionId, clientUserMessageId: correlationId, input }); + const entry = response?.queuedSubmission; + if (typeof entry?.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(entry.id) || entry.clientUserMessageId !== correlationId || JSON.stringify(entry.input) !== JSON.stringify(input)) throw new Error("queue receipt mismatch"); + nativeQueueId = entry.id; + if (resume) { + try { await request("thread/resume", { threadId: sessionId }); } + catch { resumeDiagnostic = true; } + } + }); + } catch { + fail("Codex queue outcome uncertain; inspect before retrying", 70); } - fail(safeError("Codex native queue failed", queued), 1); + } else { + const queued = await run(process.env.CODEX_BIN || "codex", [ + "queue", "--thread", sessionId, "--message", protocolMessage, ...(resume ? ["--resume"] : []) + ], (timeoutSeconds + 15) * 1000); + if (queued.code !== 0) { + if (codexSessionIsNotDirectlyWritable(queued)) { + fail("Codex spawned sub-agent sessions are readable but do not accept direct queued turns.", 79); + } + fail(safeError("Codex native queue failed", queued), 1); + } + resumeDiagnostic = Boolean(resume && queued.stderr?.trim()); } - resumeDiagnostic = Boolean(resume && queued.stderr?.trim()); deliveryMethod = "queue"; } } else { @@ -185,6 +223,7 @@ const goal = goalOptions ? await applyGoal(agent, sessionId, goalOptions) : unde // Queue acknowledgement is transport proof, never proof that the turn ran. if (values["delivery-only"]) { console.log(JSON.stringify({ status: deliveryMethod === "steer" ? "steered" : "queued", agent, sessionId, correlationId, + ...(nativeQueueId ? { nativeQueueId } : {}), ...(values["steer-or-queue"] ? { deliveryMethod, ...(steeredTurnId ? { turnId: steeredTurnId } : {}) } : {}), ...(goal ? { goal } : {}), ...(resume && deliveryMethod === "queue" ? { resumeRequested: true, resumeVerified: false, resumeDiagnostic } : {}) })); @@ -272,6 +311,20 @@ function finish(bodies, begin, end) { process.exit(0); } +function readMessageStdin() { + const max = 65536, chunks = []; + let total = 0; + for (;;) { + const chunk = Buffer.allocUnsafe(Math.min(4096, max + 1 - total)); + const count = readSync(0, chunk, 0, chunk.length, null); + if (!count) break; + total += count; + if (total > max) fail("stdin message too large", 2); + chunks.push(chunk.subarray(0, count)); + } + return Buffer.concat(chunks).toString("utf8"); +} + function messageText(record, role) { const payload = record?.payload; if (record?.type === "event_msg") { @@ -354,9 +407,9 @@ async function consumeTranscript(path, start) { } } -function run(command, args, timeoutMs, input) { +function run(command, args, timeoutMs, input, env = process.env) { return new Promise((resolveRun) => { - const child = execFile(command, args, { timeout: timeoutMs, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => { + const child = execFile(command, args, { timeout: timeoutMs, maxBuffer: 1024 * 1024, env }, (error, stdout, stderr) => { resolveRun({ code: error && typeof error.code === "number" ? error.code : error ? 1 : 0, stdout: typeof stdout === "string" ? stdout : "", diff --git a/skills/agent-tmux/bin/agent-session-inbox.py b/skills/agent-tmux/bin/agent-session-inbox.py index 3dc205cd..fc161036 100755 --- a/skills/agent-tmux/bin/agent-session-inbox.py +++ b/skills/agent-tmux/bin/agent-session-inbox.py @@ -23,6 +23,10 @@ DUPLICATE = "AGENT_MESH_INBOX_DUPLICATE do-not-relaunch" +class HookBudgetExpired(TimeoutError): + pass + + def process_identity(pid): """Use kernel start ticks as well as PID, so PID reuse is not ownership.""" if not isinstance(pid, int) or pid <= 1: @@ -434,7 +438,7 @@ def main(): return if args.mode in {'hook', 'status'}: def expire(_signum, _frame): - raise TimeoutError('hook budget expired') + raise HookBudgetExpired('hook budget expired') previous = signal.signal(signal.SIGALRM, expire) signal.setitimer(signal.ITIMER_REAL, 0.2) try: @@ -446,6 +450,11 @@ def expire(_signum, _frame): if not active: raise ValueError('no live owner-bound supervisor') print(json.dumps(active)) + except HookBudgetExpired: + if os.environ.get('AGENT_MESH_INBOX_DIAGNOSTICS') == '1': + print('agent-session-inbox: hook budget expired', file=sys.stderr, flush=True) + if args.mode == 'status': + raise SystemExit(1) except Exception: if args.mode == 'status': raise SystemExit(1) diff --git a/skills/agent-tmux/bin/agent-waker.py b/skills/agent-tmux/bin/agent-waker.py index 612af5cd..10db0928 100644 --- a/skills/agent-tmux/bin/agent-waker.py +++ b/skills/agent-tmux/bin/agent-waker.py @@ -11,6 +11,8 @@ import hashlib import json import os +import re +import stat from pathlib import Path import subprocess import sys @@ -116,24 +118,33 @@ def compose(job: str, pending: list[dict[str, Any]], errors: list[Any]) -> str: return "\n".join(lines) -def deliver(agent: str, session: str, correlation: str, message: str, inbox_root: str | None, delivery_only: bool = False, resume: bool = False) -> int: +def deliver(agent: str, session: str, correlation: str, message: str, inbox_root: str | None, delivery_only: bool = False, resume: bool = False, message_stdin: bool = False, receipt_out: dict | None = None, cloud_profile: str | None = None, cloud_scope: str | None = None) -> int: command = ["node", str(BIN / "agent-native-call.mjs"), "--agent", agent, "--session", session, - "--correlation-id", correlation, "--timeout", "5", "--message", message] + "--correlation-id", correlation, "--timeout", "5"] + command += ["--message-stdin"] if message_stdin else ["--message", message] + if cloud_profile or cloud_scope: + if not (cloud_profile and cloud_scope and agent == "claude" and delivery_only and message_stdin and not resume and not inbox_root): + raise ValueError("invalid cloud delivery options") + command += ["--cloud", "--cloud-profile", cloud_profile, "--cloud-scope", cloud_scope] if resume: if agent != "codex": raise ValueError("waker resume is supported only for Codex") command += ["--resume"] + elif message_stdin and agent == "codex": + command += ["--no-resume"] if delivery_only: command += ["--delivery-only"] if inbox_root: command += ["--managed-inbox-root", inbox_root] - result = subprocess.run(command, text=True, capture_output=True) + result = subprocess.run(command, text=True, capture_output=True, **({"input": message} if message_stdin else {})) try: receipt = json.loads(result.stdout) except (ValueError, TypeError): receipt = None bound = (isinstance(receipt, dict) and receipt.get("agent") == agent and receipt.get("sessionId") == session and receipt.get("correlationId") == correlation) + if cloud_profile and isinstance(receipt, dict) and receipt.get("status") == "queued" and (receipt.get("transport") != "claude-cloud" or receipt.get("readBack") is not False): + return 78 if delivery_only and isinstance(receipt, dict) and receipt.get("status") == "queued" and not bound: return 78 # A comms hold can exit zero: process success is not native queue acceptance. @@ -149,6 +160,12 @@ def deliver(agent: str, session: str, correlation: str, message: str, inbox_root return 78 if delivery_only and (not isinstance(receipt, dict) or receipt.get("status") != "queued"): return 78 + if delivery_only and receipt_out is not None and result.returncode == 0 and bound: + native_id = receipt.get('nativeQueueId') + if native_id is not None: + if agent != 'codex' or not isinstance(native_id, str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._:-]{0,127}', native_id): + return 78 + receipt_out['nativeQueueId'] = native_id return result.returncode @@ -158,7 +175,213 @@ def record(job: str, outcome: str, session: str, note: str) -> None: capture_output=True) +def channel_call(args: argparse.Namespace, operation: str, *options: str) -> dict[str, Any]: + command = ['node', str(BIN / 'mesh-graph.mjs')] + if args.graph_state: + command += ['--state', args.graph_state] + arguments = list(options) + payload = None + if '--input' in arguments: + index = arguments.index('--input') + 1 + payload = arguments[index] + arguments[index] = '-' + command += ['channel', operation, '--name', args.channel, *arguments] + result = subprocess.run(command, input=payload, text=True, capture_output=True, timeout=30, check=True) + value = json.loads(result.stdout) + if not isinstance(value, dict) or not isinstance(value.get('channel'), dict): + raise ValueError('invalid channel response') + return value['channel'] + + +def observe_claude_channel_delivery(args: argparse.Namespace, message_id: str, recovery: bool = False) -> None: + command = ['node', str(BIN / 'mesh-graph.mjs')] + if args.graph_state: + command += ['--state', args.graph_state] + operation = 'recover-claude-delivery' if recovery else 'observe-claude-delivery' + command += ['channel', operation, '--name', args.channel, '--id', message_id] + result = subprocess.run(command, text=True, capture_output=True, timeout=30, check=True) + value = json.loads(result.stdout) + allowed = ('accepted', 'observed') if recovery else ('observed',) + if not isinstance(value, dict) or value.get('status') not in allowed or value.get('channel') != args.channel or value.get('messageId') != message_id: + raise ValueError('invalid delivery observation') + + +def preflight_codex_channel_wake(item: dict[str, Any], channel: dict[str, Any]) -> bool: + session = channel['session'] + if not session.startswith('codex:'): + raise ValueError('invalid Codex wake target') + command = ['node', str(BIN / 'codex-wake-evidence.mjs'), '--preflight', '--thread', session[6:], + '--queue-id', item['nativeQueueId'], '--correlation', item['id']] + result = subprocess.run(command, text=True, capture_output=True, timeout=20, check=True) + value = json.loads(result.stdout) + if not isinstance(value, dict) or value.get('schema') != 'agent-mesh.wake-preflight.v1' or value.get('session') != session or value.get('queueId') != item['nativeQueueId'] or value.get('correlation') != item['id'] or value.get('status') not in ('ready', 'not-ready'): + raise ValueError('invalid wake preflight') + return value['status'] == 'ready' + + +def start_codex_channel_wake(args: argparse.Namespace, item: dict[str, Any], channel: dict[str, Any]) -> str: + session = channel['session'] + if not session.startswith('codex:') or not args.graph_state or not os.path.isabs(args.graph_state) or not os.path.isabs(args.wake_evidence_root): + raise ValueError('explicit private wake and graph roots required') + command = ['node', str(BIN / 'codex-wake-evidence.mjs'), '--apply', '--thread', session[6:], + '--queue-id', item['nativeQueueId'], '--correlation', item['id'], '--channel', args.channel, + '--generation', str(channel['generation']), '--evidence-root', args.wake_evidence_root, + '--graph-state', args.graph_state] + result = subprocess.run(command, text=True, capture_output=True, timeout=45, check=True) + value = json.loads(result.stdout) + if not isinstance(value, dict) or value.get('schema') != 'agent-mesh.wake-record.v1' or value.get('session') != session or value.get('settled') is not True or not re.fullmatch(r'codex-wake:[a-f0-9]{64}', str(value.get('evidence', ''))): + raise ValueError('wake proof not verified') + return value['evidence'] + + +def cloud_target(target: str, root: str | None) -> tuple[str, str, str]: + match = re.fullmatch(r'claude-cloud:([a-z][a-z0-9-]{0,63}):((?:session|cse)_[A-Za-z0-9]{1,128})', target) + if not match or not root: + raise ValueError('unsupported cloud recipient') + directory = Path(root) + if not directory.is_absolute() or directory.resolve() != directory: + raise ValueError('invalid cloud profile root') + info = directory.lstat() + if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077: + raise ValueError('insecure cloud profile root') + scope, session = match.groups() + profile = directory / f'{scope}.json' + info = profile.lstat() + if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1 or info.st_uid != os.getuid() or info.st_mode & 0o077: + raise ValueError('insecure cloud profile') + return session, str(profile), scope + + +def run_channel(args: argparse.Namespace) -> int: + path = Path(args.state) if args.state else state_dir() / f'{args.job}.json' + with locked(path) as acquired: + if not acquired: + print(json.dumps({'job': args.job, 'outcome': 'noop', 'reason': 'previous run still active'})) + return 0 + state, state_errors = load_state(path) + if state_errors: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'unreadable waker state'})) + return 3 + new, errors = run_producer(args.producer, args.producer_timeout) + errors = state_errors + errors + known = {entry['key'] for entry in state['pending']} + for item in new: + key = item_key(item) + if key not in known: + known.add(key) + state['pending'].append({'key': key, 'item': item}) + signature = error_signature(errors) + wake_errors = errors if signature and signature != state.get('errorSignature') else [] + if not errors: + state['errorSignature'] = None + flight = state.get('inFlight') + recipient = {'channel': args.channel} + if flight and flight.get('recipient') != recipient: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'in-flight recipient changed'})) + return 3 + if not flight and (state['pending'] or wake_errors): + flight = {'correlationId': f'waker-{uuid.uuid4()}', 'recipient': recipient, + 'message': compose(args.job, state['pending'], wake_errors), + 'itemKeys': [entry['key'] for entry in state['pending'][:MAX_LISTED]], 'errorSignature': signature} + state['inFlight'] = flight + save_state(path, state) + try: + if flight: + channel_call(args, 'enqueue', '--id', flight['correlationId'], '--input', flight['message']) + accepted = set(flight['itemKeys']) + state['pending'] = [entry for entry in state['pending'] if entry['key'] not in accepted] + state['lastDelivery'] = {'correlationId': flight['correlationId'], 'at': time.time(), + 'itemKeys': flight['itemKeys'], 'status': 'channel-queued'} + if flight['errorSignature']: + state['errorSignature'] = flight['errorSignature'] + state.pop('inFlight', None) + save_state(path, state) + channel = channel_call(args, 'get') + if channel.get('phase') not in ('active', 'draining'): + print(json.dumps({'job': args.job, 'outcome': 'queued', 'reason': 'handover'})) + return 0 + inflight = next((item for item in channel['queue'] if item.get('state') == 'inflight'), None) + if inflight and channel.get('session', '').startswith('claude:'): + observe_claude_channel_delivery(args, inflight['id'], recovery=True) + print(json.dumps({'job': args.job, 'outcome': 'acted', 'reason': 'delivery recovered'})) + return 0 + if inflight: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'unresolved delivery'})) + return 3 + if channel.get('phase') == 'draining' and channel.get('session', '').startswith('claude:'): + backlog = channel.get('handover', {}).get('backlog', []) + awaiting = next((item for item in channel['queue'] if item.get('id') in backlog and item.get('state') == 'accepted'), None) + if awaiting: + observe_claude_channel_delivery(args, awaiting['id']) + print(json.dumps({'job': args.job, 'outcome': 'acted', 'reason': 'delivery observed'})) + return 0 + if channel.get('phase') == 'draining' and channel.get('session', '').startswith('codex:') and getattr(args, 'wake_evidence_root', None): + backlog = channel.get('handover', {}).get('backlog', []) + awaiting = next((item for item in channel['queue'] if item.get('id') in backlog and item.get('state') == 'accepted'), None) + if awaiting: + identity = {'channel': args.channel, 'session': channel['session'], 'generation': channel['generation'], 'id': awaiting['id'], 'queueId': awaiting.get('nativeQueueId')} + if channel.get('wakeReservation') or state.get('wakeAttempt', {}).get('identity') == identity: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'wake attempt unresolved; inspect before retry'})) + return 3 + if not isinstance(identity['queueId'], str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._:-]{0,127}', identity['queueId']): + raise ValueError('native queue identity unavailable') + if not preflight_codex_channel_wake(awaiting, channel): + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'wake not ready'})) + return 3 + state['wakeAttempt'] = {'identity': identity, 'status': 'attempted'} + save_state(path, state) + evidence = start_codex_channel_wake(args, awaiting, channel) + current = channel_call(args, 'get') + matched = [item for item in current['queue'] if item.get('id') == identity['id'] and item.get('session') == identity['session'] and item.get('generation') == identity['generation'] and item.get('state') == 'observed' and item.get('wakeEvidence') == evidence] + if current.get('session') != identity['session'] or current.get('generation') != identity['generation'] or len(matched) != 1: + raise ValueError('wake settlement not observed') + state['wakeAttempt']['status'] = 'verified' + save_state(path, state) + print(json.dumps({'job': args.job, 'outcome': 'acted', 'reason': 'wake verified'})) + return 0 + pending = next((item for item in channel['queue'] if item.get('state') == 'pending'), None) + if not pending: + print(json.dumps({'job': args.job, 'outcome': 'noop'})) + return 0 + target = channel['session'] + generation = channel['generation'] + if isinstance(generation, bool) or not isinstance(generation, int) or generation < 1: + raise ValueError('invalid channel generation') + cloud_profile = cloud_scope = None + if target.startswith('claude-cloud:'): + session, cloud_profile, cloud_scope = cloud_target(target, getattr(args, 'cloud_profile_root', None)) + agent = 'claude' + else: + agent, sep, session = target.partition(':') + if not sep or agent not in ('codex', 'claude'): + raise ValueError('unsupported channel recipient') + channel = channel_call(args, 'begin-delivery', '--id', pending['id'], '--session', target, '--generation', str(generation)) + item = next(item for item in channel['queue'] if item['id'] == pending['id']) + if item['session'] != target or item['generation'] != generation: + raise ValueError('unsupported channel recipient') + transport_receipt = {} + options = {'cloud_profile': cloud_profile, 'cloud_scope': cloud_scope} if cloud_profile else {} + code = deliver(agent, session, item['id'], item['payload'], None if cloud_profile else args.managed_inbox_root, + True, resume=args.resume and agent == 'codex', message_stdin=True, receipt_out=transport_receipt, **options) + if code != 0: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'delivery unconfirmed'})) + return 3 + if cloud_profile: + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'cloud queued; receipt unverified'})) + return 3 + receipt = {'status': 'accepted', 'messageId': item['id'], 'session': item['session'], 'generation': item['generation']} + receipt.update(transport_receipt) + channel_call(args, 'acknowledge', '--id', item['id'], '--input', json.dumps(receipt, separators=(',', ':'))) + print(json.dumps({'job': args.job, 'outcome': 'acted', 'correlationId': item['id']})) + return 0 + except (OSError, subprocess.SubprocessError, ValueError, KeyError, TypeError, StopIteration): + print(json.dumps({'job': args.job, 'outcome': 'blocked', 'reason': 'channel unavailable or delivery unresolved'})) + return 3 + + def run(args: argparse.Namespace) -> int: + if getattr(args, 'channel', None): + return run_channel(args) path = Path(args.state) if args.state else state_dir() / f"{args.job}.json" with locked(path) as acquired: if not acquired: @@ -225,7 +448,12 @@ def main(argv: list[str] | None = None) -> int: runner = sub.add_parser("run", help="run the producer once and deliver anything new") runner.add_argument("--job", required=True) runner.add_argument("--agent", default="claude", choices=("claude", "codex")) - runner.add_argument("--session", required=True, help="owning session UUID") + recipient = runner.add_mutually_exclusive_group(required=True) + recipient.add_argument("--session", help="owning session UUID") + recipient.add_argument("--channel", help="stable channel identifier") + runner.add_argument("--graph-state", help="override graph state for isolated tests") + runner.add_argument("--wake-evidence-root", help="opt in to explicit Codex backlog wake with a private evidence root") + runner.add_argument("--cloud-profile-root", help="private directory for scoped cloud account profiles") runner.add_argument("--managed-inbox-root", help="required for Claude sessions") runner.add_argument("--delivery-only", action="store_true", help="acknowledge the native queue, without waiting for a result") runner.add_argument("--resume", action="store_true", help="opt in to native Codex resume when idle") @@ -233,7 +461,11 @@ def main(argv: list[str] | None = None) -> int: runner.add_argument("--producer-timeout", type=int, default=280) runner.add_argument("producer", nargs=argparse.REMAINDER, help="-- command that prints the JSON report") args = parser.parse_args(argv) - if args.resume and args.agent != "codex": + if args.wake_evidence_root and (not args.channel or not args.graph_state or not os.path.isabs(args.graph_state) or not os.path.isabs(args.wake_evidence_root) or args.resume): + parser.error('--wake-evidence-root requires --channel, absolute --graph-state, and no --resume') + if args.channel and not args.delivery_only: + parser.error("--channel requires --delivery-only") + if args.resume and not args.channel and args.agent != "codex": parser.error("--resume requires --agent codex") if args.producer[:1] == ["--"]: args.producer = args.producer[1:] diff --git a/skills/agent-tmux/bin/channel-state.mjs b/skills/agent-tmux/bin/channel-state.mjs new file mode 100644 index 00000000..4ae54186 --- /dev/null +++ b/skills/agent-tmux/bin/channel-state.mjs @@ -0,0 +1,148 @@ +/** Pure channel transitions. A host must persist each transition atomically. */ +import { createHash } from 'node:crypto'; +const identifier = (value) => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value); +const channelIdentifier = (value) => typeof value === 'string' && /^#?[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value); +const copy = (state) => structuredClone(state); + +export function createChannel(id, session) { + if (!channelIdentifier(id) || !identifier(session)) throw new Error('invalid channel or session'); + return { schema: 'agent-mesh.channel.v1', id, session, generation: 1, phase: 'active', queue: [] }; +} + +export function enqueue(state, id, payload) { + if (!identifier(id) || typeof payload !== 'string' || !payload || Buffer.byteLength(payload) > 65536) throw new Error('invalid message'); + const prior = state.queue.find((item) => item.id === id); + if (prior) { + if (prior.payload !== payload) throw new Error('message id conflict'); + return copy(state); + } + const next = copy(state); + next.queue.push({ id, payload, state: 'pending' }); + return next; +} + +export function beginDelivery(state, id, expectedSession, expectedGeneration) { + if (!['active', 'draining'].includes(state.phase)) throw new Error('handover in progress'); + if (expectedSession !== undefined && state.session !== expectedSession) throw new Error('channel recipient changed'); + if (expectedGeneration !== undefined && (!Number.isSafeInteger(expectedGeneration) || expectedGeneration < 1 || state.generation !== expectedGeneration)) throw new Error('channel generation changed'); + if (state.queue.some((item) => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); + if (state.queue.find((item) => item.state === 'pending')?.id !== id) throw new Error('message is not first pending'); + const next = copy(state), item = next.queue.find((row) => row.id === id); + if (!item || item.state !== 'pending') throw new Error('message not pending'); + item.state = 'inflight'; + item.session = state.session; + item.generation = state.generation; + return next; +} + +export function acknowledge(state, id, receipt) { + const next = copy(state), item = next.queue.find((row) => row.id === id); + if (!item || item.state !== 'inflight' || !receipt || receipt.status !== 'accepted' || receipt.messageId !== id || receipt.session !== item.session || receipt.generation !== item.generation) throw new Error('unverified delivery receipt'); + if (receipt.nativeQueueId !== undefined) { + if (!item.session.startsWith('codex:') || !identifier(receipt.nativeQueueId)) throw new Error('invalid native queue receipt'); + item.nativeQueueId = receipt.nativeQueueId; + } + item.state = 'accepted'; + return next; +} + +export function beginHandover(state) { + if (state.phase !== 'active') throw new Error('handover already in progress'); + if (state.wakeReservation) throw new Error('wake reservation unresolved'); + const next = copy(state); + next.phase = 'handover'; + delete next.statePreparation; + return next; +} + +// A reservation is durable and has no expiry: a crashed native call is unknown. +export function reserveWake(state, id, session, generation, nativeQueueId, mode = 'start') { + if (mode !== 'start' || !['active', 'draining'].includes(state.phase) || state.wakeReservation || state.session !== session || state.generation !== generation || !Number.isSafeInteger(generation) || generation < 1 || !identifier(nativeQueueId)) throw new Error('wake reservation unavailable'); + const matches = state.queue.filter(item => item.id === id && item.state === 'accepted' && !item.wakeEvidence && item.session === session && item.generation === generation && item.nativeQueueId === nativeQueueId); + if (matches.length !== 1 || !session.startsWith('codex:')) throw new Error('wake identity unavailable'); + const next = copy(state); + next.wakeReservation = { id, session, generation, nativeQueueId, mode }; + return next; +} + +export function settleWake(state, proof) { + const reservation = state.wakeReservation; + if (!reservation || (reservation.mode === 'auto-readback' || ['codex-app-server.auto-start-bound-readback', 'codex-app-server.correlated-recovery', 'codex-app-server.correlated-recovery-bound'].includes(proof?.source)) || !['active', 'draining'].includes(state.phase) || state.session !== reservation.session || state.generation !== reservation.generation || !proof || proof.session !== reservation.session || proof.correlation !== reservation.id || proof.queueId !== reservation.nativeQueueId || !/^codex-wake:[a-f0-9]{64}$/.test(proof.evidence || '')) throw new Error('wake proof does not match reservation'); + const next = copy(state), item = next.queue.find(row => row.id === reservation.id && row.session === reservation.session && row.generation === reservation.generation && row.nativeQueueId === reservation.nativeQueueId && row.state === 'accepted' && !row.wakeEvidence); + if (!item) throw new Error('wake item unavailable'); + item.wakeEvidence = proof.evidence; + const boundWake = proof.schema === 'agent-mesh.codex-wake-evidence.v4' && proof.source === 'codex-app-server.queue-start-bound-readback'; + if (state.phase === 'draining' && state.handover?.backlog.includes(item.id) && boundWake && proof.channel === state.id && proof.generation === item.generation && proof.payloadSha256 === createHash('sha256').update(item.payload).digest('hex')) { + item.state = 'observed'; item.observation = proof.evidence; + } + delete next.wakeReservation; + return next; +} + +// A reserved request is intentionally not retried automatically after a crash. +export function reserveStatePreparation(state, id) { + if (state.phase !== 'handover' || state.statePreparation || !identifier(id)) throw new Error('state preparation unavailable or unresolved'); + if (state.queue.some(item => item.state === 'inflight')) throw new Error('unresolved inflight delivery'); + const next = copy(state); + next.statePreparation = { id, session: state.session, generation: state.generation, status: 'requested' }; + return next; +} + +export function completeStatePreparation(state, proof) { + const pending = state.statePreparation; + if (state.phase !== 'handover' || !pending || pending.status !== 'requested' || pending.session !== state.session || pending.generation !== state.generation || !proof || proof.schema !== 'agent-mesh.handover-state.v1' || proof.nonce !== pending.id || proof.session !== pending.session || !/^[0-9a-f]{64}$/.test(proof.sha256) || typeof proof.filename !== 'string' || !Number.isSafeInteger(proof.bytes) || proof.bytes < 1) throw new Error('state preparation changed or proof invalid'); + const next = copy(state); + next.statePreparation = { ...pending, status: 'verified', filename: proof.filename, sha256: proof.sha256, bytes: proof.bytes }; + return next; +} + +// The durable reservation survives crashes; only authenticated evidence can +// settle it. It does not itself verify the successor or send a notice. +export function reserveFinalNotice(state, id, successor, noticeSha256) { + const handover = state.handover; + if (state.phase !== 'draining' || !handover || state.finalNotice || successor !== state.session || handover.successor !== successor || !identifier(id) || !/^[a-f0-9]{64}$/.test(noticeSha256 || '') || handover.backlog.some(id => !state.queue.some(item => item.id === id && item.state === 'observed' && item.session === successor && item.generation === state.generation))) throw new Error('final notice reservation unavailable'); + const next = copy(state); + next.finalNotice = { id, session: handover.predecessor, generation: handover.previousGeneration, successor, noticeSha256, status: 'requested' }; + return next; +} + +export function recordNoticeQueued(state, receipt) { + const pending = state.finalNotice; + if (state.phase !== 'draining' || !pending || pending.status !== 'requested' || pending.session !== state.handover?.predecessor || pending.generation !== state.handover?.previousGeneration || !receipt || receipt.schema !== 'agent-mesh.notice-queue.v1' || receipt.status !== 'queued-unverified' || receipt.session !== pending.session || receipt.nonce !== pending.id || receipt.noticeSha256 !== pending.noticeSha256) throw new Error('notice queue receipt does not match reservation'); + const next = copy(state); + next.finalNotice.status = 'queued-unverified'; + return next; +} + +// A transcript snapshot is evidence of a completed message at read time, +// not exclusive finality and not authorization to finish a handover. +export function recordNoticeObservation(state, proof) { + const pending = state.finalNotice; + if (state.phase !== 'draining' || !pending || !['requested', 'queued-unverified'].includes(pending.status) || pending.session !== state.handover?.predecessor || pending.generation !== state.handover?.previousGeneration || !proof || proof.schema !== 'agent-mesh.final-notice-observation.v1' || proof.session !== pending.session || proof.nonce !== pending.id || proof.messageSha256 !== pending.noticeSha256 || !/^[a-f0-9]{64}$/.test(proof.transcriptSha256 || '') || !Number.isSafeInteger(proof.bytes) || proof.bytes < 1) throw new Error('notice observation does not match reservation'); + const next = copy(state); + next.finalNotice = { ...pending, status: 'observed-snapshot', transcriptSha256: proof.transcriptSha256, transcriptBytes: proof.bytes }; + return next; +} + +// These are pure transitions. The host must independently authenticate the successor +// and delivery evidence before applying them; the operational cutover stays disabled. +export function switchHandover(state, session, verified) { + if (state.phase !== 'handover' || !identifier(session) || session === state.session || verified !== true) throw new Error('unverified successor'); + if (state.finalNotice || state.queue.some(item => item.state === 'inflight')) throw new Error('unresolved inflight delivery or notice'); + if (state.statePreparation?.status !== 'verified' || state.statePreparation.session !== state.session || state.statePreparation.generation !== state.generation) throw new Error('state preparation unresolved'); + const next = copy(state); + next.handover = { predecessor: state.session, previousGeneration: state.generation, successor: session, backlog: state.queue.filter(item => item.state === 'pending').map(item => item.id) }; + next.session = session; + next.generation += 1; + next.phase = 'draining'; + return next; +} + +// An accepted provider queue receipt is not proof of recipient observation. +export function observeDelivery(state, id, proof) { + const item = state.queue.find(row => row.id === id); + if (state.phase !== 'draining' || !state.handover?.backlog.includes(id) || !item || item.state !== 'accepted' || item.session !== state.session || item.generation !== state.generation || !proof || proof.schema !== 'agent-mesh.delivery-observation.v1' || proof.messageId !== id || proof.session !== item.session || proof.generation !== item.generation || typeof proof.evidence !== 'string' || !identifier(proof.evidence)) throw new Error('delivery observation does not match backlog'); + const next = copy(state), observed = next.queue.find(row => row.id === id); + observed.state = 'observed'; observed.observation = proof.evidence; + return next; +} diff --git a/skills/agent-tmux/bin/claude-delivery-observation.mjs b/skills/agent-tmux/bin/claude-delivery-observation.mjs new file mode 100644 index 00000000..cab69f8d --- /dev/null +++ b/skills/agent-tmux/bin/claude-delivery-observation.mjs @@ -0,0 +1,72 @@ +/** Read-only observation of one managed inbox record in a local Claude transcript. */ +import { constants, lstatSync, realpathSync } from 'node:fs'; +import { lstat, open, realpath, readdir } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { isAbsolute, join, resolve } from 'node:path'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/; +const hash = data => createHash('sha256').update(data).digest('hex'); + +export async function observeClaudeDelivery({ root, session, generation, messageId, payload, snapshotBytes }) { + if (typeof root !== 'string' || !isAbsolute(root) || typeof session !== 'string' || !session.startsWith('claude:') || !UUID.test(session.slice(7)) || !Number.isSafeInteger(generation) || generation < 1 || typeof messageId !== 'string' || !TOKEN.test(messageId) || typeof payload !== 'string' || !payload || Buffer.byteLength(payload) > 65536) throw new Error('invalid delivery observation request'); + if (snapshotBytes !== undefined && (!Number.isSafeInteger(snapshotBytes) || snapshotBytes < 1 || snapshotBytes > 128 * 1024 * 1024)) throw new Error('invalid transcript snapshot size'); + root = resolve(root); + const directory = await lstat(root); + if (!directory.isDirectory() || directory.isSymbolicLink() || directory.uid !== process.getuid() || await realpath(root) !== root) throw new Error('invalid transcript root'); + const entries = await readdir(root, { recursive: true, withFileTypes: true }); + const matches = entries.filter(entry => entry.isFile() && entry.name.toLowerCase() === `${session.slice(7).toLowerCase()}.jsonl`).map(entry => join(entry.parentPath, entry.name)); + if (matches.length !== 1 || await realpath(matches[0]) !== matches[0]) throw new Error('transcript identity unavailable or ambiguous'); + const path = matches[0], file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let bytes, snapshotIdentity; + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o022) !== 0 || before.size < 1 || before.size > 128 * 1024 * 1024) throw new Error('invalid transcript file'); + bytes = await file.readFile(); + const after = await file.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('transcript changed during observation'); + snapshotIdentity = { path, dev: after.dev, ino: after.ino, size: after.size, mtimeMs: after.mtimeMs, ctimeMs: after.ctimeMs }; + } finally { await file.close(); } + if (snapshotBytes !== undefined) { + if (snapshotBytes > bytes.length) throw new Error('transcript snapshot truncated'); + bytes = bytes.subarray(0, snapshotBytes); + } + let text; + try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } + if (!text.endsWith('\n')) throw new Error('partial transcript record'); + let found = 0, queued = 0, queuedLine = null; + for (const line of text.split('\n')) { + if (!line) continue; + let record; try { record = JSON.parse(line); } catch { throw new Error('invalid transcript record'); } + if (!record || typeof record !== 'object' || Array.isArray(record)) throw new Error('invalid transcript record'); + const isQueue = record.type === 'queue-operation' && record.operation === 'enqueue'; + const isUser = record.type === 'user' && !record.isSidechain && record.message?.role === 'user'; + if (!isQueue && !isUser) continue; + const content = isQueue ? record.content : record.message?.content; + const parts = typeof content === 'string' ? [content] : Array.isArray(content) ? content.filter(part => part?.type === 'text' && typeof part.text === 'string').map(part => part.text) : []; + for (const part of parts) for (const entry of part.split('\n')) { + if (!entry.startsWith('AGENT_MESH_INBOX ')) continue; + let inbox; try { inbox = JSON.parse(entry.slice('AGENT_MESH_INBOX '.length)); } catch { throw new Error('invalid inbox record'); } + if (inbox?.deliveryId === messageId || inbox?.meshId === messageId) { + if (record.sessionId !== session.slice(7)) throw new Error('transcript session mismatch'); + if (inbox.schema !== 'agent-mesh.monitor-inbox.v1' || inbox.deliveryId !== messageId || inbox.meshId !== messageId || inbox.prompt !== payload) throw new Error('inbox correlation mismatch'); + if (isQueue) { queued++; queuedLine = entry; } + else { if (queued !== 1 || queuedLine !== entry) throw new Error('matching prior enqueue unavailable'); found++; } + } + } + } + if (queued !== 1 || found !== 1) throw new Error('delivery not uniquely observed'); + const payloadSha256 = hash(payload), transcriptSha256 = hash(bytes); + const evidence = `claude-transcript:${hash(JSON.stringify([session, generation, messageId, payloadSha256, transcriptSha256]))}`; + return { schema: 'agent-mesh.delivery-observation.v1', session, generation, messageId, payloadSha256, transcriptSha256, transcriptBytes: bytes.length, evidence, snapshotIdentity }; +} + +// Narrows the snapshot-to-graph race; it cannot exclude a writer after this check. +export function assertClaudeDeliverySnapshotCurrent(proof) { + const snapshot = proof?.snapshotIdentity; + if (!snapshot || typeof snapshot.path !== 'string' || !isAbsolute(snapshot.path)) throw new Error('transcript snapshot identity unavailable'); + let current; + try { current = lstatSync(snapshot.path); if (realpathSync(snapshot.path) !== snapshot.path) throw new Error(); } + catch { throw new Error('transcript snapshot unavailable'); } + if (!current.isFile() || current.isSymbolicLink() || current.uid !== process.getuid() || current.nlink !== 1 || (current.mode & 0o022) !== 0 || current.dev !== snapshot.dev || current.ino !== snapshot.ino || current.size !== snapshot.size || current.mtimeMs !== snapshot.mtimeMs || current.ctimeMs !== snapshot.ctimeMs) throw new Error('transcript changed after observation'); +} diff --git a/skills/agent-tmux/bin/cloud-account-binding.mjs b/skills/agent-tmux/bin/cloud-account-binding.mjs new file mode 100644 index 00000000..8391a3f1 --- /dev/null +++ b/skills/agent-tmux/bin/cloud-account-binding.mjs @@ -0,0 +1,62 @@ +/** Bind an operator-selected Claude CLI profile to an account scope. */ +import { createHash } from 'node:crypto'; +import { execFile } from 'node:child_process'; +import { constants } from 'node:fs'; +import { lstat, open, realpath } from 'node:fs/promises'; +import { dirname, isAbsolute } from 'node:path'; +import { promisify } from 'node:util'; + +const execute = promisify(execFile); +const SCOPE = /^[a-z][a-z0-9-]{0,63}$/; + +export async function loadClaudeAccountProfile(path, scope, expectedDigest) { + if (typeof path !== 'string' || !isAbsolute(path) || !SCOPE.test(scope || '') || (expectedDigest !== undefined && !/^[0-9a-f]{64}$/.test(expectedDigest))) throw new Error('invalid cloud profile reference'); + const parent = dirname(path), dir = await lstat(parent); + if (!dir.isDirectory() || dir.isSymbolicLink() || dir.uid !== process.getuid() || (dir.mode & 0o077) !== 0 || await realpath(parent) !== parent) throw new Error('cloud profile directory not private'); + const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let bytes; + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 8192) throw new Error('invalid cloud profile file'); + bytes = await file.readFile(); + const after = await file.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('cloud profile changed'); + } finally { await file.close(); } + const digest = createHash('sha256').update(bytes).digest('hex'); + if (expectedDigest !== undefined && digest !== expectedDigest) throw new Error('cloud profile changed'); + let profile; try { profile = JSON.parse(bytes.toString('utf8')); } catch { throw new Error('invalid cloud profile'); } + if (!profile || Object.keys(profile).sort().join(',') !== 'command,configDir,expectedSubjectHash,schema,scope' || profile.schema !== 'agent-mesh.cloud-account.v1' || profile.scope !== scope) throw new Error('cloud profile scope mismatch'); + return { profile, digest }; +} + +// Only a digest is returned. Raw identity and credentials are never returned +// or copied to a receipt; the operator must protect the configured profile. +export function claudeSubjectHash(status) { + if (!status || status.loggedIn !== true || status.apiProvider !== 'firstParty' || status.authMethod !== 'claude.ai' || status.storedClaudeAiLogin !== true || typeof status.email !== 'string' || !status.email.trim() || typeof status.orgId !== 'string' || !status.orgId.trim()) throw new Error('Claude account identity unavailable'); + return createHash('sha256').update(JSON.stringify([status.email.trim().toLowerCase(), status.orgId.trim()])).digest('hex'); +} + +export async function verifyClaudeAccount(profile, run = execute) { + if (!profile || typeof profile.scope !== 'string' || !SCOPE.test(profile.scope) || typeof profile.expectedSubjectHash !== 'string' || !/^[0-9a-f]{64}$/.test(profile.expectedSubjectHash) || typeof profile.configDir !== 'string' || !isAbsolute(profile.configDir) || typeof profile.command !== 'string' || !isAbsolute(profile.command)) throw new Error('invalid cloud account profile'); + const info = await lstat(profile.configDir); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || await realpath(profile.configDir) !== profile.configDir) throw new Error('cloud profile must be private and canonical'); + let output; + try { output = await run(profile.command, ['auth', 'status', '--json'], { env: { ...process.env, CLAUDE_CONFIG_DIR: profile.configDir }, timeout: 10000, maxBuffer: 8192 }); } + catch { throw new Error('Claude account check unavailable'); } + let status; + try { status = JSON.parse(output.stdout); } catch { throw new Error('invalid Claude account response'); } + if (status.configDirectory !== profile.configDir || claudeSubjectHash(status) !== profile.expectedSubjectHash) throw new Error('Claude account scope mismatch'); + return { scope: profile.scope, subjectHash: profile.expectedSubjectHash }; +} + +// Check the same profile before and after an operation. A changed or unreadable +// profile after invocation leaves its result uncertain; callers must not resend. +export async function withClaudeAccount(profile, action, run = execute) { + const binding = await verifyClaudeAccount(profile, run); + let result; + try { result = await action({ scope: binding.scope, configDir: profile.configDir, command: profile.command }); } + catch { throw new Error('cloud operation outcome uncertain'); } + try { await verifyClaudeAccount(profile, run); } + catch { throw new Error('cloud operation outcome uncertain'); } + return result; +} diff --git a/skills/agent-tmux/bin/codex-app-server.mjs b/skills/agent-tmux/bin/codex-app-server.mjs index 1027b662..fbc65a14 100644 --- a/skills/agent-tmux/bin/codex-app-server.mjs +++ b/skills/agent-tmux/bin/codex-app-server.mjs @@ -64,7 +64,8 @@ function readFrame(buffer) { return { fin: Boolean(buffer[0] & 0x80), opcode: buffer[0] & 0x0f, payload: buffer.subarray(offset, offset + size), end: offset + size }; } -export async function withCodexAppServer({ clientName, timeout, timeoutMessage }, work) { +export async function withCodexAppServer({ clientName, timeout, timeoutMessage, onNotification }, work) { + if (onNotification !== undefined && typeof onNotification !== "function") throw new Error("invalid notification handler"); const path = codexSocket(); const key = randomBytes(16).toString("base64"); const accept = createHash("sha1").update(key + WS_GUID).digest("base64"); @@ -86,7 +87,13 @@ export async function withCodexAppServer({ clientName, timeout, timeoutMessage } let parsed; try { parsed = JSON.parse(text); } catch { rejectAll(new Error("invalid JSON from app-server")); return; } - if (parsed.method) return; + if (parsed.method) { + if (onNotification) { + try { onNotification(parsed); } + catch { rejectAll(new Error("notification handler failed")); socket.destroy(); } + } + return; + } const waiter = pending.get(parsed.id); if (!waiter) return; pending.delete(parsed.id); @@ -163,7 +170,9 @@ export async function withCodexAppServer({ clientName, timeout, timeoutMessage } capabilities: { experimentalApi: true }, }); sendText({ method: "initialized" }); - return await work(request); + const result = await work(request); + if (failure) throw failure; + return result; } finally { clearTimeout(timer); socket.destroy(); diff --git a/skills/agent-tmux/bin/codex-compaction-evidence.mjs b/skills/agent-tmux/bin/codex-compaction-evidence.mjs new file mode 100644 index 00000000..b5018086 --- /dev/null +++ b/skills/agent-tmux/bin/codex-compaction-evidence.mjs @@ -0,0 +1,101 @@ +#!/usr/bin/env node +/** Observe one native compaction and commit an idempotent local evidence reference. */ +import { parseArgs } from 'node:util'; +import { constants } from 'node:fs'; +import { lstat, open, realpath } from 'node:fs/promises'; +import { spawnSync } from 'node:child_process'; +import { createHash } from 'node:crypto'; +import { dirname, isAbsolute, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { withCodexAppServer } from './codex-app-server.mjs'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/; +const hash = text => createHash('sha256').update(text).digest('hex'); +const here = dirname(fileURLToPath(import.meta.url)); + +export function compactionFromThread(response, { thread, turn, item }) { + if (typeof thread !== 'string' || !UUID.test(thread) || typeof turn !== 'string' || !TOKEN.test(turn) || typeof item !== 'string' || !TOKEN.test(item) || response?.thread?.id !== thread || !Array.isArray(response.thread.turns)) throw new Error('native thread identity unavailable'); + const turns = response.thread.turns.filter(value => value?.id === turn); + // The native Turn schema defaults an omitted itemsView to "full". + if (turns.length !== 1 || (turns[0].itemsView !== undefined && turns[0].itemsView !== 'full') || !Array.isArray(turns[0].items) || !['completed', 'interrupted', 'failed', 'inProgress'].includes(turns[0].status)) throw new Error('native turn unavailable or incomplete'); + const items = turns[0].items.filter(value => value?.id === item); + if (items.length !== 1 || items[0].type !== 'contextCompaction' || !Number.isSafeInteger(items[0].completedAtMs) || items[0].completedAtMs <= 0) throw new Error('completed compaction unavailable'); + return { schema: 'agent-mesh.codex-compaction-evidence.v1', source: 'codex-app-server.thread-read', session: `codex:${thread}`, turn, item, completedAtMs: items[0].completedAtMs }; +} + +async function privateRoot(root) { + if (!isAbsolute(root)) throw new Error('invalid evidence root'); + const info = await lstat(root); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('evidence root must be private and canonical'); +} + +async function persistEvidence(root, body) { + await privateRoot(root); + const digest = hash(body), path = join(root, `${digest}.json`); + let file; + try { + file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); + await file.writeFile(body); + await file.sync(); + } catch (error) { + if (error.code !== 'EEXIST') throw error; + file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + const info = await file.stat(); + if (!info.isFile() || info.uid !== process.getuid() || info.nlink !== 1 || (info.mode & 0o077) !== 0 || info.size !== Buffer.byteLength(body) || await file.readFile('utf8') !== body) throw new Error('existing evidence mismatch'); + } finally { if (file) await file.close(); } + const directory = await open(root, constants.O_RDONLY); + try { await directory.sync(); } finally { await directory.close(); } + return `codex-compaction:${digest}`; +} + +/** Verify a record from the operator's trusted private evidence root. */ +export async function verifyCodexCompactionEvidence({ evidenceRoot, reference, session }) { + if (typeof reference !== 'string' || !/^codex-compaction:[a-f0-9]{64}$/.test(reference) || typeof session !== 'string' || !session.startsWith('codex:') || !UUID.test(session.slice(6))) throw new Error('invalid evidence request'); + await privateRoot(evidenceRoot); + const path = join(evidenceRoot, `${reference.slice('codex-compaction:'.length)}.json`); + const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let body; + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 4096) throw new Error('invalid evidence file'); + body = await file.readFile('utf8'); + const after = await file.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('evidence changed during verification'); + } finally { await file.close(); } + if (`codex-compaction:${hash(body)}` !== reference) throw new Error('evidence digest mismatch'); + let value; + try { value = JSON.parse(body); } catch { throw new Error('invalid evidence record'); } + if (!value || Object.keys(value).sort().join(',') !== 'completedAtMs,item,schema,session,source,turn' || `${JSON.stringify(value)}\n` !== body || value.schema !== 'agent-mesh.codex-compaction-evidence.v1' || value.source !== 'codex-app-server.thread-read' || value.session !== session || typeof value.turn !== 'string' || !TOKEN.test(value.turn) || typeof value.item !== 'string' || !TOKEN.test(value.item) || !Number.isSafeInteger(value.completedAtMs) || value.completedAtMs <= 0) throw new Error('evidence identity mismatch'); + return { schema: value.schema, session, turn: value.turn, item: value.item, completedAtMs: value.completedAtMs, evidence: reference }; +} + +export async function recordCodexCompaction({ thread, turn, item, evidenceRoot, graphState }) { + if (typeof thread !== 'string' || !UUID.test(thread) || typeof turn !== 'string' || !TOKEN.test(turn) || typeof item !== 'string' || !TOKEN.test(item) || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('invalid observation identity or graph state'); + await privateRoot(evidenceRoot); + const response = await withCodexAppServer({ clientName: 'agent-mesh-compaction-evidence', timeout: 30000, timeoutMessage: 'native observation timed out' }, request => request('thread/read', { threadId: thread, includeTurns: true })); + const evidence = compactionFromThread(response, { thread, turn, item }); + const reference = await persistEvidence(evidenceRoot, `${JSON.stringify(evidence)}\n`); + const observation = `codex-compaction-${hash(JSON.stringify([thread, turn, item]))}`; + const args = [join(here, 'mesh-graph.mjs'), '--state', graphState]; + args.push('lifecycle', 'record', '--type', 'session.compacted', '--session', evidence.session, '--id', observation, '--evidence', reference); + const result = spawnSync(process.execPath, args, { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (result.error || result.status !== 0) throw new Error('graph recording failed; retain evidence and retry with the same identity'); + let receipt; + try { receipt = JSON.parse(result.stdout); } catch { throw new Error('graph receipt unavailable'); } + if (receipt?.observation !== observation || typeof receipt.duplicate !== 'boolean') throw new Error('graph receipt mismatch'); + return { schema: 'agent-mesh.compaction-record.v1', session: evidence.session, evidence: reference, duplicate: receipt.duplicate }; +} + +if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { + try { + const { values } = parseArgs({ options: { thread: { type: 'string' }, turn: { type: 'string' }, item: { type: 'string' }, verify: { type: 'string' }, session: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' } }, strict: true }); + if (values.verify !== undefined) { + if (values.thread || values.turn || values.item || values['graph-state']) throw new Error('invalid verify options'); + console.log(JSON.stringify(await verifyCodexCompactionEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }))); + } else { + if (values.session) throw new Error('invalid record options'); + console.log(JSON.stringify(await recordCodexCompaction({ thread: values.thread, turn: values.turn, item: values.item, evidenceRoot: values['evidence-root'], graphState: values['graph-state'] }))); + } + } catch { console.error('compaction observation or recording failed; inspect locally before retry'); process.exitCode = 1; } +} diff --git a/skills/agent-tmux/bin/codex-mcp-observation.mjs b/skills/agent-tmux/bin/codex-mcp-observation.mjs new file mode 100644 index 00000000..108ad5d9 --- /dev/null +++ b/skills/agent-tmux/bin/codex-mcp-observation.mjs @@ -0,0 +1,39 @@ +/** Bounded, opt-in app-server sample. It does not start or resume a thread. */ + +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const statuses = new Set(['notStarted', 'starting', 'connected', 'authenticationRequired', 'failed', 'cancelled', 'disabled']); +const validName = name => typeof name === 'string' && name.length > 0 && name.length <= 512 && !/[\x00-\x1f\x7f]/.test(name); + +/** + * Do not treat this as launch or process evidence. Pagination is not an atomic + * snapshot, and the provider does not echo the requested thread in a response. + * A real provider call can restart an MCP; connect only to an isolated fixture. + */ +export async function sampleCodexMcpConnections({ threadId, generation, profileSha256 }, connect) { + if (typeof threadId !== 'string' || !uuid.test(threadId) || !Number.isSafeInteger(generation) || generation < 1 || typeof profileSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(profileSha256) || typeof connect !== 'function') throw new Error('invalid MCP sample request'); + return connect({ clientName: 'agent-mesh-mcp-sample', timeout: 30000, timeoutMessage: 'MCP sample timed out' }, async request => { + const startedAt = new Date().toISOString(), cursors = new Set(), names = new Set(); + let cursor = null, pages = 0, connected = 0, unavailable = 0; + for (;;) { + if (++pages > 32) throw new Error('MCP pagination limit exceeded'); + const result = await request('mcpServerStatus/list', { threadId, cursor, limit: 100, detail: 'toolsAndAuthOnly' }); + if (!result || !Array.isArray(result.data) || !Object.hasOwn(result, 'nextCursor') || !(result.nextCursor === null || (typeof result.nextCursor === 'string' && result.nextCursor.length > 0 && result.nextCursor.length <= 4096))) throw new Error('invalid MCP page'); + for (const item of result.data) { + if (!item || !validName(item.name) || names.has(item.name)) throw new Error('invalid or duplicate MCP identity'); + names.add(item.name); + if (names.size > 4096) throw new Error('MCP sample limit exceeded'); + const status = item.runtimeStatus ?? null; + if (status !== null && !statuses.has(status)) throw new Error('invalid MCP runtime status'); + if (status === 'connected') connected++; + if (status === null) unavailable++; + } + if (result.nextCursor === null) break; + if (cursors.has(result.nextCursor)) throw new Error('MCP cursor loop'); + cursors.add(result.nextCursor); cursor = result.nextCursor; + } + return { schema: 'agent-mesh.codex-mcp-sample.v1', requestedThreadId: threadId, claimedGeneration: generation, + claimedProfileSha256: profileSha256, profileBinding: 'unverified', startedAt, endedAt: new Date().toISOString(), pages, + serversReturned: names.size, connectedObserved: connected, unavailableStatus: unavailable, + completeness: 'unverified-non-atomic', mcpStarted: null, startupTokens: null }; + }); +} diff --git a/skills/agent-tmux/bin/codex-mcp-startup-notifications.mjs b/skills/agent-tmux/bin/codex-mcp-startup-notifications.mjs new file mode 100644 index 00000000..5a85201d --- /dev/null +++ b/skills/agent-tmux/bin/codex-mcp-startup-notifications.mjs @@ -0,0 +1,47 @@ +/** Passive, bounded sampling of already delivered native startup notifications. */ +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const statuses = new Set(['starting', 'ready', 'failed', 'cancelled']); +const legacyApprovalMethods = new Set(['applyPatchApproval', 'execCommandApproval']); +const permissionMethods = new Set(['item/commandExecution/requestApproval', 'item/fileChange/requestApproval', 'item/permissions/requestApproval', 'mcpServer/elicitation/request', ...legacyApprovalMethods]); +const validName = name => typeof name === 'string' && name.length > 0 && name.length <= 512 && !/[\x00-\x1f\x7f]/.test(name); + +// Attach before starting the thread. The native response can bind the thread +// after notifications arrive. Captured names never leave this in-memory object. +export function createCodexMcpStartupObserver() { + const buffered = []; let threadId = null, invalid = false; + return { + onNotification(event) { + const permission = permissionMethods.has(event?.method); + if (!permission && event?.method !== 'mcpServer/startupStatus/updated') return; + const p = event.params; + if (permission) { + const requestId = event.id, subject = legacyApprovalMethods.has(event.method) ? p?.conversationId : p?.threadId; + if (!(typeof requestId === 'string' || (typeof requestId === 'number' && Number.isFinite(requestId))) || typeof subject !== 'string' || !uuid.test(subject)) { invalid = true; return; } + if (threadId && subject !== threadId) return; + if (buffered.length >= 4096) { invalid = true; return; } + buffered.push({ threadId: subject, permission: true }); + return; + } + if (!p || typeof p.threadId !== 'string' || !uuid.test(p.threadId) || !validName(p.name) || !statuses.has(p.status)) { invalid = true; return; } + if (threadId && p.threadId !== threadId) return; + if (buffered.length >= 4096) { invalid = true; return; } + buffered.push({ threadId: p.threadId, name: p.name, status: p.status }); + }, + bindThread(id) { + if (threadId !== null || typeof id !== 'string' || !uuid.test(id)) throw new Error('invalid startup thread binding'); + threadId = id; + }, + snapshot() { + if (!threadId) throw new Error('startup thread is not bound'); + const latest = new Map(); let permissionRequestObserved = null; + for (const row of buffered) if (row.threadId === threadId) { + if (row.permission) permissionRequestObserved = true; + else latest.set(row.name, row.status); + } + const counts = { starting: 0, ready: 0, failed: 0, cancelled: 0 }; + for (const status of latest.values()) counts[status]++; + return { schema: 'agent-mesh.codex-mcp-notification-sample.v1', requestedThreadId: threadId, counts, + completeness: 'unverified', invalidOrOverflow: invalid, permissionRequestObserved, mcpStarted: null, startupTokens: null }; + } + }; +} diff --git a/skills/agent-tmux/bin/codex-role-mcp-overrides.mjs b/skills/agent-tmux/bin/codex-role-mcp-overrides.mjs new file mode 100644 index 00000000..1cab0d2e --- /dev/null +++ b/skills/agent-tmux/bin/codex-role-mcp-overrides.mjs @@ -0,0 +1,21 @@ +/** Prepare explicit exclusions from an operator-supplied effective Codex config. */ +const name = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); +const names = value => Array.isArray(value) && value.length <= 256 && value.every(name) && new Set(value).size === value.length; +const object = value => value !== null && typeof value === 'object' && !Array.isArray(value); + +// This is only a candidate override. Dynamic/plugin servers, changes between +// reading and launching, and permission enforcement require separate evidence. +export function planCodexMcpOverrides({ launchPlan, effectiveServers }) { + if (!object(launchPlan) || launchPlan.schema !== 'agent-mesh.role-launch-plan.v1' || !names(launchPlan.mcpToStart) || !names(launchPlan.mcpUnavailable) || launchPlan.mcpToStart.some(item => launchPlan.mcpUnavailable.includes(item)) || !object(effectiveServers)) throw new Error('invalid MCP override inputs'); + const keys = Object.keys(effectiveServers); + if (keys.length > 4096 || keys.some(key => !name(key) || !object(effectiveServers[key]) || (effectiveServers[key].enabled !== undefined && typeof effectiveServers[key].enabled !== 'boolean'))) throw new Error('invalid effective MCP inventory'); + for (const requested of launchPlan.mcpToStart) { + if (!Object.hasOwn(effectiveServers, requested)) throw new Error('requested MCP missing from effective inventory'); + if (effectiveServers[requested].enabled === false) throw new Error('requested MCP is disabled'); + } + const allowed = new Set(launchPlan.mcpToStart); + const excluded = keys.filter(key => !allowed.has(key)).sort(); + const servers = Object.create(null); + for (const key of excluded) servers[key] = { enabled: false }; + return { schema: 'agent-mesh.codex-mcp-overrides.v1', config: { mcp_servers: servers }, excludedCount: excluded.length, isolation: 'unverified' }; +} diff --git a/skills/agent-tmux/bin/codex-role-start-assessment.mjs b/skills/agent-tmux/bin/codex-role-start-assessment.mjs new file mode 100644 index 00000000..6b89ff56 --- /dev/null +++ b/skills/agent-tmux/bin/codex-role-start-assessment.mjs @@ -0,0 +1,23 @@ +/** Compare a native start response and passive observations to trusted policy. */ +import { isDeepStrictEqual } from 'node:util'; + +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const object = value => value !== null && typeof value === 'object' && !Array.isArray(value); + +// Neither argument authenticates itself. The caller must bind the start response +// and events to the same trusted native connection and authorized role policy. +export function assessCodexRoleStart({ startResponse, sample, expected }) { + if (!object(startResponse) || !object(sample) || sample.schema !== 'agent-mesh.codex-mcp-notification-sample.v1' || !object(expected) || !object(expected.profile) || typeof expected.profile.id !== 'string' || !expected.profile.id || !object(expected.sandbox) || expected.approvalPolicy !== 'never' || typeof startResponse.thread?.id !== 'string' || !uuid.test(startResponse.thread.id) || sample.requestedThreadId !== startResponse.thread.id || ![true, null].includes(sample.permissionRequestObserved) || typeof sample.invalidOrOverflow !== 'boolean' || !object(sample.counts) || !Number.isSafeInteger(sample.counts.ready) || sample.counts.ready < 0) throw new Error('invalid role start observation'); + const failures = []; + if (sample.permissionRequestObserved === true) failures.push('unexpected-permission-request'); + if (startResponse.approvalPolicy !== expected.approvalPolicy) failures.push('approval-policy-mismatch'); + if (startResponse.activePermissionProfile != null && !isDeepStrictEqual(startResponse.activePermissionProfile, expected.profile)) failures.push('permission-profile-mismatch'); + if (startResponse.sandbox != null && !isDeepStrictEqual(startResponse.sandbox, expected.sandbox)) failures.push('sandbox-mismatch'); + const unknown = ['plugin-isolation', 'mcp-coverage', 'startup-tokens']; + if (startResponse.activePermissionProfile == null) unknown.push('permission-profile'); + if (startResponse.sandbox == null) unknown.push('sandbox'); + if (sample.invalidOrOverflow) unknown.push('notification-integrity'); + return { schema: 'agent-mesh.codex-role-start-assessment.v1', session: `codex:${startResponse.thread.id}`, + status: failures.length ? 'rollback-required' : 'observed-incomplete', failures, unknown, + readyObserved: sample.counts.ready, mcpStarted: null, startupTokens: null }; +} diff --git a/skills/agent-tmux/bin/codex-wake-evidence.mjs b/skills/agent-tmux/bin/codex-wake-evidence.mjs new file mode 100644 index 00000000..1cb59bd2 --- /dev/null +++ b/skills/agent-tmux/bin/codex-wake-evidence.mjs @@ -0,0 +1,165 @@ +#!/usr/bin/env node +/** Explicitly start one queued waker turn and record private native evidence. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { spawnSync } from 'node:child_process'; +import { dirname, isAbsolute, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { parseArgs } from 'node:util'; +import { withCodexAppServer } from './codex-app-server.mjs'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/; +const hash = value => createHash('sha256').update(value).digest('hex'); +const here = dirname(fileURLToPath(import.meta.url)); + +async function privateRoot(root) { + if (typeof root !== 'string' || !isAbsolute(root)) throw new Error('invalid evidence root'); + const info = await lstat(root); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('evidence root must be private and canonical'); +} + +async function createDurable(root, name, body) { + const fd = await open(join(root, name), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); + try { await fd.writeFile(body); await fd.sync(); } finally { await fd.close(); } + const directory = await open(root, constants.O_RDONLY); + try { await directory.sync(); } finally { await directory.close(); } +} + +// A readback can contain a steered message while the submission is still queued. +// Keep the durable reservation unresolved until queue consumption is provable. +export async function reconcileCodexWake() { + throw new Error('wake reconciliation disabled: queue consumption is unproven'); +} + +// Disabled: a matching client ID can also come from a steer while the queued +// submission remains pending. Readback alone cannot prove queue consumption. +export async function observeAutoCodexWake() { + throw new Error('auto wake observation disabled: queue consumption is unproven'); +} + +async function wakeReadiness(request, thread, queueId, correlation) { + const read = await request('thread/read', { threadId: thread, includeTurns: false }); + if (read?.thread?.id !== thread || !['idle', 'active', 'notLoaded', 'systemError'].includes(read.thread.status?.type)) throw new Error('native thread status unavailable'); + if (read.thread.status.type !== 'idle') return false; + const queue = await request('thread/queue/list', { threadId: thread, limit: 100 }); + if (!Array.isArray(queue?.data) || queue.nextCursor != null) throw new Error('native queue inventory incomplete'); + return queue.data.filter(item => item?.id === queueId && item.clientUserMessageId === correlation && Array.isArray(item.input)).length === 1; +} + +export async function preflightCodexWake({ thread, queueId, correlation }) { + if (typeof thread !== 'string' || !UUID.test(thread) || typeof queueId !== 'string' || !TOKEN.test(queueId) || typeof correlation !== 'string' || !correlation.startsWith('waker-') || !UUID.test(correlation.slice(6))) throw new Error('invalid wake preflight identity'); + thread = thread.toLowerCase(); + const ready = await withCodexAppServer({ clientName: 'agent-mesh-wake-preflight', timeout: 15000, timeoutMessage: 'native preflight unavailable' }, request => wakeReadiness(request, thread, queueId, correlation)); + return { schema: 'agent-mesh.wake-preflight.v1', session: `codex:${thread}`, queueId, correlation, status: ready ? 'ready' : 'not-ready' }; +} + +export async function verifyCodexWakeEvidence({ evidenceRoot, reference, session }) { + if (typeof reference !== 'string' || !/^codex-wake:[a-f0-9]{64}$/.test(reference) || typeof session !== 'string' || !session.startsWith('codex:') || !UUID.test(session.slice(6))) throw new Error('invalid wake verification request'); + await privateRoot(evidenceRoot); + const path = join(evidenceRoot, `wake-${reference.slice('codex-wake:'.length)}.json`), file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let body; + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 4096) throw new Error('invalid wake evidence file'); + body = await file.readFile('utf8'); + const after = await file.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('wake evidence changed'); + } finally { await file.close(); } + if (`codex-wake:${hash(body)}` !== reference) throw new Error('wake digest mismatch'); + let value; + try { value = JSON.parse(body); } catch { throw new Error('invalid wake evidence'); } + const legacy = value && Object.keys(value).sort().join(',') === 'correlation,queueId,schema,session,source,startedAt,turn' && (value.schema === 'agent-mesh.codex-wake-evidence.v2' && value.source === 'codex-app-server.queue-start-readback'); + const bound = value && Object.keys(value).sort().join(',') === 'channel,correlation,generation,payloadSha256,queueId,schema,session,source,startedAt,turn' && value.schema === 'agent-mesh.codex-wake-evidence.v4' && value.source === 'codex-app-server.queue-start-bound-readback' && typeof value.channel === 'string' && /^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.channel) && Number.isSafeInteger(value.generation) && value.generation > 0 && /^[a-f0-9]{64}$/.test(value.payloadSha256); + if (!value || `${JSON.stringify(value)}\n` !== body || !(legacy || bound) || value.session !== session || typeof value.turn !== 'string' || !UUID.test(value.turn) || typeof value.queueId !== 'string' || !TOKEN.test(value.queueId) || typeof value.correlation !== 'string' || !value.correlation.startsWith('waker-') || !UUID.test(value.correlation.slice(6)) || !Number.isSafeInteger(value.startedAt) || value.startedAt <= 0) throw new Error('wake evidence identity mismatch'); + return { ...value, evidence: reference }; +} + +export async function publishCodexWake({ evidenceRoot, reference, session, graphState, channel }) { + if (typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit graph state required'); + const proof = await verifyCodexWakeEvidence({ evidenceRoot, reference, session }); + const observation = `codex-wake-${hash(JSON.stringify([session, proof.queueId]))}`; + const result = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'lifecycle', 'record', '--type', 'session.woken', '--session', session, '--id', observation, '--evidence', reference], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (result.error || result.status !== 0) throw new Error('graph recording failed; retain evidence for explicit publication'); + let receipt; try { receipt = JSON.parse(result.stdout); } catch { throw new Error('graph receipt unavailable'); } + if (receipt?.observation !== observation || typeof receipt.duplicate !== 'boolean') throw new Error('graph receipt mismatch'); + if (channel !== undefined) { + const settled = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'settle-wake', '--name', channel, '--session', session, '--state-root', evidenceRoot, '--input', reference], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (settled.error || settled.status !== 0) throw new Error('wake settlement unavailable; retain evidence for recovery'); + let status; try { status = JSON.parse(settled.stdout); } catch { throw new Error('wake settlement receipt unavailable'); } + const item = status?.channel?.queue?.find(row => row.id === proof.correlation && row.session === session && row.nativeQueueId === proof.queueId); + if (item?.wakeEvidence !== reference) throw new Error('wake settlement receipt mismatch'); + } + return { schema: 'agent-mesh.wake-record.v1', session, evidence: reference, duplicate: receipt.duplicate, ...(channel !== undefined ? { settled: true } : {}) }; +} + +export async function startCodexWake({ thread, queueId, correlation, channel, generation, evidenceRoot, graphState, apply }) { + if (apply !== true || typeof thread !== 'string' || !UUID.test(thread) || typeof queueId !== 'string' || !TOKEN.test(queueId) || typeof correlation !== 'string' || !correlation.startsWith('waker-') || !UUID.test(correlation.slice(6)) || typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel) || !Number.isSafeInteger(generation) || generation < 1 || typeof graphState !== 'string' || !isAbsolute(graphState)) throw new Error('explicit wake identity, channel, generation, graph and apply required'); + await privateRoot(evidenceRoot); + await privateRoot(graphState); + thread = thread.toLowerCase(); + const session = `codex:${thread}`; + const result = await spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'show', '--json'], { encoding: 'utf8', timeout: 30000, maxBuffer: 32 * 1024 * 1024 }); + let graph; try { graph = JSON.parse(result.stdout); } catch { throw new Error('graph unavailable'); } + const matches = Array.isArray(graph.nodes) ? graph.nodes.filter(node => node.agent === 'codex' && node.runtimeUuid === thread) : []; + if (result.error || result.status !== 0 || !graph.migrated || matches.length !== 1 || matches[0].status === 'closed' || matches[0].surface?.archived === true) throw new Error('wake session not registered or closed'); + const intent = hash(JSON.stringify([session, queueId])); + const evidence = await withCodexAppServer({ clientName: 'agent-mesh-wake-evidence', timeout: 30000, timeoutMessage: 'native wake outcome uncertain' }, async request => { + if (!await wakeReadiness(request, thread, queueId, correlation)) throw new Error('native wake not ready'); + const listed = await request('thread/queue/list', { threadId: thread, limit: 100 }); + if (!Array.isArray(listed?.data) || listed.nextCursor != null || listed.data.filter(item => item?.id === queueId && item.clientUserMessageId === correlation && Array.isArray(item.input)).length !== 1) throw new Error('queued waker identity unavailable'); + const reserved = spawnSync(process.execPath, [join(here, 'mesh-graph.mjs'), '--state', graphState, 'channel', 'reserve-wake', '--name', channel, '--id', correlation, '--session', session, '--generation', String(generation), '--input', queueId], { encoding: 'utf8', timeout: 30000, maxBuffer: 65536 }); + if (reserved.error || reserved.status !== 0) throw new Error('wake reservation unavailable or uncertain'); + let reservedChannel; try { reservedChannel = JSON.parse(reserved.stdout)?.channel; } catch { throw new Error('wake reservation receipt unavailable'); } + const reservation = reservedChannel?.wakeReservation; + if (!reservation || reservation.id !== correlation || reservation.session !== session || reservation.generation !== generation || reservation.nativeQueueId !== queueId) throw new Error('wake reservation receipt mismatch'); + const queued = listed.data.find(item => item?.id === queueId && item.clientUserMessageId === correlation); + const boundItems = Array.isArray(reservedChannel.queue) ? reservedChannel.queue.filter(item => item.id === correlation && item.session === session && item.generation === generation && item.nativeQueueId === queueId && item.state === 'accepted' && typeof item.payload === 'string') : []; + if (reservedChannel.id !== channel || reservedChannel.session !== session || reservedChannel.generation !== generation || boundItems.length !== 1 || JSON.stringify(queued.input) !== JSON.stringify([{ type: 'text', text: boundItems[0].payload, text_elements: [] }])) throw new Error('native queue payload does not match channel reservation'); + await createDurable(evidenceRoot, `intent-${intent}.json`, `${JSON.stringify({ schema: 'agent-mesh.codex-wake-intent.v1', session, queueId, correlation })}\n`); + const started = await request('thread/queue/start', { threadId: thread, queuedSubmissionId: queueId }); + const turn = started?.turn; + if (!turn || typeof turn.id !== 'string' || !UUID.test(turn.id) || turn.status !== 'inProgress' || (turn.startedAt != null && (!Number.isSafeInteger(turn.startedAt) || turn.startedAt <= 0))) throw new Error('native wake outcome uncertain'); + // Some runtimes return a valid start with startedAt=null before the turn is + // persisted. Poll only readback; never repeat queue/start after acceptance. + const attempts = turn.startedAt == null ? 21 : 1; + let startedAt; + for (let i = 0; i < attempts; i++) { + const readback = await request('thread/read', { threadId: thread, includeTurns: true }); + const observed = readback?.thread; + if (observed?.id !== thread || !Array.isArray(observed.turns)) throw new Error('wake readback unavailable; outcome uncertain'); + const turns = observed.turns.filter(item => item?.id === turn.id); + if (turns.length > 1) throw new Error('wake readback ambiguous'); + const observedTurn = turns[0]; + const messages = Array.isArray(observedTurn?.items) ? observedTurn.items.filter(item => item?.type === 'userMessage' && item.clientId === correlation) : []; + if (messages.length > 1 || (messages.length === 1 && (!Array.isArray(messages[0].content) || JSON.stringify(messages[0].content) !== JSON.stringify(queued.input)))) throw new Error('wake readback mismatch'); + if (observedTurn && (observedTurn.itemsView === undefined || observedTurn.itemsView === 'full') && Number.isSafeInteger(observedTurn.startedAt) && observedTurn.startedAt > 0 && messages.length === 1) { + if (turn.startedAt != null && observedTurn.startedAt !== turn.startedAt) throw new Error('wake readback timestamp mismatch'); + startedAt = observedTurn.startedAt; break; + } + if (i + 1 < attempts) await new Promise(resolve => setTimeout(resolve, 200)); + } + if (!startedAt) throw new Error('wake readback unavailable; outcome uncertain'); + return { schema: 'agent-mesh.codex-wake-evidence.v4', source: 'codex-app-server.queue-start-bound-readback', session, queueId, correlation, turn: turn.id, startedAt, channel, generation, payloadSha256: hash(boundItems[0].payload) }; + }); + const body = `${JSON.stringify(evidence)}\n`, reference = `codex-wake:${hash(body)}`; + await createDurable(evidenceRoot, `wake-${hash(body)}.json`, body); + return publishCodexWake({ evidenceRoot, reference, session, graphState, channel }); +} + +if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) { + try { + const { values } = parseArgs({ options: { apply: { type: 'boolean' }, preflight: { type: 'boolean' }, reconcile: { type: 'boolean' }, 'observe-auto': { type: 'boolean' }, thread: { type: 'string' }, 'queue-id': { type: 'string' }, correlation: { type: 'string' }, channel: { type: 'string' }, generation: { type: 'string' }, 'evidence-root': { type: 'string' }, 'graph-state': { type: 'string' }, verify: { type: 'string' }, publish: { type: 'string' }, session: { type: 'string' } }, strict: true }); + if (values.preflight && (values.apply || values.reconcile || values['observe-auto'] || values.verify || values.publish)) throw new Error('conflicting wake operations'); + if (values['observe-auto'] && (values.reconcile || values.verify || values.publish)) throw new Error('conflicting wake operations'); + let result; + if (values.preflight) result = await preflightCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation }); + else if (values['observe-auto']) result = await observeAutoCodexWake({ channel: values.channel, thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + else if (values.reconcile) result = await reconcileCodexWake({ channel: values.channel, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + else if (values.verify) result = await verifyCodexWakeEvidence({ evidenceRoot: values['evidence-root'], reference: values.verify, session: values.session }); + else if (values.publish) result = await publishCodexWake({ evidenceRoot: values['evidence-root'], reference: values.publish, session: values.session, graphState: values['graph-state'], channel: values.channel }); + else result = await startCodexWake({ thread: values.thread, queueId: values['queue-id'], correlation: values.correlation, channel: values.channel, generation: /^[1-9][0-9]*$/.test(values.generation || '') ? Number(values.generation) : NaN, evidenceRoot: values['evidence-root'], graphState: values['graph-state'], apply: values.apply }); + console.log(JSON.stringify(result)); + } catch { console.error('wake observation failed or outcome uncertain; inspect before retry'); process.exitCode = 1; } +} diff --git a/skills/agent-tmux/bin/handover-claude-observation.mjs b/skills/agent-tmux/bin/handover-claude-observation.mjs new file mode 100644 index 00000000..2123c009 --- /dev/null +++ b/skills/agent-tmux/bin/handover-claude-observation.mjs @@ -0,0 +1,63 @@ +/** Read-only final-notice evidence from one stable local Claude transcript snapshot. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath, readdir } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { isAbsolute, join, resolve } from 'node:path'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const MAX_TRANSCRIPT = 128 * 1024 * 1024; + +/** Proves only the stable snapshot read; later turns can invalidate the notice. */ +export async function observeClaudeFinalNotice({ root, id, nonce, message }) { + if (typeof root !== 'string' || !isAbsolute(root) || typeof id !== 'string' || !UUID.test(id) || + typeof nonce !== 'string' || !nonce.startsWith('handover-') || !UUID.test(nonce.slice('handover-'.length)) || + typeof message !== 'string' || !message || Buffer.byteLength(message) > 8192) throw new Error('invalid notice observation request'); + root = resolve(root); + const directory = await lstat(root); + if (!directory.isDirectory() || directory.isSymbolicLink() || await realpath(root) !== root) throw new Error('invalid transcript root'); + const entries = await readdir(root, { recursive: true, withFileTypes: true }); + const candidates = entries.filter(entry => entry.isFile() && entry.name.toLowerCase() === `${id.toLowerCase()}.jsonl`) + .map(entry => join(entry.parentPath, entry.name)); + if (candidates.length !== 1) throw new Error('transcript identity unavailable or ambiguous'); + const path = candidates[0]; + if (await realpath(path) !== path) throw new Error('non-canonical transcript'); + const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let bytes; + try { + const before = await handle.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o022) !== 0 || before.size < 1 || before.size > MAX_TRANSCRIPT) throw new Error('invalid transcript file'); + bytes = await handle.readFile(); + const after = await handle.stat(), current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('transcript changed during observation'); + } finally { await handle.close(); } + let text; + try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } + if (!text.endsWith('\n')) throw new Error('partial transcript record'); + let anchored = false, responseId = null, answer = '', completed = false; + for (const line of text.split('\n')) { + if (!line) continue; + let record; + try { record = JSON.parse(line); } catch { throw new Error('invalid transcript record'); } + if (!record || typeof record !== 'object' || Array.isArray(record)) throw new Error('invalid transcript record'); + if (record.isSidechain || record.isMeta || !['user', 'assistant'].includes(record.type)) continue; + if (record.sessionId !== id) throw new Error('transcript session mismatch'); + const content = record.message?.content; + if (record.type === 'user') { + const parts = typeof content === 'string' ? [content] : Array.isArray(content) ? content.filter(part => part?.type === 'text' && typeof part.text === 'string').map(part => part.text) : []; + if (parts.length) { anchored = parts.join('\n').includes(`[HANDOVER:${nonce}]`); responseId = null; answer = ''; completed = false; } + continue; + } + if (!anchored) continue; + const native = record.message; + if (!native || typeof native.id !== 'string' || !native.id || !Array.isArray(content)) throw new Error('invalid assistant record'); + if (native.id !== responseId) { responseId = native.id; answer = ''; completed = false; } + const toolUse = content.some(part => part?.type === 'tool_use'); + const parts = content.filter(part => part?.type === 'text' && typeof part.text === 'string').map(part => part.text); + if (parts.length) answer += parts.join('\n'); + if (native.stop_reason === 'end_turn' && !toolUse) completed = true; + else if (native.stop_reason !== null && native.stop_reason !== undefined) completed = false; + } + if (!anchored || !completed || answer !== message) throw new Error('final notice not proven in transcript snapshot'); + return { schema: 'agent-mesh.final-notice-observation.v1', session: `claude:${id}`, nonce, + messageSha256: createHash('sha256').update(message).digest('hex'), transcriptSha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length }; +} diff --git a/skills/agent-tmux/bin/handover-codex-observation.mjs b/skills/agent-tmux/bin/handover-codex-observation.mjs new file mode 100644 index 00000000..00712de5 --- /dev/null +++ b/skills/agent-tmux/bin/handover-codex-observation.mjs @@ -0,0 +1,75 @@ +/** Read-only final-notice evidence from a local Codex transcript snapshot. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath, readdir } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { isAbsolute, join, resolve } from 'node:path'; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const MAX_TRANSCRIPT = 128 * 1024 * 1024; + +function textOf(record, role) { + const payload = record?.payload; + if (record?.type === 'event_msg' && payload?.type === (role === 'user' ? 'user_message' : 'agent_message')) return typeof payload.message === 'string' ? payload.message : null; + if (record?.type !== 'response_item' || payload?.type !== 'message' || payload.role !== role || !Array.isArray(payload.content)) return null; + const type = role === 'user' ? 'input_text' : 'output_text'; + const parts = payload.content.filter(item => item?.type === type && typeof item.text === 'string').map(item => item.text); + return parts.length ? parts.join('\n') : null; +} + +/** An observation proves only the snapshot read; a later turn may still arrive. */ +export async function observeCodexFinalNotice({ root, id, nonce, message }) { + if (!isAbsolute(root) || typeof id !== 'string' || !UUID.test(id) || typeof nonce !== 'string' || !nonce.startsWith('handover-') || !UUID.test(nonce.slice('handover-'.length)) || + typeof message !== 'string' || !message || Buffer.byteLength(message) > 8192) throw new Error('invalid notice observation request'); + root = resolve(root); + const directory = await lstat(root); + if (!directory.isDirectory() || directory.isSymbolicLink() || await realpath(root) !== root) throw new Error('invalid transcript root'); + const entries = await readdir(root, { recursive: true, withFileTypes: true }); + const candidates = entries.filter(entry => entry.isFile() && entry.name.toLowerCase().endsWith(`${id.toLowerCase()}.jsonl`)) + .map(entry => join(entry.parentPath, entry.name)); + if (candidates.length !== 1) throw new Error('transcript identity unavailable or ambiguous'); + const path = candidates[0]; + if (await realpath(path) !== path) throw new Error('non-canonical transcript'); + const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + let bytes; + try { + const before = await handle.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o022) !== 0 || before.size < 1 || before.size > MAX_TRANSCRIPT) throw new Error('invalid transcript file'); + bytes = await handle.readFile(); + const after = await handle.stat(); + const current = await lstat(path); + if (!current.isFile() || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('transcript changed during observation'); + } finally { await handle.close(); } + let text; + try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error('invalid transcript encoding'); } + if (!text.endsWith('\n')) throw new Error('partial transcript record'); + let meta = false, anchored = false, lastAssistant = null, completed = false; + for (const line of text.split('\n')) { + if (!line) continue; + let record; + try { record = JSON.parse(line); } catch { throw new Error('invalid transcript record'); } + if (!record || typeof record !== 'object' || Array.isArray(record)) throw new Error('invalid transcript record'); + if (record.type === 'session_meta') { + if (meta || record?.payload?.id !== id) throw new Error('transcript session mismatch'); + meta = true; + continue; + } + if (!meta) throw new Error('transcript session metadata missing'); + const user = textOf(record, 'user'); + if (user !== null) { + const newAnchor = user.includes(`[HANDOVER:${nonce}]`); + // Native transcripts can repeat the same user message in two formats. + if (!(anchored && newAnchor && lastAssistant === null && !completed)) { anchored = newAnchor; lastAssistant = null; completed = false; } + continue; + } + if (record.type === 'event_msg' && record?.payload?.type === 'task_started' && completed) { anchored = false; completed = false; lastAssistant = null; } + if (anchored && record.type === 'response_item' && ['function_call', 'custom_tool_call'].includes(record?.payload?.type)) { lastAssistant = null; completed = false; } + const assistant = textOf(record, 'assistant'); + if (assistant !== null && anchored) { if (completed) completed = false; lastAssistant = assistant; } + if (record.type === 'event_msg' && record?.payload?.type === 'task_complete' && anchored) { + completed = lastAssistant === message && record.payload.last_agent_message === message; + } + } + if (!meta || !anchored || !completed) throw new Error('final notice not proven in transcript snapshot'); + return { schema: 'agent-mesh.final-notice-observation.v1', session: `codex:${id}`, nonce, + messageSha256: createHash('sha256').update(message).digest('hex'), transcriptSha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length }; +} diff --git a/skills/agent-tmux/bin/handover-dry-run.mjs b/skills/agent-tmux/bin/handover-dry-run.mjs new file mode 100644 index 00000000..c37ca21b --- /dev/null +++ b/skills/agent-tmux/bin/handover-dry-run.mjs @@ -0,0 +1,20 @@ +/** In-memory rehearsal only. No native session, service, timer or graph is changed. */ +import { beginHandover, createChannel, enqueue, switchHandover, reserveStatePreparation, completeStatePreparation } from './channel-state.mjs'; +import { planRoleLaunch, assessRoleLaunch } from './role-launch-profile.mjs'; + +export async function rehearseHandover({ role, oldSession, newSession, profile, authority, offlineMcp = [], fault = 'none', messageDuringHandover = false }) { + if (typeof role !== 'string' || profile?.role !== role || !['none', 'interrupted', 'quota', 'permission'].includes(fault) || !Array.isArray(offlineMcp) || !offlineMcp.every(name => typeof name === 'string') || typeof messageDuringHandover !== 'boolean') throw new Error('invalid rehearsal'); + let channel = beginHandover(createChannel(`fixture-${role}`, oldSession)); + if (messageDuringHandover) channel = enqueue(channel, 'fixture-message', 'synthetic message'); + const plan = await planRoleLaunch({ profile, authority, probe: async name => !offlineMcp.includes(name) }); + const observed = { mcpStarted: [...plan.mcpToStart], pluginsStarted: [...plan.plugins], permissionPrompt: fault === 'permission', startupTokens: null }; + const launch = assessRoleLaunch({ plan, observed }); + if (fault === 'interrupted' || fault === 'quota' || launch.status !== 'ready') { + channel = { ...channel, phase: 'active' }; + return { schema: 'agent-mesh.handover-rehearsal.v1', simulated: true, outcome: 'rolled-back', reason: fault === 'none' ? launch.reason : fault, channel, launch }; + } + channel = reserveStatePreparation(channel, 'fixture-state'); + channel = completeStatePreparation(channel, { schema: 'agent-mesh.handover-state.v1', session: oldSession, nonce: 'fixture-state', filename: 'fixture.yaml', sha256: 'a'.repeat(64), bytes: 1 }); + channel = switchHandover(channel, newSession, true); + return { schema: 'agent-mesh.handover-rehearsal.v1', simulated: true, outcome: 'switched-awaiting-delivery', reason: null, channel, launch }; +} diff --git a/skills/agent-tmux/bin/handover-notice-transport.mjs b/skills/agent-tmux/bin/handover-notice-transport.mjs new file mode 100644 index 00000000..455f37df --- /dev/null +++ b/skills/agent-tmux/bin/handover-notice-transport.mjs @@ -0,0 +1,54 @@ +/** Native queue adapter; this module does not authorize or perform a cutover. */ +import { execFile } from 'node:child_process'; +import { createHash } from 'node:crypto'; +import { dirname, isAbsolute, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { formatFinalNotice } from './handover-notice.mjs'; +import { observeCodexFinalNotice } from './handover-codex-observation.mjs'; +import { observeClaudeFinalNotice } from './handover-claude-observation.mjs'; + +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const nativeBin = join(dirname(fileURLToPath(import.meta.url)), 'agent-native-call.mjs'); +const digest = value => createHash('sha256').update(value).digest('hex'); +const exec = (command, args, { input, ...options }) => new Promise((resolve, reject) => { + const child = execFile(command, args, options, (error, stdout) => error ? reject(new Error('native notice delivery uncertain')) : resolve({ stdout })); + child.stdin.on('error', () => {}); + child.stdin.end(input); +}); + +/** The caller must first durably reserve this nonce and verify the successor. */ +export async function queueLocalFinalNotice({ session, nonce, target, label, prefix, managedInboxRoot }, runNative = exec) { + if (typeof session !== 'string') throw new Error('invalid local notice session'); + const [agent, id, ...extra] = session.split(':'); + if (!['codex', 'claude'].includes(agent) || !uuid.test(id || '') || extra.length || typeof nonce !== 'string' || !nonce.startsWith('handover-') || !uuid.test(nonce.slice('handover-'.length))) throw new Error('invalid local notice request'); + if (agent === 'claude' && (typeof managedInboxRoot !== 'string' || !isAbsolute(managedInboxRoot))) throw new Error('managed inbox required'); + if (agent === 'codex' && managedInboxRoot !== undefined) throw new Error('managed inbox only for Claude'); + const notice = formatFinalNotice({ target, label, prefix }); + const prompt = `[HANDOVER:${nonce}] The successor has been verified. As your final message, output exactly the following notice and nothing else. Do not call any tools after writing it.\n${notice}`; + const args = [nativeBin, '--agent', agent, '--session', id, '--correlation-id', nonce, '--timeout', '5', '--message-stdin', '--delivery-only']; + if (agent === 'codex') args.push('--no-resume'); + else args.push('--managed-inbox-root', managedInboxRoot); + let result; + try { result = await runNative(process.execPath, args, { input: prompt, timeout: 10000, maxBuffer: 8192 }); } + catch { throw new Error('native notice delivery uncertain; do not resend'); } + let receipt; + try { receipt = JSON.parse(result?.stdout); } catch { throw new Error('native notice delivery uncertain; do not resend'); } + if (!receipt || receipt.agent !== agent || receipt.sessionId !== id || receipt.correlationId !== nonce || receipt.held === true || receipt.status !== 'queued') throw new Error('native notice delivery unconfirmed; do not resend'); + return { schema: 'agent-mesh.notice-queue.v1', session, nonce, noticeSha256: digest(notice), status: 'queued-unverified' }; +} + +/** Call only after reserving in the trusted graph and acquiring lifecycle exclusion. */ +export async function queueReservedFinalNotice({ reservation, target, label, prefix, managedInboxRoot }, runNative = exec) { + if (!reservation || reservation.status !== 'requested' || typeof reservation.session !== 'string' || typeof reservation.id !== 'string' || !target || target.kind !== 'codex' || reservation.successor !== `codex:${target.id}` || reservation.noticeSha256 !== digest(formatFinalNotice({ target, label, prefix }))) throw new Error('final notice reservation does not match request'); + return queueLocalFinalNotice({ session: reservation.session, nonce: reservation.id, target, label, prefix, managedInboxRoot }, runNative); +} + +/** Obtain local native transcript evidence independently from the queue receipt. */ +export async function observeLocalFinalNotice({ session, nonce, target, label, prefix, transcriptRoot }) { + if (typeof session !== 'string') throw new Error('invalid local notice session'); + const [agent, id, ...extra] = session.split(':'); + if (!['codex', 'claude'].includes(agent) || !uuid.test(id || '') || extra.length) throw new Error('invalid local notice session'); + const message = formatFinalNotice({ target, label, prefix }); + const observe = agent === 'codex' ? observeCodexFinalNotice : observeClaudeFinalNotice; + return observe({ root: transcriptRoot, id, nonce, message }); +} diff --git a/skills/agent-tmux/bin/handover-notice.mjs b/skills/agent-tmux/bin/handover-notice.mjs new file mode 100644 index 00000000..8ab384c4 --- /dev/null +++ b/skills/agent-tmux/bin/handover-notice.mjs @@ -0,0 +1,32 @@ +/** Build a successor link from resolved identifiers, never from a guessed URL. */ +const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +const projectId = /^[A-Za-z0-9_-]{1,256}$/; +const threadId = /^cmsg_[A-Za-z0-9_-]{1,250}$/; + +export function successorLink(target) { + if (!target || typeof target !== 'object') throw new Error('invalid successor'); + if (target.kind === 'codex' && typeof target.id === 'string' && uuid.test(target.id)) return `codex://threads/${target.id}`; + if (target.kind === 'cloud' && typeof target.sourceProject === 'string' && projectId.test(target.sourceProject) && + typeof target.targetProject === 'string' && projectId.test(target.targetProject) && + typeof target.thread === 'string' && threadId.test(target.thread)) { + return target.sourceProject === target.targetProject ? `#${target.thread}` : + `https://claude.ai/code/project/${target.targetProject}?thread=${target.thread}`; + } + throw new Error('invalid successor link identifiers'); +} + +export function formatFinalNotice({ target, label, prefix }) { + if (typeof label !== 'string' || !label.trim() || label.length > 300 || /[\r\n\x00-\x1f\x7f]/.test(label) || + typeof prefix !== 'string' || !prefix.trim() || prefix.length > 500 || /[\r\n\x00-\x1f\x7f]/.test(prefix)) throw new Error('invalid notice text'); + const escaped = label.replace(/[\\\[\]]/g, '\\$&'); + return `${prefix} [${escaped}](${successorLink(target)})`; +} + +/** Compare a trusted, complete transcript observation; this does not obtain one. */ +export function matchesFinalNotice(observation, { session, message }) { + if (!observation || observation.complete !== true || observation.session !== session || + typeof session !== 'string' || !session || typeof message !== 'string' || !message || + !Array.isArray(observation.messages) || !observation.messages.length) return false; + const last = observation.messages.at(-1); + return Boolean(last && last.role === 'assistant' && last.text === message); +} diff --git a/skills/agent-tmux/bin/handover-state-proof.mjs b/skills/agent-tmux/bin/handover-state-proof.mjs new file mode 100644 index 00000000..c3c247e8 --- /dev/null +++ b/skills/agent-tmux/bin/handover-state-proof.mjs @@ -0,0 +1,90 @@ +/** Verify an actor's correlated response against a private state file. */ +import { constants } from 'node:fs'; +import { lstat, open, realpath } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; +import { randomUUID } from 'node:crypto'; +import { execFile, spawnSync } from 'node:child_process'; +import { dirname, isAbsolute, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { validateRestartState } from './restart-state.mjs'; + +const nativeBin = join(dirname(fileURLToPath(import.meta.url)), 'agent-native-call.mjs'); +const yamlBin = join(dirname(fileURLToPath(import.meta.url)), 'restart-yaml.py'); +const exec = (command, args, { input, ...options }) => new Promise((resolve, reject) => { + const child = execFile(command, args, options, (error, stdout) => { + if (error) reject(new Error('native state request failed')); + else resolve({ stdout }); + }); + child.stdin.on('error', () => {}); + child.stdin.end(input); +}); + +// reserve and complete are atomic host mutations; a failed request deliberately +// leaves the reservation unresolved so a caller cannot silently resend it. +export async function prepareState({ reserve, request, complete }) { + const reservation = reserve(); + const pending = reservation?.statePreparation; + if (!pending || pending.status !== 'requested' || typeof pending.session !== 'string' || typeof pending.id !== 'string') throw new Error('state preparation reservation unavailable'); + const proof = await request(pending); + return complete(proof); +} + +/** Obtain a correlated native-session result, then bind it to file bytes. */ +export async function requestStateProof({ session, channel, root, filename, managedInboxRoot, nonce = `handover-${randomUUID()}` }, runNative = exec) { + if (!/^(codex|claude):[0-9a-f-]{36}$/.test(session) || !isAbsolute(root) || /[\r\n\x00]/.test(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error('invalid state proof request'); + const rootInfo = await lstat(root); + if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink() || rootInfo.uid !== process.getuid() || (rootInfo.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('state root must be private and canonical'); + const [agent, nativeId] = session.split(':'); + if (agent === 'claude' && (typeof managedInboxRoot !== 'string' || !isAbsolute(managedInboxRoot))) throw new Error('managed inbox required'); + if (typeof nonce !== 'string' || !/^[a-zA-Z0-9._:-]{1,128}$/.test(nonce)) throw new Error('invalid request nonce'); + if (typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel)) throw new Error('invalid state proof channel'); + const message = `Write your handover state with a RIAVVIO YAML block using agent-mesh.restart.v1 to ${join(root, filename)} with private permissions. Bind the block to session ${session} and channel ${channel}, and include harness, working_directory, skills, triggers, goal and role_profile with schema agent-mesh.role-profile.v1, role and exact identifier lists permissions, mcp, plugins. List only existing grants; do not grant anything. Return only JSON with schema agent-mesh.handover-state.v1, session ${session}, nonce ${nonce}, filename ${filename}, and sha256 containing the lowercase SHA-256 of the completed file.`; + const argv = [nativeBin, '--agent', agent, '--session', nativeId, '--correlation-id', nonce, '--timeout', '120', '--message-stdin']; + if (agent === 'codex') argv.push('--no-resume'); + if (agent === 'claude') argv.push('--managed-inbox-root', managedInboxRoot); + const result = await runNative(process.execPath, argv, { input: message, timeout: 125000, maxBuffer: 8192 }); + if (!result || typeof result.stdout !== 'string') throw new Error('native result unavailable'); + return verifyStateResponse({ session, channel, nonce, response: result.stdout, root, filename }); +} + +// The caller must obtain response from the native correlated-result transport, +// bound to session and nonce. This function cannot authenticate arbitrary text. +export async function verifyStateResponse({ session, channel, nonce, response, root, filename }) { + if (!/^(codex|claude):[0-9a-f-]{36}$/.test(session) || !/^[a-zA-Z0-9._:-]{1,128}$/.test(nonce) || !isAbsolute(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error('invalid state proof request'); + const rootInfo = await lstat(root); + if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink() || rootInfo.uid !== process.getuid() || (rootInfo.mode & 0o077) !== 0 || await realpath(root) !== root) throw new Error('state root must be private and canonical'); + if (typeof response !== 'string' || Buffer.byteLength(response) > 8192) throw new Error('invalid state response'); + let attestation; + try { attestation = JSON.parse(response); } catch { throw new Error('invalid state response'); } + if (!attestation || attestation.schema !== 'agent-mesh.handover-state.v1' || attestation.session !== session || attestation.nonce !== nonce || attestation.filename !== filename || !/^[0-9a-f]{64}$/.test(attestation.sha256)) throw new Error('state response binding mismatch'); + const file = await open(join(root, filename), constants.O_RDONLY | constants.O_NOFOLLOW); + try { + const before = await file.stat(); + if (!before.isFile() || before.uid !== process.getuid() || before.nlink !== 1 || (before.mode & 0o077) !== 0 || before.size < 1 || before.size > 1024 * 1024) throw new Error('invalid state file'); + const bytes = await file.readFile(); + const after = await file.stat(), current = await lstat(join(root, filename)), currentRoot = await lstat(root); + if (!current.isFile() || current.isSymbolicLink() || current.ino !== after.ino || current.dev !== after.dev || current.size !== after.size || current.mtimeMs !== after.mtimeMs || current.ctimeMs !== after.ctimeMs || !currentRoot.isDirectory() || currentRoot.isSymbolicLink() || currentRoot.ino !== rootInfo.ino || currentRoot.dev !== rootInfo.dev || before.ino !== after.ino || before.dev !== after.dev || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('state file changed during verification'); + const digest = createHash('sha256').update(bytes).digest('hex'); + if (digest !== attestation.sha256) throw new Error('state file digest mismatch'); + if (typeof channel !== 'string' || !/^#?[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(channel)) throw new Error('invalid state proof channel'); + const decoded = spawnSync(process.env.PYTHON || 'python3', ['-I', yamlBin], { input: bytes, encoding: 'utf8', timeout: 10000, maxBuffer: 2 * 1024 * 1024 }); + if (decoded.error || decoded.status !== 0) throw new Error('restart YAML unavailable or invalid'); + let restart; + try { restart = JSON.parse(decoded.stdout); } catch { throw new Error('invalid restart YAML result'); } + validateRestartState(restart, { session, channel, requireRoleProfile: true }); + const final = await lstat(join(root, filename)), finalRoot = await lstat(root); + if (!final.isFile() || final.isSymbolicLink() || final.dev !== after.dev || final.ino !== after.ino || final.size !== after.size || final.mtimeMs !== after.mtimeMs || final.ctimeMs !== after.ctimeMs || !finalRoot.isDirectory() || finalRoot.isSymbolicLink() || finalRoot.dev !== rootInfo.dev || finalRoot.ino !== rootInfo.ino) throw new Error('state file changed during verification'); + return { schema: attestation.schema, session, nonce, filename, sha256: digest, bytes: bytes.length }; + } finally { await file.close(); } +} + +// Revalidate the bytes referenced by a previously authenticated graph receipt. +// The caller owns lifecycle exclusion and must also bind this check to its +// subsequent action; a snapshot cannot prevent later file replacement. +export async function revalidateStateProof({ root, channel, session, generation, statePreparation }) { + if (!statePreparation || statePreparation.status !== 'verified' || statePreparation.session !== session || !Number.isSafeInteger(generation) || generation < 1 || statePreparation.generation !== generation || typeof statePreparation.id !== 'string' || typeof statePreparation.filename !== 'string' || !/^[0-9a-f]{64}$/.test(statePreparation.sha256 || '') || !Number.isSafeInteger(statePreparation.bytes) || statePreparation.bytes < 1) throw new Error('state preparation receipt mismatch'); + const response = JSON.stringify({ schema: 'agent-mesh.handover-state.v1', session, nonce: statePreparation.id, filename: statePreparation.filename, sha256: statePreparation.sha256 }); + const result = await verifyStateResponse({ session, channel, nonce: statePreparation.id, response, root, filename: statePreparation.filename }); + if (result.bytes !== statePreparation.bytes) throw new Error('state preparation size mismatch'); + return result; +} diff --git a/skills/agent-tmux/bin/isolated-pid-namespace.py b/skills/agent-tmux/bin/isolated-pid-namespace.py new file mode 100644 index 00000000..002b6e93 --- /dev/null +++ b/skills/agent-tmux/bin/isolated-pid-namespace.py @@ -0,0 +1,199 @@ +#!/usr/bin/env python3 +"""Experimental, network-isolated PID namespace lease for owned processes. + +No handover or session lifecycle uses this module. It is not an authorization +boundary and cannot undo remote effects. A caller must keep the lease alive. +""" +import errno +import json +import os +from pathlib import Path +import select +import signal +import stat +import subprocess +import sys +import time +import uuid + +BWRAP = '/usr/bin/bwrap' +GATE = str(Path(__file__).resolve().with_name('namespace-exec-gate.py')) + + +def _identity(pid): + proc = Path('/proc') / str(pid) + meta = proc.stat() + fields = (proc / 'stat').read_text().rsplit(')', 1)[1].split() + status = (proc / 'status').read_text().splitlines() + nested = next(line for line in status if line.startswith('NSpid:')).split()[1:] + return meta.st_uid, int(fields[1]), fields[19], nested, (proc / 'ns/pid').stat().st_ino + + +def _pidfd_pid(fd): + lines = Path(f'/proc/self/fdinfo/{fd}').read_text().splitlines() + return int(next(line for line in lines if line.startswith('Pid:')).split()[1]) + + +class IsolatedNamespace: + """An owned lease, prepared but not released; do not target external PIDs.""" + def __init__(self, process, pidfd, gatefd): + self.process = process + self._pidfd = pidfd + self._gatefd = gatefd + self._released = False + self._stopped = False + + @classmethod + def prepare(cls, workspace, command, *, timeout=5): + if not hasattr(os, 'pidfd_open') or not hasattr(signal, 'pidfd_send_signal'): + raise RuntimeError('pidfd support unavailable') + root = Path(workspace) + if not root.is_absolute() or root.resolve(strict=True) != root: + raise ValueError('workspace must be canonical') + info = root.lstat() + if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077: + raise ValueError('workspace must be private') + if not isinstance(command, list) or not command or len(command) > 64 or not os.path.isabs(command[0]) or any(not isinstance(item, str) or not item or len(item) > 8192 or '\x00' in item for item in command) or isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not 0 < timeout <= 30: + raise ValueError('invalid isolated command') + fifo = root / f'.namespace-gate-{uuid.uuid4().hex}' + os.mkfifo(fifo, 0o600) + before = fifo.lstat() + readfd, writefd = os.pipe() + process = None + pidfd = None + gatefd = None + verified = False + try: + args = [BWRAP, '--ro-bind', '/', '/', '--tmpfs', '/tmp', '--bind', str(root), str(root), + '--proc', '/proc', '--dev', '/dev', '--unshare-pid', '--unshare-net', '--die-with-parent', + '--info-fd', str(writefd), '--clearenv', '--setenv', 'PATH', '/usr/bin:/bin', + '--chdir', str(root), sys.executable, '-B', GATE, str(fifo), '--', *command] + process = subprocess.Popen(args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, + pass_fds=(writefd,), start_new_session=True) + os.close(writefd) + writefd = None + deadline = time.monotonic() + timeout + raw = b'' + while True: + remaining = deadline - time.monotonic() + if remaining <= 0 or not select.select([readfd], [], [], remaining)[0]: + raise RuntimeError('namespace information unavailable') + chunk = os.read(readfd, 8193 - len(raw)) + if not chunk: + raise RuntimeError('incomplete namespace information') + raw += chunk + if len(raw) > 8192: + raise RuntimeError('invalid namespace information') + try: + record = json.loads(raw) + break + except json.JSONDecodeError: + continue + pid, inode = record.get('child-pid'), record.get('pid-namespace') + if isinstance(pid, bool) or not isinstance(pid, int) or pid < 2 or isinstance(inode, bool) or not isinstance(inode, int): + raise RuntimeError('invalid namespace identity') + first = _identity(pid) + if first[0] != os.getuid() or first[1] != process.pid or first[3][-1:] != ['1'] or first[4] != inode or inode == Path('/proc/self/ns/pid').stat().st_ino: + raise RuntimeError('namespace ownership unverified') + pidfd = os.pidfd_open(pid) + if _pidfd_pid(pidfd) != pid or _identity(pid) != first: + raise RuntimeError('namespace identity changed') + verified = True + deadline = time.monotonic() + timeout + while True: + try: + gatefd = os.open(fifo, os.O_WRONLY | os.O_NONBLOCK | os.O_NOFOLLOW) + break + except OSError as exc: + if exc.errno != errno.ENXIO or time.monotonic() >= deadline: + raise + time.sleep(.01) + opened = os.fstat(gatefd) + if not stat.S_ISFIFO(opened.st_mode) or opened.st_uid != os.getuid() or opened.st_mode & 0o077 or opened.st_nlink != 1 or (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino): + raise RuntimeError('gate identity changed') + result = cls(process, pidfd, gatefd) + pidfd = None + return result + except Exception as exc: + # Never release the gate on error. If ownership was verified, the + # pinned namespace init can be stopped without targeting another PID. + if pidfd is not None: + if verified: + try: + signal.pidfd_send_signal(pidfd, signal.SIGKILL) + except ProcessLookupError: + pass + os.close(pidfd) + if gatefd is not None: + os.close(gatefd) + elif process is not None and not verified: + # An empty writer makes the trusted gate refuse execution. Do + # not touch a FIFO that no longer has the original identity. + deadline = time.monotonic() + 2 + while time.monotonic() < deadline: + abortfd = None + try: + abortfd = os.open(fifo, os.O_WRONLY | os.O_NONBLOCK | os.O_NOFOLLOW) + opened = os.fstat(abortfd) + if not stat.S_ISFIFO(opened.st_mode) or (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino): + break + break + except OSError as abort_error: + if abort_error.errno != errno.ENXIO: + break + time.sleep(.01) + finally: + if abortfd is not None: + os.close(abortfd) + if process is not None: + try: + process.wait(timeout=2) + except subprocess.TimeoutExpired: + # An unverified namespace may need operator reconciliation. + pass + for stream in (process.stdin, process.stdout, process.stderr): + if stream: + stream.close() + raise RuntimeError('isolated preparation failed; cleanup may be unverified') from exc + finally: + os.close(readfd) + if writefd is not None: + os.close(writefd) + + def release(self): + if self._stopped or self._released or self._gatefd is None: + raise RuntimeError('gate unavailable') + try: + if os.write(self._gatefd, b'GO\n') != 3: + raise RuntimeError('gate release uncertain') + finally: + os.close(self._gatefd) + self._gatefd = None + self._released = True + + def stop(self, *, timeout=5): + if self._stopped or self._pidfd is None or isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not 0 < timeout <= 30: + raise RuntimeError('namespace lease unavailable') + try: + signal.pidfd_send_signal(self._pidfd, signal.SIGKILL) + except ProcessLookupError: + pass + poller = select.poll() + poller.register(self._pidfd, select.POLLIN) + if not poller.poll(int(timeout * 1000)): + raise RuntimeError('namespace init exit unverified') + try: + self.process.wait(timeout=timeout) + except subprocess.TimeoutExpired as exc: + raise RuntimeError('namespace wrapper exit unverified') from exc + if self._gatefd is not None: + os.close(self._gatefd) + self._gatefd = None + os.close(self._pidfd) + self._pidfd = None + self._stopped = True + for stream in (self.process.stdin, self.process.stdout, self.process.stderr): + if stream: + stream.close() + return {'schema': 'agent-mesh.isolated-namespace-stop.v1', 'status': 'init-exited', + 'descendants': 'unverified', 'remoteEffects': 'unverified'} diff --git a/skills/agent-tmux/bin/isolated-role-rollback.py b/skills/agent-tmux/bin/isolated-role-rollback.py new file mode 100644 index 00000000..516df67e --- /dev/null +++ b/skills/agent-tmux/bin/isolated-role-rollback.py @@ -0,0 +1,118 @@ +#!/usr/bin/env python3 +"""Crash-conservative stop of an owned isolated successor. + +This is not a handover controller or an authorization boundary. The caller +must bind the native assessment and owned stop callback to the same successor, +and consistently use the same private journal root for that session. +""" +import copy +import hashlib +import json +import os +from pathlib import Path +import re +import stat +import threading + + +SESSION = re.compile(r'^codex:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$', re.I) + + +def _open_private_root(root): + if not isinstance(root, str) or not os.path.isabs(root) or str(Path(root).resolve(strict=True)) != root: + raise ValueError('journal root must be absolute and canonical') + before = os.lstat(root) + if not stat.S_ISDIR(before.st_mode) or before.st_uid != os.getuid() or before.st_mode & 0o077: + raise ValueError('journal root must be private and owned') + fd = os.open(root, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW) + opened = os.fstat(fd) + if (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino): + os.close(fd) + raise ValueError('journal root changed') + return fd + + +def _verify_root(root, fd): + current = os.lstat(root) + opened = os.fstat(fd) + if (not stat.S_ISDIR(current.st_mode) or current.st_uid != os.getuid() or current.st_mode & 0o077 + or (current.st_dev, current.st_ino) != (opened.st_dev, opened.st_ino)): + raise ValueError('journal root changed') + + +def _write_once(directory_fd, name, record): + body = (json.dumps(record, separators=(',', ':'), sort_keys=True) + '\n').encode() + fd = os.open(name, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=directory_fd) + try: + view = memoryview(body) + while view: + written = os.write(fd, view) + if written <= 0: + raise OSError('journal write incomplete') + view = view[written:] + os.fsync(fd) + finally: + os.close(fd) + os.fsync(directory_fd) + + +class IsolatedRoleRollback: + def __init__(self, expected_session, stop_owned_successor, journal_root): + if not isinstance(expected_session, str) or not SESSION.fullmatch(expected_session) or expected_session != expected_session.lower() or not callable(stop_owned_successor): + raise ValueError('invalid isolated successor binding') + self._session = expected_session + self._stop = stop_owned_successor + self._journal_root = journal_root + self._key = hashlib.sha256(expected_session.encode()).hexdigest() + self._lock = threading.Lock() + self._receipt = None + + def apply(self, assessment): + if (not isinstance(assessment, dict) or assessment.get('schema') != 'agent-mesh.codex-role-start-assessment.v1' + or assessment.get('session') != self._session or assessment.get('status') not in ('observed-incomplete', 'rollback-required') + or not isinstance(assessment.get('failures'), list) + or any(not isinstance(item, str) or not item for item in assessment['failures'])): + raise ValueError('invalid or mismatched role assessment') + if assessment['status'] == 'rollback-required' and not assessment['failures']: + raise ValueError('rollback requires a stated failure') + if assessment['status'] == 'observed-incomplete' and assessment['failures']: + raise ValueError('inconsistent incomplete assessment') + with self._lock: + if self._receipt is not None: + return copy.deepcopy(self._receipt) + if assessment['status'] == 'observed-incomplete': + return {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'blocked-incomplete', + 'session': self._session, 'handover': 'blocked'} + directory_fd = _open_private_root(self._journal_root) + try: + intent = {'schema': 'agent-mesh.isolated-role-stop-intent.v1', 'session': self._session} + try: + _write_once(directory_fd, f'stop-{self._key}.intent.json', intent) + except FileExistsError: + self._receipt = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'stop-uncertain', + 'session': self._session, 'handover': 'blocked'} + return copy.deepcopy(self._receipt) + _verify_root(self._journal_root, directory_fd) + # Persist and fsync the attempt before the side effect. Never retry + # automatically after a crash or an ambiguous callback result. + self._receipt = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'stop-uncertain', + 'session': self._session, 'handover': 'blocked'} + try: + receipt = self._stop() + except Exception: + receipt = None + result = copy.deepcopy(self._receipt) + if (isinstance(receipt, dict) and receipt.get('schema') == 'agent-mesh.isolated-namespace-stop.v1' + and receipt.get('status') == 'init-exited' and receipt.get('descendants') == 'unverified' + and receipt.get('remoteEffects') == 'unverified'): + result = {'schema': 'agent-mesh.isolated-role-rollback.v1', 'status': 'local-init-exited', + 'session': self._session, 'handover': 'blocked', + 'namespaceStop': {key: receipt[key] for key in ('schema', 'status', 'descendants', 'remoteEffects')}} + try: + _write_once(directory_fd, f'stop-{self._key}.result.json', result) + except OSError: + return copy.deepcopy(self._receipt) + self._receipt = result + return copy.deepcopy(self._receipt) + finally: + os.close(directory_fd) diff --git a/skills/agent-tmux/bin/mesh-comms.py b/skills/agent-tmux/bin/mesh-comms.py index b5af653d..fc3e3485 100755 --- a/skills/agent-tmux/bin/mesh-comms.py +++ b/skills/agent-tmux/bin/mesh-comms.py @@ -107,6 +107,10 @@ def validate(spec): not re.fullmatch(r'(session|cse)_[A-Za-z0-9]{1,128}', spec['destination']) or spec.get('resume') or spec.get('inbox_root')): raise ValueError('invalid Claude cloud destination') + profile_keys = ('cloud_profile', 'cloud_scope', 'cloud_profile_digest') + if any(key in spec for key in profile_keys): + if not spec.get('cloud') or not all(isinstance(spec.get(key), str) for key in profile_keys) or not Path(spec['cloud_profile']).is_absolute() or not re.fullmatch(r'[a-z][a-z0-9-]{0,63}', spec['cloud_scope']) or not re.fullmatch(r'[0-9a-f]{64}', spec['cloud_profile_digest']): + raise ValueError('invalid cloud account profile') if 'steer_first' in spec and (spec['steer_first'] is not True or spec['kind'] != 'native' or spec['runtime'] != 'codex' or spec.get('cloud')): raise ValueError('invalid steer-or-queue destination') claude_goal = spec['runtime'] == 'claude' and not spec.get('cloud') and 'goal_resume' not in spec @@ -244,6 +248,8 @@ def observe_inbox(spec, ident, confirmed): def identity(spec): destination = [spec['kind'], spec['runtime'], spec['destination'], spec.get('socket'), spec.get('correlation') or encode(spec)] + if spec.get('cloud_profile'): + destination.append(spec['cloud_scope']) return hashlib.sha256(encode(destination).encode()).hexdigest() @@ -253,6 +259,8 @@ def command(spec): '--correlation-id', spec['correlation'], '--message', spec['message'], '--delivery-only'] if spec.get('cloud'): args += ['--cloud'] + if spec.get('cloud_profile'): + args += ['--cloud-profile', spec['cloud_profile'], '--cloud-scope', spec['cloud_scope'], '--cloud-profile-digest', spec['cloud_profile_digest']] if spec.get('steer_first'): args += ['--steer-or-queue'] if spec.get('inbox_root'): diff --git a/skills/agent-tmux/bin/mesh-graph.mjs b/skills/agent-tmux/bin/mesh-graph.mjs index 034563c1..9093c826 100755 --- a/skills/agent-tmux/bin/mesh-graph.mjs +++ b/skills/agent-tmux/bin/mesh-graph.mjs @@ -18,6 +18,7 @@ import { readFileSync, readSync, readlinkSync, + realpathSync, renameSync, rmSync, statSync, @@ -25,7 +26,7 @@ import { writeSync, } from "node:fs"; import { homedir } from "node:os"; -import { dirname, join, resolve } from "node:path"; +import { dirname, isAbsolute, join, resolve } from "node:path"; import { randomUUID, createHash } from "node:crypto"; import { spawn, spawnSync } from "node:child_process"; import { fileURLToPath } from "node:url"; @@ -34,6 +35,14 @@ import * as plexus from "./plexus.mjs"; import { catalogList, catalogUpdate, roleOperation, parseCatalogSessionId } from "./session-catalog.mjs"; import { linkTargets, successor, verifyLinks } from "./session-links.mjs"; +import { readModuleRegistry, describeModule, invokeModule } from "./plexus-modules.mjs"; +import { validateModuleBatch, applyModuleBatch } from "./module-batches.mjs"; +import { createChannel, enqueue, beginHandover, beginDelivery, acknowledge, observeDelivery, reserveWake, settleWake, reserveStatePreparation, completeStatePreparation, reserveFinalNotice, recordNoticeObservation } from "./channel-state.mjs"; +import { observeClaudeDelivery, assertClaudeDeliverySnapshotCurrent } from "./claude-delivery-observation.mjs"; +import { verifyCodexWakeEvidence } from "./codex-wake-evidence.mjs"; +import { prepareState, requestStateProof, revalidateStateProof } from "./handover-state-proof.mjs"; +import { formatFinalNotice } from "./handover-notice.mjs"; +import { observeLocalFinalNotice } from "./handover-notice-transport.mjs"; const REGISTRY_SCHEMA = "agent-mesh.session-registry.v1"; const ORIGINS = new Set(["human", "desktop-task", "bridge-worker", "subagent", "automation", "cloud"]); @@ -61,6 +70,10 @@ const { values, positionals } = parseArgs({ options: { state: { type: "string" }, session: { type: "string" }, + generation: { type: "string" }, + "state-root": { type: "string" }, + filename: { type: "string" }, + "managed-inbox-root": { type: "string" }, project: { type: "string" }, archive: { type: "string" }, ttl: { type: "string" }, @@ -93,6 +106,7 @@ const { values, positionals } = parseArgs({ evidence: { type: "string" }, input: { type: "string" }, config: { type: "string" }, + name: { type: "string" }, sort: { type: "string" }, filter: { type: "string", multiple: true }, format: { type: "string" }, @@ -119,7 +133,7 @@ if (values.help || positionals.length === 0) { } const command = positionals[0]; const subcommand = positionals[1]; -const SUBCOMMANDS = { links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; +const SUBCOMMANDS = { channel: ["create", "get", "enqueue", "begin-delivery", "acknowledge", "observe-claude-delivery", "recover-claude-delivery", "verify-claude-delivery", "reserve-wake", "settle-wake", "begin-handover", "prepare-state", "revalidate-state", "reserve-notice", "observe-notice", "finish-handover"], lifecycle: ["record"], module: ["list", "describe", "apply", "run", "conformance"], links: ["verify"], cloud: ["register", "get"], catalog: ["register", "update", "list", "backfill"], role: ["claim", "heartbeat", "check", "release", "run", "maintain", "list"], ledger: ["sync"], ref: ["add", "remove"], edge: ["end"], query: [...Object.keys(QUERIES), "view", "changes"] }; if (SUBCOMMANDS[command]) { if (positionals.length !== 2) fail(`${command} requires exactly one operation: ${SUBCOMMANDS[command].join(", ")}`); } else if (command === "link" && positionals.length === 2) { @@ -131,6 +145,306 @@ const stateDir = resolve(values.state || GRAPH_DIR); try { switch (command) { + case "channel": { + const name = requiredSingleLine(values.name, "--name"); + const channelInput = values.input === "-" ? readBoundedChannelInput() : values.input; + assertPrivateChannelState(stateDir); + if (subcommand === "get") { + const channel = (loadGraph(stateDir).channels || []).find((item) => item.id === name); + if (!channel) throw new Error("unknown channel"); + printResult({ channel }, { json: true }); + break; + } + if (subcommand === "verify-claude-delivery") { + const id = requiredSingleLine(values.id, "--id"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); + const items = channel?.queue?.filter(item => item.id === id && ['accepted', 'observed'].includes(item.state) && item.session?.startsWith('claude:')); + const item = items?.length === 1 ? items[0] : undefined, saved = item?.deliveryProof; + if (!saved || typeof saved.evidence !== 'string' || !/^[0-9a-f]{64}$/.test(saved.transcriptSha256 || '') || !Number.isSafeInteger(saved.transcriptBytes)) throw new Error('Claude delivery proof unavailable'); + const root = process.env.CLAUDE_SESSION_ROOT || join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'projects'); + if (!isAbsolute(root)) throw new Error('invalid configured transcript root'); + const proof = await observeClaudeDelivery({ root, session: item.session, generation: item.generation, messageId: id, payload: item.payload, snapshotBytes: saved.transcriptBytes }); + assertClaudeDeliverySnapshotCurrent(proof); + if (proof.evidence !== saved.evidence || proof.transcriptSha256 !== saved.transcriptSha256) throw new Error('Claude delivery proof mismatch'); + const latest = (loadGraph(stateDir).channels || []).find(row => row.id === name)?.queue?.find(row => row.id === id); + if (!latest || latest.session !== item.session || latest.generation !== item.generation || latest.payload !== item.payload || JSON.stringify(latest.deliveryProof) !== JSON.stringify(saved)) throw new Error('delivery changed during verification'); + printResult({ channel: name, messageId: id, status: 'verified', evidence: proof.evidence }, { json: true }); + break; + } + if (subcommand === "recover-claude-delivery") { + const id = requiredSingleLine(values.id, "--id"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); + const pending = channel?.queue?.filter(item => item.id === id && item.state === "inflight" && item.session === channel.session && item.generation === channel.generation); + if (!['active', 'draining'].includes(channel?.phase) || pending?.length !== 1 || !channel.session.startsWith("claude:")) throw new Error("Claude delivery recovery unavailable"); + const root = process.env.CLAUDE_SESSION_ROOT || join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "projects"); + if (!isAbsolute(root)) throw new Error("invalid configured transcript root"); + const proof = await observeClaudeDelivery({ root, session: channel.session, generation: channel.generation, messageId: id, payload: pending[0].payload }); + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + const item = current?.queue?.find(row => row.id === id); + if (!item || current.phase !== channel.phase || item.state !== 'inflight' || item.session !== proof.session || item.generation !== proof.generation || current.session !== proof.session || current.generation !== proof.generation || typeof item.payload !== 'string' || createHash('sha256').update(item.payload).digest('hex') !== proof.payloadSha256) throw new Error('delivery changed during recovery'); + assertClaudeDeliverySnapshotCurrent(proof); + let next = acknowledge(current, id, { status: 'accepted', messageId: id, session: proof.session, generation: proof.generation }); + if (next.phase === 'draining' && next.handover?.backlog?.includes(id)) next = observeDelivery(next, id, proof); + next.queue.find(row => row.id === id).deliveryProof = { evidence: proof.evidence, transcriptSha256: proof.transcriptSha256, transcriptBytes: proof.transcriptBytes }; + return { graph, event: event('channel.updated', { channel: next }), result: { channel: name, messageId: id, evidence: proof.evidence, status: next.queue.find(row => row.id === id).state } }; + }); + printResult(result, { json: true }); + break; + } + if (subcommand === "observe-claude-delivery") { + const id = requiredSingleLine(values.id, "--id"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); + const pending = channel?.queue?.filter(item => item.id === id && item.state === "accepted" && item.session === channel.session && item.generation === channel.generation); + if (channel?.phase !== "draining" || !channel.handover?.backlog?.includes(id) || pending?.length !== 1 || !channel.session.startsWith("claude:")) throw new Error("Claude delivery observation unavailable"); + const root = process.env.CLAUDE_SESSION_ROOT || join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "projects"); + if (!isAbsolute(root)) throw new Error("invalid configured transcript root"); + const proof = await observeClaudeDelivery({ root, session: channel.session, generation: channel.generation, messageId: id, payload: pending[0].payload }); + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + const item = current?.queue?.find(row => row.id === id); + if (!item || typeof item.payload !== "string" || createHash("sha256").update(item.payload).digest("hex") !== proof.payloadSha256) throw new Error("delivery changed during observation"); + assertClaudeDeliverySnapshotCurrent(proof); + const next = observeDelivery(current, id, proof); + next.queue.find(row => row.id === id).deliveryProof = { evidence: proof.evidence, transcriptSha256: proof.transcriptSha256, transcriptBytes: proof.transcriptBytes }; + return { graph, event: event("channel.updated", { channel: next }), result: { channel: name, messageId: id, evidence: proof.evidence, status: "observed" } }; + }); + printResult(result, { json: true }); + break; + } + if (subcommand === "observe-notice") { + const content = JSON.parse(requiredSingleLine(channelInput, "--input")); + if (!content || typeof content !== "object" || Array.isArray(content) || Object.keys(content).sort().join(",") !== "label,prefix") throw new Error("invalid notice content"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name), pending = channel?.finalNotice; + const target = /^codex:([0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/i.exec(pending?.successor || ""); + const agent = pending?.session?.split(":")[0]; + if (!pending || !["requested", "queued-unverified"].includes(pending.status) || !target || !["codex", "claude"].includes(agent)) throw new Error("local notice reservation unavailable"); + const root = agent === "codex" ? process.env.CODEX_SESSION_ROOT || join(process.env.CODEX_HOME || join(homedir(), ".codex"), "sessions") : process.env.CLAUDE_SESSION_ROOT || join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"), "projects"); + if (!isAbsolute(root)) throw new Error("invalid configured transcript root"); + const proof = await observeLocalFinalNotice({ session: pending.session, nonce: pending.id, target: { kind: "codex", id: target[1] }, label: content.label, prefix: content.prefix, transcriptRoot: root }); + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + if (!current) throw new Error("unknown channel"); + const next = recordNoticeObservation(current, proof); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: next } }; + }); + printResult(result, { json: true }); + break; + } + if (subcommand === "settle-wake") { + const session = requiredSingleLine(values.session, "--session"); + const evidence = requiredSingleLine(channelInput, "--input"); + const proof = await verifyCodexWakeEvidence({ evidenceRoot: requiredSingleLine(values["state-root"], "--state-root"), reference: evidence, session }); + const sourceId = `codex-wake-${createHash("sha256").update(JSON.stringify([session, proof.queueId])).digest("hex")}`; + const receiptId = createHash("sha256").update(sourceId).digest("hex"); + const digest = createHash("sha256").update(JSON.stringify({ type: "session.woken", session, evidence, to: null })).digest("hex"); + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + if (!current || !(graph.lifecycleReceipts || []).some(item => item.id === receiptId && item.digest === digest)) throw new Error("recorded wake proof unavailable"); + if (!current.wakeReservation && current.queue.some(item => item.id === proof.correlation && item.session === session && item.nativeQueueId === proof.queueId && item.wakeEvidence === evidence)) return { graph, result: { channel: current, duplicate: true } }; + const next = settleWake(current, proof); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: next, duplicate: false } }; + }); + printResult(result, { json: true }); + break; + } + if (subcommand === "revalidate-state") { + const root = requiredSingleLine(values["state-root"], "--state-root"); + if (!isAbsolute(root)) throw new Error("absolute state root required"); + const channel = (loadGraph(stateDir).channels || []).find(item => item.id === name); + if (!channel || channel.phase !== "handover" || channel.wakeReservation || channel.queue?.some(item => item.state === "inflight")) throw new Error("state revalidation unavailable"); + const proof = await revalidateStateProof({ root, channel: name, session: channel.session, generation: channel.generation, statePreparation: channel.statePreparation }); + assertPrivateChannelState(stateDir); + const current = (loadGraph(stateDir).channels || []).find(item => item.id === name); + if (!current || current.phase !== "handover" || current.session !== channel.session || current.generation !== channel.generation || current.wakeReservation || current.queue?.some(item => item.state === "inflight") || JSON.stringify(current.statePreparation) !== JSON.stringify(channel.statePreparation)) throw new Error("channel changed during state revalidation"); + printResult({ schema: "agent-mesh.state-revalidation.v1", channel: name, session: channel.session, generation: channel.generation, filename: proof.filename, sha256: proof.sha256, bytes: proof.bytes, status: "verified-snapshot" }, { json: true }); + break; + } + if (subcommand === "prepare-state") { + const root = requiredSingleLine(values["state-root"], "--state-root"), filename = requiredSingleLine(values.filename, "--filename"); + if (!isAbsolute(root) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(filename)) throw new Error("invalid state preparation path"); + const info = lstatSync(root); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || realpathSync(root) !== root) throw new Error("state root must be private and canonical"); + const nonce = `handover-${randomUUID()}`; + const result = await prepareState({ reserve: () => mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + if (!graph.migrated || graph.unnumbered) throw new Error("channels require a migrated graph"); + const current = (graph.channels || []).find(item => item.id === name); + if (!current) throw new Error("unknown channel"); + if (!/^(codex|claude):[0-9a-f-]{36}$/.test(current.session) || (current.session.startsWith("claude:") && (!values["managed-inbox-root"] || !isAbsolute(values["managed-inbox-root"])))) throw new Error("unsupported state preparation recipient"); + const next = reserveStatePreparation(current, nonce); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: name, statePreparation: next.statePreparation } }; + }), request: pending => requestStateProof({ session: pending.session, channel: name, root, filename, managedInboxRoot: values["managed-inbox-root"], nonce: pending.id }), complete: proof => mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + const current = (graph.channels || []).find(item => item.id === name); + if (!current) throw new Error("unknown channel"); + const next = completeStatePreparation(current, proof); + return { graph, event: event("channel.updated", { channel: next }), result: { channel: name, statePreparation: next.statePreparation } }; + }) }); + printResult(result, { json: true }); + break; + } + const result = mutate(stateDir, graph => { + assertPrivateChannelState(stateDir); + if (!graph.migrated || graph.unnumbered) throw new Error("channels require a migrated graph"); + const current = (graph.channels || []).find((item) => item.id === name); + let next; + if (subcommand === "create") { + if (current) throw new Error("channel already exists"); + const session = requiredSingleLine(values.session, "--session"); + if (graph.nodes.filter(node => plexus.sessionIdOf(node) === session).length !== 1) throw new Error("unknown or ambiguous session"); + next = createChannel(name, session); + } else { + if (!current) throw new Error("unknown channel"); + if (subcommand === "enqueue") next = enqueue(current, requiredSingleLine(values.id, "--id"), channelInput); + else if (subcommand === "begin-delivery") { + if (values.generation !== undefined && !/^[1-9][0-9]*$/.test(values.generation)) throw new Error("invalid channel generation"); + const messageId = requiredSingleLine(values.id, "--id"); + next = beginDelivery(current, messageId, values.session === undefined ? undefined : requiredSingleLine(values.session, "--session"), values.generation === undefined ? undefined : Number(values.generation)); + next.queue.find(item => item.id === messageId).dispatchReservedAtMs = Date.now(); + } + else if (subcommand === "acknowledge") next = acknowledge(current, requiredSingleLine(values.id, "--id"), JSON.parse(requiredSingleLine(channelInput, "--input"))); + else if (subcommand === "reserve-wake") { + if (!/^[1-9][0-9]*$/.test(values.generation || "")) throw new Error("invalid channel generation"); + const session = requiredSingleLine(values.session, "--session"), queueId = requiredSingleLine(channelInput, "--input"); + const sourceId = `codex-wake-${createHash("sha256").update(JSON.stringify([session, queueId])).digest("hex")}`; + const receiptId = createHash("sha256").update(sourceId).digest("hex"); + if ((graph.lifecycleReceipts || []).some(item => item.id === receiptId) || (graph.channels || []).some(item => item.id !== name && item.wakeReservation?.session === session && item.wakeReservation?.nativeQueueId === queueId)) throw new Error("wake identity already reserved or recorded"); + next = reserveWake(current, requiredSingleLine(values.id, "--id"), session, Number(values.generation), queueId, values.source === undefined ? 'start' : requiredSingleLine(values.source, '--source')); + } + else if (subcommand === "begin-handover") next = { ...beginHandover(current), handoverStartedAt: new Date().toISOString() }; + else if (subcommand === "reserve-notice") { + const target = requiredSingleLine(values.to, "--to"); + const match = /^codex:([0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/i.exec(target); + if (!match) throw new Error("successor native verification unavailable"); + const content = JSON.parse(requiredSingleLine(channelInput, "--input")); + if (!content || typeof content !== "object" || Array.isArray(content) || Object.keys(content).sort().join(",") !== "label,prefix") throw new Error("invalid notice content"); + const notice = formatFinalNotice({ target: { kind: "codex", id: match[1] }, label: content.label, prefix: content.prefix }); + const matches = graph.nodes.filter(node => plexus.sessionIdOf(node) === target), node = matches[0], proof = node?.sessionLink; + const started = Date.parse(current.handoverStartedAt), checked = Date.parse(proof?.checkedAt); + if (matches.length !== 1 || node.status === "closed" || node.surface?.archived === true || proof?.status !== "ok" || proof.resolvedSession !== target || proof.source !== "codex-threads" || proof.link !== target || proof.lastKnown === true || !Number.isFinite(started) || !Number.isFinite(checked) || checked < started || checked > Date.now()) throw new Error("successor requires fresh verified link"); + const writer = probeWriter({ harness: "codex", nativeId: match[1] }); + if (writer?.agent !== "codex" || writer.sessionId !== match[1] || !Array.isArray(writer.writers) || writer.writers.length !== 1 || !Number.isSafeInteger(writer.writers[0]?.pid) || writer.writers[0].pid <= 0 || writer.writers[0].kind !== "codex") throw new Error("successor requires one verified writer"); + next = reserveFinalNotice(current, `handover-${randomUUID()}`, target, createHash("sha256").update(notice).digest("hex")); + } + else if (subcommand === "finish-handover") { + const target = requiredSingleLine(values.to, "--to"); + if (current.phase === "active" && current.session === target && current.handoverReceipt?.successor === target) return { graph, result: { channel: current, duplicate: true } }; + const matches = graph.nodes.filter(node => plexus.sessionIdOf(node) === target); + const node = matches[0], proof = node?.sessionLink; + const started = Date.parse(current.handoverStartedAt), checked = Date.parse(proof?.checkedAt); + if (matches.length !== 1 || node.status === "closed" || node.surface?.archived === true || proof?.status !== "ok" || proof.resolvedSession !== target || proof.lastKnown === true || !Number.isFinite(started) || !Number.isFinite(checked) || checked < started || checked > Date.now()) throw new Error("successor requires fresh verified link"); + // Current native link discovery can prove an unarchived Codex thread. + // Claude link observations explicitly leave remote reachability unverified. + if (!/^codex:[0-9a-f-]{36}$/.test(target) || proof.source !== "codex-threads" || proof.link !== target) throw new Error("successor native verification unavailable"); + const writer = probeWriter({ harness: "codex", nativeId: target.slice(6) }); + if (writer?.agent !== "codex" || writer.sessionId !== target.slice(6) || !Array.isArray(writer.writers) || writer.writers.length !== 1 || !Number.isSafeInteger(writer.writers[0]?.pid) || writer.writers[0].pid <= 0 || writer.writers[0].kind !== "codex") throw new Error("successor requires one verified writer"); + // A caller assertion or a file path is not proof that the old + // session wrote its state; no verified adapter exists yet. + throw new Error("old-session state verification unavailable; cutover disabled"); + } + else throw new Error("unknown channel operation"); + } + if (current && JSON.stringify(current) === JSON.stringify(next)) return { graph, result: { channel: next, duplicate: true } }; + return { graph, event: event("channel.updated", { channel: next }), result: { channel: next, duplicate: false } }; + }); + printResult(result, { json: true }); + break; + } + case "lifecycle": { + if (subcommand !== "record") throw new Error("unknown lifecycle operation"); + if (!plexus.LIFECYCLE_EVENTS.has(values.type)) throw new Error("invalid lifecycle type"); + const session = requiredSingleLine(values.session, "--session"); + const evidence = requiredSingleLine(values.evidence, "--evidence"); + if (!OPAQUE_REF.test(evidence)) throw new Error("--evidence must be an opaque evidence reference"); + const sourceId = requiredSingleLine(values.id, "--id"); + if (!/^[A-Za-z0-9._:-]{1,128}$/.test(sourceId)) throw new Error("invalid lifecycle observation id"); + const to = values.to; + if (values.type === "session.handover" ? typeof to !== "string" || to === session : to !== undefined) throw new Error("handover alone requires a distinct --to session"); + const digest = createHash("sha256").update(JSON.stringify({ type: values.type, session, evidence, to: to ?? null })).digest("hex"); + const receiptId = createHash("sha256").update(sourceId).digest("hex"); + const result = mutate(stateDir, graph => { + if (!graph.migrated || graph.unnumbered) throw new Error("lifecycle events require a migrated graph"); + if (graph.nodes.filter(node => plexus.sessionIdOf(node) === session).length !== 1 || (to && graph.nodes.filter(node => plexus.sessionIdOf(node) === to).length !== 1)) throw new Error("unknown or ambiguous session"); + const prior = (graph.lifecycleReceipts || []).find(item => item.id === receiptId); + if (prior) { + if (prior.digest !== digest) throw new Error("observation id reused with different contents"); + return { graph, result: { observation: sourceId, duplicate: true } }; + } + return { graph, event: event(values.type, { session, evidence, ...(to ? { to } : {}), receiptId, digest }), result: { observation: sourceId, duplicate: false } }; + }); + printResult(result, { json: true }); + break; + } + case "module": { + const configPath = values.config || join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "agent-mesh", "modules.json"); + const entries = await readModuleRegistry(configPath); + if (subcommand === "list") printResult({ modules: entries.map(entry => ({ name: entry.name })) }, { json: true }); + else if (subcommand === "describe") { + const entry = entries.find(item => item.name === values.name); + if (!entry) throw new Error("module is not registered"); + printResult(await describeModule(entry), { json: true }); + } else if (subcommand === "conformance") { + const entry = entries.find(item => item.name === values.name); + if (!entry) throw new Error("module is not registered"); + const desc = await describeModule(entry); + if (!desc.operations.includes("process")) throw new Error("module does not support process"); + const graph = { nodes: [{ id: "synthetic-node", agent: "codex", runtimeUuid: "22222222-2222-4222-8222-222222222222" }], moduleStates: [] }; + const result = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", mode: "conformance", graph, cursor: null, events: [] }); + if (Object.keys(result).some(key => !["schema", "name", "batchId", "attributes", "events"].includes(key))) throw new Error("invalid module process response"); + validateModuleBatch(entry.name, entry.namespaces, { id: result.batchId, cursor: null, nextCursor: "synthetic-cursor", attributes: result.attributes, events: result.events }, graph, plexus.sessionIdOf); + printResult({ module: entry.name, conformance: "pass", scope: "synthetic protocol response only" }, { json: true }); + } else if (subcommand === "run") { + const entry = entries.find(item => item.name === values.name); + if (!entry) throw new Error("module is not registered"); + const description = await describeModule(entry); + if (!description.operations.includes("process")) throw new Error("module does not support process"); + // Feed replay can be large. Never hold the shared writer lock while + // scanning it; reject if the graph moved during observation instead. + const graph = loadGraph(stateDir); + if (!graph.migrated || graph.unnumbered) throw new Error("module runs require a migrated graph"); + const cursor = graph.moduleStates?.find(item => item.name === entry.name)?.cursor ?? null; + const query = cursor === null ? { initial: "head" } : { sinceCursor: cursor }; + const feed = runQuery(stateDir, "changes", { input: JSON.stringify(query) }); + if (feed.reset) throw new Error("module cursor expired; reconciliation required"); + const observed = loadGraph(stateDir); + if (observed.lastSeq !== graph.lastSeq || plexus.decodeCursor(feed.cursor, "changes").seq > graph.lastSeq) throw new Error("graph changed during module observation"); + const snapshot = { graph, cursor, feed }; + const events = snapshot.feed.events.filter(item => !entry.namespaces.some(namespace => item.type.startsWith(`${namespace}.`))); + const output = await invokeModule(entry, "process", { schema: "agent-mesh.plexus-module.v1", graph: snapshot.graph, cursor: snapshot.cursor, events }); + if (Object.keys(output).some(key => !["schema", "name", "batchId", "attributes", "events"].includes(key))) throw new Error("invalid module process response"); + if (snapshot.cursor !== null && events.length === 0 && Array.isArray(output.attributes) && output.attributes.length === 0 && Array.isArray(output.events) && output.events.length === 0) { + printResult({ module: entry.name, unchanged: true }, { json: true }); + break; + } + const batch = { id: output.batchId, cursor: snapshot.cursor, nextCursor: snapshot.feed.cursor, attributes: output.attributes, events: output.events }; + const result = mutate(stateDir, graph => { + if (graph.lastSeq !== snapshot.graph.lastSeq) throw new Error("graph changed during module processing"); + const checked = validateModuleBatch(entry.name, entry.namespaces, batch, graph, plexus.sessionIdOf); + if (checked.duplicate) return { graph, result: { module: entry.name, batchId: batch.id, duplicate: true } }; + return { graph, event: event("module.batch", { module: entry.name, batch, digest: checked.digest }), result: { module: entry.name, batchId: batch.id, duplicate: false } }; + }); + printResult(result, { json: true }); + } else if (subcommand === "apply") { + const entry = entries.find(item => item.name === values.name); + if (!entry) throw new Error("module is not registered"); + const raw = values.input === "-" ? readFileSync(0, "utf8") : values.input; + if (typeof raw !== "string" || Buffer.byteLength(raw) > 1024 * 1024) throw new Error("invalid module input"); + const batch = JSON.parse(raw); + const result = mutate(stateDir, graph => { + if (!graph.migrated || graph.unnumbered) throw new Error("module batches require a migrated graph"); + const checked = validateModuleBatch(entry.name, entry.namespaces, batch, graph, plexus.sessionIdOf); + if (checked.duplicate) return { graph, result: { module: values.name, batchId: batch.id, duplicate: true } }; + return { graph, event: event("module.batch", { module: values.name, batch, digest: checked.digest }), result: { module: values.name, batchId: batch.id, duplicate: false } }; + }); + printResult(result, { json: true }); + } else throw new Error("unknown module operation"); + break; + } case "links": { if (subcommand !== "verify") throw new Error("unknown links operation"); const verify = graph => { @@ -1108,7 +1422,7 @@ function readCheckpoint(statePath) { if (checkpoint.schema !== GRAPH_SCHEMA || checkpoint.graph?.schema !== GRAPH_SCHEMA || !Array.isArray(checkpoint.graph.nodes) || !Array.isArray(checkpoint.graph.edges) || // Older binaries rewrite the checkpoint without Plexus state; replaying from the file is the only safe answer. - !Array.isArray(checkpoint.graph.roleClaims) || !Array.isArray(checkpoint.graph.links) || !Number.isSafeInteger(checkpoint.graph.lastSeq) || + !Array.isArray(checkpoint.graph.roleClaims) || !Array.isArray(checkpoint.graph.links) || !Array.isArray(checkpoint.graph.moduleStates) || !Array.isArray(checkpoint.graph.lifecycleReceipts) || !Array.isArray(checkpoint.graph.channels) || !Number.isSafeInteger(checkpoint.graph.lastSeq) || !cursor || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0 || !Number.isSafeInteger(cursor.dev) || !Number.isSafeInteger(cursor.ino)) { return null; @@ -1197,7 +1511,7 @@ function* readEventRecords(statePath, offset = 0) { function deriveGraph(events, base = null) { const nodes = new Map((base?.nodes || []).map((node) => [node.id, node])); const edges = new Map((base?.edges || []).map((edge) => [edge.id, edge])); - const state = { nodes, roleClaims: new Map((base?.roleClaims || []).map(c => [c.id, c])), links: new Map((base?.links || []).map((link) => [link.id, link])), edges, renewals: [...(base?.renewals || [])], migrated: base?.migrated === true }; + const state = { nodes, channels: new Map((base?.channels || []).map(item => [item.id, item])), moduleStates: new Map((base?.moduleStates || []).map(item => [item.name, item])), lifecycleReceipts: new Map((base?.lifecycleReceipts || []).map(item => [item.id, item])), roleClaims: new Map((base?.roleClaims || []).map(c => [c.id, c])), links: new Map((base?.links || []).map((link) => [link.id, link])), edges, renewals: [...(base?.renewals || [])], migrated: base?.migrated === true }; const baseSeq = base?.lastSeq || 0; let lastSeq = baseSeq; let unnumbered = base?.unnumbered === true; @@ -1209,8 +1523,13 @@ function deriveGraph(events, base = null) { lastSeq = Math.max(lastSeq, item.seq); } else if (state.migrated) unnumbered = true; generatedAt = item.at || generatedAt; + if (item.type === "module.batch") { + applyModuleBatch(state, item, plexus.sessionIdOf); + continue; + } if (plexus.PLEXUS_EVENTS.has(item.type)) { plexus.applyPlexusEvent(state, item); + if (plexus.LIFECYCLE_EVENTS.has(item.type) && item.receiptId) state.lifecycleReceipts.set(item.receiptId, { id: item.receiptId, digest: item.digest }); continue; } if (item.type === "node.upserted") { @@ -1239,7 +1558,10 @@ function deriveGraph(events, base = null) { nodes: state.migrated ? plexus.projectNodeRefs(sortedNodes, links) : sortedNodes, edges: [...edges.values()].sort((left, right) => left.id.localeCompare(right.id)), links, + channels: [...state.channels.values()], renewals: state.renewals, + moduleStates: [...state.moduleStates.values()], + lifecycleReceipts: [...state.lifecycleReceipts.values()], roleClaims: [...state.roleClaims.values()], migrated: state.migrated, lastSeq, @@ -1332,6 +1654,30 @@ function ensureStateDir(statePath) { mkdirSync(statePath, { recursive: true, mode: 0o700 }); } +function readBoundedChannelInput() { + const max = 65536, chunks = []; + let total = 0; + while (true) { + const chunk = Buffer.allocUnsafe(Math.min(4096, max + 1 - total)); + const count = readSync(0, chunk, 0, chunk.length, null); + if (!count) break; + total += count; + if (total > max) throw new Error("channel input too large"); + chunks.push(chunk.subarray(0, count)); + } + return Buffer.concat(chunks).toString("utf8"); +} + +function assertPrivateChannelState(statePath) { + const root = lstatSync(statePath); + if (!root.isDirectory() || root.isSymbolicLink() || root.uid !== process.getuid() || (root.mode & 0o077) !== 0 || realpathSync(statePath) !== resolve(statePath)) throw new Error("channel graph directory must be private and canonical"); + for (const name of ["events.jsonl", "graph.json", "checkpoint.json", "snapshot.json"]) { + const file = join(statePath, name); + const info = lstatSync(file, { throwIfNoEntry: false }); + if (info && (!info.isFile() || info.isSymbolicLink() || info.uid !== process.getuid() || info.nlink !== 1 || (info.mode & 0o077) !== 0)) throw new Error(`channel graph file must be private: ${name}`); + } +} + function acquireLock(statePath) { const lock = join(statePath, "graph.lock"); const deadline = Date.now() + 5_000; diff --git a/skills/agent-tmux/bin/module-batches.mjs b/skills/agent-tmux/bin/module-batches.mjs new file mode 100644 index 00000000..6c0e0c50 --- /dev/null +++ b/skills/agent-tmux/bin/module-batches.mjs @@ -0,0 +1,47 @@ +import { createHash } from "node:crypto"; + +const NAME = /^[a-z][a-z0-9-]{0,63}$/; +const KEY = /^[a-z][a-z0-9_-]{0,63}$/; + +// A batch is one event, so graph changes and its checkpoint commit together. +export function validateModuleBatch(name, namespaces, batch, graph, sessionIdOf) { + if (typeof name !== "string" || !NAME.test(name)) throw new Error("invalid module name"); + if (!batch || typeof batch !== "object" || Array.isArray(batch) || Object.keys(batch).some(k => !["id", "cursor", "nextCursor", "attributes", "events"].includes(k))) throw new Error("invalid module batch"); + if (typeof batch.id !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(batch.id)) throw new Error("invalid batch id"); + for (const c of [batch.cursor, batch.nextCursor]) if (!(c === null || (typeof c === "string" && c.length <= 4096))) throw new Error("invalid module cursor"); + if (batch.nextCursor === null) throw new Error("next cursor is required"); + if (!Array.isArray(batch.attributes) || batch.attributes.length > 200 || !Array.isArray(batch.events) || batch.events.length > 200) throw new Error("invalid batch contents"); + if (Buffer.byteLength(JSON.stringify(batch)) > 1024 * 1024) throw new Error("module batch too large"); + const seen = new Set(); + for (const attr of batch.attributes) { + if (!attr || Object.keys(attr).some(k => !["session", "key", "value"].includes(k)) || typeof attr.session !== "string" || typeof attr.key !== "string" || attr.key.split(".").length !== 2 || !namespaces.includes(attr.key.split(".")[0]) || !KEY.test(attr.key.split(".")[1]) || !Object.hasOwn(attr, "value")) throw new Error("invalid namespaced module attribute"); + if (graph.nodes.filter(node => sessionIdOf(node) === attr.session).length !== 1) throw new Error("unknown or ambiguous session"); + const identity = `${attr.session}\0${attr.key}`; + if (seen.has(identity)) throw new Error("duplicate module attribute"); + seen.add(identity); + } + for (const ev of batch.events) { + if (!ev || Object.keys(ev).some(k => !["type", "session", "data"].includes(k)) || typeof ev.type !== "string" || ev.type.split(".").length !== 2 || !namespaces.includes(ev.type.split(".")[0]) || !KEY.test(ev.type.split(".")[1]) || typeof ev.session !== "string" || graph.nodes.filter(node => sessionIdOf(node) === ev.session).length !== 1 || !Object.hasOwn(ev, "data")) throw new Error("invalid namespaced event"); + } + const digest = createHash("sha256").update(JSON.stringify(batch)).digest("hex"); + const previous = (graph.moduleStates || []).find(item => item.name === name); + if (previous?.batchId === batch.id) { + if (previous.digest !== digest) throw new Error("batch id reused with different contents"); + return { duplicate: true, digest }; + } + if ((previous?.cursor ?? null) !== batch.cursor) throw new Error("module cursor conflict"); + return { duplicate: false, digest }; +} + +export function applyModuleBatch(state, event, sessionIdOf) { + if (!state.moduleStates) state.moduleStates = new Map(); + for (const attr of event.batch.attributes) { + const node = [...state.nodes.values()].find(item => sessionIdOf(item) === attr.session); + if (!node) throw new Error("module batch names unknown session"); + const modules = { ...(node.moduleAttributes || {}) }; + const [namespace, key] = attr.key.split("."); + modules[namespace] = { ...(Object.hasOwn(modules, namespace) ? modules[namespace] : {}), [key]: attr.value }; + state.nodes.set(node.id, { ...node, moduleAttributes: modules }); + } + state.moduleStates.set(event.module, { name: event.module, cursor: event.batch.nextCursor, batchId: event.batch.id, digest: event.digest }); +} diff --git a/skills/agent-tmux/bin/namespace-exec-gate.py b/skills/agent-tmux/bin/namespace-exec-gate.py new file mode 100644 index 00000000..5fea1f1c --- /dev/null +++ b/skills/agent-tmux/bin/namespace-exec-gate.py @@ -0,0 +1,43 @@ +#!/usr/bin/env python3 +"""Execute a trusted command only after an explicit private FIFO release. + +This gate is a fail-closed coordination primitive, not an authorization boundary. +The caller owns the namespace, FIFO, command, environment and lifecycle. +""" +import os +from pathlib import Path +import stat +import sys + + +def main(argv): + if len(argv) < 3 or argv[1] != '--' or not os.path.isabs(argv[0]) or not os.path.isabs(argv[2]): + return 125 + fifo = Path(argv[0]) + try: + parent = fifo.parent + directory = parent.lstat() + entry = fifo.lstat() + if (not stat.S_ISDIR(directory.st_mode) or directory.st_uid != os.getuid() or directory.st_mode & 0o077 or + parent.resolve(strict=True) != parent or not stat.S_ISFIFO(entry.st_mode) or + entry.st_uid != os.getuid() or entry.st_mode & 0o077 or entry.st_nlink != 1): + return 125 + fd = os.open(fifo, os.O_RDONLY | os.O_NOFOLLOW) + try: + opened = os.fstat(fd) + if (not stat.S_ISFIFO(opened.st_mode) or opened.st_uid != os.getuid() or opened.st_mode & 0o077 or opened.st_nlink != 1 or + opened.st_dev != entry.st_dev or opened.st_ino != entry.st_ino): + return 125 + permit = os.read(fd, 4) + finally: + os.close(fd) + if permit != b'GO\n': + return 125 + os.execv(argv[2], argv[2:]) + except OSError: + return 125 + return 125 + + +if __name__ == '__main__': + raise SystemExit(main(sys.argv[1:])) diff --git a/skills/agent-tmux/bin/plexus-modules.mjs b/skills/agent-tmux/bin/plexus-modules.mjs new file mode 100644 index 00000000..389d5be1 --- /dev/null +++ b/skills/agent-tmux/bin/plexus-modules.mjs @@ -0,0 +1,65 @@ +import { readFile } from "node:fs/promises"; +import { spawn } from "node:child_process"; + +export const MODULE_PROTOCOL = "agent-mesh.plexus-module.v1"; +const NAME = /^[a-z][a-z0-9-]{0,63}$/; +const MAX_BYTES = 1024 * 1024; +// Graph snapshots can be substantially larger than module responses. This is a +// hard bound, not permission to truncate a graph silently. +const MAX_REQUEST_BYTES = 32 * 1024 * 1024; + +// This is an operator allowlist, not a sandbox for untrusted programs. +export async function readModuleRegistry(path) { + let text; + try { text = await readFile(path, "utf8"); } + catch (error) { if (error.code === "ENOENT") return []; throw error; } + if (Buffer.byteLength(text) > MAX_BYTES) throw new Error("module registry is too large"); + const config = JSON.parse(text); + if (!config || config.schemaVersion !== 1 || !Array.isArray(config.modules)) throw new Error("invalid module registry"); + const names = new Set(), namespaces = new Set(); + return config.modules.map((entry) => { + if (!entry || typeof entry.name !== "string" || !NAME.test(entry.name) || names.has(entry.name)) throw new Error("invalid or duplicate module name"); + const owned = entry.namespaces ?? [entry.name]; + if (!Array.isArray(owned) || !owned.length || owned.length > 32 || owned.some(ns => typeof ns !== "string" || !NAME.test(ns) || namespaces.has(ns)) || new Set(owned).size !== owned.length) throw new Error("invalid or duplicate module namespace"); + if (!Array.isArray(entry.command) || !entry.command.length || entry.command.some(v => typeof v !== "string" || !v || v.includes("\0"))) throw new Error("invalid module command"); + const timeoutMs = entry.timeoutMs ?? 10000; + if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120000) throw new Error("invalid module timeout"); + names.add(entry.name); + for (const namespace of owned) namespaces.add(namespace); + return { name: entry.name, namespaces: [...owned], command: [...entry.command], timeoutMs }; + }); +} + +export async function invokeModule(entry, operation, request) { + if (!["describe", "process"].includes(operation)) throw new Error("invalid module operation"); + const input = JSON.stringify(request); + if (Buffer.byteLength(input) > MAX_REQUEST_BYTES) throw new Error("module request too large"); + const result = await new Promise((resolve, reject) => { + const child = spawn(entry.command[0], [...entry.command.slice(1), operation], { stdio: ["pipe", "pipe", "ignore"], shell: false }); + let output = [], bytes = 0, finished = false; + const finish = (error, value) => { if (finished) return; finished = true; clearTimeout(timer); error ? reject(error) : resolve(value); }; + const timer = setTimeout(() => { child.kill("SIGKILL"); finish(new Error("module timed out")); }, entry.timeoutMs); + child.on("error", () => finish(new Error("module failed"))); + child.stdout.on("data", chunk => { + bytes += chunk.length; + if (bytes > MAX_BYTES) { child.kill("SIGKILL"); finish(new Error("module response too large")); } + else output.push(chunk); + }); + child.stdin.on("error", () => {}); + child.on("close", code => { + if (code !== 0) return finish(new Error("module failed")); + try { finish(null, JSON.parse(Buffer.concat(output).toString("utf8"))); } + catch { finish(new Error("invalid module response")); } + }); + child.stdin.end(`${input}\n`); + }); + if (!result || result.schema !== MODULE_PROTOCOL || result.name !== entry.name) throw new Error("invalid module response"); + return result; +} + +export async function describeModule(entry) { + const result = await invokeModule(entry, "describe", {}); + const owned = entry.namespaces ?? [entry.name]; + if (!result || result.schema !== MODULE_PROTOCOL || result.name !== entry.name || !Array.isArray(result.namespaces) || result.namespaces.length !== owned.length || owned.some(ns => !result.namespaces.includes(ns)) || new Set(result.namespaces).size !== owned.length || !Array.isArray(result.operations) || !result.operations.includes("describe") || result.operations.some(op => typeof op !== "string")) throw new Error("invalid module description"); + return result; +} diff --git a/skills/agent-tmux/bin/plexus.mjs b/skills/agent-tmux/bin/plexus.mjs index 4706a3df..1ccf49b6 100644 --- a/skills/agent-tmux/bin/plexus.mjs +++ b/skills/agent-tmux/bin/plexus.mjs @@ -7,6 +7,7 @@ import { createHmac, randomUUID } from "node:crypto"; import { posix } from "node:path"; import { createHash } from "node:crypto"; +import { applyModuleBatch } from "./module-batches.mjs"; import { LEDGER_VIEW_SCHEMA, LEDGER_VIEW_SORT, buildLedgerViewRows, ledgerViewProfileRevision, ledgerViewValue, validateLedgerViewProfile @@ -18,7 +19,8 @@ export const LINK_SOURCES = /^(bridge-launch|hook|ledger-write|reconciler|operat export const ROLE_WEIGHTS = { owns: 1, "works-on": 1, coordinates: 0.8, reviews: 0.7, discusses: 0.6, observes: 0.3, mentioned: 0.2 }; export const HALF_LIFE_DAYS = 7; export const TOUCH_COALESCE_MS = 10 * 60 * 1000; -export const PLEXUS_EVENTS = new Set(["role.changed", "link.opened", "link.touched", "link.closed", "link.resolved", "edge.ended", "session.renewed", "store.migrated"]); +export const LIFECYCLE_EVENTS = new Set(["session.started", "session.woken", "session.idle", "session.compacted", "session.stopped", "session.handover"]); +export const PLEXUS_EVENTS = new Set(["channel.updated", "role.changed", "link.opened", "link.touched", "link.closed", "link.resolved", "edge.ended", "session.renewed", "store.migrated", ...LIFECYCLE_EVENTS]); const HARNESSES = new Set(["codex", "claude"]); const UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i; const SESSION_ID = /^(codex|claude):[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/; @@ -84,6 +86,30 @@ export function applyPlexusEvent(state, item) { const effects = []; const openLinks = () => [...state.links.values()].filter((link) => link.until === null); switch (item.type) { + case "channel.updated": + if (!item.channel || item.channel.schema !== "agent-mesh.channel.v1" || typeof item.channel.id !== "string" || !Array.isArray(item.channel.queue)) throw new Error("invalid channel event"); + if (!state.channels) state.channels = new Map(); + state.channels.set(item.channel.id, item.channel); + break; + case "session.started": + case "session.woken": + case "session.idle": + case "session.compacted": + case "session.stopped": + case "session.handover": + parseGraphSessionId(item.session); + if (typeof item.evidence !== "string" || !item.evidence || item.evidence.length > 512 || /[\r\n\x00]/.test(item.evidence)) throw new Error("lifecycle event requires an evidence reference"); + if (item.type === "session.handover") { + parseGraphSessionId(item.to); + if (item.to === item.session) throw new Error("handover target must differ"); + if (item.channel !== undefined) { + if (!item.channel || item.channel.schema !== "agent-mesh.channel.v1" || item.channel.session !== item.to) throw new Error("invalid handover channel"); + if (!state.channels) state.channels = new Map(); + state.channels.set(item.channel.id, item.channel); + } + } else if (item.to !== undefined) throw new Error("unexpected lifecycle target"); + effects.push({ kind: item.type, session: item.session, evidence: item.evidence, ...(item.to ? { to: item.to } : {}) }); + break; case "role.changed": if (!state.roleClaims) state.roleClaims = new Map(); if (item.previous) state.roleClaims.set(item.previous.id, item.previous); @@ -777,6 +803,7 @@ export function changes(snapshotGraph, events, input = {}, scope = null) { nodes: new Map((snapshotGraph?.nodes || []).map((node) => [node.id, node])), links: new Map((snapshotGraph?.links || []).map((link) => [link.id, link])), edges: new Map((snapshotGraph?.edges || []).map((edge) => [edge.id, edge])), + moduleStates: new Map((snapshotGraph?.moduleStates || []).map(item => [item.name, item])), renewals: [...(snapshotGraph?.renewals || [])], migrated: snapshotGraph?.migrated === true, }; const seen = new Set([...state.nodes.values()].map(sessionIdOf).filter(Boolean)); @@ -790,7 +817,7 @@ export function changes(snapshotGraph, events, input = {}, scope = null) { continue; } if (output.length >= limit) break; - const emitted = feedFor(state, seen, item); + const emitted = feedFor(state, seen, item, scope); applyReplay(state, item, emitted); scanned = item.seq; if (!emitted.length) continue; @@ -808,6 +835,10 @@ export function changes(snapshotGraph, events, input = {}, scope = null) { } function applyReplay(state, item, emitted) { + if (item.type === "module.batch") { + if (!emitted) applyModuleBatch(state, item, sessionIdOf); + return; + } if (item.type === "node.upserted") { state.nodes.set(item.node.id, item.node); return; @@ -824,8 +855,12 @@ function applyReplay(state, item, emitted) { if (PLEXUS_EVENTS.has(item.type) && !emitted) applyPlexusEvent(state, item); } -function feedFor(state, seen, item) { +function feedFor(state, seen, item, scope) { const out = []; + if (item.type === "module.batch") { + applyModuleBatch(state, item, sessionIdOf); + return item.batch.events.map((entry, index) => ({ type: entry.type, session: entry.session, data: entry.data, subject: `${item.id}:${index}` })); + } if (item.type === "node.upserted") { const id = sessionIdOf(item.node); const previous = state.nodes.get(item.node.id); @@ -886,6 +921,8 @@ function feedFor(state, seen, item) { if (from && to) out.push({ type: effect.kind, edgeId: effect.edge.id, kind: effect.edge.type, from, to, subject: effect.edge.id }); } else if (effect.kind === "session.renewed") { out.push({ type: "session.renewed", from: effect.from, to: effect.to, subject: effect.to }); + } else if (LIFECYCLE_EVENTS.has(effect.kind)) { + out.push({ type: effect.kind, session: effect.session, ...(scope === null ? { evidence: effect.evidence } : {}), ...(effect.to ? { to: effect.to } : {}), subject: effect.session }); } } return out; diff --git a/skills/agent-tmux/bin/restart-state.mjs b/skills/agent-tmux/bin/restart-state.mjs new file mode 100644 index 00000000..8cbb5800 --- /dev/null +++ b/skills/agent-tmux/bin/restart-state.mjs @@ -0,0 +1,34 @@ +/** Validate a parsed restart block; never execute its instructions. */ +const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype; +const nonempty = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 8192 && !value.includes('\0'); +const profileId = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); + +export function validateRoleProfile(profile) { + if (!isObject(profile) || Object.keys(profile).sort().join(',') !== 'mcp,permissions,plugins,role,schema' || profile.schema !== 'agent-mesh.role-profile.v1' || !profileId(profile.role)) throw new Error('invalid role profile'); + for (const key of ['permissions', 'mcp', 'plugins']) { + const values = profile[key]; + if (!Array.isArray(values) || values.length > 256 || !values.every(profileId) || new Set(values).size !== values.length) throw new Error(`invalid role profile ${key}`); + } + return true; +} + +export function validateRestartState(block, { session, channel, requireRoleProfile = false } = {}) { + if (!isObject(block) || block.schema !== 'agent-mesh.restart.v1') throw new Error('invalid restart schema'); + for (const field of ['session', 'channel', 'harness', 'working_directory']) { + if (!nonempty(block[field])) throw new Error(`invalid restart ${field}`); + } + if (session !== undefined && block.session !== session) throw new Error('restart session mismatch'); + if (channel !== undefined && block.channel !== channel) throw new Error('restart channel mismatch'); + if (requireRoleProfile || block.role_profile !== undefined) validateRoleProfile(block.role_profile); + if (!Array.isArray(block.skills) || block.skills.length > 256 || !block.skills.every(nonempty)) throw new Error('invalid restart skills'); + if (!Array.isArray(block.triggers) || block.triggers.length > 256) throw new Error('invalid restart triggers'); + const ids = new Set(); + for (const trigger of block.triggers) { + if (!isObject(trigger) || !nonempty(trigger.id) || !nonempty(trigger.kind) || !isObject(trigger.config)) throw new Error('invalid restart trigger'); + const key = JSON.stringify([trigger.kind, trigger.id]); + if (ids.has(key)) throw new Error('duplicate restart trigger'); + ids.add(key); + } + if (block.goal !== null && (!isObject(block.goal) || !nonempty(block.goal.objective) || !nonempty(block.goal.status))) throw new Error('invalid restart goal'); + return true; +} diff --git a/skills/agent-tmux/bin/restart-yaml.py b/skills/agent-tmux/bin/restart-yaml.py new file mode 100644 index 00000000..46144e51 --- /dev/null +++ b/skills/agent-tmux/bin/restart-yaml.py @@ -0,0 +1,67 @@ +#!/usr/bin/env python3 +"""Decode a bounded restart block; do not emit state contents on errors.""" +import json +import math +import re +import sys + +try: + import yaml +except ImportError: + print('restart YAML parser unavailable: PyYAML is required', file=sys.stderr) + sys.exit(2) + + +class UniqueLoader(yaml.SafeLoader): + def construct_mapping(self, node, deep=False): + result = {} + for key_node, value_node in node.value: + key = self.construct_object(key_node, deep=deep) + if not isinstance(key, str) or key in result: + raise ValueError('non-string or duplicate key') + result[key] = self.construct_object(value_node, deep=deep) + return result + + +def json_value(value, depth=0, count=None): + count = count if count is not None else [0] + count[0] += 1 + if depth > 32 or count[0] > 20000: + raise ValueError('restart structure too large') + if value is None or isinstance(value, (bool, str, int)): + return value + if isinstance(value, float) and math.isfinite(value): + return value + if isinstance(value, list): + return [json_value(item, depth + 1, count) for item in value] + if isinstance(value, dict): + return {key: json_value(item, depth + 1, count) for key, item in value.items()} + raise ValueError('restart value is not JSON-compatible') + + +def decode(data): + text = data.decode('utf-8').replace('\r\n', '\n') + headings = list(re.finditer(r'^## RIAVVIO[ \t]*$', text, re.MULTILINE)) + if headings: + if len(headings) != 1: + raise ValueError('ambiguous restart section') + rest = text[headings[0].end():] + match = re.match(r'\n[ \t\n]*```ya?ml[ \t]*\n(.*?)^```[ \t]*$', rest, re.MULTILINE | re.DOTALL | re.IGNORECASE) + if not match: + raise ValueError('missing restart YAML block') + text = match.group(1) + for token in yaml.scan(text, Loader=UniqueLoader): + if isinstance(token, (yaml.tokens.AliasToken, yaml.tokens.AnchorToken, yaml.tokens.TagToken)): + raise ValueError('aliases, anchors and explicit tags are not allowed') + return json_value(yaml.load(text, Loader=UniqueLoader)) + + +try: + raw = sys.stdin.buffer.read(1024 * 1024 + 1) + if not raw or len(raw) > 1024 * 1024: + raise ValueError('invalid state size') + result = decode(raw) + print(json.dumps(result, ensure_ascii=True, allow_nan=False, separators=(',', ':'))) +except (ValueError, TypeError, UnicodeError, yaml.YAMLError, RecursionError): + print('invalid restart YAML', file=sys.stderr) + sys.exit(1) diff --git a/skills/agent-tmux/bin/role-launch-profile.mjs b/skills/agent-tmux/bin/role-launch-profile.mjs new file mode 100644 index 00000000..33abcad6 --- /dev/null +++ b/skills/agent-tmux/bin/role-launch-profile.mjs @@ -0,0 +1,36 @@ +/** Build a role-scoped launch plan without granting capabilities or starting services. */ +import { validateRoleProfile } from './restart-state.mjs'; + +const id = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); +const list = value => Array.isArray(value) && value.length <= 256 && value.every(id) && new Set(value).size === value.length; + +export async function planRoleLaunch({ profile, authority, probe, timeoutMs = 3000 }) { + validateRoleProfile(profile); + if (!authority || authority.role !== profile.role || !list(authority.permissions) || !list(authority.mcp) || !list(authority.plugins) || !list(authority.humanGatedPermissions) || typeof probe !== 'function' || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw new Error('invalid role authority'); + for (const field of ['permissions', 'mcp', 'plugins']) if (profile[field].some(value => !authority[field].includes(value))) throw new Error('role profile exceeds authority'); + if (profile.permissions.some(value => authority.humanGatedPermissions.includes(value))) throw new Error('human-gated permission cannot be pregranted'); + const available = [], unavailable = []; + for (const name of profile.mcp) { + let timer, cleanupTimer; const controller = new AbortController(), timedOut = Symbol('timeout'), cleanupTimedOut = Symbol('cleanup-timeout'); + const pending = Promise.resolve().then(() => probe(name, { signal: controller.signal })); + try { + const result = await Promise.race([pending, new Promise(resolve => { timer = setTimeout(() => { controller.abort(); resolve(timedOut); }, timeoutMs); })]); + if (result === timedOut) { + const cleanup = await Promise.race([pending.then(() => true, () => true), new Promise(resolve => { cleanupTimer = setTimeout(() => resolve(cleanupTimedOut), 1500); })]); + if (cleanup === cleanupTimedOut) throw new Error('probe cancellation unconfirmed'); + unavailable.push(name); continue; + } + (result === true ? available : unavailable).push(name); + } catch (error) { if (error?.message === 'probe cancellation unconfirmed' || error?.code === 'MCP_PROBE_CONFIGURATION') throw error; unavailable.push(name); } + finally { clearTimeout(timer); clearTimeout(cleanupTimer); controller.abort(); } + } + return { schema: 'agent-mesh.role-launch-plan.v1', role: profile.role, permissions: [...profile.permissions], plugins: [...profile.plugins], mcpToStart: available, mcpUnavailable: unavailable }; +} + +/** Assess observed startup; the caller owns rollback and native observation. */ +export function assessRoleLaunch({ plan, observed }) { + if (!plan || plan.schema !== 'agent-mesh.role-launch-plan.v1' || !list(plan.permissions) || !list(plan.plugins) || !list(plan.mcpToStart) || !list(plan.mcpUnavailable) || !observed || !list(observed.mcpStarted) || !list(observed.pluginsStarted) || typeof observed.permissionPrompt !== 'boolean' || !(observed.startupTokens === null || (Number.isSafeInteger(observed.startupTokens) && observed.startupTokens >= 0))) throw new Error('invalid launch observation'); + const unexpected = observed.mcpStarted.some(value => !plan.mcpToStart.includes(value)) || observed.pluginsStarted.some(value => !plan.plugins.includes(value)); + const failed = observed.permissionPrompt || unexpected; + return { schema: 'agent-mesh.role-launch-receipt.v1', status: failed ? 'rollback-required' : 'ready', reason: observed.permissionPrompt ? 'unexpected-permission' : unexpected ? 'unexpected-component' : null, mcpStarted: observed.mcpStarted.length, mcpUnavailable: [...new Set([...plan.mcpUnavailable, ...plan.mcpToStart.filter(value => !observed.mcpStarted.includes(value))])], startupTokens: observed.startupTokens }; +} diff --git a/skills/agent-tmux/bin/role-mcp-exec-gate.py b/skills/agent-tmux/bin/role-mcp-exec-gate.py new file mode 100644 index 00000000..b3eddf44 --- /dev/null +++ b/skills/agent-tmux/bin/role-mcp-exec-gate.py @@ -0,0 +1,27 @@ +#!/usr/bin/env python3 +"""Fail-closed stdin gate for an owned experimental MCP probe process.""" +import os +import sys + + +def main(argv): + if len(argv) < 2 or argv[0] != '--' or not os.path.isabs(argv[1]): + return 125 + permit = b'' + try: + while len(permit) < 3: + part = os.read(0, 3 - len(permit)) + if not part: + return 125 + permit += part + if permit != b'GO\n': + return 125 + os.write(1, b'{"agentMeshMcpGate":"released"}\n') + os.execv(argv[1], argv[1:]) + except OSError: + return 125 + return 125 + + +if __name__ == '__main__': + raise SystemExit(main(sys.argv[1:])) diff --git a/skills/agent-tmux/bin/role-mcp-probe.mjs b/skills/agent-tmux/bin/role-mcp-probe.mjs new file mode 100644 index 00000000..f2d56b3a --- /dev/null +++ b/skills/agent-tmux/bin/role-mcp-probe.mjs @@ -0,0 +1,96 @@ +/** Probe one authorized stdio MCP in a verified PID namespace. */ +import { spawn } from 'node:child_process'; +import { readFileSync, statSync } from 'node:fs'; +import { isAbsolute } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const gateProgram = fileURLToPath(new URL('./role-mcp-exec-gate.py', import.meta.url)); +const configurationError = message => Object.assign(new Error(message), { code: 'MCP_PROBE_CONFIGURATION' }); + +// The launcher is not an authorization boundary: the command is still trusted +// and retains the caller's filesystem and network access. Verify that bubblewrap +// created a separate PID namespace with an owned init before accepting a probe. +function verifyNamespace(raw, child) { + const info = JSON.parse(raw), pid = info?.['child-pid'], inode = info?.['pid-namespace']; + if (!Number.isSafeInteger(pid) || pid < 2 || !Number.isSafeInteger(inode) || !child.pid) throw new Error('invalid namespace identity'); + const path = `/proc/${pid}`, proc = statSync(path), ns = statSync(`${path}/ns/pid`); + const stat = readFileSync(`${path}/stat`, 'utf8').split(') ').at(-1).split(' '); + const status = readFileSync(`${path}/status`, 'utf8'); + const nested = status.match(/^NSpid:\s*(.*)$/m)?.[1].trim().split(/\s+/); + if (proc.uid !== process.getuid() || Number(stat[1]) !== child.pid || ns.ino !== inode || ns.ino === statSync('/proc/self/ns/pid').ino || nested?.at(-1) !== '1') throw new Error('namespace ownership unverified'); +} + +export function roleProbeFromAllowlist(allowlist, timeoutMs = 3000) { + if (!allowlist || typeof allowlist !== 'object' || Array.isArray(allowlist)) throw configurationError('invalid MCP allowlist'); + return (name, { signal } = {}) => { + if (typeof name !== 'string' || !Object.hasOwn(allowlist, name)) throw configurationError('MCP is not allowlisted'); + const entry = allowlist[name]; + if (!entry || typeof entry !== 'object' || Array.isArray(entry)) throw configurationError('invalid MCP allowlist entry'); + return probeStdioMcp({ command: entry.command, env: entry.env, timeoutMs, signal }); + }; +} + +// The profile contains identifiers only. Callers must resolve them using a +// trusted private allowlist; never construct this command from session text. +export async function probeStdioMcp({ command, env = {}, timeoutMs = 3000, signal, spawnProcess = spawn }) { + if (!Array.isArray(command) || command.length < 1 || command.length > 64 || !command.every(value => typeof value === 'string' && value.length > 0 && value.length < 8192 && !value.includes('\0')) || !isAbsolute(command[0]) || !env || typeof env !== 'object' || Array.isArray(env) || !Object.entries(env).every(([key, value]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && typeof value === 'string' && !value.includes('\0')) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 || (signal !== undefined && !(signal instanceof AbortSignal))) throw configurationError('invalid MCP probe configuration'); + return new Promise((resolve, reject) => { + let child, timer, reapTimer, buffer = '', info = '', phase = 'gate', finished = false, closed = false, desired = false, resolved = false, namespaceVerified = false, gateAcknowledged = false, protocolReady = false; + let onAbort; + const done = result => { if (!resolved) { resolved = true; clearTimeout(reapTimer); if (!namespaceVerified || !gateAcknowledged) reject(configurationError('MCP probe containment or gate unverified')); else resolve(result); } }; + const finish = result => { + if (finished) return; + finished = true; desired = result; clearTimeout(timer); + if (signal && onAbort) signal.removeEventListener('abort', onAbort); + if (!closed && child?.pid && child.exitCode == null && child.signalCode == null) { try { process.kill(-child.pid, 'SIGKILL'); } catch {} } + if (!child || closed) done(child ? desired : false); + else reapTimer = setTimeout(() => { if (!resolved) { resolved = true; reject(new Error('probe cancellation unconfirmed')); } }, 1000); + }; + if (signal?.aborted) { resolved = true; resolve(false); return; } + try { child = spawnProcess('/usr/bin/bwrap', ['--info-fd', '3', '--die-with-parent', '--bind', '/', '/', '--proc', '/proc', '--dev-bind', '/dev', '/dev', '--unshare-pid', '--', '/usr/bin/python3', '-B', gateProgram, '--', ...command], { detached: true, shell: false, stdio: ['pipe', 'pipe', 'ignore', 'pipe'], env }); } + catch { finish(false); return; } + timer = setTimeout(() => finish(false), timeoutMs); + onAbort = () => finish(false); + signal?.addEventListener('abort', onAbort, { once: true }); + if (signal?.aborted) { finish(false); return; } + if (!child.stdio?.[3]) { finish(false); return; } + child.stdio[3].setEncoding('utf8'); + child.stdio[3].on('data', data => { info += data; if (Buffer.byteLength(info) > 8192) finish(false); }); + child.stdio[3].on('end', () => { + if (finished) return; + try { verifyNamespace(info, child); namespaceVerified = true; child.stdin.write('GO\n'); } + catch { finish(false); } + }); + child.once('error', () => finish(false)); + child.once('close', () => { closed = true; if (!finished) finish(false); else done(desired); }); + child.stdin.on('error', () => finish(false)); + child.stdout.setEncoding('utf8'); + const write = message => child.stdin.write(`${JSON.stringify(message)}\n`); + child.stdout.on('data', data => { + if (finished) return; + buffer += data; + if (Buffer.byteLength(buffer) > 1024 * 1024) return finish(false); + let index; + while (!finished && (index = buffer.indexOf('\n')) >= 0) { + const line = buffer.slice(0, index); buffer = buffer.slice(index + 1); + let reply; try { reply = JSON.parse(line); } catch { return finish(false); } + if (phase === 'gate') { + if (!namespaceVerified || Object.keys(reply || {}).join(',') !== 'agentMeshMcpGate' || reply.agentMeshMcpGate !== 'released') return finish(false); + gateAcknowledged = true; phase = 'initialize'; + write({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'role-profile-probe', version: '1' } } }); + continue; + } + if (reply?.jsonrpc !== '2.0') return finish(false); + if (phase === 'initialize' && reply.id === 1) { + if (reply.error || !reply.result || reply.result.protocolVersion !== '2024-11-05' || !reply.result.capabilities || typeof reply.result.capabilities !== 'object' || Array.isArray(reply.result.capabilities) || typeof reply.result.serverInfo?.name !== 'string' || !reply.result.serverInfo.name || typeof reply.result.serverInfo.version !== 'string' || !reply.result.serverInfo.version) return finish(false); + phase = 'ping'; + write({ jsonrpc: '2.0', method: 'notifications/initialized' }); + write({ jsonrpc: '2.0', id: 2, method: 'ping', params: {} }); + } else if (phase === 'ping' && reply.id === 2) { + if (reply.error || !reply.result || typeof reply.result !== 'object' || Array.isArray(reply.result)) finish(false); + else { protocolReady = true; if (namespaceVerified) finish(true); } + } else if (reply.id !== undefined) return finish(false); + } + }); + }); +} diff --git a/skills/agent-tmux/bin/trigger-journal.mjs b/skills/agent-tmux/bin/trigger-journal.mjs new file mode 100644 index 00000000..fa92734e --- /dev/null +++ b/skills/agent-tmux/bin/trigger-journal.mjs @@ -0,0 +1,95 @@ +/** Private crash-conservative journal for trigger transactions. */ +import { constants, closeSync, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'; +import { createHash, randomUUID } from 'node:crypto'; +import { isAbsolute, join } from 'node:path'; + +const token = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); +const terminal = new Set(['verified', 'rolled-back', 'dry-run', 'not-applied']); +const statuses = new Set(['planning', 'applying', 'rolling-back', 'uncertain', ...terminal]); +const key = trigger => JSON.stringify([trigger.kind, trigger.id]); + +export function triggerJournal(root) { + if (typeof root !== 'string' || !isAbsolute(root)) throw new Error('invalid journal root'); + const checkRoot = () => { + const info = lstatSync(root); + if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || realpathSync(root) !== root) throw new Error('journal root must be private and canonical'); + }; + const file = join(root, 'trigger-transactions.json'), lock = join(root, '.trigger-transactions.lock'); + const syncRoot = () => { const fd = openSync(root, constants.O_RDONLY | constants.O_DIRECTORY); try { fsyncSync(fd); } finally { closeSync(fd); } }; + const load = () => { + let fd; + try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW); } + catch (error) { if (error.code === 'ENOENT') return { schema: 'agent-mesh.trigger-journal.v1', entries: [] }; throw error; } + try { + const info = fstatSync(fd); + if (!info.isFile() || info.uid !== process.getuid() || info.nlink !== 1 || (info.mode & 0o077) !== 0 || info.size > 8 * 1024 * 1024) throw new Error('invalid journal file'); + const data = JSON.parse(readFileSync(fd, 'utf8')); + if (data?.schema !== 'agent-mesh.trigger-journal.v1' || !Array.isArray(data.entries) || new Set(data.entries.map(entry => entry?.id)).size !== data.entries.length || data.entries.some(entry => !token(entry?.id) || typeof entry.dryRun !== 'boolean' || !Array.isArray(entry.triggers) || entry.triggers.some(t => !token(t?.kind) || !token(t?.id)) || new Set(entry.triggers.map(key)).size !== entry.triggers.length || !statuses.has(entry.status))) throw new Error('invalid journal content'); + return data; + } finally { closeSync(fd); } + }; + const save = data => { + const body = `${JSON.stringify(data)}\n`; + if (Buffer.byteLength(body) > 8 * 1024 * 1024) throw new Error('journal is too large'); + const temporary = join(root, `.trigger-journal-${randomUUID()}.tmp`); + const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); + try { writeFileSync(fd, body); fsyncSync(fd); } finally { closeSync(fd); } + renameSync(temporary, file); syncRoot(); + }; + const transaction = operation => { + checkRoot(); + let fd; + try { fd = openSync(lock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); } + catch (error) { if (error.code === 'EEXIST') throw new Error('journal lock held or requires recovery'); throw error; } + try { fsyncSync(fd); syncRoot(); const data = load(); const result = operation(data); save(data); return result; } + finally { + const owned = fstatSync(fd); closeSync(fd); + const current = lstatSync(lock); + if (current.dev !== owned.dev || current.ino !== owned.ino) throw new Error('journal lock changed'); + unlinkSync(lock); syncRoot(); + } + }; + return { + async begin({ id, triggers, dryRun }) { + if (!token(id) || !Array.isArray(triggers) || typeof dryRun !== 'boolean' || triggers.some(t => !token(t?.kind) || !token(t?.id)) || new Set(triggers.map(key)).size !== triggers.length) throw new Error('invalid journal reservation'); + return transaction(data => { + if (data.entries.some(entry => entry.id === id)) throw new Error('transaction already reserved'); + const requested = new Set(triggers.map(key)); + if (data.entries.some(entry => !terminal.has(entry.status) && entry.triggers.some(trigger => requested.has(key(trigger))))) throw new Error('overlapping transaction unresolved'); + data.entries.push({ id, dryRun, status: 'planning', triggers: structuredClone(triggers), receipt: null }); + }); + }, + async write(receipt) { + return transaction(data => { + const entry = data.entries.find(item => item.id === receipt?.id); + if (!entry || terminal.has(entry.status) || receipt.schema !== 'agent-mesh.trigger-transaction.v1' || receipt.dryRun !== entry.dryRun || !statuses.has(receipt.status) || !Array.isArray(receipt.triggers) || JSON.stringify(receipt.triggers.map(key)) !== JSON.stringify(entry.triggers.map(key))) throw new Error('invalid journal update'); + entry.status = receipt.status; entry.receipt = structuredClone(receipt); + }); + }, + async get(id) { + checkRoot(); + if (!token(id)) throw new Error('invalid transaction id'); + const entry = load().entries.find(item => item.id === id); + return entry ? structuredClone(entry) : null; + }, + async withRecovery(id, callback) { + checkRoot(); + if (!token(id) || typeof callback !== 'function') throw new Error('invalid recovery request'); + const recoveryLock = join(root, `.trigger-recovery-${createHash('sha256').update(id).digest('hex')}.lock`); + let fd; + try { fd = openSync(recoveryLock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); } + catch (error) { if (error.code === 'EEXIST') throw new Error('recovery lock held or requires reconciliation'); throw error; } + try { + fsyncSync(fd); syncRoot(); + const journal = triggerJournal(root), entry = await journal.get(id); + if (!entry || entry.status !== 'uncertain' || !entry.receipt) throw new Error('transaction not recoverable'); + return await callback(entry.receipt, receipt => journal.write(receipt)); + } finally { + const owned = fstatSync(fd); closeSync(fd); + const current = lstatSync(recoveryLock); + if (current.dev !== owned.dev || current.ino !== owned.ino) throw new Error('recovery lock changed'); + unlinkSync(recoveryLock); syncRoot(); + } + } + }; +} diff --git a/skills/agent-tmux/bin/trigger-transaction.mjs b/skills/agent-tmux/bin/trigger-transaction.mjs new file mode 100644 index 00000000..af48dd6b --- /dev/null +++ b/skills/agent-tmux/bin/trigger-transaction.mjs @@ -0,0 +1,101 @@ +/** Reconcile session-bound triggers through an operator-provided CAS adapter. */ +const token = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value); + +// begin must atomically reserve this ID and trigger set, rejecting unresolved +// overlapping transactions. Each write must be durable before it resolves. +// The adapter atomically compares target AND version and stores operationId. +export async function reconcileTriggers({ triggers, from, to, transactionId, adapter, journal, dryRun = true }) { + if (!Array.isArray(triggers) || triggers.length > 256 || !token(from) || !token(to) || from === to || !token(transactionId) || transactionId.length > 90 || typeof dryRun !== 'boolean' || typeof adapter?.read !== 'function' || typeof adapter?.move !== 'function' || typeof journal?.begin !== 'function' || typeof journal?.write !== 'function') throw new Error('invalid trigger transaction'); + const seen = new Set(); + for (const trigger of triggers) { + if (!token(trigger?.kind) || !token(trigger?.id) || seen.has(`${trigger.kind}\0${trigger.id}`)) throw new Error('invalid or duplicate trigger'); + seen.add(`${trigger.kind}\0${trigger.id}`); + } + const receipt = { schema: 'agent-mesh.trigger-transaction.v1', id: transactionId, from, to, dryRun, status: 'planning', triggers: triggers.map(({ kind, id }) => ({ kind, id, status: 'pending' })) }; + await journal.begin({ id: transactionId, triggers: structuredClone(triggers), dryRun }); + const save = () => journal.write(structuredClone(receipt)); + for (let i = 0; i < triggers.length; i++) { + let current; + try { current = await adapter.read(triggers[i]); } catch { /* No mutation has been attempted. */ } + if (!current || current.target !== from || !token(current.version)) { + receipt.triggers[i].status = 'unverified'; + receipt.status = 'not-applied'; + receipt.reason = 'trigger source or version not verified'; + await save(); + return receipt; + } + receipt.triggers[i].before = current.version; + receipt.triggers[i].status = 'planned'; + } + receipt.status = dryRun ? 'dry-run' : 'applying'; + await save(); + if (dryRun) return receipt; + for (let i = 0; i < receipt.triggers.length; i++) { + const row = receipt.triggers[i], operationId = `${transactionId}:${i}`; + row.status = 'applying'; row.operationId = operationId; await save(); + let response; + try { response = await adapter.move({ kind: row.kind, id: row.id, expectedTarget: from, expectedVersion: row.before, target: to, operationId }); } + catch { row.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + if (response?.status !== 'applied' || !token(response.version)) { + row.status = response?.status === 'not-applied' ? 'not-applied' : 'uncertain'; + receipt.status = row.status === 'uncertain' ? 'uncertain' : 'rolling-back'; await save(); + if (row.status === 'uncertain') return receipt; + for (let j = i - 1; j >= 0; j--) { + const prior = receipt.triggers[j], rollbackId = `${transactionId}:rollback:${j}`; + prior.status = 'rolling-back'; await save(); + let rollback; + try { rollback = await adapter.move({ kind: prior.kind, id: prior.id, expectedTarget: to, expectedVersion: prior.after, target: from, operationId: rollbackId }); } + catch { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + if (rollback?.status !== 'applied' || !token(rollback.version)) { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + let observed; + try { observed = await adapter.read(prior); } catch { /* The rollback may have applied. */ } + if (observed?.target !== from || observed.version !== rollback.version || observed.lastOperationId !== rollbackId) { prior.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + prior.status = 'rolled-back'; prior.rollbackVersion = rollback.version; await save(); + } + receipt.status = 'rolled-back'; await save(); return receipt; + } + let observed; + try { observed = await adapter.read(row); } catch { /* The move may have applied. */ } + if (observed?.target !== to || observed.version !== response.version || observed.lastOperationId !== operationId) { row.status = 'uncertain'; receipt.status = 'uncertain'; await save(); return receipt; } + row.after = response.version; row.status = 'verified'; await save(); + } + receipt.status = 'verified'; await save(); return receipt; +} + +/** Explicitly roll back an uncertain transaction after inspecting all targets. */ +export async function recoverUncertainTriggers({ transactionId, adapter, journal }) { + if (!token(transactionId) || typeof adapter?.read !== 'function' || typeof adapter?.move !== 'function' || typeof journal?.withRecovery !== 'function') throw new Error('invalid trigger recovery'); + return journal.withRecovery(transactionId, async (receipt, save) => { + if (receipt.id !== transactionId || receipt.status !== 'uncertain' || receipt.dryRun !== false || !Array.isArray(receipt.triggers)) throw new Error('invalid uncertain receipt'); + const observations = []; + for (let i = 0; i < receipt.triggers.length; i++) { + const row = receipt.triggers[i], observed = await adapter.read(row); + if (!observed || !token(observed.version)) throw new Error('trigger observation unavailable'); + const forwardId = `${transactionId}:${i}`, rollbackId = `${transactionId}:rollback:${i}`; + if (observed.target === receipt.from && observed.version === row.before) observations.push({ kind: 'unchanged', observed }); + else if (observed.target === receipt.from && observed.lastOperationId === rollbackId && (!row.rollbackVersion || row.rollbackVersion === observed.version)) observations.push({ kind: 'rolled-back', observed }); + else if (observed.target === receipt.to && observed.lastOperationId === forwardId && (!row.after || row.after === observed.version)) observations.push({ kind: 'moved', observed }); + else throw new Error('trigger changed outside transaction'); + } + for (let i = receipt.triggers.length - 1; i >= 0; i--) { + const row = receipt.triggers[i], { kind, observed } = observations[i]; + if (kind !== 'moved') { + row.status = kind === 'unchanged' ? 'not-applied' : 'rolled-back'; + if (kind === 'rolled-back') row.rollbackVersion = observed.version; + continue; + } + const operationId = `${transactionId}:rollback:${i}`; + row.after = observed.version; row.status = 'rolling-back'; receipt.status = 'rolling-back'; await save(receipt); + let result, confirmed; + try { + result = await adapter.move({ kind: row.kind, id: row.id, expectedTarget: receipt.to, expectedVersion: observed.version, target: receipt.from, operationId }); + if (result?.status === 'applied' && token(result.version)) confirmed = await adapter.read(row); + } catch { /* The outcome may have been applied. */ } + if (confirmed?.target !== receipt.from || confirmed.version !== result?.version || confirmed.lastOperationId !== operationId) { + row.status = 'uncertain'; receipt.status = 'uncertain'; await save(receipt); return receipt; + } + row.status = 'rolled-back'; row.rollbackVersion = result.version; await save(receipt); + } + receipt.status = 'rolled-back'; await save(receipt); return receipt; + }); +}