feat(plugins): let plugin services provide session environments by BIackFIame · Pull Request #85 · howdeploy/CanvasTTY

BIackFIame · 2026-09-27T18:24:41Z

Goal

Let plugins decide where a card runs (a git worktree, a container, a remote host) while CanvasTTY keeps owning the card, the PTY, the record and the restore order.

What core gains

services[].environments (environment:provide): up to 8 kinds per plugin. Kinds are unique within the plugin and may be split over services, one per module. Each kind can have fields and appliesTo, terminals included.
The launcher's Where lists the kinds. While a kind applies to terminals, Open terminal uses the same launcher.

EnvironmentRegistry sends these host-only requests:

Request	When	Timeout	Answer
`prepare`	once	15 s	opaque ref of at most 4 KB, label, optional cwd
`wrap`	every start	5 s	the command to run
`resume`	restore	10 s	ok, or stopped
`release`	close	10 s
`describe`	badge	3 s	badge text

Restore resumes environments first, then brings parents back before children. Close asks "Keep environment data?" once.
Launch contributors and policies now receive the card's environment, and yolo-guard refuses YOLO only outside one.

Security posture

Wrap output is validated:
- the program is an absolute executable or a bare name resolved on PATH, never a shell string;
- the launch-contributor env rules apply;
- secretEnv is masked.
The environment never sees CANVASTTY_* or secret values.
A missing, disabled or untrusted plugin, a stopped answer or a timeout brings the card back stopped with the reason. It never runs locally.

Docs and examples

Docs (en/ru/zh), the schema, plugin-api.d.ts, the architecture doc, and examples/plugins/env-worktree: one git worktree per card, the branch as the badge, and release removes the worktree unless kept.

Tests and checks

tests/session-environments.test.mjs, including a real git worktree run through the supervisor and kinds split over services. Suite 940/940 and typecheck with a fake HOME.
Live, with hidden windows:
- terminal and agent cards ran in their worktrees, and after a relaunch they came back in the same worktrees;
- Remove and Keep on close did what they say.
With the environments plugin:
- an ssh-host card ran on a real server;
- Docker and remote-Podman cards had no network and dropped capabilities, and after a relaunch they resumed into the same containers;
- Collect brought the changes back as a local branch.

Dependency

Stacked on #80 and #84. Review only the top commit.

Used by canvastty-plugin-environments (worktree, ssh-host, container, remote-container) and canvastty-plugin-assistant (its policy reads environment).

Builds on howdeploy#80 (teo-nex, "restore each Codex card to its own conversation"): its capture of the conversation id from authenticated lifecycle hooks, the validated id saved per card, `codex resume <id>`, the resume picker when no id is known and a plain restart forgetting the id are kept as they are. This extends the same exact resume to Claude Code (`claude --resume <id>`) and OpenCode (`opencode --session <id>`); the field is renamed from codexThreadId to threadId for that, with one per-provider check (canonical UUID for Codex and Claude, `ses_` id for OpenCode) shared by the hook client, the gateway, the store and the launch, and v1 records' codexThreadId still read. Settings → General now offers Don't save / Reopen windows / Continue conversations (settings v21; the old opt-in boolean migrates true→continue, false→off). Session records move to v2 (v1 stays readable): last state at quit or exit, the thread id, a per-card restore flag, and two validated opaque plugin slots (launch options and an environment ref, 4 KB each). No scrollback, prompts or secrets are saved. Restore puts parents before children, resumes a recorded conversation by id, and without one uses a "latest in this folder" flag only when that CLI has one card in the folder (otherwise it starts fresh with a note on the card; Codex opens its picker). Finished cards come back stopped with Restart / Continue (Continue resumes the card's own conversation), and a card whose environment is unavailable is held stopped with its reason instead of running locally. Cards get an options menu with "Don't restore this card". For plugins: the v2 record's two opaque slots are where later extension points keep per-card state across restarts. A launch contributor's chosen options are saved in `options[pluginId]` and an environment's ref in `environment`, both validated and capped at 4 KB, so a restored card can be prepared or placed again (or held stopped with a reason) without the core knowing what the values mean.

Manifest apiVersion 2 adds `services`: bundled single-file JavaScript entries (integrity-declared like hook entries in modular plugins). A new PluginServiceSupervisor runs each service of an enabled plugin as its own process (process.execPath + ELECTRON_RUN_AS_NODE, cwd = plugin folder, allow-listed environment without keys, NODE_OPTIONS or CANVASTTY_*), speaks newline-delimited JSON-RPC 2.0 over stdio (1 MB messages, 15 s request timeouts, 64 pending), restarts with backoff (at most 5 in 10 minutes), stops politely then with SIGTERM/SIGKILL on disable, uninstall, update, module change, revoke and quit, and keeps a bounded per-plugin log. Services run only after a separate per-plugin "Extension native code" confirmation in Settings -> Agents. Install never grants it; it pins each entry's SHA-256 (checked before every start) and is revoked by update, module change, disable, or a changed entry file. How a plugin uses it: its sandboxed surfaces call their own plugin's services with host.service.request(serviceId, method, params) and receive host.service.onEvent; the plugin id is bound by the frame host or the identity-checked plugin window. A service may call back `log`, own-plugin `storage.*` (storage permission), `event`, and `secrets.get` (secrets permission) for its own plugin's secret, for example an API key of a model it calls; anything else is -32601. This is the base the following extension points (launch, environments, decisions, tools, sessions, cards) add host requests to. Docs (en/ru/zh), schema, plugin-api.d.ts, example examples/plugins/service-echo (a canvas app that calls its service, and a token the page saves and the service reads), and tests/plugin-services.test.mjs, tests/plugin-policy-budget-secrets.test.mjs.

A trusted plugin service can now declare a `launch` block (permission launch:contribute, one service per plugin): up to 8 boolean, select or text fields, optionally limited to some agents. The agent launcher shows them under Advanced; the person turns a plugin on for one launch, and the checked values (at most 4 KB per plugin) are saved in the session record's plugin options slot and reused on restart and restore. Before such a card is spawned, LaunchPipeline sends each chosen plugin's service `canvastty.launch.prepare` (a host-only method surfaces cannot send) and merges the answers in plugin-id order: env, secretEnv (names of the plugin's own secrets, resolved in main, never shown to the service or any UI, masked as <redacted:secret> in observe/result, the control CLI's screen/result and failure details), args (appended before the resume selection) and per-run files ({launchFiles}, removed on exit). A refusal, a 5 s timeout, an error, an invalid answer, a missing secret, two plugins setting one name, a reserved or core-set variable, or an approval or conversation argument (coreOwnedLaunchArgument) refuses the launch with the reason on the card; it is never started without the contribution. Restore holds a card whose plugin is unavailable stopped with its reason and keeps its record. Launches without options or policies stay synchronous and unchanged. What an account or policy plugin also needs: - launch.policy: a contributor with `policy: true` is also asked before every agent launch where the person did not choose it (`chosen: false`, empty options). That answer may only refuse; a contribution, a timeout or an error refuses too, so a policy never lets a launch through by failing. Policy-only contributors are not shown in the launcher. - A select may declare `optionsFrom: "service"`: the launcher asks `canvastty.launch.options` (3 s) and lists up to 64 more choices (the plugin's accounts, say) after the declared ones; such a value is any short text the service re-checks when it prepares. - spawn_agent takes `launchOptions` ({pluginId: {field: value}}), checked exactly like the launcher's, so an orchestrator can start a subagent with the account a plugin tool picked. - Claude Code applies only its last inline --settings, so a plugin's inline --settings is merged into CanvasTTY's own (hooks kept); one that sets permissions, hooks, sandbox, defaultMode or apiKeyHelper is refused. Docs (en/ru/zh), schema, plugin-api.d.ts, examples examples/plugins/launch-env (options, a service-filled Profile) and examples/plugins/yolo-guard (a policy that refuses YOLO launches), and tests/launch-contributors.test.mjs, tests/plugin-launch-choices.test.mjs, tests/plugin-policy-budget-secrets.test.mjs.

A trusted plugin service can now list `environments` kinds (permission environment:provide, up to 8 kinds per plugin with optional launcher fields and appliesTo, "terminal" included). Kinds are unique within the plugin and may be split over its services (one per module); each is answered by the service that lists it. The launcher's Advanced section shows "Where" (default "This computer"); while a kind applies to terminals, Open terminal opens the same launcher (folder and Where) instead of opening at once. EnvironmentRegistry sends host-only requests: prepare (once, 15 s: opaque ref <= 4 KB, badge label, optional cwd that becomes the card's folder), wrap (before every start, 5 s), resume (10 s), release (10 s) and describe (3 s, badge text). TerminalManager still spawns the PTY: the launch is planned (planSpawn), wrapped, then spawned. Wrap output is validated: an absolute executable or a bare name resolved on PATH, never a shell string; args array without NUL; env/secretEnv under the launch contributor rules (reserved names and names this launch already sets are refused), secretEnv resolved from the plugin's own secrets and masked. The environment sees the launch's own variables without CANVASTTY_* names or secret values (secretEnvNames lists the latter). The ref is saved in the v2 record. Restore resumes every saved environment first, then plans parents before children; a missing, disabled or untrusted plugin, a `stopped` answer, an error or a timeout brings the card back stopped with the reason, keeps its record, and never runs it locally. Closing a card asks once "Keep environment data?" and releases with the answer; quitting releases nothing unless saving is off (keepData: true, reason "quit"); a card closed while preparing releases the new environment unkept. Launch contributors and policies now receive the card's `environment` ({ pluginId, kind } or null) in canvastty.launch.prepare, so a policy can allow risky launches only inside an isolated place; the yolo-guard example now refuses YOLO only outside an environment. How a plugin uses it: a worktree, container or remote-host plugin declares its kinds, answers prepare/wrap/resume/release/describe, and keeps whatever it needs in the opaque ref. Example examples/plugins/env-worktree: git worktree add in the plugin's data folder, wrap sets the folder, resume checks it, describe shows the branch, release removes the worktree and the branch it created unless kept. Docs (en/ru/zh), schema, plugin-api.d.ts, architecture, changelogs, and tests/session-environments.test.mjs.

howdeploy · 2026-09-27T19:45:19Z

Consolidated into #88 at the maintainer's request. Its branch already includes this implementation (the #81 authentication fix is incorporated through #87). Please continue all follow-up fixes and discussion in #88. Detailed changes-requested review: #88 (review) . Closing this superseded PR preserves its branch, commits and authorship; no code is being merged into main.

fix(terminal): restore each Codex card to its own conversation

20422d5

BIackFIame added 4 commits September 27, 2026 19:39

howdeploy mentioned this pull request Sep 27, 2026

feat(core): consolidate session restore, plugin extensions and agent safety #88

Merged

BIackFIame force-pushed the core/4-environments branch from 331a590 to 495cf82 Compare September 27, 2026 19:44

howdeploy closed this Sep 27, 2026

Navigation Menu

feat(plugins): let plugin services provide session environments - #85

feat(plugins): let plugin services provide session environments#85
BIackFIame wants to merge 5 commits into
howdeploy:mainfrom
BIackFIame:core/4-environments

BIackFIame commented Sep 27, 2026

Uh oh!

howdeploy commented Sep 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

BIackFIame commented Sep 27, 2026

Goal

What core gains

Security posture

Docs and examples

Tests and checks

Dependency

Uh oh!

howdeploy commented Sep 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants