@springbrand/agent-runtime 0.1.3-alpha.4 → 0.1.3-alpha.5

package/src/runtime-assembler.ts

@@ -33,75 +33,40 @@ import {
   type PiToolSurface,
   type PiRuntimeAssembly,
 } from "./pi/assembly/snapshot";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
 import type { PiToolCandidate } from "./pi/tool/compiler";
+import type {
+  AssembleRuntimeSnapshotInput,
+  RuntimeAgentHooks,
+  RuntimeSettings,
+  RuntimeExtensionContribution,
+  RuntimeProfileContribution,
+  RuntimeSkillContribution,
+  RuntimeToolSurfacePolicy,
+} from "./runtime-definition";
+import type { ToolRegistry } from "./tool-registry";
 import {
   basePiToolCandidates,
   memoryPiToolCandidate,
 } from "./pi/tool/base";
 import {
   browserQuickActionPiToolCandidates,
-  codeExecutionPiToolCandidate,
 } from "./pi/tool/core";
-import {
-  sandboxPiToolCandidates,
-  workspacePiToolCandidates,
-} from "./pi/tool/workspace-sandbox";
-import { schedulePiToolCandidates } from "./pi/tool/schedule";
 import { skillPiToolCandidates } from "./pi/tool/skill";
-import { subagentPiToolCandidates } from "./pi/tool/subagent";
 import { createWebSearch } from "./pi/tool/web-search";
 import { resolvePiModel } from "./pi/runtime-adapter/models";
 
 /** Runtime Assembler：校验一份扁平输入并生成可原子提交的 Snapshot。 */
 
 export type { RuntimeDegradation } from "./kernel/degradation";
-
-/**
- * 提供 Runtime 核心运行参数。
- *
- * @remarks
- * Host Planner 在装配输入中提供它。
- *
- * 这里只放业务可配置字段，冻结和最终结构由 Runtime 负责。
- */
-export interface RuntimeProfileContribution {
-  readonly model: string;
-  readonly thinking: ThinkingEffort;
-  readonly systemPrompt?: string;
-  readonly executionLevel: ExecutionLevel;
-}
-
-/**
- * 描述一个已准备 Skill。
- */
-export interface RuntimeSkillContribution {
-  readonly name: string;
-  readonly description: string;
-  readonly source: SkillSource;
-  readonly script?: Partial<RuntimeSkillScriptPolicy>;
-}
-
-/**
- * 描述一个已准备 Extension。
- */
-export interface RuntimeExtensionContribution {
-  readonly name: string;
-  readonly extension: RuntimeExtensionConfig;
-}
-
-/**
- * 描述 Agent 对最终 Tool Surface 的可见性约束。
- *
- * Host 只提供策略；Runtime 在唯一 Tool Surface seam 中对所有
- * Port 和 Resource 生成的候选项统一应用。
- */
-export interface RuntimeToolSurfacePolicy {
-  readonly denyPolicy?: RuntimeDenyPolicy;
-  readonly allowsTool?: (name: string) => boolean;
-  readonly allowsExtension?: (extension: RuntimeExtensionConfig) => boolean;
-}
-
-/** Host Planner 与 Runtime Assembler 之间唯一的一次性 seam。 */
+export type {
+  RuntimeExtensionContribution,
+  RuntimeProfileContribution,
+  RuntimeSkillContribution,
+  RuntimeToolSurfacePolicy,
+} from "./runtime-definition";
+
+/** Host Planner 与 Runtime Assembler 之间的一次性内部 seam。 */
 export interface RuntimeAssemblyInput {
   readonly profile: RuntimeProfileContribution;
   readonly memoryProfile: RuntimeMemoryProfile;
@@ -147,6 +112,8 @@ export interface RuntimeSnapshot {
 export interface RuntimeCandidate {
   readonly snapshot: RuntimeSnapshot;
   readonly commitGuards: readonly (() => Promise<void>)[];
+  readonly hooks?: RuntimeAgentHooks<Cloudflare.Env, unknown, never, never>;
+  readonly turnEvents?: RuntimeTurnEventsPort;
 }
 
 const DISABLED_MEMORY: RuntimeMemoryProfile = Object.freeze({
@@ -187,12 +154,8 @@ interface ToolSurfaceInput {
     readonly port: RuntimeMemoryPort;
     readonly profile: RuntimeMemoryProfile;
   };
-  readonly codeExecution?: RuntimeCodeExecutionPort;
-  readonly sandbox?: RuntimeSandboxPort;
   readonly hostTools: readonly PiToolCandidate[];
   readonly skills: readonly RuntimeSkillSourceBinding[];
-  readonly schedule?: RuntimeSchedulePort;
-  readonly subagents?: RuntimeSubagentPort;
   readonly enabledSubagents: readonly string[];
   readonly webSearch: Parameters<typeof basePiToolCandidates>[0];
   readonly extensions: readonly RuntimeExtensionConfig[];
@@ -220,50 +183,24 @@ async function createToolSurface(
   const browserCandidates = input.platform.browser
     ? browserQuickActionPiToolCandidates(input.platform.browser)
     : [];
-  const workspaceCandidates = input.workspace
-    ? workspacePiToolCandidates(input.workspace)
-    : [];
-  const executionCandidates = input.workspace && input.codeExecution
-    ? [codeExecutionPiToolCandidate(input.codeExecution)]
-    : [];
-  const sandboxCandidates = input.sandbox
-    ? sandboxPiToolCandidates(input.sandbox)
-    : [];
-  const subagentCandidates = subagentPiToolCandidates(
-    input.subagents,
-    input.enabledSubagents,
-  );
-  const scheduleCandidates = input.schedule
-    ? schedulePiToolCandidates(input.schedule)
-    : [];
   const baseCandidates = basePiToolCandidates(input.webSearch);
   const memoryCandidates = input.memory
     ? [memoryPiToolCandidate(input.memory.port, input.memory.profile)]
     : [];
   const scriptCandidates = [
     ...browserCandidates,
-    ...workspaceCandidates,
-    ...executionCandidates,
-    ...sandboxCandidates,
     ...input.hostTools,
-    ...scheduleCandidates,
-    ...subagentCandidates,
     ...baseCandidates,
     ...memoryCandidates,
   ].filter(visible);
   const staticCandidates = [
     ...browserCandidates,
-    ...workspaceCandidates,
-    ...executionCandidates,
-    ...sandboxCandidates,
     ...input.hostTools,
     ...(await skillPiToolCandidates(input.skills, {
       loader: input.platform.loader,
       ...(input.workspace ? { workspace: input.workspace } : {}),
       tools: scriptCandidates,
     })),
-    ...scheduleCandidates,
-    ...subagentCandidates,
     ...baseCandidates,
     ...memoryCandidates,
   ];
@@ -487,17 +424,7 @@ class RuntimeBuilder {
     assertMemoryProfile(this.memoryProfile);
     if (this.memoryProfile.enabled && (!this.workspace || !this.memory)) {
       throw new Error(
-        "Enabled Runtime memory requires Workspace and Memory ports",
-      );
-    }
-    if (this.sandbox && !this.workspace) {
-      throw new Error(
-        "Runtime Sandbox requires a persistent Workspace port",
-      );
-    }
-    if (this.enabledSubagents.size > 0 && !this.subagents) {
-      throw new Error(
-        "Enabled Runtime Subagents require a Subagent port",
+        "Enabled Runtime memory requires Workspace and Memory bindings",
       );
     }
     const profile = freezeRuntimeProfile({
@@ -547,12 +474,8 @@ class RuntimeBuilder {
       ...(this.memoryProfile.enabled && this.memory
         ? { memory: { port: this.memory, profile: this.memoryProfile } }
         : {}),
-      ...(this.codeExecution ? { codeExecution: this.codeExecution } : {}),
-      ...(this.sandbox ? { sandbox: this.sandbox } : {}),
       hostTools: this.hostTools,
       skills: skillSources,
-      ...(this.schedule ? { schedule: this.schedule } : {}),
-      ...(this.subagents ? { subagents: this.subagents } : {}),
       enabledSubagents: [...this.enabledSubagents],
       webSearch,
       extensions: [...this.extensions.values()],
@@ -640,4 +563,231 @@ export async function assembleRuntime(
   commit(candidate.snapshot);
 }
 
+export function toolRegistryPiToolCandidates(
+  registry: ToolRegistry,
+  settings?: Pick<RuntimeSettings, "toolPolicy">,
+): PiToolCandidate[] {
+  const deny = new Set(settings?.toolPolicy?.denyPolicy?.deny ?? []);
+  const allowsTool = settings?.toolPolicy?.allowsTool;
+  const candidates: PiToolCandidate[] = [];
+  for (const [name, spec] of Object.entries(registry)) {
+    if (deny.has(name)) continue;
+    if (allowsTool?.(name) === false) continue;
+    const normalized = requiredName(name, "Platform Tool");
+    candidates.push(Object.freeze({
+      owner: "platform",
+      authorized: true,
+      requiredExecutionLevel: spec.requiredExecutionLevel,
+      ...(spec.alwaysRequiresApproval
+        ? { alwaysRequiresApproval: true }
+        : {}),
+      tool: Object.freeze({
+        name: normalized,
+        label: spec.label,
+        description: spec.description,
+        parameters: spec.parameters,
+        async execute(
+          toolCallId: string,
+          input: unknown,
+          signal?: AbortSignal,
+        ) {
+          const result = await spec.execute(input, {
+            toolCallId,
+            signal: signal ?? new AbortController().signal,
+          });
+          if (
+            result != null &&
+            typeof result === "object" &&
+            "content" in result &&
+            Array.isArray((result as { content?: unknown }).content)
+          ) {
+            return result as import("@earendil-works/pi-agent-core").AgentToolResult<unknown>;
+          }
+          let text: string;
+          try {
+            text = JSON.stringify(result) ?? String(result);
+          } catch {
+            text = String(result);
+          }
+          return {
+            content: [{ type: "text" as const, text }],
+            details: result,
+          };
+        },
+      } as AgentTool<any, any>),
+    }));
+  }
+  return candidates;
+}
+
+function hooksToTurnEventsPort<
+  Env extends Cloudflare.Env,
+  Config,
+  Command,
+  Change,
+>(
+  ctx: AssembleRuntimeSnapshotInput<Env, Config, Command, Change>["ctx"],
+  hooks?: RuntimeAgentHooks<Env, Config, Command, Change>,
+): RuntimeTurnEventsPort | undefined {
+  if (!hooks) return undefined;
+  if (
+    !hooks.onTurnEnd &&
+    !hooks.onModelUsage &&
+    !hooks.onToolSettled &&
+    !hooks.onApproval &&
+    !hooks.onActivityChanged &&
+    !hooks.onSubmissionTerminal
+  ) {
+    return undefined;
+  }
+  return {
+    onResponse: hooks.onTurnEnd
+      ? (messages) => hooks.onTurnEnd!(ctx, messages)
+      : async () => undefined,
+    ...(hooks.onModelUsage ? { onModelUsage: hooks.onModelUsage } : {}),
+    ...(hooks.onToolSettled ? { onToolSettled: hooks.onToolSettled } : {}),
+    ...(hooks.onApproval ? { onApproval: hooks.onApproval } : {}),
+    ...(hooks.onActivityChanged
+      ? { onActivityChanged: hooks.onActivityChanged }
+      : {}),
+    ...(hooks.onSubmissionTerminal
+      ? { onSubmissionTerminal: hooks.onSubmissionTerminal }
+      : {}),
+  };
+}
+
+/**
+ * 从 Config、Tool 和已加载 Resource 装配 Runtime 候选 Snapshot。
+ *
+ * @internal
+ */
+export async function assembleRuntimeSnapshot<
+  Env extends Cloudflare.Env,
+  Config,
+  Command = never,
+  Change = never,
+>(
+  input: AssembleRuntimeSnapshotInput<Env, Config, Command, Change>,
+): Promise<RuntimeCandidate> {
+  const resources = input.resources;
+  const toolAssembly = input.tools;
+  const settings = resources.settings;
+  const provider = resources.provider;
+  let profile = settings.profile;
+  if (input.hooks?.profileOverrides) {
+    const overrides = await input.hooks.profileOverrides(
+      input.ctx,
+      input.config,
+    );
+    if (overrides.systemPrompt !== undefined) {
+      profile = { ...profile, systemPrompt: overrides.systemPrompt };
+    }
+    if (overrides.executionLevel !== undefined) {
+      profile = { ...profile, executionLevel: overrides.executionLevel };
+    }
+  }
+
+  const hostTools = toolRegistryPiToolCandidates(
+    toolAssembly.tools,
+    settings,
+  );
+
+  const commitGuards: Array<() => Promise<void>> = [];
+  if (toolAssembly.commitGuard) commitGuards.push(toolAssembly.commitGuard);
+  if (input.hooks?.beforeCommit) {
+    for (const guard of input.hooks.beforeCommit) {
+      commitGuards.push(() => guard(input.ctx, input.config));
+    }
+  }
+
+  const platform: RuntimePlatformPort = input.hooks?.gateTool
+    ? Object.freeze({
+        ...resources.platform,
+        gateTool: (request: {
+          toolCallId: string;
+          toolName: string;
+          input: unknown;
+          requiredExecutionLevel: import("./lib/execution-level").ExecutionLevel;
+          signal: AbortSignal;
+        }) => input.hooks!.gateTool!(request),
+      })
+    : resources.platform;
+
+  const memoryProfile =
+    toolAssembly.memoryProfile ?? settings.memoryProfile;
+  const enabledSubagents =
+    toolAssembly.enabledSubagents ?? settings.enabledSubagents;
+  const turnEvents = hooksToTurnEventsPort(input.ctx, input.hooks);
+
+  const toolPolicy: RuntimeToolSurfacePolicy | undefined =
+    settings.toolPolicy || toolAssembly.surfacePolicy
+      ? {
+          ...(settings.toolPolicy?.denyPolicy
+            ? { denyPolicy: settings.toolPolicy.denyPolicy }
+            : {}),
+          ...(settings.toolPolicy?.allowsTool
+            ? { allowsTool: settings.toolPolicy.allowsTool }
+            : {}),
+          ...(settings.toolPolicy?.allowsExtension
+            ? { allowsExtension: settings.toolPolicy.allowsExtension }
+            : {}),
+          ...(toolAssembly.surfacePolicy?.allowsTool
+            ? { allowsTool: toolAssembly.surfacePolicy.allowsTool }
+            : {}),
+          ...(toolAssembly.surfacePolicy?.allowsExtension
+            ? { allowsExtension: toolAssembly.surfacePolicy.allowsExtension }
+            : {}),
+        }
+      : undefined;
+
+  const assemblyInput: RuntimeAssemblyInput = {
+    profile,
+    memoryProfile,
+    ...(toolPolicy ? { toolPolicy } : {}),
+    enabledSubagents: [...enabledSubagents],
+    provider,
+    platform,
+    ...(toolAssembly.bindings?.workspace
+      ? { workspace: toolAssembly.bindings.workspace }
+      : {}),
+    ...(memoryProfile.enabled && toolAssembly.bindings?.memory
+      ? { memory: toolAssembly.bindings.memory }
+      : {}),
+    hostTools,
+    skills: resources.skills,
+    connectors: resources.connectors.servers,
+    ...(resources.connectors.gateway
+      ? { gateway: resources.connectors.gateway }
+      : {}),
+    extensions: resources.extensions,
+    ...(turnEvents ? { turnEvents } : {}),
+    commitGuards: [],
+    degradations: [
+      ...(toolAssembly.degradations ?? []),
+      ...(resources.degradations ?? []),
+      ...resources.connectors.degradations,
+    ],
+  };
+
+  const candidate = await prepareRuntimeCandidate(assemblyInput);
+  return Object.freeze({
+    snapshot: candidate.snapshot,
+    commitGuards: Object.freeze([
+      ...candidate.commitGuards,
+      ...commitGuards,
+    ]),
+    ...(input.hooks
+      ? {
+          hooks: input.hooks as unknown as RuntimeAgentHooks<
+            Cloudflare.Env,
+            unknown,
+            never,
+            never
+          >,
+        }
+      : {}),
+    ...(turnEvents ? { turnEvents } : {}),
+  });
+}
+
 // #endregion

package/src/runtime-definition.ts

@@ -0,0 +1,173 @@
+import type { SkillSource } from "agents/skills";
+import type { ExecutionLevel } from "./lib/execution-level";
+import type {
+  RuntimeGatewayPort,
+  RuntimeModelUsageEvent,
+  RuntimePlatformPort,
+  RuntimeProviderPort,
+  RuntimeSkillScriptPolicy,
+  RuntimeTurnMessage,
+} from "./kernel/bindings";
+import type {
+  RuntimeDenyPolicy,
+  RuntimeMcpServer,
+  RuntimeMemoryProfile,
+  ThinkingEffort,
+} from "./kernel/profile";
+import type { RuntimeExtensionConfig } from "./kernel/extensions";
+import type { RuntimeActivityProjection } from "./kernel/state";
+import type { RuntimeDegradation } from "./kernel/degradation";
+import type {
+  RuntimeAgentContext,
+  RuntimeAssemblyContext,
+  RuntimeAgentPlanningContext,
+} from "./runtime-agent-context";
+
+export interface RuntimeProfileContribution {
+  readonly model: string;
+  readonly thinking: ThinkingEffort;
+  readonly systemPrompt?: string;
+  readonly executionLevel: ExecutionLevel;
+}
+
+export interface RuntimeSkillContribution {
+  readonly name: string;
+  readonly description: string;
+  readonly source: SkillSource;
+  readonly script?: Partial<RuntimeSkillScriptPolicy>;
+}
+
+export interface RuntimeExtensionContribution {
+  readonly name: string;
+  readonly extension: RuntimeExtensionConfig;
+}
+
+export interface RuntimeToolSurfacePolicy {
+  readonly denyPolicy?: RuntimeDenyPolicy;
+  readonly allowsTool?: (name: string) => boolean;
+  readonly allowsExtension?: (extension: RuntimeExtensionConfig) => boolean;
+}
+
+export type { RuntimeAgentContext, RuntimeAssemblyContext } from "./runtime-agent-context";
+
+export interface GateToolRequest {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly input: unknown;
+  readonly requiredExecutionLevel: ExecutionLevel;
+  readonly signal: AbortSignal;
+}
+
+export type {
+  PlatformToolContext,
+  PlatformToolRegistry,
+  PlatformToolSpec,
+  RuntimeToolBindings,
+  ToolAssemblyResult,
+  ToolContext,
+  ToolRegistry,
+  ToolSpec,
+} from "./tool-registry";
+export {
+  emptyPlatformToolRegistry,
+  emptyToolRegistry,
+  mergeToolRegistries,
+  normalizeToolAssembly,
+  toolRegistryFromPiCandidates,
+} from "./tool-registry";
+
+export interface ResolvedConnectors {
+  readonly servers: readonly RuntimeMcpServer[];
+  readonly gateway?: RuntimeGatewayPort;
+  readonly degradations: readonly RuntimeDegradation[];
+}
+
+export interface ResolvedResources {
+  readonly settings: RuntimeSettings;
+  readonly provider: RuntimeProviderPort;
+  readonly platform: RuntimePlatformPort;
+  readonly skills: readonly RuntimeSkillContribution[];
+  readonly extensions: readonly RuntimeExtensionContribution[];
+  readonly connectors: ResolvedConnectors;
+  readonly degradations?: readonly RuntimeDegradation[];
+}
+
+export interface ProfileOverrides {
+  readonly systemPrompt?: string;
+  readonly executionLevel?: ExecutionLevel;
+}
+
+export interface ApprovalHookInput {
+  readonly submissionId: string;
+  readonly approvalExecutionId: string;
+}
+
+export interface SubmissionTerminalHookInput {
+  readonly submissionId: string;
+  readonly status: "completed" | "aborted" | "skipped" | "error";
+  readonly error?: string;
+  readonly resultMessageId?: string;
+}
+
+export interface RuntimeToolSettlementEvent {
+  readonly eventId: string;
+  readonly submissionId: string;
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly status: "success" | "error";
+}
+
+export interface RuntimeAgentHooks<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+  Config = unknown,
+  Command = never,
+  Change = never,
+> {
+  readonly beforeCommit?: ReadonlyArray<
+    (
+      ctx: RuntimeAssemblyContext<Env, Command, Change>,
+      config: Config,
+    ) => Promise<void>
+  >;
+
+  readonly onTurnEnd?: (
+    ctx: RuntimeAssemblyContext<Env, Command, Change>,
+    messages: readonly RuntimeTurnMessage[],
+  ) => Promise<void>;
+  readonly onModelUsage?: (event: RuntimeModelUsageEvent) => Promise<void>;
+  readonly onToolSettled?: (event: RuntimeToolSettlementEvent) => Promise<void>;
+  readonly onApproval?: (input: ApprovalHookInput) => Promise<void>;
+  readonly onActivityChanged?: (
+    projection: RuntimeActivityProjection,
+  ) => Promise<void>;
+  readonly onSubmissionTerminal?: (
+    input: SubmissionTerminalHookInput,
+  ) => Promise<void>;
+
+  readonly gateTool?: (request: GateToolRequest) => Promise<void>;
+
+  readonly profileOverrides?: (
+    ctx: RuntimeAssemblyContext<Env, Command, Change>,
+    config: Config,
+  ) => ProfileOverrides | Promise<ProfileOverrides>;
+}
+
+export interface RuntimeSettings {
+  readonly profile: RuntimeProfileContribution;
+  readonly memoryProfile: RuntimeMemoryProfile;
+  readonly toolPolicy?: RuntimeToolSurfacePolicy;
+  readonly enabledSubagents: readonly string[];
+}
+
+export interface AssembleRuntimeSnapshotInput<
+  Env extends Cloudflare.Env,
+  Config,
+  Command = never,
+  Change = never,
+> {
+  readonly ctx: RuntimeAgentPlanningContext<Env, Command, Change>;
+  readonly config: Config;
+  readonly tools: import("./tool-registry").ToolAssemblyResult;
+  readonly resources: ResolvedResources;
+  readonly hooks?: RuntimeAgentHooks<Env, Config, Command, Change>;
+}