@yadsh/dsh-qa-surface 0.15.7 → 0.16.0

package/lib/types/types/policy.d.ts

@@ -0,0 +1,54 @@
+export type QaSessionPolicy = "browser-persistent" | "new-on-load" | "fixed";
+export type QaSandboxMode = "read-only" | "workspace-write";
+export type QaApprovalPolicy = "never";
+export type QaToolPolicyMode = "allow-list";
+/**
+ * How the QA tool catalog is attached. `all` attaches the whole catalog once
+ * the activation skill loads; the field is reserved so a future grouped or
+ * searched mode needs no config redesign.
+ */
+export type QaToolActivationMode = "all";
+/**
+ * How a tool policy `ask` resolves on an attested QA agent. `blocked` refuses
+ * the call with the surface's own reason; `interactive` parks it until the
+ * operator answers in the QA view.
+ */
+export type QaApprovalInteraction = "blocked" | "interactive";
+/**
+ * How a user-questions request resolves on an attested QA agent. `unsupported`
+ * refuses the ask outright; `interactive` answers it from the QA view.
+ */
+export type QaQuestionInteraction = "unsupported" | "interactive";
+/**
+ * What a deployment may write for the question seam. `enabled` is accepted as
+ * the spelling of `interactive` a feature request asked for; the resolved
+ * config carries one name only.
+ */
+export type QaQuestionInteractionInput = QaQuestionInteraction | "enabled";
+/** The operator's answer to one parked tool call. */
+export type QaApprovalDecision = "allowed-once" | "rejected";
+/** One answered question; `custom` is free text, and may accompany `selected`. */
+export interface QaQuestionAnswerItem {
+    readonly id: string;
+    readonly selected: readonly string[];
+    readonly custom?: string;
+}
+/**
+ * Authorization inside QA Surface. It is deliberately independent of a QA
+ * subrole: an admin may work as any analyst profile while still holding the
+ * administrative permissions, and a reviewer answers conversations without
+ * being able to manage accounts.
+ */
+export type QaAccountRole = "user" | "reviewer" | "admin";
+/** Administrative permissions a role grants; see `admin/permissions.ts`. */
+export type QaPermission = "users.read" | "users.manage" | "roles.read" | "roles.manage" | "conversations.read.all" | "conversations.read.own" | "conversations.delete" | "reviews.read" | "reviews.write" | "analytics.read" | "audit.read" | "settings.manage"
+/** Write access to skill files, personal and deployment-wide. */
+ | "skills.manage"
+/**
+ * What the domain experts wrote into their durable memory. Reading is split
+ * from correcting because a reviewer is the one who notices a remembered
+ * inaccuracy in an answer, and an answer the expert keeps getting wrong is
+ * the reviewer's business even though the fix is not.
+ */
+ | "memory.read" | "memory.manage";
+//# sourceMappingURL=policy.d.ts.map

package/lib/types/types/quality.d.ts

@@ -0,0 +1,100 @@
+/** A user's verdict on one assistant message. Binary by design. */
+export type QaFeedbackRating = "positive" | "negative";
+/**
+ * Optional negative-feedback reasons. The list is short on purpose: asking for
+ * a precise cause at rating time costs more answers than it buys insight, and
+ * a reviewer classifies the hard cases afterwards.
+ */
+export type QaFeedbackReason = "incorrect" | "instruction_not_followed" | "missing_information" | "outdated_information" | "tool_issue" | "too_verbose" | "too_short" | "other";
+/** One user's rating of one assistant message. */
+export interface QaMessageFeedback {
+    readonly id: string;
+    readonly conversationId: string;
+    readonly messageId: string;
+    readonly userId: string;
+    readonly rating: QaFeedbackRating;
+    readonly reasons?: readonly QaFeedbackReason[];
+    readonly comment?: string;
+    readonly createdAt: string;
+    readonly updatedAt?: string;
+}
+/** The rating fields a browser may write; identity and time are Host-owned. */
+export interface QaMessageFeedbackInput {
+    readonly rating: QaFeedbackRating;
+    readonly reasons?: readonly QaFeedbackReason[];
+    readonly comment?: string;
+}
+/**
+ * One rating a browser still holds locally: a verdict given while the surface
+ * had no way to file it, replayed by the harvest. Reasons never ride along —
+ * the browser's map only ever stored the thumbs.
+ */
+export interface QaFeedbackHarvestEntry {
+    readonly conversationId: string;
+    /** The durable log position, exactly as a live rating carries it. */
+    readonly messageId: string;
+    readonly rating: QaFeedbackRating;
+}
+/** What one harvest write did; the counts answer for the whole batch. */
+export interface QaFeedbackHarvestResult {
+    /** Ratings the Host stored now. Replaying the same batch stores none. */
+    readonly recorded: number;
+    /** Entries the Host already held a rating for, left as they were. */
+    readonly present: number;
+    /** Entries refused: not the caller's conversation, or unusable. */
+    readonly rejected: number;
+}
+/** Review workflow state of a conversation or one of its messages. */
+export type QaReviewStatus = "unreviewed" | "in_review" | "reviewed" | "needs_followup";
+/**
+ * Reviewer taxonomy, grouped the way the spec groups it. Issue ids stay flat so
+ * aggregations never depend on walking a tree in the browser.
+ */
+export type QaQualityIssueType = "answer.incorrect" | "answer.incomplete" | "answer.hallucination" | "answer.request_not_followed" | "answer.poor_formatting" | "answer.communication" | "context.missing_conversation" | "context.missing_knowledge" | "context.outdated_knowledge" | "tool.wrong_selection" | "tool.should_have_been_used" | "tool.bad_arguments" | "tool.failure" | "tool.unavailable" | "skill.missing" | "skill.wrong" | "skill.not_followed" | "skill.prompt_policy" | "access.missing_capability" | "access.excessive_capability" | "other";
+export type QaQualitySeverity = "minor" | "major" | "critical";
+/** Where a reviewer thinks the fix belongs; the loop's change target. */
+export type QaRemediationTarget = "prompt" | "skill" | "tool" | "knowledge" | "role" | "model" | "product_ux" | "user_misunderstanding" | "unknown";
+/** One reviewer result. `needs_followup` keeps the item in the queue. */
+export interface QaConversationReview {
+    readonly id: string;
+    readonly conversationId: string;
+    readonly messageId?: string;
+    readonly reviewerId: string;
+    readonly status: "reviewed" | "needs_followup";
+    readonly issues: readonly QaQualityIssueType[];
+    readonly severity: QaQualitySeverity;
+    readonly notes?: string;
+    readonly target?: QaRemediationTarget;
+    readonly suggestedAction?: string;
+    readonly createdAt: string;
+    readonly updatedAt?: string;
+}
+/** A reviewer's write; ids, author and first-seen time are Host-owned. */
+export interface QaConversationReviewInput {
+    readonly conversationId: string;
+    readonly messageId?: string;
+    readonly status: "reviewed" | "needs_followup";
+    readonly issues: readonly QaQualityIssueType[];
+    readonly severity: QaQualitySeverity;
+    readonly notes?: string;
+    readonly target?: QaRemediationTarget;
+    readonly suggestedAction?: string;
+}
+/** Why a conversation entered the review queue. */
+export type QaReviewReason = "negative_feedback" | "manual" | "tool_failure" | "automatic";
+export type QaReviewPriority = "low" | "normal" | "high";
+/** One queue row: a conversation needing attention, with its derived state. */
+export interface QaReviewQueueItem {
+    readonly conversationId: string;
+    readonly messageId?: string;
+    readonly reason: QaReviewReason;
+    readonly priority: QaReviewPriority;
+    readonly status: QaReviewStatus;
+    readonly assignedReviewerId?: string;
+    /** ISO time of the signal that put the item in the queue. */
+    readonly raisedAt: string;
+    readonly reviewerId?: string;
+    readonly reviewId?: string;
+    readonly feedbackId?: string;
+}
+//# sourceMappingURL=quality.d.ts.map

package/lib/types/types/session.d.ts

@@ -0,0 +1,382 @@
+import type { QaTurnSources } from "../provenance/types.js";
+import type { QaArtifactView } from "./documents.js";
+import type { QaCommandActivity, QaSlashView } from "./slash.js";
+export interface QaSourceFilePreview {
+    readonly path: string;
+    readonly content: string;
+    readonly size: number;
+    readonly truncated: boolean;
+    readonly markdown: boolean;
+    readonly renderableMarkdown: boolean;
+    readonly document?: QaDocumentPreview;
+}
+/**
+ * A file the panel renders by conversion rather than by bytes: the document
+ * pipeline turned a Word file into PDF, and the browser shows that PDF.
+ */
+export interface QaDocumentPreview {
+    readonly kind: "pdf";
+    readonly base64: string;
+    readonly mime: "application/pdf";
+    readonly name: string;
+    readonly bytes: number;
+}
+/** One directory entry of a chat's own workspace, as the files panel browses it. */
+export interface QaWorkspaceEntry {
+    readonly name: string;
+    readonly type: "file" | "directory";
+    readonly size: number | null;
+}
+/**
+ * One directory of the chat's workspace. `path` is the canonical form of the
+ * directory as requested — the chat root itself is the empty string — so the
+ * panel can build a breadcrumb without another round trip.
+ */
+export interface QaWorkspaceListing {
+    readonly path: string;
+    readonly entries: readonly QaWorkspaceEntry[];
+    /** More children existed than one listing carries. */
+    readonly truncated: boolean;
+}
+/**
+ * One file of the chat's workspace: decoded text when it reads as UTF-8, base64
+ * bytes when it does not. The panel needs both — documents the agent produced
+ * are binary, while notes and transcripts preview as text.
+ */
+export interface QaWorkspaceFileChunk {
+    readonly path: string;
+    readonly size: number;
+    readonly offset: number;
+    readonly version: string;
+    readonly base64: string;
+    readonly done: boolean;
+}
+export interface QaWorkspaceFile {
+    readonly path: string;
+    readonly size: number;
+    readonly truncated: boolean;
+    readonly markdown: boolean;
+    readonly renderableMarkdown: boolean;
+    readonly mime: string;
+    /** Present when the file decoded as text; absent for binary content. */
+    readonly text?: string;
+    /** Present when the file is not text; base64 of at most the byte cap. */
+    readonly base64?: string;
+}
+/** Host-attested facts required before the QA composer may become writable. */
+export interface QaLockdownProof {
+    readonly chatAccess?: import("../chat-sharing/types.js").QaChatAccess;
+    readonly sessionId: string;
+    /** Last inherited event in an ordinary fork; absent on an original chat. */
+    readonly inheritedThroughSeq?: number;
+    readonly enabled: boolean;
+    readonly agentPresetMatches: boolean;
+    readonly workspaceMatches: boolean;
+    readonly modelMatches: boolean;
+    readonly sandboxModeMatches: boolean;
+    readonly approvalIsNever: boolean;
+    readonly permissionPreset: string;
+    readonly toolPolicyLoaded: boolean;
+    readonly toolAllowList: readonly string[];
+}
+export interface QaUserMessage {
+    readonly id: string;
+    readonly role: "user";
+    readonly text: string;
+    /** `pending` is a browser-only optimistic row until the Host emits it. */
+    readonly status: "pending" | "committed";
+    readonly timestamp?: number;
+    readonly images?: readonly QaImageView[];
+    /** Durable files the user attached to this message, in prompt order. */
+    readonly files?: readonly QaFileView[];
+    /**
+     * Chat owner's display name, set only for an admin reading a foreign
+     * chat; the owner themself sees their messages unlabeled.
+     */
+    readonly author?: string;
+}
+/** Browser-only user row shown while the Host prepares the accepted turn. */
+export type QaPendingUserMessage = Omit<QaUserMessage, "status"> & {
+    readonly status: "pending";
+};
+export type QaMessage = QaUserMessage | {
+    readonly id: string;
+    readonly role: "assistant";
+    readonly text: string;
+    readonly status: "streaming" | "committed" | "failed";
+    readonly timestamp?: number;
+    /**
+     * Position of this answer in the session's durable event log. Feedback is
+     * keyed to it: a rating survives a replay, a reload and a role change,
+     * while the browser's own message id does not.
+     */
+    readonly seq?: number;
+    /** Final text of a completed turn with a durable fork boundary. */
+    readonly forkable?: boolean;
+    /** Host turn this answer belongs to; groups regenerations into variants. */
+    readonly turn?: number;
+    /**
+     * Files this turn produced, in the order the tools reported them. The
+     * answer is the place a produced document is handed over: without these
+     * cards the file exists only as a path in a paragraph, and a reader who
+     * does not know the files tab concludes nothing was made.
+     */
+    readonly artifacts?: readonly QaArtifactView[];
+    /** Canonical evidence snapshot shared with this answer's source drawer. */
+    readonly sources?: readonly QaSource[];
+    readonly sourcesComplete?: boolean;
+    readonly incompleteSourceOrigins?: QaTurnSources["incompleteOrigins"];
+    /** Host-recorded response timing, present on finalized messages only. */
+    readonly stats?: {
+        /** step start → final message. */
+        readonly durationMs: number;
+        /** step start → first token; null when no token delta was recorded. */
+        readonly ttftMs: number | null;
+        /** Estimated from visible text (≈4 chars/token) over the generation window. */
+        readonly tokensPerSecond: number | null;
+    };
+} | {
+    readonly id: string;
+    readonly role: "system";
+    readonly text: string;
+    readonly status: "info" | "error";
+    readonly timestamp?: number;
+    /**
+     * Set on a human command row. Commands stay out of the model
+     * conversation, so this projection is the only trace the user sees.
+     */
+    readonly command?: QaCommandActivity;
+    /** Collapsible settlement row (subagent finished/stopped/failed). */
+    readonly notice?: {
+        readonly title: string;
+        readonly body: string;
+        /** Muted correlation line above the body (task name, session id). */
+        readonly meta?: string;
+    };
+} | {
+    readonly id: string;
+    readonly role: "work";
+    readonly turn: number;
+    /**
+     * "error" marks a turn the host ended with a provider failure; "stopped"
+     * marks one the user ended, whose answer is a prefix rather than a reply.
+     */
+    readonly status: "running" | "complete" | "error" | "stopped";
+    readonly startedAt?: number;
+    readonly endedAt?: number;
+    readonly items: readonly QaWorkItem[];
+};
+export type QaWorkItem = {
+    readonly id: string;
+    readonly kind: "reasoning" | "progress";
+    readonly text: string;
+    readonly status: "running" | "complete";
+} | {
+    readonly id: string;
+    readonly kind: "tool";
+    readonly name: string;
+    readonly label: string;
+    readonly summary: string;
+    readonly input: string | null;
+    readonly output: string | null;
+    readonly status: "running" | "ok" | "error" | "stopped";
+    /** Durable child id, present on subagent launch calls that started one. */
+    readonly subagentId?: string;
+    readonly startedAt?: number;
+    readonly endedAt?: number;
+};
+export type QaSessionPhase = "idle" | "creating" | "ready" | "running" | "reconnecting" | "blocked" | "error";
+/** Transitional UI name; the drawer now consumes the canonical source object. */
+export type QaSource = import("../provenance/types.js").QaSourceReference;
+/** Raster formats the attachment path accepts (mirrors the host contract). */
+export type QaImageMediaType = "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+/** One image pending in the composer, browser-owned until the prompt lands. */
+export interface QaImageDraft {
+    readonly kind: "image";
+    readonly id: string;
+    readonly mediaType: QaImageMediaType;
+    readonly name: string;
+    /** Canonical base64 of the image bytes, without the data: URL prefix. */
+    readonly data: string;
+    /** Local object URL for the preview thumbnail. */
+    readonly previewUrl: string;
+}
+/**
+ * One file pending in the composer. The bytes stay in the browser until the
+ * prompt is sent: an image can ride the prompt inline, but a file must be
+ * staged through the Host upload route first and then cited by its receipt.
+ */
+export interface QaFileDraft {
+    readonly kind: "file";
+    readonly id: string;
+    readonly name: string;
+    readonly bytes: number;
+    /** Verbatim payload; a pasted blob is a File built from the pasted text. */
+    readonly blob: Blob;
+}
+/** Anything the composer may hold before the prompt is sent. */
+export type QaAttachmentDraft = QaImageDraft | QaFileDraft;
+/** A durable image attached to a sent message. */
+export interface QaImageView {
+    readonly attachmentId: string;
+    readonly mediaType: QaImageMediaType;
+    /** Browser-local thumbnail URL, present only on an optimistic message. */
+    readonly previewUrl?: string;
+}
+/**
+ * A durable file attached to a sent message. The browser never reads these
+ * bytes back (the attachment route serves images); the row shows the handle
+ * the model resolves, and the Host keeps the verbatim copy.
+ */
+export interface QaFileView {
+    readonly attachmentId: string;
+    readonly name: string;
+    readonly bytes: number;
+}
+/** A subagent transcript opened read-only from the agents panel. */
+export interface QaSubagentView {
+    readonly id: string;
+    readonly title: string;
+}
+/**
+ * One tool call waiting for the operator. The browser lists these over its own
+ * remote and answers them one by one; nothing here is answered automatically.
+ */
+export interface QaPendingApproval {
+    readonly id: string;
+    /** The chat the request belongs to: a delegated child asks under its root. */
+    readonly sessionId: string;
+    readonly toolName: string;
+    /** The reason the composed gate gave for asking, when it gave one. */
+    readonly reason: string | null;
+    readonly createdAt: number;
+    /** True when a delegated child of the chat made the call. */
+    readonly delegated: boolean;
+}
+/**
+ * One question waiting for the operator, normalized for the form the QA view
+ * renders. The protocol fields are the harness user-questions contract; absent
+ * ones become explicit nulls so the browser never branches on undefined.
+ */
+export interface QaPendingQuestionItem {
+    readonly id: string;
+    readonly question: string;
+    readonly header: string | null;
+    readonly detail: string | null;
+    readonly options: readonly QaPendingQuestionOption[];
+    readonly multiSelect: boolean;
+}
+export interface QaPendingQuestionOption {
+    readonly label: string;
+    readonly description: string | null;
+}
+/**
+ * One user-questions request parked for the operator. A single request carries
+ * every question the model asked in one call, so the card is a form with a
+ * pager, not a list of independent prompts.
+ */
+export interface QaPendingQuestion {
+    readonly id: string;
+    /** The chat the request belongs to. */
+    readonly sessionId: string;
+    readonly questions: readonly QaPendingQuestionItem[];
+    readonly createdAt: number;
+}
+/**
+ * One message that waits for the agent's next turn. Rows the Host already
+ * admitted carry their durable occurrence id, which is what a queue operation
+ * addresses; a row still in flight carries a browser id and edits nothing.
+ */
+export interface QaQueueRow {
+    readonly id: string;
+    /** Short single-line text for the strip; newlines are folded away. */
+    readonly preview: string;
+    /** Full text to edit, or null when the row is not plain text. */
+    readonly text: string | null;
+    /** Attachments the row carries besides its text. */
+    readonly attachments: number;
+    /** Set for a local row the Host queue has not echoed back yet. */
+    readonly sending: boolean;
+}
+/** What the queue strip may ask the Host to do with one waiting message. */
+export type QaQueueOperation = "edit" | "remove" | "steer";
+/**
+ * What `qaSurface/queueStatus` answers: how much of the deployment's request
+ * ceiling is in use right now. The Host counts the chats whose agent is running
+ * a turn, so the load is read where the whole of it is visible rather than
+ * guessed from one browser's view of the stand.
+ */
+export interface QaQueueStatus {
+    /** The configured ceiling; 0 means the deployment sets none. */
+    readonly limit: number;
+    /**
+     * Turns answering at the moment of the read, this visitor's own included —
+     * the stand cannot tell a place it owes someone from one it owes you.
+     */
+    readonly active: number;
+    /** Whether one more turn fits; false while no ceiling is set. */
+    readonly full: boolean;
+}
+export interface QaSessionState {
+    readonly chatAccess?: import("../chat-sharing/types.js").QaChatAccess;
+    readonly phase: QaSessionPhase;
+    readonly sessionId: string | null;
+    /**
+     * Identity of the chat the surface is showing. Unique across every chat the
+     * page has opened — a controller that is re-created for a new chat is handed
+     * a new identity, so a component keyed by it cannot carry one chat's composer
+     * text into another. It is taken only when the chat changes: a draft that
+     * creates its session on the first prompt keeps its key, because the composer
+     * holds an unsent question in component state, and remounting it on the new
+     * session id would throw that text away before the Host has accepted
+     * anything. `0` means no chat — see `QA_SESSION_IDLE_STATE`.
+     */
+    readonly chatKey: number;
+    readonly messages: readonly QaMessage[];
+    /** Immediate send feedback, kept outside the durable transcript. */
+    readonly pendingMessage: QaPendingUserMessage | null;
+    readonly error: string | null;
+    /**
+     * An owner-authorized historical chat whose recorded composition no longer
+     * matches the deployment. Its transcript remains visible, but no Host
+     * operation may be issued through this binding.
+     */
+    readonly compatibilityReadOnly?: boolean;
+    readonly canSend: boolean;
+    readonly canStop: boolean;
+    /**
+     * Messages waiting for the next turn, oldest first. Sending while the agent
+     * runs lands here instead of in the transcript, so the strip beside the
+     * composer is the only place the user can still see them.
+     */
+    readonly queue: readonly QaQueueRow[];
+    /** Whether a queue operation may be issued on this binding right now. */
+    readonly canEditQueue: boolean;
+    /** Bumped whenever this browser's chat index changes (add/forget). */
+    readonly chatsRevision: number;
+    /** Tool-derived sources of the current chat (web targets and files read). */
+    readonly sources: readonly QaSource[];
+    readonly sourcesComplete: boolean;
+    readonly incompleteSourceOrigins: QaTurnSources["incompleteOrigins"];
+    /** Set while the bound session is a subagent watched from the panel. */
+    readonly viewingSubagent: QaSubagentView | null;
+    /** Tool calls parked for the operator's answer, oldest first. */
+    readonly approvals: readonly QaPendingApproval[];
+    /** Question requests parked for the operator's answer, oldest first. */
+    readonly questions: readonly QaPendingQuestion[];
+    /**
+     * Set when a send was held back because the stand is already answering as
+     * many questions as it allows. The question never left the browser, so this
+     * is the whole of what the visitor is told about it; the surface answers with
+     * the request-ceiling dialog and the composer keeps the draft. Named apart
+     * from `queue`, which is the same chat's list of waiting messages.
+     */
+    readonly requestQueue: QaQueueStatus | null;
+    /** Slash palette state, keyed to the chat this snapshot describes. */
+    readonly slash: QaSlashView;
+}
+/** Minimal server-trusted identity exposed to principal-scoped plugins. */
+export interface QaPrincipal {
+    readonly userId: string;
+}
+//# sourceMappingURL=session.d.ts.map

package/lib/types/types/skills.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Why one skill draft cannot be saved, or why it saves with a caveat. Codes
+ * stay stable on the wire; the browser owns the Russian copy.
+ */
+export type QaSkillDiagnosticCode = "name-required" | "name-invalid" | "name-mismatch" | "description-required" | "description-too-long" | "when-to-use-too-long" | "field-type-invalid" | "invocation-never" | "invocation-invalid" | "invocation-legacy-key" | "allowed-tools-invalid" | "tool-name-invalid" | "tool-unavailable" | "tools-too-many" | "file-too-large" | "frontmatter-missing" | "skill-file-missing" | "skill-file-truncated" | "frontmatter-invalid" | "unknown-field" | "resource-unsupported";
+/** One finding about a skill file or an editor draft. */
+export interface QaSkillDiagnostic {
+    readonly code: QaSkillDiagnosticCode;
+    readonly severity: "error" | "warning";
+    /** The editor field the message belongs to, or null for a file-wide one. */
+    readonly field: string | null;
+    /** The offending value: a tool name, a frontmatter key, a limit. */
+    readonly detail: string | null;
+}
+/**
+ * A JSON-representable frontmatter value. The editor receives the preserved
+ * foreign fields verbatim over the Host bridge, which carries JSON only, so
+ * the parser drops anything a YAML document can hold but JSON cannot.
+ */
+export type QaSkillJsonValue = string | number | boolean | null | readonly QaSkillJsonValue[] | {
+    readonly [key: string]: QaSkillJsonValue;
+};
+/** One personal skill as the catalog list renders it. */
+/**
+ * One administrator write to a skill somebody else owns.
+ *
+ * The record exists so a personal skill cannot be changed behind its owner's
+ * back: it is written beside the skill and reported on every read, and the
+ * owner sees the badge in their own catalog.
+ */
+export interface QaSkillAdminEdit {
+    /** Administrator account id; the owner is told a role, not a colleague. */
+    readonly actorId: string;
+    /** ISO timestamp of that write. */
+    readonly at: string;
+}
+/**
+ * Which skill store an administrator is editing: the deployment-wide shared
+ * root every account may read, or one account's own directory.
+ */
+export type QaAdminSkillScope = {
+    readonly kind: "shared";
+} | {
+    readonly kind: "user";
+    readonly userId: string;
+};
+/** The account a personal skill scope belongs to, for the console's header. */
+export interface QaAdminSkillOwner {
+    readonly userId: string;
+    readonly email: string;
+    readonly displayName: string;
+}
+/** One scope's catalog plus the facts the console names it by. */
+export interface QaAdminSkillsView {
+    readonly scope: QaAdminSkillScope;
+    /** The account of a personal scope; null for the shared root. */
+    readonly owner: QaAdminSkillOwner | null;
+    readonly skills: readonly QaSkillSummary[];
+    /** Absolute directory this scope reads and writes, rendered read-only. */
+    readonly rootPath: string;
+}
+export interface QaSkillSummary {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse: string | null;
+    readonly modelInvocable: boolean;
+    readonly userInvocable: boolean;
+    /** Declared tools, in canonical order; unknown ones included. */
+    readonly allowedTools: readonly string[];
+    /** Declared tools the current QA scope cannot use; still stored as declared. */
+    readonly unavailableTools: readonly string[];
+    /** Entries in the skill directory besides SKILL.md (references, assets, …). */
+    readonly resourceCount: number;
+    readonly valid: boolean;
+    readonly diagnostics: readonly QaSkillDiagnostic[];
+    readonly updatedAt: string | null;
+    /** sha256 of the stored bytes; an update must echo the revision it read. */
+    readonly revision: string;
+    /**
+     * The administrator write that produced the stored revision, or null. A
+     * record whose revision no longer matches is stale and reports as null: the
+     * badge answers "did an administrator write what I am looking at", not
+     * "was this skill ever touched by an administrator".
+     */
+    readonly adminEdit: QaSkillAdminEdit | null;
+}
+/** One personal skill with everything the editor needs. */
+export interface QaSkillDocument extends QaSkillSummary {
+    readonly body: string;
+    /** Frontmatter the editor preserves but does not own. */
+    readonly extraFrontmatter: Readonly<Record<string, QaSkillJsonValue>>;
+    /** Absolute SKILL.md path; rendered read-only for advanced users. */
+    readonly sourcePath: string;
+    /** The canonical file the serializer writes, built from the parsed content. */
+    readonly preview: string;
+    /**
+     * True when the stored file is larger than the Host's read ceiling, so `body`
+     * and `preview` describe its head only. A save over such a document erases
+     * the unread tail, and the Host refuses it until the client confirms.
+     */
+    readonly truncated: boolean;
+}
+/** One tool the picker can offer, with this deployment's availability. */
+export interface QaSkillToolDescriptor {
+    readonly name: string;
+    readonly description: string;
+    /** False when the QA session's own scope cannot use the tool. */
+    readonly available: boolean;
+}
+/** The editor's save payload. */
+export interface QaSkillDraftInput {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse: string | null;
+    readonly modelInvocable: boolean;
+    readonly userInvocable: boolean;
+    readonly allowedTools: readonly string[];
+    readonly body: string;
+    /** Echo of the revision the editor read; a stale one is refused. */
+    readonly expectedRevision: string | null;
+    /**
+     * The client's acknowledgement that it is saving from an incomplete copy: the
+     * stored `SKILL.md` is over the read ceiling, so the draft carries the head
+     * of the file and a save would drop everything the read never loaded. A write
+     * without it is refused.
+     */
+    readonly confirmPartialOverwrite?: boolean;
+}
+/**
+ * The Host's answer about one unsaved draft: the file a save would write and
+ * the diagnostics it found. The editor shows its own subset immediately and
+ * this authoritative set as soon as it arrives.
+ */
+export interface QaSkillValidation {
+    readonly preview: string;
+    readonly diagnostics: readonly QaSkillDiagnostic[];
+}
+/** What one delete did: v1 keeps the directory recoverable. */
+export interface QaSkillRemoval {
+    readonly name: string;
+    readonly trashed: boolean;
+}
+//# sourceMappingURL=skills.d.ts.map