pi-daddy 0.27.4 → 0.32.0

package/src/kernel/fanout.ts

@@ -0,0 +1,106 @@
+/**
+ * Bounded synchronous fan-out — ADR-0015's option A′, and the cardinality bound ADR-0008 never had.
+ *
+ * **The gap this closes.** ADR-0008 bounds what each child may *hold* and says nothing about how many
+ * children exist. `resolve()` is a set operation; nowhere in `src/` was there a count. Blocking `delegate`
+ * bounded cardinality to one *by accident of being blocking*, so the invariant was never tested. Fan-out
+ * removes that accident: with `maxDepth: 2` and five children per call, five delegators each spawning five
+ * is thirty concurrent model sessions — **every ledger line individually correct and narrow, the aggregate
+ * a machine DoS and an uncapped bill.** The critic's verdict on this was that silence is itself a finding.
+ *
+ * **Why a budget rather than a per-call limit.** A per-call cap of K with depth D still permits K^D
+ * descendants, which is the same exponential wearing a smaller number. A *budget* is subtractive and
+ * therefore total: a session holding budget B may create at most B descendants in its whole subtree,
+ * because it spends from B to spawn and hands each child a share of what is left. That composes across
+ * process boundaries with **no shared state** — the same property that makes depth work — so it needs no
+ * registry, no lock and no counter file.
+ *
+ * It is deliberately NOT a concurrency limit. How many run at once is a resource question for the executor;
+ * how many may exist at all is a governance question, and this is the governance answer.
+ */
+
+import { parseBound } from "./propagation.ts";
+
+/** Total descendants a session may create across its entire subtree, when nothing is configured. */
+export const DEFAULT_FANOUT_BUDGET = 8;
+
+/**
+ * Hard ceiling on children in a single call, independent of budget.
+ *
+ * A budget alone would let one call spend all of it at once, and a hundred simultaneous `pi` processes is
+ * a different failure from a hundred spread over a session. This is the blast-radius bound; the budget is
+ * the total bound. Both are needed because they answer different questions.
+ */
+export const MAX_CHILDREN_PER_CALL = 8;
+
+/**
+ * Steps a single `delegate_chain` may contain — ADR-0033.
+ *
+ * **Derived from `MAX_CHILDREN_PER_CALL` so the two cannot drift.** A chain is not concurrent, so the blast-radius
+ * argument for that constant does not apply directly; what does apply is that one tool call should not be able to
+ * create an unbounded number of descendants, and eight is already a long pipeline. Sharing the number also means an
+ * operator learns one bound rather than two.
+ */
+export const MAX_CHAIN_STEPS = MAX_CHILDREN_PER_CALL;
+
+/** Read the budget from the environment, failing to the default on absent *or* malformed input. */
+export function budgetFromEnv(raw: string | undefined): number {
+  const parsed = parseBound(raw);
+  // Malformed and zero both fall back rather than disabling fan-out silently — G7's rule. A budget that a
+  // typo can switch off is the A-S4 defect wearing different clothes. To genuinely forbid delegation an
+  // operator sets `maxDepth: 0`, which says what it means.
+  return parsed === undefined || parsed === null || parsed === 0 ? DEFAULT_FANOUT_BUDGET : parsed;
+}
+
+export interface BudgetSplit {
+  ok: boolean;
+  reason?: string;
+  /** Budget each child receives. */
+  perChild: number;
+}
+
+/**
+ * Spend `count` from a budget and divide the remainder among the children.
+ *
+ * The parent pays one unit per child it creates *before* sharing what is left, so a subtree can never
+ * exceed the budget it started with: spawning is itself an expenditure, not a free act that only its
+ * descendants pay for. `Math.floor` on the division means rounding always loses budget rather than
+ * inventing it — the safe direction, and the reason a deep tree converges to zero instead of oscillating.
+ */
+export function splitBudget(budget: number, count: number): BudgetSplit {
+  if (count <= 0) return { ok: false, reason: "a fan-out needs at least one child", perChild: 0 };
+  if (count > MAX_CHILDREN_PER_CALL) {
+    return {
+      ok: false,
+      reason: `${count} children exceeds the per-call limit of ${MAX_CHILDREN_PER_CALL}`,
+      perChild: 0,
+    };
+  }
+  if (budget < count) {
+    return {
+      ok: false,
+      reason:
+        `fan-out budget exhausted: ${count} children requested, ${budget} remaining in this subtree ` +
+        `(raise PI_DADDY_FANOUT at the root, or delegate fewer at a time)`,
+      perChild: 0,
+    };
+  }
+  return { ok: true, perChild: Math.floor((budget - count) / count) };
+}
+
+/**
+ * A ledger id that distinguishes siblings.
+ *
+ * **Review finding F8.** Every child was recorded as `delegate@d1`, so four concurrent children produced
+ * four lines identical except `ts` — and two landing in the same millisecond were indistinguishable.
+ * ADR-0008 names `parent_id`/`child_id` as the correlation keys, but they were depth *labels* wearing id
+ * names, which made the ledger unjoinable to the returned result, to the OS process, or to the child's own
+ * lines one level down.
+ *
+ * The id is hierarchical and derived, not random: a child of `d0` is `d0.1`, its own second child `d0.1.2`.
+ * That means a line's ancestry is readable from the id alone with no join at all, and it is reproducible —
+ * two runs of the same fan-out produce the same ids, which is what makes a ledger diffable.
+ */
+export function childSpawnId(parentId: string, index: number): string {
+  return `${parentId}.${index + 1}`;
+}

package/src/kernel/grant-env.ts

@@ -0,0 +1,174 @@
+/**
+ * The reviewable project record (`settings.json` since ADR-0076 PR 3c) — and what `init` refuses to put in it.
+ *
+ * Split out of `init.ts` when ADR-0029's grant-width rule pushed that file past the 400-line ceiling and
+ * `test/file-size.test.ts` refused it. The seam is the natural one: `init.ts` decides *what is true about
+ * the installed packages*, this file decides *how that is presented to a human for review*.
+ *
+ * **ADR-0029.** `init` used to emit the union of every declared ceiling as a live grant. A critic's reading
+ * killed it in one sentence: the handoff's safety argument for a third party authoring `allowed-tools` is
+ * that *"the operator's `PI_DADDY_GRANT` still bounds it"* — and a generated union makes the bound and the
+ * bounded have the same author, who is not the operator. So capabilities that can change a machine are
+ * emitted **commented**, with the definitions that need them named. `init` + `source` yields a working
+ * read-only setup; the wide ones cost one deliberate uncomment.
+ *
+ * That is a decision about the **starting grant**, which is a stronger act than choosing a ceiling and is
+ * why it needed its own ADR rather than a paragraph in ADR-0028.
+ */
+
+import { DELEGATE_CAPABILITY } from "./capabilities.ts";
+import { DEFAULT_GATED } from "./propagation.ts";
+import { UNIVERSAL_CAPABILITIES, type Capability } from "./resolve.ts";
+import { PROJECT_FILES } from "./project-paths.ts";
+
+/**
+ * Capabilities `init` will never put LIVE in a generated grant.
+ *
+ * **This list is a judgement, and it is written down in one place so it can be argued with** — which is the
+ * whole reason ADR-0029 exists. The rule behind it: a capability that can *change the machine* or *execute*
+ * does not become live because a package asked for it. Everything else (reading, searching, listing) does.
+ *
+ *  - `DEFAULT_GATED` — whatever a governed session already asks a human about. Today `tool:bash`, and taking
+ *    it from there rather than restating it means the two cannot drift apart.
+ *  - `tool:write`, `tool:edit`, `tool:edit-diff` — mutate the working tree, and **are not gated by default**,
+ *    so a source-and-go operator would hand them to a child with no dialog at all. That gap is exactly what
+ *    made "the union is mitigated by gating" untrue (R-76).
+ *  - `UNIVERSAL_CAPABILITIES` — confer the whole catalog by measurement (`docs/probes/pi-fabric-eval`).
+ *    `assertNarrowing` refuses a grant containing one anyway; leaving it out of the file keeps the operator
+ *    from ever holding it by accident.
+ */
+export const WITHHELD_BY_DEFAULT: readonly Capability[] = [
+  ...new Set([...DEFAULT_GATED, "tool:write", "tool:edit", "tool:edit-diff", ...UNIVERSAL_CAPABILITIES]),
+];
+
+/** Would `init` put this capability in the live grant? */
+export function isLiveByDefault(capability: Capability): boolean {
+  // No `workspace:<id>` is ever live by default (ADR-0035), and this is the same rule the list above states
+  // rather than a new one: authority "does not become live because a package asked for it". A registry id is
+  // a *choice of where a child runs*, which is the operator's to make and cannot be inferred from a
+  // declaration — ADR-0028's whole position. Enumerated ids are unbounded, so this is a namespace test and
+  // not a list membership.
+  if (capability.startsWith("workspace:")) return false;
+  return !WITHHELD_BY_DEFAULT.includes(capability);
+}
+
+/**
+ * Every character allowed in a generated `PI_DADDY_GRANT` value.
+ *
+ * **A structural backstop, not the main defence** (R-78). The per-entry whitelist in `skill-packages.ts` is
+ * what refuses a hostile capability id; this refuses to write the FILE AT ALL if anything unexpected reached
+ * the string regardless. R-77 and R-78 were the same defect found twice, on two channels into one
+ * interpolation, so the third channel — whatever it turns out to be — should cost a refusal rather than an
+ * injection. A guard that depends on my enumeration being complete is not a guard.
+ */
+const GRANT_VALUE = /^[A-Za-z0-9:@,._/-]*$/;
+
+export class UnsafeGrantError extends Error {}
+
+/** Throw rather than write a grant string that could mean something to a shell. */
+export function assertGrantIsWritable(grant: Capability[]): void {
+  const value = grant.join(",");
+  if (!GRANT_VALUE.test(value)) {
+    throw new UnsafeGrantError(
+      `refusing to write the grant: the assembled grant contains characters that are not part of a ` +
+        `capability id (${JSON.stringify(value)}). The grant is handed to children through their environment, so it is ` +
+        `not written at all rather than written unsafely. Report this — a declared capability reached the ` +
+        `grant that should have been refused at discovery.`,
+    );
+  }
+}
+
+/** One definition's declared ceiling, as far as the grant file is concerned. */
+export interface GrantEnvSkill {
+  name: string;
+  ceiling: Capability[];
+  /** Present when the definition cannot be spawned at all; the string is why, for the reader. */
+  unspawnable?: string;
+}
+
+export interface GrantEnvInput {
+  skills: GrantEnvSkill[];
+  /** Capabilities emitted live. */
+  live: Capability[];
+  /** Withheld capability → the definitions that declared it. Emitted commented, for a deliberate uncomment. */
+  withheld: Map<Capability, string[]>;
+  /** Definitions whose `agent:` id is withheld because they need a withheld capability. */
+  withheldDefinitions: string[];
+  /** `workspace:<id>` ids this project could route to (ADR-0035). Rendered commented, never granted. */
+  routableWorkspaces?: Capability[];
+  /** `agent:<name>` ids a ceiling names that `init` did not write here. Reported, never granted. */
+  crossReferences: { from: string; capability: Capability }[];
+  cautions: string[];
+}
+
+/**
+ * Render the file.
+ *
+ * Every capability is annotated with the definition it came from, because the whole claim of this feature is
+ * that the capability decision is visible and diffable. A grant nobody can read is a grant nobody reviews.
+ */
+/**
+ * Render `.pi/pi-daddy/settings.json`, the reviewable, committable record of a project's ceiling (ADR-0076 PR 3c).
+ *
+ * It replaced `.pi/grants.env`, which was never machine-read: the root grant comes from the user-level grant
+ * store (ADR-0037), and the shell file existed so a human could read and diff the capability decision. That
+ * purpose is kept as data: every capability is annotated with the definition it came from, withheld
+ * capabilities and definitions are listed with their reasons, and nothing here is advice dressed as a value.
+ * `/grants` renders it; PR 6 adds the advisor toggles beside it.
+ */
+export interface ProjectSettings {
+  version: 1;
+  writtenBy: "pi-daddy init";
+  /** How to read this file, for the human who opens it in a diff. */
+  review: string;
+  /** The live grant: what `pi-daddy init` found declared and did not withhold. Delete an id to withhold it. */
+  grant: Capability[];
+  definitions: { name: string; declares: Capability[]; spawnable: boolean; reason?: string }[];
+  /** Withheld by default (ADR-0029) → the definitions that declared each. Never granted by init. */
+  withheld: { capability: Capability; declaredBy: string[] }[];
+  /** Definitions whose `agent:` id is withheld because they need a withheld capability. */
+  withheldDefinitions: string[];
+  /** `workspace:<id>` ids this project could route to (ADR-0035). Listed, never granted. */
+  routableWorkspaces: Capability[];
+  /** `agent:<name>` ids a ceiling names that init did not write here. Reported, never granted. */
+  crossReferences: { from: string; capability: Capability }[];
+  cautions: string[];
+  /** The project ledger file name under `.pi/pi-daddy/`; init enables it (ADR-0037). */
+  ledger: string;
+  /** Gated by default (ADR-0012): closed under subsumption, so gating tool:write also gates tool:bash. */
+  gatedByDefault: Capability[];
+}
+
+export function buildProjectSettings(input: GrantEnvInput): ProjectSettings {
+  return {
+    version: 1,
+    writtenBy: "pi-daddy init",
+    review:
+      "Every capability below was read from a SKILL.md's own allowed-tools; pi-daddy chose none of them. " +
+      "Review and commit this file. Delete an agent: id from `grant` to withhold that definition, a tool: id to " +
+      "withhold that tool from every child. A child never receives more than this grant ∩ its definition.",
+    grant: [...input.live],
+    definitions: input.skills.map((s) => ({
+      name: s.name,
+      declares: [...s.ceiling],
+      spawnable: !s.unspawnable,
+      ...(s.unspawnable ? { reason: s.unspawnable } : {}),
+    })),
+    withheld: [...input.withheld.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([capability, declaredBy]) => ({ capability, declaredBy: [...declaredBy] })),
+    withheldDefinitions: [...input.withheldDefinitions],
+    routableWorkspaces: [...(input.routableWorkspaces ?? [])],
+    crossReferences: input.crossReferences.map((c) => ({ ...c })),
+    cautions: [...input.cautions],
+    ledger: PROJECT_FILES.ledger,
+    gatedByDefault: ["tool:bash"],
+  };
+}
+
+export function renderProjectSettings(input: GrantEnvInput): string {
+  return JSON.stringify(buildProjectSettings(input), null, 2) + "\n";
+}
+
+/** The capability that must always be live, or the generated file is inert (S-5). */
+export const ALWAYS_LIVE: Capability = DELEGATE_CAPABILITY;

package/src/kernel/model-preflight.ts

@@ -0,0 +1,44 @@
+import { refusal, type StructuredRefusal } from "./refusals.ts";
+import { ENV_ALLOW_UNRESOLVED_MODELS } from "./env-names.ts";
+export { ENV_ALLOW_UNRESOLVED_MODELS } from "./env-names.ts";
+
+/** Pi's resolved catalogue carries provider support in thinkingLevelMap. Never silently clamp a user's choice. */
+export function supportedModelEfforts(model: {
+  reasoning: boolean;
+  thinkingLevelMap?: Partial<Record<string, string | null>>;
+}): ("off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max")[] {
+  if (!model.reasoning) return ["off"];
+  return (["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const).filter((level) => {
+    const mapped = model.thinkingLevelMap?.[level];
+    return mapped !== null && ((level !== "xhigh" && level !== "max") || mapped !== undefined);
+  });
+}
+
+export interface ModelCatalogue {
+  find(provider: string, modelId: string): unknown;
+}
+
+/** Resolve an explicit provider/id against pi's own session catalogue without probing credentials or network. */
+export function preflightModel(
+  model: string | undefined,
+  catalogue: ModelCatalogue,
+  cache: Map<string, boolean>,
+  allowUnresolved: boolean,
+): StructuredRefusal | undefined {
+  if (model === undefined || allowUnresolved) return undefined;
+  const slash = model.indexOf("/");
+  const provider = slash > 0 ? model.slice(0, slash) : "";
+  const id = slash > 0 ? model.slice(slash + 1) : "";
+  let resolved = cache.get(model);
+  if (resolved === undefined) {
+    resolved = provider.length > 0 && id.length > 0 && catalogue.find(provider, id) !== undefined;
+    cache.set(model, resolved);
+  }
+  if (resolved) return undefined;
+  return refusal(
+    "MODEL_UNRESOLVED",
+    `grants: model ${model || "(empty)"} is not in pi's session catalogue; use provider/id from /model, ` +
+      `or set ${ENV_ALLOW_UNRESOLVED_MODELS}=1 to let pi attempt custom resolution`,
+    { model: model || "(empty)" },
+  );
+}

package/src/kernel/pi-tools.ts

@@ -0,0 +1,32 @@
+/**
+ * Facts about pi itself: its built-in tool names, and the capability that means "all of them".
+ *
+ * These lived in `agent-types.ts` until ADR-0016 deleted that module along with the rest of the
+ * `@tintinweb/pi-subagents` port. They are not about agent types at all — `PI_BUILTIN_TOOLS` is how the
+ * catalog tells a built-in from an extension tool, and `WILDCARD` is a capability id — so they outlive
+ * the port and belong somewhere that does not name a package we no longer depend on.
+ *
+ * **`PI_BUILTIN_TOOLS` is a pinned observation, and it has already drifted once** (R-31): pi 0.84.1
+ * exposes a `parallel` tool that the 0.83.0 list did not contain, which made it classify as an
+ * *extension* capability. The list is used for classification only — never for enforcement, which is
+ * `--tools`' job — so drift misfiles a capability rather than granting one. Keep it current anyway; a
+ * misfiled capability is a confusing catalog.
+ */
+
+import type { Capability } from "./resolve.ts";
+
+/** Capability held only by a delegator authorised to hand out everything. */
+export const WILDCARD: Capability = "tool:*";
+
+/** pi's built-in tools, observed against 0.84.1. `parallel` was added since 0.83.0 — see R-31. */
+export const PI_BUILTIN_TOOLS = [
+  "bash",
+  "edit",
+  "edit-diff",
+  "find",
+  "grep",
+  "ls",
+  "parallel",
+  "read",
+  "write",
+] as const;

package/src/kernel/project-paths.ts

@@ -0,0 +1,97 @@
+/**
+ * Every filesystem location this package owns, in one place (ADR-0076 PR 3c).
+ *
+ * Project state lives under `<cwd>/.pi/pi-daddy/`; user state under `<agent dir>/pi-daddy/`. Before this
+ * module there were eight project locations under `.pi/` and three user directories under the agent dir,
+ * each spelled at its call site. `test/project-paths.test.ts` forces the rule: no shipped module outside
+ * this one may spell `.pi`.
+ *
+ * `settings.json` is the one committable file in the project directory: `pi-daddy init` writes it as the
+ * reviewable record of what a project's ceiling is and why. Everything else there is private runtime state,
+ * and init writes a `.gitignore` beside it that says so.
+ *
+ * The user-level stores moved here without migration (operator decision, 2026-09-21, following ADR-0020):
+ * a session that finds the old location and not the new one reports the old path and asks for `/grants init`
+ * or a fresh approval, rather than copying authority from one place to another.
+ */
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+
+/** pi's own per-project directory. Ours is a subdirectory of it. */
+export const PI_PROJECT_DIR = ".pi";
+export const PROJECT_STATE_DIRNAME = "pi-daddy";
+
+export function piProjectDir(cwd: string): string {
+  return join(resolve(cwd), PI_PROJECT_DIR);
+}
+
+/** `<cwd>/.pi/pi-daddy` — every project-scoped file this package writes. */
+export function projectStateDir(cwd: string): string {
+  return join(piProjectDir(cwd), PROJECT_STATE_DIRNAME);
+}
+
+export const PROJECT_FILES = Object.freeze({
+  settings: "settings.json",
+  gitignore: ".gitignore",
+  ledger: "grants.jsonl",
+  activityTimeline: "activity.jsonl",
+});
+
+export const projectSettingsPath = (cwd: string) => join(projectStateDir(cwd), PROJECT_FILES.settings);
+export const projectGitignorePath = (cwd: string) => join(projectStateDir(cwd), PROJECT_FILES.gitignore);
+export const projectLedgerPath = (cwd: string) => join(projectStateDir(cwd), PROJECT_FILES.ledger);
+export const activityTimelinePath = (cwd: string) => join(projectStateDir(cwd), PROJECT_FILES.activityTimeline);
+
+/** The `.gitignore` init writes inside the project state directory: settings is committable, nothing else is. */
+export const PROJECT_GITIGNORE_CONTENT = `# Written by pi-daddy init. Only settings.json is meant to be committed; the rest is private runtime state.
+*
+!.gitignore
+!settings.json
+`;
+
+/** Is this path inside pi's per-project directory of any project? The private controller journals refuse such paths. */
+export function isUnderPiProjectDir(path: string): boolean {
+  return path.split(/[\\/]/).includes(PI_PROJECT_DIR);
+}
+
+/** `$PI_CODING_AGENT_DIR`, or pi's default `~/.pi/agent`. */
+export function agentDir(env: NodeJS.ProcessEnv = process.env): string {
+  const explicit = env.PI_CODING_AGENT_DIR?.trim();
+  return explicit ? explicit : join(homedir(), PI_PROJECT_DIR, "agent");
+}
+
+/** `<agent dir>/pi-daddy` — every user-scoped file this package writes. */
+export function userStateDir(env: NodeJS.ProcessEnv = process.env): string {
+  return join(agentDir(env), PROJECT_STATE_DIRNAME);
+}
+
+export const USER_DIRS = Object.freeze({
+  grants: "grants",
+  approvals: "approvals",
+  workspaceLeases: "workspace-leases",
+});
+
+/**
+ * `<slug>-<16 hex>.json`: the basename keeps the directory legible, the hash makes it unambiguous, since two
+ * checkouts can share a basename. 64 bits, not the 24 this once shipped with (R-41).
+ */
+export function projectFileName(cwd: string): string {
+  const slug = (basename(cwd) || "root").replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 40);
+  const hash = createHash("sha256").update(cwd, "utf8").digest("hex").slice(0, 16);
+  return `${slug}-${hash}.json`;
+}
+
+export const grantStorePath = (cwd: string, env?: NodeJS.ProcessEnv) =>
+  join(userStateDir(env), USER_DIRS.grants, projectFileName(cwd));
+export const approvalsPath = (cwd: string, env?: NodeJS.ProcessEnv) =>
+  join(userStateDir(env), USER_DIRS.approvals, projectFileName(cwd));
+export const workspaceLeasesDir = (env?: NodeJS.ProcessEnv) => join(userStateDir(env), USER_DIRS.workspaceLeases);
+
+/** Where the same stores lived before ADR-0076 PR 3c. Reported when found, never read (ADR-0020 precedent). */
+export const legacyUserGrantStorePath = (cwd: string, env?: NodeJS.ProcessEnv) =>
+  join(agentDir(env), "grants", projectFileName(cwd));
+export const legacyUserApprovalsPath = (cwd: string, env?: NodeJS.ProcessEnv) =>
+  join(agentDir(env), "grants-approvals", projectFileName(cwd));
+export const legacyProjectLedgerPath = (cwd: string) => join(piProjectDir(cwd), "grants.jsonl");
+export const legacyGrantEnvPath = (cwd: string) => join(piProjectDir(cwd), "grants.env");