@iworkforces/tracelattice 2.0.3

package/dist/core/ThoughtProcessor.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Core thought processing logic and validation.
+ *
+ * This module provides the `ThoughtProcessor` class which handles the main
+ * sequential thinking request processing pipeline, including input validation,
+ * history management, and response formatting.
+ *
+ * @module processor
+ */
+import type { Logger } from '../logger/StructuredLogger.js';
+import { type SessionId } from '../contracts/ids.js';
+import type { IOutcomeRecorder } from '../contracts/interfaces.js';
+import type { ICalibrator } from '../contracts/calibrator.js';
+import type { ISuspensionStore } from '../contracts/suspension.js';
+import type { IReasoningStrategy } from '../contracts/strategy.js';
+import { type FeatureFlags } from '../contracts/features.js';
+import type { ISessionLock, IToolRegistry } from '../contracts/interfaces.js';
+import type { IHistoryManager } from './IHistoryManager.js';
+import type { ThoughtData } from './thought.js';
+import type { ThoughtEvaluator } from './ThoughtEvaluator.js';
+import type { ThoughtFormatter } from './ThoughtFormatter.js';
+import type { CompressionService } from './compression/CompressionService.js';
+import { SessionLifecycleCoordinator } from './SessionLifecycleCoordinator.js';
+type ThoughtProcessInput = ThoughtData & {
+    readonly register_branch_id?: string;
+};
+/**
+ * The return type expected by MCP tool invocations.
+ *
+ * This structure matches the MCP protocol for tool results,
+ * supporting both success and error responses.
+ *
+ * @example
+ * ```typescript
+ * const successResult: CallToolResult = {
+ *   content: [{ type: 'text', text: '{"status":"success"}' }]
+ * };
+ *
+ * const errorResult: CallToolResult = {
+ *   content: [{ type: 'text', text: '{"error":"Something went wrong"}' }],
+ *   isError: true
+ * };
+ * ```
+ */
+export interface CallToolResult extends Record<string, unknown> {
+    /** Array of content blocks (typically text) to return to the client. */
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    /** Whether this result represents an error condition. */
+    isError?: boolean;
+}
+/**
+ * Core processor for sequential thinking requests.
+ *
+ * Pipeline: validate → normalize → add to history → format → evaluate signals
+ * → run reasoning strategy → return structured response.
+ *
+ * Auto-adjusts `total_thoughts` if `thought_number` exceeds it. All errors are
+ * caught and returned as formatted error responses with `isError: true`.
+ *
+ * @example
+ * ```typescript
+ * const processor = new ThoughtProcessor(historyManager, formatter, new ThoughtEvaluator());
+ * const result = await processor.process({ thought: '...', thought_number: 1, total_thoughts: 5, next_thought_needed: true });
+ * ```
+ */
+export declare class ThoughtProcessor {
+    private historyManager;
+    private thoughtFormatter;
+    private readonly strategy;
+    private readonly _compressionService?;
+    private readonly _suspensionStore?;
+    private readonly _toolRegistry?;
+    private readonly _features;
+    private readonly _sessionLock?;
+    private readonly _outcomeRecorder?;
+    private readonly _lifecycle;
+    private readonly _calibrator?;
+    /** Logger for debugging and monitoring. */
+    private _logger;
+    /** Evaluator for quality signal computation. */
+    private readonly _thoughtEvaluator;
+    /**
+     * Per-session cooldown tracker: session_id → pattern → last_fired_thought_number.
+     * Prevents re-firing the same pattern hint within 3 thoughts.
+     */
+    private _hintCooldowns;
+    /**
+     * Creates a new ThoughtProcessor instance.
+     *
+     * @param historyManager - History manager for storing thoughts
+     * @param thoughtFormatter - Formatter for output formatting
+     * @param thoughtEvaluator - Evaluator for quality signal computation
+     * @param logger - Optional logger for diagnostics (defaults to NullLogger)
+     * @param strategy - Reasoning strategy controlling next-action decisions (defaults to SequentialStrategy)
+     * @param compressionService - Optional compression service for auto-compression on terminate
+     * @param suspensionStore - Optional suspension store enabling tool interleave
+     * @param toolRegistry - Optional tool registry for tool_name allowlist validation (required when toolInterleave is enabled)
+     * @param features - Optional feature flags (defaults to DEFAULT_FLAGS — all opt-in flags off)
+     * @param sessionLock - Optional per-session async lock; when provided, `process()` runs under it
+     * @param outcomeRecorder - Optional per-session calibration outcome store
+     */
+    constructor(historyManager: IHistoryManager, thoughtFormatter: ThoughtFormatter, thoughtEvaluator: ThoughtEvaluator, logger?: Logger, strategy?: IReasoningStrategy, _compressionService?: CompressionService | undefined, _suspensionStore?: ISuspensionStore | undefined, _toolRegistry?: IToolRegistry | undefined, _features?: FeatureFlags, _sessionLock?: ISessionLock | undefined, _outcomeRecorder?: IOutcomeRecorder | undefined, _lifecycle?: SessionLifecycleCoordinator, _calibrator?: ICalibrator | undefined);
+    /**
+     * Internal logging method.
+     * @param message - The message to log
+     * @param meta - Optional metadata
+     * @private
+     */
+    private log;
+    /**
+     * Priority ordering for warning patterns (lower = higher priority).
+     * Ensures the most actionable patterns fill the hint cap first.
+     */
+    private static readonly _HINT_PRIORITY;
+    /**
+     * Generate actionable hints from pattern signals.
+     * Rules: max 3 hints, warning-severity only, cooldown of 3 thoughts per pattern per session.
+     *
+     * Warning patterns are sorted by priority before selection (see _HINT_PRIORITY).
+     * Higher-priority patterns (lower number) fill the hint cap first.
+     *
+     * @param patterns - Detected pattern signals
+     * @param currentThoughtNumber - The current thought number being processed
+     * @param sessionId - Session identifier for cooldown scoping
+     * @returns Array of hint strings (max 3), empty if no warnings
+     */
+    private _generateHints;
+    /**
+     * Processes a thought through the sequential thinking pipeline.
+     *
+     * This method validates the input, adds it to history, formats the output,
+     * computes quality signals via the ThoughtEvaluator, and returns
+     * a structured response with metadata about the current state.
+     *
+     * @param input - The thought data to process
+     * @returns A Promise resolving to the formatted tool result containing:
+     *   - `thought_number` — Current thought index
+     *   - `total_thoughts` — Estimated total thoughts
+     *   - `next_thought_needed` — Whether to continue
+     *   - `branches` — Active branch IDs
+     *   - `thought_history_length` — Number of thoughts in history
+     *   - `available_mcp_tools` — MCP tools available for recommendation
+     *   - `available_skills` — Skills available for recommendation
+     *   - `current_step` — Current step recommendation
+     *   - `previous_steps` — Previously recommended steps
+     *   - `remaining_steps` — Upcoming step descriptions
+     *   - `thought_type` — Classification of thought purpose (optional)
+     *   - `quality_score` — Self-assessed quality score 0-1 (optional)
+     *   - `confidence` — Self-assessed confidence 0-1 (optional)
+     *   - `hypothesis_id` — Hypothesis link for verification chains (optional)
+     *   - `confidence_signals` — Computed reasoning quality signals (includes structural_quality and quality_components)
+     *   - `reasoning_stats` — Aggregated reasoning analytics
+     *   - `reasoning_hints` — (Conditional) Actionable hints from pattern analysis, max 3, warning-severity only (optional)
+     *
+     * @example
+     * ```typescript
+     * const result = await processor.process({
+     *   thought: 'I should read the README file',
+     *   thought_number: 1,
+     *   total_thoughts: 3,
+     *   next_thought_needed: true
+     * });
+     *
+     * console.log(result.content[0].text);
+     * // Output includes: thought_number, total_thoughts, next_thought_needed,
+     * // branches, thought_history_length, and any recommendations
+     * ```
+     */
+    process(input: ThoughtProcessInput): Promise<CallToolResult>;
+    /** Resets one canonical session and its processor-owned auxiliary state. */
+    resetSession(sessionId: string): Promise<void>;
+    /** Resets all history and processor-owned auxiliary state from a trusted context. */
+    resetAll(): Promise<void>;
+    private _prepareInput;
+    private _buildErrorResponse;
+    private static _emptySessionSnapshot;
+    /** Clears all processor-owned state for one removed session. */
+    clearSessionAuxiliaryState(sessionId: SessionId): void;
+    /** Clears all processor-owned state after global reset or successful shutdown. */
+    clearAllAuxiliaryState(): void;
+    private _validateToolArgumentsShape;
+    private _processInner;
+    private _recordVerificationOutcome;
+    private _collectReasoningSignals;
+    private _buildSuccessResponse;
+    /**
+     * Run the configured reasoning strategy and return its decision.
+     * Strategy errors degrade to `{ action: 'continue' }`.
+     * @private
+     */
+    private _runStrategy;
+    /**
+     * Locate the root thought id for a branch.
+     * Prefers GraphView.branchThoughts() when an EdgeStore is available;
+     * falls back to historyManager.getBranches()[branchId][0].id.
+     * @private
+     */
+    private _findBranchRoot;
+    /** Access the EdgeStore via IHistoryManager. @private */
+    private _getEdgeStore;
+    /**
+     * Validates and normalizes thought input.
+     *
+     * Ensures that thought numbers are consistent and within valid ranges.
+     * If `thought_number` exceeds `total_thoughts`, `total_thoughts` is
+     * automatically adjusted to match and a warning is emitted.
+     *
+     * @param input - The input to validate
+     * @returns Object with validated input and any warnings generated
+     * @private
+     *
+     * @example
+     * ```typescript
+     * // Auto-adjusts total_thoughts when thought_number exceeds it
+     * const { result, warnings } = this.validateInput(input);
+     * // result.total_thoughts === 10 (auto-adjusted from 5)
+     * // warnings === ['Auto-adjusted total_thoughts from 5 to 10 to match thought_number']
+     * ```
+     */
+    private validateInput;
+    /**
+     * Validate new thought-type invariants behind feature flags.
+     * @private
+     */
+    private _validateStatelessNewTypes;
+    private _validateNewTypes;
+    /**
+     * Validate a tool_call's tool_name against the configured allowlist.
+     *
+     * Fails closed: if no tool registry was wired, all tool_call invocations are
+     * rejected. This prevents arbitrary tool name injection through the protocol.
+     *
+     * @param toolName - The tool name from the tool_call thought
+     * @throws {UnknownToolError} When no registry is wired or the tool is not registered
+     * @private
+     */
+    private _validateToolName;
+    /**
+     * Returns a workaround thought type for a feature-flagged type.
+     * @private
+     */
+    private static _getWorkaroundType;
+    /**
+     * Persist a tool_call thought and return a `suspended` envelope.
+     * Strategy/evaluator are intentionally skipped.
+     * @private
+     */
+    private _handleToolCall;
+    /**
+     * Resume from a tool_observation and atomically admit it before consuming the record.
+     * @private
+     */
+    private _handleToolObservation;
+}
+export {};
+//# sourceMappingURL=ThoughtProcessor.d.ts.map

package/dist/core/ThoughtProcessor.d.ts.map

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