groundswell 0.0.3 → 1.0.0

package/dist/harnesses/claude-code-harness.d.ts

@@ -0,0 +1,391 @@
+/**
+ * Claude Code harness implementation (PRD §7.1)
+ *
+ * Wraps the @anthropic-ai/claude-agent-sdk to provide Anthropic Claude
+ * model access through the unified Harness interface.
+ *
+ * ## Capabilities
+ *
+ * - **MCP**: Model Context Protocol integration via createSdkMcpServer
+ * - **Skills**: System prompt-based skill loading
+ * - **LSP**: Language Server Protocol via MCP plugins
+ * - **Streaming**: Streaming response support
+ * - **Sessions**: Session-based state via abstraction layer
+ * - **Extended Thinking**: maxThinkingTokens for extended reasoning
+ *
+ * ## SDK Integration
+ *
+ * Uses lazy loading for the Anthropic SDK. The SDK is imported dynamically
+ * in the initialize() method to support optional dependencies.
+ *
+ * @example
+ * ```ts
+ * import { ClaudeCodeHarness } from 'groundswell';
+ *
+ * const harness = new ClaudeCodeHarness();
+ * await harness.initialize({ apiKey: 'sk-...' });
+ *
+ * const result = await harness.execute(
+ *   { prompt: 'Hello, Claude!', options: {} },
+ *   toolExecutor
+ * );
+ * ```
+ *
+ * @see {@link https://docs.anthropic.com/en/api/messages | Anthropic Messages API}
+ * @see {@link https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk | Agent SDK Package}
+ */
+import type { Harness, HarnessId, HarnessCapabilities, HarnessOptions, HarnessRequest, HarnessHookEvents, ToolExecutionRequest, ToolExecutionResult, ModelSpec } from "../types/harnesses.js";
+import type { SessionState } from "../types/providers.js";
+import type { AgentResponse } from "../types/agent.js";
+import type { Tool, MCPServer, Skill } from "../types/sdk-primitives.js";
+import { type SessionStore } from "./session-store.js";
+import type { StreamEvent } from "../types/streaming.js";
+/**
+ * Claude Code harness options (PRD §7.5).
+ * Extends {@link HarnessOptions} with adapter-internal session-store configuration that the
+ * slimmed base contract intentionally omits.
+ */
+export interface ClaudeCodeHarnessOptions extends HarnessOptions {
+    /** Direct session-store injection (mutually exclusive with sessionPersistence). */
+    sessionStore?: SessionStore<SessionState>;
+    /** Declarative store selection; constructs the appropriate SessionStore. */
+    sessionPersistence?: "memory" | "file" | "redis";
+    /** Session TTL in ms (default 86400000 = 24h). */
+    sessionTtl?: number;
+    /** Directory for FileSessionStore (default './sessions'). Only when sessionPersistence='file'. */
+    sessionPath?: string;
+}
+/**
+ * Thrown when a harness receives a configuration it cannot honour — e.g. a model
+ * provider it cannot run (ClaudeCodeHarness + non-anthropic, PRD §7.8). Carries a
+ * machine-readable `code` (default `AGENT_ERROR_CODES.CONFIG_ERROR`) so callers and
+ * Agent retry logic can branch structurally rather than parsing message text.
+ *
+ * @see AGENT_ERROR_CODES
+ */
+export declare class ConfigError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, options?: {
+        code?: string;
+        details?: Record<string, unknown>;
+    });
+}
+export declare class ClaudeCodeHarness implements Harness {
+    /**
+     * Unique harness identifier (PRD §7.2)
+     *
+     * @readonly
+     */
+    readonly id: HarnessId;
+    /**
+     * Provider capability flags
+     *
+     * Anthropic SDK v0.1.77 capabilities:
+     * - MCP via createSdkMcpServer
+     * - Skills via system prompt
+     * - LSP via MCP plugins
+     * - Streaming responses
+     * - No native sessions (stateless)
+     * - Extended thinking via maxThinkingTokens
+     *
+     * @readonly
+     */
+    readonly capabilities: HarnessCapabilities;
+    /**
+     * Check if a specific capability is supported
+     *
+     * @param capability - The capability to check
+     * @returns true if the capability is supported
+     */
+    supports(capability: keyof HarnessCapabilities): boolean;
+    /**
+     * Check if all specified features are supported
+     *
+     * @param features - Array of capability keys to check
+     * @returns true if all features are supported
+     */
+    requiresFeatures(features: (keyof HarnessCapabilities)[]): boolean;
+    /**
+     * Anthropic SDK module (lazy loaded)
+     *
+     * Dynamically imported in initialize() to support optional dependencies.
+     * Typed using typeof import() pattern for accurate module types.
+     *
+     * @internal
+     */
+    private sdk;
+    /**
+     * MCP handler for server registration and tool management
+     *
+     * Manages MCP server connections and converts tools to SDK format.
+     * Created on first use and reused for subsequent registrations.
+     *
+     * @internal
+     */
+    private mcpHandler;
+    /**
+     * SDK MCP server configuration for use in execute()
+     *
+     * Stores the converted SDK server config from registerMCPs().
+     * Used in sdkOptions.mcpServers during execute() calls.
+     *
+     * @internal
+     */
+    private mcpServerConfig;
+    /**
+     * Combined skills prompt for injection into system prompts
+     *
+     * Stores the formatted skills content from loadSkills() for injection
+     * into system prompts during execute() calls. Skills are combined with
+     * markdown headers and separators.
+     *
+     * @internal
+     */
+    private skillsPrompt;
+    /**
+     * Session storage backend
+     *
+     * Manages session state using pluggable storage backends. Defaults to
+     * in-memory storage but can be configured with file-based, Redis, or
+     * custom implementations via ProviderOptions or setSessionStore().
+     *
+     * @internal
+     */
+    private sessionStore;
+    /**
+     * Session TTL in milliseconds from ProviderOptions
+     *
+     * @internal
+     */
+    private sessionTtl?;
+    /**
+     * Initialize the Anthropic provider
+     *
+     * Loads the Anthropic SDK and initializes the client.
+     *
+     * @param options - Optional provider configuration (apiKey, endpoint, sessionPersistence, etc.)
+     * @remarks Session storage defaults to MemorySessionStore if not specified.
+     * Implemented in P2.M1.T1.S2
+     */
+    initialize(options?: ClaudeCodeHarnessOptions): Promise<void>;
+    /**
+     * Terminate the provider and cleanup resources
+     *
+     * Clears the SDK module reference to allow garbage collection.
+     * The Anthropic SDK is stateless and manages its own resources internally.
+     *
+     * @remarks
+     * Implemented in P2.M1.T1.S3
+     */
+    terminate(): Promise<void>;
+    /**
+     * Execute a prompt request
+     *
+     * Constructs the SDK query from ProviderRequest and executes it via the Anthropic SDK.
+     *
+     * When options.streaming is true, returns an AsyncGenerator that yields StreamEvent objects.
+     * When options.streaming is false or undefined, returns a complete AgentResponse.
+     *
+     * @param request - Provider request with prompt and options
+     * @param toolExecutor - Callback for executing tools (used in P2.M1.T1.S6)
+     * @param hooks - Optional lifecycle hooks (adapter in P2.M1.T2.S1)
+     * @returns Typed agent response or AsyncGenerator for streaming
+     * @throws {ConfigError} (code CONFIG_ERROR) if request.options.model resolves to a
+     *   non-anthropic provider (PRD §7.8) — enforced via normalizeModel.
+     * @remarks
+     * P2.M1.T1.S5: Query construction - builds AgentSDKOptions and calls SDK query()
+     * P2.M1.T1.S6: Message iteration - iterates AsyncGenerator and builds AgentResponse
+     * Streaming: Returns AsyncGenerator<StreamEvent> when options.streaming = true
+     */
+    execute<T>(request: HarnessRequest, toolExecutor: (req: ToolExecutionRequest) => Promise<ToolExecutionResult>, hooks?: HarnessHookEvents): Promise<AgentResponse<T>> | AsyncGenerator<StreamEvent, AgentResponse<T>, unknown>;
+    /**
+     * Execute a prompt request with streaming
+     *
+     * Returns an AsyncGenerator that yields StreamEvent objects during execution.
+     * Implements streaming mode for real-time response generation.
+     *
+     * @param request - Provider request with prompt and options
+     * @param toolExecutor - Callback for executing tools
+     * @param hooks - Optional lifecycle hooks
+     * @returns AsyncGenerator yielding StreamEvent objects, returning final AgentResponse
+     * @private
+     * @remarks
+     * Streaming mode implementation following PRP P4.M2.T1.S4 specification.
+     */
+    private executeStreaming;
+    /**
+     * Register MCP servers and return available tools
+     *
+     * Registers MCP servers with the internal MCPHandler and returns
+     * discovered tools in MCP format. Also converts tools to SDK format
+     * and stores the configuration for use in execute().
+     *
+     * @param servers - Array of MCP server configurations (required)
+     * @returns Array of discovered tools in MCP format (serverName__toolName)
+     * @remarks Modifies internal MCP handler state, converts tools to SDK format.
+     * Implemented in P2.M1.T1.S7
+     *
+     * @example
+     * ```ts
+     * const provider = new AnthropicProvider();
+     * await provider.initialize();
+     *
+     * const tools = await provider.registerMCPs([
+     *   {
+     *     name: 'filesystem',
+     *     transport: 'inprocess',
+     *     tools: [
+     *       {
+     *         name: 'read_file',
+     *         description: 'Read a file',
+     *         input_schema: {
+     *           type: 'object',
+     *           properties: { path: { type: 'string' } },
+     *           required: ['path']
+     *         }
+     *       }
+     *     ]
+     *   }
+     * ]);
+     *
+     * console.log(tools); // [{ name: 'filesystem__read_file', ... }]
+     * ```
+     */
+    registerMCPs(servers: MCPServer[]): Promise<Tool[]>;
+    /**
+     * Load skills into the provider
+     *
+     * Skills are read from SKILL.md files in each skill directory and combined
+     * into a formatted system prompt fragment for injection during execute().
+     *
+     * @param skills - Array of skill definitions with name and path (empty array clears existing skills)
+     * @throws {Error} When SDK is not initialized
+     * @throws {Error} When SKILL.md file cannot be read
+     * @remarks Each skill directory must contain a SKILL.md file. Skills are combined
+     * with markdown headers (### Skill Name) and separators (---).
+     *
+     * @example
+     * ```ts
+     * const provider = new AnthropicProvider();
+     * await provider.initialize();
+     * await provider.loadSkills([
+     *   { name: 'math-expert', path: '/skills/math' },
+     *   { name: 'code-reviewer', path: '/skills/code' }
+     * ]);
+     * ```
+     */
+    loadSkills(skills: Skill[]): Promise<void>;
+    /**
+     * Build system prompt with skills injected
+     *
+     * Combines the base system prompt with loaded skills for injection into
+     * the Anthropic SDK's systemPrompt parameter.
+     *
+     * @param baseSystemPrompt - Optional base system prompt to enhance with skills
+     * @returns Enhanced system prompt with skills section, or base prompt unchanged if no skills loaded
+     * @internal
+     * @remarks
+     * Three handling cases:
+     * 1. No skills loaded - returns basePrompt unchanged
+     * 2. No base prompt - returns skills-only prompt with default header
+     * 3. Both exist - combines with "## Available Skills" section
+     */
+    private buildSystemPromptWithSkills;
+    /**
+     * Build Agent SDK hooks from Provider hook events
+     *
+     * Adapts ProviderHookEvents to Anthropic Agent SDK-compatible hook format.
+     * Transforms signatures between Provider and SDK hook formats and handles
+     * async/sync hook execution.
+     *
+     * @param hooks - Optional provider hook events to adapt
+     * @returns SDK-compatible hooks object with HookCallbackMatcher arrays
+     * @internal
+     * @remarks
+     * Hook mapping:
+     * - onToolStart → PreToolUse
+     * - onToolEnd → PostToolUse
+     * - onSessionStart → SessionStart
+     * - onSessionEnd → SessionEnd
+     *
+     * Each adapter returns { continue: true } for SDK compatibility.
+     * Duration values are set to 0 as SDK doesn't provide them in hook input.
+     */
+    private buildAgentSDKHooks;
+    /**
+     * Normalize a model string to a ModelSpec
+     *
+     * Parses model strings in two formats:
+     * - Plain: "claude-sonnet-4" → { provider: 'anthropic', model: 'claude-sonnet-4', raw: 'claude-sonnet-4' }
+     * - Qualified: "anthropic/claude-opus-4" → { provider: 'anthropic', model: 'claude-opus-4', raw: 'anthropic/claude-opus-4' }
+     *
+     * Delegates to {@link parseModelSpec} for parsing and validation.
+     * Validates that the provider is 'anthropic'.
+     *
+     * @param model - Model string to normalize (required)
+     * @returns Parsed ModelSpec with provider='anthropic'
+     * @throws {Error} When model specification is invalid (delegated to parseModelSpec)
+     * @throws {ConfigError} When provider is not 'anthropic' (code === AGENT_ERROR_CODES.CONFIG_ERROR)
+     *
+     * @example
+     * ```ts
+     * const provider = new AnthropicProvider();
+     *
+     * // Plain format
+     * provider.normalizeModel('claude-sonnet-4');
+     * // Returns: { provider: 'anthropic', model: 'claude-sonnet-4', raw: 'claude-sonnet-4' }
+     *
+     * // Qualified format
+     * provider.normalizeModel('anthropic/claude-opus-4');
+     * // Returns: { provider: 'anthropic', model: 'claude-opus-4', raw: 'anthropic/claude-opus-4' }
+     *
+     * // Error: wrong provider
+     * provider.normalizeModel('openai/gpt-4');
+     * // Throws: "Cannot normalize openai/gpt-4 with ClaudeCodeHarness..."
+     * ```
+     */
+    normalizeModel(model: string): ModelSpec;
+    /**
+     * Create a new session with the specified ID
+     *
+     * Initializes empty session state for the given session ID.
+     * If session already exists, this is a no-op (idempotent).
+     *
+     * @param sessionId - Unique identifier for the session (required)
+     * @throws {Error} If SDK is not initialized
+     * @remarks Idempotent: if session exists, this is a no-op.
+     * Session will be used when execute() receives matching sessionId in options.
+     */
+    createSession(sessionId: string): Promise<void>;
+    /**
+     * Get session state for the specified ID
+     *
+     * Retrieves the current session state including conversation history
+     * and last result. Returns undefined if session doesn't exist.
+     *
+     * @param sessionId - Session identifier to retrieve (required)
+     * @returns Session state or undefined if not found
+     * @remarks Updates lastAccessedAt timestamp and saves back to persistent stores.
+     */
+    getSession(sessionId: string): Promise<SessionState | undefined>;
+    /**
+     * Delete a session
+     *
+     * Removes the session from storage. If the session doesn't exist,
+     * returns false.
+     *
+     * @param sessionId - Session identifier to delete (required)
+     * @returns true if deleted, false if not found
+     * @throws {Error} If SDK is not initialized
+     * @remarks Destructive operation: deleted sessions cannot be recovered
+     * unless the store has backup/retention policies.
+     */
+    deleteSession(sessionId: string): Promise<boolean>;
+}
+/**
+ * @deprecated Since v1.2. Use {@link ClaudeCodeHarness}. Renamed as part of the
+ * Harness/Provider split (PRD §7). Identity preserved for backward compatibility.
+ */
+export declare const AnthropicProvider: typeof ClaudeCodeHarness;
+//# sourceMappingURL=claude-code-harness.d.ts.map

package/dist/harnesses/claude-code-harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-code-harness.d.ts","sourceRoot":"","sources":["../../src/harnesses/claude-code-harness.ts"],"names":[],"mappings":"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"}