@yadsh/dsh-qa-surface 0.9.0 → 0.11.0

package/lib/types/integration/transcript-reader.d.ts

@@ -0,0 +1,100 @@
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaSessionLogReader } from "../admin/session-log.js";
+import type { QaIntegrationTranscript } from "./contract.js";
+/**
+ * A conversation read warm, for an application that pages through it.
+ *
+ * The projection itself (`transcript.ts`) answers one page from a log. That is
+ * the right shape for a review page opened once and the wrong one for a caller
+ * that follows a cursor: every read of a long chat would load the stored log
+ * and flatten every message in it to hand back the newest fifty, so a bridge
+ * paging through a two-year-old conversation pays for the whole conversation
+ * per page, and pays it again on the next poll.
+ *
+ * What is kept here is the window itself — the newest messages, already
+ * flattened — plus the newest seq below it, which is all the arithmetic a page
+ * needs to be exact. A page is then either served from that window or, when the
+ * window cannot answer for the caller's cursor, read from the log.
+ *
+ * Two things decide whether the window may be trusted:
+ *
+ * - **A chat this process holds is probed in memory.** The Harness is the
+ *   writer, so its in-memory events answer \"has anything been appended?\" with
+ *   no stored read at all, and only the appended events are projected. This is
+ *   the common case: the bridge reads back the chat it just asked in.
+ * - **A chat this process does not hold is trusted for a bounded time.** Nobody
+ *   in this process can append to it, so the window can only be wrong about a
+ *   write from somewhere else sharing the same storage — which no page read can
+ *   distinguish either. The bound is deliberately the same budget the review
+ *   console gives its own transcript cache, so the two answer a reviewer the
+ *   same way.
+ *
+ * A window is never *replaced* by an in-memory snapshot, only extended from it:
+ * a session that outlived a process restart, or a very long one, may hold only
+ * part of its history in memory, and a read that trusted it as the whole log
+ * would answer a page from half a conversation.
+ *
+ * What it costs: at most one window per conversation, and a window is at most
+ * one maximal page — so the memory this keeps is bounded by
+ * {@link QA_INTEGRATION_TRANSCRIPT_CACHE_CHATS} pages of conversation, and a
+ * page a caller would have received anyway. An old chat's *first* read is still
+ * a stored read, and its projection walks back only as far as the window it is
+ * building: the whole log of a long conversation is never flattened to answer a
+ * page of it.
+ */
+/** How long a window is trusted for a chat this process does not hold. */
+export declare const QA_INTEGRATION_TRANSCRIPT_TTL_MS = 30000;
+/** How many conversations keep a warm window. */
+export declare const QA_INTEGRATION_TRANSCRIPT_CACHE_CHATS = 128;
+export interface QaIntegrationTranscriptReaderOptions {
+    /** The deployment's conversations, as the Host reads them. */
+    log: QaSessionLogReader;
+    logger?: PluginLogger;
+    /** Injectable clock, so the trust window is testable without waiting. */
+    now?: () => number;
+    ttlMs?: number;
+    maxChats?: number;
+    /** Ceiling on the messages a window holds; one maximal page by default. */
+    maxMessages?: number;
+}
+export declare class QaIntegrationTranscriptReader {
+    private readonly windows;
+    private readonly log;
+    private readonly logger;
+    private readonly now;
+    private readonly ttlMs;
+    private readonly maxChats;
+    private readonly maxMessages;
+    constructor(options: QaIntegrationTranscriptReaderOptions);
+    /**
+     * One page of a conversation, from the window when the window can answer it.
+     * @param chatId - the conversation; the caller's ownership of it is the
+     *   service's business, and this reader only reads it.
+     * @param query - the caller's exclusive cursor and the page size it wants.
+     * @returns the newest page after the cursor, with its new cursor.
+     */
+    page(chatId: string, query: {
+        readonly after: number;
+        readonly limit: number;
+    }): Promise<QaIntegrationTranscript>;
+    /** One page out of a window: exact, whatever the caller's cursor is. */
+    private pageOf;
+    /**
+     * Fold what the Harness is holding into a window, projecting only the events
+     * the window has not covered yet.
+     * @returns whether the window absorbed the update; false means the delta is
+     *   larger than a whole window, so the log has to answer instead.
+     */
+    private merge;
+    /**
+     * The newest published seq a window has covered, which is also the cursor a
+     * probe is asked from: `undefined` while the window holds nothing, where the
+     * question is "what has this chat published at all".
+     */
+    private covered;
+    /** Read the log and remember what it says, for the pages that follow. */
+    private readLog;
+    /** Keep a bounded number of conversations warm, oldest window first. */
+    private remember;
+}
+//# sourceMappingURL=transcript-reader.d.ts.map

package/lib/types/integration/transcript.d.ts

@@ -0,0 +1,59 @@
+import type { StoredSessionEvent } from "../admin/conversation-log.js";
+import type { QaIntegrationMessage, QaIntegrationTranscript } from "./contract.js";
+/**
+ * Reading a conversation back out of its durable log, for the application that
+ * started it.
+ *
+ * This is deliberately not the admin viewer's projection. That one answers a
+ * reviewer and carries what a review needs — tool calls, ratings, the redaction
+ * policy — none of which an external caller may see or has any use for. What
+ * this projector shares with the rest of the API is the flattening rule
+ * (`messageContentText`): the text a caller reads here is the same text it
+ * would have received as an answer, so the two never disagree about what a
+ * message says.
+ *
+ * Only human prompts and assistant messages are published. Injected context —
+ * identity notes, skill payloads, a slash command's expanded body — is model
+ * input recorded as a user message, and handing it back would show the caller
+ * instructions it never wrote. Tool traffic is model plumbing: the answer is
+ * already the result of it.
+ */
+/** Newest messages one read returns; more than a page is a different tool. */
+export declare const QA_INTEGRATION_MAX_TRANSCRIPT_MESSAGES = 200;
+/**
+ * The newest published messages of a log, and what was left below them.
+ *
+ * This is the primitive both readers are built on, and it walks the events
+ * **newest first**: a page of a hundred-message conversation costs a hundred
+ * messages flattened, not the whole log, which is what makes a long chat's
+ * page cheap. Only the events below the cursor are considered, and the walk
+ * stops as soon as the window is full — the one message after that is enough
+ * to know that more exists, and `below` records its seq.
+ *
+ * @param chatId - the conversation being read; echoed back for correlation.
+ * @param events - the log's events, in any order.
+ * @param query - the cursor (exclusive) and how many messages to cover; the
+ *   cursor is `undefined` for "from the end", which a warm window asks for.
+ * @returns the window, oldest first, and the newest seq left below it.
+ */
+export declare function integrationMessageWindow(chatId: string, events: readonly StoredSessionEvent[], query: {
+    readonly after: number | undefined;
+    readonly cover: number;
+}): {
+    readonly chatId: string;
+    readonly messages: readonly QaIntegrationMessage[];
+    readonly below: number | undefined;
+};
+/**
+ * Project the log into one page of a caller's transcript.
+ *
+ * @param chatId - the conversation being read; echoed back for correlation.
+ * @param events - durable events, in any order.
+ * @param query - the caller's cursor and page size; both are already bounded.
+ * @returns the window with the caller's new cursor.
+ */
+export declare function projectIntegrationTranscript(chatId: string, events: readonly StoredSessionEvent[], query: {
+    readonly after: number;
+    readonly limit: number;
+}): QaIntegrationTranscript;
+//# sourceMappingURL=transcript.d.ts.map

package/lib/types/personal-skills/index.d.ts

@@ -2,8 +2,8 @@ export { QaPersonalSkillError, type QaPersonalSkillErrorReason, } from "./errors
 export { QA_SKILL_TRASH_SUFFIX, resolveSkillRoots, skillDirectory, skillFilePath, type QaSkillRoots, } from "./paths.js";
 export { normalizeAllowedTools, parseSkillFile, serializeSkillFile, skillFileBody, skillNameProblem, toJsonValue, type QaSkillFileContents, type QaSkillFileDraft, type QaSkillFileParse, } from "./skill-file.js";
 export { skillFileBytes, skillRelativeRootProblem, skillRelativeRootSegments, validateSkillDraft, QA_SKILL_DEFAULT_RELATIVE_ROOT, QA_SKILL_DESCRIPTION_MAX, QA_SKILL_ENABLED_BY_DEFAULT, QA_SKILL_FILE_MAX_BYTES, QA_SKILL_MAX_BYTES_MAX, QA_SKILL_MAX_BYTES_MIN, QA_SKILL_MAX_TOOLS, QA_SKILL_NAME_MAX, QA_SKILL_NAME_PATTERN, QA_SKILL_WHEN_TO_USE_MAX, type QaSkillValidationInput, } from "./skill-format.js";
-export { QA_USER_SKILLS_PROVIDER, QA_USER_SKILLS_RANK, QA_USER_SKILLS_SOURCE, createQaUserSkillProvider, } from "./provider.js";
-export { QaPersonalSkills, type QaPersonalSkillContext, type QaPersonalSkillsOptions, type QaStoredSkill, } from "./service.js";
+export { QA_SHARED_SKILLS_RANK, QA_SHARED_SKILLS_SOURCE, QA_USER_SKILLS_PROVIDER, QA_USER_SKILLS_RANK, QA_USER_SKILLS_SOURCE, createQaUserSkillProvider, } from "./provider.js";
+export { QA_SKILL_ADMIN_EDITS_FILE, QaPersonalSkills, type QaPersonalSkillContext, type QaPersonalSkillsOptions, type QaSharedSkillContext, type QaSkillScope, type QaSkillWriteOrigin, type QaStoredSkill, } from "./service.js";
 export { createQaPersonalSkillRemotes, type QaPersonalSkillRemotes, } from "./remotes.js";
 export { QaPersonalSkillsHost } from "./host.js";
 export { QaSkillWatcher } from "./watcher.js";

package/lib/types/personal-skills/paths.d.ts

@@ -20,11 +20,23 @@ export interface QaSkillRoots {
     readonly skills: string;
     /** The canonical directory a removed skill directory is moved into. */
     readonly trash: string;
+    /**
+     * Whether these roots are the deployment-wide store rather than one
+     * account's. The geometry is identical, so the flag travels with the roots
+     * instead of being re-derived from them at every use.
+     */
+    readonly shared: boolean;
 }
 /** Derive and verify every directory the feature touches for one account. */
-export declare function resolveSkillRoots(personalRoot: string, relativeRoot: string): QaSkillRoots;
-/** The directory of one skill, validated against the account's skills root. */
-export declare function skillDirectory(roots: QaSkillRoots, name: string): string;
+export declare function resolveSkillRoots(personalRoot: string, relativeRoot: string, 
+/**
+ * What the boundary refuses to leave, for the message an operator reads.
+ * The same resolution serves an account directory and the deployment-wide
+ * shared root, which have different owners but identical geometry.
+ */
+boundary?: string): QaSkillRoots;
+/** The directory of one skill, validated against the scope's skills root. */
+export declare function skillDirectory(roots: QaSkillRoots, name: string, boundary?: string): string;
 export declare function skillFilePath(roots: QaSkillRoots, name: string): string;
 /** Whether the directory exists at all, without following a symlink. */
 export declare function directoryExists(input: string): boolean;

package/lib/types/personal-skills/provider.d.ts

@@ -7,8 +7,11 @@ import type { QaPersonalSkills } from "./service.js";
  * through the nearest `.git`, which for a personal QA directory inside a larger
  * checkout would climb above the account and mix users together. This provider
  * reads exactly one place — `<cwd>/.dsh/skills` where the cwd is a provisioned
- * `.qa-users/<uuid>` directory — and replaces the filesystem layer inside the
- * QA scope rather than adding a second one beside it.
+ * `.qa-users/<uuid>` directory — and the deployment's shared root beside the
+ * registered workspace, replacing the filesystem layer inside the QA scope
+ * rather than adding a second one beside it. A shared skill is labelled and
+ * ranked distinctly, so a load can tell the deployment's own instructions from
+ * the account's.
  */
 export declare const QA_USER_SKILLS_PROVIDER = "qa-user-skills";
 /** Prompt-visible provenance label for a skill stored in an account directory. */
@@ -18,6 +21,15 @@ export declare const QA_USER_SKILLS_SOURCE = "qa-user";
  * QA scope a personal skill wins a same-named duplicate from any other layer.
  */
 export declare const QA_USER_SKILLS_RANK = 50;
+/** Prompt-visible provenance label for a deployment-wide shared skill. */
+export declare const QA_SHARED_SKILLS_SOURCE = "qa-shared";
+/**
+ * Rank between the personal layer (50) and the project layer (100). A shared
+ * skill is curated for the whole deployment, so it outranks what a checkout
+ * happens to carry — but one account's own copy of the same name still wins,
+ * because that is the layer a person deliberately edited about themselves.
+ */
+export declare const QA_SHARED_SKILLS_RANK = 60;
 /**
  * Build the provider for one registration. The factory runs synchronously
  * during `registerProvider` and all filesystem work stays inside

package/lib/types/personal-skills/service.d.ts

@@ -2,15 +2,48 @@ import type { Context } from "@deepseek-ai/cordis";
 import type { PluginLogger } from "@yadsh/dsh-plugin-log";
 import type { QaSkillDiagnostic, QaSkillDocument, QaSkillDraftInput, QaSkillRemoval, QaSkillSummary, QaSkillToolDescriptor, QaSkillValidation, ResolvedQaSurfaceConfig } from "../types.js";
 import { type QaSkillFileContents } from "./skill-file.js";
+/**
+ * Name of the sidecar that records which skills an administrator wrote. It
+ * sits beside the skill directories, and everything that enumerates skills
+ * ignores dot entries — so the record never becomes a skill and never reaches
+ * the model.
+ */
+export declare const QA_SKILL_ADMIN_EDITS_FILE = ".admin-edits.json";
 /** Per-account identity of the skill storage boundary. */
 export interface QaPersonalSkillContext {
     /** The authenticated account id whose personal root holds these skills. */
     readonly userId: string;
 }
+/**
+ * The deployment-wide store: skills every account may read, which only an
+ * administrator writes. It is resolved against the registered workspace (the
+ * same relative root, a different owner), so the two scopes have identical
+ * geometry and identical path checks.
+ */
+export interface QaSharedSkillContext {
+    readonly shared: true;
+}
+/** Which store a call reads or writes. */
+export type QaSkillScope = QaPersonalSkillContext | QaSharedSkillContext;
+/**
+ * What a save must record about itself beyond the draft.
+ *
+ * `actorId` is the administrator behind an administrator's write. An owner's
+ * own save passes nothing, which clears whatever mark the skill carried: the
+ * stored revision is theirs again, and the badge is a statement about the
+ * bytes on disk rather than a history nobody can act on. Removal takes no
+ * origin because a removed skill has no bytes left to mark — the audit row the
+ * console writes is where that actor is named.
+ */
+export interface QaSkillWriteOrigin {
+    readonly actorId?: string;
+}
 /** One stored skill: its parsed contents plus the facts a DTO needs. */
 export interface QaStoredSkill {
     /** Whether the skill directory itself exists. */
     readonly exists: boolean;
+    /** Whether the skill came from the deployment-wide store. */
+    readonly shared: boolean;
     /** Directory name; the skill's identity for every write. */
     readonly directoryName: string;
     readonly directory: string;
@@ -34,9 +67,9 @@ export interface QaPersonalSkillsOptions {
     readonly onRootDiscovered?: (root: string) => void;
 }
 /**
- * Personal Skills over one account's own directory.
+ * Skills over one directory: an account's own, or the deployment's shared one.
  *
- * The service is the only writer: it derives every path from the account id,
+ * The service is the only writer: it derives every path from the scope,
  * validates a draft before touching the disk, writes `SKILL.md` through a
  * temporary file and a rename, and keeps a removed skill recoverable in the
  * trash beside its skills root. Reading is deliberately permissive — a skill
@@ -49,8 +82,19 @@ export declare class QaPersonalSkills {
     constructor(ctx: Context, options: QaPersonalSkillsOptions);
     /** Whether the feature is available on this deployment at all. */
     get enabled(): boolean;
-    /** Resolve one account's storage roots, or refuse the operation. */
+    /** Resolve one scope's storage roots, or refuse the operation. */
     private rootsFor;
+    /** The deployment's own skills root, below the registered workspace. */
+    private sharedRoots;
+    private requireEnabled;
+    /** The registered workspace every scope is resolved against, or a refusal. */
+    private requireWorkspacePath;
+    /**
+     * The absolute directory a scope reads and writes. The console names it so
+     * an operator can open the same path in a file manager; nothing in the wire
+     * contract can name a path the service did not derive itself.
+     */
+    rootPath(scope: QaSkillScope): string;
     /**
      * Resolve the storage roots a session cwd names. This is the discovery
      * provider's entry point and takes no account token: the cwd itself is the
@@ -58,10 +102,10 @@ export declare class QaPersonalSkills {
      * directory, so no arbitrary directory can name another account's storage.
      */
     private rootsForCwd;
-    /** Every skill of one account, sorted by directory name. */
-    list(context: QaPersonalSkillContext): readonly QaSkillSummary[];
+    /** Every skill of one scope, sorted by directory name. */
+    list(context: QaSkillScope): readonly QaSkillSummary[];
     /** One skill with everything the editor needs. */
-    get(context: QaPersonalSkillContext, name: string): QaSkillDocument;
+    get(context: QaSkillScope, name: string): QaSkillDocument;
     /**
      * Check one unsaved draft without touching storage: the serializer is the
      * one a Save uses and the preserved frontmatter is the stored file's, so the
@@ -69,25 +113,25 @@ export declare class QaPersonalSkills {
      * and the diagnostics carry the operator's own limit (which the browser
      * cannot know). `name` is the stored skill being edited, or null to create.
      */
-    validate(context: QaPersonalSkillContext, name: string | null, input: QaSkillDraftInput): QaSkillValidation;
-    /** Whether one account stores a skill under this name. */
-    has(context: QaPersonalSkillContext, name: string): boolean;
+    validate(context: QaSkillScope, name: string | null, input: QaSkillDraftInput): QaSkillValidation;
+    /** Whether one scope stores a skill under this name. */
+    has(context: QaSkillScope, name: string): boolean;
     /** Create one skill directory and its `SKILL.md`. */
-    create(context: QaPersonalSkillContext, input: QaSkillDraftInput): QaSkillDocument;
+    create(context: QaSkillScope, input: QaSkillDraftInput, origin?: QaSkillWriteOrigin): QaSkillDocument;
     /**
      * Replace one skill's file, preserving the frontmatter fields this editor
      * does not own and moving the whole directory when the name changed.
      */
-    update(context: QaPersonalSkillContext, name: string, input: QaSkillDraftInput): QaSkillDocument;
+    update(context: QaSkillScope, name: string, input: QaSkillDraftInput, origin?: QaSkillWriteOrigin): QaSkillDocument;
     /** Move one skill directory into the trash beside its skills root. */
-    remove(context: QaPersonalSkillContext, name: string, expectedRevision: string | null): QaSkillRemoval;
+    remove(context: QaSkillScope, name: string, expectedRevision: string | null): QaSkillRemoval;
     /**
      * The tool catalog the picker offers. Availability is the QA session's own
      * scope — the deployment's reviewed allow-list — never a suggestion of what
      * a skill may grant: a declared tool the scope excludes stays listed and
      * stays unavailable.
      */
-    tools(context: QaPersonalSkillContext): readonly QaSkillToolDescriptor[];
+    tools(context: QaSkillScope): readonly QaSkillToolDescriptor[];
     /**
      * The skills one session cwd exposes to DSH. A file the parser rejects, or
      * one whose name disagrees with its directory, is reported in the editor and
@@ -99,8 +143,18 @@ export declare class QaPersonalSkills {
      * from every session — not just this account's skills.
      */
     discover(cwd: string): readonly QaStoredSkill[];
+    /** One roots pair's discoverable skills; never throws. */
+    private discoverIn;
+    /**
+     * The deployment's shared root for one cwd-scoped read, or undefined. It
+     * answers undefined when shared skills cannot be resolved at all, and when
+     * the shared root is the root the personal read already covered — a session
+     * pinned to the workspace root would otherwise list everything twice.
+     */
+    private sharedRootsForDiscovery;
     /** Re-read one skill of a session cwd, re-checking the same boundary. */
     read(cwd: string, directoryName: string): QaStoredSkill | undefined;
+    private readFrom;
     private observe;
     private isDiscoverable;
     private availableTools;
@@ -120,7 +174,7 @@ export declare class QaPersonalSkills {
     /** Move a renamed skill's whole directory, resources included. */
     private renameSkillDirectory;
     /** Write one file through a temporary sibling and a rename. */
-    private writeSkillFile;
+    private writeAtomic;
     private trashTarget;
     private assertRevision;
     private summarize;
@@ -132,5 +186,26 @@ export declare class QaPersonalSkills {
      * is still stored, and the deployment needs to see which half broke.
      */
     private refreshCatalog;
+    /**
+     * The administrator marks stored beside one skills root.
+     *
+     * The sidecar is advisory: a mark that cannot be read or written never fails
+     * a save, because losing a badge is a smaller failure than losing an edit.
+     * Each mark names the revision it describes, so a mark whose content has
+     * since changed reports as absent rather than as a claim about the present.
+     */
+    private adminEdits;
+    /** The mark to report for one stored skill: absent unless it still matches. */
+    private adminEditOf;
+    /**
+     * Record one administrator write, or clear the mark when the owner wrote.
+     * `previousName` is the directory the skill had before the write, so a
+     * rename by an administrator moves the mark with the skill instead of
+     * leaving one behind for a name nothing answers to any more.
+     */
+    private rememberWrite;
+    /** Drop the mark of a skill that no longer exists. */
+    private forgetWrite;
+    private writeAdminEdits;
 }
 //# sourceMappingURL=service.d.ts.map

package/lib/types/prompt-notes.d.ts

@@ -14,6 +14,21 @@ export declare const QA_IDENTITY_NOTE = "dsh-qa-surface:user-identity";
 export declare const QA_SOURCES_NOTE = "dsh-qa-surface:structured-sources";
 /** Note name asking the model to name its delegations. */
 export declare const QA_DELEGATION_NOTE = "dsh-qa-surface:delegation-naming";
+/** Note name routing an attached office document to the document pipeline. */
+export declare const QA_DOCUMENTS_NOTE = "dsh-qa-surface:attached-documents";
+/** Note name carrying the deployment's rule about where an answer comes from. */
+export declare const QA_SOURCE_PRIORITY_NOTE = "dsh-qa-surface:source-priority";
+/**
+ * Built-in note texts. Each is the fallback for its settings template
+ * (`notes.*.template`); the placeholders mark the parts the injector
+ * substitutes. Unknown or empty placeholders render as empty text.
+ */
+export declare const QA_IDENTITY_NOTE_TEMPLATE = "{identity}\n\n{instructions}";
+export declare const QA_SOURCES_NOTE_TEMPLATE = "Source provenance is collected automatically from your tool calls; the QA surface lists what it collected beside the answer. Do not append a manual Sources/\u0418\u0441\u0442\u043E\u0447\u043D\u0438\u043A\u0438 bibliography of your own.";
+export declare const QA_SOURCES_FALLBACK_TEMPLATE = "A delegated run whose provider cannot expose tool events must call {reportTool} before finishing.";
+export declare const QA_DELEGATION_NOTE_TEMPLATE = "When you start a background subagent, give the delegation a short vivid name in its description field: two or three words in the user's language that say what the run is for (\u00AB\u0421\u0432\u0435\u0440\u043A\u0430 \u043E\u0442\u0447\u0451\u0442\u043E\u0432\u00BB, \"Log triage\"). The QA surface shows that description as the subagent's display name in the operator's panel and completion notices.";
+export declare const QA_DOCUMENTS_NOTE_TEMPLATE = "A document a chat user attached is a path on disk, not text: read it with the deployment's document pipeline \u2014 `document_inspect` says what a DOCX or PDF is, `document_to_markdown` extracts its text, `document_from_url` stores the text of an attachment that only exists behind a URL. The plain file reader refuses those formats as binary, so that refusal is expected and is not a hint to go looking for the file somewhere else. When the pipeline itself refuses a path, report the refusal and the path it named instead of trying another reader.";
+export declare const QA_SOURCE_PRIORITY_NOTE_TEMPLATE = "Answer from the source that owns the question: read what the conversation and its attachments already carry, then search the product documentation and ask the domain expert, and only then look in memory. Recalled memory is background from earlier sessions \u2014 a miss there is not evidence that no source exists, and it is not where a document, a page or a product fact should be looked up.";
 export interface QaIdentityRenderInput {
     /** The owner's account address; the one fact accounts always provide. */
     readonly email: string;
@@ -98,6 +113,28 @@ export declare class QaPromptNotes {
      * the difference between a panel of hashes and a panel of tasks.
      */
     private delegationNotes;
+    /**
+     * Which reader an attached document belongs to.
+     *
+     * A chat user's `.docx` or `.pdf` arrives as a path into the attachment
+     * store, and the reader the model reaches for by habit answers `binary file`
+     * for it. That answer is a fact about the format, not about the file being
+     * missing, and a run that reads it as the second one searches the workspace
+     * for a document it was already handed. The note names the pipeline and both
+     * halves of the trap: the plain reader's refusal is expected, and the
+     * pipeline's own refusal is a report to make, not a reason to try a third
+     * reader.
+     */
+    private documentsNotes;
+    /**
+     * Where an answer comes from, in this deployment's terms.
+     *
+     * The memory plugin's own skill says the same thing in its own words, but a
+     * persona may be the entire system prompt and a skill is read only once the
+     * model decides to reach for it: the rule that outlives both is the one
+     * delivered as a note, ahead of the first tool call that would break it.
+     */
+    private sourcePriorityNotes;
     private carriedKey;
     /**
      * The text one note already carries in this agent's conversation. Process

package/lib/types/provenance/document-preview.d.ts

@@ -0,0 +1,28 @@
+import type { DocumentsFace } from "@yadsh/dsh-documents";
+import type { QaDocumentPreview } from "../types.js";
+import { type QaAllowedFileRequest } from "./file-preview.js";
+/** Look up the document subsystem a sibling Host plugin published. */
+export type DocumentsLookup = () => DocumentsFace | undefined;
+export interface QaDocumentPreviewRequest extends QaAllowedFileRequest {
+    /** The document pipeline, resolved per call so a late provider still counts. */
+    readonly documents: DocumentsLookup;
+    readonly sessionId: string;
+    /** Bytes of the rendered PDF the panel accepts before it gives up. */
+    readonly maxBytes: number;
+}
+/**
+ * Render one Word document as a PDF for the files panel.
+ *
+ * The conversion is the document pipeline's own — the same runtime, providers
+ * and limits the `document_*` tools use — reached through the face that plugin
+ * publishes for its Host siblings; a deployment without the pipeline installed
+ * refuses with `unsupported` rather than growing a second converter here. The
+ * input path passes the same containment check the panel's other reads use, so
+ * a preview cannot read what a listing could not reach.
+ *
+ * The resolved root the check opened is handed to the pipeline as well (§26.2):
+ * an uploaded Word file lives in the attachment store, and a pipeline that is
+ * not told about that root refuses the file this check just accepted.
+ */
+export declare function previewConvertibleDocument({ documents, sessionId, maxBytes, ...file }: QaDocumentPreviewRequest): Promise<QaDocumentPreview>;
+//# sourceMappingURL=document-preview.d.ts.map

package/lib/types/provenance/file-preview.d.ts

@@ -1,11 +1,13 @@
-import type { QaSourceFilePreview } from "../types.js";
+import type { QaSourceFilePreview, QaWorkspaceFile, QaWorkspaceListing } from "../types.js";
 /**
  * Coarse, wire-safe preview refusal codes. They ride the shared
  * `(reason: <code>)` marker, so the panel can tell "this file is not in a
  * directory the QA read policy opens" from "this file is gone" instead of
  * telling every audience that a present file moved away.
  */
-export type QaSourcePreviewReason = "outside-roots" | "not-evidence" | "unavailable";
+export type QaSourcePreviewReason = "outside-roots" | "not-evidence" | "unavailable"
+/** The panel has no way to render this format at all. */
+ | "unsupported";
 /** Host refusal whose wire message carries the coarse reason marker. */
 export declare class QaSourcePreviewError extends Error {
     readonly reason: QaSourcePreviewReason;
@@ -39,6 +41,32 @@ export interface QaSourceFilePreviewRequest {
     readonly maxBytes: number;
     readonly maxMarkdownRenderBytes: number;
 }
+/** A file request the panel may make: the chat's own tree or a shared root. */
+export interface QaAllowedFileRequest {
+    readonly filePath: string;
+    /** The attested chat's cwd: the anchor a relative request resolves against. */
+    readonly cwd: string;
+    readonly sharedReadOnlyRoots?: readonly string[];
+    readonly attachmentRoot?: string;
+}
+/** One resolved file that passed the read policy. */
+interface QaAllowedFile {
+    /** The path as the caller spelled it, canonicalized against the chat cwd. */
+    readonly canonicalPath: string;
+    /** Its real filesystem path, once symlinks are followed. */
+    readonly canonical: string;
+    readonly size: number;
+}
+/**
+ * Resolve one requested file and check it against the readable roots.
+ *
+ * The roots mirror the per-user execution guard — the chat's own cwd plus the
+ * deployment's shared read-only directories and the attachment store — so a
+ * file the model was explicitly allowed to read stays readable in the panel,
+ * while anything else is refused with the coarse `outside-roots` reason
+ * instead of leaking whether it exists.
+ */
+export declare function resolveAllowedFile({ filePath, cwd, sharedReadOnlyRoots, attachmentRoot, }: QaAllowedFileRequest): Promise<QaAllowedFile>;
 /**
  * Read one evidence file from the roots the QA read policy opens.
  *
@@ -50,4 +78,43 @@ export interface QaSourceFilePreviewRequest {
  * refused as foreign evidence.
  */
 export declare function readSourceFilePreview({ sourcePath, cwd, isEvidence, sharedReadOnlyRoots, attachmentRoot, maxBytes, maxMarkdownRenderBytes, }: QaSourceFilePreviewRequest): Promise<QaSourceFilePreview>;
+/** One directory request from the files panel. */
+export interface QaWorkspaceListRequest {
+    /** The directory to list, absolute or relative to the chat cwd. Empty = root. */
+    readonly dirPath: string;
+    readonly cwd: string;
+    /** Children one listing carries; the rest is reported as truncated. */
+    readonly maxEntries: number;
+}
+/** The advertised type of one file: by extension, else opaque bytes. */
+export declare function mediaTypeOf(path: string): string;
+/**
+ * List one directory of the chat's own workspace.
+ *
+ * Browsing is deliberately narrower than previewing: the panel walks the tree
+ * the chat works in, never the deployment's shared read-only roots, so the
+ * visitor cannot enumerate the deployment from the rail. The request is
+ * confined with the same realpath-then-contain check the preview uses, which
+ * is what makes `..` and symlinked directories harmless.
+ * Symlinked children are omitted rather than followed: a link inside the
+ * workspace may point anywhere, and a tree that silently leaves the chat's
+ * directory is worse than one that hides a link.
+ */
+export declare function listWorkspaceDirectory({ dirPath, cwd, maxEntries, }: QaWorkspaceListRequest): Promise<QaWorkspaceListing>;
+/** One file request from the files panel. */
+export interface QaWorkspaceFileRequest extends QaAllowedFileRequest {
+    readonly maxBytes: number;
+    readonly maxMarkdownRenderBytes: number;
+}
+/**
+ * Read one file of the chat's workspace for the panel: text when it decodes as
+ * UTF-8, base64 bytes when it does not, so a document the agent produced can be
+ * offered for download while a note previews inline.
+ *
+ * Unlike the source preview this is not bound to recorded evidence — the panel
+ * browses what the chat's workspace holds — but it is bound to the same roots
+ * the model itself may read.
+ */
+export declare function readWorkspaceFile({ filePath, cwd, sharedReadOnlyRoots, attachmentRoot, maxBytes, maxMarkdownRenderBytes, }: QaWorkspaceFileRequest): Promise<QaWorkspaceFile>;
+export {};
 //# sourceMappingURL=file-preview.d.ts.map

package/lib/types/qa-tools/catalog.d.ts

@@ -8,7 +8,7 @@ import type { QaToolDescriptor } from "./types.js";
  *
  * Bump it whenever the catalog's tool set or their schemas change.
  */
-export declare const QA_TOOL_CATALOG_VERSION = "1";
+export declare const QA_TOOL_CATALOG_VERSION = "3";
 /** One QA tool reports the activation state of whichever agent calls it. */
 export interface QaToolsSelfcheckDeps {
     readonly catalogVersion: string;