@springbrand/agent-runtime 0.3.0-alpha.16 → 0.3.0-alpha.18

package/src/submission/repository.ts

@@ -1,5 +1,5 @@
 import type { SqlTaggedTemplate } from "agents/chat";
-import type { LaneSnapshot } from "@earendil-works/pi-agent-core";
+
 import type { ExecutionLevel } from "../lib/execution-level";
 import type { RuntimeUnattendedExecutionGrant } from "./unattended";
 
@@ -446,27 +446,6 @@ export class SubmissionRepository {
     `;
   }
 
-  /** Recover ownership from the matching Pi operation, using only its active branch. */
-  associateSessionEntries(
-    submissionId: string,
-    snapshot: Pick<LaneSnapshot, "operation" | "lastResult" | "tipId" | "transcript">,
-  ): void {
-    const boundary = snapshot.operation?.id === submissionId
-      ? { fromTipId: snapshot.operation.fromTipId, tipId: snapshot.tipId }
-      : snapshot.lastResult?.operationId === submissionId
-        ? snapshot.lastResult
-        : undefined;
-    if (!boundary) return;
-    const start = boundary.fromTipId === null
-      ? 0
-      : snapshot.transcript.findIndex(({ id }) => id === boundary.fromTipId) + 1;
-    const end = boundary.tipId === null
-      ? snapshot.transcript.length
-      : snapshot.transcript.findIndex(({ id }) => id === boundary.tipId) + 1;
-    for (const entry of snapshot.transcript.slice(start, end || undefined)) {
-      this.linkSessionEntry(entry.id, submissionId);
-    }
-  }
 
   listSessionEntrySubmissionLinks(): Map<string, string> {
     const rows = this.sql<{

package/src/submission/steer-delivery.ts

@@ -1,4 +1,5 @@
-import type { CancelQueuedResult, LaneSnapshot } from "@earendil-works/pi-agent-core";
+import type { SubmissionRecord } from "@earendil-works/pi-durable";
+export type CancelQueuedResult = { kind: "cancelled" | "already_consumed" | "not_found" };
 import type { UIMessage } from "ai";
 import type { ConversationHistory } from "../conversation/history";
 import type { SubmitMessageOptions } from "./admission";
@@ -12,7 +13,8 @@ interface PendingSteerDeliveryOptions {
   steers: SteerRepository;
   messageUi: MessageUiRepository;
   transaction<T>(run: () => T): T;
-  enqueue(message: PiCanonicalUserInput): Promise<string>;
+  enqueue(steer: PendingSteer): Promise<SubmissionRecord>;
+  find(messageId: string): Promise<SubmissionRecord | undefined>;
 }
 
 /** Reconciles Host steer receipts with Pi queue identities, without owning execution. */
@@ -20,66 +22,27 @@ export class PendingSteerDelivery {
   constructor(private readonly options: PendingSteerDeliveryOptions) {}
 
   async queue(steer: PendingSteer): Promise<void> {
-    const entryId = await this.options.enqueue(
-      JSON.parse(steer.canonicalJson) as PiCanonicalUserInput,
-    );
-    this.link(steer, entryId);
+    const record = await this.options.enqueue(steer);
+    this.options.transaction(() => this.options.steers.linkHarnessEntry(steer.messageId, String(record.id)));
+    this.settleRecord(record);
   }
-
-  /** Called after Pi commits the original queued user entry. */
-  settle(entryId: string): boolean {
-    const steer = this.options.steers.findByHarnessEntryId(entryId);
+  settleRecord(record: SubmissionRecord): boolean {
+    if (!record.requestId?.startsWith("steer:") || record.entry === undefined) return false;
+    const steer = this.options.steers.findByMessageId(record.requestId.slice(6));
     if (!steer) return false;
     this.options.transaction(() => {
-      this.persistSidecar(steer, entryId);
+      if (steer.uiMessageJson) this.options.messageUi.upsert(String(record.entry), steer.uiMessageJson);
       this.options.steers.deleteByMessageId(steer.messageId);
     });
     return true;
   }
-
-  async reconcile(
-    submissionId: string,
-    snapshot: Pick<LaneSnapshot, "queues" | "transcript">,
-  ): Promise<void> {
-    const pending = this.options.steers.listForSubmission(submissionId);
-    const queuedIds = new Set(snapshot.queues.map(({ entryId }) => entryId));
-    const transcriptIds = new Set(snapshot.transcript.map(({ id }) => id));
-    const linkedIds = new Set(pending.flatMap(({ harnessEntryId }) =>
-      harnessEntryId ? [harnessEntryId] : []
-    ));
-    const unlinked = snapshot.queues.filter((entry) =>
-      entry.kind === "steer" && entry.type === "message" &&
-      !linkedIds.has(entry.entryId)
-    );
-    // Both durable queues preserve acceptance order; identical text is not identity.
-    for (const steer of pending) {
-      if (steer.harnessEntryId && transcriptIds.has(steer.harnessEntryId)) {
-        this.settle(steer.harnessEntryId);
-      } else if (steer.harnessEntryId && queuedIds.has(steer.harnessEntryId)) {
-        this.options.transaction(() =>
-          this.persistSidecar(steer, steer.harnessEntryId!)
-        );
-      } else {
-        const queued = !steer.harnessEntryId ? unlinked.shift() : undefined;
-        if (queued) this.link(steer, queued.entryId);
-        else await this.queue(steer);
-      }
-    }
-  }
-
-  private link(steer: PendingSteer, entryId: string): void {
-    this.options.transaction(() => {
-      if (steer.harnessEntryId && steer.harnessEntryId !== entryId) {
-        this.options.messageUi.delete(steer.harnessEntryId);
-      }
-      this.options.steers.linkHarnessEntry(steer.messageId, entryId);
-      this.persistSidecar(steer, entryId);
-    });
-  }
-
-  private persistSidecar(steer: PendingSteer, entryId: string): void {
-    if (steer.uiMessageJson) {
-      this.options.messageUi.upsert(entryId, steer.uiMessageJson);
+  async reconcile(submissionId: string): Promise<void> {
+    for (const steer of this.options.steers.listForSubmission(submissionId)) {
+      const existing = await this.options.find(steer.messageId);
+      if (existing) {
+        this.options.transaction(() => this.options.steers.linkHarnessEntry(steer.messageId, String(existing.id)));
+        this.settleRecord(existing);
+      } else await this.queue(steer);
     }
   }
 }
@@ -109,20 +72,18 @@ export async function finishPendingSteers(options: {
       : undefined;
     const requestId = `${options.submissionId}:steer:${steer.steerId}`;
     if (options.aborted) {
-      options.transaction(() => {
+      const owner = options.transaction(() => {
         let handoff = options.submissions.findByRequestId(requestId);
         if (handoff?.status === "pending") {
           const reason = submissionAbortReason(options.submissions.find(options.submissionId)) ?? "Cancelled";
           options.submissions.updateAbortReason(handoff.submissionId, reason);
           handoff = options.cancelHandoff(handoff.submissionId, reason);
         }
+        return handoff?.status === "aborted" || handoff?.status === "skipped" ? handoff.submissionId : options.submissionId;
+      });
+      await options.conversation.append(steer.messageId, message, { submissionId: owner, ...(userMessage ? { userMessage } : {}) });
+      options.transaction(() => {
         if (steer.harnessEntryId) options.messageUi.delete(steer.harnessEntryId);
-        options.conversation.append(steer.messageId, message, {
-          submissionId: handoff?.status === "aborted" || handoff?.status === "skipped"
-            ? handoff.submissionId
-            : options.submissionId,
-          ...(userMessage ? { userMessage } : {}),
-        });
         options.steers.deleteByMessageId(steer.messageId);
       });
       continue;
@@ -130,8 +91,7 @@ export async function finishPendingSteers(options: {
     if (steer.harnessEntryId) {
       const cancelled = await options.cancelQueued(steer.harnessEntryId);
       if (cancelled) {
-        if (!cancelled.ok) throw cancelled.error;
-        if (cancelled.value.kind === "already_consumed") {
+        if (cancelled.kind === "already_consumed") {
           options.transaction(() => options.steers.deleteByMessageId(steer.messageId));
           continue;
         }
@@ -148,20 +108,16 @@ export async function finishPendingSteers(options: {
       ...(userMessage ? { userMessage } : {}),
     });
     options.waitUntil(submitted.completion);
-    options.transaction(() => {
-      let handoff = options.submissions.find(submitted.receipt.submissionId) ?? submitted.receipt;
+    const handoff = options.transaction(() => {
+      let current = options.submissions.find(submitted.receipt.submissionId) ?? submitted.receipt;
       const abortReason = submissionAbortReason(options.submissions.find(options.submissionId));
-      if (abortReason && handoff.status === "pending" && handoff.requestId === requestId) {
-        options.submissions.updateAbortReason(handoff.submissionId, abortReason);
-        handoff = options.cancelHandoff(handoff.submissionId, abortReason);
-      }
-      if (handoff.status === "skipped" || handoff.status === "aborted") {
-        options.conversation.append(steer.messageId, message, {
-          submissionId: handoff.submissionId,
-          ...(userMessage ? { userMessage } : {}),
-        });
+      if (abortReason && current.status === "pending" && current.requestId === requestId) {
+        options.submissions.updateAbortReason(current.submissionId, abortReason);
+        current = options.cancelHandoff(current.submissionId, abortReason);
       }
-      options.steers.deleteByMessageId(steer.messageId);
+      return current;
     });
+    if (handoff.status === "skipped" || handoff.status === "aborted") await options.conversation.append(steer.messageId, message, { submissionId: handoff.submissionId, ...(userMessage ? { userMessage } : {}) });
+    options.transaction(() => options.steers.deleteByMessageId(steer.messageId));
   }
 }

package/src/telemetry/turn-events.ts

@@ -1,4 +1,6 @@
-import type { AgentHarness, Entry } from "@earendil-works/pi-agent-core";
+import type { SessionHarness } from "../harness/session-harness";
+import { projectSessionEntry, type ProjectedSessionEntry as Entry } from "../conversation/session-entry";
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import type {
   RuntimeLifecycleFact,
   RuntimeModelUsageEvent,
@@ -87,10 +89,22 @@ export class RuntimeTurnEvents {
     } }, submission.completedAt ?? Date.now());
   }
 
+  /** Pi summarizes through completeSimple; account only its successful, measured response. */
+  compactionGeneration(submissionId: string, event: import("../models").PiGenerationLifecycleEvent): void {
+    if (event.type !== "finished" || event.outcome !== "success" || !event.output || event.output.stopReason === "error" || event.output.stopReason === "aborted") return;
+    const response = event.output;
+    this.save({ type: "model-usage", event: {
+      eventId: `${submissionId}:compaction:${event.generationId}`, submissionId, runId: submissionId,
+      kind: "compaction", api: response.api, provider: response.provider, model: response.model,
+      ...(response.responseModel ? { responseModel: response.responseModel } : {}), usage: response.usage,
+    } }, event.timestamp);
+    this.options.waitUntil(this.drain());
+  }
+
   private recordEntry(submissionId: string, entry: Entry, model: RequestedModel): void {
     if (entry.type === "message" && entry.message.role === "assistant") {
       this.save({ type: "model-usage", event: {
-        eventId: `${submissionId}:model:${entry.id}`,
+        eventId: `${submissionId}:model:${entry.identity}`,
         submissionId,
         runId: submissionId,
         kind: "assistant",
@@ -107,7 +121,7 @@ export class RuntimeTurnEvents {
     } else if (entry.type === "compaction" || entry.type === "branch_summary") {
       if (entry.usage) {
         this.save({ type: "model-usage", event: {
-          eventId: `${submissionId}:compaction:${entry.id}`,
+          eventId: `${submissionId}:compaction:${entry.identity}`,
           submissionId,
           runId: submissionId,
           kind: "compaction",
@@ -131,28 +145,24 @@ export class RuntimeTurnEvents {
   }
 
   /** Live observation and recovery use exactly the same committed-entry projection. */
-  observe(harness: Pick<AgentHarness, "events">, submissionId: string, model: RequestedModel): void {
-    harness.events.on("entry_added", ({ entry }) => {
-      this.recordEntry(submissionId, entry, model);
-      this.options.waitUntil(this.drain());
-    });
-    harness.events.on("tool_start", (event) => {
-      this.options.telemetry.capture("toolStarted", {
-        submissionId,
-        toolCallId: event.toolCallId,
-        toolName: event.toolName,
-        input: event.args,
-      });
+  async observe(runtime: SessionHarness, submissionId: string, model: RequestedModel): Promise<void> {
+    runtime.harness.subscribeCommits((publication) => {
+      for (const change of publication.changes) {
+        if (change.type === "entry" && change.value.conversationId === runtime.conversation.id) {
+          this.recordEntry(submissionId, projectSessionEntry(change.value), model);
+          this.options.waitUntil(this.drain());
+        }
+      }
     });
-    harness.events.on("tool_end", (event) => {
-      this.options.telemetry.capture("toolFinished", {
-        submissionId,
-        toolCallId: event.toolCallId,
-        toolName: event.toolName,
-        outcome: event.isError ? "failed" : "completed",
-        output: event.result,
-        outputBytes: JSON.stringify(event.result).length,
-      });
+    const watch = await runtime.watch(BACKGROUND_CONTEXT);
+    watch.start(async (events) => {
+      for (const event of events) {
+        if (event.type === "tool_execution_start") this.options.telemetry.capture("toolStarted", { submissionId, toolCallId: event.toolCallId, toolName: event.toolName, input: event.args });
+        if (event.type === "tool_execution_end") {
+          const result = event.entry?.model?.[0];
+          this.options.telemetry.capture("toolFinished", { submissionId, toolCallId: event.toolCallId, toolName: event.toolName, outcome: result?.role === "toolResult" && !result.isError ? "completed" : "failed", output: result, outputBytes: JSON.stringify(result ?? {}).length });
+        }
+      }
     });
   }
 

package/src/tools/runtime/compiler.ts

@@ -1,4 +1,6 @@
-import type { AgentHarnessTool, AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ToolRegistration } from "@earendil-works/pi-durable";
+import { awaitWithContext } from "@earendil-works/chord/context";
 import { boundDurableToolOutput, spillDurableToolOutput } from "../../context/memory/budget/gate";
 import { artifactId, serializeOutput, sha256Hex, type ArtifactRef, type SpillWorkspace } from "../../lib/artifacts";
 import type { CompileHarnessToolsOptions, PiToolCandidate } from "./contracts";
@@ -134,29 +136,6 @@ async function durableResult(
   );
 }
 
-async function untilAborted<T>(
-  signal: AbortSignal | undefined,
-  run: () => T | Promise<T>,
-): Promise<T> {
-  // ponytail: 这会立即释放 Turn，但无法杀死不配合的进程内副作用；需要物理终止的 Tool 必须放进可销毁的隔离执行器。
-  signal?.throwIfAborted();
-  if (!signal) return run();
-  let onAbort!: () => void;
-  const aborted = new Promise<never>((_resolve, reject) => {
-    onAbort = () => reject(
-      signal.reason ?? new DOMException("Aborted", "AbortError"),
-    );
-    signal.addEventListener("abort", onAbort, { once: true });
-  });
-  try {
-    return await Promise.race([run(), aborted]);
-  } finally {
-    signal.removeEventListener("abort", onAbort);
-  }
-}
-
-
-
 /**
  * Convert the configured candidate surface once at the AgentHarness boundary.
  * Schema, argument preparation, progress, cancellation, replay classification,
@@ -165,7 +144,7 @@ async function untilAborted<T>(
 export function compileHarnessTools(
   candidates: readonly PiToolCandidate[],
   options: CompileHarnessToolsOptions = {},
-): AgentHarnessTool<object | undefined>[] {
+): ToolRegistration<any, any>[] {
   return candidates.map((candidate) => {
     const source = candidate.tool;
     const tool = source.constrainedSampling === false
@@ -185,16 +164,21 @@ export function compileHarnessTools(
         !candidate.requiredExecutionLevelForInput &&
         !candidate.interaction
         ? "safe" as const
-        : "never" as const,
+        : "unsafe" as const,
       ...(candidate.deferLoading ? { deferLoading: true as const } : {}),
-      async execute(
-        toolCallId,
-        args,
-        onUpdate,
-        _toolContext,
-        _invocation,
-        context,
-      ) {
+      async execute(args, api, context) {
+        const toolCallId = api.callId;
+        // AgentTool progress is a replacing snapshot (web_search sends its accumulated text), but Pi output only
+        // appends and has no replace operation: append a grown snapshot's suffix, and start a new line otherwise.
+        let shown = "";
+        const onUpdate = (update: AgentToolResult<unknown>) => {
+          const text = update.content.flatMap((part) => part.type === "text" ? [part.text] : []).join("");
+          if (text && text !== shown) {
+            api.output(text.startsWith(shown) ? text.slice(shown.length) : shown ? `\n${text}` : text);
+            shown = text;
+          }
+          if (update.details !== undefined) void api.details(update.details, context).catch(() => {});
+        };
         const signal = context.abortSignal ?? new AbortController().signal;
         let result: AgentToolResult<unknown>;
         try {
@@ -208,19 +192,17 @@ export function compileHarnessTools(
             args,
           );
           if (replay) return durableResult(replay, candidate, options.workspace);
-          result = await untilAborted(
-            signal,
-            async () => durableResult(
-              await (candidate.confirmation
-                ? (() => {
-                  const confirmed = options.resolveConfirmation?.(candidate, toolCallId, args);
-                  if (!confirmed) throw new Error("User confirmation is required");
-                  return candidate.confirmation.execute(confirmed.prepared, { intentId: confirmed.intentId, signal });
-                })()
-                : source.execute(toolCallId, args, signal, (update) => onUpdate(update))),
-              candidate,
-              options.workspace,
-            ),
+          signal.throwIfAborted();
+          const execution = candidate.confirmation
+            ? (() => {
+              const confirmed = options.resolveConfirmation?.(candidate, toolCallId, args);
+              if (!confirmed) throw new Error("User confirmation is required");
+              return candidate.confirmation.execute(confirmed.prepared, { intentId: confirmed.intentId, signal });
+            })()
+            : source.execute(toolCallId, args, signal, (update) => onUpdate(update));
+          result = await awaitWithContext(
+            Promise.resolve(execution).then((result) => durableResult(result, candidate, options.workspace)),
+            context,
           );
         } catch (cause) {
           const message = errorMessage(cause);
@@ -239,7 +221,7 @@ export function compileHarnessTools(
             source: candidate.source,
           });
           if (cause instanceof UnattendedExecutionError) {
-            return { ...failed, terminate: true };
+            return { ...failed, isError: true, control: { terminate: true as const } };
           }
           throw cause instanceof Error && cause.message === message
             ? cause
@@ -257,8 +239,8 @@ export function compileHarnessTools(
           summary: candidate.summary,
           source: candidate.source,
         });
-        return result;
+        return { ...result, ...(result.terminate ? { control: { terminate: true as const } } : {}) };
       },
-    } satisfies AgentHarnessTool<object | undefined>;
+    } satisfies ToolRegistration<any, any>;
   });
 }

package/src/tools/runtime/decision-gate.ts

@@ -1,4 +1,4 @@
-import type { AgentToolResult, HookHandler } from "@earendil-works/pi-agent-core";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { ExecutionLevel } from "../../lib/execution-level";
 import {
   EXECUTION_LEVELS,
@@ -86,7 +86,7 @@ export class HarnessDecisionGate {
     );
   }
 
-  readonly beforeTool: HookHandler<"before_tool"> = async (event, context) => {
+  readonly beforeTool = async (event: { toolName: string; toolCallId: string; args: unknown }, context: import("@earendil-works/chord").Context): Promise<{ block: string } | undefined> => {
     const candidate = this.candidates.get(event.toolName);
     if (!candidate) return undefined;
     let requiredExecutionLevel: ExecutionLevel;
@@ -94,7 +94,7 @@ export class HarnessDecisionGate {
       requiredExecutionLevel = await this.resolveExecutionLevel(candidate, event.args);
     } catch (error) {
       if (!(error instanceof UnattendedExecutionError)) throw error;
-      return { block: { reason: error.message, terminate: true } };
+      return { block: error.message };
     }
     const effectiveLevel = this.effectiveExecutionLevel();
     const needsApproval = candidate.alwaysRequiresApproval ||
@@ -108,7 +108,7 @@ export class HarnessDecisionGate {
       }, requiredExecutionLevel);
     } catch (error) {
       if (!(error instanceof UnattendedExecutionError)) throw error;
-      return { block: { reason: error.message, terminate: true } };
+      return { block: error.message };
     }
     const existing = this.options.approvals.find(executionId);
     if (existing && (existing.requestId !== this.options.submission.requestId ||
@@ -116,7 +116,7 @@ export class HarnessDecisionGate {
       throw new Error(`Conflicting durable Tool approval: ${event.toolCallId}`);
     }
     if (existing?.status === "rejected") {
-      return { block: { reason: existing.reason ?? "Tool execution denied by user" } };
+      return { block: existing.reason ?? "Tool execution denied by user" };
     }
     if (needsApproval && !unattendedAuthorized && existing?.status !== "approved") {
       if (!existing) {