@pi-archimedes/subagent 2.10.3 → 2.11.0

package/src/thinking-validation.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from "vitest";
+import {
+  THINKING_LEVELS,
+  THINKING_LEVELS_PI_VERSION,
+  isThinkingLevel,
+  resolveThinkingLevel,
+  formatUnknownThinkingWarning,
+} from "./thinking-validation.js";
+
+// pi's CLI keeps its own list of accepted `--thinking` levels and, for anything
+// outside it, warns and drops the flag rather than failing
+// (`pi/dist/cli/args.js`: `VALID_THINKING_LEVELS`). A child configured with a
+// level pi does not take therefore runs at the default while its config claims
+// otherwise, and in `--mode json` the warning lands in stderr — which the stream
+// reader only ever shows for a failed run.
+//
+// This file pins the copy of that list the suite checks against. The host's own
+// validator cannot be consulted: pi's `exports` map publishes only `"."` and
+// `"./rpc-entry"`, so `dist/cli/args.js` is not importable, and the root entry
+// re-exports neither `isValidThinkingLevel` nor `VALID_THINKING_LEVELS` nor the
+// `ThinkingLevel` type that could pin it at compile time. What the test can do is
+// pin the list and the pi version it claims to describe, so drift is a
+// deliberately-edited constant rather than an invisible difference — and the
+// consequence of not editing it stays a warning plus pi's default, never a
+// dispatch refused over a word the host has since learned.
+
+describe("isThinkingLevel", () => {
+  it("accepts exactly pi's seven levels", () => {
+    expect([...THINKING_LEVELS]).toEqual([
+      "off",
+      "minimal",
+      "low",
+      "medium",
+      "high",
+      "xhigh",
+      "max",
+    ]);
+    for (const level of THINKING_LEVELS) expect(isThinkingLevel(level)).toBe(true);
+  });
+
+  it("refines the value it accepts", () => {
+    const value: unknown = "high";
+    if (isThinkingLevel(value)) {
+      const asString: string = value;
+      expect(asString).toBe("high");
+    } else {
+      throw new Error("high should be a thinking level");
+    }
+  });
+
+  it("refuses a level pi warns about and drops", () => {
+    for (const bad of ["ultra", "Medium", "medium ", "highest", "auto", "0"]) {
+      expect(isThinkingLevel(bad), bad).toBe(false);
+    }
+  });
+
+  it("refuses anything that is not a string at all", () => {
+    for (const bad of [undefined, null, 2, true, ["low"]]) {
+      expect(isThinkingLevel(bad)).toBe(false);
+    }
+  });
+});
+
+describe("resolveThinkingLevel", () => {
+  it("passes a valid level through", () => {
+    expect(resolveThinkingLevel("xhigh")).toEqual({ level: "xhigh", warning: undefined });
+  });
+
+  it("says nothing when the config set no level", () => {
+    expect(resolveThinkingLevel(undefined)).toEqual({ level: undefined, warning: undefined });
+    expect(resolveThinkingLevel("")).toEqual({ level: undefined, warning: undefined });
+  });
+
+  it("withholds a level pi would drop, and says so", () => {
+    const resolved = resolveThinkingLevel("ultra");
+    expect(resolved.level).toBeUndefined();
+    expect(resolved.warning).toContain('"ultra"');
+    expect(resolved.warning).toMatch(/default thinking level/i);
+    for (const level of THINKING_LEVELS) {
+      expect(resolved.warning).toContain(level);
+    }
+  });
+});
+
+describe("formatUnknownThinkingWarning", () => {
+  it("names the value rather than describing the problem in the abstract", () => {
+    expect(formatUnknownThinkingWarning("turbo")).toContain("turbo");
+  });
+
+  it("says which pi the level list came from", () => {
+    // The list is a copy of the host's, so the sentence that quotes it has to
+    // say whose list it is — a reader on a newer pi should question it rather
+    // than trust it.
+    expect(formatUnknownThinkingWarning("turbo")).toContain(THINKING_LEVELS_PI_VERSION);
+  });
+});

package/src/thinking-validation.ts

@@ -0,0 +1,78 @@
+// ── The `thinking:` field: what the child will actually accept ─────────────
+//
+// A child is spawned with `--thinking <level>`, and pi's CLI parser keeps its
+// own list (`pi/dist/cli/args.js`: `VALID_THINKING_LEVELS`, `isValidThinkingLevel`).
+// A level outside that list is **not** an error there: the parser pushes a
+// `warning` diagnostic and drops the flag, so the child runs at the default
+// thinking level while the config says something else. In `--mode json` that
+// warning goes to stderr, and `stream.ts` only reads stderr for a *failed* run —
+// so a successful dispatch reported "thinking: medium" having run nothing of the
+// sort. Greptile found it; a live 1.2.0 child confirmed the mechanism.
+//
+// So the suite drops the same value first and says so out loud, at dispatch,
+// where the user is watching. Not a refusal: the run still happens, at exactly
+// the level pi would have used anyway — the difference is that it is now named
+// instead of swallowed. That is also what keeps this safe across a pi upgrade
+// that *adds* a level: the worst case is a warning and the default, never a
+// dispatch refused over a word the host has since learned.
+//
+// The list is duplicated here because there is no other way to read it. pi
+// exports only `"."` and `"./rpc-entry"` (its package `exports` map), so
+// `@earendil-works/pi-coding-agent/dist/cli/args.js` — where `isValidThinkingLevel`
+// and `VALID_THINKING_LEVELS` live — is not importable; the root entry does not
+// re-export either, nor the `ThinkingLevel` type that would pin the set at
+// compile time (that lives in `@earendil-works/pi-agent-core`, which this package
+// cannot resolve). So the copy below is checked by test, not by the host, and the
+// warning names the pi version it was read from — `thinking-validation.test.ts`
+// pins both. `model-validation.ts` (ADR 0008) already keeps a host-owned set the
+// same way for model ids, obtaining those through the `modelRegistry` handle
+// instead, which for levels does not exist.
+
+/** pi's own `VALID_THINKING_LEVELS` were read from, and the version they were
+ * read from. The warning quotes the version so a reader on a newer host knows
+ * which list they are being handed. */
+export const THINKING_LEVELS_PI_VERSION = "1.2.0";
+
+/** pi 1.2.0's `VALID_THINKING_LEVELS`, in pi's order. */
+export const THINKING_LEVELS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+] as const;
+
+/** Whether `level` is a thinking level pi's own `--thinking` accepts. */
+export function isThinkingLevel(level: unknown): level is string {
+  return typeof level === "string" && (THINKING_LEVELS as readonly string[]).includes(level);
+}
+
+/**
+ * The thinking level to put on the child's command line, and what to say about
+ * the one we are not putting there.
+ *
+ * `level` is what to pass (undefined = no `--thinking` flag at all); `warning`
+ * is set when the config asked for something pi would have dropped anyway.
+ */
+export function resolveThinkingLevel(
+  configured: string | undefined,
+): { level: string | undefined; warning: string | undefined } {
+  if (configured === undefined || configured === "") return { level: undefined, warning: undefined };
+  if (isThinkingLevel(configured)) return { level: configured, warning: undefined };
+  return { level: undefined, warning: formatUnknownThinkingWarning(configured) };
+}
+
+/**
+ * The warning for a level pi's `--thinking` does not take.
+ *
+ * It names the value, the accepted set, and what the child is running at
+ * instead — "the flag was dropped" is only useful if you learn the consequence.
+ */
+export function formatUnknownThinkingWarning(configured: string): string {
+  return [
+    `Subagent asked for thinking level "${configured}", which pi's --thinking does not take.`,
+    `The run proceeds at pi's default thinking level. Valid levels (pi ${THINKING_LEVELS_PI_VERSION}): ${THINKING_LEVELS.join(", ")}.`,
+  ].join(" ");
+}

package/src/tool-declarations.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Task 11 item 3 — `subagent` is for the model, not for scripts, and
+ * `list_agents` stays reachable both ways.
+ *
+ * `exposure: "model-only"` is measured, not assumed (see the same file in
+ * `ask` for the method and the pi source references). For `subagent` the cost is
+ * concrete and it was observed before the change: a codemode script called
+ * `tools.subagent({ task: "Reply with exactly the single word: child" })` and
+ * got the whole run back as a structured value —
+ * `{"mode":"single","results":[{... "outcome":"completed","finalOutput":"child" ...}]}`.
+ * After the change that same script line reports
+ * `tools.subagent does not exist` and `subagent` is absent from `ALL_TOOLS`.
+ *
+ * The plan takes the exposure anyway (`docs/roadmap/pi-1-x-alignment.md`,
+ * Task 11 item 3): a subagent dispatch is an orchestration step that pi's own
+ * docs file under "Use it for orchestrating or interactive tools", the model
+ * still drives it, and the nested-call path it does remove is one where the
+ * child's row renders inside a script row the user cannot expand. Say so to the
+ * maintainer rather than discover it later.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { registerSubagent } from "./index.js";
+
+type RegisteredTool = { name: string; exposure?: string; annotations?: Record<string, boolean> };
+
+function register(): Record<string, RegisteredTool> {
+  const tools: RegisteredTool[] = [];
+  registerSubagent({
+    registerTool: (t: unknown) => tools.push(t as RegisteredTool),
+    on: () => {},
+    getAllTools: () => [],
+    events: { emit: () => {}, on: () => () => {} },
+  } as never);
+  return Object.fromEntries(tools.map((t) => [t.name, t]));
+}
+
+describe("subagent exposure", () => {
+  it("subagent is model-only: declared to the model, never callable from a script", () => {
+    expect(register().subagent!.exposure).toBe("model-only");
+  });
+
+  it("list_agents stays direct — a script that dispatches nothing still reads the catalogue", () => {
+    expect(register().list_agents!.exposure ?? "direct").toBe("direct");
+  });
+
+  it("neither tool carries annotations", () => {
+    const tools = register();
+    expect(tools.subagent!.annotations).toBeUndefined();
+    expect(tools.list_agents!.annotations).toBeUndefined();
+  });
+
+  it("nothing in this package is codemode or deferred exposure (ADR 0029)", () => {
+    for (const tool of Object.values(register())) {
+      expect(["codemode", "deferred", "hidden"]).not.toContain(tool.exposure);
+    }
+  });
+});