pi-ptc-subagents 1.5.1 → 2.0.0

package/dist/index.d.ts

@@ -662,14 +662,16 @@ interface DefaultModeConfig {
 export declare function readDefaultModeConfig(agentDir: string): DefaultModeConfig;
 /**
  * Which model-facing tools this package registers, independent of PTC mode (which decides
- * which registered tools are *active*). Read from the same agent-dir file as
- * {@link readDefaultModeConfig}, beside the `defaultMode` key. ADR-0025.
+ * which registered tools are *active*).
  *
- * The order below is the order of increasing responsibility: `off` hands the whole
- * orchestration question back to pi, `subagents` keeps only the subagent face and lets pi's
- * `codemode` orchestrate, `full` keeps today's set.
+ * These are DETECTED values, not settings. The list is two long because detection is the only
+ * thing that produces them: `subagents` keeps the subagent face and lets pi's `codemode`
+ * orchestrate, `full` keeps the whole set. There was a third, `off`, and a `surfaceMode` key
+ * that could pin any of the three (ADR-0025); both are gone, and
+ * {@link detectSurfaceMode} is now a pure function of what pi is — see its doc for why the
+ * escape hatch the setting provided is not one this package can replace.
  */
-export declare const SURFACE_MODES: readonly ["off", "subagents", "full"];
+declare const SURFACE_MODES: readonly ["subagents", "full"];
 type SurfaceMode = (typeof SURFACE_MODES)[number];
 /**
  * Whether the pi that launched us will actually LOAD its `codemode` extension.
@@ -719,43 +721,98 @@ export declare function readCodemodeSwitch(agentDir: string, cwd: string, argv?:
  * Whether `codemode` will be CALLABLE, as a third question distinct from whether pi ships the
  * directory (ADR-0026) and whether it will load the extension (ADR-0027).
  *
- * - `"active"` — a loadout names it, so the model can call it.
- * - `"inactive"` — nothing names it, which on a real install is the DEFAULT: pi registers
- *   `codemode` with `defaultActive: false` and activates it only when a loadout says so.
+ * - `"active"` — a loadout names it OR pi's MCP extension will auto-enable it from `mcp.json`
+ *   (ADR-0033), so the model can call it.
+ * - `"inactive"` — nothing names it and nothing auto-enables it, which on a real install is the
+ *   DEFAULT: pi registers `codemode` with `defaultActive: false`
+ *   (`dist/extensions/codemode/index.js:26`).
  *
  * `"inactive"` is what every failure of this probe on the positive side resolves to, and that is
  * the design rather than a fallback: `subagents` is chosen only on positive evidence that the tool
  * is callable. See ADR-0029, "The bound that makes the weaker guarantee sufficient".
  */
 type CodemodeActivation = "active" | "inactive";
-/** How the answer was decided, so a test can tell a configured answer from pi's default. */
-type CodemodeActivationSource = "cli" | "project" | "user" | "default" | "invalid";
+/**
+ * How the answer was decided, so a test can tell a configured answer from pi's default.
+ *
+ * `"loadout"` is pi's own live tool set — the answer is read, not reconstructed, so there is no
+ * provenance left to name: whatever put `codemode` there is pi's business and not something this
+ * package can see. `"mcp"` is ADR-0033: the live loadout said `inactive` and the MCP auto-enable
+ * evidence said pi will activate `codemode` anyway, because pi's MCP extension does that from its
+ * own `session_start` handler and a read from ours can be too early to see it.
+ */
+type CodemodeActivationSource = "loadout" | "invalid" | "mcp";
 /** The answer plus enough provenance to explain it in a notice. */
 interface CodemodeActivationResolution {
   activation: CodemodeActivation;
   source: CodemodeActivationSource;
   /** Set when a settings file could not be read as a JSON object; the answer still resolves. */
   error?: string;
+  /**
+   * Set when an `mcp.json` could not be read as a JSON object (ADR-0033); that file contributed
+   * nothing to the answer, and the answer still resolves.
+   */
+  mcpError?: string;
 }
 /**
- * Resolve whether `codemode` will be in the model's tool list, in the order pi resolves the
- * loadout: the command-line allowlist, then the merged `defaultTools`, then pi's own default.
+ * Everything the loadout side of this probe used to need, deleted with the probe.
+ *
+ * `PI_DEFAULT_TOOL_NAMES`, `isToolModifier`, `stringEntries`, `mergeDefaultTools` and
+ * `resolveDefaultTools` were a second implementation of pi's `defaultTools` resolution — the merge
+ * direction, the modifier grammar, the "a list of only modifiers starts from pi's four defaults"
+ * rule. It existed because the factory had to know the answer before pi would let this package ask,
+ * and reimplementing the rule was the only way to know it in advance.
+ *
+ * The answer is now read from pi instead, so there is nothing left for these to be right about. A
+ * second implementation of a rule the host owns is a defect waiting for the host to change the rule,
+ * which is how #131 happened: a project's `defaultTools` was honoured here whether or not pi would
+ * ever read it.
+ */
+/**
+ * The command-line reader is gone with the reconstruction it existed for.
+ *
+ * `splitCliToolList`, `PI_VALUE_CONSUMING_FLAGS`, `PI_CONDITIONALLY_CONSUMING_FLAGS`,
+ * `piPrintConsumesNext`, `CliToolFlags` and `cliToolFlags` parsed `process.argv` to work out
+ * which tools pi would activate: `--tools` as an allowlist, `--exclude-tools` as a denylist,
+ * `--no-tools` and `--no-builtin-tools` as the two ways of emptying the list, plus the value-
+ * consuming grammar those flags live in, because a value that looks like a flag must not be
+ * re-read as one.
  *
- * The last of those is the load-bearing one and is what makes absence of evidence mean
- * `inactive`: pi registers `codemode` inactive, so a session that configured nothing does not get
- * it, and delegating orchestration to a tool the model cannot call is the failure this exists to
- * prevent.
+ * It was careful — a 294-case differential against pi's own parser found no disagreement once it
+ * was made to agree, and every divergence before that had been argued away as pointing in a safe
+ * direction. That argument is what this deletion is about rather than the code: it was wrong.
+ * Reading the command line correctly is not the same as knowing what pi will do with it, and the
+ * settings half had already shown how that goes wrong — #131 is this reader's sibling, with the
+ * same shape of mistake on the file side.
+ *
+ * The reader's replacement is one call, and it is the host's own answer rather than a second
+ * opinion on it. See {@link readCodemodeActivation}.
  */
-export declare function resolveCodemodeActivation(argv: readonly string[], projectSettings: unknown, userSettings: unknown): CodemodeActivationResolution;
 /**
- * Whether an explicit `surfaceMode` disagrees with what the table above decided.
+ * Whether `codemode` is in pi's active tool set, as pi reports it.
+ *
+ * This is the ADR-0029 loadout mirror with the mirror taken out. It used to resolve the same
+ * question by parsing the command line and merging the two `defaultTools` files, replaying pi's
+ * precedence over them:
+ *
+ * 1. `--tools` decides the list, and it beats `--no-tools`.
+ * 2. `--exclude-tools` vetoes whichever list won, because the denylist is a `.filter` over that
+ *    list rather than another source.
+ * 3. `--no-tools` and `--no-builtin-tools` with no allowlist empty the list, so `codemode` is not
+ *    active whatever `defaultTools` says.
+ * 4. Otherwise `defaultTools` decides, vetoed by the denylist exactly as in (2).
  *
- * The explicit key always WINS — that is what an override is for — so this exists only to be
- * reported. `off` is exempt: it means "I do not want this package's surface at all", which is a
- * statement about the package rather than a claim about who orchestrates, and warning about it on
- * every session would be crying wolf.
+ * All four are still true, and none of them is restated here. pi has already applied them, along
+ * with the project-trust decision, by the time an extension can read its loadout at
+ * `session_start`; asking it is both shorter and correct in the case that a second implementation
+ * cannot be, which is when the two disagree about something pi changed.
+ *
+ * Absence still means `inactive`, and that is unchanged rather than defaulted: pi registers
+ * `codemode` with `defaultActive: false`, so a session that configured nothing does not get it, and
+ * delegating orchestration to a tool the model cannot call is the failure this whole probe exists
+ * to prevent.
  */
-export declare function surfaceModeConflict(explicit: SurfaceMode | undefined, detected: SurfaceMode): boolean;
+export declare function resolveCodemodeActivation(activeToolNames: readonly string[]): CodemodeActivationResolution;
 /**
  * Whether the pi that launched us ships its own `codemode` orchestration tool.
  *
@@ -785,80 +842,75 @@ interface CodemodePresence {
   /** How the answer was reached, so a test can tell a measured yes from a failed probe. */
   how: "found" | "not-found" | "no-entry" | "unresolvable-entry";
 }
-/** Result of reading the surface mode, with enough detail to warn about a broken file. */
-interface SurfaceModeConfig {
+/** The detected surface, plus every probe result `session_start` reports on. */
+interface DetectedSurface {
+  /** What this package registers. Decided by {@link detectedSurfaceMode}; never configured. */
   surfaceMode: SurfaceMode;
-  source: "file" | "default" | "invalid";
-  error?: string;
-  /**
-   * What the probe found, on the paths where the surface was NOT decided by the file. Absent
-   * when the user set the key: that call never consults the probe (see
-   * {@link readSurfaceModeConfig}), so there is nothing to report.
-   */
-  codemode?: CodemodePresence;
-  /**
-   * Whether pi will actually load its own codemode (ADR-0027). Absent for the same reason as
-   * {@link codemode}: an explicit key short-circuits the probe, so there is nothing to report.
-   */
-  codemodeSwitch?: CodemodeSwitchResolution;
-  /**
-   * Whether `codemode` will be in the model's tool list (ADR-0029), the third axis of the
-   * detected table. Absent for the same reason as {@link codemodeSwitch}.
-   */
-  codemodeActivation?: CodemodeActivationResolution;
-  /**
-   * What the four-case table decided, carried even when an explicit key overrode it — that
-   * difference is exactly what {@link surfaceModeConflict} reports on.
-   */
-  detected?: SurfaceMode;
+  /** Whether this pi ships a `codemode` at all. */
+  codemode: CodemodePresence;
+  /** Whether pi will load it (ADR-0027). */
+  codemodeSwitch: CodemodeSwitchResolution;
+  /** Whether the model will be able to call it (ADR-0029), the third axis of the table. */
+  codemodeActivation: CodemodeActivationResolution;
 }
 /**
- * Read `surfaceMode` from the agent-dir config file.
+ * Decide the surface by asking the pi. A pure function of the three probes and nothing else.
+ *
+ * This used to read a `surfaceMode` key first and only fall back to the probes, and the argument
+ * for that was an escape hatch: pi has `registerTool` but no `unregisterTool`, so a surface chosen
+ * wrongly cannot be corrected once the factory has returned — a session that got the wrong answer
+ * keeps it until it restarts. That argument is real, and it is also why the hatch is gone rather
+ * than merely narrowed:
  *
- * A pure function over the filesystem, shaped like {@link readDefaultModeConfig} on purpose:
- * an absent file, an absent key, unparseable JSON, a non-object, a wrong-typed value and an
- * out-of-set value all resolve to the detected default rather than a hardcoded one, and every
- * malformed shape additionally reports `invalid` with a reason. A malformed setting must never
- * half-apply - which tools exist is not something to change on a guess.
+ * - **The wrong answer is now reported rather than prevented.** `session_start` measures the live
+ *   registry against all three probes and says so when they disagree (ADR-0029), which a pinned
+ *   value used to suppress.
+ * - **The direction that actually hurts is not reachable by a setting anyway.** A pin can only
+ *   make the surface *more* capable than detection, never less: every way the probes come back
+ *   wrong (`subagents` chosen for a `codemode` that cannot run) resolves to `full`, and no value
+ *   the file could hold would have produced a better outcome than the one already chosen.
+ * - **Disabling is pi's job now.** The `off` value existed because a package that cannot be
+ *   switched off is a package that stays loaded forever. `pi config` turns a package's extensions
+ *   off without loading them — measured, not assumed: on pi 1.1.0 a `packages` entry whose
+ *   `extensions` is `[]` or `["!dist/index.js"]` does not load the extension at all, while
+ *   `["+dist/index.js"]` and an absent key both do. That is a channel this package cannot offer
+ *   for itself, because the switch that uses it is pi's.
  *
- * The `presence` and `codemodeSwitch` arguments are parameters rather than hidden calls, so a test
- * can state the pi it is reasoning about instead of depending on the machine it runs on. Omit
- * them and the real probes answer, but only on a path that actually needs the answer: they are
- * resolved inside the fallback branches rather than in a default parameter, because a default
- * parameter is evaluated on EVERY call -- including the ones an explicit `surfaceMode` key
- * short-circuits, where the user paid a `realpathSync` plus up to three `statSync` and two
- * settings reads to set one line of JSON and get a constant.
+ * The `presence` and `codemodeSwitch` arguments stay parameters rather than hidden calls, so a
+ * test can state the pi it is reasoning about instead of depending on the machine it runs on.
+ *
+ * The probes are resolved here rather than in default parameters, so every call pays for all
+ * three — the shortcut that used to exist (`a default parameter is evaluated on EVERY call`)
+ * saved real work only when a key short-circuited the probes entirely, and there is no key left.
+ * The cost, named rather than rounded: each of the two settings-reading probes reads the SAME two
+ * files, so one detection is four settings reads over two files plus the two `mcp.json` reads
+ * ADR-0033 added. The duplication is pre-existing and deliberate — each probe is copied from pi
+ * whole and kept self-contained — so the number is recorded, not optimised.
  */
-export declare function readSurfaceModeConfig(agentDir: string, presence?: CodemodePresence, codemodeSwitch?: CodemodeSwitchResolution, codemodeActivation?: CodemodeActivationResolution, cwd?: string): SurfaceModeConfig;
-/** Outcome of writing `surfaceMode` for `/ptc surface`. */
-type SurfaceModeWrite = {
-  ok: true;
-  path: string;
-  /** The value already in the file, or `undefined` when there was none. */
-  previous: SurfaceMode | undefined;
-  /** False when the file already said this, in which case NOTHING was written. */
-  changed: boolean;
-} | {
-  ok: false;
+export declare function detectSurfaceMode(agentDir: string, activeToolNames: readonly string[], presence?: CodemodePresence, codemodeSwitch?: CodemodeSwitchResolution, codemodeActivation?: CodemodeActivationResolution, cwd?: string): DetectedSurface;
+/** A `surfaceMode` left in `ptc.json` by a release that still had the key. */
+interface LegacySurfaceKey {
+  /** The path it was found in, or `undefined` when there was no file to look in. */
   path: string;
-  error: string;
-};
+  /** The value that was there, or the JSON rendering when it was not a string. */
+  value: unknown;
+}
 /**
- * Write one `surfaceMode` key into the agent-dir config, preserving every other key.
+ * Read a `surfaceMode` key that this package no longer acts on, so `session_start` can say so.
  *
- * Three rules, each of which is a way a naive rewrite goes wrong:
+ * The key shipped in v1.6.0 and the three values it took are gone, which means a user who set
+ * `"off"` to keep this package out of their sessions would find it back on the next upgrade with
+ * nothing to explain why. Nothing here restores the behaviour: the returned value is only ever
+ * turned into a notice that names the replacement. The alternative — honouring `off` forever as a
+ * compatibility shim — is the switch this change exists to delete, and it would leave the package
+ * carrying two ways to be disabled, one of which silently does nothing.
  *
- * - **A malformed file is never overwritten.** An unparseable `ptc.json` is a file the user may
- *   be mid-edit on, and this command is not a licence to replace it with something valid that
- *   drops whatever was in it. The read side already reports that shape rather than acting on it
- *   ({@link readSurfaceModeConfig}), and the write side has to agree.
- * - **Other keys survive.** `defaultMode` lives in the same file (ADR-0010), and a command that
- *   wrote `{"surfaceMode": …}` wholesale would silently reset the user's mode preference.
- * - **An unchanged value writes nothing.** `/ptc surface full` on a session already at `full`
- *   should not touch the file's mtime, and — more to the point — should not trigger the reload
- *   that would follow, since a reload replaces every extension instance for no reason.
+ * Returns `undefined` for an absent file, an absent key, and for a file this cannot parse or that
+ * is not an object. Those last two are NOT reported here: a `ptc.json` too broken to read has no
+ * `surfaceMode` to be stale about, and the parse failure belongs to whoever owns that file
+ * (`defaultMode` still lives there, and {@link readDefaultModeConfig} is what reports it).
  */
-export declare function setSurfaceMode(agentDir: string, value: unknown): SurfaceModeWrite;
+export declare function readLegacySurfaceKey(agentDir: string): LegacySurfaceKey | undefined;
 /** Why the mode declined to turn on. Surfaced in the entry notification / debug logs. */
 type ModeBlockReason = "not-tui" | "config-off" | "tools-unavailable" | "restricted-session";
 /** Either the loadout to apply, or the reason the mode stayed off. */
@@ -1520,16 +1572,9 @@ export declare class TurnPools {
 export interface PtcSubagentsOptions {
   /** Use this session-scoped background runtime instead of constructing one. */
   backgroundRuntime?: BackgroundTaskRuntime;
-  /**
-   * Test seam for ADR-0025's surface mode. When set it wins over the agent-dir `ptc.json`,
-   * so a test never reads the developer's real settings -- and the four test files that all
-   * build this factory through one stub would otherwise inherit whatever the machine happens
-   * to have. Undefined in production, where the file is the only source.
-   */
-  surfaceMode?: SurfaceMode;
   /**
    * ADR-0026 test seam: what the codemode probe found. Undefined in production, where the
-   * probe really runs. A test that exercises the DETECTED default states the pi it
+   * probe really runs. A test that exercises the DETECTED surface states the pi it
    * assumes rather than inheriting whatever process.argv the test runner happens to have,
    * which is how the previous version of that test passed for the wrong reason.
    */
@@ -1541,8 +1586,24 @@ export interface PtcSubagentsOptions {
    * and that is the case this seam exists to state.
    */
   codemodeSwitch?: CodemodeSwitchResolution;
+  /**
+   * ADR-0029 test seam: whether `codemode` will be in the model's tool list. Undefined in
+   * production, where `readCodemodeActivation` reads pi's own active tool set and the MCP
+   * evidence — no settings file and no `argv` on this axis any more (ADR-0035).
+   *
+   * This seam exists because the `surfaceMode` pin it replaced did. That pin was there to keep a
+   * test off the developer's machine: the probe it fed read a settings file out of the developer's
+   * own agent dir, so a test file that pinned nothing decided its own surface by however the
+   * machine running it happened to be configured. Removing the pin without adding this would have
+   * moved that failure back in, silently, to every stub-built factory.
+   *
+   * The machine-dependence is gone — the loadout is handed in rather than read off disk — but the
+   * seam stays, because a test whose subject IS the axis needs to state an answer pi would not
+   * produce on its own (`null` runs the real probe; see `tests/helpers/ptc.ts`).
+   */
+  codemodeActivation?: CodemodeActivationResolution;
 }
 export default function ptcSubagents(pi: ExtensionAPI, options?: PtcSubagentsOptions): void;
 //#endregion
-export type { Binding, BindingContext, BindingTable, CodemodePresence, CodemodeSwitch, CodemodeSwitchResolution, CodemodeSwitchSource, CreateBuiltinBindingsOptions, DefaultModeConfig, ModeBlockReason, ModeEntryDecision, ModeEntryInput, ModeHideStrategy, PersistedModeState, PtcConfig, PtcErrorKind, PtcErrorShape, PtcImage, PtcJsonValue, PtcModeState, PtcRunOutcome, PtcSurface, RunPtcProgramOptions, SurfaceModeConfig, TurnPoolsOptions, WorkerPoolOptions, WorkerPoolStats, WorkerPoolWorkerOptions };
+export type { Binding, BindingContext, BindingTable, CodemodePresence, CodemodeSwitch, CodemodeSwitchResolution, CodemodeSwitchSource, CreateBuiltinBindingsOptions, DefaultModeConfig, DetectedSurface, LegacySurfaceKey, ModeBlockReason, ModeEntryDecision, ModeEntryInput, ModeHideStrategy, PersistedModeState, PtcConfig, PtcErrorKind, PtcErrorShape, PtcImage, PtcJsonValue, PtcModeState, PtcRunOutcome, PtcSurface, RunPtcProgramOptions, TurnPoolsOptions, WorkerPoolOptions, WorkerPoolStats, WorkerPoolWorkerOptions };
 //# sourceMappingURL=index.d.ts.map