berry-agent 0.1.0-alpha.1

package/dist/webui/assets/index-DOlgSZ9Q.css

@@ -0,0 +1,2 @@
+/*! tailwindcss v4.3.3 | MIT License | https://tailwindcss.com */
+@layer properties{@supports (((-webkit-hyphens:none)) and (not (margin-trim:inline))) or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))){*,:before,:after,::backdrop{--tw-space-y-reverse:0;--tw-border-style:solid;--tw-leading:initial;--tw-font-weight:initial;--tw-tracking:initial}}}@layer theme{:root,:host{--font-sans:-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";--font-mono:ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;--color-red-200:oklch(88.5% .062 18.334);--color-red-400:oklch(70.4% .191 22.216);--color-red-700:oklch(50.5% .213 27.518);--color-red-800:oklch(44.4% .177 26.899);--color-red-900:oklch(39.6% .141 25.723);--color-amber-200:oklch(92.4% .12 95.746);--color-amber-900:oklch(41.4% .112 45.904);--color-emerald-200:oklch(90.5% .093 164.15);--color-emerald-600:oklch(59.6% .145 163.225);--color-emerald-700:oklch(50.8% .118 165.612);--color-emerald-900:oklch(37.8% .077 168.94);--color-sky-200:oklch(90.1% .058 230.902);--color-sky-900:oklch(39.1% .09 240.876);--color-zinc-100:oklch(96.7% .001 286.375);--color-zinc-200:oklch(92% .004 286.32);--color-zinc-300:oklch(87.1% .006 286.286);--color-zinc-400:oklch(70.5% .015 286.067);--color-zinc-500:oklch(55.2% .016 285.938);--color-zinc-600:oklch(44.2% .017 285.786);--color-zinc-700:oklch(37% .013 285.805);--color-zinc-800:oklch(27.4% .006 286.033);--color-zinc-900:oklch(21% .006 285.885);--color-zinc-950:oklch(14.1% .005 285.823);--color-white:#fff;--spacing:.25rem;--text-xs:.75rem;--text-xs--line-height:calc(1 / .75);--text-sm:.875rem;--text-sm--line-height:calc(1.25 / .875);--text-base:1rem;--text-base--line-height:calc(1.5 / 1);--font-weight-medium:500;--font-weight-semibold:600;--tracking-wide:.025em;--radius-lg:.5rem;--animate-pulse:pulse 2s cubic-bezier(.4, 0, .6, 1) infinite;--default-font-family:var(--font-sans);--default-mono-font-family:var(--font-mono)}}@layer base{*,:after,:before,::backdrop{box-sizing:border-box;border:0 solid;margin:0;padding:0}::file-selector-button{box-sizing:border-box;border:0 solid;margin:0;padding:0}html,:host{-webkit-text-size-adjust:100%;tab-size:4;line-height:1.5;font-family:var(--default-font-family,-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji");font-feature-settings:var(--default-font-feature-settings,normal);font-variation-settings:var(--default-font-variation-settings,normal);-webkit-tap-highlight-color:transparent}hr{height:0;color:inherit;border-top-width:1px}abbr:where([title]){-webkit-text-decoration:underline dotted;text-decoration:underline dotted}h1,h2,h3,h4,h5,h6{font-size:inherit;font-weight:inherit}a{color:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;-webkit-text-decoration:inherit;text-decoration:inherit}b,strong{font-weight:bolder}code,kbd,samp,pre{font-family:var(--default-mono-font-family,ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace);font-feature-settings:var(--default-mono-font-feature-settings,normal);font-variation-settings:var(--default-mono-font-variation-settings,normal);font-size:1em}small{font-size:80%}sub,sup{vertical-align:baseline;font-size:75%;line-height:0;position:relative}sub{bottom:-.25em}sup{top:-.5em}table{text-indent:0;border-color:inherit;border-collapse:collapse}:-moz-focusring:where(:not(iframe)){outline:auto}progress{vertical-align:baseline}summary{display:list-item}ol,ul,menu{list-style:none}img,svg,video,canvas,audio,iframe,embed,object{vertical-align:middle;display:block}img,video{max-width:100%;height:auto}button,input,select,optgroup,textarea{font:inherit;font-feature-settings:inherit;font-variation-settings:inherit;letter-spacing:inherit;color:inherit;opacity:1;background-color:#0000;border-radius:0}::file-selector-button{font:inherit;font-feature-settings:inherit;font-variation-settings:inherit;letter-spacing:inherit;color:inherit;opacity:1;background-color:#0000;border-radius:0}:where(select:is([multiple],[size])) optgroup{font-weight:bolder}:where(select:is([multiple],[size])) optgroup option{padding-inline-start:20px}::file-selector-button{margin-inline-end:4px}::placeholder{opacity:1}@supports (not ((-webkit-appearance:-apple-pay-button))) or (contain-intrinsic-size:1px){::placeholder{color:currentColor}@supports (color:color-mix(in lab, red, red)){::placeholder{color:color-mix(in oklab, currentcolor 50%, transparent)}}}textarea{resize:vertical}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-date-and-time-value{min-height:1lh;text-align:inherit}::-webkit-datetime-edit{display:inline-flex}::-webkit-datetime-edit-fields-wrapper{padding:0}::-webkit-datetime-edit{padding-block:0}::-webkit-datetime-edit-year-field{padding-block:0}::-webkit-datetime-edit-month-field{padding-block:0}::-webkit-datetime-edit-day-field{padding-block:0}::-webkit-datetime-edit-hour-field{padding-block:0}::-webkit-datetime-edit-minute-field{padding-block:0}::-webkit-datetime-edit-second-field{padding-block:0}::-webkit-datetime-edit-millisecond-field{padding-block:0}::-webkit-datetime-edit-meridiem-field{padding-block:0}::-webkit-calendar-picker-indicator{line-height:1}:-moz-ui-invalid{box-shadow:none}button,input:where([type=button],[type=reset],[type=submit]){appearance:button}::file-selector-button{appearance:button}::-webkit-inner-spin-button{height:auto}::-webkit-outer-spin-button{height:auto}[hidden]:where(:not([hidden=until-found])){display:none!important}}@layer components;@layer utilities{.static{position:static}.mt-1{margin-top:var(--spacing)}.mt-2{margin-top:calc(var(--spacing) * 2)}.mr-16{margin-right:calc(var(--spacing) * 16)}.mb-0\.5{margin-bottom:calc(var(--spacing) * .5)}.mb-1{margin-bottom:var(--spacing)}.mb-2{margin-bottom:calc(var(--spacing) * 2)}.mb-3{margin-bottom:calc(var(--spacing) * 3)}.mb-4{margin-bottom:calc(var(--spacing) * 4)}.ml-2{margin-left:calc(var(--spacing) * 2)}.ml-16{margin-left:calc(var(--spacing) * 16)}.block{display:block}.flex{display:flex}.h-screen{height:100vh}.max-h-40{max-height:calc(var(--spacing) * 40)}.max-h-48{max-height:calc(var(--spacing) * 48)}.min-h-0{min-height:0}.min-h-\[2\.5rem\]{min-height:2.5rem}.w-64{width:calc(var(--spacing) * 64)}.w-72{width:calc(var(--spacing) * 72)}.w-80{width:calc(var(--spacing) * 80)}.w-full{width:100%}.max-w-none{max-width:none}.min-w-0{min-width:0}.flex-1{flex:1}.shrink-0{flex-shrink:0}.animate-pulse{animation:var(--animate-pulse)}.resize-y{resize:vertical}.flex-col{flex-direction:column}.items-center{align-items:center}.items-end{align-items:flex-end}.justify-between{justify-content:space-between}.justify-center{justify-content:center}.gap-1\.5{gap:calc(var(--spacing) * 1.5)}.gap-2{gap:calc(var(--spacing) * 2)}:where(.space-y-0\.5>:not(:last-child)){--tw-space-y-reverse:0;margin-block-start:calc(calc(var(--spacing) * .5) * var(--tw-space-y-reverse));margin-block-end:calc(calc(var(--spacing) * .5) * calc(1 - var(--tw-space-y-reverse)))}:where(.space-y-2>:not(:last-child)){--tw-space-y-reverse:0;margin-block-start:calc(calc(var(--spacing) * 2) * var(--tw-space-y-reverse));margin-block-end:calc(calc(var(--spacing) * 2) * calc(1 - var(--tw-space-y-reverse)))}:where(.space-y-4>:not(:last-child)){--tw-space-y-reverse:0;margin-block-start:calc(calc(var(--spacing) * 4) * var(--tw-space-y-reverse));margin-block-end:calc(calc(var(--spacing) * 4) * calc(1 - var(--tw-space-y-reverse)))}.truncate{text-overflow:ellipsis;white-space:nowrap;overflow:hidden}.overflow-y-auto{overflow-y:auto}.rounded{border-radius:.25rem}.rounded-lg{border-radius:var(--radius-lg)}.border{border-style:var(--tw-border-style);border-width:1px}.border-t{border-top-style:var(--tw-border-style);border-top-width:1px}.border-r{border-right-style:var(--tw-border-style);border-right-width:1px}.border-b{border-bottom-style:var(--tw-border-style);border-bottom-width:1px}.border-l{border-left-style:var(--tw-border-style);border-left-width:1px}.border-zinc-700{border-color:var(--color-zinc-700)}.border-zinc-800{border-color:var(--color-zinc-800)}.bg-amber-900\/60{background-color:#7b330699}@supports (color:color-mix(in lab, red, red)){.bg-amber-900\/60{background-color:color-mix(in oklab, var(--color-amber-900) 60%, transparent)}}.bg-emerald-700\/80{background-color:#007956cc}@supports (color:color-mix(in lab, red, red)){.bg-emerald-700\/80{background-color:color-mix(in oklab, var(--color-emerald-700) 80%, transparent)}}.bg-emerald-900\/60{background-color:#004e3b99}@supports (color:color-mix(in lab, red, red)){.bg-emerald-900\/60{background-color:color-mix(in oklab, var(--color-emerald-900) 60%, transparent)}}.bg-red-800\/80{background-color:#9f0712cc}@supports (color:color-mix(in lab, red, red)){.bg-red-800\/80{background-color:color-mix(in oklab, var(--color-red-800) 80%, transparent)}}.bg-red-900\/60{background-color:#82181a99}@supports (color:color-mix(in lab, red, red)){.bg-red-900\/60{background-color:color-mix(in oklab, var(--color-red-900) 60%, transparent)}}.bg-sky-900\/60{background-color:#024a7099}@supports (color:color-mix(in lab, red, red)){.bg-sky-900\/60{background-color:color-mix(in oklab, var(--color-sky-900) 60%, transparent)}}.bg-zinc-200{background-color:var(--color-zinc-200)}.bg-zinc-800{background-color:var(--color-zinc-800)}.bg-zinc-900{background-color:var(--color-zinc-900)}.bg-zinc-950{background-color:var(--color-zinc-950)}.p-2{padding:calc(var(--spacing) * 2)}.p-3{padding:calc(var(--spacing) * 3)}.p-4{padding:calc(var(--spacing) * 4)}.p-5{padding:calc(var(--spacing) * 5)}.px-2{padding-inline:calc(var(--spacing) * 2)}.px-3{padding-inline:calc(var(--spacing) * 3)}.px-4{padding-inline:calc(var(--spacing) * 4)}.px-6{padding-inline:calc(var(--spacing) * 6)}.py-0\.5{padding-block:calc(var(--spacing) * .5)}.py-1{padding-block:var(--spacing)}.py-1\.5{padding-block:calc(var(--spacing) * 1.5)}.py-2{padding-block:calc(var(--spacing) * 2)}.py-3{padding-block:calc(var(--spacing) * 3)}.py-4{padding-block:calc(var(--spacing) * 4)}.pb-2{padding-bottom:calc(var(--spacing) * 2)}.text-left{text-align:left}.text-base{font-size:var(--text-base);line-height:var(--tw-leading,var(--text-base--line-height))}.text-sm{font-size:var(--text-sm);line-height:var(--tw-leading,var(--text-sm--line-height))}.text-xs{font-size:var(--text-xs);line-height:var(--tw-leading,var(--text-xs--line-height))}.text-\[10px\]{font-size:10px}.text-\[11px\]{font-size:11px}.text-\[13px\]{font-size:13px}.leading-6{--tw-leading:calc(var(--spacing) * 6);line-height:calc(var(--spacing) * 6)}.font-medium{--tw-font-weight:var(--font-weight-medium);font-weight:var(--font-weight-medium)}.font-semibold{--tw-font-weight:var(--font-weight-semibold);font-weight:var(--font-weight-semibold)}.tracking-wide{--tw-tracking:var(--tracking-wide);letter-spacing:var(--tracking-wide)}.whitespace-pre-wrap{white-space:pre-wrap}.text-amber-200{color:var(--color-amber-200)}.text-emerald-200{color:var(--color-emerald-200)}.text-red-200{color:var(--color-red-200)}.text-red-400{color:var(--color-red-400)}.text-sky-200{color:var(--color-sky-200)}.text-white{color:var(--color-white)}.text-zinc-100{color:var(--color-zinc-100)}.text-zinc-200{color:var(--color-zinc-200)}.text-zinc-300{color:var(--color-zinc-300)}.text-zinc-400{color:var(--color-zinc-400)}.text-zinc-500{color:var(--color-zinc-500)}.text-zinc-600{color:var(--color-zinc-600)}.text-zinc-900{color:var(--color-zinc-900)}.uppercase{text-transform:uppercase}.opacity-60{opacity:.6}.outline-none{--tw-outline-style:none;outline-style:none}@media (hover:hover){.hover\:bg-emerald-600:hover{background-color:var(--color-emerald-600)}.hover\:bg-red-700:hover{background-color:var(--color-red-700)}.hover\:bg-white:hover{background-color:var(--color-white)}.hover\:bg-zinc-700:hover{background-color:var(--color-zinc-700)}.hover\:bg-zinc-800:hover{background-color:var(--color-zinc-800)}.hover\:bg-zinc-900:hover{background-color:var(--color-zinc-900)}}.focus\:border-zinc-500:focus{border-color:var(--color-zinc-500)}.disabled\:opacity-40:disabled{opacity:.4}.disabled\:opacity-50:disabled{opacity:.5}.\[\&_code\]\:rounded code{border-radius:.25rem}.\[\&_code\]\:bg-zinc-800 code{background-color:var(--color-zinc-800)}.\[\&_code\]\:px-1 code{padding-inline:var(--spacing)}.\[\&_pre\]\:rounded pre{border-radius:.25rem}.\[\&_pre\]\:bg-zinc-950 pre{background-color:var(--color-zinc-950)}.\[\&_pre\]\:p-2 pre{padding:calc(var(--spacing) * 2)}}@property --tw-space-y-reverse{syntax:"*";inherits:false;initial-value:0}@property --tw-border-style{syntax:"*";inherits:false;initial-value:solid}@property --tw-leading{syntax:"*";inherits:false}@property --tw-font-weight{syntax:"*";inherits:false}@property --tw-tracking{syntax:"*";inherits:false}@keyframes pulse{50%{opacity:.5}}

package/dist/webui/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="dark" />
+    <title>berry-agent</title>
+    <script type="module" crossorigin src="/assets/index-B-t2O8gh.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DOlgSZ9Q.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/dist/webui/index.js

@@ -0,0 +1,14 @@
+/**
+ * webui 模块公开面（L4 core: 官方插件 15 之 #13——02 §4.1 席 25 / 03
+ * §10.4 webui 件章 + 批 18a-2' 改形注记：SSE + 微路由 + 跨入口审批，
+ * 承载位改注册 sdk 路由扩展位——零自持监听）。
+ *
+ * 批 18a-1 服务端核心 → 18a-2' 改形：backend（UiBackend 第四实装——claim
+ * 桥）+ 微路由五撮 + SSE 信封三族全维持，防线/token/体帽/SSE 基建归面级
+ * 单源；本面出 mountWebui（路由族注册形）。SPA 客户端腿（dist/webui/
+ * 静态面）已落（6881b38）；host `--port` 归一已落（18a-3' 三入口咬合——
+ * TUI/serve/daemon 共用统一 HTTP 面端口）。
+ */
+import './types.js';
+export { WEBUI_DEFAULT_PORT, WEBUI_DEFAULT_HOST, WEBUI_MAX_CONNECTIONS, WEBUI_BODY_LIMIT_BYTES, WEBUI_COOKIE_NAME, WEBUI_ENDPOINTS, } from './types.js';
+export { mountWebui } from './server.js';

package/dist/webui/server.js

@@ -0,0 +1,549 @@
+/**
+ * webui/server — Web 通道路由实装（03 §10.4 批 18a-2' 改形；批 18a-1 传输
+ * 实装 → 承载位改注册）。
+ *
+ * **承载位改注册（18a-2'——03 §10.4 改形注记 + §10.6 路由扩展位段）**：
+ * 件零自持 node:http 监听——mountWebui(deps) 把五撮 13 端点 + SPA fallback
+ * 逐条注册进注入的注册器（sdk 面注册器结构兼容）。归面级的四块（原自持
+ * 已删）：三防线（Host 白名单/Origin 硬防线——面级先行适用于一切路由，仅
+ * TCP）/ token 鉴权执法（token-or-cookie 档 Bearer ∪ cookie 双通道、恒时
+ * 比对——面 token 唯一验换位 ctx.verifyToken）/ POST 体帽与排空纪律
+ * （ctx.readBody——超帽 413 永不早于体收完）/ SSE 单流基建（帧形/ping/
+ * 看门狗/shedding——ctx.openSse 注入件侧可丢判据）。
+ *
+ * 件内维持位（§10.4 改形注②-⑦语义全保）：
+ * - **backend**：UiBackend 第四实装（claim 桥）。审批腿**进程作用域语义**
+ *   （定形注④——与 SDK 腿「连接作用域无订阅即 cancel」分立）：开面在场即
+ *   持应答能力、不采无连接即时 cancel；败腿/撤销经 signal abort 清槽
+ *   （abort 恒后于竞速落定——UiCore finish 内序，不构成抢答）。
+ * - **SSE 信封三族**：分档判据注②（终结型两型 + asked 镜像 → session 族，
+ *   其余活体 → display 族）；连接即当下（v1 无重放游标——正确性层 = 客户端
+ *   onopen 恒重拉投影）；全局连接帽 16 件侧自记账（面级 openStreams 不暴露
+ *   计数）超帽 503；背压 shedding 判据 = display 的 update 两型（session/
+ *   notify/status 镜像帧不弃）。
+ * - **微路由语义**：会话存在性分账（missing submit/events 404 not_found /
+ *   closed submit 404 closed；messages/todo 不受闭态拦；closed events 放行
+ *   空流）；cookie 桥注③（体 {token} 经面级 verifyToken 验换 → Set-Cookie
+ *   HttpOnly SameSite=Strict——EventSource 无头位，浏览器侧唯一凭证通道）；
+ *   SPA 静态位注⑦（路径穿越防线 + 未知深路径 fallback index.html；缺席
+ *   API-only 404 no_spa）；JSON 均 typebox 校验后消费。
+ * - **decide 只 resolve pending resolver**（绝不直接写 durable——decided
+ *   durable 写唯一保留在 ask() 汇流点；unknown/已决 → superseded 幂等回执）。
+ *
+ * 收场语义：detach() = 全路由摘除 + 全流收口 + 审批清槽（**丢弃性结算——
+ * 不 resolve**：未决条目不凭空造值抢答；败腿 promise 悬挂由核 finish/队列
+ * 收口吸收）——行回卷语义与原 stop() 同律；监听关停归面（宿主 face.stop）。
+ */
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { join, resolve, sep } from 'node:path';
+import { Type } from 'typebox';
+import { Value } from 'typebox/value';
+import { WEBUI_BODY_LIMIT_BYTES, WEBUI_COOKIE_NAME, WEBUI_ENDPOINTS, WEBUI_MAX_CONNECTIONS, } from './types.js';
+/* ---------------- typebox 校验（03 §10.4「JSON 均 typebox 校验后消费」） ---------------- */
+/** 公共字段词面：未知字段拒收（收窄律——请求面载荷即全集） */
+const strict = { additionalProperties: false };
+/** auth 体（cookie 桥——token 必填） */
+const AuthSchema = Type.Object({ token: Type.String() }, strict);
+/** submit 体（text 必填；messageId 选填 = SPA 重试幂等位，缺席服务端生成） */
+const SubmitSchema = Type.Object({ text: Type.String(), messageId: Type.Optional(Type.String()) }, strict);
+/** decide 体（answer 四值闭集 = ApprovalAskAnswer；note 选填） */
+const DecideSchema = Type.Object({
+    answer: Type.Union([
+        Type.Literal('approve'),
+        Type.Literal('reject'),
+        Type.Literal('cancel'),
+        Type.Literal('always'),
+    ]),
+    note: Type.Optional(Type.String()),
+}, strict);
+/** 深校验非抛型（fail-loud 可行动报因——首错定位） */
+function validate(schema, value, what) {
+    if (!Value.Check(schema, value)) {
+        const errors = [...Value.Errors(schema, value)];
+        const first = errors[0];
+        const at = first === undefined ? '' : `（${first.instancePath || '(root)'}：${first.message}）`;
+        return { ok: false, reason: `${what} 不合 schema${at}` };
+    }
+    return { ok: true, value: value };
+}
+/* ---------------- 应答与解析 ---------------- */
+/** JSON 应答（content-type 单源） */
+function sendJson(res, status, body) {
+    if (res.writableEnded)
+        return;
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(body));
+}
+/** 错误应答（machine word + 人读消息——SPA 面无错误码族，HTTP 状态即词面） */
+function sendError(res, status, error, message) {
+    sendJson(res, status, { error, ...(message !== undefined ? { message } : {}) });
+}
+/** 解析 JSON 体（坏形 → 可行动报因） */
+function parseJson(raw) {
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch {
+        return { ok: false, reason: '请求体非 JSON' };
+    }
+}
+/** query 解析（ctx 窄面无 query 位——handler 侧自 req.url 取；基座仅为相对形合法） */
+function queryOf(req) {
+    return new URL(req.url ?? '/', 'http://webui.internal').searchParams;
+}
+/** 判信封是否纯活体可丢（背压 shedding 面——display 族的 update 两型；session
+ *  镜像/notify/status 不弃） */
+function isDroppableEnvelope(env) {
+    return (env.kind === 'display' && (env.payload.type === 'message_update' || env.payload.type === 'tool_execution_update'));
+}
+/* ---------------- 静态面 ---------------- */
+/** 静态面内容型表（扩展名 → content-type；缺席 application/octet-stream） */
+const CONTENT_TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.ico': 'image/x-icon',
+    '.json': 'application/json; charset=utf-8',
+    '.txt': 'text/plain; charset=utf-8',
+    '.map': 'application/json',
+    '.woff2': 'font/woff2',
+    '.webmanifest': 'application/manifest+json',
+};
+/**
+ * 造 webui 路由件并注册进注入的注册器（承载位改注册——零自持监听）。
+ *
+ * @param deps 装配根闭包注入窄面 + 路由注册器（sdk 面注册器结构兼容直传）
+ * @param options 件侧帽参（SSE 连接帽 / POST 体帽——测试确定性注入位）
+ */
+export function mountWebui(deps, options = {}) {
+    const maxConnections = options.maxConnections ?? WEBUI_MAX_CONNECTIONS;
+    const bodyLimitBytes = options.bodyLimitBytes ?? WEBUI_BODY_LIMIT_BYTES;
+    const warn = options.warn ?? (() => { });
+    /** 活体流注册表（全局帽计数 + 按会话扇出索引） */
+    const streams = new Set();
+    const bySession = new Map();
+    /** 未决审批账（approvalId → 账项——decide 幂等判据 + 清单投影） */
+    const pending = new Map();
+    /** 后端内 ask 计数（调用方未指派 approvalId 时生成 `webui-N`） */
+    let askSeq = 0;
+    /** 件内 submit 计数（SPA 未携 messageId 时生成 `webui-N`——无幂等） */
+    let submitSeq = 0;
+    /** 流退订（终结回调——双索引摘除；挂点位 = res close〔连接 close/看门狗/
+     *  面收场三路共用的真连接终结信号〕，与面级流账自摘并存不冲突） */
+    const deregister = (entry) => {
+        streams.delete(entry);
+        const set = bySession.get(entry.sessionId);
+        if (set === undefined)
+            return;
+        set.delete(entry);
+        if (set.size === 0)
+            bySession.delete(entry.sessionId);
+    };
+    /** 会话路由扇出（display/session/status 三族——按订阅索引） */
+    const pushToSession = (sessionId, env) => {
+        const set = bySession.get(sessionId);
+        if (set === undefined)
+            return;
+        for (const entry of set)
+            entry.stream.write(env);
+    };
+    /** notify 广播（非阻塞原语不分会话呈现位——全流扇出） */
+    const broadcast = (env) => {
+        for (const entry of streams)
+            entry.stream.write(env);
+    };
+    /* ---- UiBackend 第四实装（claim 桥——通道核 addBackend 注册） ---- */
+    const backend = {
+        id: 'webui',
+        // 三位能力面对应信封三族（notify·status·approval）；confirm/select/input
+        // 缺席（微路由 v1 无应答端点——降级判定归核）；setWidget 是 TUI 呈现概念
+        capabilities: {
+            notify: true,
+            confirm: false,
+            select: false,
+            input: false,
+            approval: true,
+            setStatus: true,
+            setWidget: false,
+        },
+        // 观众探针：在线 SSE 连接数（零连接 = 无人接帧 = 无观众）
+        hasAudience: () => streams.size > 0,
+        notify: (message, opts) => {
+            broadcast({
+                kind: 'notify',
+                payload: { message, ...(opts?.level !== undefined ? { level: opts.level } : {}) },
+            });
+        },
+        // 状态行更新（last-writer-wins 天然——多写者扇出覆盖）
+        setStatus: (sessionId, status) => {
+            pushToSession(sessionId, { kind: 'status', sessionId, payload: { status } });
+        },
+        // 活体信封呈现（focused 位无 webui 语义——SPA 自选视图，无聚焦降档）
+        onEnvelope: (env) => {
+            // 分档判据（批 18a 定形注②）：终结型两型落 durable → session 镜像族；
+            // 其余活体 → display 族
+            const terminal = env.event.type === 'message_end' || env.event.type === 'tool_execution_end';
+            pushToSession(env.sessionId, terminal
+                ? { kind: 'session', sessionId: env.sessionId, payload: env.event }
+                : { kind: 'display', sessionId: env.sessionId, payload: env.event });
+        },
+        askApproval: (sessionId, request, opts) => new Promise((resolve) => {
+            // 进程作用域语义（定形注④）：不采无连接即时 cancel——开面在场即持
+            // 应答能力，浏览器迟到也可应答；纯 webui 无浏览器时 ask 挂起至
+            // run 打断/会话收口（核保守值兜底）。
+            const approvalId = request.approvalId ?? `webui-${++askSeq}`;
+            const entry = {
+                sessionId,
+                summary: request.summary,
+                ...(request.reason !== undefined ? { reason: request.reason } : {}),
+                ...(request.toolName !== undefined ? { toolName: request.toolName } : {}),
+                ...(request.suggestedEntry !== undefined ? { suggestedEntry: request.suggestedEntry } : {}),
+                settled: false,
+                resolve,
+            };
+            pending.set(approvalId, entry);
+            // asked 镜像外推（session 族承载——零新词汇：payload 形复用 durable
+            // approval/asked 词汇；可见性半边经此镜像，无第二套 ask 帧词面；
+            // approvalId 显式置尾防 request 内 undefined 值覆写生成位）
+            pushToSession(sessionId, {
+                kind: 'session',
+                sessionId,
+                payload: { type: 'approval/asked', ...request, approvalId },
+            });
+            // 败腿撤销传播位（UiCore 竞速先答后 abort——abort 恒后于竞速落定，
+            // 本 resolve 是无害清槽不构成抢答）；已决后迟到 abort 是 no-op
+            opts?.signal?.addEventListener('abort', () => {
+                const e = pending.get(approvalId);
+                if (e === undefined || e.settled)
+                    return;
+                e.settled = true;
+                pending.delete(approvalId);
+                resolve('cancel');
+            }, { once: true });
+        }),
+    };
+    /** decide 应答（跨入口竞速回执——只 resolve pending resolver，绝不直接写
+     *  durable：decided durable 写唯一保留在 ask() 汇流点；unknown/已决 →
+     *  superseded 幂等回执） */
+    const decideApproval = (approvalId, answer) => {
+        const entry = pending.get(approvalId);
+        if (entry === undefined || entry.settled)
+            return 'superseded';
+        entry.settled = true;
+        pending.delete(approvalId);
+        entry.resolve(answer);
+        return 'applied';
+    };
+    /* ---- 静态面（SPA 壳——open/static-shell 三位之一；缺席 = API-only 形） ---- */
+    async function serveStatic(res, wildcard) {
+        if (deps.staticDir === undefined) {
+            sendError(res, 404, 'no_spa', 'SPA 静态面未装配（API-only 形态）');
+            return;
+        }
+        const root = resolve(deps.staticDir);
+        // wildcard 无前导斜杠（面级匹配器以段拼回）——根路径空串归 index.html
+        let rel = wildcard === '' ? 'index.html' : decodeURIComponent(wildcard);
+        let target = resolve(join(root, rel));
+        // 路径穿越防线：归一后须仍在根内（.. 段与编码形出根即拒）
+        if (target !== root && !target.startsWith(root + sep)) {
+            sendError(res, 403, 'forbidden', '路径出静态面根');
+            return;
+        }
+        try {
+            const s = await stat(target);
+            if (!s.isFile())
+                throw new Error('not file');
+        }
+        catch {
+            // SPA fallback 路由：未知/非文件路径回 index.html（前端路由接管）
+            rel = 'index.html';
+            target = join(root, rel);
+            try {
+                if (!(await stat(target)).isFile())
+                    throw new Error('no index');
+            }
+            catch {
+                sendError(res, 404, 'no_spa', '静态面缺 index.html');
+                return;
+            }
+        }
+        const dot = target.lastIndexOf('.');
+        const ext = dot === -1 ? '' : target.slice(dot).toLowerCase();
+        res.writeHead(200, { 'content-type': CONTENT_TYPES[ext] ?? 'application/octet-stream' });
+        createReadStream(target)
+            .on('error', () => res.destroy())
+            .pipe(res);
+    }
+    /* ---- 路由族注册（五撮 13 端点 + /api 兜底 + SPA fallback——全族 loopbackOnly） ---- */
+    /** API 族鉴权档（Bearer ∪ cookie 双通道——cookie 名单源） */
+    const tokenOrCookie = { mode: 'token-or-cookie', cookie: WEBUI_COOKIE_NAME };
+    /** 摘除 fn 账（detach 全路由摘除用） */
+    const detachers = [];
+    /** 注册速记（loopbackOnly 全族恒真——07 E1 恒回环可达） */
+    const add = (descriptor) => {
+        detachers.push(deps.register({ loopbackOnly: true, ...descriptor }));
+    };
+    // —— 探活（open/liveness——只回 ok 零敏感面）——
+    add({
+        method: 'GET',
+        path: WEBUI_ENDPOINTS.health,
+        auth: { mode: 'open', purpose: 'liveness' },
+        handler: (_req, res) => sendJson(res, 200, { ok: true }),
+    });
+    // —— auth cookie 桥（open/auth-exchange——本位即鉴权：体 token 经面级
+    //    verifyToken 验换，落定 Set-Cookie；cookie 值 = 验换通过的那枚 token）——
+    add({
+        method: 'POST',
+        path: WEBUI_ENDPOINTS.auth,
+        auth: { mode: 'open', purpose: 'auth-exchange' },
+        bodyLimitBytes,
+        handler: async (req, res, ctx) => {
+            const body = await ctx.readBody(req);
+            if (!body.ok)
+                return sendError(res, body.status, 'too_large', body.message);
+            const parsed = parseJson(body.body);
+            if (!parsed.ok)
+                return sendError(res, 400, 'bad_request', parsed.reason);
+            const auth = validate(AuthSchema, parsed.value, 'auth 体');
+            if (!auth.ok)
+                return sendError(res, 400, 'bad_request', auth.reason);
+            if (!ctx.verifyToken(auth.value.token))
+                return sendError(res, 401, 'unauthorized', 'token 不符');
+            // cookie 桥落定（HttpOnly + SameSite=Strict——EventSource 不能携头，本桥
+            // 是浏览器侧唯一凭证通道；Path=/ 覆盖全 API 面；token-or-cookie 档由面
+            // 级用同一 token 验 cookie——闭环成立）
+            res.writeHead(204, {
+                'set-cookie': `${WEBUI_COOKIE_NAME}=${auth.value.token}; HttpOnly; SameSite=Strict; Path=/`,
+            });
+            res.end();
+        },
+    });
+    // —— 会话族根：GET 清单 / POST 开新 ——
+    add({
+        method: 'GET',
+        path: WEBUI_ENDPOINTS.sessions,
+        auth: tokenOrCookie,
+        handler: (_req, res) => sendJson(res, 200, { sessions: deps.sessions.listSessions() }),
+    });
+    add({
+        method: 'POST',
+        path: WEBUI_ENDPOINTS.sessions,
+        auth: tokenOrCookie,
+        handler: (_req, res) => sendJson(res, 200, { sessionId: deps.sessions.createSession() }),
+    });
+    // —— 会话族子路由（存在性分账注⑥：messages/todo 不受闭态拦；events 前
+    //    missing 拒、closed 放行空流；submit/interrupt 受闭态拦）——
+    add({
+        method: 'GET',
+        path: WEBUI_ENDPOINTS.sessionMessages,
+        auth: tokenOrCookie,
+        handler: async (_req, res, ctx) => {
+            // 近史投影兜底可拉（closed 会话同样可拉——只读腿）
+            const messages = await deps.read.fetchMessages(ctx.params.id);
+            sendJson(res, 200, { messages });
+        },
+    });
+    add({
+        method: 'GET',
+        path: WEBUI_ENDPOINTS.sessionTodo,
+        auth: tokenOrCookie,
+        handler: (_req, res, ctx) => {
+            const items = deps.read.todoOf?.(ctx.params.id);
+            sendJson(res, 200, { items: items ?? null }); // null = 无数据源（诚实不虚报）
+        },
+    });
+    add({
+        method: 'GET',
+        path: WEBUI_ENDPOINTS.sessionEvents,
+        auth: tokenOrCookie,
+        handler: (_req, res, ctx) => {
+            const sessionId = ctx.params.id;
+            if (deps.sessions.sessionStateOf(sessionId) === 'missing') {
+                sendError(res, 404, 'not_found', '会话缺席');
+                return;
+            }
+            // closed 会话放行（空流形——近史走 messages 兜底，流恒静默无假帧）
+            if (streams.size >= maxConnections) {
+                sendError(res, 503, 'overloaded', `SSE 连接帽（${maxConnections}）已满`);
+                return;
+            }
+            // 面级开流（帧形/ping/看门狗面单源；shedding 判据 = display 的 update
+            // 两型可丢——unknown 域收敛转型 = 本面流载荷恒 WebuiEnvelope 的件内不变式）
+            const stream = ctx.openSse(res, {
+                droppable: (data) => isDroppableEnvelope(data),
+            });
+            const entry = { stream, sessionId };
+            streams.add(entry);
+            const set = bySession.get(sessionId) ?? new Set();
+            set.add(entry);
+            bySession.set(sessionId, set);
+            // 件侧销账位 = res close（连接 close/面级看门狗 destroy/宿主收场三路
+            // 共用的真连接终结信号——与面级流账自摘并存）
+            res.on('close', () => deregister(entry));
+        },
+    });
+    add({
+        method: 'POST',
+        path: WEBUI_ENDPOINTS.sessionSubmit,
+        auth: tokenOrCookie,
+        bodyLimitBytes,
+        handler: async (req, res, ctx) => {
+            const sessionId = ctx.params.id;
+            const state = deps.sessions.sessionStateOf(sessionId);
+            if (state === 'missing')
+                return sendError(res, 404, 'not_found', '会话缺席');
+            if (state === 'closed')
+                return sendError(res, 404, 'closed', '会话已闭（只读兜底）');
+            const body = await ctx.readBody(req);
+            if (!body.ok)
+                return sendError(res, body.status, 'too_large', body.message);
+            const parsed = parseJson(body.body);
+            if (!parsed.ok)
+                return sendError(res, 400, 'bad_request', parsed.reason);
+            const submit = validate(SubmitSchema, parsed.value, 'submit 体');
+            if (!submit.ok)
+                return sendError(res, 400, 'bad_request', submit.reason);
+            const outcome = deps.sessions.submitPrompt({
+                sessionId,
+                content: submit.value.text,
+                messageId: submit.value.messageId ?? `webui-${++submitSeq}`,
+            });
+            sendJson(res, 200, { sessionId: outcome.sessionId });
+        },
+    });
+    add({
+        method: 'POST',
+        path: WEBUI_ENDPOINTS.sessionInterrupt,
+        auth: tokenOrCookie,
+        handler: (_req, res, ctx) => {
+            const sessionId = ctx.params.id;
+            const state = deps.sessions.sessionStateOf(sessionId);
+            if (state === 'missing')
+                return sendError(res, 404, 'not_found', '会话缺席');
+            if (state === 'closed')
+                return sendError(res, 404, 'closed', '会话已闭（只读兜底）');
+            deps.sessions.interruptSession(sessionId);
+            res.writeHead(204).end();
+        },
+    });
+    // —— 审批族 ——
+    add({
+        method: 'GET',
+        path: WEBUI_ENDPOINTS.approvals,
+        auth: tokenOrCookie,
+        handler: (req, res) => {
+            const filter = queryOf(req).get('sessionId');
+            const list = [];
+            for (const [approvalId, entry] of pending) {
+                if (entry.settled || (filter !== null && entry.sessionId !== filter))
+                    continue;
+                list.push({
+                    approvalId,
+                    sessionId: entry.sessionId,
+                    summary: entry.summary,
+                    ...(entry.reason !== undefined ? { reason: entry.reason } : {}),
+                    ...(entry.toolName !== undefined ? { toolName: entry.toolName } : {}),
+                    ...(entry.suggestedEntry !== undefined ? { suggestedEntry: entry.suggestedEntry } : {}),
+                });
+            }
+            sendJson(res, 200, { approvals: list });
+        },
+    });
+    add({
+        method: 'POST',
+        path: WEBUI_ENDPOINTS.approvalsDecide,
+        auth: tokenOrCookie,
+        bodyLimitBytes,
+        handler: async (req, res, ctx) => {
+            const body = await ctx.readBody(req);
+            if (!body.ok)
+                return sendError(res, body.status, 'too_large', body.message);
+            const parsed = parseJson(body.body);
+            if (!parsed.ok)
+                return sendError(res, 400, 'bad_request', parsed.reason);
+            const decide = validate(DecideSchema, parsed.value, 'decide 体');
+            if (!decide.ok)
+                return sendError(res, 400, 'bad_request', decide.reason);
+            // 只 resolve pending resolver（绝不直接写 durable——decided durable 写
+            // 唯一保留在 ask() 汇流点；后到/未知 = superseded 幂等回执）
+            const outcome = decideApproval(ctx.params.approvalId, decide.value.answer);
+            sendJson(res, 200, { outcome });
+        },
+    });
+    // —— 补全族（两段——注入面缺席诚实空）——
+    add({
+        method: 'GET',
+        path: WEBUI_ENDPOINTS.workspaceFiles,
+        auth: tokenOrCookie,
+        handler: (req, res) => {
+            const q = queryOf(req).get('q') ?? '';
+            sendJson(res, 200, { items: deps.completion?.workspaceFiles?.(q) ?? [] });
+        },
+    });
+    add({
+        method: 'GET',
+        path: WEBUI_ENDPOINTS.workspaceSymbols,
+        auth: tokenOrCookie,
+        handler: (req, res) => {
+            const q = queryOf(req).get('q') ?? '';
+            sendJson(res, 200, { items: deps.completion?.workspaceSymbols?.(q) ?? [] });
+        },
+    });
+    // —— /api 兜底（鉴权先行语义维持：未知 /api 路径过鉴权门后 404——防 SPA
+    //    fallback 吞程序面打错路径；GET/POST 双形，其余 method 落面级 404）——
+    add({
+        method: 'GET',
+        path: '/api/*',
+        auth: tokenOrCookie,
+        handler: (_req, res) => sendError(res, 404, 'not_found', '未知 API 路由'),
+    });
+    add({
+        method: 'POST',
+        path: '/api/*',
+        auth: tokenOrCookie,
+        handler: (_req, res) => sendError(res, 404, 'not_found', '未知 API 路由'),
+    });
+    // —— SPA 静态面（open/static-shell——壳先于鉴权必须可载，壳无 API 即惰性；
+    //    GET/HEAD 双形；注册序在 /api/* 之后 = /api 射界先由兜底圈占）——
+    add({
+        method: 'GET',
+        path: '*',
+        auth: { mode: 'open', purpose: 'static-shell' },
+        handler: (_req, res, ctx) => {
+            void serveStatic(res, ctx.wildcard ?? '').catch((err) => {
+                warn(`webui 静态面处理异常：${err instanceof Error ? err.message : String(err)}`);
+                if (!res.writableEnded)
+                    sendError(res, 500, 'internal');
+            });
+        },
+    });
+    add({
+        method: 'HEAD',
+        path: '*',
+        auth: { mode: 'open', purpose: 'static-shell' },
+        handler: (_req, res, ctx) => {
+            void serveStatic(res, ctx.wildcard ?? '').catch((err) => {
+                warn(`webui 静态面处理异常：${err instanceof Error ? err.message : String(err)}`);
+                if (!res.writableEnded)
+                    sendError(res, 500, 'internal');
+            });
+        },
+    });
+    return {
+        backend,
+        detach: () => {
+            // 收场序：全路由摘除 → 全流收口（面级流随 res 终结）→ 审批清槽
+            // （**丢弃性结算——不 resolve**：未决条目不凭空造值抢答；败腿 promise
+            // 悬挂由核 finish/队列收口吸收——行回卷语义）
+            for (const detach of detachers.splice(0))
+                detach();
+            for (const entry of [...streams])
+                entry.stream.close();
+            pending.clear();
+        },
+    };
+}

package/dist/webui/types.js

@@ -0,0 +1,38 @@
+/* ---------------- 常量（缺省值单源——03 §10.4 各条款钉死值） ---------------- */
+/** 缺省端口（`--port <n>` 一次性开面——缺省 7860；装配位消费） */
+export const WEBUI_DEFAULT_PORT = 7860;
+/** 缺省回环绑定地址（恒回环钉死——非回环须配凭证 fail-closed 由面级 judgeListenConfig 执法） */
+export const WEBUI_DEFAULT_HOST = '127.0.0.1';
+/** 全局 SSE 连接帽（超帽新连接 503——件侧自记账：面级 openStreams 不暴露计数） */
+export const WEBUI_MAX_CONNECTIONS = 16;
+/** POST 族字节帽（256KiB——per-route bodyLimitBytes 位；超帽 413 且应答永不早于请求体收完〔面级排空纪律〕） */
+export const WEBUI_BODY_LIMIT_BYTES = 256 * 1024;
+/** auth cookie 桥 cookie 名（HttpOnly SameSite=Strict——EventSource 无头位；token-or-cookie 档位） */
+export const WEBUI_COOKIE_NAME = 'webui_token';
+/** 微路由端点表（五撮——03 §10.4 批 18a 落码定形注①定形；SPA fallback 承载位 = 单 `*` catch-all） */
+export const WEBUI_ENDPOINTS = {
+    /** GET——探活（open/liveness；只回 ok 零敏感面） */
+    health: '/api/health',
+    /** POST——auth cookie 桥（open/auth-exchange；体 {token} → Set-Cookie） */
+    auth: '/api/auth',
+    /** GET——会话清单 / POST——开新 */
+    sessions: '/api/sessions',
+    /** GET——投影拉取（近史正文——正确性层真源） */
+    sessionMessages: '/api/sessions/:id/messages',
+    /** GET SSE——活体流（连接即当下，v1 无重放游标） */
+    sessionEvents: '/api/sessions/:id/events',
+    /** POST——提交（体 {text, messageId?}） */
+    sessionSubmit: '/api/sessions/:id/submit',
+    /** POST——打断在飞 run */
+    sessionInterrupt: '/api/sessions/:id/interrupt',
+    /** GET——todo 数据源（goal 计划态呈现投影） */
+    sessionTodo: '/api/sessions/:id/todo',
+    /** GET——审批清单（?sessionId= 过滤，缺省全量） */
+    approvals: '/api/approvals',
+    /** POST——审批应答（体 {answer, note?}——跨入口竞速回执） */
+    approvalsDecide: '/api/approvals/:approvalId/decide',
+    /** GET——补全族两段之一（?q= 前缀查询） */
+    workspaceFiles: '/api/workspace/files',
+    /** GET——补全族两段之二（?q= 前缀查询） */
+    workspaceSymbols: '/api/workspace/symbols',
+};