Skip to content

Run terminal applications across the JVM facades #172

Open

Description

@tony

Summary

The JVM libraries need an owned terminal-application API shared by Java, Kotlin, Clojure and every current Scala variant. Existing pane creation, shell-command completion and output subscriptions provide useful pieces, but callers still assemble application execution, input, exact exit and cleanup themselves.

Motivation

A Java consumer should run a literal executable/argv application through a scoped owner and receive a bounded result after cleanup. Kotlin coroutines, Clojure tasks and Scala effect scopes need their own native interfaces to the same responsibility. Cancelling an owning run must settle its application; cancelling an output reader or exit observation must leave the owner reachable.

Evidence

Current shared core and facade boundaries

This is a source-based proposal. The managed application contract has not been qualified through these public JVM surfaces. #143 provides private server startup, which is adjacent to application ownership.

Proposal

Add a shared immutable ProgramSpec, ProgramResult and typed ProgramExit, plus an owning Java Program with AutoCloseable and Server.runProgram:

  • Accept literal executable/argv, including zero arguments, cwd, environment and terminal geometry. Validate before dispatch; distinguish setup/exec failure, normal nonzero exit, signal, cancellation, timeout and uncertain observation.
  • Register ownership and exit observation before launch. Provide literal input, bounded rendered screen/output, observation-only waits and explicit termination. Finish the final output drain before completing the result.
  • Make owning run interruption, timeout and scope release terminate and settle owned work. Preserve interruption and the primary failure, carrying cleanup failure and reachable recovery separately. Borrowed sessions, panes and control clients must survive.
  • Reuse the existing command transport, control client, byte subscriptions and generation/receipt machinery. Keep blocking explicit in Java; use bounded execution and notification callbacks for nonblocking callers. Cancelling a CompletableFuture must not be treated as proof that its responsible worker or terminal application exited.
  • Gate every composed application feature from the canonical table using the actual accepted daemon version and generation. Refuse unavailable features before creating panes, files or waiters; a newer client executable cannot enable an older daemon. Public native discovery, generated capability metadata and MCP must disclose the same decisions and any intentional fallback.

One shared initial PR must include native APIs, examples and acceptance for all these facades:

  • Kotlin: suspend runProgram, spawnProgram and an owning withProgram scope, with sealed outcomes and bounded Flow observation. Parent cancellation awaits cleanup through the existing bounded I/O policy; cancelling a collector closes only its subscription.
  • Clojure: run-program!, start-program!, wait-program!, terminate-program! and with-program, checked option maps, immutable namespaced result data and one opaque owner. Route owning task cancellation to core termination; keep blocking work outside core.async go blocks. Namespace loading must stay free of processes and executors.
  • Scala direct: scoped opaque Program handles, native options/outcome ADTs and Using or try/finally that preserve primary and close failures.
  • Scala Cats/FS2: Resource acquisition and release through the bounded execution policy, cancellation-safe awaited cleanup, and bounded byte/gap streams whose consumer release leaves the Program owner alive.
  • Scala Ox: a supervised owning scope and Flow observation with explicit subscription cleanup and interruption behavior. Qualify its release behavior independently from Cats.

The initial PR should state its delivered subset. Continue with byte-bounded streaming and explicit gaps, incremental decoding/final flush, readiness predicates, controller-crash leases/recovery and structured MCP start/input/read/wait/terminate tools. Keep rendered screen state separate from byte output. All facades reuse the Java gates and protocol implementation; they need native usability proof rather than separate engines.

Acceptance needs complete programs and critical tests in every listed facade: zero-argument/Unicode argv, arbitrary output bytes, fast exit, final-burst output, interactive input, slow readers, early stream release, owning cancellation during acquisition/run/cleanup, paired failures, external respawn, daemon replacement and borrowed-resource survival. Prove old-daemon/new-client refusal before effects, release/patch/RC boundaries, generated forwarder/metadata drift and deliberate disabled-gate controls. Test current supported JDK/package consumers; experimental variants absent from the registered build must retain an explicit unqualified status.

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