@springbrand/agent-runtime 0.2.0-alpha.72 → 0.3.0-alpha.10

package/src/submission/steer-delivery.ts

@@ -0,0 +1,167 @@
+import type { CancelQueuedResult, LaneSnapshot } from "@earendil-works/pi-agent-core";
+import type { UIMessage } from "ai";
+import type { ConversationHistory } from "../conversation/history";
+import type { SubmitMessageOptions } from "./admission";
+import type { SubmissionHandle } from "./lifecycle";
+import { submissionAbortReason, type StoredSubmission, type SubmissionRepository } from "./repository";
+import type { PiCanonicalUserInput } from "../conversation/message/contract";
+import type { MessageUiRepository } from "../conversation/repository";
+import type { PendingSteer, SteerRepository } from "./steer-repository";
+
+interface PendingSteerDeliveryOptions {
+  steers: SteerRepository;
+  messageUi: MessageUiRepository;
+  transaction<T>(run: () => T): T;
+  enqueue(message: PiCanonicalUserInput): Promise<string>;
+}
+
+/** Reconciles Host steer receipts with Pi queue identities, without owning execution. */
+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);
+  }
+
+  /** Called after Pi commits the original queued user entry. */
+  settle(entryId: string): boolean {
+    const steer = this.options.steers.findByHarnessEntryId(entryId);
+    if (!steer) return false;
+    this.options.transaction(() => {
+      this.persistSidecar(steer, entryId);
+      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);
+    }
+  }
+}
+
+
+/** Keep accepted steers visible on stop, or transfer unconsumed messages to new Submissions. */
+export async function finishPendingSteers(options: {
+  submissionId: string;
+  aborted: boolean;
+  submissions: SubmissionRepository;
+  cancelHandoff(submissionId: string, reason: string): StoredSubmission;
+  steers: SteerRepository;
+  messageUi: MessageUiRepository;
+  transaction<T>(run: () => T): T;
+  conversation: Pick<ConversationHistory, "append">;
+  cancelQueued(entryId: string): Promise<CancelQueuedResult | undefined>;
+  submit(
+    message: PiCanonicalUserInput,
+    options: SubmitMessageOptions,
+  ): Promise<SubmissionHandle<StoredSubmission>>;
+  waitUntil(promise: Promise<unknown>): void;
+}): Promise<void> {
+  for (const steer of options.steers.listForSubmission(options.submissionId)) {
+    const message = JSON.parse(steer.canonicalJson) as PiCanonicalUserInput;
+    const userMessage = steer.uiMessageJson
+      ? JSON.parse(steer.uiMessageJson) as UIMessage & { role: "user" }
+      : undefined;
+    const requestId = `${options.submissionId}:steer:${steer.steerId}`;
+    if (options.aborted) {
+      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);
+        }
+        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;
+    }
+    if (steer.harnessEntryId) {
+      const cancelled = await options.cancelQueued(steer.harnessEntryId);
+      if (cancelled) {
+        if (!cancelled.ok) throw cancelled.error;
+        if (cancelled.value.kind === "already_consumed") {
+          options.transaction(() => options.steers.deleteByMessageId(steer.messageId));
+          continue;
+        }
+        options.transaction(() => options.messageUi.delete(steer.harnessEntryId!));
+      }
+    }
+    // A queued Submission moved to this Turn already owns messageId and is aborted.
+    // Handoff needs its own stable identity while preserving the user's message identity.
+    const submitted = await options.submit(message, {
+      requestId,
+      idempotencyKey: requestId,
+      userMessageId: steer.messageId,
+      steerHandoff: { submissionId: options.submissionId, steerId: steer.steerId },
+      ...(userMessage ? { userMessage } : {}),
+    });
+    options.waitUntil(submitted.completion);
+    options.transaction(() => {
+      let handoff = 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 } : {}),
+        });
+      }
+      options.steers.deleteByMessageId(steer.messageId);
+    });
+  }
+}

package/src/{db/steer.repo.ts → submission/steer-repository.ts}

@@ -4,6 +4,7 @@ export interface PendingSteer {
   steerId: string;
   submissionId: string;
   messageId: string;
+  harnessEntryId: string | null;
   canonicalJson: string;
   uiMessageJson: string | null;
   createdAt: number;
@@ -13,6 +14,7 @@ type PendingSteerRow = {
   steer_id: string;
   submission_id: string;
   message_id: string;
+  harness_entry_id: string | null;
   canonical_json: string;
   ui_message_json: string | null;
   created_at: number;
@@ -23,6 +25,7 @@ function mapRow(row: PendingSteerRow): PendingSteer {
     steerId: row.steer_id,
     submissionId: row.submission_id,
     messageId: row.message_id,
+    harnessEntryId: row.harness_entry_id,
     canonicalJson: row.canonical_json,
     uiMessageJson: row.ui_message_json,
     createdAt: row.created_at,
@@ -35,28 +38,29 @@ export class SteerRepository {
   insert(steer: PendingSteer): void {
     this.sql`
       INSERT INTO pi_pending_steers (
-        steer_id, submission_id, message_id, canonical_json,
+        steer_id, submission_id, message_id, harness_entry_id, canonical_json,
         ui_message_json, created_at
       ) VALUES (
         ${steer.steerId}, ${steer.submissionId}, ${steer.messageId},
-        ${steer.canonicalJson}, ${steer.uiMessageJson}, ${steer.createdAt}
+        ${steer.harnessEntryId}, ${steer.canonicalJson},
+        ${steer.uiMessageJson}, ${steer.createdAt}
       )
     `;
   }
 
   listForSubmission(submissionId: string): PendingSteer[] {
     return this.sql<PendingSteerRow>`
-      SELECT steer_id, submission_id, message_id, canonical_json,
+      SELECT steer_id, submission_id, message_id, harness_entry_id, canonical_json,
              ui_message_json, created_at
       FROM pi_pending_steers
       WHERE submission_id = ${submissionId}
-      ORDER BY created_at ASC, rowid ASC
+      ORDER BY rowid ASC
     `.map(mapRow);
   }
 
   findByMessageId(messageId: string): PendingSteer | null {
     const row = this.sql<PendingSteerRow>`
-      SELECT steer_id, submission_id, message_id, canonical_json,
+      SELECT steer_id, submission_id, message_id, harness_entry_id, canonical_json,
              ui_message_json, created_at
       FROM pi_pending_steers
       WHERE message_id = ${messageId}
@@ -64,6 +68,24 @@ export class SteerRepository {
     return row ? mapRow(row) : null;
   }
 
+  findByHarnessEntryId(entryId: string): PendingSteer | null {
+    const row = this.sql<PendingSteerRow>`
+      SELECT steer_id, submission_id, message_id, harness_entry_id, canonical_json,
+             ui_message_json, created_at
+      FROM pi_pending_steers
+      WHERE harness_entry_id = ${entryId}
+    `[0];
+    return row ? mapRow(row) : null;
+  }
+
+  linkHarnessEntry(messageId: string, entryId: string): void {
+    this.sql`
+      UPDATE pi_pending_steers
+      SET harness_entry_id = ${entryId}
+      WHERE message_id = ${messageId}
+    `;
+  }
+
   deleteByMessageId(messageId: string): void {
     this.sql`
       DELETE FROM pi_pending_steers

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/contract.ts

@@ -88,6 +88,12 @@ export interface TelemetryPayloadByType {
     readonly generationId: string;
     readonly outcome: "completed" | "failed" | "cancelled";
     readonly durationMs?: number;
+    readonly responseHeadersMs?: number;
+    readonly firstRawEventMs?: number;
+    readonly firstMeaningfulEventMs?: number;
+    readonly firstTextEventMs?: number;
+    readonly sourceWaitMs?: number;
+    readonly forwardingOverheadMs?: number;
     readonly inputTokens?: number;
     readonly outputTokens?: number;
     readonly totalTokens?: number;
@@ -288,6 +294,12 @@ function assertPayload(
   }
   for (const field of [
     "durationMs",
+    "responseHeadersMs",
+    "firstRawEventMs",
+    "firstMeaningfulEventMs",
+    "firstTextEventMs",
+    "sourceWaitMs",
+    "forwardingOverheadMs",
     "inputTokens",
     "outputTokens",
     "totalTokens",

package/src/telemetry/coordinator.ts

@@ -4,6 +4,8 @@ import type { TelemetryOutboxWriter } from "./recorder";
 import { TelemetryRecorder } from "./recorder";
 import { RuntimeTelemetry } from "./runtime-telemetry";
 import type { AgentTelemetryBinding } from "./contract";
+import type { PiGenerationLifecycleEvent } from "../models";
+import type { TemporaryAgentLifecycleEvent } from "../tools/subagent/temporary/coordinator";
 
 const TELEMETRY_COLD_BUFFER_LIMIT = 1_000;
 
@@ -93,6 +95,69 @@ export class RuntimeTelemetryCoordinator {
     }
   }
 
+  generation(submissionId: string, event: PiGenerationLifecycleEvent): void {
+    if (event.type === "started") {
+      this.capture("generationStarted", {
+        submissionId,
+        generationId: event.generationId,
+        provider: event.provider,
+        model: event.model,
+        input: event.input,
+        occurredAt: event.timestamp,
+      });
+      return;
+    }
+    this.capture("generationFinished", {
+      submissionId,
+      generationId: event.generationId,
+      outcome: event.outcome === "success" ? "completed"
+        : event.outcome === "cancelled" ? "cancelled" : "failed",
+      durationMs: event.durationMs,
+      responseHeadersMs: event.responseHeadersMs,
+      firstRawEventMs: event.firstRawEventMs,
+      firstMeaningfulEventMs: event.firstMeaningfulEventMs,
+      firstTextEventMs: event.firstTextEventMs,
+      sourceWaitMs: event.sourceWaitMs,
+      forwardingOverheadMs: event.forwardingOverheadMs,
+      ...(event.usage ? {
+        inputTokens: event.usage.input,
+        outputTokens: event.usage.output,
+        totalTokens: event.usage.totalTokens,
+        cost: event.usage.cost.total,
+      } : {}),
+      ...(event.errorName ? { error: event.errorName } : {}),
+      ...(event.output ? { output: event.output } : {}),
+      occurredAt: event.timestamp,
+    });
+  }
+
+  temporaryAgent(
+    submissionId: string,
+    toolCallId: string,
+    event: TemporaryAgentLifecycleEvent,
+  ): void {
+    const identity = { submissionId, toolCallId, subagentId: `temporary:${toolCallId}` };
+    if (event.type === "started") {
+      this.capture("subagentStarted", {
+        ...identity,
+        agentType: event.request.subagentName,
+        prompt: { instructions: event.request.instructions, task: event.request.task },
+        occurredAt: event.occurredAt,
+      });
+      return;
+    }
+    this.capture("subagentFinished", {
+      ...identity,
+      outcome: event.outcome,
+      durationMs: event.durationMs,
+      occurredAt: event.occurredAt,
+      ...(event.output === undefined ? {} : { output: event.output }),
+      ...(event.error === undefined ? {} : {
+        error: event.error instanceof Error ? event.error.message : String(event.error),
+      }),
+    });
+  }
+
   recover(ensureReady: () => Promise<void>): void {
     if (!this.options.outbox()?.hasPending()) return;
     this.options.waitUntil(

package/src/telemetry/delivery.ts

@@ -1,9 +1,9 @@
 import type {
   StoredTelemetryOutboxEvent,
-} from "../db/telemetry-outbox.repo";
+} from "./repository";
 import {
   TELEMETRY_OUTBOX_BATCH_SIZE,
-} from "../db/telemetry-outbox.repo";
+} from "./repository";
 import {
   assertUniversalTelemetryEvent,
   type AgentTelemetryPort,

package/src/telemetry/index.ts

@@ -5,3 +5,8 @@ export * from "./ids";
 export * from "./recorder";
 export * from "./runtime-telemetry";
 export * from "./sanitize";
+export * from "./model-usage";
+export * from "./repository";
+export * from "./runtime-event-repository";
+export * from "./subagent-lifecycle";
+export * from "./turn-events";

package/src/{model-usage.ts → telemetry/model-usage.ts}

@@ -1,5 +1,5 @@
 import type { Api, AssistantMessage, Model } from "@earendil-works/pi-ai";
-import type { RuntimeModelUsageEvent } from "./kernel/bindings";
+import type { RuntimeModelUsageEvent } from "../config/ports";
 
 type ModelUsage = Pick<RuntimeModelUsageEvent,
   "api" | "provider" | "model" | "responseModel" | "stopReason" | "usage"

package/src/telemetry/recorder.ts

@@ -1,7 +1,7 @@
 import type {
   NewTelemetryOutboxEvent,
   TelemetryOutboxInsertResult,
-} from "../db/telemetry-outbox.repo";
+} from "./repository";
 import {
   assertUniversalTelemetryEvent,
   type TelemetryPrivacyMode,

package/src/telemetry/runtime-telemetry.ts

@@ -188,6 +188,12 @@ export class RuntimeTelemetry {
     generationId: string;
     outcome: "completed" | "failed" | "cancelled";
     durationMs?: number;
+    responseHeadersMs?: number;
+    firstRawEventMs?: number;
+    firstMeaningfulEventMs?: number;
+    firstTextEventMs?: number;
+    sourceWaitMs?: number;
+    forwardingOverheadMs?: number;
     inputTokens?: number;
     outputTokens?: number;
     totalTokens?: number;
@@ -204,6 +210,12 @@ export class RuntimeTelemetry {
       generationId: input.generationId,
       outcome: input.outcome,
       ...(input.durationMs === undefined ? {} : { durationMs: input.durationMs }),
+      responseHeadersMs: input.responseHeadersMs,
+      firstRawEventMs: input.firstRawEventMs,
+      firstMeaningfulEventMs: input.firstMeaningfulEventMs,
+      firstTextEventMs: input.firstTextEventMs,
+      sourceWaitMs: input.sourceWaitMs,
+      forwardingOverheadMs: input.forwardingOverheadMs,
       ...(input.inputTokens === undefined ? {} : { inputTokens: input.inputTokens }),
       ...(input.outputTokens === undefined ? {} : { outputTokens: input.outputTokens }),
       ...(input.totalTokens === undefined ? {} : { totalTokens: input.totalTokens }),

package/src/{kernel/durable-lifecycle.ts → telemetry/subagent-lifecycle.ts}

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