pi-long-task 0.4.0 → 0.6.0

package/src/worker_config.ts

@@ -1,10 +1,21 @@
+import {
+  NetworkRecoveryConfigError,
+  resolveNetworkRecoveryConfig,
+  type NetworkRecoveryConfigInput,
+} from "./network_recovery_config.ts";
+
 export interface ParsedWorkerRuntimeConfig {
   modelName?: string;
   maxAttemptsPerTask?: number;
   taskTimeoutMs?: number;
   maxBashTimeoutMs?: number;
+  workerSessionReuseEnabled?: boolean;
+  workerSessionReuseContextThresholdPercent?: number;
+  networkRecovery?: NetworkRecoveryConfigInput;
 }
 
+type MutableWorkerRuntimeConfig = ParsedWorkerRuntimeConfig & { provider?: string; model?: string };
+
 const MODEL_TOKEN_RE = /[A-Za-z0-9][A-Za-z0-9._~:+/@-]*/;
 const STOP_WORDS = new Set([
   "and",
@@ -28,10 +39,13 @@ const STOP_WORDS = new Set([
 ]);
 
 export function parseWorkerRuntimeConfig(text: string): ParsedWorkerRuntimeConfig {
-  const state: ParsedWorkerRuntimeConfig & { provider?: string; model?: string } = {};
+  const state: MutableWorkerRuntimeConfig = {};
 
   parseLineDirectives(text, state);
   parseNaturalLanguageDirectives(text, state);
+  if (state.networkRecovery) {
+    resolveNetworkRecoveryConfig(state.networkRecovery);
+  }
 
   const modelName = combineProviderAndModel(state.provider, state.model);
   return {
@@ -39,13 +53,17 @@ export function parseWorkerRuntimeConfig(text: string): ParsedWorkerRuntimeConfi
     ...(state.maxAttemptsPerTask !== undefined ? { maxAttemptsPerTask: state.maxAttemptsPerTask } : {}),
     ...(state.taskTimeoutMs !== undefined ? { taskTimeoutMs: state.taskTimeoutMs } : {}),
     ...(state.maxBashTimeoutMs !== undefined ? { maxBashTimeoutMs: state.maxBashTimeoutMs } : {}),
+    ...(state.workerSessionReuseEnabled !== undefined
+      ? { workerSessionReuseEnabled: state.workerSessionReuseEnabled }
+      : {}),
+    ...(state.workerSessionReuseContextThresholdPercent !== undefined
+      ? { workerSessionReuseContextThresholdPercent: state.workerSessionReuseContextThresholdPercent }
+      : {}),
+    ...(state.networkRecovery ? { networkRecovery: { ...state.networkRecovery } } : {}),
   };
 }
 
-function parseLineDirectives(
-  text: string,
-  state: ParsedWorkerRuntimeConfig & { provider?: string; model?: string },
-): void {
+function parseLineDirectives(text: string, state: MutableWorkerRuntimeConfig): void {
   for (const rawLine of text.split(/\r?\n/)) {
     const line = rawLine.replace(/^\s{0,3}>+\s?/, "").trim();
     const match = line.match(
@@ -64,10 +82,7 @@ function parseLineDirectives(
   }
 }
 
-function parseNaturalLanguageDirectives(
-  text: string,
-  state: ParsedWorkerRuntimeConfig & { provider?: string; model?: string },
-): void {
+function parseNaturalLanguageDirectives(text: string, state: MutableWorkerRuntimeConfig): void {
   captureTokens(
     text,
     /\bworker\s+(?:model|provider\/model)\s*(?:is|=|:|to|as)?\s*[`'"]?([A-Za-z0-9][A-Za-z0-9._~:+/@-]*)/gi,
@@ -139,13 +154,43 @@ function parseNaturalLanguageDirectives(
       state.maxBashTimeoutMs = value;
     },
   );
+
+  for (const match of text.matchAll(
+    /\b(?:worker\s+)?session\s+reuse(?:\s+is|\s*=|\s*:|\s+to)?\s+(enabled|disabled|on|off|true|false)\b/gi,
+  )) {
+    const enabled = booleanSetting(match[1] ?? "");
+    if (enabled !== undefined) state.workerSessionReuseEnabled = enabled;
+  }
+  for (const match of text.matchAll(
+    /\b(?:worker\s+)?(?:session\s+)?reuse\s+context(?:\s+usage)?\s+threshold\s*(?:is|=|:|to|of)?\s*(\d+(?:\.\d+)?)\s*%/gi,
+  )) {
+    const threshold = percentageFromText(match[1] ?? "");
+    if (threshold !== undefined) state.workerSessionReuseContextThresholdPercent = threshold;
+  }
 }
 
-function applyDirective(
-  key: string,
-  value: string,
-  state: ParsedWorkerRuntimeConfig & { provider?: string; model?: string },
-): void {
+function applyDirective(key: string, value: string, state: MutableWorkerRuntimeConfig): void {
+  if (/\bnetwork\b/.test(key) && /\brecover(?:y|ies)?\b/.test(key)) {
+    applyNetworkRecoveryDirective(key, value, state);
+    return;
+  }
+
+  if (/\breuse\b/.test(key) && /\b(?:threshold|context)\b/.test(key)) {
+    const threshold = percentageFromText(value);
+    if (threshold !== undefined) {
+      state.workerSessionReuseContextThresholdPercent = threshold;
+    }
+    return;
+  }
+
+  if (/\breuse\b/.test(key)) {
+    const enabled = booleanSetting(value);
+    if (enabled !== undefined) {
+      state.workerSessionReuseEnabled = enabled;
+    }
+    return;
+  }
+
   if (/\bprovider\b/.test(key)) {
     const token = modelToken(value);
     if (token) {
@@ -186,6 +231,64 @@ function applyDirective(
   }
 }
 
+function applyNetworkRecoveryDirective(key: string, value: string, state: MutableWorkerRuntimeConfig): void {
+  const recovery = (state.networkRecovery ??= {});
+
+  if (/\bbase\b/.test(key) && /\bdelay\b/.test(key)) {
+    recovery.baseDelayMs = requiredNetworkRecoveryDuration("base delay", value);
+    return;
+  }
+  if (/\bmax(?:imum)?\b/.test(key) && /\bdelay\b/.test(key)) {
+    recovery.maxDelayMs = requiredNetworkRecoveryDuration("maximum delay", value);
+    return;
+  }
+  if (/\b(?:outage|duration|wait)\b/.test(key)) {
+    const normalized = trimDirectiveValue(value)
+      .toLowerCase()
+      .replace(/[.!]+$/g, "")
+      .trim();
+    if (/^(?:unlimited|indefinite|indefinitely|until cancelled|until canceled)$/.test(normalized)) {
+      recovery.maxOutageMs = null;
+      return;
+    }
+    recovery.maxOutageMs = requiredNetworkRecoveryDuration("maximum outage", value);
+    return;
+  }
+  if (/\b(?:enabled?|enablement)\b/.test(key) || /\bnetwork recovery\b/.test(key)) {
+    const enabled = booleanSetting(value);
+    if (enabled === undefined) {
+      throw new NetworkRecoveryConfigError(
+        "Network recovery must be configured as enabled/disabled, on/off, true/false, or yes/no.",
+      );
+    }
+    recovery.enabled = enabled;
+    return;
+  }
+
+  throw new NetworkRecoveryConfigError(`Unknown network recovery configuration directive: ${key}.`);
+}
+
+function requiredNetworkRecoveryDuration(label: string, value: string): number {
+  const trimmed = trimDirectiveValue(value)
+    .replace(/[.!]+$/g, "")
+    .trim();
+  const match = /^(\d+(?:\.\d+)?)\s*(milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)?$/i.exec(
+    trimmed,
+  );
+  if (!match) {
+    throw new NetworkRecoveryConfigError(
+      `Network recovery ${label} must be a positive finite duration (for example 1000ms, 30s, or 5m).`,
+    );
+  }
+  const milliseconds = durationMsFromText(trimmed, { allowBareSeconds: true });
+  if (milliseconds === undefined) {
+    throw new NetworkRecoveryConfigError(
+      `Network recovery ${label} must be a positive finite duration (for example 1000ms, 30s, or 5m).`,
+    );
+  }
+  return milliseconds;
+}
+
 function captureTokens(text: string, pattern: RegExp, apply: (token: string) => void): void {
   for (const match of text.matchAll(pattern)) {
     const token = modelToken(match[1] ?? "");
@@ -250,6 +353,26 @@ function positiveIntegerFromText(value: string): number | undefined {
   return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
 }
 
+function percentageFromText(value: string): number | undefined {
+  const match = /\d+(?:\.\d+)?/.exec(value);
+  if (!match) {
+    return undefined;
+  }
+  const parsed = Number.parseFloat(match[0]);
+  return Number.isFinite(parsed) && parsed > 0 && parsed <= 100 ? parsed : undefined;
+}
+
+function booleanSetting(value: string): boolean | undefined {
+  const normalized = trimDirectiveValue(value).toLowerCase().split(/\s+/)[0];
+  if (normalized === "enabled" || normalized === "on" || normalized === "true" || normalized === "yes") {
+    return true;
+  }
+  if (normalized === "disabled" || normalized === "off" || normalized === "false" || normalized === "no") {
+    return false;
+  }
+  return undefined;
+}
+
 function durationMsFromText(value: string, options: { allowBareSeconds: boolean }): number | undefined {
   const match = /(\d+(?:\.\d+)?)\s*(milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)?\b/i.exec(
     value,

package/src/worker_reuse_policy.ts

@@ -0,0 +1,389 @@
+import path from "node:path";
+
+/** Reuse starts conservatively rotating before two thirds of the context is occupied. */
+export const DEFAULT_WORKER_SESSION_REUSE_CONTEXT_THRESHOLD_PERCENT = 62.5;
+export const DEFAULT_WORKER_SESSION_REUSE_ENABLED = true;
+
+export interface WorkerSessionReuseConfig {
+  enabled: boolean;
+  contextThresholdPercent: number;
+}
+
+export interface WorkerSessionCompatibilityInput {
+  coordinatorRunId: string;
+  repositoryRoot: string;
+  worktreeRoot?: string;
+  provider?: string;
+  modelName?: string;
+  model?: unknown;
+  tools?: readonly string[];
+  thinkingLevel?: string;
+  /** Any additional worker option whose value changes session behavior. */
+  workerOptions?: Readonly<Record<string, unknown>>;
+  agentDir?: string;
+  modelRuntime?: unknown;
+  authStorage?: unknown;
+  modelRegistry?: unknown;
+  settingsManager?: unknown;
+  resourceLoader?: unknown;
+  sessionFactory?: unknown;
+  /** Additional options that can alter the constructed AgentSession. */
+  sessionConfiguration?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * A run-scoped description of every input that can make two worker sessions
+ * incompatible. Individual fields are retained so policy diagnostics can name
+ * the mismatch instead of reporting only an opaque hash.
+ */
+export interface WorkerSessionCompatibilityFingerprint {
+  coordinatorRunId: string;
+  repositoryRoot: string;
+  worktreeRoot: string;
+  provider: string;
+  model: string;
+  workerOptions: string;
+  sessionConfiguration: string;
+}
+
+export type WorkerSessionHealth =
+  | "healthy"
+  | "unknown"
+  | "timed_out"
+  | "aborted"
+  | "cancelled"
+  | "unrecoverable_error"
+  | "invalid_state";
+
+export type WorkerSessionReuseState = "reusable" | "rotation_required" | "isolated";
+
+export type WorkerSessionRetryMode = "no_retry" | "safe_partial_continuation" | "independent_retry";
+
+export type WorkerSessionRetryReasonCode =
+  | "task_completed"
+  | "explicit_partial_work"
+  | "retry_after_timeout"
+  | "retry_after_abort"
+  | "retry_after_cancellation"
+  | "retry_after_error"
+  | "retry_after_invalid_result"
+  | "retry_after_non_partial_status";
+
+export interface WorkerSessionRetryInput {
+  done: boolean;
+  reportedStatus: string;
+  completeTaskResult: boolean;
+  timedOut: boolean;
+  aborted: boolean;
+  cancelled?: boolean;
+  error?: string;
+}
+
+export interface WorkerSessionRetryDecision {
+  mode: WorkerSessionRetryMode;
+  reasonCode: WorkerSessionRetryReasonCode;
+  mayContinueInSession: boolean;
+}
+
+export type WorkerSessionReuseReasonCode =
+  | "reuse_eligible"
+  | "reuse_disabled"
+  | "session_disposed"
+  | "session_active"
+  | "health_unknown"
+  | "health_timed_out"
+  | "health_aborted"
+  | "health_cancelled"
+  | "health_unrecoverable_error"
+  | "health_invalid_state"
+  | "coordinator_run_mismatch"
+  | "repository_mismatch"
+  | "worktree_mismatch"
+  | "provider_mismatch"
+  | "model_mismatch"
+  | "worker_options_mismatch"
+  | "session_configuration_mismatch"
+  | "context_usage_unavailable"
+  | "context_usage_invalid"
+  | "context_threshold_reached";
+
+export interface WorkerSessionReuseCandidate {
+  health: WorkerSessionHealth;
+  compatibility: WorkerSessionCompatibilityFingerprint;
+  /** A normalized percentage in the inclusive range 0..100. */
+  contextUsagePercent?: number;
+  assignmentState: "idle" | "active";
+  disposed: boolean;
+}
+
+export interface WorkerSessionReusePolicyInput {
+  config: WorkerSessionReuseConfig;
+  candidate: WorkerSessionReuseCandidate;
+  requestedCompatibility: WorkerSessionCompatibilityFingerprint;
+}
+
+export interface WorkerSessionReuseDecision {
+  state: WorkerSessionReuseState;
+  reasonCode: WorkerSessionReuseReasonCode;
+  reusable: boolean;
+  healthy: boolean;
+  contextUsagePercent?: number;
+  contextThresholdPercent: number;
+}
+
+const objectIds = new WeakMap<object, number>();
+const symbolIds = new Map<symbol, number>();
+let nextObjectId = 1;
+
+export function normalizeWorkerSessionReuseThreshold(value: unknown): number {
+  return isValidThresholdPercentage(value) ? value : DEFAULT_WORKER_SESSION_REUSE_CONTEXT_THRESHOLD_PERCENT;
+}
+
+export function resolveWorkerSessionReuseConfig(options: {
+  enabled?: boolean;
+  contextThresholdPercent?: number;
+}): WorkerSessionReuseConfig {
+  return {
+    enabled: options.enabled ?? DEFAULT_WORKER_SESSION_REUSE_ENABLED,
+    contextThresholdPercent: normalizeWorkerSessionReuseThreshold(options.contextThresholdPercent),
+  };
+}
+
+export function createWorkerSessionCompatibilityFingerprint(
+  input: WorkerSessionCompatibilityInput,
+): WorkerSessionCompatibilityFingerprint {
+  const parsedModel = splitProviderModel(input.modelName);
+  const provider = normalizeOptional(input.provider) ?? parsedModel.provider ?? "<default>";
+  const model = parsedModel.model
+    ? `name:${parsedModel.model}`
+    : input.model !== undefined
+      ? `value:${fingerprintValue(input.model)}`
+      : "<default>";
+  const repositoryRoot = path.resolve(input.repositoryRoot);
+  const worktreeRoot = path.resolve(input.worktreeRoot ?? repositoryRoot);
+
+  return {
+    coordinatorRunId: input.coordinatorRunId,
+    repositoryRoot,
+    worktreeRoot,
+    provider,
+    model,
+    workerOptions: canonicalRecord({
+      tools: input.tools ? [...input.tools] : undefined,
+      thinkingLevel: input.thinkingLevel,
+      workerOptions: input.workerOptions,
+    }),
+    sessionConfiguration: canonicalRecord({
+      agentDir: input.agentDir ? path.resolve(input.agentDir) : undefined,
+      modelRuntime: fingerprintOpaqueOption(input.modelRuntime),
+      authStorage: fingerprintOpaqueOption(input.authStorage),
+      modelRegistry: fingerprintOpaqueOption(input.modelRegistry),
+      settingsManager: fingerprintOpaqueOption(input.settingsManager),
+      resourceLoader: fingerprintOpaqueOption(input.resourceLoader),
+      sessionFactory: fingerprintOpaqueOption(input.sessionFactory),
+      sessionConfiguration: input.sessionConfiguration,
+    }),
+  };
+}
+
+/**
+ * Classify retry ownership independently from session health. Only an explicit,
+ * complete `partial` result is eligible to continue in the same session; every
+ * failure mode remains an independent attempt and therefore starts fresh.
+ */
+export function classifyWorkerSessionRetry(input: WorkerSessionRetryInput): WorkerSessionRetryDecision {
+  if (input.timedOut) {
+    return { mode: "independent_retry", reasonCode: "retry_after_timeout", mayContinueInSession: false };
+  }
+  if (input.cancelled) {
+    return { mode: "independent_retry", reasonCode: "retry_after_cancellation", mayContinueInSession: false };
+  }
+  if (input.aborted) {
+    return { mode: "independent_retry", reasonCode: "retry_after_abort", mayContinueInSession: false };
+  }
+  if (input.error) {
+    return { mode: "independent_retry", reasonCode: "retry_after_error", mayContinueInSession: false };
+  }
+  if (input.done) {
+    return { mode: "no_retry", reasonCode: "task_completed", mayContinueInSession: false };
+  }
+  if (!input.completeTaskResult) {
+    return { mode: "independent_retry", reasonCode: "retry_after_invalid_result", mayContinueInSession: false };
+  }
+  if (input.reportedStatus.trim().toLowerCase() === "partial") {
+    return { mode: "safe_partial_continuation", reasonCode: "explicit_partial_work", mayContinueInSession: true };
+  }
+  return { mode: "independent_retry", reasonCode: "retry_after_non_partial_status", mayContinueInSession: false };
+}
+
+/** Decide whether an idle completed session can accept the next assignment. */
+export function decideWorkerSessionReuse(input: WorkerSessionReusePolicyInput): WorkerSessionReuseDecision {
+  const threshold = normalizeWorkerSessionReuseThreshold(input.config.contextThresholdPercent);
+  const base = {
+    contextThresholdPercent: threshold,
+    ...(input.candidate.contextUsagePercent !== undefined
+      ? { contextUsagePercent: input.candidate.contextUsagePercent }
+      : {}),
+  };
+
+  if (!input.config.enabled) {
+    return {
+      ...base,
+      state: "isolated",
+      reasonCode: "reuse_disabled",
+      reusable: false,
+      healthy: input.candidate.health === "healthy" && !input.candidate.disposed,
+    };
+  }
+  if (input.candidate.disposed) {
+    return { ...base, state: "rotation_required", reasonCode: "session_disposed", reusable: false, healthy: false };
+  }
+  if (input.candidate.assignmentState === "active") {
+    return { ...base, state: "rotation_required", reasonCode: "session_active", reusable: false, healthy: false };
+  }
+  if (input.candidate.health !== "healthy") {
+    return {
+      ...base,
+      state: "rotation_required",
+      reasonCode: healthReason(input.candidate.health),
+      reusable: false,
+      healthy: false,
+    };
+  }
+
+  const incompatibility = compatibilityReason(input.candidate.compatibility, input.requestedCompatibility);
+  if (incompatibility) {
+    return { ...base, state: "rotation_required", reasonCode: incompatibility, reusable: false, healthy: true };
+  }
+
+  const usage = input.candidate.contextUsagePercent;
+  if (usage === undefined) {
+    return {
+      ...base,
+      state: "rotation_required",
+      reasonCode: "context_usage_unavailable",
+      reusable: false,
+      healthy: true,
+    };
+  }
+  if (!isValidContextUsagePercentage(usage)) {
+    return {
+      ...base,
+      state: "rotation_required",
+      reasonCode: "context_usage_invalid",
+      reusable: false,
+      healthy: true,
+    };
+  }
+  if (usage >= threshold) {
+    return {
+      ...base,
+      state: "rotation_required",
+      reasonCode: "context_threshold_reached",
+      reusable: false,
+      healthy: true,
+    };
+  }
+
+  return { ...base, state: "reusable", reasonCode: "reuse_eligible", reusable: true, healthy: true };
+}
+
+function compatibilityReason(
+  current: WorkerSessionCompatibilityFingerprint,
+  requested: WorkerSessionCompatibilityFingerprint,
+): WorkerSessionReuseReasonCode | undefined {
+  if (current.coordinatorRunId !== requested.coordinatorRunId) return "coordinator_run_mismatch";
+  if (current.repositoryRoot !== requested.repositoryRoot) return "repository_mismatch";
+  if (current.worktreeRoot !== requested.worktreeRoot) return "worktree_mismatch";
+  if (current.provider !== requested.provider) return "provider_mismatch";
+  if (current.model !== requested.model) return "model_mismatch";
+  if (current.workerOptions !== requested.workerOptions) return "worker_options_mismatch";
+  if (current.sessionConfiguration !== requested.sessionConfiguration) return "session_configuration_mismatch";
+  return undefined;
+}
+
+function healthReason(health: Exclude<WorkerSessionHealth, "healthy">): WorkerSessionReuseReasonCode {
+  return health === "unknown" ? "health_unknown" : `health_${health}`;
+}
+
+function splitProviderModel(modelName: string | undefined): { provider?: string; model?: string } {
+  const normalized = normalizeOptional(modelName);
+  if (!normalized) return {};
+  const separator = normalized.indexOf("/");
+  if (separator <= 0 || separator === normalized.length - 1) return { model: normalized };
+  return { provider: normalized.slice(0, separator), model: normalized.slice(separator + 1) };
+}
+
+function canonicalRecord(value: Readonly<Record<string, unknown>>, seen = new Set<object>()): string {
+  return Object.keys(value)
+    .sort()
+    .filter((key) => value[key] !== undefined)
+    .map((key) => `${JSON.stringify(key)}:${fingerprintValue(value[key], seen)}`)
+    .join("|");
+}
+
+function fingerprintValue(value: unknown, seen = new Set<object>()): string {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+  if (typeof value === "number") return Number.isFinite(value) ? String(value) : `number:${String(value)}`;
+  if (typeof value === "bigint" || typeof value === "symbol" || typeof value === "function") {
+    return opaqueValue(value);
+  }
+  if (value === undefined) return "undefined";
+  if (Array.isArray(value)) {
+    if (seen.has(value)) return opaqueValue(value);
+    seen.add(value);
+    const result = `[${value.map((item) => fingerprintValue(item, seen)).join(",")}]`;
+    seen.delete(value);
+    return result;
+  }
+  if (typeof value === "object") {
+    if (seen.has(value)) return opaqueValue(value);
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype === Object.prototype || prototype === null) {
+      seen.add(value);
+      const result = `{${canonicalRecord(value as Record<string, unknown>, seen)}}`;
+      seen.delete(value);
+      return result;
+    }
+    return opaqueValue(value);
+  }
+  return String(value);
+}
+
+function fingerprintOpaqueOption(value: unknown): string | undefined {
+  return value === undefined ? undefined : opaqueValue(value);
+}
+
+function opaqueValue(value: unknown): string {
+  if ((typeof value !== "object" || value === null) && typeof value !== "function" && typeof value !== "symbol") {
+    return `${typeof value}:${String(value)}`;
+  }
+  if (typeof value === "symbol") {
+    let symbolId = symbolIds.get(value);
+    if (!symbolId) {
+      symbolId = nextObjectId++;
+      symbolIds.set(value, symbolId);
+    }
+    return `identity:${symbolId}`;
+  }
+  const object = value as object;
+  let objectId = objectIds.get(object);
+  if (!objectId) {
+    objectId = nextObjectId++;
+    objectIds.set(object, objectId);
+  }
+  return `identity:${objectId}`;
+}
+
+function normalizeOptional(value: string | undefined): string | undefined {
+  const normalized = value?.trim();
+  return normalized || undefined;
+}
+
+function isValidThresholdPercentage(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= 100;
+}
+
+function isValidContextUsagePercentage(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 100;
+}