@jameslovespancakes/pi-plus 1.0.10 → 1.0.12

package/src/domains/workflows/runtime/agent-runner.ts

@@ -0,0 +1,203 @@
+import { assertWorkflowBudgetAvailable } from "./budget.ts";
+import { WorkflowAgentTimeoutError } from "./agent-limits.ts";
+import { abortReason, linkAbortSignal, throwIfAborted } from "./cancellation.ts";
+import { executeAgentAttempt } from "./agent-attempt.ts";
+import {
+  createAgentReplayPlan,
+  isReplayEnabled,
+  settleAgentAttempt,
+  type AgentAttemptResult,
+  type AgentReplayPlan,
+} from "./agent-replay.ts";
+import {
+  resolveAgentModel,
+  type ResolvedAgentModel,
+} from "./agent-session.ts";
+import type {
+  AgentExecutionOptions,
+  AgentRunTags,
+  RunContext,
+} from "./agent-runner-types.ts";
+import type { AgentResumeBaseContext } from "./resume-context.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+import {
+  agentRetryDelayMs,
+  WorkflowProviderError,
+} from "./agent-retry.ts";
+import { resolveAgentModelProfile } from "./model-profiles.ts";
+
+export type {
+  AgentExecutionOptions,
+  AgentProgress,
+  AgentRunnerSession,
+  CreateAgentSession,
+  RunContext,
+} from "./agent-runner-types.ts";
+export { resolveAgentModel } from "./agent-session.ts";
+export type { ResolvedAgentModel, ResolvedAgentModelRequest } from "./agent-session.ts";
+
+/**
+ * Run one subagent to completion in an isolated in-memory session.
+ *
+ * Session construction, replay validation, and workspace cleanup live in focused
+ * modules; this boundary owns admission, progress, and bounded cache/provider retries.
+ */
+export async function runAgent(
+  rc: RunContext,
+  prompt: string,
+  opts: AgentExecutionOptions,
+  resumeBaseContext: AgentResumeBaseContext,
+): Promise<unknown> {
+  if (typeof prompt !== "string") {
+    throw new Error(`agent() prompt must be a string; received ${describeAgentPrompt(prompt)}`);
+  }
+
+  const label = opts.label ?? "agent";
+  const phase = opts.phase ?? "Workflow";
+  const tags: AgentRunTags = { label, phase };
+
+  return await rc.perf.time("agent.total_ms", async () => {
+    throwIfAborted(rc.signal);
+    const routing = resolveAgentRouting(rc, opts, label);
+    const effectiveOpts = routing.thinkingLevel === opts.thinkingLevel
+      ? opts
+      : { ...opts, thinkingLevel: routing.thinkingLevel };
+    const replay = createAgentReplayPlan(prompt, effectiveOpts);
+    if (!isReplayEnabled(replay)) assertWorkflowBudgetAvailable(rc.budget);
+
+    const modelLabel = describeAgentModel(routing.model);
+    const rowId = rc.progress.agentQueued(opts.phase, label, modelLabel);
+    rc.progress.agentMessage(rowId, "task", prompt);
+    const liveScope = createAgentLiveScope(rc, label);
+    try {
+      return await rc.semaphore.run(
+        async () => {
+          const agentRc: RunContext = { ...rc, signal: liveScope.signal };
+          throwIfAborted(agentRc.signal);
+          if (!isReplayEnabled(replay)) assertWorkflowBudgetAvailable(agentRc.budget);
+          rc.progress.agentStart(opts.phase, label, rowId, modelLabel);
+          if (replay.kind === "disabled") {
+            rc.progress.log(`${label}: resume disabled for this call (${replay.reason})`);
+          }
+
+          let attemptPlan: AgentReplayPlan = replay;
+          let providerRetries = 0;
+          while (true) {
+            let outcome: AgentAttemptResult;
+            try {
+              outcome = await executeAgentAttempt({
+                rc: agentRc,
+                prompt,
+                opts: effectiveOpts,
+                resumeBaseContext,
+                model: routing.model,
+                replay: attemptPlan,
+                label,
+                rowId,
+                tags,
+                admitLiveAgent: liveScope.admit,
+              });
+            } catch (error) {
+              if (!(error instanceof WorkflowProviderError) || !error.retryable) throw error;
+              if (providerRetries >= agentRc.agentRetries) {
+                if (agentRc.agentRetries > 0) {
+                  rc.progress.log(`${label}: transient provider failure after ${providerRetries} retries; giving up`);
+                }
+                throw error;
+              }
+
+              assertWorkflowBudgetAvailable(agentRc.budget);
+              providerRetries++;
+              const delayMs = agentRetryDelayMs(providerRetries);
+              rc.progress.log(`${label}: transient provider failure; retry ${providerRetries}/${agentRc.agentRetries} in ${delayMs}ms`);
+              rc.perf.counter("agent.provider_retry", 1, tags);
+              rc.perf.observe("agent.provider_retry_delay_ms", delayMs, tags);
+              attemptPlan = { kind: "off" };
+              await agentRc.retryScheduler.sleep(delayMs, agentRc.signal);
+              continue;
+            }
+            const settlement = await settleAgentAttempt({ rc: agentRc, label, tags, replay: attemptPlan, outcome });
+            if (settlement.kind === "retry-live") {
+              attemptPlan = { kind: "off" };
+              continue;
+            }
+            rc.progress.agentDone(label, rowId);
+            return settlement.result;
+          }
+        },
+        {
+          onQueueWaitMs: (durationMs) => rc.perf.observe("agent.queue_wait_ms", durationMs, tags),
+          signal: rc.signal,
+        },
+      );
+    } catch (error) {
+      let failure = error;
+      if (liveScope.signal.aborted) failure = abortReason(liveScope.signal);
+      if (rc.signal?.aborted) failure = abortReason(rc.signal);
+      rc.progress.agentFailed(label, failure, rowId);
+      rc.progress.log(`${label} failed: ${unknownErrorMessage(failure)}`);
+      throw failure;
+    } finally {
+      liveScope.dispose();
+    }
+  }, tags);
+}
+
+function createAgentLiveScope(rc: RunContext, label: string) {
+  const controller = new AbortController();
+  const unlink = linkAbortSignal(rc.signal, controller);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let timerStarted = false;
+
+  return {
+    signal: controller.signal,
+    admit() {
+      rc.agentLimiter.admit(controller.signal);
+      if (timerStarted || rc.agentTimeoutMs === null) return;
+      timerStarted = true;
+      const timeoutMs = rc.agentTimeoutMs;
+      timer = setTimeout(
+        () => controller.abort(new WorkflowAgentTimeoutError(label, timeoutMs)),
+        timeoutMs,
+      );
+    },
+    dispose() {
+      if (timer) clearTimeout(timer);
+      unlink();
+    },
+  };
+}
+
+function resolveAgentRouting(
+  rc: RunContext,
+  opts: AgentExecutionOptions,
+  label: string,
+): { readonly model: ResolvedAgentModel["model"]; readonly thinkingLevel: AgentExecutionOptions["thinkingLevel"] } {
+  try {
+    return resolveAgentModelProfile(
+      {
+        request: opts,
+        profiles: rc.modelProfiles,
+        resolveExplicitModel: (modelRef) => resolveAgentModel(modelRef, rc.modelRegistry, rc.hostModel).model,
+        hostModel: rc.hostModel,
+      },
+    );
+  } catch (error) {
+    rc.progress.agentFailed(label, error);
+    throw error;
+  }
+}
+
+/** "provider/id" for progress rows so every agent shows the model it routed to. */
+function describeAgentModel(model: unknown): string | undefined {
+  if (!model || typeof model !== "object") return undefined;
+  const candidate = model as { provider?: unknown; id?: unknown };
+  if (typeof candidate.id !== "string") return undefined;
+  return typeof candidate.provider === "string" ? `${candidate.provider}/${candidate.id}` : candidate.id;
+}
+
+function describeAgentPrompt(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}

package/src/domains/workflows/runtime/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/src/domains/workflows/runtime/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);
+  }
+}