@springbrand/agent-runtime 0.1.3-alpha.8 → 0.2.0-alpha.13

package/src/db/submission.repo.ts

@@ -48,6 +48,11 @@ export interface StoredSubmission {
   regenerateMessageId: string | null;
   recoveryErrorCount: number;
   recoveryReason: SubmissionRecoveryReason | null;
+  runId: string | null;
+  accountId: string | null;
+  rateVersion: number | null;
+  slotIdentity: string | null;
+  retryable?: boolean;
 }
 
 export interface NewSubmission {
@@ -62,6 +67,10 @@ export interface NewSubmission {
   queuedUiMessageJson?: string | null;
   userMessageId?: string | null;
   regenerateMessageId?: string | null;
+  runId?: string | null;
+  accountId?: string | null;
+  rateVersion?: number | null;
+  slotIdentity?: string | null;
 }
 
 type SubmissionRow = {
@@ -83,6 +92,11 @@ type SubmissionRow = {
   regenerate_message_id: string | null;
   recovery_error_count: number;
   recovery_reason: string | null;
+  run_id: string | null;
+  account_id: string | null;
+  rate_version: number | null;
+  slot_identity: string | null;
+  admission_retryable: number | null;
 };
 
 // #endregion
@@ -110,6 +124,13 @@ function mapRow(row: SubmissionRow): StoredSubmission {
     regenerateMessageId: row.regenerate_message_id,
     recoveryErrorCount: row.recovery_error_count,
     recoveryReason: row.recovery_reason as SubmissionRecoveryReason | null,
+    runId: row.run_id,
+    accountId: row.account_id,
+    rateVersion: row.rate_version,
+    slotIdentity: row.slot_identity,
+    retryable: row.admission_retryable === null
+      ? undefined
+      : row.admission_retryable === 1,
   };
 }
 
@@ -130,7 +151,9 @@ export class SubmissionRepository {
              error, created_at, completed_at, assembly_revision,
              assembly_descriptor, assistant_message_id, abort_reason,
              queued_input_json, queued_ui_message_json, user_message_id,
-             regenerate_message_id, recovery_error_count, recovery_reason
+             regenerate_message_id, recovery_error_count, recovery_reason,
+             run_id, account_id, rate_version, slot_identity,
+             admission_retryable
       FROM pi_submissions
       WHERE submission_id = ${id}
     `[0];
@@ -230,7 +253,8 @@ export class SubmissionRepository {
         submission_id, request_id, idempotency_key, status, accepted,
         created_at, assembly_revision, assembly_descriptor,
         assistant_message_id, queued_input_json, queued_ui_message_json,
-        user_message_id, regenerate_message_id
+        user_message_id, regenerate_message_id,
+        run_id, account_id, rate_version, slot_identity
       ) VALUES (
         ${s.submissionId},
         ${s.requestId},
@@ -244,7 +268,34 @@ export class SubmissionRepository {
         ${s.queuedInputJson ?? null},
         ${s.queuedUiMessageJson ?? null},
         ${s.userMessageId ?? null},
-        ${s.regenerateMessageId ?? null}
+        ${s.regenerateMessageId ?? null},
+        ${s.runId ?? s.submissionId},
+        ${s.accountId ?? null},
+        ${s.rateVersion ?? null},
+        ${s.slotIdentity ?? null}
+      )
+    `;
+  }
+
+  insertRejected(s: {
+    submissionId: string;
+    requestId: string;
+    idempotencyKey: string | null;
+    createdAt: number;
+    code: string;
+    retryable: boolean;
+  }): void {
+    this.sql`
+      INSERT INTO pi_submissions (
+        submission_id, request_id, idempotency_key, status, accepted,
+        error, created_at, completed_at, assembly_revision,
+        assembly_descriptor, assistant_message_id, abort_reason,
+        recovery_error_count, recovery_reason, run_id, account_id,
+        rate_version, slot_identity, admission_retryable
+      ) VALUES (
+        ${s.submissionId}, ${s.requestId}, ${s.idempotencyKey}, 'skipped', 0,
+        ${s.code}, ${s.createdAt}, ${s.createdAt}, '', '', '', NULL,
+        0, NULL, ${s.submissionId}, NULL, NULL, NULL, ${s.retryable ? 1 : 0}
       )
     `;
   }

package/src/index.ts

@@ -50,6 +50,7 @@ export * from "./kernel/runtime-config";
 export type { RuntimeAssemblyView } from "./kernel/runtime-assembly-view";
 export * from "./runtime-agent";
 export * from "./kernel/state";
+export * from "./workspace-versioning";
 export * from "./lib/execution-level";
 export type {
   RuntimeAssemblyInput,
@@ -119,8 +120,10 @@ export {
 } from "./pi/tool";
 export {
   createSandboxTools,
+  createWorkspaceRevisionTools,
   createWorkspaceTools,
   sandboxPiToolCandidates,
+  workspaceRevisionPiToolCandidate,
   workspacePiToolCandidates,
 } from "./pi/tool";
 export {

package/src/kernel/bindings.ts

@@ -2,6 +2,23 @@ import type { SkillSource } from "agents/skills";
 import type { ScheduleSpec } from "./receipts";
 import type { RuntimeActivityProjection } from "./state";
 import type { ExecutionLevel } from "../lib/execution-level";
+import type {
+  RuntimeEventConfirmation,
+  RuntimeLifecycleFact,
+  RuntimeSubagentUsageEvent,
+  RuntimeSubagentUsageMetrics,
+} from "./submission-authority";
+export type {
+  RuntimeEventConfirmation,
+  RuntimeLifecycleFact,
+  RuntimeSubagentLifecyclePort,
+  RuntimeSubagentUsageEvent,
+  RuntimeSubagentUsageMetrics,
+  RuntimeSubmissionAdmissionHook,
+  RuntimeSubmissionAdmissionInput,
+  RuntimeSubmissionAdmissionResult,
+  RuntimeSubmissionAdmissionContext,
+} from "./submission-authority";
 
 // #region Workspace 端口
 
@@ -194,6 +211,7 @@ export interface WorkspacePort {
  * Workspace；Tool Surface 只把这个已授权 Port 转成 `execute` Tool。
  */
 export interface RuntimeCodeExecutionPort {
+  readonly description: string;
   execute(input: { code: string }): Promise<unknown>;
 }
 
@@ -654,12 +672,16 @@ export type RuntimeSubagentRunResult =
       runId: string;
       output: unknown;
       error?: undefined;
+      usage?: RuntimeSubagentUsageMetrics;
+      childStillRunning?: boolean;
     }
   | {
       status: string;
       runId: string;
       output?: unknown;
       error?: string;
+      usage?: RuntimeSubagentUsageMetrics;
+      childStillRunning?: boolean;
     };
 
 /**
@@ -671,6 +693,15 @@ export type RuntimeSubagentRunResult =
  * 运行记录、后台通知和实际 Agent 路由由 Host 保持，Runtime 只传入类型与结构化输入。
  */
 export interface RuntimeSubagentPort {
+  reserve?(
+    agentType: string,
+    input: Readonly<Record<string, unknown>>,
+    options?: Readonly<{
+      parentRunId?: string;
+      submissionId?: string;
+      toolCallId?: string;
+    }>,
+  ): Promise<{ readonly runId: string }>;
   /**
    * 启动一次 Subagent 运行并返回当前结果。
    *
@@ -686,6 +717,12 @@ export interface RuntimeSubagentPort {
       detached?: boolean;
       maxBudgetMs?: number;
       notifySource?: string;
+      subagentRunId?: string;
+      parentRunId?: string;
+      submissionId?: string;
+      accountId?: string;
+      rateVersion?: number;
+      slotIdentity?: string;
     }>,
   ): Promise<RuntimeSubagentRunResult>;
 }
@@ -706,6 +743,10 @@ export interface RuntimeTurnMessage {
 export interface RuntimeModelUsageEvent {
   readonly eventId: string;
   readonly submissionId: string;
+  readonly runId?: string;
+  readonly accountId?: string;
+  readonly rateVersion?: number;
+  readonly slotIdentity?: string;
   readonly kind: "assistant" | "compaction";
   readonly api: string;
   readonly provider: string;
@@ -777,6 +818,14 @@ export interface RuntimeTurnEventsPort {
   ): Promise<void>;
   /** 投递 Assistant 或 Compaction 的原始 provider usage。 */
   onModelUsage?(event: RuntimeModelUsageEvent): Promise<void>;
+  /** Durable SubAgent usage callback. Runtime keeps the event pending until confirmation. */
+  onSubagentUsage?(
+    event: RuntimeSubagentUsageEvent,
+  ): Promise<RuntimeEventConfirmation | void>;
+  /** Durable lifecycle callback. Runtime keeps the fact pending until confirmation. */
+  onLifecycleFact?(
+    event: RuntimeLifecycleFact,
+  ): Promise<RuntimeEventConfirmation | void>;
   /**
    * 投递一次 Tool 开始执行的事件，带上它的参数。
    *
@@ -863,6 +912,8 @@ export interface RuntimeModelEndpoint {
   headers?: Readonly<Record<string, string>>;
   baseURL: string;
   models: readonly string[];
+  /** OpenRouter upstream provider pins keyed by model ID; pinned requests never fall back. */
+  openRouterProviderPins?: Readonly<Record<string, string>>;
 }
 
 /**
@@ -977,6 +1028,7 @@ export interface RuntimeBindings {
   gateway?: RuntimeGatewayPort;
   workspace?: WorkspacePort;
   memory?: RuntimeMemoryPort;
+  subagents?: RuntimeSubagentPort;
   skills: RuntimeSkillBindings;
   turnEvents?: RuntimeTurnEventsPort;
 }

package/src/kernel/durable-lifecycle.ts

@@ -0,0 +1,100 @@
+import type {
+  RuntimeEventConfirmation,
+  RuntimeLifecycleFact,
+  RuntimeSubagentUsageEvent,
+} from "./submission-authority";
+
+export interface RuntimeLifecycleSink {
+  save(
+    event: RuntimeLifecycleFact | RuntimeSubagentUsageEvent,
+  ): void | Promise<void>;
+  has(eventId: string): boolean;
+  hasSubagentUsage(submissionId: string, subagentRunId: string): boolean;
+}
+
+/**
+ * Small ordering guard used by Host adapters while they persist child facts.
+ * The sink is the Runtime outbox; this class owns no prompt or billing state.
+ */
+export class RuntimeSubagentLifecycleRecorder {
+  constructor(
+    private readonly input: {
+      submissionId: string;
+      parentRunId: string;
+      accountId?: string;
+      rateVersion?: number;
+      slotIdentity?: string;
+    },
+    private readonly sink: RuntimeLifecycleSink,
+  ) {}
+
+  async register(subagentRunId: string): Promise<RuntimeEventConfirmation> {
+    if (!subagentRunId.trim()) throw new Error("SubAgent run ID is required");
+    const eventId = `${subagentRunId}:registered`;
+    if (this.sink.has(eventId)) return { confirmed: true };
+    if (this.sink.has(`${this.input.submissionId}:terminal`)) {
+      throw new Error("SubAgent registration is closed");
+    }
+    await this.sink.save({
+      kind: "subagent-run-registered",
+      eventId,
+      submissionId: this.input.submissionId,
+      subagentRunId,
+      parentRunId: this.input.parentRunId,
+      ...(this.input.accountId ? { accountId: this.input.accountId } : {}),
+      ...(this.input.rateVersion !== undefined ? { rateVersion: this.input.rateVersion } : {}),
+      ...(this.input.slotIdentity ? { slotIdentity: this.input.slotIdentity } : {}),
+    });
+    return { confirmed: true };
+  }
+
+  async usage(event: RuntimeSubagentUsageEvent): Promise<RuntimeEventConfirmation> {
+    if (
+      event.submissionId !== this.input.submissionId ||
+      event.parentRunId !== this.input.parentRunId
+    ) {
+      throw new Error("SubAgent usage identity does not match its lifecycle");
+    }
+    if (!this.sink.has(`${event.subagentRunId}:registered`)) {
+      throw new Error("SubAgent usage is outside its lifecycle");
+    }
+    if (
+      this.sink.has(`${event.subagentRunId}:terminal`) &&
+      !this.sink.has(event.eventId)
+    ) {
+      throw new Error("SubAgent usage is outside its lifecycle");
+    }
+    await this.sink.save(event);
+    return { confirmed: true };
+  }
+
+  async terminal(input: {
+    subagentRunId: string;
+    status: "completed" | "failed" | "aborted" | "skipped";
+    zeroUsage?: boolean;
+  }): Promise<RuntimeEventConfirmation> {
+    if (!this.sink.has(`${input.subagentRunId}:registered`)) {
+      throw new Error("SubAgent is not registered");
+    }
+    const usageSaved = this.sink.hasSubagentUsage(
+      this.input.submissionId,
+      input.subagentRunId,
+    );
+    if (!usageSaved && !input.zeroUsage) {
+      throw new Error("SubAgent terminal requires durable usage or zero usage");
+    }
+    await this.sink.save({
+      kind: "subagent-terminal",
+      eventId: `${input.subagentRunId}:terminal`,
+      submissionId: this.input.submissionId,
+      subagentRunId: input.subagentRunId,
+      parentRunId: this.input.parentRunId,
+      status: input.status,
+      zeroUsage: input.zeroUsage ?? !usageSaved,
+      ...(this.input.accountId ? { accountId: this.input.accountId } : {}),
+      ...(this.input.rateVersion !== undefined ? { rateVersion: this.input.rateVersion } : {}),
+      ...(this.input.slotIdentity ? { slotIdentity: this.input.slotIdentity } : {}),
+    });
+    return { confirmed: true };
+  }
+}

package/src/kernel/public-contracts.ts

@@ -17,3 +17,14 @@ export * from "../pi/message";
 export * from "./receipts";
 export * from "./state";
 export * from "../lib/execution-level";
+export type {
+  RuntimeEventConfirmation,
+  RuntimeLifecycleFact,
+  RuntimeSubagentLifecyclePort,
+  RuntimeSubagentUsageEvent,
+  RuntimeSubagentUsageMetrics,
+  RuntimeSubmissionAdmissionHook,
+  RuntimeSubmissionAdmissionInput,
+  RuntimeSubmissionAdmissionResult,
+  RuntimeSubmissionAdmissionContext,
+} from "./submission-authority";

package/src/kernel/receipts.ts

@@ -86,6 +86,7 @@ export interface SubmissionReceipt {
   status: string;
   accepted: boolean;
   error?: string;
+  retryable?: boolean;
   createdAt: number;
   completedAt?: number;
 }

package/src/kernel/recoverable-chat-agent.ts

@@ -453,12 +453,6 @@ export abstract class RecoverableChatAgent<
     connection: Connection,
     probeId?: string,
   ): Promise<void> {
-    console.info("[DEBUG-ws-old-9f3a] resume-request", {
-      connectionId: connection.id,
-      probeId,
-      activeRequestId: this.resumableStream.activeRequestId,
-      pending: [...this.pendingResumeConnections],
-    });
     return this.resumeHandshake.handleResumeRequest(connection, probeId);
   }
 
@@ -474,12 +468,6 @@ export abstract class RecoverableChatAgent<
     connection: Connection,
     requestId: string,
   ): Promise<void> {
-    console.info("[DEBUG-ws-old-9f3a] resume-ack", {
-      connectionId: connection.id,
-      requestId,
-      activeRequestId: this.resumableStream.activeRequestId,
-      pending: [...this.pendingResumeConnections],
-    });
     return this.resumeHandshake.handleResumeAck(connection, requestId);
   }
 
@@ -504,13 +492,6 @@ export abstract class RecoverableChatAgent<
       readonly continuation?: boolean;
     } = {},
   ): void {
-    console.info("[DEBUG-ws-old-9f3a] broadcast", {
-      requestId,
-      done,
-      activeRequestId: this.resumableStream.activeRequestId,
-      pending: [...this.pendingResumeConnections],
-      connections: Array.from(this.getConnections(), ({ id }) => id),
-    });
     this.broadcast(
       json({
         type: MessageType.CF_AGENT_USE_CHAT_RESPONSE,

package/src/kernel/subagent-runtime.ts

@@ -0,0 +1,137 @@
+import type { RuntimeSubagentUsageMetrics } from "./submission-authority";
+
+export interface RuntimeSubagentRunMetadata {
+  readonly submissionId: string;
+  readonly parentRunId: string;
+  readonly accountId?: string;
+  readonly rateVersion?: number;
+  readonly slotIdentity?: string;
+}
+
+export function emptySubagentUsage(): RuntimeSubagentUsageMetrics {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    cacheWrite1h: 0,
+    reasoning: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  };
+}
+
+export function isZeroSubagentUsage(
+  usage: RuntimeSubagentUsageMetrics,
+): boolean {
+  return usage.totalTokens === 0 && usage.cost.total === 0;
+}
+
+export function subagentTerminalStatus(
+  status: string,
+): "completed" | "failed" | "aborted" | "skipped" {
+  if (status === "completed" || status === "aborted" || status === "skipped") {
+    return status;
+  }
+  return "failed";
+}
+
+export function addSubagentUsage(
+  total: RuntimeSubagentUsageMetrics,
+  usage: RuntimeSubagentUsageMetrics,
+): void {
+  const target = total as {
+    -readonly [Key in keyof RuntimeSubagentUsageMetrics]: RuntimeSubagentUsageMetrics[Key];
+  };
+  const cost = total.cost as {
+    -readonly [Key in keyof RuntimeSubagentUsageMetrics["cost"]]: number;
+  };
+  target.input += usage.input;
+  target.output += usage.output;
+  target.cacheRead += usage.cacheRead;
+  target.cacheWrite += usage.cacheWrite;
+  target.cacheWrite1h = (target.cacheWrite1h ?? 0) + (usage.cacheWrite1h ?? 0);
+  target.reasoning = (target.reasoning ?? 0) + (usage.reasoning ?? 0);
+  target.totalTokens += usage.totalTokens;
+  cost.input += usage.cost.input;
+  cost.output += usage.cost.output;
+  cost.cacheRead += usage.cost.cacheRead;
+  cost.cacheWrite += usage.cost.cacheWrite;
+  cost.total += usage.cost.total;
+}
+
+export function encodeSubagentCompletion(
+  output: unknown,
+  usage: RuntimeSubagentUsageMetrics,
+): string {
+  return JSON.stringify({ output, usage });
+}
+
+export function decodeSubagentCompletion(value: unknown): {
+  output: unknown;
+  usage: RuntimeSubagentUsageMetrics;
+} | null {
+  if (typeof value !== "string") return null;
+  try {
+    const parsed = JSON.parse(value) as Record<string, unknown>;
+    const usage = parsed.usage as Record<string, unknown> | undefined;
+    const cost = usage?.cost as Record<string, unknown> | undefined;
+    const tokenFields = [
+      usage?.input,
+      usage?.output,
+      usage?.cacheRead,
+      usage?.cacheWrite,
+      usage?.totalTokens,
+    ];
+    const costFields = [
+      cost?.input,
+      cost?.output,
+      cost?.cacheRead,
+      cost?.cacheWrite,
+      cost?.total,
+    ];
+    if (
+      tokenFields.some((item) =>
+        !Number.isSafeInteger(item) || (item as number) < 0
+      ) ||
+      costFields.some((item) =>
+        typeof item !== "number" || !Number.isFinite(item) || item < 0
+      ) ||
+      (usage?.cacheWrite1h !== undefined &&
+        (!Number.isSafeInteger(usage.cacheWrite1h) ||
+          (usage.cacheWrite1h as number) < 0)) ||
+      (usage?.reasoning !== undefined &&
+        (!Number.isSafeInteger(usage.reasoning) ||
+          (usage.reasoning as number) < 0))
+    ) {
+      return null;
+    }
+    return {
+      output: parsed.output,
+      usage: usage as unknown as RuntimeSubagentUsageMetrics,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function runtimeSubagentRunMetadata(
+  value: unknown,
+): RuntimeSubagentRunMetadata | null {
+  if (!value || typeof value !== "object") return null;
+  const input = value as Record<string, unknown>;
+  if (
+    typeof input.submissionId !== "string" || !input.submissionId.trim() ||
+    typeof input.parentRunId !== "string" || !input.parentRunId.trim() ||
+    (input.accountId !== undefined &&
+      (typeof input.accountId !== "string" || !input.accountId.trim())) ||
+    (input.slotIdentity !== undefined &&
+      (typeof input.slotIdentity !== "string" || !input.slotIdentity.trim())) ||
+    (input.rateVersion !== undefined &&
+      (!Number.isSafeInteger(input.rateVersion) ||
+        (input.rateVersion as number) <= 0))
+  ) {
+    return null;
+  }
+  return input as unknown as RuntimeSubagentRunMetadata;
+}

package/src/kernel/submission-authority.ts

@@ -0,0 +1,114 @@
+export interface RuntimeSubagentUsageMetrics {
+  readonly input: number;
+  readonly output: number;
+  readonly cacheRead: number;
+  readonly cacheWrite: number;
+  readonly cacheWrite1h?: number;
+  readonly reasoning?: number;
+  readonly totalTokens: number;
+  readonly cost: {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly total: number;
+  };
+}
+
+export interface RuntimeSubagentUsageEvent {
+  readonly eventId: string;
+  readonly submissionId: string;
+  readonly runId: string;
+  readonly subagentRunId: string;
+  readonly parentRunId: string;
+  readonly accountId?: string;
+  readonly rateVersion?: number;
+  readonly slotIdentity?: string;
+  readonly kind: "subagent";
+  readonly status: "completed" | "failed" | "aborted" | "skipped";
+  readonly usage: RuntimeSubagentUsageMetrics;
+}
+
+export interface RuntimeSubagentLifecyclePort {
+  readonly parentRunId: string;
+  readonly submissionId: string;
+  readonly accountId?: string;
+  readonly rateVersion?: number;
+  readonly slotIdentity?: string;
+  onRegistered(subagentRunId: string): Promise<void> | void;
+  onUsage(event: RuntimeSubagentUsageEvent): Promise<void> | void;
+  onTerminal(input: {
+    readonly subagentRunId: string;
+    readonly status: "completed" | "failed" | "aborted" | "skipped";
+    readonly zeroUsage?: boolean;
+  }): Promise<void> | void;
+}
+
+export interface RuntimeSubmissionAdmissionInput {
+  readonly requestId: string;
+  readonly idempotencyKey?: string;
+  readonly runId: string;
+}
+
+export interface RuntimeSubmissionAdmissionContext {
+  readonly accountId: string;
+  readonly rateVersion: number;
+  readonly slotIdentity: string;
+}
+
+export type RuntimeSubmissionAdmissionResult =
+  | ({ readonly accepted: true } & RuntimeSubmissionAdmissionContext)
+  | {
+      readonly accepted: false;
+      readonly code: string;
+      readonly retryable?: boolean;
+    };
+
+export type RuntimeSubmissionAdmissionHook = (
+  input: RuntimeSubmissionAdmissionInput,
+) => Promise<RuntimeSubmissionAdmissionResult>;
+
+export type RuntimeLifecycleFact =
+  | ({ readonly kind: "submission-admitted" } & RuntimeSubmissionAdmissionContext & {
+      readonly eventId: string;
+      readonly submissionId: string;
+      readonly runId: string;
+    })
+  | {
+      readonly kind: "submission-terminal";
+      readonly eventId: string;
+      readonly submissionId: string;
+      readonly runId: string;
+      readonly status: "completed" | "aborted" | "skipped" | "error";
+      readonly childRegistrationClosed: true;
+      readonly zeroUsage: boolean;
+      readonly accountId?: string;
+      readonly rateVersion?: number;
+      readonly slotIdentity?: string;
+    }
+  | {
+      readonly kind: "subagent-run-registered";
+      readonly eventId: string;
+      readonly submissionId: string;
+      readonly subagentRunId: string;
+      readonly parentRunId: string;
+      readonly accountId?: string;
+      readonly rateVersion?: number;
+      readonly slotIdentity?: string;
+    }
+  | {
+      readonly kind: "subagent-terminal";
+      readonly eventId: string;
+      readonly submissionId: string;
+      readonly subagentRunId: string;
+      readonly parentRunId: string;
+      readonly status: "completed" | "failed" | "aborted" | "skipped";
+      readonly zeroUsage: boolean;
+      readonly accountId?: string;
+      readonly rateVersion?: number;
+      readonly slotIdentity?: string;
+    };
+
+export interface RuntimeEventConfirmation {
+  readonly confirmed: true;
+}