@xingular/harness 1.0.0 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +46 -5
- package/README.md +75 -21
- package/dist/cli.js +17421 -8711
- package/dist/sdk/accounts/accounts.d.ts +27 -3
- package/dist/sdk/accounts/accounts.js +78 -24
- package/dist/sdk/accounts/secrets.d.ts +12 -0
- package/dist/sdk/accounts/secrets.js +114 -7
- package/dist/sdk/accounts/store.d.ts +26 -1
- package/dist/sdk/accounts/store.js +1 -1
- package/dist/sdk/agents/builtin.d.ts +2 -0
- package/dist/sdk/agents/builtin.js +48 -0
- package/dist/sdk/agents/narrow.d.ts +13 -0
- package/dist/sdk/agents/narrow.js +29 -0
- package/dist/sdk/agents/planResearch.d.ts +5 -0
- package/dist/sdk/agents/planResearch.js +19 -0
- package/dist/sdk/agents/profiles.d.ts +81 -0
- package/dist/sdk/agents/profiles.js +226 -0
- package/dist/sdk/annotations/bridge.d.ts +42 -0
- package/dist/sdk/annotations/bridge.js +264 -0
- package/dist/sdk/annotations/capture.d.ts +116 -0
- package/dist/sdk/annotations/capture.js +308 -0
- package/dist/sdk/annotations/delivery.d.ts +72 -0
- package/dist/sdk/annotations/delivery.js +130 -0
- package/dist/sdk/annotations/inspect.d.ts +10 -0
- package/dist/sdk/annotations/inspect.js +33 -0
- package/dist/sdk/annotations/isolated.d.ts +6 -0
- package/dist/sdk/annotations/isolated.js +51 -0
- package/dist/sdk/annotations/pageScript.d.ts +28 -0
- package/dist/sdk/annotations/pageScript.js +871 -0
- package/dist/sdk/annotations/part.d.ts +10 -0
- package/dist/sdk/annotations/part.js +155 -0
- package/dist/sdk/annotations/queue.d.ts +4 -0
- package/dist/sdk/annotations/queue.js +40 -0
- package/dist/sdk/annotations/serverMethods.d.ts +3 -0
- package/dist/sdk/annotations/serverMethods.js +62 -0
- package/dist/sdk/annotations/store.d.ts +167 -0
- package/dist/sdk/annotations/store.js +394 -0
- package/dist/sdk/browser/backend.d.ts +16 -0
- package/dist/sdk/browser/backend.js +17 -0
- package/dist/sdk/browser/contracts.d.ts +19 -0
- package/dist/sdk/browser/contracts.js +116 -0
- package/dist/sdk/browser/index.d.ts +14 -3
- package/dist/sdk/browser/index.js +11 -4
- package/dist/sdk/browser/serverMethods.d.ts +3 -0
- package/dist/sdk/browser/serverMethods.js +7 -0
- package/dist/sdk/browser/session.d.ts +1 -0
- package/dist/sdk/browser/session.js +45 -9
- package/dist/sdk/browser/tools.d.ts +1 -4
- package/dist/sdk/browser/tools.js +14 -91
- package/dist/sdk/cli.js +24 -15
- package/dist/sdk/commands/list.d.ts +3 -0
- package/dist/sdk/commands/list.js +75 -0
- package/dist/sdk/commands/registry.d.ts +250 -0
- package/dist/sdk/commands/registry.js +47 -0
- package/dist/sdk/commands/routes.d.ts +16 -0
- package/dist/sdk/commands/routes.js +33 -0
- package/dist/sdk/core/bus.js +1 -1
- package/dist/sdk/core/commandBudget.d.ts +23 -0
- package/dist/sdk/core/commandBudget.js +57 -0
- package/dist/sdk/core/env.d.ts +1 -1
- package/dist/sdk/core/env.js +1 -1
- package/dist/sdk/core/index.js +17 -1
- package/dist/sdk/core/interactiveProfile.d.ts +46 -0
- package/dist/sdk/core/interactiveProfile.js +143 -0
- package/dist/sdk/core/workspace.d.ts +13 -0
- package/dist/sdk/core/workspace.js +88 -0
- package/dist/sdk/core/workspaceBashTool.d.ts +4 -0
- package/dist/sdk/core/workspaceBashTool.js +36 -0
- package/dist/sdk/core/workspaceSandbox.d.ts +31 -0
- package/dist/sdk/core/workspaceSandbox.js +320 -0
- package/dist/sdk/core/workspaceWriteOperations.d.ts +22 -0
- package/dist/sdk/core/workspaceWriteOperations.js +206 -0
- package/dist/sdk/doctor/serverMethods.d.ts +3 -0
- package/dist/sdk/doctor/serverMethods.js +8 -0
- package/dist/sdk/doctor/types.d.ts +2 -2
- package/dist/sdk/harness.d.ts +22 -0
- package/dist/sdk/harness.js +84 -5
- package/dist/sdk/history/recall.js +8 -8
- package/dist/sdk/history/serverMethods.d.ts +3 -0
- package/dist/sdk/history/serverMethods.js +8 -0
- package/dist/sdk/hub/cli.d.ts +1 -1
- package/dist/sdk/hub/cli.js +1 -1
- package/dist/sdk/hub/schema.d.ts +1 -1
- package/dist/sdk/hub/serverMethods.d.ts +3 -0
- package/dist/sdk/hub/serverMethods.js +11 -0
- package/dist/sdk/index.d.ts +16 -1
- package/dist/sdk/index.js +10 -0
- package/dist/sdk/mcp/connections.js +14 -7
- package/dist/sdk/mcp/serverMethods.d.ts +3 -0
- package/dist/sdk/mcp/serverMethods.js +22 -0
- package/dist/sdk/pi/runtime.d.ts +2 -1
- package/dist/sdk/pi/runtime.js +2 -2
- package/dist/sdk/plugins/builtin.d.ts +1 -0
- package/dist/sdk/plugins/builtin.js +145 -33
- package/dist/sdk/plugins/builtinRegistry.d.ts +60 -0
- package/dist/sdk/plugins/builtinRegistry.js +71 -0
- package/dist/sdk/plugins/catalogue.js +2 -1
- package/dist/sdk/plugins/cli.d.ts +1 -1
- package/dist/sdk/plugins/cli.js +4 -3
- package/dist/sdk/plugins/commandPrefix.d.ts +8 -0
- package/dist/sdk/plugins/commandPrefix.js +21 -0
- package/dist/sdk/plugins/firstParty.d.ts +1 -1
- package/dist/sdk/plugins/firstParty.js +8 -2
- package/dist/sdk/plugins/inventory.js +4 -3
- package/dist/sdk/plugins/manifest.d.ts +2 -0
- package/dist/sdk/plugins/manifest.js +2 -1
- package/dist/sdk/plugins/surfaces.d.ts +5 -0
- package/dist/sdk/plugins/surfaces.js +11 -0
- package/dist/sdk/plugins/types.d.ts +15 -0
- package/dist/sdk/prompt/compile.d.ts +19 -2
- package/dist/sdk/prompt/compile.js +79 -26
- package/dist/sdk/prompt/standard.d.ts +17 -0
- package/dist/sdk/prompt/standard.js +21 -0
- package/dist/sdk/refine/cli.d.ts +1 -1
- package/dist/sdk/refine/cli.js +2 -2
- package/dist/sdk/refine/serverMethods.d.ts +3 -0
- package/dist/sdk/refine/serverMethods.js +20 -0
- package/dist/sdk/server/methods.js +27 -86
- package/dist/sdk/server/params.d.ts +4 -0
- package/dist/sdk/server/params.js +11 -0
- package/dist/sdk/server/remote.js +36 -11
- package/dist/sdk/sessions/compactionCheckpoint.d.ts +11 -0
- package/dist/sdk/sessions/compactionCheckpoint.js +79 -0
- package/dist/sdk/sessions/continuation.d.ts +3 -0
- package/dist/sdk/sessions/continuation.js +5 -1
- package/dist/sdk/sessions/contracts.d.ts +185 -0
- package/dist/sdk/sessions/contracts.js +101 -4
- package/dist/sdk/sessions/control.d.ts +72 -0
- package/dist/sdk/sessions/control.js +158 -0
- package/dist/sdk/sessions/initialBash.d.ts +7 -0
- package/dist/sdk/sessions/initialBash.js +7 -0
- package/dist/sdk/sessions/planMode.d.ts +18 -4
- package/dist/sdk/sessions/planMode.js +82 -16
- package/dist/sdk/sessions/reasoningSummaries.d.ts +2 -2
- package/dist/sdk/sessions/reasoningSummaries.js +3 -3
- package/dist/sdk/sessions/registry.d.ts +2 -1
- package/dist/sdk/sessions/registry.js +6 -3
- package/dist/sdk/sessions/runIndex.js +7 -7
- package/dist/sdk/sessions/runStore.d.ts +14 -0
- package/dist/sdk/sessions/runStore.js +38 -1
- package/dist/sdk/sessions/runner.d.ts +40 -2
- package/dist/sdk/sessions/runner.js +163 -15
- package/dist/sdk/sessions/sessions.d.ts +40 -8
- package/dist/sdk/sessions/sessions.js +279 -27
- package/dist/sdk/sessions/sideQuestionServerMethods.d.ts +3 -0
- package/dist/sdk/sessions/sideQuestionServerMethods.js +19 -0
- package/dist/sdk/sessions/sideQuestions.d.ts +66 -0
- package/dist/sdk/sessions/sideQuestions.js +290 -0
- package/dist/sdk/sessions/subagentServerMethods.d.ts +3 -0
- package/dist/sdk/sessions/subagentServerMethods.js +41 -0
- package/dist/sdk/sessions/subagentService.d.ts +22 -2
- package/dist/sdk/sessions/subagentService.js +93 -16
- package/dist/sdk/sessions/subagents.d.ts +9 -1
- package/dist/sdk/sessions/subagents.js +19 -0
- package/dist/sdk/sessions/workSlice.d.ts +103 -0
- package/dist/sdk/sessions/workSlice.js +297 -0
- package/dist/sdk/sessions/workspaceBoundary.d.ts +15 -0
- package/dist/sdk/sessions/workspaceBoundary.js +46 -0
- package/dist/sdk/terminal/browser.d.ts +62 -0
- package/dist/sdk/terminal/browser.js +41 -0
- package/dist/sdk/terminal/browserControl.d.ts +29 -0
- package/dist/sdk/terminal/browserControl.js +187 -0
- package/dist/sdk/terminal/commandHelp.d.ts +17 -0
- package/dist/sdk/terminal/commandHelp.js +20 -0
- package/dist/sdk/terminal/controller.d.ts +15 -1
- package/dist/sdk/terminal/controller.js +67 -8
- package/dist/sdk/terminal/opentui/subagentsWidget.d.ts +28 -0
- package/dist/sdk/terminal/opentui/subagentsWidget.js +52 -0
- package/dist/sdk/terminal/opentui/theme.d.ts +43 -0
- package/dist/sdk/terminal/opentui/theme.js +87 -0
- package/dist/sdk/terminal/piExtension.d.ts +6 -1
- package/dist/sdk/terminal/piExtension.js +169 -84
- package/dist/sdk/terminal/socket.d.ts +6 -3
- package/dist/sdk/terminal/socket.js +40 -9
- package/dist/sdk/terminal/standalone.d.ts +9 -0
- package/dist/sdk/terminal/standalone.js +118 -19
- package/dist/sdk/terminal/subagentMonitor.d.ts +47 -0
- package/dist/sdk/terminal/subagentMonitor.js +152 -0
- package/dist/sdk/terminal/terminals.d.ts +60 -7
- package/dist/sdk/terminal/terminals.js +598 -47
- package/dist/sdk/terminal/trajectory.js +2 -2
- package/dist/sdk/terminal/tui/annotateCommand.d.ts +3 -0
- package/dist/sdk/terminal/tui/annotateCommand.js +22 -0
- package/dist/sdk/terminal/tui/commandPages.d.ts +7 -1
- package/dist/sdk/terminal/tui/commandPages.js +57 -6
- package/dist/sdk/terminal/tui/commands.d.ts +10 -4
- package/dist/sdk/terminal/tui/commands.js +269 -65
- package/dist/sdk/terminal/tui/dialogGeometry.d.ts +2 -2
- package/dist/sdk/terminal/tui/dialogGeometry.js +4 -2
- package/dist/sdk/terminal/tui/dialogs.d.ts +6 -1
- package/dist/sdk/terminal/tui/dialogs.js +9 -2
- package/dist/sdk/terminal/tui/list.d.ts +14 -1
- package/dist/sdk/terminal/tui/list.js +96 -14
- package/dist/sdk/terminal/tui/modelPicker.js +1 -6
- package/dist/sdk/terminal/tui/page.d.ts +3 -0
- package/dist/sdk/terminal/tui/pageOverlay.js +27 -7
- package/dist/sdk/terminal/tui/pages/accountsPage.d.ts +26 -4
- package/dist/sdk/terminal/tui/pages/accountsPage.js +264 -36
- package/dist/sdk/terminal/tui/pages/agentsPage.d.ts +74 -0
- package/dist/sdk/terminal/tui/pages/agentsPage.js +190 -0
- package/dist/sdk/terminal/tui/pages/annotatePage.d.ts +94 -0
- package/dist/sdk/terminal/tui/pages/annotatePage.js +341 -0
- package/dist/sdk/terminal/tui/pages/browserPage.d.ts +87 -0
- package/dist/sdk/terminal/tui/pages/browserPage.js +738 -0
- package/dist/sdk/terminal/tui/pages/doctorPage.d.ts +2 -0
- package/dist/sdk/terminal/tui/pages/doctorPage.js +103 -15
- package/dist/sdk/terminal/tui/pages/notesPage.d.ts +75 -0
- package/dist/sdk/terminal/tui/pages/notesPage.js +201 -0
- package/dist/sdk/terminal/tui/pages/pluginsPage.d.ts +0 -5
- package/dist/sdk/terminal/tui/pages/pluginsPage.js +9 -3
- package/dist/sdk/terminal/tui/pages/settingsPage.d.ts +8 -0
- package/dist/sdk/terminal/tui/pages/settingsPage.js +16 -1
- package/dist/sdk/terminal/tui/pages/subagentsPage.d.ts +24 -0
- package/dist/sdk/terminal/tui/pages/subagentsPage.js +152 -0
- package/dist/sdk/terminal/tui/pages/trajectoryPage.d.ts +12 -5
- package/dist/sdk/terminal/tui/pages/trajectoryPage.js +156 -83
- package/dist/sdk/terminal/tui/pages/usagePage.d.ts +43 -0
- package/dist/sdk/terminal/tui/pages/usagePage.js +370 -0
- package/dist/sdk/terminal/tui/pages/worktreesPage.d.ts +72 -0
- package/dist/sdk/terminal/tui/pages/worktreesPage.js +203 -0
- package/dist/sdk/terminal/tui/piAdapter.d.ts +1 -2
- package/dist/sdk/terminal/tui/piAdapter.js +3 -5
- package/dist/sdk/terminal/tui/planMode.d.ts +1 -1
- package/dist/sdk/terminal/tui/planMode.js +1 -1
- package/dist/sdk/terminal/tui/pluginCommands.d.ts +16 -0
- package/dist/sdk/terminal/tui/pluginCommands.js +31 -0
- package/dist/sdk/terminal/tui/questions.d.ts +2 -0
- package/dist/sdk/terminal/tui/runtime.js +27 -5
- package/dist/sdk/terminal/tui/sessionPicker.d.ts +40 -0
- package/dist/sdk/terminal/tui/sessionPicker.js +141 -0
- package/dist/sdk/terminal/tui/settingsModel.d.ts +2 -0
- package/dist/sdk/terminal/tui/settingsModel.js +32 -2
- package/dist/sdk/terminal/tui/sideQuestion.d.ts +26 -26
- package/dist/sdk/terminal/tui/sideQuestion.js +131 -98
- package/dist/sdk/terminal/tui/ui.d.ts +2 -0
- package/dist/sdk/terminal/tui/ui.js +1 -0
- package/dist/sdk/tools/askUser.js +26 -8
- package/dist/sdk/tools/checklist.js +3 -2
- package/dist/sdk/tools/checkpoint.d.ts +27 -0
- package/dist/sdk/tools/checkpoint.js +154 -0
- package/dist/sdk/tools/getCapabilities.d.ts +31 -0
- package/dist/sdk/tools/getCapabilities.js +34 -0
- package/dist/sdk/tools/harnessTools.d.ts +2 -0
- package/dist/sdk/tools/harnessTools.js +1 -1
- package/dist/sdk/tools/spawnSubagent.js +14 -4
- package/dist/sdk/usage/analytics.d.ts +20 -0
- package/dist/sdk/usage/analytics.js +151 -0
- package/dist/sdk/usage/ledger.d.ts +38 -0
- package/dist/sdk/usage/ledger.js +142 -0
- package/dist/sdk/usage/limits/adapters.d.ts +11 -0
- package/dist/sdk/usage/limits/adapters.js +349 -0
- package/dist/sdk/usage/limits/capture.d.ts +8 -0
- package/dist/sdk/usage/limits/capture.js +47 -0
- package/dist/sdk/usage/limits/http.d.ts +12 -0
- package/dist/sdk/usage/limits/http.js +51 -0
- package/dist/sdk/usage/limits/normalize.d.ts +15 -0
- package/dist/sdk/usage/limits/normalize.js +211 -0
- package/dist/sdk/usage/limits/service.d.ts +30 -0
- package/dist/sdk/usage/limits/service.js +176 -0
- package/dist/sdk/usage/limits/types.d.ts +65 -0
- package/dist/sdk/usage/limits/types.js +1 -0
- package/dist/sdk/usage/serverMethods.d.ts +3 -0
- package/dist/sdk/usage/serverMethods.js +22 -0
- package/dist/sdk/usage/service.d.ts +32 -0
- package/dist/sdk/usage/service.js +66 -0
- package/dist/sdk/usage/settings.d.ts +7 -0
- package/dist/sdk/usage/settings.js +28 -0
- package/dist/sdk/usage/types.d.ts +60 -0
- package/dist/sdk/usage/types.js +4 -0
- package/dist/sdk/web/part.d.ts +10 -0
- package/dist/sdk/web/part.js +6 -0
- package/dist/sdk/web/serverMethods.d.ts +3 -0
- package/dist/sdk/web/serverMethods.js +7 -0
- package/dist/sdk/wiki/serverMethods.d.ts +3 -0
- package/dist/sdk/wiki/serverMethods.js +26 -0
- package/dist/sdk/worktrees/cli.d.ts +11 -0
- package/dist/sdk/worktrees/cli.js +146 -0
- package/dist/sdk/worktrees/copy.d.ts +9 -0
- package/dist/sdk/worktrees/copy.js +111 -0
- package/dist/sdk/worktrees/git.d.ts +16 -0
- package/dist/sdk/worktrees/git.js +81 -0
- package/dist/sdk/worktrees/serverMethods.d.ts +3 -0
- package/dist/sdk/worktrees/serverMethods.js +30 -0
- package/dist/sdk/worktrees/service.d.ts +73 -0
- package/dist/sdk/worktrees/service.js +483 -0
- package/dist/sdk/worktrees/setup.d.ts +23 -0
- package/dist/sdk/worktrees/setup.js +65 -0
- package/dist/sdk/worktrees/types.d.ts +91 -0
- package/dist/sdk/worktrees/types.js +1 -0
- package/dist/sdk/world/cli.d.ts +2 -2
- package/dist/sdk/world/cli.js +6 -6
- package/dist/sdk/world/world.d.ts +3 -1
- package/dist/sdk/world/world.js +8 -9
- package/dist/terminal-opentui.js +16456 -5966
- package/dist/terminal-pi.js +1579 -573
- package/docs/README.md +22 -2
- package/docs/architecture/00-overview.md +28 -16
- package/docs/architecture/02-sessions-and-runs.md +184 -25
- package/docs/architecture/03-variants.md +10 -2
- package/docs/architecture/04-prompt.md +65 -7
- package/docs/architecture/06-plugins-and-capabilities.md +57 -4
- package/docs/architecture/07-tools-and-gate.md +112 -17
- package/docs/architecture/08-memory-and-history.md +4 -2
- package/docs/architecture/09-accounts-and-connectors.md +39 -1
- package/docs/architecture/10-server-protocol.md +168 -4
- package/docs/architecture/11-terminal.md +251 -8
- package/docs/architecture/12-storage.md +45 -3
- package/docs/architecture/13-world-tools.md +49 -6
- package/docs/architecture/14-surfaces-and-parity.md +136 -0
- package/docs/architecture/README.md +17 -4
- package/docs/architecture/proposals/PROP-0006-run-checklist.md +4 -2
- package/docs/architecture/proposals/PROP-0013-resource-browser.md +58 -0
- package/docs/architecture/proposals/PROP-0014-fullscreen-browser-tabs.md +58 -0
- package/docs/architecture/proposals/PROP-0015-one-capability-surface.md +88 -0
- package/docs/architecture/proposals/PROP-0016-managed-worktrees.md +156 -0
- package/docs/architecture/proposals/PROP-0017-page-annotations.md +131 -0
- package/docs/architecture/proposals/PROP-0018-annotation-queue-and-app-targets.md +179 -0
- package/docs/architecture/proposals/PROP-0019-contextual-side-questions.md +122 -0
- package/docs/architecture/proposals/PROP-0020-builtin-feature-plugins.md +105 -0
- package/docs/architecture/proposals/PROP-0021-command-namespaces-and-duplicates.md +99 -0
- package/docs/architecture/proposals/PROP-0022-plan-only-questions.md +102 -0
- package/docs/architecture/proposals/PROP-0023-xagent-cli-name.md +61 -0
- package/docs/architecture/proposals/PROP-0024-question-sketch-previews.md +130 -0
- package/docs/architecture/proposals/PROP-0025-contextual-question-wireframes.md +49 -0
- package/docs/architecture/proposals/PROP-0026-connected-sketch-display.md +94 -0
- package/docs/architecture/proposals/PROP-0027-xingular-agent-product-identity.md +60 -0
- package/docs/architecture/proposals/PROP-0028-normalize-question-wireframes.md +55 -0
- package/docs/architecture/proposals/PROP-0029-agent-profiles.md +124 -0
- package/docs/architecture/proposals/PROP-0030-subagent-title.md +86 -0
- package/docs/architecture/proposals/PROP-0031-plugin-command-owner-namespaces.md +54 -0
- package/docs/architecture/proposals/PROP-0032-planning-quality.md +196 -0
- package/docs/architecture/proposals/PROP-0033-compaction-plan-checkpoints.md +75 -0
- package/docs/architecture/proposals/PROP-0034-conversation-fast-mode.md +120 -0
- package/docs/architecture/proposals/PROP-0035-retain-subagent-status.md +47 -0
- package/docs/architecture/proposals/PROP-0036-first-class-harness-commands.md +59 -0
- package/docs/architecture/proposals/PROP-0037-workspace-write-boundary.md +63 -0
- package/docs/architecture/proposals/PROP-0038-annotate-open-shadow-roots.md +73 -0
- package/docs/architecture/proposals/PROP-0039-workspace-boundary-hardening.md +139 -0
- package/docs/architecture/proposals/PROP-0040-one-launch-path.md +87 -0
- package/docs/architecture/proposals/PROP-0041-bounded-work-slices.md +247 -0
- package/docs/architecture/proposals/PROP-0042-usage-and-provider-limits.md +127 -0
- package/docs/architecture/proposals/PROP-0043-read-only-plan-bash.md +74 -0
- package/docs/architecture/proposals/README.md +39 -0
- package/docs/decisions/ADR-0001-owned-terminal.md +1 -1
- package/docs/decisions/ADR-0009-xharness-command.md +6 -5
- package/docs/decisions/ADR-0014-public-release-baseline.md +3 -2
- package/docs/decisions/ADR-0015-resource-browser.md +28 -0
- package/docs/decisions/ADR-0016-fullscreen-browser-tabs.md +31 -0
- package/docs/decisions/ADR-0017-one-capability-surface.md +34 -0
- package/docs/decisions/ADR-0018-builtin-feature-plugins.md +35 -0
- package/docs/decisions/ADR-0019-managed-git-worktrees.md +31 -0
- package/docs/decisions/ADR-0020-page-annotations.md +37 -0
- package/docs/decisions/ADR-0021-required-command-namespaces.md +40 -0
- package/docs/decisions/ADR-0022-plan-only-question-tools.md +34 -0
- package/docs/decisions/ADR-0023-contextual-side-question-runs.md +35 -0
- package/docs/decisions/ADR-0024-xagent-command.md +40 -0
- package/docs/decisions/ADR-0025-question-choice-sketches.md +49 -0
- package/docs/decisions/ADR-0026-contextual-question-wireframes.md +58 -0
- package/docs/decisions/ADR-0027-connected-sketch-display.md +60 -0
- package/docs/decisions/ADR-0028-xingular-agent-product-identity.md +56 -0
- package/docs/decisions/ADR-0029-normalized-question-wireframe-borders.md +33 -0
- package/docs/decisions/ADR-0030-agent-profiles.md +43 -0
- package/docs/decisions/ADR-0031-plugin-command-owner-namespaces.md +37 -0
- package/docs/decisions/ADR-0032-compaction-run-checkpoints.md +33 -0
- package/docs/decisions/ADR-0033-plan-mode-research-delegation.md +47 -0
- package/docs/decisions/ADR-0034-first-class-harness-terminal-commands.md +25 -0
- package/docs/decisions/ADR-0035-one-launch-path.md +40 -0
- package/docs/decisions/ADR-0036-workspace-write-operation-boundary.md +54 -0
- package/docs/decisions/ADR-0037-usage-ledger-and-provider-limits.md +44 -0
- package/docs/decisions/ADR-0038-plan-bash-os-read-only.md +29 -0
- package/docs/doctor.md +10 -4
- package/docs/experiments/EXP-0003-performance-audit/data/session-runtime-replication.json +420 -0
- package/docs/experiments/EXP-0003-performance-audit/data/session-runtime.json +420 -0
- package/docs/experiments/EXP-0003-performance-audit/data/terminal-compact.json +376 -0
- package/docs/experiments/EXP-0003-performance-audit/data/terminal-history.json +422 -0
- package/docs/experiments/EXP-0003-performance-audit/data/terminal-question.json +95 -0
- package/docs/experiments/EXP-0003-performance-audit/data/terminal-wide.json +1036 -0
- package/docs/experiments/EXP-0003-performance-audit/plan.md +109 -0
- package/docs/experiments/EXP-0003-performance-audit/results.md +151 -0
- package/docs/features/README.md +26 -0
- package/docs/features/interfaces/README.md +1 -1
- package/docs/future-work.md +48 -0
- package/docs/handoff-2026-10-25-app-parity-and-solo-tabs.md +202 -0
- package/docs/parity.md +134 -0
- package/docs/releases/1.0.0.md +2 -2
- package/docs/releases/1.1.1.md +28 -0
- package/docs/releases/1.2.0.md +49 -0
- package/docs/releases/4.0.0.md +47 -0
- package/docs/releases/README.md +37 -27
- package/docs/study/00-index.md +8 -0
- package/docs/study/STUDY-0003-long-horizon-runs.md +210 -0
- package/docs/study/autonomous-engineering-sources.md +277 -0
- package/docs/study/autonomy-sources.md +147 -0
- package/docs/study/proactive-autonomy.md +408 -0
- package/docs/study/tui-resource-browser.md +78 -0
- package/docs/terminal-tui.md +386 -113
- package/package.json +6 -5
package/docs/terminal-tui.md
CHANGED
|
@@ -1,9 +1,14 @@
|
|
|
1
1
|
# Harness terminal frontend
|
|
2
2
|
|
|
3
|
-
Status:
|
|
3
|
+
Status: current terminal behavior, checked against `@xingular/harness` 1.2.0. Last updated: 2026-11-19.
|
|
4
4
|
Decision: [ADR-0001](decisions/ADR-0001-owned-terminal.md),
|
|
5
5
|
[ADR-0006](decisions/ADR-0006-opentui-only-terminal.md),
|
|
6
|
-
[ADR-0009](decisions/ADR-0009-xharness-command.md)
|
|
6
|
+
[ADR-0009](decisions/ADR-0009-xharness-command.md),
|
|
7
|
+
[ADR-0021](decisions/ADR-0021-required-command-namespaces.md),
|
|
8
|
+
[ADR-0024](decisions/ADR-0024-xagent-command.md),
|
|
9
|
+
[ADR-0026](decisions/ADR-0026-contextual-question-wireframes.md),
|
|
10
|
+
[ADR-0027](decisions/ADR-0027-connected-sketch-display.md),
|
|
11
|
+
[ADR-0028](decisions/ADR-0028-xingular-agent-product-identity.md).
|
|
7
12
|
|
|
8
13
|
## OpenTUI terminal
|
|
9
14
|
|
|
@@ -24,19 +29,26 @@ overrides the Bun executable.
|
|
|
24
29
|
`TerminalRuntime`, session replacement, commands, decisions, account pinning and run records. It
|
|
25
30
|
projects the runtime's snapshot and transcript into an OpenCode-inspired view, with a native
|
|
26
31
|
OpenTUI textarea for the prompt, `Ctrl+K` for the command palette, `Return` to send (or to queue behind a running reply),
|
|
27
|
-
`Cmd+Return` (or `Alt+Return`) to steer a running reply, and `Shift+Return` for a newline.
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
and
|
|
32
|
+
`Cmd+Return` (or `Alt+Return`) to steer a running reply, and `Shift+Return` for a newline. Typing `/` or `$` filters
|
|
33
|
+
matching commands or skills; `Tab` inserts the selected entry and leaves the cursor at the end of the inserted text.
|
|
34
|
+
With an empty composer, unmodified Up recalls the latest non-empty user message from the active session.
|
|
35
|
+
With a draft, unmodified Up browses older history and Down browses newer history when the caret is at
|
|
36
|
+
either absolute draft endpoint (start or end). Down past the newest entry restores the draft, cursor
|
|
37
|
+
and attachments that were present when history browsing began. At non-endpoint positions, Up on the
|
|
38
|
+
first visual line moves the cursor to the first character and Down on the last visual line moves it
|
|
39
|
+
to the final character; elsewhere, Up/Down move the caret normally. Ctrl+Up/Down remain explicit
|
|
40
|
+
history shortcuts from anywhere. History includes
|
|
41
|
+
user messages and Bash commands from the active Pi session; recalled Bash commands return to `!`
|
|
42
|
+
mode. Executed slash commands from this terminal instance are included too, across session switches.
|
|
43
|
+
`/new` and `/session` (also `/resume`) switch the saved-message and Bash history to that session.
|
|
44
|
+
Steering needs a terminal that reports Cmd with the
|
|
33
45
|
kitty keyboard protocol; elsewhere `Alt+Return` steers. In the composer, `Tab` opens up to eight matching filesystem entries for the path token at the cursor, or current-folder entries when the token is empty. The list has no heading or hint row. Up/Down select; Enter or Tab inserts the selection; Escape closes the list. Directories end in `/`, and Bash mode escapes shell-special characters. Use `/effort` or Shift+Up/Down to change effort. The command palette opens above the composer under a muted (`dim`) top rule, and has no other border. Its rows align slash commands and descriptions in two columns: the command column sizes to the widest visible name, bounded to preserve description space, and both columns wrap instead of truncating. The plan-choice rule, question block's top-only divider, and `/btw` block's top rule use the same muted color as the normal composer divider. The console has no background of its own: the renderer, root surface
|
|
34
46
|
and transcript are transparent, so the terminal's own background shows through, while panels,
|
|
35
47
|
dialogs and the scrim stay opaque. The composer has no panel background: it is bounded by a top and
|
|
36
48
|
a bottom rule, with the working status and spinner above it and a wrapping status bar below it. Its
|
|
37
49
|
fixed-width left gutter shows `❯` on the first input row and leaves continuation rows blank, including
|
|
38
50
|
explicit newlines and soft wraps; Bash mode shows `!` on the first row instead. In plan mode,
|
|
39
|
-
`plan mode` is right-aligned within the top rule, followed by exactly one divider character. The status bar shows the working folder's name
|
|
51
|
+
`plan mode` is right-aligned within the top rule, followed by exactly one divider character. The status bar shows the working folder's name and Git branch together as `<repo>:<branch>`, followed by the account, model and effort separated by spaces, and input (`↑`) and output (`↓`) token counts with each glyph adjacent to its count; `|` separates the groups. Token counts
|
|
40
52
|
below 1,000 show as whole numbers and larger counts use K/M/B suffixes. A leading `!`
|
|
41
53
|
enters Bash mode: the chevron becomes `!`, and the marker and both rules use the `bashMode` colour.
|
|
42
54
|
In plan mode, the marker and rules use the plan blue and `plan mode` is right-aligned within the
|
|
@@ -50,29 +62,51 @@ never receive an OpenTUI renderable or a second account. A theme an extension se
|
|
|
50
62
|
its own components, while the OpenTUI chrome keeps the fixed OpenCode-inspired palette. Component
|
|
51
63
|
UI is supported; an extension that draws only by writing raw ANSI through the TUI terminal is not.
|
|
52
64
|
|
|
53
|
-
|
|
54
|
-
`/
|
|
65
|
+
Most pages become centered dialogs. The page commands `/permissions`, `/log`, the `/model` and
|
|
66
|
+
`/history` pickers, and
|
|
55
67
|
the `select`, `confirm`, `input` and `editor` dialogs (such as `/effort` and the Thinking setting),
|
|
56
68
|
take 80% of the terminal, capped at 100 columns by 30 rows, on a flat panel in the console's panel
|
|
57
69
|
colour. A full-screen scrim dims the console behind the panel so the transcript stays faintly
|
|
58
70
|
visible. Centered Harness dialogs fit their rendered content, capped by the available dialog
|
|
59
71
|
height, with four columns of horizontal padding and two rows of vertical padding to account for
|
|
60
72
|
the terminal's taller-than-wide cells. They use a plain title with a muted `Esc` hint and
|
|
61
|
-
omit divider rules and footer hints. Shortcut behavior remains available.
|
|
73
|
+
omit divider rules and footer hints. Shortcut behavior remains available. Bracketed paste and the
|
|
74
|
+
clipboard-paste shortcut insert text into the active dialog input or search field, using that
|
|
75
|
+
component's input semantics; images and file attachments remain composer-only. Searchable lists share
|
|
62
76
|
the same glyph, placeholder, spacing, and muted result note, with search context included on that
|
|
63
77
|
row. A terminal too small for a 30-column by
|
|
64
78
|
12-row dialog falls back to the full-screen page chrome. A plugin's full-screen surface stays full
|
|
65
|
-
screen.
|
|
79
|
+
screen. `/settings` fills the terminal with its category tabs, search, settings list and full-screen
|
|
80
|
+
page chrome. `/accounts` also fills the terminal with Accounts/Pools tabs and search. Wide terminals
|
|
81
|
+
show selected-account details beside the list; opening an account reveals grouped actions in that
|
|
82
|
+
inspector. On compact terminals, opening an account replaces the list with a full-page detail view
|
|
83
|
+
and its grouped actions. `Enter` opens the selected account; `Esc` returns to the list. Tab and
|
|
84
|
+
Shift+Tab move focus between tabs, the list and (when open) actions; Left/Right changes a focused
|
|
85
|
+
tab and Up/Down moves the focused list or action list. Search, section and account selection survive
|
|
86
|
+
returning and resizing.
|
|
87
|
+
Account actions are grouped by Session, Account, Sign-in and Remove; pool
|
|
88
|
+
actions are grouped by Manage and Remove. Existing confirmations and account-service calls remain
|
|
89
|
+
unchanged. The Harness resource browser and all its shortcuts use a full-screen page with persistent
|
|
90
|
+
resource-section tabs.
|
|
66
91
|
|
|
67
92
|
The frontend is verified with a real isolated PTY and a loopback provider. Run
|
|
68
|
-
`python3 scripts/verify-terminal.py --
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
93
|
+
`python3 scripts/verify-terminal.py --welcome-only --sizes 40x20,80x24,120x40` to check the empty
|
|
94
|
+
welcome, product label, accent colors and `/help` transition. Run
|
|
95
|
+
`python3 scripts/verify-terminal.py --composer-only` for recognized slash-command colors in the composer
|
|
96
|
+
and a user bubble, unknown-command and argument colors, explicit-newline and soft-wrap checks of both
|
|
97
|
+
prompt gutters, and normal/plan/Bash mode exclusivity. Run it with `--sizes 40x20,80x24,120x40` for
|
|
98
|
+
compact through wide layouts. Use `--dialog-paste-only` to verify bracketed paste into a centered
|
|
99
|
+
input dialog, `--file-completion-only` for filesystem completion and insertion,
|
|
100
|
+
`--history-only` for active-session history across `/new` and `/session`, `--resume-only` for the full-screen searchable, unnumbered two-line saved-session picker, `--help-only` for `/help` replacing the welcome screen with grouped two-column output that wraps without per-command gaps, `--questions-only` for multi-select marker glyphs, recommended choices,
|
|
72
101
|
selected-row and Continue/Submit colors, `--jump-latest-only` for scroll-away badge visibility and click-to-latest (screen-level click assertions use optional `pyte`), and choice-backed “Something else” answers, or `--thinking-only` for `/thinking` visibility toggles. The full suite covers a complete turn, `read`, `bash` approval, `ask_user_question` approval and picker, plugin overlay/widget/status
|
|
73
102
|
disposal, a completed run record with usage and decision events, `/help`, `/permissions`,
|
|
74
|
-
`/settings`, `/model`, palette selection, confirm cancel, and Ctrl+D exit.
|
|
75
|
-
|
|
103
|
+
`/settings`, `/model`, palette selection, confirm cancel, and Ctrl+D exit. `--questions-only` checks
|
|
104
|
+
recommended choices, bounded literal ASCII sketch previews, focus-driven preview changes and answer
|
|
105
|
+
colors; run it with `--sizes 40x20,80x24,120x40` for compact through wide layouts. At 80 columns and
|
|
106
|
+
above it also checks wrapped notes and free-text; the narrowest run keeps the sketch and answer
|
|
107
|
+
interaction compact. The normal turn omits question tools; plan-mode flows exercise `ask_user` batches
|
|
108
|
+
and `ask_user_question` cancellation. Live-provider behavior, exact OpenCode parity and concurrent
|
|
109
|
+
session tabs are not established.
|
|
76
110
|
|
|
77
111
|
## Native subagents (2026-10-18)
|
|
78
112
|
|
|
@@ -85,8 +119,30 @@ The terminal joins outstanding children before its final reply, projects child a
|
|
|
85
119
|
with their original run IDs, and stops descendants when interrupted or disposed. Connected apps
|
|
86
120
|
need not be enabled. `TerminalPrepareInput.subagents: null` disables the capability.
|
|
87
121
|
|
|
88
|
-
|
|
89
|
-
|
|
122
|
+
The terminal also projects the latest parent's subagent descendants into rows under the status line
|
|
123
|
+
and a searchable `/subagents` page. The rows poll a private monitor route once per second
|
|
124
|
+
during a turn and make a final read at settlement. They sit one blank row below the status line, with
|
|
125
|
+
no heading, and each reads: the status mark, the agent profile name in its colour (`subagent` for a
|
|
126
|
+
copy of the parent), the title the parent gave the child (PROP-0030), and `n of m tasks` from the
|
|
127
|
+
child's own checklist. At most three show, active first, then `+N more · /subagents`. The
|
|
128
|
+
`/subagents` page uses a colored profile and normal-color title on the first line, then muted account,
|
|
129
|
+
effective model, effort and cumulative usage metadata on the second. One blank row separates each
|
|
130
|
+
two-line entry. The page also shows status, elapsed time and the latest tool name. Runtime metadata
|
|
131
|
+
stays in the private terminal projection.
|
|
132
|
+
Usage contains safe token/cache/cost/context totals, not per-request payloads or reasoning summaries.
|
|
133
|
+
The projection is read-only, flat across nested descendants, and scoped to the latest parent run in
|
|
134
|
+
this terminal session; finished rows remain visible until the next parent run starts. It is cleared
|
|
135
|
+
on session replacement or terminal disposal. It never includes tool arguments (beyond the title),
|
|
136
|
+
output or checklist item text.
|
|
137
|
+
|
|
138
|
+
`/agents` opens the Agents page (PROP-0029): built-in, global, project and variant profiles with
|
|
139
|
+
their tools, plugins, variant, model and instructions. Enter on a row edits a person's own profile
|
|
140
|
+
in `$VISUAL`/`$EDITOR`, copies one, or deletes one after confirmation; New profile writes a template
|
|
141
|
+
in the project or global folder and opens it.
|
|
142
|
+
|
|
143
|
+
Real scripted Pi execution over the actual terminal socket verifies result delivery, decision
|
|
144
|
+
routing, and the monitor's parent scoping and summary redaction. It does not establish live-provider
|
|
145
|
+
behavior. See
|
|
90
146
|
[ADR-0003](decisions/ADR-0003-shared-asynchronous-subagents.md) for recovery and lifecycle details.
|
|
91
147
|
|
|
92
148
|
## Ownership and process boundary
|
|
@@ -95,7 +151,7 @@ Harness owns its interactive terminal application in
|
|
|
95
151
|
[`src/terminal/opentui/`](../src/terminal/opentui/). [`app.ts`](../src/terminal/opentui/app.ts)
|
|
96
152
|
owns terminal lifecycle, submission, commands, decisions and run records;
|
|
97
153
|
[`root.tsx`](../src/terminal/opentui/root.tsx) owns composition, the transcript, the composer,
|
|
98
|
-
palette and dialogs. It does not construct Pi's `InteractiveMode`. Pi 1.
|
|
154
|
+
palette and dialogs. It does not construct Pi's `InteractiveMode`. Pi 1.4.0 supplies the
|
|
99
155
|
persistent agent session, model and auth runtime, native JSONL history, tool execution and rich
|
|
100
156
|
content components.
|
|
101
157
|
|
|
@@ -132,24 +188,42 @@ unattended execution path.
|
|
|
132
188
|
## Screen layout
|
|
133
189
|
|
|
134
190
|
[`root.tsx`](../src/terminal/opentui/root.tsx) draws the terminal on OpenTUI's alternate screen.
|
|
135
|
-
An empty conversation shows
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
191
|
+
An empty conversation shows a centered welcome. The default `Xingular Agent` identity appears as
|
|
192
|
+
an orange block `X` and blue letter-spaced `A G E N T`, followed by `Welcome.`, the tagline
|
|
193
|
+
`One run, done well.`, and a blue `/help` hint. Explicit host product names use the same generic mark and
|
|
194
|
+
subline formatting. The current model and thinking level remain available in dim text. Once a message
|
|
195
|
+
exists, a scrollable transcript fills the space above the composer. Single-line notices can appear
|
|
196
|
+
with the welcome, while multiline notices such as `/help` switch to the transcript layout so their
|
|
197
|
+
output cannot overlap it. The composer is a single top and bottom rule, with the right-aligned `plan mode` label followed by one divider character in the top rule,
|
|
139
198
|
and the textarea in the middle.
|
|
140
199
|
The working status row shows the active verb with a soft, warm glint that feathers across it and
|
|
141
200
|
fades past its edges, followed by run duration and the latest completed assistant response's output
|
|
142
201
|
rate, formatted as `(time, tok/s)`; the spinner and metrics stay steady, and duration updates during a run.
|
|
143
202
|
Until response usage is available, the rate shows `— tok/s`. On settlement, the completion verb and
|
|
144
203
|
final run statistics stay in that row until the next run replaces them; they do not become a transcript
|
|
145
|
-
entry. Notifications, queue announcements
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
204
|
+
entry. Notifications, queue announcements and retry updates—including retries while summarizing
|
|
205
|
+
context or branches—are one-line transcript entries at the point they occur, so subsequent chat
|
|
206
|
+
moves them up rather than keeping them pinned at the bottom.
|
|
207
|
+
|
|
208
|
+
While context compaction runs, the working line shows `Compacting context` (or `Retrying
|
|
209
|
+
compaction`) with the same spinner, in place of the working verb. During a run it keeps the run's
|
|
210
|
+
clock; a `/compact` while idle shows the spinner with its own clock. Compaction does not start a new
|
|
211
|
+
session or hide earlier chat. After it, the transcript shows, in order: the whole conversation from
|
|
212
|
+
before the compaction (rebuilt from Pi's session history, kept messages included); a rule labelled
|
|
213
|
+
`Context compacted · <tokens> tokens`; the summary printed as a normal reply; an `End of summary`
|
|
214
|
+
rule; then the work that followed. The summary is shown by default. Clicking either rule hides or
|
|
215
|
+
shows it, and Ctrl+O shows every summary again. On a narrow screen the rule drops the click hint, then
|
|
216
|
+
the token count. Earlier compactions in the same session keep their own rules and summary in place.
|
|
217
|
+
Notices stay after the message they followed. The model sees the summary and recent messages plus a
|
|
218
|
+
bounded, hidden checkpoint of the active request, checklist and plan instructions when available;
|
|
219
|
+
the checkpoint is regenerated for each post-compaction request until the run settles. The visible
|
|
220
|
+
transcript remains a presentation of the full history, not the model context.
|
|
221
|
+
Transcript entry ids follow positions in the displayed message list, so when a rebuilt list moves a
|
|
222
|
+
different kind of entry onto an id, the renderer builds a new component for it instead of reusing the
|
|
223
|
+
old layout, and each entry draws inside its own error boundary. A run therefore keeps updating live
|
|
224
|
+
through a compaction; it does not need `/resume` to show its later output.
|
|
225
|
+
A successful copy shows a temporary, opaque toast anchored at the terminal's top-right. Interactive blocks and widgets remain docked above the composer. A wrapping status bar
|
|
226
|
+
below the composer shows `<repo>:<branch>`, account, model, effort and token totals, with `|` between groups. After
|
|
153
227
|
the input token count it shows cache hit rate as `R<percentage>%`, calculated from cache reads divided
|
|
154
228
|
by total input tokens. The footer shows status messages without a shortcut-hint row. Press `?` with an empty
|
|
155
229
|
composer to open the shortcut reference. Transcript entries include
|
|
@@ -165,15 +239,17 @@ their content; other entries have no internal vertical padding. Bubble padding i
|
|
|
165
239
|
inter-entry gap. Internal lines within an entry stay together. The transcript stays pinned to the
|
|
166
240
|
latest message until you scroll away. While scrolled away, a `↓ Jump to latest` badge overlays the
|
|
167
241
|
transcript's lower-right corner; clicking it returns to the newest message and hides the badge.
|
|
168
|
-
`Ctrl+End` remains an alternate way to jump to the end. A primary click in the transcript or empty
|
|
169
|
-
|
|
170
|
-
|
|
242
|
+
`Ctrl+End` remains an alternate way to jump to the end. A primary click in the transcript or empty
|
|
243
|
+
welcome area focuses the composer. Dragging to select text anywhere in the TUI—including the
|
|
244
|
+
composer, transcript, widgets, dialogs and pages—copies the selected plain text when selection ends;
|
|
245
|
+
a simple click does not copy. `/copy` and `Ctrl+X` continue to copy the latest assistant reply.
|
|
171
246
|
|
|
172
247
|
Mouse movement highlights the row under the pointer in the command palette, plan choices, question
|
|
173
248
|
dock, searchable dialogs and Harness page lists; the highlight uses the same selection style as
|
|
174
249
|
keyboard navigation. A primary click activates the row, and clicks on page tabs switch that page's
|
|
175
|
-
section.
|
|
176
|
-
|
|
250
|
+
section. In `/accounts`, clicking an account opens its inspector or compact detail view, and clicking
|
|
251
|
+
an action runs the existing account flow. Question choices still stage their answer until the
|
|
252
|
+
question's action is clicked. Dialogs preserve their existing confirmation safeguards. OpenTUI enables terminal mouse-motion reporting for
|
|
177
253
|
hover; terminals or multiplexers that do not report motion retain keyboard navigation. ANSI-only
|
|
178
254
|
custom UI without a mouse handler remains keyboard-driven.
|
|
179
255
|
|
|
@@ -192,6 +268,16 @@ OSC 8 support. Inline and fenced code use a subtle panel fill with syntax colors
|
|
|
192
268
|
list markers, tables, dividers and task-list markers use the existing titanium palette. Images
|
|
193
269
|
display their alt text and are not fetched or rendered as image files.
|
|
194
270
|
|
|
271
|
+
## Checklist block
|
|
272
|
+
|
|
273
|
+
`checklist_write` is registered in terminal sessions (PAR-001). Each call renders in the
|
|
274
|
+
transcript as a checklist block: a status mark, `Checklist · n of m done`, then one line per item
|
|
275
|
+
with `✓` (done, success colour), `●` (in progress, warning yellow, bold) or `○` (pending, dim).
|
|
276
|
+
Each row reserves a one-cell status column and one-cell gap; item text and wrapped lines share the
|
|
277
|
+
same starting column. A call whose arguments are not a checklist, or that failed, stays an ordinary
|
|
278
|
+
tool row. The prompt's Progress group asks the model to keep the list current and write a final
|
|
279
|
+
update before replying; unfinished work remains unfinished rather than being marked complete.
|
|
280
|
+
|
|
195
281
|
## Blocks and pages
|
|
196
282
|
|
|
197
283
|
In Pi's own terminal UI, [`chrome.ts`](../src/terminal/tui/chrome.ts) gives terminal surfaces one
|
|
@@ -203,9 +289,10 @@ of two rule-based shapes, using the 2-cell composer gutter on each side and a di
|
|
|
203
289
|
Approvals, questions, and the `select`, `confirm`, `input` and `editor` dialogs use this shape
|
|
204
290
|
there. OpenTUI renders Harness-managed centered dialogs with the inset header treatment below.
|
|
205
291
|
- A **page** is a header row (title left, position or status right), a neutral rule, the body,
|
|
206
|
-
a neutral rule, and the hint row. `/settings`, `/
|
|
207
|
-
`/
|
|
208
|
-
|
|
292
|
+
a neutral rule, and the hint row. `/settings`, `/log`, `/permissions`, and the `/accounts`,
|
|
293
|
+
`/plugins` and `/hub` menus are pages. Section labels inside a page are plain bold headings, never
|
|
294
|
+
text set into a rule. `/trajectory` is a full-screen page with searchable Runs and Events
|
|
295
|
+
tabs; its Events view keeps the event list beside the selected event's JSON on wide terminals.
|
|
209
296
|
|
|
210
297
|
`DialogPanel` takes a `variant` (`block` by default). `ui.select` accepts a harness-owned `page`
|
|
211
298
|
option, which Pi's own dialogs ignore, so the same extension code runs in either terminal. Selected
|
|
@@ -214,24 +301,82 @@ frontends draw that field from the same muted-blue selection palette (`selection
|
|
|
214
301
|
explicit high-contrast text on it instead of the accent colour, so a choice reads the same in every
|
|
215
302
|
list. Rules use the theme's `warning` and `dim` colors, so a custom theme restyles them.
|
|
216
303
|
|
|
217
|
-
|
|
218
|
-
and
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
304
|
+
The Harness resource browser (PROP-0013) unifies Overview, Foundation, Variant, Skills, Plugins,
|
|
305
|
+
Connections, Tools and Library. `/harness` opens Overview; `/skills`, `/plugins`, `/connections`
|
|
306
|
+
(`/mcp`) and `/tools` open sections. `/hub` selects Discover and `/components` selects Library.
|
|
307
|
+
The existing Accounts, Permissions, Settings, Trajectory and Log pages retain their own tabs.
|
|
308
|
+
|
|
309
|
+
`/settings` includes a Browser tab with the device-local **Private address access** setting. It is
|
|
310
|
+
off by default. Enabling it asks for confirmation and allows agent browsing and annotation capture
|
|
311
|
+
to reach localhost and private networks.
|
|
312
|
+
|
|
313
|
+
Resource sections share Installed/Discover and source filters. Installed includes locally present
|
|
314
|
+
resources; current-session availability comes only from the runtime loader and active tool registry.
|
|
315
|
+
Discover uses the existing Hub with All/Community/Official filtering and an explicit remote refresh.
|
|
316
|
+
No matching community entries is an empty result, never replaced with built-in resources.
|
|
317
|
+
The view preserves search across source switches and restores section selection on return.
|
|
318
|
+
|
|
319
|
+
The browser fills the terminal (PROP-0014), with Overview, Foundation, Variant, Skills, Plugins,
|
|
320
|
+
Connections, Tools and Library as persistent top tabs. The section dropdown and sidebar are removed.
|
|
321
|
+
When the strip cannot fit, it shows the active tab and its position with previous/next navigation.
|
|
322
|
+
At 88 content columns, inventory sits beside an inspector containing metadata, actions and readable
|
|
323
|
+
content. Enter focuses the inspector. Its action rows group related tasks under Use, Inspect, Manage,
|
|
324
|
+
Access and Remove. Compact terminals show details/content within the active tab; resizing preserves
|
|
325
|
+
the selected resource and content position, clamped to the available height.
|
|
326
|
+
|
|
327
|
+
Tab/Shift+Tab focuses tabs, source, filter, toolbar actions, list and (when available) inspector.
|
|
328
|
+
Left/Right changes the focused tab or control; Enter on the tab strip returns to the inventory.
|
|
329
|
+
Ctrl+F focuses search. Escape returns from content to actions, returns to the list, clears search,
|
|
330
|
+
then closes. Mouse clicks select tabs directly, activate resource actions and focus filters;
|
|
331
|
+
wheel scrolling targets the list or inspector under the pointer. Other command pages keep their
|
|
332
|
+
centered presentation; `/settings` and `/accounts` use full-screen page layouts. Closing the browser preserves
|
|
333
|
+
the composer draft and attachments.
|
|
334
|
+
|
|
335
|
+
Foundation explains fixed runtime ownership; it is read-only. Variant shows c1–c8 with the
|
|
336
|
+
prepared version and current head separately. It previews pinned files from the preparation
|
|
337
|
+
snapshot and compares their text with the latest saved version. No in-place editing or adoption
|
|
338
|
+
is added. Library skills and rules are added through `terminal.components.add`, which commits a
|
|
339
|
+
validated future version. Directory-backed variants stay read-only.
|
|
340
|
+
|
|
341
|
+
Skill browsing is independent of the Skill commands setting. Use inserts a leading `$name`
|
|
342
|
+
without submitting. Ctrl+K opens a separate command filter; choosing a browser section keeps
|
|
343
|
+
the existing draft text and attachment labels. Canceling the filter restores that draft. OpenTUI completes
|
|
344
|
+
loaded skills for a leading `$`; Enter or Tab inserts the selected skill rather than sending.
|
|
345
|
+
Plugin contributions, settings, attachment and code trust share one detail flow. Package install
|
|
346
|
+
and removal delegate to existing services; installing never trusts or activates code.
|
|
347
|
+
|
|
348
|
+
Connections supports local stdio and remote HTTP forms, masked credentials, explicit scope,
|
|
349
|
+
saved disabled defaults, explicit testing and OAuth sign-in. Browsing never starts an MCP process.
|
|
350
|
+
Saved test results show timestamps rather than claiming a live connection. A Hub connector document
|
|
351
|
+
is inert: a separate setup action validates supported remote-definition fields before opening the
|
|
352
|
+
normal connection form. Other document kinds stay inspectable data. Tools show their owner,
|
|
353
|
+
parameters, active state and saved approval; each call still passes the gate.
|
|
354
|
+
|
|
355
|
+
The typed model is `terminal/browser.ts`; the protected adapter is `terminal/browserControl.ts`.
|
|
356
|
+
The browser accepts resource IDs for bounded regular-file previews, not arbitrary paths. Local
|
|
357
|
+
skill import rejects symbolic links and limits bytes, files and traversal. See
|
|
358
|
+
[source study and wireframes](study/tui-resource-browser.md),
|
|
359
|
+
[PROP-0013](architecture/proposals/PROP-0013-resource-browser.md) and
|
|
360
|
+
[ADR-0015](decisions/ADR-0015-resource-browser.md).
|
|
361
|
+
|
|
362
|
+
## Annotate pane (PROP-0018)
|
|
363
|
+
|
|
364
|
+
`/annotate:` opens the full-screen capture pane (equivalent to `/annotate:annotate`) beside the window being inspected. Add a page address with `/annotate:annotate [url]`. The target window is one of:
|
|
365
|
+
- the visible capture browser
|
|
366
|
+
- an app's own windows attached over its DevTools port (`--app`)
|
|
367
|
+
- app windows that loaded the page bridge script (`--bridge`)
|
|
368
|
+
|
|
369
|
+
The header shows the target and window and whether the inspector is on. The list has three groups: Queue, Sent and fixed, and Saved. While the inspector is on, the page polls for the next popover comment every 400 ms, shows the result as a notice, and refreshes the list.
|
|
370
|
+
|
|
371
|
+
| Key | Action |
|
|
372
|
+
|---|---|
|
|
373
|
+
| `i` | inspector on/off |
|
|
374
|
+
| `s` | send the queue |
|
|
375
|
+
| `x` | unqueue the selected note |
|
|
376
|
+
| `t` | choose a window |
|
|
377
|
+
| `Enter` | the note menu |
|
|
378
|
+
|
|
379
|
+
The page has no search row, so these letters are free for actions. `/annotate:notes` opens the searchable Web annotations list.
|
|
235
380
|
|
|
236
381
|
## Plan mode and thinking keys
|
|
237
382
|
|
|
@@ -239,10 +384,16 @@ Use `/plan <brief>` for one read-only planning request. A plan waits outside Pi'
|
|
|
239
384
|
queue until the active response settles, then runs by itself. Later messages remain behind it, even
|
|
240
385
|
when Pi's follow-up mode is `all`. During that run the session narrows to read-only inspection
|
|
241
386
|
(`read`, `grep`, `find`, `ls`), web search/page reading, questions (`ask_user`, `ask_user_question`)
|
|
242
|
-
and recall (history and Wiki reads, `memory_facts`).
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
387
|
+
and recall (history and Wiki reads, `memory_facts`). It may also delegate bounded research to a
|
|
388
|
+
named profile whose effective tool and plugin allowlists qualify for research; the child inherits
|
|
389
|
+
plan mode and receives only the intersection of the parent's frozen capabilities, profile and
|
|
390
|
+
plan-research set. Children cannot write, run commands, ask the user, use connectors or spawn more
|
|
391
|
+
children. Normal mode omits both question tools from the active set; the plan request enables
|
|
392
|
+
registered questions and research delegation temporarily and restores the normal set when it settles,
|
|
393
|
+
including on failure or interruption. Providers may mark individual calls as safe for research; every
|
|
394
|
+
other call is blocked before approval. Edits, writes, shell commands, memory writes and connected-app
|
|
395
|
+
tools remain unavailable to the parent and child. The plan instructions arrive as a request-scoped
|
|
396
|
+
prompt section, which the next ordinary request withdraws.
|
|
246
397
|
|
|
247
398
|
Each mode keeps its own model and effort for the account. Every selection the person makes (the model
|
|
248
399
|
picker, `/effort`, Shift+Up/Down, Ctrl+P) is saved against the mode it was made in, so Shift+Tab switches to that
|
|
@@ -254,7 +405,7 @@ and the App reads and writes them through `accounts.choices` and `accounts.choos
|
|
|
254
405
|
A bare `/plan` toggles plan mode, and Shift+Tab cycles between normal and plan mode. Normal, plan
|
|
255
406
|
and Bash are mutually exclusive composer modes. While plan mode is on, each submitted message is sent
|
|
256
407
|
as a plan request through that same queue, and the composer's top and bottom rules take the plan colour.
|
|
257
|
-
Commands still run as commands. Entering Bash with a leading `!` exits plan mode; Shift+Tab from Bash
|
|
408
|
+
Commands still run as commands. The model may run Bash during a plan request, only in the read-only sandbox scope (PROP-0043); your own `!` commands are not part of the plan. Entering Bash with a leading `!` exits plan mode; Shift+Tab from Bash
|
|
258
409
|
switches to plan mode and keeps the draft text. Turning plan mode off returns to normal mode. The old
|
|
259
410
|
on/off/toggle forms are rejected; a bare `/plan` is the switch.
|
|
260
411
|
|
|
@@ -268,9 +419,11 @@ Implement leaves plan mode, so the normal tools and the mode's own model and eff
|
|
|
268
419
|
mode and focuses the composer, so the next message revises the plan and offers a new choice. A plan run
|
|
269
420
|
that was interrupted, failed, or had work queued behind it is not offered.
|
|
270
421
|
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
422
|
+
A recognized leading slash command uses the selected theme's link color while typing and in its
|
|
423
|
+
user-message bubble. Only the command token is accented; arguments and unknown slash tokens keep the
|
|
424
|
+
normal text color. Recognition follows the active command registry, including built-in commands and
|
|
425
|
+
aliases, loaded extension and prompt commands, and enabled skill invocations written as
|
|
426
|
+
`/skill:name`.
|
|
274
427
|
|
|
275
428
|
SDK session runs receive plan instructions as a dynamic context update, leaving the stable system
|
|
276
429
|
prompt unchanged; their session gate refuses calls outside the read-only set. The standalone
|
|
@@ -287,13 +440,17 @@ the marker and rules blue; in the normal prompt, the marker matches the divider
|
|
|
287
440
|
an empty Bash body returns to the normal prompt. Submitting while a reply is active queues
|
|
288
441
|
the command as a standalone turn; it does not steer the current model request.
|
|
289
442
|
|
|
290
|
-
The terminal
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
443
|
+
The terminal checks Bash policy before using Pi's native `executeBash`. Ordinary `!command` runs
|
|
444
|
+
workspace-scoped; `!outside <command>` explicitly requests human-only approval before the command
|
|
445
|
+
runs once with broader filesystem access. The complete command is shown as escaped, scrollable
|
|
446
|
+
approval details; if the terminal is too small to show both details and choices, the request is
|
|
447
|
+
denied. Shell output never triggers approval or replay. Output streams into the transcript while the
|
|
448
|
+
command runs, so browser-login URLs are visible before the
|
|
449
|
+
command finishes; the running item shows that Escape stops the command. The native result is
|
|
450
|
+
recorded in run activity and session history before the model is prompted to read and explain it.
|
|
451
|
+
This does not attach interactive stdin to the shell. SDK callers may opt into this behavior with
|
|
452
|
+
`SessionRunInput.initialBashCommand`; it is restricted to a new interactive user turn and the
|
|
453
|
+
session runner applies the same Bash gate and explicit outside-scope request.
|
|
297
454
|
|
|
298
455
|
## Reference and reproduced presentation
|
|
299
456
|
|
|
@@ -311,8 +468,8 @@ not an arbitrary checkout of upstream main. The source repository is
|
|
|
311
468
|
In the extracted `pi-tui` package, `src/theme/defaults/titanium.json` establishes the titanium
|
|
312
469
|
palette and its indexed-color fallbacks. Harness adapts these into
|
|
313
470
|
[`theme.ts`](../src/terminal/tui/theme.ts) and
|
|
314
|
-
[`opentui/theme.ts`](../src/terminal/opentui/theme.ts). The OpenTUI status bar shows the project name
|
|
315
|
-
branch
|
|
471
|
+
[`opentui/theme.ts`](../src/terminal/opentui/theme.ts). The OpenTUI status bar shows the project name and
|
|
472
|
+
branch together as `<repo>:<branch>`, followed by account, model, context use and current-session input/output totals. Input totals add cache
|
|
316
473
|
reads and exclude cache writes; its `R<percentage>%` hit rate is cache reads divided by total input.
|
|
317
474
|
Token counts below 1,000 show as whole numbers; larger counts use floor-rounded K/M/B suffixes
|
|
318
475
|
without decimals.
|
|
@@ -337,7 +494,7 @@ Full upstream copyright and MIT permission notices are in [NOTICE.md](../NOTICE.
|
|
|
337
494
|
## Runtime compatibility adapter
|
|
338
495
|
|
|
339
496
|
Most integration uses public Pi exports. [`piAdapter.ts`](../src/terminal/tui/piAdapter.ts)
|
|
340
|
-
contains the remaining presentation dependencies and requires exactly Pi **1.
|
|
497
|
+
contains the remaining presentation dependencies and requires exactly Pi **1.4.0** before
|
|
341
498
|
loading them. The shared [`runtime.ts`](../src/pi/runtime.ts) loader imports Pi first, then invokes
|
|
342
499
|
the same HTTP dispatcher hook as Pi's CLI before any Harness Pi runtime is used. This reapplies
|
|
343
500
|
the process `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` settings after Pi's bundled Undici has
|
|
@@ -347,7 +504,7 @@ concurrent initialization.
|
|
|
347
504
|
|
|
348
505
|
| Internal dependency | Reason |
|
|
349
506
|
|---|---|
|
|
350
|
-
| `dist/bundle/chunks/chunk-
|
|
507
|
+
| `dist/bundle/chunks/chunk-MM3LKT73.js:configureHttpDispatcher` | Restore Pi's environment-aware HTTP proxy dispatcher after the SDK import |
|
|
351
508
|
| `dist/extensions/index.js` builtin inventory | Preserve selected `llama.cpp`, `codemode`, `tool-search` and MCP builtins with the CLI's replacement semantics |
|
|
352
509
|
| `dist/modes/interactive/theme/theme.js:setThemeInstance` | Keep public native rich components on the same active theme as the Harness screen |
|
|
353
510
|
| `dist/core/tools/renderers/index.js:withBuiltInRenderers` | Preserve existing read/edit/bash/write formatting without replacing tool execution |
|
|
@@ -403,7 +560,7 @@ personal Pi profile. Provider authentication and model catalogs use that account
|
|
|
403
560
|
The selected account stays pinned. The existing `/accounts` command requests a parent-managed
|
|
404
561
|
restart to use a different account while resuming the conversation.
|
|
405
562
|
|
|
406
|
-
An initial `--session` or `/
|
|
563
|
+
An initial `--session` option or `/session` target (also accepted as `/resume`) must resolve inside the prepared history directory,
|
|
407
564
|
including symlink targets, and its stored absolute working folder must match the terminal's
|
|
408
565
|
canonical working folder. `/import` may copy an explicitly selected external native JSONL file
|
|
409
566
|
only when its recorded working folder matches. A caller cannot override a foreign recorded
|
|
@@ -450,22 +607,74 @@ a tool waiting forever on a question after the screen has closed. Native `sessio
|
|
|
450
607
|
clears controller readiness and stops that session's poller; the replacement's `session_start`
|
|
451
608
|
restores readiness while retaining the same process control claim.
|
|
452
609
|
|
|
453
|
-
The bridge
|
|
454
|
-
`ask_user_question` contract
|
|
455
|
-
recommended choice; recommendations remain visual and
|
|
456
|
-
retain a free-text “Something else” answer. A pending
|
|
457
|
-
composer
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
610
|
+
The bridge registers the shared `ask_user` batch tool alongside the single-question
|
|
611
|
+
`ask_user_question` contract; only plan requests activate them. Each question has a concise 1–2 word
|
|
612
|
+
label, at least one choice, and at least one recommended choice; recommendations remain visual and
|
|
613
|
+
never preselect. Choice-based questions also retain a free-text “Something else” answer. A pending
|
|
614
|
+
question occupies the composer position in a flat block, not a modal, with the chat transcript
|
|
615
|
+
above it. The dock fits its content and grows to at most two-thirds of the terminal height; each
|
|
616
|
+
question tab is sized from its own content. When content overflows, its body scrolls while tabs and
|
|
617
|
+
answer/action controls stay outside that region.
|
|
618
|
+
The final choice sits one blank row above “Something else”. The block has only a muted top divider
|
|
619
|
+
and separates its hint from the content by one blank line; below 60 terminal columns, it uses a
|
|
620
|
+
compact hint. While the dock is active, PageUp/PageDown scroll its body and Ctrl+Home/End jump to
|
|
621
|
+
its beginning/end instead of the transcript. Focused choices and note fields are brought into view.
|
|
622
|
+
A tab strip shows each question label above the active question title, with one blank row below the tabs
|
|
623
|
+
and below the title;
|
|
624
|
+
clicking a tab or using Left/Right changes questions without discarding staged answers. The header has
|
|
625
|
+
no pager controls, and the block cannot be collapsed. Choices and descriptions appear above the numbered free-text answer and Continue or Skip
|
|
626
|
+
action. Selected choices fill the whole row with subtle dark green; Continue and Submit uses a
|
|
627
|
+
green-filled button, while Skip remains neutral. While the block is active, the chat composer and
|
|
628
|
+
its lower status bar are hidden. Tab and Shift+Tab move through the available controls; `n` opens a
|
|
629
|
+
note for the focused selected choice. Its editor appears below that choice, aligned with the description
|
|
630
|
+
column, and begins with an accent-colored `Note:` label. Tab only visits note fields that are already
|
|
631
|
+
open. Notes are submitted by choice label and cleared when that choice is deselected. Notes and
|
|
632
|
+
free-text answers wrap across lines. Tab takes precedence over normal thinking and plan-mode shortcuts. Up
|
|
633
|
+
and Down navigate choices. Enter selects a choice, activates the focused action, or submits the
|
|
634
|
+
answer or note field. Escape cancels the pending question and interrupts the run.
|
|
635
|
+
|
|
636
|
+
Questions may set `uiSketch: true` to enable a choice sketch preview. Every choice must then include
|
|
637
|
+
an ASCII sketch of 1–24 LF-separated lines, no more than 80 printable ASCII characters per line
|
|
638
|
+
(1,943 bytes maximum), and at least one visible character. Tabs, CR, controls, escape sequences and
|
|
639
|
+
non-ASCII text are rejected. Without the flag, choice sketches are rejected. Tool guidance asks for
|
|
640
|
+
contextual UI wireframes with actual panel/table structure and neighboring elements, consistent
|
|
641
|
+
across alternatives, rather than isolated decorative diagrams; quality is not a schema guarantee.
|
|
642
|
+
|
|
643
|
+
The dock uses one shared measured layout for all choices: marker gutter, one-third label cell,
|
|
644
|
+
two-cell gap, and remaining description cell. Boundaries align across rows at every width, including
|
|
645
|
+
compact terminals; both cells wrap independently, missing descriptions keep their cell, and columns
|
|
646
|
+
never stack. Recommendation text becomes `(Rec.)` when the label column is fewer than 14 cells.
|
|
647
|
+
Multi-select choices use `✓` when selected and `○` when unselected, matching checklist glyphs;
|
|
648
|
+
single-choice options remain numbered.
|
|
649
|
+
|
|
650
|
+
One shared border-only monospace preview below the choices follows the hovered choice, falling
|
|
651
|
+
back to keyboard focus. It has no visible caption or extra left rule. Under the approved
|
|
652
|
+
[PROP-0026](architecture/proposals/PROP-0026-connected-sketch-display.md) /
|
|
653
|
+
[ADR-0027](decisions/ADR-0027-connected-sketch-display.md) and
|
|
654
|
+
[PROP-0028](architecture/proposals/PROP-0028-normalize-question-wireframes.md) /
|
|
655
|
+
[ADR-0029](decisions/ADR-0029-normalized-question-wireframe-borders.md) amendments,
|
|
656
|
+
the terminal display uses a bounded structural projection in
|
|
657
|
+
`src/terminal/opentui/sketchPanel.ts`: recognized ASCII table-border rows—including title-bearing
|
|
658
|
+
top rules—and enclosed vertical table edges become connected box-drawing glyphs. Internal framed
|
|
659
|
+
tables keep their original widths and positions. Within a high-confidence frame, a missing side
|
|
660
|
+
edge may be filled or a displaced edge moved only through whitespace to matched corner columns;
|
|
661
|
+
interior text and ambiguous rows remain literal. Bare standalone hyphen divider rows expand to
|
|
662
|
+
`max(panel viewport width, original sketch widest line)` and attach to the outer single-line frame
|
|
663
|
+
with `├` and `┤`. Prose, content operators, ordinary pipes and unrecognized rows remain literal;
|
|
664
|
+
there is no global `+|-` substitution. The original validated ASCII source, including whitespace,
|
|
665
|
+
is persisted untouched; normalization and projected glyphs are display-only.
|
|
666
|
+
|
|
667
|
+
A bounded two-axis viewport exposes all overflow without wrapping, reflow, truncation or
|
|
668
|
+
Markdown/ANSI interpretation. Shift+arrows pan the sketch; ordinary arrows retain question/choice
|
|
669
|
+
navigation. Hosts may keep literal previews of that same source. The preview does not change the
|
|
670
|
+
selected answer, and sketch metadata is not included in the answer event. The 80×24 source bounds
|
|
671
|
+
and dock layout remain as specified by
|
|
672
|
+
[PROP-0025](architecture/proposals/PROP-0025-contextual-question-wireframes.md) and
|
|
673
|
+
[ADR-0026](decisions/ADR-0026-contextual-question-wireframes.md). Isolated production PTY evidence
|
|
674
|
+
for [PROP-0026](architecture/proposals/PROP-0026-connected-sketch-display.md) and
|
|
675
|
+
[PROP-0028](architecture/proposals/PROP-0028-normalize-question-wireframes.md) is retained under
|
|
676
|
+
`docs/evidence/terminal-wireframe-normalization/`; it does not claim every-emulator rendering or
|
|
677
|
+
live-model sketch quality.
|
|
469
678
|
|
|
470
679
|
Recommended choices appear first with a warning-colored marker, without changing their labels or
|
|
471
680
|
preselecting them; every question requires at least one recommendation. A single-choice question
|
|
@@ -480,22 +689,40 @@ event subscriptions and custom transcript components detach before native invali
|
|
|
480
689
|
Cleanup failures cannot prevent terminal restoration. Fatal asynchronous errors restore the
|
|
481
690
|
terminal and exit with failure; startup failures and suspend/resume use the same lifecycle.
|
|
482
691
|
|
|
483
|
-
The command registry supplies help and completion for Harness commands, loaded extensions
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
692
|
+
The command registry supplies help and slash completion for Harness commands, loaded extensions
|
|
693
|
+
and prompts. `/session` selects a saved session (`/resume` remains an alias), and `/history` navigates
|
|
694
|
+
branches in the current session (`/tree` remains an alias). `/btw <question>` asks a side question;
|
|
695
|
+
`/side` is its alias. Help and the slash-command palette show each pair once, as `/session (resume)`,
|
|
696
|
+
`/history (tree)` and `/btw (side)`; aliases still match palette searches.
|
|
697
|
+
With no path argument, `/session` opens a full-screen searchable page. Each unnumbered row shows a
|
|
698
|
+
normal-color title and a muted second line with relative activity time, `<project>:<branch>` and JSONL
|
|
699
|
+
file size separated by ` · `. One blank line separates each session. Enter resumes the selected
|
|
700
|
+
session; account and folder scope checks
|
|
701
|
+
remain enforced. Supplying an explicit path continues directly without opening the picker.
|
|
702
|
+
The separate `$` palette completes enabled skill invocations; `/skills` always browses skills. `/help`
|
|
703
|
+
renders the command list as one transcript entry, grouped under Core, Run, Model, Session, Inspect,
|
|
704
|
+
Harness, Plugins and Prompts; command names and descriptions wrap in aligned columns, with no
|
|
705
|
+
blank rows between choices. `/plugins` opens the browser with protected code trust and plugin settings actions. Settings use
|
|
706
|
+
`plugins.configure`; on/off settings and bounded whole-number settings keep their existing ranges.
|
|
707
|
+
Saved settings are read when the plugin next uses them and do not require a restart. The standalone
|
|
489
708
|
terminal no longer has separate `/login`, `/trust`, `/bug`, `/changelog`, `/share`, `/scoped-mode` or
|
|
490
|
-
`/import` commands. `/btw <question>`
|
|
709
|
+
`/import` commands. `/btw <question>` (or `/side <question>`) starts a separate Harness run with the
|
|
710
|
+
main run's effective instructions, visible conversation and redacted public tool inputs/results.
|
|
711
|
+
Hidden reasoning and image bytes are excluded; the side run has no tools. Its block puts the
|
|
712
|
+
question after `/btw`, shows the normal animated spinner while answering, and separates the answer
|
|
713
|
+
and hint by one blank row; it has no status labels. PageUp/PageDown browse a long answer and Ctrl+X
|
|
714
|
+
copies the full answer. Escape or either command with no question dismisses the dock and interrupts
|
|
715
|
+
only that side run; the main reply continues. `/stop` interrupts the current main reply. The `/accounts` page handles sign-in
|
|
491
716
|
and sign-out. `/components` browses reusable skills, prompts and rules; a confirmed skill or rule addition
|
|
492
717
|
creates a variant version for future sessions while the current terminal keeps its pinned version. `/reload` applies trusted resource and keybinding changes.
|
|
493
718
|
|
|
494
719
|
`/trajectory` opens the newest recorded run for the current native conversation; `/trajectory <run-id>`
|
|
495
|
-
opens a selected run from that conversation.
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
720
|
+
opens a selected run from that conversation. The full-screen page keeps searchable Runs and Events
|
|
721
|
+
tabs. In Events, the list sits beside the selected event's JSON on wide terminals and stacks above it
|
|
722
|
+
on compact terminals. Type to search run IDs, goals, event types, timestamps, summaries and payload
|
|
723
|
+
text; `[` and `]` change runs, up/down selects events, PageUp/PageDown scrolls event details, and
|
|
724
|
+
`Shift+C` copies the selected event JSON. Active runs refresh while the page is open. The protected
|
|
725
|
+
terminal socket scopes both the run list and event reads to the current terminal and native session file.
|
|
499
726
|
|
|
500
727
|
`/log` opens a centered page dialog with separate Harness diagnostics and current-conversation
|
|
501
728
|
run-event views. The diagnostic file is read at its captured size in bounded socket chunks. Tab/Shift+Tab
|
|
@@ -504,6 +731,21 @@ diagnostics retain available error stacks and safe request metadata, while the v
|
|
|
504
731
|
and URL queries and omits response bodies, prompts and message contents. Embedded hosts without a
|
|
505
732
|
`harness.log` still show the conversation's recorded run events.
|
|
506
733
|
|
|
734
|
+
## Slash command ownership
|
|
735
|
+
|
|
736
|
+
Harness core commands are unprefixed and live in the core terminal command registry, independently
|
|
737
|
+
of feature-plugin command metadata: `/doctor`, `/worktree`, `/trajectory`, `/subagents`, and `/agents`.
|
|
738
|
+
`/history` (also `/tree`) continues to navigate session branches. `/mcp` and `/connections` open the
|
|
739
|
+
Connections browser. Feature descriptors and their services remain registered; only these terminal
|
|
740
|
+
routes move out of the plugin command registry. Other plugin-owned commands continue to use
|
|
741
|
+
`/<owner-prefix>:<command>`. The annotations plugin uses `/annotate:annotate` and `/annotate:notes`;
|
|
742
|
+
`/annotate:` opens its default capture pane. Pi package extensions use their normalized package name
|
|
743
|
+
as owner prefix unless `harness.commandPrefix` overrides it; loose extensions use their normalized
|
|
744
|
+
extension name. A plugin prefix collision or a duplicate command within one owner is rejected with
|
|
745
|
+
owner paths in the diagnostic. The former owner-qualified and `/plugin:<command>` routes of promoted
|
|
746
|
+
Harness commands remain hidden compatibility aliases for one release, omitted from help and
|
|
747
|
+
completion. Prompt templates and `/skill:<name>` keep their existing forms.
|
|
748
|
+
|
|
507
749
|
## Input performance profile
|
|
508
750
|
|
|
509
751
|
`npm run profile:terminal-latency` (`scripts/profile-terminal-latency.py`) types into the real
|
|
@@ -529,8 +771,8 @@ How the frontend keeps typing fast:
|
|
|
529
771
|
results change; session statistics refresh at most every 250 ms during a run.
|
|
530
772
|
- **Kept connections.** Session-socket requests ask to `keep` their connection, so the two 100 ms
|
|
531
773
|
polls and per-key draft updates reuse a connection instead of opening one each.
|
|
532
|
-
- **No swallowed keys.**
|
|
533
|
-
is typed there.
|
|
774
|
+
- **No swallowed keys.** While a question is active, an unused printable character moves focus to
|
|
775
|
+
“Something else” and is typed there when free text is allowed; it never creates a hidden chat draft.
|
|
534
776
|
|
|
535
777
|
## Verification and remaining limits
|
|
536
778
|
|
|
@@ -665,7 +907,38 @@ truncate trailing text. Renaming refreshes the line through Pi's existing metada
|
|
|
665
907
|
## `/doctor`
|
|
666
908
|
|
|
667
909
|
Checks accounts/models, tools, MCP, plugins/skills, variant/prompt validity, runtime assets, storage
|
|
668
|
-
and startup recovery.
|
|
669
|
-
|
|
670
|
-
and
|
|
671
|
-
|
|
910
|
+
and startup recovery. The summary keeps mode, progress, account/model and status counts visible above
|
|
911
|
+
the findings. Wide layouts use aligned Status, Check, Category and Verification columns, with evidence
|
|
912
|
+
and any next step beneath each finding; narrow layouts stack those fields. Status colors follow the
|
|
913
|
+
active theme: pass is success, warning/blocked warning, fail error, disabled dim and unverified muted.
|
|
914
|
+
|
|
915
|
+
`r` refreshes, `t` retries one local finding, `l` selects live checks, `c` cancels, Up/Down scroll by
|
|
916
|
+
line, PgUp/PgDn or the mouse wheel by page, and Home/End jump to the first/last finding. Escape
|
|
917
|
+
closes/cancels. Live
|
|
918
|
+
checks show their costs and isolated resources before confirmation. Providers without diagnostic
|
|
919
|
+
callbacks are reported unverified. See [Doctor](doctor.md).
|
|
920
|
+
|
|
921
|
+
## Resource browser verification (2026-10-22)
|
|
922
|
+
|
|
923
|
+
The [retained evidence](evidence/terminal-resource-browser/README.md) records three-size PTY
|
|
924
|
+
acceptance, pointer/filter and resize behavior, skill completion/insertion and preserved drafts,
|
|
925
|
+
with zero model requests. Isolated idle/history/stream input profiling reported no missed keys
|
|
926
|
+
and p95 14.81/14.27/17.32 ms. The manifest binds both the CLI and OpenTUI bundle to their digests.
|
|
927
|
+
Live external connector authentication and community package installation were not exercised.
|
|
928
|
+
|
|
929
|
+
|
|
930
|
+
## Full-screen browser verification (2026-10-23)
|
|
931
|
+
|
|
932
|
+
[PROP-0014](architecture/proposals/PROP-0014-fullscreen-browser-tabs.md) and
|
|
933
|
+
[ADR-0016](decisions/ADR-0016-fullscreen-browser-tabs.md) replace the browser's centered layout
|
|
934
|
+
with full-screen section tabs and a responsive inventory/inspector. The
|
|
935
|
+
[retained PTY evidence](evidence/terminal-fullscreen-browser/README.md) covers 40×20, 80×24 and
|
|
936
|
+
120×40, keyboard and pointer tab selection, filter interaction, resizing and draft preservation,
|
|
937
|
+
with zero model requests. The manifest binds the CLI, OpenTUI bundle and verification script.
|
|
938
|
+
|
|
939
|
+
Harness typecheck, full tests (893 passing, three platform skips), build and standalone proof
|
|
940
|
+
passed. The final focused browser/page/command run passed 75 tests. Agent app typecheck, layer
|
|
941
|
+
checks, frontend tests, all 40 sidecar tests and 240 Rust tests passed (one Rust test ignored).
|
|
942
|
+
Sidecar tests were rerun with two workers and a 30-second timeout after four five-second timeouts
|
|
943
|
+
under concurrent load. Socket-backed Harness and PTY checks required sandbox escalation;
|
|
944
|
+
verification used local fixtures and disposable session data.
|