@yadsh/dsh-qa-surface 0.8.0 → 0.10.0

package/lib/types/qa-tools/file-delete-gate.d.ts

@@ -0,0 +1,42 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { QaSessionOwnership } from "../session-ownership.js";
+/** The one QA tool whose every call is parked for the operator. */
+export declare const QA_FILE_DELETE_TOOL = "file_delete";
+/** Why the gate answers `ask` before the chain can decide alone. */
+export declare const QA_FILE_DELETE_ASK_REASON = "deleting a workspace file requires operator confirmation";
+/**
+ * The inner half of `file_delete`'s safety: the decision that composes the
+ * approval flow around one destructive tool.
+ *
+ * Installed WITHOUT `prepend`, deliberately. The approval gate sits outside
+ * every other `tools/pre-execute` listener and resolves the decision the rest
+ * of the chain produced — an `ask` from an inner gate is what it parks for
+ * the operator. This listener is that inner gate: for a `file_delete` call
+ * from an attested QA session it answers `ask` on its own, without asking
+ * the chain, so the interactive approval card appears for every deletion,
+ * whatever the deployment's other policies would have said. The operator's
+ * answer becomes the decision, and on a deployment with
+ * `interaction.approvals: blocked` the approval gate keeps its fail-closed
+ * behavior and refuses the call — nothing is ever deleted without a person.
+ *
+ * Any other tool, and any caller this deployment did not attest, is handed
+ * back to the chain untouched.
+ */
+export declare class QaFileDeleteGate {
+    private readonly ctx;
+    private readonly ownership;
+    private readonly disposers;
+    constructor(ctx: Context, ownership: QaSessionOwnership);
+    /** Sit inside the approval gate; registration order is the composition. */
+    install(): void;
+    /** Detach the listener. Wired as an effect, like every other gate. */
+    dispose(): void;
+    private handle;
+    /**
+     * Whether this deployment attested the chat the call belongs to, delegated
+     * children included. The same ownership service the approval gate reads,
+     * so one chat is parked under exactly one surface.
+     */
+    private attested;
+}
+//# sourceMappingURL=file-delete-gate.d.ts.map

package/lib/types/qa-tools/file-delete.d.ts

@@ -0,0 +1,32 @@
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+/**
+ * `file_delete` — the QA catalog's one destructive capability.
+ *
+ * The QA surface serves untrusted-audience chats pinned to a read-only or
+ * workspace-write sandbox, and until now no chat could remove a file it had
+ * created. This tool deletes exactly one regular file strictly inside the
+ * calling agent's workspace root (the session cwd) and refuses everything
+ * else with a reason the model can act on: directories, missing paths, paths
+ * spelled outside the root, and paths that leave it through a symbolic link.
+ * Every call is additionally answered `ask` by the always-ask gate, so the
+ * interactive approval card parks it for the operator before this body ever
+ * runs — the fence here is the second of two boundaries, not the only one.
+ *
+ * The workspace root is read from `exec.agent` at call time, so building the
+ * tool (and the catalog that carries it) stays side-effect free.
+ */
+/** Why `file_delete` refused a call. */
+export type QaFileDeleteRefusal = "workspace-unavailable" | "outside-workspace" | "symlink-escape" | "not-found" | "not-a-file";
+/**
+ * A typed refusal of one `file_delete` call.
+ *
+ * The message is what the model reads; it names the reason in words and
+ * deliberately never echoes the requested absolute host path, so a refusal
+ * cannot leak the deployment's layout into the conversation.
+ */
+export declare class QaFileDeleteError extends Error {
+    readonly code: QaFileDeleteRefusal;
+    constructor(code: QaFileDeleteRefusal, message: string, options?: ErrorOptions);
+}
+export declare function createFileDeleteTool(): ToolDefinition;
+//# sourceMappingURL=file-delete.d.ts.map

package/lib/types/questions.d.ts

@@ -33,6 +33,12 @@ export interface QaQuestionAnswer {
 }
 /** What the model reads when the deployment does not answer questions. */
 export declare const QA_QUESTIONS_UNSUPPORTED = "questions are not answered in this assistant view; ask the user in plain text instead";
+/**
+ * The harness tool that produces these requests. A deployment that parks
+ * questions still has to let the attested session call it: this plugin never
+ * adds the name to a tool policy on its own.
+ */
+export declare const QA_ASK_QUESTION_TOOL = "ask_user_question";
 /**
  * User questions in the QA view.
  *
@@ -84,5 +90,7 @@ export declare class QaQuestionGate {
     private park;
     /** Fail the questions one session's agent owns; a disposed agent cannot ask. */
     private settleOwner;
+    /** Fail the questions one agent parked; an idle agent cannot receive them. */
+    private settleAgent;
 }
 //# sourceMappingURL=questions.d.ts.map

package/lib/types/shared/documents.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Formats the files panel previews by conversion instead of by bytes.
+ *
+ * Shared by the Host half (which owns the conversion) and the browser card
+ * (which decides whether opening a file should ask for one), so the two cannot
+ * drift on what "we can render this" means. Dependency-free on purpose: the
+ * card bundle inlines it.
+ */
+/** OOXML word-processing documents, as the deployment detects them. */
+export declare const QA_WORD_MEDIA_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+/** The media type of the PDF a converted document arrives as. */
+export declare const QA_PDF_MEDIA_TYPE = "application/pdf";
+/**
+ * Whether the panel asks the Host for a converted PDF rather than rendering the
+ * bytes it already holds. Word documents are the whole set: the document
+ * pipeline reads them and renders PDF, while its other inputs are already
+ * previewable (Markdown as text, PDF through the browser's own viewer).
+ */
+export declare function isConvertibleDocument(mediaType: string): boolean;
+//# sourceMappingURL=documents.d.ts.map

package/lib/types/slash/catalog.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The unified presentation model behind the palette.
+ *
+ * Two native catalogs arrive here — the session's user-invocable skills and
+ * the session agent's effective commands — and leave as one list of entries
+ * whose identity is `skill:<name>` / `command:<name>`. The prefix is the whole
+ * point: both registries may publish a `plan`, and a palette that keyed rows
+ * by bare name would let one of them silently replace the other.
+ *
+ * Pure on purpose. Nothing here reads a session, a service or a file: the host
+ * remote gathers the native inputs, this module decides what the palette sees,
+ * and the tests drive it with plain arrays.
+ */
+import type { QaSlashCatalogEntry, QaSlashCommandSurface } from "../types.js";
+import { type QaSlashPolicy } from "./policy.js";
+export declare const QA_SLASH_SKILL_PREFIX = "skill:";
+export declare const QA_SLASH_COMMAND_PREFIX = "command:";
+/** One user-invocable skill, as the skills registry published it. */
+export interface QaSlashNativeSkill {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse?: string;
+    /** Whether the model is also offered this skill. */
+    readonly modelInvocable?: boolean;
+}
+/** One effective command descriptor, as the command registry published it. */
+export interface QaSlashNativeCommand {
+    readonly name: string;
+    readonly description: string;
+    readonly inputHint?: string;
+    readonly acceptsAttachments?: boolean;
+}
+export interface BuildSlashCatalogOptions {
+    readonly skills: readonly QaSlashNativeSkill[];
+    readonly commands: readonly QaSlashNativeCommand[];
+    readonly skillPolicy: QaSlashPolicy;
+    readonly commandPolicy: QaSlashPolicy;
+    /**
+     * The session role's own user-skill grant, when the access system is on.
+     * `undefined` means the role system has no opinion, which is its state on a
+     * deployment that never enabled roles — not "grant nothing".
+     */
+    readonly grantedSkills?: readonly string[] | undefined;
+    readonly commandSurface: QaSlashCommandSurface;
+    /** Native entries arrive alphabetically; this makes the order explicit. */
+    readonly localeCompare?: (left: string, right: string) => number;
+}
+/** The routing identity of one native name; never the bare name. */
+export declare function slashEntryId(kind: QaSlashCatalogEntry["kind"], name: string): string;
+/**
+ * Build the palette the browser is allowed to show. Skills lead, commands
+ * follow: the two kinds stay contiguous so the palette can group them without
+ * re-sorting, and a name collision keeps both rows.
+ */
+export declare function buildSlashCatalog(options: BuildSlashCatalogOptions): readonly QaSlashCatalogEntry[];
+//# sourceMappingURL=catalog.d.ts.map

package/lib/types/slash/matcher.d.ts

@@ -0,0 +1,51 @@
+/**
+ * One matcher for both halves of the slash catalog.
+ *
+ * Upstream matches skills with `startsWith` and commands fuzzily, so the same
+ * query behaves differently depending on which registry answers it. QA always
+ * ranks with the ladder below, in this order:
+ *
+ *   exact → prefix → name-token boundary → substring → ordered subsequence
+ *
+ * so `/tkp` finds `generate-tkp` through the token boundary and `/contract`
+ * finds both `contract-analysis` (prefix) and `review-contract` (token).
+ *
+ * Dependency-free on purpose: inlined into the browser bundle.
+ */
+/** How a name matched; lower is a stronger claim on the top of the list. */
+export declare const SLASH_MATCH_EXACT = 0;
+export declare const SLASH_MATCH_PREFIX = 1;
+export declare const SLASH_MATCH_TOKEN = 2;
+export declare const SLASH_MATCH_SUBSTRING = 3;
+export declare const SLASH_MATCH_SUBSEQUENCE = 4;
+export interface QaSlashMatch {
+    readonly rank: number;
+    /** Where the match starts; earlier wins inside one rank. */
+    readonly index: number;
+}
+export interface QaSlashMatchOptions {
+    /**
+     * Whether the two weakest rungs run. Turning them off keeps the matcher
+     * predictable for deployments that read the palette as an index.
+     */
+    readonly fuzzy?: boolean;
+}
+/**
+ * Rank one name against a palette query. An empty query matches everything at
+ * the prefix rung, which keeps the unfiltered catalog in catalog order.
+ */
+export declare function matchSlashName(name: string, query: string, options?: QaSlashMatchOptions): QaSlashMatch | undefined;
+/**
+ * Order two ranked names; the caller has already ruled out `undefined`. Ties
+ * fall back to the name, so equal-rank rows keep catalog order and the list
+ * never reshuffles between two renders of the same query.
+ */
+export declare function compareSlashMatches(leftName: string, left: QaSlashMatch, rightName: string, right: QaSlashMatch): number;
+/**
+ * The matching entries in rank order. Identity of the input entries is
+ * preserved, so a caller can render them without a lookup.
+ */
+export declare function rankSlashEntries<T extends {
+    readonly name: string;
+}>(entries: readonly T[], query: string, options?: QaSlashMatchOptions): readonly T[];
+//# sourceMappingURL=matcher.d.ts.map

package/lib/types/slash/parser.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Composer input classification for the slash interface.
+ *
+ * The grammars are mirrors, not inventions: a command line is what the native
+ * command runtime parses (`/name` at byte zero, name then end-of-input or
+ * whitespace, everything after kept verbatim as `rawInput`), and a skill
+ * gesture is what `dsh-tool-skill` recognises (any whitespace-bounded `/name`
+ * token with the public skill-name grammar). A line that matches neither is
+ * ordinary prose and must keep behaving exactly as it did before this feature.
+ *
+ * Deliberately dependency-free: this module is inlined into the browser
+ * bundle, where the Host's config surface must not follow it.
+ */
+export interface QaSlashLine {
+    readonly name: string;
+    /** Exact text after the name, including the separator whitespace. */
+    readonly args: string;
+}
+/**
+ * Parse a command-shaped line. `undefined` means the line is not one — either
+ * it is not slash-led at all, or the token after the slash is not a command
+ * name (`/usr/bin/env` stays a path, not a call).
+ */
+export declare function parseSlashLine(input: string): QaSlashLine | undefined;
+/** The palette filter of a draft, or `undefined` when the palette is closed. */
+export declare function slashPaletteQuery(input: string): string | undefined;
+/**
+ * Every whitespace-bounded `/name` gesture in the text, first-seen order and
+ * deduplicated. The Host owns invocation; this list exists only so the QA
+ * surface can warn about a gesture its own policy withholds before the turn
+ * is submitted.
+ */
+export declare function skillGestures(input: string): readonly string[];
+/** The invocation a submitted draft carries, once its route is decided. */
+export interface QaSlashInvocation {
+    readonly name: string;
+    /** Text after the name with its separator whitespace removed. */
+    readonly args: string;
+}
+/**
+ * The invocation a draft names, independent of the catalog. Used for the
+ * routing decision and for the "unknown command" refusal, both of which must
+ * work while the catalog itself is unavailable.
+ */
+export declare function slashInvocation(input: string): QaSlashInvocation | undefined;
+//# sourceMappingURL=parser.d.ts.map

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

@@ -0,0 +1,40 @@
+/**
+ * Admission policy for one half of the slash catalog.
+ *
+ * The policy is name-based because the persisted config is: an operator writes
+ * `generate-tkp`, never an internal id, and the same name means the same thing
+ * on every Host restart. Names that cannot be a native skill or command name
+ * are refused at config resolution rather than silently ignored at admission,
+ * so a typo surfaces while the deployment is being configured.
+ */
+import type { QaSlashPolicyMode } from "../types.js";
+/** Every accepted policy mode, in the order the settings card lists them. */
+export declare const QA_SLASH_MODES: readonly QaSlashPolicyMode[];
+/** Longest name either registry accepts in practice; keeps host echoes bounded. */
+export declare const QA_SLASH_NAME_MAX = 200;
+export interface QaSlashPolicy {
+    readonly mode: QaSlashPolicyMode;
+    readonly allow: readonly string[];
+}
+export declare function isQaSlashPolicyMode(value: unknown): value is QaSlashPolicyMode;
+/**
+ * Normalize one allow-list: trimmed, deduplicated, order-preserving. Refuses
+ * a name that neither registry could ever carry, and refuses `all` alongside a
+ * non-empty list, which would be two answers to one question.
+ */
+export declare function normalizeSlashAllow(values: readonly string[], label: string): readonly string[];
+/** Whether the policy admits this native name. */
+export declare function allowsSlashName(policy: QaSlashPolicy, name: string): boolean;
+/** The admitted subset, in the order the native registry returned it. */
+export declare function filterBySlashPolicy<T extends {
+    readonly name: string;
+}>(entries: readonly T[], policy: QaSlashPolicy): readonly T[];
+/**
+ * Intersect an already-admitted list with a second name set (the session's
+ * role grant). An empty set means "no second opinion" — the role system keeps
+ * its own switch, and a deployment that never enabled it grants nothing here.
+ */
+export declare function intersectSlashNames<T extends {
+    readonly name: string;
+}>(entries: readonly T[], names: readonly string[] | undefined): readonly T[];
+//# sourceMappingURL=policy.d.ts.map

package/lib/types/slash/remotes.d.ts

@@ -0,0 +1,35 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaSlashCatalog, QaSlashExecution, QaSlashSubmitAttachment, ResolvedQaSurfaceConfig } from "../types.js";
+/**
+ * Host-side bodies of the slash remotes. The `@Remote`-decorated signatures
+ * stay on the `QaSurface` service class (typert code generation reads the class
+ * shape); this context owns everything behind them.
+ *
+ * The division of labour is the whole feature in one sentence: QA decides what
+ * the palette may show and whether a line may run, and the native registries
+ * decide what a skill and a command *mean*. Nothing here reads a SKILL.md,
+ * injects instructions or re-implements a registry.
+ */
+export interface QaSlashRemotes {
+    /** The catalog this browser may render, already policy-filtered. */
+    catalog(token: string, sessionId: string): Promise<QaSlashCatalog>;
+    /** Run one human command line through the native command runtime. */
+    execute(token: string, sessionId: string, line: string, attachments: readonly QaSlashSubmitAttachment[]): Promise<QaSlashExecution>;
+}
+export interface QaSlashRemotesOptions {
+    readonly ctx: Context;
+    readonly getConfig: () => ResolvedQaSurfaceConfig;
+    readonly logger: PluginLogger;
+    /**
+     * Ownership and role check for the current QA session. Runs only while the
+     * deployment gates QA users with accounts; it throws on refusal, which is
+     * what makes a foreign session unreadable instead of merely unowned.
+     *
+     * @returns the role's user-skill grant, or `undefined` when the access
+     * system has no opinion about this session's skills.
+     */
+    readonly sessionGrant: (token: string, sessionId: string, agent: unknown) => Promise<readonly string[] | undefined>;
+}
+export declare function createQaSlashRemotes(options: QaSlashRemotesOptions): QaSlashRemotes;
+//# sourceMappingURL=remotes.d.ts.map