Skip to content

oxa lead: the session the owner talks to, on top of oxa work (replaces an outside orchestrator) #629

Open

Description

@n0rpan

Owner direction (2026-11-16): the project is not meant to be steered by an outside orchestrating assistant with shell scripts. ox-llm itself should be the complete suite: the owner talks to one oxa session and it runs the team. This issue tracks that layer; oxa work (#333) is the floor under it.

Steps, each proven by real use before the next:

  1. Facts (in the runner's crate): typed events with sequence numbers, a small bounded situation file the runner keeps current (what runs where, what landed, what is blocked, what is asked), oxa work situation and oxa work events --after N, stall detection, an incident list.
  2. Standing rules: one file for the owner's rules, holds and asks, with revisions, read at every action (a held pull request is refused by approve, enqueue and update alike); oxa work rule|hold|ask.
  3. oxa lead: an ordinary oxa session (TUI or print) with one extra tool, work, and read-only file tools. It stores what the owner says as typed entries, writes task goals, orders work through the runner, and brings a decision as one item with options, a recommendation and what happens meanwhile. Every 'merged', 'running', 'validated' or 'held' it states comes from the runner's state, never from its own memory. Woken by events, not polling; cheap enough for the local model.
  4. Truthful reporting: state beside every mention, evidence kinds, a generated summary after an unattended period.
  5. Team: model profiles per task kind, review and verify tasks with typed findings, filling idle machines from facts.
  6. Unattended period: goal mode for a night, with its own time and token allowance.
  7. Lanes: long-lived workers with a standing goal started from one goal document; local process, another machine or hosted is a property of the lane.
  8. Lead on the local model; 9. merge policy in the runner; 10. vendor agents as workers.

Also part of the suite rather than outside scripts: provider balances (#627), live model discovery (#628).

First acceptance: the owner works one evening with oxa lead, one helper machine and the merge queue, and never has to ask for a manual check.

🤖 Generated with Claude Code

Activity

  1. n0rpan commented on Nov 16, 2026

    @n0rpan
    CollaboratorAuthor

    Inputs from a comparison with the Codex CLI harness: the session inbox (#638) is the wake-up mechanism for the lead; the ask tool and the schema-checked final answer are filed separately; still to place after checking overlap with the open runner drafts: goal mode (stored objective, a done/blocked tool, one fixed continuation message), oxa review with typed findings, and a richer oxa_result (session id, tokens, files changed) with a no-delta JSON stream. Runner agent: say on #331 which of these your drafts already cover.

    🤖 Generated with Claude Code

  2. n0rpan commented on Nov 16, 2026

    @n0rpan
    CollaboratorAuthor

    Owner direction (2026-11-16): the current orchestrator dogfoods the lead before the owner does. Stages:

    1. Shadow (can start as soon as the lead skill and preset are on main, before the runner facts exist): an oxa lead session on a helper machine gets the same inputs the orchestrator gets (a state digest, the board, review verdicts) with read-only tools, and writes what it would do: approve, send back, hand out, ask the owner. The orchestrator compares that with what it actually did and files every difference as an issue: a wrong or missing action, something stated that the state does not support, a hold not honoured, a reminder it needed.
    2. Supervised: the lead acts through the runner on one helper machine; the orchestrator plays the owner, steers only through the lead's own interface (messages, holds, decisions) and files an issue each time it has to step around it.
    3. Owner's first evening: only after a supervised session with no step-around.

    Each filed issue names the stage and carries the lead's card and the state it was based on.

    🤖 Generated with Claude Code

  3. n0rpan commented on Nov 16, 2026

    @n0rpan
    CollaboratorAuthor

    O-367 decision: option B. Preserve the capabilities, including steering and following another agent's session (O-307). Do not review or merge the roughly 37k-line a2a/* drafts as integration units. After v0.2.1 ships, rebuild the carry items below as small, separately reviewable PRs against then-current main. All three drafts remain untouched until then; no A2A review capacity before release. “Drop” below means omit duplicate implementation from the rebuild, not close or alter a draft.

    The table below remains the previously inspected, pinned source map, not a fresh claim about today's main. Revalidate each carry against current main after release before opening its PR. Steering and following are required capabilities; the A2A transport is conditional on a concrete external-worker need. The useful unreleased pieces are chiefly #129's owned background jobs and shared-session control. Merging the old orchestrator wholesale would also introduce a second task/goal owner beside oxa work and #709.

    Read-only source snapshot: main cf8e748, #88 ee04d55, #129 f89ba2e, #436 c36efefd. Paths below are under oxa/. “Missing” means the remaining capability was not found in these inspected implementations; pending successor PRs are identified explicitly and are not counted as main. This is a source map, not runtime acceptance. No draft branch was checked out, edited, built, pushed or merged.

    Capability In main already (where) Only in A2A drafts (file/function) Missing everywhere Recommendation (carry: smallest PR; drop)
    Deterministic task execution and crash recovery #336/#692: oxa-work/src/lib.rs::{plan_task_for_run,run_task_with_observer,recover_checkpoints}, state.rs, checkpoint.rs; frozen acceptance, retained worktrees and local saving. Main also has inert oxa-orchestrator::{AuditJournal,workspace} foundations. #88 run.rs::{run,run_cancellable}, recovery.rs::InspectedRun::inspect, resume.rs::resume_queued; #436's newer supervisor.rs, recovery.rs, workspace_jobs.rs implement another supervisor/recovery family. Wiring the lead to the runner's protected read/action boundary; old recovery code does not provide that wiring. Drop the duplicate local scheduler/task journal. Keep runner state authoritative; carry any genuinely new recovery invariant as a focused runner regression, not a replacement runtime.
    One persistent goal and bounded continuation #731: oxa-session/src/goal.rs::Goal persists objective/status/spent budgets in the existing Custom envelope. #709 is the requirement; #747 is still open, so its print continuation/goal_done/cancellable wait are not main. #129 goal_session.rs::pursue, goals.rs::Goal::{begin_turn,finish_turn,pause,resume,set_goal}; #436 goals.rs adds explicit overrun and corrected event pagination, but its interactive-control feature is a state machine, not a live CLI/TUI integration. Unified live goal control through the current TUI/print/inbox, with the required acceptance. Carry the smallest existing successor, #747 “pursue stored goals in print mode”, then a TUI/inbox slice over #731. Drop the second goal ledger and old orchestrate --goal loop.
    Background commands that wake the same session Synchronous bash/runner/subagent work, plus #651's wake delivery substrate: oxa-session/src/inbox.rs::{send_inbox,Inbox::watch}, consumed by interactive driver.rs and RPC server.rs. The inbox alone does not launch/supervise jobs. #129 background.rs::{Manager::start,Manager::completions,Snapshot::wake_text,augment}, background_process.rs; tui.rs::Owner::tick handles completion/goal wakes. Access::Exec, sandbox admission, bounded output and owned cancellation are implemented there. A current-session background tool wired to #651/#709. Terminal-close survival is also unprovided: #129's TaskHooks::shutdown/Drop call Manager::stop; runner/subagent ownership is not a detached service. Carry: “core: owned background_command with inbox completion” from #129, reusing current Exec/sandbox/cancellation and one owner. Keep terminal-survival as an explicit separate lifecycle requirement, not an accidental orphan process.
    Watch a log or process #651 watches its own inbox directory; oxa status reads progress. Neither is a general log/process watch. #129 can supervise a command that waits/watches and wake on its completion; it has no dedicated typed log/process watcher. Bounded watch registration, cancellation, coalesced events and delivery to the owning session without model polling. Carry: “session: bounded file/process watch to inbox”, a new small Rust event-source slice; reuse #651 and the owned-job lifecycle. Do not carry a shell polling loop.
    Scheduled wake-ups No session wake scheduler. #747's pending wait is a cancellable relative wait in an active goal, not a durable schedule. #129/#436 Goal::tick enforces budget/deadline state; it does not register future session wake-ups. Persisted one-shot/recurring schedules, restart handling and delivery identity/receipt semantics. Carry: “inbox: persisted one-shot wake deadline” first; recurring scheduling is a follow-on. Neither old A2A scheduler is a calendar/wake scheduler.
    Subagents with their own context oxa-core/src/subagent.rs::SubagentHooks and child launch/cleanup: own child sessions, bounded results, local serialization and bounded remote-model concurrency; oxa-cli/tests/e11_subagent_processes.rs. Parent waits inside the call. #88/#436 rpc_agent.rs::RpcAgent and a2a_run.rs::run_a2a add registered A2A endpoints and a separate fan-out scheduler. Nonblocking child results/steering through the current parent session; separate-context subagents themselves are already present. Drop duplicate same-machine subagent/context machinery. Carry: “subagent: background handle with inbox completion” after the owned-background primitive; only add A2A for an actual external worker requirement.
    Steer another agent's session #651: oxa send, CLI dispatch.rs → send_inbox; TUI/RPC receive it. Native RPC server.rs already supports steer, follow_up, abort, get_state. Inbox callback acceptance is in-memory admission, not durable execution confirmation. #129 control.rs::{Request,Server::start} and goal_session.rs::Control provide request IDs, revisioned pause/resume/set-goal/steer and admitted/rejected events; tui.rs::Owner::control connects them to the same session. #436 does not carry this live control transport. One trusted, typed current-session control/receipt API for lead, preserving source authority and stale-revision rejection. Carry: “session: revisioned control receipts over the existing inbox” using #129's admission/rejection rules and tests. Do not add a second socket/runtime merely to send text; retain #651's real delivery limits until receipts are implemented.
    Follow another session oxa-cli/src/status.rs::run gives bounded progress/stall snapshots; owned RPC streams provide live events. No general reconnectable attach/follow command for another existing TUI session. #129 control.rs::Publisher::{publish,bind_session} and events handling expose bounded sequenced status/reply events with gaps; tui.rs::Owner::native supplies TUI events. #436 goals.rs::Goal::events plus tests/goal_pagination.rs preserve unread-page cursor correctness. A current-runtime follow API with bounded/redacted events, reconnect cursors, gap recovery and appropriate delivery receipts. Carry: “session: bounded follow events with cursor recovery”; port #129's event selection and #436's no-skipped-events regression intent, adapting to the current exclusive-after contract rather than copying incompatible cursor numbers.
    Persistent memory Session transcripts/store and #731 goal metadata persist; oxa-resources/src/context.rs::load_context loads explicit AGENTS/CLAUDE/SYSTEM/APPEND_SYSTEM files. Those are useful storage/context, not a managed cross-session memory feature. Journals/checkpoints/goals in all three drafts are execution/recovery data, not semantic/project memory. No dedicated memory implementation found. User-controlled memory write/read, scope/provenance, review/update and deletion integrated with the normal context policy. Carry: “resources: explicit project-memory read/write contract”, initially on existing text/context files and permission APIs. Drop any claim that retaining an orchestrator journal solves memory; no new memory service is needed for the first slice.
    Publish a page/report oxa-export/src/html.rs::{export_html,write_export} writes an HTML artifact. oxa-cli/src/report_cmd.rs::{save_draft,submit} can submit a scrubbed issue after real user/TTY confirmation; model-originated calls cannot self-confirm. This is not unattended lead publishing or page hosting. #88/#436 review.rs::PreparedReview::{prepare,stage} publishes an approved local candidate directory, not a public report/page or GitHub PR. A scoped model-facing report publication operation with explicit authority and a returned publication receipt; page hosting is absent. Carry: “lead: approved scrubbed report publication” over existing export/report code and runner authority. Preserve the current confirmation boundary; do not mistake local staging or bash capability for an authorized publisher.
    Review bundles and publishing code changes oxa-work/src/execute.rs::save_work saves local work; main oxa-orchestrator/src/workspace.rs::ReviewBundle::{verify,overlaps,verify_current_base} already has bounded review primitives. Local success/commit is not publication or merge. #88/#436 review.rs::PreparedReview::{prepare,stage} adds selected-worker conflict checks and exact approval-bound candidate staging. #436 also has lineage/checkpoint/registered-workspace bindings. Runner-owned PR/push/queue effects under fresh standing/hold checks; none of these local staging functions proves a remote effect. Carry: “work: approval-bound candidate export”, reusing review/overlap tests and current runner state. Drop a second publication policy or automatic merge path; subsequent remote effects stay separate guarded runner slices.
    Owner-facing lead session #624's preset-only LEAD_SKILL, proposal schema and explicit read-only print recipe are main. #685 typed cards and #764 oxa lead --shadow remain open; they are not main features. #129 provides a generic shared goal conversation, not #629's typed runner-backed owner entries/holds/asks/decisions. #88/#436's old CLI does not supply that contract. The live restricted oxa lead, work adapter and deterministic /status /asks /hold /decide, plus the SHADOW → supervised → owner acceptance. Carry existing #685 then #764, followed by “lead: typed work adapter and direct command routing” on the published runner/standing APIs. Drop parallel facts/task-state writers and old CLI integration.
    Optional A2A interoperability oxa-a2a/{wire,loopback,sse,server,collect}.rs already exists (hosting/collect behind agent-host); main's normal CLI/work/lead has no production caller of this transport. #436 rpc_agent.rs::RpcAgent, a2a_run.rs::{LocalAgent,Controller::steer,run_a2a}, a2a_recovery.rs::InspectedRun and a2a_reconcile.rs::InspectedRun::reconcile bind workers and reconcile uncertain results without replay. #88 has earlier versions. A typed optional A2A backend beneath the existing runner for a concrete external agent; this is not required for local wake/watch/memory/report capabilities. Carry only when needed: “work: one registered A2A worker transport”, then “work: reconcile uncertain remote task without replay”. Keep operator-fixed grants/budgets and identity bindings; drop the second A2A task queue/goal owner.

    Verdicts

    Current #129 carry accounting

    The pinned source map above remains historical evidence. The current required-piece accounting maps all14 #129 pieces to exact retained-source ranges and extracted/deferred status. #949 merged at97575bc7121c714674cdf808f9b45f8a7620ddb5; #1013 is open at6dcce4ed7c4b5a457b27b30f704b42b7e6954d5e; #1014 is open at92cb2351e3731f710c016ed5d055ca5170814541. These are bounded history, publication and admission foundations only. Every remaining live-control/background/goal/lifecycle/integration obligation is explicitly deferred to public #629 (and #939 for flags), including the known #129 cancellation finding. No rollup closure is authorized by this accounting; exact-head archive, parked label, #946 entry and branch retention remain required before any later authorized close.

  4. oxa-agent commented on Nov 17, 2026

    @oxa-agent
    Contributor

    O403 first extraction: #949 at085b4ad0,167 own changed lines on trunk. Ports #129 control.rs bounded follow-event retention and exclusive-after pages; carries #436 pagination regression intent, adapted to the current cursor contract. Default-off a2a feature, no second task/goal owner or socket. Tests cover unread pages, retention gaps/bytes and atomic rejection; hosted CI pending. Live follow/control wiring remains a subsequent carry. #88/#129/#436 remain untouched and retained; no closure/rewrite or archive action.

  5. added a commit that references this issue on Nov 17, 2026
  6. oxa-agent commented on Nov 17, 2026

    @oxa-agent
    Contributor

    The first three retained-source slices are now PRs: #949 merged (167 lines, bounded follow history); #1013 at6dcce4ed (180 lines, session-bound publication); #1014 at92cb2351 (177 lines, bounded control admission). All derive from retained #129 control.rs, with #436 pagination regression intent in #949, behind default-off a2a. Both new hosted crate lanes passed:44099731154 and44099738319. New PRs remain draft; full required/check summaries are not yet claimed green. No live follow/steering integration, new session/task owner, closure or merge claimed. Current main-red/docs priority takes precedence; heads and draft source are preserved.

  7. oxa-agent commented on Nov 17, 2026

    @oxa-agent
    Contributor

    Updated #129 carry accounting: #129 (comment)

    14 required pieces mapped to pinned source ranges, exact949/1013/1014 heads and explicit public deferrals. The three foundations are not live steering/background acceptance. No close, new issue, review, CI edit or dispatch; source branches retained.

  8. n0rpan commented on Nov 17, 2026

    @n0rpan
    CollaboratorAuthor

    Next carry for #927 and #307 row codex-send / bridge, after #1013 reaches main: qualify one native session owner's goal observations against the existing follow publisher.

    • Reuse the ordinary session's Session::state and Session::goal at the owning frontend. The follow publisher takes the session ID and a finite goal status. It has no goal writer or separate goal ledger. The first control uses goal status only. Objective, evidence, transcript, session file path and credentials stay inside the session.
    • Exercise the composition with the existing isolated native-session fixture and a persisted goal. Establish a goal through Session::set_goal, observe its status, close and reopen the saved session, then switch to a different session with no goal. Assert that current status carries the new session ID, that a status-only refresh leaves the event cursor unchanged, and that any earlier retained observation stays bound to its original session.
    • Keep the existing default-off feature and publisher ownership. A later consumer can read the bounded observations over an approved local path. Text/Enter delivery, stall detection and undelivered-input alarms remain separate acceptance under the same port row.

    #1013 stays on its reviewed publication patch for landing. As of main 5f091c51 it composes with main, but composition behind #1014 conflicts in the orchestrator README. Landing maintenance will preserve both sections once the queue leader lands.

    Port plan

  9. oxa-agent commented on Nov 17, 2026

    @oxa-agent
    Contributor

    The bounded control-admission slice #1014 is merged (head 6a219f1, merge e417e45); #1013 follow/publisher remains the next existing slice in qualification. These port the #307 codex-send/bridge row as data-contract foundations only. Live steering must reuse the existing receiving Session owner: native goal pause/resume exists, while an authoritative revision and terminal-cancel API still need the owner seam already requested by Local. Do not map cancel to resumable pause or add a second goal ledger. Helpers remain paused; neither slice enables live transport or execution.

  10. oxa-orchestrator commented on Nov 17, 2026

    @oxa-orchestrator

    Owner requirement (2026-11-17): a2a must be token-efficient and easy to use. Messages between lead and workers are compact structured envelopes (goal, task packet reference, state, result, ask), with deltas instead of full transcripts and references to artifacts (PR, commit, log) instead of pasted content. Each exchange has a size bound and its token cost is recorded. Workers get exactly the context packet they need (#1020); results come back as a typed summary plus links. Acceptance: a measured tokens-per-task figure lower than today's lane steering, with no loss of control (see #1199).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    post-0.2Not on the v0.2.0 release path

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions