pi-workflow-engine 0.10.2 → 0.11.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.ts

@@ -0,0 +1,413 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import {
+  createAgentSession,
+  defineTool,
+  SessionManager,
+  type CreateAgentSessionOptions,
+  type ModelRegistry,
+  type Skill,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import {
+  appendSkillReminder,
+  createAgentSkillResourceLoader,
+  extractSkillSelectorsFromText,
+} from "./agent-skills.ts";
+import type {
+  AgentExecutionOptions,
+  AgentRunTags,
+  AgentRunnerSession,
+  AgentRunnerToolInfo,
+  RunContext,
+} from "./agent-runner-types.ts";
+import {
+  captureEffectiveAgentSessionIdentity,
+  type EffectiveAgentSessionIdentity,
+  type EffectiveToolInfoLike,
+} from "./agent-session-identity.ts";
+import { throwIfAborted } from "./cancellation.ts";
+
+export const FINAL_TOOL = "final_answer";
+
+const SCHEMA_REPROMPT_ATTEMPTS = 1;
+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 BUILTIN_TOOL_NAMES = ["read", "bash", "edit", "write", "grep", "find", "ls"] as const;
+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[];
+  structuredResult(): unknown;
+}
+
+export type EffectiveSessionCapture =
+  | { readonly kind: "verified"; readonly identity: EffectiveAgentSessionIdentity }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+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;
+  const skillSetup = shouldCreateSkillResourceLoader(rc, prompt, opts)
+    ? await rc.perf.time(
+        "agent.skills_ms",
+        () =>
+          createAgentSkillResourceLoader({
+            cwd,
+            prompt,
+            skills: opts.skills,
+            log: (message) => rc.progress.log(`${label}: ${message}`),
+          }),
+        tags,
+      )
+    : undefined;
+  const selectedSkills = skillSetup?.selectedSkills ?? [];
+  const toolSelection = buildToolSelection(opts, selectedSkills.length > 0);
+  let captured: unknown = null;
+  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 = params;
+            return { content: [{ type: "text", text: "Recorded." }], details: params, terminate: true };
+          },
+        }),
+      ]
+    : [];
+  const createSessionForRun = rc.createSession ?? defaultCreateSession;
+  const createSubagentSession = (sessionOptions: ToolSessionOptions) =>
+    rc.perf.time(
+      "agent.create_session_ms",
+      () =>
+        createSessionForRun({
+          cwd,
+          model,
+          modelRegistry: rc.modelRegistry as ModelRegistry,
+          thinkingLevel: opts.thinkingLevel,
+          tools: sessionOptions.tools,
+          excludeTools: sessionOptions.excludeTools,
+          customTools,
+          resourceLoader: skillSetup?.resourceLoader,
+          sessionManager: SessionManager.inMemory(cwd),
+        }),
+      tags,
+    );
+
+  let session: AgentRunnerSession | undefined;
+  try {
+    throwIfAborted(rc.signal);
+    session = (await createSubagentSession(toolSelection.sessionOptions)).session;
+    const dynamicToolHintsApplied = toolSelection.toolHints.length === 0 || applyDynamicToolHints(session, toolSelection);
+    if (!dynamicToolHintsApplied) {
+      rc.progress.log(`${label}: dynamic tool hints unavailable; falling back to concrete tools only`);
+      rc.perf.counter("agent.tool_hint_fallback", 1, tags);
+      const dynamicSession = session;
+      session = undefined;
+      rc.perf.timeSync("agent.dispose_ms", () => dynamicSession.dispose(), tags);
+      throwIfAborted(rc.signal);
+      session = (await createSubagentSession(toolSelection.fallbackSessionOptions)).session;
+    }
+    throwIfAborted(rc.signal);
+    return { session, selectedSkills, structuredResult: () => captured };
+  } 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, selectedSkills } = 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 promptedWithSkills = appendSkillReminder(prompt, selectedSkills);
+    const finalPrompt = opts.schema
+      ? `${promptedWithSkills}\n\nWhen finished, return your result by calling the ${FINAL_TOOL} tool.`
+      : promptedWithSkills;
+    throwIfAborted(rc.signal);
+    const unlinkPromptAbort = linkSessionAbort(rc.signal, session);
+    try {
+      try {
+        await rc.perf.time("agent.prompt_ms", () => session.prompt(finalPrompt), tags);
+        if (opts.schema) {
+          for (let attempt = 0; handle.structuredResult() === null && attempt < SCHEMA_REPROMPT_ATTEMPTS; attempt++) {
+            throwIfAborted(rc.signal);
+            rc.progress.log(`${label}: no final answer; re-prompting (${attempt + 1}/${SCHEMA_REPROMPT_ATTEMPTS})`);
+            rc.perf.counter("agent.structured_reprompt", 1, tags);
+            await rc.perf.time("agent.prompt_ms", () => session.prompt(SCHEMA_REPROMPT), tags);
+          }
+        }
+
+        throwIfAborted(rc.signal);
+        return rc.perf.timeSync(
+          "agent.extract_result_ms",
+          () => {
+            if (!opts.schema) return lastAssistantText(session.state);
+            const result = handle.structuredResult();
+            if (result === null) {
+              rc.progress.log(`${label}: no structured answer returned`);
+              rc.perf.counter("agent.structured_missing", 1, tags);
+            }
+            return result;
+          },
+          tags,
+        );
+      } finally {
+        rc.usage.recordAgentSession({ label, phase: tags.phase, messages: session.state.messages });
+      }
+    } finally {
+      unlinkPromptAbort();
+    }
+  } finally {
+    unsubscribe();
+  }
+}
+
+export async function captureEffectiveSession(
+  session: AgentRunnerSession,
+  sessionCwd: string,
+  workspaceRoot: string,
+  signal: AbortSignal | undefined,
+): Promise<EffectiveSessionCapture> {
+  const state = session.state;
+  if (typeof state.systemPrompt !== "string") {
+    return { kind: "unverifiable", reason: "effective system prompt is unavailable" };
+  }
+  if (!state.model) return { kind: "unverifiable", reason: "effective model is unavailable" };
+  if (typeof state.thinkingLevel !== "string") {
+    return { kind: "unverifiable", reason: "effective thinking level is unavailable" };
+  }
+  if (!session.getActiveToolNames || !session.getAllTools || !session.getToolDefinition) {
+    return { kind: "unverifiable", reason: "effective tool APIs are unavailable" };
+  }
+  const toolInfos = effectiveToolInfos(session.getAllTools());
+  if (toolInfos.kind === "unverifiable") return toolInfos;
+  return await captureEffectiveAgentSessionIdentity(
+    {
+      systemPrompt: state.systemPrompt,
+      model: state.model,
+      thinkingLevel: state.thinkingLevel,
+      getActiveToolNames: () => session.getActiveToolNames!(),
+      getAllTools: () => toolInfos.tools,
+      getToolDefinition: (name) => session.getToolDefinition!(name),
+    },
+    { sessionCwd, workspaceRoot, signal },
+  );
+}
+
+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 };
+}
+
+async function defaultCreateSession(options: CreateAgentSessionOptions): Promise<{ session: AgentRunnerSession }> {
+  const { session } = await createAgentSession(options);
+  return { session };
+}
+
+function linkSessionAbort(signal: AbortSignal | undefined, session: AgentRunnerSession): () => void {
+  if (!signal) return () => {};
+  if (signal.aborted) {
+    void session.abort();
+    return () => {};
+  }
+  const onAbort = () => {
+    void session.abort();
+  };
+  signal.addEventListener("abort", onAbort, { once: true });
+  return () => signal.removeEventListener("abort", onAbort);
+}
+
+type ToolSessionOptions = Pick<CreateAgentSessionOptions, "tools" | "excludeTools">;
+
+interface ToolSelection {
+  readonly sessionOptions: ToolSessionOptions;
+  readonly fallbackSessionOptions: ToolSessionOptions;
+  readonly activeTools?: readonly string[];
+  readonly toolHints: NonNullable<AgentExecutionOptions["toolHints"]>;
+}
+
+interface DynamicToolSession extends AgentRunnerSession {
+  getAllTools(): readonly AgentRunnerToolInfo[];
+  setActiveToolsByName(toolNames: readonly string[]): void;
+}
+
+function buildToolSelection(opts: AgentExecutionOptions, skillsEnabled: boolean): ToolSelection {
+  const toolHints = opts.toolHints ?? [];
+  const fallback = toolHints.includes("search") ? DEFAULT_SEARCH_BASE_TOOLS : undefined;
+  const activeTools = buildToolList(opts, skillsEnabled, fallback);
+  const strictSessionOptions = { tools: activeTools ? [...activeTools] : undefined };
+  if (toolHints.length === 0) {
+    return { sessionOptions: strictSessionOptions, fallbackSessionOptions: strictSessionOptions, activeTools, toolHints };
+  }
+
+  const explicitlyActive = new Set(activeTools ?? []);
+  return {
+    sessionOptions: { excludeTools: BUILTIN_TOOL_NAMES.filter((name) => !explicitlyActive.has(name)) },
+    fallbackSessionOptions: { tools: activeTools ? [...activeTools] : [] },
+    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): boolean {
+  if (!hasDynamicToolApis(session)) return false;
+
+  const active = new Set(selection.activeTools ?? []);
+  for (const tool of session.getAllTools()) {
+    if (selection.toolHints.some((hint) => hint === "search" && isSearchLikeTool(tool))) active.add(tool.name);
+  }
+  session.setActiveToolsByName([...active]);
+  return true;
+}
+
+function hasDynamicToolApis(session: AgentRunnerSession): session is DynamicToolSession {
+  return typeof session.getAllTools === "function" && typeof session.setActiveToolsByName === "function";
+}
+
+function isSearchLikeTool(tool: AgentRunnerToolInfo): boolean {
+  if (/(?:^|[-_])(?:edit|write|replace|patch|apply|delete|remove|move|rename|create|commit|push)(?:$|[-_])/.test(tool.name.toLowerCase())) {
+    return false;
+  }
+  const name = tool.name.toLowerCase();
+  if (name.includes("grep") || name.includes("find") || name.includes("search") || name === "rg" || name.includes("ripgrep")) return true;
+  return /\b(?:grep|find|search|ripgrep|rg|structural search|code search)\b/.test(tool.description?.toLowerCase() ?? "");
+}
+
+function shouldCreateSkillResourceLoader(rc: RunContext, prompt: string, opts: AgentExecutionOptions): boolean {
+  return !rc.createSession || opts.skills !== undefined || extractSkillSelectorsFromText(prompt).length > 0;
+}
+
+function effectiveToolInfos(
+  tools: readonly AgentRunnerToolInfo[],
+): { readonly kind: "verified"; readonly tools: readonly EffectiveToolInfoLike[] } | { readonly kind: "unverifiable"; readonly reason: string } {
+  const normalized: EffectiveToolInfoLike[] = [];
+  for (const tool of tools) {
+    if (typeof tool.description !== "string" || tool.parameters === undefined || !tool.sourceInfo) {
+      return { kind: "unverifiable", reason: `active tool metadata is incomplete for ${tool.name}` };
+    }
+    normalized.push({
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters,
+      promptGuidelines: tool.promptGuidelines,
+      sourceInfo: tool.sourceInfo,
+    });
+  }
+  return { kind: "verified", tools: normalized };
+}
+
+function lastAssistantText(state: { readonly messages: readonly unknown[] }): string {
+  for (let index = state.messages.length - 1; index >= 0; index--) {
+    const message = state.messages[index];
+    if (hasRole(message, "assistant")) return messageTextContent(message).trim();
+  }
+  return "";
+}
+
+function hasRole(value: unknown, role: string): value is { role: string } {
+  return typeof value === "object" && value !== null && "role" in value && value.role === role;
+}
+
+function messageTextContent(message: unknown): string {
+  if (!hasContentArray(message)) return "";
+  return message.content.filter(isTextPart).map((part) => part.text).join("");
+}
+
+function hasContentArray(value: unknown): value is { content: unknown[] } {
+  return typeof value === "object" && value !== null && "content" in value && Array.isArray(value.content);
+}
+
+function isTextPart(value: unknown): value is { type: "text"; text: string } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "type" in value &&
+    value.type === "text" &&
+    "text" in value &&
+    typeof value.text === "string"
+  );
+}