pi-daddy 0.28.0 → 0.32.0

package/src/definitions.ts

@@ -1,211 +0,0 @@
-/**
- * Agent Skills (`SKILL.md`) as this package's definition format — ADR-0016.
- *
- * A subagent is a skill you spawn: the `SKILL.md` body becomes the child's system prompt
- * (`--append-system-prompt`) and `allowed-tools` becomes its capability ceiling, enforced through
- * `--tools`. That collapses a duplication `principal-pi-skills` already strains against, where
- * `plan`/`review`/`debug` exist twice — once as a skill and once as a subagent prompt — and are
- * generated from one contract precisely so the two cannot drift.
- *
- * **The spec's own words about `allowed-tools`:** *"a space-separated string of tools that are
- * pre-approved to run"*, marked **experimental**. Pre-approved, not enforced — the field declares intent
- * and blocks nothing, and implementations differ on whether they honour it at all. Turning that
- * declaration into something structural is this package's entire value here.
- *
- * **One inversion is deliberate and load-bearing.** In pi-subagents' frontmatter an absent `tools:` key
- * means *pi's full default toolset*, so an undeclared definition was the most powerful kind and any
- * parse failure produced a wildcard — the direction that caused R-28 and review finding F18. Here an
- * absent `allowed-tools` means **undeclared, therefore not spawnable**. A typo or an unreadable YAML
- * form now costs a refusal instead of a grant.
- */
-
-import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
-import { resolveSkillResources, skillResourceName } from "./skill-resources.ts";
-import { CAPABILITY_NAMESPACE_PREFIXES } from "./capabilities.ts";
-import type { Capability } from "./resolve.ts";
-
-/**
- * Identifies WHICH instructions a child was given, without reproducing them (ADR-0018).
- *
- * The ledger's standing rule is *capability ids, counts and identifiers only — never prompts, tool
- * arguments or results*. A hash is an identifier: it names a version of an operator-authored file. The
- * **task** is model-assembled from the parent's context and is never recorded anywhere, by decision.
- */
-export interface DefinitionDigest {
-  name: string;
-  /** Where the definition was read from, so a reader can go and rehash it. */
-  source: string;
-  /** SHA-256 of the body — the exact text passed as `--append-system-prompt`. */
-  sha256: string;
-}
-
-/**
- * Digest a definition's body.
- *
- * Over the **body alone**, deliberately: that is precisely the text the child receives, so a digest that
- * also covered the frontmatter would change when `description` was reworded and report an instruction
- * change that never happened. `allowed-tools` is already recorded in full on every record.
- */
-export function digestDefinition(definition: SkillDefinition): DefinitionDigest {
-  return {
-    name: definition.name,
-    source: definition.source,
-    sha256: createHash("sha256").update(definition.body, "utf8").digest("hex"),
-  };
-}
-
-export interface SkillDefinition {
-  /** From the path, never the frontmatter — see `parseSkillDefinition`. */
-  name: string;
-  description: string;
-  /** Raw `allowed-tools` value. `undefined` means the key was absent; `""` means it declared none. */
-  allowedTools?: string;
-  /** The spec's sanctioned extension point: a map of string keys to string values. */
-  metadata?: Record<string, string>;
-  /** Everything after the frontmatter — the child's system prompt. */
-  body: string;
-  source: string;
-}
-
-export interface DefinitionCeiling {
-  /** The declared capabilities, as this package's ids. */
-  capabilities: Capability[];
-  /**
-   * Entries carrying a sub-tool pattern, e.g. `Bash(git:*)`.
-   *
-   * ADR-0016 refuses these rather than reinterpreting them, because every reinterpretation is wrong:
-   * granting bare `bash` **widens** a deliberately narrow declaration, dropping the tool silently
-   * **narrows** and yields a child that mysteriously cannot work, and matching patterns inside a wrapper
-   * would be a security control implemented by string-matching a shell command. Non-empty means the
-   * caller must refuse and say so.
-   */
-  patterns: string[];
-  /** The `allowed-tools` key was absent entirely: the definition is not spawnable. */
-  undeclared: boolean;
-}
-
-/**
- * Read a `SKILL.md`.
- *
- * The frontmatter reader handles the subset these files use — `key: value`, block scalars (`>` / `|`),
- * and a one-level `metadata:` map. Anything it cannot read leaves the key **absent**, which for
- * `allowed-tools` means *undeclared* and therefore refused. That is the whole reason this parser can be
- * hand-rolled without the hazard its sibling in `agent-types.ts` carries.
- */
-export function parseSkillDefinition(source: string, text: string): SkillDefinition | null {
-  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
-  if (!match) return null;
-
-  const fields = new Map<string, string>();
-  const metadata: Record<string, string> = {};
-  const lines = match[1].split(/\r?\n/);
-
-  for (let i = 0; i < lines.length; i++) {
-    const kv = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(lines[i]);
-    if (!kv) continue;
-    const [, key, rawValue] = kv;
-    const value = rawValue.trim();
-
-    // A folded/literal scalar: fold the indented continuation into one line. `principal-pi-skills`
-    // writes every description this way, and the sibling parser SKIPS these — which is safe there only
-    // because it never needs the value. Here a skipped `description` would be a missing required field.
-    if (value === ">" || value === "|") {
-      const parts: string[] = [];
-      for (let j = i + 1; j < lines.length; j++) {
-        if (!/^\s+\S/.test(lines[j])) break;
-        parts.push(lines[j].trim());
-        i = j;
-      }
-      fields.set(key, parts.join(" "));
-      continue;
-    }
-
-    // `metadata:` introduces a one-level map of string keys to string values (the spec's shape).
-    if (key === "metadata" && value === "") {
-      for (let j = i + 1; j < lines.length; j++) {
-        const item = /^\s+([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(lines[j]);
-        if (!item) break;
-        metadata[item[1]] = item[2].trim().replace(/^["']|["']$/g, "");
-        i = j;
-      }
-      continue;
-    }
-
-    // A YAML collection/block we cannot parse is not an explicit empty ceiling.
-    if (key === "allowed-tools" && value === "") {
-      const nextValue = lines.slice(i + 1).find(line => line.trim() !== "" && !/^\s*#/.test(line));
-      if (/^\s+\S/.test(nextValue ?? "")) continue;
-    }
-    fields.set(key, value);
-  }
-
-  const description = fields.get("description");
-  if (description === undefined) return null;
-
-  return {
-    // Identity comes from the PATH. ADR-0013 learned this the hard way on the other format: pi keys
-    // skills by their directory, so trusting a frontmatter `name` lets our view and the loader's
-    // disagree about which file a name refers to. The spec requires `name` to match the parent
-    // directory anyway, so a mismatch is the file's defect and not something to honour.
-    name: skillResourceName(source),
-    description,
-    allowedTools: fields.get("allowed-tools"),
-    metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
-    body: text.slice(match[0].length).trim(),
-    source,
-  };
-}
-
-/**
- * Turn a definition's `allowed-tools` into a capability ceiling.
- *
- * Name mapping is **lowercasing and nothing else**, deliberately. A translation table from Claude
- * Code's names to pi's would have to decide what `Glob` means, and pi has no glob tool — so the table
- * would either invent a grant or quietly drop one. Lowercasing leaves `Glob` as `tool:glob`, which the
- * catalog then refuses as unknown, naming the actual problem to whoever wrote the file.
- */
-export function ceilingForDefinition(definition: SkillDefinition): DefinitionCeiling {
-  const raw = definition.allowedTools;
-  if (raw === undefined) return { capabilities: [], patterns: [], undeclared: true };
-
-  const capabilities = new Set<Capability>();
-  const patterns: string[] = [];
-
-  // The spec says space-separated. Commas are tolerated because `Read, Grep` is what people type, and
-  // accepting them grants nothing extra — it only avoids a comma becoming part of a capability name.
-  for (const entry of raw.split(/[\s,]+/).filter((e) => e.length > 0)) {
-    if (entry.includes("(")) {
-      patterns.push(entry);
-      continue;
-    }
-    // Every namespaced id passes through untouched; only a BARE tool name gets the `tool:` prefix and the
-    // lowercasing. `workspace:` was missing here after ADR-0035 taught `normaliseCapability` about it, so a
-    // definition declaring `allowed-tools: workspace:prod` produced `tool:workspace:prod` — a capability
-    // that names nothing, refused as unknown, and dropped by `init` as "probably a typo or an attack". Two
-    // spellings of one grammar with this one wrong is R-28's shape; the list is now shared.
-    if (CAPABILITY_NAMESPACE_PREFIXES.some((prefix) => entry.startsWith(prefix))) {
-      capabilities.add(entry);
-      continue;
-    }
-    capabilities.add(`tool:${entry.toLowerCase()}`);
-  }
-
-  return { capabilities: [...capabilities].sort(), patterns, undeclared: false };
-}
-
-/**
- * Read definitions from Pi's enabled resources, including installed packages and local overrides.
- * Resolver precedence and filters are shared with the capability catalog; unregistered npm packages
- * are not runtime resources until legacy init explicitly scaffolds them.
- */
-export async function loadDefinitions(cwd: string): Promise<Map<string, SkillDefinition>> {
-  const definitions = new Map<string, SkillDefinition>();
-  for (const { path } of (await resolveSkillResources(cwd)).skills) {
-    let text: string;
-    try { text = await readFile(path, "utf8"); } catch { continue; }
-    const parsed = parseSkillDefinition(path, text);
-    if (parsed && !definitions.has(parsed.name)) definitions.set(parsed.name, parsed);
-  }
-  return definitions;
-}

package/src/delegate-types.ts

@@ -1,154 +0,0 @@
-/**
- * The shapes `planDelegation` consumes and produces. Split out of `./delegate.ts` only to stay under the
- * 400-line module ceiling this project enforces mechanically; `./delegate.ts` re-exports all three, so
- * "the delegate module" remains one import for every caller.
- */
-import type { Capability, ResolveResult } from "./resolve.ts";
-import type { DefinitionDigest, SkillDefinition } from "./definitions.ts";
-import type { InheritableApproval } from "./approval.ts";
-import type { Catalog } from "./catalog.ts";
-import type { ApprovalBinding, CorrelationMetadata } from "./correlation.ts";
-import type { StructuredRefusal } from "./refusals.ts";
-import type { ExecutorKind } from "./executor.ts";
-
-export interface DelegationRequest {
-  task: string;
-  /**
-   * Capabilities the delegator wants the child to hold.
-   *
-   * Optional since ADR-0016: prefer `agent`, which names an operator-authored definition. This form
-   * lets the MODEL choose the capability set, which is the weaker arrangement — it is still bounded by
-   * the session grant (ADR-0008), so it cannot escalate, but nothing about it was reviewed by a human.
-   */
-  tools?: string[];
-  /**
-   * Name of a `SKILL.md` definition to spawn (ADR-0016).
-   *
-   * When given, the definition's `allowed-tools` is the ceiling and its body is the child's system
-   * prompt. The model chooses only *which* definition and *what* task; the capability set is the
-   * operator's, written down in a file.
-   */
-  agent?: string;
-  model?: string;
-  provider?: string;
-  thinking?: string;
-  /** Optional external join metadata. It never participates in capability authority. */
-  correlation?: CorrelationMetadata;
-  /**
-   * Trusted binding scope, supplied by the caller that actually resolved and leased the
-   * workspace. Deliberately separate from `correlation`, whose values are a model-supplied
-   * claim: reading the workspace id out of correlation let a bound approval be spent outside
-   * the workspace it named (R-110).
-   */
-  boundWorkspaceId?: string;
-  boundContextId?: string;
-}
-
-export interface DelegationContext {
-  ownGrant: Capability[];
-  depth: number;
-  maxDepth: number;
-  gated: Capability[];
-  /**
-   * Approvals in force for this delegation, with subject and scope (ADR-0014).
-   *
-   * One source of truth for two different questions. The **gate check here** honours every entry,
-   * including `once` — that approval applies to *this* spawn, which is exactly what the human said yes
-   * to. What crosses to the CHILD is `inheritApprovals`, which drops `once` and keeps the subject, so
-   * the same list cannot silently authorise a subtree.
-   */
-  approved?: InheritableApproval[];
-  ledgerPath?: string;
-  /** Path to this extension, so a child granted `tool:delegate` can delegate in turn. */
-  extensionPath?: string;
-  /** No-tool activity observer injected only for governed leaf children. */
-  observerExtensionPath?: string;
-  /** Parent-owned local activity identity for this exact turn. */
-  activity?: { rootId: string; path: string; taskId?: string };
-  /** Live capability catalog. When supplied, capabilities absent from it are refused as unknown. */
-  catalog?: Catalog;
-  /**
-   * Absolute path per skill NAME, from the catalog's `source` field (R-32).
-   *
-   * Without it every granted `skill:` capability is unresolvable and the delegation is refused, which
-   * is the correct direction: a caller that cannot say where a skill lives cannot honestly grant it.
-   */
-  skillPaths?: Record<string, string>;
-  /** Let the child load `AGENTS.md` / `CLAUDE.md`. Default false — see `planSpawn`. */
-  contextFiles?: boolean;
-  /** Known `SKILL.md` definitions by name, for `DelegationRequest.agent` (ADR-0016). */
-  definitions?: Map<string, SkillDefinition>;
-  /**
-   * Build an INTERACTIVE plan — no `--print` — for an executor that drives the child after starting it.
-   *
-   * `runHerdrPane` requires this: `--print` makes pi process the prompt and exit, so it never reaches the
-   * interactive readiness `herdr agent start` waits for and the agent is never detected. Default is the
-   * non-interactive plan, because a governed child should not sit waiting for a human by accident.
-   */
-  interactive?: boolean;
-  /** Explicit host-owned pi persistence target; never model-facing and never enabled by archive observation. */
-  sessionFile?: string;
-  /**
-   * Total descendants this session may still create (`src/fanout.ts`). Split among children by the caller.
-   *
-   * Omitted means unbounded, which is the pre-fan-out behaviour and correct for a single blocking
-   * delegation — the accident that used to bound cardinality to one.
-   */
-  fanoutBudget?: number;
-  /** This session's ledger id, so a child's `parentId` names its real parent (F8). */
-  spawnId?: string;
-  /** Ledger id assigned to THIS child, distinguishing logical siblings (F8). */
-  childSpawnId?: string;
-  /** Unique identity assigned to THIS execution occurrence; never derive joins from childSpawnId. */
-  childExecutionId?: string;
-}
-
-export interface Delegation {
-  ok: boolean;
-  reason?: string;
-  /** Stable machine-readable refusal accompanying the unchanged human diagnostic. */
-  refusal?: StructuredRefusal;
-  args: string[];
-  /** Per-child environment — never merged into the parent's process.env. */
-  env: Record<string, string>;
-  effective: Capability[];
-  /**
-   * The result this plan was made from. **Required** (B-I3): while it was optional the extension
-   * guarded its ledger write with `if (ledgerPath && plan.result)`, silently dropping every refusal
-   * that returned before `resolve()` ran. The type is what keeps a new early exit auditable.
-   */
-  result: ResolveResult;
-  childDepth: number;
-  /**
-   * The capabilities this delegation asked for, whatever route named them.
-   *
-   * Carried on the plan rather than re-derived by the caller (the B-I3 lesson): with `agent`, the
-   * request names a DEFINITION and the capabilities come from its `allowed-tools`, so a ledger that
-   * read the tool parameters would record an empty request for every definition spawn.
-   */
-  requested: Capability[];
-  /** Ledger id for this child's readable logical position, if the caller assigned one (F8). */
-  childId?: string;
-  /** Unique identity for this occurrence, if the caller assigned one. */
-  executionId?: string;
-  /**
-   * Which operator-authored instructions this spawn used (ADR-0018).
-   *
-   * Absent for a `tools:`-style delegation, which has no definition and therefore no instructions to
-   * identify — and absent on an ADR-0017 authorisation refusal, which is decided before the file is read.
-   */
-  definitionDigest?: DefinitionDigest;
-  /** Trusted SHA-256 of the exact model-authored task. The task text itself is never stored. */
-  taskDigest: string;
-  /** Non-authoritative external join metadata, snapshotted at planning time. */
-  correlation?: CorrelationMetadata;
-  /** Exact approval scope, present when correlation/workspace context requested task-bound approval. */
-  approvalBinding?: ApprovalBinding;
-}
-
-/**
- * Plan a governed delegation. Pure: returns argv and env, spawns nothing.
- *
- * Fails closed on depth, on any requested capability the delegator does not hold, on gated capabilities
- * without approval, and on a grant that cannot narrow (a universal capability slipping through).
- */