Model ephemeral interactive tool sessions without declaring durable agent services

[schickling-assistant]

Problem

An agent workspace can need a short-lived interactive terminal for tools such as lazygit, git add -p, a shell, or tail -f. Fractal should be able to open that terminal beside the agent session.

These tools need a pseudo-terminal. They do not need a durable Agent Spec identity, permanent PTY registry entry, supervisor restart, adoption, or reconciliation after they exit.

The current st2 model has declared pty service tasks and terminal-free exec tasks. A declared missing service is reconciled back into existence. That is the wrong lifecycle for an on-demand tool owned by one UI or agent session.

Boundary to decide

Decide how Agent Spec and st2 describe or authorize an ephemeral interactive tool without making its runtime instance durable.

The likely split is:

• Agent Spec can declare available tool intent or a launch capability, if declaration is needed.
• A runtime request creates one ephemeral PTY instance.
• The instance is attributed to the stable agent, host, workspace, and purpose.
• The instance is not a new agent and does not receive an inbox or durable actor identity.
• st2 does not reconcile, restart, adopt, or relaunch it after exit.
• The owning client can terminate it. Owner loss can terminate it.
• Fractal observes it as a local tool terminal, not as another declared seat.

Do not add lifecycle "once" to declared tasks without resolving the ownership problem. A reconciler cannot infer whether an absent one-shot task has never run or has already completed without adding durable run state.

Questions

• Does this belong in Agent Spec, or should Agent Spec expose only workspace/tool metadata while a separate st2 runtime API owns instances?
• Is the owner the agent session, the Fractal process, or an explicit lease?
• Should a UI crash terminate the tool immediately, or should a short reconnect grace exist?
• Which launch inputs are declared and which are request-time data?
• How is authority to launch an arbitrary command bounded?
• How should st2 tasks distinguish declared service tasks from ephemeral tool instances?
• Should completed tools remain observable for a bounded diagnostic period without becoming durable resources?

Required semantics

• A short-lived interactive command can run in the selected agent workspace.
• The command receives a real PTY, size changes, input, and terminal modes.
• Normal exit is terminal and never triggers automatic relaunch.
• Closing the owning surface terminates the owned process after a defined grace policy.
• The tool has an instance ID and stable parent-agent attribution, but no durable agent identity.
• The tool cannot route Agent Spec messages or impersonate the parent agent.
• Fractal can list and close its own tool panes without editing the Agent Spec catalog.
• The design composes with the pty-rust embedded spawn_pty and attach_pty API.
• Cross-layer tests cover lazygit, a long-running log tail, normal exit, owner close, resize, and client crash.

Related

• Define Node compatibility contract and export an embeddable PTY client crate pty-rust#1
• Export one embedded terminal API for attached and spawned PTYs pty-rust#3
• Specify terminal DATA byte semantics and add Node/Rust conformance fixtures pty#160
• schickling/dotfiles#1374
• schickling/dotfiles#1375