@autonav/core 1.5.0 → 1.7.0

package/README.md

@@ -54,9 +54,9 @@ A knowledge pack must contain:
 ## Programmatic use
 
 ```typescript
-import { ClaudeAdapter } from "@autonav/core";
+import { NavigatorAdapter } from "@autonav/core";
 
-const adapter = new ClaudeAdapter();
+const adapter = new NavigatorAdapter();
 const nav = await adapter.loadNavigator("./my-docs");
 const response = await adapter.query(nav, "How do I deploy?");
 

package/dist/adapter/index.d.ts

@@ -1,7 +1,7 @@
 /**
- * Claude SDK Adapter
+ * Navigator Adapter
  *
- * Execution engine that bridges Claude API to Communication Layer protocol
+ * Execution engine that bridges agent harnesses to Communication Layer protocol
  */
-export { ClaudeAdapter, type ClaudeAdapterOptions, type LoadedNavigator, type QueryOptions, } from "./claude-adapter.js";
+export { NavigatorAdapter, type NavigatorAdapterOptions, type LoadedNavigator, type QueryOptions, } from "./navigator-adapter.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/adapter/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapter/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,YAAY,GAClB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapter/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,KAAK,YAAY,GAClB,MAAM,wBAAwB,CAAC"}

package/dist/adapter/index.js

@@ -1,7 +1,7 @@
 /**
- * Claude SDK Adapter
+ * Navigator Adapter
  *
- * Execution engine that bridges Claude API to Communication Layer protocol
+ * Execution engine that bridges agent harnesses to Communication Layer protocol
  */
-export { ClaudeAdapter, } from "./claude-adapter.js";
+export { NavigatorAdapter, } from "./navigator-adapter.js";
 //# sourceMappingURL=index.js.map

package/dist/adapter/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapter/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,aAAa,GAId,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapter/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,gBAAgB,GAIjB,MAAM,wBAAwB,CAAC"}

package/dist/adapter/navigator-adapter.d.ts

@@ -0,0 +1,196 @@
+import { NavigatorConfig, NavigatorResponse, type ValidationResult } from "@autonav/communication-layer";
+import { PluginManager } from "../plugins/index.js";
+import { type Harness } from "../harness/index.js";
+/**
+ * Configuration options for Navigator Adapter
+ */
+export interface NavigatorAdapterOptions {
+    /**
+     * Claude model to use (defaults to claude-sonnet-4-5)
+     */
+    model?: string;
+    /**
+     * Maximum turns for agentic loop
+     *
+     * The SDK's agentic loop continues until Claude naturally stops responding,
+     * or until this limit is reached. MCP tools cannot force early termination -
+     * instead, we rely on the system prompt instructing Claude to stop after
+     * calling submit_answer.
+     *
+     * In practice, Claude typically stops within 0-2 turns after calling submit_answer,
+     * often stopping immediately on the same turn. This parameter serves as a safety
+     * limit to prevent runaway execution in edge cases (e.g., if Claude ignores the
+     * stop instruction or enters an unexpected loop).
+     *
+     * @default 50
+     */
+    maxTurns?: number;
+    /**
+     * Pre-created harness instance. If provided, this harness is used directly.
+     * If omitted, defaults to ClaudeCodeHarness.
+     */
+    harness?: Harness;
+}
+/**
+ * Loaded navigator with all necessary context
+ */
+export interface LoadedNavigator {
+    config: NavigatorConfig;
+    systemPrompt: string;
+    navigatorPath: string;
+    knowledgeBasePath: string;
+    pluginManager?: PluginManager;
+    pluginsConfigPath?: string;
+}
+/**
+ * Query options
+ */
+export interface QueryOptions {
+    /**
+     * Enable self-configuration tools (defaults to true)
+     */
+    enableSelfConfig?: boolean;
+    /**
+     * Maximum turns for agentic loop
+     *
+     * The SDK's agentic loop continues until Claude naturally stops responding,
+     * or until this limit is reached. MCP tools cannot force early termination -
+     * instead, we rely on the system prompt instructing Claude to stop after
+     * calling submit_answer.
+     *
+     * In practice, Claude typically stops within 0-2 turns after calling submit_answer,
+     * often stopping immediately on the same turn. This parameter serves as a safety
+     * limit to prevent runaway execution in edge cases (e.g., if Claude ignores the
+     * stop instruction or enters an unexpected loop).
+     *
+     * @default 50
+     */
+    maxTurns?: number;
+}
+/**
+ * Navigator Adapter
+ *
+ * Bridges Claude Agent SDK to the Communication Layer protocol.
+ * Loads navigators, executes queries, and validates responses.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new NavigatorAdapter({
+ *   model: 'claude-sonnet-4-5'
+ * });
+ *
+ * const navigator = adapter.loadNavigator('./my-navigator');
+ * const response = await adapter.query(navigator, 'How do I deploy?');
+ * ```
+ */
+export declare class NavigatorAdapter {
+    private readonly options;
+    private readonly harness;
+    /**
+     * Create a new Navigator Adapter
+     *
+     * @param options - Configuration options
+     */
+    constructor(options?: NavigatorAdapterOptions);
+    /**
+     * Load a navigator from a directory
+     *
+     * Reads and validates config.json and CLAUDE.md (or custom instructions file).
+     * Verifies that the knowledge base directory exists.
+     * If .claude/plugins.json exists, initializes configured plugins.
+     *
+     * @param navigatorPath - Path to the navigator directory
+     * @returns Loaded navigator with config, system prompt, paths, and optional plugin manager
+     * @throws {Error} If directory doesn't exist, config is invalid, or required files are missing
+     *
+     * @example
+     * ```typescript
+     * const adapter = new NavigatorAdapter();
+     * const navigator = await adapter.loadNavigator('./my-navigator');
+     * console.log(`Loaded: ${navigator.config.name}`);
+     * ```
+     */
+    loadNavigator(navigatorPath: string): Promise<LoadedNavigator>;
+    /**
+     * Execute a query using Claude Agent SDK
+     *
+     * Sends the question to Claude with the navigator's system prompt,
+     * handles tool use via the built-in agentic loop, parses the response,
+     * and validates it against the knowledge base.
+     *
+     * @param navigator - Loaded navigator to query
+     * @param question - Question to ask
+     * @param options - Query options (enableSelfConfig, maxTurns)
+     * @returns Validated navigator response with answer and sources
+     * @throws {Error} If API call fails, response parsing fails, or validation fails
+     *
+     * @example
+     * ```typescript
+     * const response = await adapter.query(navigator, 'How do I deploy?');
+     * console.log(response.answer);
+     * console.log(`Confidence: ${response.confidence}`);
+     * console.log(`Sources: ${response.sources.map(s => s.filePath).join(', ')}`);
+     * ```
+     */
+    query(navigator: LoadedNavigator, question: string, options?: QueryOptions): Promise<NavigatorResponse>;
+    /**
+     * Internal method to execute the query
+     * Separated to allow for LangSmith tracing wrapper
+     *
+     * @internal
+     */
+    private executeQuery;
+    /**
+     * Update navigator documentation
+     *
+     * Sends an update message to Claude with write permissions enabled.
+     * Claude can edit files in the knowledge base to document progress,
+     * add troubleshooting steps, or update existing documentation.
+     *
+     * @param navigator - Loaded navigator to update
+     * @param message - Update message or report
+     * @param options - Query options (maxTurns)
+     * @returns Text response from the agent describing what was updated
+     * @throws {Error} If API call fails or update fails
+     *
+     * @example
+     * ```typescript
+     * const result = await adapter.update(
+     *   navigator,
+     *   'I completed feature X. Please document this in the knowledge base.'
+     * );
+     * console.log(result);
+     * ```
+     */
+    update(navigator: LoadedNavigator, message: string, options?: QueryOptions): Promise<string>;
+    /**
+     * Parse Claude's response into a NavigatorResponse
+     *
+     * Extracts JSON from the response text (either from code blocks or raw JSON)
+     * and validates it against the NavigatorResponseSchema.
+     *
+     * @param rawResponse - Raw text response from the agent
+     * @param query - Original query (used to populate missing query field)
+     * @returns Parsed and validated NavigatorResponse
+     * @throws {Error} If JSON cannot be extracted or schema validation fails
+     *
+     * @internal
+     */
+    parseResponse(rawResponse: string, query: string): NavigatorResponse;
+    /**
+     * Validate a NavigatorResponse
+     *
+     * Runs comprehensive validation including:
+     * - Source file existence checks
+     * - Hallucination pattern detection
+     * - Confidence level validation
+     *
+     * @param response - Navigator response to validate
+     * @param knowledgeBasePath - Path to knowledge base directory
+     * @returns Validation result with errors and warnings
+     *
+     * @internal
+     */
+    validate(response: NavigatorResponse, knowledgeBasePath: string): ValidationResult;
+}
+//# sourceMappingURL=navigator-adapter.d.ts.map

package/dist/adapter/navigator-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigator-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/navigator-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,eAAe,EAEf,iBAAiB,EAMjB,KAAK,gBAAgB,EAEtB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAuB,aAAa,EAA0B,MAAM,qBAAqB,CAAC;AAKjG,OAAO,EAAE,KAAK,OAAO,EAAqB,MAAM,qBAAqB,CAAC;AA+CtE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;IAChE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAElC;;;;OAIG;gBACS,OAAO,GAAE,uBAA4B;IAUjD;;;;;;;;;;;;;;;;;OAiBG;IACG,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAmHpE;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,KAAK,CACT,SAAS,EAAE,eAAe,EAC1B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,iBAAiB,CAAC;IAwB7B;;;;;OAKG;YACW,YAAY;IAmQ1B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,MAAM,CACV,SAAS,EAAE,eAAe,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,MAAM,CAAC;IA+ElB;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB;IAoCpE;;;;;;;;;;;;;OAaG;IACH,QAAQ,CACN,QAAQ,EAAE,iBAAiB,EAC3B,iBAAiB,EAAE,MAAM,GACxB,gBAAgB;CAGpB"}