@yadsh/dsh-qa-surface 0.1.1 → 0.3.0

package/capability-policy.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "description": "Reviewed capabilities in the shipped default QA tool allow-list.",
+  "tools": []
+}

package/compatibility.json

@@ -1,14 +1,28 @@
 {
   "deepseekHarness": {
     "channel": "next",
-    "range": ">=0.1.1-rc.2 <0.2.0",
-    "testedReleases": ["0.1.1-rc.2"],
+    "range": ">=0.1.5-rc.2 <0.2.0",
+    "testedReleases": ["0.1.5-rc.2"],
     "requiredClientFeatures": [
       "shell.overlay",
-      "connection.api.sessions",
+      "remote.session.selectModel",
+      "remote.agentPresets.select",
+      "uiConversation.binding",
       "sessions.binding",
       "settingsScope",
-      "webServer.register"
+      "settings.onboarding list-slot shadowing",
+      "webServer.register",
+      "typert.remote",
+      "agentPresets.composedPreset",
+      "permissionPresets.set",
+      "tools.restrict",
+      "tools.guard",
+      "tools.register",
+      "session.event-extension",
+      "agent.turn-stopping",
+      "agent.currentInitiator",
+      "systemPrompt.section",
+      "workspaceRegistry.get"
     ]
   },
   "node": "^22.19.0 || >=24.0.0"

package/cordis.patch.yml

@@ -7,3 +7,14 @@
         route:
           path: /qa
           matchChildren: true
+        ui:
+          showReset: false
+        lockdown:
+          enabled: true
+          sandboxMode: read-only
+          approvalPolicy: never
+          permissionPreset: qa-read-only
+          allowSessionReset: false
+          toolPolicy:
+            mode: allow-list
+            allow: []

package/docs/ARCHITECTURE.md

@@ -2,22 +2,64 @@
 
 The Host half validates the Loader configuration, registers the `qa-surface`
 settings namespace and owns one narrow GET/HEAD route for the configured QA
-path. Published DSH `0.1.1-rc.2` returns 404 for unknown frontend paths, so the
+path. Published DSH releases return 404 for unknown frontend paths, so the
 route redirects navigation through the canonical `/` index with an encoded
-same-origin path marker. It does not serve HTML, create another server, replace
-the frontend fallback, or touch API/plugin routes. The browser removes the
+same-origin path marker. It also exposes one typed
+`secureSession(sessionId)` operation whose policy is read only from Host
+settings. The entry delegates that operation to `QaPolicyAdmission`
+(`secure-session.ts`), the Host-side admission boundary. It does not serve
+HTML, create another server, replace the frontend fallback, or touch
+API/plugin routes. The browser removes the
 marker and restores the requested path with `history.replaceState` before
-route matching. The Host creates no sessions.
+route matching. The Host creates no sessions itself.
 
 The browser half registers `QaSurface` in the root-scoped `shell.overlay` list.
 `QaRouteController` keeps that entry dormant outside the configured path and
 reversibly observes `pushState`, `replaceState` and `popstate`.
 
-`QaSessionController` is the only DSH session-coupled module. It uses
+`QaSessionController` is the only browser-side DSH session-coupled module. It uses
 `connection.api.sessions.create/selectModel` for creation policy and the public
-`SessionFace` for prompt, cancel and snapshots. `QaTranscriptAdapter` projects
-those snapshots to plugin-local messages, excluding reasoning, tool arguments,
-tool results, system context and raw failures.
+`SessionFace` for prompt, cancel and snapshots; the shared client contracts and
+the idle state live in `client/types.ts`. Its supporting modules are pure
+helpers: `client/wait-for.ts` waits on observable stores, `client/chat-index.ts`
+(`QaChatIndex`) keeps the browser-local chat index and persisted active
+session in storage, and `client/attestation.ts` parses Host reason markers and
+validates proofs against the deployed lockdown config. `QaTranscriptAdapter`
+projects session snapshots to plugin-local messages. "New chat" enters a
+draft that materializes an attested session only when the first prompt is
+sent, and the chat list orders by the host's `updatedAt`. The log is
+append-only and there is no truncation seam, so regeneration prompts a
+hidden instruction and projects the follow-up turns as variants of one
+question; the same projection flattens tool activity into the sources
+drawer (web targets, searches, files read). Subagent delegation, when the
+deployment opts it in, renders launches and settlement notices inline, and
+the agents drawer opens a child session as a read-only live transcript: the
+binding skips attestation and every send path stays closed. By default it excludes
+reasoning, tool arguments and tool results. When explicitly enabled, it
+correlates assistant blocks, paired tool results, running calls and turn
+timings into one plugin-local work group per turn; `QaWorkGroup` owns
+disclosure state and collapses the group when the turn completes. System
+context and raw failures remain excluded.
+
+In locked mode the Host operation verifies immutable session composition,
+refuses to adopt a non-QA session with user history, validates the named
+permission preset, installs `ToolRestriction.allow`, installs an agent-scoped
+monotonic execution guard, selects the permission preset, and returns only a
+sanitized proof. The controller remains non-writable until every proof field
+matches its Host-delivered config and repeats the check before prompt
+admission. No private RPC handler, slash command, direct provider API, or DSH
+core patch is used.
+
+This narrows a QA agent's effective session/tool policy, but a route overlay on
+a shared privileged Host is not an authorization boundary for other DSH
+clients. Strong isolation requires a dedicated process/profile, restricted
+identity and network boundary.
+
+All interaction colors come from the company interaction palette
+("Цвета взаимодействия"), defined once as the `QA_BRAND_PALETTE` object at the
+top of `styles.ts` and emitted as `--dsh-qa-*` custom properties on the
+overlay root; surfaces and typography keep using the themed `--dsw-alias-*`
+tokens so light and dark hosts stay coherent.
 
 The overlay locks document scrolling and contains keyboard focus while active.
 It does not locate AppFrame through generated CSS classes and does not dispose

package/docs/COMPATIBILITY.md

@@ -1,12 +1,13 @@
 # Compatibility
 
-| Plugin version | Tested DSH release | Required public contracts                                                                             |
-| -------------- | ------------------ | ----------------------------------------------------------------------------------------------------- |
-| 0.1.x          | 0.1.1-rc.2         | `shell.overlay`, `settingsScope`, `connection.api.sessions`, `sessions.binding`, `webServer.register` |
+| Plugin version | Tested DSH release | Required public contracts                                                                                                                                                              |
+| -------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 0.1.x          | 0.1.5-rc.2         | `shell.overlay`, Typert remote, `agentPresets.composedPreset`, `permissionPresets`, agent-scoped `tools.restrict/guard`, `workspaceRegistry`, session/model APIs, `webServer.register` |
 
 DSH is developer-preview software. Compatibility-sensitive calls are isolated
 in `QaSessionController`, `QaTranscriptAdapter`, `QaConfigController` and
-`QaRouteController`. The Host navigation adapter also works around this tested
+`QaRouteController`; Host lockdown coupling is isolated in
+`QaSurface.secureSession`. The Host navigation adapter also works around this tested
 release's exact-index static serving: `/qa` is redirected through `/`, then the
 client restores the original pathname. Missing settings fall back to default
 browser config; missing required client services prevent the browser plugin

package/docs/CONFIGURATION.md

@@ -7,12 +7,193 @@ rules are:
   `/`, `/api` or `/plugins`;
 - `fixed` requires `fixedSessionId`;
 - `provider` and `model` are either both absent or both present;
-- `maxContentWidth` is an integer from 480 through 1600;
+- `maxContentWidth` is an integer from 480 through 1600 and caps the
+  user-resizable transcript/composer width; each QA route persists its chosen
+  width in browser storage;
 - duplicate/blank suggested questions are removed;
 - approval and question policies are fixed to safe blocking behavior;
-- reasoning display cannot be enabled in the 0.1.x MVP.
+- reasoning and tool details are opt-in through `ui.showReasoning` and
+  `ui.showToolActivity`; enable them only where those contents are appropriate
+  for the QA audience;
+- accounts default to disabled; when enabled, `sessionTtlDays` is an integer
+  from 1 through 365, and other users' chats stay hidden unless an admin view
+  explicitly enables `accounts.showOtherUsersChats`;
+- lockdown defaults to enabled and requires a non-empty permission preset;
+- the preset must resolve on the Host to exactly `read-only` + `never`;
+- permission, slash-command, settings, rename, delete and arbitrary-open
+  capability flags cannot be enabled;
+- `showReset` requires the independent `allowSessionReset` opt-in;
+- the tool policy is an allow-list; unknown configured tool names fail closed.
+  A name only resolves while its tool is actually mounted: MCP tools
+  (`mcp__<server>__*`) exist only while their server is reachable, so keep
+  them out of the allow list on hosts that cannot reach the server. Tools
+  mounted by an agent preset live in that preset's ancestor scope; the Host
+  validates and restricts the complete agent-scoped view, not just globals.
+
+## Pinning chats to a directory
+
+By default a QA chat is created against the Host working directory. Two
+mutually exclusive pins anchor every new chat (and its subagents) to the
+deployment's own directory:
+
+- `session.cwd: "D:/qa-docs"` - an absolute directory used directly as the
+  session cwd; no registration needed. Attestation compares the session's
+  recorded cwd case- and separator-insensitively on Windows.
+- `session.workspaceId: "<uuid>"` - a registered DSH workspace (created in
+  the web UI or via the workspace API; the id is a generated uuid, not the
+  path). Sessions attach to the workspace, so they group under it in the
+  host UI. When the id does not resolve, attestation refuses with
+  `reason: workspace-unavailable` instead of an opaque mismatch.
+
+With `lockdown.enforceFixedWorkspace: true` (the default) a chat created
+anywhere else refuses to attest, so the QA audience can never pull the
+assistant out of the pinned directory.
 
 Browser persistence stores only the DSH session id under
-`<storageKey>:v1:<route>:session`. Transcript content, credentials and tool
+`<storageKey>:v1:<route>:session`, plus — when `ui.showSessionList` is
+enabled — a per-browser chat index under `<storageKey>:v1:<route>:chats`
+(session ids only, capped at 50). Transcript content, credentials and tool
 results remain in the Host-owned DSH Session and are never copied to browser
 storage.
+
+When either work-detail flag is enabled, the QA transcript groups reasoning,
+intermediate assistant progress, and tool rows by DSH turn. Running work is
+expanded. Completed work is collapsed behind a duration summary and can be
+reopened; each tool row can separately reveal its formatted input and output.
+These controls change presentation only and never widen the Host allow-list.
+
+The browser cannot override lockdown settings. Before binding and immediately
+before every prompt, it requests a Host attestation for the selected session.
+Any unproved agent preset, workspace, model, permission bundle or tool policy
+disables Send with the generic message `Настройки помощника недоступны.`
+Detailed mismatch facts are written only to Host logs; the
+browser console additionally prints one line with a stable coarse reason code
+(`reason: unknown-tools`, `workspace-unavailable`, `composition-mismatch`, `permission-preset`,
+`adoption-refused`, `proof-mismatch` or `attestation-failed`) plus an operator
+hint, so a refused surface can be diagnosed without Host log access.
+
+The built-in branding, controls, status messages and accessibility labels are
+Russian. The default quick questions are rendered directly above the composer
+only while the current chat is empty. Set `suggestedQuestions: []` to hide
+them, or provide a deployment-specific list to replace them.
+
+When adding tools, update the deployment's reviewed capability inventory as
+part of the same change. The package's
+[default inventory](../capability-policy.json) is intentionally empty, matching
+the default `toolPolicy.allow`.
+
+## Structured sources
+
+The `sources` block controls provenance independently from Activity rendering.
+The defaults collect parent and subagent results, persist a `qa/sources` event,
+hide discovery-only candidates, group visible evidence by kind, and promote at
+most five substantive `web_search` results when no fetch occurs. URL tracking
+parameters and overlapping file ranges are normalized during deduplication.
+
+`sources.filePreview` is a narrow read capability, not a filesystem browser.
+The Host serves only a path already present in the attested session's canonical
+evidence bundle, resolves symlinks with `realpath`, rejects root escape, and
+applies `maxBytes` plus `maxMarkdownRenderBytes`. Markdown uses the client's
+HTML-free renderer; relative links and executable raw HTML are not activated.
+
+Set `sources.display.showOriginBadges: true` while auditing inheritance. Local
+subagent sources carry run/session origins automatically. An opaque provider
+can call the internal `qa_report_sources` tool; if it does not, and
+`markIncompleteOpaqueRuns` remains enabled, the bundle is explicitly marked
+incomplete.
+
+See [Structured sources migration](SOURCES-MIGRATION.md) before removing an
+older prompt-authored bibliography convention.
+
+## Accounts and the QA gate
+
+`accounts.enabled: true` mounts the login/registration gate in front of the
+QA surface and turns on server-side session ownership:
+
+- The store lives at `$DSH_HOME/qa-accounts.json` (created on first use). It
+  holds scrypt password hashes, a persisted HMAC secret for the account
+  tokens, and the session ownership map. The path is not configurable and no
+  secret ever reaches `describe()`.
+- `accounts.allowRegistration` (default true) controls self-service signup
+  in the gate; the first account ever registered becomes `admin`.
+- `accounts.sessionTtlDays` (default 30) is the account token lifetime. The
+  token is an HMAC-signed value the browser keeps in `localStorage`; logout
+  or expiry returns the browser to the gate, and the Host re-derives the
+  identity on every attestation.
+- `accounts.showOtherUsersChats` (default false) lets admins load and display
+  chats owned by other QA accounts. It has no effect for ordinary users.
+- Session ownership is first come, first served: attesting or bulk-claiming
+  an unowned session binds it to the caller's account (this is how existing
+  per-browser chats migrate on the first login). Sessions owned by another
+  user are refused with the coarse `session-owned-elsewhere` reason and
+  hidden from the sidebar; admins are not refused.
+- Manage accounts with the bundled CLI (no hand-editing of the JSON):
+
+  ```sh
+  qa-accounts list
+  qa-accounts add user@example.com --password-stdin --role user
+  qa-accounts set-role user@example.com admin
+  qa-accounts disable user@example.com   # blocks logins, revokes live tokens
+  qa-accounts revoke user@example.com    # invalidates every issued token
+  ```
+
+  `disable` bumps the account's token version, so all outstanding tokens die
+  server-side; `enable` requires a fresh sign-in. After a secret rotation
+  suspicion, `revoke` is the single-step response.
+
+- Honest boundary: accounts identify QA users and gate the QA surface and
+  its remotes. They do not fence the harness: every QA user also holds the
+  host launch-token cookie, with which the full root UI stays technically
+  reachable. Keep the network scoping advice from the deployment kit.
+
+## Entry redirect
+
+`entry.redirectNonLoopback: true` (default) injects one script into the
+served root `index.html`: browsers whose URL host is not loopback
+(`localhost`, `127.0.0.1`, `::1`, `*.localhost`) continue into the QA route,
+so LAN visitors never see the full harness root. The check is client-side on
+`location.hostname` on purpose - behind a local reverse proxy every request
+looks loopback to the server. The navigation hand-off `/?__dsh_qa_route=…`
+is never redirected (that would loop), `/?ui=admin` bypasses the redirect
+and is remembered for the browser, and `/?ui=qa` clears the bypass.
+
+`entry.cookieBootstrap: true` (default) additionally lets the `/qa` route
+itself bootstrap the host cookie: a browser without any `dsh-auth-` cookie is
+sent to the one-time `/?token=…` exchange (relative redirect, token resolved
+from the host connection service) before the marker hand-off. This makes the
+transparent entry work without the deploy proxy; with the proxy in front,
+either side may perform the exchange and the other becomes a no-op.
+
+## Configuration channel over the LAN
+
+The browser normally reads the effective configuration from the Host-owned
+`qa-surface` settings namespace. DSH pins settings RPCs to loopback, so a
+browser served over the LAN always sees that namespace as unavailable. In
+that case the client calls the plugin's `qaSurface/describe` Host Remote and
+uses the returned effective configuration; a rejected call falls back to the
+client defaults with the same `unavailable` status as before. Only one
+describe request runs per page load, and a settled answer survives scope
+updates — the namespace (when readable) stays the authority and keeps
+delivering live changes.
+
+Host-side enforcement never depended on the browser's read path: `secureSession`
+attestation re-derives everything from the Host-owned configuration on every
+bind and every prompt.
+
+## Skill catalog scope
+
+The deployment's agent preset controls which skills the QA assistant sees.
+The shipped `qa-research` preset mounts the skill filesystem with
+`includeDefaultRoots: false`: project-root skills (for example the harness
+checkout's own `.dsh/skills`) and user-home skills stay out of the catalog,
+and skills enter only through plugin providers or an explicit
+`customSkillDirs` list in the preset. Keep the QA catalog to exactly the
+skills the audience is meant to use.
+
+## Deleting chats
+
+The sidebar delete control removes a chat from this browser's index only;
+the Host session stays on disk. Deleting the chat that is currently open
+continues in a fresh attested session when `lockdown.allowSessionReset` is
+enabled. There is no Host session-deletion API in DSH 0.1.x for the plugin
+to call.

package/docs/SOURCES-MIGRATION.md

@@ -0,0 +1,28 @@
+# Structured sources migration
+
+`dsh-qa-surface` now treats `QaTurnSources` as the only canonical provenance
+model. Assistant prose is never parsed for a `Sources` or `Источники` section,
+and the default `sources.legacy.parseAssistantSourcesBlock` remains `false`.
+
+## Deployment steps
+
+1. Keep the QA agent's existing read-only retrieval tools in
+   `lockdown.toolPolicy.allow`.
+2. Leave `sources.collect.persistTurnEvent: true` so completed turns append a
+   replayable `qa/sources` snapshot.
+3. Remove prompt instructions that ask the assistant to manually write a
+   bibliography. The plugin contributes its own scoped guidance after QA
+   attestation.
+4. For an opaque subagent provider, expose the inherited
+   `qa_report_sources` tool and ask the provider to call it before completion.
+   Local DSH subagents require no reporting prompt.
+5. Start with `sources.display.showDiscovered: false`; enable it only for
+   provenance debugging.
+
+Historical sessions without `qa/sources` remain readable: the Host reconstructs
+bundles from durable structured tool metadata when available. Historical
+assistant-authored source prose remains ordinary answer text and is not trusted
+as provenance.
+
+The `qa/sources` event is a required plugin-owned session event. Keep
+`dsh-qa-surface` loaded in any Host that restores sessions containing it.

package/docs/SOURCES-PROVENANCE-AUDIT.md

@@ -0,0 +1,88 @@
+# Sources / provenance implementation audit
+
+Date: 2026-09-11  
+Pinned DSH development API: `0.1.5-rc.2`
+
+This note records the Phase 0 findings for
+`SPEC-dsh-qa-surface-sources-provenance.md`. It is intentionally tied to the
+versions in this repository rather than to DSH `master`.
+
+## Existing QA data path
+
+- `QaSessionController` binds the client `UiConversation` snapshot.
+- `QaTranscriptAdapter` reads the `chat.legacy` projection.
+- The former Sources drawer inferred one row from selected tool names and raw
+  arguments. It counted a search query as a source and did not retain turn,
+  line-range, evidence, or origin data.
+- `ToolResultNode.meta` is available in the client projection. DSH documents it
+  as the tool-private, JSON-safe result presentation payload persisted on the
+  corresponding `tool/result` event.
+
+## Structured metadata available in the pinned version
+
+`@deepseek-ai/dsh-tools` exports the provider-neutral result shapes needed by
+the first implementation slice:
+
+- `ReadResultView`: `path`, numbered `lines`, `offset`, `totalLines`, `lang`;
+- `SearchResultView`: grouped grep matches or path discovery;
+- `WebSearchResultView`: structured `sources[]` and truncation state;
+- `WebFetchResultView`: final redirect URL, status, and truncation state;
+- generic call `FileLocation` values.
+
+The QA extractor layer therefore consumes `ToolResultNode.meta` first and uses
+tool arguments only as a compatibility fallback for direct read/fetch calls.
+It does not parse assistant prose.
+
+## Replay and persistence
+
+The completed implementation rebuilds collectors from persisted
+`tool/call`/`tool/result.meta` events and writes one materialized `qa/sources`
+snapshot at `agent/turn-stopping`. The type is declaration-merged into
+`SessionEventMap`.
+
+The pinned DSH exports its live `KNOWN_SESSION_EVENT_TYPES` set. As already
+demonstrated by the repository's `dsh-session-scope` plugin, registering the
+plugin event there is the supported compatibility mechanism when
+`Session.append` cannot mark an extension event ignorable. Registration is
+effect-scoped and removed on plugin disposal. A Host that owns sessions with
+these events must load `dsh-qa-surface`, just as it must load any plugin that
+owns a required durable event vocabulary.
+
+## Subagent lifecycle
+
+The pinned `@deepseek-ai/dsh-subagent` does expose process-local
+`subagent/start` and `subagent/end` events. Both carry `runId`, `provider`, child
+session `id`, and `local`; the terminal payload additionally carries
+`stopReason` and optional `lastAssistantMessage`. Scoped dispatch is keyed by
+the delegating parent.
+
+The Host now maintains that lineage registry, uses the child header or causal
+`AgentRegistry.currentInitiator()` attribution, bubbles nested local-child
+sources to the original root turn, and retains run/session origin fields.
+Opaque providers can call `qa_report_sources`; an unreported opaque run sets
+`complete=false` with an `incompleteOrigins` entry.
+
+## File preview reuse
+
+The new `readSourceFile` Remote is limited to evidence paths in canonical
+bundles, re-attests the session, resolves both root and target with `realpath`,
+rejects traversal/symlink escape, caps bytes, and exposes no write/list API.
+
+## Implemented scope
+
+- canonical source and turn-bundle types;
+- URL/path/range normalization;
+- extractor registry with read, grep discovery, web search, and web fetch;
+- evidence promotion, deduplication, ranking, and a default display threshold;
+- bounded structured web-search promotion (five results by default);
+- Host per-turn collectors and materialized/replayable `qa/sources` events;
+- local and nested subagent inheritance plus opaque-provider reporting;
+- structured Jira, Confluence, knowledge and reported-source adapters;
+- one canonical snapshot used by grouped drawer and answer footer;
+- source details, origin/partial badges and completeness state;
+- safe local-file preview, rendered/raw Markdown, range chips and exact raw
+  line highlighting;
+- configuration and tests for the feature surface.
+
+Optional inline citation rendering (SPEC Phase 5) remains intentionally out of
+the MVP, as specified.