groundswell 0.0.2 → 1.0.0

package/dist/harnesses/pi-harness.d.ts

@@ -0,0 +1,219 @@
+import type { Harness, HarnessId, HarnessCapabilities, HarnessOptions, HarnessRequest, HarnessHookEvents, ToolExecutionRequest, ToolExecutionResult, ModelSpec } from "../types/harnesses.js";
+import type { Tool, MCPServer, Skill } from "../types/sdk-primitives.js";
+import type { AgentResponse } from "../types/agent.js";
+import type { StreamEvent } from "../types/streaming.js";
+import { ModelRegistry } from "@earendil-works/pi-coding-agent";
+/**
+ * The Pi `Model<Api>` element type, derived from the re-exported ModelRegistry so
+ * NO import from the non-hoisted `@earendil-works/pi-ai` is needed (Decision 4).
+ * Structurally identical to Model<Api>; assignable to Model<any> for createAgentSession.
+ */
+type PiModel = NonNullable<ReturnType<ModelRegistry["find"]>>;
+/**
+ * Pi harness implementation (PRD §7.1).
+ *
+ * Wraps `@earendil-works/pi-coding-agent` (the vendor-neutral default runtime). This file is the
+ * S2 implementation: it wires the SDK via lazy import in `initialize()`, builds a headless
+ * `ModelRegistry`, and provides `resolveModel()` to map `ModelSpec` → Pi `Model<Api>`.
+ * Tools/streaming/hooks/skills land in P2.M3/P2.M4.
+ *
+ * ## Capabilities (PRD §7.4 `pi` column — ALL supported)
+ * - **MCP**: via Groundswell `MCPHandler` (tools registered with the harness)
+ * - **Skills**: native agentskills.io
+ * - **LSP**: via MCP plugins through `MCPHandler`
+ * - **Streaming**: `session.subscribe` (`MessageUpdateEvent`)
+ * - **Sessions**: `SessionManager` (fork/switch/clone)
+ * - **Extended Thinking**: model-dependent
+ *
+ * Pi is vendor-neutral: it runs ANY LLM provider (PRD §7.4/§7.8), so `normalizeModel` applies NO
+ * provider constraint (unlike `ClaudeCodeHarness`).
+ *
+ * @example
+ * ```ts
+ * import { PiHarness } from './harnesses/pi-harness.js';
+ * const harness = new PiHarness();
+ * await harness.initialize({ apiKey: 'sk-...' });
+ * const spec = harness.normalizeModel('anthropic/claude-sonnet-4');
+ * const model = harness.resolveModel(spec); // Model<Api>
+ * ```
+ */
+export declare class PiHarness implements Harness {
+    /** Harness identifier (PRD §7.2). */
+    readonly id: HarnessId;
+    /** Capability flags — PRD §7.4 `pi` column (all true; vendor-neutral runtime). */
+    readonly capabilities: HarnessCapabilities;
+    /** Lazily-imported Pi SDK module (mirrors ClaudeCodeHarness.sdk). Null until initialize(). */
+    private sdk;
+    /** Headless auth store (env/runtime API-key resolution). Null until initialize(). */
+    private authStorage;
+    /** Model registry (built-in + custom models; per-provider auth). Null until initialize(). */
+    private modelRegistry;
+    /** Caller-supplied options (apiKey forwarded per-provider at resolveModel time). */
+    private options;
+    /** MCP tool registry — mirrors ClaudeCodeHarness L177. */
+    private mcpHandler;
+    /**
+     * Combined skills prompt (agentskills.io XML) from loadSkills(), injected into the session's system
+     * prompt during execute() via a DefaultResourceLoader.appendSystemPrompt (parity with
+     * ClaudeCodeHarness.skillsPrompt). Empty string when no skills are loaded (loadSkills not called, or
+     * called with []). When empty, execute() omits the resourceLoader → Pi builds its own default loader
+     * (current behavior preserved — no regression).
+     * @internal
+     */
+    private skillsPrompt;
+    /**
+     * Initialize the Pi harness (PRD §7.3).
+     *
+     * Lazily `await import`s the Pi SDK, builds a headless `ModelRegistry.inMemory(...)`, and stores
+     * the caller's options. Does NOT call `createAgentSession` — that is T2 (P2.M2.T2.S1), which
+     * consumes `this.sdk`, `this.modelRegistry`, and `this.resolveModel(spec)`.
+     *
+     * Idempotent: a no-op if already initialized. API keys are resolved per-provider at
+     * `resolveModel` time (the provider is unknown until a model string is parsed — GOTCHA #8).
+     */
+    initialize(options?: HarnessOptions): Promise<void>;
+    /**
+     * Terminate the harness and release references (PRD §7.3).
+     *
+     * Idempotent. Nulls sdk/authStorage/modelRegistry/options to allow GC. The Pi SDK manages its
+     * own resources internally; no session exists at this layer (createAgentSession is T2).
+     */
+    terminate(): Promise<void>;
+    /**
+     * Resolve a parsed {@link ModelSpec} to a Pi `Model<Api>` via the registry (PRD §7.8).
+     *
+     * Uses `modelRegistry.find(provider, model)` — the open-set, registry/auth-aware seam (NOT
+     * `getModel`, which is generic-constrained to known providers/models and not importable —
+     * research/model-resolution-path.md). T2 passes the result to `createAgentSession({ model })`.
+     *
+     * @throws {Error} if initialize() has not been called.
+     * @throws {ConfigError} (code CONFIG_ERROR) if the model is not in the registry.
+     */
+    resolveModel(spec: ModelSpec): PiModel;
+    /**
+     * Execute a prompt and return a structured AgentResponse (PRD §7.3, §7.11, §7.14.4).
+     *
+     * Creates a Pi AgentSession via createAgentSession, drives one prompt through session.prompt(),
+     * aggregates the terminal assistant text + token usage + tool-call count from the event stream
+     * (session.subscribe), fires session lifecycle hooks, and returns an AgentResponse<T>.
+     *
+     * Non-streaming path (P2.M2.T2.S1): returns Promise<AgentResponse<T>>.
+     * Streaming path: delegates to executeStreaming() (P2.M3.T2.S1) — returns AsyncGenerator<StreamEvent, AgentResponse<T>>.
+     * Tool delegation: customTools wired via buildCustomTools (P2.M3.T1).
+     * All hooks fire: session hooks inline (S1/P2.M2.T2.S1); tool/stream hooks via fireHookEvents() (P2.M3.T2.S2).
+     */
+    execute<T>(request: HarnessRequest, toolExecutor: (req: ToolExecutionRequest) => Promise<ToolExecutionResult>, hooks?: HarnessHookEvents): Promise<AgentResponse<T>> | AsyncGenerator<StreamEvent, AgentResponse<T>, unknown>;
+    /**
+     * Stream a Pi turn as `StreamEvent`s (PRD §7.3, §7.4, §7.14.4).
+     *
+     * Pi's `session.subscribe(listener)` is SYNCHRONOUS — a listener cannot `yield`. This method
+     * bridges sync callbacks → async generator via an internal queue: the listener `enqueue`s events
+     * (and resolves a parked drain), the generator `dequeue`s/maps/`yield`s. `session.prompt()` runs
+     * detached; its resolution flips the terminal condition.
+     *
+     * Mapping (PRD §7.11): message_update→text_delta (snapshot-diff), tool_execution_start→tool_call_start,
+     * tool_execution_end→tool_call_done, turn_end→usage, terminal→done, errors→error.
+     *
+     * Hooks (Decision 5): session lifecycle hooks (onSessionStart/onSessionEnd) fire for parity with
+     * the non-streaming path. onToolStart/onToolEnd/onStream are P2.M3.T2.S2 (NOT wired here).
+     */
+    private executeStreaming;
+    /**
+     * Dispatch the three harness hooks owned by P2.M3.T2.S2 (PRD §7.11):
+     *   tool_execution_start → onToolStart({name, input})
+     *   tool_execution_end   → onToolEnd({name, input}, {content, isError}, duration)
+     *   message_update       → onStream(delta)   [snapshot-diff; assistant text only]
+     *
+     * Session hooks (onSessionStart/onSessionEnd) are NOT handled here — they stay inline in the
+     * listeners as S1/P2.M2.T2.S1 wrote them (no scope overlap, no merge conflict).
+     *
+     * Pi fidelity advantage over claude-code (item note): onToolEnd observes the REAL isError
+     * (ToolExecutionEndEvent.isError) and a REAL duration (computed from the stashed start timestamp);
+     * claude-code's PostToolUse cannot (always isError:false, duration:0).
+     *
+     * Hooks are FIRE-AND-TRACK (`void`): the Pi listener runs SYNCHRONOUSLY during session.prompt()
+     * and cannot `await` a hook Promise (would block/reorder the SDK event loop). Matches the existing
+     * `void hooks?.onSessionStart?.()` pattern. Tests use sync vi.fn() hooks for deterministic assertions.
+     *
+     * @param event  Pi session event (structurally cast — transitive types are non-importable).
+     * @param hooks  Optional HarnessHookEvents. Early-returns on `!hooks` (cheap no-op).
+     * @param ctx    Mutable accumulators (toolStarts for duration/input reconstruction; streamText for onStream).
+     */
+    private fireHookEvents;
+    registerMCPs(servers: MCPServer[]): Promise<Tool[]>;
+    /**
+     * Build Pi `ToolDefinition[]` from the registered MCPHandler tools (PRD §7.10, §7.12, §7.14.1).
+     *
+     * Delegates to `MCPHandler.toPiCustomTools()` (P2.M4.T1.S2) which produces schema-faithful
+     * ToolDefinitions with REAL TypeBox `parameters` (converted via `jsonSchemaToTypebox`) and
+     * `execute` delegating to `registered.executor` (Claude parity).
+     *
+     * When `toolExecutor` is provided (PRD §7.10 bridge), forwards it to `toPiCustomTools` so
+     * each tool's `execute` dispatches through the caller-supplied executor instead of the
+     * harness's internal `registered.executor`.
+     */
+    private buildCustomTools;
+    /**
+     * Load skills via Pi's NATIVE agentskills.io implementation (PRD §7.12, §7.14.2).
+     *
+     * For each Groundswell {@link Skill} ({name, path}), calls Pi's `loadSkillsFromDir({dir: path,
+     * source: name})` (which reads SKILL.md from the dir), collects all returned Pi Skills, then formats
+     * them to agentskills.io XML via `formatSkillsForPrompt` and stores the result in {@link skillsPrompt}.
+     *
+     * ## No session re-init required
+     * PiHarness creates a FRESH AgentSession per execute()/executeStreaming() call (P2.M2.T2.S1 /
+     * P2.M3.T2.S1), so this stored skillsPrompt is consumed on the NEXT execute() when
+     * buildSkillsResourceLoader() builds the DefaultResourceLoader. This mirrors how registerMCPs()
+     * state is consumed when execute() builds customTools. (A long-lived-session model would need an
+     * explicit rebuild; not the case here.)
+     *
+     * ## Parity with ClaudeCodeHarness
+     * ClaudeCodeHarness reads each SKILL.md and joins with markdown; PiHarness uses Pi's native loaders
+     * and emits the agentskills.io XML format. Both store the result in a `skillsPrompt` field and inject
+     * at BOTH execute sites. EFFECT is identical: the skill's SKILL.md content reaches the model's system
+     * prompt.
+     *
+     * @param skills - Groundswell portable Skill list ({name, path}). path = dir containing SKILL.md.
+     * @throws {Error} /not initialized/i if initialize() has not been called.
+     * @throws {Error} "Failed to load skill '<name>' from <path>: <msg>" if loadSkillsFromDir throws.
+     */
+    loadSkills(skills: Skill[]): Promise<void>;
+    /**
+     * Build a DefaultResourceLoader that appends the loaded skills ({@link skillsPrompt}) to the
+     * session's system prompt (PRD §7.12, §7.14.2).
+     *
+     * Returns `undefined` when no skills are loaded (`skillsPrompt === ""`), so execute() OMITS the
+     * `resourceLoader` option and Pi builds its own default loader — current behavior is preserved
+     * (zero regression in the execute/streaming suites).
+     *
+     * ## Parity: noSkills: true
+     * Suppresses Pi's DEFAULT skill discovery (~/.pi/agent/skills, cwd-local) so the session's skills are
+     * EXACTLY Groundswell's portable Skill[] (parity with ClaudeCodeHarness, which builds its prompt only
+     * from the passed skills). `appendSystemPrompt` is INDEPENDENT of `noSkills`, so our pre-formatted
+     * agentskills.io XML is still appended to the system prompt.
+     *
+     * createAgentSession uses a caller-provided loader AS-IS (no reload), so we `await loader.reload()`.
+     *
+     * @returns A configured DefaultResourceLoader, or undefined when no skills are loaded.
+     * @throws {Error} /not initialized/i if called before initialize() (defensive — execute() guards too).
+     */
+    private buildSkillsResourceLoader;
+    /**
+     * Parse a model string into a ModelSpec (PRD §7.8).
+     *
+     * Pi is vendor-neutral — ANY provider is valid (PRD §7.4 "LLM providers: any"). Unlike
+     * `ClaudeCodeHarness`, there is NO anthropic-only constraint here. Delegates to `parseModelSpec`
+     * (open `ModelProviderId` set; rejects harness-qualified 3-segment strings per PRD §7.8).
+     *
+     * Threads the global `defaultModelProvider` when configured (backward-compatible — when unset,
+     * `defaultModelProvider` is `undefined`, so `parseModelSpec` defaults to `'anthropic'` exactly
+     * as S1 does).
+     *
+     * This is the string→ModelSpec layer. `resolveModel()` owns the ModelSpec→Pi `Model<Api>` step.
+     */
+    normalizeModel(model: string): ModelSpec;
+    supports(capability: keyof HarnessCapabilities): boolean;
+    requiresFeatures(features: (keyof HarnessCapabilities)[]): boolean;
+}
+export {};
+//# sourceMappingURL=pi-harness.d.ts.map

package/dist/harnesses/pi-harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-harness.d.ts","sourceRoot":"","sources":["../../src/harnesses/pi-harness.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EACT,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,SAAS,EACV,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAYzD,OAAO,EAAE,aAAa,EAAe,MAAM,iCAAiC,CAAC;AAE7E;;;;GAIG;AACH,KAAK,OAAO,GAAG,WAAW,CAAC,UAAU,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAa9D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,SAAU,YAAW,OAAO;IACvC,qCAAqC;IACrC,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAQ;IAE9B,kFAAkF;IAClF,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAOV;IAGhC,8FAA8F;IAC9F,OAAO,CAAC,GAAG,CAAiE;IAC5E,qFAAqF;IACrF,OAAO,CAAC,WAAW,CAA4B;IAC/C,6FAA6F;IAC7F,OAAO,CAAC,aAAa,CAA8B;IACnD,oFAAoF;IACpF,OAAO,CAAC,OAAO,CAA+B;IAC9C,0DAA0D;IAC1D,OAAO,CAAC,UAAU,CAAgC;IAClD;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY,CAAc;IAGlC;;;;;;;;;OASG;IACG,UAAU,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BzD;;;;;OAKG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAUhC;;;;;;;;;OASG;IACH,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO;IAuBtC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,CAAC,EACP,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,CAAC,GAAG,EAAE,oBAAoB,KAAK,OAAO,CAAC,mBAAmB,CAAC,EACzE,KAAK,CAAC,EAAE,iBAAiB,GACxB,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC;IAwHrF;;;;;;;;;;;;;OAaG;YACY,gBAAgB;IAgN/B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,cAAc;IAmEhB,YAAY,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAUzD;;;;;;;;;;OAUG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAkChD;;;;;;;;;;;;;;;;;;OAkBG;YACW,yBAAyB;IA6BvC;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS;IAKxC,QAAQ,CAAC,UAAU,EAAE,MAAM,mBAAmB,GAAG,OAAO;IAIxD,gBAAgB,CAAC,QAAQ,EAAE,CAAC,MAAM,mBAAmB,CAAC,EAAE,GAAG,OAAO;CAGnE"}