@nredd/pi-subagents 0.0.0-stage → 0.22.0-nredd.10

package/src/quota-admission.ts

@@ -0,0 +1,121 @@
+/**
+ * quota-admission.ts — ask a subscription router whether a dispatch may start.
+ *
+ * Quota tracking lives in a separate extension (nredd/pi-subscription-router),
+ * reached over `pi.events` with the same envelope as `cross-extension-rpc.ts`:
+ * emit `router:rpc:admit` `{ requestId, model }`, reply on
+ * `router:rpc:admit:reply:<requestId>` as `{ success, data?: { ok, resolvedModel?, resetAt?, wait? } }` (`resolvedModel` labels the admitted physical model).
+ *
+ * Admission fails open. No router installed, a slow router, a malformed reply
+ * or a router error all admit the dispatch: quota is advisory here, and the
+ * router still routes (or fails) each request inside the child.
+ */
+
+import { nanoid } from "nanoid";
+import { type Clock, realClock } from "./clock.js";
+import type { TierAdmission } from "./model-tiers.js";
+
+export const ADMIT_CHANNEL = "router:rpc:admit";
+
+/**
+ * How long to wait for a reply. The router answers from cached state within
+ * the same macrotask, so this only bounds the cost when no router is installed.
+ */
+const ADMIT_TIMEOUT_MS = 100;
+
+/** Minimal `pi.events` surface. */
+export interface AdmissionEvents {
+  emit(channel: string, data: unknown): void;
+  on(channel: string, handler: (data: unknown) => void): () => void;
+}
+
+/** A dispatch the router refused, with the earliest known reset (epoch ms). */
+export interface QuotaBlock {
+  model: string;
+  resetAt?: number;
+  /**
+   * False when the router's exhaustion policy says fail now instead of parking.
+   * Absent (an older router) means the dispatch may park until `resetAt`.
+   */
+  wait?: boolean;
+}
+
+/** Whether a refused background dispatch may be parked until the block's reset. */
+export function mayPark(block: QuotaBlock): block is QuotaBlock & { resetAt: number } {
+  return block.resetAt !== undefined && block.wait !== false;
+}
+
+/** `provider/id` for a model, the key the router expects. */
+export function modelRef(model: { provider: string; id: string }): string {
+  return `${model.provider}/${model.id}`;
+}
+
+/** Resolve to the block when the router refuses `model`, else undefined. */
+export async function checkAdmission(
+  events: AdmissionEvents,
+  model: string,
+  timeoutMs = ADMIT_TIMEOUT_MS,
+  clock: Clock = realClock,
+  signal?: AbortSignal,
+): Promise<QuotaBlock | undefined> {
+  return (await admissionOutcome(events, model, timeoutMs, clock, signal)).block;
+}
+
+/** Retain the physical admission label and whether the router supplied a signal. */
+export function admissionOutcome(
+  events: AdmissionEvents,
+  model: string,
+  timeoutMs = ADMIT_TIMEOUT_MS,
+  clock: Clock = realClock,
+  signal?: AbortSignal,
+): Promise<TierAdmission> {
+  if (signal?.aborted) return Promise.reject(new DOMException("Admission cancelled", "AbortError"));
+  const requestId = nanoid();
+  return new Promise((resolve, reject) => {
+    // Every step is idempotent and a promise settles once, so no `done` latch is needed.
+    const cleanup = () => {
+      timer.cancel();
+      unsubscribe();
+      signal?.removeEventListener("abort", abort);
+    };
+    const abort = () => {
+      cleanup();
+      reject(new DOMException("Admission cancelled", "AbortError"));
+    };
+    const finish = (outcome: TierAdmission) => {
+      cleanup();
+      resolve(outcome);
+    };
+    const unsubscribe = events.on(`${ADMIT_CHANNEL}:reply:${requestId}`, raw => {
+      const reply = raw as { success?: unknown; data?: { ok?: unknown; resolvedModel?: unknown; resetAt?: unknown; wait?: unknown } } | undefined;
+      if (reply?.success !== true || typeof reply.data?.ok !== "boolean") return finish({ quotaSignal: false });
+      if (reply.data.ok) return finish({ quotaSignal: true, resolvedModel: typeof reply.data.resolvedModel === "string" ? reply.data.resolvedModel : undefined });
+      const resetAt = reply.data.resetAt;
+      const wait = reply.data.wait;
+      finish({ quotaSignal: true, block: {
+        model,
+        resetAt: typeof resetAt === "number" && Number.isFinite(resetAt) ? resetAt : undefined,
+        ...(typeof wait === "boolean" ? { wait } : {}),
+      } });
+    });
+    const timer = clock.setTimeout(() => finish({ quotaSignal: false }), timeoutMs);
+    signal?.addEventListener("abort", abort, { once: true });
+    events.emit(ADMIT_CHANNEL, { requestId, model });
+  });
+}
+
+/** One-line reason for a refused dispatch. */
+export function describeBlock(block: QuotaBlock): string {
+  const when = block.resetAt === undefined ? "an unknown time" : new Date(block.resetAt).toISOString();
+  return `Subscription quota for ${block.model} is exhausted; it resets at ${when}.`;
+}
+
+/** Delay past a reported reset before a parked dispatch starts, so usage has refilled. */
+export const QUOTA_RESTART_GRACE_MS = 60_000;
+
+/**
+ * Delay before re-admitting a parked dispatch whose reset passed while pi was
+ * closed. The router warms its usage cache on session_start; asking before that
+ * finishes would always fail open.
+ */
+export const PARKED_RESUME_DELAY_MS = 10_000;

package/src/resource-loader.ts

@@ -0,0 +1,65 @@
+/** Normalize explicit settings paths before Pi's real package manager resolves them. */
+import { DefaultPackageManager, DefaultResourceLoader, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { normalizeHomePath } from "./home-paths.js";
+
+type ResourceLoaderOptions = ConstructorParameters<typeof DefaultResourceLoader>[0];
+type ResourceSettings = ReturnType<SettingsManager["getGlobalSettings"]>;
+
+const RESOURCE_FIELDS = ["extensions", "skills", "prompts", "themes"] as const;
+
+/** Keep filter modifiers and non-home paths intact; only replace leading home references. */
+function expandSetting(entry: string, homeDir: string, modifiers = true): string {
+  const prefix = modifiers && /^[!+-]/.test(entry) ? entry[0] : "";
+  const path = entry.slice(prefix.length);
+  const trimmed = path.trim();
+  if (trimmed !== "~" && !trimmed.startsWith("~/") && !(process.platform === "win32" && trimmed.startsWith("~\\"))) return entry;
+  return prefix + normalizeHomePath(trimmed, homeDir);
+}
+
+/** Return copies so loading resources never changes persisted settings or their source objects. */
+export function normalizeResourceSettings(settings: ResourceSettings, homeDir: string): ResourceSettings {
+  const normalized = { ...settings };
+  for (const field of RESOURCE_FIELDS) {
+    if (settings[field]) normalized[field] = settings[field].map(entry => expandSetting(entry, homeDir));
+  }
+  if (settings.packages) {
+    normalized.packages = settings.packages.map(pkg => {
+      if (typeof pkg === "string") return expandSetting(pkg, homeDir, false);
+      const copy = { ...pkg, source: expandSetting(pkg.source, homeDir, false) };
+      for (const field of RESOURCE_FIELDS) {
+        if (pkg[field]) copy[field] = pkg[field].map(entry => expandSetting(entry, homeDir));
+      }
+      return copy;
+    });
+  }
+  return normalized;
+}
+
+type PackageManagerOptions = ConstructorParameters<typeof DefaultPackageManager>[0];
+
+/** Wrap settings readers once so Pi receives injected-home resource paths. */
+function normalizeHomeResourceSettings(settingsManager: SettingsManager, homeDir: string): SettingsManager {
+  const globalSettings = settingsManager.getGlobalSettings.bind(settingsManager);
+  const projectSettings = settingsManager.getProjectSettings.bind(settingsManager);
+  // Wrap the public readers, not a cached snapshot: reload and project-trust
+  // decisions continue to be owned by Pi, and every read receives fresh copies.
+  Object.assign(settingsManager, {
+    getGlobalSettings: () => normalizeResourceSettings(globalSettings(), homeDir),
+    getProjectSettings: () => normalizeResourceSettings(projectSettings(), homeDir),
+  });
+  return settingsManager;
+}
+
+/** Build Pi's package manager with injected-home settings normalization. */
+export function createHomePackageManager(options: PackageManagerOptions, homeDir?: string): DefaultPackageManager {
+  if (homeDir === undefined) return new DefaultPackageManager(options);
+  // `homeDir` also redirects Pi's automatic `<home>/.agents/skills` root (nredd/pi#13).
+  return new DefaultPackageManager({ ...options, homeDir, settingsManager: normalizeHomeResourceSettings(options.settingsManager, homeDir) });
+}
+
+/** Use the real loader/manager while preventing ambient-home expansion of explicit settings. */
+export function createHomeResourceLoader(options: ResourceLoaderOptions, homeDir?: string): DefaultResourceLoader {
+  if (homeDir === undefined) return new DefaultResourceLoader(options);
+  const settingsManager = options.settingsManager ?? SettingsManager.create(options.cwd, options.agentDir);
+  return new DefaultResourceLoader({ ...options, homeDir, settingsManager: normalizeHomeResourceSettings(settingsManager, homeDir) });
+}

package/src/schedule-store.ts

@@ -0,0 +1,153 @@
+/**
+ * schedule-store.ts — File-backed store for scheduled subagents.
+ *
+ * Session-scoped: each pi session owns its own schedules at
+ * `<cwd>/.pi/subagent-schedules/<sessionId>.json`. `/new` starts a fresh
+ * empty store; `/resume` reloads.
+ *
+ * Concurrency model lifted from pi-chonky-tasks/src/task-store.ts: every
+ * mutation acquires a PID-based exclusion lock, re-reads the latest state
+ * from disk, applies the change, atomic-writes via temp+rename, releases.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { ScheduledSubagent, ScheduleStoreData } from "./types.js";
+
+const LOCK_RETRY_MS = 50;
+const LOCK_MAX_RETRIES = 100;
+
+function isProcessRunning(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function acquireLock(lockPath: string): void {
+  for (let i = 0; i < LOCK_MAX_RETRIES; i++) {
+    try {
+      writeFileSync(lockPath, `${process.pid}`, { flag: "wx" });
+      return;
+    } catch (e: any) {
+      if (e.code === "EEXIST") {
+        try {
+          const pid = parseInt(readFileSync(lockPath, "utf-8"), 10);
+          if (pid && !isProcessRunning(pid)) {
+            unlinkSync(lockPath);
+            continue;
+          }
+        } catch { /* ignore — try again */ }
+        const start = Date.now();
+        while (Date.now() - start < LOCK_RETRY_MS) { /* busy wait */ }
+        continue;
+      }
+      throw e;
+    }
+  }
+  throw new Error(`Failed to acquire schedule lock: ${lockPath}`);
+}
+
+function releaseLock(lockPath: string): void {
+  try { unlinkSync(lockPath); } catch { /* ignore */ }
+}
+
+/** Resolve the storage path for a session-scoped store. */
+export function resolveStorePath(cwd: string, sessionId: string): string {
+  return join(cwd, ".pi", "subagent-schedules", `${sessionId}.json`);
+}
+
+export class ScheduleStore {
+  private filePath: string;
+  private lockPath: string;
+  private jobs = new Map<string, ScheduledSubagent>();
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+    this.lockPath = filePath + ".lock";
+    this.load();
+  }
+
+  /** Create the backing directory lazily — only when we're about to persist. */
+  private ensureDir(): void {
+    mkdirSync(dirname(this.filePath), { recursive: true });
+  }
+
+  /** Load from disk into the in-memory cache. Silent on parse errors. */
+  private load(): void {
+    if (!existsSync(this.filePath)) return;
+    try {
+      const data: ScheduleStoreData = JSON.parse(readFileSync(this.filePath, "utf-8"));
+      this.jobs.clear();
+      for (const j of data.jobs ?? []) this.jobs.set(j.id, j);
+    } catch { /* corrupt — start fresh, next save rewrites */ }
+  }
+
+  /** Atomic write via temp file + rename (POSIX-atomic). */
+  private save(): void {
+    const data: ScheduleStoreData = { version: 1, jobs: [...this.jobs.values()] };
+    const tmp = this.filePath + ".tmp";
+    writeFileSync(tmp, JSON.stringify(data, null, 2));
+    renameSync(tmp, this.filePath);
+  }
+
+  /** Acquire lock → reload → mutate → save → release. */
+  private withLock<T>(fn: () => T): T {
+    this.ensureDir();
+    acquireLock(this.lockPath);
+    try {
+      this.load();
+      const result = fn();
+      this.save();
+      return result;
+    } finally {
+      releaseLock(this.lockPath);
+    }
+  }
+
+  /** Read-only — returns a snapshot of the in-memory cache. */
+  list(): ScheduledSubagent[] {
+    return [...this.jobs.values()];
+  }
+
+  /** Read-only check — uses the cache. */
+  hasName(name: string, exceptId?: string): boolean {
+    for (const j of this.jobs.values()) {
+      if (j.id !== exceptId && j.name === name) return true;
+    }
+    return false;
+  }
+
+  get(id: string): ScheduledSubagent | undefined {
+    return this.jobs.get(id);
+  }
+
+  add(job: ScheduledSubagent): void {
+    this.withLock(() => {
+      this.jobs.set(job.id, job);
+    });
+  }
+
+  update(id: string, patch: Partial<ScheduledSubagent>): ScheduledSubagent | undefined {
+    // No-op fast path — an unknown id changes nothing, so don't lock or touch
+    // disk (which would otherwise lazily create the backing directory).
+    if (!this.jobs.has(id)) return undefined;
+    return this.withLock(() => {
+      const existing = this.jobs.get(id);
+      if (!existing) return undefined;
+      const updated = { ...existing, ...patch };
+      this.jobs.set(id, updated);
+      return updated;
+    });
+  }
+
+  remove(id: string): boolean {
+    // No-op fast path — see update().
+    if (!this.jobs.has(id)) return false;
+    return this.withLock(() => this.jobs.delete(id));
+  }
+
+  /** Delete the backing file (used when no jobs remain, optional cleanup). */
+  deleteFileIfEmpty(): void {
+    if (this.jobs.size === 0 && existsSync(this.filePath)) {
+      try { unlinkSync(this.filePath); } catch { /* ignore */ }
+    }
+  }
+}