@plumeai/plugin-sdk 0.0.0-stage → 0.1.3

package/dist/client/ui/src/scroll/Scroller.d.ts

@@ -0,0 +1,66 @@
+import type { Direction } from "./follow.ts";
+/**
+ * 应用里唯一的滚动面。
+ *
+ * 原生滚动容器做不到、而参考设计处处都有的几件事：
+ *
+ *   - 滚动条浮在内容上，而不是预留一条槽，列表一长过它的盒子，内容不会横向重排；
+ *   - 边缘说明那个方向还藏着东西，画成边界实际的样子：内容化进空白的地方是渐隐，滑到实心的东西
+ *     底下的地方是一道细线。见 `top`——选错了，列表看起来就像坏了。
+ *
+ * `overscroll-contain` 让滚到头的滚轮停在这里，而不是传给后面的窗口——否则嵌套列表一到底就会带着
+ * 父级一起滚。
+ *
+ * 嵌在外层滚动面里的面（比如转录里的工具卡片、错误日志、代码输出），用 `overscroll="auto"`，
+ * 里面滚到边界之后自然地接到外层。
+ */
+export declare function Scroller({ children, className, contentClassName, top, fadeTop, bottom, overscroll, onScroll, onResize, onUserScroll, onHold, scrollRef, }: {
+    children: React.ReactNode;
+    className?: string;
+    contentClassName?: string;
+    /**
+     * 滚到自己的边界之后，滚轮还传不传给外面。
+     *
+     * 判断标准是这一块**是页面里的一段内容，还是一块独立的面**。一段内容——设置页里的发版说明、一列
+     * 搜索结果——读到底了还想接着往下看页面，是很自然的一件事，那就该给 `"auto"`。一块
+     * 独立的面——弹窗、浮层、菜单、转录本身——滚到底就该停住，不然一个嵌套列表刚到底就把它背后的整页
+     * 带跑了，那是默认的 `"contain"` 要挡的事。
+     *
+     * 「滚不动的面要不要拦」不用在这里操心：它一律放行，见下面 `chain` 那段。
+     */
+    overscroll?: "contain" | "auto";
+    /**
+     * 上沿怎么收尾。
+     *
+     * `"fade"` 把最后几行柔化掉，不画任何东西就说出「这边还有」。上面是什么都成立——空窗格也好、
+     * 不透明的导航也好——因为它降的是内容自己的 alpha，而不是往上面刷颜色；为什么这一点就是全部，
+     * 见 `ui/scroll.css` 里 `.plume-fade-y` 上面那段。
+     *
+     * 只在确实有东西滚到底下去之后才出现，短列表完全没有边缘处理：边界在起作用时才值得画。
+     */
+    top?: "fade" | "none";
+    /** 默认值不适合这个列表时，上沿渐隐伸进去多深，单位 px。 */
+    fadeTop?: number;
+    /** 下沿的同一个问题。 */
+    bottom?: "fade" | "none";
+    onScroll?: (element: HTMLDivElement) => void;
+    /** 内容或视口尺寸变了就调用。 */
+    onResize?: (element: HTMLDivElement) => void;
+    /**
+     * 下面滑块的一次拖动，按它本来的手势报出来。
+     *
+     * 滑块是视口的兄弟节点，靠赋值 `scrollTop` 移动视口，于是拖动传到跟随方那里，是一个和浏览器
+     * 夹住正在变短的转录分不开的滚动事件——而跟随方不能因为一次来路不明的位置变化就脱离（见
+     * `follow.ts`），就永远发现不了读者在往外拉。这是唯一知道真相的组件把那个手势明说出来。
+     */
+    onUserScroll?: (direction: Direction) => void;
+    /**
+     * 读者刚把手指按在了什么上面。
+     *
+     * 给跟随底部的那一方一个机会，把接下来这一次长高认成「读者点开了手里这一块」而不是「新消息
+     * 到了」——两者在 `onResize` 里长得一模一样，而处理方式正好相反。
+     */
+    onHold?: (target: EventTarget | null) => void;
+    /** 给自己驱动滚动位置的调用方用，比如转录。 */
+    scrollRef?: React.RefObject<HTMLDivElement | null>;
+}): import("react").JSX.Element;

package/dist/client/ui/src/scroll/Sideways.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 一条横着滚的标签栏。
+ *
+ * 普通滚轮直接横着走，触摸板两指一划照旧——见 `useSideways` 的 `plainWheel`。标签栏都长在头部或
+ * 底边，上面没有要竖着滚的东西，把滚轮让出去也没人接。
+ *
+ * 这里从前两头各浮一枚方向键，那是给「只有鼠标、又不知道 Shift + 滚轮」的人准备的；滚轮能直接
+ * 横滚之后它们只剩下压住两端标签的那一块，于是拿掉了。附件条躺在可滚动的转录区里，滚轮得留给
+ * 上层，它还用着 `SidewaysArrow`。
+ */
+export declare function Sideways({ children, className, trackRef, ...rest }: {
+    children: React.ReactNode;
+    /** 给会滚的那一层，`overflow-x-auto` 和「我在父级里占多大」的类都写在这里。 */
+    className?: string;
+    /** 需要自己够到滚动容器的地方传进来——比如「把选中的标签滚进视野」。 */
+    trackRef?: React.RefObject<HTMLDivElement | null>;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "className" | "children">): import("react").JSX.Element;
+/**
+ * 附件条两头的方向键：那里滚轮要留给转录区，只有鼠标的人得靠它们。
+ *
+ * - **不占地方。** 绝对定位浮在两端、压在渐隐上，不进 flex 流——占位置的话，刚好排得下的一条会
+ *   因为多了两个按钮而排不下。定位壳由附件条自己提供。
+ * - **到头就没有。** 和渐隐读同一个「这边还有没有」，永远同进同出；`disabled` 的灰按钮不说明任何事。
+ * - **一次滚八成。** 整屏翻页会把刚看到的那个也带走，留一点重叠，眼睛才接得上。
+ */
+export declare function SidewaysArrow({ side, shown, track }: {
+    side: "left" | "right";
+    shown: boolean;
+    track: React.RefObject<HTMLElement | null>;
+}): import("react").JSX.Element;

package/dist/client/ui/src/scroll/fade.d.ts

@@ -0,0 +1,2 @@
+/** 几个窗格分一个矮窗口时，中间也要读得清。`depth` 覆盖某一边的默认值。 */
+export declare function scrollFade(height: number, edge: "top" | "bottom", depth?: number): number;

package/dist/client/ui/src/scroll/follow.d.ts

@@ -0,0 +1,157 @@
+/**
+ * 一个滚动面是不是在跟随自己的底部，以及什么东西有权改变这一点。
+ *
+ * 窗口里每一份转录——对话、侧聊、委派的日志——要的都是同一种行为：有东西进来时贴着底部走，读者
+ * 往上翻去看什么时留在原地，并且给一条回来的路。三份各自长出来的实现会慢慢走样，所以这个文件是
+ * 规则，每个滚动面都只是调用方。
+ *
+ * 这里什么都不碰 DOM。每样东西都是一次几何读数加一个事件的纯函数，这样那些有意思的情形——只在
+ * 一轮输出中途的某一帧出现的那些——才能写成测试，而不是靠手去复现。
+ *
+ * 这里唯一值得带走的想法：
+ *
+ *   跟随是一种**意图**，不是一个位置。
+ *
+ * 在每次滚动事件里问「scrollTop 是不是接近末尾」并把答案当成读者的意愿，是行不通的。scrollTop
+ * 不只是读者在写，程序也在写——视口变矮、图片加载、面板隐藏又显示，都会挪动它——于是程序会一直用
+ * 自己的写入推翻读者。所以 `nextState` 是不对称的：离开由事件驱动（滚轮往上一格是明确的，不管多小），
+ * 回来由位置驱动（没有一个事件叫「我想重新跟随」；到达底部是唯一的表达方式）。
+ *
+ * 这个不对称有一条推论，同一个毛病犯了第二次才学到：
+ *
+ *   位置变化可以**恢复**跟随，永远不能结束它。
+ *
+ * 留一道后门的做法是：一次位置往上移的滚动事件，只要最近 300ms 里见过某个输入，就结束跟随——这个
+ * 时间窗之所以在，是因为滚动锚定会自己挪 `scrollTop`，不能被当成读者。可它分不清两者。输入是从整个
+ * 窗口听来的，于是在任何地方松开鼠标——侧栏、面板、输入框——都会打开这个窗口，落在窗口里的任何重排
+ * 都被读成「读者往上走了」。一组工具落定、运行行折叠、最旧的一轮离开挂载范围：每一件都会让一份没人碰
+ * 过的转录停止跟随，在读者正看着内容进来的会话上留下「有新内容」。
+ *
+ * 所以一次单纯的位置变化，现在只说它能诚实说出的那一件事，那就是 `arrived`。所有结束跟随的东西都以
+ * 手势的形式到来，来自一个叫得出它名字的监听器。
+ */
+export type FollowState = 
+/** 贴着底部走：尾部长高和视口变化都会重新钉住。 */
+"following"
+/** 读者在上面某处，除了读者自己，谁都不能挪动他们。 */
+ | "detached"
+/** 正在滑回底部。可以打断——见 `nextState`。 */
+ | "returning";
+/**
+ * 换掉滚动面之后还留着的意图。
+ *
+ * 正在回去的面已经被要求跟随末尾了；动画只是这个意图正在被执行的方式。滑动途中打开了另一个会话，
+ * 要是把它记成 detached，旧的面恢复时就停在半路，又一次给出「回到最新」。
+ */
+export declare function followsAfterRestore(state: FollowState): boolean;
+/**
+ * 某一瞬间滚动面的样子：这里每个判断都从这三个数出发。
+ *
+ * 有意只有几何。浮在最后一段内容上的东西——审批卡、回到最新的按钮——在它该在的地方处理，作为滚动
+ * 内容底部的内边距（`--plume-bottom-inset`），好让页面的底部是最新消息真正看得见的地方。把重叠量折进
+ * 这里的算术是双重错误：`scrollTop` 不可能超过 `scrollHeight - clientHeight`，一个正的 inset 会让
+ * `atBottom` 永远够不着，钉住一份永远满足不了自己判断的转录。
+ */
+export interface Reading {
+    scrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+}
+/**
+ * 让内容末尾贴住视口底边的 scrollTop。
+ *
+ * 整数，而且只是近似：`scrollHeight` 和 `clientHeight` 都取过整，所以这个值最多比内容真正的末尾
+ * 差一个像素。对下面那些都留了一像素余量的距离判断够用；拿来写不够——见 `targetScrollTop`。
+ */
+export declare function visualBottom(reading: Reading): number;
+/** 读者离底部多远。 */
+export declare function distanceToBottom(reading: Reading): number;
+/** 内容没填满视口。永远算「在底部」，永远不值得一个按钮。 */
+export declare function fitsInView(reading: Reading): boolean;
+/**
+ * 滚动面不在屏幕上时拿到的读数。
+ *
+ * 用 `display: none` 收起的窗格、最小化的窗口、元素被摘下时触发的 `ResizeObserver`：报的都是零，
+ * 而零满足所有「在底部」的判断。这样的读数什么都证明不了，绝不能进状态机——按它行事，切换面板就会
+ * 把一个会话记住的位置覆盖成「转录顶部，并且算作钉住」。
+ */
+export declare function isDegenerate(reading: Reading): boolean;
+/** 读者在哪，只分要紧的两段。 */
+export declare function atBottom(reading: Reading): boolean;
+export declare function isAway(reading: Reading): boolean;
+/**
+ * 一个手势往哪个方向，在能知道的时候。
+ *
+ * 滚轮、按键、拖滑块都直接说了。按下手指没说，报成 `"unknown"`：由之后的位置决定，和一次停在底部的
+ * 拖动一直遵守的规则一样。
+ */
+export type Direction = "up" | "down" | "unknown";
+/**
+ * 什么可以改变意图。
+ *
+ * 几何有意不在这里——内容追加、上面有东西折叠、输入框长高。它们都不能改变意图，把新几何读回来当作
+ * 「读者想不想跟随」的答案，正是往一个长高 200px 的输入框里打字会冒出「回到最新」按钮、一个窗格短暂
+ * 报 0×0 会得到一份滚在顶部却算作钉住的转录的原因。它们作为位置应用（`targetScrollTop`），从不喂给
+ * `nextState`。
+ */
+export type FollowEvent = 
+/** 读者动了，这是唯一可以结束跟随意图的事件。 */
+{
+    kind: "user-scroll";
+    direction: Direction;
+}
+/**
+ * 面停在一个这里没人要求过的位置。
+ *
+ * 每一次不是这个模块自己写的滚动：甩动的尾巴、浏览器夹住一份刚失去最旧一轮的转录、上方展开一段
+ * 推理时锚定稳住一行。到达状态机时它们只是四个来路不明的数，彼此分不开，也没有一个是手势。所以
+ * 唯一能做的断言是面回到了末尾——唯一能做的事是重新开始跟随。见文件顶部的推论。
+ */
+ | {
+    kind: "arrived";
+}
+/** 读者要求回去：按钮、End 键、发送一条消息。 */
+ | {
+    kind: "user-return";
+}
+/** 一次滑动到达了。 */
+ | {
+    kind: "settle";
+};
+/**
+ * 整个状态机。
+ *
+ * 有意写得像一张表：它要防的毛病，都是一个分支和另一个分支在一个谁都没点名的情形上意见不一。
+ */
+export declare function nextState(state: FollowState, event: FollowEvent, reading: Reading): FollowState;
+/**
+ * 一个事件之后面应该在哪，`null` 表示别动它。
+ *
+ * 和 `nextState` 分开，是因为它们回答的问题不同、被调用的时机也不同：状态在事件处理里决定，位置在
+ * 绘制前的布局副作用里应用。返回 `null`——而不是当前的 `scrollTop`——调用方才能整个跳过写入，而跳过
+ * 写入正是惯性滚动不被打断的原因。
+ */
+export declare function targetScrollTop(state: FollowState, reading: Reading): number | null;
+/**
+ * 足够判断到底有没有新东西来的那一部分转录。
+ *
+ * 只看 `count` 会漏掉正在写的回复——一条消息，在长。只看 `tail` 会漏掉同时落地、结尾看着一样的
+ * 两条消息。两个合起来才够回答「这还是我上次看的那份转录吗」，而且——要紧的是——两个都是**值**，
+ * 所以从磁盘重读、以新数组交回的转录，和它替换掉的那份比较起来相等。
+ */
+export interface Marker {
+    count: number;
+    /** 最后一行变了它就变的东西：它的键加上它已经有多少。 */
+    tail: string;
+}
+export declare function marker(count: number, tail: string): Marker;
+/**
+ * 读者上次看到末尾之后，来了多少条消息。
+ *
+ * 它要杜绝的毛病：一份只是又被交给了 React 一次的转录，亮起「有新内容」。打开一个会话会设置两遍
+ * 消息——一遍来自缓存，一遍是磁盘读完落地——第二遍改变了数组的引用，别的什么都没变。按引用判断的
+ * 未读标记把那当成了新内容。这里按上面那两个数判断，第二遍什么都不贡献。
+ *
+ * 回退和压缩会让转录变短。两者都不是新内容，也都没给读者留下什么要追的，所以都报零。
+ */
+export declare function unreadSince(seen: Marker | null, now: Marker): number;

package/dist/client/ui/src/scroll/measure-batch.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 各个滚动面板下一帧要量的东西，合进同一个 rAF：先把所有面板都读完，再一起写。
+ *
+ * 每个 `Scroller` 各量各的时候，一个面板刚写完滑块，下一个面板读 `scrollTop` 就得为它把整页的样式
+ * 和布局先算一遍——几个面板同时在输出，滚动事件一来就是一串交错的读写。量过：滚动事件里同步量
+ * 占了渲染主线程 9%，几乎全是这种被逼出来的排版。
+ *
+ * 推到 rAF 不会让滑块晚一帧：滚动事件在同一帧的 rAF 回调之前派发，这里约的回调当帧就跑。
+ */
+/** 读这一帧要的数，交回一个只写不读的函数。 */
+export type Measure = () => () => void;
+export declare function queueMeasure(measure: Measure): void;
+export declare function cancelMeasure(measure: Measure): void;

package/dist/client/ui/src/scroll/memory.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 读的人读到了哪里，和读的是什么分开存。
+ *
+ * 阅读位置要是和转录缓存放在一起，就没用了：你在别处时一个会话说了新东西，它缓存的转录会被丢掉
+ * ——这是对的，事件里的信息不够重建它——阅读位置也跟着一起没了。而还在后台跑的那个会话，恰恰是
+ * 你最想回到原处的那一个。
+ *
+ * 所以单独一份存储，按界面分键，只放错了也不要紧的东西。这里每个字段缺了都能退回一个合理的默认值，
+ * 这也是它可以是一个模块级的普通 Map、而不是应用状态一部分的原因——别处不用读它，它变了不用重新
+ * 渲染，全丢了也只是多滚一次到底。
+ */
+import type { Marker } from "./follow.ts";
+export interface FollowSnapshot {
+    /** 意图，比位置优先：跟随的意思是「带我到末尾」，不管末尾现在在哪。 */
+    following: boolean;
+    /** 只在不跟随时有意义。 */
+    scrollTop: number;
+    /** 转录已经看过多少，未读数离开再回来也还在。 */
+    seen: Marker | null;
+}
+export declare function readFollow(namespace: string, id: string): FollowSnapshot | undefined;
+export declare function writeFollow(namespace: string, id: string, snapshot: FollowSnapshot): void;

package/dist/client/ui/src/scroll/signature.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 转录末尾变了它才变的一个值。
+ *
+ * `useFollowBottom` 要回答「到底有没有新东西来」，而比较数组答不了：打开一个会话时 React 会拿到
+ * 两遍同样的消息——一遍来自缓存，一遍是磁盘读完落地——两个数组是不同的对象、内容完全一样。按引用
+ * 判断的未读标记把第二遍当成了新内容，于是一个谁都没往里加过东西的会话，一打开就是「有新内容」。
+ *
+ * 所以改问内容。两个数就够：有几条消息，最后一条多大。正在写的回复条数不变、大小在长；一条回复
+ * 写完、下一条开始，条数变了。从磁盘重读的转录两个都不变。
+ */
+import type { Message } from "../../../../contract/src/index.d.ts";
+/**
+ * 转录尾部的签名。
+ *
+ * `extra` 带上消息列表之外、同样算作新内容到来的东西——有几次工具运行、几次已经落定，委派的最终
+ * 报告——因为它们不碰任何消息也会改变屏幕上的内容。
+ *
+ * 看两条而不是一条，这不是多此一举。调用了工具的回复，在工具结果落到它后面时仍是**进行中**的那条，
+ * 而存储是原地更新它的：数组以 `[…, assistant(进行中), toolResult]` 结尾，真正在长的是倒数第二条。
+ * 只问最后一条得到的是 `toolResult:<固定时间戳>:0`——只要那条回复还在继续，签名就一直冻着——而签名
+ * 冻住，跟随底部的那个布局副作用就永远不跑。多看一条不花什么：两条消息本来就在手上，也没有哪个
+ * 转录会同时有第三条在变。
+ */
+export declare function tailSignature(messages: readonly Message[], extra?: string | number): string;

package/dist/client/ui/src/scroll/useFollowBottom.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 一个滚动面和它自己底部的关系。
+ *
+ * 规则在 `follow.ts`，不用浏览器就能测。这里是所有需要 DOM 的部分：读者的意图从哪里听来、位置什么
+ * 时候写、回去的那一段怎么动。
+ *
+ * 每份转录都调用它——对话（侧聊也是一份）和委派的。各自留一份近似的副本会慢慢走样：余量不同、只有
+ * 一份在看内容改尺寸、只有一份给回去的路。一处修好了另外两处照样坏着，这才是它存在的真正原因。
+ */
+import { type Direction } from "./follow.ts";
+export interface FollowBottom {
+    /** 交给 `Scroller` 的 `scrollRef`。 */
+    scrollRef: React.RefObject<HTMLDivElement | null>;
+    /**
+     * 放在滚动内容的最末尾。
+     *
+     * 「你已经看到最新消息了」指的就是它，而且必须是一个元素，不能是一道算术题：往上滚两屏、读完新到
+     * 的三段、停在那里的读者已经跟上了，任何离底距离的门槛都分不清他和没跟上的人。
+     *
+     * 用回调而不用 ref 对象，这不是风格问题。转录容器按会话作键，所以打开一个会话——或者空白对话在
+     * 第一条消息后拿到 id——会扔掉整棵子树重建。ref 对象会悄悄改指向新的哨兵，观察器却还盯着一个已经
+     * 不在文档里、因此再也不会和任何东西相交的节点：标记已读一次都不会触发，「有新内容」永远亮着。
+     */
+    tailRef: (node: HTMLDivElement | null) => void;
+    /** 要不要给出回去的路。 */
+    away: boolean;
+    /** 读者离开期间来了多少条消息。除非真的来了东西，否则是零。 */
+    unread: number;
+    /** 读者要求回去：按了按钮，或者刚发出了什么。 */
+    returnToBottom(instant?: boolean): void;
+    /** 明确的导航拥有滚动位置，回复正在输出时也一样。 */
+    detach(): void;
+    /** 立刻跳过去；从那以后位置归导航。 */
+    scrollTo(top: number): void;
+    /** 交给 `Scroller` 的 `onScroll`。 */
+    onScroll(el: HTMLDivElement): void;
+    /** 交给 `Scroller` 的 `onResize`。 */
+    onResize(el: HTMLDivElement): void;
+    /**
+     * 交给 `Scroller` 的 `onUserScroll`：视口自己听不到的那一种手势。
+     *
+     * 浮动滚动条画在视口旁边而不是里面，靠赋值移动滚动面，所以拖滑块不产生滚轮、触摸或按键——只有
+     * 一个滚动事件，而按 `follow.ts` 的规则它不能让任何东西脱离跟随。`Scroller` 是唯一知道拖动就是拖动
+     * 的地方，所以由它说出来，而不是事后和其他一切挪动转录的东西一起从位置里猜。
+     */
+    onUserScroll(direction: Direction): void;
+    /**
+     * 交给 `Scroller` 的 `onHold`：读者刚把手指按在了什么上面。
+     *
+     * 展开一段折叠区会让转录长高，而长高本身分不清是「新消息到了」还是「读者点开了手里这一块」。
+     * 这一条就是那个区别：按下时记住按到的元素在视口的哪个高度，接下来这一次长高把它放回原处，
+     * 跟随底部让路。没有它，点开历史里的一个工具组会把读者直接甩到转录末尾。
+     */
+    hold(target: EventTarget | null): void;
+    /**
+     * 接下来这一阵子的高度变化里，把这个元素留在视口的原位——只在读者没跟着底部时。
+     *
+     * 跟着底部时底部本来就钉着，元素下面没变它就不动；这时按住反而让跟随底部让路 `HOLD_MS`，底下随后
+     * 冒出来的东西没人带进视口。不能拿 `away` 来问：它要离底过了门槛才亮，滚开几十像素时已经不跟了、它还没亮。
+     */
+    keep(target: HTMLElement): void;
+}
+export declare function useFollowBottom({ surfaceId, count, tail, namespace, ready, live, }: {
+    /** 这是哪个对话、侧聊或委派。没东西可显示时是 `null`。 */
+    surfaceId: string | null;
+    /** 转录有多少行。 */
+    count: number;
+    /** 最后一行变了它就变的东西——见 `Marker`。 */
+    tail: string;
+    /** 记在哪一类界面名下；见 `memory.ts`。 */
+    namespace: string;
+    /** 恢复的偏移只有在这个面的内容到了之后才有意义。 */
+    ready?: boolean;
+    /**
+     * 这份转录此刻是不是正在被写。只有这时——以及之后的 `TAIL_MS`，最后几个字还在放出来——长高才算
+     * 输出，也只有输出才追：静止时长高是一张卡片或一张图片晚到了——交付卡片挂载后才去取文件——为它
+     * 滑动，等于把整段历史从下面往上拖。
+     */
+    live: boolean;
+}): FollowBottom;

package/dist/client/ui/src/scroll/useSideways.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 一条横着滚的东西，怎么让人滚得动、以及怎么说明它还没滚完。
+ *
+ * 两件事一直缺，而且缺在每一个横向容器上——标签栏、附件条、宽表格。
+ *
+ * **滚得动。** 横向滚动在这个应用里此前只有触摸板能做：两指一划。用鼠标的人手上只有一个垂直
+ * 滚轮，而垂直滚轮在一个只能横着滚的容器上什么也不做——内容明明溢出了，滚轮转起来毫无反应，看
+ * 起来就像卡住了。Shift + 滚轮是这件事在别处的通用手势，这里把它接上。
+ *
+ * 默认只接管按住 Shift 的那一下，不碰光秃秃的垂直滚轮。后者要留给上层：附件条就躺在输入框里，
+ * 输入框躺在转录区里，吃掉它等于让人滚不动这一整页。标签栏长在头部或底边，上面没有要竖着滚的
+ * 东西，传 `plainWheel` 让普通滚轮直接横着走——那里就不再需要一对方向键。
+ *
+ * **说明还没滚完。** 两端各一道渐隐，按滚动位置来：左边滚出去了左边才有，右边还有货右边才有。
+ * 硬边缘和「刚好排满」长得一模一样，而它们的意思相反——一个是「右边还有三个标签」，另一个是
+ * 「就这些了」。`plume-fade-tail` 那张遮罩早就在，只是 `--plume-fade-left/right` 从来没人喂过值，于是
+ * 三个标签栏都挂着一张全不透明的遮罩，等于没有。
+ *
+ * 量的是滚动条自己的三个数，不是鼠标做了什么：内容变了、窗口宽了、程序改了 `scrollLeft`，渐隐
+ * 都得跟着变，而这些一个都不经过滚轮。
+ */
+/** 两头各自还有没有东西。渐隐和方向键读的是同一份，所以永远同进同出。 */
+export interface SidewaysEdges {
+    canLeft: boolean;
+    canRight: boolean;
+}
+export declare function useSideways(ref: React.RefObject<HTMLElement | null>, { plainWheel }?: {
+    plainWheel?: boolean;
+}): SidewaysEdges;

package/dist/contract/src/app.d.ts

@@ -0,0 +1,16 @@
+/**
+ * agent 和装配它的应用之间的约定：应用提供要加载的插件，接收日志。
+ */
+/** 待加载的插件。load 导入逻辑入口，返回模块的默认导出。 */
+export interface PluginEntry {
+    /** 出错时用来指认插件；拿不到名字时（导入失败、导出不合法）状态里也用它。 */
+    key: string;
+    load(): Promise<unknown>;
+    /** 界面入口的地址。 */
+    ui?: string;
+    /** 随应用发的插件，见 `PluginStatus.builtin`。 */
+    builtin?: boolean;
+    /** 插件目录（`package.json` 所在处），经 `ctx.plugins.list()` 告诉别的插件。只测宿主时可以不给。 */
+    dir?: string;
+}
+export type Log = (source: string, level: "info" | "warn" | "error", message: string) => void;

package/dist/contract/src/changes.d.ts

@@ -0,0 +1,50 @@
+/** 文件工具留下的本轮净变化；快照和撤销由提供 file.changes 服务的插件负责。 */
+export interface ChangeHunk {
+    oldStart: number;
+    newStart: number;
+    lines: {
+        type: "context" | "add" | "remove";
+        text: string;
+        oldLine?: number;
+        newLine?: number;
+    }[];
+}
+export interface ChangedFile {
+    /** 真实绝对路径；界面只在显示时相对化，文件菜单和撤销不丢失工作目录。 */
+    path: string;
+    added: number;
+    removed: number;
+    hunks: ChangeHunk[];
+    canUndo: boolean;
+    /** 不能撤销时给人看的原因，按当前界面语言返回。 */
+    undoReason?: string;
+    /** 不能撤销的原因归哪一类；快照读不出来时不给，那时 `FileChangesSummary.warnings` 不为空。 */
+    undoProblem?: UndoProblem;
+}
+/** 不能自动退回的几种情况：改动来自命令、中途被别处改过、不在项目内、之后被改过。 */
+export type UndoProblem = "command" | "interleaved" | "outside" | "modified";
+export interface FileChangesSummary {
+    files: ChangedFile[];
+    warnings: string[];
+}
+/** 快照标识来自工具结果的 changeId / changeIds，不接受界面传来的文件原文。 */
+export interface FileChangesService {
+    collect(sessionId: string, cwd: string, ids: readonly string[]): Promise<FileChangesSummary>;
+    /** path 不给时撤销全部；写入前重新校验快照、当前内容和项目边界。 */
+    undo(sessionId: string, cwd: string, ids: readonly string[], path?: string): Promise<void>;
+}
+/** 撤回、编辑重发截掉一段对话时，那段里改过的一个文件。`problem` 为 null 的能安全退回到截断点之前。 */
+export interface RevertFile {
+    path: string;
+    added: number;
+    removed: number;
+    problem: UndoProblem | null;
+}
+/**
+ * 截掉的那段改过哪些文件。`unrecorded` 说有改动没记下来（快照缺了、命令影响的文件太多没记全），这时退回的不完整，
+ * 一个文件都不该写。
+ */
+export interface RevertPlan {
+    files: RevertFile[];
+    unrecorded: boolean;
+}

package/dist/contract/src/diagnostics.d.ts

@@ -0,0 +1,86 @@
+import type { AssistantMessage, Message, ToolSpec } from "../../core/llm/types.d.ts";
+import type { AgentEvent, TurnStop } from "./service.ts";
+/** 会话的只读运行观察，不包含供应商配置、请求头和密钥。观察者失败不影响运行。 */
+export interface SessionObservation {
+    sessionId: string;
+    /** 观察时已有的消息数；撤回时诊断记录跟着截断。 */
+    at: number;
+    timestamp: number;
+    event: Extract<AgentEvent, {
+        type: "toolStart" | "approval" | "hiccups" | "notice" | "rewound";
+    }> | {
+        type: "request";
+        id: string;
+        provider: string;
+        model: string;
+        systemPrompt: string;
+        messages: Message[];
+        tools: ToolSpec[];
+    } | {
+        type: "response";
+        id: string;
+        reply: AssistantMessage;
+    } | {
+        type: "running";
+        running: boolean;
+    }
+    /** 一轮收场了、为什么收场：完成、出错、被停下、用满步数、原地打转，退出应用时停下的是 `interrupted`。 */
+     | {
+        type: "turnEnd";
+        stop: TurnStop;
+    };
+}
+/** 后台进程只按所属会话和任务 id 操作，不能传 pid 或日志路径。 */
+export interface BackgroundJobInfo {
+    id: string;
+    command: string;
+    description?: string;
+    startedAt: number;
+    finishedAt?: number;
+    exitCode: number | null;
+    pid?: number;
+    status: "running" | "stopping" | "exited" | "failed";
+    error?: string;
+    kind?: "monitor";
+}
+export interface BackgroundJobsService {
+    list(sessionId: string): BackgroundJobInfo[];
+    /** 尾部输出；不标记为模型已读，不消费后台送达。 */
+    output(sessionId: string, jobId: string): Promise<{
+        text: string;
+        done: boolean;
+        truncated: boolean;
+        error?: string;
+    }>;
+    stop(sessionId: string, jobId: string, force: boolean): boolean;
+}
+/**
+ * 模型给一个会话安排的「以后再接着做」：`schedule_wakeup` 的一次性唤醒（`kind: "wakeup"`）或 `cron_create` 的定时触发，还没触发的那一个。
+ * 只活在 agent 进程的内存里：退出应用、人按停止、撤回或编辑重发都会取消。
+ */
+export interface SessionWakeup {
+    /** `wake-1`、`cron-2`，在会话里唯一。 */
+    id: string;
+    kind: "wakeup" | "cron";
+    /** 到点时送给模型的那段话，模型写给自己的。 */
+    prompt: string;
+    /** 给人看的几个字（一次性唤醒必填）；没有时界面用 `prompt` 的第一行。 */
+    reason?: string;
+    /** 5 段 cron 表达式，本地时间；一次性唤醒没有。 */
+    cron?: string;
+    recurring: boolean;
+    createdAt: number;
+    /** 下一次触发的时刻。 */
+    nextAt: number;
+    /** 循环任务过期的时刻，之后不再触发。 */
+    expiresAt?: number;
+    /** 已经触发过几次。 */
+    fired: number;
+}
+/** 服务 `session.wakeups`：读、取消会话里待触发的定时唤醒。内置插件 plume.tools 提供（它注册 `schedule_wakeup`、`cron_*` 这几件工具）。 */
+export interface SessionWakeupsService {
+    /** 按下一次触发的先后；会话没有、没安排过时是空数组。 */
+    list(sessionId: string): SessionWakeup[];
+    /** 取消一个；已经触发了、不存在时返回 false。 */
+    cancel(sessionId: string, id: string): boolean;
+}

package/dist/contract/src/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 共享类型：跨包、跨进程的约定都在这里，只有类型，没有运行时代码。按用途分文件：
+ *
+ * - `plugin.ts`：插件逻辑入口的 API（钩子、工具、ctx）；界面入口的在 `ui.ts`（`@plume/contract/ui`）；`resources.ts`：服务 `resources` 的资源地址；
+ * - `service.ts`：agent 进程给界面的 AgentService、事件和视图；`usage.ts`：存储页和插件读的使用统计数据；
+ * - `app.ts`：agent 和装配它的应用之间的约定（待加载的插件、日志）。
+ *
+ * 消息类型定义在 `@plume/llm`，在这里转出，使用方一律从 `@plume/contract` 引用。
+ */
+export type { ApiFormat, AssistantMessage, DeliveredReport, ImageContent, Message, MessageAttachment, PeerLetter, TextContent, ToolResultMessage, ToolSpec, UserContent, UserMessage, } from "../../core/llm/types.d.ts";
+export type { CallContext } from "../../infra/rpc/src/index.d.ts";
+export type * from "./app.ts";
+export type * from "./changes.ts";
+export type * from "./diagnostics.ts";
+export type * from "./plugin.ts";
+export type * from "./resources.ts";
+export type * from "./service.ts";
+export type * from "./usage.ts";