@xingular/harness 0.1.7 → 1.1.1

package/docs/study/tui-resource-browser.md

@@ -0,0 +1,78 @@
+# TUI resource browser study
+
+Status: source study completed, 2026-10-22. Runtime acceptance is recorded separately.
+
+## Current gaps
+
+`/components` browses registry resources and compares them with the latest variant head;
+it does not enumerate the session loader. `/plugins` controls attachments and trust while
+`/hub` installs into separate destinations. The OpenTUI palette accepts slash commands only;
+`skillCompletions` exists but has no OpenTUI caller. `$name` expansion works on submission.
+
+## Local reference evidence
+
+| Reference | Inspected source | Adopted pattern | Harness adaptation |
+|---|---|---|---|
+| OMP | `external/omp/packages/tui/src/overlays/extensions/extension-dashboard.ts`, `inspector-model.ts` | Inventory, owner/provider and inspector in one browser | Inspect before changing state; existing loader and gate remain authoritative |
+| OpenCode | `external/opencode/packages/tui/src/component/dialog-skill.tsx`, `dialog-mcp.tsx`, `command-palette.tsx` | Searchable skills, explicit loading/errors, actionable MCP states | Use inserts a draft; cached MCP checks are labelled with dates |
+| Kimi CLI | `external/kimi-cli/src/kimi_cli/ui/shell/slash.py`, `mcp_status.py` | Skills in help and server/tool relationships | Link relationships inside the browser rather than requiring a second command |
+| OpenHands | `external/openhands/src/components/features/plugins/build-plugins-view-model.ts`, `routes/skills-plugins.tsx` | Reconcile catalog, installed and ambient resources | Preserve distinct owners/paths for duplicate names; runtime proves availability |
+| DeepSeek | `external/deepseek-harness/apps/web/tests/expected/plugin-manager/manager.expected.md` | Descriptive built-in settings and explicit plugin details | Foundation descriptions and configuration links; no web card layout in the terminal |
+| Harness² | `external/harness2/harness2/core/tree.py` | Explicit editable surface and eight components | Read-only c1–c8 inspection with pinned/latest versions |
+
+These are bounded source observations, not claims of runtime visual equivalence.
+The other checkouts (Orca, OpenHands SDK, smolagents, SWE-agent) are not primary terminal
+layout references for this change. No reference implementation is copied into the runtime.
+
+Inspected checkout revisions (source observations above):
+
+- OMP: `63a7ba5dcc74cca2cb0ecb710770eb756102035d`
+- OpenCode: `94bc5662c4ad3b983276021ce9df7f0bc1b11d5c`
+- Kimi CLI: `9ab1286b8fe4e6bcd116949a27ce5e0ac3389c82`
+- OpenHands: `9057a57f4a7b5a74e93989090edaffc21e3554ff`
+- DeepSeek Harness: `687f282e8625c6b8d11ff58211a90524be2e4317`
+- Harness²: `1cfe254e8d25b15f37048c3730134686abe60335`
+
+## Navigation decision
+
+`/harness` is the main browser. `/skills`, `/plugins`, `/connections` (`/mcp`) and `/tools`
+are direct section shortcuts; `/hub` selects Discover, `/components` selects Library.
+Installed includes locally present resources and labels their effective state. Discover uses
+the existing Hub with All/Community/Official filters. Built-in and foundation are different axes:
+foundation is a runtime ownership boundary; built-in is provenance.
+
+## Responsive wireframes
+
+Wide (inner width >=88):
+
+```text
+Harness > Skills       Installed | Discover       All | Community | Official
+Overview        Search skills...             | Selected skill
+Foundation      Review        Available now  | Description, owner, origin
+Variant         Review        Library only   | Availability, path, scope
+Skills          Another       Disabled       | Inspect / Use / Manage
+Plugins                                      |
+Connections                                  |
+Tools                                        |
+Library                                      |
+```
+
+Compact (80-column terminal):
+
+```text
+Harness > Skills [choose section]
+Installed | Discover
+Search skills...
+Review                    Available now
+Another                   Library only
+Enter details; Tab controls; Ctrl+F search
+```
+
+At 40 columns, controls truncate or wrap into the bounded frame. Detail replaces the list;
+Escape returns without losing query/selection. Wide and compact modes share the same state.
+
+## Acceptance journeys
+
+Find and invoke a skill; import a local bundle; install a Hub skill and add it to a future
+variant; review/trust a local plugin; configure local/remote MCP; inspect web_fetch ownership;
+compare pinned/latest variant files; recover from offline/empty discovery and failed sign-in.

package/docs/system-prompt-design.md

@@ -0,0 +1,196 @@
+# System-prompt design: a fixed foundation with an adapting harness
+
+> Terminology (PROP-0009): this draft's *foundation* is the architecture spec's foundation, and its *adapting surface* is a **variant**. See [Foundation and variants](architecture/00-overview.md#foundation-and-variants).
+
+Status: **design draft** (working notes; not yet an ADR). Feed: the arm study
+([study/00-index.md](study/00-index.md), arms 01 and 10). The compiler is
+`src/prompt/compile.ts` — the only place model instructions are assembled
+(repo rule). Everything below constrains that file and its inputs.
+
+## 1. The problem in one sentence
+
+Harness² core adapts the tree **that generates** the prompt over time
+(Propose–Probe–Compose adopts new tree versions), while providers pay for every
+byte changed in the *already-sent* text — so the prompt must have a part that
+adapts **only by version supersession** and a part that never adapts at all.
+The design is about making those two parts orthogonal.
+
+## 2. Three planes, three owners, three change rates
+
+| Plane | What | Owner | Versioned how | Change cadence |
+|---|---|---|---|---|
+| **Foundation** | The non-negotiable core: caller identity framing, session mechanics (native history, context-update protocol, the hidden context message semantics), tool-gate expectations, top-level defaults | package (`src/prompt/compile.ts` template text) | code, released with the package | rare (release-grade edits only) |
+| **Adapting surface** | The tree's always-on files and on-demand components: `systemprompt.md` (c1), `guardrails.md` (c2), `memory.md` (c3), `tool_guidance.md` (c4), plus skills (c6), sub-agents (c5), scripts (c7), plugins (c8) | the tree, per scope (`src/tree/surface.ts`); superseding versions only (`src/tree/store.ts` — **a tree is never edited, only supersedes**) | tree versions, pinned per run and recorded | per refinement adoption or person edit |
+| **Dynamic context** | Per-run changing state: selected `references`, the `wiki` section, app `active work`; future: skill-catalog deltas, volatile date/cwd | app + harness at launch | recorded per run in the pack/context (`pack.delivery`) | every session / every turn |
+
+The stable prefix = Foundation ∪ Adapting-surface text ∪ (static) tool
+sections, compiled once per session; dynamic text rides exclusively in the
+hidden `xingular-context` message appended to native history
+(`src/prompt/compile.ts:326-345`). This is the existing split; the design
+decisions below make it deliberate under harness² drift.
+
+## 3. The fixed foundation: what it contains
+
+Foundation text is written as **contract prose about mechanics**, never about
+the task:
+
+- **Identity/handshake**: where the caller's identity and role come from
+  (application-supplied `HostSection`s; the harness's own c-file text never
+  names the application).
+- **Session mechanics**: what native history is; that app-origin context
+  updates are *context, not requests*; what a listed section *replaces*; that
+  withdrawn sections are no longer current. Today this is `CONTEXT_GUIDANCE` —
+  the one string that **must be byte-stable forever** because it explains the
+  channel every later message uses.
+- **Tool ordination**: one-line statement that tool availability and gates are
+  fixed for the session (the tool manifest section), plus the standing
+  "policy_missing ⇒ ask" framing from the governance arm — as prose once, not
+  per tool.
+- **Boundary statements**: answer-free refinement boundaries, redaction, and
+  account isolation stated here (they are the harness's *own* rules, not
+  work-specific advice).
+
+Rules for anything entering this plane:
+
+1. No volatile values — no date, cwd, env, model settings. The omp lesson is
+   specific: even one participant-dependent tail line in the prefix invalidates
+   everything cached after it (`external/omp/.../date-cwd-reminder.ts:1-12`;
+   our roadmap item 9). If such a value is ever needed, it goes into an
+   app-origin dynamic section or a first-user-turn injection, never the prefix.
+2. No task facts or work guidance — those belong to the adapting surface
+   (`memory.md`, skills) or dynamic context (`references`, wiki). A foundation
+   sentence that names a workflow is an adapting-layer idea Deferred.
+3. Template-only text, deterministic rendering: no timestamps, no
+   randomization; identical inputs produce identical bytes — a compile test.
+
+## 4. The adapting surface: how harness² evolution stays cache-legible
+
+The refinement loop edits only the surface the prompts declare editable
+(`PI_SURFACE.alwaysOn` + `skillDir`/`subagentDir`/`scriptDir`/`pluginDir`,
+`src/tree/surface.ts:58-90`), and each adoption **supersedes a version** rather
+than mutating anything a running session might hold.
+
+Cache-level consequences to keep:
+
+1. **The prefix may change only at known events**: package version bump
+   (Foundation edit), tree adoption (adapting surface supersession), toolset
+   change (providers attached/detached at `capabilities.freeze`). Every one of
+   these is already recorded per run (tree fingerprint, pack
+   `systemSectionIds`), which makes both the *event* and the *delta* auditable →
+   measurable against real requests with the App's cache probe.
+2. **Adoption is atomic, gradual in effect**: a session launched before an
+   adoption keeps its pinned version (runs pin one tree version), so an
+   adoption invalidates only newly launched sessions. Amplification of
+   optimization: never re-write a tree file `.md` *to keep it the same*
+   ("Files you do not touch are inherited unchanged").
+3. **Cut-to-pay budget discipline inside the adapting surface**:
+   `alwaysOnMax = 24_000` characters with its reason string
+   (every token competes with the agent's own output budget). Proposals must
+   add *component* (skill/script/subagent) before *prose* (c1–c4 text), the
+   economics harness² states explicitly (`external/harness2/.../prompts.py:129-146`).
+4. **INV/DOM split maps onto components** (arm 10): INV edits (how the agent
+   works) may shape c1, c4, c6 procedures and c7 scripts; DOM edits (practitioner
+   knowledge) may shape c3 `memory.md` and c6 skills. Neither dimension touches
+   the Foundation plane or the session-protocol prose; a composer that wanted
+   to rewrite `CONTEXT_GUIDANCE` could never reach it — it is not on the
+   editable surface.
+
+## 5. Ordering: derivable, not incidental
+
+`SECTION_ORDER` today (`src/prompt/compile.ts:27`) fixes where each class of
+text sits:
+
+```
+identity/role (app, ~<25) · systemprompt c1 (25) · guardrails c2 (40) ·
+memory c3 (45) · [references: dynamic 50] · subagents c5 (64) · scripts c7 (66)
+· [wiki: dynamic 80] · tool guidance + manifest c4 (90) · context-updates
+guidance (suffix)
+```
+
+Design deltas, already on the roadmap (T1-1):
+
+- an **ordering contract** with numeric-declaration semantics like dsh's
+  (order, then name tie-break; duplicate ids throw; scoped shadowing; a
+  `complete` section replacing the rest `external/deepseek-harness/.../system-prompt/src/index.ts:131-179`)
+- a **dynamic allowlist** (`BUILT_IN_DYNAMIC` = references, wiki; plus app
+  sections marked `dynamic: true`, `compile.ts:428`) — the single mechanism
+  that decides stable vs updated.
+
+Tool guidance as *prose* (c4) and tool *schema* (manifest) both stay in the
+prefix: their input is the session's toolset, which is frozen at launch, so
+they are stable for the session regardless of tree state.
+
+## 6. The dynamic plane: one channel, dated sections
+
+Everything changing within a session travels in `xingular-context` messages:
+content = currently-current dynamic sections; snapshots recorded per file
+(`deliveredSnapshot`), so the next update lists **only what changed** — a
+supersede/repercussion protocol rather than a rebuild. Future members of this
+plane, in priority order:
+
+- skill-catalog deltas (name + capped description) when a tree adoption happens
+  between sessions of the same app (roadmap K1/T1-14 — as long as it stays a
+  delta channel, not a second copy of the tree),
+- volatile date/cwd as an app-origin section (only if a caller actually needs
+  it; measure with the cache probe first).
+
+## 7. Validation gates for prompt text (anti-drift machinery)
+
+From arm 04/10, the harness² rules that turn prompt-writing conventions into
+machine checks, adoptable as tree-validation tests (roadmap item 6):
+
+- always-on prose references a skill ⇒ the trigger line exists
+  (`surface.ts` already carries `triggerLine`/`autotriggerFile` — verify
+  enforcement coverage in `validate()`);
+- no template-brace syntax in always-on files (they are rendered, not
+  templated — `{{` kills the run upstream);
+- every referenced script on the run-shape exists (`scriptRef` regex already
+  compiles; test both directions);
+- a redacted-equivalent rule for `memory.md`: facts yes,
+  procedures-with-audit-trail no ("workspace fact" framing from harness²'s
+  DOM guidance, arm 06/M1).
+
+Anti-drift lint (foundation level): a compile test asserting the stable prefix
+contains no volatile markers (today's date surface: none — keep it tested).
+
+## 8. What this means in practice, file by file
+
+| File | Who writes it | In refinement? | Cache effect |
+|---|---|---|---|
+| `systemprompt.md` (c1) | seed + person/rekeeper edits | yes (INV) | prefix rewrite on adoption |
+| `guardrails.md` (c2) | seed + person; autotrigger host for skills | yes (INV largely) | prefix rewrite on adoption |
+| `memory.md` (c3) | refinement/sections; the Wiki feeds facts in, not the reverse | yes (DOM) | prefix rewrite on adoption |
+| `tool_guidance.md` (c4) | seed + INV-edits | yes (INV) | prefix rewrite on adoption |
+| `skills/<name>/SKILL.md` | composition; trigger text patched in c2 too? never *silently* — the trigger line lands in the same edit | yes (both) | zero bytes until invoked |
+| `sub_agents/<name>/AGENT.md` | composition | yes | zero bytes (own context) |
+| `scripts/*`, `plugins/*` | person or invoker; person trusted | yes (c7 only; c8 behind trust) | zero bytes (they act, not prompt) |
+| `CONTEXT_GUIDANCE` + identity/role prefix text | package only | **no — Foundation**, out of all proposer surfaces | changes only at release |
+
+## 9. Invariants checklist (for CI and for reviewers)
+
+1. Only `src/prompt/compile.ts` assembles model instructions; sessions use
+   `sessionLaunch`, terminals use `compile` + `render`.
+2. The stable prefix has: no volatile values; no task facts; template
+   determinism; byte-stability in absentia of imports/adoption/toolset change.
+3. Dynamic text travels only in `xingular-context` messages, and those may
+   never be vouched for as *user* intent (their framing keeps saying so).
+4. Tree changes: new version supersedes; the budget cap and the harness²
+  -validation rules hold; `keep_base`/unchanged files inherit untouched.
+5. The Foundation plane is not in any editable surface; the adapting surface
+   never references Foundation mechanics as editable.
+6. Answer-free boundaries stay: no rubric/score/verdict text may ride the
+   dynamic channel into a refinement improver or selector (`refine/evidence.ts`
+   still guards every evidence folder).
+
+## 10. Open questions
+
+1. Should the tool manifest (static part) be moved *before* guardrails/memory,
+   so c-file edits invalidate a shorter cache story? (Provider differences —
+   Anthropic head-breakpoint placement vs OpenAI prefix-style; measure with
+   probe-channel script.) — prototype behind the App's cache probe before deciding.
+2. Does the Wiki pointer section belong in the dynamic plane even when empty
+   (today: omitted until a note exists — `wiki` section cut rules in
+   `compile.ts`, `wiki` 80)?
+3. Skill-catalog deltas: cold-start semantics for apps that launch sessions
+   against a recently-superseded tree — decide the *delta channel* shape from
+   two measurement runs before embedding anything.