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

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

@@ -234,7 +234,8 @@ const IDEMPOTENT_TOOL_NAMES = new Set([
 export function piToolRetryPolicy(
   candidate: PiToolCandidate,
 ): "idempotent" | "non-idempotent" {
-  return IDEMPOTENT_TOOL_NAMES.has(candidate.tool.name)
+  return IDEMPOTENT_TOOL_NAMES.has(candidate.tool.name) ||
+      candidate.owner.startsWith("subagent:")
     ? "idempotent"
     : "non-idempotent";
 }

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

@@ -371,6 +371,11 @@ export interface CreatePreparedPiTurnOptions {
    */
   readonly canonicalMessages: () => Promise<readonly AgentMessage[]>;
   readonly durability: PiTurnDurability;
+  /** Per-Submission executors for tools whose metadata is fixed at assembly time. */
+  readonly toolExecutors?: Readonly<Record<
+    string,
+    NonNullable<PiToolCandidate["tool"]["execute"]>
+  >>;
   /**
    * 上报受治理工具的耗时、结果大小和成败。
    *
@@ -617,7 +622,9 @@ export class PreparedPiTurnAdapter {
               `Non-idempotent Tool outcome is uncertain after recovery: ${candidate.tool.name}`,
             );
           }
-          return candidate.tool.execute(
+          const execute = options.toolExecutors?.[candidate.tool.name] ??
+            candidate.tool.execute;
+          return execute(
             toolCallId,
             input,
             signal,

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

@@ -33,6 +33,11 @@ import {
   PiRuntimeTranscript,
   type PiTranscriptDurability,
 } from "./transcript";
+import { subagentPiToolCandidates } from "../tool/subagent";
+import type {
+  RuntimeSubagentLifecyclePort,
+  RuntimeSubagentPort,
+} from "../../kernel/bindings";
 import type { SqlTaggedTemplate } from "agents/chat";
 
 /**
@@ -201,6 +206,34 @@ export class PiRuntimeAdapter {
    * 实现理由：构造时会校验 Prepared Runtime 的 owner 和 pinned descriptor 格式，再建立本 Turn 独享的 Tool governance 与执行状态。
    * 不要跨 Turn 复用返回对象；abort、steer、assistant ordinal 和 Tool governance 都是单次执行状态。
    */
+  /**
+   * 为一个已准入的 Submission 生成绑定 durable lifecycle 的 SubAgent Tool 执行器。
+   *
+   * @remarks
+   * 调用方：Runtime 在创建 Turn 前调用一次，并把结果作为 `createTurn` 的 `toolExecutors` 传入。
+   *
+   * 实现理由：SubAgent Tool 的名称、Schema 和执行语义属于 Pi Tool 层，而 accountId、
+   * rateVersion 和 slot identity 这些计费事实属于 Submission。两者在这里汇合：Pi 提供工具，
+   * Runtime 提供本次 Submission 的 lifecycle 端口，因此 Runtime 不需要认识 Tool 模块本身。
+   * 没有可用 SubAgent 类型时返回 `undefined`，让 Turn 继续使用装配期的无 lifecycle 执行器。
+   */
+  subagentToolExecutors(
+    subagents: RuntimeSubagentPort,
+    enabledSubagents: readonly string[],
+    lifecycle: RuntimeSubagentLifecyclePort,
+  ): CreatePreparedPiTurnOptions["toolExecutors"] {
+    const entries = subagentPiToolCandidates(
+      subagents,
+      enabledSubagents,
+      lifecycle,
+    ).flatMap((candidate) =>
+      candidate.tool.execute
+        ? [[candidate.tool.name, candidate.tool.execute] as const]
+        : []
+    );
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+  }
+
   createTurn(
     options: CreatePreparedPiTurnOptions,
   ): PreparedPiTurnAdapter {

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

@@ -513,6 +513,7 @@ function configuredModel(
     ...catalogHeaders,
     ...endpoint.headers,
   };
+  const openRouterProviderPin = endpoint.openRouterProviderPins?.[modelId];
   return {
     ...metadata,
     api: apiFor(endpoint.protocol),
@@ -524,6 +525,14 @@ function configuredModel(
             ...compat,
             sendSessionAffinityHeaders: true,
             sessionAffinityFormat: "openrouter" as const,
+            ...(openRouterProviderPin
+              ? {
+                  openRouterRouting: {
+                    order: [openRouterProviderPin],
+                    allow_fallbacks: false,
+                  },
+                }
+              : {}),
           },
         }
       : {}),

package/src/pi/tool/core-host.ts

@@ -36,11 +36,15 @@ export function createWorkspaceCodeExecutionPort(options: {
     ),
     name: "execute",
   });
-  const execute = tool.execute;
+  const { description, execute } = tool;
+  if (typeof description !== "string" || description.length === 0) {
+    throw new Error("Think createExecuteRuntime returned a tool without a description");
+  }
   if (typeof execute !== "function") {
     throw new Error("Think createExecuteRuntime returned a non-executable tool");
   }
   return {
+    description,
     execute: (input) => Promise.resolve(execute(input, {
       toolCallId: "execute",
       messages: [],

package/src/pi/tool/core.ts

@@ -125,16 +125,7 @@ export function codeExecutionPiToolCandidate(
   const tool: AgentTool<typeof executeParameters> = {
     name: "execute",
     label: "Execute JavaScript",
-    description:
-      "Run JavaScript in a short-lived Code Mode Dynamic Worker and return a value. This is your " +
-      "raw-network and tool-composition instrument, not a general web-search tool. Call fetch directly " +
-      "when you need a raw response, custom headers/method/body, a structured API, or content that " +
-      "web_search could not retrieve. Check res.status; when several known endpoints are necessary, " +
-      "fetch them in one invocation. Also available: " +
-      "state.* for your workspace filesystem (readFile/writeFile/glob/searchFiles/replaceInFiles, " +
-      "each taking one object argument), and codemode.step(name, fn) to run a side-effecting block " +
-      "exactly once so it survives replay. Write plain JavaScript — TypeScript type annotations are " +
-      "a syntax error. Use return for the result and console.log for notes.",
+    description: runtime.description,
     parameters: executeParameters,
     // 把模型提供的 JavaScript 交给 Codemode Runtime 执行。
     // Pi 工具循环在模型选择 `execute` 时调用，调用前允许 Turn 取消。

package/src/pi/tool/index.ts

@@ -30,4 +30,5 @@ export * from "./schedule";
 export * from "./skill";
 export * from "./subagent";
 export * from "./workspace-sandbox";
+export * from "./workspace-revision";
 export * from "./web-search";

package/src/pi/tool/mcp.ts

@@ -59,7 +59,8 @@ export interface PiMcpHost {
      * 参数和中止信号必须原样交给 Agents SDK，避免另造一套传输生命周期。
      */
     callTool(
-      ...args: Parameters<MCPClientManager["callTool"]>
+      params: Parameters<MCPClientManager["callTool"]>[0],
+      options?: { signal?: AbortSignal },
     ): Promise<unknown>;
   };
 }
@@ -333,7 +334,6 @@ export function createPiMcpToolCandidates(
           name: mcpTool.name,
           arguments: args,
         },
-        undefined,
         { signal },
       ),
       {

package/src/pi/tool/schedule.ts

@@ -94,7 +94,10 @@ function result<T>(details: T): AgentToolResult<T> {
 function candidate<T extends TSchema>(
   tool: AgentTool<T>,
   options: Partial<
-    Pick<PiToolCandidate, "owner" | "requiredExecutionLevel" | "summary">
+    Pick<
+      PiToolCandidate,
+      "alwaysRequiresApproval" | "owner" | "requiredExecutionLevel" | "summary"
+    >
   > = {},
 ): PiToolCandidate {
   return {
@@ -102,6 +105,9 @@ function candidate<T extends TSchema>(
     requiredExecutionLevel: options.requiredExecutionLevel ?? "safe",
     source: "action",
     tool,
+    ...(options.alwaysRequiresApproval
+      ? { alwaysRequiresApproval: true }
+      : {}),
     ...(options.summary ? { summary: options.summary } : {}),
   };
 }
@@ -110,24 +116,30 @@ export function schedulePiToolCandidates(
   schedule: RuntimeSchedulePort,
 ): PiToolCandidate[] {
   return [
-    candidate({
-      name: "schedule",
-      label: "Schedule prompt",
-      description:
-        "Schedule a prompt to run LATER, autonomously. Use when the user asks to be reminded, or to run something after a delay / at a time / on a recurring basis. The scheduled prompt runs in its own dedicated session at each trigger with NO memory of this conversation, so phrase `prompt` as a fully standalone instruction. After scheduling, tell the user what you set.",
-      parameters: scheduleParameters,
-      async execute(_toolCallId, input, signal) {
-        signal?.throwIfAborted();
-        const spec: ScheduleSpec = {
-          trigger: input.trigger,
-          job: { kind: "prompt", prompt: input.prompt },
-          label: input.label,
-          ...(input.timezone ? { tz: input.timezone } : {}),
-        };
-        const { id } = await schedule.create(spec);
-        return result({ scheduled: true, id });
+    candidate(
+      {
+        name: "schedule",
+        label: "Schedule prompt",
+        description:
+          "Schedule a prompt to run LATER, autonomously. Use when the user asks to be reminded, or to run something after a delay / at a time / on a recurring basis. The user always reviews the proposed schedule before it is created. The scheduled prompt runs in its own dedicated session at each trigger with NO memory of this conversation, so phrase `prompt` as a fully standalone instruction. After scheduling, tell the user what you set.",
+        parameters: scheduleParameters,
+        async execute(_toolCallId, input, signal) {
+          signal?.throwIfAborted();
+          const spec: ScheduleSpec = {
+            trigger: input.trigger,
+            job: { kind: "prompt", prompt: input.prompt },
+            label: input.label,
+            ...(input.timezone ? { tz: input.timezone } : {}),
+          };
+          const { id } = await schedule.create(spec);
+          return result({ scheduled: true, id });
+        },
       },
-    }),
+      {
+        alwaysRequiresApproval: true,
+        summary: "Create a scheduled task",
+      },
+    ),
     candidate({
       name: "list_schedules",
       label: "List schedules",

package/src/pi/tool/subagent.ts

@@ -1,8 +1,17 @@
 import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
 import { z } from "zod";
-import type { RuntimeSubagentPort } from "../../kernel/bindings";
+import type {
+  RuntimeSubagentLifecyclePort,
+  RuntimeSubagentPort,
+  RuntimeSubagentRunResult,
+  RuntimeSubagentUsageEvent,
+} from "../../kernel/bindings";
 import { AGENT_TYPES } from "../../layers/orchestration/subagents/agent-types/registry";
 import { serializeOutput } from "../../lib/artifacts";
+import {
+  isZeroSubagentUsage,
+  subagentTerminalStatus,
+} from "../../kernel/subagent-runtime";
 import type { PiToolCandidate } from "./compiler";
 import {
   toolRegistryFromPiCandidates,
@@ -38,6 +47,61 @@ function failure(agentType: string, status: string, error?: string) {
   };
 }
 
+async function runRegisteredSubagent(
+  lifecycle: RuntimeSubagentLifecyclePort,
+  subagentRunId: string,
+  run: () => Promise<RuntimeSubagentRunResult>,
+): Promise<RuntimeSubagentRunResult> {
+  let result: RuntimeSubagentRunResult;
+  try {
+    result = await run();
+  } catch (error) {
+    await lifecycle.onTerminal({
+      subagentRunId,
+      status: "failed",
+      zeroUsage: true,
+    });
+    throw error;
+  }
+  if (result.runId !== subagentRunId) {
+    await recordSubagentResult(lifecycle, {
+      ...result,
+      runId: subagentRunId,
+      status: "error",
+    });
+    throw new Error("SubAgent run ID changed after durable registration");
+  }
+  return result;
+}
+
+async function recordSubagentResult(
+  lifecycle: RuntimeSubagentLifecyclePort,
+  run: RuntimeSubagentRunResult,
+): Promise<void> {
+  const status = subagentTerminalStatus(run.status);
+  if (run.usage) {
+    const event: RuntimeSubagentUsageEvent = {
+      eventId: `${run.runId}:usage`,
+      submissionId: lifecycle.submissionId,
+      runId: run.runId,
+      subagentRunId: run.runId,
+      parentRunId: lifecycle.parentRunId,
+      ...(lifecycle.accountId ? { accountId: lifecycle.accountId } : {}),
+      ...(lifecycle.rateVersion !== undefined ? { rateVersion: lifecycle.rateVersion } : {}),
+      ...(lifecycle.slotIdentity ? { slotIdentity: lifecycle.slotIdentity } : {}),
+      kind: "subagent",
+      status,
+      usage: run.usage,
+    };
+    await lifecycle.onUsage(event);
+  }
+  await lifecycle.onTerminal({
+    subagentRunId: run.runId,
+    status,
+    zeroUsage: !run.usage || isZeroSubagentUsage(run.usage),
+  });
+}
+
 /**
  * 把已启用的 SubAgent 类型转换成 Pi 候选工具。
  *
@@ -53,6 +117,7 @@ function failure(agentType: string, status: string, error?: string) {
 export function subagentPiToolCandidates(
   subagents: RuntimeSubagentPort | undefined,
   enabledSubagents: readonly string[],
+  lifecycle?: RuntimeSubagentLifecyclePort,
 ): PiToolCandidate[] {
   if (!subagents) return [];
   const types = [...new Set(enabledSubagents)].flatMap((name) => {
@@ -79,10 +144,38 @@ export function subagentPiToolCandidates(
       // 适配层只固定类型名并统一结果语义。
       async execute(_toolCallId, input, signal) {
         signal?.throwIfAborted();
-        const run = await subagents.run(
-          type.name,
-          input as Record<string, unknown>,
-        );
+        const childInput = input as Record<string, unknown>;
+        if (lifecycle && !subagents.reserve) {
+          throw new Error("Durable SubAgent execution requires run reservation");
+        }
+        const reserved = lifecycle
+          ? await subagents.reserve!(type.name, childInput, {
+              parentRunId: lifecycle.parentRunId,
+              submissionId: lifecycle.submissionId,
+              toolCallId: _toolCallId,
+            })
+          : undefined;
+        if (reserved && lifecycle) await lifecycle.onRegistered(reserved.runId);
+        const runOptions = lifecycle
+          ? {
+              parentRunId: lifecycle.parentRunId,
+              submissionId: lifecycle.submissionId,
+              ...(reserved ? { subagentRunId: reserved.runId } : {}),
+              ...(lifecycle.accountId ? { accountId: lifecycle.accountId } : {}),
+              ...(lifecycle.rateVersion !== undefined ? { rateVersion: lifecycle.rateVersion } : {}),
+              ...(lifecycle.slotIdentity ? { slotIdentity: lifecycle.slotIdentity } : {}),
+            }
+          : undefined;
+        const run = lifecycle && reserved
+          ? await runRegisteredSubagent(
+              lifecycle,
+              reserved.runId,
+              () => subagents.run(type.name, childInput, runOptions),
+            )
+          : await subagents.run(type.name, childInput);
+        if (lifecycle && !run.childStillRunning) {
+          await recordSubagentResult(lifecycle, run);
+        }
         if (run.status !== "completed" || run.output === undefined) {
           return result(failure(type.name, run.status, run.error));
         }
@@ -112,7 +205,7 @@ export function subagentPiToolCandidates(
     // 调用：Pi 需要子任务异步进行、不应阻塞当前 Turn 时调用。
     // 原因：先用具体 AgentType Schema 复核嵌套 input，
     // 再把 detached 和通知语义交给 Host，避免后台入口绕过类型约束。
-    async execute(_toolCallId, value, signal) {
+    async execute(toolCallId, value, signal) {
       signal?.throwIfAborted();
       const input = value as z.infer<typeof parameters>;
       const parsed = AGENT_TYPES.byName[input.agentType]!.inputSchema.safeParse(
@@ -123,15 +216,47 @@ export function subagentPiToolCandidates(
           `SubAgent input failed schema validation: ${parsed.error.message}`,
         );
       }
-      const run = await subagents.run(
-        input.agentType,
-        parsed.data as Record<string, unknown>,
-        {
-          detached: true,
-          maxBudgetMs: BACKGROUND_MAX_BUDGET_MS,
-          notifySource: "dispatch-background",
-        },
-      );
+      if (lifecycle && !subagents.reserve) {
+        throw new Error("Durable SubAgent execution requires run reservation");
+      }
+      const reserved = lifecycle
+        ? await subagents.reserve!(
+            input.agentType,
+            parsed.data as Record<string, unknown>,
+            {
+              parentRunId: lifecycle.parentRunId,
+              submissionId: lifecycle.submissionId,
+              toolCallId,
+            },
+          )
+        : undefined;
+      if (reserved && lifecycle) await lifecycle.onRegistered(reserved.runId);
+      const runInput = parsed.data as Record<string, unknown>;
+      const runOptions = {
+        detached: true,
+        maxBudgetMs: BACKGROUND_MAX_BUDGET_MS,
+        notifySource: "dispatch-background",
+        ...(lifecycle
+          ? {
+              parentRunId: lifecycle.parentRunId,
+              submissionId: lifecycle.submissionId,
+              ...(reserved ? { subagentRunId: reserved.runId } : {}),
+              ...(lifecycle.accountId ? { accountId: lifecycle.accountId } : {}),
+              ...(lifecycle.rateVersion !== undefined ? { rateVersion: lifecycle.rateVersion } : {}),
+              ...(lifecycle.slotIdentity ? { slotIdentity: lifecycle.slotIdentity } : {}),
+            }
+          : {}),
+      };
+      const run = lifecycle && reserved
+        ? await runRegisteredSubagent(
+            lifecycle,
+            reserved.runId,
+            () => subagents.run(input.agentType, runInput, runOptions),
+          )
+        : await subagents.run(input.agentType, runInput, runOptions);
+      if (lifecycle && !run.childStillRunning && run.status !== "running") {
+        await recordSubagentResult(lifecycle, run);
+      }
       return result({
         runId: run.runId,
         status: run.status,
@@ -153,8 +278,9 @@ export function subagentPiToolCandidates(
 export function createSubagentTools(
   subagents: RuntimeSubagentPort | undefined,
   enabledSubagents: readonly string[],
+  lifecycle?: RuntimeSubagentLifecyclePort,
 ): ToolRegistry {
   return toolRegistryFromPiCandidates(
-    subagentPiToolCandidates(subagents, enabledSubagents),
+    subagentPiToolCandidates(subagents, enabledSubagents, lifecycle),
   );
 }

package/src/pi/tool/workspace-revision.ts

@@ -0,0 +1,64 @@
+import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
+import { Type } from "@earendil-works/pi-ai";
+import type { WorkspaceRevisionRestorePort } from "../../workspace-versioning";
+import { serializeOutput } from "../../lib/artifacts";
+import {
+  toolRegistryFromPiCandidates,
+  type ToolRegistry,
+} from "../../tool-registry";
+import type { PiToolCandidate } from "./compiler";
+
+const parameters = Type.Object({
+  target: Type.Union([
+    Type.Literal("previous"),
+    Type.String({
+      pattern: "^[0-9a-f]{40}$",
+      description: "A complete revision ID shown in Workspace history.",
+    }),
+  ], {
+    description: "Use previous for the revision immediately before the current one.",
+  }),
+});
+
+function result<T>(details: T): AgentToolResult<T> {
+  return {
+    content: [{ type: "text", text: serializeOutput(details).text }],
+    details,
+  };
+}
+
+export function workspaceRevisionPiToolCandidate(
+  versions: WorkspaceRevisionRestorePort,
+): PiToolCandidate {
+  const tool: AgentTool<typeof parameters> = {
+    name: "restore_workspace_revision",
+    label: "Restore Workspace revision",
+    description:
+      "Restore the configured Workspace tree to the previous revision or an exact revision. Use only when the person explicitly asks to roll back. This always asks for approval and changes only the Workspace files managed by the Host.",
+    parameters,
+    async execute(_toolCallId, input, signal) {
+      signal?.throwIfAborted();
+      return result({
+        status: "restored",
+        ...await versions.restore(input.target),
+        note: "The approved Workspace revision is now current.",
+      });
+    },
+  };
+  return {
+    owner: "workspace",
+    tool,
+    requiredExecutionLevel: "safe",
+    alwaysRequiresApproval: true,
+    source: "action",
+    summary: "Restore the Workspace tree",
+  };
+}
+
+export function createWorkspaceRevisionTools(
+  versions: WorkspaceRevisionRestorePort,
+): ToolRegistry {
+  return toolRegistryFromPiCandidates([
+    workspaceRevisionPiToolCandidate(versions),
+  ]);
+}

package/src/runtime-agent-context.ts

@@ -37,6 +37,7 @@ export interface RuntimeAgentToolResult {
   output?: unknown;
   summary?: string;
   error?: string;
+  childStillRunning?: boolean;
 }
 
 export type RuntimeAgentRole = "primary" | "temporary";

package/src/runtime-assembler.ts

@@ -55,6 +55,7 @@ import {
 } from "./pi/tool/core";
 import { skillPiToolCandidates } from "./pi/tool/skill";
 import { createWebSearch } from "./pi/tool/web-search";
+import { subagentPiToolCandidates } from "./pi/tool/subagent";
 import { resolvePiModel } from "./pi/runtime-adapter/models";
 
 /** Runtime Assembler：校验一份扁平输入并生成可原子提交的 Snapshot。 */
@@ -474,7 +475,13 @@ class RuntimeBuilder {
       ...(this.memoryProfile.enabled && this.memory
         ? { memory: { port: this.memory, profile: this.memoryProfile } }
         : {}),
-      hostTools: this.hostTools,
+      hostTools: [
+        ...this.hostTools,
+        ...subagentPiToolCandidates(
+          this.subagents,
+          [...this.enabledSubagents],
+        ),
+      ],
       skills: skillSources,
       enabledSubagents: [...this.enabledSubagents],
       webSearch,
@@ -492,6 +499,7 @@ class RuntimeBuilder {
       ...(this.memoryProfile.enabled && this.memory
         ? { memory: this.memory }
         : {}),
+      ...(this.subagents ? { subagents: this.subagents } : {}),
       skills: Object.freeze({
         sources: Object.freeze(skillSources),
       }),
@@ -632,6 +640,8 @@ function hooksToTurnEventsPort<
   if (
     !hooks.onTurnEnd &&
     !hooks.onModelUsage &&
+    !hooks.onSubagentUsage &&
+    !hooks.onLifecycleFact &&
     !hooks.onToolStart &&
     !hooks.onToolSettled &&
     !hooks.onApproval &&
@@ -645,6 +655,8 @@ function hooksToTurnEventsPort<
       ? (messages) => hooks.onTurnEnd!(ctx, messages)
       : async () => undefined,
     ...(hooks.onModelUsage ? { onModelUsage: hooks.onModelUsage } : {}),
+    ...(hooks.onSubagentUsage ? { onSubagentUsage: hooks.onSubagentUsage } : {}),
+    ...(hooks.onLifecycleFact ? { onLifecycleFact: hooks.onLifecycleFact } : {}),
     ...(hooks.onToolStart ? { onToolStart: hooks.onToolStart } : {}),
     ...(hooks.onToolSettled ? { onToolSettled: hooks.onToolSettled } : {}),
     ...(hooks.onApproval ? { onApproval: hooks.onApproval } : {}),
@@ -757,6 +769,9 @@ export async function assembleRuntimeSnapshot<
     ...(memoryProfile.enabled && toolAssembly.bindings?.memory
       ? { memory: toolAssembly.bindings.memory }
       : {}),
+    ...(toolAssembly.bindings?.subagents
+      ? { subagents: toolAssembly.bindings.subagents }
+      : {}),
     hostTools,
     skills: resources.skills,
     connectors: resources.connectors.servers,

package/src/runtime-definition.ts

@@ -3,6 +3,10 @@ import type { ExecutionLevel } from "./lib/execution-level";
 import type {
   RuntimeGatewayPort,
   RuntimeModelUsageEvent,
+  RuntimeSubmissionAdmissionHook,
+  RuntimeSubagentUsageEvent,
+  RuntimeLifecycleFact,
+  RuntimeEventConfirmation,
   RuntimePlatformPort,
   RuntimeProviderPort,
   RuntimeSkillScriptPolicy,
@@ -136,6 +140,14 @@ export interface RuntimeAgentHooks<
     messages: readonly RuntimeTurnMessage[],
   ) => Promise<void>;
   readonly onModelUsage?: (event: RuntimeModelUsageEvent) => Promise<void>;
+  readonly onSubagentUsage?: (
+    event: RuntimeSubagentUsageEvent,
+  ) => Promise<RuntimeEventConfirmation | void>;
+  readonly onLifecycleFact?: (
+    event: RuntimeLifecycleFact,
+  ) => Promise<RuntimeEventConfirmation | void>;
+  /** Single admission seam shared by chat, RPC, regenerate and scheduled submissions. */
+  readonly onSubmissionAdmission?: RuntimeSubmissionAdmissionHook;
   readonly onToolStart?: (event: RuntimeToolStartEvent) => Promise<void>;
   readonly onToolSettled?: (event: RuntimeToolSettlementEvent) => Promise<void>;
   readonly onApproval?: (input: ApprovalHookInput) => Promise<void>;