@bermudi/pi-delegate 0.1.0

package/config.ts

@@ -0,0 +1,358 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import {
+  MAX_ASYNC_TICKETS,
+  MAX_CONCURRENCY,
+  OUTPUT_SPILL_TAIL_CHARS,
+  OUTPUT_SPILL_THRESHOLD_CHARS,
+} from "./constants.ts";
+
+export interface DelegateConfig {
+  agent: {
+    /** Global default model for all agent types. */
+    default: string | null;
+    /** Per-agent-type model overrides. Keys are agent names or "default". */
+    [agentType: string]: string | null | undefined;
+  };
+  /** Per-model and per-provider concurrency limits. */
+  concurrency: {
+    /** Default concurrency limit for unspecified models. */
+    default: number;
+    /** Per-provider limits (e.g. "llamacpp": 2). */
+    providers?: Record<string, number>;
+    /** Per-model limits keyed by "provider/modelId". */
+    models?: Record<string, number>;
+  };
+  /** Hard ceiling on total concurrent agents across all models. */
+  maxConcurrent?: number;
+  /** Max concurrent async tickets. */
+  maxAsyncTickets?: number;
+  /** Maximum inactivity before cooperative stall cancellation is requested (0 disables). */
+  stallTimeoutMs?: number;
+  /** Whole-task transient-error retry settings. */
+  retry?: {
+    /** Max whole-task retries after the initial attempt (0 = no retry). */
+    wholeTaskMaxRetries?: number;
+    /** Base delay (ms) for exponential backoff between whole-task retries. */
+    wholeTaskBaseDelayMs?: number;
+  };
+  /** User-scope extension sources to load for subagents by provider. */
+  providerExtensions?: {
+    [provider: string]: readonly string[];
+  };
+  /** LLM-facing output bounding: over-threshold final output is spilled to a
+   *  temp file with a tail kept in-context. See `spill.ts`. */
+  output?: {
+    /** Over this many chars (strictly), spill. Default 8000. */
+    spillThresholdChars?: number;
+    /** Tail length (chars) kept in-context when spilled. Default 2000. */
+    spillTailChars?: number;
+  };
+}
+
+const DELEGATE_CONFIG_DIR = path.join(os.homedir(), ".pi", "agent");
+const DELEGATE_CONFIG_PATH = path.join(DELEGATE_CONFIG_DIR, "delegate.json");
+
+function normalizeProviderExtensions(
+  raw: unknown,
+): Record<string, readonly string[]> {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+
+  // A null-prototype map keeps config keys such as `constructor` and
+  // `__proto__` from resolving to Object.prototype members or mutating the
+  // map's prototype during normalization.
+  const out = Object.create(null) as Record<string, readonly string[]>;
+  for (const [provider, entries] of Object.entries(
+    raw as Record<string, unknown>,
+  )) {
+    const normalizedProvider = provider.trim().toLowerCase();
+    if (!normalizedProvider || !Array.isArray(entries)) continue;
+    const normalizedEntries = entries
+      .map((entry) => (typeof entry === "string" ? entry.trim() : ""))
+      .filter((entry): entry is string => entry.length > 0);
+    if (normalizedEntries.length === 0) continue;
+    out[normalizedProvider] = [...new Set(normalizedEntries)];
+  }
+
+  return out;
+}
+
+// Provider-scoped opt-in extension map for subagents. Keep this aligned with
+// the currently shipped codex remote-compaction integration. `delegate.json`
+// `providerExtensions` replaces a provider's entries (it does not append); an
+// empty array is ignored so the default persists.
+const DEFAULT_PROVIDER_EXTENSIONS: Record<string, readonly string[]> = {
+  "openai-codex": ["npm:@ogulcancelik/pi-codex-compaction"],
+};
+
+function resolveProviderExtensions(
+  raw: unknown,
+): Record<string, readonly string[]> {
+  const out = Object.create(null) as Record<string, readonly string[]>;
+  Object.assign(
+    out,
+    DEFAULT_PROVIDER_EXTENSIONS,
+    normalizeProviderExtensions(raw),
+  );
+  return out;
+}
+
+const DEFAULT_DELEGATE_CONFIG: DelegateConfig = {
+  agent: { default: null },
+  concurrency: { default: MAX_CONCURRENCY },
+  maxConcurrent: MAX_CONCURRENCY,
+  stallTimeoutMs: 15 * 60 * 1000,
+  retry: {
+    wholeTaskMaxRetries: 3,
+    wholeTaskBaseDelayMs: 1_000,
+  },
+  providerExtensions: DEFAULT_PROVIDER_EXTENSIONS,
+  output: {
+    spillThresholdChars: OUTPUT_SPILL_THRESHOLD_CHARS,
+    spillTailChars: OUTPUT_SPILL_TAIL_CHARS,
+  },
+};
+
+/** Module-level config singleton. Loaded lazily, mutated by setters. */
+let __delegateConfig: DelegateConfig = {
+  ...DEFAULT_DELEGATE_CONFIG,
+  agent: { ...DEFAULT_DELEGATE_CONFIG.agent },
+  concurrency: { ...DEFAULT_DELEGATE_CONFIG.concurrency },
+};
+let stallTimeoutOverrideForTesting: number | undefined;
+
+/** Read delegate config from disk. Returns defaults if file missing or corrupt. */
+export function loadDelegateConfig(): DelegateConfig {
+  try {
+    const raw = fs.readFileSync(DELEGATE_CONFIG_PATH, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      return structuredClone(DEFAULT_DELEGATE_CONFIG);
+    // Merge with defaults so new fields are always present
+    return {
+      ...DEFAULT_DELEGATE_CONFIG,
+      ...parsed,
+      agent: { ...DEFAULT_DELEGATE_CONFIG.agent, ...(parsed.agent ?? {}) },
+      concurrency: {
+        ...DEFAULT_DELEGATE_CONFIG.concurrency,
+        ...(parsed.concurrency ?? {}),
+      },
+      retry: { ...DEFAULT_DELEGATE_CONFIG.retry, ...(parsed.retry ?? {}) },
+      providerExtensions: resolveProviderExtensions(parsed.providerExtensions),
+      output: { ...DEFAULT_DELEGATE_CONFIG.output, ...(parsed.output ?? {}) },
+    } as DelegateConfig;
+  } catch {
+    return structuredClone(DEFAULT_DELEGATE_CONFIG);
+  }
+}
+
+/** Initialize module config from disk. Called once at extension load. */
+function initDelegateConfig(): void {
+  __delegateConfig = loadDelegateConfig();
+}
+
+// Auto-init on module load
+initDelegateConfig();
+
+/**
+ * Test-only seam: reset the module config singleton to compiled defaults.
+ *
+ * `__delegateConfig` is auto-initialized from `~/.pi/agent/delegate.json` at
+ * import time, so any test that exercises the config-dependent renderers
+ * (e.g. the `queued (N running)` label, which reads `getMaxConcurrent()`) is
+ * otherwise at the mercy of the developer's on-disk `maxConcurrent`. There are
+ * no production mutators (the file is the only write path); this restores the
+ * deterministic default baseline for tests, mirroring `_resetPoolForTesting` /
+ * `_resetGlobalConcurrencyForTesting`.
+ */
+export function _resetDelegateConfigForTesting(): void {
+  __delegateConfig = structuredClone(DEFAULT_DELEGATE_CONFIG);
+  stallTimeoutOverrideForTesting = undefined;
+}
+
+/** @internal Test-only override; production configuration is file-only. */
+export function _setStallTimeoutForTesting(
+  timeoutMs: number | undefined,
+): void {
+  stallTimeoutOverrideForTesting = timeoutMs;
+}
+
+/**
+ * Test-only seam: replace delegate config at runtime.
+ *
+ * This is only for deterministic tests; production config is file-only and not
+ * expected to mutate at runtime.
+ */
+export function _setDelegateConfigForTesting(
+  config: Partial<DelegateConfig> = {},
+): void {
+  __delegateConfig = {
+    ...DEFAULT_DELEGATE_CONFIG,
+    ...config,
+    agent: {
+      ...DEFAULT_DELEGATE_CONFIG.agent,
+      ...(config.agent ?? {}),
+    },
+    concurrency: {
+      ...DEFAULT_DELEGATE_CONFIG.concurrency,
+      ...(config.concurrency ?? {}),
+    },
+    retry: {
+      ...DEFAULT_DELEGATE_CONFIG.retry,
+      ...(config.retry ?? {}),
+    },
+    providerExtensions: resolveProviderExtensions(config.providerExtensions),
+    output: {
+      ...DEFAULT_DELEGATE_CONFIG.output,
+      ...(config.output ?? {}),
+    },
+  };
+  stallTimeoutOverrideForTesting = undefined;
+}
+
+/**
+ * Get the configured provider-scoped extension allowlist for subagents.
+ * Explicit configs are normalized here too, so callers using the injected
+ * config form get the same case-insensitive and replace-per-provider
+ * semantics as the file-backed singleton.
+ */
+export function getSubagentProviderExtensionMap(
+  config: DelegateConfig = __delegateConfig,
+): Readonly<Record<string, readonly string[]>> {
+  return config.providerExtensions
+    ? resolveProviderExtensions(config.providerExtensions)
+    : DEFAULT_PROVIDER_EXTENSIONS;
+}
+
+/**
+ * Get extension sources for a specific provider's subagents. Provider matching is
+ * case-insensitive.
+ */
+export function getSubagentProviderExtensionsForProvider(
+  provider: string | undefined,
+  config: DelegateConfig = __delegateConfig,
+): readonly string[] {
+  const normalized = provider?.trim().toLowerCase();
+  if (!normalized) return [];
+  const extensions = getSubagentProviderExtensionMap(config);
+  return Object.prototype.hasOwnProperty.call(extensions, normalized)
+    ? (extensions[normalized] ?? [])
+    : [];
+}
+
+// ── Config Getters ───────────────────────────────────────────────────────
+
+/**
+ * Get the effective concurrency limit for a model key.
+ *
+ * Precedence: per-model → per-provider → default. Accepts an injected config
+ * so the precedence chain is testable without touching the module singleton
+ * (there are no config mutators — `delegate.json` is the only write path).
+ */
+export function getConcurrencyLimit(
+  modelKey: string,
+  config: DelegateConfig = __delegateConfig,
+): number {
+  // 1. Per-model
+  const perModel = config.concurrency.models?.[modelKey];
+  if (perModel != null) return perModel;
+  // 2. Per-provider
+  const provider = modelKey.split("/")[0];
+  const perProvider = config.concurrency.providers?.[provider];
+  if (perProvider != null) return perProvider;
+  // 3. Default
+  return config.concurrency.default;
+}
+
+/** Get the effective max async tickets limit. */
+export function getMaxAsyncTickets(): number {
+  return __delegateConfig.maxAsyncTickets ?? MAX_ASYNC_TICKETS;
+}
+
+/** Get the hard ceiling on total concurrent agents. */
+export function getMaxConcurrent(): number {
+  return __delegateConfig.maxConcurrent ?? MAX_CONCURRENCY;
+}
+
+/** Maximum inactivity before cooperative stall cancellation is requested.
+ * `0` disables detection; malformed values fall back to the compiled default. */
+export function getStallTimeoutMs(
+  config: DelegateConfig = __delegateConfig,
+): number {
+  const configured = stallTimeoutOverrideForTesting ?? config.stallTimeoutMs;
+  if (
+    typeof configured === "number" &&
+    Number.isFinite(configured) &&
+    configured >= 0
+  ) {
+    return configured;
+  }
+  return DEFAULT_DELEGATE_CONFIG.stallTimeoutMs!;
+}
+
+/** Get the max whole-task retries after the initial attempt. */
+export function getWholeTaskMaxRetries(): number {
+  return __delegateConfig.retry?.wholeTaskMaxRetries ?? 3;
+}
+
+/** Get the base delay (ms) for whole-task retry exponential backoff. */
+export function getWholeTaskBaseDelayMs(): number {
+  return __delegateConfig.retry?.wholeTaskBaseDelayMs ?? 1_000;
+}
+
+/** Get the output-spill threshold (chars). Over this, final output is spilled. */
+export function getOutputSpillThreshold(): number {
+  return (
+    __delegateConfig.output?.spillThresholdChars ?? OUTPUT_SPILL_THRESHOLD_CHARS
+  );
+}
+
+/** Get the output-spill tail length (chars) kept in-context when spilled. */
+export function getOutputSpillTail(): number {
+  return __delegateConfig.output?.spillTailChars ?? OUTPUT_SPILL_TAIL_CHARS;
+}
+
+/**
+ * Resolve an *explicit* model spec string using the precedence chain.
+ * Returns the first non-null, non-empty string value, or `undefined` when no
+ * explicit spec is set — in which case the caller inherits the parent
+ * session's model object directly (see extension.ts).
+ *
+ * Parent inheritance is intentionally NOT a tier here: the parent model is
+ * already a resolved, authenticated Model object. Re-resolving its id string
+ * through the registry would be both redundant and lossy for composite ids
+ * such as OpenRouter's "provider/upstream/model", whose first segment is an
+ * upstream provider name, not a configured pi provider — that misroutes auth
+ * lookup to the wrong provider.
+ *
+ * Precedence (highest to lowest):
+ *   1. taskModel                 — per-task explicit override (from API call)
+ *   2. config.agent[agentType]   — config per-type (delegate.json)
+ *   3. config.agent["default"]   — config global
+ *   4. frontmatterModel          — agent .md frontmatter
+ */
+export function resolveModelSpec(options: {
+  taskModel?: string;
+  agentType: string;
+  frontmatterModel?: string;
+  config?: DelegateConfig;
+}): string | undefined {
+  const {
+    taskModel,
+    agentType,
+    frontmatterModel,
+    config = __delegateConfig,
+  } = options;
+
+  const candidates: Array<string | null | undefined> = [
+    taskModel,
+    config.agent[agentType] as string | null | undefined,
+    config.agent["default"],
+    frontmatterModel,
+  ];
+
+  return candidates.find(
+    (v): v is string => typeof v === "string" && v.length > 0,
+  );
+}

package/constants.ts

@@ -0,0 +1,41 @@
+/** Full-capability agent set. Inline-task default and the `*` shorthand.
+ *  Bash subsumes search, so the dedicated grep/find/ls tools are excluded. */
+export const DEFAULT_TOOLS = ["read", "write", "edit", "bash"];
+
+/** Read-only scout set: search without a shell. The `ro` shorthand. */
+export const READONLY_TOOLS = ["read", "grep", "find", "ls"];
+
+/** Maximum concurrent subagent tasks. Prevents rate-limit thundering herds. */
+export const MAX_CONCURRENCY = 3;
+
+/** Maximum concurrent background async tickets. */
+export const MAX_ASYNC_TICKETS = 5;
+
+/** Completed tickets cleaned up after 30 minutes. */
+export const ASYNC_TICKET_TTL_MS = 30 * 60 * 1000;
+
+/** Subagent final output longer than this (chars) is spilled to a temp file,
+ *  keeping only a tail in the LLM-facing context. See `spill.ts`. */
+export const OUTPUT_SPILL_THRESHOLD_CHARS = 8000;
+
+/** Tail length (chars) kept in-context when an output is spilled. */
+export const OUTPUT_SPILL_TAIL_CHARS = 2000;
+
+/** Literal union of valid thinking levels. Source of truth for both the
+ *  runtime Set (below) and the TypeBox schema's static type — the `as const`
+ *  tuple keeps `StringEnum`'s `T[number]` narrow so `DelegateArguments["tasks"]`
+ *  projects `thinking` to the literal union rather than `string`. */
+export const VALID_THINKING_LEVELS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+] as const;
+
+/** Runtime membership check for thinking levels. Kept as `Set<string>` (not
+ *  `Set<VALID_THINKING_LEVELS[number]>`) so the `.has(string)` call sites in
+ *  task-resolution.ts and agents.ts stay ergonomic under strict typing. */
+export const VALID_THINKING: Set<string> = new Set(VALID_THINKING_LEVELS);

package/delegate.ts

@@ -0,0 +1,115 @@
+export { default } from "./extension.ts";
+
+export type {
+  AgentConfig,
+  SessionAction,
+  DelegateAction,
+  DelegateArguments,
+  TaskDef,
+  AsyncTicket,
+  ResolvedTask,
+  ToolActivity,
+  TaskProgress,
+  DelegateDetails,
+  TaskResult,
+  TaskFailureKind,
+  ReuseIntent,
+  AgentRunConfig,
+  TaskRunEnv,
+} from "./types.ts";
+export type { DelegateConfig } from "./config.ts";
+
+export {
+  DEFAULT_TOOLS,
+  READONLY_TOOLS,
+  MAX_CONCURRENCY,
+  VALID_THINKING,
+} from "./constants.ts";
+export { TOOL_FACTORIES, resolveToolGroups } from "./tools.ts";
+export {
+  loadDelegateConfig,
+  getConcurrencyLimit,
+  getMaxAsyncTickets,
+  getMaxConcurrent,
+  getStallTimeoutMs,
+  resolveModelSpec,
+  getOutputSpillThreshold,
+  getOutputSpillTail,
+} from "./config.ts";
+export {
+  checkout,
+  commit,
+  configFor,
+  closePooledAgent,
+  closeAllPooledAgents,
+  listPooledAgents,
+  withSessionLock,
+} from "./pool.ts";
+export type {
+  FrozenConfig,
+  ConfigCandidate,
+  ConfigMismatch,
+  CheckoutResult,
+  CommitPayload,
+} from "./pool.ts";
+export {
+  ticketRegistry,
+  sweepTickets,
+  cancelTicketForShutdown,
+  isSessionBusy,
+  handlePoll,
+  handleCancel,
+  handleWait,
+  notifyWaiters,
+  deliverTicketResults,
+  resolveFinalTicketStatus,
+  formatCompletedTicket,
+} from "./tickets.ts";
+export { runAgentSession } from "./runner.ts";
+export { getHostDeps } from "./host.ts";
+export type { HostDeps, HostDepsOptions } from "./host.ts";
+export {
+  emptyUsage,
+  snapshotSessionUsage,
+  usageDelta,
+  addUsage,
+  sumUsage,
+} from "./usage.ts";
+export type { SessionUsageSnapshot } from "./usage.ts";
+export {
+  truncLine,
+  shortenPath,
+  getActivityAge,
+  fmtDuration,
+  fmtTokens,
+  trunc,
+  tree,
+  indent,
+  formatFailedTask,
+  formatCompletedTask,
+} from "./format.ts";
+export {
+  parseFrontmatter,
+  findProjectRoot,
+  loadAgentFile,
+  loadClaudeAgentFile,
+  discoverAgents,
+  buildSubagentSystemPrompt,
+  DEFAULT_SUBAGENT_SYSTEM_PROMPT,
+} from "./agents.ts";
+export { buildParentTranscript, extractTextContent } from "./parent-context.ts";
+export { extractTouchedFromActivities } from "./file-tracking.ts";
+export {
+  resolveModel,
+  resolveModelRequest,
+  findAvailableAlternative,
+} from "./model.ts";
+export { readDelegateSettingsFile, loadDelegateSettings } from "./settings.ts";
+export { resolveCwd, extractOutput, extractUsage } from "./utils.ts";
+export {
+  decideSpill,
+  spillToTempFile,
+  renderOutputForLLM,
+  renderOutputForPoll,
+} from "./spill.ts";
+export type { SpillDecision } from "./spill.ts";