@springbrand/agent-runtime 0.2.0-alpha.34 → 0.2.0-alpha.38

package/src/runtime-agent.ts

@@ -35,13 +35,8 @@ import {
 } from "./runtime-assembler";
 import type {
   ResolvedResources,
-  RuntimeAgentHooks,
+  ToolAssemblyResult,
 } from "./runtime-definition";
-import {
-  normalizeToolAssembly,
-  type ToolAssemblyResult,
-  type ToolRegistry,
-} from "./tool-registry";
 import type { RuntimeAssemblyView } from "./kernel/runtime-assembly-view";
 import type { RuntimeConfigUpdateResult } from "./kernel/runtime-config";
 import {
@@ -82,6 +77,7 @@ export interface LoadedRuntime<Config> {
   readonly runtimeKey: string;
   readonly config: Config;
   readonly resources: ResolvedResources;
+  readonly commitGuard?: () => Promise<void>;
 }
 
 export interface RuntimeConfigUpdate<Change> {
@@ -108,12 +104,7 @@ interface RuntimeAgentDefinitionBase<
   readonly tools: (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
     config: Config,
-  ) => ToolRegistry | ToolAssemblyResult | Promise<ToolRegistry | ToolAssemblyResult>;
-
-  readonly hooks?:
-    | RuntimeAgentHooks<Env, Config, Command, Change>
-    | ((context: RuntimeAgentPlanningContext<Env, Command, Change>) =>
-      RuntimeAgentHooks<Env, Config, Command, Change>);
+  ) => ToolAssemblyResult | Promise<ToolAssemblyResult>;
 
   /** Prepare the optional telemetry consumer for this concrete Agent facet. */
   readonly telemetry?: (
@@ -411,18 +402,6 @@ export function defineRuntimeAgent<
     | MutableRuntimeAgentDefinition<Env, Config, Command, Change>
     | ReadonlyRuntimeAgentDefinition<Env, Config>,
 ): RuntimeAgentClass<Env, Command, Change> {
-  const resolveDefinitionHooks = (
-    context: RuntimeAgentPlanningContext<Env, Command, Change>,
-  ): RuntimeAgentHooks<Env, Config, Command, Change> | undefined => {
-    const hooks = definition.hooks;
-    if (!hooks) return undefined;
-    return typeof hooks === "function"
-      ? (hooks as (
-          ctx: RuntimeAgentPlanningContext<Env, Command, Change>,
-        ) => RuntimeAgentHooks<Env, Config, Command, Change>)(context)
-      : hooks as RuntimeAgentHooks<Env, Config, Command, Change>;
-  };
-
   const resolveDefinitionTelemetry = (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
   ): AgentTelemetryBinding | undefined => {
@@ -628,17 +607,18 @@ export function defineRuntimeAgent<
             const context = this.createDefinitionContext({
               value: loaded.config,
             });
-            let tools = normalizeToolAssembly(await withRuntimeLoadTimeout(
+            let tools = await withRuntimeLoadTimeout(
               "definition.tools",
               () => (
                 definition.tools as (
                   context: RuntimeAgentPlanningContext<Env, Command, Change>,
                   config: Config,
-                ) => ToolRegistry | ToolAssemblyResult | Promise<ToolRegistry | ToolAssemblyResult>
+                ) => ToolAssemblyResult | Promise<ToolAssemblyResult>
               )(context, loaded.config),
               { timeoutMs: RUNTIME_LOAD_TIMEOUT_MS },
-            ));
-            let hooks = resolveDefinitionHooks(context);
+            );
+            let resources = loaded.resources;
+            let commitGuard = loaded.commitGuard;
             if (!this.telemetryResolved) {
               this.resolvedTelemetry = resolveDefinitionTelemetry(context);
               this.telemetryResolved = true;
@@ -647,14 +627,14 @@ export function defineRuntimeAgent<
             if (this.role === "temporary") {
               this.temporaryDispose = tools.dispose;
               tools = this.applyTemporaryToolPolicy(tools);
-              hooks = await this.createTemporaryHooks();
+              resources = await this.applyTemporaryResources(resources);
+              commitGuard = undefined;
             }
             const candidate = await assembleRuntimeSnapshot({
               ctx: context,
-              config: loaded.config,
               tools,
-              resources: loaded.resources,
-              hooks,
+              resources,
+              ...(commitGuard ? { commitGuard } : {}),
               ...(telemetry ? { telemetry } : {}),
             });
 
@@ -713,9 +693,9 @@ export function defineRuntimeAgent<
         };
       }
 
-      private async createTemporaryHooks(): Promise<
-        RuntimeAgentHooks<Env, Config, Command, Change>
-      > {
+      private async applyTemporaryResources(
+        resources: ResolvedResources,
+      ): Promise<ResolvedResources> {
         const launch = this.temporaryLaunch ??
           await this.ctx.storage.get<TemporaryAgentLaunch<Config>>(
             TEMPORARY_AGENT_LAUNCH_KEY,
@@ -723,17 +703,27 @@ export function defineRuntimeAgent<
         if (!launch) throw new Error("Temporary Agent is not initialized");
         this.temporaryLaunch = launch;
         return {
-          profileOverrides: () => ({
-            systemPrompt: launch.instructions,
-            executionLevel: "high",
-          }),
-          gateTool: async (request) => {
-            if (!requiresExecutionApproval(
-              launch.executionLevel,
-              request.requiredExecutionLevel,
-            )) return;
-            await this.requestParentTemporaryApproval(launch, request);
+          ...resources,
+          settings: {
+            ...resources.settings,
+            profile: {
+              ...resources.settings.profile,
+              systemPrompt: launch.instructions,
+              executionLevel: "high",
+            },
+          },
+          platform: {
+            ...resources.platform,
+            gateTool: async (request) => {
+              if (!requiresExecutionApproval(
+                launch.executionLevel,
+                request.requiredExecutionLevel,
+              )) return;
+              await this.requestParentTemporaryApproval(launch, request);
+            },
           },
+          turnEvents: undefined,
+          admission: undefined,
         };
       }
 

package/src/runtime-assembler.ts

@@ -7,6 +7,7 @@ import type {
   RuntimeSandboxPort,
   RuntimeSchedulePort,
   RuntimeSkillSourceBinding,
+  RuntimeSubmissionAdmissionHook,
   RuntimeSubagentPort,
   RuntimeTurnEventsPort,
   RuntimeBindings,
@@ -29,6 +30,7 @@ import {
 } from "./lib/execution-level";
 import {
   createPiRuntimeAssembly,
+  type FinalizedPiToolSurface,
   type PiToolSurface,
   type PiRuntimeAssembly,
 } from "./pi/assembly/snapshot";
@@ -36,19 +38,13 @@ 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 {
-  toolRegistryFromPiCandidates,
-  type RuntimeCodeExecutionFactory,
-  type ToolRegistry,
-} from "./tool-registry";
-import { withRuntimeLoadTimeout } from "./kernel/runtime-load";
+import type { RuntimeCodeExecutionFactory } from "./kernel/bindings";
 import {
   basePiToolCandidates,
   memoryPiToolCandidate,
@@ -125,8 +121,7 @@ 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;
+  readonly admission?: RuntimeSubmissionAdmissionHook;
   readonly telemetry?: AgentTelemetryBinding;
 }
 
@@ -198,9 +193,13 @@ async function createToolSurface(
   const classify = (candidate: PiToolCandidate): PiToolCandidate =>
     Object.freeze({
       ...candidate,
-      ...(defersTool?.(candidate.tool.name) === true
-        ? { deferLoading: true as const }
-        : { deferLoading: undefined }),
+      ...(defersTool
+        ? {
+            deferLoading: defersTool(candidate.tool.name) === true
+              ? true as const
+              : undefined,
+          }
+        : {}),
     });
   // 平台没有浏览器能力时注册空集：宁可没有这个 Tool，也不注册一个必然失败的 Tool 误导模型。
   // `create()` 推迟到确认这个名字真的可见之后，被 deny 的装配不白建一个浏览器连接器。
@@ -267,7 +266,10 @@ async function createToolSurface(
           deny.has("execute") ||
           allowsTool?.("execute") === false
         ) {
-          return Object.freeze(directVisible.map(classify));
+          return Object.freeze({
+            candidates: Object.freeze(directVisible.map(classify)),
+            codeExecutionCandidates: Object.freeze([]),
+          }) satisfies FinalizedPiToolSurface;
         }
         const mergeable = finalized.filter(
           (candidate) =>
@@ -275,11 +277,40 @@ async function createToolSurface(
             !candidate.interaction &&
             typeof candidate.tool.execute === "function",
         );
-        const codeExecutionTools = Object.freeze([...mergeable]);
+        const codeExecutionCandidates = Object.freeze([...mergeable]);
+        const codeExecutionToolNames = new Set(
+          codeExecutionCandidates.map(({ tool }) => tool.name),
+        );
         const codeExecution = input.codeExecution.create(
-          toolRegistryFromPiCandidates(codeExecutionTools),
+          codeExecutionCandidates,
         );
-        const materializeGuidance = codeExecutionTools.some(
+        const topLevelOnly = directVisible.filter(
+          ({ tool }) => !codeExecutionToolNames.has(tool.name),
+        );
+        const routeList = (deferred: boolean) => {
+          const matches = topLevelOnly.filter((candidate) =>
+            (defersTool?.(candidate.tool.name) === true) === deferred
+          );
+          return matches.length > 0
+            ? matches.map(({ tool }) =>
+                `- \`${tool.name}\` — ${(tool.label ?? tool.name)
+                  .replaceAll(/\s+/g, " ").trim().replaceAll("`", "'")}`
+              ).join("\n")
+            : "- None.";
+        };
+        const routeGuidance = [
+          "## Tool routing",
+          "Top-level deferred Tools are not callable through `tools.*`. Use Provider Tool Search with their exact name, then call them directly.",
+          "Top-level immediate Tools are already available outside execute; call them directly.",
+          "",
+          "## Top-level deferred Tools",
+          routeList(true),
+          "",
+          "## Top-level immediate Tools",
+          routeList(false),
+          "",
+        ].join("\n");
+        const materializeGuidance = codeExecutionCandidates.some(
             ({ tool }) => tool.name === "materialize_skill_resource",
           )
           ? "Skill resource copying is available only inside execute through " +
@@ -287,18 +318,17 @@ async function createToolSurface(
             "no Direct Tool is registered for it. " +
             "Use a loop or Promise.all when copying multiple resources.\n\n"
           : "";
-        return Object.freeze([
-          classify({
-            ...codeExecutionPiToolCandidate(
-              {
-                ...codeExecution,
-                description: materializeGuidance + codeExecution.description,
-              },
-            ),
-            codeExecutionTools,
-          }),
-          ...directVisible.map(classify),
-        ]);
+        return Object.freeze({
+          candidates: Object.freeze([
+            classify(codeExecutionPiToolCandidate({
+              ...codeExecution,
+              description:
+                routeGuidance + "\n" + materializeGuidance + codeExecution.description,
+            })),
+            ...directVisible.map(classify),
+          ]),
+          codeExecutionCandidates,
+        }) satisfies FinalizedPiToolSurface;
       },
     }),
     extensions: input.extensions.filter(
@@ -658,174 +688,34 @@ 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");
-    const {
-      label,
-      description,
-      parameters,
-      execute,
-      owner = "platform",
-      ...metadata
-    } = spec;
-    candidates.push(Object.freeze({
-      ...metadata,
-      owner,
-      tool: Object.freeze({
-        name: normalized,
-        label,
-        description,
-        parameters,
-        async execute(
-          toolCallId: string,
-          input: unknown,
-          signal?: AbortSignal,
-        ) {
-          const result = await 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.onSubagentUsage &&
-    !hooks.onLifecycleFact &&
-    !hooks.onToolStart &&
-    !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.onSubagentUsage ? { onSubagentUsage: hooks.onSubagentUsage } : {}),
-    ...(hooks.onLifecycleFact ? { onLifecycleFact: hooks.onLifecycleFact } : {}),
-    ...(hooks.onToolStart ? { onToolStart: hooks.onToolStart } : {}),
-    ...(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。
+ * 从 Tool 和已加载 Resource 装配 Runtime 候选 Snapshot。
  *
  * @internal
  */
 export async function assembleRuntimeSnapshot<
   Env extends Cloudflare.Env,
-  Config,
   Command = never,
   Change = never,
 >(
-  input: AssembleRuntimeSnapshotInput<Env, Config, Command, Change>,
+  input: AssembleRuntimeSnapshotInput<Env, 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 withRuntimeLoadTimeout(
-      "profile-overrides",
-      () => 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 profile = settings.profile;
 
-  const hostTools = toolRegistryPiToolCandidates(
-    toolAssembly.tools,
-    settings,
-  );
+  const hostTools = toolAssembly.tools;
 
   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;
+  if (input.commitGuard) commitGuards.push(input.commitGuard);
 
   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
@@ -860,7 +750,7 @@ export async function assembleRuntimeSnapshot<
     ...(toolPolicy ? { toolPolicy } : {}),
     enabledSubagents: [...enabledSubagents],
     provider,
-    platform,
+    platform: resources.platform,
     ...(toolAssembly.bindings?.workspace
       ? { workspace: toolAssembly.bindings.workspace }
       : {}),
@@ -883,9 +773,9 @@ export async function assembleRuntimeSnapshot<
       ? { gateway: resources.connectors.gateway }
       : {}),
     extensions: resources.extensions,
-    ...(turnEvents ? { turnEvents } : {}),
+    ...(resources.turnEvents ? { turnEvents: resources.turnEvents } : {}),
     ...(input.telemetry ? { telemetry: input.telemetry } : {}),
-    commitGuards: [],
+    commitGuards,
     degradations: [
       ...(toolAssembly.degradations ?? []),
       ...(resources.degradations ?? []),
@@ -895,22 +785,8 @@ export async function assembleRuntimeSnapshot<
 
   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 } : {}),
+    ...candidate,
+    ...(resources.admission ? { admission: resources.admission } : {}),
     ...(candidate.telemetry ? { telemetry: candidate.telemetry } : {}),
   });
 }