@bermudi/pi-delegate 0.1.10 → 0.1.12

package/manual.ts

@@ -110,7 +110,7 @@ export function getSubagentManualMarkdown(
     'delegate({ tasks: [{ agent: "default", prompt: "Investigate the auth module" }] })',
     "```",
     "",
-    "Delegate subagents to execute tasks in parallel. Each subagent gets an independent conversation but uses the real filesystem at its task `cwd`; tasks sharing a directory can observe and overwrite one another's changes. Fresh prompts must therefore be self-contained, and dependent or shared-file work should run separately.",
+    'Delegate subagents to execute tasks in parallel. Each subagent gets an independent conversation. A batch with multiple write-capable tasks in one shared tree is rejected before dispatch; run them sequentially, use synchronous one-shot `workspace: "isolated"` for Git-backed ordered reconciliation, or use disposable scratch workspaces.',
     "",
     "The three handles have different lifetimes:",
     "",
@@ -136,7 +136,7 @@ export function getSubagentManualMarkdown(
     "",
     ...builtinLines,
     "",
-    "Fresh built-ins inherit the parent's exact model object and thinking level. A same-named Markdown file can override any built-in (first definition wins); an explicit `model` or `thinking` in that file replaces parent inheritance. Task-level `model`/`thinking`/`tools` always win. For `scout`/`coder`/`reviewer`, settings overrides (`settings.json` `delegate.agentOverrides` and `delegate.agentOverridesByParentModel`) win over the Markdown file; `default` ignores settings and uses only an explicit Markdown `model`/`thinking` when present. A prompt-only Markdown override keeps the built-in's tools and workspace, so `scout` stays read-only and `reviewer` stays scratch unless the file explicitly changes them. Parent extension/MCP tools are not copied. Parent-global `AGENTS.md` instructions are also excluded. Project-local context and skills are rebuilt for the task's `cwd`; per-task fields remain explicit overrides.",
+    "Fresh built-ins inherit the parent's exact model object and thinking level. A same-named Markdown file can override any built-in (first definition wins); an explicit `model` or `thinking` in that file replaces parent inheritance. Task-level `model`/`thinking`/`tools` always win. For `scout`/`coder`/`reviewer`, delegate.json overrides (`agentOverrides`, `agentOverridesByParentModel`) win over the Markdown file; `default` ignores overrides and uses only an explicit Markdown `model`/`thinking` when present. A prompt-only Markdown override keeps the built-in's tools and workspace, so `scout` stays read-only and `reviewer` stays scratch unless the file explicitly changes them. Parent extension/MCP tools are not copied. Parent-global `AGENTS.md` instructions are also excluded. Project-local context and skills are rebuilt for the task's `cwd`; per-task fields remain explicit overrides.",
     "",
     "## Available Custom Agents",
     "",
@@ -234,6 +234,7 @@ export function getSubagentManualMarkdown(
     "## Gotchas",
     "",
     "- Dispatch validation is batch-wide and runs before spawning: one invalid task rejects the call without starting its siblings.",
+    '- Shared writers that overlap tasks in the same call or a running sync/async dispatch are rejected. Unknown tools count as mutating. Run them sequentially, use `workspace: "isolated"` for Git-backed ordered reconciliation, or use `workspace: "scratch"` when changes may be discarded.',
     "- `*` means read/write/edit/bash, not every tool. `grep`, `find`, and `ls` are valid explicit tools and are the `ro` preset.",
     '- `tasks` is an array. The tool recovers common stringified calls for compatibility, but canonical calls use `{ tasks: [{ prompt: "..." }] }`.',
     '- Use `agent: "default"` for the parent\'s live model/thinking/native tools/base prompt. Built-ins are `default`, `scout`, `coder`, and `reviewer`; omitting `agent` creates an ad-hoc task.',
@@ -242,13 +243,9 @@ export function getSubagentManualMarkdown(
     `- Sync \`delegate\` runs at most ${getMaxConcurrent()} tasks at once (the rest queue, not fail). Use \`async: true\` to move work to the background.`,
     "- `deadlineMs` is a per-task wall-clock budget measured from when the task starts running (after queuing). It requests cooperative abort and is not a hard kill; completed writes/commands remain. Omission disables the deadline.",
     "",
-    "## Legacy `action` compatibility",
-    "",
-    "The overloaded `action` field was split into `ticketAction` (poll/wait/cancel) and `sessionAction` (prompt/close/list). Legacy `action` values are still accepted at runtime through automatic normalization, but new calls should use the canonical fields. Programmatic TypeScript consumers should note the exported type `DelegateAction` is now `TicketAction`.",
-    "",
     "## Config",
     "",
-    "Tunables live in `~/.pi/agent/delegate.json`: `maxConcurrent` (sync ceiling), `maxAsyncTickets` (background ticket cap), `stallTimeoutMs` (inactivity watchdog; default 900000, 0 disables), per-model/per-provider concurrency limits, and legacy custom-agent model overrides. Built-in model/thinking/tools overrides live in `settings.json`; `agentOverridesByParentModel` uses an exact `provider/model-id` key and project settings take precedence.",
+    "Tunables live in `~/.pi/agent/delegate.json` (user scope, global — no project-level config): `maxConcurrent` (sync ceiling), `maxAsyncTickets` (background ticket cap), `stallTimeoutMs` (inactivity watchdog; default 900000, 0 disables), per-model/per-provider concurrency limits, legacy custom-agent model overrides (`agent`), and agent model/thinking/tools overrides — `agentOverrides` and `agentOverridesByParentModel` (exact `provider/model-id` key of the parent model; wins over `agentOverrides` on match). Config edits apply from the next delegate call.",
     "The inactivity watchdog requests cooperative `AgentSession.abort()` cancellation and waits for the subagent to become idle; it is not a hard wall-clock execution deadline.",
     "",
     `Output bounding: subagent outputs longer than ${OUTPUT_SPILL_THRESHOLD_CHARS} characters are spilled to a temp file, and only the last ${OUTPUT_SPILL_TAIL_CHARS} characters stay in the LLM-facing result. Adjust with \`output.spillThresholdChars\` and \`output.spillTailChars\`. Spill files are written to the system temp directory with owner-only permissions; the full output is always available in the expanded TUI view and the spilled file.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bermudi/pi-delegate",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Delegate tool for the Pi coding agent.",
   "keywords": [
     "pi-package"

package/pi-package-source.ts

@@ -0,0 +1,293 @@
+/**
+ * The single seam onto Pi's package-source grammar.
+ *
+ * Provider-extension verification needs three facts about a configured source:
+ * whether it is a local path, which Git repository and ref it pins, and which
+ * npm version range it requires. All three come from
+ * `DefaultPackageManager.parseSource`, which is private upstream.
+ *
+ * Reaching into that private is not the hazard — *duplicating* it is. This
+ * module exists because the previous implementation hand-rolled its own
+ * `isLocalPath`, its own npm-spec regex, and its own Git URL grammar in order
+ * to avoid the cast, and all three drifted from the originals:
+ *
+ *   - the local check lowercased its input, so `NPM:pkg` was "managed" to us
+ *     and "local" to Pi;
+ *   - the npm regex was a verbatim copy of Pi's private `parseNpmSpec`, kept in
+ *     sync by hand;
+ *   - the Git parser knew nothing of `hosted-git-info`, which Pi's real parser
+ *     uses for every hosted provider.
+ *
+ * A second grammar that must track a private one on every upgrade is strictly
+ * worse than one narrow cast that fails loudly. It is also not buying any
+ * independence: `getInstalledPath` — a *public* method the resolution path
+ * already depends on — calls this same private parser internally, so if
+ * `parseSource` disappears, path resolution is broken with or without this
+ * module.
+ *
+ * Hence: one cast, one module, one error type. Callers deal in the parsed
+ * result and never see Pi's raw shape.
+ */
+import type { DefaultPackageManager } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Pi's private parser is missing, threw, or returned a shape this version of
+ * delegate cannot trust.
+ *
+ * Callers fail closed on this rather than falling back to a guess: an
+ * unverifiable source is treated exactly like a source that failed
+ * verification. Callers that wrap it in a friendlier message must preserve it
+ * as `cause`, so a Pi-version mismatch stays distinguishable from a genuinely
+ * mismatched checkout.
+ */
+export class PiPackageSourceError extends Error {
+  /**
+   * Which kind of source Pi had already classified when the contract broke, if
+   * it got that far. Callers use it to report the failure in terms of the
+   * verification the user configured ("this Git source could not be verified")
+   * rather than as an unrelated internal error.
+   */
+  readonly sourceType?: "git" | "npm";
+
+  constructor(
+    message: string,
+    options?: { cause?: unknown; sourceType?: "git" | "npm" },
+  ) {
+    super(message, { cause: options?.cause });
+    this.name = "PiPackageSourceError";
+    this.sourceType = options?.sourceType;
+  }
+}
+
+/** A Git repository identity, normalized for comparison. */
+export interface GitRepositoryIdentity {
+  /** Lowercased host, e.g. `github.com`. */
+  host: string;
+  /** Repository path, e.g. `example/extension`. */
+  path: string;
+}
+
+export interface GitPackageSource extends GitRepositoryIdentity {
+  type: "git";
+  /** Configured ref. Present exactly when Pi reports the source as pinned. */
+  ref?: string;
+}
+
+export interface NpmPackageSource {
+  type: "npm";
+  /** Version, range, or dist-tag text after the package name, if any. */
+  version?: string;
+  /** Semver range. Undefined when `version` is a dist-tag such as `latest`. */
+  range?: string;
+  /**
+   * Whether the package installed at `installedPath` satisfies this source,
+   * using Pi's own semver comparison rather than a reimplementation. Resolves
+   * `true` for an unconstrained source, matching Pi's install-time behavior.
+   */
+  satisfiedBy(installedPath: string): Promise<boolean>;
+}
+
+export interface LocalPackageSource {
+  type: "local";
+}
+
+export type PiPackageSource =
+  GitPackageSource | NpmPackageSource | LocalPackageSource;
+
+type PackageManagerInternals = {
+  parseSource(source: string): unknown;
+  installedNpmMatchesConfiguredVersion(
+    parsed: unknown,
+    installedPath: string,
+  ): Promise<boolean>;
+};
+
+function internalsOf(
+  packageManager: DefaultPackageManager,
+): Partial<PackageManagerInternals> {
+  return packageManager as unknown as Partial<PackageManagerInternals>;
+}
+
+/**
+ * Normalize a Pi-parsed Git identity for equality comparison.
+ *
+ * This is comparison hygiene, not a grammar: both sides of every comparison
+ * are produced by Pi's parser, and this only removes differences Pi is
+ * indifferent to (host case, a trailing slash or `.git` that Pi strips in some
+ * source forms but not others). It never decides what a source *is*.
+ */
+function normalizeIdentity(
+  host: string,
+  repoPath: string,
+): GitRepositoryIdentity | undefined {
+  const path = repoPath.replace(/\/+$/, "").replace(/\.git$/i, "");
+  if (!host || !path) return undefined;
+  return { host: host.toLowerCase(), path };
+}
+
+/**
+ * Parse a configured package source with Pi's own parser.
+ *
+ * Throws `PiPackageSourceError` when the parser is unavailable or returns a
+ * result whose security-relevant fields (Git pin state, npm range) cannot be
+ * trusted. Unrecognized sources come back as `local`, which is exactly how Pi
+ * itself resolves them.
+ */
+export function parsePackageSource(
+  packageManager: DefaultPackageManager,
+  source: string,
+): PiPackageSource {
+  const internals = internalsOf(packageManager);
+  if (typeof internals.parseSource !== "function") {
+    throw new PiPackageSourceError(
+      "This Pi version no longer exposes the package-source parser that delegate uses to verify provider extensions.",
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = internals.parseSource.call(packageManager, source);
+  } catch (error) {
+    throw new PiPackageSourceError(
+      "Pi could not parse a configured provider extension source.",
+      { cause: error },
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new PiPackageSourceError(
+      "Pi's package-source parser returned an unusable result for a configured provider extension.",
+    );
+  }
+
+  const record = parsed as {
+    type?: unknown;
+    host?: unknown;
+    path?: unknown;
+    ref?: unknown;
+    pinned?: unknown;
+    version?: unknown;
+    range?: unknown;
+  };
+
+  if (record.type === "git") return toGitSource(record);
+  if (record.type === "npm") {
+    return toNpmSource(record, parsed, packageManager);
+  }
+  return { type: "local" };
+}
+
+function toGitSource(record: {
+  host?: unknown;
+  path?: unknown;
+  ref?: unknown;
+  pinned?: unknown;
+}): GitPackageSource {
+  if (typeof record.host !== "string" || typeof record.path !== "string") {
+    throw new PiPackageSourceError(
+      "Pi's package-source parser reported a Git source without a usable repository identity.",
+      { sourceType: "git" },
+    );
+  }
+  const identity = normalizeIdentity(record.host, record.path);
+  if (!identity) {
+    throw new PiPackageSourceError(
+      "Pi's package-source parser reported an empty Git repository identity.",
+      { sourceType: "git" },
+    );
+  }
+
+  // `pinned` and `ref` are a security contract, not decoration. If a Pi
+  // upgrade drops either, never reinterpret a pinned source as an unpinned
+  // checkout and silently skip commit validation.
+  if (typeof record.pinned !== "boolean") {
+    throw new PiPackageSourceError(
+      "Pi's package-source parser no longer reports Git pin state.",
+      { sourceType: "git" },
+    );
+  }
+  if (!record.pinned) {
+    if (record.ref !== undefined) {
+      throw new PiPackageSourceError(
+        "Pi's package-source parser reported an unpinned Git source that still carries a ref.",
+        { sourceType: "git" },
+      );
+    }
+    return { type: "git", ...identity };
+  }
+  if (typeof record.ref !== "string" || record.ref.length === 0) {
+    throw new PiPackageSourceError(
+      "Pi's package-source parser reported a pinned Git source without a ref.",
+      { sourceType: "git" },
+    );
+  }
+  return { type: "git", ...identity, ref: record.ref };
+}
+
+function toNpmSource(
+  record: { version?: unknown; range?: unknown },
+  parsed: unknown,
+  packageManager: DefaultPackageManager,
+): NpmPackageSource {
+  if (record.version !== undefined && typeof record.version !== "string") {
+    throw new PiPackageSourceError(
+      "Pi's package-source parser reported an unusable npm version specifier.",
+      { sourceType: "npm" },
+    );
+  }
+  if (record.range !== undefined && typeof record.range !== "string") {
+    throw new PiPackageSourceError(
+      "Pi's package-source parser reported an unusable npm version range.",
+      { sourceType: "npm" },
+    );
+  }
+
+  return {
+    type: "npm",
+    version: record.version,
+    range: record.range,
+    async satisfiedBy(installedPath: string): Promise<boolean> {
+      const compare =
+        internalsOf(packageManager).installedNpmMatchesConfiguredVersion;
+      if (typeof compare !== "function") {
+        throw new PiPackageSourceError(
+          "This Pi version no longer exposes the npm version check that delegate uses to verify provider extensions.",
+          { sourceType: "npm" },
+        );
+      }
+      // Pi's own parsed object is handed back untouched: it owns the contract
+      // between its parser and its comparison, and a reconstructed stand-in
+      // would silently change meaning if that contract grew a field.
+      return compare.call(packageManager, parsed, installedPath);
+    },
+  };
+}
+
+/**
+ * Read the repository identity of an installed checkout from its origin URL,
+ * using the same parser the configured source went through.
+ *
+ * The `git:` prefix is what makes that possible: without it Pi only accepts
+ * explicit protocol URLs, while with it Pi accepts every shorthand it accepts
+ * in a configured source (SCP `git@host:path`, bare `host/path`). Prefixing a
+ * URL that already carries a scheme is harmless — Pi strips the prefix before
+ * parsing. Returns undefined for an origin Pi does not recognize as Git, which
+ * callers treat as a failed identity match.
+ */
+export function parseGitOriginIdentity(
+  packageManager: DefaultPackageManager,
+  originUrl: string,
+): GitRepositoryIdentity | undefined {
+  const trimmed = originUrl.trim();
+  if (!trimmed) return undefined;
+  const parsed = parsePackageSource(packageManager, `git:${trimmed}`);
+  if (parsed.type !== "git") return undefined;
+  return { host: parsed.host, path: parsed.path };
+}
+
+/** Whether two Pi-parsed Git identities name the same repository. */
+export function sameRepository(
+  a: GitRepositoryIdentity,
+  b: GitRepositoryIdentity,
+): boolean {
+  return a.host === b.host && a.path === b.path;
+}

package/pool.ts

@@ -18,6 +18,10 @@ export interface FrozenConfig {
   thinking: ThinkingLevel;
   tools: string[];
   cwd: string;
+  /** Stable signature of the provider-scoped extension allowlist this session
+   * was built with. A change in `delegate.json` providerExtensions must force
+   * session recreation so the old executable runtime is not silently reused. */
+  providerExtensions?: string;
 }
 
 /** The subset a reuse request supplies for validation. `model` and
@@ -29,12 +33,20 @@ export interface ConfigCandidate {
   tools: string[];
   model?: Model<Api>;
   systemPrompt?: string;
+  /** Provider-scoped extension allowlist signature for the current dispatch. */
+  providerExtensions?: string;
 }
 
 /** One field-level diff from a reuse that conflicts with the frozen config. The
  * pool computes these; the caller formats the error string. */
 export interface ConfigMismatch {
-  field: "cwd" | "thinking" | "tools" | "model" | "systemPrompt";
+  field:
+    | "cwd"
+    | "thinking"
+    | "tools"
+    | "model"
+    | "systemPrompt"
+    | "providerExtensions";
   frozen: string;
   requested: string;
 }
@@ -189,6 +201,16 @@ export function checkout(
       requested: "<requested>",
     });
   }
+  if (frozen.providerExtensions !== candidate.providerExtensions) {
+    // This field is derived from configured package sources, which may contain
+    // credentials. Never expose either the sources or their digest through the
+    // public checkout result; a digest can still enable dictionary guessing.
+    mismatches.push({
+      field: "providerExtensions",
+      frozen: "<redacted>",
+      requested: "<redacted>",
+    });
+  }
   if (mismatches.length) return { status: "mismatch", mismatches };
 
   return {