@qilin-agent/client-ui-approval 0.0.0-stage → 3.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,28 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/ui-approval/README.md
+/:
+  en: a16f3a25592b9a2d
+  zh: 6be5e99282ce23d9
+/qilin-client-ui-approval:
+  en: 0ac6bc9269959e2f
+  zh: 556b595de66d9f16
+/qilin-client-ui-approval/summary:
+  en: 8d6c7c6e63f849f6
+  zh: d89fa273e30b99d3
+/qilin-client-ui-approval/table-of-contents:
+  en: b4683d2a53256fda
+  zh: 4e65ff63dc8c48fe
+/qilin-client-ui-approval/model-experience:
+  en: 8161dce49e9f899c
+  zh: a17401e1e78ba6be
+/qilin-client-ui-approval/model-experience/kv-cache-effect:
+  en: adf7112e0691b89e
+  zh: 14eeddcff985119f
+/qilin-client-ui-approval/known-limitations-and-deferred-work:
+  en: 158f435625e41ca9
+  zh: 9d58169aaf6c7ed7
+/qilin-client-ui-approval/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: e88aeb617ffb74ea

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+---
+description: "Browser approval UI that answers Host permission requests through the scoped interaction path."
+kind: "package-reference"
+---
+# @qilin-agent/client-ui-approval
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English | [中文](README.zh.md)
+
+## Summary
+
+Browser approval presentation over the Agent-scoped Remote Event waterfall. The plugin publishes each pending request through `ctx.uiSession`, takes over the Conversation composer, optionally renders correlated Tool detail, and returns the user's decision to the waiting Host request. Use it when a browser must collect approval for a waiting Host operation.
+
+## Table of Contents
+
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as this package presents approval requests in the browser and registers nothing model-facing.
+
+#### KV Cache effect
+
+None; approval request and response rendering does not alter a model request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **The panel exposes transient decisions only** — it supports allow-once and reject; persistent permission policy remains owned by Host-side approval packages.
+
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,45 @@
+---
+description: "通过作用域交互路径响应 Host 权限请求的浏览器批准界面。"
+kind: "package-reference"
+---
+# @qilin-agent/client-ui-approval
+
+[English](README.md) | 中文
+
+## 概述
+
+基于 Agent-scoped Remote Event waterfall 的浏览器审批界面。插件通过 `ctx.uiSession` 发布每个待处理请求、接管 Conversation composer、按需渲染关联的 Tool 详情，并将用户决定返回给等待中的 Host 请求。当浏览器必须为等待中的 Host 操作收集批准时，请使用它。
+
+## 目录
+
+- [模型体验](#model-experience)
+- [已知限制与暂缓事项](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为本包只在浏览器中呈现审批请求，不注册任何面向模型的内容。
+
+#### KV Cache 影响
+
+无；审批请求和响应的呈现不会改变模型请求。
+
+## 已知限制与暂缓事项
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **面板只提供临时决定**——它支持仅本次允许和拒绝；持久权限策略仍由 Host 侧审批包拥有。
+
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/client.js

@@ -0,0 +1,353 @@
+window.__ModuleLoader__.load({
+	id: "@qilin-agent/client-ui-approval",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let react_jsx_runtime = require("react/jsx-runtime");
+		let react = require("react");
+		let _qilin_agent_client_ui_primitives = require("@qilin-agent/client-ui-primitives");
+		//#region \0qilin-css:/home/runner/work/QiLin/QiLin/packages/client/ui-approval/src/client/ApprovalPanel.module.css.mjs
+		const css = ".Dg9Iaq_root{padding:8px calc(var(--qilin-composer-side-clearance) + 16px) 12px;flex-direction:column;align-items:center;display:flex}.Dg9Iaq_card{width:100%;max-width:var(--qilin-chat-content-width);border:1px solid var(--qilin-alias-state-warn-secondary);background:var(--qilin-specific-input-major);box-shadow:var(--qilin-shadow-lv2);--qilin-scrollbar-thumb:var(--qilin-alias-scrollbar-bg-l2);--qilin-scrollbar-thumb-hover:var(--qilin-alias-scrollbar-hover-l2);border-radius:20px;overflow:hidden}.Dg9Iaq_strip{background:var(--qilin-alias-state-warn-tertiary);color:var(--qilin-alias-state-warn-primary);align-items:center;gap:8px;padding:10px 16px;font-size:13px;line-height:18px;display:flex}.Dg9Iaq_dot{corner-shape:round;background:var(--qilin-alias-state-warn-primary);border-radius:50%;width:8px;height:8px}.Dg9Iaq_body{box-sizing:border-box;max-height:var(--qilin-composer-text-max-height);flex-direction:column;gap:6px;padding:12px 16px 0;display:flex;overflow-y:auto}.Dg9Iaq_headline{color:var(--qilin-alias-label-primary);font-size:15px;font-weight:500;line-height:24px}.Dg9Iaq_command{color:var(--qilin-alias-label-tertiary);font-family:var(--ds-font-family-code);word-break:break-all;font-size:13px;line-height:20px}.Dg9Iaq_actionRow{justify-content:flex-end;gap:8px;padding:14px 16px;display:flex}.Dg9Iaq_reject:hover:not(:disabled){background:var(--qilin-alias-interactive-bg-hover-danger);color:var(--qilin-alias-state-error-primary);border-color:#0000}";
+		const tagId = "@qilin-agent/client-ui-approval/ApprovalPanel.module.css";
+		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
+			const tag = document.createElement("style");
+			tag.dataset.plugin = "@qilin-agent/client-ui-approval";
+			tag.dataset.pluginCss = tagId;
+			tag.textContent = css;
+			document.head.appendChild(tag);
+		}
+		var ApprovalPanel_module_css_default = {
+			"actionRow": "Dg9Iaq_actionRow",
+			"body": "Dg9Iaq_body",
+			"card": "Dg9Iaq_card",
+			"command": "Dg9Iaq_command",
+			"dot": "Dg9Iaq_dot",
+			"headline": "Dg9Iaq_headline",
+			"reject": "Dg9Iaq_reject",
+			"root": "Dg9Iaq_root",
+			"strip": "Dg9Iaq_strip"
+		};
+		//#endregion
+		//#region lib/types/client/ApprovalPanel.js
+		/** Composer takeover for one pending approval waterfall. */
+		/**
+		* Render one pending approval and its optional Tool-owned detail.
+		* @param props - selector-matched request and standard Slot props.
+		* @returns The approval composer takeover.
+		*/
+		function ApprovalPanel(props) {
+			const approval = props.matched;
+			const detail = approval.callId === void 0 ? null : props.renderSlot("conversation.approval.detail", { callId: approval.callId });
+			return (0, react_jsx_runtime.jsx)(ApprovalFlow, {
+				pending: approval,
+				reason: approval.displayReason === void 0 ? approval.reason : props.resolveReason(approval.displayReason),
+				detail,
+				t: props.t
+			}, approval.key);
+		}
+		function ApprovalFlow({ pending, reason, detail, t }) {
+			const [answered, setAnswered] = (0, react.useState)(false);
+			const active = (0, react.useRef)(false);
+			const waiting = (0, react.useRef)(false);
+			const composing = (0, react.useRef)(false);
+			const compositionEnded = (0, react.useRef)(false);
+			(0, react.useEffect)(() => {
+				active.current = true;
+				return () => {
+					active.current = false;
+				};
+			}, []);
+			const answer = (outcome) => {
+				if (waiting.current) return;
+				waiting.current = true;
+				setAnswered(true);
+				pending.answer(outcome).catch(() => {
+					if (!active.current) return;
+					waiting.current = false;
+					setAnswered(false);
+				});
+			};
+			const keydown = (event) => {
+				const element = event.target;
+				if (event.defaultPrevented || !event.currentTarget.contains(document.activeElement) || element.closest("input, textarea, select, [contenteditable=\"true\"], [contenteditable=\"\"]") !== null) return;
+				if (event.key !== "Enter" && event.key !== "Escape") return;
+				if (event.key === "Enter" && element.closest("button, a[href], [role=\"button\"]") !== null) return;
+				if (event.ctrlKey || event.metaKey || event.altKey || event.shiftKey) return;
+				event.preventDefault();
+				event.stopPropagation();
+				if (event.repeat || composing.current || compositionEnded.current || event.nativeEvent.isComposing || event.keyCode === 229) return;
+				answer(event.key === "Enter" ? "allowed-once" : "rejected");
+			};
+			return (0, react_jsx_runtime.jsx)("div", {
+				className: ApprovalPanel_module_css_default.root,
+				"data-approval-key": pending.key,
+				"aria-busy": answered,
+				onKeyDown: keydown,
+				onKeyUpCapture: () => {
+					compositionEnded.current = false;
+				},
+				children: (0, react_jsx_runtime.jsxs)("div", {
+					className: ApprovalPanel_module_css_default.card,
+					children: [
+						(0, react_jsx_runtime.jsxs)("div", {
+							className: ApprovalPanel_module_css_default.strip,
+							children: [(0, react_jsx_runtime.jsx)("span", { className: ApprovalPanel_module_css_default.dot }), t("waiting")]
+						}),
+						(0, react_jsx_runtime.jsxs)("div", {
+							className: ApprovalPanel_module_css_default.body,
+							"data-approval-scroll": "",
+							tabIndex: 0,
+							role: "group",
+							"aria-label": t("detail.aria"),
+							children: [(0, react_jsx_runtime.jsx)("div", {
+								className: ApprovalPanel_module_css_default.headline,
+								children: reason ?? t("escalation", { toolName: pending.toolName })
+							}), detail !== null && (0, react_jsx_runtime.jsx)("div", {
+								className: ApprovalPanel_module_css_default.command,
+								children: detail
+							})]
+						}),
+						(0, react_jsx_runtime.jsxs)("div", {
+							className: ApprovalPanel_module_css_default.actionRow,
+							children: [(0, react_jsx_runtime.jsx)(_qilin_agent_client_ui_primitives.Button, {
+								variant: "outline",
+								className: ApprovalPanel_module_css_default.reject,
+								disabled: answered,
+								onClick: () => {
+									answer("rejected");
+								},
+								children: t("reject")
+							}), (0, react_jsx_runtime.jsx)(_qilin_agent_client_ui_primitives.Button, {
+								variant: "primary",
+								disabled: answered,
+								onClick: () => {
+									answer("allowed-once");
+								},
+								children: t("allowOnce")
+							})]
+						})
+					]
+				})
+			});
+		}
+		//#endregion
+		//#region lib/types/client/contract/slots.js
+		function settlePendingComposer(settle, failureMessage) {
+			try {
+				settle();
+				return Promise.resolve();
+			} catch (error) {
+				return Promise.reject(error instanceof Error ? error : new Error(failureMessage, { cause: error }));
+			}
+		}
+		let nextApprovalKey = 0;
+		/** One answerable Client presentation of a pending Host waterfall. */
+		var PendingApproval = class {
+			sessionId;
+			/** Domain discriminator used by Session pending-interaction consumers. */
+			kind;
+			/** Opaque render identity and one-shot remount axis. */
+			key;
+			/** Tool requesting the decision. */
+			toolName;
+			/** Correlated Tool call, when supplied by the asker. */
+			callId;
+			/** Human-readable reason supplied by the asker. */
+			reason;
+			/** Localized presentation copy, when supplied by the asker. */
+			displayReason;
+			/** Result returned by the Remote Event listener to the Host waterfall. */
+			result;
+			#resolve;
+			#reject;
+			#signal;
+			#onAbort;
+			#delegated = Symbol("pending approval delegated");
+			#settled = false;
+			/**
+			* @param sessionId - Agent/Session identity owning the scoped request.
+			* @param request - Host approval request projected through the Remote Event.
+			*/
+			constructor(sessionId, request) {
+				this.sessionId = sessionId;
+				this.kind = "approval";
+				nextApprovalKey += 1;
+				this.key = `approval:${String(nextApprovalKey)}`;
+				this.toolName = request.toolName;
+				this.callId = request.callId;
+				this.reason = request.reason;
+				this.displayReason = request.displayReason;
+				const completion = Promise.withResolvers();
+				this.result = completion.promise;
+				this.#resolve = completion.resolve;
+				this.#reject = completion.reject;
+				this.#signal = request.signal;
+				if (request.signal === void 0) {
+					this.#onAbort = void 0;
+					return;
+				}
+				const onAbort = () => {
+					this.abort(request.signal?.reason ?? /* @__PURE__ */ new Error("approval request was aborted"));
+				};
+				this.#onAbort = onAbort;
+				request.signal.addEventListener("abort", onAbort, { once: true });
+				if (request.signal.aborted) onAbort();
+			}
+			/**
+			* Resolve the Host waterfall with the user's decision.
+			* @param outcome - supported interactive decision.
+			*/
+			answer(outcome) {
+				return settlePendingComposer(() => {
+					this.finish(() => {
+						this.#resolve(outcome);
+					});
+				}, "pending approval settlement failed");
+			}
+			/** Delegate an unanswered request to the next waterfall listener. */
+			delegate() {
+				if (this.#settled) return;
+				this.finish(() => {
+					this.#reject(this.#delegated);
+				});
+			}
+			/**
+			* Test whether a rejection requests waterfall delegation.
+			* @param reason - rejection received from {@link PendingApproval.result}.
+			* @returns whether {@link PendingApproval.delegate} produced it.
+			*/
+			isDelegation(reason) {
+				return reason === this.#delegated;
+			}
+			/**
+			* End an unanswered presentation when its transport, scope, or plugin lifetime ends.
+			* @param reason - rejection exposed to the waiting Remote Event listener.
+			*/
+			abort(reason) {
+				if (this.#settled) return;
+				this.finish(() => {
+					this.#reject(reason);
+				});
+			}
+			finish(settle) {
+				if (this.#settled) throw new Error(`pending approval ${this.key} is already settled`);
+				this.#settled = true;
+				if (this.#signal !== void 0 && this.#onAbort !== void 0) this.#signal.removeEventListener("abort", this.#onAbort);
+				settle();
+			}
+		};
+		//#endregion
+		//#region lib/types/client/locales.js
+		/** `approval` namespace dictionaries. */
+		/** Simplified Chinese dictionary and key-set source of truth. */
+		const zh = {
+			waiting: "等待审批",
+			"detail.aria": "审批详情",
+			escalation: "工具 {toolName} 请求越权执行",
+			reject: "拒绝",
+			allowOnce: "允许一次"
+		};
+		/** English dictionary, checked against the Chinese key set. */
+		const en = {
+			waiting: "Waiting for approval",
+			"detail.aria": "Approval details",
+			escalation: "Tool {toolName} requests privileged execution",
+			reject: "Reject",
+			allowOnce: "Allow once"
+		};
+		//#endregion
+		//#region lib/types/client/index.js
+		/** Required services: Agent scopes, Remote Events, Session UI, Slot registry, and copy. */
+		const inject = [
+			"sessions",
+			"remote",
+			"uiSession",
+			"slots",
+			"locale"
+		];
+		const NS = "approval";
+		/** Present one request until the user answers or its lifetime ends. */
+		async function answerApproval(ctx, owner, request, next, registerPendingInteraction) {
+			const sessionId = ctx.sessions.scopeOf(owner);
+			if (sessionId === void 0) return next();
+			const pending = new PendingApproval(sessionId, {
+				toolName: request.toolName,
+				...request.callId === void 0 ? {} : { callId: request.callId },
+				...request.reason === void 0 ? {} : { reason: request.reason },
+				...request.displayReason === void 0 ? {} : { displayReason: request.displayReason },
+				...request.signal === void 0 ? {} : { signal: request.signal }
+			});
+			const completed = Promise.withResolvers();
+			const remove = registerPendingInteraction(pending, async () => {
+				pending.delegate();
+				await completed.promise;
+			});
+			try {
+				try {
+					return await pending.result;
+				} catch (error) {
+					if (pending.isDelegation(error)) return await next();
+					throw error;
+				}
+			} finally {
+				remove();
+				completed.resolve();
+			}
+		}
+		/**
+		* Install approval copy and the scoped waterfall consumer.
+		* @param ctx - Client root context.
+		*/
+		function apply(ctx) {
+			ctx.effect(() => ctx.locale.register(NS, {
+				zh,
+				en
+			}), "ui-approval: dictionaries");
+			ctx.inject(["shortcuts"], (scope) => {
+				const t = ctx.locale.bind(NS);
+				scope.effect(() => scope.shortcuts.registerFixed({
+					id: "approval.allow",
+					label: () => t("allowOnce"),
+					keys: ["Enter"],
+					bindings: [{
+						code: "Enter",
+						modifiers: []
+					}],
+					group: "approval"
+				}), "ui-approval: fixed allow reference");
+				scope.effect(() => scope.shortcuts.registerFixed({
+					id: "approval.reject",
+					label: () => t("reject"),
+					keys: ["Esc"],
+					bindings: [{
+						code: "Escape",
+						modifiers: []
+					}],
+					group: "approval"
+				}), "ui-approval: fixed reject reference");
+			});
+			const registerPendingInteraction = ctx.uiSession.registerPendingInteraction(() => 0);
+			ctx.slots.inject("conversation.composer", () => ctx.slots.register({
+				name: "conversation.composer",
+				priority: 1,
+				select: ({ pendingInteraction }) => pendingInteraction instanceof PendingApproval ? pendingInteraction : null,
+				locale: NS,
+				inject: () => ({ resolveReason: (reason) => ctx.locale.resolveText(reason) }),
+				children: { "conversation.approval.detail": {
+					kind: "single",
+					scope: "session"
+				} }
+			}, ApprovalPanel));
+			ctx.remote.$on("approval/request", function(request, next) {
+				return answerApproval(ctx, this, request, next, registerPendingInteraction);
+			});
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/index.js

@@ -0,0 +1,6 @@
+//#region lib/types/index.js
+/** Browser-only approval presentation plugin; the Host capability is composed independently. */
+/** Node plugin body. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/types/client/ApprovalPanel.d.ts

@@ -0,0 +1,8 @@
+import type { ApprovalComposerProps } from './contract/slots.ts';
+/**
+ * Render one pending approval and its optional Tool-owned detail.
+ * @param props - selector-matched request and standard Slot props.
+ * @returns The approval composer takeover.
+ */
+export declare function ApprovalPanel(props: ApprovalComposerProps): import("react").JSX.Element;
+//# sourceMappingURL=ApprovalPanel.d.ts.map

package/lib/types/client/contract/slots.d.ts

@@ -0,0 +1,105 @@
+/** Approval composer and optional correlated-detail contracts. */
+import type { ToolCallId } from '@qilin-agent/llm';
+import type { SessionId } from '@qilin-agent/session/types';
+import type { PropsLocale, PropsRenderSlots, PropsRuntime } from '@qilin-agent/client-ui-slots';
+import type { ApprovalKey } from '../locales.ts';
+declare module '@qilin-agent/client-ui-session/client' {
+    interface SessionPendingInteractionMap {
+        /** Pending approval request. */
+        approval: PendingApproval;
+    }
+}
+declare module '@qilin-agent/client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Approval prompt copy. */
+        approval: ApprovalKey;
+    }
+    interface SlotMap {
+        /** Optional detail for the Tool call correlated with an approval request. */
+        'conversation.approval.detail': {
+            kind: 'single';
+            scope: 'session';
+            owner: ApprovalDetailOwnerProps;
+        };
+    }
+}
+/** Stable identity handed to an optional approval-detail renderer. */
+export interface ApprovalDetailOwnerProps {
+    /** Tool call correlated with the request. */
+    callId: ToolCallId;
+}
+/** Client-visible fields of an approval request projected through Remote Events. */
+export interface ApprovalPresentationRequest {
+    /** Tool requesting the decision. */
+    readonly toolName: string;
+    /** Tool call correlated with the request. */
+    readonly callId?: ToolCallId;
+    /** Human-readable reason supplied by the requester. */
+    readonly reason?: string;
+    /** Localized presentation copy; the audit reason remains unchanged. */
+    readonly displayReason?: {
+        readonly en: string;
+        readonly [locale: string]: string;
+    };
+    /** Cancellation projected from the Host waterfall. */
+    readonly signal?: AbortSignal;
+}
+/** Decisions this interactive Client presentation can return. */
+export type ApprovalDecision = 'allowed-once' | 'rejected';
+/** One answerable Client presentation of a pending Host waterfall. */
+export declare class PendingApproval {
+    #private;
+    readonly sessionId: SessionId;
+    /** Domain discriminator used by Session pending-interaction consumers. */
+    readonly kind: 'approval';
+    /** Opaque render identity and one-shot remount axis. */
+    readonly key: string;
+    /** Tool requesting the decision. */
+    readonly toolName: string;
+    /** Correlated Tool call, when supplied by the asker. */
+    readonly callId: ToolCallId | undefined;
+    /** Human-readable reason supplied by the asker. */
+    readonly reason: string | undefined;
+    /** Localized presentation copy, when supplied by the asker. */
+    readonly displayReason: ApprovalPresentationRequest['displayReason'];
+    /** Result returned by the Remote Event listener to the Host waterfall. */
+    readonly result: Promise<ApprovalDecision>;
+    /**
+     * @param sessionId - Agent/Session identity owning the scoped request.
+     * @param request - Host approval request projected through the Remote Event.
+     */
+    constructor(sessionId: SessionId, request: ApprovalPresentationRequest);
+    /**
+     * Resolve the Host waterfall with the user's decision.
+     * @param outcome - supported interactive decision.
+     */
+    answer(outcome: ApprovalDecision): Promise<void>;
+    /** Delegate an unanswered request to the next waterfall listener. */
+    delegate(): void;
+    /**
+     * Test whether a rejection requests waterfall delegation.
+     * @param reason - rejection received from {@link PendingApproval.result}.
+     * @returns whether {@link PendingApproval.delegate} produced it.
+     */
+    isDelegation(reason: unknown): boolean;
+    /**
+     * End an unanswered presentation when its transport, scope, or plugin lifetime ends.
+     * @param reason - rejection exposed to the waiting Remote Event listener.
+     */
+    abort(reason: unknown): void;
+    private finish;
+}
+/** Locale lookup supplied by the approval registration. */
+export interface ApprovalInjected {
+    /**
+     * Resolve requester-owned copy in the current UI language.
+     * @param reason - localized presentation text with an English fallback.
+     * @returns text for the active UI language.
+     */
+    resolveReason(reason: NonNullable<ApprovalPresentationRequest['displayReason']>): string;
+}
+/** Full props of the approval composer takeover. */
+export type ApprovalComposerProps = PropsRuntime<'conversation.composer'> & PropsRenderSlots<'conversation.approval.detail'> & {
+    matched: PendingApproval;
+} & PropsLocale<'approval'> & ApprovalInjected;
+//# sourceMappingURL=slots.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,12 @@
+/** Browser approval consumer over the existing scoped Remote Event waterfall. */
+import type { Context as ClientContext } from '@qilin-agent/kylin';
+export type { ApprovalComposerProps, ApprovalDecision, ApprovalDetailOwnerProps, ApprovalPresentationRequest, PendingApproval, } from './contract/slots.ts';
+export type { ApprovalKey } from './locales.ts';
+/** Required services: Agent scopes, Remote Events, Session UI, Slot registry, and copy. */
+export declare const inject: string[];
+/**
+ * Install approval copy and the scoped waterfall consumer.
+ * @param ctx - Client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,20 @@
+/** `approval` namespace dictionaries. */
+/** Simplified Chinese dictionary and key-set source of truth. */
+export declare const zh: {
+    waiting: string;
+    'detail.aria': string;
+    escalation: string;
+    reject: string;
+    allowOnce: string;
+};
+/** Approval dictionary key union. */
+export type ApprovalKey = keyof typeof zh;
+/** English dictionary, checked against the Chinese key set. */
+export declare const en: {
+    waiting: string;
+    'detail.aria': string;
+    escalation: string;
+    reject: string;
+    allowOnce: string;
+};
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+/** Browser-only approval presentation plugin; the Host capability is composed independently. */
+/** Node plugin body. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@qilin-agent/client-ui-approval",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Approval composer takeover over the scoped Remote Event waterfall",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/ui-approval"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "qilin": {
+    "client": {
+      "inject": [
+        "@qilin-agent/api-remotes",
+        "@qilin-agent/api-session-controller",
+        "@qilin-agent/client-locale",
+        "@qilin-agent/client-shortcuts",
+        "@qilin-agent/client-ui-conversation",
+        "@qilin-agent/client-ui-renderer",
+        "@qilin-agent/client-ui-session"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/api-remotes": "3.1.3",
+    "@qilin-agent/api-session-controller": "3.1.3",
+    "@qilin-agent/client-ui-conversation": "3.1.3",
+    "@qilin-agent/client-shortcuts": "3.1.3",
+    "@qilin-agent/client-locale": "3.1.3",
+    "@qilin-agent/client-ui-primitives": "3.1.3",
+    "@qilin-agent/client-ui-renderer": "3.1.3",
+    "@qilin-agent/client-ui-session": "3.1.3",
+    "@qilin-agent/client-ui-slots": "3.1.3",
+    "@qilin-agent/llm": "3.1.3",
+    "@qilin-agent/typert-protocol": "3.1.3",
+    "@qilin-agent/session": "3.1.3"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }