@kadi.build/core 0.0.1-alpha.10 → 0.0.1-alpha.12

package/dist/utils/LockfileResolver.js

@@ -0,0 +1,230 @@
+/**
+ * Lockfile Resolver
+ *
+ * Utilities for resolving ability paths from agent-lock.json
+ * Integrates kadi-core with kadi-install's global cache architecture
+ *
+ * @module utils/LockfileResolver
+ */
+import fs from 'fs';
+import path from 'path';
+import { KadiError, ErrorCode } from '../errors/index.js';
+/**
+ * Find project root by looking for agent.json
+ *
+ * Walks up directory tree from cwd until finding agent.json
+ *
+ * @param startDir - Directory to start search from (defaults to cwd)
+ * @returns Absolute path to project root
+ * @throws {KadiError} If no project root found
+ */
+export function findProjectRoot(startDir = process.cwd()) {
+    let current = path.resolve(startDir);
+    const root = path.parse(current).root;
+    while (current !== root) {
+        const agentJsonPath = path.join(current, 'agent.json');
+        if (fs.existsSync(agentJsonPath)) {
+            return current;
+        }
+        // Move up one directory
+        current = path.dirname(current);
+    }
+    throw new KadiError('No KADI project found - could not locate agent.json', ErrorCode.INVALID_CONFIG, 404, {
+        searchedFrom: startDir,
+        reason: 'No agent.json found in current directory or parent directories',
+        suggestion: 'Make sure you are running from within a KADI project',
+        alternatives: [
+            'Run from a directory containing agent.json',
+            'Initialize a new KADI project: kadi init',
+            'Provide explicit path when loading ability'
+        ]
+    });
+}
+/**
+ * Read agent-lock.json from project root
+ *
+ * @param projectRoot - Project root directory
+ * @returns Parsed lockfile
+ * @throws {KadiError} If lockfile not found or invalid
+ */
+export function readLockfile(projectRoot) {
+    const lockfilePath = path.join(projectRoot, 'agent-lock.json');
+    // Check if lockfile exists
+    if (!fs.existsSync(lockfilePath)) {
+        throw new KadiError('No agent-lock.json found - cannot auto-resolve ability paths', ErrorCode.INVALID_CONFIG, 404, {
+            projectRoot,
+            lockfilePath,
+            reason: 'agent-lock.json not found in project root',
+            suggestion: 'Run `kadi install` to generate lockfile',
+            alternatives: [
+                'Run: kadi install (to install all abilities from agent.json)',
+                'Run: kadi install <ability-name> (to install specific ability)',
+                'Provide explicit path: client.load("ability", "native", { path: "./abilities/..." })'
+            ],
+            hint: 'agent-lock.json is created by running `kadi install`'
+        });
+    }
+    // Read and parse lockfile
+    try {
+        const content = fs.readFileSync(lockfilePath, 'utf-8');
+        const lockfile = JSON.parse(content);
+        // Basic validation
+        if (!lockfile.abilities || typeof lockfile.abilities !== 'object') {
+            throw new Error('Invalid lockfile format: missing or invalid "abilities" field');
+        }
+        return lockfile;
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new KadiError('Invalid agent-lock.json - malformed JSON', ErrorCode.INVALID_CONFIG, 400, {
+                lockfilePath,
+                parseError: error.message,
+                suggestion: 'Delete agent-lock.json and run `kadi install` to regenerate'
+            });
+        }
+        throw new KadiError('Failed to read agent-lock.json', ErrorCode.INTERNAL_ERROR, 500, {
+            lockfilePath,
+            error: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
+/**
+ * Resolve ability path from lockfile
+ *
+ * @param abilityName - Name of ability to resolve
+ * @param projectRoot - Project root directory
+ * @returns Resolved ability entry from lockfile
+ * @throws {KadiError} If ability not found in lockfile or path doesn't exist
+ */
+export function resolveAbilityPath(abilityName, projectRoot) {
+    const lockfile = readLockfile(projectRoot);
+    // Check if ability exists in lockfile
+    const abilityEntry = lockfile.abilities[abilityName];
+    if (!abilityEntry) {
+        // Ability not in lockfile - show helpful error
+        const installedAbilities = Object.keys(lockfile.abilities);
+        throw new KadiError(`Ability '${abilityName}' not found in agent-lock.json`, ErrorCode.ABILITY_NOT_FOUND, 404, {
+            abilityName,
+            projectRoot,
+            installedAbilities,
+            installedCount: installedAbilities.length,
+            reason: `'${abilityName}' is not installed in this project`,
+            suggestion: `Run: kadi install ${abilityName}`,
+            alternatives: [
+                `Install ability: kadi install ${abilityName}`,
+                'View installed abilities in agent-lock.json',
+                'Provide explicit path when loading ability'
+            ],
+            hint: installedAbilities.length === 0
+                ? 'No abilities installed yet. Run `kadi install` to install from agent.json'
+                : `Currently installed: ${installedAbilities.slice(0, 5).join(', ')}${installedAbilities.length > 5 ? '...' : ''}`
+        });
+    }
+    // Resolve path (may be relative to project root)
+    const absolutePath = path.isAbsolute(abilityEntry.resolved)
+        ? abilityEntry.resolved
+        : path.resolve(projectRoot, abilityEntry.resolved);
+    // Verify the resolved path exists
+    if (!fs.existsSync(absolutePath)) {
+        throw new KadiError(`Ability '${abilityName}@${abilityEntry.version}' is in lockfile but directory not found`, ErrorCode.ABILITY_NOT_FOUND, 404, {
+            abilityName,
+            version: abilityEntry.version,
+            expectedPath: absolutePath,
+            reason: 'Directory listed in lockfile does not exist',
+            possibleCauses: [
+                'Ability was manually deleted',
+                'Project was moved without abilities/ folder',
+                'File system error or permissions issue'
+            ],
+            suggestion: `Run: kadi install --force ${abilityName}`,
+            alternatives: [
+                `Reinstall ability: kadi install --force ${abilityName}`,
+                'Check if abilities/ folder exists',
+                'Run `kadi install` to restore all abilities'
+            ]
+        });
+    }
+    // Return entry with absolute path
+    return {
+        ...abilityEntry,
+        resolved: absolutePath
+    };
+}
+/**
+ * Read ability's agent.json manifest
+ *
+ * @param abilityPath - Path to ability directory
+ * @returns Parsed ability manifest
+ * @throws {KadiError} If manifest not found or invalid
+ */
+export function readAbilityManifest(abilityPath) {
+    const manifestPath = path.join(abilityPath, 'agent.json');
+    if (!fs.existsSync(manifestPath)) {
+        throw new KadiError('Ability agent.json not found', ErrorCode.INVALID_CONFIG, 404, {
+            abilityPath,
+            manifestPath,
+            reason: 'agent.json not found in ability directory',
+            suggestion: 'Reinstall the ability: kadi install --force <ability-name>'
+        });
+    }
+    try {
+        const content = fs.readFileSync(manifestPath, 'utf-8');
+        const manifest = JSON.parse(content);
+        // Basic validation
+        if (!manifest.name || !manifest.version) {
+            throw new Error('Invalid manifest: missing name or version');
+        }
+        return manifest;
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new KadiError('Invalid ability agent.json - malformed JSON', ErrorCode.INVALID_CONFIG, 400, {
+                manifestPath,
+                parseError: error.message
+            });
+        }
+        throw new KadiError('Failed to read ability agent.json', ErrorCode.INTERNAL_ERROR, 500, {
+            manifestPath,
+            error: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
+/**
+ * Auto-resolve ability configuration for loading
+ *
+ * Combines lockfile lookup with manifest reading to provide
+ * all information needed to load an ability.
+ *
+ * @param abilityName - Name of ability
+ * @param projectRoot - Project root directory (optional, will search if not provided)
+ * @returns Resolved ability configuration
+ *
+ * @example
+ * ```typescript
+ * const config = resolveAbilityConfig('math-lib');
+ * // Returns:
+ * // {
+ * //   path: '/path/to/project/abilities/math-lib@1.0.0',
+ * //   version: '1.0.0',
+ * //   entry: 'service.js',
+ * //   manifest: { ... }
+ * // }
+ * ```
+ */
+export function resolveAbilityConfig(abilityName, projectRoot) {
+    // Find project root if not provided
+    const root = projectRoot || findProjectRoot();
+    // Resolve ability from lockfile
+    const entry = resolveAbilityPath(abilityName, root);
+    // Read ability manifest
+    const manifest = readAbilityManifest(entry.resolved);
+    // Get entry point (default to 'index.js' if not specified)
+    const entryPoint = manifest.entry || 'index.js';
+    return {
+        path: entry.resolved,
+        version: entry.version,
+        entry: entryPoint,
+        manifest
+    };
+}
+//# sourceMappingURL=LockfileResolver.js.map

package/dist/utils/LockfileResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LockfileResolver.js","sourceRoot":"","sources":["../../src/utils/LockfileResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAyC1D;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,WAAmB,OAAO,CAAC,GAAG,EAAE;IAC9D,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC;IAEtC,OAAO,OAAO,KAAK,IAAI,EAAE,CAAC;QACxB,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAEvD,IAAI,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;YACjC,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,wBAAwB;QACxB,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAED,MAAM,IAAI,SAAS,CACjB,qDAAqD,EACrD,SAAS,CAAC,cAAc,EACxB,GAAG,EACH;QACE,YAAY,EAAE,QAAQ;QACtB,MAAM,EAAE,gEAAgE;QACxE,UAAU,EAAE,sDAAsD;QAClE,YAAY,EAAE;YACZ,4CAA4C;YAC5C,0CAA0C;YAC1C,4CAA4C;SAC7C;KACF,CACF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,WAAmB;IAC9C,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC;IAE/D,2BAA2B;IAC3B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,SAAS,CACjB,8DAA8D,EAC9D,SAAS,CAAC,cAAc,EACxB,GAAG,EACH;YACE,WAAW;YACX,YAAY;YACZ,MAAM,EAAE,2CAA2C;YACnD,UAAU,EAAE,yCAAyC;YACrD,YAAY,EAAE;gBACZ,8DAA8D;gBAC9D,gEAAgE;gBAChE,sFAAsF;aACvF;YACD,IAAI,EAAE,sDAAsD;SAC7D,CACF,CAAC;IACJ,CAAC;IAED,0BAA0B;IAC1B,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAkB,CAAC;QAEtD,mBAAmB;QACnB,IAAI,CAAC,QAAQ,CAAC,SAAS,IAAI,OAAO,QAAQ,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;YAClE,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;QACnF,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;YACjC,MAAM,IAAI,SAAS,CACjB,0CAA0C,EAC1C,SAAS,CAAC,cAAc,EACxB,GAAG,EACH;gBACE,YAAY;gBACZ,UAAU,EAAE,KAAK,CAAC,OAAO;gBACzB,UAAU,EAAE,6DAA6D;aAC1E,CACF,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,SAAS,CACjB,gCAAgC,EAChC,SAAS,CAAC,cAAc,EACxB,GAAG,EACH;YACE,YAAY;YACZ,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CACF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,WAAmB,EACnB,WAAmB;IAEnB,MAAM,QAAQ,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;IAE3C,sCAAsC;IACtC,MAAM,YAAY,GAAG,QAAQ,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAErD,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,+CAA+C;QAC/C,MAAM,kBAAkB,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAE3D,MAAM,IAAI,SAAS,CACjB,YAAY,WAAW,gCAAgC,EACvD,SAAS,CAAC,iBAAiB,EAC3B,GAAG,EACH;YACE,WAAW;YACX,WAAW;YACX,kBAAkB;YAClB,cAAc,EAAE,kBAAkB,CAAC,MAAM;YACzC,MAAM,EAAE,IAAI,WAAW,oCAAoC;YAC3D,UAAU,EAAE,qBAAqB,WAAW,EAAE;YAC9C,YAAY,EAAE;gBACZ,iCAAiC,WAAW,EAAE;gBAC9C,6CAA6C;gBAC7C,4CAA4C;aAC7C;YACD,IAAI,EAAE,kBAAkB,CAAC,MAAM,KAAK,CAAC;gBACnC,CAAC,CAAC,2EAA2E;gBAC7E,CAAC,CAAC,wBAAwB,kBAAkB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;SACrH,CACF,CAAC;IACJ,CAAC;IAED,iDAAiD;IACjD,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,QAAQ,CAAC;QACzD,CAAC,CAAC,YAAY,CAAC,QAAQ;QACvB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAErD,kCAAkC;IAClC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,SAAS,CACjB,YAAY,WAAW,IAAI,YAAY,CAAC,OAAO,0CAA0C,EACzF,SAAS,CAAC,iBAAiB,EAC3B,GAAG,EACH;YACE,WAAW;YACX,OAAO,EAAE,YAAY,CAAC,OAAO;YAC7B,YAAY,EAAE,YAAY;YAC1B,MAAM,EAAE,6CAA6C;YACrD,cAAc,EAAE;gBACd,8BAA8B;gBAC9B,6CAA6C;gBAC7C,wCAAwC;aACzC;YACD,UAAU,EAAE,6BAA6B,WAAW,EAAE;YACtD,YAAY,EAAE;gBACZ,2CAA2C,WAAW,EAAE;gBACxD,mCAAmC;gBACnC,6CAA6C;aAC9C;SACF,CACF,CAAC;IACJ,CAAC;IAED,kCAAkC;IAClC,OAAO;QACL,GAAG,YAAY;QACf,QAAQ,EAAE,YAAY;KACvB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IAE1D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,SAAS,CACjB,8BAA8B,EAC9B,SAAS,CAAC,cAAc,EACxB,GAAG,EACH;YACE,WAAW;YACX,YAAY;YACZ,MAAM,EAAE,2CAA2C;YACnD,UAAU,EAAE,4DAA4D;SACzE,CACF,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAoB,CAAC;QAExD,mBAAmB;QACnB,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC/D,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;YACjC,MAAM,IAAI,SAAS,CACjB,6CAA6C,EAC7C,SAAS,CAAC,cAAc,EACxB,GAAG,EACH;gBACE,YAAY;gBACZ,UAAU,EAAE,KAAK,CAAC,OAAO;aAC1B,CACF,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,SAAS,CACjB,mCAAmC,EACnC,SAAS,CAAC,cAAc,EACxB,GAAG,EACH;YACE,YAAY;YACZ,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CACF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,oBAAoB,CAClC,WAAmB,EACnB,WAAoB;IAOpB,oCAAoC;IACpC,MAAM,IAAI,GAAG,WAAW,IAAI,eAAe,EAAE,CAAC;IAE9C,gCAAgC;IAChC,MAAM,KAAK,GAAG,kBAAkB,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IAEpD,wBAAwB;IACxB,MAAM,QAAQ,GAAG,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAErD,2DAA2D;IAC3D,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,IAAI,UAAU,CAAC;IAEhD,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,QAAQ;QACpB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,KAAK,EAAE,UAAU;QACjB,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/utils/StdioMessageReader.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Stdio Message Reader
+ *
+ * Reads Content-Length framed messages from a stream (LSP-style).
+ * Handles partial messages across multiple chunks and ignores non-framed output.
+ *
+ * Message format:
+ * ```
+ * Content-Length: 67\r\n
+ * \r\n
+ * {"jsonrpc":"2.0","id":1,"method":"invoke","params":{...}}
+ * ```
+ *
+ * @module utils/StdioMessageReader
+ */
+import { EventEmitter } from 'events';
+/**
+ * Message reader for Content-Length framed messages
+ *
+ * Implements the LSP (Language Server Protocol) message framing format.
+ * This allows reliable JSON-RPC communication over stdio even when the
+ * ability writes logs or debug output to stdout.
+ *
+ * @example
+ * ```typescript
+ * const reader = new StdioMessageReader();
+ *
+ * reader.on('message', (message) => {
+ *   console.log('Received:', message);
+ * });
+ *
+ * reader.on('error', (error) => {
+ *   console.error('Parse error:', error);
+ * });
+ *
+ * // Feed data chunks
+ * process.stdout.on('data', (chunk) => {
+ *   reader.onData(chunk);
+ * });
+ * ```
+ */
+export declare class StdioMessageReader extends EventEmitter {
+    /**
+     * Buffer for accumulating incoming data
+     */
+    private buffer;
+    /**
+     * Whether the reader has been destroyed
+     */
+    private destroyed;
+    /**
+     * Header end marker
+     */
+    private static readonly HEADER_END;
+    /**
+     * Content-Length header regex
+     * Note: No multiline flag - header must be clean (no garbage before it)
+     */
+    private static readonly CONTENT_LENGTH_PATTERN;
+    /**
+     * Process incoming data chunk
+     *
+     * Appends chunk to buffer and attempts to parse complete messages.
+     * May emit multiple 'message' events if buffer contains multiple messages.
+     *
+     * @param chunk - Incoming data chunk
+     *
+     * @example
+     * ```typescript
+     * stream.on('data', (chunk) => {
+     *   reader.onData(chunk);
+     * });
+     * ```
+     */
+    onData(chunk: Buffer): void;
+    /**
+     * Attempt to read and emit complete messages from buffer
+     *
+     * Continues reading until no complete message can be extracted.
+     * Handles multiple messages in a single buffer.
+     */
+    private tryReadMessages;
+    /**
+     * Attempt to read a single complete message
+     *
+     * @returns Parsed message object, or null if no complete message available
+     * @throws {Error} If header is malformed or JSON is invalid
+     */
+    private tryReadSingleMessage;
+    /**
+     * Skip to next potential header in buffer
+     *
+     * Used for error recovery when a malformed message is encountered.
+     * Searches for the next "Content-Length:" pattern.
+     */
+    private skipToNextHeader;
+    /**
+     * Get current buffer size (for debugging/monitoring)
+     *
+     * @returns Number of bytes in buffer
+     */
+    getBufferSize(): number;
+    /**
+     * Clear the internal buffer
+     *
+     * Useful for resetting state after errors or for cleanup.
+     */
+    clearBuffer(): void;
+    /**
+     * Destroy the reader
+     *
+     * Cleans up resources and prevents further processing.
+     */
+    destroy(): void;
+    /**
+     * Check if reader is destroyed
+     *
+     * @returns true if destroyed
+     */
+    isDestroyed(): boolean;
+}
+//# sourceMappingURL=StdioMessageReader.d.ts.map

package/dist/utils/StdioMessageReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StdioMessageReader.d.ts","sourceRoot":"","sources":["../../src/utils/StdioMessageReader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;IAClD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAmB;IAEjC;;OAEG;IACH,OAAO,CAAC,SAAS,CAAS;IAE1B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAc;IAEhD;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAmC;IAEjF;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAY3B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAqBvB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAmD5B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;;;OAIG;IACH,aAAa,IAAI,MAAM;IAIvB;;;;OAIG;IACH,WAAW,IAAI,IAAI;IAInB;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAMf;;;;OAIG;IACH,WAAW,IAAI,OAAO;CAGvB"}

package/dist/utils/StdioMessageReader.js

@@ -0,0 +1,209 @@
+/**
+ * Stdio Message Reader
+ *
+ * Reads Content-Length framed messages from a stream (LSP-style).
+ * Handles partial messages across multiple chunks and ignores non-framed output.
+ *
+ * Message format:
+ * ```
+ * Content-Length: 67\r\n
+ * \r\n
+ * {"jsonrpc":"2.0","id":1,"method":"invoke","params":{...}}
+ * ```
+ *
+ * @module utils/StdioMessageReader
+ */
+import { EventEmitter } from 'events';
+/**
+ * Message reader for Content-Length framed messages
+ *
+ * Implements the LSP (Language Server Protocol) message framing format.
+ * This allows reliable JSON-RPC communication over stdio even when the
+ * ability writes logs or debug output to stdout.
+ *
+ * @example
+ * ```typescript
+ * const reader = new StdioMessageReader();
+ *
+ * reader.on('message', (message) => {
+ *   console.log('Received:', message);
+ * });
+ *
+ * reader.on('error', (error) => {
+ *   console.error('Parse error:', error);
+ * });
+ *
+ * // Feed data chunks
+ * process.stdout.on('data', (chunk) => {
+ *   reader.onData(chunk);
+ * });
+ * ```
+ */
+export class StdioMessageReader extends EventEmitter {
+    /**
+     * Buffer for accumulating incoming data
+     */
+    buffer = Buffer.alloc(0);
+    /**
+     * Whether the reader has been destroyed
+     */
+    destroyed = false;
+    /**
+     * Header end marker
+     */
+    static HEADER_END = '\r\n\r\n';
+    /**
+     * Content-Length header regex
+     * Note: No multiline flag - header must be clean (no garbage before it)
+     */
+    static CONTENT_LENGTH_PATTERN = /^Content-Length:\s*(\d+)\s*$/i;
+    /**
+     * Process incoming data chunk
+     *
+     * Appends chunk to buffer and attempts to parse complete messages.
+     * May emit multiple 'message' events if buffer contains multiple messages.
+     *
+     * @param chunk - Incoming data chunk
+     *
+     * @example
+     * ```typescript
+     * stream.on('data', (chunk) => {
+     *   reader.onData(chunk);
+     * });
+     * ```
+     */
+    onData(chunk) {
+        if (this.destroyed) {
+            return;
+        }
+        // Append to buffer
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        // Try to extract messages
+        this.tryReadMessages();
+    }
+    /**
+     * Attempt to read and emit complete messages from buffer
+     *
+     * Continues reading until no complete message can be extracted.
+     * Handles multiple messages in a single buffer.
+     */
+    tryReadMessages() {
+        while (true) {
+            try {
+                const message = this.tryReadSingleMessage();
+                if (!message) {
+                    // No complete message available
+                    break;
+                }
+                // Emit the message
+                this.emit('message', message);
+            }
+            catch (error) {
+                // Emit error but continue processing
+                this.emit('error', error);
+                // Try to recover by skipping to next potential header
+                this.skipToNextHeader();
+            }
+        }
+    }
+    /**
+     * Attempt to read a single complete message
+     *
+     * @returns Parsed message object, or null if no complete message available
+     * @throws {Error} If header is malformed or JSON is invalid
+     */
+    tryReadSingleMessage() {
+        // Look for header end marker
+        const headerEndIndex = this.buffer.indexOf(StdioMessageReader.HEADER_END);
+        if (headerEndIndex === -1) {
+            // No complete header yet
+            return null;
+        }
+        // Extract header
+        const headerBytes = this.buffer.slice(0, headerEndIndex);
+        const header = headerBytes.toString('utf8');
+        // Parse Content-Length
+        const match = header.match(StdioMessageReader.CONTENT_LENGTH_PATTERN);
+        if (!match || !match[1]) {
+            throw new Error(`Invalid message header: missing or malformed Content-Length\nHeader: ${header}`);
+        }
+        const contentLength = parseInt(match[1], 10);
+        if (isNaN(contentLength) || contentLength < 0) {
+            throw new Error(`Invalid Content-Length value: ${match[1]}`);
+        }
+        // Check if we have the complete message
+        const messageStart = headerEndIndex + StdioMessageReader.HEADER_END.length;
+        const messageEnd = messageStart + contentLength;
+        if (this.buffer.length < messageEnd) {
+            // Need more data - message is incomplete
+            return null;
+        }
+        // Extract message bytes
+        const messageBytes = this.buffer.slice(messageStart, messageEnd);
+        const messageJson = messageBytes.toString('utf8');
+        // Parse JSON
+        let message;
+        try {
+            message = JSON.parse(messageJson);
+        }
+        catch (error) {
+            throw new Error(`Invalid JSON in message body: ${error instanceof Error ? error.message : String(error)}\nJSON: ${messageJson.substring(0, 200)}`);
+        }
+        // Remove processed data from buffer
+        this.buffer = this.buffer.slice(messageEnd);
+        return message;
+    }
+    /**
+     * Skip to next potential header in buffer
+     *
+     * Used for error recovery when a malformed message is encountered.
+     * Searches for the next "Content-Length:" pattern.
+     */
+    skipToNextHeader() {
+        const searchString = this.buffer.toString('utf8');
+        const nextHeaderIndex = searchString.indexOf('Content-Length:', 1);
+        if (nextHeaderIndex === -1) {
+            // No next header found - clear buffer
+            this.buffer = Buffer.alloc(0);
+        }
+        else {
+            // Skip to next header
+            this.buffer = this.buffer.slice(nextHeaderIndex);
+        }
+    }
+    /**
+     * Get current buffer size (for debugging/monitoring)
+     *
+     * @returns Number of bytes in buffer
+     */
+    getBufferSize() {
+        return this.buffer.length;
+    }
+    /**
+     * Clear the internal buffer
+     *
+     * Useful for resetting state after errors or for cleanup.
+     */
+    clearBuffer() {
+        this.buffer = Buffer.alloc(0);
+    }
+    /**
+     * Destroy the reader
+     *
+     * Cleans up resources and prevents further processing.
+     */
+    destroy() {
+        this.destroyed = true;
+        this.buffer = Buffer.alloc(0);
+        this.removeAllListeners();
+    }
+    /**
+     * Check if reader is destroyed
+     *
+     * @returns true if destroyed
+     */
+    isDestroyed() {
+        return this.destroyed;
+    }
+}
+//# sourceMappingURL=StdioMessageReader.js.map

package/dist/utils/StdioMessageReader.js.map

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

package/dist/utils/StdioMessageWriter.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Stdio Message Writer
+ *
+ * Writes Content-Length framed messages to a stream (LSP-style).
+ * Ensures reliable message delivery even when other output is written to the stream.
+ *
+ * Message format:
+ * ```
+ * Content-Length: 67\r\n
+ * \r\n
+ * {"jsonrpc":"2.0","id":1,"result":{"value":42}}
+ * ```
+ *
+ * @module utils/StdioMessageWriter
+ */
+import type { Writable } from 'stream';
+/**
+ * Message writer for Content-Length framed messages
+ *
+ * Implements the LSP (Language Server Protocol) message framing format.
+ * Automatically calculates content length and formats headers.
+ *
+ * @example
+ * ```typescript
+ * const writer = new StdioMessageWriter(process.stdout);
+ *
+ * // Write a JSON-RPC message
+ * await writer.write({
+ *   jsonrpc: '2.0',
+ *   id: 1,
+ *   result: { value: 42 }
+ * });
+ * ```
+ */
+export declare class StdioMessageWriter {
+    /**
+     * Output stream
+     */
+    private readonly stream;
+    /**
+     * Whether the writer has been destroyed
+     */
+    private destroyed;
+    /**
+     * Header separator
+     */
+    private static readonly HEADER_SEPARATOR;
+    /**
+     * Create a new message writer
+     *
+     * @param stream - Output stream (typically stdout)
+     */
+    constructor(stream: Writable);
+    /**
+     * Write a framed message to the stream
+     *
+     * Serializes the message to JSON, calculates byte length, formats
+     * Content-Length header, and writes everything to the stream.
+     *
+     * @param message - Message object to write (will be JSON-stringified)
+     * @returns Promise that resolves when message is fully written
+     *
+     * @throws {Error} If writer is destroyed or write fails
+     *
+     * @example
+     * ```typescript
+     * await writer.write({
+     *   jsonrpc: '2.0',
+     *   id: 1,
+     *   method: 'invoke',
+     *   params: { toolName: 'add', toolInput: { a: 5, b: 3 } }
+     * });
+     * ```
+     */
+    write(message: Record<string, unknown>): Promise<void>;
+    /**
+     * Flush the stream
+     *
+     * Ensures all buffered data is written to the underlying stream.
+     *
+     * @returns Promise that resolves when flush is complete
+     */
+    flush(): Promise<void>;
+    /**
+     * Destroy the writer
+     *
+     * Cleans up resources. After calling destroy(), the writer cannot be used.
+     * Note: This does NOT close the underlying stream.
+     */
+    destroy(): void;
+    /**
+     * Check if writer is destroyed
+     *
+     * @returns true if destroyed
+     */
+    isDestroyed(): boolean;
+    /**
+     * Get the underlying stream
+     *
+     * @returns The writable stream
+     */
+    getStream(): Writable;
+}
+//# sourceMappingURL=StdioMessageWriter.d.ts.map

package/dist/utils/StdioMessageWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StdioMessageWriter.d.ts","sourceRoot":"","sources":["../../src/utils/StdioMessageWriter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAEvC;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,kBAAkB;IAC7B;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAElC;;OAEG;IACH,OAAO,CAAC,SAAS,CAAS;IAE1B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAElD;;;;OAIG;gBACS,MAAM,EAAE,QAAQ;IAI5B;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAqC5D;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB5B;;;;;OAKG;IACH,OAAO,IAAI,IAAI;IAIf;;;;OAIG;IACH,WAAW,IAAI,OAAO;IAItB;;;;OAIG;IACH,SAAS,IAAI,QAAQ;CAGtB"}