feat(web): add interactive sidebar terminals
This commit is contained in:
1 parent
6d99a8a53a
commit
e15a9b1bec
132 files changed
+5985
-101
No files matched your search
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/subsystems/subprocess.md
|
||||
subprocess.md: 782623760e70648a108ac51252b610e27bffbe45
|
||||
subprocess.zh.md: 7b8e590a843899b5f00a309a913e1dcb152c5c1b
|
||||
subprocess.md: 71040fb28b8cf919f72f8c727a7d0c7add30dada
|
||||
subprocess.zh.md: dda7356108305ac7e2f3182608b248ce6fa781de
|
||||
@@ -240,7 +240,9 @@ interface SubprocessOutcome {
|
||||
|
||||
`spawnTerminal(spec)` is the non-pipe process primitive. The provider allocates the controlling terminal and owns UTF-8 text transport, foreground-process-group inspection and signalling, and one awaited TERM-to-KILL operation that reaches quiescence for every session member the provider can still observe; providers document substrate-specific observability limits. The PTY backend remains responsible for prompt detection, readiness inference, scrollback, sandbox policy, and persistent-session ownership; ordinary `spawn()` cannot reconstruct controlling-terminal semantics.
|
||||
|
||||
The terminal spec fully specifies argv, cwd, environment overrides, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `inspectForeground`, `signalForeground`, and awaited `terminate`; the exact public shapes are generated into the [`ctx.subprocess` service catalog](#ctxsubprocess--subprocessruntime-abstract-seam).
|
||||
The terminal spec fully specifies argv, cwd, environment overrides, terminal type, dimensions, cleanup grace, and optional allocation cancellation. Its handle exposes `pid`, ordered output, `done`, `write`, `resize`, `inspectForeground`, `signalForeground`, and awaited `terminate`; [`SubprocessTerminalSpawnSpec` and `SubprocessTerminalHandle`](../../packages/subprocess/subprocess/src/types.ts) define these fields and operations. `resize(cols, rows)` updates the live PTY dimensions and rejects after process exit.
|
||||
|
||||
`terminalEnvironment(signal?)` returns `SubprocessTerminalEnvironment`: the execution environment platform (`posix` or `windows`) and optional `defaultShell`. These facts come from the provider rather than the Web server or browser. `resolveExecutable` verifies shell candidates; `SubprocessExecutableNotFoundError` identifies a missing executable, while provider and transport failures remain errors.
|
||||
|
||||
## Service behavior
|
||||
|
||||
@@ -300,6 +302,13 @@ Implementations must honor these semantics:
|
||||
*/
|
||||
abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>
|
||||
|
||||
/**
|
||||
* Inspect shell-selection facts in the provider's execution environment.
|
||||
* @param signal - cancellation of remote environment inspection.
|
||||
* @returns platform and preferred shell; executable lookup and allocation remain separate operations.
|
||||
*/
|
||||
abstract terminalEnvironment(signal?: AbortSignal): Promise<SubprocessTerminalEnvironment>
|
||||
|
||||
/**
|
||||
* Start one managed child process from a fully-specified spec; this seam
|
||||
* applies no defaults.
|
||||
|
||||
@@ -240,7 +240,9 @@ interface SubprocessOutcome {
|
||||
|
||||
`spawnTerminal(spec)` 是非管道进程原语。提供方分配控制终端,并负责 UTF-8 文本传输、前台进程组检查与信号发送,以及一项须等待的 TERM→KILL 操作;该操作会使提供方仍可观察到的每个会话成员完全停稳,提供方则会记录执行基底特有的可观察性限制。PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略和持久会话所有权;普通 `spawn()` 无法重建控制终端语义。
|
||||
|
||||
终端 spec 完全指定 argv、cwd、环境覆盖、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`;确切的公共形状生成到 [`ctx.subprocess` 服务目录](#ctxsubprocess--subprocessruntime-abstract-seam)中。
|
||||
终端 spec 完全指定 argv、cwd、环境覆盖、终端类型、尺寸、清理宽限期与可选的分配取消。其句柄公开 `pid`、有序输出、`done`、`write`、`resize`、`inspectForeground`、`signalForeground` 和须等待的 `terminate`;[`SubprocessTerminalSpawnSpec` 与 `SubprocessTerminalHandle`](../../packages/subprocess/subprocess/src/types.ts) 定义这些字段和操作。`resize(cols, rows)` 更新正在运行的 PTY 尺寸,进程退出后拒绝调用。
|
||||
|
||||
`terminalEnvironment(signal?)` 返回 `SubprocessTerminalEnvironment`:执行环境平台(`posix` 或 `windows`)与可选的 `defaultShell`。这些事实来自提供方,而非 Web 服务器或浏览器。`resolveExecutable` 验证候选 shell;`SubprocessExecutableNotFoundError` 表示可执行文件不存在,提供方与传输故障仍作为错误报告。
|
||||
|
||||
## 服务行为
|
||||
|
||||
@@ -300,6 +302,13 @@ Implementations must honor these semantics:
|
||||
*/
|
||||
abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>
|
||||
|
||||
/**
|
||||
* Inspect shell-selection facts in the provider's execution environment.
|
||||
* @param signal - cancellation of remote environment inspection.
|
||||
* @returns platform and preferred shell; executable lookup and allocation remain separate operations.
|
||||
*/
|
||||
abstract terminalEnvironment(signal?: AbortSignal): Promise<SubprocessTerminalEnvironment>
|
||||
|
||||
/**
|
||||
* Start one managed child process from a fully-specified spec; this seam
|
||||
* applies no defaults.
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/subsystems/workspace.md
|
||||
workspace.md: a7c4b8843f0a0b2d2fb251157f7928a40df1e405
|
||||
workspace.zh.md: 3474cbf147848b04a4ec51147983a343bcc1e91d
|
||||
workspace.md: f37af82d7f8cec018d24a22534bc0b7342425d34
|
||||
workspace.zh.md: 02dd976abde63992b65f09ea4852cedf0d0b4b36
|
||||
@@ -183,6 +183,89 @@ Host service backing the generated `ctx.remote.directoryPicker` namespace. The s
|
||||
|
||||
Source: [`packages/api/workspace-controller/src/directory-picker.ts`](../../packages/api/workspace-controller/src/directory-picker.ts)
|
||||
|
||||
<a id="ctxterminalcontroller--terminalcontroller"></a>
|
||||
|
||||
### `ctx.terminalController` — `TerminalController`
|
||||
|
||||
Typed Remote control of transient Session-owned terminal processes.
|
||||
|
||||
```ts cordis-catalog
|
||||
/**
|
||||
* Read the Session working directory and terminal limits without resolving a shell.
|
||||
* @param agent - Session owner supplied by the Gateway.
|
||||
* @param signal - request cancellation.
|
||||
* @returns the Session workspace directory and terminal limits.
|
||||
*/
|
||||
@Remote environment(agent: Agent, signal: AbortSignal): TerminalEnvironment
|
||||
|
||||
/**
|
||||
* List running and exited terminals available for reattachment.
|
||||
* @param agent - Session owner supplied by the Gateway.
|
||||
* @returns terminals retained for this Host lifetime.
|
||||
*/
|
||||
@Remote list(agent: Agent): WebTerminalInfo[]
|
||||
|
||||
/**
|
||||
* Allocate an interactive shell once for a caller-generated identity.
|
||||
* @param agent - Session owner supplied by the Gateway.
|
||||
* @param request - initial dimensions and idempotency identity.
|
||||
* @param signal - allocation cancellation; committed terminals survive disconnection.
|
||||
* @returns the existing or newly committed terminal.
|
||||
*/
|
||||
@Remote async create(agent: Agent, request: TerminalCreateRequest, signal: AbortSignal): Promise<WebTerminalInfo>
|
||||
|
||||
/**
|
||||
* Attach to a terminal without binding its process lifetime to the transport.
|
||||
* @param agent - Session owner supplied by the Gateway.
|
||||
* @param id - terminal identity.
|
||||
* @param attachmentId - new exclusive input attachment.
|
||||
* @param signal - physical stream cancellation.
|
||||
* @returns screen recovery followed by output and metadata changes.
|
||||
*/
|
||||
@Remote({ mode: 'stream' }) follow(agent: Agent, id: WebTerminalId, attachmentId: TerminalAttachmentId, signal: AbortSignal): AsyncIterable<TerminalFrame>
|
||||
|
||||
/**
|
||||
* Deliver raw input, including Tab completion and control characters.
|
||||
* @param agent - Session owner supplied by the Gateway.
|
||||
* @param id - terminal identity.
|
||||
* @param attachmentId - current writable attachment.
|
||||
* @param data - input bytes represented as UTF-8 text.
|
||||
* @returns after provider input acceptance.
|
||||
*/
|
||||
@Remote async write(agent: Agent, id: WebTerminalId, attachmentId: TerminalAttachmentId, data: string): Promise<void>
|
||||
|
||||
/**
|
||||
* Update the dimensions of the PTY and recovery screen.
|
||||
* @param agent - Session owner supplied by the Gateway.
|
||||
* @param id - terminal identity.
|
||||
* @param attachmentId - current writable attachment.
|
||||
* @param cols - column count.
|
||||
* @param rows - row count.
|
||||
* @returns after the resize completes.
|
||||
*/
|
||||
@Remote async resize(agent: Agent, id: WebTerminalId, attachmentId: TerminalAttachmentId, cols: number, rows: number): Promise<void>
|
||||
|
||||
/**
|
||||
* Rename a terminal without changing its shell.
|
||||
* @param agent - Session owner supplied by the Gateway.
|
||||
* @param id - terminal identity.
|
||||
* @param title - nonempty display title, at most 120 characters.
|
||||
*/
|
||||
@Remote rename(agent: Agent, id: WebTerminalId, title: string): void
|
||||
|
||||
/**
|
||||
* Close an identity to future creation and kill its process range; repeated closes succeed.
|
||||
* @param agent - Session owner supplied by the Gateway.
|
||||
* @param id - terminal identity.
|
||||
* @returns after provider cleanup succeeds. A failure retains the terminal for retry.
|
||||
*/
|
||||
@Remote async close(agent: Agent, id: WebTerminalId): Promise<void>
|
||||
```
|
||||
|
||||
Types: [Agent](core.md)
|
||||
|
||||
Source: [`packages/api/terminal-controller/src/index.ts`](../../packages/api/terminal-controller/src/index.ts)
|
||||
|
||||
<a id="ctxworkspacecontroller--workspacecontroller"></a>
|
||||
|
||||
### `ctx.workspaceController` — `WorkspaceController`
|
||||
|
||||
@@ -183,6 +183,89 @@ Host service backing the generated `ctx.remote.directoryPicker` namespace. The s
|
||||
|
||||
Source: [`packages/api/workspace-controller/src/directory-picker.ts`](../../packages/api/workspace-controller/src/directory-picker.ts)
|
||||
|
||||
<a id="ctxterminalcontroller--terminalcontroller"></a>
|
||||
|
||||
### `ctx.terminalController` — `TerminalController`
|
||||
|
||||
Typed Remote control of transient Session-owned terminal processes.
|
||||
|
||||
```ts cordis-catalog
|
||||
/**
|
||||
* Read the Session working directory and terminal limits without resolving a shell.
|
||||
* @param agent - Session owner supplied by the Gateway.
|
||||
* @param signal - request cancellation.
|
||||
* @returns the Session workspace directory and terminal limits.
|
||||
*/
|
||||
@Remote environment(agent: Agent, signal: AbortSignal): TerminalEnvironment
|
||||
|
||||
/**
|
||||
* List running and exited terminals available for reattachment.
|
||||
* @param agent - Session owner supplied by the Gateway.
|
||||
* @returns terminals retained for this Host lifetime.
|
||||
*/
|
||||
@Remote list(agent: Agent): WebTerminalInfo[]
|
||||
|
||||
/**
|
||||
* Allocate an interactive shell once for a caller-generated identity.
|
||||
* @param agent - Session owner supplied by the Gateway.
|
||||
* @param request - initial dimensions and idempotency identity.
|
||||
* @param signal - allocation cancellation; committed terminals survive disconnection.
|
||||
* @returns the existing or newly committed terminal.
|
||||
*/
|
||||
@Remote async create(agent: Agent, request: TerminalCreateRequest, signal: AbortSignal): Promise<WebTerminalInfo>
|
||||
|
||||
/**
|
||||
* Attach to a terminal without binding its process lifetime to the transport.
|
||||
* @param agent - Session owner supplied by the Gateway.
|
||||
* @param id - terminal identity.
|
||||
* @param attachmentId - new exclusive input attachment.
|
||||
* @param signal - physical stream cancellation.
|
||||
* @returns screen recovery followed by output and metadata changes.
|
||||
*/
|
||||
@Remote({ mode: 'stream' }) follow(agent: Agent, id: WebTerminalId, attachmentId: TerminalAttachmentId, signal: AbortSignal): AsyncIterable<TerminalFrame>
|
||||
|
||||
/**
|
||||
* Deliver raw input, including Tab completion and control characters.
|
||||
* @param agent - Session owner supplied by the Gateway.
|
||||
* @param id - terminal identity.
|
||||
* @param attachmentId - current writable attachment.
|
||||
* @param data - input bytes represented as UTF-8 text.
|
||||
* @returns after provider input acceptance.
|
||||
*/
|
||||
@Remote async write(agent: Agent, id: WebTerminalId, attachmentId: TerminalAttachmentId, data: string): Promise<void>
|
||||
|
||||
/**
|
||||
* Update the dimensions of the PTY and recovery screen.
|
||||
* @param agent - Session owner supplied by the Gateway.
|
||||
* @param id - terminal identity.
|
||||
* @param attachmentId - current writable attachment.
|
||||
* @param cols - column count.
|
||||
* @param rows - row count.
|
||||
* @returns after the resize completes.
|
||||
*/
|
||||
@Remote async resize(agent: Agent, id: WebTerminalId, attachmentId: TerminalAttachmentId, cols: number, rows: number): Promise<void>
|
||||
|
||||
/**
|
||||
* Rename a terminal without changing its shell.
|
||||
* @param agent - Session owner supplied by the Gateway.
|
||||
* @param id - terminal identity.
|
||||
* @param title - nonempty display title, at most 120 characters.
|
||||
*/
|
||||
@Remote rename(agent: Agent, id: WebTerminalId, title: string): void
|
||||
|
||||
/**
|
||||
* Close an identity to future creation and kill its process range; repeated closes succeed.
|
||||
* @param agent - Session owner supplied by the Gateway.
|
||||
* @param id - terminal identity.
|
||||
* @returns after provider cleanup succeeds. A failure retains the terminal for retry.
|
||||
*/
|
||||
@Remote async close(agent: Agent, id: WebTerminalId): Promise<void>
|
||||
```
|
||||
|
||||
Types: [Agent](core.zh.md)
|
||||
|
||||
Source: [`packages/api/terminal-controller/src/index.ts`](../../packages/api/terminal-controller/src/index.ts)
|
||||
|
||||
<a id="ctxworkspacecontroller--workspacecontroller"></a>
|
||||
|
||||
### `ctx.workspaceController` — `WorkspaceController`
|
||||
|
||||
Reference in new issue
Block a user