@xingular/harness 0.1.6 → 2.0.0

package/docs/README.md

@@ -0,0 +1,15 @@
+# Harness documentation
+
+Current implementation: [Harness terminal frontend](terminal-tui.md). The package-level
+[README](../README.md) describes the embedding API, accounts, plugins, memory and storage.
+
+| ID | Record | Type | Status | Related |
+|---|---|---|---|---|
+| ADR-0004 | [Fullscreen terminal layout with a fixed dock](decisions/ADR-0004-fullscreen-terminal-layout.md) | Decision | Accepted; working tree implementation | ADR-0001, [Terminal architecture and evidence](terminal-tui.md) |
+| ADR-0003 | [Shared asynchronous subagents with native-history delivery receipts](decisions/ADR-0003-shared-asynchronous-subagents.md) | Decision | Accepted; working tree implementation | ADR-0002, [Embedding API](../README.md) |
+| ADR-0002 | [Native subagent lifecycle in Harness sessions](decisions/ADR-0002-native-subagent-lifecycle.md) | Decision | Superseded by ADR-0003 | [Embedding API](../README.md) |
+| ADR-0001 | [Own the terminal frontend and keep Pi as the session runtime](decisions/ADR-0001-owned-terminal.md) | Decision | Accepted; working tree implementation | [Terminal architecture and evidence](terminal-tui.md) |
+
+Living reference pages describe checked source behavior. Accepted decisions record the choice;
+they do not establish publication or release. Evidence references on the terminal page identify
+the inspected upstream artifacts and bound the verification claims.

package/docs/decisions/ADR-0001-owned-terminal.md

@@ -0,0 +1,87 @@
+---
+id: ADR-0001
+title: Own the terminal frontend and keep Pi as the session runtime
+status: accepted
+created: 2026-10-17
+updated: 2026-10-17
+related: []
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0001 — Own the terminal frontend and keep Pi as the session runtime
+
+## Context and decision drivers
+
+The requested terminal must reproduce the supported Oh My Pi presentation using capabilities
+Harness already has. An extension can replace a header, footer or editor, but Pi's
+`InteractiveMode` still owns transcript layout, command routing, focus and screen lifecycle.
+That arrangement cannot give Harness full control over those surfaces.
+
+The existing terminal boundary already provides isolated accounts, a compiled prompt, trusted
+resource selection, a session socket and controller, a final tool gate and one writer for run
+records. Retaining that boundary avoids a second authority for authentication or run state.
+
+## Decision
+
+Own the terminal application in `src/terminal/tui/` and run a persistent Pi SDK
+`AgentSessionRuntime` inside the prepared terminal child. Harness owns composition, editor and
+input routing, dialogs, overlays and built-in command dispatch. Pi owns model/tool execution
+and native history. The frontend binds the public extension UI contract in `tui` mode and may
+reuse public rich content components.
+
+Keep `TerminalAssets` and `Terminals.prepare/send/state/input/dispose` compatible. Preserve the
+socket/controller bridge and its final gate. Keep the private control claim in process memory
+across native session replacement, revalidate prepared resource trust before every load, and
+scope native resume/import to the terminal's original working folder. Put unavoidable Pi
+implementation imports in one adapter checked against the pinned 1.2.0 version.
+
+Use the shipped OMP 18.11.3 artifacts as the visual reference, with Harness identity and existing
+commands. [The living reference](../terminal-tui.md) records artifact digests, evidence and
+verification limits. [NOTICE.md](../../NOTICE.md) preserves the upstream MIT license.
+
+## Alternatives and rejection reasons
+
+- **Only install a presentation extension:** leaves the default interactive frontend in control
+  of transcript geometry, built-in commands and terminal lifecycle, contrary to the requested ownership.
+- **Call `sessions.run` for each prompt:** recreates and disposes the runtime per turn, losing
+  persistent plugin UI/queue state and overlapping terminal controller run accounting.
+- **Replace the execution stack with OMP:** changes tools, model/provider behavior and product
+  capabilities beyond the requested presentation migration.
+- **Fork Pi's complete interactive mode:** introduces a large second implementation of session
+  and terminal behavior, making upgrades and account/governance boundaries harder to review.
+
+## Consequences and risks
+
+Harness must maintain its own command routing, focus, keybindings and extension UI lifecycle.
+The small internal adapter is an explicit upgrade constraint. Native session format and
+account storage stay compatible; cross-folder navigation requires a freshly prepared scope.
+Changes to trusted plugin code require review and reopening the terminal.
+
+This record accepts the architectural choice. Implementation exists in the working tree;
+publication and exhaustive visual/provider/platform parity are not implied. The living page
+records passed focused tests and the pending controlled PTY verification result.
+
+## Implementation and evidence
+
+- [`TerminalApplication`](../../src/terminal/tui/application.ts) owns the screen and input lifecycle.
+- [`runtime.ts`](../../src/terminal/tui/runtime.ts) owns the persistent SDK adapter and scoped navigation.
+- [`piAdapter.ts`](../../src/terminal/tui/piAdapter.ts) contains pinned compatibility imports.
+- [`piExtension.ts`](../../src/terminal/piExtension.ts) retains gate/telemetry integration.
+- [`runtime.socket.test.ts`](../../src/terminal/tui/runtime.socket.test.ts) checks the real isolated SDK/socket boundary without a provider request.
+- [Reference identities, retained REA evidence and verification limits](../terminal-tui.md#verification-and-remaining-limits).
+
+## Verification follow-up — 2026-10-17
+
+The earlier pending-PTY statement above records the state when this decision was written.
+The [living reference](../terminal-tui.md#verification-and-remaining-limits) now records passed
+production PTY scenarios at all three planned sizes, 419 Harness tests, a standalone proof and
+portable OMP/Harness comparison records. The implementation also scopes retained plugin UI
+callbacks and transcript components to a native resource generation, provides frozen runtime
+state, and submits grouped question answers through the existing registry atomically.
+
+The personal Codex live attempt reached the provider but was rejected because its usage limit
+had been reached. The isolated credentials were deleted, the source sign-in remained unchanged,
+and terminal restoration passed; see the [live evidence](../evidence/terminal-2026-10-17-followup/live-codex/README.md).
+Successful live streaming/tool acceptance and App renderer acceptance remain open. This evidence
+does not establish a released package or exhaustive platform/visual parity.

package/docs/decisions/ADR-0002-native-subagent-lifecycle.md

@@ -0,0 +1,49 @@
+---
+id: ADR-0002
+title: Native subagent lifecycle in Harness sessions
+status: superseded
+superseded_by: ADR-0003
+created: 2026-10-18
+updated: 2026-10-18
+---
+# ADR-0002 — Native subagent lifecycle in Harness sessions
+
+Superseded by [ADR-0003](ADR-0003-shared-asynchronous-subagents.md), which expands the native
+service to asynchronous execution, reliable delivery, and terminal parity. The earlier decision
+and its rationale are retained below.
+
+## Context
+
+Subagents already used Harness sessions, capability snapshots and run lineage, but their tool
+owned launching and polled run files for completion. A host inferred ownership from session
+names, coupling it to an internal identifier format.
+
+## Decision
+
+`Sessions.spawnSubagent` owns child creation. A live parent's captured launch supplies caller,
+account, model selection, folder, policy context, prompt and capability ceiling. The host or
+model supplies only a complete brief and an optional tool subset. Current capability availability
+and the captured nesting limit further restrict each child. Empty tool subsets stay empty;
+spawning permission is never added back after narrowing. Children start with fresh history,
+without inherited image attachments or request preamble. Existing tool gating applies.
+
+The model tool is an adapter to the same native API exposed over RPC. `RunRegistry.wait` resolves
+on settlement, including failed startup and interruption, without polling or per-call listeners.
+The Harness Subagents plugin attributes the model-visible tool. Opt-in remains a session option;
+`{}` selects the Harness default depth of one. Application organization delegation remains a host
+concern. Consumers resolve ownership from run lineage rather than parsing session IDs.
+
+## Alternatives and consequences
+
+Keeping orchestration in the tool would leave hosts without the same lifecycle contract.
+Moving application organizations into Harness would violate the embedding boundary. A new
+background job manager would duplicate existing run tracking, approvals and interruption.
+The selected change reuses these layers and preserves the synchronous model tool behavior.
+The native API starts children only for live parents in the same Harness instance; it does not
+resume a stopped parent's launch or implement cross-process child management.
+
+## Evidence
+
+Regression coverage is in `src/sessions/sessions.test.ts` and `src/server/server.test.ts`.
+Application host and run-family tests cover nested lineage with opaque session IDs. Verification
+results belong to the implementation handoff; no release or live-provider behavior is claimed.

package/docs/decisions/ADR-0003-shared-asynchronous-subagents.md

@@ -0,0 +1,68 @@
+---
+id: ADR-0003
+title: Shared asynchronous subagents with native-history delivery receipts
+status: accepted
+created: 2026-10-18
+updated: 2026-10-18
+supersedes: ADR-0002
+---
+# ADR-0003 — Shared asynchronous subagents with native-history delivery receipts
+
+## Context and decision
+
+The owner selected reliable delivery, asynchronous spawn/wait, and one SDK/terminal/App API after
+studying OMP. They chose attached children joined before the parent finishes, async spawning by
+default, availability for every interactive caller within its capability ceiling, and recovery
+only when the user explicitly resumes. This supersedes the blocking tool contract in ADR-0002.
+
+`harness.subagents` owns spawning, selective waits and results. SDK and terminal adapters register
+live, frozen parent context with it; no model argument supplies caller, account or replacement
+launch metadata. The terminal adapter uses its private control key. Children use normal Harness
+sessions, isolated accounts, fresh history, existing gates and capability intersection. The old
+`sessions.spawnSubagent` entry point forwards to the service for compatibility.
+
+A parent reserves each child in `runs/<parent>/subagents.json` through the run store before startup.
+A native branch owner marker is persisted before a real parent accepts spawns. Results are delivered
+at turn boundaries or through explicit blocking tools. Native messages and tool results carry typed
+receipts; only receipts on the selected branch acknowledge delivery. Constructing a delivery draft
+never acknowledges it. Large batches acknowledge only the included children. The final settlement
+hook joins children and injects remaining results; an adapter verification guard refuses successful
+completion if persisted native history still lacks a result. The stable system prefix is unchanged.
+
+On explicit resume, matching owner markers, caller/account/folder/native identity and run lineage
+restore undelivered results. A startup reservation that never opened becomes an interrupted run.
+Existing startup recovery interrupts orphaned active runs. Neither recovery path restarts model
+work. Cancellation settles approvals and questions before waiting for SDK abort, preventing blocked
+child interactions from deadlocking parent shutdown.
+
+Interactive sessions enable the tools by default, `null` disables them, and explicit capability
+sets can exclude them. Unattended callers remain off unless the host explicitly enables them.
+Default nesting remains one, with a maximum of three. There is no new scheduler, reusable-worker
+lifecycle, model routing, workspace isolation system, concurrency cap or family budget here.
+
+## Alternatives and consequences
+
+A tool-owned launcher leaves terminal and SDK behavior divergent. An in-memory delivery flag loses
+results across restart; searching prose for run IDs confuses mentions with delivery. Native-history
+receipts identify persisted context without adding a second acknowledgement store. Run records
+remain the outcome source of truth, while the parent file preserves startup reservations.
+
+The App owns organization delegation and resolves native ancestry for thread routing, tools,
+isolation and connections. Its existing work-budget accounting includes native descendants. Harness
+learns no organizational role or application concept. Native completion records execution outcome;
+it does not certify the child's findings or artifacts.
+
+## Evidence and limits
+
+`subagentService.test.ts` covers selective waits, foreign handles, cancellation, bounded batches and
+recovery windows. Real scripted Pi tests in `conversation.test.ts` cover async delivery, inline
+receipts and interruption during a child question. `runtime.socket.test.ts` exercises the real
+terminal socket, private controls, native execution and child decision routing. RPC and App host
+regressions cover protocol shapes and ancestry. Tests use disposable storage without external
+model requests. These are working-tree changes, not a publication or live-provider acceptance claim.
+
+Verification on 2026-10-18: Harness typecheck, 455 tests (two skipped), unchanged golden fixtures,
+build and standalone proof passed. App typecheck, layer/UI checks, sidecar build, 30 sidecar tests
+and 217 Rust tests passed (one ignored). The renderer suite passed 491 tests and retained its
+pre-existing `PendingRequestDock.test.ts` heading-text assertion failure. No live account or
+user-data-root testing was performed.

package/docs/decisions/ADR-0004-fullscreen-terminal-layout.md

@@ -0,0 +1,49 @@
+---
+id: ADR-0004
+title: Fullscreen terminal layout with a fixed dock
+status: accepted
+created: 2026-10-18
+updated: 2026-10-18
+supersedes: none
+---
+# ADR-0004 — Fullscreen terminal layout with a fixed dock
+
+## Context and decision
+
+The owned terminal drew its transcript and composer as one flowing list on the main screen. With a
+short transcript the composer sat under the last line and moved down as the transcript grew. Harness
+also kept its own scroll offset, mouse regions and paging, which duplicated the viewport Pi already
+provides in fullscreen.
+
+Harness now uses Pi's fullscreen renderer by default. The welcome and transcript form a scroll view
+that fills the terminal; the dock (working line, queue and notices, widgets, editor and status band,
+footer) sits fixed below it. Pi's `tuiMode`, `fullscreenScrollbar`, `fullscreenWheelScrollLines`,
+`fullscreenCopyOnSelect` and `fullscreenExitOutput` settings are read from the account and honoured.
+`tuiMode: "regular"` keeps the flowing layout on the main screen. When fullscreen ends with
+`fullscreenExitOutput: "transcript"`, the rendered conversation is copied into the normal scrollback.
+
+## Consequences
+
+- While fullscreen is running, the transcript is not in the terminal's scrollback. Mouse capture is
+  on, so terminal drag-selection gives way to the application's selection, which copies on release.
+  These are Pi's defaults and remain changeable in settings.
+- Harness no longer owns scroll state, wheel handling or paging. Those come from Pi's viewport and its
+  `tui.altScreen.*` bindings, and the keyboard list shows the scroll keys only in fullscreen.
+- Regular mode has no Harness-managed scroll position; scrolling there belongs to the terminal.
+- When the screen is short, a long notice shows its first rows and scrolls for the rest. The prompt
+  and status are never clipped; the head of a notice stays readable, so the newest line of a long
+  list may need a scroll.
+- Only `transcript` exit output is implemented. Other values write nothing on exit.
+
+## Alternatives considered
+
+Padding the main-screen output to the terminal height also keeps the composer on the last rows for a
+short transcript. It keeps native scrollback, but Harness would still own its scrolling and mouse
+handling, and the composer would scroll away with the terminal's scrollback once the transcript
+overflowed. That was rejected because it keeps the duplicated code this change removes.
+
+## Evidence
+
+The layout is covered by `src/terminal/tui/screen.test.ts`: the dock stays on the last rows as the
+transcript grows and scrolls, regular mode flows in order, and the exit copy is written with its styles
+reset. The PTY verification of the built CLI is recorded in [the terminal reference](../terminal-tui.md).

package/docs/decisions/ADR-0005-app-provided-oauth-clients.md

@@ -0,0 +1,54 @@
+---
+id: ADR-0005
+title: Application-provided OAuth clients for connected apps
+status: accepted
+created: 2026-10-18
+updated: 2026-10-18
+supersedes: none
+---
+# ADR-0005 — Application-provided OAuth clients for connected apps
+
+## Context and decision
+
+Every remote connected app so far authenticated one of two ways: the server registers this app
+dynamically (RFC 7591), or the person registers a client with the provider and pastes its ID and
+secret into Connections. Google's Workspace MCP servers support neither in practice: they have no
+dynamic registration, and requiring every person to create a Google Cloud project before connecting
+Gmail is not a product.
+
+A connection's `oauthClient` now has a third value, `app`: **the application supplies the client**.
+The host does so through one extension point on the harness:
+
+```ts
+export interface AppOAuthClients {
+  ids(): string[]
+  get(catalogId: string): Promise<{ clientId: string; clientSecret?: string } | null>
+}
+```
+
+`HarnessOptions.oauthClients` carries it. Only a connection whose `catalogId` appears in `ids()` can
+use it — a hand-typed connection, a Hub connector recipe, and a plugin template cannot, because none
+of them can name a client the application actually holds. `connections.appClients` reports the ids so
+an application can offer only the connectors it can actually sign in for.
+
+The client is resolved inside `Connections.oauthLoad` and placed in the OAuth state as
+`staticClient`, exactly where a user-registered client goes. `oauthSave` already strips
+`staticClient`, so the client is never written to `connections.json` or the secret store; it is
+re-resolved on each load. Refresh tokens continue to be stored per connection.
+
+## Consequences
+
+- The harness learns no product concept: it knows a catalog entry id, a client, and a sign-in. Which
+  entries an application can serve is entirely the host's answer.
+- A build without a client is a first-class state, not an error: `ids()` is empty, `signIn` refuses
+  with "This connector has no app sign-in in this build", and the application hides those catalog
+  entries instead of offering a dead end.
+- A client secret in a distributed desktop build is extractable, so it is treated as public. The real
+  controls stay Google's consent screen, the requested scopes, and the tool approval gate.
+- One client can serve several catalog entries (five Google servers, one client). Each entry is still
+  its own connection with its own tokens, so signing in to one does not authorize another.
+- The per-user path is untouched: `oauthClient: 'user'` still stores a person's own client in
+  Keychain, and it remains the only route for providers or accounts an application cannot pre-register
+  for.
+- Google's Developer Preview terms, app verification and CASA assessment for restricted scopes are
+  outside this decision; they decide who can use the shipped client, not how it is delivered.