@yadsh/dsh-qa-surface 0.8.0 → 0.10.0

package/lib/client/QaSessionController.js

@@ -1,11 +1,13 @@
 import { bytesToBase64 } from "./base64.js";
 import { qaStorageNamespace } from "../shared/session-key.js";
+import { resolveSlashRoute } from "./slash/slash-router.js";
+import { SLASH_DISABLED_COPY, slashAttachmentsCopy, slashExecuteFailureCopy, slashHostRefusalCopy, slashRefusalCopy, slashWithheldCopy, } from "./slash/copy.js";
 import { canOpenAsCompatibilityReadOnly, QaPolicyAttestationError, } from "./attestation.js";
 import { QaChatIndex } from "./chat-index.js";
 import { isDelegatedSession } from "./lineage.js";
 import { SessionAssetRepository } from "./session-assets.js";
 import { createQaSession } from "./create-session.js";
-import { buildQaPromptContent, stageQaFiles } from "./prompt-content.js";
+import { buildQaPromptContent, buildQaSlashAttachments, stageQaFiles, } from "./prompt-content.js";
 import { attestQaPolicy } from "./session-admission.js";
 import { QaHostSourceBridge } from "./session-sources.js";
 import { QaHostApprovalBridge } from "./approvals.js";
@@ -18,6 +20,13 @@ import { readableSubagentName } from "./settlement.js";
 import { projectBoundSessionState } from "./project-session-state.js";
 import { projectTurnSources } from "./turn-sources.js";
 const CONFIGURATION_ERROR = "Настройки помощника недоступны.";
+/**
+ * How long a catalog answer stays fresh enough to skip a re-read when the
+ * palette opens. Short on purpose: the check is one round-trip and a stale
+ * palette shows a skill that was deleted or hides one that was just added.
+ * No polling loop — the palette opening is the only trigger.
+ */
+const SLASH_CATALOG_STALE_MS = 3_000;
 /**
  * Spacing of the parked-request poll. A request is answered by a person, so a
  * second of latency is invisible; the poll only runs while a turn runs.
@@ -39,6 +48,8 @@ export class QaSessionController {
     sourceApi;
     chats;
     accounts;
+    /** Slash half of the Host namespace; absent on an older Host build. */
+    slashApi;
     /** Resolved per send: a page without the upload plugin has no receipts. */
     fileUpload;
     /** Per-chat attachment URL cache; blob URLs die with the chat binding. */
@@ -79,6 +90,25 @@ export class QaSessionController {
     hostQuestions;
     /** Set while a running turn is polled for parked requests. */
     pendingTimer;
+    /**
+     * Slash catalog of the bound chat. Keyed by session: it depends on the
+     * chat's cwd, its agent composition and its role, so it is dropped with the
+     * binding instead of being carried across chats.
+     */
+    slashSessionId = null;
+    slashEntries = [];
+    slashDenied = [];
+    slashSurface = "unavailable";
+    slashState = "idle";
+    slashError = null;
+    slashLoadedAt = 0;
+    slashLoading;
+    /** Last published view; its identity is the render signal. */
+    slashViewCache;
+    /** Bumped to re-open a palette the user dismissed; see `QaSlashView`. */
+    slashReopen = 0;
+    /** Chat, connection and admission state of the last one-shot probe. */
+    pendingProbeKey = "";
     constructor(options) {
         this.sessions = options.sessions;
         this.createSessionRemote = options.createSession;
@@ -94,9 +124,22 @@ export class QaSessionController {
                         ok: false,
                         error: "unavailable",
                     }),
+                    listWorkspaceFiles: async () => ({
+                        ok: false,
+                        error: "unavailable",
+                    }),
+                    readWorkspaceFile: async () => ({
+                        ok: false,
+                        error: "unavailable",
+                    }),
+                    previewWorkspaceDocument: async () => ({
+                        ok: false,
+                        error: "unavailable",
+                    }),
                 };
         this.chats = new QaChatIndex(options.storage, qaStorageNamespace(options.config));
         this.accounts = options.accounts;
+        this.slashApi = options.slashApi;
         this.selectedSubrole = options.initialSubrole ?? null;
         this.adminPreview = options.adminPreview === true;
         this.fileUpload = options.fileUpload ?? (() => undefined);
@@ -139,7 +182,52 @@ export class QaSessionController {
         this.adminPreview = adminPreview;
         await this.startDraft(true);
     }
-    async send(text, attachments = []) {
+    /**
+     * The attested live session a submission may ride, or `undefined` when the
+     * caller must abort. Materializing a draft chat, attesting policy and
+     * recovering from a stale proof live here, so the prompt path and the
+     * command path cannot drift apart on what "ready to send" means.
+     */
+    async liveTarget() {
+        if (this.session === undefined) {
+            // A draft chat materializes its session only now: nothing was created
+            // when the user pressed "New chat", so the first submission pays for it.
+            if (!this.drafting || this.materializing !== undefined)
+                return undefined;
+            if (!(await this.materializeDraft()) || this.session === undefined) {
+                return undefined;
+            }
+        }
+        const step = await this.attestPolicy();
+        if (step.kind === "stale") {
+            // The user moved to another chat while the proof was pending; that
+            // binding attests through its own flow and must not receive a submission
+            // meant for the old one.
+            return undefined;
+        }
+        let attestedId = step.kind === "ok" ? step.sessionId : null;
+        if (attestedId === null) {
+            attestedId = await this.recoverForSend();
+            if (attestedId === null)
+                return undefined;
+        }
+        // Nothing can interleave between the last await and here, so matching the
+        // attested id proves the submission rides exactly the session it proved.
+        const target = this.session;
+        if (this.disposed ||
+            target === undefined ||
+            String(target.sessionId) !== attestedId) {
+            return undefined;
+        }
+        return target;
+    }
+    /**
+     * Route one composer draft. Ordinary text and a skill invocation both ride
+     * the native prompt path — a skill is a gesture inside the prompt, not a
+     * call this surface makes — while a human command goes to the Host's command
+     * runtime and never becomes a model message.
+     */
+    async send(text, attachments = [], pick = null) {
         const prompt = text.trim();
         // Images ride the prompt inline; files must be staged first, because the
         // wire carries a receipt rather than bytes.
@@ -147,8 +235,37 @@ export class QaSessionController {
         if ((prompt === "" && attachments.length === 0) || !this.state.canSend) {
             return false;
         }
-        if (prompt.startsWith("/")) {
-            this.operationError = "Команды со слешем недоступны в режиме помощника.";
+        const route = resolveSlashRoute({
+            text: prompt,
+            enabled: this.config.slashCommands.enabled,
+            catalogReady: this.slashCatalogReady(),
+            entries: this.slashEntries,
+            deniedSkills: this.slashDenied,
+            picked: pick,
+        });
+        if (route.kind === "command") {
+            return this.sendCommand(prompt, attachments, files, route.entry);
+        }
+        if (route.kind === "disabled") {
+            this.operationError = SLASH_DISABLED_COPY;
+            this.publish();
+            return false;
+        }
+        if (route.kind !== "prompt" && route.kind !== "skill") {
+            this.operationError = slashRefusalCopy(route);
+            if (route.kind === "unknown" || route.kind === "ambiguous") {
+                // Re-open the palette the user had to dismiss to reach this line: the
+                // refusal is only useful next to the choices it is talking about.
+                this.slashReopen += 1;
+            }
+            this.publish();
+            return false;
+        }
+        if (route.kind === "prompt" && (route.withheld?.length ?? 0) > 0) {
+            // The gesture is real and user-invocable here, and this deployment
+            // withholds it. Sending it would let the user believe it took effect —
+            // the native consumer refuses the injection, but only after the turn.
+            this.operationError = slashWithheldCopy(route.withheld ?? []);
             this.publish();
             return false;
         }
@@ -160,36 +277,9 @@ export class QaSessionController {
         let accepted = false;
         let target;
         try {
-            if (this.session === undefined) {
-                // A draft chat materializes its session only now: nothing was created
-                // when the user pressed "New chat", so the first prompt pays for it.
-                if (!this.drafting || this.materializing !== undefined)
-                    return false;
-                if (!(await this.materializeDraft()) || this.session === undefined) {
-                    return false;
-                }
-            }
-            const step = await this.attestPolicy();
-            if (step.kind === "stale") {
-                // The user moved to another chat while the proof was pending; that
-                // binding attests through its own flow and must not receive a prompt
-                // meant for the old one.
-                return false;
-            }
-            let attestedId = step.kind === "ok" ? step.sessionId : null;
-            if (attestedId === null) {
-                attestedId = await this.recoverForSend();
-                if (attestedId === null)
-                    return false;
-            }
-            // Nothing can interleave between the last await and here, so matching the
-            // attested id proves the prompt rides exactly the session it proved.
-            target = this.session;
-            if (this.disposed ||
-                target === undefined ||
-                String(target.sessionId) !== attestedId) {
+            target = await this.liveTarget();
+            if (target === undefined)
                 return false;
-            }
             if (submission !== undefined && this.pendingSubmission === submission) {
                 // Recovery may have replaced the original chat with a fresh session;
                 // reconcile against the actual prompt target, not the abandoned one.
@@ -247,6 +337,198 @@ export class QaSessionController {
             }
         }
     }
+    /**
+     * Run one admitted human command. The Host answers it and writes the
+     * lifecycle into the session log; this method only decides what the composer
+     * does next, which is why nothing here creates a pending user row.
+     *
+     * A refusal keeps the draft and the attachments: the user asked for
+     * something the deployment does not allow, and retyping the line is a worse
+     * answer than leaving it in place to be edited.
+     */
+    async sendCommand(line, attachments, files, entry) {
+        if (this.slashApi === undefined) {
+            this.operationError = SLASH_DISABLED_COPY;
+            this.publish();
+            return false;
+        }
+        if (attachments.length > 0 && entry.acceptsAttachments !== true) {
+            // Checked here so nothing is staged and no Host round-trip is paid for a
+            // submission that cannot be admitted; the Host checks it again anyway.
+            this.operationError = slashAttachmentsCopy(entry);
+            this.publish();
+            return false;
+        }
+        let target;
+        try {
+            target = await this.liveTarget();
+            if (target === undefined)
+                return false;
+            let receipts = new Map();
+            if (files.length > 0) {
+                const outcome = await stageQaFiles(this.fileUpload(), target, files);
+                if (outcome.kind !== "ok") {
+                    if (this.session === target) {
+                        this.operationError =
+                            outcome.kind === "unavailable"
+                                ? "Вложения недоступны на этом сервере."
+                                : "Не удалось приложить файл.";
+                        this.publish();
+                    }
+                    return false;
+                }
+                receipts = outcome.receipts;
+            }
+            const result = await this.slashApi.execute(this.accounts?.token() ?? "", String(target.sessionId), line, buildQaSlashAttachments(attachments, receipts));
+            if (this.session !== target)
+                return false;
+            if (!result.ok) {
+                this.operationError = slashExecuteFailureCopy(entry);
+                this.publish();
+                return false;
+            }
+            if (result.value.kind === "refused") {
+                this.operationError = slashHostRefusalCopy(result.value);
+                this.publish();
+                return false;
+            }
+            this.operationError = null;
+            this.publish();
+            return true;
+        }
+        catch (error) {
+            console.error("dsh-qa-surface: slash command failed", error);
+            if (this.session === target) {
+                this.operationError = slashExecuteFailureCopy(entry);
+                this.publish();
+            }
+            return false;
+        }
+    }
+    /**
+     * Refresh the catalog of the bound chat. Called when a chat binds, and again
+     * when the palette opens on a catalog that has had time to go stale: the
+     * skill registry has no browser-facing change event, so a skill installed
+     * while the page is open is only discovered by asking again.
+     */
+    async refreshSlashCatalog(force = false) {
+        const session = this.session;
+        if (session === undefined || this.disposed)
+            return;
+        if (!this.config.slashCommands.enabled || this.compatibilityReadOnly) {
+            this.applySlashCatalog(String(session.sessionId), null);
+            return;
+        }
+        if (this.slashApi === undefined) {
+            this.applySlashCatalog(String(session.sessionId), undefined);
+            return;
+        }
+        if (this.slashLoading !== undefined)
+            return this.slashLoading;
+        if (!force && this.slashSessionId === String(session.sessionId)) {
+            if (Date.now() - this.slashLoadedAt < SLASH_CATALOG_STALE_MS)
+                return;
+        }
+        const sessionId = String(session.sessionId);
+        this.slashState = "loading";
+        this.publish();
+        const operation = (async () => {
+            try {
+                const result = await this.slashApi?.catalog(this.accounts?.token() ?? "", sessionId);
+                if (result === undefined)
+                    return;
+                if (!result.ok) {
+                    this.applySlashCatalog(sessionId, undefined);
+                    return;
+                }
+                this.applySlashCatalog(sessionId, result.value);
+            }
+            catch (error) {
+                console.error("dsh-qa-surface: slash catalog failed", error);
+                this.applySlashCatalog(sessionId, undefined);
+            }
+        })().finally(() => {
+            if (this.slashLoading === operation)
+                this.slashLoading = undefined;
+        });
+        this.slashLoading = operation;
+        return operation;
+    }
+    /**
+     * Install one catalog answer. `null` means the deployment runs with the
+     * slash interface off; `undefined` means the answer never arrived. The
+     * difference matters: an unreachable catalog must not turn ordinary prompts
+     * into refusals.
+     */
+    applySlashCatalog(sessionId, catalog) {
+        if (this.session === undefined ||
+            String(this.session.sessionId) !== sessionId) {
+            return;
+        }
+        this.slashSessionId = sessionId;
+        this.slashLoadedAt = Date.now();
+        if (catalog === null) {
+            this.slashEntries = [];
+            this.slashDenied = [];
+            this.slashSurface = "unavailable";
+            this.slashState = "idle";
+            this.slashError = null;
+            this.publish();
+            return;
+        }
+        if (catalog === undefined) {
+            this.slashEntries = [];
+            this.slashDenied = [];
+            this.slashSurface = "unavailable";
+            this.slashState = "error";
+            this.slashError = "Не удалось загрузить команды";
+            this.publish();
+            return;
+        }
+        this.slashEntries = catalog.entries;
+        this.slashDenied = catalog.deniedSkills;
+        this.slashSurface = catalog.commandSurface;
+        this.slashState = "ready";
+        this.slashError = null;
+        this.publish();
+    }
+    /** Whether the catalog of the bound chat was read successfully. */
+    slashCatalogReady() {
+        return this.slashState === "ready" || this.slashState === "loading";
+    }
+    /** The slash view of the current state; assembled where the state is. */
+    slashView() {
+        const enabled = this.config.slashCommands.enabled &&
+            !this.compatibilityReadOnly &&
+            this.slashSessionId !== null &&
+            this.slashApi !== undefined;
+        // Identity is the render signal: this runs on every publish, including
+        // every stream frame of a running turn, and the composer is memoized on
+        // its props. A fresh object here would re-render the composer for each
+        // frame of an answer, which is exactly what its memo exists to prevent.
+        const cached = this.slashViewCache;
+        if (cached !== undefined &&
+            cached.enabled === enabled &&
+            cached.state === this.slashState &&
+            cached.entries === this.slashEntries &&
+            cached.commandSurface === this.slashSurface &&
+            cached.deniedSkills === this.slashDenied &&
+            cached.error === this.slashError &&
+            cached.reopen === this.slashReopen) {
+            return cached;
+        }
+        const view = {
+            enabled,
+            state: this.slashState,
+            entries: this.slashEntries,
+            commandSurface: this.slashSurface,
+            deniedSkills: this.slashDenied,
+            error: this.slashError,
+            reopen: this.slashReopen,
+        };
+        this.slashViewCache = view;
+        return view;
+    }
     /** Publish a browser-only copy before any network or Host admission awaits. */
     beginSubmission(text, attachments) {
         const submission = {
@@ -803,6 +1085,9 @@ export class QaSessionController {
             this.accounts?.onSessionCreated(String(this.session.sessionId));
         }
         this.publish();
+        // Deliberately not awaited: the palette is a convenience, and a chat must
+        // open at once whether or not the skill and command registries answer.
+        void this.refreshSlashCatalog(true);
     }
     unbind() {
         this.streamPublisher.clear();
@@ -821,9 +1106,21 @@ export class QaSessionController {
         this.hostApprovals.reset();
         this.hostQuestions.reset();
         this.stopPendingPolling();
+        // The next binding probes the Host again even for the same chat.
+        this.pendingProbeKey = "";
         this.admissionPending = false;
         this.policyReady = false;
         this.compatibilityReadOnly = false;
+        // The catalog belongs to the chat that produced it: another chat has a
+        // different cwd, composition and role, so carrying it across would offer
+        // actions this chat may not have.
+        this.slashSessionId = null;
+        this.slashEntries = [];
+        this.slashDenied = [];
+        this.slashSurface = "unavailable";
+        this.slashState = "idle";
+        this.slashError = null;
+        this.slashLoadedAt = 0;
     }
     waitForConnection() {
         return waitFor(this.connection, (description) => description !== undefined, this.timeoutMs);
@@ -874,6 +1171,7 @@ export class QaSessionController {
         if (!snapshot.running) {
             void this.hostSources.refresh(sessionId, () => this.publish());
         }
+        this.probePending(sessionId, connected);
         this.syncPendingPolling(snapshot.running === true && !this.compatibilityReadOnly);
         const projectionInput = {
             connected,
@@ -892,6 +1190,7 @@ export class QaSessionController {
             admissionPending: this.admissionPending || this.pendingSubmission !== undefined,
             chatsRevision: this.chatsRevision,
             viewingSubagent: this.viewingSubagent,
+            slash: this.slashView(),
             config: this.config,
             subagentNames: this.subagentNames(),
         };
@@ -1041,6 +1340,12 @@ export class QaSessionController {
      * inside an open turn, and it is Host state: polling is how the page learns
      * about it, and how it reappears after a reload. One timer serves both seams,
      * and each is polled only where the deployment answers it.
+     *
+     * A request that is already on screen keeps the timer alive past the end of
+     * its turn: the Host settles what the turn can no longer answer — an aborted
+     * tool call, an agent that went idle — and this keeps reading until that
+     * settlement reaches the page, so the form goes away instead of sitting
+     * there answerable but dead.
      */
     syncPendingPolling(running) {
         const approvals = this.hostApprovals.available
@@ -1049,8 +1354,9 @@ export class QaSessionController {
         const questions = this.hostQuestions.available
             ? this.config.interaction.questions === "interactive"
             : false;
-        const wanted = running &&
-            (approvals || questions) &&
+        const pending = this.hostApprovals.list().length > 0 ||
+            this.hostQuestions.list().length > 0;
+        const wanted = ((running && (approvals || questions)) || pending) &&
             // A subagent watched from the panel is a read-only view of a session the
             // chat owns: its own requests belong to the chat, not to this binding.
             this.viewingSubagent === null &&
@@ -1064,16 +1370,44 @@ export class QaSessionController {
         const sessionId = String(this.session.sessionId);
         const token = this.hostToken();
         const tick = () => {
-            if (approvals) {
+            // A seam still on screen is re-read even where its config gate has since
+            // closed: the Host is the authority on what it holds, and an empty answer
+            // is what takes a settled request off the screen.
+            if (approvals || this.hostApprovals.list().length > 0) {
                 void this.hostApprovals.refresh(sessionId, token, () => this.publish());
             }
-            if (questions) {
+            if (questions || this.hostQuestions.list().length > 0) {
                 void this.hostQuestions.refresh(sessionId, token, () => this.publish());
             }
         };
         this.pendingTimer = setInterval(tick, PENDING_POLL_MS);
         tick();
     }
+    /**
+     * Read what the Host parks once per chat and connection, whether or not a
+     * turn is running. A reload binds the chat before any turn reports itself
+     * over the fresh stream, and a turn that is already waiting on a question
+     * would otherwise sit behind an empty composer until the operator happened
+     * to send something.
+     */
+    probePending(sessionId, connected) {
+        const key = `${sessionId}:${connected ? "up" : "down"}:${String(this.policyReady)}`;
+        // Attestation is what lets the Host answer about this chat at all, so the
+        // read waits for it: the publish that follows a successful attestation
+        // carries a new key and probes then.
+        if (!connected || !this.policyReady || key === this.pendingProbeKey)
+            return;
+        this.pendingProbeKey = key;
+        const token = this.hostToken();
+        if (this.hostApprovals.available &&
+            this.config.interaction.approvals === "interactive") {
+            void this.hostApprovals.refresh(sessionId, token, () => this.publish());
+        }
+        if (this.hostQuestions.available &&
+            this.config.interaction.questions === "interactive") {
+            void this.hostQuestions.refresh(sessionId, token, () => this.publish());
+        }
+    }
     stopPendingPolling() {
         if (this.pendingTimer === undefined)
             return;