@springbrand/agent-runtime 0.2.0-alpha.38 → 0.2.0-alpha.40

package/package.json

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

package/src/pi/runtime-adapter/assembly.ts

@@ -236,10 +236,10 @@ const IDEMPOTENT_TOOL_NAMES = new Set([
 export function piToolRetryPolicy(
   candidate: PiToolCandidate,
 ): "idempotent" | "non-idempotent" {
-  return IDEMPOTENT_TOOL_NAMES.has(candidate.tool.name) ||
+  return candidate.retry ?? (IDEMPOTENT_TOOL_NAMES.has(candidate.tool.name) ||
       candidate.owner.startsWith("subagent:")
     ? "idempotent"
-    : "non-idempotent";
+    : "non-idempotent");
 }
 
 // 把工具候选整理成版本描述里要保存的稳定字段。

package/src/pi/runtime-adapter/execution.ts

@@ -543,6 +543,25 @@ export interface CreatePreparedPiTurnOptions {
   readonly durability: PiTurnDurability;
   /** Reports paired model-generation lifecycle facts to the Runtime owner. */
   readonly onGeneration?: PiGenerationLifecycleObserver;
+  /** Reports Code Mode child Tool starts without adding Pi recovery state. */
+  readonly onNestedToolStarted?: (input: Readonly<{
+    parentToolCallId: string;
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    occurredAt: number;
+  }>) => void;
+  /** Reports Code Mode child Tool outcomes without adding Pi settlements. */
+  readonly onNestedToolFinished?: (input: Readonly<{
+    parentToolCallId: string;
+    toolCallId: string;
+    toolName: string;
+    outcome: "completed" | "failed" | "cancelled";
+    durationMs: number;
+    output?: import("@earendil-works/pi-agent-core").AgentToolResult<unknown>;
+    error?: unknown;
+    occurredAt: number;
+  }>) => void;
   /** Per-Submission executors for tools whose metadata is fixed at assembly time. */
   readonly toolExecutors?: Readonly<Record<
     string,
@@ -634,6 +653,7 @@ export class PreparedPiTurnAdapter {
   private readonly turn: PiTurnAdapter;
   private readonly abortController = new AbortController();
   private readonly candidates: readonly PiToolCandidate[];
+  private nestedToolOrdinal = 0;
   private assistantOrdinal: number;
   private readonly encoder: PiChunkEncoder;
   private readonly steerMessageIds: string[] = [];
@@ -805,12 +825,44 @@ export class PreparedPiTurnAdapter {
           }
           const execute = options.toolExecutors?.[candidate.tool.name] ??
             candidate.tool.execute;
-          return execute(
-            toolCallId,
+          if (recordRecoveryAttempt || !toolCallIdPrefix) {
+            return execute(toolCallId, input, signal, onUpdate);
+          }
+          const startedAt = Date.now();
+          const telemetryToolCallId = `${toolCallId}:${++this.nestedToolOrdinal}`;
+          options.onNestedToolStarted?.({
+            parentToolCallId: toolCallIdPrefix,
+            toolCallId: telemetryToolCallId,
+            toolName: candidate.tool.name,
             input,
-            signal,
-            onUpdate,
-          );
+            occurredAt: startedAt,
+          });
+          try {
+            const output = await execute(toolCallId, input, signal, onUpdate);
+            const occurredAt = Date.now();
+            options.onNestedToolFinished?.({
+              parentToolCallId: toolCallIdPrefix,
+              toolCallId: telemetryToolCallId,
+              toolName: candidate.tool.name,
+              outcome: "completed",
+              durationMs: occurredAt - startedAt,
+              output,
+              occurredAt,
+            });
+            return output;
+          } catch (error) {
+            const occurredAt = Date.now();
+            options.onNestedToolFinished?.({
+              parentToolCallId: toolCallIdPrefix,
+              toolCallId: telemetryToolCallId,
+              toolName: candidate.tool.name,
+              outcome: signal?.aborted ? "cancelled" : "failed",
+              durationMs: occurredAt - startedAt,
+              error,
+              occurredAt,
+            });
+            throw error;
+          }
         },
       },
     });

package/src/pi/tool/compiler.ts

@@ -66,6 +66,8 @@ export interface PiToolCandidate {
    * 那是失效不是降级。`deny` 仍然优先，被 deny 的工具根本不会注入。
    */
   readonly alwaysRequiresApproval?: boolean;
+  /** Recovery may replay this Tool Call only when the candidate guarantees convergence. */
+  readonly retry?: "idempotent" | "non-idempotent";
   readonly summary?: string;
   readonly source?: ApprovalReceipt["source"];
   readonly interaction?: PiToolInteractionSpec;

package/src/pi/tool/declared.ts

@@ -50,6 +50,7 @@ export interface PiDeclaredToolPolicy<Reply = unknown> {
   readonly requiredExecutionLevel: PiToolCandidate["requiredExecutionLevel"];
   readonly requiredExecutionLevelForInput?: PiToolCandidate["requiredExecutionLevelForInput"];
   readonly direct?: true;
+  readonly retry?: PiToolCandidate["retry"];
   readonly source?: PiToolCandidate["source"];
   readonly summary?: string;
   /**
@@ -116,6 +117,7 @@ export function createPiDeclaredToolCandidate<Reply = unknown>(
       ? { requiredExecutionLevelForInput: policy.requiredExecutionLevelForInput }
       : {}),
     ...(policy.direct ? { direct: policy.direct } : {}),
+    ...(policy.retry ? { retry: policy.retry } : {}),
     ...(policy.source ? { source: policy.source } : {}),
   };
 }

package/src/runtime.ts

@@ -975,6 +975,28 @@ export abstract class AgentRuntimeKernel<
           occurredAt: event.timestamp,
         });
       },
+      onNestedToolStarted: (event) => {
+        this.telemetry.capture("toolStarted", {
+          submissionId: submission.submissionId,
+          ...event,
+        });
+      },
+      onNestedToolFinished: (event) => {
+        this.telemetry.capture("toolFinished", {
+          submissionId: submission.submissionId,
+          parentToolCallId: event.parentToolCallId,
+          toolCallId: event.toolCallId,
+          toolName: event.toolName,
+          outcome: event.outcome,
+          durationMs: event.durationMs,
+          ...(event.output ? {
+            output: event.output,
+            outputBytes: json(event.output).length,
+          } : {}),
+          ...(event.error ? { error: errorText(event.error) } : {}),
+          occurredAt: event.occurredAt,
+        });
+      },
       ...(toolExecutors && Object.keys(toolExecutors).length > 0
         ? { toolExecutors }
         : {}),

package/src/telemetry/runtime-telemetry.ts

@@ -223,6 +223,7 @@ export class RuntimeTelemetry {
     submissionId: string;
     toolCallId: string;
     toolName: string;
+    parentToolCallId?: string;
     input?: unknown;
     occurredAt?: number;
   }>): TelemetryRecordResult {
@@ -235,10 +236,9 @@ export class RuntimeTelemetry {
       ...(input.input === undefined ? {} : { input: input.input as never }),
     }, {
       ...input,
-      parentOperationId: telemetryOperations.turn(
-        this.resource.sessionId,
-        input.submissionId,
-      ),
+      parentOperationId: input.parentToolCallId
+        ? telemetryOperations.tool(input.submissionId, input.parentToolCallId)
+        : telemetryOperations.turn(this.resource.sessionId, input.submissionId),
     });
   }
 
@@ -246,6 +246,7 @@ export class RuntimeTelemetry {
     submissionId: string;
     toolCallId: string;
     toolName: string;
+    parentToolCallId?: string;
     outcome: "completed" | "failed" | "cancelled";
     durationMs?: number;
     outputBytes?: number;
@@ -268,10 +269,9 @@ export class RuntimeTelemetry {
       ...(input.error ? { error: input.error } : {}),
     }, {
       ...input,
-      parentOperationId: telemetryOperations.turn(
-        this.resource.sessionId,
-        input.submissionId,
-      ),
+      parentOperationId: input.parentToolCallId
+        ? telemetryOperations.tool(input.submissionId, input.parentToolCallId)
+        : telemetryOperations.turn(this.resource.sessionId, input.submissionId),
     });
   }