@capekai/core 1.0.0

package/src/plugins/workflow-domain.ts

@@ -0,0 +1,198 @@
+import type { WorkflowInput, WorkflowResult } from '@capekai/types';
+import { serviceKey } from '../kernel/service-key';
+import type {
+  CapekPlugin,
+  PluginContext,
+  ToolDefinition as KernelToolDefinition,
+} from '../kernel/types';
+import {
+  DOMAIN_TOOL_PAYLOAD_FIELD,
+  registerDomainToolFallback,
+  type DomainToolPayload,
+} from '../runtime/domain-tool-source';
+import {
+  buildWorkflowToolDefinition,
+  canSpawnSubagent,
+  executeWorkflow,
+  executeWorkflowWithDeps,
+  getWorkflowToolDefinition,
+  type GetWorkflowToolDefinitionOptions,
+  type WorkflowExecutionOptions,
+  type WorkflowServiceDeps,
+  type WorkflowToolDefinition,
+} from '../workflow/execution';
+import {
+  capekSubagentDomainKey,
+  type SubagentDomainService,
+} from './subagent-domain';
+import {
+  capekOrchestratorSessionKey,
+  type OrchestratorSessionContract,
+} from './service-keys';
+
+/**
+ * C5 workflow domain plugin. Owns the agent-scoped workflow service and the
+ * `workflow` tool contribution through the generic contributed-domain-tool
+ * seam. Decompose → fan out → synthesize runs over the scope-captured
+ * subagent domain service (leaf execution, depth, targets, subagent
+ * listing) and the shared `capek.orchestrator-session` contract; composed
+ * payloads never read module globals. The unscoped fallback keeps the
+ * pre-C5 module accessors and is installed explicitly, never at module
+ * load.
+ */
+
+export const CURRENT_WORKFLOW_DOMAIN_PLUGIN_ID = 'current.workflow-domain';
+export const WORKFLOW_TOOL_CONTRIBUTION_ID = 'workflow.workflow';
+/** Between task (650) and session_search (700) so the composed tool order
+ * keeps the pre-C5 relative position: workflow before session_search and
+ * scheduler. */
+export const WORKFLOW_TOOL_CONTRIBUTION_ORDER = 690;
+
+export interface WorkflowDomainService {
+  readonly tools: readonly DomainToolPayload[];
+  /** Depth gate shared by the workflow tool payload. */
+  canSpawn(sessionId: string): boolean | Promise<boolean>;
+  resolveDefinition(
+    options: GetWorkflowToolDefinitionOptions,
+  ): Promise<WorkflowToolDefinition | null>;
+  execute(input: WorkflowInput, options: WorkflowExecutionOptions): Promise<WorkflowResult>;
+}
+
+export const capekWorkflowDomainKey = serviceKey<WorkflowDomainService>(
+  'capek.workflow-domain',
+  'agent',
+);
+
+interface WorkflowPayloadDeps {
+  canSpawn(sessionId: string): boolean | Promise<boolean>;
+  resolveDefinition(
+    options: GetWorkflowToolDefinitionOptions,
+  ): Promise<WorkflowToolDefinition | null>;
+  execute(input: WorkflowInput, options: WorkflowExecutionOptions): Promise<WorkflowResult>;
+}
+
+function workflowPayload(deps: WorkflowPayloadDeps): DomainToolPayload {
+  const placeholder = buildWorkflowToolDefinition([]);
+  return {
+    name: placeholder.name,
+    description: placeholder.description,
+    inputSchema: placeholder.inputSchema,
+    isEnabled: async (workspaceId, sessionId) =>
+      typeof sessionId === 'string' && await deps.canSpawn(sessionId),
+    resolveDefinition: async (sessionId, options) => {
+      const definition = await deps.resolveDefinition({
+        sessionId,
+        canSpawnSubagents: options?.canSpawnSubagents as boolean | string[] | null | undefined,
+        allowSelfAsSubagent: options?.allowSelfAsSubagent as boolean | undefined,
+      });
+      if (!definition) return null;
+      return {
+        description: definition.description,
+        inputSchema: definition.inputSchema,
+        allowedSubagentIds: definition.allowedSubagentIds,
+      };
+    },
+    execute: async (input, context) => {
+      const workflowInput = {
+        prompt: input.prompt as string,
+        ...(input.description ? { description: input.description as string } : {}),
+        ...(input.subtasks ? { subtasks: input.subtasks as WorkflowInput['subtasks'] } : {}),
+        ...(input.leafPreconfigId ? { leafPreconfigId: input.leafPreconfigId as string } : {}),
+        ...(input.outputSchema ? { outputSchema: input.outputSchema as Record<string, unknown> } : {}),
+      } as WorkflowInput;
+
+      // No broadcast pass-through: pre-C5 leaves defaulted to the module
+      // broadcast, and composed leaves default to the subagent domain's
+      // scope-captured host delivery.
+      return deps.execute(workflowInput, {
+        sessionId: context.sessionId,
+        workspaceId: typeof context.workspaceId === 'string' ? context.workspaceId : undefined,
+        workspacePath: typeof context.workspacePath === 'string' ? context.workspacePath : undefined,
+        abortSignal: context.abortSignal as AbortSignal | undefined,
+        allowedSubagentIds: context.allowedSubagentIds as string[] | undefined,
+      }) as unknown as Promise<Record<string, unknown>>;
+    },
+  };
+}
+
+/** Unscoped compatibility payload: keeps the pre-C5 execute-time module
+ * accessors. Installed through `installWorkflowToolFallback`, never at
+ * module load. */
+export function createWorkflowToolFallbackPayload(): DomainToolPayload {
+  return workflowPayload({
+    canSpawn: canSpawnSubagent,
+    resolveDefinition: (options) => getWorkflowToolDefinition(options),
+    execute: (input, options) => executeWorkflow(input, options),
+  });
+}
+
+/** Explicitly installs the unscoped legacy fallback. Called by the Jean2
+ * compatibility bindings installation (server bootstrap) and by focused
+ * tests; no module-load registration exists. */
+export function installWorkflowToolFallback(): void {
+  registerDomainToolFallback('workflow', createWorkflowToolFallbackPayload());
+}
+
+export function workflowDomainPlugin(id: string): CapekPlugin<unknown> {
+  return {
+    id,
+    scope: 'agent',
+    provides: [capekWorkflowDomainKey],
+    requires: [capekSubagentDomainKey, capekOrchestratorSessionKey],
+    setup(context: PluginContext) {
+      const subagent: SubagentDomainService = context.require(capekSubagentDomainKey);
+      const orchestrator: OrchestratorSessionContract = context.require(capekOrchestratorSessionKey);
+
+      const serviceDeps: WorkflowServiceDeps = {
+        canSpawn: subagent.canSpawnSubagent,
+        listSubagents: subagent.listSubagents,
+        executeLeaf: subagent.execute,
+        orchestrator,
+      };
+
+      const service: WorkflowDomainService = {
+        tools: [
+          workflowPayload({
+            canSpawn: async (sessionId) => subagent.canSpawnSubagent(sessionId),
+            resolveDefinition: async (options) => {
+              // The composed path resolves targets through the subagent
+              // domain service's scope-captured deps; it never reads module
+              // globals.
+              const maximumDepthReached = !(await subagent.canSpawnSubagent(options.sessionId));
+              return subagent.resolveTargets({
+                ...options,
+                maximumDepthReached,
+              }).then((targets) =>
+                targets.length === 0 ? null : buildWorkflowToolDefinition(targets));
+            },
+            execute: (input, options) => executeWorkflowWithDeps(input, options, serviceDeps),
+          }),
+        ],
+        canSpawn: async (sessionId) => subagent.canSpawnSubagent(sessionId),
+        resolveDefinition: async (options) => {
+          const maximumDepthReached = !(await subagent.canSpawnSubagent(options.sessionId));
+          return subagent.resolveTargets({
+            ...options,
+            maximumDepthReached,
+          }).then((targets) =>
+            targets.length === 0 ? null : buildWorkflowToolDefinition(targets));
+        },
+        execute: (input, options) => executeWorkflowWithDeps(input, options, serviceDeps),
+      };
+
+      context.provide(capekWorkflowDomainKey, service);
+      context.contributeTool({
+        id: WORKFLOW_TOOL_CONTRIBUTION_ID,
+        order: WORKFLOW_TOOL_CONTRIBUTION_ORDER,
+        definition: {
+          name: service.tools[0].name,
+          description: service.tools[0].description,
+          inputSchema: service.tools[0].inputSchema,
+          timeout: 600000,
+          [DOMAIN_TOOL_PAYLOAD_FIELD]: service.tools[0],
+        } as KernelToolDefinition,
+        requiredCapabilities: [capekWorkflowDomainKey],
+      });
+    },
+  };
+}

package/src/plugins/workspace-policy.ts

@@ -0,0 +1,37 @@
+import type { CapekPlugin, PluginContext } from '../kernel/types';
+import { homedir } from 'os';
+import { SENSITIVE_FILE_PATTERNS } from '@capekai/types';
+import {
+  BLOCKED_PATHS,
+  createWorkspaceService,
+  type WorkspacePolicyOptions,
+} from '../workspace/policy';
+import { capekWorkspacePolicyKey } from './service-keys';
+
+/**
+ * C6 provider for the agent-scoped workspace policy service
+ * (`capek.workspace-policy`). The path inputs translate into provider
+ * options here, at composition: the blocked-path list, the sensitive
+ * pattern list, and the home directory freeze into the service options, so
+ * no runtime code re-reads them. The default provider reproduces the exact
+ * current containment, root classification, expansion, and sensitive/blocked
+ * denial behavior.
+ */
+export function workspacePolicyPlugin(id: string): CapekPlugin<unknown> {
+  return {
+    id,
+    scope: 'agent',
+    provides: [capekWorkspacePolicyKey],
+    setup(context: PluginContext) {
+      const options: WorkspacePolicyOptions = {
+        blockedPaths: [...BLOCKED_PATHS],
+        sensitivePatterns: [...SENSITIVE_FILE_PATTERNS],
+        homeDir: homedir(),
+      };
+      context.provide(
+        capekWorkspacePolicyKey,
+        createWorkspaceService({ id, options }),
+      );
+    },
+  };
+}

package/src/providers/registry.ts

@@ -0,0 +1,63 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { ProviderStatus } from '@capekai/types';
+import type {
+  ConnectableProvider,
+  ConnectOptions,
+  ConnectResult,
+  ModelFactoryOptions,
+  ModelFactoryResult,
+} from './types';
+
+const providers = new Map<string, ConnectableProvider>();
+const scopedProviders = new AsyncLocalStorage<ReadonlyMap<string, ConnectableProvider>>();
+
+function activeProvider(id: string): ConnectableProvider | undefined {
+  return scopedProviders.getStore()?.get(id) ?? providers.get(id);
+}
+
+export function withProviderOverrides<T>(overrides: ReadonlyMap<string, ConnectableProvider>, callback: () => T): T {
+  return scopedProviders.run(overrides, callback);
+}
+
+export function registerProvider(provider: ConnectableProvider): void {
+  providers.set(provider.descriptor.id, provider);
+}
+
+export function getConnectableProviders(): ConnectableProvider[] {
+  const combined = new Map(providers);
+  for (const [id, provider] of scopedProviders.getStore() ?? []) combined.set(id, provider);
+  return [...combined.values()];
+}
+
+export function getProvider(id: string): ConnectableProvider | undefined {
+  return activeProvider(id);
+}
+
+export function getProviderStatus(id: string): ProviderStatus {
+  return activeProvider(id)?.getStatus() ?? { provider: id, connected: false };
+}
+
+export async function connectProvider(id: string, options?: ConnectOptions): Promise<ConnectResult> {
+  const provider = activeProvider(id);
+  if (!provider) throw new Error(`Unknown connectable provider: ${id}`);
+  return provider.connect(options);
+}
+
+export async function disconnectProvider(id: string): Promise<void> {
+  const provider = activeProvider(id);
+  if (!provider) throw new Error(`Unknown connectable provider: ${id}`);
+  await provider.disconnect();
+}
+
+export async function createModelForProvider(options: ModelFactoryOptions): Promise<ModelFactoryResult> {
+  const provider = activeProvider(options.providerId);
+  if (!provider) throw new Error(`Unknown connectable provider: ${options.providerId}`);
+  if (!provider.createModel) {
+    throw new Error(`Provider '${options.providerId}' does not support creating models (kind: 'service')`);
+  }
+  return provider.createModel(options);
+}
+
+export function resetProviders(): void {
+  providers.clear();
+}

package/src/providers/types.ts

@@ -0,0 +1,44 @@
+import type { LanguageModel } from 'ai';
+import type { OAuthRedirectStrategy, ProviderDescriptor, ProviderStatus } from '@capekai/types';
+
+export interface ModelFactoryOptions {
+  modelId: string;
+  providerId: string;
+  systemPrompt: string;
+  sessionId?: string;
+}
+
+export interface ModelFactoryResult {
+  model: LanguageModel;
+  useProviderInstructions?: boolean;
+  omitMaxOutputTokens?: boolean;
+  providerOptions?: Record<string, Record<string, unknown>>;
+}
+
+export interface ConnectOptions {
+  redirectStrategy?: OAuthRedirectStrategy;
+}
+
+export interface ConnectResult {
+  authorizationUrl?: string;
+  flowId?: string;
+  redirectStrategy?: OAuthRedirectStrategy;
+  redirectUri?: string;
+}
+
+export interface TokenResponse {
+  access_token: string;
+  refresh_token: string;
+  expires_in?: number;
+  id_token?: string;
+  token_type?: string;
+}
+
+export interface ConnectableProvider {
+  descriptor: ProviderDescriptor;
+  getStatus(): ProviderStatus;
+  connect(options?: ConnectOptions): Promise<ConnectResult>;
+  disconnect(): Promise<void>;
+  onTokensReceived(tokens: TokenResponse): Promise<void>;
+  createModel?(options: ModelFactoryOptions): Promise<ModelFactoryResult>;
+}

package/src/retry/policy.ts

@@ -0,0 +1,282 @@
+/**
+ * C6 retry policy contract and default provider.
+ *
+ * The policy owns retry classification, backoff computation, circuit state,
+ * and the no-retry-after-tool-activity side-effect barrier. `core/retry.ts`
+ * is a pinned compatibility forwarder to `retry/stream-chat.ts`, which
+ * resolves the active policy through `getRetryPolicy()`: a composed agent
+ * scope seeds its own agent-scoped policy (own circuit map), and unscoped
+ * consumers (the current Jean2 server path) fall back to one lazily created
+ * process-default policy whose circuit state lives for the process lifetime,
+ * exactly like the pre-C6 module-global map.
+ *
+ * `withRetryCircuitState` is the compatibility overlay seam: it overrides
+ * only the circuit map for the callback duration, exactly like the pre-C6
+ * scoped-circuit ALS. The server retry tests and legacy consumers keep using
+ * it until C8 retires the compat surface.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { ChatRetryErrorType } from '@capekai/types';
+import {
+  ApiErrorType,
+  classifyApiError,
+  type ClassifiedError,
+} from '../utils/errors';
+
+export interface StreamRetryPolicy {
+  maxRetries?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  jitterRatio?: number;
+}
+
+export interface CircuitState {
+  failures: number;
+  lastFailureAt: number;
+  openUntil: number;
+}
+
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BASE_DELAY_MS = 2_000;
+const DEFAULT_MAX_DELAY_MS = 30_000;
+const DEFAULT_JITTER_RATIO = 0.2;
+const CIRCUIT_FAILURE_THRESHOLD = 3;
+const CIRCUIT_FAILURE_WINDOW_MS = 60_000;
+const CIRCUIT_COOLDOWN_MS = 30_000;
+
+/** Inputs for the retry decision on one failed attempt. */
+export interface RetryDecisionContext {
+  /** One-based attempt number of the failing attempt. */
+  retryNumber: number;
+  maxRetries: number;
+  classified: ClassifiedError;
+  attemptHadToolActivity: boolean;
+  aborted: boolean;
+}
+
+/**
+ * C6 retry policy contract. Agent-scoped behind `capekRetryPolicyKey`. The
+ * default provider reproduces the exact pre-C6 behavior; a custom provider
+ * may vary the numeric defaults, the backoff curve, the circuit thresholds,
+ * or the side-effect barrier without the stream loop changing.
+ */
+export interface RetryPolicy {
+  readonly id: string;
+  /** Numeric defaults used when per-call policy options omit a field. */
+  readonly defaults: Readonly<Required<StreamRetryPolicy>>;
+  /** Resolves an already-classified error as-is, otherwise classifies it. */
+  classify(error: unknown): ClassifiedError;
+  /** Maps a classified error to the `chat.retry` errorType value. */
+  retryErrorType(classified: ClassifiedError): ChatRetryErrorType;
+  /** True when the failed attempt may be retried: retryable, retries remain,
+   * the attempt had no tool activity, and the run is not aborted. The
+   * tool-activity check is the side-effect barrier. */
+  canRetry(context: RetryDecisionContext): boolean;
+  /** Exponential backoff with jitter, honoring Retry-After as a minimum. */
+  calculateDelay(
+    retryNumber: number,
+    classified: ClassifiedError,
+    baseDelayMs: number,
+    maxDelayMs: number,
+    jitterRatio: number,
+  ): number;
+  /** Abort-aware backoff wait; rejects with `RetryDelayAbortedError`. */
+  waitForRetry(delayMs: number, signal: AbortSignal): Promise<void>;
+  /** Circuit key derived from provider and model identity. */
+  circuitKey(providerId: string | null | undefined, modelId: string | null | undefined): string;
+  /** Milliseconds until the open circuit for the key closes, or 0. */
+  openCircuitRemainingMs(key: string): number;
+  /** Records a failed attempt; returns whether the circuit just opened. */
+  recordCircuitFailure(key: string): boolean;
+  /** Closes the circuit for the key (successful stream or expiry). */
+  resetCircuit(key: string): void;
+  /** Message override for the exhausted `chat.retry` event, or null to keep
+   * the classified error message. */
+  exhaustedMessage(context: {
+    attemptHadToolActivity: boolean;
+    circuitOpened: boolean;
+  }): string | null;
+}
+
+export class RetryDelayAbortedError extends Error {
+  constructor() {
+    super('Retry delay aborted');
+    this.name = 'RetryDelayAbortedError';
+  }
+}
+
+function isClassifiedError(err: unknown): err is ClassifiedError {
+  if (typeof err !== 'object' || err === null) {
+    return false;
+  }
+
+  const candidate = err as Record<string, unknown>;
+  return (
+    typeof candidate.type === 'string'
+    && typeof candidate.retryable === 'boolean'
+    && typeof candidate.message === 'string'
+    && 'originalError' in candidate
+  );
+}
+
+function toRetryErrorType(type: ApiErrorType): ChatRetryErrorType {
+  if (type === ApiErrorType.RateLimit) return 'rate_limit';
+  if (type === ApiErrorType.Timeout) return 'timeout';
+  if (type === ApiErrorType.Network) return 'network';
+  return 'server_error';
+}
+
+/** Creates an empty circuit state map. Kept as the compat seam used by the
+ * server retry tests and by `withRetryCircuitState`. */
+export function createRetryCircuitState(): Map<string, CircuitState> {
+  return new Map<string, CircuitState>();
+}
+
+export interface RetryPolicyOptions {
+  id?: string;
+  /** When omitted the policy owns a fresh map for its lifetime. */
+  circuitState?: Map<string, CircuitState>;
+}
+
+/** The C6 default provider wrapping the exact pre-C6 behavior. */
+export function createRetryPolicy(options: RetryPolicyOptions = {}): RetryPolicy {
+  const id = options.id ?? 'retry.default';
+  const circuitState = options.circuitState ?? createRetryCircuitState();
+
+  function activeStateMap(): Map<string, CircuitState> {
+    return scopedCircuitState.getStore() ?? circuitState;
+  }
+
+  const policy: RetryPolicy = {
+    id,
+    defaults: {
+      maxRetries: DEFAULT_MAX_RETRIES,
+      baseDelayMs: DEFAULT_BASE_DELAY_MS,
+      maxDelayMs: DEFAULT_MAX_DELAY_MS,
+      jitterRatio: DEFAULT_JITTER_RATIO,
+    },
+    classify(error: unknown): ClassifiedError {
+      return isClassifiedError(error) ? error : classifyApiError(error);
+    },
+    retryErrorType(classified: ClassifiedError): ChatRetryErrorType {
+      return toRetryErrorType(classified.type);
+    },
+    canRetry(context: RetryDecisionContext): boolean {
+      return context.classified.retryable
+        && context.retryNumber <= context.maxRetries
+        && !context.attemptHadToolActivity
+        && !context.aborted;
+    },
+    calculateDelay(
+      retryNumber: number,
+      classified: ClassifiedError,
+      baseDelayMs: number,
+      maxDelayMs: number,
+      jitterRatio: number,
+    ): number {
+      const exponentialDelay = Math.min(baseDelayMs * 2 ** (retryNumber - 1), maxDelayMs);
+      const jitterRange = exponentialDelay * jitterRatio;
+      const jitteredDelay = Math.round(exponentialDelay - jitterRange + Math.random() * jitterRange * 2);
+      return Math.max(jitteredDelay, classified.retryAfterMs ?? 0);
+    },
+    waitForRetry(delayMs: number, signal: AbortSignal): Promise<void> {
+      if (signal.aborted) {
+        return Promise.reject(new RetryDelayAbortedError());
+      }
+
+      return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          signal.removeEventListener('abort', onAbort);
+          resolve();
+        }, delayMs);
+        const onAbort = () => {
+          clearTimeout(timeout);
+          signal.removeEventListener('abort', onAbort);
+          reject(new RetryDelayAbortedError());
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+      });
+    },
+    circuitKey(providerId: string | null | undefined, modelId: string | null | undefined): string {
+      return `${providerId ?? 'default'}:${modelId ?? 'default'}`;
+    },
+    openCircuitRemainingMs(key: string): number {
+      const states = activeStateMap();
+      const state = states.get(key);
+      if (!state) return 0;
+
+      const now = Date.now();
+      if (state.openUntil === 0) {
+        if (now - state.lastFailureAt > CIRCUIT_FAILURE_WINDOW_MS) {
+          states.delete(key);
+        }
+        return 0;
+      }
+      if (state.openUntil <= now) {
+        states.delete(key);
+        return 0;
+      }
+      return state.openUntil - now;
+    },
+    recordCircuitFailure(key: string): boolean {
+      const now = Date.now();
+      const states = activeStateMap();
+      const previous = states.get(key);
+      const previousFailures = previous && now - previous.lastFailureAt <= CIRCUIT_FAILURE_WINDOW_MS
+        ? previous.failures
+        : 0;
+      const failures = previousFailures + 1;
+      const openUntil = failures >= CIRCUIT_FAILURE_THRESHOLD
+        ? now + CIRCUIT_COOLDOWN_MS
+        : 0;
+      states.set(key, { failures, lastFailureAt: now, openUntil });
+      return openUntil > 0;
+    },
+    resetCircuit(key: string): void {
+      activeStateMap().delete(key);
+    },
+    exhaustedMessage(context: { attemptHadToolActivity: boolean; circuitOpened: boolean }): string | null {
+      if (context.attemptHadToolActivity) {
+        return 'Automatic retry stopped because the failed attempt used a tool and replay could duplicate side effects.';
+      }
+      if (context.circuitOpened) {
+        return 'Automatic retry stopped after repeated provider failures.';
+      }
+      return null;
+    },
+  };
+  return policy;
+}
+
+const scopedPolicy = new AsyncLocalStorage<RetryPolicy>();
+const scopedCircuitState = new AsyncLocalStorage<Map<string, CircuitState>>();
+let processDefaultPolicy: RetryPolicy | undefined;
+
+/** Resolves the policy seeded for the active agent scope, falling back to one
+ * lazily created process-default policy for consumers that run outside a
+ * composed scope (the current Jean2 server path). The process default keeps
+ * the exact pre-C6 process-wide circuit behavior. */
+export function getRetryPolicy(): RetryPolicy {
+  return scopedPolicy.getStore()
+    ?? (processDefaultPolicy ??= createRetryPolicy({ id: 'retry.process-default' }));
+}
+
+/** Seeds a policy for the callback duration. `enterAgentScope` seeds the
+ * composed agent scope's policy here. */
+export function withRetryPolicy<T>(policy: RetryPolicy, callback: () => T): T {
+  return scopedPolicy.run(policy, callback);
+}
+
+/** Compatibility overlay: replaces only the circuit map for the callback
+ * duration, exactly like the pre-C6 scoped-circuit AsyncLocalStorage. */
+export function withRetryCircuitState<T>(state: Map<string, CircuitState>, callback: () => T): T {
+  return scopedCircuitState.run(state, callback);
+}
+
+/** Test-only reset of the lazily created process default so unscoped-path
+ * tests never leak circuit state across cases. Exported from this module
+ * only; no package subpath re-exports it. */
+export function resetDefaultRetryPolicyForTests(): void {
+  processDefaultPolicy = undefined;
+}