@qjp88995/agent-runtime 0.0.0-stage → 0.1.0

package/dist/ports/image-source.d.ts

@@ -0,0 +1,26 @@
+/** 一张图的字节。 */
+export interface ImageBytes {
+    data: Uint8Array;
+    /** 存储给的媒体类型；投影层 part 上的 `mediaType` 优先，这个只在那边缺席时兜底。 */
+    contentType: string;
+    /** 字节的 sha256 hex。存储已经算过就给，省一次哈希；缺席时 runtime 自己算。 */
+    contentHash?: string;
+}
+/**
+ * 图片字节从哪来（`ToolResultImage.src` → 字节）。runtime 不认识存储：库里只有 `src`，
+ * 递送时才按它取字节（agent-base 里是存储中心 + `/api/files/<id>`）。
+ *
+ * `src` 指向的内容必须不可变（换内容就是新的 `src`）——递送按 `src` 缓存字节，前缀缓存也
+ * 要求同一张图每轮逐字节相同。
+ */
+export interface ImageSource {
+    /** 取字节。对象没了 / 后端不可达就抛：递送把它变成一句给模型看的话，不会让这一轮失败。 */
+    read(src: string): Promise<ImageBytes>;
+    /**
+     * 这张图的公网地址（递送第二档），没有给 null。必须是**稳定**的地址（例如本站的
+     * `/api/files/<id>` 再 302 到签名链接），不要直接给会过期的签名链接：地址一变，
+     * 历史里的图跟着变，前缀缓存整段 miss。只有承载包 `supportedUrls` 认这个地址时才会用。
+     */
+    publicUrl?(src: string): string | null;
+}
+//# sourceMappingURL=image-source.d.ts.map

package/dist/ports/image-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-source.d.ts","sourceRoot":"","sources":["../../src/ports/image-source.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACvC;;;;OAIG;IACH,SAAS,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACxC"}

package/dist/ports/image-source.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=image-source.js.map

package/dist/ports/image-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-source.js","sourceRoot":"","sources":["../../src/ports/image-source.ts"],"names":[],"mappings":""}

package/dist/ports/index.d.ts

@@ -0,0 +1,11 @@
+export type { ContextInputs, ContextRow, ContextStore, } from './context-store.js';
+export type { ConversationMessage, ConversationStore, InboxItem, InboxMessageKind, InboxSourceKind, ListMessagesFilter, NewConversationMessage, } from './conversation-store.js';
+export { AWAIT_LEASE_TTL_MS, AWAIT_RENEW_INTERVAL_MS, LOCK_TTL_MS, type SessionLock, type SubagentAwaitLease, type TreeBudget, type WakeChannel, } from './coordination.js';
+export type { ImageBytes, ImageSource } from './image-source.js';
+export { consoleLogger, type Logger, type LoggerFactory, silentLogger, } from './logger.js';
+export { type NewQuestion, QuestionConflictError, type QuestionProbe, type QuestionRecord, type QuestionStore, type SettledQuestionStatus, } from './question-store.js';
+export type { RunFinishInput, RunOpenInput, RunStore, StaleRun, } from './run-store.js';
+export type { NewSubSession, SessionKind, SessionRecord, SessionStore, } from './session-store.js';
+export type { SessionStreamEntry, StreamBus } from './stream-bus.js';
+export type { VendorFileCache, VendorFileKey, VendorFileRecord, } from './vendor-file-cache.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/ports/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,aAAa,EACb,UAAU,EACV,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,WAAW,EACX,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EACL,aAAa,EACb,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,WAAW,EAChB,qBAAqB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,cAAc,EACd,YAAY,EACZ,QAAQ,EACR,QAAQ,GACT,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,aAAa,EACb,WAAW,EACX,aAAa,EACb,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACrE,YAAY,EACV,eAAe,EACf,aAAa,EACb,gBAAgB,GACjB,MAAM,wBAAwB,CAAC"}

package/dist/ports/index.js

@@ -0,0 +1,4 @@
+export { AWAIT_LEASE_TTL_MS, AWAIT_RENEW_INTERVAL_MS, LOCK_TTL_MS, } from './coordination.js';
+export { consoleLogger, silentLogger, } from './logger.js';
+export { QuestionConflictError, } from './question-store.js';
+//# sourceMappingURL=index.js.map

package/dist/ports/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,WAAW,GAKZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,aAAa,EAGb,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,qBAAqB,GAKtB,MAAM,qBAAqB,CAAC"}

package/dist/ports/logger.d.ts

@@ -0,0 +1,14 @@
+/** 日志端口。runtime 不依赖任何日志框架；Nest 适配把它接到 Nest 的 Logger。 */
+export interface Logger {
+    debug(message: string): void;
+    log(message: string): void;
+    warn(message: string): void;
+    error(message: string, stack?: string): void;
+}
+/** 按作用域取一个 logger（对应 Nest 的 `new Logger(Class.name)`）。 */
+export type LoggerFactory = (scope: string) => Logger;
+/** 缺省实现：写 console，带作用域前缀；debug 只在 `AGENT_RUNTIME_DEBUG` 设置时输出。 */
+export declare const consoleLogger: LoggerFactory;
+/** 什么都不输出（单测用）。 */
+export declare const silentLogger: LoggerFactory;
+//# sourceMappingURL=logger.d.ts.map

package/dist/ports/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/ports/logger.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9C;AAED,0DAA0D;AAC1D,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;AAEtD,kEAAkE;AAClE,eAAO,MAAM,aAAa,EAAE,aAa3B,CAAC;AAEF,mBAAmB;AACnB,eAAO,MAAM,YAAY,EAAE,aAKzB,CAAC"}

package/dist/ports/logger.js

@@ -0,0 +1,23 @@
+/** 缺省实现：写 console，带作用域前缀；debug 只在 `AGENT_RUNTIME_DEBUG` 设置时输出。 */
+export const consoleLogger = scope => {
+    const tag = `[${scope}]`;
+    return {
+        debug: message => {
+            if (process.env.AGENT_RUNTIME_DEBUG)
+                console.debug(tag, message);
+        },
+        log: message => console.log(tag, message),
+        warn: message => console.warn(tag, message),
+        error: (message, stack) => stack
+            ? console.error(tag, message, '\n', stack)
+            : console.error(tag, message),
+    };
+};
+/** 什么都不输出（单测用）。 */
+export const silentLogger = () => ({
+    debug: () => { },
+    log: () => { },
+    warn: () => { },
+    error: () => { },
+});
+//# sourceMappingURL=logger.js.map

package/dist/ports/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/ports/logger.ts"],"names":[],"mappings":"AAWA,kEAAkE;AAClE,MAAM,CAAC,MAAM,aAAa,GAAkB,KAAK,CAAC,EAAE;IAClD,MAAM,GAAG,GAAG,IAAI,KAAK,GAAG,CAAC;IACzB,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,EAAE;YACf,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB;gBAAE,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACnE,CAAC;QACD,GAAG,EAAE,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC;QACzC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC;QAC3C,KAAK,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CACxB,KAAK;YACH,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC;YAC1C,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC;KAClC,CAAC;AACJ,CAAC,CAAC;AAEF,mBAAmB;AACnB,MAAM,CAAC,MAAM,YAAY,GAAkB,GAAG,EAAE,CAAC,CAAC;IAChD,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;IACf,GAAG,EAAE,GAAG,EAAE,GAAE,CAAC;IACb,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;CAChB,CAAC,CAAC"}

package/dist/ports/question-store.d.ts

@@ -0,0 +1,91 @@
+import type { AgentQuestionAnswer, AgentQuestionStatus, AskQuestionItem } from '../builtins/ask-schema.js';
+/**
+ * `Ask` 工具的问题行。搬自 agent-base 的 `agent_question` 表：每一次提问一行，
+ * `pending` 的那一行就是「这一轮正在等用户」。
+ *
+ * **时间一律按存储自己的时钟**（数据库实现里是 `now()`）：期限在落行时由存储算出，
+ * 「到点没有」也由存储判——等待方、回答接口可能在不同实例上，各自的挂钟比出来的
+ * 结果不可信（容器的挂钟还会回拨）。
+ */
+export interface QuestionRecord {
+    id: string;
+    sessionId: string;
+    userId: string;
+    /** 提问的那一轮。 */
+    runId: string;
+    /** 那次 `Ask` 调用；界面按它把这一行对到工具卡上。 */
+    toolCallId: string;
+    questions: AskQuestionItem[];
+    status: AgentQuestionStatus;
+    /** null = 不限时（或已经停表，见 `hold`）。 */
+    deadlineAt: Date | null;
+    /** `answered` 是用户选的，`expired` 是默认项，其余为 null。 */
+    answers: AgentQuestionAnswer[] | null;
+    createdAt: Date;
+    resolvedAt: Date | null;
+}
+export type SettledQuestionStatus = Exclude<AgentQuestionStatus, 'pending'>;
+export interface NewQuestion {
+    sessionId: string;
+    userId: string;
+    runId: string;
+    toolCallId: string;
+    questions: AskQuestionItem[];
+    /** 从落行起多少秒到期；缺省不限时。 */
+    timeoutSeconds?: number;
+}
+/** `probe` 的读数：那一行，加上按存储时钟判出的两个标志。 */
+export interface QuestionProbe {
+    question: QuestionRecord;
+    /** 有期限且已到。 */
+    due: boolean;
+    /** 从落行起已经过了 `maxWaitSeconds`。 */
+    overdue: boolean;
+}
+/** 同一个会话里同一轮已有一个问题在等（`open` 抛它）。 */
+export declare class QuestionConflictError extends Error {
+    constructor(sessionId: string);
+}
+/**
+ * 问题行的存储。
+ *
+ * **一个会话同时至多一个 pending**（数据库实现：`sessionId` 上 `status = 'pending'`
+ * 的部分唯一索引）。所有「给结局」的写法都带 `status = 'pending'` 谓词——回答、到点、
+ * 改为打字、停止抢的是同一句原子更新，只有一个生效。
+ */
+export interface QuestionStore {
+    /**
+     * 落一个新问题，**一个原子步骤**里先把这个会话里**别的轮次**留下的 pending 作废
+     * （那只可能是残骸：等它的那一轮已经死了），再插入。同一轮已有 pending 时抛
+     * `QuestionConflictError`（同一步里的第二次调用，让模型合并）。
+     *
+     * 返回新行与被作废的残骸（调用方要把它们也广播出去）。
+     */
+    open(input: NewQuestion): Promise<{
+        question: QuestionRecord;
+        swept: QuestionRecord[];
+    }>;
+    /** 读一行并按存储时钟判到期；行不存在（会话被删）返回 null。 */
+    probe(id: string, maxWaitSeconds: number): Promise<QuestionProbe | null>;
+    /** 读一行；限定会话时，不属于它的当不存在。 */
+    get(id: string, sessionId?: string): Promise<QuestionRecord | null>;
+    /**
+     * 给一个 pending 的问题一个结局（CAS：仅当仍是 pending）。没抢到返回 null。
+     * 同时写 `resolvedAt`。
+     */
+    settle(id: string, status: SettledQuestionStatus, answers: AgentQuestionAnswer[] | null): Promise<QuestionRecord | null>;
+    /**
+     * 这个会话所有 pending（或仅 `onlyId` 那一个）一律记为 `status`，返回被改的行。
+     */
+    settleSession(sessionId: string, status: Extract<SettledQuestionStatus, 'superseded' | 'cancelled'>, onlyId?: string): Promise<QuestionRecord[]>;
+    /**
+     * 停表：仅当仍是 pending **且**还有期限时把期限摘掉，返回改后的行；条件不满足
+     * 返回 null（调用方自己读当前行）。与到点互斥靠同一个 pending 谓词。
+     */
+    hold(id: string, sessionId: string): Promise<QuestionRecord | null>;
+    /** 这个会话问过的全部问题，按落行时间正序。 */
+    list(sessionId: string): Promise<QuestionRecord[]>;
+    /** 存储时钟（算 `remainingMs` 用）。 */
+    now(): Promise<Date>;
+}
+//# sourceMappingURL=question-store.d.ts.map

package/dist/ports/question-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-store.d.ts","sourceRoot":"","sources":["../../src/ports/question-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EAChB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc;IACd,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,kCAAkC;IAClC,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,gDAAgD;IAChD,OAAO,EAAE,mBAAmB,EAAE,GAAG,IAAI,CAAC;IACtC,SAAS,EAAE,IAAI,CAAC;IAChB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,MAAM,qBAAqB,GAAG,OAAO,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAC;AAE5E,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,uBAAuB;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,cAAc,CAAC;IACzB,cAAc;IACd,GAAG,EAAE,OAAO,CAAC;IACb,iCAAiC;IACjC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,oCAAoC;AACpC,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,SAAS,EAAE,MAAM;CAI9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,IAAI,CACF,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC;QAAE,QAAQ,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,cAAc,EAAE,CAAA;KAAE,CAAC,CAAC;IAElE,sCAAsC;IACtC,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAEzE,2BAA2B;IAC3B,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAEpE;;;OAGG;IACH,MAAM,CACJ,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,mBAAmB,EAAE,GAAG,IAAI,GACpC,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAElC;;OAEG;IACH,aAAa,CACX,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,OAAO,CAAC,qBAAqB,EAAE,YAAY,GAAG,WAAW,CAAC,EAClE,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAE7B;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAEpE,2BAA2B;IAC3B,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAEnD,+BAA+B;IAC/B,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB"}

package/dist/ports/question-store.js

@@ -0,0 +1,8 @@
+/** 同一个会话里同一轮已有一个问题在等（`open` 抛它）。 */
+export class QuestionConflictError extends Error {
+    constructor(sessionId) {
+        super(`session ${sessionId} already has a pending question`);
+        this.name = 'QuestionConflictError';
+    }
+}
+//# sourceMappingURL=question-store.js.map

package/dist/ports/question-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-store.js","sourceRoot":"","sources":["../../src/ports/question-store.ts"],"names":[],"mappings":"AAqDA,oCAAoC;AACpC,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,SAAiB;QAC3B,KAAK,CAAC,WAAW,SAAS,iCAAiC,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF"}

package/dist/ports/run-store.d.ts

@@ -0,0 +1,66 @@
+import type { AgentRunStatus, AgentRunStepEntry, StopReason } from '../schema/agent-run.js';
+/**
+ * 开一个跑次要记的东西。
+ *
+ * `attrs` 是宿主的不透明附加列：跑的是哪个 agent（agent-base 是 `agent_id` / `builtin_agent`
+ * 两列二选一）、发布版号、账本序号……runtime 不解释，只从 turn 的入参原样转交给存储。
+ */
+export interface RunOpenInput {
+    id: string;
+    streamId: string;
+    parentRunId: string | null;
+    depth: number;
+    sessionId: string | null;
+    /** 父写给子的任务；根跑次为 null。 */
+    prompt: string | null;
+    /** 本轮实际用的模型与推理档位。 */
+    model: {
+        modelId: string;
+        label: string;
+        reasoningEffort: string;
+    };
+    attrs?: Readonly<Record<string, unknown>>;
+}
+export interface RunFinishInput {
+    id: string;
+    status: AgentRunStatus;
+    stopReason: StopReason | null;
+    text: string;
+    steps: AgentRunStepEntry[];
+    usage?: Record<string, number>;
+    error?: string;
+}
+/** 孤儿收尾的候选（仍是 running 且开跑已久）。 */
+export interface StaleRun {
+    id: string;
+    streamId: string;
+    sessionId: string | null;
+    /** 补发会话事件要按根会话定位；会话已删时为 null。 */
+    rootSessionId: string | null;
+    parentRunId: string | null;
+    depth: number;
+}
+/**
+ * 跑次记录。搬自 agent-base `agent-core/runtime/agent-run.service.ts`，只留 runtime 要用的；
+ * 给界面用的读接口（调用树、按 agent 显示名）留在宿主。
+ */
+export interface RunStore {
+    /** 跑次开始即建记录（status = running）。 */
+    open(input: RunOpenInput): Promise<void>;
+    finish(input: RunFinishInput): Promise<void>;
+    /**
+     * 仍是 running、且开跑已超过 `olderThanMs` 的跑次——只出候选，是不是孤儿由调用方
+     * 问会话锁。时间下限挡住「刚 open、锁还没抢上」的窗口。
+     */
+    findStaleRunning(olderThanMs: number): Promise<StaleRun[]>;
+    /**
+     * 把一条孤儿收成 aborted。**只在它仍是 running 时生效**，返回是否由本次调用翻的牌
+     * （并发下只可能成功一次；调用方据此决定要不要再去改消息、发事件）。
+     */
+    markInterrupted(id: string, error: string): Promise<boolean>;
+    /** 跑次所属会话；缺记录返回 null。 */
+    getSessionId(runId: string): Promise<string | null>;
+    /** 跑次深度；缺记录返回 0。 */
+    getDepth(runId: string): Promise<number>;
+}
+//# sourceMappingURL=run-store.d.ts.map

package/dist/ports/run-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-store.d.ts","sourceRoot":"","sources":["../../src/ports/run-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,UAAU,EACX,MAAM,wBAAwB,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,yBAAyB;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,qBAAqB;IACrB,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,cAAc,CAAC;IACvB,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,iCAAiC;AACjC,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,iCAAiC;IACjC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,kCAAkC;IAClC,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C;;;OAGG;IACH,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC3D;;;OAGG;IACH,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7D,yBAAyB;IACzB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACpD,oBAAoB;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1C"}

package/dist/ports/run-store.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run-store.js.map

package/dist/ports/run-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-store.js","sourceRoot":"","sources":["../../src/ports/run-store.ts"],"names":[],"mappings":""}

package/dist/ports/session-store.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 会话行：loop 与子 Agent 要读写的那几个字段。搬自 agent-base `chat_session` 被
+ * `subagent-session.service` / `loop-driver` 读写的部分；会话的其余一切（标题怎么改、
+ * 谁看得见、列表、删除）归宿主。
+ *
+ * **根会话由宿主建**（用户开对话是宿主的事），runtime 只建子会话。
+ */
+export type SessionKind = 'root' | 'subagent';
+export interface SessionRecord {
+    id: string;
+    kind: SessionKind;
+    /** 根会话 id；根会话等于自己的 id。 */
+    rootSessionId: string;
+    /** 子会话：派它的那一轮（父的跑次 id）。父会话经 `RunStore.getSessionId` 由它找到。根会话 null。 */
+    parentRunId: string | null;
+    /**
+     * 子会话钉住的子 Agent 名（派生时给的名字，可能是改名前的旧名——查定义要认
+     * `formerNames`）。根会话 null。
+     */
+    subagentName: string | null;
+    title: string | null;
+    userId: string | null;
+    /**
+     * 里程碑游标：上次回投覆盖到的子会话消息 `seq`。**null = 从未到达过 idle 终态**
+     * （＝「存活」，占着树的名额）。只经 `advanceMilestone` 的 CAS 推进。根会话恒 null。
+     */
+    lastMilestoneSeq: number | null;
+    /** 会话上的不透明附加信息（`ToolContext.sessionMetadata`）；子会话照抄父的。 */
+    metadata: Readonly<Record<string, unknown>>;
+    /** 宿主的不透明附加列（agent-base：跑哪个 agent、哪一版）。runtime 不解释。 */
+    attrs: Readonly<Record<string, unknown>>;
+}
+export interface NewSubSession {
+    rootSessionId: string;
+    parentRunId: string;
+    subagentName: string;
+    userId: string | null;
+    title: string;
+    metadata?: Readonly<Record<string, unknown>>;
+    attrs?: Readonly<Record<string, unknown>>;
+}
+export interface SessionStore {
+    /** 建一个子会话（`kind = 'subagent'`、游标 null）。 */
+    createSubSession(input: NewSubSession): Promise<SessionRecord>;
+    /** 会话行；不存在（或已删）返回 null。 */
+    getSession(id: string): Promise<SessionRecord | null>;
+    /**
+     * 里程碑游标的**乐观 CAS**：仅当游标仍等于 `expected`（null 即「仍为空」）时写成
+     * `next`，返回是否写成。
+     *
+     * 子会话的收尾可能并发进来两次（两次抢锁成功的唤醒），都读到同一个旧游标；恰有一个
+     * 能从它推进——回投、唤醒父、还名额这些副作用全收在这一步之后，所以恰好发生一次。
+     * 游标是整数，写回读出不丢精度（时间戳版本靠「两边都截到毫秒」才成立，一环换成
+     * 微秒就静默失配）。
+     */
+    advanceMilestone(id: string, expected: number | null, next: number): Promise<boolean>;
+    /**
+     * 兜底扫描的候选：子会话、`idleForMs` 内没有新动静（`ConversationStore` 记的那个
+     * 「更新时间」）、且有 `seq > coalesce(游标, 0)` 的 assistant 消息——收尾可能在回投之前
+     * 崩掉，这些是「跑完了却没人通知父」的嫌疑。是不是真的漏了由收尾自己判（它是幂等的）。
+     */
+    listSubagentSessionsForSweep(idleForMs: number): Promise<SessionRecord[]>;
+    /**
+     * 每棵树此刻「存活」的子会话数（`kind = 'subagent'` 且游标为 null）。零存活的树
+     * 可以不出现，调用方自己补 0。兜底扫描据此校正 `TreeBudget`。
+     */
+    countAliveSubsByRoot(): Promise<{
+        rootSessionId: string;
+        count: number;
+    }[]>;
+}
+//# sourceMappingURL=session-store.d.ts.map

package/dist/ports/session-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.d.ts","sourceRoot":"","sources":["../../src/ports/session-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,0BAA0B;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;OAGG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,0DAA0D;IAC1D,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5C,uDAAuD;IACvD,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7C,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAE/D,2BAA2B;IAC3B,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAEtD;;;;;;;;OAQG;IACH,gBAAgB,CACd,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB;;;;OAIG;IACH,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAE1E;;;OAGG;IACH,oBAAoB,IAAI,OAAO,CAAC;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAC;CAC7E"}

package/dist/ports/session-store.js

@@ -0,0 +1,9 @@
+/**
+ * 会话行：loop 与子 Agent 要读写的那几个字段。搬自 agent-base `chat_session` 被
+ * `subagent-session.service` / `loop-driver` 读写的部分；会话的其余一切（标题怎么改、
+ * 谁看得见、列表、删除）归宿主。
+ *
+ * **根会话由宿主建**（用户开对话是宿主的事），runtime 只建子会话。
+ */
+export {};
+//# sourceMappingURL=session-store.js.map

package/dist/ports/session-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.js","sourceRoot":"","sources":["../../src/ports/session-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/ports/stream-bus.d.ts

@@ -0,0 +1,52 @@
+import type { AgentEvent } from '../schema/agent-event.js';
+/** 会话级订阅的一条：游标（断线续订用，实现自定格式）+ 领域事件。 */
+export interface SessionStreamEntry {
+    id: string;
+    event: AgentEvent;
+}
+/**
+ * 事件总线。搬自 agent-base `agent-core/events/stream-bus.interface.ts`。
+ *
+ * 两个面：
+ * - **per-stream 面**（`open` / `publish` / `subscribe` / `close` / `abort`）：一轮一条流，
+ *   带 seq 分配与中断信号。
+ * - **会话面**（`subscribeSession`）：按根会话聚合整棵树的事件，跨轮、跨子会话；前端走这个。
+ *
+ * 默认实现 `InProcessStreamBus` 只在单进程里成立（POST 落 A 实例、SSE 落 B 实例就收不到）；
+ * 多实例换 Redis 适配。
+ */
+export interface StreamBus {
+    /** 开一条流；返回该流的 seq 分配器。重复 open 同一 id 抛错。 */
+    open(streamId: string): {
+        nextSeq: () => number;
+    };
+    /** 发布事件（seq 由调用方用 open 返回的分配器取）。流未 open / 已 close 时丢弃。 */
+    publish(event: AgentEvent): void;
+    /**
+     * 发布一条**不属于任何 run** 的会话级事件，直接进会话面。
+     * `event` 的 `seq` / `streamId` / `runId` 对本方法无意义（填 0 / 会话 id），消费方不得读。
+     */
+    publishSessionEvent(event: AgentEvent): void;
+    /**
+     * 订阅一条流。`fromSeq` 给出时先补发 seq >= fromSeq 的历史，再接活流；流已结束则补完即止。
+     * `signal` abort 时等待中的迭代立即结束并摘掉监听（否则 `.return()` 会卡在未 settle 的
+     * promise 上，订阅者变僵尸）。
+     */
+    subscribe(streamId: string, fromSeq?: number, signal?: AbortSignal): AsyncIterable<AgentEvent>;
+    /** 按根会话树订阅。`fromId` 给出时从该游标之后补发；缺省从最旧保留项起。 */
+    subscribeSession(rootSessionId: string, fromId: string | undefined, signal: AbortSignal): AsyncIterable<SessionStreamEntry>;
+    /**
+     * 这一轮 seq ≤ `uptoSeq` 的事件已完整落库，会话面可以让它们退役（刷新重建时由库里的行顶替）。
+     * 实现可以留宽限期再删，也可以是 no-op。
+     */
+    retireUpTo(runId: string, uptoSeq: number): void;
+    /** 标记流结束，唤醒所有订阅者收尾。buffer 保留一段时间供重连补发。 */
+    close(streamId: string): void;
+    /** 请求取消：触发该流的 AbortSignal。 */
+    abort(streamId: string): void;
+    /** 该流是否仍在生成中（未 close）。 */
+    isActive(streamId: string): boolean;
+    /** 取该流的 AbortSignal，喂给模型调用。 */
+    signalOf(streamId: string): AbortSignal | undefined;
+}
+//# sourceMappingURL=stream-bus.d.ts.map

package/dist/ports/stream-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-bus.d.ts","sourceRoot":"","sources":["../../src/ports/stream-bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,UAAU,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,MAAM,CAAA;KAAE,CAAC;IAClD,0DAA0D;IAC1D,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACjC;;;OAGG;IACH,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAC7C;;;;OAIG;IACH,SAAS,CACP,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,WAAW,GACnB,aAAa,CAAC,UAAU,CAAC,CAAC;IAC7B,8CAA8C;IAC9C,gBAAgB,CACd,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,WAAW,GAClB,aAAa,CAAC,kBAAkB,CAAC,CAAC;IACrC;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACjD,0CAA0C;IAC1C,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,8BAA8B;IAC9B,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,0BAA0B;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,+BAA+B;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;CACrD"}

package/dist/ports/stream-bus.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=stream-bus.js.map

package/dist/ports/stream-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-bus.js","sourceRoot":"","sources":["../../src/ports/stream-bus.ts"],"names":[],"mappings":""}

package/dist/ports/vendor-file-cache.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 厂商文件按「哪家、哪个账号、哪份字节」定位：同一份字节传到不同账号是不同的文件，
+ * 一个账号传上去的 file id 别的账号用不了。
+ */
+export interface VendorFileKey {
+    /** 厂商 slug（`ModelRef.vendor`）。 */
+    vendor: string;
+    /**
+     * 文件落在哪个账号上：中心模式是上传结果的 `credentialRef`（之后引用它要 pin 这把），
+     * 直连模式是 `DIRECT_ACCOUNT`。
+     */
+    account: string;
+    /** 上传字节的 sha256 hex。 */
+    contentHash: string;
+}
+export interface VendorFileRecord extends VendorFileKey {
+    fileId: string;
+    /** 来自哪张图（只做关联、排查用）。 */
+    src: string | null;
+    mediaType: string;
+    bytes: number;
+    /** 厂商侧到期时间；null = 永久。 */
+    expiresAt: Date | null;
+    lastUsedAt: Date;
+}
+/**
+ * 厂商 Files API 的上传缓存（agent-base 的 `llm_vendor_file` 表）。只是存储：
+ * 新鲜度判据（到期前留余量）、上传合流、失效重传都在 `VendorFiles` 里。
+ *
+ * 多实例共用一份时，宿主用自己的库实现（唯一约束 `(vendor, account, contentHash)`）；
+ * 进程内实现只保证单实例——两个实例同时首传同一张图会各传一份，后写的覆盖前写的，
+ * 前一份成为厂商侧的孤儿直到它自己到期，代价只是厂商配额里多一份副本。
+ */
+export interface VendorFileCache {
+    /** 这家厂商下，这些字节在**任一账号**上的记录（含已到期的，判据归调用方）。 */
+    find(vendor: string, contentHashes: readonly string[]): Promise<VendorFileRecord[]>;
+    /** 按 `(vendor, account, contentHash)` 插入或覆盖。 */
+    put(record: VendorFileRecord): Promise<void>;
+    /** 更新 `lastUsedAt`（调用方已节流）。记录不在就什么都不做。 */
+    touch(key: VendorFileKey, at: Date): Promise<void>;
+    /** 删掉这个账号下这些 file id 的记录（厂商说它们不存在了 / 已到期重传）。 */
+    forget(vendor: string, account: string, fileIds: readonly string[]): Promise<void>;
+    /** 删掉 `expiresAt < now` 的记录，返回删了几条。 */
+    sweepExpired(now: Date): Promise<number>;
+}
+//# sourceMappingURL=vendor-file-cache.d.ts.map

package/dist/ports/vendor-file-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vendor-file-cache.d.ts","sourceRoot":"","sources":["../../src/ports/vendor-file-cache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,IAAI,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,IAAI,CACF,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,SAAS,MAAM,EAAE,GAC/B,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAC/B,gDAAgD;IAChD,GAAG,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,0CAA0C;IAC1C,KAAK,CAAC,GAAG,EAAE,aAAa,EAAE,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,gDAAgD;IAChD,MAAM,CACJ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,uCAAuC;IACvC,YAAY,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1C"}

package/dist/ports/vendor-file-cache.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=vendor-file-cache.js.map

package/dist/ports/vendor-file-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vendor-file-cache.js","sourceRoot":"","sources":["../../src/ports/vendor-file-cache.ts"],"names":[],"mappings":""}

package/dist/schema/agent-event.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 内层领域事件。搬自 agent-base `agent-core/events/agent-event.ts`（2026-11-11）。
+ *
+ * 刻意不用 AI SDK 的 UIMessageChunk：① 会把内核钉死在 SDK 版本的内部形状上；
+ * ② 子 Agent 的 runId / parentRunId / depth 在里面无处安放。
+ *
+ * 只列 runtime 自己产生的类型。宿主的**会话级**事件（自动标题、追问、确认面板……）
+ * 经 `StreamBus.publishSessionEvent` 发，类型名由宿主定——所以 `AgentEvent.type`
+ * 也接受任意字符串；runtime 只对下面这些分支。
+ */
+export declare const AGENT_EVENT_TYPES: readonly ["run-start", "step-start", "text-delta", "text-end", "reasoning-delta", "tool-input-start", "tool-input-delta", "tool-input-progress", "tool-input-preview", "tool-call", "tool-result", "step-finish", "step-retract", "step-usage", "run-finish", "error", "inbox-drained", "agent-question"];
+export type AgentEventType = (typeof AGENT_EVENT_TYPES)[number];
+export interface AgentEvent {
+    /** 每个 streamId 内单调递增，从 1 开始。断线补发的基础。 */
+    seq: number;
+    /** 根 turn 的 id。子 Agent 事件共享父的 streamId 与 seq 序列。 */
+    streamId: string;
+    /** 根会话 id（树级作用域键）。 */
+    rootSessionId: string;
+    /** 产生该事件的会话 id（根或子）。 */
+    sessionId: string;
+    /** 产生该事件的跑次（根或子）。 */
+    runId: string;
+    /** 输出归属哪一条 assistant 消息（恒等于 `runId`）；会话级事件没有。 */
+    messageId?: string;
+    parentRunId: string | null;
+    depth: number;
+    ts: number;
+    /** runtime 的类型见 `AGENT_EVENT_TYPES`；宿主的会话级事件用自己的名字。 */
+    type: AgentEventType | (string & {});
+    payload: unknown;
+}
+/** 每个 stream 一个自增计数器。 */
+export declare function createSeqCounter(): () => number;
+//# sourceMappingURL=agent-event.d.ts.map

package/dist/schema/agent-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-event.d.ts","sourceRoot":"","sources":["../../src/schema/agent-event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,2SA6BpB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,uDAAuD;IACvD,IAAI,EAAE,cAAc,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACrC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,yBAAyB;AACzB,wBAAgB,gBAAgB,IAAI,MAAM,MAAM,CAG/C"}

package/dist/schema/agent-event.js

@@ -0,0 +1,46 @@
+/**
+ * 内层领域事件。搬自 agent-base `agent-core/events/agent-event.ts`（2026-11-11）。
+ *
+ * 刻意不用 AI SDK 的 UIMessageChunk：① 会把内核钉死在 SDK 版本的内部形状上；
+ * ② 子 Agent 的 runId / parentRunId / depth 在里面无处安放。
+ *
+ * 只列 runtime 自己产生的类型。宿主的**会话级**事件（自动标题、追问、确认面板……）
+ * 经 `StreamBus.publishSessionEvent` 发，类型名由宿主定——所以 `AgentEvent.type`
+ * 也接受任意字符串；runtime 只对下面这些分支。
+ */
+export const AGENT_EVENT_TYPES = [
+    'run-start',
+    'step-start',
+    'text-delta',
+    'text-end',
+    'reasoning-delta',
+    'tool-input-start',
+    'tool-input-delta',
+    /** 入参流式构建的进度（`{toolCallId, toolName, chars}`），节流后发出，只服务界面。 */
+    'tool-input-progress',
+    /** 入参的内容预览（白名单工具），只服务界面、不落库、不进模型。 */
+    'tool-input-preview',
+    'tool-call',
+    'tool-result',
+    'step-finish',
+    /**
+     * 这一步在响应中途断连、内核把已经播出去的半截产出作废并原地重发
+     * （`{afterSeq, textChars, reasoningChars, attempt, maxAttempts, message}`）。
+     * 账本那边这些事件已物理删除，本事件只服务界面。
+     */
+    'step-retract',
+    /** 一步的真实用量（`{usage, runUsage}`，后者是本轮累计）。只服务界面。 */
+    'step-usage',
+    'run-finish',
+    'error',
+    /** loop 从 inbox 取走 ≥1 条待处理项后发出，供前端失效待处理队列。 */
+    'inbox-drained',
+    /** 向用户提问的会话级事件（问题落库或状态变了），载荷是整行 `{question}`。 */
+    'agent-question',
+];
+/** 每个 stream 一个自增计数器。 */
+export function createSeqCounter() {
+    let seq = 0;
+    return () => ++seq;
+}
+//# sourceMappingURL=agent-event.js.map

package/dist/schema/agent-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-event.js","sourceRoot":"","sources":["../../src/schema/agent-event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,WAAW;IACX,YAAY;IACZ,YAAY;IACZ,UAAU;IACV,iBAAiB;IACjB,kBAAkB;IAClB,kBAAkB;IAClB,8DAA8D;IAC9D,qBAAqB;IACrB,qCAAqC;IACrC,oBAAoB;IACpB,WAAW;IACX,aAAa;IACb,aAAa;IACb;;;;OAIG;IACH,cAAc;IACd,kDAAkD;IAClD,YAAY;IACZ,YAAY;IACZ,OAAO;IACP,8CAA8C;IAC9C,eAAe;IACf,iDAAiD;IACjD,gBAAgB;CACR,CAAC;AAyBX,yBAAyB;AACzB,MAAM,UAAU,gBAAgB;IAC9B,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,OAAO,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC;AACrB,CAAC"}