@jopqior/pi-subagents 1.0.0

package/dist/public.d.ts

@@ -0,0 +1,331 @@
+import { Model, Api } from '@earendil-works/pi-ai';
+
+/**
+ * thinking-level.ts — The thinking-level vocabulary both spawn doors validate against.
+ *
+ * Pi accepts `off` alongside pi-ai's `ThinkingLevel`, but does not export the
+ * combined list: `THINKING_LEVEL_OPTIONS` lives in `@earendil-works/pi-coding-agent`'s
+ * internals and is absent from its public entry, so this package carries its own.
+ *
+ * An unrecognized level is not ignored by the SDK — `clampThinkingLevel` misses it in
+ * the ordered table and falls to the first supported level, which is always `off`. A
+ * typo therefore disables thinking entirely, which is why both doors reject rather
+ * than pass the value through (Refs #834).
+ */
+/**
+ * Every level Pi accepts, in ascending order of effort.
+ *
+ * The `satisfies` clause rejects an entry the installed SDK does not declare, and the
+ * parity tests in `test/config/thinking-level.test.ts` check both directions at runtime.
+ * One drift escapes them: a level the SDK adds *and* gates behind a `thinkingLevelMap`
+ * key, the way `xhigh` and `max` are gated, is invisible until a caller names it.
+ */
+declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+/** A thinking level as an agent file or a spawn caller may spell it. */
+type SubagentThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+/**
+ * types.ts — Type definitions for the subagent system.
+ */
+
+/** Agent type: any string name (built-in defaults or user-defined). */
+type SubagentType = string;
+
+/** usage.ts — Token usage: shapes, accumulator operators, session-stats readers. */
+/**
+ * Lifetime usage components, accumulated via `message_end` events. Survives
+ * compaction (which replaces session.state.messages and would reset any
+ * stats-derived sum). cacheRead is excluded because each turn's cacheRead is
+ * the cumulative cached prefix re-read on that one call — summing across
+ * turns counts the prefix N times. See issue #38.
+ */
+type LifetimeUsage = {
+    input: number;
+    output: number;
+    cacheWrite: number;
+};
+
+/**
+ * subagent-state.ts — SubagentState value object: lifecycle status, metrics, and live activity.
+ *
+ * Owns the passive, readable state of a subagent — status, result, error,
+ * timestamps, stats (toolUses, lifetimeUsage, compactionCount), and live-activity
+ * fields (turnCount, activeTools, responseText) — together with the transition
+ * methods (markRunning, markCompleted, …), accumulation methods
+ * (incrementToolUses, addUsage, incrementCompactions), and live-activity
+ * transition methods (incrementTurnCount, addActiveTool, removeActiveTool,
+ * resetResponseText, appendResponseText) that mutate them.
+ *
+ * State is encapsulated behind getters; external code reads through them but
+ * mutates only via the transition/accumulation methods. The value object owns
+ * all of its own mutations — no field is written from outside.
+ *
+ * Subagent holds one of these privately and delegates its getters and mutation
+ * methods to it. Extracting it lets the lifecycle state machine and the
+ * session-event observer be unit-tested without constructing an executor.
+ */
+
+type SubagentStatus = "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+
+/**
+ * workspace.ts — The single generative extension seam (ADR 0002, Phase 16 Step 2).
+ *
+ * "Where does a child run, and what brackets the run?" is a strategy (git
+ * worktree, container, tmpdir, remote sandbox), not core behavior. The core
+ * needs only a working directory plus a disposal hook; the default — the
+ * parent's cwd, with no setup/teardown — is always correct.
+ *
+ * Unlike the observational lifecycle events in child-lifecycle.ts, this is a
+ * *generative* seam: a registered provider returns a value the core consumes
+ * synchronously at run-start. The core has no knowledge of git or worktrees.
+ */
+
+/** Context the core hands a provider when a child run starts. */
+interface WorkspacePrepareContext {
+    agentId: string;
+    agentType: SubagentType;
+    baseCwd: string;
+}
+/** Outcome the core reports to a workspace when the run ends. */
+interface WorkspaceDisposeOutcome {
+    status: SubagentStatus;
+    description: string;
+}
+/** What dispose may hand back for the core to fold into the child result. */
+interface WorkspaceDisposeResult {
+    /** Appended verbatim to the child's result text — the provider owns the wording. */
+    resultAddendum?: string;
+}
+/** A prepared working directory plus its bracketed teardown. Born complete. */
+interface Workspace {
+    /** The working directory — already exists when the workspace is handed back. */
+    readonly cwd: string;
+    dispose(outcome: WorkspaceDisposeOutcome): WorkspaceDisposeResult | undefined;
+}
+/** The single generative seam: supplies a child's workspace. */
+interface WorkspaceProvider {
+    prepare(ctx: WorkspacePrepareContext): Promise<Workspace | undefined>;
+}
+
+/**
+ * subagent.ts — Subagent class: identity, lifecycle status, and per-subagent behavior.
+ *
+ * Status/stats are delegated to the SubagentState value object; listener
+ * lifecycle to RunListeners; workspace prepare/dispose to WorkspaceBracket.
+ * Behavior (abort, steer buffering) lives here rather than on SubagentManager.
+ */
+
+/**
+ * Why a resume of an agent would be refused.
+ *
+ * One vocabulary for a fact three record-level conditions used to answer
+ * separately: the resume door decided it from `isSessionReady()`,
+ * `sessionReleased`, and `workspaceDisposed`, while the result carriers never
+ * consulted any of them and advertised the resume regardless.
+ *
+ * `still-running` is the one transient member: it is a refusal of *now* rather
+ * than of ever, and the carriers word it accordingly.
+ */
+type ResumeRefusal = "still-running" | "no-session" | "session-released" | "workspace-disposed";
+
+/**
+ * subagent-manager.ts - Tracks subagents, background execution, resume support.
+ *
+ * Background agents are subject to a configurable concurrency limit (default: 4).
+ * Excess agents are scheduled on a ConcurrencyLimiter and auto-started as running
+ * agents complete. Foreground agents bypass the limiter (they block the parent anyway).
+ */
+
+/**
+ * Why a resume was refused, across every front door.
+ *
+ * Widens the record's own vocabulary by the one refusal that is not a fact
+ * about a record: an id no record answers to.
+ */
+type ResumeRefusalReason = ResumeRefusal | "unknown-agent";
+
+/**
+ * service.ts — Public API surface for cross-extension access to subagents.
+ *
+ * Consumers declare this package as an optional peer dependency and use
+ * dynamic import to access the accessor functions:
+ *
+ *   const { getSubagentsService } = await import("@jopqior/pi-subagents");
+ *   const svc = getSubagentsService();
+ *   svc?.spawn("Explore", "Check for stale TODOs");
+ */
+
+/**
+ * Serializable by-value snapshot of an agent's state.
+ *
+ * Produced by this package and read by consumers — not a contract third
+ * parties implement, so a new field is a minor release. What earns a field a
+ * place here (and what the snapshot deliberately withholds) is decided in
+ * `docs/decisions/0005-subagent-record-admission-policy.md`.
+ */
+interface SubagentRecord {
+    id: string;
+    type: string;
+    description: string;
+    status: SubagentStatus;
+    /** Scheduling and announcement mode, resolved once at the manager choke point. */
+    isBackground: boolean;
+    result?: string;
+    /** The question the agent ended its turn with, when it declared one. */
+    pendingQuestion?: string;
+    error?: string;
+    toolUses: number;
+    /** Turns consumed so far; starts at 1. */
+    turnCount: number;
+    /** Turn ceiling for this run, when one was set. */
+    maxTurns?: number;
+    startedAt: number;
+    completedAt?: number;
+    lifetimeUsage: LifetimeUsage;
+    compactionCount: number;
+    /** Path to the agent's session JSONL, once the session exists. */
+    outputFile?: string;
+}
+/** Options for resuming an agent via the service. */
+interface ResumeOptions {
+    /**
+     * Declare that the caller will deliver the resumed outcome to the parent,
+     * suppressing the completion nudge for it. Omitted, the resumed outcome is
+     * announced exactly as a background completion is.
+     */
+    claimOutcome?: boolean;
+    /**
+     * Cancels the resumed turn loop. `abort(id)` does not reach it: a resume does
+     * not run under the record's own abort controller.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * What a resume attempt produced.
+ *
+ * A resumed run that *failed* is still `resumed` — the snapshot carries
+ * `status: "error"` and the message. `refused` means no turn loop ran.
+ */
+type ResumeResult = {
+    kind: "resumed";
+    record: SubagentRecord;
+} | {
+    kind: "refused";
+    reason: ResumeRefusalReason;
+};
+/** Options for spawning an agent via the service. */
+interface SpawnOptions {
+    description?: string;
+    model?: string;
+    maxTurns?: number;
+    thinkingLevel?: string;
+    inheritContext?: boolean;
+    foreground?: boolean;
+    bypassQueue?: boolean;
+}
+/** The pair a human selected for one new run — the authority for model and thinking. */
+interface SpawnSelection {
+    readonly model: Model<Api>;
+    /** Mandatory and never `undefined`: `off` through `max`, including `off`. */
+    readonly thinkingLevel: SubagentThinkingLevel;
+}
+/** What a provider is asked, for one admitted new run about to create a child session. */
+interface SpawnSelectionRequest {
+    /** Identifies the request in the root UI. */
+    readonly agentId: string;
+    readonly agentType: string;
+    readonly description: string;
+    /** The authenticated available models of the session whose manager is spawning — the actual choices. */
+    readonly availableModels: readonly Model<Api>[];
+}
+/**
+ * Asks for the model and thinking level a new run should use.
+ *
+ * Resolves with the selected pair, or `undefined` for user cancellation —
+ * never an approval that silently keeps inherited values. Infrastructure
+ * failures (no UI, unavailable catalogue) reject rather than resolve.
+ */
+interface SpawnSelectionProvider {
+    select(request: SpawnSelectionRequest, signal: AbortSignal): Promise<SpawnSelection | undefined>;
+}
+/**
+ * The outcome of registering a selection provider.
+ *
+ * `owned` — this session is the root of its subagent tree and now holds the
+ * lease; `dispose()` revokes it (idempotent) and a new session is required to
+ * register again.
+ *
+ * `inherited` — this session is a descendant: the supplied provider is NOT
+ * installed and the root's ownership is untouched (including when the
+ * inherited lease is already closed); `dispose()` is a no-op.
+ */
+type SpawnSelectionRegistration = {
+    readonly kind: "owned";
+    dispose(): void;
+} | {
+    readonly kind: "inherited";
+    dispose(): void;
+};
+/** The public service contract for cross-extension subagent access. */
+interface SubagentsService {
+    /** Spawn an agent. Returns the agent ID immediately. */
+    spawn(type: string, prompt: string, options?: SpawnOptions): string;
+    /** Get a snapshot of an agent's current state. */
+    getRecord(id: string): SubagentRecord | undefined;
+    /** List all tracked agents, most recent first. */
+    listAgents(): SubagentRecord[];
+    /** Abort a running or queued agent. Returns false if not found. */
+    abort(id: string): boolean;
+    /** Send a steering message to a running agent. */
+    steer(id: string, message: string): Promise<boolean>;
+    /**
+     * Resume a settled agent with a new prompt, continuing its session.
+     *
+     * Resolves when the resumed run reaches a terminal state, carrying the
+     * terminal snapshot — a caller that does not need the outcome can ignore the
+     * promise. A refusal resolves promptly instead: the checks are synchronous
+     * and no turn loop is started.
+     */
+    resume(id: string, prompt: string, options?: ResumeOptions): Promise<ResumeResult>;
+    /** Wait for all running and queued agents to complete. */
+    waitForAll(): Promise<void>;
+    /** Whether any agents are running or queued. */
+    hasRunning(): boolean;
+    /**
+     * Register the single workspace provider that supplies a child's working
+     * directory plus bracketed setup/teardown. Throws if one is already
+     * registered. Returns a disposer that unregisters the provider.
+     */
+    registerWorkspaceProvider(provider: WorkspaceProvider): () => void;
+    /**
+     * Register the per-spawn selection provider this session's subagent tree
+     * will consult before creating any new child session.
+     *
+     * On the tree's root session: installs the provider (throws if one is
+     * already registered, or once this session's scope is closed) and returns an
+     * `owned` registration whose disposer revokes it. On a descendant session:
+     * installs nothing and returns `inherited` — the root's chooser serves the
+     * whole tree.
+     */
+    registerSpawnSelectionProvider(provider: SpawnSelectionProvider): SpawnSelectionRegistration;
+}
+/** Event channel constants for pi.events subscriptions. */
+declare const SUBAGENT_EVENTS: {
+    readonly STARTED: "subagents:started";
+    readonly COMPLETED: "subagents:completed";
+    readonly FAILED: "subagents:failed";
+    readonly RESUMING: "subagents:resuming";
+    readonly RESUMED: "subagents:resumed";
+    readonly COMPACTED: "subagents:compacted";
+    readonly CREATED: "subagents:created";
+    readonly STEERED: "subagents:steered";
+};
+/** Publish the SubagentsService on globalThis for cross-extension access. */
+declare function publishSubagentsService(service: SubagentsService): void;
+/** Retrieve the published SubagentsService, or undefined if not yet published. */
+declare function getSubagentsService(): SubagentsService | undefined;
+/** Remove the SubagentsService from globalThis (call on shutdown/reload). */
+declare function unpublishSubagentsService(): void;
+
+export { SUBAGENT_EVENTS, getSubagentsService, publishSubagentsService, unpublishSubagentsService };
+export type { LifetimeUsage, ResumeOptions, ResumeRefusal, ResumeRefusalReason, ResumeResult, SpawnOptions, SpawnSelection, SpawnSelectionProvider, SpawnSelectionRegistration, SpawnSelectionRequest, SubagentRecord, SubagentStatus, SubagentsService, Workspace, WorkspaceDisposeOutcome, WorkspaceDisposeResult, WorkspacePrepareContext, WorkspaceProvider };

package/dist/settings.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Generic layered settings loader for `@gotgenes/pi-*` extensions.
+ *
+ * Extensions that store configuration in JSON files under a global agent
+ * directory and a per-project `.pi/` folder share the same three-step idiom:
+ *
+ *   1. Read the global file (`<agentDir>/<filename>`).
+ *   2. Read the project file (`<cwd>/.pi/<filename>`).
+ *   3. Merge them — project wins on conflicts — and return the result.
+ *
+ * Both layers are optional: a missing file is silent (`{}`), and a file that
+ * cannot be parsed warns to stderr and is treated as absent so startup
+ * proceeds normally.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { loadLayeredSettings, type LayeredSettingsSource } from "@jopqior/pi-subagents/settings";
+ *
+ * interface MyConfig { enabled?: boolean; limit?: number }
+ *
+ * function sanitize(raw: unknown): Partial<MyConfig> {
+ *   if (!raw || typeof raw !== "object") return {};
+ *   const r = raw as Record<string, unknown>;
+ *   const out: Partial<MyConfig> = {};
+ *   if (typeof r.enabled === "boolean") out.enabled = r.enabled;
+ *   if (typeof r.limit === "number") out.limit = r.limit;
+ *   return out;
+ * }
+ *
+ * const config = loadLayeredSettings<MyConfig>({
+ *   agentDir,     // e.g. from the Pi runtime env — the agent home directory
+ *   cwd,          // project root — project file is at <cwd>/.pi/<filename>
+ *   filename: "my-extension.json",
+ *   sanitize,
+ *   warnLabel: "my-extension",
+ * });
+ * ```
+ *
+ * @public
+ */
+/**
+ * Parameters for one layered settings load: describes where the files live,
+ * how to validate their contents, and what label to use in warnings.
+ *
+ * @public
+ */
+interface LayeredSettingsSource<T> {
+    /** Directory holding the global settings file (typically the Pi agent dir). */
+    agentDir: string;
+    /** Project root; the project file lives at `<cwd>/.pi/<filename>`. */
+    cwd: string;
+    /** Base filename for both layers, e.g. `"subagents.json"`. */
+    filename: string;
+    /**
+     * Validate and coerce parsed JSON into a partial settings object.
+     * Unknown or invalid fields should be silently dropped — return `{}` for
+     * unrecognised shapes. Never throw.
+     */
+    sanitize: (raw: unknown) => Partial<T>;
+    /**
+     * Short label used in the malformed-file warning prefix,
+     * e.g. `"pi-subagents"` → `"[pi-subagents] Ignoring malformed settings at …"`.
+     */
+    warnLabel: string;
+}
+/**
+ * Load merged layered settings: global provides defaults, project overrides.
+ *
+ * - A missing file is silent — returns `{}` for that layer.
+ * - A file that exists but cannot be parsed warns to stderr and returns `{}` for
+ *   that layer, so startup proceeds normally.
+ * - The two layers are merged with a shallow spread; project keys win.
+ *
+ * Throws nothing. All error conditions produce a warning and fall back to `{}`.
+ *
+ * @public
+ */
+declare function loadLayeredSettings<T>(source: LayeredSettingsSource<T>): Partial<T>;
+
+export { loadLayeredSettings };
+export type { LayeredSettingsSource };