@portel/photon-core 1.0.2 → 1.2.0

package/dist/generator.js

@@ -0,0 +1,410 @@
+/**
+ * Generator-based Tool Execution with Ask/Emit Pattern
+ *
+ * Enables photon tools to use async generator functions with `yield` for:
+ * - Interactive user input (ask) - blocks until user responds
+ * - Real-time output (emit) - fire and forget, no response needed
+ *
+ * ══════════════════════════════════════════════════════════════════════════════
+ * DESIGN PHILOSOPHY
+ * ══════════════════════════════════════════════════════════════════════════════
+ *
+ * The `ask` vs `emit` pattern provides instant clarity:
+ * - `ask` = "I need something FROM the user" (blocks, returns value)
+ * - `emit` = "I'm sending something TO the user" (non-blocking, void)
+ *
+ * This maps naturally to all runtime contexts:
+ *
+ * | Runtime    | ask (input)              | emit (output)              |
+ * |------------|--------------------------|----------------------------|
+ * | REST API   | Returns 202 + continue   | Included in response or SSE|
+ * | WebSocket  | Server request → client  | Server push to client      |
+ * | CLI        | Readline prompt          | Console output             |
+ * | MCP        | Elicitation dialog       | Notification/logging       |
+ * | Chatbot    | Bot question → user reply| Status message, typing...  |
+ *
+ * ══════════════════════════════════════════════════════════════════════════════
+ * REST API CONTINUATION PATTERN
+ * ══════════════════════════════════════════════════════════════════════════════
+ *
+ * When a generator yields `ask`, REST APIs can implement a continuation flow:
+ *
+ * ```
+ * POST /api/google-tv/connect
+ * Body: { ip: "192.168.1.100" }
+ *
+ * Response (202 Accepted):
+ * {
+ *   "status": "awaiting_input",
+ *   "continuation_id": "ctx_abc123",
+ *   "ask": { "type": "text", "id": "pairing_code", "message": "Enter code:" },
+ *   "continue": "/api/google-tv/connect/ctx_abc123"
+ * }
+ *
+ * POST /api/google-tv/connect/ctx_abc123
+ * Body: { "pairing_code": "123456" }
+ *
+ * Response (200 OK):
+ * { "status": "complete", "result": { "success": true } }
+ * ```
+ *
+ * ══════════════════════════════════════════════════════════════════════════════
+ * USAGE EXAMPLE
+ * ══════════════════════════════════════════════════════════════════════════════
+ *
+ * ```typescript
+ * async *connect(params: { ip: string }) {
+ *   yield { emit: 'status', message: 'Connecting to TV...' };
+ *
+ *   await this.startPairing(params.ip);
+ *
+ *   yield { emit: 'progress', value: 0.3, message: 'Waiting for code...' };
+ *
+ *   // Blocks until user provides input
+ *   const code: string = yield {
+ *     ask: 'text',
+ *     id: 'pairing_code',
+ *     message: 'Enter the 6-digit code shown on TV:',
+ *     pattern: '^[0-9]{6}$',
+ *     required: true
+ *   };
+ *
+ *   yield { emit: 'status', message: 'Verifying code...' };
+ *
+ *   await this.sendCode(code);
+ *
+ *   yield { emit: 'toast', message: 'Connected!', type: 'success' };
+ *
+ *   return { success: true, paired: true };
+ * }
+ * ```
+ *
+ * @module generator
+ */
+// ══════════════════════════════════════════════════════════════════════════════
+// TYPE GUARDS - Check what kind of yield we have
+// ══════════════════════════════════════════════════════════════════════════════
+/**
+ * Check if yield is an ask (requires user input)
+ *
+ * @example
+ * if (isAskYield(yielded)) {
+ *   const userInput = await promptUser(yielded);
+ *   generator.next(userInput);
+ * }
+ */
+export function isAskYield(y) {
+    return 'ask' in y;
+}
+/**
+ * Check if yield is an emit (output only, no response needed)
+ *
+ * @example
+ * if (isEmitYield(yielded)) {
+ *   handleOutput(yielded);
+ *   generator.next(); // Continue without value
+ * }
+ */
+export function isEmitYield(y) {
+    return 'emit' in y;
+}
+/**
+ * Get the type of an ask yield
+ */
+export function getAskType(y) {
+    return y.ask;
+}
+/**
+ * Get the type of an emit yield
+ */
+export function getEmitType(y) {
+    return y.emit;
+}
+// ══════════════════════════════════════════════════════════════════════════════
+// GENERATOR DETECTION
+// ══════════════════════════════════════════════════════════════════════════════
+/**
+ * Check if a function is an async generator function
+ *
+ * @example
+ * if (isAsyncGeneratorFunction(method)) {
+ *   const gen = method.call(instance, params);
+ *   await executeGenerator(gen, config);
+ * }
+ */
+export function isAsyncGeneratorFunction(fn) {
+    if (!fn)
+        return false;
+    const constructor = fn.constructor;
+    if (!constructor)
+        return false;
+    if (constructor.name === 'AsyncGeneratorFunction')
+        return true;
+    const prototype = Object.getPrototypeOf(fn);
+    return prototype?.constructor?.name === 'AsyncGeneratorFunction';
+}
+/**
+ * Check if a value is an async generator instance (already invoked)
+ *
+ * @example
+ * const result = method.call(instance, params);
+ * if (isAsyncGenerator(result)) {
+ *   await executeGenerator(result, config);
+ * }
+ */
+export function isAsyncGenerator(obj) {
+    return obj &&
+        typeof obj.next === 'function' &&
+        typeof obj.return === 'function' &&
+        typeof obj.throw === 'function' &&
+        typeof obj[Symbol.asyncIterator] === 'function';
+}
+// ══════════════════════════════════════════════════════════════════════════════
+// GENERATOR EXECUTOR - Runs generator tools to completion
+// ══════════════════════════════════════════════════════════════════════════════
+/**
+ * Execute a generator-based photon tool to completion.
+ *
+ * Handles the yield/resume loop:
+ * 1. Run generator until it yields
+ * 2. If ask yield: get input from provider (or pre-provided), resume with value
+ * 3. If emit yield: call output handler, resume without value
+ * 4. Repeat until generator returns
+ *
+ * @param generator - The async generator to execute
+ * @param config - Configuration for handling yields
+ * @returns The final return value of the generator
+ *
+ * @example
+ * const result = await executeGenerator(photon.connect({ ip: '192.168.1.1' }), {
+ *   inputProvider: async (ask) => {
+ *     if (ask.ask === 'text') return await readline(ask.message);
+ *     if (ask.ask === 'confirm') return await confirm(ask.message);
+ *   },
+ *   outputHandler: (emit) => {
+ *     if (emit.emit === 'progress') console.log(`${emit.value * 100}%`);
+ *   }
+ * });
+ */
+export async function executeGenerator(generator, config) {
+    const { inputProvider, outputHandler, preProvidedInputs } = config;
+    let askIndex = 0;
+    let result = await generator.next();
+    while (!result.done) {
+        const yielded = result.value;
+        // Handle ask yields (need input)
+        if (isAskYield(yielded)) {
+            // Generate id if not provided
+            const askId = yielded.id || `ask_${askIndex++}`;
+            // Check for pre-provided input (REST API style)
+            if (preProvidedInputs && askId in preProvidedInputs) {
+                result = await generator.next(preProvidedInputs[askId]);
+                continue;
+            }
+            // Get input from provider
+            const input = await inputProvider(yielded);
+            result = await generator.next(input);
+        }
+        // Handle emit yields (output only)
+        else if (isEmitYield(yielded)) {
+            if (outputHandler) {
+                await outputHandler(yielded);
+            }
+            // Continue without providing a value
+            result = await generator.next();
+        }
+        // Unknown yield type - skip
+        else {
+            console.warn('[generator] Unknown yield type:', yielded);
+            result = await generator.next();
+        }
+    }
+    return result.value;
+}
+/**
+ * Extract ask yield information by running generator with mock provider.
+ *
+ * This is used for REST API schema generation - each ask becomes
+ * an optional request parameter.
+ *
+ * Note: Only extracts asks reachable with default/empty inputs.
+ * Conditional asks may not be discovered.
+ *
+ * @example
+ * const asks = await extractAsks(Photon.prototype.connect, { ip: '' });
+ * // Returns: [{ id: 'pairing_code', type: 'text', message: '...' }]
+ * // These become optional query/body params in REST API
+ */
+export async function extractAsks(generatorFn, mockParams = {}) {
+    const asks = [];
+    let askIndex = 0;
+    try {
+        const generator = generatorFn(mockParams);
+        let result = await generator.next();
+        while (!result.done) {
+            const yielded = result.value;
+            if (isAskYield(yielded)) {
+                const id = yielded.id || `ask_${askIndex++}`;
+                const extracted = {
+                    id,
+                    type: yielded.ask,
+                    message: yielded.message,
+                    required: yielded.required,
+                };
+                // Extract type-specific properties
+                if (yielded.ask === 'text') {
+                    extracted.default = yielded.default;
+                    extracted.pattern = yielded.pattern;
+                }
+                else if (yielded.ask === 'confirm') {
+                    extracted.default = yielded.default;
+                }
+                else if (yielded.ask === 'select') {
+                    extracted.options = yielded.options;
+                    extracted.default = yielded.default;
+                }
+                else if (yielded.ask === 'number') {
+                    extracted.default = yielded.default;
+                    extracted.min = yielded.min;
+                    extracted.max = yielded.max;
+                }
+                asks.push(extracted);
+                // Provide mock value to continue
+                const mockValue = getMockValue(yielded);
+                result = await generator.next(mockValue);
+            }
+            else {
+                // Skip emit yields
+                result = await generator.next();
+            }
+        }
+    }
+    catch (error) {
+        // Generator may throw if it needs real resources
+        // Return what we've extracted so far
+        console.warn('[generator] Ask extraction incomplete:', error);
+    }
+    return asks;
+}
+/**
+ * Get a mock value for an ask yield (for extraction purposes)
+ */
+function getMockValue(ask) {
+    switch (ask.ask) {
+        case 'text':
+        case 'password':
+            return ask.default || '';
+        case 'confirm':
+            return ask.default ?? true;
+        case 'select':
+            const select = ask;
+            const firstOpt = select.options[0];
+            const firstVal = typeof firstOpt === 'string' ? firstOpt : firstOpt.value;
+            return select.multi ? [firstVal] : firstVal;
+        case 'number':
+            return ask.default ?? 0;
+        case 'file':
+            return null;
+        case 'date':
+            return ask.default || new Date().toISOString();
+        default:
+            return null;
+    }
+}
+// ══════════════════════════════════════════════════════════════════════════════
+// BUILT-IN INPUT PROVIDERS
+// ══════════════════════════════════════════════════════════════════════════════
+/**
+ * Error thrown when input is required but not available.
+ *
+ * REST APIs can catch this to return a continuation response.
+ *
+ * @example
+ * try {
+ *   await executeGenerator(gen, { inputProvider: createPrefilledProvider({}) });
+ * } catch (e) {
+ *   if (e instanceof NeedsInputError) {
+ *     return {
+ *       status: 'awaiting_input',
+ *       ask: e.ask,
+ *       continuation_id: saveContinuation(gen)
+ *     };
+ *   }
+ * }
+ */
+export class NeedsInputError extends Error {
+    ask;
+    constructor(ask) {
+        super(`Input required: ${ask.message}`);
+        this.name = 'NeedsInputError';
+        this.ask = ask;
+    }
+}
+/**
+ * Create an input provider from pre-provided values.
+ * Throws NeedsInputError if a required value is missing.
+ *
+ * Use for REST APIs where all inputs are provided upfront.
+ *
+ * @example
+ * const provider = createPrefilledProvider({
+ *   name: 'John',
+ *   confirmed: true
+ * });
+ */
+export function createPrefilledProvider(inputs) {
+    let askIndex = 0;
+    return async (ask) => {
+        const id = ask.id || `ask_${askIndex++}`;
+        if (id in inputs) {
+            return inputs[id];
+        }
+        // Check for default value
+        if ('default' in ask && ask.default !== undefined) {
+            return ask.default;
+        }
+        // No input available
+        throw new NeedsInputError(ask);
+    };
+}
+// ══════════════════════════════════════════════════════════════════════════════
+// UTILITY: Wrap regular function as generator
+// ══════════════════════════════════════════════════════════════════════════════
+/**
+ * Wrap a regular async function to behave like a generator.
+ * Useful for uniform handling in runtimes.
+ *
+ * @example
+ * const gen = wrapAsGenerator(() => photon.simpleMethod(params));
+ * const result = await executeGenerator(gen, config);
+ */
+export async function* wrapAsGenerator(asyncFn) {
+    return await asyncFn();
+}
+/**
+ * @deprecated Use isAskYield instead
+ */
+export const isInputYield = isAskYield;
+/**
+ * @deprecated Use isEmitYield instead
+ */
+export function isProgressYield(y) {
+    return isEmitYield(y) && y.emit === 'progress';
+}
+/**
+ * @deprecated Use isEmitYield instead
+ */
+export function isStreamYield(y) {
+    return isEmitYield(y) && y.emit === 'stream';
+}
+/**
+ * @deprecated Use isEmitYield instead
+ */
+export function isLogYield(y) {
+    return isEmitYield(y) && y.emit === 'log';
+}
+/**
+ * @deprecated Use extractAsks instead
+ */
+export const extractYields = extractAsks;
+//# sourceMappingURL=generator.js.map

package/dist/generator.js.map

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

package/dist/index.d.ts

@@ -38,4 +38,6 @@ export { SchemaExtractor } from './schema-extractor.js';
 export { formatOutput, detectFormat, renderPrimitive, renderList, renderTable, renderTree, renderNone, formatKey, formatValue, formatToMimeType, printSuccess, printError, printInfo, printWarning, printHeader, STATUS, } from './cli-formatter.js';
 export { resolvePath, listFiles, ensureDir, resolvePhotonPath, listPhotonFiles, ensurePhotonDir, DEFAULT_PHOTON_DIR, type ResolverOptions, } from './path-resolver.js';
 export * from './types.js';
+export { isAskYield, isEmitYield, getAskType, getEmitType, isAsyncGeneratorFunction, isAsyncGenerator, executeGenerator, extractAsks, createPrefilledProvider, NeedsInputError, wrapAsGenerator, type AskYield, type AskText, type AskPassword, type AskConfirm, type AskSelect, type AskNumber, type AskFile, type AskDate, type EmitYield, type EmitStatus, type EmitProgress, type EmitStream, type EmitLog, type EmitToast, type EmitThinking, type EmitArtifact, type PhotonYield, type InputProvider, type OutputHandler, type GeneratorExecutorConfig, type ExtractedAsk, isInputYield, isProgressYield, isStreamYield, isLogYield, extractYields, type PromptYield, type ConfirmYield, type SelectYield, type ProgressYield, type StreamYield, type LogYield, type ExtractedYield, } from './generator.js';
+export { prompt, confirm, elicit, elicitReadline, elicitNativeDialog, setPromptHandler, getPromptHandler, setElicitHandler, getElicitHandler, type ElicitOptions, type ElicitResult, type ElicitHandler, type PromptHandler, } from './elicit.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,UAAU,EACV,WAAW,EACX,UAAU,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,MAAM,GACP,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,WAAW,EACX,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAC;AAG5B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,UAAU,EACV,WAAW,EACX,UAAU,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,MAAM,GACP,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,WAAW,EACX,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAC;AAG5B,cAAc,YAAY,CAAC;AAI3B,OAAO,EAEL,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EAGX,wBAAwB,EACxB,gBAAgB,EAGhB,gBAAgB,EAGhB,WAAW,EAGX,uBAAuB,EACvB,eAAe,EAGf,eAAe,EAGf,KAAK,QAAQ,EACb,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,OAAO,EAGZ,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,YAAY,EAGjB,KAAK,WAAW,EAGhB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAC5B,KAAK,YAAY,EAGjB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,UAAU,EACV,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAEL,MAAM,EACN,OAAO,EAEP,MAAM,EACN,cAAc,EACd,kBAAkB,EAElB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAEhB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -44,4 +44,29 @@ export { formatOutput, detectFormat, renderPrimitive, renderList, renderTable, r
 export { resolvePath, listFiles, ensureDir, resolvePhotonPath, listPhotonFiles, ensurePhotonDir, DEFAULT_PHOTON_DIR, } from './path-resolver.js';
 // Types
 export * from './types.js';
+// Generator-based tools with ask/emit pattern
+// See generator.ts for comprehensive documentation
+export { 
+// Type guards - check yield direction
+isAskYield, isEmitYield, getAskType, getEmitType, 
+// Generator detection
+isAsyncGeneratorFunction, isAsyncGenerator, 
+// Executor - runs generators to completion
+executeGenerator, 
+// Ask extraction (for REST API schema generation)
+extractAsks, 
+// Built-in providers
+createPrefilledProvider, NeedsInputError, 
+// Utility
+wrapAsGenerator, 
+// Legacy compatibility (deprecated)
+isInputYield, isProgressYield, isStreamYield, isLogYield, extractYields, } from './generator.js';
+// Elicit - Cross-platform user input (legacy, prefer generators)
+export { 
+// Simple functions (no imports needed in photon files)
+prompt, confirm, 
+// Full elicit with options
+elicit, elicitReadline, elicitNativeDialog, 
+// Handler management (for runtimes)
+setPromptHandler, getPromptHandler, setElicitHandler, getElicitHandler, } from './elicit.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uCAAuC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,wBAAwB;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,oBAAoB;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,iBAAiB;AACjB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,UAAU,EACV,WAAW,EACX,UAAU,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,MAAM,GACP,MAAM,oBAAoB,CAAC;AAE5B,kBAAkB;AAClB,OAAO,EACL,WAAW,EACX,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,kBAAkB,GAEnB,MAAM,oBAAoB,CAAC;AAE5B,QAAQ;AACR,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uCAAuC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,wBAAwB;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,oBAAoB;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,iBAAiB;AACjB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,UAAU,EACV,WAAW,EACX,UAAU,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,MAAM,GACP,MAAM,oBAAoB,CAAC;AAE5B,kBAAkB;AAClB,OAAO,EACL,WAAW,EACX,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,kBAAkB,GAEnB,MAAM,oBAAoB,CAAC;AAE5B,QAAQ;AACR,cAAc,YAAY,CAAC;AAE3B,8CAA8C;AAC9C,mDAAmD;AACnD,OAAO;AACL,sCAAsC;AACtC,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW;AAEX,sBAAsB;AACtB,wBAAwB,EACxB,gBAAgB;AAEhB,2CAA2C;AAC3C,gBAAgB;AAEhB,kDAAkD;AAClD,WAAW;AAEX,qBAAqB;AACrB,uBAAuB,EACvB,eAAe;AAEf,UAAU;AACV,eAAe;AA+Bf,oCAAoC;AACpC,YAAY,EACZ,eAAe,EACf,aAAa,EACb,UAAU,EACV,aAAa,GAQd,MAAM,gBAAgB,CAAC;AAExB,iEAAiE;AACjE,OAAO;AACL,uDAAuD;AACvD,MAAM,EACN,OAAO;AACP,2BAA2B;AAC3B,MAAM,EACN,cAAc,EACd,kBAAkB;AAClB,oCAAoC;AACpC,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GAMjB,MAAM,aAAa,CAAC"}

package/dist/schema-extractor.d.ts

@@ -108,5 +108,11 @@ export declare class SchemaExtractor {
      * Example: @mimeType text/markdown
      */
     private extractMimeType;
+    /**
+     * Extract yield information from JSDoc for generator methods
+     * Supports @yields tags with id, type, and description
+     * Example: @yields {pairing_code} text Enter the 6-digit code shown on TV
+     */
+    private extractYieldsFromJSDoc;
 }
 //# sourceMappingURL=schema-extractor.d.ts.map

package/dist/schema-extractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-extractor.d.ts","sourceRoot":"","sources":["../src/schema-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAE,UAAU,EAAgB,MAAM,YAAY,CAAC;AAEvG,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,qBAAa,eAAe;IAC1B;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAUnE;;OAEG;IACH,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB;IAyHvD;;OAEG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,EAAE;IAIpD;;OAEG;IACH,OAAO,CAAC,eAAe;IAqBvB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAS7B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAiC3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAyGxB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IA0F5B;;OAEG;IACH,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAmD5D;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAuB3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAqB1B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IA4BxB;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IA2G/B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IA0FxB;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,YAAY;IAIpB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAKxB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAsBrB;;;OAGG;IACH,OAAO,CAAC,eAAe;CAIxB"}
+{"version":3,"file":"schema-extractor.d.ts","sourceRoot":"","sources":["../src/schema-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAE,UAAU,EAA2B,MAAM,YAAY,CAAC;AAElH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,qBAAa,eAAe;IAC1B;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAUnE;;OAEG;IACH,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB;IAgIvD;;OAEG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,EAAE;IAIpD;;OAEG;IACH,OAAO,CAAC,eAAe;IAqBvB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAS7B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAiC3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAyGxB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IA0F5B;;OAEG;IACH,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAmD5D;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAuB3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAqB1B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IA4BxB;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IA2G/B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IA0FxB;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,YAAY;IAIpB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAKxB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAsBrB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAKvB;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;CAiB/B"}

package/dist/schema-extractor.js

@@ -45,6 +45,8 @@ export class SchemaExtractor {
             const processMethod = (member) => {
                 const methodName = member.name.getText(sourceFile);
                 const jsdoc = this.getJSDocComment(member, sourceFile);
+                // Check if this is an async generator method (has asterisk token)
+                const isGenerator = member.asteriskToken !== undefined;
                 // Extract parameter type information
                 const paramsType = this.getFirstParameterType(member, sourceFile);
                 if (!paramsType) {
@@ -100,11 +102,14 @@ export class SchemaExtractor {
                 // Otherwise, it's a regular tool
                 else {
                     const outputFormat = this.extractFormat(jsdoc);
+                    const yields = isGenerator ? this.extractYieldsFromJSDoc(jsdoc) : undefined;
                     tools.push({
                         name: methodName,
                         description,
                         inputSchema,
                         ...(outputFormat ? { outputFormat } : {}),
+                        ...(isGenerator ? { isGenerator: true } : {}),
+                        ...(yields && yields.length > 0 ? { yields } : {}),
                     });
                 }
             };
@@ -113,7 +118,7 @@ export class SchemaExtractor {
                 // Look for class declarations
                 if (ts.isClassDeclaration(node)) {
                     node.members.forEach((member) => {
-                        // Look for async methods
+                        // Look for async methods (including async generators with *)
                         if (ts.isMethodDeclaration(member) &&
                             member.modifiers?.some(m => m.kind === ts.SyntaxKind.AsyncKeyword)) {
                             processMethod(member);
@@ -736,5 +741,25 @@ export class SchemaExtractor {
         const match = jsdocContent.match(/@mimeType\s+([\w\/\-+.]+)/i);
         return match ? match[1].trim() : undefined;
     }
+    /**
+     * Extract yield information from JSDoc for generator methods
+     * Supports @yields tags with id, type, and description
+     * Example: @yields {pairing_code} text Enter the 6-digit code shown on TV
+     */
+    extractYieldsFromJSDoc(jsdocContent) {
+        const yields = [];
+        // Match @yields {id} type description
+        const yieldRegex = /@yields?\s+\{(\w+)\}\s+(prompt|confirm|select)\s+(.+)/gi;
+        let match;
+        while ((match = yieldRegex.exec(jsdocContent)) !== null) {
+            const [, id, type, description] = match;
+            yields.push({
+                id,
+                type: type.toLowerCase(),
+                prompt: description.trim(),
+            });
+        }
+        return yields;
+    }
 }
 //# sourceMappingURL=schema-extractor.js.map