@springbrand/agent-runtime 0.3.0-alpha.10 → 0.3.0-alpha.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.3.0-alpha.10",
+  "version": "0.3.0-alpha.12",
   "type": "module",
   "files": [
     "src",
@@ -21,8 +21,8 @@
     "@cloudflare/sandbox": "0.12.4",
     "@cloudflare/shell": "0.4.3",
     "@cloudflare/think": "0.18.0",
-    "@earendil-works/pi-agent-core": "0.85.1",
-    "@earendil-works/pi-ai": "0.85.1",
+    "@earendil-works/pi-agent-core": "0.86.1",
+    "@earendil-works/pi-ai": "0.86.1",
     "@types/lodash-es": "^4.17.12",
     "cron-schedule": "6.0.0",
     "isomorphic-git": "1.38.6",

package/src/adapter/cloudflare/agent.ts

@@ -67,6 +67,7 @@ import {
 import type { UIMessage, UIMessageChunk } from "ai";
 import type {
   AssistantMessage,
+  JsonObject,
 } from "@earendil-works/pi-ai";
 import { BACKGROUND_CONTEXT } from "@earendil-works/pi-agent-core/harness/context";
 import { openCloudflareSession } from "../../session";
@@ -74,6 +75,7 @@ import { openSessionHarness, prepareSubmissionOperation } from "../../harness";
 import type { SessionHarness } from "../../harness";
 import {
   compileHarnessTools,
+  harnessToolActivation,
   decodeSubagentCompletion,
   HarnessDecisionGate,
   HarnessHumanDecisions,
@@ -854,6 +856,7 @@ export abstract class AgentRuntimeKernel<
         resolveReplay: gate.resolveReplay.bind(gate),
         resolveConfirmation: gate.resolveConfirmation.bind(gate),
       }),
+      ...harnessToolActivation(harnessInput.candidates),
       modelToolResultExemptions: harnessInput.candidates
         .filter(({ outputBudget }) => outputBudget?.kind === "structure")
         .map(({ tool }) => tool.name),
@@ -871,7 +874,7 @@ export abstract class AgentRuntimeKernel<
             part.arguments = prepareToolInput(
               part.name,
               part.arguments,
-            ) as Record<string, unknown>;
+            ) as JsonObject;
           }
         }
         return { message };

package/src/conversation/history.ts

@@ -5,6 +5,7 @@ import type {
 } from "@earendil-works/pi-agent-core";
 import type {
   AssistantMessage,
+  JsonValue,
   ToolResultMessage,
   UserMessage,
 } from "@earendil-works/pi-ai";
@@ -490,6 +491,7 @@ export class ConversationHistory {
           toolName: tool.toolName,
           ...toolResult,
           content: toolResult.content ?? [],
+          details: toolResult.details as JsonValue | undefined,
           isError: tool.status === "settled" && tool.isError,
           timestamp: snapshot.operation!.startedAt,
         }, { preliminary: tool.status === "running" });

package/src/conversation/message/conversion.ts

@@ -56,9 +56,9 @@ export function normalizeUIUserInput(
       continue;
     }
     if (capability.kind === "tool") {
-      if (!installed.hasTool(capability.name)) {
-        throw new Error(`Requested Tool is not installed: ${capability.name}`);
-      }
+      // if (!installed.hasTool(capability.name)) {
+      //   throw new Error(`Requested Tool is not installed: ${capability.name}`);
+      // }
       context.push(
         `requested capability: tool/${capability.name}`,
         `required action: call tool "${capability.name}" when handling the task`,

package/src/harness/session-harness.ts

@@ -4,6 +4,7 @@ import {
   type AgentHarness as PiAgentHarness,
   type AgentHarnessOptions,
   type AgentLane,
+  type AgentToolResult,
   type DriveOutcome,
   type DriveOptions,
   type OpenOperation,
@@ -35,6 +36,22 @@ export interface SessionHarnessOptions<TContext extends object | undefined>
   modelToolResultExemptions?: readonly string[];
   /** Base provider Session identity, retained except after a server Tool timeout. */
   modelSessionId?: string;
+  /**
+   * Compiled tools omitted from the initial active set. A later successful
+   * result may add them through {@link SessionHarnessOptions.toolsToActivate}.
+   */
+  onDemandToolNames?: readonly string[];
+  /**
+   * Names to add with `setActiveTools` from `after_tool`. That hook runs
+   * before the next generation snapshots `activeToolNames`; Pi then writes
+   * the difference as transcript `toolsAdded`. Do not call `setActiveTools`
+   * from `tool_end`: event delivery is serialized and would deadlock.
+   */
+  toolsToActivate?: (
+    toolName: string,
+    result: AgentToolResult<unknown>,
+    isError: boolean,
+  ) => readonly string[];
 }
 
 export type SessionHarnessRunResult = DriveOutcome | {
@@ -75,6 +92,10 @@ function toolCallKey(toolName: string, args: unknown): string {
   return `${toolName}\0${canonicalJson(args)}`;
 }
 
+function uniqueToolNames(names: readonly string[]): string[] {
+  return [...new Set(names)];
+}
+
 function projectToolResultsForModel(
   messages: readonly AgentMessage[],
   exemptions: ReadonlySet<string>,
@@ -133,14 +154,10 @@ function artifactManifestMessage(
   ];
   let omitted = 0;
   for (const ref of refs.values()) {
-    const preview = ref.preview.replace(/[\r\n]+/g, " ").slice(0, 240);
+    const preview = ref.preview.replace(/[\r\n]+/g, " ").slice(0, 160);
     const line = [
-      `artifactId=${ref.artifactId}`,
       `path=${ref.path}`,
-      `hash=${ref.hash}`,
-      `bytes=${ref.bytes}`,
-      `workspaceRevision=${ref.workspaceRevision}`,
-      `availability=${ref.availability}`,
+      ...(ref.availability === "unavailable" ? ["unavailable"] : []),
       `preview=${preview}`,
     ].join(" ");
     if ([...lines, line, "</workspace_artifact_manifest>"].join("\n").length > ARTIFACT_MANIFEST_MAX_CHARS) {
@@ -149,7 +166,7 @@ function artifactManifestMessage(
     }
     lines.push(line);
   }
-  if (omitted > 0) lines.push(`omitted=${omitted} older artifact references due to manifest budget`);
+  if (omitted > 0) lines.push(`omitted=${omitted} additional artifact references due to manifest budget`);
   lines.push("</workspace_artifact_manifest>");
   return {
     role: "user",
@@ -192,6 +209,15 @@ export class SessionHarness<TContext extends object | undefined> {
   private readonly modelSessionId: string | undefined;
   private readonly wrapUpInstruction: string;
   private readonly configuredToolNames: string[];
+  private readonly compiledToolNames: ReadonlySet<string>;
+  private readonly onDemandToolNames: ReadonlySet<string>;
+  private readonly toolsToActivate:
+    | ((
+      toolName: string,
+      result: AgentToolResult<unknown>,
+      isError: boolean,
+    ) => readonly string[])
+    | undefined;
   private readonly modelToolResultExemptions: ReadonlySet<string>;
   private readonly toolFailures = new Map<string, number>();
   private totalToolFailures = 0;
@@ -236,6 +262,9 @@ export class SessionHarness<TContext extends object | undefined> {
       DEFAULT_WRAP_UP_INSTRUCTION;
     this.configuredToolNames = options.activeToolNames ??
       (options.tools ?? []).map(({ name }) => name);
+    this.compiledToolNames = new Set((options.tools ?? []).map(({ name }) => name));
+    this.onDemandToolNames = new Set(options.onDemandToolNames ?? []);
+    this.toolsToActivate = options.toolsToActivate;
     this.modelToolResultExemptions = new Set(
       options.modelToolResultExemptions ?? [],
     );
@@ -323,6 +352,8 @@ export class SessionHarness<TContext extends object | undefined> {
       limits: _limits,
       modelToolResultExemptions: _modelToolResultExemptions,
       modelSessionId: _modelSessionId,
+      onDemandToolNames: _onDemandToolNames,
+      toolsToActivate: _toolsToActivate,
       ...harnessOptions
     } = options;
     let runtime!: SessionHarness<TContext>;
@@ -452,6 +483,17 @@ export class SessionHarness<TContext extends object | undefined> {
       }
       await this.harness.close(eventContext);
     });
+    this.harness.hooks.on("after_tool", async (event, eventContext) => {
+      await this.activateToolsFromResult({
+        toolName: event.toolName,
+        result: {
+          content: event.content,
+          details: event.details,
+        },
+        isError: event.isError,
+      }, eventContext);
+      return undefined;
+    });
     this.harness.events.on("tool_start", (event) => {
       this.activeTools.add(event.toolCallId);
     });
@@ -474,6 +516,34 @@ export class SessionHarness<TContext extends object | undefined> {
     await new Promise<void>((resolve) => this.toolsIdle.add(resolve));
   }
 
+  private async activeToolsForNewOperation(context: Context): Promise<string[]> {
+    const previous = await this.lane.getActiveTools(context);
+    const keepOnDemand = previous.filter((name) =>
+      this.onDemandToolNames.has(name) && this.compiledToolNames.has(name)
+    );
+    return uniqueToolNames([...this.configuredToolNames, ...keepOnDemand]);
+  }
+
+  private async activateToolsFromResult(
+    event: {
+      toolName: string;
+      result: AgentToolResult<unknown>;
+      isError: boolean;
+    },
+    context: Context,
+  ): Promise<void> {
+    const requested = this.toolsToActivate?.(
+      event.toolName,
+      event.result,
+      event.isError,
+    ) ?? [];
+    const allowed = requested.filter((name) => this.compiledToolNames.has(name));
+    if (allowed.length === 0) return;
+    const current = await this.lane.getActiveTools(context);
+    if (allowed.every((name) => current.includes(name))) return;
+    await this.lane.setActiveTools(uniqueToolNames([...current, ...allowed]), context);
+  }
+
   private async completedModelTurns(context: Context): Promise<number> {
     return (await this.operationEntries(context)).filter((entry) =>
       entry.type === "message" && entry.message.role === "assistant"
@@ -498,7 +568,10 @@ export class SessionHarness<TContext extends object | undefined> {
       this.toolFailureWrapUp = false;
       this.toolFailureWrapUpAt = undefined;
       this.releaseReason = undefined;
-      await this.lane.setActiveTools(this.configuredToolNames, context);
+      await this.lane.setActiveTools(
+        await this.activeToolsForNewOperation(context),
+        context,
+      );
       const admission = await this.lane.accept(request, context);
       if (!admission.ok) throw admission.error;
       operationId = admission.value.operationId;

package/src/index.ts

@@ -94,6 +94,7 @@ export type {
 } from "./tools";
 export { basePiToolCandidates } from "./tools";
 export { createPiDeclaredToolCandidate } from "./tools";
+export { harnessToolActivation } from "./tools";
 export type {
   PiDeclaredTool,
   PiDeclaredToolCallContext,

package/src/lib/prompt.ts

@@ -118,10 +118,8 @@ export const INTERACTION =
   "without that answer; required defaults to false. At most one question may request attachments. Do not add an accept field or tell the user to upload through the normal chat composer; " +
   "continue the same turn when its result arrives. " +
   "Don't use it when a sensible default lets you proceed. " +
-  "After completing a substantive task (report, analysis, multi-step job), finish all work and other Tool calls, " +
-  "then call suggest_followups (2-4 directions) as the last Tool call before your final answer. " +
-  "After it returns, write your complete final answer and make no further Tool calls. Never for small talk or while a " +
-  "task is still in progress; it is non-blocking, unlike ask_user.";
+  "When a substantive task (report, analysis, or multi-step job) is complete, call suggest_followups once before the final answer. " +
+  "Never use it for small talk, quick answers, or while a task is still in progress; it is non-blocking, unlike ask_user.";
 
 // Separates short always-on memory from indexed long-tail workspace files.
 export const MEMORY =

package/src/models/index.ts

@@ -2,6 +2,7 @@ import type { StreamFn } from "@earendil-works/pi-agent-core";
 import {
   createModels,
   createProvider,
+  getCurrentSystemPrompt,
   isRetryableAssistantError,
   lazyStream,
   type Api,
@@ -11,6 +12,8 @@ import {
   type Model,
   type MutableModels,
   type ProviderStreams,
+  type SimpleStreamOptions,
+  type TranscriptContext,
 } from "@earendil-works/pi-ai";
 import { anthropicMessagesApi } from "@earendil-works/pi-ai/api/anthropic-messages.lazy";
 import {
@@ -38,7 +41,7 @@ import {
   openaiCodexProvider,
 } from "@earendil-works/pi-ai/providers/openai-codex";
 import {
-  cloudflareStreams,
+  resolveCloudflareModel,
 } from "@earendil-works/pi-ai/providers/cloudflare-stream";
 import {
   ChatStreamStalledError,
@@ -51,6 +54,10 @@ import type {
 } from "../config/ports";
 import { modelInputMessages } from "../conversation/message/model-input";
 import { openRouterMessagesApi } from "./openrouter/messages";
+import {
+  overlayProviderStreams,
+  remapProviderStreamModels,
+} from "./provider-streams";
 
 const CATALOGS = {
   "openai-chat": openaiProvider().getModels(),
@@ -130,6 +137,12 @@ export type PiGenerationLifecycleObserver = (
   event: PiGenerationLifecycleEvent,
 ) => void;
 
+type ProviderBoundStream = (
+  model: Model<Api>,
+  context: Context | TranscriptContext,
+  options?: SimpleStreamOptions,
+) => ReturnType<StreamFn>;
+
 export function structuredOutputStream(
   streamFn: StreamFn,
   model: Model<Api>,
@@ -490,16 +503,19 @@ export function modelRequestUrl(model: Model<Api>): string {
  * observer 的异常被隔离，不能改变模型执行结果。
  */
 export function withProviderBoundary(
-  streamFn: StreamFn,
+  streamFn: ProviderBoundStream,
   defaultSessionId?: string,
   onGeneration?: PiGenerationLifecycleObserver,
-): StreamFn {
+): ProviderBoundStream {
   return (model, context, options) =>
     lazyStream(model, async () => {
       const requestId = crypto.randomUUID();
       const startedAt = Date.now();
       const sessionId = options?.sessionId ?? defaultSessionId;
       const url = modelRequestUrl(model);
+      const systemPrompt = "systemPrompt" in context && typeof context.systemPrompt === "string"
+        ? context.systemPrompt
+        : getCurrentSystemPrompt(context.messages);
       const notify = (event: PiGenerationLifecycleEvent) => {
         try {
           onGeneration?.(event);
@@ -516,7 +532,7 @@ export function withProviderBoundary(
         model: model.id,
         url,
         input: {
-          ...(context.systemPrompt ? { systemPrompt: context.systemPrompt } : {}),
+          ...(systemPrompt ? { systemPrompt } : {}),
           messages: context.messages,
         },
       });
@@ -708,7 +724,10 @@ function piApiFor(endpoint: RuntimeModelEndpoint): ProviderStreams {
         return openAICodexResponsesApi();
     }
   })();
-  const contextFor = (model: Model<Api>, context: Context): Context => ({
+  const contextFor = (
+    model: Model<Api>,
+    context: TranscriptContext,
+  ): TranscriptContext => ({
     ...context,
     messages: modelInputMessages(
       context.messages,
@@ -716,12 +735,12 @@ function piApiFor(endpoint: RuntimeModelEndpoint): ProviderStreams {
       adapterHostedInputModalities(protocol),
     ),
   });
-  return {
+  return overlayProviderStreams(api, {
     stream: (model, context, options) =>
       api.stream(model, contextFor(model, context), options),
     streamSimple: (model, context, options) =>
       api.streamSimple(model, contextFor(model, context), options),
-  };
+  });
 }
 
 function anthropicMessagesModelForOpenRouter(
@@ -866,9 +885,11 @@ export function configurePiModels(
       models: endpoint.models.map((modelId) =>
         configuredModel(endpoint, index, modelId),
       ),
-      // cloudflareStreams 在运行时把 baseURL 里的 {CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}
-      // 占位符替换成真实值；如果 baseURL 不含占位符则直接透传，不影响现有端点。
-      api: cloudflareStreams(piApiFor(endpoint)),
+      // remapProviderStreamModels 在运行时把 baseURL 里的
+      // {CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID} 占位符替换成真实值；
+      // 如果 baseURL 不含占位符则直接透传。Pi 自带的 cloudflareStreams 只保留
+      // stream / streamSimple，这里 spread 其余方法以免丢掉 deferred 入口。
+      api: remapProviderStreamModels(piApiFor(endpoint), resolveCloudflareModel),
     })
   );
   models.clearProviders();

package/src/models/openrouter/messages.ts

@@ -1,12 +1,14 @@
 import type {
-  Context,
   Model,
   ProviderStreams,
   StreamOptions,
+  TranscriptContext,
 } from "@earendil-works/pi-ai";
+import { getCurrentTools } from "@earendil-works/pi-ai";
 import {
   anthropicMessagesApi,
 } from "@earendil-works/pi-ai/api/anthropic-messages.lazy";
+import { overlayProviderStreams } from "../provider-streams";
 
 type Payload = Record<string, unknown>;
 
@@ -21,14 +23,16 @@ function record(value: unknown): Payload | undefined {
 function decoratePayload(
   payload: unknown,
   model: Model<"anthropic-messages">,
-  context: Context,
+  context: TranscriptContext,
   sessionId?: string,
 ): unknown {
   const body = record(payload);
   if (!body) throw new Error("OpenRouter Messages payload must be an object");
 
   const deferredNames = new Set(
-    context.tools?.filter((tool) => tool.deferLoading).map((tool) => tool.name),
+    getCurrentTools(context.messages)
+      .filter((tool) => tool.deferLoading)
+      .map((tool) => tool.name),
   );
   const tools = Array.isArray(body.tools) ? body.tools : [];
   const immediate: unknown[] = [];
@@ -80,7 +84,7 @@ function decoratePayload(
 
 function openRouterOptions(
   model: Model<"anthropic-messages">,
-  context: Context,
+  context: TranscriptContext,
   options: StreamOptions | undefined,
 ): StreamOptions {
   const apiKey = options?.apiKey;
@@ -107,9 +111,10 @@ function openRouterOptions(
   };
 }
 
-export function openRouterMessagesApi(): ProviderStreams {
-  const anthropic = anthropicMessagesApi();
-  return {
+export function openRouterMessagesApi(
+  anthropic: ProviderStreams = anthropicMessagesApi(),
+): ProviderStreams {
+  return overlayProviderStreams(anthropic, {
     stream: (model, context, options) =>
       anthropic.stream(
         model,
@@ -130,5 +135,5 @@ export function openRouterMessagesApi(): ProviderStreams {
           options,
         ),
       ),
-  };
+  });
 }

package/src/models/provider-streams.ts

@@ -0,0 +1,45 @@
+import type {
+  Api,
+  Model,
+  ProviderEnv,
+  ProviderStreams,
+} from "@earendil-works/pi-ai";
+
+/**
+ * ProviderStreams 是普通对象，不是 class。完整适配先 spread 底层全部方法，再覆盖需要装饰的入口。
+ * 只手写 stream / streamSimple 会丢掉 Pi 后续挂上的 fetchDeferred / cancelDeferred。
+ */
+export function overlayProviderStreams(
+  base: ProviderStreams,
+  overlay: Partial<ProviderStreams>,
+): ProviderStreams {
+  return { ...base, ...overlay };
+}
+
+/**
+ * 在保留其余方法的前提下，把每个已知的 model 入口改写到 remap 后的模型。
+ * 未知的未来方法仍通过 spread 透传，避免再出现白名单丢方法。
+ */
+export function remapProviderStreamModels(
+  streams: ProviderStreams,
+  remap: (model: Model<Api>, env: ProviderEnv | undefined) => Model<Api>,
+): ProviderStreams {
+  return overlayProviderStreams(streams, {
+    stream: (model, context, options) =>
+      streams.stream(remap(model, options?.env), context, options),
+    streamSimple: (model, context, options) =>
+      streams.streamSimple(remap(model, options?.env), context, options),
+    ...(streams.fetchDeferred
+      ? {
+          fetchDeferred: (model, handle, options) =>
+            streams.fetchDeferred!(remap(model, options?.env), handle, options),
+        }
+      : {}),
+    ...(streams.cancelDeferred
+      ? {
+          cancelDeferred: (model, handle, options) =>
+            streams.cancelDeferred!(remap(model, options?.env), handle, options),
+        }
+      : {}),
+  });
+}

package/src/session/cloudflare/migration.ts

@@ -436,7 +436,6 @@ function assertSameToolResult(
     "content",
     "details",
     "usage",
-    "addedToolNames",
     "isError",
   ] as const) {
     if (!isEqual(left[key], right[key]))
@@ -456,11 +455,8 @@ function legacyToolResultMessage(input: {
     toolCallId: input.toolCallId,
     toolName: input.toolName,
     content: input.result.content ?? [],
-    details: input.result.details,
+    details: input.result.details as JsonValue | undefined,
     ...(input.result.usage ? { usage: input.result.usage } : {}),
-    ...(input.result.addedToolNames?.length
-      ? { addedToolNames: input.result.addedToolNames }
-      : {}),
     isError: input.isError,
     timestamp: input.timestamp,
   };

package/src/tools/adapters/pi-to-ai.ts

@@ -1,5 +1,5 @@
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import { validateToolArguments } from "@earendil-works/pi-ai";
+import { validateToolArguments, type JsonObject } from "@earendil-works/pi-ai";
 import { tool as aiTool, jsonSchema, type ToolSet } from "ai";
 import type { PiToolCandidate } from "../runtime/contracts";
 
@@ -27,7 +27,7 @@ export function piCandidatesToAiTools(
           type: "toolCall",
           id: toolCallId,
           name: candidate.tool.name,
-          arguments: prepared as Record<string, unknown>,
+          arguments: prepared as JsonObject,
         });
         const result = await candidate.tool.execute(
           toolCallId,

package/src/tools/assistant/candidate.ts

@@ -2,7 +2,7 @@ import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { type TSchema } from "@earendil-works/pi-ai";
 import type { PiToolCandidate } from "../runtime/contracts";
 
-export function candidate<T extends TSchema>(tool: AgentTool<T>): PiToolCandidate {
+export function candidate<T extends TSchema, D = any>(tool: AgentTool<T, D>): PiToolCandidate<T, D> {
   return {
     owner: "runtime-base",
     requiredExecutionLevel: "safe",
@@ -10,6 +10,6 @@ export function candidate<T extends TSchema>(tool: AgentTool<T>): PiToolCandidat
     tool: {
       ...tool,
       constrainedSampling: { type: "json_schema", strict: "prefer" },
-    } as AgentTool<T>,
+    } as AgentTool<T, D>,
   };
 }

package/src/tools/assistant/followups.ts

@@ -19,7 +19,7 @@ export function suggestFollowupsPiToolCandidate(): PiToolCandidate {
       name: "suggest_followups",
       label: "Suggest follow-ups",
       description:
-        "Offer the user 2-4 optional follow-up directions after completing a substantive task (a report, an analysis, a multi-step job). Call this at most once, after all work and other Tool calls are complete. It MUST be the last Tool call before the final answer. After it returns, write the complete final answer and make no further Tool calls. Do NOT call it for small talk, quick answers, or while a task is still in progress.",
+        "Offer the user 2-4 optional follow-up directions for a completed substantive task. Call at most once.",
       parameters: suggestFollowupsParameters,
       async execute(_toolCallId, input) {
         return result({ noted: true, count: input.items.length });

package/src/tools/codemode/adapter.ts

@@ -164,13 +164,9 @@ function codeExecutionResult(
   details: unknown,
   innerResults: readonly AgentToolResult<unknown>[],
 ): AgentToolResult<unknown> {
-  const addedToolNames = [...new Set(
-    innerResults.flatMap(({ addedToolNames }) => addedToolNames ?? []),
-  )].sort();
   const usage = sumUsage(innerResults);
   return {
     ...result(details),
-    ...(addedToolNames.length > 0 ? { addedToolNames } : {}),
     ...(usage ? { usage } : {}),
     ...(innerResults.length > 0 && innerResults.every(({ terminate }) => terminate === true)
       ? { terminate: true }

package/src/tools/index.ts

@@ -3,6 +3,7 @@ export * from "./runtime/approval";
 export * from "./assistant";
 export * from "./runtime/contracts";
 export * from "./runtime/compiler";
+export * from "./runtime/activation";
 export * from "./codemode";
 export * from "./codemode/adapter";
 export * from "./extension";

package/src/tools/runtime/activation.ts

@@ -0,0 +1,40 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { PiToolCandidate } from "./contracts";
+
+/**
+ * 把 Candidate 上的按需激活声明收成 SessionHarness 可直接消费的选项。
+ *
+ * `inactiveUntilActivated` 的工具仍编译进 Harness，只是一开始不在活动集里。
+ * 其他工具成功返回后通过 `toolsToActivate` 点名，Harness 在 `after_tool`
+ * 里 `setActiveTools`，由 Pi Agent Loop 写成 transcript 的 `toolsAdded`。
+ */
+export function harnessToolActivation(candidates: readonly PiToolCandidate[]): {
+  readonly activeToolNames: string[];
+  readonly onDemandToolNames: readonly string[];
+  readonly toolsToActivate: (
+    toolName: string,
+    result: AgentToolResult<unknown>,
+    isError: boolean,
+  ) => readonly string[];
+} {
+  const compiled = candidates.map(({ tool }) => tool.name);
+  const onDemand = candidates
+    .filter((candidate) => candidate.inactiveUntilActivated === true)
+    .map(({ tool }) => tool.name);
+  const onDemandSet = new Set(onDemand);
+  const activators = new Map(
+    candidates.flatMap((candidate) =>
+      candidate.toolsToActivate
+        ? [[candidate.tool.name, candidate.toolsToActivate] as const]
+        : [],
+    ),
+  );
+  return {
+    activeToolNames: compiled.filter((name) => !onDemandSet.has(name)),
+    onDemandToolNames: onDemand,
+    toolsToActivate: (toolName, result, isError) => {
+      if (isError) return [];
+      return activators.get(toolName)?.(result) ?? [];
+    },
+  };
+}

package/src/tools/runtime/contracts.ts

@@ -1,4 +1,5 @@
 import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { TSchema } from "@earendil-works/pi-ai";
 import type { ApprovalReceipt } from "../../submission/contracts";
 import { type BudgetPolicy } from "../../context/memory/budget/gate";
 import { type SpillWorkspace } from "../../lib/artifacts";
@@ -45,12 +46,22 @@ export interface PiToolConfirmationSpec {
   execute(prepared: unknown, context: { intentId: string; signal: AbortSignal }): Promise<AgentToolResult<unknown>>;
 }
 
-export interface PiToolCandidate {
+/**
+ * 一份尚未进入最终 Tool Surface 的 Pi 工具及其治理字段。
+ *
+ * 单个工厂可以写成 `PiToolCandidate<typeof parameters, Details>`，把 Schema 和
+ * details 留在类型里。混进同一个 `PiToolCandidate[]` 时走默认擦除形式：
+ * `AgentTool` 在两个类型参数上都是不变的，只有默认 `any` 能收进异构列表。
+ */
+export interface PiToolCandidate<
+  TParameters extends TSchema = any,
+  TDetails = any,
+> {
   /** Presentation only, resolved at the model boundary; never changes approved execution inputs. */
   readonly modelGuidance?: () => Promise<{ description: string; systemPrompt?: string }>;
   readonly confirmation?: PiToolConfirmationSpec;
   readonly owner: string;
-  readonly tool: AgentTool<any, any>;
+  readonly tool: AgentTool<TParameters, TDetails>;
   /** @internal Send the complete schema but hide it until provider Tool Search finds it. */
   readonly deferLoading?: true;
   /** Omitted means visible both directly and through Code Mode. */
@@ -80,6 +91,18 @@ export interface PiToolCandidate {
   readonly interaction?: PiToolInteractionSpec;
   /** Large payloads spill by default; protocol-shaped results opt into structure. */
   readonly outputBudget?: BudgetPolicy;
+  /**
+   * 编进 Harness 工具表，但不进入初始 `setActiveTools`。
+   * 之后由其他 Tool 的 `toolsToActivate` 经 `setActiveTools` 写入 transcript `toolsAdded`。
+   */
+  readonly inactiveUntilActivated?: true;
+  /**
+   * 本次成功结果要把哪些已编译工具加入活动集。未知名字会被忽略。
+   * 替代已删除的 `AgentToolResult.addedToolNames`。
+   */
+  readonly toolsToActivate?: (
+    result: AgentToolResult<unknown>,
+  ) => readonly string[];
 }
 
 export interface CompileHarnessToolsOptions {

package/src/tools/schedule/index.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
-import { Type, fauxToolCall, validateToolArguments, type TSchema } from "@earendil-works/pi-ai";
+import { Type, fauxToolCall, validateToolArguments, type JsonObject, type TSchema } from "@earendil-works/pi-ai";
 import {
   toScheduleRuleSpec,
   validateScheduleRuleSpec,
@@ -261,7 +261,7 @@ export function schedulePiToolCandidates(
     return [{
       ...toolCandidate, alwaysRequiresApproval: true, confirmation: {
         async prepare(args, { intentId }) {
-          const validated = validateToolArguments(toolCandidate.tool, fauxToolCall(name, args as Record<string, unknown>));
+          const validated = validateToolArguments(toolCandidate.tool, fauxToolCall(name, args as JsonObject));
           const input = validated as { id?: string; prompt?: string; trigger?: ScheduleSpec["trigger"]; label?: string; timezone?: string };
           if (input.timezone !== undefined && !isValidTimeZone(input.timezone)) throw new Error("A valid IANA timezone is required");
           if (input.trigger?.kind === "local" && input.timezone) {