Skip to content

Expose owned program lifecycles and daemon capabilities over MCP #160

Open

Description

@tony

Summary

Expose an owned program workflow in libtmux-mcp: launch literal arguments in a fresh PTY, inspect bounded output and completion evidence, send input, and explicitly stop or clean up that program. Report the connected daemon's feature decisions so an agent can choose an available operation before creating resources.

Motivation

The existing run_command tool sends a shell command into a borrowed pane and waits for a cooperative completion signal. An agent starting a test runner or development server also needs a separately owned lifetime, a handle it can revisit, and cleanup that preserves the user's existing session.

The Python core already tracks the owner in libtmux#823, with an initial implementation in libtmux#833. This issue tracks its MCP consumer. The core's stock-dispatcher implementation must remain usable independently of experimental engine branches.

Evidence

The current run_command implementation builds a shell payload, sends it to an existing pane, and waits on a private channel. RunCommandResult records shell status and bounded capture. Neither provides an independently owned program handle. The dependency declaration accepts libtmux>=0.62.0,<1.0; the proposed core owner is still separate work.

These are source observations. An MCP managed-program implementation and its runtime acceptance cases have not been qualified.

Proposal

  • Provide run-to-completion and start/read/input/wait/stop/cleanup workflows over the same core owner. Reuse core lifecycle and capability decisions; keep shell-context run_command available for its existing use case.
  • Accept literal argument arrays, working directory, environment and terminal geometry. Return a program handle bound to its daemon and pane lifetime, exact exit status or signal when observed, and explicit unknown outcomes when evidence is missing.
  • Make reads bounded and immediately useful while the program runs. Identify rendered capture, raw bytes and truncation or lost history in the result. Define final-output draining and backpressure before advertising byte streaming.
  • Keep tool calls responsive to cancellation and concurrent requests. Cancelling an observation and terminating a program need distinct documented effects; a cancelled worker thread alone does not settle an owned subprocess. Retain the original failure and any cleanup failures.
  • Expose supported, unsupported or unverified feature decisions with reasons from the actual connected daemon. Reuse the capability work in Gate unsafe optional tmux features independently #138 and libtmux#778. Test client/daemon version mismatch, prereleases, unknown versions, reconnects and server replacement. Refuse unsupported operations before launching or sending input.
  • Extend the existing toolset declarations, result models and discoverable tool descriptions. Document ownership, local-versus-remote daemon restrictions, controller shutdown, retained output and process-tree limits. A managed PTY provides lifecycle management; operating-system confinement requires a separate mechanism.
  • Keep the first delivery installable against its declared core dependency. Record core availability as a dependency and avoid silently requiring an unmerged engine branch or an unreleased package version.

Acceptance needs a short program that exits with status 7 and an unterminated final line; an interactive program receiving literal input; an unrelated pane that survives cleanup; refusal after external respawn or daemon replacement; cancellation that leaves no owned wait subprocess; and a second MCP request that remains responsive during a wait. Test discovery and the actual advertised schemas through an MCP client, including read-only tool selections. Pair critical guards with deliberate breaks that make their tests fail. Keep raw streaming or crash-recovery criteria open if the initial PR does not deliver them.

References

Activity

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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions