@jameslovespancakes/pi-plus 1.0.11 → 1.0.13

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

@@ -0,0 +1,399 @@
+import type { Skill } from "@earendil-works/pi-coding-agent";
+import { Value } from "typebox/value";
+import { captureAgentSkillIdentities, extractSkillSelectorsFromText } from "./agent-skills.ts";
+import type { AgentExecutionOptions, AgentRunnerSession, AgentRunTags, RunContext } from "./agent-runner-types.ts";
+import { captureEffectiveAgentSessionIdentity } from "./agent-session-identity.ts";
+import { FINAL_TOOL } from "./agent-session.ts";
+import type { AgentWorkspace, IsolatedAgentWorkspace } from "./agent-workspace.ts";
+import { captureAgentJournalKey } from "./journal.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+import {
+  captureRepositoryMutationGuard,
+  captureIsolatedRepositoryContext,
+  captureRepositoryResumeContext,
+  createAgentResumeContext,
+  resumeContextMismatchReason,
+  type AgentResumeBaseContext,
+  type AgentResumeContext,
+  type RepositoryResumeContext,
+  type VerifiedRepositoryResumeContext,
+  type VerifiedWorkflowResumeContext,
+} from "./resume-context.ts";
+
+export type AgentReplayPlan =
+  | { readonly kind: "off" }
+  | { readonly kind: "disabled"; readonly reason: string }
+  | { readonly kind: "shared"; readonly key: string; readonly additionalInputs: readonly string[] }
+  | { readonly kind: "isolated"; readonly key: string };
+
+export type AgentReplayEvidence =
+  | { readonly kind: "shared" }
+  | { readonly kind: "isolated"; readonly mutationGuard: string };
+
+export type AgentAttemptResult =
+  | { readonly kind: "cache-hit"; readonly result: unknown; readonly identity: AgentResumeContext; readonly evidence: AgentReplayEvidence }
+  | { readonly kind: "live-recordable"; readonly result: unknown; readonly identity: AgentResumeContext; readonly evidence: AgentReplayEvidence }
+  | { readonly kind: "live-unrecordable"; readonly result: unknown };
+
+export type AgentAttemptSettlement =
+  | { readonly kind: "done"; readonly result: unknown }
+  | { readonly kind: "retry-live" };
+
+type ReplayIdentityCapture =
+  | { readonly kind: "verified"; readonly identity: AgentResumeContext }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+const INACCESSIBLE_REPOSITORY_CONTEXT: VerifiedRepositoryResumeContext = {
+  kind: "verified",
+  state: "inaccessible",
+  workingTreeFingerprint: "no-workspace-capability",
+};
+
+export function createAgentReplayPlan(
+  prompt: string,
+  opts: AgentExecutionOptions,
+): AgentReplayPlan {
+  if (opts.resume !== undefined && opts.resume !== "read-only" && opts.resume !== "off") {
+    return { kind: "disabled", reason: "resume policy must be read-only or off" };
+  }
+  const isolated = opts.isolation === "worktree";
+  if (opts.resume === "off" || (!isolated && opts.resume !== "read-only")) return { kind: "off" };
+  const additionalInputs = inspectResumeInputs(opts);
+  if (typeof additionalInputs === "string") return { kind: "disabled", reason: additionalInputs };
+  const capture = captureAgentJournalKey(prompt, opts, opts.worktreeBaseline);
+  if (capture.kind === "unverifiable") return { kind: "disabled", reason: capture.reason };
+  return isolated
+    ? { kind: "isolated", key: capture.key }
+    : { kind: "shared", key: capture.key, additionalInputs };
+}
+
+export function isReplayEnabled(
+  replay: AgentReplayPlan,
+): replay is Extract<AgentReplayPlan, { readonly kind: "shared" | "isolated" }> {
+  return replay.kind === "shared" || replay.kind === "isolated";
+}
+
+export async function captureSharedRepositoryBeforeSetup(
+  rc: RunContext,
+  prompt: string,
+  opts: AgentExecutionOptions,
+  replay: Extract<AgentReplayPlan, { readonly kind: "shared" }>,
+): Promise<RepositoryResumeContext> {
+  if (declaresNoWorkspaceCapability(prompt, opts)) return INACCESSIBLE_REPOSITORY_CONTEXT;
+  return await captureRepositoryResumeContext(rc.cwd, replay.additionalInputs, rc.signal);
+}
+
+export async function captureIsolatedRepositoryAfterSetup(
+  rc: RunContext,
+  prompt: string,
+  opts: AgentExecutionOptions,
+  workspace: IsolatedAgentWorkspace,
+): Promise<RepositoryResumeContext> {
+  if (declaresNoWorkspaceCapability(prompt, opts)) return INACCESSIBLE_REPOSITORY_CONTEXT;
+  return await captureIsolatedRepositoryContext(workspace.cwd, workspace.baselineOid, rc.signal);
+}
+
+export async function captureReplayIdentity(input: {
+  readonly rc: RunContext;
+  readonly base: AgentResumeBaseContext;
+  readonly repository: RepositoryResumeContext;
+  readonly selectedSkills: readonly Skill[];
+  readonly session: AgentRunnerSession;
+  readonly sessionCwd: string;
+}): Promise<ReplayIdentityCapture> {
+  if (input.repository.kind === "unverifiable") return input.repository;
+  if (input.base.workflow.kind === "unverifiable") return input.base.workflow;
+  return await captureVerifiedReplayIdentity({
+    ...input,
+    repository: input.repository,
+    workflow: input.base.workflow,
+  });
+}
+
+export async function lookupReplayResult(input: {
+  readonly rc: RunContext;
+  readonly key: string;
+  readonly identity: AgentResumeContext;
+  readonly opts: AgentExecutionOptions;
+  readonly workspace: AgentWorkspace;
+}): Promise<{ readonly hit: true; readonly result: unknown } | { readonly hit: false; readonly reason?: string }> {
+  const cached = input.rc.journal.lookup(input.key, input.identity, {
+    allowWorkflowSourceMismatch: input.rc.resumeEditedWorkflow,
+  });
+  if (!cached.hit) return cached;
+  const validation = await validateCachedResult(cached.value, input.opts, input.rc, input.workspace);
+  return validation.ok
+    ? { hit: true, result: cached.value }
+    : { hit: false, reason: validation.reason };
+}
+
+export async function validateReplayIdentity(input: {
+  readonly rc: RunContext;
+  readonly identity: AgentResumeContext;
+  readonly selectedSkills: readonly Skill[];
+  readonly session: AgentRunnerSession;
+  readonly sessionCwd: string;
+  readonly replay: Extract<AgentReplayPlan, { readonly kind: "shared" | "isolated" }>;
+  readonly workspace: AgentWorkspace;
+}): Promise<{ readonly ok: true } | { readonly ok: false; readonly reason: string }> {
+  const repository = input.identity.repository.state === "inaccessible"
+    ? INACCESSIBLE_REPOSITORY_CONTEXT
+    : await captureCurrentRepository(input.rc, input.replay, input.workspace);
+  if (repository.kind === "unverifiable") return { ok: false, reason: repository.reason };
+
+  const current = await captureVerifiedReplayIdentity({
+    rc: input.rc,
+    repository,
+    workflow: input.identity.workflow,
+    selectedSkills: input.selectedSkills,
+    session: input.session,
+    sessionCwd: input.sessionCwd,
+  });
+  if (current.kind === "unverifiable") return { ok: false, reason: current.reason };
+  const mismatch = resumeContextMismatchReason(input.identity, current.identity, {
+    allowWorkflowSourceMismatch: input.rc.resumeEditedWorkflow,
+  });
+  return mismatch ? { ok: false, reason: mismatch } : { ok: true };
+}
+
+export async function settleAgentAttempt(input: {
+  readonly rc: RunContext;
+  readonly label: string;
+  readonly tags: AgentRunTags;
+  readonly replay: AgentReplayPlan;
+  readonly outcome: AgentAttemptResult;
+}): Promise<AgentAttemptSettlement> {
+  const { rc, label, replay, outcome } = input;
+  if (outcome.kind === "live-unrecordable") {
+    recordAgentResultSource(rc, "live");
+    return { kind: "done", result: outcome.result };
+  }
+  if (!isReplayEnabled(replay)) throw new Error("Replayable agent outcome produced without an enabled replay plan.");
+
+  const repository = await validateRepositoryAfterCleanup(
+    rc,
+    outcome.identity,
+    replay,
+    outcome.evidence,
+  );
+  if (!repository.ok) {
+    if (outcome.kind === "cache-hit") {
+      rc.progress.log(`${label}: cached result invalidated after cleanup (${repository.reason})`);
+      return { kind: "retry-live" };
+    }
+    rc.progress.log(`${label}: read-only resume contract was not recorded (${repository.reason})`);
+    return { kind: "done", result: outcome.result };
+  }
+
+  await recordJournalResult(rc, label, replay.key, outcome.result, outcome.identity);
+  if (outcome.kind === "cache-hit") {
+    rc.progress.log(`${label}: using cached result from workflow journal`);
+    rc.perf.counter("agent.cache_hit", 1, input.tags);
+    recordAgentResultSource(rc, "cached");
+  } else {
+    recordAgentResultSource(rc, "live");
+  }
+  return { kind: "done", result: outcome.result };
+}
+
+function recordAgentResultSource(rc: RunContext, source: "cached" | "live"): void {
+  if (!rc.resumeEditedWorkflow) return;
+  rc.progress.event({
+    type: "counter_delta",
+    key: `resume.${source}`,
+    label: source === "cached" ? "Cached agents" : "Live agents",
+    delta: 1,
+  });
+}
+
+async function captureVerifiedReplayIdentity(input: {
+  readonly rc: RunContext;
+  readonly repository: VerifiedRepositoryResumeContext;
+  readonly workflow: VerifiedWorkflowResumeContext;
+  readonly selectedSkills: readonly Skill[];
+  readonly session: AgentRunnerSession;
+  readonly sessionCwd: string;
+}): Promise<ReplayIdentityCapture> {
+  const [skills, effectiveSession] = await Promise.all([
+    captureAgentSkillIdentities(input.selectedSkills, {
+      sessionCwd: input.sessionCwd,
+      workspaceRoot: input.rc.cwd,
+      signal: input.rc.signal,
+    }),
+    captureEffectiveAgentSessionIdentity(input.session, {
+      sessionCwd: input.sessionCwd,
+      workspaceRoot: input.rc.cwd,
+      signal: input.rc.signal,
+    }),
+  ]);
+  if (skills.kind === "unverifiable") return skills;
+  if (effectiveSession.kind === "unverifiable") return effectiveSession;
+  if (
+    input.repository.state === "inaccessible" &&
+    (skills.skills.length > 0 || effectiveSession.identity.tools.some((tool) => tool.name !== FINAL_TOOL))
+  ) {
+    return { kind: "unverifiable", reason: "session unexpectedly retained workspace-observing capabilities" };
+  }
+  return {
+    kind: "verified",
+    identity: createAgentResumeContext(
+      { workflow: input.workflow },
+      input.repository,
+      effectiveSession.identity,
+      skills.skills,
+    ),
+  };
+}
+
+async function validateCachedResult(
+  value: unknown,
+  opts: AgentExecutionOptions,
+  rc: RunContext,
+  workspace: AgentWorkspace,
+): Promise<{ readonly ok: true } | { readonly ok: false; readonly reason: string }> {
+  let result: unknown;
+  if (opts.isolation === "worktree") {
+    const isolated = isolatedCachedResult(value);
+    if (!isolated.ok) return isolated;
+    const patch = await rc.worktrees.validatePatch(workspace.cwd, isolated.wrapper, rc.signal);
+    if (!patch.ok) {
+      return {
+        ok: false,
+        reason: `cached isolated patch does not apply to the current baseline (${(patch.error ?? patch.stderr.trim()) || "unknown error"})`,
+      };
+    }
+    result = isolated.wrapper.result;
+  } else {
+    result = value;
+  }
+  if (!opts.schema) {
+    return typeof result === "string"
+      ? { ok: true }
+      : { ok: false, reason: "cached text result is not a string" };
+  }
+  if (result === null) return { ok: true };
+  try {
+    return Value.Check(opts.schema, result)
+      ? { ok: true }
+      : { ok: false, reason: "cached structured result does not match the current schema" };
+  } catch (error) {
+    return { ok: false, reason: `cached structured result could not be validated (${unknownErrorMessage(error)})` };
+  }
+}
+
+function isolatedCachedResult(value: unknown):
+  | {
+      readonly ok: true;
+      readonly wrapper: { readonly result: unknown; readonly patch: string; readonly changed: boolean };
+    }
+  | { readonly ok: false; readonly reason: string } {
+  if (typeof value !== "object" || value === null) {
+    return { ok: false, reason: "cached isolated result is not an object" };
+  }
+  const candidate = value as { readonly result?: unknown; readonly patch?: unknown; readonly changed?: unknown };
+  if (!("result" in candidate) || typeof candidate.patch !== "string" || typeof candidate.changed !== "boolean") {
+    return { ok: false, reason: "cached isolated result has an invalid wrapper" };
+  }
+  const wrapper = { result: candidate.result, patch: candidate.patch, changed: candidate.changed };
+  return { ok: true, wrapper };
+}
+
+async function validateRepositoryAfterCleanup(
+  rc: RunContext,
+  identity: AgentResumeContext,
+  replay: Extract<AgentReplayPlan, { readonly kind: "shared" | "isolated" }>,
+  evidence: AgentReplayEvidence,
+): Promise<{ readonly ok: true } | { readonly ok: false; readonly reason: string }> {
+  if (replay.kind === "isolated") {
+    return evidence.kind === "isolated"
+      ? await validateReplayEvidence(rc, evidence)
+      : { ok: false, reason: "isolated replay omitted its main-workspace mutation guard" };
+  }
+
+  const repository = identity.repository.state === "inaccessible"
+    ? INACCESSIBLE_REPOSITORY_CONTEXT
+    : await captureRepositoryResumeContext(rc.cwd, replay.additionalInputs, rc.signal);
+  if (repository.kind === "unverifiable") return { ok: false, reason: repository.reason };
+  const mismatch = resumeContextMismatchReason(identity, { ...identity, repository });
+  if (mismatch) return { ok: false, reason: mismatch };
+  return evidence.kind === "shared"
+    ? { ok: true }
+    : { ok: false, reason: "shared replay carried isolated mutation evidence" };
+}
+
+export async function validateReplayEvidence(
+  rc: RunContext,
+  evidence: AgentReplayEvidence,
+): Promise<{ readonly ok: true } | { readonly ok: false; readonly reason: string }> {
+  return evidence.kind === "shared"
+    ? { ok: true }
+    : await validateRepositoryMutationGuard(rc, evidence.mutationGuard);
+}
+
+export async function validateRepositoryMutationGuard(
+  rc: RunContext,
+  expected: string,
+): Promise<{ readonly ok: true } | { readonly ok: false; readonly reason: string }> {
+  const current = await captureRepositoryMutationGuard(rc.cwd, rc.signal);
+  if (current.kind === "unverifiable") return { ok: false, reason: current.reason };
+  return current.fingerprint === expected
+    ? { ok: true }
+    : { ok: false, reason: "main workspace changed outside the isolated worktree" };
+}
+
+async function captureCurrentRepository(
+  rc: RunContext,
+  replay: Extract<AgentReplayPlan, { readonly kind: "shared" | "isolated" }>,
+  workspace: AgentWorkspace,
+): Promise<RepositoryResumeContext> {
+  if (replay.kind === "shared") return await captureRepositoryResumeContext(rc.cwd, replay.additionalInputs, rc.signal);
+  if (workspace.kind !== "isolated") {
+    return { kind: "unverifiable", reason: "isolated replay lost its isolated workspace baseline" };
+  }
+  return await captureIsolatedRepositoryContext(workspace.cwd, workspace.baselineOid, rc.signal);
+}
+
+async function recordJournalResult(
+  rc: RunContext,
+  label: string,
+  key: string,
+  result: unknown,
+  identity: AgentResumeContext,
+): Promise<void> {
+  try {
+    const recorded = await rc.journal.record(key, result, identity);
+    if (!recorded.ok) {
+      rc.progress.log(`${label}: workflow journal write failed (${recorded.error}); future resume may be incomplete`);
+    }
+  } catch (error) {
+    rc.progress.log(`${label}: workflow journal write failed (${unknownErrorMessage(error)}); future resume may be incomplete`);
+  }
+}
+
+function declaresNoWorkspaceCapability(prompt: string, opts: AgentExecutionOptions): boolean {
+  return (
+    opts.tools !== undefined &&
+    opts.tools.length === 0 &&
+    (opts.toolHints?.length ?? 0) === 0 &&
+    (opts.skills?.length ?? 0) === 0 &&
+    extractSkillSelectorsFromText(prompt).length === 0
+  );
+}
+
+function inspectResumeInputs(opts: AgentExecutionOptions): readonly string[] | string {
+  try {
+    const inputs = opts.resumeInputs;
+    if (inputs === undefined) return [];
+    if (!Array.isArray(inputs)) return "read-only resume inputs must be an array";
+    if (inputs.length > 128) return "read-only resume accepts at most 128 repository inputs";
+    const inspected: string[] = [];
+    for (let index = 0; index < inputs.length; index++) {
+      const value = inputs[index];
+      if (typeof value !== "string") return "read-only resume inputs must be strings";
+      inspected.push(value);
+    }
+    return inspected;
+  } catch {
+    return "read-only resume inputs could not be inspected";
+  }
+}

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

@@ -0,0 +1,116 @@
+import { isRetryableAssistantError, type AssistantMessage } from "@earendil-works/pi-ai";
+import { abortReason, throwIfAborted } from "./cancellation.ts";
+import {
+  providerUsageLimitFromMessages,
+  type WorkflowProviderUsageLimitError,
+} from "./provider-usage-limit.ts";
+
+export const AGENT_RETRY_BASE_DELAY_MS = 1_000;
+export const AGENT_RETRY_MAX_DELAY_MS = 30_000;
+export const WORKFLOW_PROVIDER_ERROR_CODE = "WORKFLOW_PROVIDER_ERROR";
+
+export interface AgentRetryScheduler {
+  sleep(delayMs: number, signal: AbortSignal | undefined): Promise<void>;
+}
+
+export interface ProviderErrorDetails {
+  readonly stopReason: "error";
+  readonly retryable: boolean;
+  readonly provider?: string;
+  readonly model?: string;
+  readonly api?: string;
+}
+
+/** Provider failure reconstructed from pi's terminal assistant-message metadata. */
+export class WorkflowProviderError extends Error {
+  override readonly name = "WorkflowProviderError";
+  readonly code = WORKFLOW_PROVIDER_ERROR_CODE;
+
+  constructor(
+    message: string,
+    readonly details: ProviderErrorDetails,
+  ) {
+    super(message);
+  }
+
+  get retryable(): boolean {
+    return this.details.retryable;
+  }
+
+  toJSON(): {
+    readonly name: string;
+    readonly message: string;
+    readonly code: string;
+    readonly details: ProviderErrorDetails;
+  } {
+    return { name: this.name, message: this.message, code: this.code, details: this.details };
+  }
+}
+
+export const defaultAgentRetryScheduler: AgentRetryScheduler = {
+  async sleep(delayMs, signal) {
+    throwIfAborted(signal);
+    await new Promise<void>((resolve, reject) => {
+      const cleanup = () => signal?.removeEventListener("abort", onAbort);
+      const timer = setTimeout(() => {
+        cleanup();
+        resolve();
+      }, delayMs);
+      const onAbort = () => {
+        clearTimeout(timer);
+        cleanup();
+        reject(abortReason(signal));
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      if (signal?.aborted) onAbort();
+    });
+  },
+};
+
+export function agentRetryDelayMs(retryAttempt: number): number {
+  return Math.min(AGENT_RETRY_MAX_DELAY_MS, AGENT_RETRY_BASE_DELAY_MS * 2 ** Math.max(0, retryAttempt - 1));
+}
+
+export function providerErrorFromMessages(
+  messages: readonly unknown[],
+  options: { readonly pauseOnUsageLimit?: boolean } = {},
+): WorkflowProviderError | WorkflowProviderUsageLimitError | undefined {
+  const usageLimit = providerUsageLimitFromMessages(messages);
+  if (usageLimit && options.pauseOnUsageLimit) return usageLimit;
+  const message = messages.findLast(isAssistantMessage);
+  if (!message || message.stopReason !== "error") return undefined;
+  const errorMessage = typeof message.errorMessage === "string" && message.errorMessage.length > 0
+    ? message.errorMessage
+    : "Provider session ended with an unspecified error.";
+  const retryable = isRetryableAssistantError(message as AssistantMessage);
+  const provider = stringDetail(message.provider);
+  const model = stringDetail(message.model);
+  const api = stringDetail(message.api);
+  return new WorkflowProviderError(errorMessage, {
+    stopReason: "error",
+    retryable,
+    ...(provider ? { provider } : {}),
+    ...(model ? { model } : {}),
+    ...(api ? { api } : {}),
+  });
+}
+
+function isAssistantMessage(value: unknown): value is {
+  readonly role: "assistant";
+  readonly stopReason?: unknown;
+  readonly errorMessage?: unknown;
+  readonly provider?: unknown;
+  readonly model?: unknown;
+  readonly api?: unknown;
+} {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "role" in value &&
+    value.role === "assistant"
+  );
+}
+
+function stringDetail(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}

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

@@ -0,0 +1,96 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type {
+  AgentSession,
+  CreateAgentSessionOptions,
+  ModelRegistry,
+} from "@earendil-works/pi-coding-agent";
+import type { WorkflowBudget } from "./budget.ts";
+import type { Semaphore } from "./concurrency.ts";
+import type { WorkflowAgentLimiter } from "./agent-limits.ts";
+import type { AgentRetryScheduler } from "./agent-retry.ts";
+import type { ResolvedWorkflowModelProfiles } from "./model-profiles.ts";
+import type { WorkflowJournal } from "./journal.ts";
+import type { PerfSink } from "./perf.ts";
+import type { AgentOptions, WorkflowProgressEvent } from "./types.ts";
+import type { AgentChatRole } from "./progress-types.ts";
+import type { WorkflowUsageSink } from "./usage.ts";
+import type { WorktreeBaseline, WorktreeRegistry } from "./worktree.ts";
+
+export type AgentRunnerSession = Pick<
+  AgentSession,
+  | "messages"
+  | "systemPrompt"
+  | "model"
+  | "thinkingLevel"
+  | "prompt"
+  | "subscribe"
+  | "dispose"
+  | "abort"
+  | "getAllTools"
+  | "getActiveToolNames"
+  | "getToolDefinition"
+  | "setActiveToolsByName"
+  | "setAutoRetryEnabled"
+  | "getLastAssistantText"
+  | "isStreaming"
+  | "followUp"
+>;
+
+export type CreateAgentSession = (options: CreateAgentSessionOptions) => Promise<{ session: AgentRunnerSession }>;
+
+export interface AgentProgress {
+  agentQueued(phase: string | undefined, label: string, model?: string): number;
+  agentStart(phase: string | undefined, label: string, id?: number, model?: string): void;
+  agentTool(label: string, tool: string, id?: number): void;
+  agentMessage(id: number, role: AgentChatRole, text: string): void;
+  bindAgentFollowUp(id: number, send: (message: string) => Promise<void>): () => void;
+  agentDone(label: string, id?: number): void;
+  agentFailed(label: string, error: unknown, id?: number): void;
+  event(event: WorkflowProgressEvent): void;
+  log(message: string): void;
+}
+
+interface RunContextBase {
+  cwd: string;
+  hostModel: Model<Api> | undefined;
+  semaphore: Semaphore;
+  agentLimiter: WorkflowAgentLimiter;
+  agentTimeoutMs: number | null;
+  agentRetries: number;
+  pauseOnProviderUsageLimit?: boolean;
+  resumeEditedWorkflow?: boolean;
+  retryScheduler: AgentRetryScheduler;
+  modelProfiles: ResolvedWorkflowModelProfiles;
+  progress: AgentProgress;
+  signal: AbortSignal | undefined;
+  perf: PerfSink;
+  usage: WorkflowUsageSink;
+  budget: WorkflowBudget;
+  journal: WorkflowJournal;
+  worktrees: WorktreeRegistry;
+}
+
+/** Shared per-run context threaded into every agent() call. */
+export type RunContext = RunContextBase & (
+  | {
+      /** Production sessions inherit the host's live provider and auth state. */
+      modelRegistry: ModelRegistry;
+      createSession?: undefined;
+    }
+  | {
+      /** Injected test sessions bypass Pi's resource loader and therefore do not resolve skills. */
+      modelRegistry: Pick<ModelRegistry, "find">;
+      createSession: CreateAgentSession;
+    }
+);
+
+/** Runtime-only options. The authored WorkflowApi exposes only AgentOptions. */
+export type AgentExecutionOptions = AgentOptions & {
+  readonly worktreeBaseline?: WorktreeBaseline;
+};
+
+export interface AgentRunTags {
+  readonly [key: string]: string | number;
+  readonly label: string;
+  readonly phase: string;
+}