@kodaris/krubble-app-components 1.0.111 → 1.0.113

package/dist/chatbot.js

@@ -15,6 +15,25 @@ import { marked } from 'marked';
 // (kr-dialog, kr-tab-group, kr-tab, kr-text-field) used by the browse dialog.
 import { KRFilePreview, KRSnackbar } from '@kodaris/krubble-components';
 import { KRHttp } from '@kodaris/krubble-http';
+/**
+ * The action-confirmation decisions, in the left-to-right order they render and
+ * the order the arrow keys walk. Yes is first so it's the default highlight.
+ * Shared by the render and the keyboard handler so the two never drift.
+ */
+const CONFIRMATION_DECISIONS = [
+    {
+        decision: 'approve',
+        label: 'Yes',
+    },
+    {
+        decision: 'approveAlways',
+        label: 'Always allow',
+    },
+    {
+        decision: 'reject',
+        label: 'No',
+    },
+];
 /** Image extensions the chatbot renders as thumbnails (used when MIME is absent). */
 const IMAGE_EXTENSIONS = ['jpg', 'jpeg', 'png', 'gif', 'webp'];
 /**
@@ -49,9 +68,20 @@ const ACCEPTED_FILE_EXTENSIONS = [
  * - `TOOL_RESULT` — `{ type: "TOOL_RESULT", message: "tool_name", data: {...} }`
  * - `ERROR` — `{ type: "ERROR", message: "Something went wrong" }`
  * - `HEARTBEAT` — `{ type: "HEARTBEAT" }` (ignored)
+ * - `ACTION_CONFIRMATION_REQUIRED` — a guarded tool paused for approval;
+ *   `{ type, data: { actions: [...] }, finished: true }` (Rail 3).
  *
  * The final event should include `finished: true` to signal stream completion.
  *
+ * ## Turn locking (when the composer is free to send)
+ * `finished: true` is the single reliable "turn over, safe to send" signal — the
+ * component unlocks the composer on it, and also on stream close/error as a
+ * fallback so a dropped stream never wedges the UI. The one exception is
+ * `ACTION_CONFIRMATION_REQUIRED`: it too carries `finished: true`, but the
+ * conversation is now awaiting an approve/deny decision, so the composer stays
+ * blocked and only a confirmation decision (not a new message) is a valid next
+ * call.
+ *
  * ## Usage
  * ```html
  * <kr-chatbot
@@ -221,6 +251,32 @@ let KRChatbot = class KRChatbot extends LitElement {
         this._contextLimitReached = false;
         /** Server-provided limit text (`CONVERSATION_LIMIT_REACHED`), if any. */
         this._contextLimitMessage = '';
+        /**
+         * The guarded tool awaiting the user's decision, from the turn's
+         * `ACTION_CONFIRMATION_REQUIRED` event (`data.actions[]`, of which we handle the
+         * first — the framework confirms one guarded tool at a time). Non-empty means
+         * the conversation is paused on a confirmation: the normal composer is blocked
+         * (a new chat message would be rejected by the server with
+         * `awaitingConfirmation`) and the approve/deny prompt is shown instead. Cleared
+         * once a decision is sent.
+         *
+         * This is the one case where `finished:true` unlocks the turn lock but does
+         * NOT free the composer — the only valid next call is a confirmation decision.
+         */
+        this._pendingActions = [];
+        /**
+         * Keyboard-highlighted confirmation option, as an index into the decision list
+         * (0 = Yes, 1 = Always allow, 2 = No). Yes is highlighted by default so Enter
+         * approves. Arrow Left/Right move it; Enter activates it. -1 when no batch is
+         * pending.
+         */
+        this._confirmationHighlighted = -1;
+        /**
+         * True while a confirmation decision (approve/deny) is being sent and its
+         * follow-up turn streams. Disables the approve/deny buttons so the batch can't
+         * be resolved twice.
+         */
+        this._confirmationInFlight = false;
         /**
          * INTERNAL-ONLY latest telemetry snapshot (last-value-wins). Populated from
          * `TOKEN_USAGE` events during streaming and hydrated from the conversation
@@ -374,6 +430,36 @@ let KRChatbot = class KRChatbot extends LitElement {
             document.removeEventListener('mouseup', this._handleMouseUp);
             this._saveState();
         };
+        /**
+         * Keyboard control for the confirmation prompt. Bound at the document so it
+         * works even though the composer (where focus usually sits) is blocked while a
+         * batch is pending: Left/Right move the highlight across Yes / Always allow /
+         * No, Enter activates the highlighted one. No-op when nothing is pending or a
+         * decision is already in flight.
+         */
+        this._handleDocumentKeydown = (e) => {
+            if (!this._pendingActions.length || this._confirmationInFlight) {
+                return;
+            }
+            if (e.key === 'ArrowRight') {
+                e.preventDefault();
+                this._confirmationHighlighted = (this._confirmationHighlighted + 1) % CONFIRMATION_DECISIONS.length;
+                return;
+            }
+            if (e.key === 'ArrowLeft') {
+                e.preventDefault();
+                this._confirmationHighlighted =
+                    (this._confirmationHighlighted - 1 + CONFIRMATION_DECISIONS.length) % CONFIRMATION_DECISIONS.length;
+                return;
+            }
+            if (e.key === 'Enter') {
+                e.preventDefault();
+                const option = CONFIRMATION_DECISIONS[this._confirmationHighlighted];
+                if (option) {
+                    this._handleConfirmationDecision(option.decision);
+                }
+            }
+        };
         this._handleDebugResizeMouseMove = (e) => {
             if (!this._isDebugResizing) {
                 return;
@@ -459,6 +545,9 @@ let KRChatbot = class KRChatbot extends LitElement {
         }
         this._restoreState();
         document.addEventListener('click', this._handleDocumentClick);
+        // Drive the confirmation prompt from the keyboard even when focus isn't in the
+        // (blocked) composer: Left/Right move the highlight, Enter activates it.
+        document.addEventListener('keydown', this._handleDocumentKeydown);
     }
     disconnectedCallback() {
         super.disconnectedCallback();
@@ -469,6 +558,7 @@ let KRChatbot = class KRChatbot extends LitElement {
         document.removeEventListener('mousemove', this._handleMouseMove);
         document.removeEventListener('mouseup', this._handleMouseUp);
         document.removeEventListener('click', this._handleDocumentClick);
+        document.removeEventListener('keydown', this._handleDocumentKeydown);
         // Release the mic if the chatbot is torn down mid-dictation — otherwise the
         // recognizer keeps the browser's recording indicator lit with nothing to
         // transcribe into. abort() (not stop()) since the discarded text has nowhere to go.
@@ -1343,6 +1433,13 @@ let KRChatbot = class KRChatbot extends LitElement {
         if (this._isStreaming) {
             return;
         }
+        // A guarded-tool batch is awaiting a decision. The turn lock released with
+        // its finished:true, but the server rejects a normal chat message with
+        // awaitingConfirmation until it's resolved — so the composer stays blocked
+        // and the approve/deny prompt owns the next call.
+        if (this._pendingActions.length) {
+            return;
+        }
         const messageText = this._inputValue.trim();
         const pending = this._pendingConversationFiles;
         // Allow sending an image with no text, but require at least one of them.
@@ -1449,6 +1546,22 @@ let KRChatbot = class KRChatbot extends LitElement {
         // the consumer hasn't provided their own `send`.
         if (!this.send) {
             this.send = (params) => {
+                // Rail-3 confirmation decision: resolve a paused guarded-tool batch by
+                // hitting the SAME streaming endpoint with `confirmation` set. There's no
+                // userText/files on this path (the server ignores message text here), and
+                // the conversation is always already pinned (a batch can't pause before
+                // the conversation exists), so no upload and no createNew.
+                if (params.confirmation) {
+                    return KRHttp.fetch({
+                        url: '/api/system/integration/aws/bedrock/stream/invokeModelForConversationWithState',
+                        method: 'POST',
+                        headers: { Accept: 'text/event-stream' },
+                        body: {
+                            confirmation: params.confirmation,
+                            conversationID: this.conversationId,
+                        },
+                    });
+                }
                 // Images are upload-first: each file is stored as a conversation file
                 // (type LIBRARY — the format lives in mimeType), then the resulting
                 // conversationFileIDs are attached to the message via `fileIds` on the
@@ -1588,6 +1701,59 @@ let KRChatbot = class KRChatbot extends LitElement {
             }
         });
     }
+    /**
+     * Resolve the paused guarded-tool batch (Rail 3). Hits the SAME streaming
+     * endpoint as a normal turn but with a `confirmation` value instead of a
+     * message; the server runs (approve/approveAlways) or denies (reject) the batch
+     * and continues the turn, streaming the outcome into a fresh assistant bubble.
+     *
+     * The decision uses the same `send` callback so a custom `send` can own its own
+     * targeting — it just receives `confirmation` set and no message.
+     */
+    _handleConfirmationDecision(decision) {
+        if (this._confirmationInFlight) {
+            return;
+        }
+        this._confirmationInFlight = true;
+        this._error = '';
+        // The batch is being resolved — drop the prompt so the composer unblocks once
+        // this follow-up turn ends, and stream the outcome into a new assistant bubble.
+        this._pendingActions = [];
+        this._confirmationHighlighted = -1;
+        this.messages = [...this.messages, {
+                type: 'assistant',
+                content: '',
+            }];
+        this._isStreaming = true;
+        this._userHasScrolledUp = false;
+        this.send({
+            message: '',
+            messages: this.messages.slice(0, -1),
+            conversationFiles: [],
+            pageContext: '',
+            selectionContext: '',
+            confirmation: decision,
+        }).then((response) => {
+            this._confirmationInFlight = false;
+            if (!response.ok) {
+                this._handleStreamError('Request failed: ' + response.status);
+                return;
+            }
+            if (!response.body) {
+                this._handleStreamError('No response body');
+                return;
+            }
+            this._reader = response.body.getReader();
+            this._decoder = new TextDecoder();
+            this._buffer = '';
+            this._readStreamChunk();
+        }).catch((err) => {
+            this._confirmationInFlight = false;
+            if (err.name !== 'AbortError') {
+                this._handleStreamError(err.message);
+            }
+        });
+    }
     /**
      * Capture ambient "where is the user / what are they looking at" context at
      * send time, so the AI is grounded without the host passing anything in.
@@ -1680,8 +1846,11 @@ let KRChatbot = class KRChatbot extends LitElement {
         }
         this._reader.read().then((result) => {
             if (result.done) {
-                this._isStreaming = false;
-                this._reader = null;
+                // Fallback unlock: the stream closed without a `finished:true` chunk
+                // (network drop, server crash, the 5-min emitter timeout). Treat it as
+                // the turn ending so a dropped stream never wedges the composer — the
+                // server self-heals its turn lock and bounces any premature send.
+                this._finishStream();
                 return;
             }
             this._buffer = this._buffer + this._decoder.decode(result.value, { stream: true });
@@ -1766,6 +1935,20 @@ let KRChatbot = class KRChatbot extends LitElement {
                         this._contextLimitMessage = String(data.message || '');
                         this._contextWarning = '';
                     }
+                    else if (data.type === 'ACTION_CONFIRMATION_REQUIRED') {
+                        // A guarded tool paused for approval (Rail 3). Carries finished:true
+                        // (handled below), so the turn lock releases — but the conversation
+                        // is now awaiting a decision, and a normal chat message would be
+                        // rejected with awaitingConfirmation. Capture the batch so the
+                        // composer stays blocked and the approve/deny prompt renders instead;
+                        // the next call must be a confirmation, not a userText.
+                        const actions = data.data?.actions;
+                        if (Array.isArray(actions) && actions.length) {
+                            this._pendingActions = actions;
+                            // Default the keyboard highlight to Yes so Enter approves.
+                            this._confirmationHighlighted = 0;
+                        }
+                    }
                     else if (data.type === 'TOKEN_USAGE') {
                         // INTERNAL-ONLY debug telemetry. Update the panel snapshot and the
                         // per-iteration log; never render as a chat bubble.
@@ -1796,11 +1979,17 @@ let KRChatbot = class KRChatbot extends LitElement {
                         }
                     }
                     if (data.finished) {
-                        this._isStreaming = false;
-                        this._reader = null;
+                        // Primary unlock signal: the turn is over and the server released
+                        // the turn lock. The SSE stream closes right after this chunk.
+                        this._finishStream();
                     }
                 }
             }
+            // Stop reading once a terminal chunk ended the turn — the reader is nulled
+            // by _finishStream and the stream is closing anyway.
+            if (!this._reader) {
+                return;
+            }
             this._readStreamChunk();
         }).catch((err) => {
             if (err.name !== 'AbortError') {
@@ -1808,6 +1997,32 @@ let KRChatbot = class KRChatbot extends LitElement {
             }
         });
     }
+    /**
+     * End the current turn: release the turn lock and the reader. Called on the
+     * primary unlock signal (`finished:true`) and the fallback (stream close).
+     *
+     * A turn that paused for confirmation (`_pendingActions` set) leaves the
+     * composer blocked even though the lock released — the approve/deny prompt
+     * owns the next call. Its trailing empty assistant bubble is dropped so the
+     * prompt doesn't sit under an empty message with a typing indicator.
+     */
+    _finishStream() {
+        this._isStreaming = false;
+        this._reader = null;
+        if (this._pendingActions.length) {
+            const lastIndex = this.messages.length - 1;
+            // Drop the trailing assistant bubble only when it's truly empty — no
+            // streamed text AND no reasoning. A reasoning-only bubble (the model thought
+            // out loud, then went straight to the guarded tool) must be kept, else its
+            // "Thinking" trace is lost when the confirmation card renders.
+            if (lastIndex >= 0
+                && this.messages[lastIndex].type === 'assistant'
+                && !this.messages[lastIndex].content
+                && !this.messages[lastIndex].reasoning) {
+                this.messages = this.messages.slice(0, -1);
+            }
+        }
+    }
     _handleStreamError(message) {
         this._isStreaming = false;
         this._error = message;
@@ -1824,6 +2039,52 @@ let KRChatbot = class KRChatbot extends LitElement {
         }
     }
     // --- Render ---
+    /**
+     * The approve/deny card shown when a guarded tool is paused (Rail 3). Floats
+     * OVER the messages, anchored just above the composer — not part of the message
+     * scroll — so it stays in view while the transcript scrolls behind it.
+     *
+     * Written for a non-technical user: one plain-language sentence saying what's
+     * about to happen (the model's schema-required `confirmationMessage`), then a
+     * row of Yes / Always allow / No. Deliberately NO tool code, NO raw
+     * arguments/JSON, and NO separate `description` line — those are noise (or
+     * alarming) to a normal user; the confirmation sentence is the whole story.
+     */
+    _renderConfirmation() {
+        // The framework confirms one guarded tool at a time, so we render the first
+        // (and only) pending action.
+        const action = this._pendingActions[0];
+        // Title names the tool being run ("Run {tool}?").
+        let title = 'Run this action?';
+        if (action) {
+            title = `Run ${action.displayName || action.toolName}?`;
+        }
+        return html `
+      <div
+        class="confirmation"
+        role="alertdialog"
+        aria-label="Confirm before continuing"
+      >
+        <div class="confirmation__title">${title}</div>
+        <p class="confirmation__message">${action?.confirmationMessage || 'The assistant wants to take an action. Is that OK?'}</p>
+        <div class="confirmation__actions">
+          ${CONFIRMATION_DECISIONS.map((option, index) => html `
+            <kr-button
+              class=${classMap({
+            'confirmation__btn': true,
+            'confirmation__btn--highlighted': index === this._confirmationHighlighted,
+        })}
+              variant=${option.decision === 'approve' ? 'flat' : 'outline'}
+              color=${option.decision === 'reject' ? 'secondary' : 'primary'}
+              size="small"
+              ?disabled=${this._confirmationInFlight}
+              @click=${() => this._handleConfirmationDecision(option.decision)}
+            >${option.label}</kr-button>
+          `)}
+        </div>
+      </div>
+    `;
+    }
     /** The `/` skill menu shown above the composer while typing a slash command. */
     _renderSkillMenu() {
         const skills = this._invocableSkills;
@@ -2447,6 +2708,8 @@ let KRChatbot = class KRChatbot extends LitElement {
           </div>
         </div>
 
+        ${this._pendingActions.length ? this._renderConfirmation() : nothing}
+
         ${this._error ? html `
           <div class="error">
             <span>${this._error}</span>
@@ -2642,10 +2905,13 @@ let KRChatbot = class KRChatbot extends LitElement {
               <button
                 class=${classMap({
             'send': true,
-            'send--disabled': !this._inputValue.trim() && !this._pendingConversationFiles.length,
+            // Blocked while a guarded-tool batch awaits a decision — a
+            // normal message would be rejected until it's resolved.
+            'send--disabled': (!this._inputValue.trim() && !this._pendingConversationFiles.length)
+                || this._pendingActions.length > 0,
         })}
                 @click=${this._handleSubmit}
-                title="Send message"
+                title=${this._pendingActions.length ? 'Approve or deny the pending action first' : 'Send message'}
               >
                 <svg
                   width="16"
@@ -3190,6 +3456,68 @@ KRChatbot.styles = css `
       flex-shrink: 0;
     }
 
+    /* Action-confirmation card (Rail 3). Floats OVER the messages, anchored just
+       above the composer — not part of the message scroll — so it stays put and
+       in view while the transcript scrolls behind it. Its width matches the
+       message text column: .messages-inner is 768px max with 32px padding, so the
+       text column is 768 - 64. Plain-language ask + Yes/No for a non-technical
+       user; no tool codes, no raw arguments. */
+    .confirmation {
+      position: absolute;
+      left: 32px;
+      right: 32px;
+      /* Sits above the footer/composer with a clear gap between the two. */
+      bottom: 104px;
+      z-index: 6;
+      max-width: 720px;
+      margin: 0 auto;
+      padding: 24px;
+      border: 1px solid #d8d8d8;
+      border-radius: 8px;
+      background: var(--kr-chatbot-bg);
+      color: var(--kr-chatbot-text);
+      box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);
+      /* Never taller than the panel leaves room for — scroll the card itself if a
+         batched multi-action ask is long, rather than covering the whole panel. */
+      max-height: calc(100% - 176px);
+      overflow-y: auto;
+    }
+
+    /* "Run {tool}?" heading — names the tool being run. */
+    .confirmation__title {
+      font-size: 16px;
+      font-weight: 600;
+      margin-bottom: 8px;
+    }
+
+    .confirmation__message {
+      margin: 0;
+      font-size: 14px;
+      line-height: 1.5;
+    }
+
+    .confirmation__message + .confirmation__message {
+      margin-top: 6px;
+    }
+
+    /* Buttons in a row; wrap on a narrow panel rather than overflowing the card. */
+    .confirmation__actions {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      gap: 8px;
+      margin-top: 16px;
+    }
+
+    /* Keyboard-highlighted decision — a focus ring around the button host, drawn
+       outside its border so it reads over both the flat (Yes) and outline
+       variants without recoloring the button itself. */
+    .confirmation__btn--highlighted {
+      border-radius: 8px;
+      outline: 2px solid var(--kr-chatbot-primary);
+      outline-offset: 2px;
+    }
+
     /*
      * INTERNAL-ONLY debug telemetry drawer. A layout drawer docked to the right
      * of the inline chat — the chat column shrinks to make room; it does not
@@ -4130,6 +4458,15 @@ __decorate([
 __decorate([
     state()
 ], KRChatbot.prototype, "_contextLimitMessage", void 0);
+__decorate([
+    state()
+], KRChatbot.prototype, "_pendingActions", void 0);
+__decorate([
+    state()
+], KRChatbot.prototype, "_confirmationHighlighted", void 0);
+__decorate([
+    state()
+], KRChatbot.prototype, "_confirmationInFlight", void 0);
 __decorate([
     state()
 ], KRChatbot.prototype, "_telemetry", void 0);