Skip to content

tracking(cli): improve the external-agent CLI experience #6168

Open

Description

@me2seeks

Problem

When another agent uses Maka CLI as a worker, Session IDs and --no-wait already provide a useful control flow: submit, keep the ID, then inspect, steer, answer, or stop the Session. The gap reported in hands-on use is understanding the progress of a long-running task. A running status and a steering admission receipt do not convey intermediate findings.

TUI /recap already summarizes recorded Session progress through an independent Host model call, including during an active Turn. External CLI callers need access to that capability. Portable Session export serves a different purpose and should not be needed to observe progress.

Desired outcome

Keep the existing Session ID and control model, and improve the caller's ability to understand progress and handle interactions. Track concrete experience improvements here rather than treating one CLI test run as a mandate to redesign every interface.

Recap acceptance: text and JSON output, no stdin blocking, fresh independent model generation, unchanged Turn identity/queue/permissions, visible generation errors, and cancellation that leaves Host execution running. Explain that a recap summarizes recorded evidence, consumes model usage, and is not a direct reply from the running worker.

Alternatives or workarounds

--status remains useful for lifecycle and pending interactions. --steer changes the running Turn's input and its receipt is not a progress reply. session-export is a portable bundle operation. A dedicated worker-to-parent message channel can be evaluated separately if evidence-based recap proves insufficient.

Related existing work: #6119 / #6120 (Session discovery) and #5958 / #6036 (transcript export); this tracker does not replace those contributions.

Prepared with Codex at the contributor's request.

GitHub native stack #6172: #6169 → #6170 → #6171. Review fixes for executor model changes and unchanged native targets are in #6170 (e6036a1b2c).

Activity

  1. me2seeks commented on Oct 19, 2026

    @me2seeks
    ContributorAuthor

    Real-provider acceptance completed against #6170 head 5c6c1a1987c560b3e4817751133172c58923a5f8 (stacked on #6169), using the built production CLI, an isolated XDG profile, and the existing selected account. The user's original Host and active tasks were preserved.

    Verified as a parent-agent workflow:

    • Detached task → durable Session ID → independent wait → AskUser options → parent answer → task continues.
    • Active review --status --recap returned a stage summary in 4.177 seconds; the worker continued its original review.
    • Sandbox approval: Write first returned sandbox_boundary_required; the CLI returned the exact path/write/subtree request; approval allowed the retry; the parent read back the expected file.
    • Denial in a separate Session left the file absent and boundary revision unchanged. No pending approval remained.
    • Queued input while AskUser was pending returned submission: "queued" together with needs_input; answering the current task yielded its result, then a later wait yielded the queued task's result.
    • A different model on an active Session was rejected by Host; identical settings were accepted as a no-op. An unknown model was rejected before persistence.
    • An actual Kimi request failed with insufficient credits. The CLI preserved the provider error and exit 1. Saving DeepSeek on the same Session did not run work; explicit --resume --no-wait then completed successfully. No CLI failure classification or automatic fallback was needed.

    Two concrete follow-ups remain:

    1. Denied-approval outcome consistency: --status returned completed, whereas --result --json / --wait --json returned failed with Turn encountered an unresolved sandbox boundary, exit 1, for the same latest Turn. The current status path reads root lifecycle; result additionally applies the sandbox outcome classifier. Reconcile or explicitly distinguish those contracts without making lightweight status replay the entire transcript or guessing failure causes.
    2. Structured operation errors: invalid-model and active-configuration failures with --json returned empty stdout and human stderr; terminal provider failures returned structured JSON. Preserve the Host message/code in a compact error envelope consistently, without quota-specific policy.

    Source-grounded self-review found no new blocking defect in the submitted diffs. The worker's proposed thinking-reset concern matches existing Desktop behavior; its missing-validation concern was disproved by Host validation and the live unknown-model probe. This is AI-assisted self-review and does not replace independent human review.

    Prepared with Codex at the contributor's request.

  2. me2seeks commented on Oct 19, 2026

    @me2seeks
    ContributorAuthor

    Combined-stack native CLI experience with the user's requested OpenAI official gpt-6-luna is complete. Two real Maka Sessions reviewed different PRs, then cross-checked each other's reports under this parent coordinator. AskUser and exact path approval requests were serviced by the parent. After the user requested direct CLI use, subsequent control calls used maka run directly, without a Python invocation wrapper.

    Verified:

    • AskUser → parent answer → same task continues; running recap described real recorded progress.
    • Approval granted only a dedicated report directory; the file was read back. Denial left the target file absent. A direct --deny --wait --json continued waiting until the model successfully read HEAD and completed; status/result agreed on completed.
    • Missing-file Read and Bash exit 7 remained recoverable tool errors; a subsequent Read succeeded and the Turn completed.
    • A real alternative-model request returned insufficient credits. Saving the official OpenAI connection + gpt-6-luna on that Session and explicitly resuming completed the task. No automatic CLI recovery was involved.
    • A deliberately capped --max-steps 1 Turn failed with the existing Runtime class tool_step_cap_reached. This exposed a presentation bug: the stored Turn already had errorClass, but a generic fallback masked it. Fixed in fix(cli): preserve Runtime outcomes and explicit JSON errors #6171 commit 008bb67dd3; direct CLI result now returns the existing class when no original message exists. 67 affected outcome/adapter/activation tests passed, along with CLI build/typecheck and lint/format checks. No new error classification was introduced.

    Separate reproducible Runtime issue: stopping a native Turn while AskUser is pending drains the Host. Reproduced three times, including with a foreground production Host and a single active Turn:

    1. Start a native gpt-6-luna task whose first action is AskUserQuestion and wait for needs_input.
    2. Invoke maka run --session <id> --stop --json.
    3. Observe exit 1 with original {error:"Runtime Host is draining",code:"host_draining"}.
    4. Foreground Host logs unexpected turn.stop failure: Error: Cannot terminalize invocation ... with unsettled tool operation toolop_... from SqliteRuntimeStore.importRuntimeEventSync. Recovery has also produced failed / outcome_unknown; other active test work was cancelled during drain.

    Investigate native AskUser tool settlement before invocation terminalization. Keep the storage invariant; do not work around it in CLI. The three PRs do not modify Runtime/Host/storage relative to their base, so this is recorded as a separate stop-path issue rather than attributed to the CLI changes. Existing FakeBackend stop tests did not cover this native behavior.

    The reviewers found no other verified blocking defect. One reviewer correctly limited its initial step-cap conclusion until the parent supplied the matching Host + persisted transcript evidence. Cross-review also corrected an overly strong claim that every executor configuration callback must return a confirming snapshot: the interface permits void, so completion and snapshot confirmation are distinct. Neither automated review constitutes independent human approval.

    Prepared with Codex at the contributor's request. Test sessions used an isolated profile; the original user Host and defaults were preserved.

  3. me2seeks commented on Oct 19, 2026

    @me2seeks
    ContributorAuthor

    Codex update: the native AskUser stop defect is fixed in #6174 (ccfea27ba2), independently based on main.

    Confirmed on main with a production Host/native-backend regression: the normal interaction closure bypassed tool T2 settlement, then storage rejected terminalization with an unsettled operation. The fix commits the known aborted tool result before rethrowing the same control signal. Storage guards and invariant/fail-stop behavior remain intact.

    Local validation: 196 focused tests, 89 overlapping broader ToolRuntime/RuntimeKernel tests, full build/typecheck/lint/format, Desktop/UI knip, ASF headers and Windows inventory passed. The real official gpt-6-luna CLI repro now stops without draining, with Host ready and canonical Turn cancelled; the same Session then completes a new prompt with stop-recovered. Isolated credentials were removed and the original user Host was untouched.

    The tracker item remains open pending review/merge. This is separate from the CLI output simplification stack #6172.

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

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions