pi-workflow-engine 0.10.3 → 0.12.0

package/.pi/extensions/pi-workflow-engine/src/agent-session-identity.ts

@@ -0,0 +1,256 @@
+import { resolve } from "node:path";
+import { VERSION } from "@earendil-works/pi-coding-agent";
+import { throwIfAborted } from "./cancellation.ts";
+import { hashIdentity, inspectableFunctionSource } from "./identity-fingerprint.ts";
+import { normalizeWorkspaceReferences } from "./replay-path-identity.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+import {
+  captureEffectiveToolSourceIdentity,
+  type EffectiveToolSourceIdentity,
+  type EffectiveToolSourceInfoLike,
+  type ToolSourceFingerprintCache,
+} from "./tool-source-identity.ts";
+export type { EffectiveToolSourceIdentity, EffectiveToolSourceInfoLike } from "./tool-source-identity.ts";
+
+export interface EffectiveAgentModelLike {
+  readonly provider: string;
+  readonly id: string;
+}
+
+export interface EffectiveToolInfoLike {
+  readonly name: string;
+  readonly description: string;
+  readonly parameters: unknown;
+  readonly promptGuidelines?: readonly string[];
+  readonly sourceInfo: EffectiveToolSourceInfoLike;
+}
+
+/** Only execution-relevant fields are required; installed pi ToolDefinition values satisfy this shape. */
+export interface EffectiveToolDefinitionLike {
+  readonly name: string;
+  readonly description: string;
+  readonly parameters: unknown;
+  readonly promptSnippet?: string;
+  readonly promptGuidelines?: readonly string[];
+  readonly executionMode?: string;
+  readonly prepareArguments?: unknown;
+  readonly execute: unknown;
+}
+
+/** Structural subset of AgentSession so lightweight fakes can verify replay identity behavior. */
+export interface EffectiveAgentSessionLike {
+  readonly systemPrompt: string;
+  readonly model: EffectiveAgentModelLike | undefined;
+  readonly thinkingLevel: string;
+  getActiveToolNames(): readonly string[];
+  getAllTools(): readonly EffectiveToolInfoLike[];
+  getToolDefinition(name: string): EffectiveToolDefinitionLike | undefined;
+}
+
+export interface EffectiveToolIdentity {
+  readonly name: string;
+  readonly definitionFingerprint: string;
+  readonly implementationFingerprint: string;
+  readonly source: EffectiveToolSourceIdentity;
+}
+
+export interface EffectiveAgentSessionIdentity {
+  readonly fingerprint: string;
+  readonly runtimeVersion: string;
+  readonly systemPromptFingerprint: string;
+  readonly model: EffectiveAgentModelLike;
+  readonly thinkingLevel: string;
+  /** Ordered exactly as the effective AgentSession reports its active tools. */
+  readonly tools: readonly EffectiveToolIdentity[];
+}
+
+export type EffectiveAgentSessionIdentityCapture =
+  | { readonly kind: "verified"; readonly identity: EffectiveAgentSessionIdentity }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+export interface EffectiveAgentSessionIdentityOptions {
+  /** Stable main-workspace root used as the logical path namespace across replay attempts. */
+  readonly workspaceRoot: string;
+  /** Effective cwd used to create the session, which may be a randomized disposable worktree. */
+  readonly sessionCwd: string;
+  /** Override only for tests or a host embedding a version-compatible coding-agent runtime. */
+  readonly runtimeVersion?: string;
+  readonly signal?: AbortSignal;
+}
+
+interface IdentityComponents {
+  readonly runtimeVersion: string;
+  readonly systemPromptFingerprint: string;
+  readonly model: EffectiveAgentModelLike;
+  readonly thinkingLevel: string;
+  readonly tools: readonly EffectiveToolIdentity[];
+}
+
+/**
+ * Capture the post-creation AgentSession state that determines whether a cached
+ * agent result is safe to replay. Any missing or opaque executable identity
+ * fails closed instead of producing a partial key.
+ */
+export async function captureEffectiveAgentSessionIdentity(
+  session: EffectiveAgentSessionLike,
+  options: EffectiveAgentSessionIdentityOptions,
+): Promise<EffectiveAgentSessionIdentityCapture> {
+  try {
+    throwIfAborted(options.signal);
+    const workspaceRoot = resolve(nonEmptyString(options.workspaceRoot, "workspace root"));
+    const sessionCwd = resolve(nonEmptyString(options.sessionCwd, "session cwd"));
+    const runtimeVersion = nonEmptyString(options.runtimeVersion ?? VERSION, "coding-agent runtime version");
+    const systemPrompt = stringValue(session.systemPrompt, "effective system prompt");
+    const thinkingLevel = nonEmptyString(session.thinkingLevel, "effective thinking level");
+    const model = captureModel(session.model);
+    const activeToolNames = captureActiveToolNames(session.getActiveToolNames());
+    const toolInfoByName = indexToolInfo(session.getAllTools());
+    const sourceCaptures: ToolSourceFingerprintCache = new Map();
+    const tools: EffectiveToolIdentity[] = [];
+
+    for (const name of activeToolNames) {
+      throwIfAborted(options.signal);
+      const info = toolInfoByName.get(name);
+      if (!info) throw new Error(`active tool "${name}" is absent from the tool registry`);
+      const definition = session.getToolDefinition(name);
+      if (!definition) throw new Error(`active tool "${name}" has no executable definition`);
+      tools.push(
+        await captureToolIdentity(name, info, definition, {
+          runtimeVersion,
+          signal: options.signal,
+          sessionCwd,
+          sourceCaptures,
+          workspaceRoot,
+        }),
+      );
+    }
+
+    const components: IdentityComponents = {
+      runtimeVersion,
+      systemPromptFingerprint: hashIdentity(
+        normalizeWorkspaceReferences(systemPrompt, { sessionCwd, workspaceRoot }),
+      ),
+      model,
+      thinkingLevel,
+      tools,
+    };
+    return {
+      kind: "verified",
+      identity: {
+        fingerprint: hashIdentity(components),
+        ...components,
+      },
+    };
+  } catch (error) {
+    throwIfAborted(options.signal);
+    return { kind: "unverifiable", reason: unknownErrorMessage(error) };
+  }
+}
+
+interface ToolCaptureOptions {
+  readonly runtimeVersion: string;
+  readonly sessionCwd: string;
+  readonly workspaceRoot: string;
+  readonly sourceCaptures: ToolSourceFingerprintCache;
+  readonly signal?: AbortSignal;
+}
+
+async function captureToolIdentity(
+  name: string,
+  info: EffectiveToolInfoLike,
+  definition: EffectiveToolDefinitionLike,
+  options: ToolCaptureOptions,
+): Promise<EffectiveToolIdentity> {
+  if (nonEmptyString(info.name, `registry name for active tool "${name}"`) !== name) {
+    throw new Error(`tool registry returned a mismatched definition for "${name}"`);
+  }
+  if (nonEmptyString(definition.name, `definition name for active tool "${name}"`) !== name) {
+    throw new Error(`tool definition returned a mismatched definition for "${name}"`);
+  }
+
+  const registryGuidelines = stringArray(info.promptGuidelines ?? [], `prompt guidelines for active tool "${name}"`);
+  const definitionGuidelines = stringArray(definition.promptGuidelines ?? [], `definition prompt guidelines for active tool "${name}"`);
+  const executeSource = inspectableFunctionSource(definition.execute, `execute handler for active tool "${name}"`);
+  const prepareArgumentsSource =
+    definition.prepareArguments === undefined
+      ? null
+      : inspectableFunctionSource(definition.prepareArguments, `argument-preparation handler for active tool "${name}"`);
+  const source = await captureEffectiveToolSourceIdentity(info.sourceInfo, {
+    runtimeVersion: options.runtimeVersion,
+    sessionCwd: options.sessionCwd,
+    workspaceRoot: options.workspaceRoot,
+    cache: options.sourceCaptures,
+    signal: options.signal,
+  });
+
+  return {
+    name,
+    definitionFingerprint: hashIdentity({
+      registry: {
+        description: stringValue(info.description, `description for active tool "${name}"`),
+        parameters: info.parameters,
+        promptGuidelines: registryGuidelines,
+      },
+      definition: {
+        description: stringValue(definition.description, `definition description for active tool "${name}"`),
+        parameters: definition.parameters,
+        promptSnippet: optionalString(definition.promptSnippet, `prompt snippet for active tool "${name}"`),
+        promptGuidelines: definitionGuidelines,
+        executionMode: optionalString(definition.executionMode, `execution mode for active tool "${name}"`),
+      },
+    }),
+    implementationFingerprint: hashIdentity({ executeSource, prepareArgumentsSource }),
+    source,
+  };
+}
+
+function captureModel(model: EffectiveAgentModelLike | undefined): EffectiveAgentModelLike {
+  if (!model) throw new Error("effective model is unavailable");
+  return {
+    provider: nonEmptyString(model.provider, "effective model provider"),
+    id: nonEmptyString(model.id, "effective model id"),
+  };
+}
+
+function captureActiveToolNames(names: readonly string[]): readonly string[] {
+  if (!Array.isArray(names)) throw new Error("active tool names are unavailable");
+  const seen = new Set<string>();
+  return names.map((value, index) => {
+    const name = nonEmptyString(value, `active tool name at index ${index}`);
+    if (seen.has(name)) throw new Error(`active tool list contains duplicate "${name}" entries`);
+    seen.add(name);
+    return name;
+  });
+}
+
+function indexToolInfo(tools: readonly EffectiveToolInfoLike[]): ReadonlyMap<string, EffectiveToolInfoLike> {
+  if (!Array.isArray(tools)) throw new Error("tool registry is unavailable");
+  const indexed = new Map<string, EffectiveToolInfoLike>();
+  for (const [index, tool] of tools.entries()) {
+    const name = nonEmptyString(tool.name, `tool registry name at index ${index}`);
+    if (indexed.has(name)) throw new Error(`tool registry contains duplicate "${name}" entries`);
+    indexed.set(name, tool);
+  }
+  return indexed;
+}
+
+function stringArray(value: readonly string[], label: string): readonly string[] {
+  if (!Array.isArray(value) || !value.every((entry) => typeof entry === "string")) throw new Error(`${label} must be a string array`);
+  return [...value];
+}
+
+function optionalString(value: string | undefined, label: string): string | null {
+  if (value === undefined) return null;
+  return stringValue(value, label);
+}
+
+function nonEmptyString(value: string, label: string): string {
+  const result = stringValue(value, label);
+  if (result.length === 0) throw new Error(`${label} is empty`);
+  return result;
+}
+
+function stringValue(value: string, label: string): string {
+  if (typeof value !== "string") throw new Error(`${label} is not a string`);
+  return value;
+}

package/.pi/extensions/pi-workflow-engine/src/agent-session-providers.ts

@@ -0,0 +1,50 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ModelRegistry, ModelRuntime } from "@earendil-works/pi-coding-agent";
+
+type HostProviderRegistry = Pick<
+  ModelRegistry,
+  | "getApiKeyForProvider"
+  | "getProviderAuthStatus"
+  | "getRegisteredProviderConfig"
+  | "getRegisteredProviderIds"
+  | "isUsingOAuth"
+>;
+
+/** Mirror the host's live provider and selected-model auth state into a child runtime. */
+export async function synchronizeWorkflowModelRuntime(input: {
+  readonly host: HostProviderRegistry;
+  readonly child: ModelRuntime;
+  readonly selectedModel: Model<Api> | undefined;
+  readonly removeChildOnlyProviders: boolean;
+}): Promise<void> {
+  const { host, child, selectedModel, removeChildOnlyProviders } = input;
+  const hostProviderIds = new Set(host.getRegisteredProviderIds());
+
+  if (removeChildOnlyProviders) {
+    for (const providerId of child.getRegisteredProviderIds()) {
+      if (!hostProviderIds.has(providerId)) child.unregisterProvider(providerId);
+    }
+  }
+
+  for (const providerId of hostProviderIds) {
+    const config = host.getRegisteredProviderConfig(providerId);
+    if (!config) continue;
+    child.unregisterProvider(providerId);
+    child.registerProvider(providerId, config);
+  }
+
+  const selectedProvider = selectedModel?.provider;
+  if (!selectedModel || !selectedProvider) return;
+
+  const hostAuth = host.getProviderAuthStatus(selectedProvider);
+  const childAuth = child.getProviderAuthStatus(selectedProvider);
+  if (hostAuth.configured && !childAuth.configured && host.isUsingOAuth(selectedModel)) {
+    throw new Error(
+      `Workflow subagents cannot inherit OAuth credentials for "${selectedProvider}" from a host-only credential store; configure OAuth in Pi's shared agent directory.`,
+    );
+  }
+  if (hostAuth.source === "runtime" || (hostAuth.configured && !childAuth.configured)) {
+    const apiKey = await host.getApiKeyForProvider(selectedProvider);
+    if (apiKey !== undefined) await child.setRuntimeApiKey(selectedProvider, apiKey);
+  }
+}

package/.pi/extensions/pi-workflow-engine/src/agent-session.ts

@@ -0,0 +1,368 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import {
+  createAgentSessionFromServices,
+  createAgentSessionServices,
+  defineTool,
+  SessionManager,
+  type CreateAgentSessionOptions,
+  type ModelRegistry,
+  type Skill,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { prepareAgentSkillResources } from "./agent-skills.ts";
+import type {
+  AgentExecutionOptions,
+  AgentRunTags,
+  AgentRunnerSession,
+  RunContext,
+} from "./agent-runner-types.ts";
+import { raceWithAbort, throwIfAborted } from "./cancellation.ts";
+import {
+  MAX_SCHEMA_REPAIR_ATTEMPTS,
+  WorkflowStructuredOutputError,
+} from "./structured-output.ts";
+import { providerErrorFromMessages } from "./agent-retry.ts";
+import { synchronizeWorkflowModelRuntime } from "./agent-session-providers.ts";
+import { matchesAgentToolHint, WorkflowToolHintUnavailableError } from "./tool-capabilities.ts";
+import type { AgentToolHint } from "./types.ts";
+
+export const FINAL_TOOL = "final_answer";
+
+const SCHEMA_REPROMPT =
+  `You ended your turn without calling the ${FINAL_TOOL} tool, so no result was recorded. ` +
+  `Call ${FINAL_TOOL} now with your final answer as its arguments. Do not reply with plain text.`;
+const DEFAULT_SEARCH_BASE_TOOLS = ["read", "bash", "grep", "find", "ls"];
+
+export interface ResolvedAgentModelRequest {
+  readonly ref: string;
+  readonly provider: string;
+  readonly id: string;
+}
+
+export interface ResolvedAgentModel {
+  readonly model: Model<Api> | undefined;
+  readonly requested: ResolvedAgentModelRequest | undefined;
+}
+
+export interface AgentSessionHandle {
+  readonly session: AgentRunnerSession;
+  readonly selectedSkills: readonly Skill[];
+  hasStructuredResult(): boolean;
+  structuredResult(): unknown;
+}
+
+export function resolveAgentModel(
+  modelRef: string | undefined,
+  modelRegistry: Pick<ModelRegistry, "find">,
+  hostModel: Model<Api> | undefined,
+): ResolvedAgentModel {
+  if (modelRef === undefined) return { model: hostModel, requested: undefined };
+
+  const parsed = parseAgentModelRef(modelRef);
+  const found = modelRegistry.find(parsed.provider, parsed.id);
+  if (!found) {
+    throw new Error(`Agent model "${modelRef}" not found (resolved as ${parsed.provider}/${parsed.id}).`);
+  }
+  return { model: found, requested: parsed };
+}
+
+export async function openAgentSession(input: {
+  readonly rc: RunContext;
+  readonly prompt: string;
+  readonly opts: AgentExecutionOptions;
+  readonly cwd: string;
+  readonly model: Model<Api> | undefined;
+  readonly label: string;
+  readonly tags: AgentRunTags;
+}): Promise<AgentSessionHandle> {
+  const { rc, prompt, opts, cwd, model, label, tags } = input;
+  let captured = false;
+  let structuredResult: unknown;
+  const customTools: ToolDefinition[] = opts.schema
+    ? [
+        defineTool({
+          name: FINAL_TOOL,
+          label: "Final Answer",
+          description:
+            "Return your final structured answer. This MUST be your last action — do not write a normal reply after calling it.",
+          parameters: opts.schema,
+          async execute(_toolCallId, params) {
+            captured = true;
+            structuredResult = params;
+            return { content: [{ type: "text", text: "Recorded." }], details: params, terminate: true };
+          },
+        }),
+      ]
+    : [];
+  let session: AgentRunnerSession | undefined;
+  try {
+    throwIfAborted(rc.signal);
+    const resourceInput = { rc, prompt, opts, cwd, model, customTools, label };
+    const resources = rc.createSession
+      ? await prepareAgentSessionResources(resourceInput)
+      : await rc.perf.time(
+          "agent.session_resources_ms",
+          () => prepareAgentSessionResources(resourceInput),
+          tags,
+        );
+    const toolSelection = buildToolSelection(opts, resources.selectedSkills.length > 0);
+    session = (
+      await rc.perf.time(
+        "agent.create_session_ms",
+        () => resources.createSession(toolSelection.sessionOptions),
+        tags,
+      )
+    ).session;
+    session.setAutoRetryEnabled(false);
+    const matchedToolHints = toolSelection.toolHints.length === 0
+      ? new Set<AgentToolHint>()
+      : applyDynamicToolHints(session, toolSelection);
+    if (opts.requireToolHints) {
+      const missing = toolSelection.toolHints.filter((hint) => !matchedToolHints.has(hint));
+      if (missing.length > 0) throw new WorkflowToolHintUnavailableError(missing);
+    }
+    throwIfAborted(rc.signal);
+    return {
+      session,
+      selectedSkills: resources.selectedSkills,
+      hasStructuredResult: () => captured,
+      structuredResult: () => structuredResult,
+    };
+  } catch (error) {
+    if (session) {
+      const activeSession = session;
+      session = undefined;
+      rc.perf.timeSync("agent.dispose_ms", () => activeSession.dispose(), tags);
+    }
+    throw error;
+  }
+}
+
+export async function promptAgentSession(input: {
+  readonly rc: RunContext;
+  readonly handle: AgentSessionHandle;
+  readonly prompt: string;
+  readonly opts: AgentExecutionOptions;
+  readonly label: string;
+  readonly rowId: number;
+  readonly tags: AgentRunTags;
+}): Promise<unknown> {
+  const { rc, handle, prompt, opts, label, rowId, tags } = input;
+  const { session } = handle;
+  const unsubscribe = session.subscribe((event) => {
+    if (event.type === "tool_execution_start" && event.toolName !== undefined && event.toolName !== FINAL_TOOL) {
+      rc.progress.agentTool(label, event.toolName, rowId);
+    }
+  });
+
+  try {
+    const finalPrompt = opts.schema
+      ? `${prompt}\n\nWhen finished, return your result by calling the ${FINAL_TOOL} tool.`
+      : prompt;
+    throwIfAborted(rc.signal);
+    const unlinkPromptAbort = linkSessionAbort(rc.signal, session);
+    try {
+      try {
+        const promptSession = async (text: string) => {
+          await rc.perf.time("agent.prompt_ms", () => raceWithAbort(() => session.prompt(text), rc.signal), tags);
+          const failure = providerErrorFromMessages(session.messages, {
+            pauseOnUsageLimit: rc.pauseOnProviderUsageLimit,
+          });
+          if (failure) throw failure;
+        };
+        await promptSession(finalPrompt);
+        if (opts.schema) {
+          for (let attempt = 0; !handle.hasStructuredResult() && attempt < MAX_SCHEMA_REPAIR_ATTEMPTS; attempt++) {
+            throwIfAborted(rc.signal);
+            session.setActiveToolsByName([FINAL_TOOL]);
+            rc.progress.log(`${label}: no final answer; re-prompting (${attempt + 1}/${MAX_SCHEMA_REPAIR_ATTEMPTS})`);
+            rc.perf.counter("agent.structured_reprompt", 1, tags);
+            await promptSession(SCHEMA_REPROMPT);
+          }
+        }
+
+        throwIfAborted(rc.signal);
+        return rc.perf.timeSync(
+          "agent.extract_result_ms",
+          () => {
+            if (!opts.schema) {
+              return session.getLastAssistantText() ?? "";
+            }
+            if (!handle.hasStructuredResult()) {
+              rc.progress.log(`${label}: no structured answer returned`);
+              rc.perf.counter("agent.structured_missing", 1, tags);
+              throw new WorkflowStructuredOutputError(label, MAX_SCHEMA_REPAIR_ATTEMPTS);
+            }
+            return handle.structuredResult();
+          },
+          tags,
+        );
+      } finally {
+        rc.usage.recordAgentSession({ label, phase: tags.phase, messages: session.messages });
+      }
+    } finally {
+      unlinkPromptAbort();
+    }
+  } finally {
+    unsubscribe();
+  }
+}
+
+function parseAgentModelRef(modelRef: string): ResolvedAgentModelRequest {
+  const normalized = modelRef.trim();
+  if (normalized.length === 0) {
+    throw new Error('Invalid agent model ref: expected a bare model id or "provider/id".');
+  }
+  if (normalized !== modelRef) {
+    throw new Error(`Invalid agent model ref "${modelRef}": remove leading or trailing whitespace.`);
+  }
+
+  const slash = modelRef.indexOf("/");
+  if (slash === -1) return { ref: modelRef, provider: "anthropic", id: modelRef };
+  const provider = modelRef.slice(0, slash);
+  const id = modelRef.slice(slash + 1);
+  if (provider.length === 0 || id.length === 0 || id.startsWith("/")) {
+    throw new Error(`Invalid agent model ref "${modelRef}": expected "provider/id".`);
+  }
+  return { ref: modelRef, provider, id };
+}
+
+interface AgentSessionResources {
+  readonly selectedSkills: readonly Skill[];
+  createSession(sessionOptions: ToolSessionOptions): Promise<{ session: AgentRunnerSession }>;
+}
+
+async function prepareAgentSessionResources(input: {
+  readonly rc: RunContext;
+  readonly prompt: string;
+  readonly opts: AgentExecutionOptions;
+  readonly cwd: string;
+  readonly model: Model<Api> | undefined;
+  readonly customTools: ToolDefinition[];
+  readonly label: string;
+}): Promise<AgentSessionResources> {
+  const { rc, prompt, opts, cwd, model, customTools, label } = input;
+  const commonSessionOptions = (sessionOptions: ToolSessionOptions) => ({
+    model,
+    thinkingLevel: opts.thinkingLevel,
+    noTools: sessionOptions.noTools,
+    tools: sessionOptions.tools,
+    customTools,
+    sessionManager: SessionManager.inMemory(cwd),
+  });
+  const createSession = rc.createSession;
+  if (createSession) {
+    return {
+      selectedSkills: [],
+      createSession: (sessionOptions) =>
+        createSession({
+          cwd,
+          ...commonSessionOptions(sessionOptions),
+        }),
+    };
+  }
+
+  const skillOptions = {
+    prompt,
+    skills: opts.skills,
+    log: (message: string) => rc.progress.log(`${label}: ${message}`),
+  };
+  const preparedSkills = prepareAgentSkillResources(skillOptions);
+  const services = await createAgentSessionServices({
+    cwd,
+    resourceLoaderOptions: preparedSkills.resourceLoaderOptions,
+  });
+  await synchronizeWorkflowModelRuntime({
+    host: rc.modelRegistry,
+    child: services.modelRuntime,
+    selectedModel: model,
+    // Shared-cwd sessions mirror live removals; isolated cwd sessions retain target-only providers.
+    removeChildOnlyProviders: cwd === rc.cwd,
+  });
+  for (const diagnostic of services.diagnostics) {
+    rc.progress.log(`${label}: session ${diagnostic.type}: ${diagnostic.message}`);
+  }
+  const selectedSkills = preparedSkills.resolve(services.resourceLoader);
+  return {
+    selectedSkills,
+    createSession: (sessionOptions) =>
+      createAgentSessionFromServices({
+        services,
+        ...commonSessionOptions(sessionOptions),
+      }),
+  };
+}
+
+function linkSessionAbort(signal: AbortSignal | undefined, session: AgentRunnerSession): () => void {
+  if (!signal) return () => {};
+  const onAbort = () => {
+    void session.abort().catch(() => undefined);
+  };
+  if (signal.aborted) {
+    onAbort();
+    return () => {};
+  }
+  signal.addEventListener("abort", onAbort, { once: true });
+  return () => signal.removeEventListener("abort", onAbort);
+}
+
+type ToolSessionOptions = Pick<CreateAgentSessionOptions, "tools" | "noTools">;
+
+interface ToolSelection {
+  readonly sessionOptions: ToolSessionOptions;
+  readonly activeTools?: readonly string[];
+  readonly toolHints: NonNullable<AgentExecutionOptions["toolHints"]>;
+}
+
+function buildToolSelection(opts: AgentExecutionOptions, skillsEnabled: boolean): ToolSelection {
+  const toolHints = opts.toolHints ?? [];
+  const fallback = toolHints.includes("search")
+    ? DEFAULT_SEARCH_BASE_TOOLS
+    : toolHints.includes("external-search")
+      ? ["read"]
+      : undefined;
+  const activeTools = buildToolList(opts, skillsEnabled, fallback);
+  if (toolHints.length === 0) {
+    return {
+      sessionOptions: { tools: activeTools ? [...activeTools] : undefined },
+      activeTools,
+      toolHints,
+    };
+  }
+
+  return {
+    sessionOptions: { noTools: "builtin" },
+    activeTools,
+    toolHints,
+  };
+}
+
+function buildToolList(
+  opts: AgentExecutionOptions,
+  skillsEnabled: boolean,
+  fallback?: readonly string[],
+): string[] | undefined {
+  const configured = opts.tools ?? fallback;
+  const allow = configured ? [...configured] : undefined;
+  if (!allow) return undefined;
+  if (skillsEnabled && !allow.includes("read")) allow.push("read");
+  if (opts.schema && !allow.includes(FINAL_TOOL)) allow.push(FINAL_TOOL);
+  return allow;
+}
+
+function applyDynamicToolHints(
+  session: AgentRunnerSession,
+  selection: ToolSelection,
+): ReadonlySet<AgentToolHint> {
+  const active = new Set(selection.activeTools ?? []);
+  const matched = new Set<AgentToolHint>();
+  for (const tool of session.getAllTools()) {
+    for (const hint of selection.toolHints) {
+      if (!matchesAgentToolHint(tool, hint)) continue;
+      matched.add(hint);
+      active.add(tool.name);
+    }
+  }
+  session.setActiveToolsByName([...active]);
+  return matched;
+}