@springbrand/agent-runtime 0.3.0-alpha.2 → 0.3.0-alpha.20

package/src/submission/contracts.ts

@@ -13,6 +13,8 @@ export const APPROVAL_DECISIONS = [
   "allow_level",
 ] as const satisfies readonly ApprovalDecision["decision"][];
 
+export type { RuntimeUnattendedExecutionGrant } from "./unattended";
+
 /**
  * 记录一次待审批 Tool 执行的身份、摘要和原始输入。
  *
@@ -58,12 +60,35 @@ export type ScheduleJob =
  *
  * 触发条件与工作放在同一份规格里，使更新时可以原地替换两者，不用改变任务标识。
  */
+/**
+ * 一条按任务时区解释的当地时间规则。
+ *
+ * @remarks
+ * `once` 在单个本地日历日触发;`daily` 每个本地日触发;`weekly` 在选中的每个本地星期触发
+ * (0 = 周日 … 6 = 周六)。所有星期共用同一个本地钟点。
+ *
+ * 规则只描述当地墙上时间;缺失/重复钟点、起止日期和夏令时语义由
+ * `adapter/cloudflare/scheduling` 的公共计算边界处理。
+ */
+export type LocalScheduleRule =
+  | { kind: "once"; date: string; time: string }
+  | { kind: "daily"; time: string }
+  | { kind: "weekly"; weekdays: number[]; time: string };
+
 export interface ScheduleSpec {
   trigger:
     | { kind: "once-at"; at: string }
     | { kind: "once-in"; seconds: number }
     | { kind: "cron"; cron: string }
-    | { kind: "interval"; seconds: number };
+    | { kind: "interval"; seconds: number }
+    | {
+        kind: "local";
+        rule: LocalScheduleRule;
+        /** 含当天的最早生效本地日期 `YYYY-MM-DD`。 */
+        startDate?: string;
+        /** 含当天的最后生效本地日期 `YYYY-MM-DD`。 */
+        endDate?: string;
+      };
   job: ScheduleJob;
   label?: string;
   /**
@@ -115,7 +140,9 @@ export type MessageDelivery = "steer" | "enqueue";
 export type MessageDispatchErrorCode =
   | "queue_full"
   | "not_steerable"
-  | "invalid_message";
+  | "invalid_message"
+  /** A scheduled Run owns this Session's input until it reaches a terminal state. */
+  | "input_locked";
 
 export type MessageDispatchReceipt =
   | {
@@ -139,3 +166,16 @@ export type MessageDispatchReceipt =
       code: MessageDispatchErrorCode;
       message: string;
     };
+
+/** Complete, credential-free task version prepared by a trusted Host for human confirmation. */
+export interface RuntimeSchedulePreparation {
+  candidateId: string;
+  candidateVersion: string;
+  id?: string;
+  prompt: string;
+  label: string;
+  trigger: ScheduleSpec["trigger"];
+  timezone: string;
+  nextRunAt?: number;
+  authorization: { version: string; missing: string[]; scope: string };
+}

package/src/submission/delivery.ts

@@ -2,7 +2,7 @@ import type { UIMessage } from "ai";
 import type { PiCanonicalUserInput } from "../conversation/message/contract";
 import type { RuntimeTelemetryCoordinator } from "../telemetry/coordinator";
 import type { RuntimeTurnEvents } from "../telemetry/turn-events";
-import type { HarnessHumanDecisions } from "../tools/human-decisions";
+import type { HarnessHumanDecisions } from "../tools/runtime/human-decisions";
 import type { SubmitMessageOptions } from "./admission";
 import {
   projectSubmissionReceipt,

package/src/submission/finalization.ts

@@ -1,10 +1,10 @@
 import type { AssistantMessage } from "@earendil-works/pi-ai";
-import type { CancelQueuedResult } from "@earendil-works/pi-agent-core";
+import type { CancelQueuedResult } from "./steer-delivery";
 import type { ConversationHistory } from "../conversation/history";
 import type { MessageUiRepository } from "../conversation/repository";
 import type { RuntimeTelemetryCoordinator } from "../telemetry/coordinator";
 import type { RuntimeTurnEvents } from "../telemetry/turn-events";
-import type { HarnessHumanDecisions } from "../tools/human-decisions";
+import type { HarnessHumanDecisions } from "../tools/runtime/human-decisions";
 import { USER_STOP_REASON } from "./contracts";
 import type { SubmissionOutcome } from "./lifecycle";
 import { isTerminalSubmissionStatus, type StoredSubmission, type SubmissionRepository } from "./repository";
@@ -13,6 +13,8 @@ import type { SteerRepository } from "./steer-repository";
 
 /** Commits the Submission outcome and human/Host facts after accepted steering is preserved. */
 export class SubmissionFinalizer {
+  /** User-stop markers appended after their terminal commit; every `finish()` of that Turn awaits it. */
+  private readonly stopMarkers = new Map<string, Promise<unknown>>();
   constructor(private readonly options: {
     submissions: SubmissionRepository;
     steers: SteerRepository;
@@ -34,7 +36,12 @@ export class SubmissionFinalizer {
     message?: string,
   ): Promise<StoredSubmission> {
     const initial = this.read(submissionId);
-    if (isTerminalSubmissionStatus(initial.status)) return initial;
+    if (isTerminalSubmissionStatus(initial.status)) {
+      // A stop RPC and the ending harness finish the same Turn; whichever loses
+      // still waits for the stop marker, so its history broadcast carries it.
+      await this.stopMarkers.get(submissionId);
+      return initial;
+    }
     const aborted = Boolean(initial.abortReason) || outcome === "aborted";
     if (aborted) await this.options.releaseAbortedHarness();
     await finishPendingSteers({
@@ -53,7 +60,13 @@ export class SubmissionFinalizer {
     const output = (await this.options.conversation.storedMessages())
       .filter((entry) => entry.submissionId === submissionId && entry.message.role === "assistant")
       .at(-1)?.message;
-    return this.commit(submissionId, outcome, message, output?.role === "assistant" ? output : undefined);
+    const completed = this.commit(submissionId, outcome, message, output?.role === "assistant" ? output : undefined);
+    const marker = this.stopMarkers.get(submissionId);
+    if (marker) {
+      await marker;
+      this.stopMarkers.delete(submissionId);
+    }
+    return completed;
   }
 
   /** Shares atomic terminal facts with an admitted handoff cancelled before execution. */
@@ -63,7 +76,8 @@ export class SubmissionFinalizer {
     message?: string,
     output?: AssistantMessage,
   ): StoredSubmission {
-    return this.options.transaction(() => {
+    let stoppedByUser = false;
+    const completed = this.options.transaction(() => {
       // Host admission and history reads can await while an explicit stop wins.
       const latest = this.read(submissionId);
       if (isTerminalSubmissionStatus(latest.status)) return latest;
@@ -79,16 +93,9 @@ export class SubmissionFinalizer {
       const status = effectiveOutcome === "succeeded" ? "completed" : effectiveOutcome === "aborted" ? "aborted" : "error";
       this.options.submissions.updateTerminal(submissionId, status, reason, Date.now());
       const completed = this.read(submissionId);
-      if (effectiveOutcome === "aborted" && reason === USER_STOP_REASON) {
-        if (completed.completedAt === null) {
-          throw new Error(
-            `Aborted SpringBrand submission has no completion time: ${submissionId}`,
-          );
-        }
-        this.options.conversation.appendTurnAbortedMarker(
-          submissionId,
-          completed.completedAt,
-        );
+      stoppedByUser = effectiveOutcome === "aborted" && reason === USER_STOP_REASON;
+      if (stoppedByUser && completed.completedAt === null) {
+        throw new Error(`Aborted SpringBrand submission has no completion time: ${submissionId}`);
       }
       this.options.events.submissionTerminal(completed);
       this.options.telemetry.capture("turnFinished", {
@@ -101,6 +108,20 @@ export class SubmissionFinalizer {
       });
       return completed;
     });
+    if (stoppedByUser) this.appendStopMarker(submissionId, completed.completedAt!);
+    return completed;
+  }
+
+  /**
+   * The browser projects `interruptedByUser` from this marker and the next model request sees it as user context.
+   * Pi history writes are async, so the marker follows the synchronous terminal commit.
+   */
+  private appendStopMarker(submissionId: string, completedAt: number): void {
+    const marker = this.options.conversation.appendTurnAbortedMarker(submissionId, completedAt).catch((error: unknown) => {
+      console.warn("[runtime-stop-marker:failed]", submissionId, error instanceof Error ? error.message : String(error));
+    });
+    this.stopMarkers.set(submissionId, marker);
+    this.options.waitUntil(marker);
   }
 
   private read(submissionId: string): StoredSubmission {

package/src/submission/repository.ts

@@ -1,5 +1,7 @@
 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";
 
 // Submission 的统一定义见 ./index.ts。
 // #region 状态与行类型
@@ -11,6 +13,14 @@ export type SubmissionStatus =
   | "skipped"
   | "error";
 
+/**
+ * 谁发起了这条 Submission。
+ *
+ * `scheduled` 是定时 Run 的注入:它在本 Session 未结束期间独占输入,
+ * 普通 `user` Submission 必须被拒绝,而不是排队等它结束。
+ */
+export type SubmissionOrigin = "user" | "scheduled";
+
 const TERMINAL_SUBMISSION_STATUSES: ReadonlySet<SubmissionStatus> = new Set([
   "completed",
   "aborted",
@@ -46,6 +56,10 @@ export interface StoredSubmission {
   userMessageId: string | null;
   regenerateMessageId: string | null;
   runId: string | null;
+  origin: SubmissionOrigin;
+  scheduledMaxExecutionLevel: ExecutionLevel | null;
+  unattendedExecutionGrant: RuntimeUnattendedExecutionGrant | null;
+  unattendedFailure: string | null;
   retryable?: boolean;
 }
 
@@ -69,6 +83,9 @@ export interface NewSubmission {
   userMessageId?: string | null;
   regenerateMessageId?: string | null;
   runId?: string | null;
+  origin?: SubmissionOrigin;
+  scheduledMaxExecutionLevel?: ExecutionLevel;
+  unattendedExecutionGrant?: RuntimeUnattendedExecutionGrant;
 }
 
 type SubmissionRow = {
@@ -90,7 +107,11 @@ type SubmissionRow = {
   user_message_id: string | null;
   regenerate_message_id: string | null;
   run_id: string | null;
+  origin: string | null;
+  scheduled_max_execution_level: string | null;
   admission_retryable: number | null;
+  unattended_execution_grant_json: string | null;
+  unattended_failure: string | null;
 };
 
 // #endregion
@@ -118,6 +139,12 @@ function mapRow(row: SubmissionRow): StoredSubmission {
     userMessageId: row.user_message_id,
     regenerateMessageId: row.regenerate_message_id,
     runId: row.run_id,
+    origin: row.origin === "scheduled" ? "scheduled" : "user",
+    scheduledMaxExecutionLevel: row.scheduled_max_execution_level as ExecutionLevel | null,
+    unattendedExecutionGrant: row.unattended_execution_grant_json
+      ? JSON.parse(row.unattended_execution_grant_json) as RuntimeUnattendedExecutionGrant
+      : null,
+    unattendedFailure: row.unattended_failure,
     retryable: row.admission_retryable === null
       ? undefined
       : row.admission_retryable === 1,
@@ -150,7 +177,11 @@ export class SubmissionRepository {
              queued_input_json, queued_ui_message_json, user_message_id,
              regenerate_message_id,
              run_id,
-             admission_retryable
+             origin,
+             scheduled_max_execution_level,
+             admission_retryable,
+             unattended_execution_grant_json,
+             unattended_failure
       FROM pi_submissions
       WHERE submission_id = ${id}
     `[0];
@@ -251,7 +282,7 @@ export class SubmissionRepository {
         created_at, assembly_revision, assembly_descriptor, runtime_key,
         assistant_message_id, queued_input_json, queued_ui_message_json,
         user_message_id, regenerate_message_id,
-        run_id
+        run_id, origin, scheduled_max_execution_level, unattended_execution_grant_json
       ) VALUES (
         ${s.submissionId},
         ${s.requestId},
@@ -267,11 +298,31 @@ export class SubmissionRepository {
         ${s.queuedUiMessageJson ?? null},
         ${s.userMessageId ?? null},
         ${s.regenerateMessageId ?? null},
-        ${s.runId ?? s.submissionId}
+        ${s.runId ?? s.submissionId},
+        ${s.origin ?? "user"},
+        ${s.scheduledMaxExecutionLevel ?? null},
+        ${s.unattendedExecutionGrant
+          ? JSON.stringify(s.unattendedExecutionGrant)
+          : null}
       )
     `;
   }
 
+  /**
+   * 是否存在一条未结束的定时 Submission。
+   *
+   * 定时 Run 未结束时它独占本 Session 的输入:普通消息在准入前被拒绝,
+   * 不排队等待。Run 进入终态后查询自然为空,普通追问恢复。
+   */
+  hasUnfinishedScheduled(): boolean {
+    return (
+      this.sql<{ count: number }>`
+        SELECT COUNT(*) AS count FROM pi_submissions
+        WHERE status IN ('pending', 'running') AND origin = 'scheduled'
+      `[0]?.count ?? 0
+    ) > 0;
+  }
+
   insertRejected(s: {
     submissionId: string;
     requestId: string;
@@ -310,6 +361,15 @@ export class SubmissionRepository {
     return updated.length === 1;
   }
 
+  recordUnattendedFailure(id: string, reason: string): void {
+    this.sql`
+      UPDATE pi_submissions
+      SET unattended_failure = COALESCE(unattended_failure, ${reason})
+      WHERE submission_id = ${id}
+        AND status IN ('pending', 'running')
+    `;
+  }
+
   // 只在当前状态属于 from 时把 Submission 切换到 to，否则返回 false。
   // SubmissionLifecycle 开始 Turn 时调用，调用方用返回值识别过期或重复的状态切换。
   // Cloudflare SQLite 查询是同步的，两条语句之间不会让其他事件交错；UPDATE 再次带旧状态条件，不能去掉这层幂等保护。
@@ -386,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/submission/unattended.ts

@@ -0,0 +1,40 @@
+/** Host-confirmed authority pinned to one scheduled task Requirement version.
+ * Credentials never belong in scope; only trusted Host ports consume it.
+ */
+export interface RuntimeUnattendedExecutionGrant {
+  readonly taskId: string;
+  readonly requirementVersion: string;
+  readonly authorizationVersion: string;
+  readonly scope: Readonly<Record<string, unknown>>;
+}
+
+export function pinnedUnattendedExecutionGrant(
+  value: RuntimeUnattendedExecutionGrant,
+): RuntimeUnattendedExecutionGrant {
+  for (const [name, version] of [
+    ["task ID", value.taskId],
+    ["Requirement", value.requirementVersion],
+    ["authorization", value.authorizationVersion],
+  ] as const) {
+    if (typeof version !== "string" || !version.trim()) {
+      throw new Error(`Unattended execution ${name} is required`);
+    }
+  }
+  if (!value.scope || typeof value.scope !== "object" || Array.isArray(value.scope)) {
+    throw new Error("Unattended execution scope must be an object");
+  }
+  try {
+    const scope = JSON.parse(JSON.stringify(value.scope)) as unknown;
+    if (!scope || typeof scope !== "object" || Array.isArray(scope)) {
+      throw new Error("scope changed shape during serialization");
+    }
+    return Object.freeze({
+      taskId: value.taskId,
+      requirementVersion: value.requirementVersion,
+      authorizationVersion: value.authorizationVersion,
+      scope: scope as Readonly<Record<string, unknown>>,
+    });
+  } catch (error) {
+    throw new Error("Unattended execution scope must be JSON-serializable", { cause: error });
+  }
+}

package/src/telemetry/coordinator.ts

@@ -5,7 +5,7 @@ import { TelemetryRecorder } from "./recorder";
 import { RuntimeTelemetry } from "./runtime-telemetry";
 import type { AgentTelemetryBinding } from "./contract";
 import type { PiGenerationLifecycleEvent } from "../models";
-import type { TemporaryAgentLifecycleEvent } from "../tools/temporary-agent/coordinator";
+import type { TemporaryAgentLifecycleEvent } from "../tools/subagent/temporary/coordinator";
 
 const TELEMETRY_COLD_BUFFER_LIMIT = 1_000;
 

package/src/telemetry/subagent-lifecycle.ts

@@ -2,7 +2,7 @@ import type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
   RuntimeSubagentUsageEvent,
-} from "../tools/subagent-authority";
+} from "../tools/subagent/authority";
 
 export interface RuntimeLifecycleSink {
   save(

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,
@@ -7,7 +9,7 @@ import type {
   RuntimeTurnEventsPort,
 } from "../config/ports";
 import type { StoredSubmission } from "../submission/repository";
-import { decodeSubagentCompletion, isZeroSubagentUsage, subagentTerminalStatus, type RuntimeSubagentRunMetadata } from "../tools/subagent-runtime";
+import { decodeSubagentCompletion, isZeroSubagentUsage, subagentTerminalStatus, type RuntimeSubagentRunMetadata } from "../tools/subagent/runtime";
 import type { RuntimeTelemetryCoordinator } from "./coordinator";
 import { summarizeModelUsage } from "./model-usage";
 import type { RuntimeEventOutboxRepository } from "./runtime-event-repository";
@@ -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 });
+        }
+      }
     });
   }