@ymy88/pi-subagents 0.0.0-stage → 0.24.0

package/dist/package-resources.js

@@ -0,0 +1,519 @@
+/**
+ * package-resources.ts — Discover agent and workflow files that installed pi
+ * packages declare in their `package.json`.
+ *
+ * ## Why this exists
+ *
+ * Pi already ships four resource types inside packages — `extensions`, `skills`,
+ * `prompts`, `themes` — resolved from a `pi` manifest key or, when there is no
+ * `pi` key at all, from convention directories. Subagents are *our* concept, so
+ * pi knows nothing about them and a package author's only option was to copy
+ * `.md` files into `.pi/agents/` on every container start (#109).
+ *
+ * ## The contract
+ *
+ * Two-sided, deliberately:
+ *
+ *   1. The package author opts in by naming the paths in `package.json`.
+ *   2. The user opts in by running `pi install`, which is already the trust
+ *      decision for that package — pi executes its `extensions/` and injects its
+ *      `skills/` into the system prompt with no further prompt. A declared `.md`
+ *      agent is strictly less privileged than either, so it rides the boundary
+ *      the user already crossed rather than inventing a second one.
+ *
+ * There is deliberately **no convention-directory fallback**. Pi scans `skills/`
+ * only when a package has no `pi` key whatsoever; we never scan an undeclared
+ * `agents/`. A package that happens to carry an `agents/` folder for some other
+ * tool must not start contributing subagents to pi because it was installed for
+ * an unrelated reason.
+ *
+ * ## Which packages are visible
+ *
+ * Only what pi itself has configured — `settings.json -> packages[]`, global and
+ * project — read through pi's own `DefaultPackageManager.listConfiguredPackages()`.
+ * That call is synchronous, pure, and never installs anything; it also resolves
+ * npm / git / local install roots, pnpm global roots and legacy fallbacks, which
+ * is why it is worth borrowing rather than reimplementing.
+ *
+ * `node_modules` is never scanned. Being a transitive dependency of the user's
+ * project means nothing here — the same rule pi applies to itself.
+ *
+ * ## Accepted manifest spellings
+ *
+ * All four mean the same thing. The `pi-subagents` top-level key exists for
+ * cross-compatibility with `nicobailon/pi-subagents`, which reads the same two
+ * shapes, so a package author writes one manifest that works on either extension.
+ *
+ *   "pi":            { "subagents": { "agents": ["./agents"], "workflows": ["./flows"] } }
+ *   "pi":            { "subagents": ["./agents"] }            // shorthand for { agents }
+ *   "pi-subagents":  { "agents": ["./agents"] }
+ *   "pi-subagents":  ["./agents"]                             // shorthand for { agents }
+ *
+ * Adding `pi.subagents` is safe for pi itself: its `readPiManifest` reads only
+ * `extensions`/`skills`/`prompts`/`themes` and ignores every other key.
+ */
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { DefaultPackageManager, getAgentDir, ProjectTrustStore, SettingsManager } from "@earendil-works/pi-coding-agent";
+/** File extension scanned for each kind, mirroring the local roots for each. */
+const KIND_EXTENSION = {
+    agents: ".md",
+    workflows: ".js",
+};
+/**
+ * Per-file size ceiling for package-provided resources, matching Claude Code's
+ * plugin-agent limit. These files come from third-party packages and are read
+ * eagerly on every agent load; a pathological one should be skipped, not
+ * `readFileSync`'d into the session.
+ */
+export const MAX_PACKAGE_RESOURCE_BYTES = 1_048_576;
+// ---- Session state ----
+//
+// Held here rather than threaded through every caller, matching how the rest of
+// this extension carries session-wide settings (`setMaxSubagentDepth`,
+// `setWorktreeIsolationEnabled`, ...). The alternative was an options bag
+// travelling from `index.ts` through `resolveWorkflowScript`,
+// `resolveWorkflowSource`, `readSavedWorkflow` and `listSavedWorkflows` purely
+// so a gate could be consulted at the bottom.
+//
+// Both gates start `undefined`, which reads as `true`: absent settings mean
+// every declaring package contributes, matching pi's own default for the
+// resources it owns.
+let agentsGate;
+let workflowsGate;
+/**
+ * Defaults to `false` — an extension activates before any session context
+ * exists, and reading an untrusted project's package list only to take it away
+ * again is the wrong direction to fail. `index.ts` corrects it from
+ * `ctx.isProjectTrusted()` on `session_start`.
+ */
+let projectTrustedState = false;
+/** Apply the `packageAgents` setting. Drops the cache, since roots may change. */
+export function setPackageAgentsGate(gate) {
+    agentsGate = gate;
+    invalidatePackageCache();
+}
+/** Apply the `packageWorkflows` setting. Drops the cache, since roots may change. */
+export function setPackageWorkflowsGate(gate) {
+    workflowsGate = gate;
+    invalidatePackageCache();
+}
+export function getPackageAgentsGate() {
+    return agentsGate;
+}
+export function getPackageWorkflowsGate() {
+    return workflowsGate;
+}
+/**
+ * Seed the trust state from pi's *saved* decision, before any session exists.
+ *
+ * The correction on `session_start` is too late for one thing that matters: the
+ * `Agent` tool's description — the list of agent types the model is told about —
+ * is built once at activation, so an agent registered after it never reaches the
+ * model even though dispatch would accept it. That is exactly the shape a team
+ * ships agents in: a package named in a committed `.pi/settings.json`, which is
+ * invisible until the project is trusted.
+ *
+ * Pi keeps that decision in `<agentDir>/trust.json`, keyed by canonical path
+ * with the nearest ancestor winning, so on the second and every later session in
+ * a trusted repo the answer is already on disk. No saved decision falls back to
+ * the global `defaultProjectTrust`, which is what pi does; `"ask"` resolves to
+ * untrusted here, because the prompt has not been answered yet and guessing yes
+ * would be the wrong direction to guess.
+ *
+ * Best-effort by design: any failure leaves the state untrusted, and
+ * `session_start` still delivers pi's real answer either way.
+ */
+export function seedProjectTrust(cwd) {
+    try {
+        if (typeof ProjectTrustStore !== "function")
+            return;
+        const agentDir = getAgentDir();
+        const saved = new ProjectTrustStore(agentDir).get(cwd);
+        if (typeof saved === "boolean") {
+            setProjectTrusted(saved);
+            return;
+        }
+        const settings = SettingsManager.create(cwd, agentDir, { projectTrusted: false });
+        setProjectTrusted(settings.getGlobalSettings().defaultProjectTrust === "always");
+    }
+    catch {
+        // Leave it untrusted; session_start corrects it.
+    }
+}
+/**
+ * Record pi's project-trust answer. Drops the cache when the answer changes,
+ * since a project's `packages[]` becomes visible or invisible with it. A repeat
+ * of the same answer is a no-op — `session_start` fires on every new, resumed
+ * and forked session, and it has its own reason to invalidate.
+ */
+export function setProjectTrusted(trusted) {
+    if (projectTrustedState === trusted)
+        return;
+    projectTrustedState = trusted;
+    invalidatePackageCache();
+}
+/** Reset every session-scoped value. Tests only — the extension never un-loads. */
+export function resetPackageState() {
+    agentsGate = undefined;
+    workflowsGate = undefined;
+    projectTrustedState = false;
+    invalidatePackageCache();
+}
+// ---- Manifest reading ----
+/** A string array, or undefined for anything else. Mirrors pi's `readPiManifest` strictness. */
+function stringArray(val) {
+    return Array.isArray(val) && val.every(e => typeof e === "string") ? val : undefined;
+}
+/**
+ * Normalize one accepted spelling into `{ agents, workflows }`.
+ * A bare array is the `agents` shorthand — the only kind that existed when the
+ * shorthand was worth having, and the shape the other fork's docs show.
+ */
+function normalizeDeclaration(val) {
+    const asArray = stringArray(val);
+    if (asArray)
+        return { agents: asArray };
+    if (!val || typeof val !== "object" || Array.isArray(val))
+        return undefined;
+    const obj = val;
+    const agents = stringArray(obj.agents);
+    const workflows = stringArray(obj.workflows);
+    if (!agents && !workflows)
+        return undefined;
+    return { agents, workflows };
+}
+/**
+ * Read the subagent declaration out of a parsed `package.json`.
+ *
+ * `pi.subagents` wins over the top-level `pi-subagents` when a package carries
+ * both — the pi-namespaced key is the primary spelling here, and a package that
+ * writes both almost certainly means them to be identical anyway.
+ */
+export function readSubagentManifest(pkg) {
+    if (!pkg || typeof pkg !== "object")
+        return undefined;
+    const obj = pkg;
+    const piKey = obj.pi;
+    if (piKey && typeof piKey === "object" && !Array.isArray(piKey)) {
+        const nested = normalizeDeclaration(piKey.subagents);
+        if (nested)
+            return nested;
+    }
+    return normalizeDeclaration(obj["pi-subagents"]);
+}
+/** Parse `<root>/package.json`, or undefined when it is missing or malformed. */
+function readPackageJson(root) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"));
+        return parsed && typeof parsed === "object" ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `@scope/foo` becomes `foo`, lowercased. The name a user types in an allowlist. */
+export function unscopedShortName(name) {
+    const short = name.startsWith("@") ? name.slice(name.indexOf("/") + 1) : name;
+    return short.toLowerCase();
+}
+// ---- Path resolution ----
+/**
+ * Canonical absolute path, resolving symlinks as far as the path exists.
+ *
+ * A plain `realpathSync` is not enough: an exclusion may name a file the package
+ * does not ship yet, and a bare `resolve()` fallback would leave it uncanonical
+ * — which on macOS means `/var/...` compared against a canonical `/private/var/...`
+ * root, so the containment check below rejects it. Canonicalizing the nearest
+ * existing ancestor and re-appending the rest keeps both sides comparable.
+ */
+function realOrSelf(path) {
+    const abs = resolve(path);
+    try {
+        return realpathSync(abs);
+    }
+    catch {
+        const parent = dirname(abs);
+        return parent === abs ? abs : join(realOrSelf(parent), basename(abs));
+    }
+}
+/**
+ * True when `candidate` is inside `root`. Package manifests are third-party
+ * input, so `"../../.ssh"` must not become a scanned directory — pi refuses the
+ * same shape with "Refusing to use path outside package install root".
+ *
+ * Compared on canonical paths, because `..` is not the only way out: a symlinked
+ * `agents/` pointing at `/etc` is textually inside the root, and `readdirSync`
+ * follows it. Both sides are canonicalized so a package installed *under* a
+ * symlink (`/var` → `/private/var` on macOS) still matches itself.
+ */
+function isInside(root, candidate) {
+    const rel = relative(realOrSelf(root), realOrSelf(candidate));
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+/**
+ * Resolve one manifest entry against the package root, returning the path only
+ * when it stays inside the package and exists.
+ *
+ * Globs are deliberately not supported. Pi's own manifest expands them because
+ * it resolves four resource types across arbitrary layouts; here the entries are
+ * one or two directories, and a glob would mean walking a third-party tree to
+ * answer. A directory or a file path covers the declared use cases.
+ */
+function expandEntry(root, entry) {
+    const target = resolve(root, entry);
+    if (!isInside(root, target) || !existsSync(target))
+        return undefined;
+    return target;
+}
+/**
+ * Resolve one kind's declared entries into concrete absolute paths inside the
+ * package: directories to scan, and individual files.
+ *
+ * Split into `{ dirs, files }` rather than a flat list because the agent loader
+ * takes directories (it does its own `readdirSync` and frontmatter handling),
+ * while a manifest entry naming a single file has to be surfaced on its own.
+ *
+ * `!entry` marks an exclusion. Exact paths only — pi's own `!` is gitignore-style
+ * glob negation, and globs are not supported here for the reason above.
+ */
+export function resolveDeclaredPaths(root, entries, kind) {
+    const dirs = [];
+    const files = [];
+    const excluded = new Set();
+    if (!entries)
+        return { dirs, files, excluded };
+    // Exclusions are collected first and stored canonically, so `!./agents/wip.md`
+    // matches the same file however the loader spelled its way to it. They do not
+    // have to exist: a package may exclude a path it ships conditionally.
+    for (const entry of entries) {
+        if (!entry.startsWith("!"))
+            continue;
+        const target = resolve(root, entry.slice(1));
+        if (isInside(root, target))
+            excluded.add(realOrSelf(target));
+    }
+    const ext = KIND_EXTENSION[kind];
+    for (const entry of entries) {
+        if (entry.startsWith("!"))
+            continue;
+        const path = expandEntry(root, entry);
+        if (!path || excluded.has(realOrSelf(path)))
+            continue;
+        let stat;
+        try {
+            stat = statSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            if (!dirs.includes(path))
+                dirs.push(path);
+        }
+        else if (stat.isFile() && path.endsWith(ext) && !files.includes(path)) {
+            files.push(path);
+        }
+    }
+    return { dirs, files, excluded };
+}
+/**
+ * Build a read-only view of pi's configured packages.
+ *
+ * Feature-detected rather than assumed: the peer range `>=1.1.0` is open-ended,
+ * so a later pi that drops or renames this API contributes no packages instead
+ * of failing activation.
+ */
+function configuredPackages(cwd, projectTrusted) {
+    try {
+        if (typeof DefaultPackageManager !== "function")
+            return [];
+        const agentDir = getAgentDir();
+        const settingsManager = SettingsManager.create(cwd, agentDir, { projectTrusted });
+        const manager = new DefaultPackageManager({ cwd, agentDir, settingsManager });
+        if (typeof manager.listConfiguredPackages !== "function")
+            return [];
+        return manager.listConfiguredPackages();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Every installed pi package that declares subagent resources, in pi's own
+ * order (global entries first, then project). Duplicates by root are collapsed —
+ * a package listed in both scopes is one package on disk.
+ */
+export function listPiPackages(cwd, projectTrusted = false) {
+    const seen = new Set();
+    const out = [];
+    for (const entry of configuredPackages(cwd, projectTrusted)) {
+        const root = entry.installedPath;
+        if (!root || seen.has(root))
+            continue;
+        const manifest = readPackageJson(root);
+        const declared = manifest ? readSubagentManifest(manifest) : undefined;
+        if (!manifest || !declared)
+            continue;
+        seen.add(root);
+        const name = typeof manifest.name === "string" ? manifest.name : undefined;
+        out.push({
+            source: entry.source,
+            name,
+            shortName: name ? unscopedShortName(name) : undefined,
+            scope: entry.scope,
+            root,
+            declared,
+        });
+    }
+    return out;
+}
+/**
+ * Whether `pkg` passes the gate. `true`/omitted admits everything; an array
+ * matches case-insensitively against the unscoped short name, the full package
+ * name, or the settings source string — users reach for whichever of the three
+ * they happen to have in front of them.
+ */
+export function packageAllowed(pkg, gate) {
+    if (gate === false)
+        return false;
+    if (gate === undefined || gate === true)
+        return true;
+    const candidates = new Set([pkg.shortName, pkg.name?.toLowerCase(), pkg.source.toLowerCase()].filter((v) => typeof v === "string"));
+    return gate.some(allowed => candidates.has(allowed.trim().toLowerCase()));
+}
+/** A resolved-paths value with nothing in it. Fresh each call — callers get copies. */
+function emptyPaths() {
+    return { dirs: [], files: [], excluded: new Set() };
+}
+/** A whole cache entry with nothing in it, for a gate that admits no package. */
+function emptyEntry() {
+    return { agents: emptyPaths(), workflows: emptyPaths(), owners: [] };
+}
+const cache = new Map();
+/** Drop the memoized package scan. Called on `/reload` and after settings changes. */
+export function invalidatePackageCache() {
+    cache.clear();
+}
+function scan(cwd, projectTrusted, gate) {
+    const entry = emptyEntry();
+    for (const pkg of listPiPackages(cwd, projectTrusted)) {
+        if (!packageAllowed(pkg, gate))
+            continue;
+        // The root is normalized here, not at lookup time: the declared paths below
+        // go through `resolve(root, entry)`, so a root that arrived with a trailing
+        // separator would never prefix-match the very paths it produced.
+        //
+        // `name` is absent only when the manifest had no usable `name` string; the
+        // settings source (`npm:@foo/bar@1.0.0`) is the last resort, which is what
+        // pi itself falls back to when it labels a package-provided resource.
+        entry.owners.push({ root: resolve(pkg.root), name: pkg.name ?? pkg.shortName ?? pkg.source });
+        for (const kind of ["agents", "workflows"]) {
+            const resolvedPaths = resolveDeclaredPaths(pkg.root, pkg.declared[kind], kind);
+            entry[kind].dirs.push(...resolvedPaths.dirs);
+            entry[kind].files.push(...resolvedPaths.files);
+            // One flat set across packages: an exclusion is an absolute path, so it
+            // can only ever match inside the package that wrote it.
+            for (const path of resolvedPaths.excluded)
+                entry[kind].excluded.add(path);
+        }
+    }
+    // Longest root first, so a package installed inside another's `node_modules`
+    // claims its own files rather than losing them to its host.
+    entry.owners.sort((a, b) => b.root.length - a.root.length);
+    return entry;
+}
+function cacheEntryFor(cwd, kind, opts) {
+    const gate = opts.gate ?? (kind === "agents" ? agentsGate : workflowsGate);
+    // An empty allowlist matches nothing, like `false` — see `sanitizePackageGate`
+    // in settings.ts for why an empty array is kept rather than dropped.
+    if (gate === false || (Array.isArray(gate) && gate.length === 0))
+        return emptyEntry();
+    const projectTrusted = opts.projectTrusted ?? projectTrustedState;
+    // `\u0000` written as an escape, not a raw byte: a literal NUL makes this
+    // whole file read as binary to grep, ripgrep and git, which silently drops
+    // it from search results.
+    const key = `${cwd}\u0000${projectTrusted ? 1 : 0}\u0000${JSON.stringify(gate ?? true)}`;
+    let hit = cache.get(key);
+    if (!hit) {
+        hit = scan(cwd, projectTrusted, gate);
+        cache.set(key, hit);
+    }
+    return hit;
+}
+function resolved(cwd, kind, opts) {
+    return cacheEntryFor(cwd, kind, opts)[kind];
+}
+/**
+ * Name of the installed package that provided `path`, or undefined when no
+ * admitted package owns it. What `/agents` shows so a package agent can name its
+ * origin, and what a user needs in order to write a `packageAgents` allowlist.
+ *
+ * `kind` selects which gate to consult, because the two are configured
+ * separately: a package may be admitted for agents but not for workflows.
+ *
+ * A plain prefix test is enough. `resolveDeclaredPaths` builds every declared
+ * path as `resolve(root, entry)` without canonicalizing it — only the
+ * containment check and the exclusion set go through `realOrSelf` — so a
+ * `sourcePath` the loader derived from one is textually inside the root it came
+ * from. The `sep` anchor keeps `…/node_modules/foo` from claiming
+ * `…/node_modules/foo-bar`.
+ */
+export function packageNameForPath(path, cwd, kind = "agents", opts = {}) {
+    const abs = resolve(path);
+    return cacheEntryFor(cwd, kind, opts).owners.find(o => abs === o.root || abs.startsWith(o.root + sep))?.name;
+}
+/**
+ * Directories of package-declared agent files, lowest-precedence first.
+ * Fed to `loadCustomAgents` ahead of the global and project roots.
+ */
+export function packageAgentDirs(cwd, opts = {}) {
+    // A copy: the cache holds this array for the rest of the session, so a caller
+    // that sorted or spliced it would corrupt every later load.
+    return [...resolved(cwd, "agents", opts).dirs];
+}
+/** Individually declared agent `.md` files (a manifest entry naming a file, not a directory). */
+export function packageAgentFiles(cwd, opts = {}) {
+    return [...resolved(cwd, "agents", opts).files];
+}
+/**
+ * Whether a `!` entry in some package manifest excludes this path.
+ *
+ * Checked at load time rather than subtracted during resolution, because the
+ * common exclusion — `["./agents", "!./agents/wip.md"]` — names a file inside a
+ * directory that is not enumerated until the loader reads it.
+ */
+export function isPackageResourceExcluded(path, cwd, kind, opts = {}) {
+    const excluded = resolved(cwd, kind, opts).excluded;
+    return excluded.size > 0 && excluded.has(realOrSelf(path));
+}
+/**
+ * Directories of package-declared workflow scripts, appended to
+ * `savedWorkflowRoots` so a name resolves there last.
+ */
+export function packageWorkflowDirs(cwd, opts = {}) {
+    return [...resolved(cwd, "workflows", opts).dirs];
+}
+/**
+ * Individually declared workflow scripts, as `name -> absolute path`.
+ *
+ * A name lookup wants a directory, and a declared *file* has none — but standing
+ * its parent directory in as a root would make every sibling `.js` resolvable,
+ * so `workflows: ["./one.js"]` would quietly offer the package's other scripts
+ * too, and `["./index.js"]` would offer everything at the package root. That is
+ * the opposite of the rule the whole feature rests on, that a package only
+ * contributes what it names. An exact map keeps the declaration honest, and
+ * matches how a declared agent file is already handled.
+ *
+ * Later entries lose a name clash, so a package's own directory-sourced script
+ * is not displaced by a file entry from a package resolved after it.
+ */
+export function packageWorkflowFiles(cwd, opts = {}) {
+    const out = new Map();
+    for (const path of resolved(cwd, "workflows", opts).files) {
+        const name = basename(path, KIND_EXTENSION.workflows);
+        if (!out.has(name))
+            out.set(name, path);
+    }
+    return out;
+}

package/dist/prompts.d.ts

@@ -0,0 +1,76 @@
+/**
+ * prompts.ts — System prompt builder for agents.
+ */
+import type { AgentConfig, EnvInfo } from "./types.js";
+/** Extra sections to inject into the system prompt (memory, skills, etc.). */
+export interface PromptExtras {
+    /** Persistent memory content to inject (first 200 lines of MEMORY.md + instructions). */
+    memoryBlock?: string;
+    /** Preloaded skill contents to inject. */
+    skillBlocks?: {
+        name: string;
+        content: string;
+    }[];
+    /**
+     * Parent directory the worktree copy was created from. Set only for
+     * `isolation: "worktree"` spawns — triggers the block that tells the agent
+     * to stay in the copy.
+     */
+    worktreeBase?: string;
+    /**
+     * Set only for a workflow's own children, and only when they have no
+     * `StructuredOutput` tool to answer through.
+     *
+     * A workflow child's final text is not read by a human — it is the value
+     * `agent()` resolves to, and the script interpolates it straight into the
+     * next stage's prompt. Without this, children answer the way every other
+     * subagent does (a report addressed to a reader), and the padding becomes
+     * input tokens for the stage downstream. Claude Code's `Workflow` tool
+     * documents this contract to the script-writing model; this is the end of it
+     * that makes the documentation true.
+     *
+     * Deliberately NOT applied to every subagent. In pi an ordinary agent's
+     * output IS read by a human — through FleetView, the conversation viewer and
+     * `get_subagent_result` — so terse raw data would be the wrong answer there.
+     */
+    workflowChild?: boolean;
+}
+/**
+ * Build the system prompt for an agent from its config.
+ *
+ * - "replace" mode: env header + config.systemPrompt (full control, no parent identity)
+ * - "append" mode: parent system prompt + sub-agent context + env header + config.systemPrompt
+ * - "append" with empty systemPrompt: pure parent clone
+ *
+ * Both modes include an `<active_agent name="${config.name}"/>` tag so downstream
+ * extensions (e.g. permission/policy systems) can resolve per-agent policy
+ * inside the child session by parsing the system prompt. In replace mode the tag
+ * is prepended; in append mode it follows the shared inherited content so the
+ * parent prompt forms an identical, cacheable byte prefix with the parent
+ * session (the LLM's KV cache can then reuse those tokens across every spawn).
+ *
+ * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
+ * @param extras  Optional extra sections to inject (memory, preloaded skills).
+ */
+export declare function buildAgentPrompt(config: AgentConfig, cwd: string, env: EnvInfo, parentSystemPrompt?: string, extras?: PromptExtras): string;
+/**
+ * The part of the parent's rendered system prompt that an append-mode child inherits.
+ *
+ * Pi renders a prompt as the preamble followed by tagged sections in a fixed order:
+ * `tools`, `rules`, `docs` (default preamble only), `addendum`, `project_context`,
+ * `skills`, `cwd`, then the sections extensions add during a turn. The child session renders its own `skills` (from its `skills:`
+ * setting), its own `cwd` and its own extension sections after the inherited text.
+ * Inheriting the parent's copies too listed them twice, showed the parent's skills to
+ * children configured with `skills: false` or a preload list, and left copies that
+ * section-editing extensions in the child cannot reach. It also made the result depend
+ * on timing: `getSystemPrompt()` includes the extension sections only while the
+ * parent's turn runs.
+ *
+ * Returns the text before the `skills` section, or before the `cwd` section when there
+ * are no skills. A prompt without the `cwd` section (for example, a forced prompt) is
+ * returned unchanged.
+ *
+ * @param rendered  The parent's `ctx.getSystemPrompt()`.
+ * @param cwd  The cwd the parent's prompt was rendered with.
+ */
+export declare function inheritableParentPrompt(rendered: string, cwd: string): string;