@majkapp/plugin-kit 3.5.5 → 3.6.1

package/README.md

@@ -15,6 +15,7 @@ Build type-safe, production-ready MAJK plugins with excellent developer experien
 🔧 **Tool Management** - Declare tools with schema validation
 💾 **Storage Integration** - Direct access to plugin storage
 📡 **Event Bus** - Subscribe to system events
+🔗 **RPC Callbacks** - Pass callbacks across plugin boundaries with automatic serialization
 🧹 **Auto Cleanup** - Managed lifecycle with automatic resource cleanup
 ❤️ **Health Checks** - Built-in health monitoring
 
@@ -446,6 +447,90 @@ if (imageProviders.length > 0) {
 - Integrate multiple AI providers
 - Generate content, analyze data, summarize text
 
+### Plugin Management API
+
+Generate authenticated URLs for opening plugin UIs in external browsers or creating cross-plugin links:
+
+```typescript
+// Simple convenience method - get URL for another plugin's screen
+const url = await ctx.majk.plugins.getExternalUrl(
+  '@analytics/dashboard',  // Plugin ID (package name format)
+  'main',                  // Screen ID (optional)
+  '#/overview'             // Hash fragment (optional)
+);
+
+// Opens: http://localhost:9000/plugins/analytics/dashboard/ui/main?token=abc123#/overview
+await ctx.shell?.openExternal(url);
+
+// Advanced: Full control over URL generation
+const customUrl = await ctx.majk.plugins.getPluginScreenUrl('@myorg/plugin', {
+  screenId: 'settings',      // Specific screen
+  theme: 'dark',             // Theme preference
+  hash: '#/advanced',        // Client-side route
+  queryParams: {             // Custom query parameters
+    view: 'compact',
+    filter: 'active'
+  }
+});
+
+// Direct URL with custom path (when you know the exact endpoint)
+const apiUrl = await ctx.majk.plugins.getPluginExternalUrl('plugin-id', {
+  path: '/api/export',       // Custom path within plugin
+  queryParams: { format: 'json' }
+});
+```
+
+**API Methods:**
+
+- **`getExternalUrl(pluginId, screenId?, hash?)`** - Simple convenience method for getting screen URLs
+- **`getPluginScreenUrl(pluginId, options)`** - Screen-aware URL generation with full options
+- **`getPluginExternalUrl(pluginId, options)`** - Low-level URL generation for custom paths
+
+**URL Format:**
+```
+http://localhost:{port}/plugins/{org}/{plugin}/ui/{screen}?token={token}&theme={theme}#{hash}
+```
+
+**Security:**
+- URLs include one-time authentication tokens (60s TTL)
+- After expiration, users are redirected to login if required
+- Tokens are automatically validated by the plugin server
+
+**Use Cases:**
+- Open plugin screens in external browser windows
+- Create shareable links to plugin functionality
+- Cross-plugin navigation and deep linking
+- Programmatic browser-based testing
+- Integration with external tools and workflows
+
+**Example - Cross-Plugin Integration:**
+
+```typescript
+.apiRoute({
+  method: 'POST',
+  path: '/api/generate-report',
+  name: 'Generate Report',
+  description: 'Generates analytics report. Creates report and returns link to view.',
+  handler: async (req, res, { majk }) => {
+    // Generate report data
+    const reportId = await generateReport(req.body);
+
+    // Create link to analytics plugin's viewer
+    const viewerUrl = await majk.plugins.getExternalUrl(
+      '@analytics/viewer',
+      'report',
+      `#/report/${reportId}`
+    );
+
+    return {
+      success: true,
+      reportId,
+      viewUrl: viewerUrl  // User can click to view in analytics plugin
+    };
+  }
+})
+```
+
 ### PluginStorage
 
 Simple key-value storage scoped to your plugin:
@@ -646,6 +731,69 @@ See `example.ts` for a comprehensive example showing:
 - Storage usage
 - Health checks
 
+## RPC & Callbacks
+
+Plugins can communicate with each other using RPC services and pass callbacks across plugin boundaries:
+
+### Basic RPC Service
+
+```typescript
+// Plugin A: Register a service
+.onLoad(async (ctx) => {
+  await ctx.rpc.registerService('fileProcessor', {
+    async processFile(path: string, onProgress: (percent: number) => void): Promise<string> {
+      await onProgress(0);
+      await onProgress(50);
+      await onProgress(100);
+      return `Processed: ${path}`;
+    }
+  });
+})
+```
+
+### Consuming with Callbacks
+
+```typescript
+// Plugin B: Use the service with callbacks
+.onLoad(async (ctx) => {
+  const processor = await ctx.rpc.createProxy<{
+    processFile(path: string, onProgress: (p: number) => void): Promise<string>
+  }>('fileProcessor');
+
+  // Pass callback - it just works!
+  const result = await processor.processFile('/file.txt', (progress) => {
+    console.log(`Progress: ${progress}%`);
+  });
+})
+```
+
+### Explicit Callbacks with Cleanup
+
+For long-lived callbacks (subscriptions, event listeners), use `createCallback()`:
+
+```typescript
+// Auto-cleanup after 10 calls
+const callback = await ctx.rpc.createCallback!(
+  (event) => console.log('Event:', event),
+  { maxCalls: 10 }
+);
+await eventService.subscribe(callback);
+
+// Auto-cleanup after 5 seconds
+const callback = await ctx.rpc.createCallback!(
+  (data) => console.log('Data:', data),
+  { timeout: 5000 }
+);
+await dataStream.subscribe(callback);
+
+// Manual cleanup
+const callback = await ctx.rpc.createCallback!((msg) => console.log(msg));
+// ... later
+ctx.rpc.cleanupCallback!(callback);
+```
+
+See [docs/RPC_CALLBACKS.md](docs/RPC_CALLBACKS.md) for comprehensive documentation, patterns, and best practices.
+
 ## TypeScript
 
 Full TypeScript support with:

package/bin/promptable-cli.js

@@ -58,6 +58,12 @@ cli.addCommand('--services',
   { description: 'Organize functions by service' }
 );
 
+// RPC and callbacks
+cli.addCommand('--rpc',
+  cli.createFullDocCommand('RPC_CALLBACKS.md'),
+  { description: 'Inter-plugin RPC with callbacks' }
+);
+
 // Teammates
 cli.addCommand('--teammates',
   cli.createFullDocCommand('TEAMMATES.md'),

package/dist/generator/cli.js

@@ -39,6 +39,7 @@ const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const child_process_1 = require("child_process");
 const generator_1 = require("./generator");
+const extract_command_1 = require("./extract-command");
 // Check args BEFORE commander parses to intercept for documentation
 const args = process.argv.slice(2);
 // If -h or --help, let commander handle it normally (show generator help)
@@ -163,6 +164,26 @@ commander_1.program
         await generate();
     }
 });
+// Extract capabilities command
+commander_1.program
+    .command('extract')
+    .description('Extract plugin capabilities to .majk/capabilities.json for market indexing')
+    .option('-e, --entry <path>', 'Path to the compiled plugin entry file', './dist/index.js')
+    .option('-o, --output <path>', 'Output directory for capabilities.json', '.majk')
+    .option('-s, --silent', 'Suppress output messages', false)
+    .action(async (options) => {
+    try {
+        await (0, extract_command_1.extractCapabilities)({
+            entry: options.entry,
+            output: options.output,
+            silent: options.silent
+        });
+    }
+    catch (error) {
+        console.error(error.message);
+        process.exit(1);
+    }
+});
 // Add documentation options to help
 commander_1.program
     .option('--llm', 'Show plugin development documentation (quick start)')
@@ -198,6 +219,8 @@ async function extractMetadata(entryPath) {
         }
         const content = fs.readFileSync(tempFile, 'utf-8');
         const metadata = JSON.parse(content);
+        // NEW: Also save capabilities.json for market indexing
+        await saveCapabilitiesForMarket(metadata);
         // Clean up temp file
         fs.unlinkSync(tempFile);
         return metadata;
@@ -210,3 +233,70 @@ async function extractMetadata(entryPath) {
         throw new Error(`Failed to extract metadata: ${error.message}`);
     }
 }
+/**
+ * Save capabilities.json to .majk/ directory and auto-update package.json
+ */
+async function saveCapabilitiesForMarket(metadata) {
+    try {
+        // Find project root (where package.json is)
+        const projectRoot = process.cwd();
+        // Check if plugin opted out
+        const pkgPath = path.join(projectRoot, 'package.json');
+        if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+            if (pkg.majk?.skipCapabilitiesExtraction === true) {
+                console.log('  ℹ️  Skipping capabilities extraction (skipCapabilitiesExtraction: true)');
+                return;
+            }
+        }
+        // 1. Create .majk directory
+        const majkDir = path.join(projectRoot, '.majk');
+        fs.mkdirSync(majkDir, { recursive: true });
+        // 2. Write capabilities.json
+        const capabilitiesPath = path.join(majkDir, 'capabilities.json');
+        fs.writeFileSync(capabilitiesPath, JSON.stringify(metadata, null, 2) + '\n');
+        console.log('  ✓ Generated .majk/capabilities.json for market indexing');
+        // 3. Check and update package.json files array
+        if (fs.existsSync(pkgPath)) {
+            const content = fs.readFileSync(pkgPath, 'utf-8');
+            const pkg = JSON.parse(content);
+            if (pkg.files) {
+                if (!pkg.files.includes('.majk')) {
+                    // Detect original indentation
+                    const indent = detectIndent(content);
+                    pkg.files.push('.majk');
+                    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + '\n');
+                    console.log('  ✓ Added .majk to package.json files array (commit this change)');
+                }
+            }
+            else {
+                // No files array means all files included by default
+                console.log('  ℹ️  No "files" array in package.json - .majk will be included by default');
+            }
+        }
+        // 4. Check for service implementations
+        const capabilities = metadata.capabilities || [];
+        const services = capabilities.filter((c) => c.type === 'service');
+        const implementations = services.filter((s) => s.implements);
+        if (implementations.length > 0) {
+            console.log('  🔌 Service interface implementations detected:');
+            implementations.forEach((impl) => {
+                console.log(`     • ${impl.implements}`);
+            });
+        }
+    }
+    catch (error) {
+        // Non-fatal: log but don't fail the build
+        console.warn(`  ⚠️  Could not save capabilities for market: ${error.message}`);
+    }
+}
+/**
+ * Detect indentation used in a JSON file
+ */
+function detectIndent(jsonString) {
+    const match = jsonString.match(/^(\s+)/m);
+    if (match) {
+        return match[1].length;
+    }
+    return 2; // Default to 2 spaces
+}

package/dist/generator/extract-command.d.ts

@@ -0,0 +1,10 @@
+export interface ExtractOptions {
+    entry?: string;
+    output?: string;
+    silent?: boolean;
+}
+/**
+ * Extract plugin capabilities and write to .majk/capabilities.json
+ */
+export declare function extractCapabilities(options?: ExtractOptions): Promise<void>;
+//# sourceMappingURL=extract-command.d.ts.map

package/dist/generator/extract-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-command.d.ts","sourceRoot":"","sources":["../../src/generator/extract-command.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyFrF"}

package/dist/generator/extract-command.js

@@ -0,0 +1,122 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractCapabilities = extractCapabilities;
+/**
+ * Extract capabilities command - Creates .majk/capabilities.json for market indexing
+ */
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const child_process_1 = require("child_process");
+/**
+ * Extract plugin capabilities and write to .majk/capabilities.json
+ */
+async function extractCapabilities(options = {}) {
+    const entryPath = path.resolve(options.entry || './dist/index.js');
+    const outputDir = path.resolve(options.output || '.majk');
+    const outputFile = path.join(outputDir, 'capabilities.json');
+    const silent = options.silent || false;
+    if (!silent) {
+        console.log('🔍 Extracting plugin capabilities...');
+        console.log(`   Entry: ${entryPath}`);
+        console.log(`   Output: ${outputFile}`);
+        console.log('');
+    }
+    // Check if entry file exists
+    if (!fs.existsSync(entryPath)) {
+        throw new Error(`Entry file not found: ${entryPath}\n` +
+            `Make sure to run 'npm run build' first to compile your plugin.`);
+    }
+    // Ensure output directory exists
+    fs.mkdirSync(outputDir, { recursive: true });
+    try {
+        // Run the plugin in extract mode
+        (0, child_process_1.execSync)(`node "${entryPath}"`, {
+            env: {
+                ...process.env,
+                PLUGIN_KIT_MODE: 'extract',
+                PLUGIN_KIT_OUTPUT: outputFile
+            },
+            cwd: path.dirname(entryPath),
+            stdio: silent ? 'pipe' : 'inherit'
+        });
+        // Verify the file was created
+        if (!fs.existsSync(outputFile)) {
+            throw new Error('Capabilities file was not created');
+        }
+        // Validate it's valid JSON
+        const content = fs.readFileSync(outputFile, 'utf-8');
+        const capabilities = JSON.parse(content);
+        if (!silent) {
+            console.log('✅ Successfully extracted capabilities!');
+            console.log('');
+            console.log('📊 Summary:');
+            console.log(`   Plugin: ${capabilities.name} v${capabilities.version}`);
+            console.log(`   Functions: ${capabilities.functions?.length || 0}`);
+            console.log(`   Services: ${capabilities.capabilities?.filter((c) => c.type === 'service').length || 0}`);
+            console.log(`   Screens: ${capabilities.screens?.length || 0}`);
+            console.log(`   Tools: ${capabilities.tools?.length || 0}`);
+            console.log('');
+            // Check for service implementations
+            const services = capabilities.capabilities?.filter((c) => c.type === 'service') || [];
+            const implementations = services.filter((s) => s.implements);
+            if (implementations.length > 0) {
+                console.log('🔌 Service Interface Implementations:');
+                implementations.forEach((impl) => {
+                    console.log(`   • ${impl.implements} (${impl.serviceName})`);
+                });
+                console.log('');
+            }
+            console.log('📝 Next steps:');
+            console.log('   1. Ensure ".majk" is in your package.json "files" array');
+            console.log('   2. Run this command before publishing (add to prepublishOnly script)');
+            console.log('   3. Publish to npm/CodeArtifact as usual');
+            console.log('');
+            console.log('💡 Tip: Add this to package.json scripts:');
+            console.log('   "scripts": {');
+            console.log('     "extract": "plugin-kit extract",');
+            console.log('     "prepublishOnly": "npm run build && npm run extract"');
+            console.log('   }');
+        }
+    }
+    catch (error) {
+        if (!silent) {
+            console.error('');
+            console.error('❌ Failed to extract capabilities');
+            console.error('');
+        }
+        throw new Error(`Failed to extract capabilities: ${error.message}`);
+    }
+}

package/dist/index.d.ts

@@ -18,6 +18,90 @@ export { definePlugin, FluentBuilder, ServiceBuilder } from './plugin-kit';
 export { FunctionRegistryImpl, FunctionProviderImpl } from './registry';
 export { FilesystemResourceProvider } from './resource-provider';
 export { generateClient } from './generator/generator';
-export type { PluginContext, PluginLogger, PluginStorage, ScopedTimers, ScopedIpcRegistry, PluginCapabilities, PluginCapability, ToolImplementation, InProcessPlugin, PluginHealthStatus, ToolSpec, ToolHandler, ApiMethod, ApiRouteDef, JsonSchema, RouteHandler, RequestLike, ResponseLike, UiConfig, HistoryMode, ScreenBase, ReactScreen, HtmlScreen, ConfigWizardDef, SettingsDef, Scope, EntityType, CleanupFn, HealthCheckFn, MCPServerEntity, TeamMemberEntity, ServiceFunctionBinding, FunctionHandler, SubscriptionHandler, FunctionDefinition, SubscriptionDefinition, FunctionRegistry, ClientGenerationConfig, Plugin, FunctionProvider, ResourceProvider, FunctionInfo, AsyncPluginHealthStatus, ServiceCapability, ServiceMetadata, ServiceFunctionMetadata, ServiceParameterMetadata, ServiceReturnMetadata, FunctionEnrichment, IdentityDefinitionCapability, IdentityProviderInfo, IdentitySetupInstructions, IdentityTestConfig, IdentityRequirement } from './types';
-export type { MajkInterface, EntityId, Unsubscribe, BaseEntity, StandardEventType, PluginEventType, RepositoryEventType, EntityType as MajkEntityType, RepositoryEvent, EventFilter, EventListener, Subscription, QueryBuilder, QueryableEventChannel, EventBusAPI, PluginInfo, PluginHealth, PluginCapabilityInfo, PluginLog, InstallPluginOptions, InstallPluginResult, GetLogsOptions, PluginManagementAPI, SecretScope, SecretInfo, ScopedSecretsAPI, SecretsAPI, StartTaskRequest, TaskFilter, TaskMessage, TaskProgress, TaskResult, TaskError, TaskHandle, TaskEventHandler, TaskEvent, TaskAPI, AccountType, AccountMetadata, TimeWindow, CredentialOptions, RefreshOptions, RefreshResult, ValidationResult, TokenInfo, AutoRefreshConfig, AutoRefreshHandle, AwsSdkCredentials, CognitoTokenSet, AzureSdkCredentials, AccountJSON, AwsCognitoCredentials, AzureEntraCredentials, ApiKeyCredentials, SystemDefaultCredentials, Credentials, SystemAccount, OAuthAccount, AwsAccount, AzureAccount, AuthEvent, AuthStateChangeEvent, AuthTokenRefreshedEvent, AuthErrorEvent, AccountChangedEvent, AuthAPI, Message, Conversation, Agent, TeamMember, TeamMemberSkills, TeamMemberPersonality, TeamMemberCodeStats, TeamMemberMetadata, ServiceFunctionBinding as MajkServiceFunctionBinding, Todo, WorkStrategy, Project, MCPServer, ConversationFilter, MessageQueryOptions, ConversationHandle, ConversationAPI, CreateTeammateRequest, TeammateUpdate, TeammateFilter, TeammateHandle, TeammateAPI, CreateTodoRequest, TodoUpdate, TodoFilter, SpawnOptions, TodoHandle, TodoAPI, CreateProjectRequest, ProjectUpdate, ProjectFilter, ProjectHandle, ProjectAPI, CreateMCPServerRequest, MCPServerUpdate, MCPServerFilter, ConnectionTestResult, MCPServerHandle, MCPServerScopedHandle, DiscoveredTool, MCPServerAPI, EverywhereScope, EverywhereScopedHandle, CreateAgentRequest, AgentUpdate, AgentFilter, TestResult, AgentHandle, AgentAPI, AddKnowledgeInput, KnowledgeNode, KnowledgeTree, KnowledgeSearchOptions, KnowledgeAPI, AIAPI, AIProvider, AIProviderCapabilities, AIProviderError, LLMInterface, ModelInfo, AIMessage, ContentBlock, PromptParams, PromptResult, PromptChunk, AIFunctionDefinition, AIJsonSchema, FunctionCallParams, FunctionCallResult, ImageGenerationParams, ImageResult, TranscriptionParams, TranscriptionResult, ProviderStatus } from './majk-interface-types';
+/**
+ * Service Discovery Utilities
+ *
+ * Helper functions for discovering services that implement specific interfaces at runtime.
+ * Uses ctx.capabilities to query installed plugins and filter by interface implementation.
+ */
+export declare const ServiceDiscovery: {
+    /**
+     * Find all installed services that implement a specific interface
+     *
+     * @param ctx - Plugin context with capabilities API
+     * @param interfacePackage - Interface package identifier (e.g., "@majk/service-registry/task-service")
+     * @returns Array of CapabilityMetadata for services implementing the interface
+     *
+     * @example
+     * const openaiServices = await ServiceDiscovery.findImplementations(
+     *   ctx,
+     *   '@majk/service-registry/openai-services'
+     * );
+     *
+     * if (openaiServices.length > 0) {
+     *   const service = await ctx.rpc.createProxy(openaiServices[0].serviceName);
+     *   const result = await service.prompt({ message: 'Hello!' });
+     * }
+     */
+    findImplementations(ctx: any, interfacePackage: string): Promise<any[]>;
+    /**
+     * Find the first service that implements a specific interface
+     *
+     * @param ctx - Plugin context with capabilities API
+     * @param interfacePackage - Interface package identifier
+     * @returns CapabilityMetadata for the first matching service, or undefined if none found
+     *
+     * @example
+     * const taskService = await ServiceDiscovery.findFirst(
+     *   ctx,
+     *   '@majk/service-registry/task-service'
+     * );
+     *
+     * if (taskService) {
+     *   const service = await ctx.rpc.createProxy(taskService.serviceName);
+     *   await service.createTask({ title: 'New task' });
+     * }
+     */
+    findFirst(ctx: any, interfacePackage: string): Promise<any | undefined>;
+    /**
+     * Create an RPC proxy for the first service implementing an interface
+     *
+     * @param ctx - Plugin context with capabilities and RPC APIs
+     * @param interfacePackage - Interface package identifier
+     * @returns RPC proxy to the service, or undefined if no implementation found
+     *
+     * @example
+     * const openai = await ServiceDiscovery.resolve(
+     *   ctx,
+     *   '@majk/service-registry/openai-services'
+     * );
+     *
+     * if (openai) {
+     *   const result = await openai.prompt({ message: 'Hello!' });
+     * } else {
+     *   throw new Error('No OpenAI service implementation found');
+     * }
+     */
+    resolve<T = any>(ctx: any, interfacePackage: string): Promise<T | undefined>;
+    /**
+     * Create an RPC proxy for a service implementing an interface, or throw an error
+     *
+     * @param ctx - Plugin context with capabilities and RPC APIs
+     * @param interfacePackage - Interface package identifier
+     * @returns RPC proxy to the service
+     * @throws Error if no implementation is found
+     *
+     * @example
+     * const storage = await ServiceDiscovery.resolveOrThrow(
+     *   ctx,
+     *   '@majk/service-registry/storage-service'
+     * );
+     *
+     * // Guaranteed to be defined - will throw if not found
+     * await storage.save({ key: 'data', value: '...' });
+     */
+    resolveOrThrow<T = any>(ctx: any, interfacePackage: string): Promise<T>;
+};
+export type { PluginContext, PluginLogger, PluginStorage, ScopedTimers, ScopedIpcRegistry, PluginCapabilities, PluginCapability, ToolImplementation, InProcessPlugin, PluginHealthStatus, ToolSpec, ToolHandler, ApiMethod, ApiRouteDef, JsonSchema, RouteHandler, RequestLike, ResponseLike, UiConfig, HistoryMode, ScreenBase, ReactScreen, HtmlScreen, ConfigWizardDef, SettingsDef, Scope, EntityType, CleanupFn, HealthCheckFn, MCPServerEntity, TeamMemberEntity, ServiceFunctionBinding, CallbackHandle, CreateCallbackOptions, CallbackStats, FunctionHandler, SubscriptionHandler, FunctionDefinition, SubscriptionDefinition, FunctionRegistry, ClientGenerationConfig, Plugin, FunctionProvider, ResourceProvider, FunctionInfo, AsyncPluginHealthStatus, ServiceCapability, ServiceMetadata, ServiceFunctionMetadata, ServiceParameterMetadata, ServiceReturnMetadata, FunctionEnrichment, IdentityDefinitionCapability, IdentityProviderInfo, IdentitySetupInstructions, IdentityTestConfig, IdentityRequirement } from './types';
+export type { MajkInterface, EntityId, Unsubscribe, BaseEntity, StandardEventType, PluginEventType, RepositoryEventType, EntityType as MajkEntityType, RepositoryEvent, EventFilter, EventListener, Subscription, QueryBuilder, QueryableEventChannel, EventBusAPI, PluginInfo, PluginHealth, PluginCapabilityInfo, PluginLog, InstallPluginOptions, InstallPluginResult, GetLogsOptions, GetPluginExternalUrlOptions, GetPluginScreenUrlOptions, PluginManagementAPI, SecretScope, SecretInfo, ScopedSecretsAPI, SecretsAPI, StartTaskRequest, TaskFilter, TaskMessage, TaskProgress, TaskResult, TaskError, TaskHandle, TaskEventHandler, TaskEvent, TaskAPI, AccountType, AccountMetadata, TimeWindow, CredentialOptions, RefreshOptions, RefreshResult, ValidationResult, TokenInfo, AutoRefreshConfig, AutoRefreshHandle, AwsSdkCredentials, CognitoTokenSet, AzureSdkCredentials, AccountJSON, AwsCognitoCredentials, AzureEntraCredentials, ApiKeyCredentials, SystemDefaultCredentials, Credentials, SystemAccount, OAuthAccount, AwsAccount, AzureAccount, AuthEvent, AuthStateChangeEvent, AuthTokenRefreshedEvent, AuthErrorEvent, AccountChangedEvent, AuthAPI, Message, Conversation, Agent, TeamMember, TeamMemberSkills, TeamMemberPersonality, TeamMemberCodeStats, TeamMemberMetadata, ServiceFunctionBinding as MajkServiceFunctionBinding, Todo, WorkStrategy, Project, MCPServer, ConversationFilter, MessageQueryOptions, ConversationHandle, ConversationAPI, CreateTeammateRequest, TeammateUpdate, TeammateFilter, TeammateHandle, TeammateAPI, CreateTodoRequest, TodoUpdate, TodoFilter, SpawnOptions, TodoHandle, TodoAPI, CreateProjectRequest, ProjectUpdate, ProjectFilter, ProjectHandle, ProjectAPI, CreateMCPServerRequest, MCPServerUpdate, MCPServerFilter, ConnectionTestResult, MCPServerHandle, MCPServerScopedHandle, DiscoveredTool, MCPServerAPI, EverywhereScope, EverywhereScopedHandle, CreateAgentRequest, AgentUpdate, AgentFilter, TestResult, AgentHandle, AgentAPI, AddKnowledgeInput, KnowledgeNode, KnowledgeTree, KnowledgeSearchOptions, KnowledgeAPI, AIAPI, AIProvider, AIProviderCapabilities, AIProviderError, LLMInterface, ModelInfo, AIMessage, ContentBlock, PromptParams, PromptResult, PromptChunk, AIFunctionDefinition, AIJsonSchema, FunctionCallParams, FunctionCallResult, ImageGenerationParams, ImageResult, TranscriptionParams, TranscriptionResult, ProviderStatus } from './majk-interface-types';
 //# 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;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,YAAY,EACV,aAAa,EACb,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,QAAQ,EACR,WAAW,EACX,SAAS,EACT,WAAW,EACX,UAAU,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,EACV,eAAe,EACf,WAAW,EACX,KAAK,EACL,UAAU,EACV,SAAS,EACT,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,sBAAsB,EAEtB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,EAChB,sBAAsB,EAEtB,MAAM,EACN,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,EAEvB,iBAAiB,EACjB,eAAe,EACf,uBAAuB,EACvB,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,EAElB,4BAA4B,EAC5B,oBAAoB,EACpB,yBAAyB,EACzB,kBAAkB,EAElB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,aAAa,EACb,QAAQ,EACR,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,UAAU,IAAI,cAAc,EAC5B,eAAe,EACf,WAAW,EACX,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,UAAU,EACV,YAAY,EACZ,oBAAoB,EACpB,SAAS,EACT,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,YAAY,EACZ,UAAU,EACV,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,OAAO,EACP,WAAW,EACX,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,SAAS,EACT,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,WAAW,EACX,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,EACxB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,SAAS,EACT,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACd,mBAAmB,EACnB,OAAO,EACP,OAAO,EACP,YAAY,EACZ,KAAK,EACL,UAAU,EACV,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,IAAI,0BAA0B,EACpD,IAAI,EACJ,YAAY,EACZ,OAAO,EACP,SAAS,EACT,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,YAAY,EACZ,UAAU,EACV,OAAO,EACP,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,aAAa,EACb,UAAU,EACV,sBAAsB,EACtB,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,WAAW,EACX,WAAW,EACX,UAAU,EACV,WAAW,EACX,QAAQ,EACR,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,sBAAsB,EACtB,YAAY,EAEZ,KAAK,EACL,UAAU,EACV,sBAAsB,EACtB,eAAe,EACf,YAAY,EACZ,SAAS,EACT,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACf,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -16,7 +16,7 @@
  * - Lifecycle hooks with cleanup management
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateClient = exports.FilesystemResourceProvider = exports.FunctionProviderImpl = exports.FunctionRegistryImpl = exports.definePlugin = void 0;
+exports.ServiceDiscovery = exports.generateClient = exports.FilesystemResourceProvider = exports.FunctionProviderImpl = exports.FunctionRegistryImpl = exports.definePlugin = void 0;
 var plugin_kit_1 = require("./plugin-kit");
 Object.defineProperty(exports, "definePlugin", { enumerable: true, get: function () { return plugin_kit_1.definePlugin; } });
 var registry_1 = require("./registry");
@@ -26,3 +26,106 @@ var resource_provider_1 = require("./resource-provider");
 Object.defineProperty(exports, "FilesystemResourceProvider", { enumerable: true, get: function () { return resource_provider_1.FilesystemResourceProvider; } });
 var generator_1 = require("./generator/generator");
 Object.defineProperty(exports, "generateClient", { enumerable: true, get: function () { return generator_1.generateClient; } });
+/**
+ * Service Discovery Utilities
+ *
+ * Helper functions for discovering services that implement specific interfaces at runtime.
+ * Uses ctx.capabilities to query installed plugins and filter by interface implementation.
+ */
+exports.ServiceDiscovery = {
+    /**
+     * Find all installed services that implement a specific interface
+     *
+     * @param ctx - Plugin context with capabilities API
+     * @param interfacePackage - Interface package identifier (e.g., "@majk/service-registry/task-service")
+     * @returns Array of CapabilityMetadata for services implementing the interface
+     *
+     * @example
+     * const openaiServices = await ServiceDiscovery.findImplementations(
+     *   ctx,
+     *   '@majk/service-registry/openai-services'
+     * );
+     *
+     * if (openaiServices.length > 0) {
+     *   const service = await ctx.rpc.createProxy(openaiServices[0].serviceName);
+     *   const result = await service.prompt({ message: 'Hello!' });
+     * }
+     */
+    async findImplementations(ctx, interfacePackage) {
+        const allServices = await ctx.capabilities.getProviders('service');
+        return allServices.filter((s) => s.metadata?.implements === interfacePackage);
+    },
+    /**
+     * Find the first service that implements a specific interface
+     *
+     * @param ctx - Plugin context with capabilities API
+     * @param interfacePackage - Interface package identifier
+     * @returns CapabilityMetadata for the first matching service, or undefined if none found
+     *
+     * @example
+     * const taskService = await ServiceDiscovery.findFirst(
+     *   ctx,
+     *   '@majk/service-registry/task-service'
+     * );
+     *
+     * if (taskService) {
+     *   const service = await ctx.rpc.createProxy(taskService.serviceName);
+     *   await service.createTask({ title: 'New task' });
+     * }
+     */
+    async findFirst(ctx, interfacePackage) {
+        const implementations = await this.findImplementations(ctx, interfacePackage);
+        return implementations[0];
+    },
+    /**
+     * Create an RPC proxy for the first service implementing an interface
+     *
+     * @param ctx - Plugin context with capabilities and RPC APIs
+     * @param interfacePackage - Interface package identifier
+     * @returns RPC proxy to the service, or undefined if no implementation found
+     *
+     * @example
+     * const openai = await ServiceDiscovery.resolve(
+     *   ctx,
+     *   '@majk/service-registry/openai-services'
+     * );
+     *
+     * if (openai) {
+     *   const result = await openai.prompt({ message: 'Hello!' });
+     * } else {
+     *   throw new Error('No OpenAI service implementation found');
+     * }
+     */
+    async resolve(ctx, interfacePackage) {
+        const service = await this.findFirst(ctx, interfacePackage);
+        if (!service) {
+            return undefined;
+        }
+        return (await ctx.rpc.createProxy(service.serviceName));
+    },
+    /**
+     * Create an RPC proxy for a service implementing an interface, or throw an error
+     *
+     * @param ctx - Plugin context with capabilities and RPC APIs
+     * @param interfacePackage - Interface package identifier
+     * @returns RPC proxy to the service
+     * @throws Error if no implementation is found
+     *
+     * @example
+     * const storage = await ServiceDiscovery.resolveOrThrow(
+     *   ctx,
+     *   '@majk/service-registry/storage-service'
+     * );
+     *
+     * // Guaranteed to be defined - will throw if not found
+     * await storage.save({ key: 'data', value: '...' });
+     */
+    async resolveOrThrow(ctx, interfacePackage) {
+        const service = await this.resolve(ctx, interfacePackage);
+        if (!service) {
+            throw new Error(`No service found implementing interface: ${interfacePackage}. ` +
+                `Make sure the required plugin is installed and enabled.`);
+        }
+        return service;
+    }
+};