kankaku-pi 1.0.0

package/dist/domain/subagent-profile.d.ts

@@ -0,0 +1,278 @@
+import type { UsageTotals } from "./work-record.ts";
+/**
+ * A child-process env marker a {@link SubagentProfile} recognises as
+ * confirmation that THIS process is one of its children (never guessed —
+ * see `resolveChildProfile`). `value: undefined` means "any non-empty
+ * value counts as present" (e.g. pi-subagents' `PI_SUBAGENT_DEPTH`, a
+ * recursion-depth counter, not a fixed sentinel); a defined `value`
+ * requires an exact match (e.g. gentle-pi's `GENTLE_PI_AGENTS_CHILD=1`).
+ */
+export interface ChildEnvMarker {
+    name: string;
+    value?: string;
+}
+/**
+ * How strongly a profile's children can be joined back to their
+ * orchestrator (ADR 0021): `"explicit-id"` when the tool result carries a
+ * stable id kankaku can use directly (gentle-pi's `taskId` — parent-side
+ * only, the child cannot read its own); `"ancestry"` when only the
+ * machine-wide process registry/ancestor-chain walk can join it;
+ * `"none"` for a profile that offers no join signal at all.
+ */
+export type JoinKeyConfidence = "explicit-id" | "ancestry" | "none";
+export interface SubagentLaunchInfo {
+    agent?: string;
+    mode?: string;
+}
+export interface SubagentResultInfo {
+    taskId?: string;
+    agent?: string;
+    status?: string;
+    mode?: string;
+    cwd?: string;
+    /**
+     * Nested LLM usage the subagent tool result reports on itself (pi's
+     * documented convention: "a tool making nested LLM calls should return
+     * their combined Usage as `usage`" — see `docs/extensions.md`). A
+     * profile whose children are ALSO separately tracked and joined via a
+     * confirmed child-env marker (ancestry-based `joinKeyConfidence`) must
+     * never report this — see `PI_SUBAGENTS_PROFILE` for why.
+     */
+    usage?: Partial<UsageTotals>;
+}
+/**
+ * Declares how kankaku recognises one subagent-launching ecosystem
+ * package: which tool call(s) open a subagent span, how to read
+ * `agent`/`mode` from the launch args and `taskId`/`status`/`mode`/`cwd`/
+ * `usage` from the tool result, which env var(s) confirm a child process of
+ * this kind, and how strong a join key it offers. See ADR 0020 and
+ * SUBAGENT-REQ-001.
+ */
+export interface SubagentProfile {
+    id: string;
+    toolNames: readonly string[];
+    childEnvMarkers: readonly ChildEnvMarker[];
+    joinKeyConfidence: JoinKeyConfidence;
+    readLaunchArgs(args: Record<string, unknown> | undefined): SubagentLaunchInfo;
+    readResult(result: unknown): SubagentResultInfo;
+}
+/**
+ * gentle-pi (first-class, ADR 0020): the richest, most robust profile —
+ * explicit `taskId` join, live `status`, `mode` (task/background) and
+ * cross-worktree `cwd`, all read from `result.details.gentleAgents`
+ * exactly as `work-tracker.ts#extractTaskId` did before this module
+ * existed. Verified against gentle-pi 3.3.0 source
+ * (`extensions/gentle-agents.ts`, `lib/agents-protocol.ts`,
+ * `lib/agents-runner.ts`): its tool result never carries a top-level
+ * `usage` field (children are separate OS processes, cost tracked
+ * independently through the existing ancestry/registry join) — this
+ * profile therefore never reports `usage`, so 6c's forwarding never
+ * touches gentle-pi's numbers.
+ */
+export declare const GENTLE_PI_PROFILE: SubagentProfile;
+/**
+ * pi's bundled reference example extension
+ * (`examples/extensions/subagent/index.ts`, tool `subagent`). Verified: its
+ * `spawn()` call passes no `env` option at all (the child simply inherits
+ * the parent's environment unmodified) — so it sets NO child-identifying
+ * env marker, and a child of this kind can only ever be recognised through
+ * ancestry (ADR 0020: "always starts uncertain"). Because it has no
+ * marker, it can never become a *confirmed* `role: "subagent"` record
+ * (see `resolveChildProfile`) and therefore can never be double-joined —
+ * safe to forward `usage` unconditionally.
+ */
+/**
+ * C1 investigation note (real-shape disambiguation, verified against the
+ * bundled reference example's actual source above): its real tool RESULT
+ * never actually sets a top-level `usage` field at all — every `execute()`
+ * return statement in `examples/extensions/subagent/index.ts` returns only
+ * `{content, details, isError?}`; nested-call usage lives per-result inside
+ * `details.results[].usage`, not where pi's documented convention (and
+ * `readStandardUsage` below) looks. `pi-subagents` (npm, verified against
+ * 0.28.0 `src/runs/foreground/subagent-executor.ts` and
+ * `src/runs/foreground/execution.ts`) is the same: no `execute()` return
+ * anywhere in that package sets a top-level `usage` either. So for BOTH
+ * real packages examined, `readStandardUsage(result)` returns `undefined`
+ * today regardless of which one actually answered the call — this
+ * profile's generic top-level-`usage` read exists for pi's DOCUMENTED
+ * convention (`docs/extensions.md`: "If a tool makes nested LLM calls,
+ * return their combined Usage as usage"), which a well-behaved third-party
+ * "subagent"-named tool, or a future version of either package, could
+ * start following at any time. That forward-looking risk is exactly what
+ * C1 guards against — see `safeAmbiguousResultInfo`.
+ */
+export declare const PI_REFERENCE_PROFILE: SubagentProfile;
+/**
+ * pi-subagents (npm package, tool `subagent`, action-based). Verified
+ * against the installed 0.28.0 source (`src/shared/types.ts`
+ * `getSubagentDepthEnv`): every child it spawns (foreground AND the
+ * detached background runner) carries `PI_SUBAGENT_DEPTH` — NOT
+ * `PI_SUBAGENT_PARENT_SESSION`, an earlier, unverified assumption this
+ * profile deliberately does not use. Because this marker CAN confirm a
+ * child as `role: "subagent"` (ancestry-joined, its own usage/cost already
+ * counted through that join), this profile's `readResult` deliberately
+ * never forwards `usage` even when present — forwarding it here would risk
+ * counting the same nested LLM work twice (once via the join, once via the
+ * forwarded figure). See `GENTLE_PI_PROFILE`/`PI_REFERENCE_PROFILE` for the
+ * two cases where forwarding is safe.
+ */
+export declare const PI_SUBAGENTS_PROFILE: SubagentProfile;
+export declare const BUILTIN_SUBAGENT_PROFILES: readonly SubagentProfile[];
+/**
+ * SUBAGENT-REQ-001/002/003: the user-configured profile built from
+ * `KANKAKU_SUBAGENT_TOOLS`/`KANKAKU_SUBAGENT_CHILD_ENV` (parsed in
+ * `config.ts`, mirroring `KANKAKU_INTERACTIVE_TOOLS`'s tolerant
+ * comma-split convention). Always additive to the built-ins, never
+ * replacing gentle-pi's own recognition. `undefined` when neither is
+ * configured, so `loadConfig` never adds an inert profile. Forwards
+ * `result.usage` generically (like `PI_REFERENCE_PROFILE`) — a documented,
+ * unavoidable residual risk: kankaku cannot know whether an arbitrary
+ * configured child process also runs kankaku itself and would otherwise be
+ * ancestry-joined, so a user who configures BOTH a child-env marker AND a
+ * tool that forwards `usage` for the same third-party package accepts that
+ * narrow double-count risk (see README "Subagents").
+ */
+export declare function buildConfiguredProfile(toolNames: readonly string[], childEnvMarkers: readonly ChildEnvMarker[]): SubagentProfile | undefined;
+/** Every profile whose `toolNames` include `toolName`, in the given order. */
+export declare function matchToolProfiles(profiles: readonly SubagentProfile[], toolName: string): SubagentProfile[];
+export interface ToolProfileResolution {
+    /** The single matching profile, or `undefined` when there is none or the tool name is ambiguous (never guessed). */
+    profile: SubagentProfile | undefined;
+    /** `true` when 2+ profiles register this exact tool name (SUBAGENT-REQ-005). */
+    ambiguous: boolean;
+    candidates: SubagentProfile[];
+}
+/**
+ * SUBAGENT-REQ-005: resolve which profile should be used to open/read a
+ * subagent span for a given tool name. Exactly one match resolves
+ * unambiguously; zero means this is not a recognised subagent tool call at
+ * all; two or more (e.g. `"subagent"`, registered by both the pi reference
+ * example and pi-subagents) is a genuine name collision — never guessed:
+ * `profile` stays `undefined` and `ambiguous` is `true` so the caller can
+ * still open a best-effort span (see `readLaunchInfo`/`readResultInfo`)
+ * without ever claiming a specific profile matched.
+ */
+/**
+ * C1 investigation note — real disambiguation was investigated and
+ * rejected for the "subagent" name collision between `PI_REFERENCE_PROFILE`
+ * and `PI_SUBAGENTS_PROFILE`, both by args/result SHAPE and by pi's own
+ * `getAllTools()[].sourceInfo.path`:
+ *
+ * - Args shape: pi-subagents' `action` field ("list"/"get"/"create"/
+ *   "update"/"delete"/"status"/"interrupt"/"resume"/"doctor" — verified
+ *   0.28.0 `src/extension/schemas.ts`) is absent from pi-reference's schema
+ *   entirely, so its PRESENCE would be conclusive — but it is only ever
+ *   set for pi-subagents' management/diagnostic calls, never for the
+ *   money-affecting single/parallel/chain execution calls (`agent`+`task`,
+ *   `tasks[]`, `chain[]`) that are the whole point of C1: those look
+ *   identical in both packages' schemas (`agent`, `task`, `tasks`,
+ *   `chain`, `cwd` all present in both). Result shape is no better: neither
+ *   package's real result carries a top-level `usage` at all (see
+ *   `PI_REFERENCE_PROFILE`'s doc comment) — no distinguishing signal is
+ *   present in exactly the calls that matter.
+ * - `sourceInfo.path`: `pi.getAllTools()` does expose which extension
+ *   registered a given tool name (`docs/extensions.md` "pi.getAllTools()").
+ *   But that same doc explicitly warns, for the structurally identical
+ *   `sourceInfo` on `pi.getCommands()`: "Use sourceInfo as the canonical
+ *   provenance field. Do not infer ownership from command names or from ad
+ *   hoc path parsing." Matching a tool's `sourceInfo.path` against a
+ *   hardcoded substring (a package name, an examples/ path) IS ad hoc path
+ *   parsing — the path is not guaranteed to contain any stable, portable
+ *   substring across install layouts (a monorepo, a symlinked/hoisted
+ *   dependency, a vendored fork). This was rejected as unreliable, not
+ *   merely inconvenient.
+ *
+ * Neither route was conclusive, so kankaku stays ambiguous by design
+ * (SUBAGENT-REQ-005: never guessed) and instead fixes the CONSEQUENCE of
+ * ambiguity — see `safeAmbiguousResultInfo`/`mergeAgreeingLaunchInfo` and
+ * `domain/work-tracker.ts#onToolEnd`.
+ */
+export declare function resolveToolProfile(profiles: readonly SubagentProfile[], toolName: string): ToolProfileResolution;
+/** Every tool name registered by 2+ profiles at once, with the colliding profile ids — a static property of the active profile set, independent of any record. */
+export declare function findAmbiguousToolNames(profiles: readonly SubagentProfile[]): Array<{
+    toolName: string;
+    profileIds: string[];
+}>;
+/** Best-effort merge of `readLaunchArgs` across several candidate profiles (an ambiguous tool-name match): first defined field, in profile order, wins. */
+export declare function readLaunchInfo(candidates: readonly SubagentProfile[], args: Record<string, unknown> | undefined): SubagentLaunchInfo;
+/** Best-effort merge of `readResult` across several candidate profiles (an ambiguous tool-name match): first defined field, in profile order, wins — never a profile-specific field none of the candidates actually provided. */
+export declare function readResultInfo(candidates: readonly SubagentProfile[], result: unknown): SubagentResultInfo;
+/**
+ * C1 (CRITICAL fix): the launch-args counterpart of `readResultInfo`'s
+ * caution, used specifically for a genuinely AMBIGUOUS tool-name match
+ * (2+ candidate profiles, none of them the winner — SUBAGENT-REQ-005).
+ * Unlike `readLaunchInfo`'s "first defined field wins" merge (kept as-is,
+ * still used for the unambiguous single-candidate case, where there is
+ * nothing to disagree about), this only keeps a field when every candidate
+ * that reports a value for it reports the SAME value — "agent/mode if they
+ * read identically, else omitted". Two candidates disagreeing (e.g. one
+ * profile reads `mode` from `args.mode`, another from `args.action`, and
+ * they differ) means kankaku genuinely does not know which is right, so
+ * the field is dropped rather than silently picking one. Never reads
+ * anything money- or join-affecting — launch args never carry `usage` or
+ * `taskId` in the first place, only descriptive `agent`/`mode`.
+ */
+export declare function mergeAgreeingLaunchInfo(candidates: readonly SubagentProfile[], args: Record<string, unknown> | undefined): SubagentLaunchInfo;
+/**
+ * C1 (CRITICAL fix): the result-reading counterpart for a genuinely
+ * AMBIGUOUS tool-name match. `readResultInfo`'s own best-effort merge stays
+ * available (and is still exactly right for the UNAMBIGUOUS single-
+ * candidate case), but when 2+ profiles registered the same tool name and
+ * neither could be told apart, nothing MONEY- or JOIN-affecting is ever
+ * taken from any candidate: `usage` (would silently double-bill the day a
+ * package sharing an ambiguous tool name, e.g. "subagent", starts
+ * following pi's documented top-level `usage` convention — see
+ * `PI_REFERENCE_PROFILE`) and `taskId` (a join key) are always stripped.
+ * Purely descriptive fields (`agent`/`status`/`mode`/`cwd`) are kept from
+ * the best-effort merge — they affect neither billing nor task/child
+ * joining, only how a span/record is labelled for a human reading it.
+ * `profile` itself is never part of this shape; the caller already leaves
+ * it `undefined` for an ambiguous match (see `resolveToolProfile`).
+ */
+export declare function safeAmbiguousResultInfo(candidates: readonly SubagentProfile[], result: unknown): SubagentResultInfo;
+/**
+ * Whether any of `markers` is present in `env`: an exact-value marker
+ * requires an exact match, a presence-only marker (`value: undefined`)
+ * matches any non-empty value. Shared by `profileMarkerMatches` (one
+ * profile's own markers) and `config.ts#detectRole` (the full active set,
+ * generalised beyond the single hardcoded `GENTLE_PI_AGENTS_CHILD` check).
+ */
+export declare function matchesAnyMarker(env: NodeJS.ProcessEnv, markers: readonly ChildEnvMarker[]): boolean;
+/** Whether `profile`'s child-env marker(s) are present in `env`. A profile with no markers at all (e.g. `PI_REFERENCE_PROFILE`) never matches, by construction. */
+export declare function profileMarkerMatches(profile: SubagentProfile, env: NodeJS.ProcessEnv): boolean;
+export interface ChildProfileResolution {
+    /** The single profile confirmed by an env marker, or `undefined` when none matched or 2+ matched at once (never guessed). */
+    profile: SubagentProfile | undefined;
+    matchedProfiles: SubagentProfile[];
+}
+/**
+ * SUBAGENT-REQ-005: resolve which profile's child-env marker(s) confirm
+ * THIS process as a subagent of a known kind — the child-side counterpart
+ * of `resolveToolProfile`. Exactly one profile's marker present resolves
+ * unambiguously; none present means this process's role, if any, must come
+ * from ancestry instead (see `config.ts#detectRole`); two or more present
+ * at once (a genuine marker collision, not expected among the built-ins) is
+ * never guessed either — `profile` stays `undefined`, but every match is
+ * still reported so `/kankaku doctor` can surface it.
+ */
+export declare function resolveChildProfile(profiles: readonly SubagentProfile[], env: NodeJS.ProcessEnv): ChildProfileResolution;
+/** Every distinct child-env marker declared by any of `profiles`, de-duplicated by `name` (first-declared value wins) — used to generalise `detectRole`'s single hardcoded marker check. */
+export declare function allChildMarkers(profiles: readonly SubagentProfile[]): ChildEnvMarker[];
+/**
+ * C2 (CRITICAL fix): the "always confirms, regardless of interactivity"
+ * tier for `config.ts#detectRole`'s 4th param — every active profile's
+ * markers EXCEPT the single user-configured one (`id === "configured"`,
+ * built from `KANKAKU_SUBAGENT_CHILD_ENV` in `config.ts#loadConfig`). Only
+ * a real subagent runner (gentle-pi, pi-subagents) sets a built-in marker,
+ * so this tier keeps today's unconditional precedence.
+ */
+export declare function builtinChildMarkers(profiles: readonly SubagentProfile[]): ChildEnvMarker[];
+/**
+ * C2 (CRITICAL fix): the "never demotes an interactive session" tier for
+ * `config.ts#detectRole`'s 5th param — the user-configured profile's own
+ * markers only (empty when no `"configured"` profile is active). Kept
+ * separate from `builtinChildMarkers` because kankaku cannot verify an
+ * arbitrary configured environment variable name is genuinely child-only
+ * (see `config.ts#loadConfig`'s denylist and `detectRole`'s doc comment).
+ */
+export declare function configuredChildMarkers(profiles: readonly SubagentProfile[]): ChildEnvMarker[];