@springbrand/agent-runtime 0.1.3-alpha.6 → 0.1.3-alpha.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.1.3-alpha.6",
+  "version": "0.1.3-alpha.7",
   "type": "module",
   "files": [
     "src",

package/src/kernel/bindings.ts

@@ -730,6 +730,22 @@ export interface RuntimeModelUsageEvent {
   };
 }
 
+/**
+ * 一次 Tool 调用刚开始，还不知道它会怎么结束。
+ *
+ * @remarks
+ * 结算事件刻意不带参数，因为它只用来记账；开始事件必须带，因为它唯一的用处
+ * 就是让 Host 立刻知道「正在写的是什么」——只有工具名的话，「write 开始了」
+ * 和「一个网页正在生成」之间的差别就丢了，而后者才是盯着屏幕的人要看的。
+ * 参数本来就随 Tool 输入里程碑落库，这里没有多暴露任何东西。
+ */
+export interface RuntimeToolStartEvent {
+  readonly submissionId: string;
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly args: unknown;
+}
+
 export interface RuntimeToolSettlementEvent {
   readonly eventId: string;
   readonly submissionId: string;
@@ -761,6 +777,17 @@ export interface RuntimeTurnEventsPort {
   ): Promise<void>;
   /** 投递 Assistant 或 Compaction 的原始 provider usage。 */
   onModelUsage?(event: RuntimeModelUsageEvent): Promise<void>;
+  /**
+   * 投递一次 Tool 开始执行的事件，带上它的参数。
+   *
+   * @remarks
+   * 只在这次调用第一次落下 durable intent 时投递：恢复重放不会再报一次开始，
+   * 否则一个早就结束的 Tool 会在几分钟后再宣布自己「正在跑」。
+   *
+   * 这条是活性信号而不是账，所以不进 durable outbox：迟到的开始事件本身就是
+   * 错的，投递失败就让它丢掉，最终状态由 `onToolSettled` 兜底。
+   */
+  onToolStart?(event: RuntimeToolStartEvent): Promise<void>;
   /** 投递不含参数与结果的 Tool 最终结算事件。 */
   onToolSettled?(event: RuntimeToolSettlementEvent): Promise<void>;
   onApproval?(input: {

package/src/runtime-assembler.ts

@@ -632,6 +632,7 @@ function hooksToTurnEventsPort<
   if (
     !hooks.onTurnEnd &&
     !hooks.onModelUsage &&
+    !hooks.onToolStart &&
     !hooks.onToolSettled &&
     !hooks.onApproval &&
     !hooks.onActivityChanged &&
@@ -644,6 +645,7 @@ function hooksToTurnEventsPort<
       ? (messages) => hooks.onTurnEnd!(ctx, messages)
       : async () => undefined,
     ...(hooks.onModelUsage ? { onModelUsage: hooks.onModelUsage } : {}),
+    ...(hooks.onToolStart ? { onToolStart: hooks.onToolStart } : {}),
     ...(hooks.onToolSettled ? { onToolSettled: hooks.onToolSettled } : {}),
     ...(hooks.onApproval ? { onApproval: hooks.onApproval } : {}),
     ...(hooks.onActivityChanged

package/src/runtime-definition.ts

@@ -6,6 +6,7 @@ import type {
   RuntimePlatformPort,
   RuntimeProviderPort,
   RuntimeSkillScriptPolicy,
+  RuntimeToolStartEvent,
   RuntimeTurnMessage,
 } from "./kernel/bindings";
 import type {
@@ -135,6 +136,7 @@ export interface RuntimeAgentHooks<
     messages: readonly RuntimeTurnMessage[],
   ) => Promise<void>;
   readonly onModelUsage?: (event: RuntimeModelUsageEvent) => Promise<void>;
+  readonly onToolStart?: (event: RuntimeToolStartEvent) => Promise<void>;
   readonly onToolSettled?: (event: RuntimeToolSettlementEvent) => Promise<void>;
   readonly onApproval?: (input: ApprovalHookInput) => Promise<void>;
   readonly onActivityChanged?: (

package/src/runtime.ts

@@ -1505,12 +1505,41 @@ export abstract class AgentRuntimeKernel<
       kind: "record-tool-input",
       record: input,
     });
-    return this.db.transaction(() =>
+    const appended = this.db.transaction(() =>
       this.applyPiRecoveryMutations(
         submission,
         decision.mutations,
       ),
     );
+    if (appended) this.announceToolStart(submission.submissionId, input);
+    return appended;
+  }
+
+  // 作用：把「这个 Tool 开始跑了」连同参数投给 Host。
+  // 调用：durable intent 第一次落库之后，Tool 真正执行之前。
+  // 原因：人在等的是「正在写一个网页」，不是三十秒后的「write 完成了」。
+  //
+  // 只在第一次落库时发：恢复重放会再走一遍这条路径，那时 Tool 可能早就结束了，
+  // 再宣布一次「开始」比不宣布更糟。也不进 durable outbox —— 这是活性信号，
+  // 补投一条迟到的开始事件没有意义，投失败就算了，终态有 onToolSettled 兜底。
+  private announceToolStart(
+    submissionId: string,
+    input: PiToolInputRecord,
+  ): void {
+    const turnEvents = this.turnEventsPort();
+    if (!turnEvents?.onToolStart) return;
+    const delivery = turnEvents.onToolStart({
+      submissionId,
+      toolCallId: input.toolCallId,
+      toolName: input.toolName,
+      args: input.input,
+    }).catch((error: unknown) => {
+      console.warn(
+        "[runtime-tool-start:degraded]",
+        json({ toolCallId: input.toolCallId, error: errorText(error) }),
+      );
+    });
+    this.ctx.waitUntil(delivery);
   }
 
   // 作用：持久化一次 Tool 结果，并推进相应的恢复里程碑。